| allowed-tools | Bash(tbd:*) Read Write |
| description | Git-native issue tracking (beads), coding guidelines, knowledge injection, and spec-driven planning for AI agents. Drop-in replacement for bd/Beads with simpler architecture.
Use for: tracking issues/beads with dependencies, creating bugs/features/tasks, planning specs, implementing features from specs, code reviews, committing code, creating PRs, loading coding guidelines (TypeScript, Python, TDD, golden testing, Convex, monorepo patterns), code cleanup, research briefs, architecture docs, agent handoffs, and checking out third-party library source code.
Invoke when user mentions: tbd, beads, bd, shortcuts, issues, bugs, tasks, features, epics, todo, tracking, specs, planning, implementation, validation, guidelines, templates, commit, PR, pull request, code review, testing, TDD, test-driven, golden testing, snapshot testing, TypeScript, Python, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, checkout library, source code review, or any workflow shortcut. |
| name | tbd |
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: 25+ 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@0.4.2
tbd setup --auto --prefix=<name>
tbd setup --auto
tbd setup --from-beads
If tbd refuses with “This repository requires a newer version of tbd”, run the two
install/upgrade commands above.
Routine Commands
tbd --help
tbd status
tbd doctor
tbd setup --auto
tbd prime
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” (or several) | tbd show <id1> [<id2> …] (one call, never a loop; --max-lines <n> caps output per issue) |
| “Where do things stand on spec X?” | tbd list --spec <path-or-filename> (all specs at once: tbd list --specs) |
| “Close this issue” | tbd close <id> (several: tbd close <id1> <id2> … — one call, never a loop) |
| “Search issues for X” | tbd search "X" (matches content and issue IDs, so partial IDs work) |
| “Add label X to issue” | tbd label add <id> <label> (several beads: tbd update <id1> <id2> … --add-label <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” |
Loading guidelines for engineering work: Before writing or reviewing code, load the
General engineering group—the general-* rules plus error-handling-rules—since
these apply to all code regardless of language.
Then load the group for the language or framework in use (TypeScript, Python, Convex,
etc.). Load a whole group in one call; guidelines, shortcut, template, and
docs show all take several names:
tbd guidelines general-coding-rules general-comment-rules error-handling-rules general-testing-rules
Run tbd guidelines --list to see all available guidelines.
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 <id1> <id2> ... --reason "..." — one bulk call per group of beads sharing a reason (never a per-ID loop)
[ ] 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 list --spec <path> | Beads tracking a spec (filename or suffix is enough) |
tbd list --sort updated --limit 10 | Recent activity; --count for totals |
tbd show <id1> [<id2> …] | Bead details with dependencies (bulk: delimited per issue; --max-lines <n> caps each) |
Creating & Updating
| Command | Purpose |
|---|
tbd create "title" --type=bug --priority=1 | New bead; run tbd create --help for all types and priorities (P0-P4, not “high/medium/low”) |
tbd create "title" --parent <epic> --depends-on <id> | Create fully wired: parent and blockers in one call (--depends-on is repeatable) |
tbd update <id> --status in_progress | Claim work |
tbd close <id> [--reason "..."] | Mark complete |
tbd close <id1> <id2> <id3> --reason "..." | Close several at once (always preferred over one-at-a-time) |
tbd update <id1> <id2> <id3> --priority 1 | Bulk-update shared fields on several beads |
IMPORTANT: if you are about to shell-loop or pipe around tbd, stop; the bulk or filter
form exists. show, close, reopen, and update take multiple IDs;
guidelines/shortcut/template/docs show take multiple names; dep add takes
multiple blockers; list/search/show have --limit/--count/--max-lines. NEVER
for id in …; do tbd close $id; done (one call gives one lock, one summary, --json,
and --ignore-missing), NEVER tbd show X | head (use --max-lines), NEVER
tbd list | grep <id> (use tbd search <partial-id>). A bulk call shares one reason
(and, for update, one set of field changes), so group the beads that share the same
mutation and make one call per group.
Dependencies & Sync
| Command | Purpose |
|---|
tbd dep add <bead> <blocker1> [<blocker2> …] | Add blocker dependencies (one call per bead) |
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 or (partial) issue ID |
tbd label add <id> <label> | Add label to issue (several beads: tbd update <ids…> --add-label) |
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> [<name> …] | Load coding guidelines (a whole group in one call) |
tbd guidelines --list | List guidelines |
tbd template <name> | Output a template |
tbd docs / tbd docs list | Managed-docs overview / cross-kind list with state markers |
tbd docs fork/unfork/update <name> | Fork docs into docs/tbd/, return to upstream, pull upstream updates |
Quick Reference
- Priority: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
- Types: issues default to
task; run tbd create --help for the valid types
- 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 |
|---|
| address-pr-review | Address an existing PR review from any channel—track every finding as a bead, fix or rebut each, reply with a per-finding disposition map, and get CI green |
| 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 the current branch with conflict resolution, then verify, push, and watch CI |
| 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 |
Available Guidelines
Run tbd guidelines <name> to apply any of these guidelines.
Load the General engineering group first, then the language or framework group.
General engineering
Read all of these for any engineering work (writing or reviewing code).
| Name | Description |
|---|
| backward-compatibility-rules | Guidelines for maintaining backward compatibility across code, APIs, file formats, and database schemas |
| commit-conventions | Conventional Commits format with extensions for agentic workflows |
| 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-agent-principles | Core principles for AI agents acting as senior engineers—objectivity and communication conduct plus the engineering process (detailed understanding, verification, end-to-end ownership, scope discipline, tracking future work, and acting versus seeking clarification) |
| 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 |
TypeScript & JS ecosystem
Also load these when working in TypeScript or JavaScript.
| Name | Description |
|---|
| bun-monorepo-patterns | Modern patterns for Bun-based TypeScript monorepo architecture |
| electron-app-development-patterns | Guidelines for Electron development ecosystems including npm, pnpm, and Bun, with security baselines and framework comparisons |
| pnpm-monorepo-patterns | Modern patterns for pnpm-based TypeScript monorepo architecture |
| 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-lint-format-rules | The shared lint and auto-formatting floor for all TypeScript and JavaScript projects, across pnpm and Bun and across ESLint/Prettier and Biome toolchains. Defines the rules every project enforces, the per-toolchain profiles that implement them, and the verification steps that prove the floor is real. |
| 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 |
Python
Also load these when working in Python.
| Name | Description |
|---|
| 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 |
Convex
Also load these when working with Convex.
| Name | Description |
|---|
| 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 |
Docs, process & tooling
| Name | Description |
|---|
| cli-agent-skill-patterns | A concise decision guide for portable skills, CLI-backed skills, safe bundle installation, and agent integration |
| common-doc-guidelines | Common cross-project standards for writing and organizing docs, code comments, and text files—how to organize, structure, write, and format documents, plus the guideline footer convention. Downstream of github.com/jlevy/practical-prose. Use whenever writing or editing any documentation, README, guideline, or design doc. |
| release-notes-guidelines | Guidelines for writing clear, accurate release notes |
| supply-chain-hardening | Strongly recommended for EVERY repo—apply it if a repo has not been hardened yet. Cross-ecosystem policy for installing dependencies safely (the 14-day cool-off, disabled install scripts, lockfile discipline, untrusted-repo handling). Use whenever a user mentions hardening, security, supply chain, or setting up a new repo; before adding/upgrading dependencies; when auditing for compromised packages; or when reviewing install/build/run commands across npm/pnpm, PyPI, Cargo, or Go. |
| tbd-sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |
