get-tbd 0.1.12 → 0.1.13

package/README.md

@@ -3,8 +3,8 @@
 **Task management, spec-driven planning, and instant knowledge injection for AI coding
 agents.**
 
-**tbd** (short for “To Be Done,” or “TypeScript beads” if you prefer) combines three
-things that are each powerful on their own but unreasonably effective together:
+**tbd** (short for “To Be Done,” or “TypeScript beads” if you prefer) combines four
+things that are each powerful on their own but work even better together:
 
 1. **Task tracking (beads):** Agent-friendly, CLI-native issue tracking for bugs,
    features, epics, and dependencies that persist across sessions in git.
@@ -12,51 +12,93 @@ things that are each powerful on their own but unreasonably effective together:
    [Beads](https://github.com/steveyegge/beads) are fantastic and *unreasonably
    effective* at scaling an agent’s capacity from ~5-10 ad-hoc tasks to hundreds of
    structured beads.
-2. **Spec-driven planning:** workflows for writing specs, breaking them into beads, and
-   implementing systematically.
+2. **Spec-driven planning:** Templates and workflows for writing specs, breaking them
+   into beads, and implementing systematically.
    With a good spec and beads, you can leave an agent running overnight and come back to
    solid code.
-3. **Instant knowledge injection:** Instant availability of guidelines and rules docs.
-   These are essentially “self-injected context” for an agent to get smarter when it
-   needs it.
+3. **Knowledge injection:** Instant availability of in-depth engineering guidelines and
+   rules docs. These are essentially “self-injected context” for an agent to get smarter
+   when it needs it.
+4. **Shortcuts:** Reusable instructions for common tasks like code review, PR creation,
+   and writing planning specs, architecture docs, and research briefs.
+
+`tbd` comes pre-installed with in-depth guidelines docs on many topics, including
+TypeScript and Python best practices and common agent pitfalls, red-green TDD, golden
+testing, Convex, monorepo project setup, error handling practices, and backward
+compatibility rules.
+(But you can use your own guidelines if you prefer.)
+
+I use `tbd` most frequently in Claude Code since it’s most powerful as a skill, but it
+will work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.
 
-`tbd` comes pre-installed with guideline docs on dozens of topics, notably TypeScript
-and Python best practices and common agent pitfalls, red-green TDD, golden testing,
-Convex, monorepo project setup, error handling practices, and backward compatibility
-rules. But you can use your own if you prefer.
+## Quick Start
 
-I use `tbd` most frequently in Claude Code, where it self-installs as a skill, but it
-will work in Cursor, Codex, or any agent environment that can use the `tbd` CLI.
+> [!TIP]
+> 
+> If running on your own machine, install the `tbd` CLI yourself:
+> 
+> **`npm install -g get-tbd@latest`**
+> 
+> Then tell your agent:
+> 
+> ***“run tbd for instructions to set up this project”***
+> 
+> If running on a fresh cloud instance (like Claude Code Cloud), tell the agent:
+> 
+> ***“install tbd (npm install -g get-tbd@latest) and run tbd for instructions to set up
+> this project”***
 
-## Should You Use `tbd`?
+That’s it. Running `tbd` with no arguments “primes” the agent with how to use `tbd` and
+how to help you. It will then bootstraps a SKILL.md into your project by running
+`tbd setup --auto` (which will add a `.tbd` directory and add itself to your `.claude`
+skills and hooks). And then it will use shortcuts to welcome you and get you started.
+
+You can then always ask questions like: “what can I do with tbd?”
 
-Firstly, you can use `tbd` simply as a Beads replacement.
-It’s largely compatible with the original `bd` at the CLI level for core issue tracking
-functionality.
+## How Should You Use `tbd`?
 
-Unfortunately, inspite of the power of the beads ideas, there are quite a few
-[practical frustrations](#how-does-tbd-compare-to-beads) with the original
+### Drop-In `bd` Replacement
+
+You can use `tbd` as a drop-in replacement for the original Beads (`bd`). It’s largely
+compatible at the CLI level for core issue tracking functionality.
+
+Despite the general power of the beads, there are quite a few
+[practical frustrations](#how-does-tbd-compare-to-beads) with the original Beads
 implementation—notably the daemon modifying files, merge conflicts, sync confusions
-across branches and database, and SQLite not working in Claude Code Cloud.
+across branches and database, and SQLite not working on network drives, such as Claude
+Code Cloud. After using `bd` for over a month, this became my greatest pain point.
+I now use `tbd` for all my agent coding and its sync architecture works pretty well.
+
+### Spec-Driven Coding and Review
+
+What excites me now is that `tbd` is more than just task management.
 
-`tbd` is *very* new but aims to be a fully functional option for those who want an
-alternative to `bd` for agent issue tracking.
-I now use it instead of `bd` now.
+These workflows arose from several months of
+[heavy spec-driven agentic coding](https://github.com/jlevy/speculate/blob/main/about/lessons_in_spec_coding.md).
+With better use of specs, what you build is far clearer and more maintainable.
+In fact, I think of iterating on a spec as the hard part now.
+Writing the code is often almost automatic, if a spec is good enough!
+
+Basically 100% of the code I now write is agent-written, planned and tracked through
+specs and beads and streamlined with shortcuts.
 
-But what excites me now is that `tbd` is more than just task management: the CLI is a
-way to **inject engineering rules and best practices** and **streamline reproducible
-workflows with shortcuts**.
+To help with this, `tbd` provides a way to **inject engineering rules and best
+practices** and **streamline reproducible workflows with shortcuts**.
 
 By combining task management, knowledge injection, and shortcuts, I find my agents ship
 code with speed, quality, and discipline.
+
+### Shortcuts for Common Tasks (Easy with Voice!)
+
+Once you start doing things like the above workflows, it gets repetitive.
+And I like to now use voice to give prompts.
+So having “shortcut” docs that list common tasks is really helpful.
+
 I can now ship entire large features just with voice prompts like “use the shortcut to
 create a new plan spec that …” and “now use the shortcut to file a PR with a validation
 plan.”
 
-These workflows arose from several months of
-[heavy spec-driven agentic coding](https://github.com/jlevy/speculate/blob/main/about/lessons_in_spec_coding.md).
-Basically 100% of the code I now write is agent-written, planned and tracked through
-specs and beads and streamlined with shortcuts.
+### What `tbd` Doesn’t Do (Yet)
 
 `tbd` focuses on the *durable layer* of agent development: issue tracking, planning, and
 knowledge that persist in git across sessions.
@@ -73,34 +115,15 @@ agents handling different aspects that I manage) is slower, because it forces yo
 design, but it gives higher quality results.
 
 > [!NOTE]
+> 
 > We use *Beads* (capitalized) to refer to Steve Yegge’s original
 > [`bd` tool](https://github.com/steveyegge/beads).
 > Lowercase “beads” refers generically to the issues stored in `tbd` or `bd`.
 
-## Quick Start
-
-> [!TIP]
-> 
-> *Install `tbd` globally for convenience:*
-> 
-> **`npm install -g get-tbd@latest`**
-> 
-> Then tell your agent:
-> 
-> ***“run tbd for instructions to set up this project”***
-
-That’s it. Running `tbd` with no arguments gives your agent what it needs as well as
-information on how to help you.
-It will then bootstraps a SKILL.md into your project by running `tbd setup --auto`
-(which will add a `.tbd` directory and add itself to your `.claude` skills and hooks).
-And then it will use then use shortcuts to welcome you and get you started.
-
-You can then always ask questions like: “what can I do with tbd?”
-
-## How to Use tbd
+## How to Use `tbd`
 
 You talk to your agent in natural language.
-The agent translates your requests into tbd commands.
+The agent translates your requests into `tbd` commands.
 
 The `tbd` CLI blends task tracking and context injection.
 Some `tbd` commands do things, like create or update beads, and some help the agent get
@@ -108,19 +131,20 @@ status or context or knowledge and know what to do next:
 
 | What you say | What happens | What runs |
 | --- | --- | --- |
-| "Let's plan a new feature that …" | Agent creates a spec from a template | `tbd shortcut new-plan-spec` |
-| "Break this spec into beads" | Agent creates implementation beads from the spec | `tbd shortcut plan-implementation-with-beads` |
-| "Implement these beads" | Agent works through beads systematically | `tbd shortcut implement-beads` |
+| "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) |
+| "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) |
+| "Implement these beads" | Agent works through beads systematically | [`tbd shortcut implement-beads`](packages/tbd/docs/shortcuts/standard/implement-beads.md) |
 | "Create a bead for the bug where …" | Agent creates and tracks a bead | `tbd create "..." --type=bug` |
 | "Let's work on current beads" | Agent finds ready beads and starts working | `tbd ready` |
-| "Code review all changes on this branch" | Agent loads language-specific review guidelines | `tbd shortcut review-code-typescript` or `tbd shortcut review-code-python` |
-| "Use the shortcut to commit" | Agent runs full pre-commit checks, code review, and commits | `tbd shortcut commit-code` |
-| "Create a PR" | Agent creates or updates the pull request | `tbd shortcut create-or-update-pr-simple` |
-| "Let's create a research brief on …" | Agent creates a research document using a template | `tbd shortcut new-research-brief` |
-| "How could we test this better?" | Agent loads TDD and testing guidelines | `tbd guidelines general-tdd-guidelines` |
-| "How can we make this a well-designed TypeScript CLI?" | Agent loads TypeScript CLI guidelines | `tbd guidelines typescript-cli-tool-rules` |
-| "Can you review if this TypeScript package setup follows best practices" | Agent loads monorepo patterns | `tbd guidelines typescript-monorepo-patterns` |
-| "How can we do a better job of testing?" | Agent loads golden testing guidelines | `tbd guidelines golden-testing-guidelines` |
+| "Review this code" | Agent performs comprehensive code review with all guidelines | [`tbd shortcut review-code`](packages/tbd/docs/shortcuts/standard/review-code.md) |
+| "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) |
+| "Use the shortcut to commit" | Agent runs full pre-commit checks, code review, and commits | [`tbd shortcut commit-code`](packages/tbd/docs/shortcuts/standard/commit-code.md) |
+| "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) |
+| "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) |
+| "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) |
+| "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) |
+| "Can you review if this TypeScript package setup follows best practices" | Agent loads monorepo patterns | [`tbd guidelines typescript-monorepo-patterns`](packages/tbd/docs/guidelines/typescript-monorepo-patterns.md) |
+| "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) |
 
 Under the hood, your agent runs these `tbd` commands automatically.
 You just talk naturally.
@@ -133,7 +157,7 @@ You just talk naturally.
 > (`tbd design`).
 
 - **Git-native:** Beads live in your repo, synced to a separate, dedicated `tbd-sync`
-  branch. Your code history stays clean — no bead churn polluting your logs.
+  branch. Your code history stays clean—no bead churn polluting your logs.
 - **Agent friendly:** JSON output, non-interactive mode, simple commands that agents
   understand. Installs itself as a skill in Claude Code.
 - **Markdown + YAML frontmatter:** One file per bead, human-readable and editable.
@@ -141,8 +165,8 @@ You just talk naturally.
 - **Beads alternative:** Largely compatible with `bd` at the CLI level, but with a
   simpler architecture: no JSONL merge conflicts, no daemon modifying your working tree,
   no SQLite file locking on network filesystems (see
-  [FAQ: How does tbd compare to Beads?](#how-does-tbd-compare-to-beads)).
-- **Shortcuts:** Over a dozen reusable workflow documents — plan specs, code reviews,
+  [FAQ: How does `tbd` compare to Beads?](#how-does-tbd-compare-to-beads)).
+- **Shortcuts:** Over a dozen reusable workflow documents—plan specs, code reviews,
   commit processes, PR creation, research briefs, and more.
 - **Guidelines:** [17+ guideline docs](packages/tbd/docs/guidelines/) of coding rules
   and best practices (see
@@ -150,19 +174,25 @@ You just talk naturally.
 - **Templates:** Document templates for planning specs, research briefs, architecture
   docs.
 
-## Why?
+## Why is This a Good Idea?
 
-With the right structures, agents can often write 100% of your code.
-But without structure and knowledge, the results are hit-or-miss and they don’t scale to
-large projects.
+Engineers are still adjusting to how fast things are changing.
+But the reality is that most of the time now, if you’re doing it right, *agents should
+write 100% of your code*.
 
-Agents by nature are mediocre engineers.
+But anyone who’s coded a lot with agents knows they can be very bad or very good,
+depending on the situation.
+Without structure and knowledge, the results are often slop or have critical flaws or
+they don’t scale to large projects.
 They forget conventions between sessions, skip testing, and don’t follow your team’s
-patterns. The usual fix—pasting rules into prompts or CLAUDE.md files—is fragile and
-doesn’t scale.
+patterns.
 
-Beads (git-native CLI-based issue tracking) solve the task management problem
-brilliantly. If you’re not using beads already, you should be!
+The usual tactics like pasting rules into prompts is fragile and tiring.
+And even adding all these rules to CLAUDE.md or AGENTS.md doesn’t scale.
+
+Beads (git-native CLI-based issue tracking) is one element of the solution.
+It solves the task management problem brilliantly.
+If you’re not using beads already, you should be!
 
 But task tracking alone doesn’t help with *planning* or *quality*. You still need a way
 to think through what you’re building before you start, and a way to make sure the agent
@@ -177,17 +207,26 @@ sessions.
 My current favorite workflows and guidelines are included by default, but you’re not
 locked in. Add your own via `--add` or configure what’s available in `.tbd/config.yml`.
 
-And yes, all the code *and* all the speccs of `tbd` are agent written—see
+And yes, all the code *and* all the specs of `tbd` are agent written—see
 [the FAQ](#was-tbd-built-with-tbd).
 
 ## Built-in Engineering Knowledge
 
 When you run `tbd setup`, your agent gets instant access to
 [17+ guideline documents](packages/tbd/docs/guidelines/) covering real-world engineering
-practices. These aren’t generic tips — they’re detailed, opinionated rules with concrete
-examples, built from months of heavy agentic coding.
+practices. These aren’t generic tips; they’re mostly my own detailed and sometimes
+opinionated rules with concrete examples, built from months of heavy agentic coding.
 
-**Highlights:**
+> [!TIP]
+> 
+> An example: I *strongly* believe there are much better ways to do testing
+> proliferating hundreds of unit and integration tests.
+> So (with help from some Opus 4.5 and GPT-5 Pro) I wrote a multi-page brief about
+> “[golden testing](packages/tbd/docs/guidelines/golden-testing-guidelines.md)”
+> techniques, which allow the LLM to do end-to-end testing of CLI or web app flows in a
+> clean, token-friendly way.
+> Now simply telling your agent “check the guidelines on golden testing” can make a huge
+> difference, encouraging far more maintainable, deeper tests.
 
 | Guideline | What it covers |
 | --- | --- |
@@ -228,10 +267,10 @@ npm install -g get-tbd@latest
 ### Setup
 
 ```bash
-# Fresh project (--prefix is REQUIRED — it appears in every bead ID, e.g. myapp-a1b2)
+# Fresh project (--prefix is REQUIRED—it appears in every bead ID, e.g. myapp-a1b2)
 tbd setup --auto --prefix=myapp
 
-# Joining an existing tbd project (no prefix needed — reads existing config)
+# Joining an existing tbd project (no prefix needed—reads existing config)
 tbd setup --auto
 
 # Migrate from Beads (uses your existing beads prefix)
@@ -243,7 +282,7 @@ tbd setup --from-beads
 
 ### Team Setup
 
-tbd is designed for teams where one person sets up the project and others join later.
+`tbd` is designed for teams where one person sets up the project and others join later.
 
 **First contributor:**
 ```bash
@@ -257,7 +296,7 @@ git push
 ```bash
 git clone <repo>
 npm install -g get-tbd@latest
-tbd setup --auto                    # No --prefix needed — reads existing config
+tbd setup --auto                    # No --prefix needed—reads existing config
 ```
 
 ### Claude Code Integration
@@ -265,8 +304,8 @@ tbd setup --auto                    # No --prefix needed — reads existing conf
 `tbd setup --auto` configures SessionStart hooks that run at the beginning of each
 Claude Code session:
 
-- **`tbd prime`** — injects workflow context so the agent knows how to use tbd
-- **`ensure-gh-cli.sh`** — installs the GitHub CLI (`gh`) if not already available
+- **`tbd prime`**—injects workflow context so the agent knows how to use `tbd`
+- **`ensure-gh-cli.sh`**—installs the GitHub CLI (`gh`) if not already available
 
 **GitHub authentication:** For `gh` to work, set these environment variables before
 starting your agent session:
@@ -294,7 +333,7 @@ tbd list --all
 tbd setup beads --disable    # Optionally disable beads after migration
 ```
 
-Issue IDs are preserved: `proj-123` in beads becomes `proj-123` in tbd.
+Issue IDs are preserved: `proj-123` in beads becomes `proj-123` in `tbd`.
 
 ## Commands
 
@@ -326,18 +365,18 @@ tbd search "authentication"            # Search beads
 
 ### Shortcuts, Guidelines, and Templates
 
-tbd bundles three types of documentation your agent can invoke on demand:
+`tbd` bundles three types of documentation your agent can invoke on demand:
 
 ```bash
-# Shortcuts — workflow instructions
+# Shortcuts—workflow instructions
 tbd shortcut --list              # List all shortcuts
 tbd shortcut new-plan-spec       # Get the plan spec workflow
 
-# Guidelines — coding rules and best practices
+# Guidelines—coding rules and best practices
 tbd guidelines --list            # List all guidelines
 tbd guidelines typescript-rules  # Get TypeScript rules
 
-# Templates — document scaffolds
+# Templates—document scaffolds
 tbd template --list              # List all templates
 tbd template plan-spec           # Get a plan spec template
 
@@ -357,35 +396,18 @@ tbd template --add=<url> --name=<name>
 | `new-validation-plan` | Create a test/validation plan |
 | `plan-implementation-with-beads` | Break a spec into implementation beads |
 | `implement-beads` | Implement beads from a spec |
+| `review-code` | Comprehensive code review (uncommitted, branch, or PR) |
+| `review-github-pr` | Review a GitHub PR with commenting and CI checks |
+| `review-code-typescript` | TypeScript-focused code review |
+| `review-code-python` | Python-focused code review |
 | `precommit-process` | Pre-commit review and testing |
 | `commit-code` | Commit with pre-commit checks |
-| `review-code-typescript` | Code review for TypeScript |
-| `review-code-python` | Code review for Python |
 | `create-or-update-pr-simple` | Basic PR creation |
 | `create-or-update-pr-with-validation-plan` | PR with a validation plan |
 
-**Available guidelines** (see
-[Built-in Engineering Knowledge](#built-in-engineering-knowledge) for details):
-
-| Guideline | Description |
-| --- | --- |
-| [`general-tdd-guidelines`](packages/tbd/docs/guidelines/general-tdd-guidelines.md) | TDD methodology |
-| [`golden-testing-guidelines`](packages/tbd/docs/guidelines/golden-testing-guidelines.md) | Golden/snapshot testing |
-| [`general-testing-rules`](packages/tbd/docs/guidelines/general-testing-rules.md) | General testing principles |
-| [`typescript-code-coverage`](packages/tbd/docs/guidelines/typescript-code-coverage.md) | Code coverage with Vitest and v8 |
-| [`typescript-rules`](packages/tbd/docs/guidelines/typescript-rules.md) | TypeScript coding rules |
-| [`typescript-monorepo-patterns`](packages/tbd/docs/guidelines/typescript-monorepo-patterns.md) | pnpm workspaces, package setup, monorepo architecture |
-| [`typescript-cli-tool-rules`](packages/tbd/docs/guidelines/typescript-cli-tool-rules.md) | CLI tools with Commander.js |
-| [`python-rules`](packages/tbd/docs/guidelines/python-rules.md) | Python coding rules |
-| [`python-cli-patterns`](packages/tbd/docs/guidelines/python-cli-patterns.md) | Python CLI architecture |
-| [`backward-compatibility-rules`](packages/tbd/docs/guidelines/backward-compatibility-rules.md) | API and schema compatibility |
-| [`general-coding-rules`](packages/tbd/docs/guidelines/general-coding-rules.md) | Constants, magic numbers, practices |
-| [`general-comment-rules`](packages/tbd/docs/guidelines/general-comment-rules.md) | Comment best practices |
-| [`general-style-rules`](packages/tbd/docs/guidelines/general-style-rules.md) | Auto-formatting and output formatting |
-| [`general-eng-assistant-rules`](packages/tbd/docs/guidelines/general-eng-assistant-rules.md) | AI assistant objectivity and communication |
-| [`commit-conventions`](packages/tbd/docs/guidelines/commit-conventions.md) | Conventional commits format |
-| [`convex-rules`](packages/tbd/docs/guidelines/convex-rules.md) | Convex database patterns |
-| [`convex-limits-best-practices`](packages/tbd/docs/guidelines/convex-limits-best-practices.md) | Convex platform limits and workarounds |
+**Available guidelines:** See
+[Built-in Engineering Knowledge](#built-in-engineering-knowledge) for the full list of
+17+ guidelines covering TypeScript, Python, testing, TDD, and more.
 
 **Available templates:**
 
@@ -436,59 +458,16 @@ tbd docs                     # Full CLI reference
 ```
 
 Or read online:
-- [CLI Reference](packages/tbd/docs/tbd-docs.md) — Complete command documentation
-- [Design Doc](packages/tbd/docs/tbd-design.md) — Technical architecture
-
-## Team Workflows
-
-tbd is designed for teams where one person sets up the project and others join later.
-
-**First contributor (project setup):**
-```bash
-npm install -g get-tbd@latest
-tbd setup --auto --prefix=myproject
-git add .tbd/ .claude/ && git commit -m "Initialize tbd"
-git push
-```
-
-**Joining contributors:**
-```bash
-git clone <repo>                    # .tbd/ directory comes with repo
-npm install -g get-tbd@latest       # If not already installed
-tbd setup --auto                    # No --prefix needed! Reads existing config
-```
-
-The second contributor just runs `tbd setup --auto` — no need to know the project prefix
-or any other configuration details.
-
-**Updating tbd:** After upgrading tbd (`npm install -g get-tbd@latest`), run
-`tbd setup --auto` to refresh local skill files with the latest shortcuts, guidelines,
-and templates.
-
-## Migration from Beads
-
-```bash
-# Auto-detects beads and migrates (uses existing beads prefix)
-tbd setup --from-beads
-
-# Verify
-tbd stats
-tbd list --all
-
-# If you wish to disable beads after migration
-tbd setup beads --disable
-```
-
-Issue IDs are preserved: `proj-123` in beads becomes `proj-123` in tbd.
-The prefix from your beads configuration is automatically used.
+- [CLI Reference](packages/tbd/docs/tbd-docs.md)—Complete command documentation
+- [Design Doc](packages/tbd/docs/tbd-design.md)—Technical architecture
 
 ## How It Works
 
-tbd keeps two things separate from your code:
+`tbd` keeps two things separate from your code:
 
 - **Beads** live on a dedicated `tbd-sync` branch.
   One Markdown file per bead means parallel creation never conflicts.
-  `tbd sync` pushes changes — no manual git operations needed.
+  `tbd sync` pushes changes—no manual git operations needed.
 - **Documents** (shortcuts, guidelines, templates) are cached locally in `.tbd/docs/`
   during `tbd setup --auto`. Your agent reads them on demand via `tbd shortcut`,
   `tbd guidelines`, and `tbd template`. Re-run `tbd setup --auto` anytime to refresh
@@ -496,37 +475,36 @@ tbd keeps two things separate from your code:
 - **Everything is self-documented via the CLI.** Running `tbd` with no arguments gives
   full orientation. `tbd setup --auto` writes a skill file (SKILL.md/AGENTS.md) that
   teaches the agent all available commands, shortcuts, and guidelines.
-  This means agents can inject context — specs, engineering guidelines, workflow
-  instructions — at any point in a session, not just at startup.
+  This means agents can inject context—specs, engineering guidelines, workflow
+  instructions—at any point in a session, not just at startup.
 
 See the [design doc](packages/tbd/docs/tbd-design.md) for details.
 
 ## FAQ
 
-### How does tbd compare to Beads?
+### How does `tbd` compare to Beads?
 
-tbd was inspired by [Beads](https://github.com/steveyegge/beads) by Steve Yegge, and I’m
-grateful for the idea — it genuinely changed how I work with agents.
+`tbd` was inspired by [Beads](https://github.com/steveyegge/beads) by Steve Yegge, and
+I’m grateful for the idea—it genuinely changed how I work with agents.
 If you’re not familiar with Beads, the core insight is that git-native issue tracking
 raises an agent’s capacity for structured work from ~5-10 to-do items to hundreds of
 beads.
 
-tbd builds on that foundation with a simpler architecture: plain Markdown files instead
-of JSONL, no daemon, no SQLite, no 4-way sync.
+`tbd` builds on that foundation with a simpler architecture: plain Markdown files
+instead of JSONL, no daemon, no SQLite, no 4-way sync.
 This avoids the edge cases I ran into with network filesystems (Claude Code Cloud),
 merge conflicts, and multi-agent workflows.
 
-tbd also adds spec-driven planning and curated engineering guidelines — things Beads
-doesn’t attempt. If you already use Beads, `tbd setup --from-beads` migrates your beads
-with IDs preserved.
+If you already use Beads, `tbd setup --from-beads` migrates you to `tbd`. This imports
+and sets up your `.tbd` directory and preserves the IDs of all issues.
 
-**Scope:** tbd focuses on the *durable layer* — issue tracking, specs, and knowledge
+**Scope:** `tbd` focuses on the *durable layer*—issue tracking, specs, and knowledge
 that persist across sessions and live in git.
 It does *not* aim to solve real-time multi-agent coordination, which is a separate
 problem requiring sub-second messaging and atomic claims.
 Tools like [Agent Mail](https://github.com/Dicklesworthstone/mcp_agent_mail) and
 [Gas Town](https://github.com/steveyegge/gastown) address that space and are
-complementary to tbd — you could layer real-time coordination on top of tbd’s durable
+complementary to `tbd`—you could layer real-time coordination on top of `tbd`'s durable
 tracking. See the [design doc](packages/tbd/docs/tbd-design.md) for a detailed
 comparison.
 
@@ -541,22 +519,22 @@ work into well-defined beads.
 The agent then implements each bead with clear context about the bigger picture.
 
 This matters because with a good spec broken into beads, you can leave an agent running
-overnight and come back to code that’s well-structured and coherent — not a pile of
+overnight and come back to code that’s well-structured and coherent—not a pile of
 disconnected changes.
-tbd bakes in shortcuts for the full cycle: writing specs, breaking them into beads,
+`tbd` bakes in shortcuts for the full cycle: writing specs, breaking them into beads,
 implementing, validating, and shipping.
 
-### Was tbd built with tbd?
+### Was `tbd` built with `tbd`?
 
-Of course! I boostrapped with the original `bd`. It imported from `bd` and began
+Of course! I bootstrapped with the original `bd`. It imported from `bd` and began
 self-hosting its own tasks, then took over its own specs and reminds itself of its own
 coding guidelines. Here’s what that looks like in practice:
 
-**Specs:** tbd has dozens of active and completed plan specs, such as:
-- `plan-2026-01-15-tbd-v1-implementation.md` — The original v1 design
-- `plan-2026-01-20-streamlined-init-setup-design.md` — Redesigning the setup flow
-- `plan-2026-01-26-configurable-doc-cache-sync.md` — Making the doc system configurable
-- `plan-2026-01-28-cli-add-docs-by-url.md` — Adding `--add` for external docs
+**Specs:** `tbd` has dozens of active and completed plan specs, such as:
+- `plan-2026-01-15-tbd-v1-implementation.md`—The original v1 design
+- `plan-2026-01-20-streamlined-init-setup-design.md`—Redesigning the setup flow
+- `plan-2026-01-26-configurable-doc-cache-sync.md`—Making the doc system configurable
+- `plan-2026-01-28-cli-add-docs-by-url.md`—Adding `--add` for external docs
 
 **Beads:** Features are broken into beads and worked through systematically.
 For example, the current list of open beads for this project looks like
@@ -586,9 +564,8 @@ $
 
 ### Can I add my own guidelines?
 
-Yes.
-tbd comes with 17+ bundled guidelines, but you can add your own team’s docs from any
-URL:
+Yes. `tbd` comes with 17+ bundled guidelines, but you can add your own team’s docs from
+any URL:
 
 ```bash
 tbd guidelines --add=<url> --name=my-team-rules