# Jlevy Flowmark Tbd > --- title: tbd Workflow description: Full tbd workflow guide for agents --- **`tbd` helps humans and agents ship code with greater speed, quality, and discipline.** 1. **Beads**: Git-native issue tracking (tasks, bugs, features). Never lose work across sessions. 2. **Spec-Driven Workflows**: Plan features → break into beads → implement systematically. 3. **Shortcuts**: Reusable instruction templates for common workflows. 4. **Guidelines**: Coding rules and best practices. ## Installation ```bash npm install -g get-tbd@latest tbd setup --auto --prefix= # 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 ```bash 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. - **WRONG**: "Run `tbd create` to track this bug" - **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)* **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 --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 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 ` | 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 --status in_progress` | Claim work | | `tbd close [--reason "..."]` | Mark complete | ### Dependencies & Sync | Command | Purpose | | --- | --- | | `tbd dep add ` | 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 ` | Run a shortcut | | `tbd shortcut --list` | List shortcuts | | `tbd guidelines ` | Load coding guidelines | | `tbd guidelines --list` | List guidelines | | `tbd template ` | 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 ` 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 ` 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](https://tomevault.io/claim/jlevy) — claim your Tome and manage your conversions.