beads/examples/claude-code-skill/SKILL.md

name, description

name	description
bd-issue-tracking	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.

For detailed decision criteria and examples, read: references/BOUNDARIES.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:

1. Always check ready work automatically at session start
2. Report status to establish shared context

Quick Start Pattern

# At session start, run:
bd ready --json

# Report to user:
"I can see X items ready to work on: [brief summary]"

# If using global ~/.beads, note this in report

This gives immediate shared context about available work without requiring user prompting.

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.

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.

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:

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"

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

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:

bd update issue-123 --status in_progress

Update throughout work:

# Add design notes as implementation progresses
bd update issue-123 --design "Using JWT with RS256 algorithm"

# Update acceptance criteria if requirements clarify
bd update issue-123 --acceptance "- JWT validation works\n- Tests pass\n- Error handling returns 401"

Close when complete:

bd close issue-123 --reason "Implemented JWT validation with tests passing"

Important: Closed issues remain in database - they're not deleted, just marked complete for project history.

3. Planning Phase (Dependency Graphs)

For complex multi-step work, structure issues with dependencies before starting:

Create parent epic:

bd create "Implement user authentication" -t epic -d "OAuth integration with JWT tokens"

Create subtasks:

bd create "Set up OAuth credentials" -t task
bd create "Implement authorization flow" -t task
bd create "Add token refresh" -t task

Link with dependencies:

# parent-child for epic structure
bd dep add auth-epic auth-setup --type parent-child
bd dep add auth-epic auth-flow --type parent-child

# blocks for ordering
bd dep add auth-setup auth-flow

For detailed dependency patterns and types, read: references/DEPENDENCIES.md

Dependency Types Reference

bd supports four dependency types:

1. blocks - Hard blocker (issue A blocks issue B from starting)
2. related - Soft link (issues are related but not blocking)
3. parent-child - Hierarchical (epic/subtask relationship)
4. discovered-from - Provenance (issue B discovered while working on A)

For complete guide on when to use each type with examples and patterns, read: references/DEPENDENCIES.md

Integration with TodoWrite

Both tools can coexist in a session:

Recommended Pattern

1. Use bd for project-level issue tracking and dependencies
2. Use TodoWrite as "working copy" for current session's active tasks
3. Sync status: When completing TodoWrite items, update corresponding bd issues

Example Flow

Session start:
- bd ready shows: "3 issues ready to work on"
- User chooses one: "Let's work on issue-123"
- Create TodoWrite checklist for implementation steps
- bd update issue-123 --status in_progress
- Work through TodoWrite items
- When done: bd close issue-123
- bd ready to see what unblocked

For patterns on transitioning between tools mid-session, read: references/BOUNDARIES.md

Common Patterns

Pattern 1: Knowledge Work Session

User asks for strategic document development:

1. Check if bd available: bd ready
2. If related epic exists, show current status
3. Create new issues for discovered research needs
4. Use discovered-from to track where ideas came from
5. Update design notes as research progresses

Pattern 2: Side Quest Handling

During main task, discover a problem:

1. Create issue: bd create "Found: inventory system needs refactoring"
2. Link using discovered-from: bd dep add main-task new-issue --type discovered-from
3. Assess: blocker or can defer?
4. If blocker: bd update main-task --status blocked, work on new issue
5. If deferrable: note in issue, continue main task

Pattern 3: Multi-Session Project Resume

Starting work after time away:

1. Run bd ready to see available work
2. Run bd blocked to understand what's stuck
3. Run bd list --status closed --limit 10 to see recent completions
4. Run bd show issue-id on issue to work on
5. Update status and begin work

For complete workflow walkthroughs with checklists, read: references/WORKFLOWS.md

Issue Creation Guidelines

When to Ask First vs Create Directly

Ask the user before creating when:

• Knowledge work with fuzzy boundaries
• Task scope is unclear
• Multiple valid approaches exist
• User's intent needs clarification

Create directly when:

• Clear bug discovered during implementation
• Obvious follow-up work identified
• Technical debt with clear scope
• Dependency or blocker found

Reason: Creating issues helps clarify thinking, but for ambiguous knowledge work, discussion refines the task structure first.

Issue Quality

Use clear, specific titles and include sufficient context in descriptions to resume work later.

Use --design flag for:

• Implementation approach decisions, architecture notes, trade-offs considered

Use --acceptance flag for:

• Definition of done, testing requirements, success metrics

Statistics and Monitoring

Check project health:

bd stats
bd stats --json

Returns: total issues, open, in_progress, closed, blocked, ready, avg lead time

Find blocked work:

bd blocked
bd blocked --json

Use stats to:

• Report progress to user
• Identify bottlenecks
• Understand project velocity

Advanced Features

Issue Types

bd create "Title" -t task        # Standard work item (default)
bd create "Title" -t bug         # Defect or problem
bd create "Title" -t feature     # New functionality
bd create "Title" -t epic        # Large work with subtasks
bd create "Title" -t chore       # Maintenance or cleanup

Priority Levels

bd create "Title" -p 0    # Highest priority (critical)
bd create "Title" -p 1    # High priority
bd create "Title" -p 2    # Normal priority (default)
bd create "Title" -p 3    # Low priority

Bulk Operations

# Close multiple issues at once
bd close issue-1 issue-2 issue-3 --reason "Completed in sprint 5"

# Create multiple issues from markdown file
bd create --file issues.md

Dependency Visualization

# Show full dependency tree for an issue
bd dep tree issue-123

# Check for circular dependencies
bd dep cycles

Built-in Help

# Quick start guide (comprehensive built-in reference)
bd quickstart

# Command-specific help
bd create --help
bd dep --help

JSON Output

All bd commands support --json flag for structured output:

bd ready --json
bd show issue-123 --json
bd list --status open --json
bd stats --json

Use JSON output when you need to parse results programmatically or extract specific fields.

Troubleshooting

If bd command not found:

• Check installation: bd version
• Verify PATH includes bd binary location

If issues seem lost:

• Use bd list to see all issues
• Filter by status: bd list --status closed
• Closed issues remain in database permanently

If dependencies seem wrong:

• Use bd show issue-id to see full dependency tree
• Use bd dep tree issue-id for visualization
• Dependencies are directional: bd dep add from-id to-id means from-id blocks to-id
• See references/DEPENDENCIES.md

If database seems out of sync:

• bd auto-syncs JSONL after each operation (5s debounce)
• bd auto-imports JSONL when newer than DB (after git pull)
• Manual operations: bd export, bd import

Reference Files

Detailed information organized by topic:

Reference	Read When
references/BOUNDARIES.md	Need detailed decision criteria for bd vs TodoWrite, or integration patterns
references/CLI_REFERENCE.md	Need complete command reference, flag details, or examples
references/WORKFLOWS.md	Need step-by-step workflows with checklists for common scenarios
references/DEPENDENCIES.md	Need deep understanding of dependency types or relationship patterns