Tbd

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. Installed Claude hooks call this at session start and before compaction when .tbd/ is detected.

Setup/Refresh: A fresh repository needs tbd setup --auto --prefix=<name>; ask the user for the prefix. Run tbd setup --auto to refresh an existing tbd repository.

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 (open; no delegate, hold, future deferral, or non-closed blocker)
• tbd list --status open - All open issues
• tbd list --status in_progress - All in-progress 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 start <id> - 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

Use tbd start, not a raw status update, to claim work. It records the acting agent in delegate. On an already in-progress bead, it reports a different visible delegate instead of overwriting that claim. It does not require readiness or coordinate with a stale clone. Before editing, run tbd sync --pull, re-read the bead, use tbd start <id>, and run tbd sync so other replicas can see the accepted claim. assignee remains the person accountable for the work. The acting name resolves from start --as, then TBD_AGENT, then the machine-local session identity, and finally a derived <harness>@<host> fallback. Use tbd whoami to inspect it; setup hooks initialize the local identity with tbd whoami --ensure-id.

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 docs and issue Git status without syncing

Note: tbd sync handles all git operations for issues--no manual git push needed. Plain sync also handles trackers according to integrations.on_tbd_sync. Top-level --push/--pull selects the issue Git surface and excludes trackers unless --integrations is explicit. tbd sync --status checks docs and issue Git only; use tbd integration status for tracker health.

Project Health

• tbd stats - Project statistics (open/closed/blocked counts)
• tbd doctor - Check for issues (sync problems, missing hooks)

Common Workflows

Starting work:

tbd sync --pull                        # Refresh shared state
tbd ready                              # Find available work
tbd show <id>                          # Review current issue details
tbd start <id>                         # Claim it
tbd sync                               # Publish the claim

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 --prefix=<name> - Initialize a fresh repository
• tbd setup --auto - Refresh an existing tbd repository
• tbd setup --from-beads - In an uninitialized repository, import and archive .beads/; verify the import because setup can continue after a warning
• tbd setup --auto --surfaces=<list> - Generate a comma-separated subset of portable, agents-md, claude, and codex; omission installs all four

The surface selector controls only generated agent files, not initialization, migrations, or docs refresh. Bare tbd setup displays help. Beads migration renames only .beads/ to .beads-disabled/; it does not remove other Beads integrations.

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, blocked, deferred, closed
• JSON output: Data-oriented commands honor --json; raw document commands such as readme, prime, skill, and closing remain text