---

name: bd-issue-tracking description: Track complex, multi-session work with dependency graphs using bd (beads) issue tracker. Use when work spans multiple sessions, has complex dependencies, or requires persistent context across compaction cycles. For simple single-session linear tasks, TodoWrite remains appropriate.

bd Issue Tracking

Overview

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.

For detailed decision criteria and examples, read: references/BOUNDARIES.md

Surviving Compaction Events

Critical: Compaction events delete conversation history but preserve beads. After compaction, bd state is your only persistent memory.

What survives compaction:

• All bead data (issues, notes, dependencies, status)
• Complete work history and context

What doesn't survive:

• Conversation history
• TodoWrite lists
• Recent discussion context

Writing notes for post-compaction recovery:

Write notes as if explaining to a future agent with zero conversation context:

Pattern:

notes field format:
- COMPLETED: Specific deliverables ("implemented JWT refresh endpoint + rate limiting")
- IN PROGRESS: Current state + next immediate step ("testing password reset flow, need user input on email template")
- BLOCKERS: What's preventing progress
- KEY DECISIONS: Important context or user guidance

After compaction: bd show <issue-id> reconstructs full context from notes field.

Notes Quality Self-Check

Before checkpointing (especially pre-compaction), verify your notes pass these tests:

❓ Future-me test: "Could I resume this work in 2 weeks with zero conversation history?"

• [ ] What was completed? (Specific deliverables, not "made progress")
• [ ] What's in progress? (Current state + immediate next step)
• [ ] What's blocked? (Specific blockers with context)
• [ ] What decisions were made? (Why, not just what)

❓ Stranger test: "Could another developer understand this without asking me?"

• [ ] Technical choices explained (not just stated)
• [ ] Trade-offs documented (why this approach vs alternatives)
• [ ] User input captured (decisions that came from discussion)

Good note example:

COMPLETED: JWT auth with RS256 (1hr access, 7d refresh tokens)
KEY DECISION: RS256 over HS256 per security review - enables key rotation
IN PROGRESS: Password reset flow - email service working, need rate limiting
BLOCKERS: Waiting on user decision: reset token expiry (15min vs 1hr trade-off)
NEXT: Implement rate limiting (5 attempts/15min) once expiry decided

Bad note example:

Working on auth. Made some progress. More to do.

For complete compaction recovery workflow, read: references/WORKFLOWS.md

Session Start Protocol

bd is available when:

• Project has a .beads/ directory (project-local database), OR
• ~/.beads/ exists (global fallback database for any directory)

At session start, always check for bd availability and run ready check.

Session Start Checklist

Copy this checklist when starting any session where bd is available:

Session Start:
- [ ] Run bd ready --json to see available work
- [ ] Run bd list --status in_progress --json for active work
- [ ] If in_progress exists: bd show <issue-id> to read notes
- [ ] Report context to user: "X items ready: [summary]"
- [ ] If using global ~/.beads, mention this in report
- [ ] If nothing ready: bd blocked --json to check blockers

Pattern: Always check both bd ready AND bd list --status in_progress. Read notes field first to understand where previous session left off.

Report format:

• "I can see X items ready to work on: [summary]"
• "Issue Y is in_progress. Last session: [summary from notes]. Next: [from notes]. Should I continue with that?"

This establishes immediate shared context about available and active work without requiring user prompting.

For detailed collaborative handoff process, read: references/WORKFLOWS.md

Note: bd auto-discovers the database:

• Uses .beads/*.db in current project if exists
• Falls back to ~/.beads/default.db otherwise
• No configuration needed

When No Work is Ready

If bd ready returns empty but issues exist:

bd blocked --json

Report blockers and suggest next steps.

---

Progress Checkpointing

Update bd notes at these checkpoints (don't wait for session end):

Critical triggers:

• ⚠️ Context running low - User says "running out of context" / "approaching compaction" / "close to token limit"
• 📊 Token budget > 70% - Proactively checkpoint when approaching limits
• 🎯 Major milestone reached - Completed significant piece of work
• 🚧 Hit a blocker - Can't proceed, need to capture what was tried
• 🔄 Task transition - Switching issues or about to close this one
• ❓ Before user input - About to ask decision that might change direction

Proactive monitoring during session:

• At 70% token usage: "We're at 70% token usage - good time to checkpoint bd notes?"
• At 85% token usage: "Approaching token limit (85%) - checkpointing current state to bd"
• At 90% token usage: Automatically checkpoint without asking

Current token usage: Check <system-warning>Token usage: messages to monitor proactively.

Checkpoint checklist:

Progress Checkpoint:
- [ ] Update notes with COMPLETED/IN_PROGRESS/NEXT format
- [ ] Document KEY DECISIONS or BLOCKERS since last update
- [ ] Mark current status (in_progress/blocked/closed)
- [ ] If discovered new work: create issues with discovered-from
- [ ] Verify notes are self-explanatory for post-compaction resume

Most important: When user says "running out of context" OR when you see >70% token usage - checkpoint immediately, even if mid-task.

Test yourself: "If compaction happened right now, could future-me resume from these notes?"

---

Database Selection

bd automatically selects the appropriate database:

• Project-local (.beads/ in project): Used for project-specific work
• Global fallback (~/.beads/): Used when no project-local database exists

Use case for global database: Cross-project tracking, personal task management, knowledge work that doesn't belong to a specific project.

When to use --db flag explicitly:

• Accessing a specific database outside current directory
• Working with multiple databases (e.g., project database + reference database)
• Example: bd --db /path/to/reference/terms.db list

Database discovery rules:

• bd looks for .beads/*.db in current working directory
• If not found, uses ~/.beads/default.db
• Shell cwd can reset between commands - use absolute paths with --db when operating on non-local databases

For complete session start workflows, read: references/WORKFLOWS.md

Core Operations

All bd commands support --json flag for structured output when needed for programmatic parsing.

Essential Operations

Check ready work:

bd ready
bd ready --json              # For structured output
bd ready --priority 0        # Filter by priority
bd ready --assignee alice    # Filter by assignee

Create new issue:

IMPORTANT: Always quote title and description arguments with double quotes, especially when containing spaces or special characters.

bd create "Fix login bug"
bd create "Add OAuth" -p 0 -t feature
bd create "Write tests" -d "Unit tests for auth module" --assignee alice
bd create "Research caching" --design "Evaluate Redis vs Memcached"

# Examples with special characters (requires quoting):
bd create "Fix: auth doesn't handle edge cases" -p 1
bd create "Refactor auth module" -d "Split auth.go into separate files (handlers, middleware, utils)"

Update issue status:

bd update issue-123 --status in_progress
bd update issue-123 --priority 0
bd update issue-123 --assignee bob
bd update issue-123 --design "Decided to use Redis for persistence support"

Close completed work:

bd close issue-123
bd close issue-123 --reason "Implemented in PR #42"
bd close issue-1 issue-2 issue-3 --reason "Bulk close related work"

Show issue details:

bd show issue-123
bd show issue-123 --json

List issues:

bd list
bd list --status open
bd list --priority 0
bd list --type bug
bd list --assignee alice

For complete CLI reference with all flags and examples, read: references/CLI_REFERENCE.md

Field Usage Reference

Quick guide for when and how to use each bd field:

| Field | Purpose | When to Set | Update Frequency | |-------|---------|-------------|------------------| | description | Immutable problem statement | At creation | Never (fixed forever) | | design | Initial approach, architecture, decisions | During planning | Rarely (only if approach changes) | | acceptance-criteria | Concrete deliverables checklist (- [ ] syntax) | When design is clear | Mark - [x] as items complete | | notes | Session handoff (COMPLETED/IN_PROGRESS/NEXT) | During work | At session end, major milestones | | status | Workflow state (open→in_progress→closed) | As work progresses | When changing phases | | priority | Urgency level (0=highest, 3=lowest) | At creation | Adjust if priorities shift |

Key pattern: Notes field is your "read me first" at session start. See WORKFLOWS.md for session handoff details.

---

Issue Lifecycle Workflow

1. Discovery Phase (Proactive Issue Creation)

During exploration or implementation, proactively file issues for:

• Bugs or problems discovered
• Potential improvements noticed
• Follow-up work identified
• Technical debt encountered
• Questions requiring research

Pattern:

# When encountering new work during a task:
bd create "Found: auth doesn't handle profile permissions"
bd dep add current-task-id new-issue-id --type discovered-from

# Continue with original task - issue persists for later

Key benefit: Capture context immediately instead of losing it when conversation ends.

2. Execution Phase (Status Maintenance)

**Mark issues in_progress when starting work: