get-tbd 0.1.13 → 0.1.15

package/dist/docs/shortcuts/standard/{commit-code.md → code-review-and-commit.md}

@@ -1,6 +1,7 @@
 ---
 title: Commit Code
 description: Run pre-commit checks, review changes, and commit code
+category: git
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/coding-spike.md

@@ -0,0 +1,54 @@
+---
+title: Coding Spike
+description: Prototype to validate a spec through hands-on implementation
+category: planning
+author: Kam Leung with LLM assistance
+---
+We track work as beads using tbd.
+Run `tbd` for more on using tbd and current status.
+
+A **coding spike** is time-boxed exploration to validate technical assumptions through
+implementation.
+Write production-quality code to uncover real constraints, but treat this
+as a learning exercise—the code may be discarded or revised.
+
+Instructions:
+
+Create a to-do list with the following items then perform all of them:
+
+1. Create a spike bead:
+   ```bash
+   tbd create "Spike: <what you're validating>" --type task
+   ```
+
+2. Understand the spec and identify technical questions that need answers.
+
+3. Define spike scope: What’s the minimum implementation needed to learn?
+   What will you explicitly NOT build?
+
+4. Build production-quality prototypes:
+   - Follow project conventions and include tests
+   - Focus on uncertain approaches that need validation
+   - Prioritize learning over feature completeness
+   - Create child beads for distinct components if helpful
+
+5. Capture learnings as you go—document in the spec given to you:
+   - Spec gaps, ambiguities, or errors found
+   - Complexity surprises (harder or easier than expected)
+   - Better approaches or patterns discovered
+   - New risks, dependencies, or performance concerns
+
+6. Refine the specification with findings:
+   - Clarify ambiguous sections
+   - Correct technical details that proved wrong
+   - Document discovered risks and update estimates
+
+7. Decide on spike code: keep and refine, keep as reference, or discard.
+
+8. Close the spike:
+   ```bash
+   tbd close <spike-bead-id> --reason "Spike complete: <outcome summary>"
+   tbd sync
+   ```
+
+9. Report findings and recommend next steps.

package/dist/docs/shortcuts/standard/create-or-update-pr-simple.md

@@ -1,6 +1,7 @@
 ---
 title: Create or Update PR (Simple)
 description: Create or update a pull request with a concise summary
+category: git
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/create-or-update-pr-with-validation-plan.md

@@ -1,6 +1,7 @@
 ---
 title: Create or Update PR with Validation Plan
 description: Create or update a pull request with a detailed test/validation plan
+category: git
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/implement-beads.md

@@ -1,6 +1,7 @@
 ---
 title: Implement Beads
 description: Implement beads from a spec, following TDD and project rules
+category: planning
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/merge-upstream.md

@@ -1,6 +1,7 @@
 ---
 title: Merge Upstream
 description: Merge origin/main into current branch with conflict resolution
+category: git
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Merge upstream changes from origin/main into the current branch.

package/dist/docs/shortcuts/standard/new-architecture-doc.md

@@ -1,6 +1,7 @@
 ---
 title: New Architecture Doc
 description: Create an architecture document for a system or component design
+category: documentation
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/new-guideline.md

@@ -1,6 +1,7 @@
 ---
 title: New Guideline
 description: Create a new coding guideline document for tbd
+category: meta
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 This shortcut helps create new guideline documents that agents can reference via
@@ -87,6 +88,11 @@ Create a to-do list with the following items then perform all of them:
    - Rebuild tbd: `pnpm build` (in packages/tbd/)
    - Verify bundled: check `packages/tbd/dist/docs/guidelines/<name>.md`
 
+9. **Update documentation** (for official guidelines):
+   - Add to root `README.md` “Built-in Engineering Knowledge” table
+   - Sync docs cache: `tbd setup --auto` (updates `.tbd/docs/`)
+   - Note: `packages/tbd/README.md` is auto-copied from root during build
+
 ## Guideline Quality Checklist
 
 - [ ] Frontmatter has title and description
@@ -96,6 +102,8 @@ Create a to-do list with the following items then perform all of them:
 - [ ] Cross-references to related guidelines
 - [ ] No relative links (use full URLs for external refs)
 - [ ] Tested with `tbd guidelines <name>`
+- [ ] (Official) Added to root README.md “Built-in Engineering Knowledge” table
+- [ ] (Official) Docs cache synced: `tbd setup --auto`
 
 ## Example Frontmatter
 

package/dist/docs/shortcuts/standard/new-plan-spec.md

@@ -1,6 +1,7 @@
 ---
 title: New Plan Spec
 description: Create a new feature planning specification document
+category: planning
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/new-research-brief.md

@@ -1,6 +1,7 @@
 ---
 title: New Research Doc
 description: Create a research document for investigating a topic or technology
+category: documentation
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/new-shortcut.md

@@ -1,6 +1,7 @@
 ---
 title: New Shortcut
 description: Create a new shortcut (reusable instruction template) for tbd
+category: meta
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Create a new shortcut for `tbd shortcut <name>`.
@@ -16,6 +17,7 @@ Create a new shortcut for `tbd shortcut <name>`.
 ---
 title: [Title]
 description: [One line for --list output]
+category: [category]
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 [Concise instructions. Focus on what's specific to this task.
@@ -23,11 +25,26 @@ Skip obvious steps the agent would figure out.
 Reference other shortcuts/guidelines/templates as needed.]
 ```
 
+## Categories
+
+Use one of these standard categories in the frontmatter:
+
+| Category | Use For |
+| --- | --- |
+| `planning` | Spec creation, implementation planning, validation plans |
+| `documentation` | Research briefs, architecture docs, doc revisions |
+| `review` | Code review, PR review |
+| `git` | Commits, PRs, merging, pre-commit workflows |
+| `cleanup` | Code cleanup, dead code removal, test cleanup |
+| `session` | Session management, handoffs, setup, recovery |
+| `meta` | Creating new shortcuts/guidelines |
+| `research` | Research tasks, third-party code checkout |
+
 ## Naming
 
 Use kebab-case: `new-<thing>`, `<verb>-<noun>`, `<thing>-<variant>`
 
-Examples: `commit-code`, `new-plan-spec`, `review-code-typescript`
+Examples: `code-review-and-commit`, `new-plan-spec`, `review-code-typescript`
 
 ## Key Principles
 
@@ -45,6 +62,15 @@ tbd shortcut --list      # Verify listing
 
 For official shortcuts: `pnpm build` in packages/tbd/
 
+## Documentation Updates (Official Shortcuts)
+
+For official shortcuts added to `packages/tbd/docs/shortcuts/standard/`:
+
+1. **Update root README.md** — Add to the “Available shortcuts” table (grouped by
+   category: Planning, Documentation, Review, Git, Cleanup, Session, Meta)
+2. **Sync docs cache** — Run `tbd setup --auto` to update `.tbd/docs/`
+3. **Rebuild** — `pnpm build` in packages/tbd/ (also copies README to package)
+
 ## Shortcuts vs Guidelines
 
 - **Shortcuts**: Workflows to follow (process)

package/dist/docs/shortcuts/standard/new-validation-plan.md

@@ -1,6 +1,7 @@
 ---
 title: New Validation Plan
 description: Create a validation/test plan showing what's tested and what remains
+category: planning
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Create a validation plan documenting completed and remaining validation work.

package/dist/docs/shortcuts/standard/plan-implementation-with-beads.md

@@ -1,6 +1,7 @@
 ---
 title: Plan Implementation with Beads
 description: Create implementation beads from a feature planning spec
+category: planning
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Break a plan spec (or other work) into implementation beads.

package/dist/docs/shortcuts/standard/precommit-process.md

@@ -1,6 +1,7 @@
 ---
 title: Pre-Commit Process
 description: Full pre-commit checklist including spec sync, code review, and testing
+category: git
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/review-code-python.md

@@ -1,6 +1,7 @@
 ---
 title: Review Code (Python)
 description: Python-focused code review (language-specific rules only)
+category: review
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 This shortcut performs a **Python-focused** code review, checking Python-specific best

package/dist/docs/shortcuts/standard/review-code-typescript.md

@@ -1,6 +1,7 @@
 ---
 title: Review Code (TypeScript)
 description: TypeScript-focused code review (language-specific rules only)
+category: review
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 This shortcut performs a **TypeScript-focused** code review, checking

package/dist/docs/shortcuts/standard/review-code.md

@@ -1,6 +1,7 @@
 ---
 title: Review Code
 description: Comprehensive code review for uncommitted changes, branch work, or GitHub PRs
+category: review
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 This is the **core code review** shortcut.

package/dist/docs/shortcuts/standard/review-github-pr.md

@@ -1,6 +1,7 @@
 ---
 title: Review GitHub PR
 description: Review a GitHub pull request with follow-up actions (comment, fix, CI check)
+category: review
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 This shortcut reviews a **GitHub pull request** and handles GitHub-specific follow-ups
@@ -34,36 +35,107 @@ Create a to-do list with the following items then perform all of them:
    - Run `tbd shortcut review-code` using the **GitHub PR** scope
    - The diff is obtained via: `gh pr diff <PR_NUMBER> --repo $REPO`
 
-5. **Compile full review:** Combine the code review findings with GitHub-specific info:
+5. **Check documentation consistency:**
+   - Review any specs referenced by the PR in `docs/project/specs/active/`
+   - Check if `docs/development.md` needs updates for behavioral changes
+   - Check if architecture docs in `docs/project/architecture/` need updates
+   - Note any documentation that is out of sync with the code changes
+
+6. **Review existing PR comments:**
+   - Get PR comments: `gh pr view <PR_NUMBER> --repo $REPO --comments`
+   - For review comments: `gh api repos/{owner}/{repo}/pulls/<PR_NUMBER>/comments`
+   - Note any unresolved comments or requested changes
+
+7. **Compile full review:** Combine the code review findings with GitHub-specific info:
 
    - **Summary**: Brief assessment (1-2 sentences)
    - **Strengths**: What’s done well (if any)
    - **Issues**: Problems found with `file:line` references and suggested fixes
+   - **Documentation gaps**: Specs or docs that need updating
+   - **Unresolved comments**: Any PR comments still needing attention
    - **Suggestions**: Optional improvements (not blockers)
    - **CI Status**: Current state of checks (passing/failing/pending)
 
-6. **Determine next action:**
+8. **Determine next action:**
    - If the user already specified what to do (e.g., “review and comment”, “review and
      fix”), follow those instructions
    - Otherwise, present the review and ask the user:
      - **Add as PR comment**: Post the review as a comment on the PR
-     - **Create fix beads**: Create tbd beads for issues found and begin fixing
+     - **Fix with beads**: Create tbd beads for every issue and systematically fix them
      - **Report only**: Just output the review (no action)
 
-7. **Take the requested action:**
+9. **Take the requested action:**
+
+   ### If adding as comment:
+
+   ```bash
+   gh pr review <PR_NUMBER> --repo $REPO --comment --body "<review>"
+   ```
+
+   ### If fixing with beads (comprehensive tracking):
+
+   This approach ensures **every issue is tracked** and nothing is lost:
+
+   a. **Create a parent bead** for the PR review:
+   ```bash
+   tbd create "Review PR #<NUMBER>: <title>" --type task --priority P1
+   ```
+
+   b. **Create child beads for EVERY issue found:**
+   ```bash
+   tbd create "<issue description>" --type bug --parent <parent-bead-id>
+   ```
+
+   Categories to track as beads:
+   - Code issues (bugs, antipatterns, missing error handling)
+   - Test gaps (missing tests, inadequate coverage)
+   - Documentation gaps (specs out of sync, missing updates)
+   - CI failures (each failing check)
+   - Unresolved PR comments
+
+   Each bead description should include:
+   - File and line number (e.g., `src/foo.ts:42`)
+   - Brief description of the issue
+   - Reference to the PR (e.g., `(PR #123)`)
+
+   c. **Check out the PR branch:**
+   ```bash
+   gh pr checkout <PR_NUMBER> --repo $REPO
+   ```
+
+   d. **Fix issues systematically:**
+   - Mark the parent bead as in_progress: `tbd update <id> --status in_progress`
+   - Work through each child bead in order:
+     - Mark as in_progress before starting
+     - Follow `tbd guidelines general-tdd-guidelines` for code fixes
+     - Run tests after each fix
+     - Mark as closed when complete: `tbd close <id>`
+   - Commit fixes with conventional commit messages
+
+   e. **Verify CI passes:**
+   - Push changes: `git push`
+   - Wait for CI: `gh pr checks <PR_NUMBER> --repo $REPO --watch 2>&1`
+   - **IMPORTANT**: Wait for the final summary—don’t stop at early “passing” output
+   - If CI fails: create a bead for the failure, fix it, restart this step
+
+   f. **Update PR description** to reflect what was fixed:
+   ```bash
+   gh pr edit <PR_NUMBER> --repo $REPO --body "..."
+   ```
+
+   g. **Close the parent bead:**
+   ```bash
+   tbd close <parent-bead-id> --reason "PR review complete, all issues resolved"
+   tbd sync
+   ```
 
-   - **If adding as comment:**
-     ```bash
-     gh pr review <PR_NUMBER> --repo $REPO --comment --body "<review>"
-     ```
+   ### If report only:
 
-   - **If creating fix beads:**
-     - Create a bead for each issue: `tbd create "Fix: ..." --type bug`
-     - Check out the PR branch if not already on it:
-       `gh pr checkout <PR_NUMBER> --repo $REPO`
-     - Follow `tbd shortcut implement-beads` to fix issues
-     - Push changes and update the PR
+   - Output the review
+   - No further action needed
 
-   - **If report only:**
-     - Output the review
-     - No further action needed
+10. **Report to user:**
+    - Summarize what was reviewed (and fixed, if applicable)
+    - List any beads created (if fixing with beads)
+    - Confirm CI status
+    - Provide the PR URL

package/dist/docs/shortcuts/standard/revise-all-architecture-docs.md

@@ -1,6 +1,7 @@
 ---
 title: Revise All Architecture Docs
 description: Comprehensive revision of all current architecture documents
+category: documentation
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 We track work as beads using tbd.

package/dist/docs/shortcuts/standard/revise-architecture-doc.md

@@ -1,6 +1,7 @@
 ---
 title: Revise Architecture Doc
 description: Update an architecture document to reflect current codebase state
+category: documentation
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Review and update an architecture document to ensure accuracy with current code.

package/dist/docs/shortcuts/standard/setup-github-cli.md

@@ -1,6 +1,7 @@
 ---
 title: Setup GitHub CLI
 description: Ensure GitHub CLI (gh) is installed and working
+category: session
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 The GitHub CLI (`gh`) is required for PR and issue operations.

package/dist/docs/shortcuts/standard/sync-failure-recovery.md

@@ -1,16 +1,13 @@
 ---
 title: Sync Failure Recovery
 description: Handle tbd sync failures by saving to workspace and recovering later
+category: session
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 When `tbd sync` fails to push (e.g., network errors, permission issues, branch
 restrictions), use this workflow to preserve and recover issue data.
 
-## Workflow
-
-### 1. When sync fails
-
-If `tbd sync` fails with a push error:
+## When Sync Fails
 
 ```bash
 # Save unsynced changes to the outbox
@@ -22,9 +19,7 @@ git commit -m "tbd: save outbox"
 git push
 ```
 
-The `--outbox` flag saves only issues modified since the last successful sync.
-
-### 2. Later, when sync works
+## Later, When Sync Works
 
 In a new session or environment where sync works:
 
@@ -36,52 +31,10 @@ tbd import --outbox
 tbd sync
 ```
 
-## Understanding Workspaces
-
-Workspaces are directories under `.tbd/workspaces/` that store issue backups.
-
-- `tbd save --outbox` saves to `.tbd/workspaces/outbox/`
-- `tbd import --outbox` imports from outbox and clears it on success
-- Workspaces are committed to your working branch (not gitignored)
+## More Information
 
-## Alternative: Named Workspaces
-
-For backups or bulk editing, use named workspaces:
+For detailed troubleshooting, workspace usage, and diagnostic commands, see:
 
 ```bash
-# Create a backup
-tbd save --workspace=backup-2026-01
-
-# Save to arbitrary directory
-tbd save --dir=/tmp/issues-backup
-
-# Import from named workspace
-tbd import --workspace=backup-2026-01
+tbd guidelines sync-troubleshooting
 ```
-
-## Checking Workspace Status
-
-```bash
-# List all workspaces
-tbd workspace list
-
-# See workspaces in tbd status output
-tbd status
-```
-
-## Multi-Agent Scenarios
-
-Multiple agents can save to the same outbox:
-
-- Different issues: No conflicts, all preserved
-- Same issue edited compatibly: Merged automatically
-- Same issue with conflicts: Conflict goes to attic for review
-
-## Troubleshooting
-
-If sync continues to fail:
-
-1. Check network connectivity
-2. Verify push permissions: `git push --dry-run origin tbd-sync`
-3. Check for branch restrictions in your environment
-4. Review error message from `tbd sync` for specific guidance

package/dist/docs/shortcuts/standard/update-specs-status.md

@@ -1,6 +1,7 @@
 ---
 title: Update Specs Status
 description: Review active specs and sync their status with tbd issues
+category: planning
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Review all active specs and ensure tbd issues accurately reflect current progress.

package/dist/docs/shortcuts/standard/welcome-user.md

@@ -1,6 +1,7 @@
 ---
 title: Welcome User
 description: Welcome message for users after tbd installation or setup
+category: session
 author: Joshua Levy (github.com/jlevy) with LLM assistance
 ---
 Welcome the user with the message below.
@@ -38,7 +39,7 @@ Here are examples of things you can say and what happens:
 | "Let's plan a new feature" | Walks you through creating a planning spec (`tbd shortcut new-plan-spec`) |
 | "Break the spec into issues" | Creates implementation beads from your spec (`tbd shortcut plan-implementation-with-beads`) |
 | "Implement these issues" | Works through beads systematically (`tbd shortcut implement-beads`) |
-| "Commit this code" | Reviews changes and commits properly (`tbd shortcut commit-code`) |
+| "Commit this code" | Reviews changes and commits properly (`tbd shortcut code-review-and-commit`) |
 | "Create a PR" | Creates a pull request with summary (`tbd shortcut create-or-update-pr-simple`) |
 | "Review this for best practices" | Performs a code review with guidelines |
 

package/dist/docs/shortcuts/system/skill-brief.md

@@ -27,7 +27,7 @@ tbd sync               # Sync with remote
 | --- | --- |
 | Found a bug | `tbd create "..." --type=bug` |
 | Plan a feature | `tbd shortcut new-plan-spec` |
-| Commit code | `tbd shortcut commit-code` |
+| Commit code | `tbd shortcut code-review-and-commit` |
 | Create a PR | `tbd shortcut create-or-update-pr-simple` |
 | TypeScript review | `tbd guidelines typescript-rules` |
 

package/dist/docs/shortcuts/system/skill.md

@@ -6,16 +6,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
 ```
@@ -48,20 +51,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
@@ -115,6 +140,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
 

package/dist/docs/skill-brief.md

@@ -27,7 +27,7 @@ tbd sync               # Sync with remote
 | --- | --- |
 | Found a bug | `tbd create "..." --type=bug` |
 | Plan a feature | `tbd shortcut new-plan-spec` |
-| Commit code | `tbd shortcut commit-code` |
+| Commit code | `tbd shortcut code-review-and-commit` |
 | Create a PR | `tbd shortcut create-or-update-pr-simple` |
 | TypeScript review | `tbd guidelines typescript-rules` |