tbd

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.

Setup/Refresh: Run tbd setup --auto to set up or refresh tbd configuration. This is idempotent and safe to run anytime.

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
• Remote/proxied session where GitHub seems blocked? If the environment has egress, gh works through a scoped NO_PROXY bypass — run tbd shortcut setup-github-cli and follow “Proxied Remote Sessions” before concluding gh is unavailable
• 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 issues
• tbd list --status in_progress - Your active work
• tbd show <id> - Detailed issue view with dependencies

Creating & Updating

• tbd create "title" --type=bug --priority=1 - New issue (run tbd create --help for all types and priorities)
  • Priority: P0-P4 (P0=critical, P2=medium, P4=backlog). Do NOT use "high"/"medium"/"low"
• tbd update <id> --status in_progress - Claim work
• tbd update <id> --assignee username - Assign to someone
• tbd close <id> - Mark complete
• tbd 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 issues
• tbd 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                              # Find available work
tbd show <id>                          # Review issue details
tbd update <id> --status in_progress   # Claim it

Completing work:

tbd close <id>    # Mark complete
tbd sync          # Push to remote

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>   # Tests depend on feature

Setup Commands

• tbd setup --auto - Non-interactive setup with smart defaults (for agents/scripts)
• tbd setup --interactive - Interactive setup with prompts (for humans)
• tbd setup --from-beads - Migrate from Beads to tbd

Quick Reference

• Priority levels: 0=critical, 1=high, 2=medium (default), 3=low, 4=backlog
• Issue types: default task; run tbd create --help for the valid types
• Status values: open, in_progress, closed
• JSON output: Add --json to any command for machine-readable output