<!-- Generated via `bd prime` and then modified - regenerate with that command if needed -->

Beads Workflow Context

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

When to Use bd vs TodoWrite

Use bd when:

• Multi-session work - Tasks spanning multiple compaction cycles or days
• Complex dependencies - Work with blockers, prerequisites, or hierarchical structure
• Knowledge work - Strategic documents, research, or tasks with fuzzy boundaries
• Side quests - Exploratory work that might pause the main task
• Project memory - Need to resume work after weeks away with full context

Use TodoWrite when:

• Single-session tasks - Work that completes within current session
• Linear execution - Straightforward step-by-step tasks with no branching
• Immediate context - All information already in conversation
• Simple tracking - Just need a checklist to show progress

Key insight: If resuming work after 2 weeks would be difficult without bd, use bd. If the work can be picked up from a markdown skim, TodoWrite is sufficient.

Test Yourself: bd or TodoWrite?

Ask these questions to decide:

Choose bd if:

• ❓ "Will I need this context in 2 weeks?" → Yes = bd
• ❓ "Could conversation history get compacted?" → Yes = bd
• ❓ "Does this have blockers/dependencies?" → Yes = bd
• ❓ "Is this fuzzy/exploratory work?" → Yes = bd

Choose TodoWrite if:

• ❓ "Will this be done in this session?" → Yes = TodoWrite
• ❓ "Is this just a task list for me right now?" → Yes = TodoWrite
• ❓ "Is this linear with no branching?" → Yes = TodoWrite

When in doubt: Use bd. Better to have persistent memory you don't need than to lose context you needed.

Essential Commands

Finding Work

• bd ready - Show issues ready to work (no blockers)
• bd list --status=open - All open issues
• bd list --status=in_progress - Your active work
• bd show <id> - Detailed issue view with dependencies

Creating & Updating

• bd create --title="..." --type=task|bug|feature - New issue
• bd update <id> --status=in_progress - Claim work
• bd update <id> --assignee=username - Assign to someone
• bd close <id> - Mark complete
• bd close <id1> <id2> ... - Close multiple issues at once (more efficient)
• bd close <id> --reason="explanation" - Close with reason

Dependencies & Blocking

• bd dep add <issue> <depends-on> - Add dependency (issue depends on depends-on)
• bd blocked - Show all blocked issues
• bd show <id> - See what's blocking/blocked by this issue

Common Workflows

Starting work:

bd ready           # Find available work
bd show <id>       # Review issue details
bd update <id> --status=in_progress  # Claim it

Completing work:

bd close <id1> <id2> ...    # Close all completed issues at once

Creating dependent work:

# Run bd create commands in parallel (use subagents for many items)
bd create --title="Implement feature X" --type=feature
bd create --title="Write tests for X" --type=task
bd dep add beads-yyy beads-xxx  # Tests depend on Feature (Feature blocks tests)