---
allowed-tools: Bash(tbd:*) Read Write
description: |-
  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, Rust, TDD, golden testing, Convex, monorepo patterns), code cleanup, research briefs, architecture docs, agent handoffs, external tracker and Linear integration setup, personal Linear API key onboarding, viewing beads in a live browser, 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, Rust, Convex, monorepo, cleanup, dead code, refactor, handoff, research, architecture, labels, search, web, browser, live view, external tracker, Linear, Linear API key, integration setup, checkout library, source code review, or any workflow shortcut.
name: tbd
---
<!-- DO NOT EDIT: Generated by tbd setup (format=f08).
Run 'tbd setup' to update.
-->

**`tbd` helps humans and agents ship code with greater speed, quality, and discipline.**

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. **Knowledge Injection**: 40+ engineering guidelines (TypeScript, Python, Rust, 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      # Install or upgrade the CLI (same command for both)
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 — also the upgrade step (applies any format migration; commit the diff it reports)
tbd setup --from-beads             # Migration from .beads/ if `bd` has been used
```

If tbd refuses with “This repository requires a newer version of tbd”, run the two
install/upgrade commands above.

## Routine Commands

```bash
tbd --help    # Command reference
tbd status    # Status
tbd doctor    # If there are problems

tbd setup --auto   # Run any time to refresh setup
tbd prime      # Restore full context on tbd after compaction
tbd web --open # Open the live, read-only bead viewer
```

## CRITICAL: You Operate tbd, the User Doesn’t

**You are the tbd operator:** Users talk naturally; you translate their requests to tbd
actions. DO NOT tell users to run tbd commands.
That’s your job.

- **WRONG**: “Run `tbd create` to track this bug”

- **RIGHT**: *(you run `tbd create` yourself and tell the user it’s tracked)*

**Live browser requests:** When the user asks to see, show, open, or view beads in a
browser, start `tbd web --open` yourself with the agent platform’s long-running process
facility. Do not merely print the command.
If the requested project is outside your current working directory, start
`tbd web <path> --open`; the path may be its repository root or any subdirectory.
Wait for the startup descriptor, give the user its loopback URL, and leave the process
running until they ask you to stop it or the session environment requires cleanup.

The page is a live, read-only viewer, not an editor.
You remain the tbd operator: make every requested bead change with ordinary `tbd`
commands, and the running page observes the resulting local state automatically.
Browser filters change only the presentation.
Starting the viewer never justifies an implicit fetch, merge, or push; run `tbd sync`
only when the user asks to exchange remote bead state, after which its local result also
appears automatically.

**Welcoming a user:** When users ask “what is tbd?”
or want help → run `tbd shortcut welcome-user`

## User Request → Agent Action

| User Says | You (the Agent) Run |
| --- | --- |
| **Issues/Beads** |  |
| “There’s a bug where …” | `tbd create "..." --type=bug` |
| “Create a task/feature for …” | `tbd create "..." --type=task` or `--type=feature` |
| “Let’s work on issues/beads” | `tbd ready` |
| “Show my beads in a browser” | Start `tbd web --open` yourself, wait for its URL, and keep it running |
| “Show me issue X” (or several) | `tbd show <id1> [<id2> …]` (one call, never a loop; `--max-lines <n>` caps output per issue) |
| “Where do things stand on spec X?” | `tbd list --spec <path-or-filename>` (all specs at once: `tbd list --specs`) |
| “Close this issue” | `tbd close <id>` (several: `tbd close <id1> <id2> …` — one call, never a loop) |
| “Search issues for X” | `tbd search "X"` (matches content and issue IDs, so partial IDs work) |
| “Add label X to issue” | `tbd label add <id> <label>` (several beads: `tbd update <id1> <id2> … --add-label <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` |
| **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** |  |
| *(any engineering work)* | Load the **General engineering** group first (see below) |
| “Use TypeScript best practices” | `tbd guidelines typescript-rules typescript-lint-format-rules` |
| “Use Python best practices” | `tbd guidelines python-rules` |
| “Use Rust best practices” | `tbd guidelines rust-rules rust-lint-format-rules` |
| “Set up TS/JS lint, format, or hooks” | `tbd guidelines typescript-lint-format-rules` |
| “Set up Rust lint, clippy, or the quality floor” | `tbd guidelines rust-lint-format-rules` |
| “Build a Rust CLI” | `tbd guidelines rust-cli-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` |
| “What guidelines/docs are there?” | `tbd docs list` |
| “Make the guidelines visible / customize doc X” | `tbd docs fork --category=general --category=<lang>` (recommended: general + the repo’s languages), or `tbd docs fork <name>` / `--all`; then edit in `docs/tbd/` |
| “Update the guidelines to the latest” | `tbd docs update`; on conflicts ask the user, then `--merge` or `--keep-ours` |
| “I deleted a forked doc file” | `tbd docs status` shows it `missing`; restore with `tbd docs fork <name> --force` or finalize with `tbd docs unfork <name>` |
| **External Trackers** |  |
| “Set up Linear” / “Connect this repo to Linear” | `tbd shortcut setup-linear` |
| “My Linear sync isn’t working” / “Add my Linear key” | `tbd shortcut setup-linear` |
| **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. |

**Loading guidelines for engineering work:** three layers, in this order.

1. **Always**, before writing or reviewing code, load the engineering core:

   ```bash
   tbd guidelines general-eng-agent-principles
   ```

2. **The language documents** that match the changed surface.
   Do not load an entire language group by default.

3. **Cross-cutting topics, by what the change actually touches**—errors, tests and
   goldens, code and comment policy, dependencies, published interfaces, commits,
   review, CI and gates, filesystem work, and releases.
   These are not always-load: read the group’s note in `tbd guidelines --list` and pull
   the ones that apply.

Load several selected documents in **one call**; `guidelines`, `shortcut`, `template`,
and `docs show` all take several names.

Run `tbd guidelines --list` to see all available guidelines.

**Where beads live:** on the dedicated `tbd-sync` branch, not your working branch.
Bead changes never appear in your feature branch’s commits or its PR diff.
That is the design, not lost work: don’t hunt for them there, and don’t claim
“everything is on this PR” about bead state.

**Let tbd own that branch.** `tbd sync` maintains it and `tbd doctor --fix` repairs it.
Use tbd commands rather than raw git for anything touching `tbd-sync`; hand checkouts,
merges, and pushes are how bead state gets tangled.

**Note:** `.tbd/workspaces/` is the exception: never gitignore it; the outbox must be
committed to your working branch.
See `tbd guidelines tbd-sync-troubleshooting` for details.

## CRITICAL: Session Closing Protocol

**Before saying “done”, you MUST complete this checklist:**

```
[ ] 1. git add + git commit
[ ] 2. git push
[ ] 3. gh pr checks <PR> --watch 2>&1 (IMPORTANT: WAIT for final summary, do NOT tell user it is done until you confirm it passes CI!)
[ ] 4. tbd close <id1> <id2> ... --reason "..." — one bulk call per group of beads sharing a reason (never a per-ID loop)
[ ] 5. tbd sync
[ ] 6. CONFIRM CI passed (if failed: fix, run tests, re-push, restart from step 3)
```

**Work is not done until pushed, CI passes, and tbd is synced.**

**Remote/proxied session where GitHub seems blocked?** If the environment has egress,
`gh` works through a scoped `NO_PROXY` bypass.
Three facts decide most of these:

- The git remote may sit behind a **ref-scoped credential broker**: pushes to
  `refs/heads/*` succeed, pushes to `refs/tags/*` fail with HTTP 403. Create the tag on
  the direct channel instead:
  `gh api repos/OWNER/REPO/git/refs -f ref=refs/tags/vX.Y.Z -f sha=SHA`.
- `git push --dry-run` **passes** for tags the broker then refuses at receive-pack, so a
  clean dry run proves nothing.
- A GitHub-host 403 carrying no `x-github-request-id` header is proxy-manufactured, not
  an organization egress denial.

Run `tbd shortcut setup-github-cli` and follow “Proxied Remote Sessions” before
concluding gh is unavailable.

## Bead Tracking Rules

- Track all task work not done immediately as beads (discovered work, TODOs,
  multi-session work)
- When in doubt, create a bead
- Check `tbd ready` when not given specific directions
- Always close/update beads and run `tbd sync` at session end

## Commands

### Finding Work

| Command | Purpose |
| --- | --- |
| `tbd ready` | Beads ready to work (no blockers) |
| `tbd list --status open` | All open beads |
| `tbd list --status in_progress` | Your active work |
| `tbd list --spec <path>` | Beads tracking a spec (filename or suffix is enough) |
| `tbd list --sort updated --limit 10` | Recent activity; `--count` for totals |
| `tbd show <id1> [<id2> …]` | Bead details with dependencies (bulk: delimited per issue; `--max-lines <n>` caps each) |

### Creating & Updating

| Command | Purpose |
| --- | --- |
| `tbd create "title" --type=bug --priority=1` | New bead; run `tbd create --help` for all types and priorities (P0-P4, not “high/medium/low”) |
| `tbd create "title" --parent <epic> --depends-on <id>` | Create fully wired: parent and blockers in one call (`--depends-on` is repeatable) |
| `tbd update <id> --status in_progress` | Claim work |
| `tbd close <id> [--reason "..."]` | Mark complete |
| `tbd close <id1> <id2> <id3> --reason "..."` | Close several at once (always preferred over one-at-a-time) |
| `tbd update <id1> <id2> <id3> --priority 1` | Bulk-update shared fields on several beads |

**IMPORTANT: if you are about to shell-loop or pipe around tbd, stop; the bulk or filter
form exists.** `show`, `close`, `reopen`, and `update` take multiple IDs;
`guidelines`/`shortcut`/`template`/`docs show` take multiple names; `dep add` takes
multiple blockers; list/search/show have `--limit`/`--count`/`--max-lines`. NEVER
`for id in …; do tbd close $id; done` (one call gives one lock, one summary, `--json`,
and `--ignore-missing`), NEVER `tbd show X | head` (use `--max-lines`), NEVER
`tbd list | grep <id>` (use `tbd search <partial-id>`). A bulk call shares one reason
(and, for `update`, one set of field changes), so group the beads that share the same
mutation and make one call per group.

### Dependencies & Sync

| Command | Purpose |
| --- | --- |
| `tbd dep add <bead> <blocker1> [<blocker2> …]` | Add blocker dependencies (one call per bead) |
| `tbd blocked` | Show blocked beads |
| `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 or (partial) issue ID |
| `tbd label add <id> <label>` | Add label to issue (several beads: `tbd update <ids…> --add-label`) |
| `tbd label remove <id> <label>` | Remove label from issue |
| `tbd label list` | List all labels in use |
| `tbd stale` | List issues not updated recently |

### External Trackers (Linear)

| Command | Purpose |
| --- | --- |
| `tbd integration status --offline` | Distinguish shared config from a missing personal key without a network call |
| `tbd integration status` | Verify the configured key and Linear team are reachable |
| `tbd --dry-run integration sync --push` | Preview which beads would go outward |
| `tbd integration sync --push` | Outbound only: create/update tracker issues (idempotent) |
| `tbd integration sync --pull` | Inbound only: tracker changes into beads, no external writes |
| `tbd integration sync --pull --external <ref...>` | Create beads from exactly named tracker items, independent of policy |
| `tbd integration sync` | Both directions; converges to `nothing to do` |
| `tbd integration link/unlink <bead> [ref]` | Bind or sever a bead and an existing tracker item; unlink safely cancels pending writes for that pair before clearing the link |
| `tbd integration comment <bead> "text"` | Author a comment offline; posted on next sync |

**Setting Linear up at all — including “add my key” — is `tbd shortcut setup-linear`.**
Run it rather than improvising; it detects which case applies and walks the user through
only that case.

The mental model it encodes: **config is shared, credentials are personal.** The
`integrations` block in `.tbd/config.yml` (team, project, policy) is committed, so a
teammate who clones already has it; `LINEAR_API_KEY` lives in the environment or a
**gitignored** `.env` and is never committed.
So a user joining a repo whose team already syncs needs *only* a key—never a config
edit, and never `integration sync --push` (their links arrived with the clone; after a
dry-run preview, plain `tbd sync` first pulls the team’s current bead state and then
reconciles Linear). Run `tbd integration status --offline` first in every case.
Full details: the External Tracker Integrations section of `tbd docs`. Bulk runs over 20
creates / 40 updates refuse without `--yes`. Never echo credentials into output or
commits.
`--pull` never replays or performs provider writes; deferred claims and conflict
notices remain journaled until the next full sync.
Link/inbound creation refuse a remote `tbd://bead/…` claim unless `--force` is explicit
and the old claim was verified stale.
Configured `project` scopes both creates and automatic inbound scans; an explicit
`--external` import bypasses that scan scope.
Assignees sync only through `user_map`: beads retain aliases (including on initial
import), runtime email/UUID targets never persist, unmapped local aliases are reported,
and an unmapped provider identity leaves the local field and prior bridge base unchanged
with a safe warning, preserving local divergence until mapping recovers.
Linear sub-issues import parent-first and never flatten; `max_nesting` limits only new
outbound creation. Comments are append-only and paginated; edits, deletions, reactions,
and thread shape are not synchronized.
Linear descriptions carry a tbd-owned `⟦tbd⟧` … `⟦/tbd⟧` region.
Human prose outside it is preserved; legacy HTML-comment delimiters are upgraded on the
next outbound sync. Never hand-edit the managed region—change the bead and sync instead.

**Direction flags mean the same thing everywhere in tbd**: bare = both directions,
`--push` = outbound only, `--pull` = inbound only, `--status` = report only.
Plain `tbd sync` at session end covers docs, issues, AND enabled trackers; surfaces run
independently, so one failing (an expired key, a down remote) never stops the others,
and every failure is reported at the end.
Narrow with `--docs`, `--issues`, or `--integrations` for a single surface.

### Documentation

| Command | Purpose |
| --- | --- |
| `tbd shortcut <name>` | Run a shortcut |
| `tbd shortcut --list` | List shortcuts |
| `tbd guidelines <name> [<name> …]` | Load coding guidelines (several names in one call) |
| `tbd guidelines --list` | List guidelines |
| `tbd template <name>` | Output a template |
| `tbd docs` / `tbd docs list` | Managed-docs overview / cross-kind list with state markers |
| `tbd docs fork/unfork/update <name>` | Fork docs into `docs/tbd/`, return to upstream, pull upstream updates |

## Quick Reference

- **Priority**: P0=critical, P1=high, P2=medium (default), P3=low, P4=backlog
- **Types**: issues default to `task`; run `tbd create --help` for the valid types
- **Status**: open, in_progress, closed
- **JSON output**: Add `--json` to any command

<!-- BEGIN SHORTCUT DIRECTORY -->
## Available Shortcuts

Run `tbd shortcut <name>` to use any of these shortcuts:

| Name | Description |
| --- | --- |
| address-pr-review | Address an existing PR review from any channel—track every finding as a bead, fix or rebut each, reply with a per-finding disposition map, and get CI green |
| agent-handoff | Generate a concise handoff prompt for another coding agent to continue work |
| checkout-third-party-repo | Get source code for libraries and third-party repos using git. Essential for reliable source code review. Prefer this to web searches or fetching of web pages from github.com as it is far more effective (github.com blocks web scraping from main website). |
| code-cleanup-all | Full cleanup cycle including duplicate removal, dead code, and code quality improvements |
| code-cleanup-docstrings | Review and add concise docstrings to major functions and types |
| code-cleanup-tests | Review and remove tests that do not add meaningful coverage |
| code-review-and-commit | Run pre-commit checks, review changes, and commit code |
| coding-spike | Prototype to validate a spec through hands-on implementation |
| create-or-update-pr-simple | Create or update a pull request with a concise summary |
| create-or-update-pr-with-validation-plan | Create or update a pull request with a detailed test/validation plan |
| implement-beads | Implement beads from a spec, following TDD and project rules |
| merge-upstream | Merge origin/main into the current branch with conflict resolution, then verify, push, and watch CI |
| new-architecture-doc | Create an architecture document for a system or component design |
| new-guideline | Create a new coding guideline document for tbd |
| new-plan-spec | Create a new feature planning specification document |
| new-qa-playbook | Create a QA test playbook for manual validation workflows |
| new-research-brief | Create a research document for investigating a topic or technology |
| new-shortcut | Create a new shortcut (reusable instruction template) for tbd |
| new-validation-plan | Create a validation/test plan showing what’s tested and what remains |
| plan-implementation-with-beads | Create implementation beads from a feature planning spec |
| pr-review-workflows | The PR review lifecycle—how reviews are created, published (formal review, PR comment, GitHub issue, or review doc), and addressed, and which shortcut runs each stage. Start here to pick the right review shortcut. |
| precommit-process | Full pre-commit checklist including spec sync, code review, and testing |
| review-code | Comprehensive code review for uncommitted changes, branch work, or GitHub PRs |
| review-code-python | Python-focused code review (language-specific rules only) |
| review-code-rust | Rust-focused code review (language-specific rules only) |
| review-code-typescript | TypeScript-focused code review (language-specific rules only) |
| review-github-pr | Review a GitHub pull request and publish the review to a chosen channel (formal review, PR comment, GitHub issue, or in-repo review doc). To fix the findings, see address-pr-review. |
| revise-all-architecture-docs | Comprehensive revision of all current architecture documents |
| revise-architecture-doc | Update an architecture document to reflect current codebase state |
| setup-github-cli | Ensure GitHub CLI (gh) is installed and working |
| setup-linear | Set up the Linear integration end to end—first-time configuration for a repository, or adding your own API key to a repository your team already configured |
| suggest-upstream-improvements | Review local doc-fork customizations and contribute the generally useful changes back upstream |
| sync-failure-recovery | Handle tbd sync failures by saving to workspace and recovering later |
| update-specs-status | Reconcile active specs, the top-level work index (e.g. TODO.md), and tbd beads into one current status map |
| watch-beads | Wake an agent when selected remote bead state changes |
| welcome-user | Welcome message for users after tbd installation or setup |

## Available Guidelines

Run `tbd guidelines <name>` to apply any of these guidelines.
Load the **General engineering** core, then only guidelines matching the task.

### General engineering

*Read this core before writing or reviewing code. Everything else is routed by what the change touches.*

| Name | Description |
| --- | --- |
| general-eng-agent-principles | Core principles for AI agents acting as senior engineers—objectivity and communication conduct plus the engineering process (detailed understanding, verification, end-to-end ownership, scope discipline, tracking future work, acting versus seeking clarification, and no ceremony without benefit) |

### Cross-cutting engineering topics

*Select by the changed surface; do not load this whole group by default.*

| Name | Description |
| --- | --- |
| backward-compatibility-rules | Guidelines for maintaining backward compatibility only for real consumers and data from released versions |
| ci-and-gates-rules | How to wire a quality gate that actually holds—one entry point in two modes, thin workflow and build-file orchestration backed by tested project-native programs, config-contract checks that prove the floor is live, the traps that keep a gate green while it checks nothing (pipeline exit status, self-recorded evidence, single-platform blindness, scope holes), suppression ratchets, generated-file ownership, and least-privilege workflow authority. Language-neutral; load it with the language floor document whenever wiring, debugging, or reviewing a gate. |
| code-review-rules | The language-neutral substance of a code review—the Blocker/High/Medium/Low severity vocabulary, establishing a baseline before hunting findings, reviewing highest-risk boundaries first, writing findings that can be acted on, and investigative quick-scan questions with possible consequences. The review-code shortcuts are the procedure; this is what they apply. Load for any review, with the language-specific review document where one exists. |
| commit-conventions | Conventional Commits format with extensions for agentic workflows |
| error-handling-rules | Rules for handling errors, failures, and exceptional conditions |
| filesystem-rules | Language-neutral rules for code that reads directory trees or mutates files—atomic publication of completed output files, atomic visibility versus crash durability, explicit metadata and collision policy, cross-device moves, deterministic traversal, symlink and root boundaries, honest partial failure, and failure injection at commit boundaries. Load whenever a change touches file mutation, traversal, or path handling, alongside the language-specific filesystem document if one exists. |
| general-coding-rules | Rules for constants, magic numbers, cryptographic hash checks, and general coding practices |
| general-comment-rules | Language-agnostic rules for writing clean, maintainable comments |
| general-tdd-guidelines | Test-Driven Development methodology and best practices |
| general-testing-rules | Rules for keeping test volume low while preserving broad evidence—rejecting vacuous tests, choosing portable black-box tests when they preserve coverage, keeping the inner loop fast, controlling nondeterminism, and never letting an empty or skipped selection look like a pass. |
| golden-testing-guidelines | Guidelines for implementing golden/snapshot testing for complex systems |
| release-engineering-rules | Language-neutral rules for turning a reviewed commit into artifacts users execute—one release identity, a pre-release gate that runs where publishing happens, least-privilege publishing authority, build-once-and-promote, packaging and checksums, smoke-testing the packaged artifact rather than the build output, multi-channel coordination, testable release logic, and incident preparation. Load for any release, alongside release-notes-guidelines and the language-specific release document. |
| supply-chain-hardening | Strongly recommended for EVERY repo—apply it if a repo has not been hardened yet. Cross-ecosystem policy for installing dependencies safely (the 14-day cool-off, disabled install scripts, lockfile discipline, untrusted-repo handling). Use whenever a user mentions hardening, security, supply chain, or setting up a new repo; before adding/upgrading dependencies; when auditing for compromised packages; or when reviewing install/build/run commands across npm/pnpm, PyPI, Cargo, or Go. |

### TypeScript & JS ecosystem

*Select the documents that match the TypeScript or JavaScript surface; do not load this whole group by default.*

| Name | Description |
| --- | --- |
| bun-monorepo-patterns | Modern patterns for Bun-based TypeScript monorepo architecture |
| electron-app-development-patterns | Building a clean, minimal, standalone Electron app—process model, modern Vite-based build system, attaching a Node/Bun/Python backend, security baseline, packaging, code signing, and auto-update |
| pnpm-monorepo-patterns | Modern patterns for pnpm-based TypeScript monorepo architecture |
| typescript-cli-tool-rules | Rules for building CLI tools with Commander.js, picocolors, and TypeScript |
| typescript-code-coverage | Best practices for code coverage in TypeScript with Vitest and v8 provider |
| typescript-lint-format-rules | The shared lint and auto-formatting floor for all TypeScript and JavaScript projects, across pnpm and Bun and across ESLint/Prettier and Biome toolchains. Defines the rules every project enforces, the per-toolchain profiles that implement them, and the verification steps that prove the floor is real. |
| typescript-rules | TypeScript coding rules and best practices |
| typescript-sorting-patterns | Deterministic sorting patterns and comparison chains for TypeScript |
| typescript-yaml-handling-rules | Best practices for parsing and serializing YAML in TypeScript |

### Python

*Select the documents that match the Python surface; do not load this whole group by default.*

| Name | Description |
| --- | --- |
| python-cli-patterns | Modern patterns for Python CLI application architecture |
| python-modern-guidelines | Guidelines for modern Python projects using uv, with a few more opinionated practices |
| python-rules | General Python coding rules and best practices |

### Rust

*Select the documents that match the Rust surface; do not load this whole group by default.*

| Name | Description |
| --- | --- |
| rust-cli-rules | Rules for composable, testable, and cross-platform Rust command-line applications |
| rust-code-review-rules | The Rust-specific half of review—which guideline owns each changed surface, the unsafe and FFI checklist, and a Rust quick-scan table of investigative questions and possible consequences. The severity vocabulary, review baseline, and risk ordering live in code-review-rules. |
| rust-filesystem-rules | The Rust-specific half of filesystem work—path and string types, intent-specific write boundaries, the tempfile atomic-replacement sequence, traversal crate choice and error propagation, and platform metadata. The behavior contract itself lives in filesystem-rules. |
| rust-lint-format-rules | The lint and auto-formatting floor for every Rust project—the `[lints]` block, the clippy.toml, rustfmt and toolchain pinning, hooks and CI gates, and how to prove the floor is live. Includes measured adoption cost for the lints beyond the floor, taken from a real 35k-line codebase, so a project can decide with evidence rather than taste. |
| rust-project-setup | Rules for structuring, validating, and maintaining modern Rust packages and workspaces |
| rust-release-rules | The Rust-specific half of releasing—crates.io publishing and workspace ordering, trusted publishing, cargo package and the unpublished-sibling trap, semver checks, and shipping a Rust binary as a Python wheel through maturin. The release contract itself lives in release-engineering-rules. |
| rust-rules | General Rust coding rules for modern libraries, applications, services, and command-line tools |
| rust-testing-rules | Rules for effective unit, integration, property, snapshot, and cross-platform testing in Rust |

### Convex

*Select the documents that match the Convex surface; do not load this whole group by default.*

| Name | Description |
| --- | --- |
| convex-limits-best-practices | Comprehensive reference for Convex platform limits, workarounds, and performance best practices |
| convex-rules | Guidelines and best practices for building Convex projects, including database schema design, queries, mutations, and real-world examples |

### Docs, process & tooling

| Name | Description |
| --- | --- |
| agent-session-bootstrap | When and how to make a repository install its own pinned toolchain at agent session start, for repos whose agents run in containers they do not control. Covers the fit test, the alternatives that are usually better, the install rules a bootstrap must follow, and the PATH and pin-drift traps that make one fail silently. Use when an agent session starts without the tools the repo requires, when writing or reviewing a SessionStart hook, or when deciding between a session hook and a provisioned image. |
| cli-agent-skill-patterns | A concise decision guide for portable skills, CLI-backed skills, safe bundle installation, and agent integration |
| common-doc-guidelines | Common cross-project standards for writing and organizing docs, code comments, and text files—how to organize, structure, write, and format documents, plus the guideline footer convention. Downstream of github.com/jlevy/practical-prose. Use whenever writing or editing any documentation, README, guideline, or design doc. |
| electrobun-app-development-patterns | Building desktop apps with Electrobun—runtime and process model, typed RPC, project layout, packaging and the delta updater, plus an evidence-based maturity and security assessment |
| release-notes-guidelines | Rules for release notes that describe the published delta and exclude defects introduced and corrected before release from separate Fixes entries |
| tauri-app-development-patterns | Building desktop apps with Tauri 2—the Rust core and system webview model, capabilities and permissions, typed commands and IPC, attaching Rust or non-Rust backends, packaging, signing, and the signed updater |
| tbd-sync-troubleshooting | Common issues and solutions for tbd sync and workspace operations |

<!-- END SHORTCUT DIRECTORY -->