title: tbd Workflow
description: Full tbd workflow guide for agents
tbd helps humans and agents ship code with greater speed, quality, and discipline.
- Beads: Git-native issue tracking (tasks, bugs, features).
Never lose work across sessions.
- Spec-Driven Workflows: Plan features → break into beads → implement
systematically.
- Shortcuts: Reusable instruction templates for common workflows.
- Guidelines: Coding rules and best practices.
Installation
npm install -g get-tbd@latest
tbd setup --auto --prefix=<name> # Fresh project (--prefix is REQUIRED and should be short. For new project setup, ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)
tbd setup --auto # Existing tbd project (prefix already set)
tbd setup --from-beads # Migration from .beads/ if `bd` has been used
Routine Commands
tbd --help # Command reference
tbd status # Status
tbd doctor # If there are problems
tbd setup --auto # Run any time to refresh setup
tbd prime # Restore full context on tbd after compaction
CRITICAL: You Operate tbd — The User Doesn’t
You are the tbd operator: Users talk naturally; you translate their requests to tbd
actions. DO NOT tell users to run tbd commands.
That’s your job.
Welcoming a user: When users ask “what is tbd?”
or want help → run tbd shortcut welcome-user
User Request → Agent Action
| User Says |
You (the Agent) Run |
| "There's a bug where ..." |
tbd create "..." --type=bug |
| "Let's work on issues" |
tbd ready |
| "Build a TypeScript CLI" |
tbd guidelines typescript-cli-tool-rules |
| "Improve eslint/monorepo" |
tbd guidelines typescript-monorepo-patterns |
| "Add e2e/golden testing" |
tbd guidelines golden-testing-guidelines |
| "Review changes" (TS) |
tbd guidelines typescript-rules |
| "Review changes" (Python) |
tbd guidelines python-rules |
| "Plan a new feature" |
tbd shortcut new-plan-spec |
| "Break spec into beads" |
tbd shortcut plan-implementation-with-beads |
| "Implement these beads" |
tbd shortcut implement-beads |
| "Commit this" |
tbd shortcut commit-code |
| "Create a PR" |
tbd shortcut create-or-update-pr-simple |
| "Research this topic" |
tbd shortcut new-research-brief |
| "Document architecture" |
tbd shortcut new-architecture-doc |
| (your choice whenever appropriate) |
tbd list, tbd dep add, tbd close, tbd sync, etc. |
CRITICAL: Session Closing Protocol
Before saying “done”, you MUST complete this checklist:
[ ] 1. git add + git commit
[ ] 2. git push
[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
[ ] 4. tbd close/update <id> for all beads worked on
[ ] 5. tbd sync
[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)
Work is not done until pushed, CI passes, and tbd is synced.
Bead Tracking Rules
- Track all task work not done immediately as beads (discovered work, TODOs,
multi-session work)
- When in doubt, create a bead
- Check
tbd ready when not given specific directions
- Always close/update beads and run
tbd sync at session end
Commands
Finding Work
| Command |
Purpose |
tbd ready |
Beads ready to work (no blockers) |
tbd list --status open |
All open beads |
tbd list --status in_progress |
Your active work |
tbd show <id> |
Bead details with dependencies |
Creating & Updating
| Command |
Purpose |
tbd create "title" --type task|bug|feature --priority=P2 |
New bead (P0-P4, not "high/medium/low") |
tbd update <id> --status in_progress |
Claim work |
tbd close <id> [--reason "..."] |
Mark complete |
Dependencies & Sync
| Command |
Purpose |
tbd dep add <bead> <depends-on> |
Add dependency |
tbd blocked |
Show blocked beads |
tbd sync |
Sync with git remote (run at session end) |
tbd stats |
Project statistics |
tbd doctor |
Check for problems |
Documentation
| Command |
Purpose |
tbd shortcut <name> |
Run a shortcut |
tbd shortcut --list |
List shortcuts |
tbd guidelines <name> |
Load coding guidelines |
tbd guidelines --list |
List guidelines |
tbd template <name> |
Output a template |
Quick Reference
- Priority: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
- Types: task, bug, feature, epic
- Status: open, in_progress, closed
- JSON output: Add
--json to any command
Available Shortcuts
Run tbd shortcut <name> to use any of these shortcuts:
| Name |
Description |
| agent-handoff |
Generate a concise handoff prompt for another coding agent to continue work |
| cleanup-all |
Full cleanup cycle including duplicate removal, dead code, and code quality improvements |
| cleanup-remove-trivial-tests |
Review and remove tests that do not add meaningful coverage |
| cleanup-update-docstrings |
Review and add concise docstrings to major functions and types |
| commit-code |
Run pre-commit checks, review changes, and commit code |
| create-or-update-pr-simple |
Create or update a pull request with a concise summary |
| create-or-update-pr-with-validation-plan |
Create or update a pull request with a detailed test/validation plan |
| implement-beads |
Implement beads from a spec, following TDD and project rules |
| merge-upstream |
Merge origin/main into current branch with conflict resolution |
| new-architecture-doc |
Create an architecture document for a system or component design |
| new-guideline |
Create a new coding guideline document for tbd |
| new-plan-spec |
Create a new feature planning specification document |
| new-research-brief |
Create a research document for investigating a topic or technology |
| new-shortcut |
Create a new shortcut (reusable instruction template) for tbd |
| new-validation-plan |
Create a validation/test plan showing what's tested and what remains |
| plan-implementation-with-beads |
Create implementation beads from a feature planning spec |
| precommit-process |
Full pre-commit checklist including spec sync, code review, and testing |
| review-code |
Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |
| review-code-python |
Python-focused code review (language-specific rules only) |
| review-code-typescript |
TypeScript-focused code review (language-specific rules only) |
| review-github-pr |
Review a GitHub pull request with follow-up actions (comment, fix, CI check) |
| revise-all-architecture-docs |
Comprehensive revision of all current architecture documents |
| revise-architecture-doc |
Update an architecture document to reflect current codebase state |
| setup-github-cli |
Ensure GitHub CLI (gh) is installed and working |
| sync-failure-recovery |
Handle tbd sync failures by saving to workspace and recovering later |
| update-specs-status |
Review active specs and sync their status with tbd issues |
| welcome-user |
Welcome message for users after tbd installation or setup |
Available Guidelines
Run tbd guidelines <name> to apply any of these guidelines:
| Name |
Description |
| backward-compatibility-rules |
Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |
| cli-agent-skill-patterns |
Best practices for building TypeScript CLIs that function as agent skills in Claude Code and other AI coding agents |
| commit-conventions |
Conventional Commits format with extensions for agentic workflows |
| convex-limits-best-practices |
Comprehensive reference for Convex platform limits, workarounds, and performance best practices |
| convex-rules |
Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |
| error-handling-rules |
Rules for handling errors, failures, and exceptional conditions |
| general-coding-rules |
Rules for constants, magic numbers, and general coding practices |
| general-comment-rules |
Language-agnostic rules for writing clean, maintainable comments |
| general-eng-assistant-rules |
Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines |
| general-style-rules |
Style guidelines for auto-formatting, emoji usage, and output formatting |
| general-tdd-guidelines |
Test-Driven Development methodology and best practices |
| general-testing-rules |
Rules for writing minimal, effective tests with maximum coverage |
| golden-testing-guidelines |
Guidelines for implementing golden/snapshot testing for complex systems |
| python-cli-patterns |
Modern patterns for Python CLI application architecture |
| python-modern-guidelines |
Guidelines for modern Python projects using uv, with a few more opinionated practices |
| python-rules |
General Python coding rules and best practices |
| sync-troubleshooting |
Common issues and solutions for tbd sync and workspace operations |
| typescript-cli-tool-rules |
Rules for building CLI tools with Commander.js, picocolors, and TypeScript |
| typescript-code-coverage |
Best practices for code coverage in TypeScript with Vitest and v8 provider |
| typescript-monorepo-patterns |
Modern patterns for TypeScript monorepo architecture |
| typescript-rules |
TypeScript coding rules and best practices |
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
1---2name: jlevy-flowmark-tbd3description: <!-- DO NOT EDIT: Generated by tbd setup.4---5<!-- DO NOT EDIT: Generated by tbd setup.6Run 'tbd setup' to update.7-->89---10title: tbd Workflow11description: Full tbd workflow guide for agents12---13**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**14151. **Beads**: Git-native issue tracking (tasks, bugs, features).16 Never lose work across sessions.172. **Spec-Driven Workflows**: Plan features → break into beads → implement18 systematically.193. **Shortcuts**: Reusable instruction templates for common workflows.204. **Guidelines**: Coding rules and best practices.2122## Installation2324```bash25npm install -g get-tbd@latest26tbd setup --auto --prefix=<name> # Fresh project (--prefix is REQUIRED and should be short. For new project setup, ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)27tbd setup --auto # Existing tbd project (prefix already set)28tbd setup --from-beads # Migration from .beads/ if `bd` has been used29```3031## Routine Commands3233```bash34tbd --help # Command reference35tbd status # Status36tbd doctor # If there are problems3738tbd setup --auto # Run any time to refresh setup39tbd prime # Restore full context on tbd after compaction40```4142## CRITICAL: You Operate tbd — The User Doesn’t4344**You are the tbd operator:** Users talk naturally; you translate their requests to tbd45actions. DO NOT tell users to run tbd commands.46That’s your job.4748- **WRONG**: "Run `tbd create` to track this bug"4950- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*5152**Welcoming a user:** When users ask “what is tbd?”53or want help → run `tbd shortcut welcome-user`5455## User Request → Agent Action5657| User Says | You (the Agent) Run |58| --- | --- |59| "There's a bug where ..." | `tbd create "..." --type=bug` |60| "Let's work on issues" | `tbd ready` |61| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |62| "Improve eslint/monorepo" | `tbd guidelines typescript-monorepo-patterns` |63| "Add e2e/golden testing" | `tbd guidelines golden-testing-guidelines` |64| "Review changes" (TS) | `tbd guidelines typescript-rules` |65| "Review changes" (Python) | `tbd guidelines python-rules` |66| "Plan a new feature" | `tbd shortcut new-plan-spec` |67| "Break spec into beads" | `tbd shortcut plan-implementation-with-beads` |68| "Implement these beads" | `tbd shortcut implement-beads` |69| "Commit this" | `tbd shortcut commit-code` |70| "Create a PR" | `tbd shortcut create-or-update-pr-simple` |71| "Research this topic" | `tbd shortcut new-research-brief` |72| "Document architecture" | `tbd shortcut new-architecture-doc` |73| *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |7475## CRITICAL: Session Closing Protocol7677**Before saying “done”, you MUST complete this checklist:**7879```80[ ] 1. git add + git commit81[ ] 2. git push82[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)83[ ] 4. tbd close/update <id> for all beads worked on84[ ] 5. tbd sync85[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)86```8788**Work is not done until pushed, CI passes, and tbd is synced.**8990## Bead Tracking Rules9192- Track all task work not done immediately as beads (discovered work, TODOs,93 multi-session work)94- When in doubt, create a bead95- Check `tbd ready` when not given specific directions96- Always close/update beads and run `tbd sync` at session end9798## Commands99100### Finding Work101102| Command | Purpose |103| --- | --- |104| `tbd ready` | Beads ready to work (no blockers) |105| `tbd list --status open` | All open beads |106| `tbd list --status in_progress` | Your active work |107| `tbd show <id>` | Bead details with dependencies |108109### Creating & Updating110111| Command | Purpose |112| --- | --- |113| `tbd create "title" --type task\|bug\|feature --priority=P2` | New bead (P0-P4, not "high/medium/low") |114| `tbd update <id> --status in_progress` | Claim work |115| `tbd close <id> [--reason "..."]` | Mark complete |116117### Dependencies & Sync118119| Command | Purpose |120| --- | --- |121| `tbd dep add <bead> <depends-on>` | Add dependency |122| `tbd blocked` | Show blocked beads |123| `tbd sync` | Sync with git remote (run at session end) |124| `tbd stats` | Project statistics |125| `tbd doctor` | Check for problems |126127### Documentation128129| Command | Purpose |130| --- | --- |131| `tbd shortcut <name>` | Run a shortcut |132| `tbd shortcut --list` | List shortcuts |133| `tbd guidelines <name>` | Load coding guidelines |134| `tbd guidelines --list` | List guidelines |135| `tbd template <name>` | Output a template |136137## Quick Reference138139- **Priority**: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog140- **Types**: task, bug, feature, epic141- **Status**: open, in_progress, closed142- **JSON output**: Add `--json` to any command143144<!-- BEGIN SHORTCUT DIRECTORY -->145## Available Shortcuts146147Run `tbd shortcut <name>` to use any of these shortcuts:148149| Name | Description |150| --- | --- |151| agent-handoff | Generate a concise handoff prompt for another coding agent to continue work |152| cleanup-all | Full cleanup cycle including duplicate removal, dead code, and code quality improvements |153| cleanup-remove-trivial-tests | Review and remove tests that do not add meaningful coverage |154| cleanup-update-docstrings | Review and add concise docstrings to major functions and types |155| commit-code | Run pre-commit checks, review changes, and commit code |156| create-or-update-pr-simple | Create or update a pull request with a concise summary |157| create-or-update-pr-with-validation-plan | Create or update a pull request with a detailed test/validation plan |158| implement-beads | Implement beads from a spec, following TDD and project rules |159| merge-upstream | Merge origin/main into current branch with conflict resolution |160| new-architecture-doc | Create an architecture document for a system or component design |161| new-guideline | Create a new coding guideline document for tbd |162| new-plan-spec | Create a new feature planning specification document |163| new-research-brief | Create a research document for investigating a topic or technology |164| new-shortcut | Create a new shortcut (reusable instruction template) for tbd |165| new-validation-plan | Create a validation/test plan showing what's tested and what remains |166| plan-implementation-with-beads | Create implementation beads from a feature planning spec |167| precommit-process | Full pre-commit checklist including spec sync, code review, and testing |168| review-code | Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |169| review-code-python | Python-focused code review (language-specific rules only) |170| review-code-typescript | TypeScript-focused code review (language-specific rules only) |171| review-github-pr | Review a GitHub pull request with follow-up actions (comment, fix, CI check) |172| revise-all-architecture-docs | Comprehensive revision of all current architecture documents |173| revise-architecture-doc | Update an architecture document to reflect current codebase state |174| setup-github-cli | Ensure GitHub CLI (gh) is installed and working |175| sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |176| update-specs-status | Review active specs and sync their status with tbd issues |177| welcome-user | Welcome message for users after tbd installation or setup |178179## Available Guidelines180181Run `tbd guidelines <name>` to apply any of these guidelines:182183| Name | Description |184| --- | --- |185| backward-compatibility-rules | Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |186| cli-agent-skill-patterns | Best practices for building TypeScript CLIs that function as agent skills in Claude Code and other AI coding agents |187| commit-conventions | Conventional Commits format with extensions for agentic workflows |188| convex-limits-best-practices | Comprehensive reference for Convex platform limits, workarounds, and performance best practices |189| convex-rules | Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |190| error-handling-rules | Rules for handling errors, failures, and exceptional conditions |191| general-coding-rules | Rules for constants, magic numbers, and general coding practices |192| general-comment-rules | Language-agnostic rules for writing clean, maintainable comments |193| general-eng-assistant-rules | Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines |194| general-style-rules | Style guidelines for auto-formatting, emoji usage, and output formatting |195| general-tdd-guidelines | Test-Driven Development methodology and best practices |196| general-testing-rules | Rules for writing minimal, effective tests with maximum coverage |197| golden-testing-guidelines | Guidelines for implementing golden/snapshot testing for complex systems |198| python-cli-patterns | Modern patterns for Python CLI application architecture |199| python-modern-guidelines | Guidelines for modern Python projects using uv, with a few more opinionated practices |200| python-rules | General Python coding rules and best practices |201| sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |202| typescript-cli-tool-rules | Rules for building CLI tools with Commander.js, picocolors, and TypeScript |203| typescript-code-coverage | Best practices for code coverage in TypeScript with Vitest and v8 provider |204| typescript-monorepo-patterns | Modern patterns for TypeScript monorepo architecture |205| typescript-rules | TypeScript coding rules and best practices |206207<!-- END SHORTCUT DIRECTORY -->208209---210> Converted and distributed by [TomeVault](https://tomevault.io/claim/jlevy) — claim your Tome and manage your conversions.211<!-- tomevault:4.0:skill_md:2026-04-11 -->
tomevault-io