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.
Drop-in replacement for
bd.
- Spec-Driven Workflows: Plan features → break into beads → implement
systematically.
- Knowledge Injection: 17+ engineering guidelines (TypeScript, Python, TDD,
testing, Convex, monorepos) available on demand.
- Shortcuts: Reusable instruction templates for common workflows (code review,
commits, PRs, cleanup, handoffs).
Installation
npm install -g get-tbd@latest
tbd setup --auto --prefix=<name> # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. 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 |
| Issues/Beads |
|
| “There’s a bug where …” |
tbd create "..." --type=bug |
| “Create a task/feature for …” |
tbd create "..." --type=task or --type=feature |
| “Let’s work on issues/beads” |
tbd ready |
| “Show me issue X” |
tbd show <id> |
| “Close this issue” |
tbd close <id> |
| “Search issues for X” |
tbd search "X" |
| “Add label X to issue” |
tbd label add <id> <label> |
| “What issues are stale?” |
tbd stale |
| Planning & Specs |
|
| “Plan a new feature” / “Create a spec” |
tbd shortcut new-plan-spec |
| “Break spec into beads” |
tbd shortcut plan-implementation-with-beads |
| “Implement these beads” |
tbd shortcut implement-beads |
| Code Review & Commits |
|
| “Review this code” / “Code review” |
tbd shortcut review-code |
| “Review this PR” |
tbd shortcut review-github-pr |
| “Commit this” / “Use the commit shortcut” |
tbd shortcut code-review-and-commit |
| “Create a PR” / “File a PR” |
tbd shortcut create-or-update-pr-simple |
| “Merge main into my branch” |
tbd shortcut merge-upstream |
| Guidelines & Knowledge |
|
| “Use TypeScript best practices” |
tbd guidelines typescript-rules |
| “Use Python best practices” |
tbd guidelines python-rules |
| “Build a TypeScript CLI” |
tbd guidelines typescript-cli-tool-rules |
| “Improve monorepo setup” |
tbd guidelines pnpm-monorepo-patterns or bun-monorepo-patterns |
| “Add golden/e2e testing” |
tbd guidelines golden-testing-guidelines |
| “Use TDD” / “Test-driven development” |
tbd guidelines general-tdd-guidelines |
| “Convex best practices” |
tbd guidelines convex-rules |
| Documentation |
|
| “Research this topic” |
tbd shortcut new-research-brief |
| “Document architecture” |
tbd shortcut new-architecture-doc |
| Cleanup & Maintenance |
|
| “Clean up this code” / “Remove dead code” |
tbd shortcut code-cleanup-all |
| “Fix repository problems” |
tbd doctor --fix |
| Sessions & Handoffs |
|
| “Hand off to another agent” |
tbd shortcut agent-handoff |
| “Check out this library’s source” |
tbd shortcut checkout-third-party-repo |
| (your choice whenever appropriate) |
tbd list, tbd dep add, tbd close, tbd sync, etc. |
Note: Never gitignore .tbd/workspaces/ — the outbox must be committed to your
working branch. See tbd guidelines tbd-sync-troubleshooting for details.
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 |
tbd doctor --fix |
Auto-fix repository problems |
Labels & Search
| Command |
Purpose |
tbd search <query> |
Search issues by text |
tbd label add <id> <label> |
Add label to issue |
tbd label remove <id> <label> |
Remove label from issue |
tbd label list |
List all labels in use |
tbd stale |
List issues not updated recently |
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 |
| checkout-third-party-repo |
Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website). |
| code-cleanup-all |
Full cleanup cycle including duplicate removal, dead code, and code quality improvements |
| code-cleanup-docstrings |
Review and add concise docstrings to major functions and types |
| code-cleanup-tests |
Review and remove tests that do not add meaningful coverage |
| code-review-and-commit |
Run pre-commit checks, review changes, and commit code |
| coding-spike |
Prototype to validate a spec through hands-on implementation |
| 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-qa-playbook |
Create a QA test playbook for manual validation workflows |
| 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 |
| bun-monorepo-patterns |
Modern patterns for Bun-based TypeScript monorepo architecture |
| 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 |
| electron-app-development-patterns |
Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons |
| 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 |
| pnpm-monorepo-patterns |
Modern patterns for pnpm-based TypeScript monorepo architecture |
| 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 |
| release-notes-guidelines |
Guidelines for writing clear, accurate release notes |
| tbd-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-rules |
TypeScript coding rules and best practices |
| typescript-sorting-patterns |
Deterministic sorting patterns and comparison chains for TypeScript |
| typescript-yaml-handling-rules |
Best practices for parsing and serializing YAML in TypeScript |
| writing-style-guidelines |
Guidelines for clear, concise, and reader-friendly writing in documentation and code |
Source: jlevy/strif — distributed by TomeVault.
1---2name: jlevy-strif-strif3description: <!-- 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.17 Drop-in replacement for `bd`.182. **Spec-Driven Workflows**: Plan features → break into beads → implement19 systematically.203. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,21 testing, Convex, monorepos) available on demand.224. **Shortcuts**: Reusable instruction templates for common workflows (code review,23 commits, PRs, cleanup, handoffs).2425## Installation2627```bash28npm install -g get-tbd@latest29tbd setup --auto --prefix=<name> # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. ALWAYS ASK THE USER FOR THE PREFIX; do not guess it)30tbd setup --auto # Existing tbd project (prefix already set)31tbd setup --from-beads # Migration from .beads/ if `bd` has been used32```3334## Routine Commands3536```bash37tbd --help # Command reference38tbd status # Status39tbd doctor # If there are problems4041tbd setup --auto # Run any time to refresh setup42tbd prime # Restore full context on tbd after compaction43```4445## CRITICAL: You Operate tbd — The User Doesn’t4647**You are the tbd operator:** Users talk naturally; you translate their requests to tbd48actions. DO NOT tell users to run tbd commands.49That’s your job.5051- **WRONG**: “Run `tbd create` to track this bug”5253- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*5455**Welcoming a user:** When users ask “what is tbd?”56or want help → run `tbd shortcut welcome-user`5758## User Request → Agent Action5960| User Says | You (the Agent) Run |61| --- | --- |62| **Issues/Beads** | |63| “There’s a bug where …” | `tbd create "..." --type=bug` |64| “Create a task/feature for …” | `tbd create "..." --type=task` or `--type=feature` |65| “Let’s work on issues/beads” | `tbd ready` |66| “Show me issue X” | `tbd show <id>` |67| “Close this issue” | `tbd close <id>` |68| “Search issues for X” | `tbd search "X"` |69| “Add label X to issue” | `tbd label add <id> <label>` |70| “What issues are stale?” | `tbd stale` |71| **Planning & Specs** | |72| “Plan a new feature” / “Create a spec” | `tbd shortcut new-plan-spec` |73| “Break spec into beads” | `tbd shortcut plan-implementation-with-beads` |74| “Implement these beads” | `tbd shortcut implement-beads` |75| **Code Review & Commits** | |76| “Review this code” / “Code review” | `tbd shortcut review-code` |77| “Review this PR” | `tbd shortcut review-github-pr` |78| “Commit this” / “Use the commit shortcut” | `tbd shortcut code-review-and-commit` |79| “Create a PR” / “File a PR” | `tbd shortcut create-or-update-pr-simple` |80| “Merge main into my branch” | `tbd shortcut merge-upstream` |81| **Guidelines & Knowledge** | |82| “Use TypeScript best practices” | `tbd guidelines typescript-rules` |83| “Use Python best practices” | `tbd guidelines python-rules` |84| “Build a TypeScript CLI” | `tbd guidelines typescript-cli-tool-rules` |85| “Improve monorepo setup” | `tbd guidelines pnpm-monorepo-patterns` or `bun-monorepo-patterns` |86| “Add golden/e2e testing” | `tbd guidelines golden-testing-guidelines` |87| “Use TDD” / “Test-driven development” | `tbd guidelines general-tdd-guidelines` |88| “Convex best practices” | `tbd guidelines convex-rules` |89| **Documentation** | |90| “Research this topic” | `tbd shortcut new-research-brief` |91| “Document architecture” | `tbd shortcut new-architecture-doc` |92| **Cleanup & Maintenance** | |93| “Clean up this code” / “Remove dead code” | `tbd shortcut code-cleanup-all` |94| “Fix repository problems” | `tbd doctor --fix` |95| **Sessions & Handoffs** | |96| “Hand off to another agent” | `tbd shortcut agent-handoff` |97| “Check out this library’s source” | `tbd shortcut checkout-third-party-repo` |98| *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |99100**Note:** Never gitignore `.tbd/workspaces/` — the outbox must be committed to your101working branch. See `tbd guidelines tbd-sync-troubleshooting` for details.102103## CRITICAL: Session Closing Protocol104105**Before saying “done”, you MUST complete this checklist:**106107```108[ ] 1. git add + git commit109[ ] 2. git push110[ ] 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!)111[ ] 4. tbd close/update <id> for all beads worked on112[ ] 5. tbd sync113[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)114```115116**Work is not done until pushed, CI passes, and tbd is synced.**117118## Bead Tracking Rules119120- Track all task work not done immediately as beads (discovered work, TODOs,121 multi-session work)122- When in doubt, create a bead123- Check `tbd ready` when not given specific directions124- Always close/update beads and run `tbd sync` at session end125126## Commands127128### Finding Work129130| Command | Purpose |131| --- | --- |132| `tbd ready` | Beads ready to work (no blockers) |133| `tbd list --status open` | All open beads |134| `tbd list --status in_progress` | Your active work |135| `tbd show <id>` | Bead details with dependencies |136137### Creating & Updating138139| Command | Purpose |140| --- | --- |141| `tbd create "title" --type task\|bug\|feature --priority=P2` | New bead (P0-P4, not “high/medium/low”) |142| `tbd update <id> --status in_progress` | Claim work |143| `tbd close <id> [--reason "..."]` | Mark complete |144145### Dependencies & Sync146147| Command | Purpose |148| --- | --- |149| `tbd dep add <bead> <depends-on>` | Add dependency |150| `tbd blocked` | Show blocked beads |151| `tbd sync` | Sync with git remote (run at session end) |152| `tbd stats` | Project statistics |153| `tbd doctor` | Check for problems |154| `tbd doctor --fix` | Auto-fix repository problems |155156### Labels & Search157158| Command | Purpose |159| --- | --- |160| `tbd search <query>` | Search issues by text |161| `tbd label add <id> <label>` | Add label to issue |162| `tbd label remove <id> <label>` | Remove label from issue |163| `tbd label list` | List all labels in use |164| `tbd stale` | List issues not updated recently |165166### Documentation167168| Command | Purpose |169| --- | --- |170| `tbd shortcut <name>` | Run a shortcut |171| `tbd shortcut --list` | List shortcuts |172| `tbd guidelines <name>` | Load coding guidelines |173| `tbd guidelines --list` | List guidelines |174| `tbd template <name>` | Output a template |175176## Quick Reference177178- **Priority**: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog179- **Types**: task, bug, feature, epic180- **Status**: open, in_progress, closed181- **JSON output**: Add `--json` to any command182183<!-- BEGIN SHORTCUT DIRECTORY -->184## Available Shortcuts185186Run `tbd shortcut <name>` to use any of these shortcuts:187188| Name | Description |189| --- | --- |190| agent-handoff | Generate a concise handoff prompt for another coding agent to continue work |191| checkout-third-party-repo | Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website). |192| code-cleanup-all | Full cleanup cycle including duplicate removal, dead code, and code quality improvements |193| code-cleanup-docstrings | Review and add concise docstrings to major functions and types |194| code-cleanup-tests | Review and remove tests that do not add meaningful coverage |195| code-review-and-commit | Run pre-commit checks, review changes, and commit code |196| coding-spike | Prototype to validate a spec through hands-on implementation |197| create-or-update-pr-simple | Create or update a pull request with a concise summary |198| create-or-update-pr-with-validation-plan | Create or update a pull request with a detailed test/validation plan |199| implement-beads | Implement beads from a spec, following TDD and project rules |200| merge-upstream | Merge origin/main into current branch with conflict resolution |201| new-architecture-doc | Create an architecture document for a system or component design |202| new-guideline | Create a new coding guideline document for tbd |203| new-plan-spec | Create a new feature planning specification document |204| new-qa-playbook | Create a QA test playbook for manual validation workflows |205| new-research-brief | Create a research document for investigating a topic or technology |206| new-shortcut | Create a new shortcut (reusable instruction template) for tbd |207| new-validation-plan | Create a validation/test plan showing what's tested and what remains |208| plan-implementation-with-beads | Create implementation beads from a feature planning spec |209| precommit-process | Full pre-commit checklist including spec sync, code review, and testing |210| review-code | Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |211| review-code-python | Python-focused code review (language-specific rules only) |212| review-code-typescript | TypeScript-focused code review (language-specific rules only) |213| review-github-pr | Review a GitHub pull request with follow-up actions (comment, fix, CI check) |214| revise-all-architecture-docs | Comprehensive revision of all current architecture documents |215| revise-architecture-doc | Update an architecture document to reflect current codebase state |216| setup-github-cli | Ensure GitHub CLI (gh) is installed and working |217| sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |218| update-specs-status | Review active specs and sync their status with tbd issues |219| welcome-user | Welcome message for users after tbd installation or setup |220221## Available Guidelines222223Run `tbd guidelines <name>` to apply any of these guidelines:224225| Name | Description |226| --- | --- |227| backward-compatibility-rules | Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |228| bun-monorepo-patterns | Modern patterns for Bun-based TypeScript monorepo architecture |229| cli-agent-skill-patterns | Best practices for building TypeScript CLIs that function as agent skills in Claude Code and other AI coding agents |230| commit-conventions | Conventional Commits format with extensions for agentic workflows |231| convex-limits-best-practices | Comprehensive reference for Convex platform limits, workarounds, and performance best practices |232| convex-rules | Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |233| electron-app-development-patterns | Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons |234| error-handling-rules | Rules for handling errors, failures, and exceptional conditions |235| general-coding-rules | Rules for constants, magic numbers, and general coding practices |236| general-comment-rules | Language-agnostic rules for writing clean, maintainable comments |237| general-eng-assistant-rules | Rules for AI assistants acting as senior engineers, including objectivity and communication guidelines |238| general-style-rules | Style guidelines for auto-formatting, emoji usage, and output formatting |239| general-tdd-guidelines | Test-Driven Development methodology and best practices |240| general-testing-rules | Rules for writing minimal, effective tests with maximum coverage |241| golden-testing-guidelines | Guidelines for implementing golden/snapshot testing for complex systems |242| pnpm-monorepo-patterns | Modern patterns for pnpm-based TypeScript monorepo architecture |243| python-cli-patterns | Modern patterns for Python CLI application architecture |244| python-modern-guidelines | Guidelines for modern Python projects using uv, with a few more opinionated practices |245| python-rules | General Python coding rules and best practices |246| release-notes-guidelines | Guidelines for writing clear, accurate release notes |247| tbd-sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |248| typescript-cli-tool-rules | Rules for building CLI tools with Commander.js, picocolors, and TypeScript |249| typescript-code-coverage | Best practices for code coverage in TypeScript with Vitest and v8 provider |250| typescript-rules | TypeScript coding rules and best practices |251| typescript-sorting-patterns | Deterministic sorting patterns and comparison chains for TypeScript |252| typescript-yaml-handling-rules | Best practices for parsing and serializing YAML in TypeScript |253| writing-style-guidelines | Guidelines for clear, concise, and reader-friendly writing in documentation and code |254255<!-- END SHORTCUT DIRECTORY -->256257---258> Source: [jlevy/strif](https://github.com/jlevy/strif) — distributed by [TomeVault](https://tomevault.io).259<!-- tomevault:4.0:skill_md:2026-06-18 -->
tomevault-io