### Install vp-beads Plugin

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Commands to add the marketplace and install the plugin via the Claude Code CLI.

```bash
# Add the marketplace and install the plugin
/plugin marketplace add voxpelli/vp-claude
/plugin install vp-beads@vp-plugins
```

--------------------------------

### Install Optional Knowledge Plugin

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Install the knowledge gap audit plugin using the existing marketplace.

```bash
/plugin install vp-knowledge@vp-plugins
```

--------------------------------

### Install Plugin via Slash Commands

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Use these commands within the Claude interface to add the marketplace and install the plugin.

```bash
/plugin marketplace add voxpelli/vp-claude
/plugin install vp-beads@vp-plugins
```

--------------------------------

### Sprint Review Agent Triggers and Output

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Example triggers and output format for the automated sprint-review agent.

```bash
# The agent triggers on these phrases:
# - "bd close worked. What should we do now?"
# - "sprint done"
# - "we're done"
# - "what did we accomplish"

# Example agent output:
## Sprint 5

**Commits this sprint:** 12 commits
- feat: Add dark mode toggle (3 commits)
- fix: Correct session validation edge case (2 commits)
- chore: Update dependencies (4 commits)
- refactor: Extract validation helpers (3 commits)

**Open beads issues:** 18 total, 2 in_progress carry-overs
**Upstream status:** 3 open entries across 2 files, 1 stale (>90 days)
**Synergy status:** 2 extraction candidates (1 ready)

**Recommendation:** Ready to close — run `/retrospective` when ready.
```

--------------------------------

### Retrospective Document Template

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Example content generated in a RETRO-NN.md file.

```markdown
## Sprint 5 Retrospective — 2026-03-28

### What went well

- Established consistent error handling pattern across all route handlers
- Test coverage increased from 78% to 85%

### What could improve

- Session validation edge cases discovered late in sprint
- Need clearer contribution guidelines for vendor packages

### Upstream observations

- UPSTREAM-fastify.md: 2 open bugs, 1 feature request
- New friction discovered: missing type export in @fastify/session

### Synergy observations

- **Extraction Candidates ready:** validate-helpers (vp-knowledge) — Readiness: ready
- **Drifting shared patterns:** none
- **Active convergence paths:** error handling — adopt-theirs from vp-knowledge
- **New patterns logged this sprint:** 1 Extraction Candidate
- **Stale entries flagged:** none

### Lessons learned

- **Guard session access with type narrowing** — FastifyRequest.session can be undefined in edge cases
```

--------------------------------

### Run Knowledge Gap Audit

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/retrospective/SKILL.md

Execute the `/knowledge-gaps` command to scan project manifests and identify undocumented packages and tools. Ensure `vp-knowledge` is installed for full functionality.

```bash
/knowledge-gaps
```

--------------------------------

### Re-link Workspaces

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/vendor-sync/SKILL.md

Run `npm install` after updating vendor subtrees to ensure all workspace symlinks are correctly updated.

```bash
npm install
```

--------------------------------

### View backlog statistics

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Run 'bd stats' to get an overview of backlog statistics, which may include counts of issues by status, priority, or other metrics.

```bash
bd stats
```

--------------------------------

### Review all open upstream items

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Execute /upstream-tracker review to get an overview of all currently open issues tracked by the upstream-tracker skill.

```bash
# Review all open items (workflow 2)
/upstream-tracker review
```

--------------------------------

### Example triage output

Source: https://context7.com/voxpelli/claude-beads/llms.txt

This markdown table displays an example of triage output, showing issue ID, title, age, priority, and flags. It also includes suggested actions for specific issues.

```markdown
| ID           | Title                        | Age  | Priority | Flags                    |
|--------------|------------------------------|------|----------|--------------------------|
| vp-beads-12  | Add rate limiting to API     | 45d  | P3       | stale, missing desc      |
| vp-beads-18  | Fix session edge case        | 12d  | P1       | blocked by vp-beads-15   |
| vp-beads-23  | Update dependencies          | 90d  | P4       | superseded by vp-beads-31|

**Suggested actions:**
- vp-beads-12: Close (addressed by commit a1b2c3d) or reprioritize to P2
- vp-beads-23: Close (superseded)
```

--------------------------------

### Git Subtree Pull Workflow

Source: https://context7.com/voxpelli/claude-beads/llms.txt

A step-by-step guide for pulling Git subtree changes, resolving conflicts by accepting upstream, cleaning stale modules, and verifying changes.

```bash
# Step 1: Check working tree
git status

# Step 2: Capture pre-pull state
PRE_PULL_HEAD=$(git rev-parse HEAD)

# Step 3: Pull subtree
git subtree pull --prefix vendor/typed-utils typed-utils main --squash

# Step 4: Resolve conflicts (always accept upstream)
git diff --name-only --diff-filter=U
git checkout --theirs vendor/typed-utils/conflicted-file.ts

# Step 5: Clean stale node_modules
rm -rf vendor/typed-utils/node_modules

# Step 6: Re-link workspaces
npm install

# Step 7: Cross-reference changelog
git diff $PRE_PULL_HEAD -- vendor/typed-utils/CHANGELOG.md
# Parse for fixed bugs matching UPSTREAM entries

# Step 8: Cross-reference code diff
git show HEAD -- vendor/typed-utils
# Check if changes address open UPSTREAM items

# Step 9: Verify
npm run check && npm test
```

--------------------------------

### Configure Plugin via settings.json

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Manually register the marketplace and enable the plugin in the local settings file.

```json
{
  "extraKnownMarketplaces": {
    "vp-plugins": {
      "source": { "source": "github", "repo": "voxpelli/vp-claude" }
    }
  },
  "enabledPlugins": {
    "vp-beads@vp-plugins": true
  }
}
```

--------------------------------

### Inject Reflection Instructions

Source: https://context7.com/voxpelli/claude-beads/llms.txt

JSON configuration for compacting context and identifying project opportunities.

```json
{"additionalContext": "Context is about to be compacted. Review for:
1. Upstream friction → suggest /upstream-tracker log
2. Technical decisions → write to Basic Memory
3. Resolved UPSTREAM entries → annotate BM
4. Contribution opportunities → log as Upstream Opportunity
5. Extraction candidates → suggest /synergy-tracker"}
```

--------------------------------

### Add Basic Memory MCP Server

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Register the knowledge graph backend required for sprint learnings.

```bash
claude mcp add basic-memory -- basic-memory mcp
```

--------------------------------

### Manage Synergy Files with /synergy-tracker

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use the /synergy-tracker skill to log, review, or compare cross-project patterns tracked in SYNERGY-*.md files.

```bash
# Log a synergy entry (workflow 1)
/synergy-tracker log vp-knowledge

# Review open synergies (workflow 2)
/synergy-tracker review

# Compare with sibling project (workflow 3)
/synergy-tracker compare vp-knowledge
```

--------------------------------

### Research workflow step 2: Check existing beads issues

Source: https://context7.com/voxpelli/claude-beads/llms.txt

After checking Basic Memory, search for related issues within the 'beads' system using 'bd search "<query>"'.

```bash
# Step 2: Check existing beads issues
bd search "rate limit"
```

--------------------------------

### Get Recent Commits for Retrospective

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/retrospective/SKILL.md

Retrieves a list of one-line commit messages since the last retrospective file was created or modified. It correctly handles the initial sprint (Sprint 1) by defaulting to all commits if no previous retrospective file is found.

```bash
# Anchor to the commit that created/last modified the previous RETRO file.
# Edge cases that both result in full-history range (correct for Sprint 1):
#   1. No prior RETRO-*.md files exist yet
#   2. RETRO files are gitignored — git log -- RETRO-*.md returns empty
# In both cases the inner git log returns empty, making the range "..HEAD"
# which shows all commits — the right behavior for a first retrospective.
git log --oneline "$(git log -1 --format=%H -- RETRO-*.md)"..HEAD --no-merges
```

--------------------------------

### View Plugin Directory Structure

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Overview of the standard file layout for a Claude plugin project.

```text
.claude-plugin/plugin.json              Plugin manifest
agents/
  sprint-review.md                      End-of-sprint assessment agent
skills/
  backlog-groomer/
    SKILL.md                            Backlog triage and research workflow
    references/
      backlog-health-heuristics.md      Staleness, closure, priority heuristics
  retrospective/
    SKILL.md                            Sprint retrospective workflow
  upstream-tracker/
    SKILL.md                            Upstream issue tracking workflow
    references/
      basic-memory-friction-format.md   BM section templates, routing, gotchas
  vendor-sync/
    SKILL.md                            Vendor subtree sync workflow
  synergy-tracker/
    SKILL.md                            Cross-project synergy tracking workflow
    references/
      synergy-entry-format.md           Entry templates, naming, registry schema
hooks/
  hooks.json                            Hook definitions (4 event types)
  precompact.sh                         Sprint insight capture before compaction
  session-start.sh                      Trend-review reminder + dormancy nudges
  post-file-edit.sh                     Auto-format hooks/*.sh with shfmt
```

--------------------------------

### PostToolUseFailure Hook Guidance

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Recovery logic for handling Basic Memory MCP tool failures.

```bash
# Classifies failures into:
# 1. Server unavailable → check `claude mcp list`
# 2. Invalid argument → show correct format
# 3. Note not found → suggest /package-intel first
# 4. Permission error → check MCP config
# 5. Unknown → surface raw error
```

--------------------------------

### SessionStart Hook Reminders

Source: https://context7.com/voxpelli/claude-beads/llms.txt

The SessionStart hook provides automated reminders for trend-review sprints and dormancy nudges, and warns about tracked sensitive files.

```bash
# Output when Sprint 4 is upcoming (trend-review sprint):
{"systemMessage": "Trend-review reminder: Sprint 4 will be a trend-review sprint..."}

# Output for low-activity repo with UPSTREAM files:
{"systemMessage": "Low-activity repo with 2 UPSTREAM tracking file(s). Consider /upstream-tracker W2 (review) or W6 (promote to BM)..."}

# Output for tracked sensitive files:
{"systemMessage": "WARNING: .beads/interactions.jsonl is tracked by git..."}
```

--------------------------------

### Research workflow step 1: Search Basic Memory

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Begin research by querying Basic Memory for relevant notes using 'mcp__basic-memory__search_notes'. This helps gather existing knowledge on the topic.

```bash
# Step 1: Search Basic Memory first
mcp__basic-memory__search_notes query="rate limiting patterns"
```

--------------------------------

### List all in-progress issues

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Execute 'bd list --status in_progress' to view all issues that are currently being worked on.

```bash
bd list --status in_progress
```

--------------------------------

### List all open issues

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use 'bd list --status open' to retrieve a comprehensive list of all currently open issues in the backlog.

```bash
# Get full backlog picture
bd list --status open
```

--------------------------------

### Retrospective Workflow Execution

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Steps to gather context and run tests before generating a retrospective document.

```bash
# Step 1: Determine sprint number
ls RETRO-*.md | sort -V | tail -1
# Output: RETRO-04.md → Next sprint is 5

# Step 2: Gather commits since last retro
git log --oneline "$(git log -1 --format=%H -- RETRO-*.md)"..HEAD --no-merges

# Step 3: Check upstream status
ls UPSTREAM-*.md
# Output: UPSTREAM-voxpelli--typed-utils.md, UPSTREAM-fastify.md

# Step 4: Run tests
npm test
```

--------------------------------

### Create structured issue with backlog-groomer

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use 'bd create "<title>"' with flags like '-t' for type, '-p' for priority, and '--description' to create a new, structured issue in the backlog.

```bash
# Create structured issue
bd create "[API] Add rate limiting middleware" \
  -t feature \
  -p 2 \
  --description "Implement request rate limiting to prevent abuse.

```

--------------------------------

### Compare Synergy Patterns with Sibling Project

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Read files from a sibling project to identify shared conventions, structural differences, extraction opportunities, and missing features.

```bash
# Read sibling project files
cat ../vp-knowledge/package.json
cat ../vp-knowledge/CLAUDE.md
ls ../vp-knowledge/skills/**/SKILL.md
cat ../vp-knowledge/hooks/hooks.json

# Diff patterns and identify:
# - Shared conventions
# - Structural differences
# - Extraction opportunities
# - Features we lack
```

--------------------------------

### Format Feature Request Entry

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/upstream-tracker/SKILL.md

Standard format for documenting desired capabilities in upstream packages.

```text
- **Short title** (YYYY-MM-DD) — Description of the desired behavior and why
  it matters for the consuming app. [upstream: <url>]
  Ownership: upstream|us|shared · Workaround: none|partial|full — description
```

--------------------------------

### Review and triage open issues with backlog-groomer

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Initiate the backlog grooming process by running the /backlog-groomer command. This workflow helps in triaging and prioritizing open issues.

```bash
# Review and triage open issues (workflow 1)
/backlog-groomer
```

--------------------------------

### Create UPSTREAM-*.md Template

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/upstream-tracker/SKILL.md

Use this template when creating a new upstream tracking file for non-vendor dependencies.

```markdown
## Feature Requests

_No entries yet._

## Bugs

_No entries yet._

## Upstream Opportunities

_No entries yet._
```

--------------------------------

### Declare Vendor Subtrees

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Define vendor subtrees in the registry file to map remotes to local prefixes.

```json
[
  {
    "prefix": "vendor/my-pkg",
    "remote": "my-pkg",
    "branch": "main",
    "package": "@scope/my-pkg"
  }
]
```

--------------------------------

### Issue creation commands

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/backlog-groomer/references/backlog-health-heuristics.md

Commands for managing issue creation and deduplication.

```bash
bd search <keywords>
```

```bash
bd create
```

--------------------------------

### Vendor Registry Configuration

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Configure vendor registry settings in .claude/vendor-registry.json to define prefixes, remotes, branches, and package names for vendor synchronization.

```json
[
  {
    "prefix": "vendor/typed-utils",
    "remote": "typed-utils",
    "branch": "main",
    "package": "@voxpelli/typed-utils"
  },
  {
    "prefix": "vendor/fastify-helpers",
    "remote": "fastify-helpers",
    "branch": "main",
    "package": "@voxpelli/fastify-helpers"
  }
]
```

--------------------------------

### Check blocked issue chains

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Run 'bd blocked' to identify issues that are blocking other issues, helping to resolve dependencies and bottlenecks.

```bash
# Check blocked chains
bd blocked
```

--------------------------------

### Synergy Registry Configuration

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Configure the synergy registry in .claude/synergy-registry.json to link project names with their corresponding synergy files, remotes, and BM entities.

```json
[
  {
    "name": "vp-knowledge",
    "file": "SYNERGY-vp-knowledge.md",
    "remote": "https://github.com/voxpelli/vp-knowledge",
    "bm-entity": "projects/vp-knowledge",
    "relationship": "sibling-plugin"
  }
]
```

--------------------------------

### Create Beads Issue Command

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/retrospective/SKILL.md

Use this command to create new issues in the beads tracking system. Specify the issue type, priority, and a detailed description.

```bash
bd create "..." -t bug|task|feature|chore -p N --description "..."

```

--------------------------------

### Write Learnings to Basic Memory

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Commands for searching, editing, or creating notes in Basic Memory.

```bash
# Search first
mcp__basic-memory__search_notes query="fastify error handling"

# If note exists, edit with find_replace
mcp__basic-memory__read_note identifier="engineering/fastify/error-handling"
mcp__basic-memory__edit_note \
  identifier="engineering/fastify/error-handling" \
  operation="find_replace" \
  find="## Observations\n" \
  replace="## Observations\n\n- [lesson] Always wrap async handlers with try-catch for proper error propagation\n" \
  expected_replacements=1

# If no note exists, create new
mcp__basic-memory__write_note \
  title="Fastify Error Handling" \
  folder="engineering/fastify" \
  content="---\ntype: engineering\ntags: [fastify, error-handling]\n---\n\n## Observations\n\n- [lesson] Always wrap async handlers..."
```

--------------------------------

### Sync Vendor Packages with /vendor-sync

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use the /vendor-sync command to pull the latest upstream changes for vendor packages. Specify a package name to sync only that specific one.

```bash
# Sync all vendor packages
/vendor-sync

# Sync specific package
/vendor-sync auth
/vendor-sync @voxpelli/typed-utils
```

--------------------------------

### Write Note to Basic Memory

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/retrospective/SKILL.md

Use `mcp__basic-memory__write_note` to create a new generalizable engineering learning in the cross-project knowledge base. Avoid using this for existing notes.

```python
mcp__basic-memory__write_note
```

--------------------------------

### Resolve Content Conflicts

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/vendor-sync/SKILL.md

For content conflicts, use `git checkout --theirs <file>` to accept the upstream version of the file. Vendor directories must mirror upstream exactly.

```bash
git checkout --theirs <file>
```

--------------------------------

### Sprint Retrospective Markdown Template

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/retrospective/SKILL.md

A Markdown template for drafting a sprint retrospective. It includes sections for 'What went well', 'What could improve', 'Upstream observations', and 'Synergy observations'. The Synergy section is optional and depends on the availability of SYNERGY-*.md files.

```markdown
## Sprint {N} Retrospective — {YYYY-MM-DD}

### What went well

- ...

### What could improve

- ...

### Upstream observations

<!-- Review recent work — anything to add to UPSTREAM-*.md files? -->

- ...

### Synergy observations

<!-- From SYNERGY-*.md: extraction-ready candidates first, then drifting
     patterns, then active convergence paths. Omit if no SYNERGY files. -->

- **Extraction Candidates ready:** <!-- e.g. "validate-helpers (vp-knowledge) — Readiness: ready" or "none" -->
- **Drifting shared patterns:** <!-- e.g. "BM note format — drifting since 2026-01" or "none" -->
- **Active convergence paths:** <!-- e.g. "error handling — adopt-theirs from vp-knowledge" or "none" -->
- **New patterns logged this sprint:** <!-- e.g. "Logged 2 new Extraction Candidates" or "none" -->
- **Stale entries flagged:** <!-- entries >3 months old, or "none" -->


```

--------------------------------

### Assess open beads issues

Source: https://github.com/voxpelli/claude-beads/blob/main/agents/sprint-review.md

Use these commands to list and filter project issues for backlog health assessment.

```bash
bd list --status in_progress 2>/dev/null
bd list --status open 2>/dev/null | head -40
bd blocked 2>/dev/null
bd stale --days 60 2>/dev/null
```

--------------------------------

### Basic Memory Ownership Table

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Mapping of workflows to Basic Memory sections and entity types.

```markdown
| Skill/Workflow       | Section Owned                    | Entity Types           |
|----------------------|----------------------------------|------------------------|
| upstream-tracker W6  | ## Upstream Friction             | npm/*, brew/*, cask/*  |
| synergy-tracker W5   | ## Cross-Project Synergy         | projects/*             |
| retrospective step 7 | engineering/* notes              | engineering/*          |
```

--------------------------------

### Create issues from findings

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Employ the /backlog-groomer create-issues command to generate new issues based on research findings or identified tasks.

```bash
# Create issues from findings (workflow 5)
/backlog-groomer create-issues
```

--------------------------------

### Upstream Issue Tracking

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Command to manage upstream package friction and tracking files.

```text
/upstream-tracker
```

--------------------------------

### Format Upstream Opportunity Entry

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/upstream-tracker/SKILL.md

Standard format for documenting local solutions that could be contributed back to the upstream package.

```text
- **Short title** (YYYY-MM-DD) — What was built, why it could be valuable
  upstream, and the consumer-side motivation. [upstream: <url>]
  Source: <file-or-branch> · Merge readiness: direct|needs-redesign|proof-of-concept
  Ownership: us|shared · Workaround: full|partial — description of local solution
```

--------------------------------

### Run Project Validation Checks

Source: https://github.com/voxpelli/claude-beads/blob/main/CLAUDE.md

Execute all project validation checks, including plugin validation, markdown linting, and shell script linting. All checks must pass before committing.

```bash
npm run check
```

--------------------------------

### Research workflow step 3: Scan codebase

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Perform a codebase scan using 'grep -r "<pattern>" <directory>' to find occurrences of specific code patterns or keywords.

```bash
# Step 3: Scan codebase
grep -r "rateLimit" src/
```

--------------------------------

### Suggest issues for closure

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Run /backlog-groomer suggest-closures to identify issues that may be candidates for closure, potentially due to being resolved, outdated, or duplicates.

```bash
# Suggest issues to close (workflow 3)
/backlog-groomer suggest-closures
```

--------------------------------

### PostToolUse Hook Configuration

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Shell script trigger for auto-formatting hooks using shfmt.

```bash
# Triggers on Edit|Write to hooks/*.sh
bash hooks/post-file-edit.sh
# Runs: shfmt -w hooks/*.sh
```

--------------------------------

### Research a topic with backlog-groomer

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use /backlog-groomer followed by a topic, such as 'rate limiting', to initiate research on that subject within the context of backlog grooming.

```bash
# Research a topic (workflow 4)
/backlog-groomer rate limiting
```

--------------------------------

### Upstream file naming convention for non-npm tools

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Convention for naming UPSTREAM files for non-npm tools. Prefixes like 'brew:', 'cask:', 'action:', and 'docker:' are used, with slashes replaced by double hyphens.

```bash
# Non-npm tools use prefix notation
brew:ripgrep         → UPSTREAM-brew--ripgrep.md
cask:docker          → UPSTREAM-cask--docker.md
action:actions/checkout → UPSTREAM-action--actions--checkout.md
docker:node          → UPSTREAM-docker--node.md
vscode:dbaeumer.vscode-eslint → UPSTREAM-vscode--dbaeumer.vscode-eslint.md
```

--------------------------------

### Capture sync diff

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/vendor-sync/SKILL.md

Retrieve the full synchronization diff for a specific vendor directory to identify resolved issues.

```bash
git show HEAD -- <prefix>
```

--------------------------------

### Run Node.js Test Script

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/retrospective/SKILL.md

Attempts to run a Node.js test script using npm. It tries common test script names and displays the last 5 lines of output. This is used to check the test and coverage status for the retrospective.

```bash
npm test
```

```bash
npm run test:node
```

--------------------------------

### Retrieve Sprint Statistics

Source: https://github.com/voxpelli/claude-beads/blob/main/agents/sprint-review.md

Fetches current sprint statistics using the beads tracker.

```bash
bd stats 2>/dev/null
```

--------------------------------

### Sync upstream entries from Basic Memory

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Execute /upstream-tracker sync to synchronize tracked upstream issues with data stored in Basic Memory.

```bash
# Sync from Basic Memory (workflow 7)
/upstream-tracker sync
```

--------------------------------

### Format Bug Entry

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/upstream-tracker/SKILL.md

Standard format for documenting unexpected behavior, including severity and reproduction details.

```text
- **Short title** (YYYY-MM-DD) [blocking|degraded|minor] — What happens, how to
  reproduce, and the expected behavior. [upstream: <url>]
  Severity: blocking|degraded|minor · Ownership: upstream|us|shared · Workaround: none|partial|full — description
```

--------------------------------

### Search for existing entity note in Basic Memory

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use mcp__basic-memory__search_notes to find existing notes related to a specific query, useful for gathering context before promoting an upstream issue.

```bash
# Search for existing entity note
mcp__basic-memory__search_notes query="fastify session"
```

--------------------------------

### Research workflow step 4: Check Raindrop bookmarks

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Utilize 'mcp__raindrop__find_bookmarks' to search for relevant bookmarks in Raindrop, useful for finding external resources or articles.

```bash
# Step 4: Check Raindrop bookmarks
mcp__raindrop__find_bookmarks query="rate limiting api"
```

--------------------------------

### Check for stale issues

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/backlog-groomer/references/backlog-health-heuristics.md

Commands to identify stale issues based on inactivity duration.

```bash
bd stale --days 60
```

```bash
bd stale
```

--------------------------------

### Log a new upstream issue

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use the /upstream-tracker command to log a new issue. The system infers the package and issue details from the conversation context.

```bash
# Log a new upstream issue (workflow 1)
/upstream-tracker
# Infers package and issue from conversation context
```

--------------------------------

### Generate Sprint Retrospective

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Triggers the generation of a sprint retrospective document based on git history and current context.

```text
/retrospective
```

--------------------------------

### Vendor Registry JSON Structure

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/vendor-sync/SKILL.md

Defines the expected structure for the `.claude/vendor-registry.json` file, which maps local vendor prefixes to upstream Git remotes and branches.

```json
{
  "prefix": "vendor/pkg",
  "remote": "remote-name",
  "branch": "branch-name",
  "package": "@scope/pkg-name"
}
```

--------------------------------

### Research workflow step 5: External research

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Conduct external research using tools like 'mcp__deepwiki__ask_question' or 'mcp__tavily__tavily_search' to gather information from external knowledge bases or search engines.

```bash
# Step 5: External research
mcp__deepwiki__ask_question question="How does fastify implement rate limiting?"
mcp__tavily__tavily_search query="api rate limiting best practices nodejs"
```

--------------------------------

### Search for duplicate issues

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/backlog-groomer/references/backlog-health-heuristics.md

Commands to find duplicate or similar issues within the backlog.

```bash
bd duplicates
```

```bash
bd search <keywords>
```

--------------------------------

### Find duplicate issues

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Execute 'bd duplicates' to identify and list potential duplicate issues within the backlog.

```bash
# Find duplicates
bd duplicates
```

--------------------------------

### Upstream opportunity entry format

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Markdown format for upstream opportunities, such as contribution candidates. Includes title, date, source file, and merge readiness.

```markdown
## Upstream Opportunities

- **Typed session helper** (2026-03-25) — Built a type-safe session wrapper that
  handles the undefined edge case and provides better DX. Could benefit other
  fastify/session users.
  Source: lib/session-helpers.ts · Merge readiness: needs-redesign
  Ownership: us · Workaround: full — using locally
```

--------------------------------

### List issues by area

Source: https://github.com/voxpelli/claude-beads/blob/main/skills/backlog-groomer/references/backlog-health-heuristics.md

Command to list issues, utilizing the area prefix for better scannability.

```bash
bd list
```

--------------------------------

### Promote upstream entry to Basic Memory

Source: https://context7.com/voxpelli/claude-beads/llms.txt

The /upstream-tracker promote command is used to move an upstream issue or feature request into Basic Memory for further tracking or action.

```bash
# Promote to Basic Memory (workflow 6)
/upstream-tracker promote
```

--------------------------------

### Summarize Recent Commits

Source: https://github.com/voxpelli/claude-beads/blob/main/agents/sprint-review.md

Lists commits since the last retrospective or the most recent history if no retrospective exists.

```bash
git log --oneline --no-merges "<hash>"..HEAD 2>/dev/null
# or, if no hash:
git log --oneline --no-merges -30 2>/dev/null
```

--------------------------------

### Backlog Grooming Commands

Source: https://github.com/voxpelli/claude-beads/blob/main/README.md

Commands for triaging and researching work items, including optional rate limiting parameters.

```text
/backlog-groomer
/backlog-groomer rate limiting
```

--------------------------------

### Invoke Retrospective Skill

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Basic invocation of the /retrospective skill.

```bash
# Basic invocation
/retrospective

# The skill produces RETRO-NN.md covering:
# - What went well
# - What could improve
# - Upstream observations
# - Synergy observations (if SYNERGY files exist)
# - Lessons learned
```

--------------------------------

### Enrich an existing issue

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use /backlog-groomer enrich followed by an issue identifier (e.g., vp-beads-42) to add more details or context to an existing issue.

```bash
# Enrich existing issue (workflow 6)
/backlog-groomer enrich vp-beads-42
```

--------------------------------

### Generate retro upstream section

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use /upstream-tracker retro-support to generate content for the upstream section of a retrospective meeting.

```bash
# Generate retro upstream section (workflow 5)
/upstream-tracker retro-support
```

--------------------------------

### Reprioritize backlog items

Source: https://context7.com/voxpelli/claude-beads/llms.txt

Use the /backlog-groomer reprioritize command to adjust the priority of issues based on current sprint goals or project needs.

```bash
# Reprioritize based on sprint goals (workflow 2)
/backlog-groomer reprioritize
```