| name | using-beads-for-task-management |
| description | Use when managing tasks and long-term memory with Beads in a repository or workspace. |
Issue Tracking with bd (beads)
IMPORTANT: Use this skill only in repositories/workspaces that intentionally use bd (beads) for issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
Why bd?
- Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
Quick Start
Check for ready work:
bd ready --json
Create new issues:
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
Claim and update:
bd update <id> --claim --json
bd update bd-42 --priority 1 --json
Complete work:
bd close bd-42 --reason "Completed" --json
Issue Types
bug - Something broken
feature - New functionality
task - Work item (tests, docs, refactoring)
epic - Large feature with subtasks
chore - Maintenance (dependencies, tooling)
Priorities
0 - Critical (security, data loss, broken builds)
1 - High (major features, important bugs)
2 - Medium (default, nice-to-have)
3 - Low (polish, optimization)
4 - Backlog (future ideas)
Workflow for AI Agents
- Check ready work:
bd ready shows unblocked issues
- Claim your task atomically:
bd update <id> --claim
- Work on it: Implement, test, document
- Discover new work? Create linked issue:
bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
- Complete:
bd close <id> --reason "Done"
Quality
- Use
--acceptance and --design fields when creating issues
- Use
--validate to check description completeness
Lifecycle
bd defer <id> / bd supersede <id> for issue management
bd stale / bd orphans / bd lint for hygiene
bd human <id> to flag for human decisions
bd formula list / bd mol pour <name> for structured workflows
Auto-Sync
bd automatically syncs via Dolt:
- Each write auto-commits to Dolt history
- Use
bd dolt push/bd dolt pull for remote sync
- No manual export/import needed!
Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use
--json flag for programmatic use
- ✅ Link discovered work with
discovered-from dependencies
- ✅ Check
bd ready before asking "what should I work on?"
- ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
For more details, see README.md and docs/QUICKSTART.md.