---
name: tbd
description: >-
  Git-native issue tracking (beads), coding guidelines, and spec-driven planning for AI agents.
  Use for tracking issues with dependencies, creating and closing bugs, features, and tasks,
  planning specs for new features, implementing features from specs, code reviews, committing code,
  creating PRs, research briefs, and architecture docs. Invoke when user mentions: tbd, beads,
  issues, bugs, tasks, todo, tracking, specs, planning, implementation, validation, guidelines,
  shortcuts, templates, commit, PR workflows, code review, testing best practices, or monorepo patterns.
allowed-tools: Bash(tbd:*), Read, Write
---

# tbd Workflow

**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**

1. **Issue Tracking**: Git-native tasks/bugs.
   Never lose work across sessions.
2. **Spec-Driven Workflows**: Plan features → break into issues → implement
   systematically.
3. **Shortcuts**: Pre-built processes for commits, PRs, reviews.
4. **Guidelines**: Best practices for TypeScript, Python, testing.

These features work together to create high-quality workflows.
Be sure to apply the workflows below for all issue tracking, spec driven planning and
implementation, and code review.

## Installation

If `tbd` is not installed, install and set up:

```bash
npm install -g tbd-git@latest
tbd                                # Gives full orientation
tbd setup --auto --prefix=<name>   # Fresh project (--prefix REQUIRED)
tbd setup --auto                   # Existing tbd project (prefix already set)
```

The prefix appears in every issue ID (e.g., `myapp-a1b2`) and is a matter of user
preference for a given project.

**IMPORTANT NOTES ON SETUP:**
- **Fresh projects**: `--prefix` is REQUIRED. NEVER guess or invent a prefix.
  Always ask the user first.
- **Existing tbd projects** (`.tbd/` exists): No `--prefix` needed, just run
  `tbd setup --auto`.
- **Beads migration** (`.beads/` exists): Use `tbd setup --from-beads` (uses beads
  prefix).
- **Refresh configs**: Run `tbd setup --auto` anytime to update skill files, hooks, and
  get the latest shortcuts/guidelines/templates.

> `tbd prime` restores context after compaction/clear (auto-called by hooks).

## CRITICAL: You Use tbd — The User Doesn’t

**You are the tbd operator.** The user talks to you naturally; you translate their
requests into tbd actions.
Never tell the user to run tbd commands themselves.

- **WRONG**: "Run `tbd create` to track this bug"

- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*

- **WRONG**: "You can use `tbd ready` to see available work"

- **RIGHT**: *(you run `tbd ready` yourself and show the user what’s available)*

## Orientation and Help

When users ask for orientation, help getting started, or want to understand tbd:

- Run `tbd shortcut welcome-user` and follow its instructions
- Show the user what they can **say** (natural language), not commands to run
- The welcome message explains tbd’s value through examples of what the user can ask

**DO NOT** respond to “what is tbd?”
or “help me get started” by listing CLI commands.
Instead, welcome them and show them the kinds of things they can ask you to do.

## How to Use tbd to Help Users

Use tbd proactively on behalf of the user:

- User describes a bug → You run `tbd create "Bug: ..." --type=bug`
- User wants a feature → You create a plan spec, then break into issues
- Starting a session → You check `tbd ready` for available work
- Completing work → You run `tbd close <id>` with clear reason
- User asks what tbd does → You run `tbd shortcut welcome-user`
- User asks for help/orientation → You run `tbd shortcut welcome-user`

### Quick Reference Table

This table shows what the user says naturally and what you (the agent) do in response.

| What the User Says | What You (Agent) Do | What Happens |
| --- | --- | --- |
| "There's a bug where ..." | `tbd create "..." --type=bug` | Creates and tracks a bug |
| "Let's work on current issues" | `tbd ready` | Shows ready issues |
| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` | You follow the guidelines |
| "Improve eslint setup" | `tbd guidelines typescript-monorepo-patterns` | You follow the guidelines |
| "Add better e2e testing" | `tbd guidelines golden-testing-guidelines` | You follow the guidelines |
| "Review these changes" (TypeScript) | `tbd guidelines typescript-rules` | You follow the guidelines |
| "Review these changes" (Python) | `tbd guidelines python-rules` | You follow the guidelines |
| "Let's plan a new feature" | `tbd shortcut new-plan-spec` | You follow the spec template |
| "Break spec into issues" | `tbd shortcut new-implementation-beads-from-spec` | You create implementation issues |
| "Implement these issues" | `tbd shortcut implement-beads` | You implement systematically |
| "Commit this" | `tbd shortcut commit-code` | You review and commit |
| "Create a PR" | `tbd shortcut create-or-update-pr-simple` | You create the PR |
| "Research this topic" | `tbd shortcut new-research-brief` | You research and document |
| "Document this architecture" | `tbd shortcut new-architecture-doc` | You create the doc |
| *(your judgment)* | `tbd dep add`, `tbd close`, `tbd sync` | You manage issues as needed |

## IMPORTANT: 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.**

## IMPORTANT: Issue Tracking 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)

## Documentation Commands

### Shortcuts

Reusable instruction templates for common tasks:

- `tbd shortcut <name>` - Output a shortcut by name
- `tbd shortcut --list` - List all available shortcuts

### Guidelines

Coding rules and best practices:

- `tbd guidelines <name>` - Output a guideline by name
- `tbd guidelines --list` - List all available guidelines

Example: `tbd guidelines typescript-rules`

### Templates

Document templates for specs, research, architecture:

- `tbd template <name>` - Output a template by name
- `tbd template --list` - List all available templates

Example: `tbd template plan-spec > docs/project/specs/active/plan-YYYY-MM-DD-feature.md`

## 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