# 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