get-tbd 0.1.13 → 0.1.15

package/README.md

@@ -1,7 +1,6 @@
 # tbd
 
-**Task management, spec-driven planning, and instant knowledge injection for AI coding
-agents.**
+**Task tracking, spec-driven planning, and knowledge injection for AI coding agents.**
 
 **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:
@@ -138,12 +137,12 @@ status or context or knowledge and know what to do next:
 | "Let's work on current beads" | Agent finds ready beads and starts working | `tbd ready` |
 | "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) |
+| "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) |
 | "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) |
+| "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) |
 | "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.
@@ -168,7 +167,7 @@ You just talk naturally.
   [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
+- **Guidelines:** [20+ guideline docs](packages/tbd/docs/guidelines/) of coding rules
   and best practices (see
   [Built-in Engineering Knowledge](#built-in-engineering-knowledge)).
 - **Templates:** Document templates for planning specs, research briefs, architecture
@@ -213,7 +212,7 @@ And yes, all the code *and* all the specs of `tbd` are agent written—see
 ## 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
+[20+ guideline documents](packages/tbd/docs/guidelines/) covering real-world engineering
 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.
 
@@ -235,8 +234,12 @@ opinionated rules with concrete examples, built from months of heavy agentic cod
 | [general-testing-rules](packages/tbd/docs/guidelines/general-testing-rules.md) | Minimal tests for maximum coverage, avoiding redundant test cases |
 | [typescript-code-coverage](packages/tbd/docs/guidelines/typescript-code-coverage.md) | Code coverage best practices with Vitest and v8 provider |
 | [typescript-rules](packages/tbd/docs/guidelines/typescript-rules.md) | Strict type safety, no `any`, type guards, null safety, async patterns |
-| [typescript-monorepo-patterns](packages/tbd/docs/guidelines/typescript-monorepo-patterns.md) | pnpm workspaces, package setup, tsdown, Changesets, publint, dual ESM/CJS |
+| [typescript-sorting-patterns](packages/tbd/docs/guidelines/typescript-sorting-patterns.md) | Deterministic sorting, comparison chains for multi-field sorts |
+| [pnpm-monorepo-patterns](packages/tbd/docs/guidelines/pnpm-monorepo-patterns.md) | pnpm workspaces, tsdown, Vitest, Changesets, publint, dual ESM/CJS |
+| [bun-monorepo-patterns](packages/tbd/docs/guidelines/bun-monorepo-patterns.md) | Bun workspaces, Bunup, Biome, bun test, standalone executables |
 | [typescript-cli-tool-rules](packages/tbd/docs/guidelines/typescript-cli-tool-rules.md) | Commander.js patterns, picocolors, terminal formatting |
+| [cli-agent-skill-patterns](packages/tbd/docs/guidelines/cli-agent-skill-patterns.md) | Building CLIs that function as agent skills in Claude Code |
+| [typescript-yaml-handling-rules](packages/tbd/docs/guidelines/typescript-yaml-handling-rules.md) | YAML parsing/serialization with the `yaml` package, Zod validation, consistent formatting |
 | [python-rules](packages/tbd/docs/guidelines/python-rules.md) | Type hints, docstrings, exception handling, resource management |
 | [python-cli-patterns](packages/tbd/docs/guidelines/python-cli-patterns.md) | Modern Python CLI stack: uv, Typer, Rich, Ruff, BasedPyright |
 | [backward-compatibility-rules](packages/tbd/docs/guidelines/backward-compatibility-rules.md) | Compatibility across code, APIs, file formats, and database schemas |
@@ -267,7 +270,7 @@ 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—2-8 alphabetic chars, e.g. myapp-a1b2)
 tbd setup --auto --prefix=myapp
 
 # Joining an existing tbd project (no prefix needed—reads existing config)
@@ -318,8 +321,9 @@ GH_PROMPT_DISABLED=1
 Create a [Personal Access Token](https://github.com/settings/tokens?type=beta)
 (fine-grained recommended) with **Contents** and **Pull requests** read/write
 permissions. For Claude Code Cloud, set these in your project’s environment variables.
-For local CLI usage, add them to your shell profile (`~/.zshrc` or `~/.bashrc`). See
-[GitHub CLI setup docs](docs/general/agent-setup/github-cli-setup.md) for details.
+For local CLI usage, add them to your shell profile (`~/.zshrc` or `~/.bashrc`). See the
+[setup-github-cli shortcut](packages/tbd/docs/shortcuts/standard/setup-github-cli.md)
+for details.
 
 To disable automatic `gh` installation, pass `--no-gh-cli` during setup or set
 `use_gh_cli: false` in `.tbd/config.yml` under `settings:`.
@@ -388,26 +392,41 @@ tbd template --add=<url> --name=<name>
 
 **Available shortcuts:**
 
-| Shortcut | Purpose |
-| --- | --- |
-| `new-plan-spec` | Create a feature planning spec |
-| `new-research-brief` | Create a research document |
-| `new-architecture-doc` | Create an architecture document |
-| `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 |
-| `create-or-update-pr-simple` | Basic PR creation |
-| `create-or-update-pr-with-validation-plan` | PR with a validation plan |
+| Category | Shortcut | Purpose |
+| --- | --- | --- |
+| **Planning** | `new-plan-spec` | Create a feature planning spec |
+|  | `plan-implementation-with-beads` | Break a spec into implementation beads |
+|  | `implement-beads` | Implement beads from a spec |
+|  | `new-validation-plan` | Create a test/validation plan |
+|  | `update-specs-status` | Review active specs and sync with tbd issues |
+| **Documentation** | `new-research-brief` | Create a research document |
+|  | `new-architecture-doc` | Create an architecture document |
+|  | `revise-architecture-doc` | Update an architecture doc to match current code |
+|  | `revise-all-architecture-docs` | Revise all current architecture documents |
+| **Review** | `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 |
+| **Git** | `precommit-process` | Pre-commit review and testing |
+|  | `code-review-and-commit` | Commit with pre-commit checks |
+|  | `create-or-update-pr-simple` | Basic PR creation |
+|  | `create-or-update-pr-with-validation-plan` | PR with a validation plan |
+|  | `merge-upstream` | Merge origin/main with conflict resolution |
+| **Cleanup** | `code-cleanup-all` | Full code cleanup (duplicates, dead code, quality) |
+|  | `code-cleanup-tests` | Remove trivial/low-value tests |
+|  | `code-cleanup-docstrings` | Add docstrings to major functions |
+| **Session** | `agent-handoff` | Generate handoff prompt for another agent |
+|  | `welcome-user` | Welcome message after tbd installation |
+|  | `setup-github-cli` | Ensure GitHub CLI is installed and working |
+|  | `sync-failure-recovery` | Handle tbd sync failures |
+|  | `checkout-third-party-repo` | Clone library source code for review |
+| **Exploration** | `coding-spike` | Prototype to validate a spec through implementation |
+| **Meta** | `new-guideline` | Create a new coding guideline for tbd |
+|  | `new-shortcut` | Create a new shortcut for tbd |
 
 **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.
+20+ guidelines covering TypeScript, Python, testing, TDD, and more.
 
 **Available templates:**
 
@@ -564,7 +583,7 @@ $
 
 ### Can I add my own guidelines?
 
-Yes. `tbd` comes with 17+ bundled guidelines, but you can add your own team’s docs from
+Yes. `tbd` comes with 20+ bundled guidelines, but you can add your own team’s docs from
 any URL:
 
 ```bash