Agent skill
bd-issue-tracking
Track and manage work with bd issue tracker for persistent context across sessions and compaction events. Use for work needing dependencies, recovery after compaction, or multi-session tracking.
Install this agent skill to your Project
npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/devops/bd-issue-tracking
SKILL.md
bd Issue Tracking
bd is a graph-based issue tracker providing persistent memory across sessions. Use for multi-session work; use TodoWrite for simple single-session tasks.
When to Use bd vs TodoWrite
| Use bd | Use TodoWrite |
|---|---|
| Multi-session work (days/weeks) | Single-session tasks (this hour) |
| Complex dependencies/blockers | Linear step-by-step execution |
| Need context after compaction | All context in conversation |
| Fuzzy/exploratory work | Simple checklist |
Decision rule: "If I need this context in 2 weeks after compaction, use bd"
Session Start
bd ready --json # Find available work
bd list --status in_progress --json # Check active work
bd show <issue-id> # Read notes from previous session
Report to user: "X items ready. Issue Y in_progress: [summary from notes]"
Core Operations
# Create issue
bd create "Title" -d "Description" -p 2 -t task --json
# Start work
bd update bd-xxx --status in_progress --json
# Checkpoint progress (at 70% tokens, milestones, blockers)
bd update bd-xxx --notes "COMPLETED: ...\nIN_PROGRESS: ...\nNEXT: ..." --json
# Complete work
bd close bd-xxx --reason "What was done and how verified" --json
# Manage dependencies
bd dep add bd-setup bd-impl --type blocks # A blocks B
bd dep tree bd-xxx # View dependency tree
Notes Format
Write for post-compaction recovery (no conversation context):
COMPLETED: Specific deliverables done
KEY DECISION: Important choices with rationale
IN PROGRESS: Current state + immediate next step
BLOCKERS: What's preventing progress
NEXT: What to do when unblocked
Priority Levels
0=critical, 1=high, 2=normal (default), 3=low, 4=backlog
Description Template
bd create --title "$TITLE" --description "$(cat <<'EOF'
# Description
1-4 sentences: what and why.
# Relevant files and snippets
Files identified during discovery with code snippets.
# Additional sources
Repos explored, web searches performed.
EOF
)" --json
Reference Documentation
For detailed guidance, read these files:
| Topic | Reference |
|---|---|
| bd vs TodoWrite decisions | references/BOUNDARIES.md |
| Complete CLI reference | references/CLI_REFERENCE.md |
| Session workflows & checklists | references/WORKFLOWS.md |
| Dependency types & patterns | references/DEPENDENCIES.md |
| Issue creation guidance | references/ISSUE_CREATION.md |
| Context recovery patterns | references/RESUMABILITY.md |
| Static data usage | references/STATIC_DATA.md |
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
agent-ops-spec
Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-testing
Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.
agent-ops-state
Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.
Didn't find tool you were looking for?