tbd git:20260529.38a854eA

Immutable. This exact content is served forever at /api/v1/blob/6605ac525797709e.

---
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
- 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:**

```bash
tbd ready                              # Find available work
tbd show <id>                          # Review issue details
tbd update <id> --status in_progress   # Claim it
```

**Completing work:**

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

**Creating dependent work:**

```bash
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