| name | tbd |
| description | Lightweight, git-native issue tracking (aka beads) for AI agents. Use for creating, planning, updating, and tracking issues with dependencies. Invoke when user mentions tbd, beads, to-do lists, planning, tracking tasks, issues, or bugs. |
| allowed-tools | Bash(tbd:*), Read, Write |
tbd Workflow
tbd provides lightweight, git-native task and issue tracking using beads, which are
just lightweight issues managed from the CLI.
Context Recovery: Run tbd prime after compaction, clear, or new session.
Hooks auto-call this in Claude Code when .tbd/ detected.
SESSION CLOSING PROTOCOL
CRITICAL: Before saying “done” or “complete”, you MUST run this checklist:
[ ] 1. Stage and commit: git add + git commit
[ ] 2. Push to remote: git push
[ ] 3. Start CI watch (BLOCKS until done): gh pr checks <PR> --watch 2>&1
[ ] 4. While CI runs: tbd close/update <id> for issues worked on
[ ] 5. While CI runs: tbd sync
[ ] 6. Return to step 3 and CONFIRM CI passed
[ ] 7. If CI failed: fix, re-push, restart from step 3
NON-NEGOTIABLE Requirements
CI: Wait for --watch to finish
The --watch flag blocks until ALL checks complete.
Do NOT see “passing” in early output and move on—wait for the final summary showing
all checks passed.
tbd: Update issues and sync
Every session must end with tbd in a clean state:
- Close/update every issue you worked on
- Run
tbd sync and confirm it completed
Work is not done until pushed, CI passes, and tbd is synced.
Core Rules
- Track all task work not being done immediately as beads using
tbd (discovered
work, future work, TODOs for the session, multi-session work)
- When in doubt, prefer tbd for tracking tasks, bugs, and issues
- Use
tbd create for creating beads
- Git workflow: update or close issues and run
tbd sync at session end
- If not given specific directions, check
tbd ready for available work
Essential Commands
Finding Work
tbd ready - Show issues ready to work (no blockers)tbd list --status open - All open issuestbd list --status in_progress - Your active worktbd show <id> - Detailed issue view with dependencies
Creating & Updating
tbd create "title" --type task|bug|feature --priority P2 - New issue
- Priority: P0-P4 (P0=critical, P2=medium, P4=backlog).
Do NOT use "high"/"medium"/"low"
tbd update <id> --status in_progress - Claim worktbd update <id> --assignee username - Assign to someonetbd close <id> - Mark completetbd close <id> --reason "explanation" - Close with reason- Tip: When creating multiple issues, use parallel subagents for efficiency
Dependencies & Blocking
tbd dep add <issue> <depends-on> - Add dependency (issue depends on depends-on)tbd blocked - Show all blocked issuestbd show <id> - See what’s blocking/blocked by this issue
Sync & Collaboration
tbd sync - Sync with git remote (run at session end)tbd sync --status - Check sync status without syncing
Note: tbd sync handles all git operations for issues--no manual git push needed.
Project Health
tbd stats - Project statistics (open/closed/blocked counts)tbd doctor - Check for issues (sync problems, missing hooks)
Common Workflows
Starting work:
tbd ready
tbd show <id>
tbd update <id> --status in_progress
Completing work:
tbd close <id>
tbd sync
Creating dependent work:
tbd create "Implement feature X" --type feature
tbd create "Write tests for X" --type task
tbd dep add <tests-id> <feature-id>
Setup Commands
tbd setup claude - Install Claude Code hooks and skill filetbd setup cursor - Create Cursor IDE rules filetbd setup codex - Create/update AGENTS.md for Codextbd setup beads --disable - Migrate from Beads to tbd
Quick Reference
- Priority levels: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
- Issue types: task, bug, feature, epic
- Status values: open, in_progress, closed
- JSON output: Add
--json to any command for machine-readable output
