get-tbd 0.1.13 → 0.1.15

package/dist/docs/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

package/dist/docs/SKILL.md

@@ -1,12 +1,19 @@
 ---
 name: tbd
 description: >-
-  Git-native issue tracking (beads), coding guidelines, and spec-driven planning for AI agents.
-  Use for tracking issues with dependencies, creating and closing bugs, features, and tasks,
-  planning specs for new features, implementing features from specs, code reviews, committing code,
-  creating PRs, research briefs, and architecture docs. Invoke when user mentions: tbd, beads,
-  issues, bugs, tasks, todo, tracking, specs, planning, implementation, validation, guidelines,
-  shortcuts, templates, commit, PR workflows, code review, testing best practices, or monorepo patterns.
+  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.
 allowed-tools: Bash(tbd:*), Read, Write
 ---
 
@@ -18,16 +25,19 @@ description: Full tbd workflow guide for agents
 
 1. **Beads**: Git-native issue tracking (tasks, bugs, features).
    Never lose work across sessions.
+   Drop-in replacement for `bd`.
 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.
+3. **Knowledge Injection**: 17+ engineering guidelines (TypeScript, Python, TDD,
+   testing, Convex, monorepos) available on demand.
+4. **Shortcuts**: Reusable instruction templates for common workflows (code review,
+   commits, PRs, cleanup, handoffs).
 
 ## Installation
 
 ```bash
 npm install -g get-tbd@latest
-tbd setup --auto --prefix=<name>   # 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 --prefix=<name>   # Fresh project (--prefix is REQUIRED: 2-8 alphabetic chars recommended. 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
 ```
@@ -60,20 +70,42 @@ or want help → run `tbd shortcut welcome-user`
 
 | User Says | You (the Agent) Run |
 | --- | --- |
+| **Issues/Beads** |  |
 | "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` |
+| "Create a task/feature for ..." | `tbd create "..." --type=task` or `--type=feature` |
+| "Let's work on issues/beads" | `tbd ready` |
+| "Show me issue X" | `tbd show <id>` |
+| "Close this issue" | `tbd close <id>` |
+| "Search issues for X" | `tbd search "X"` |
+| "Add label X to issue" | `tbd label add <id> <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` |
-| "Commit this" | `tbd shortcut commit-code` |
-| "Create a PR" | `tbd shortcut create-or-update-pr-simple` |
+| **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" | `tbd shortcut merge-upstream` |
+| **Guidelines & Knowledge** |  |
+| "Use TypeScript best practices" | `tbd guidelines typescript-rules` |
+| "Use Python best practices" | `tbd guidelines python-rules` |
+| "Build a TypeScript CLI" | `tbd guidelines typescript-cli-tool-rules` |
+| "Improve monorepo setup" | `tbd guidelines pnpm-monorepo-patterns` or `bun-monorepo-patterns` |
+| "Add golden/e2e testing" | `tbd guidelines golden-testing-guidelines` |
+| "Use TDD" / "Test-driven development" | `tbd guidelines general-tdd-guidelines` |
+| "Convex best practices" | `tbd guidelines convex-rules` |
+| **Documentation** |  |
 | "Research this topic" | `tbd shortcut new-research-brief` |
 | "Document architecture" | `tbd shortcut new-architecture-doc` |
+| **Cleanup & Maintenance** |  |
+| "Clean up this code" / "Remove dead code" | `tbd shortcut code-cleanup-all` |
+| "Fix repository problems" | `tbd doctor --fix` |
+| **Sessions & Handoffs** |  |
+| "Hand off to another agent" | `tbd shortcut agent-handoff` |
+| "Check out this library's source" | `tbd shortcut checkout-third-party-repo` |
 | *(your choice whenever appropriate)* | `tbd list`, `tbd dep add`, `tbd close`, `tbd sync`, etc. |
 
 ## CRITICAL: Session Closing Protocol
@@ -127,6 +159,17 @@ or want help → run `tbd shortcut welcome-user`
 | `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 |
+| `tbd label add <id> <label>` | Add label to issue |
+| `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