bd Issue Tracking

bd is a graph-based issue tracker providing persistent memory across sessions. Use for multi-session work; use TodoWrite for simple single-session tasks.

When to Use bd vs TodoWrite

Decision rule: "If I need this context in 2 weeks after compaction, use bd"

Session Start

bd ready --json                              # Find available work
bd list --status in_progress --json          # Check active work
bd show <issue-id>                           # Read notes from previous session

Report to user: "X items ready. Issue Y in_progress: [summary from notes]"

Core Operations

# Create issue
bd create "Title" -d "Description" -p 2 -t task --json

# Start work
bd update bd-xxx --status in_progress --json

# Checkpoint progress (at 70% tokens, milestones, blockers)
bd update bd-xxx --notes "COMPLETED: ...\nIN_PROGRESS: ...\nNEXT: ..." --json

# Complete work
bd close bd-xxx --reason "What was done and how verified" --json

# Manage dependencies
bd dep add bd-setup bd-impl --type blocks    # A blocks B
bd dep tree bd-xxx                           # View dependency tree

Notes Format

Write for post-compaction recovery (no conversation context):

COMPLETED: Specific deliverables done
KEY DECISION: Important choices with rationale
IN PROGRESS: Current state + immediate next step
BLOCKERS: What's preventing progress
NEXT: What to do when unblocked

Priority Levels

0=critical, 1=high, 2=normal (default), 3=low, 4=backlog

Description Template

bd create --title "$TITLE" --description "$(cat <<'EOF'
# Description
1-4 sentences: what and why.

# Relevant files and snippets
Files identified during discovery with code snippets.

# Additional sources
Repos explored, web searches performed.
EOF
)" --json

Reference Documentation

For detailed guidance, read these files: