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
• •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 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 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: task, bug, feature, epic
• •Status values: open, in_progress, closed
• •JSON output: Add --json to any command for machine-readable output