BD (Beads) issue tracker planning and execution commands for Claude Code

bdexecplan.md

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

Execute BD Plan Command

Overview

Execute a bd plan by working through issues with proper status tracking, commenting, and git workflow integration. Do not ask which one to start with. Start with any ready task by priority, if there is a tie, choose the first one. Please continue implementing until all ready tasks are complete, or you hit a critical question that demands a human answer.

Instructions

Plan Selection

• Identify the epic or starting issue based on $ARGUMENTS (can be issue ID or search term)
• Use bd show [issue-id] to view the issue details
• Use bd dep tree [epic-id] to visualize the full plan structure
• Use bd ready to find the next unblocked issue to work on
• Ensure you understand the complete scope before beginning execution

BD Workflow Integration

Starting Work

1. Find Ready Work:

   bd ready

   This shows all issues with status 'open' and no blocking dependencies

2. Claim the Issue:

   bd update [issue-id] --status in_progress

   ⚠️ CRITICAL: Always mark issue as in_progress IMMEDIATELY when starting work

3. Review Issue Details:

   bd show [issue-id]

   Read description, acceptance criteria, and any comments

During Work

1. Commit Early and Often:

   • Commit after each meaningful feature or fix is complete and working
   • Each commit should represent a single logical unit of work
   • Avoid bundling multiple unrelated changes in one commit
   • Never commit broken or failing code (unless intentionally adding failing tests before implementation)
   • Avoid mentioning Claude in commit messages

2. Add Comments to Track Progress:

   bd comment [issue-id]
   # Opens editor to add comment

   Or inline:

   bd comments add [issue-id] "Completed database schema migration"

3. Update After Each Commit: After making a git commit, document it in the issue:

   git add [files]
   git commit -m "Clear, descriptive message"
   bd comment [issue-id]
   # Add note: "Commit: [commit-hash] - [what was done]"

4. Progress Notes: Use comments to track:

   • What's been completed
   • Current blockers or challenges
   • Design decisions made
   • References to commits
   • Questions or uncertainties

Completing Work

1. Verify Acceptance Criteria:

   • Check all criteria in the issue description are met
   • Ensure tests pass
   • Verify functionality works as expected

2. Final Commit:

   git add .
   git commit -m "Descriptive message for final piece"

3. Close the Issue:

   bd close [issue-id]

   Or with a closing comment:

   bd close [issue-id] --reason "All acceptance criteria met. Tests passing."

4. Find Next Work:

   bd ready

   This automatically accounts for the just-closed issue and shows newly unblocked work

Execution Guidelines

Commit Strategy

• Early and Often: Commit small, working increments
• Logical Units: Each commit is one coherent change
• Working Code: Never commit broken code (except failing tests before TDD implementation)
• Clear Messages: Descriptive commit messages that explain why, not just what
• No Claude References: Keep commit messages professional and implementation-focused

Testing Approach

• Focus on light-touch unit and integration testing initially
• Prioritize having passing tests over exhaustive coverage
• Ensure basic functionality works before expanding test coverage
• Run tests before closing issues

Status Management

Issue status should always reflect reality:

• open: Not started, waiting for dependencies or to be claimed
• in_progress: Actively being worked on RIGHT NOW
• closed: Completed and verified

⚠️ Never leave orphaned in_progress issues - if you stop work, either close it or reopen it

Work Flow

1. Plan Review:

   bd show [epic-id]          # Understand the plan
   bd dep tree [epic-id]      # See structure
   bd ready                   # Find starting point

2. Start Issue:

   bd update [issue-id] --status in_progress  # IMMEDIATELY
   bd show [issue-id]                          # Review details

3. Implement:

   • Write code
   • Test functionality
   • Commit when working
   • Add comment with commit reference
   • Repeat

4. Complete Issue:

   bd close [issue-id]        # Mark complete
   bd ready                   # Find next work

5. Repeat until plan is complete

Git + BD Integration

BD auto-syncs with git, so your workflow is:

# Start work
bd update proj-5 --status in_progress

# Do work, commit
git add src/auth.ts
git commit -m "Implement JWT token generation"
bd comment proj-5 "Commit abc123: Added JWT generation utility"

# More work, more commits
git add tests/auth.test.ts
git commit -m "Add tests for JWT token generation"
bd comment proj-5 "Commit def456: Tests passing, token validation working"

# Complete
bd close proj-5
git push  # BD changes auto-sync via JSONL export

Tracking Progress Across Sessions

BD maintains full audit trail:

bd show [issue-id]              # See all comments and history
bd comments list [issue-id]     # List all comments
bd list --status in_progress    # What's being worked on
bd list --status closed         # What's been completed
bd stats                        # Overall progress

Handling Blockers

If you discover a blocker while working:

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

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

# Update original issue
bd comment [original-issue] "Blocked by [blocker-issue]"

# Optionally reopen original if needed
bd update [original-issue] --status open

# Work on blocker instead
bd update [blocker-issue] --status in_progress

Discovering New Work

If you discover additional work needed during execution:

# Create new issue
bd create "[New task description]" \
  --description "Discovered during [original-issue]: [context]"

# Link to plan
bd dep add [epic-id] [new-issue] --type parent-child

# Add dependencies if needed
bd dep add [dependent-issue] [new-issue] --type blocks

# Comment on discovery
bd comment [original-issue] "Created [new-issue] for [reason]"

Multi-Issue Sessions

When working through multiple issues in one session:

bd ready                # Find first issue
bd update proj-5 --status in_progress

# Work, commit, comment...

bd close proj-5         # Complete first
bd ready                # Find next
bd update proj-7 --status in_progress

# Continue...

Important: Only have ONE issue in_progress at a time (the one you're actively working on)

Plan Completion

When all issues in the plan are closed:

bd list --status open    # Verify nothing remaining
bd close [epic-id]       # Close the epic
git push                 # Sync everything

Best Practices

1. Status Hygiene:

   • Update to in_progress when you start
   • Close when truly complete
   • Don't leave stale in_progress issues

2. Comment Richness:

   • Reference commit hashes
   • Document decisions
   • Note blockers immediately
   • Link related issues

3. Commit Quality:

   • Small, focused commits
   • Clear messages
   • Working code only
   • Test before committing

4. Dependency Awareness:

   • Use bd ready to find unblocked work
   • Create blockers when discovered
   • Link new issues to plan structure

5. Full Git Commits Before Closing:

   • Ensure all changes are committed
   • Push to remote if working in a team
   • BD auto-exports to JSONL (syncs via git)
   • Never close an issue with uncommitted changes

Example Session

# Start
bd ready
# Output: proj-12 "Implement user registration endpoint"

bd update proj-12 --status in_progress
bd show proj-12
# Read requirements...

# First increment
# ... write registration route ...
git add src/routes/auth.ts
git commit -m "Add registration endpoint structure"
bd comment proj-12 "Commit a1b2c3d: Basic route structure in place"

# Second increment
# ... add validation ...
git add src/routes/auth.ts src/validation/user.ts
git commit -m "Add input validation for registration"
bd comment proj-12 "Commit e4f5g6h: Validation working, email/password checks"

# Tests
# ... write tests ...
git add tests/auth/registration.test.ts
git commit -m "Add registration endpoint tests"
bd comment proj-12 "Commit i7j8k9l: Tests passing, all acceptance criteria met"

# Complete
bd close proj-12
bd ready
# Output: proj-13 "Implement password hashing with bcrypt"

bd update proj-13 --status in_progress
# Continue...

Command Reference

Viewing Work

• bd ready - Show unblocked issues ready to work
• bd show [id] - View issue details
• bd dep tree [id] - Visualize plan structure
• bd list --status [status] - List by status
• bd blocked - Show blocked issues

Status Updates

• bd update [id] --status in_progress - Start work
• bd update [id] --status open - Reopen if needed
• bd close [id] - Mark complete

Progress Tracking

• bd comment [id] - Add progress note (opens editor)
• bd comments add [id] "message" - Quick inline comment
• bd comments list [id] - View all comments

Dependency Management

• bd dep add [depends-on] [blocker] --type blocks - Add blocker
• bd create "new task" - Create discovered work
• bd dep add [epic] [task] --type parent-child - Link to plan

Integration with Global Instructions

From your CLAUDE.md:

• ✅ Call bd commands unadorned (bd is in PATH)
• ✅ Mark tasks as in_progress immediately when starting
• ✅ Ensure fully git committed before closing issues
• ✅ Include enough detail in issues for fresh LLM sessions

Arguments

$ARGUMENTS

bdplan.md

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