--- name: beads description: Git-backed issue tracker for multi-session work with dependencies and persistent memory across conversation compaction. Use when work spans sessions, has blockers, or needs context recovery after compaction. --- # Beads (bd) - Git-Backed Issue Tracker Use the `bd` CLI for managing work that spans sessions, has dependencies, or needs to persist across conversation compaction. ## When to Use Beads **Use `bd` for:** - Work spanning multiple sessions - Tasks with dependencies or blockers - Complex multi-step implementations - Discovered work that needs tracking - Epics with child tasks - Work requiring context recovery after compaction **Use TodoWrite for:** - Simple single-session tasks - Quick in-conversation tracking - No persistence needed ## Essential Commands ### Finding Work ```bash bd ready --json # Show issues ready to work (no blockers) bd list --status=open # All open issues bd list --status=in_progress # Active work bd show # Detailed view with dependencies bd blocked # Show blocked issues bd stats # Project statistics ``` ### Creating Issues ```bash # Basic creation bd create "Title" -t -p # Types: bug | feature | task | epic | chore # Priority: 0-4 (0=critical, 1=high, 2=medium, 3=low, 4=backlog) # Examples bd create "Fix auth bug" -t bug -p 1 bd create "Add export feature" -t feature -p 2 --description="Export reports as PDF" bd create "Epic: OAuth Implementation" -t epic -p 0 # With labels bd create "Update CI config" -t task -l "ci,infrastructure" ``` ### Epics with Children ```bash # Create epic bd create "Epic: Auth System" -t epic -p 0 # Returns: bd-abc123 # Create child tasks bd create "Research OAuth providers" -p 1 --parent bd-abc123 bd create "Implement backend endpoints" -p 1 --parent bd-abc123 bd create "Add frontend login UI" -p 2 --parent bd-abc123 ``` ### Dependencies ```bash # Add dependency (issue depends on depends-on) bd dep add

# Dependency types bd dep add bd-child bd-parent --type blocks # Blocking bd dep add bd-child bd-parent --type parent-child # Hierarchy bd dep add bd-bug bd-feature --type discovered-from # Discovered work ``` ### Updates and Closing ```bash bd update --status=in_progress # Claim work bd update --assignee=username # Assign bd close # Close single bd close # Close multiple (efficient) bd close --reason="Completed" # Close with reason ``` ### Labels ```bash bd label add security # Add label bd list --label backend,auth # AND filter bd list --label-any frontend,backend # OR filter ``` ### Sync ```bash bd sync # Force immediate sync (CRITICAL at session end) bd doctor # Check for issues bd doctor --fix # Auto-fix problems ``` ## Session Workflow ### Start ```bash bd prime # Load context (auto on session start) bd ready --json # Find available work bd show # Review details bd update --status=in_progress # Claim ``` ### End (CRITICAL) ```bash bd close # Close finished work bd sync # Force sync before ending git push # Push code (beads auto-synced) ``` ## Context Recovery After compaction or new session: ```bash bd prime # Reload workflow context bd list --status=in_progress # See active work bd show # Full context ``` For detailed CLI reference, see [CLI_REFERENCE.md](references\/CLI_REFERENCE.md).