Claude Code slash commands for bd (beads) issue tracking workflow

bdexecissue.md

description	argument-hint	allowed-tools	context
execute a single bd issue	<issue key>	Bash(bd *), Bash(git *), Bash(tea *), Read(.)	fork

Execute Single BD Issue

Overview

Execute a single bd issue with proper status tracking, commenting, and git workflow integration. This command handles one issue in isolation, keeping context clean.

Execute the bd issue [issue-id] following the bdexecissue workflow:

1. IMMEDIATELY mark in_progress: bd update [issue-id] --status in_progress
2. Review details: bd show [issue-id]
3. Implement the work with atomic commits
4. Track progress with bd comments after commits
5. Verify acceptance criteria and tests pass
6. Close when complete: bd close [issue-id] --reason "[summary]"

If blocked, create blocker issues and report back.

Report final status: completed, blocked, or needs-attention.

Arguments

$ARGUMENTS

The argument should be a bd issue ID (e.g., proj-5, app-12).

Instructions

1. Claim the Issue Immediately

bd update [issue-id] --status in_progress

⚠️ CRITICAL: Do this FIRST before any other work.

2. Review Issue Details

bd show [issue-id]

Read the description, acceptance criteria, and any existing comments carefully.

3. Implement the Work

Commit Strategy

• Commit early and often - each logical unit of working code
• Never commit broken code (except failing tests before TDD implementation)
• Clear messages - explain why, not just what
• No Claude references in commit messages

Track Progress with Comments

After each meaningful commit:

bd comment [issue-id] "Commit [hash]: [what was done]"

4. Complete the Issue

Before Closing

• ✅ All acceptance criteria met
• ✅ Tests pass (run them!)
• ✅ All changes committed to git
• ✅ No uncommitted files related to this issue

Close with Summary

bd close [issue-id] --reason "Brief summary of what was completed"

5. Report Back

When done, provide a brief summary:

• What was implemented
• Key commits made
• Any issues discovered (should be filed with bd create)
• Final status

Handling Blockers

If you discover a blocker:

# Create blocker issue
bd create "Fix: [blocker description]" \
  --priority 0 \
  --description "Discovered while working on [issue-id]"

# Link dependency
bd dep add [issue-id] [blocker-id] --type blocks

# Comment on original
bd comment [issue-id] "Blocked by [blocker-id]: [reason]"

# Reopen original issue
bd update [issue-id] --status open

Then report back that the issue is blocked.

Discovering New Work

If you find additional work needed:

bd create "[New task]" \
  --description "Discovered during [issue-id]: [context]"
bd comment [issue-id] "Created [new-id] for [reason]"

Continue with the original issue unless it's truly blocked.

Error Handling

If you cannot complete the issue:

1. Document what was done in a comment
2. Document what's blocking completion
3. Either:
   • Create a blocker issue and link it
   • Or leave in_progress with clear comment about state
4. Report back with status and blockers

Best Practices

1. One Issue Focus - Don't work on other issues, stay focused
2. Atomic Commits - Small, working increments
3. Rich Comments - Reference commits, document decisions
4. Test Before Close - Verify functionality works
5. Clean Exit - Always leave issue in a valid state (closed or clearly documented)

bdexecplan.md

description	allowed-tools
execute a set of bd issues sequentially	Bash(bd:*), Skill

Execute BD Plan

Overview

Execute a bd plan by running /bdexecissue for each ready issue. Each issue runs in a forked context (context isolation without summarization), so you see full progress while keeping the orchestrator context clean.

Arguments

$ARGUMENTS

Optional: epic ID or search term to scope which issues to work on. If not provided, works through all ready issues.

Instructions

How it works

bdexecplan
    ├── /bdexecissue issue-1  (forked context, full output)
    ├── /bdexecissue issue-2  (forked context, full output)
    └── /bdexecissue issue-N  (forked context, full output)

Each /bdexecissue runs in a forked context—you see full progress, but tool calls don't pollute the main conversation.

1. Initial Plan Review (if scoped)

If an epic ID or scope is provided:

bd show [epic-id]          # Understand the plan
bd dep tree [epic-id]      # See structure

2. Main Orchestration Loop

Repeat until no ready issues remain:

Step A: Find Ready Work

bd ready

If scoped to an epic, filter to relevant issues.

Step B: Select Next Issue

• Choose by priority (lower number = higher priority)
• If tied, take the first one
• Don't deliberate - just pick and go

Step C: Show Summary Card, then Run /bdexecissue [issue-id]

Before invoking bdexecissue, output a brief summary card so the user knows what's being worked on:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: [issue-id] (P[priority])
  [issue title]
  [1-2 line description or acceptance criteria summary]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Then use the Skill tool to invoke bdexecissue with the issue ID.

Step D: Process Result and Show Completion Card

When the issue completes, output a completion card:

✓ DONE: [issue-id] — [outcome: completed/blocked/needs-attention]
  [brief summary of what happened]

• If blocked, bdexecissue should have created/linked blocker issues
• Continue to next ready issue

Step E: Repeat

bd ready

Loop back to Step B if issues remain.

3. Completion

When bd ready returns no issues:

bd list --status open    # Verify nothing remaining

If all issues in an epic are done:

bd close [epic-id] --reason "All subtasks completed"

Orchestrator State Tracking

Keep a simple mental log:

• Issues attempted
• Issues completed
• Issues blocked (and why)
• New issues discovered

Report summary at end.

Handling Blocked Issues

If an issue reports blocked:

1. Verify blocker issue was created
2. Check if blocker is something you can address
3. If blocker is ready, run /bdexecissue for it next
4. Otherwise, note it and continue with other ready work

Example Session

# Start
bd ready
→ proj-12 (p1), proj-15 (p2), proj-18 (p2)

# Summary card before running
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-12 (P1)
  Add user authentication to API endpoints
  Implement JWT validation middleware for protected routes
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# Run first issue
/bdexecissue proj-12
→ [forked context runs]

✓ DONE: proj-12 — completed
  Added JWT middleware, updated 3 endpoints, tests passing

# Check ready again
bd ready
→ proj-13 (p1, was blocked by proj-12), proj-15 (p2), proj-18 (p2)

# Summary card
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-13 (P1)
  Refactor database connection pooling
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/bdexecissue proj-13
→ [forked context runs]

✗ DONE: proj-13 — blocked
  Missing config schema, created proj-19 as blocker

# Check ready
bd ready
→ proj-19 (p0, blocker), proj-15 (p2), proj-18 (p2)

# Summary card for blocker
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
▶ STARTING: proj-19 (P0)
  Add config schema for connection pool settings
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

/bdexecissue proj-19
→ [forked context runs]

✓ DONE: proj-19 — completed
  Added schema, proj-13 now unblocked

# Continue until bd ready returns empty...

Best Practices

1. Stay Lightweight - Orchestrator only tracks status, doesn't do implementation
2. Trust bdexecissue - Let it handle the details
3. React to Blockers - Check if newly-ready issues include just-created blockers
4. Report Progress - Keep user informed of overall status between issues

Stopping Conditions

Stop the loop when:

• bd ready returns no issues (success!)
• Critical blocker needs human input (report and ask)
• Repeated failures on same issue (escalate)

bdplan.md

description	allowed-tools
plan a set of bd issues	Bash(bd:*)

Create BD Implementation Plan

Overview

Create a structured implementation plan as a series of linked bd issues with dependency management. Uses bd's native issue tracking and dependency chains to represent a complete project plan.

Plan Creation Process

Initialization

1. Ensure bd is initialized: Check if .beads/ directory exists
2. Parse Requirements: Extract key functionality, constraints, and goals from input
3. Structure Plan: Break down into hierarchical tasks with dependencies
4. Create Issues: Generate bd issues with proper blocking relationships

Issue Structure Strategy

Hierarchical Organization

Use bd's dependency system to create project structure:

• Epic Issues: High-level features (e.g., "Implement user authentication")
• Task Issues: Specific implementation steps
• Dependencies: Use bd dep add to chain tasks in execution order

Dependency Types to Use

• blocks: For sequential tasks (Task B must complete before Task A)
• parent-child: For epic/subtask relationships
• related: For tasks that share context but don't block

Creating the Plan

🔑 Best Practice: Use --parent and --blocks flags during creation

Instead of creating all issues first and then adding dependencies separately, set dependencies during issue creation for maximum efficiency:

# ✅ EFFICIENT: Dependencies set during creation
bd create "Task name" \
  --parent [epic-id] \
  --blocks [blocking-task-id] \
  --blocks [another-blocker]

# ❌ INEFFICIENT: Separate dep add commands
bd create "Task name"
bd dep add [epic-id] [task-id] --type parent-child
bd dep add [task-id] [blocker] --type blocks

Benefits:

• Fewer commands (1 instead of 3+)
• Clearer intent (dependencies visible in creation)
• Easier to script and automate
• Less error-prone (no ID tracking needed)

Step 1: Create Epic Issue

bd create "Plan: [Feature Name]" \
  --priority 0 \
  --type epic \
  --description "Executive summary and technical approach"

Step 2: Create Task Issues with Dependencies

For each implementation step, use --parent and --blocks flags to set dependencies during creation:

# Create task with parent and blocking relationships in one command
bd create "[Task Description]" \
  --priority [0-4] \
  --type [feature|bug|task] \
  --description "Detailed implementation notes" \
  --parent [epic-id] \
  --blocks [blocking-task-id] \
  --assignee [optional]

Using --parent flag:

• Automatically creates parent-child dependency
• Child task is created, parent epic depends on it
• More efficient than separate bd dep add command

Using --blocks flag:

• Automatically creates blocks dependency
• New task depends on (is blocked by) the specified task
• Multiple --blocks flags can be used for multiple blockers

Alternative: Manual Dependency Management If you need to add dependencies after creation:

# Task B blocks Task A (A depends on B)
bd dep add [prefix]-[A] [prefix]-[B] --type blocks

# Create parent-child for epic relationship
bd dep add [epic-id] [task-id] --type parent-child

⚠️ CRITICAL: Parent-Child Dependency Direction

The parent-child dependency type uses the format: parent depends_on child

# ✅ CORRECT: Parent epic depends on child task
bd dep add [parent-epic-id] [child-task-id] --type parent-child

# ❌ WRONG: Child depends on parent (backwards, won't show in tree)
bd dep add [child-task-id] [parent-epic-id] --type parent-child

Why this matters:

• The dependency tree shows issues that appear in the parent's depends_on_id field
• Backwards dependencies cause children to NOT appear under their parent in bd dep tree
• The semantics: "parent depends on child" means "parent is complete when children are done"

Verification:

# After adding dependencies, always verify:
bd dep tree [epic-id]
# You should see child tasks indented under the epic
# If children don't appear, dependencies are backwards

Step 4: Verify Plan Structure

bd dep tree [epic-id]  # Visualize the full plan
bd ready               # Verify what's ready to start

Issue Content Template

Each issue should include:

Title: Clear, action-oriented description (e.g., "Implement JWT token generation")

Description:

## Context
[Why this task is needed]

## Implementation Details
[Technical approach and key considerations]

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3

## Testing
[How to verify this works]

## Notes
[Additional context, links, references]

Priority Levels

• 0: Critical path, high priority
• 1: Important but not blocking
• 2: Normal priority
• 3: Low priority
• 4: Nice to have

Status Workflow

1. open: Issue created, ready to work when unblocked
2. in_progress: Actively being worked on
3. closed: Completed successfully

Use bd ready to find next available work.

Plan Workflow Commands

View Plan Status

bd list --type epic                    # See all epics
bd show [epic-id]                      # Epic details
bd dep tree [epic-id]                  # Full plan structure
bd ready                               # What can be worked on now
bd blocked                             # What's waiting on dependencies

Work on Plan

bd ready                               # Find next task
bd update [issue-id] --status in_progress  # Start work
bd comment [issue-id]                  # Add progress notes
bd close [issue-id]                    # Complete task
bd ready                               # Find next task

Track Progress

bd stats                               # Overall progress
bd list --status open                  # Remaining work
bd list --status closed                # Completed work
bd stale                               # Issues not recently updated

Input Processing

When user provides requirements:

1. Parse Requirements:

   • Identify main feature/change
   • Extract key components and phases
   • Determine logical groupings

2. Create Epic:

   • One epic for the overall plan
   • Summary in title
   • Full context in description

3. Break Down Tasks:

   • Each atomic step becomes an issue
   • Descriptive titles
   • Detailed descriptions with acceptance criteria

4. Map Dependencies:

   • Identify which tasks must happen first
   • Create blocking relationships
   • Link related tasks

5. Set Priorities:

   • Critical path items: priority 0
   • Supporting tasks: priority 1-2
   • Nice-to-haves: priority 3-4

6. Output Summary:

   • Show created issues
   • Display dependency tree
   • List first ready tasks

Example Plan Creation

Given requirements: "Build user authentication with email/password and JWT tokens"

Efficient approach using --parent and --blocks:

# Step 1: Create epic (assuming it gets ID proj-100)
EPIC=$(bd create "Plan: User Authentication System" \
  --type epic \
  --priority 0 \
  --description "Complete user auth with email/password and JWT" \
  --json | jq -r '.issues[0].id')

# Step 2: Create tasks with dependencies in one command each
# First task (no blockers)
SCHEMA=$(bd create "Design database schema for users table" \
  --parent $EPIC \
  --json | jq -r '.issues[0].id')

# Tasks that depend on schema
REG=$(bd create "Implement user registration endpoint" \
  --parent $EPIC \
  --blocks $SCHEMA \
  --json | jq -r '.issues[0].id')

HASH=$(bd create "Implement password hashing with bcrypt" \
  --parent $EPIC \
  --blocks $SCHEMA \
  --json | jq -r '.issues[0].id')

# JWT utility (no dependencies)
JWT=$(bd create "Create JWT token generation utility" \
  --parent $EPIC \
  --json | jq -r '.issues[0].id')

# Login needs JWT utility and registration
bd create "Implement login endpoint with token issuance" \
  --parent $EPIC \
  --blocks $JWT \
  --blocks $REG

# Middleware needs login (get login ID from previous command if needed)
bd create "Add authentication middleware" \
  --parent $EPIC \
  --blocks proj-105  # Login endpoint ID

# Tests need everything (use final --blocks for last critical task)
bd create "Write integration tests for auth flow" \
  --parent $EPIC \
  --blocks proj-106  # Middleware ID

# Step 3: View the plan
bd dep tree $EPIC
bd ready

Alternative: Old approach (less efficient but works)

# Create all issues first
bd create "Plan: User Authentication System" --type epic -p 0
bd create "Design database schema for users table"
bd create "Implement user registration endpoint"
# ... create all tasks

# Then add dependencies manually (20+ commands)
bd dep add proj-100 proj-101 --type parent-child
bd dep add proj-100 proj-102 --type parent-child
# ... repeat for all parent-child relationships

bd dep add proj-102 proj-101 --type blocks
bd dep add proj-103 proj-101 --type blocks
# ... repeat for all blocking relationships

Raw Requirements

$ARGUMENTS

Git Integration

bd auto-syncs with git:

• Issues export to .beads/*.jsonl automatically
• Changes sync across team members via git
• No manual export/import needed
• Plan persists in version control

Multi-Repository Plans

For plans spanning multiple repos:

bd init --prefix api    # In api repo
bd init --prefix web    # In web repo

# Reference across repos in descriptions
bd create "Integrate with API" \
  --description "Depends on api-15 being deployed"

Cleanup

When plan is complete:

bd cleanup --age 30d    # Archive old closed issues
bd compact              # Compress issue history

Advanced Features

Templates

Create issue templates for common task types:

bd template create feature-task
# Opens editor with template

Comments for Progress

bd comment [issue-id]
# Add detailed progress notes, blockers, decisions

Labels

Organize by component:

bd label add [issue-id] "backend"
bd label add [issue-id] "database"
bd list --label backend

Benefits Over Traditional Planning

1. Dependency Awareness: bd ready always shows unblocked work
2. Git Native: Plans version controlled and synced
3. Programmatic: --json flags for agent integration
4. Flexible: Add/modify issues as plan evolves
5. Visible: bd dep tree shows complete structure
6. Audit Trail: Full history in git and issue comments