{"id":41845447,"url":"https://github.com/jlevy/tbd","last_synced_at":"2026-02-10T04:04:30.117Z","repository":{"id":331965066,"uuid":"1130183999","full_name":"jlevy/tbd","owner":"jlevy","description":"Beads, planning, and knowledge injection for AI coding agents","archived":false,"fork":false,"pushed_at":"2026-02-03T10:53:47.000Z","size":3927,"stargazers_count":16,"open_issues_count":3,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-02-03T18:51:11.576Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jlevy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-08T06:34:46.000Z","updated_at":"2026-02-03T14:39:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/jlevy/tbd","commit_stats":null,"previous_names":["jlevy/ceads","jlevy/tbd"],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/jlevy/tbd","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Ftbd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Ftbd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Ftbd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Ftbd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jlevy","download_url":"https://codeload.github.com/jlevy/tbd/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jlevy%2Ftbd/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29290477,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-10T03:42:42.660Z","status":"ssl_error","status_checked_at":"2026-02-10T03:42:41.897Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-25T09:45:57.469Z","updated_at":"2026-02-10T04:04:30.110Z","avatar_url":"https://github.com/jlevy.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"# tbd\n\n**Task tracking, spec-driven planning, and knowledge injection for AI coding agents.**\n\n**tbd** (short for “To Be Done,” or “TypeScript beads” if you prefer) combines four\nthings that are each powerful on their own but work even better together:\n\n1. **Task tracking (beads):** Agent-friendly, CLI-native issue tracking for bugs,\n   features, epics, and dependencies that persist across sessions in git.\n   This alone is a step change in what agents can do.\n   [Beads](https://github.com/steveyegge/beads) are fantastic and *unreasonably\n   effective* at scaling an agent’s capacity from ~5-10 ad-hoc tasks to hundreds of\n   structured beads.\n2. **Spec-driven planning:** Templates and workflows for writing specs, breaking them\n   into beads, and implementing systematically.\n   With a good spec and beads, you can leave an agent running overnight and come back to\n   solid code.\n3. **Knowledge injection:** Instant availability of in-depth engineering guidelines and\n   rules docs. These are essentially “self-injected context” for an agent to get smarter\n   when it needs it.\n4. **Shortcuts:** Reusable instructions for common tasks like code review, PR creation,\n   and writing planning specs, architecture docs, and research briefs.\n\n`tbd` comes pre-installed with in-depth guidelines docs on many topics, including\nTypeScript and Python best practices and common agent pitfalls, red-green TDD, golden\ntesting, Convex, monorepo project setup, error handling practices, and backward\ncompatibility rules.\n(But you can use your own guidelines if you prefer.)\n\nI use `tbd` most frequently in Claude Code since it’s most powerful as a skill, but it\nwill work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.\n\n## Quick Start\n\n\u003e [!TIP]\n\u003e \n\u003e If running on your own machine, install the `tbd` CLI yourself:\n\u003e \n\u003e **`npm install -g get-tbd@latest`**\n\u003e \n\u003e Then tell your agent:\n\u003e \n\u003e ***“run tbd for instructions to set up this project”***\n\u003e \n\u003e If running on a fresh cloud instance (like Claude Code Cloud), tell the agent:\n\u003e \n\u003e ***“install tbd (npm install -g get-tbd@latest) and run tbd prime for instructions to\n\u003e set up this project”***\n\nThat’s it.\nRunning `tbd prime` gives agents full workflow context on how to use `tbd` and\nhow to help you. It will then bootstrap a SKILL.md into your project by running\n`tbd setup --auto` (which will add a `.tbd` directory and add itself to your `.claude`\nskills and hooks). And then it will use shortcuts to welcome you and get you started.\n\nRunning `tbd` with no arguments shows help with a prominent reminder for agents to run\n`tbd prime`.\n\nYou can then always ask questions like: “what can I do with tbd?”\n\n## How Should You Use `tbd`?\n\n### Drop-In `bd` Replacement\n\nYou can use `tbd` as a drop-in replacement for the original Beads (`bd`). It’s largely\ncompatible at the CLI level for core issue tracking functionality.\n\nDespite the general power of the beads, there are quite a few\n[practical frustrations](#how-does-tbd-compare-to-beads) with the original Beads\nimplementation—notably the daemon modifying files, merge conflicts, sync confusions\nacross branches and database, and SQLite not working on network drives, such as Claude\nCode Cloud. After using `bd` for over a month, this became my greatest pain point.\nI now use `tbd` for all my agent coding and its sync architecture works pretty well.\n\n### Spec-Driven Coding and Review\n\nWhat excites me now is that `tbd` is more than just task management.\n\nThese workflows arose from several months of\n[heavy spec-driven agentic coding](https://github.com/jlevy/speculate/blob/main/about/lessons_in_spec_coding.md).\nWith better use of specs, what you build is far clearer and more maintainable.\nIn fact, I think of iterating on a spec as the hard part now.\nWriting the code is often almost automatic, if a spec is good enough!\n\nBasically 100% of the code I now write is agent-written, planned and tracked through\nspecs and beads and streamlined with shortcuts.\n\nTo help with this, `tbd` provides a way to **inject engineering rules and best\npractices** and **streamline reproducible workflows with shortcuts**.\n\nBy combining task management, knowledge injection, and shortcuts, I find my agents ship\ncode with speed, quality, and discipline.\n\n### Shortcuts for Common Tasks (Easy with Voice!)\n\nOnce you start doing things like the above workflows, it gets repetitive.\nAnd I like to now use voice to give prompts.\nSo having “shortcut” docs that list common tasks is really helpful.\n\nI can now ship entire large features just with voice prompts like “use the shortcut to\ncreate a new plan spec that …” and “now use the shortcut to file a PR with a validation\nplan.”\n\n### What `tbd` Doesn’t Do (Yet)\n\n`tbd` focuses on the *durable layer* of agent development: issue tracking, planning, and\nknowledge that persist in git across sessions.\nIt does not (yet) try to solve real-time multi-agent coordination features of Beads or\n[Gas Town](https://github.com/steveyegge/gastown) or\n[Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) or unstructured agent\nloops like\n[Ralph Wiggum](https://github.com/anthropics/claude-code/tree/main/plugins/ralph-wiggum).\nThese seem great for rapid prototyping, but so far, code where quality or scale matters,\nI’ve not fully embraced unstructured automation (e.g. 20+ concurrent agents or Ralph\nloops).\nI find having more process and discipline around specs (and around 6–8 concurrent\nagents handling different aspects that I manage) is slower, because it forces you to\ndesign, but it gives higher quality results.\n\n\u003e [!NOTE]\n\u003e \n\u003e We use *Beads* (capitalized) to refer to Steve Yegge’s original\n\u003e [`bd` tool](https://github.com/steveyegge/beads).\n\u003e Lowercase “beads” refers generically to the issues stored in `tbd` or `bd`.\n\n## How to Use `tbd`\n\nYou talk to your agent in natural language.\nThe agent translates your requests into `tbd` commands.\n\nThe `tbd` CLI blends task tracking and context injection.\nSome `tbd` commands do things, like create or update beads, and some help the agent get\nstatus or context or knowledge and know what to do next:\n\n| What you say | What happens | What runs |\n| --- | --- | --- |\n| \"Let's plan a new feature that …\" | Agent creates a spec from a template | [`tbd shortcut new-plan-spec`](packages/tbd/docs/shortcuts/standard/new-plan-spec.md) |\n| \"Break this spec into beads\" | Agent creates implementation beads from the spec | [`tbd shortcut plan-implementation-with-beads`](packages/tbd/docs/shortcuts/standard/plan-implementation-with-beads.md) |\n| \"Implement these beads\" | Agent works through beads systematically | [`tbd shortcut implement-beads`](packages/tbd/docs/shortcuts/standard/implement-beads.md) |\n| \"Create a bead for the bug where …\" | Agent creates and tracks a bead | `tbd create \"...\" --type=bug` |\n| \"Let's work on current beads\" | Agent finds ready beads and starts working | `tbd ready` |\n| \"Review this code\" | Agent performs comprehensive code review with all guidelines | [`tbd shortcut review-code`](packages/tbd/docs/shortcuts/standard/review-code.md) |\n| \"Review this PR\" | Agent reviews a GitHub pull request and can comment/fix | [`tbd shortcut review-github-pr`](packages/tbd/docs/shortcuts/standard/review-github-pr.md) |\n| \"Use the shortcut to commit\" | Agent runs full pre-commit checks, code review, and commits | [`tbd shortcut code-review-and-commit`](packages/tbd/docs/shortcuts/standard/code-review-and-commit.md) |\n| \"Create a PR\" | Agent creates or updates the pull request | [`tbd shortcut create-or-update-pr-simple`](packages/tbd/docs/shortcuts/standard/create-or-update-pr-simple.md) |\n| \"Let's create a research brief on …\" | Agent creates a research document using a template | [`tbd shortcut new-research-brief`](packages/tbd/docs/shortcuts/standard/new-research-brief.md) |\n| \"How could we test this better?\" | Agent loads TDD and testing guidelines | [`tbd guidelines general-tdd-guidelines`](packages/tbd/docs/guidelines/general-tdd-guidelines.md) |\n| \"How can we make this a well-designed TypeScript CLI?\" | Agent loads TypeScript CLI guidelines | [`tbd guidelines typescript-cli-tool-rules`](packages/tbd/docs/guidelines/typescript-cli-tool-rules.md) |\n| \"Can you review if this TypeScript package setup follows best practices\" | Agent loads monorepo patterns | [`tbd guidelines pnpm-monorepo-patterns`](packages/tbd/docs/guidelines/pnpm-monorepo-patterns.md) |\n| \"How can we do a better job of testing?\" | Agent loads golden testing guidelines | [`tbd guidelines golden-testing-guidelines`](packages/tbd/docs/guidelines/golden-testing-guidelines.md) |\n\nUnder the hood, your agent runs these `tbd` commands automatically.\nYou just talk naturally.\n\n## Features\n\n\u003e [!NOTE]\n\u003e For full technical details, see the [reference docs](packages/tbd/docs/tbd-docs.md)\n\u003e (run `tbd docs`) or the full [design doc](packages/tbd/docs/tbd-design.md)\n\u003e (`tbd design`).\n\n- **Git-native:** Beads live in your repo, synced to a separate, dedicated `tbd-sync`\n  branch. Your code history stays clean—no bead churn polluting your logs.\n- **Agent friendly:** JSON output, non-interactive mode, simple commands that agents\n  understand. Installs itself as a skill in Claude Code.\n- **Markdown + YAML frontmatter:** One file per bead, human-readable and editable.\n  This eliminates most merge conflicts.\n- **Beads alternative:** Largely compatible with `bd` at the CLI level, but with a\n  simpler architecture: no JSONL merge conflicts, no daemon modifying your working tree,\n  no SQLite file locking on network filesystems (see\n  [FAQ: How does `tbd` compare to Beads?](#how-does-tbd-compare-to-beads)).\n- **Shortcuts:** Over a dozen reusable workflow documents—plan specs, code reviews,\n  commit processes, PR creation, research briefs, and more.\n- **Guidelines:** [20+ guideline docs](packages/tbd/docs/guidelines/) of coding rules\n  and best practices (see\n  [Built-in Engineering Knowledge](#built-in-engineering-knowledge)).\n- **Templates:** Document templates for planning specs, research briefs, architecture\n  docs.\n\n## Why is This a Good Idea?\n\nEngineers are still adjusting to how fast things are changing.\nBut the reality is that most of the time now, if you’re doing it right, *agents should\nwrite 100% of your code*.\n\nBut anyone who’s coded a lot with agents knows they can be very bad or very good,\ndepending on the situation.\nWithout structure and knowledge, the results are often slop or have critical flaws or\nthey don’t scale to large projects.\nThey forget conventions between sessions, skip testing, and don’t follow your team’s\npatterns.\n\nThe usual tactics like pasting rules into prompts is fragile and tiring.\nAnd even adding all these rules to CLAUDE.md or AGENTS.md doesn’t scale.\n\nBeads (git-native CLI-based issue tracking) is one element of the solution.\nIt solves the task management problem brilliantly.\nIf you’re not using beads already, you should be!\n\nBut task tracking alone doesn’t help with *planning* or *quality*. You still need a way\nto think through what you’re building before you start, and a way to make sure the agent\nfollows good engineering practices while it works.\n\n`tbd` combines all three: beads for task management, spec-driven workflows for planning,\nand curated engineering guidelines for quality.\nTogether, they let you hand an agent a well-defined spec with clear beads and expert\nknowledge, and get back careful, well-structured code—even overnight, even across\nsessions.\n\nMy current favorite workflows and guidelines are included by default, but you’re not\nlocked in. Add your own via `--add` or configure what’s available in `.tbd/config.yml`.\n\nAnd yes, all the code *and* all the specs of `tbd` are agent written—see\n[the FAQ](#was-tbd-built-with-tbd).\n\n## Built-in Engineering Knowledge\n\nWhen you run `tbd setup`, your agent gets instant access to\n[20+ guideline documents](packages/tbd/docs/guidelines/) covering real-world engineering\npractices. These aren’t generic tips; they’re mostly my own detailed and sometimes\nopinionated rules with concrete examples, built from months of heavy agentic coding.\n\n\u003e [!TIP]\n\u003e \n\u003e An example: I *strongly* believe there are much better ways to do testing\n\u003e proliferating hundreds of unit and integration tests.\n\u003e So (with help from some Opus 4.5 and GPT-5 Pro) I wrote a multi-page brief about\n\u003e “[golden testing](packages/tbd/docs/guidelines/golden-testing-guidelines.md)”\n\u003e techniques, which allow the LLM to do end-to-end testing of CLI or web app flows in a\n\u003e clean, token-friendly way.\n\u003e Now simply telling your agent “check the guidelines on golden testing” can make a huge\n\u003e difference, encouraging far more maintainable, deeper tests.\n\n| Guideline | What it covers |\n| --- | --- |\n| [general-tdd-guidelines](packages/tbd/docs/guidelines/general-tdd-guidelines.md) | Red-Green-Refactor methodology, small slices, test-first discipline |\n| [golden-testing-guidelines](packages/tbd/docs/guidelines/golden-testing-guidelines.md) | Snapshot/golden testing for complex systems: session schemas, YAML captures, mock modes |\n| [general-testing-rules](packages/tbd/docs/guidelines/general-testing-rules.md) | Minimal tests for maximum coverage, avoiding redundant test cases |\n| [typescript-code-coverage](packages/tbd/docs/guidelines/typescript-code-coverage.md) | Code coverage best practices with Vitest and v8 provider |\n| [typescript-rules](packages/tbd/docs/guidelines/typescript-rules.md) | Strict type safety, no `any`, type guards, null safety, async patterns |\n| [typescript-sorting-patterns](packages/tbd/docs/guidelines/typescript-sorting-patterns.md) | Deterministic sorting, comparison chains for multi-field sorts |\n| [pnpm-monorepo-patterns](packages/tbd/docs/guidelines/pnpm-monorepo-patterns.md) | pnpm workspaces, tsdown, Vitest, Changesets, publint, dual ESM/CJS |\n| [bun-monorepo-patterns](packages/tbd/docs/guidelines/bun-monorepo-patterns.md) | Bun workspaces, Bunup, Biome, bun test, standalone executables |\n| [typescript-cli-tool-rules](packages/tbd/docs/guidelines/typescript-cli-tool-rules.md) | Commander.js patterns, picocolors, terminal formatting |\n| [cli-agent-skill-patterns](packages/tbd/docs/guidelines/cli-agent-skill-patterns.md) | Building CLIs that function as agent skills in Claude Code |\n| [electron-app-development-patterns](packages/tbd/docs/guidelines/electron-app-development-patterns.md) | Electron ecosystems (npm, pnpm, Bun), security baselines, Electrobun comparison |\n| [typescript-yaml-handling-rules](packages/tbd/docs/guidelines/typescript-yaml-handling-rules.md) | YAML parsing/serialization with the `yaml` package, Zod validation, consistent formatting |\n| [python-rules](packages/tbd/docs/guidelines/python-rules.md) | Type hints, docstrings, exception handling, resource management |\n| [python-cli-patterns](packages/tbd/docs/guidelines/python-cli-patterns.md) | Modern Python CLI stack: uv, Typer, Rich, Ruff, BasedPyright |\n| [backward-compatibility-rules](packages/tbd/docs/guidelines/backward-compatibility-rules.md) | Compatibility across code, APIs, file formats, and database schemas |\n| [convex-rules](packages/tbd/docs/guidelines/convex-rules.md) | Convex function syntax, schema design, queries, mutations |\n| [convex-limits-best-practices](packages/tbd/docs/guidelines/convex-limits-best-practices.md) | Convex platform limits, workarounds, performance tuning |\n\nPlus guidelines on [coding rules](packages/tbd/docs/guidelines/general-coding-rules.md),\n[comment quality](packages/tbd/docs/guidelines/general-comment-rules.md),\n[commit conventions](packages/tbd/docs/guidelines/commit-conventions.md), and\n[style](packages/tbd/docs/guidelines/general-style-rules.md).\n\nYou can also add your own team’s guidelines from any URL:\n\n```bash\ntbd guidelines --add=\u003curl\u003e --name=my-team-rules\n```\n\n## Installation and Setup\n\n**Requirements:**\n- Node.js 20+\n- Git 2.42+ (for orphan worktree support)\n\n```bash\nnpm install -g get-tbd@latest\n```\n\n### Setup\n\n```bash\n# Fresh project (--prefix is REQUIRED—2-8 alphabetic chars, e.g. myapp-a1b2)\ntbd setup --auto --prefix=myapp\n\n# Joining an existing tbd project (no prefix needed—reads existing config)\ntbd setup --auto\n\n# Migrate from Beads (uses your existing beads prefix)\ntbd setup --from-beads\n```\n\n\u003e **Tip:** Run `tbd setup --auto` anytime to refresh skill files, hooks, and configs\n\u003e with the latest shortcuts, guidelines, and templates.\n\n### Team Setup\n\n`tbd` is designed for teams where one person sets up the project and others join later.\n\n**First contributor:**\n```bash\nnpm install -g get-tbd@latest\ntbd setup --auto --prefix=myproject\ngit add .tbd/ .claude/ \u0026\u0026 git commit -m \"Initialize tbd\"\ngit push\n```\n\n**Joining contributors:**\n```bash\ngit clone \u003crepo\u003e\nnpm install -g get-tbd@latest\ntbd setup --auto                    # No --prefix needed—reads existing config\n```\n\n### Claude Code Integration\n\n`tbd setup --auto` configures SessionStart hooks that run at the beginning of each\nClaude Code session:\n\n- **`tbd prime`**—injects workflow context so the agent knows how to use `tbd`\n- **`ensure-gh-cli.sh`**—installs the GitHub CLI (`gh`) if not already available\n\n**GitHub authentication:** For `gh` to work, set these environment variables before\nstarting your agent session:\n\n```\nGH_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\nGH_PROMPT_DISABLED=1\n```\n\nCreate a [Personal Access Token](https://github.com/settings/tokens?type=beta)\n(fine-grained recommended) with **Contents** and **Pull requests** read/write\npermissions. For Claude Code Cloud, set these in your project’s environment variables.\nFor local CLI usage, add them to your shell profile (`~/.zshrc` or `~/.bashrc`). See the\n[setup-github-cli shortcut](packages/tbd/docs/shortcuts/standard/setup-github-cli.md)\nfor details.\n\nTo disable automatic `gh` installation, pass `--no-gh-cli` during setup or set\n`use_gh_cli: false` in `.tbd/config.yml` under `settings:`.\n\n### Migrating from Beads\n\n```bash\ntbd setup --from-beads       # Auto-detects and migrates\ntbd stats                    # Verify\ntbd list --all\ntbd setup beads --disable    # Optionally disable beads after migration\n```\n\nIssue IDs are preserved: `proj-123` in beads becomes `proj-123` in `tbd`.\n\n## Commands\n\n### Beads\n\n```bash\ntbd ready                      # Beads ready to work on (open, unblocked, unassigned)\ntbd list                       # List open beads\ntbd list --all                 # Include closed\ntbd list --specs               # Group beads by spec\ntbd show proj-a7k2             # View bead details\ntbd create \"Title\" --type=bug  # Create bead (bug/feature/task/epic/chore)\ntbd update proj-a7k2 --status=in_progress\ntbd close proj-a7k2            # Close bead\ntbd close proj-a7k2 --reason=\"Fixed in commit abc123\"\ntbd sync                       # Sync with remote (auto-commits and pushes)\n```\n\n### Dependencies and Labels\n\n```bash\ntbd dep add proj-b3m9 proj-a7k2        # b3m9 depends on a7k2\ntbd blocked                            # Show blocked beads\ntbd label add proj-a7k2 urgent backend\ntbd label remove proj-a7k2 urgent\ntbd label list                         # All labels in use\ntbd search \"authentication\"            # Search beads\n```\n\n### Shortcuts, Guidelines, and Templates\n\n`tbd` bundles three types of documentation your agent can invoke on demand:\n\n```bash\n# Shortcuts—workflow instructions\ntbd shortcut --list              # List all shortcuts\ntbd shortcut new-plan-spec       # Get the plan spec workflow\n\n# Guidelines—coding rules and best practices\ntbd guidelines --list            # List all guidelines\ntbd guidelines typescript-rules  # Get TypeScript rules\n\n# Templates—document scaffolds\ntbd template --list              # List all templates\ntbd template plan-spec           # Get a plan spec template\n\n# Add your own from any URL\ntbd guidelines --add=\u003curl\u003e --name=\u003cname\u003e\ntbd shortcut --add=\u003curl\u003e --name=\u003cname\u003e\ntbd template --add=\u003curl\u003e --name=\u003cname\u003e\n```\n\n**Available shortcuts:**\n\n| Category | Shortcut | Purpose |\n| --- | --- | --- |\n| **Planning** | `new-plan-spec` | Create a feature planning spec |\n|  | `plan-implementation-with-beads` | Break a spec into implementation beads |\n|  | `implement-beads` | Implement beads from a spec |\n|  | `new-validation-plan` | Create a test/validation plan |\n|  | `update-specs-status` | Review active specs and sync with tbd issues |\n| **Documentation** | `new-research-brief` | Create a research document |\n|  | `new-architecture-doc` | Create an architecture document |\n|  | `revise-architecture-doc` | Update an architecture doc to match current code |\n|  | `revise-all-architecture-docs` | Revise all current architecture documents |\n| **Review** | `review-code` | Comprehensive code review (uncommitted, branch, or PR) |\n|  | `review-github-pr` | Review a GitHub PR with commenting and CI checks |\n|  | `review-code-typescript` | TypeScript-focused code review |\n|  | `review-code-python` | Python-focused code review |\n| **Git** | `precommit-process` | Pre-commit review and testing |\n|  | `code-review-and-commit` | Commit with pre-commit checks |\n|  | `create-or-update-pr-simple` | Basic PR creation |\n|  | `create-or-update-pr-with-validation-plan` | PR with a validation plan |\n|  | `merge-upstream` | Merge origin/main with conflict resolution |\n| **Cleanup** | `code-cleanup-all` | Full code cleanup (duplicates, dead code, quality) |\n|  | `code-cleanup-tests` | Remove trivial/low-value tests |\n|  | `code-cleanup-docstrings` | Add docstrings to major functions |\n| **Session** | `agent-handoff` | Generate handoff prompt for another agent |\n|  | `welcome-user` | Welcome message after tbd installation |\n|  | `setup-github-cli` | Ensure GitHub CLI is installed and working |\n|  | `sync-failure-recovery` | Handle tbd sync failures |\n|  | `checkout-third-party-repo` | Clone library source code for review |\n| **Exploration** | `coding-spike` | Prototype to validate a spec through implementation |\n| **Meta** | `new-guideline` | Create a new coding guideline for tbd |\n|  | `new-shortcut` | Create a new shortcut for tbd |\n\n**Available guidelines:** See\n[Built-in Engineering Knowledge](#built-in-engineering-knowledge) for the full list of\n20+ guidelines covering TypeScript, Python, testing, TDD, and more.\n\n**Available templates:**\n\n| Template | Description |\n| --- | --- |\n| `plan-spec` | Feature planning specification |\n| `research-brief` | Research document |\n| `architecture` | Architecture document |\n\n### Spec-Driven Development\n\nFor non-trivial features, `tbd` supports a full spec-driven workflow:\n\n1. **Plan**: Create a planning spec (`tbd shortcut new-plan-spec`)\n2. **Break down**: Convert spec into implementation beads\n   (`tbd shortcut plan-implementation-with-beads`)\n3. **Implement**: Work through beads systematically (`tbd shortcut implement-beads`)\n4. **Validate**: Create validation plan, run tests (`tbd shortcut new-validation-plan`)\n5. **Ship**: Commit, create PR (`tbd shortcut create-or-update-pr-with-validation-plan`)\n\n### Maintenance\n\n```bash\ntbd status                   # Repository status (works before init too)\ntbd stats                    # Bead statistics\ntbd doctor                   # Check for problems\ntbd doctor --fix             # Auto-fix issues\n```\n\n### Agent-Friendly Flags\n\nEvery command supports these flags for automation:\n\n| Flag | Purpose |\n| --- | --- |\n| `--json` | Machine-parseable output |\n| `--non-interactive` | Fail if input required |\n| `--yes` | Auto-confirm prompts |\n| `--dry-run` | Preview changes |\n| `--quiet` | Minimal output |\n\n## Documentation\n\n```bash\ntbd                          # Full orientation and workflow guidance\ntbd readme                   # This file\ntbd docs                     # Full CLI reference\n```\n\nOr read online:\n- [CLI Reference](packages/tbd/docs/tbd-docs.md)—Complete command documentation\n- [Design Doc](packages/tbd/docs/tbd-design.md)—Technical architecture\n\n## How It Works\n\n`tbd` keeps two things separate from your code:\n\n- **Beads** live on a dedicated `tbd-sync` branch.\n  One Markdown file per bead means parallel creation never conflicts.\n  `tbd sync` pushes changes—no manual git operations needed.\n- **Documents** (shortcuts, guidelines, templates) are cached locally in `.tbd/docs/`\n  during `tbd setup --auto`. Your agent reads them on demand via `tbd shortcut`,\n  `tbd guidelines`, and `tbd template`. Re-run `tbd setup --auto` anytime to refresh\n  with the latest bundled docs, or add your own via `--add`.\n- **Everything is self-documented via the CLI.** Running `tbd` shows help with quick\n  command reference; `tbd prime` gives full workflow orientation.\n  `tbd setup --auto` (idempotent, safe anytime) writes a skill file (SKILL.md/AGENTS.md)\n  that teaches the agent all available commands, shortcuts, and guidelines.\n  This means agents can inject context—specs, engineering guidelines, workflow\n  instructions—at any point in a session, not just at startup.\n\nSee the [design doc](packages/tbd/docs/tbd-design.md) for details.\n\n## FAQ\n\n### How does `tbd` compare to Beads?\n\n`tbd` was inspired by [Beads](https://github.com/steveyegge/beads) by Steve Yegge, and\nI’m grateful for the idea—it genuinely changed how I work with agents.\nIf you’re not familiar with Beads, the core insight is that git-native issue tracking\nraises an agent’s capacity for structured work from ~5-10 to-do items to hundreds of\nbeads.\n\n`tbd` builds on that foundation with a simpler architecture: plain Markdown files\ninstead of JSONL, no daemon, no SQLite, no 4-way sync.\nThis avoids the edge cases I ran into with network filesystems (Claude Code Cloud),\nmerge conflicts, and multi-agent workflows.\n\nIf you already use Beads, `tbd setup --from-beads` migrates you to `tbd`. This imports\nand sets up your `.tbd` directory and preserves the IDs of all issues.\n\n**Scope:** `tbd` focuses on the *durable layer*—issue tracking, specs, and knowledge\nthat persist across sessions and live in git.\nIt does *not* aim to solve real-time multi-agent coordination, which is a separate\nproblem requiring sub-second messaging and atomic claims.\nTools like [Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) and\n[Gas Town](https://github.com/steveyegge/gastown) address that space and are\ncomplementary to `tbd`—you could layer real-time coordination on top of `tbd`'s durable\ntracking. See the [design doc](packages/tbd/docs/tbd-design.md) for a detailed\ncomparison.\n\n### Why spec-driven development?\n\nAfter months of heavy agentic coding, I’ve found that the single biggest lever for\nquality is planning before you code.\nA\n[carefully written spec](https://github.com/jlevy/speculate/blob/main/about/lessons_in_spec_coding.md)\nlets you think through what you’re building, catch design problems early, and break the\nwork into well-defined beads.\nThe agent then implements each bead with clear context about the bigger picture.\n\nThis matters because with a good spec broken into beads, you can leave an agent running\novernight and come back to code that’s well-structured and coherent—not a pile of\ndisconnected changes.\n`tbd` bakes in shortcuts for the full cycle: writing specs, breaking them into beads,\nimplementing, validating, and shipping.\n\n### Was `tbd` built with `tbd`?\n\nOf course! I bootstrapped with the original `bd`. It imported from `bd` and began\nself-hosting its own tasks, then took over its own specs and reminds itself of its own\ncoding guidelines. Here’s what that looks like in practice:\n\n**Specs:** `tbd` has dozens of active and completed plan specs, such as:\n- `plan-2026-01-15-tbd-v1-implementation.md`—The original v1 design\n- `plan-2026-01-20-streamlined-init-setup-design.md`—Redesigning the setup flow\n- `plan-2026-01-26-configurable-doc-cache-sync.md`—Making the doc system configurable\n- `plan-2026-01-28-cli-add-docs-by-url.md`—Adding `--add` for external docs\n\n**Beads:** Features are broken into beads and worked through systematically.\nFor example, the current list of open beads for this project looks like\n\n```\n$ tbd list --pretty \ntbd-0nuf      P2  ○ open  [feature] Add remote vs local issue counts to tbd stats\ntbd-1r0w      P2  ○ open  [epic] Spec: CLI Output Formatting Consistency\n...\ntbd-pt3v      P2  ○ open  [epic] Spec: CLI Output Design System\ntbd-tv5i      P2  ○ open  [feature] Format option (json/yaml/table/csv)\ntbd-w4un      P2  ○ open  [task] Create claude-installation.md with installation section for Claude only\ntbd-x3zq      P2  ○ open  [task] Add integration tests for shortcut command\ntbd-x8va      P2  ○ open  [epic] Agent documentation consolidation and cleanup\ntbd-xqn2      P2  ○ open  [feature] Issue templates\ntbd-yom2      P2  ○ open  [feature] Improve sync commit messages with ticket IDs and summaries\n├── tbd-f0nb      P2  ○ open  [task] Generate commit body with long-format issue summaries (title, description, close_reason)\n├── tbd-qi6q      P2  ○ open  [task] Add tests for sync commit message generation\n├── tbd-r6s8      P2  ○ open  [task] Track modified issues at commit time and pass to commit message generator\n└── tbd-xdwv      P2  ○ open  [task] Generate commit subject line with up to 8 short IDs (truncate if \u003e10)\ntbd-z26l      P2  ○ open  [task] Document configuration options in tbd-design.md\ntbd-6org      P3  ○ open  [task] Add ESLint rule to enforce atomically for file writes\n\n39 issue(s)\n$ \n```\n\n### Can I add my own guidelines?\n\nYes. `tbd` comes with 20+ bundled guidelines, but you can add your own team’s docs from\nany URL:\n\n```bash\ntbd guidelines --add=\u003curl\u003e --name=my-team-rules\ntbd shortcut --add=\u003curl\u003e --name=my-team-workflow\ntbd template --add=\u003curl\u003e --name=my-team-template\n```\n\nYou can also configure which docs are available in `.tbd/config.yml`. I put my favorite\nguidelines and shortcuts in by default, but you’re not locked into using them.\n\n## Contributing\n\nSee [docs/development.md](docs/development.md) for build and test instructions.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Ftbd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjlevy%2Ftbd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjlevy%2Ftbd/lists"}