--- description: How to use the bd (beads) CLI for issue tracking, dependencies, and workflow orchestration --- # BD Workflow The `bd` CLI is a git-backed issue tracker with first-class dependency support. Use it for multi-session work, blocking relationships, and persistent memory across conversation compaction. ## When to Use BD vs TodoWrite | Use BD | Use TodoWrite | |--------|---------------| | Work spans multiple sessions | Single-session tasks | | Dependencies between tasks | Independent subtasks | | Need audit trail in git | Ephemeral tracking | | Cross-repo coordination | Local project only | | Resuming after compaction | Simple task lists | ## Core Commands ### Creating Issues ```bash bd create "Issue title" # Basic task bd create "Bug title" --type=bug --priority=1 # P1 bug bd create "Feature" --type=feature -d "Details" # With description bd q "Quick capture" # Output only ID ``` ### Managing Issues ```bash bd show # View issue details bd show --children # View children of epic bd list # List open issues (default 50) bd list --all # Include closed bd list -s in_progress # Filter by status bd list -t bug -p 0 # P0 bugs bd list --pretty # Tree format ``` ### Updating Issues ```bash bd update --status=in_progress # Start work bd update --status=blocked # Mark blocked bd update --claim # Claim atomically bd update --add-label=urgent # Add label bd update -d "New description" # Update description ``` ### Closing Issues ```bash bd close # Close issue bd close --continue # Auto-advance to next step bd close --suggest-next # Show newly unblocked ``` ## Finding Work ```bash bd ready # Ready issues (no blockers) bd ready --mol # Ready steps in molecule bd ready -n 5 # Limit to 5 bd ready --assignee me # Assigned to me bd blocked # Show blocked issues bd blocked --parent # Blocked within epic ``` ## Dependency Management ### Creating Dependencies ```bash bd dep --blocks # A blocks B bd dep add # Same as above bd dep relate # Bidirectional link ``` ### Viewing Dependencies ```bash bd dep list # Show dependencies bd dep tree # Dependency tree bd dep cycles # Detect cycles ``` ### Removing Dependencies ```bash bd dep remove # Remove dependency bd dep unrelate # Remove relation ``` ## Sync Workflow BD syncs issues via git. The daemon handles this automatically, but manual sync is available: ```bash bd sync # Full sync (pull, merge, push) bd sync --flush-only # Export to JSONL only bd sync --import-only # Import from JSONL only bd sync --status # Show sync branch diff bd sync --squash # Accumulate without commit ``` ## Formula and Molecule Workflow Formulas are reusable workflow templates. Molecules are instantiated workflows. ### Formulas ```bash bd formula list # List available formulas bd formula list --type=workflow # Filter by type bd formula show # Show formula details bd cook # Compile to proto (stdout) bd cook --var name=auth # With variable substitution bd cook --dry-run # Preview steps bd cook --persist # Save to database ``` ### Molecules: Pour vs Wisp | pour (persistent) | wisp (ephemeral) | |-------------------|------------------| | Feature implementations | Release workflows | | Multi-session work | Patrol cycles | | Audit trail needed | Health checks | | Git-synced | Local only | ```bash # Persistent molecule (liquid phase) bd mol pour --var name=auth # Ephemeral molecule (vapor phase) bd mol wisp --var version=1.0 bd mol wisp list # List wisps bd mol wisp gc # Garbage collect ``` ### Tracking Molecule Progress ```bash bd mol show # Show structure bd mol show --parallel # Parallelizable steps bd mol current # Where am I? bd mol current # Status for molecule bd mol progress # Progress summary + ETA ``` ### Molecule Lifecycle ```bash bd mol squash # Condense to digest bd mol burn # Delete wisp bd mol distill # Extract formula from epic ``` ## Gates and Human Checkpoints Gates are async wait conditions that block workflow steps: | Gate Type | Wait Condition | |-----------|---------------| | human | Manual `bd close` | | timer | Timeout expires | | gh:run | GitHub workflow completes | | gh:pr | PR merges | | bead | Cross-rig bead closes | ```bash bd gate list # Show open gates bd gate list --all # Include closed bd gate check # Evaluate all gates bd gate check --type=bead # Check bead gates only bd gate resolve # Close manually ``` ## Common Patterns ### Starting Work on a Bead ```bash bd update --status=in_progress # ... do work ... bd close ``` ### Creating Related Issues ```bash bd create "Main task" --deps "blocks:" bd dep add ``` ### Working Through a Molecule ```bash bd mol pour my-workflow --var name=feature bd ready --mol # Find next step bd update --claim # Claim step # ... do work ... bd close --continue # Close and advance ``` ### Quick Status Check ```bash bd ready -n 3 # Top 3 ready items bd list -s in_progress # What's in flight? bd blocked # What's stuck? ``` ## Useful Flags | Flag | Effect | |------|--------| | `--json` | JSON output for scripting | | `--quiet` | Suppress non-essential output | | `--dry-run` | Preview without executing | | `--pretty` | Tree format display | ## Integration Notes - BD auto-syncs via daemon (check with `bd info`) - Issues stored in `.beads/` directory - JSONL files sync through git - Use `bd doctor` if something seems wrong