get-tbd 0.1.30 → 0.2.1

package/dist/docs/guidelines/cli-agent-skill-patterns.md

@@ -100,19 +100,28 @@ So:
    Stop here unless you have many subcommands or need cross-session state, structured
    auth, or background services — then see §6 (CLI-as-skill) and §7 (MCP).
 
+> **The skill points; the CLI documents.** A CLI’s `--help` (and per-command
+> `mycli <cmd> --help`) is the source of truth for flags, arguments, and exact command
+> sequences. The skill’s job is to name each capability and the command that reaches it,
+> then let the agent open the CLI’s own help for the details.
+> A skill carries the focused context an agent needs to judge that the tool is relevant;
+> copying its help text, flag tables, and command recipes wholesale is the most common
+> way a CLI-backed skill goes wrong.
+> See §3.1 for why and §6.5 for how to avoid it.
+
 ### 0.3 The one-paragraph decision guide
 
 - **Prompt/instructions only** → ship a `SKILL.md`. (§3, §4)
 - **Project-wide conventions** (build/test/style) → add an `AGENTS.md`. (§2)
-- **You have a CLI** → `SKILL.md` + agent-friendly `--json` CLI. (§0.2, §6)
+- **You have a CLI** → `SKILL.md` and an agent-friendly `--json` CLI. (§0.2, §6)
 - **Many subcommands / a knowledge library** → CLI-as-skill meta-pattern.
   (§6)
 - **A service with no CLI, or you need OAuth / multi-tenant / audit** → MCP server.
   (§7)
-- **Maximum reach across many agents** → layer them: AGENTS.md + SKILL.md + CLI + MCP.
+- **Maximum reach across many agents** → layer them: AGENTS.md, SKILL.md, CLI, and MCP.
   (§1)
 - **Self-installs into agents & ships evolving skills?** → that is the advanced Tier 2
-  pattern (self-upgrade + format versioning); most tools are Tier 1: a pure skill run
+  pattern (self-upgrade and format versioning); most tools are Tier 1: a pure skill run
   via a **pinned** `npx`/`uvx`. (§6.0)
 
 Everything below is reference material.
@@ -136,7 +145,7 @@ or capability.
 | 5. Per-agent polish | `.cursor/rules/*.mdc`, plugin packaging, ACP, etc. | Glob-scoped activation, enterprise distribution, editor discovery | Per-agent |
 
 **Recommended default for a tool author who wants broad reach**: ship an `AGENTS.md`
-snippet (universal baseline) + a `SKILL.md` (portable capability) + an agent-friendly
+snippet (universal baseline), a `SKILL.md` (portable capability), and an agent-friendly
 CLI. Add an MCP server only when a CLI can’t serve the need.
 Add agent-specific files last, and only where they buy something.
 
@@ -204,8 +213,8 @@ current ones. Only the `format=fNN` value changes when the block’s shape chang
 
 ## 3. The Agent Skills Standard (SKILL.md)
 
-**What it is**: a folder with a `SKILL.md` file (YAML frontmatter + Markdown body), plus
-optional supporting files.
+**What it is**: a folder with a `SKILL.md` file (YAML frontmatter and a Markdown body),
+plus optional supporting files.
 Created by Anthropic (Dec 2025), published under Apache 2.0 at
 [agentskills.io](https://agentskills.io).
 280,000+ public skills exist as of early 2026.
@@ -231,6 +240,17 @@ material (schemas, examples, scripts) in supporting files.
 Scripts execute *outside* the context window — only their output costs tokens, which is
 why bundling a script can be far cheaper than inlining instructions.
 
+**For a CLI-backed skill, the CLI itself is the Level-3 layer.** Treat `mycli --help`,
+`mycli <command> --help`, and the tool’s informational subcommands (§6.1) as the
+on-demand disclosure tier, the role supporting files play for a prompt-only skill.
+The body (Level 2) should route to them, not transcribe them.
+Inlining a command’s flags, arguments, or step-by-step usage pulls Level-3 detail up
+into Level 2, so it loads on every activation and goes stale whenever the CLI changes.
+The body names the capability and the command; the agent runs that command’s `--help` or
+`--list` when it needs the mechanics.
+This is progressive disclosure applied to a CLI: the tool documents itself, and the
+skill stays a thin pointer to it.
+
 ### 3.2 Bundled scripts and resources
 
 A skill folder can ship executable helpers:
@@ -318,8 +338,8 @@ Earlier guidance cited a flat ~15K-character budget.
 - The skill listing gets a budget of **~1% of the model’s context window** by default
   (`skillListingBudgetFraction`, default `0.01`). When it overflows, the
   least-recently-invoked skills lose their descriptions first.
-- Per-skill listing text (`description` + `when_to_use`) is truncated at **1,536 chars**
-  (`maxSkillDescriptionChars`).
+- Per-skill listing text (`description` and `when_to_use`) is truncated at **1,536
+  chars** (`maxSkillDescriptionChars`).
 - `SLASH_COMMAND_TOOL_CHAR_BUDGET` overrides the fraction with a fixed character count.
 - `skillOverrides` can set any skill to `on` / `name-only` / `user-invocable-only` /
   `off` without editing the file; `/doctor` reports overflow.
@@ -399,14 +419,14 @@ Verified against the Codex source (`codex-rs/core-skills/src/loader.rs`, tags
 `<dir>/.agents/skills/` from the project root down to cwd), `User`
 (`$HOME/.agents/skills/`), `Admin`, plus plugin roots and `$CODEX_HOME/skills`. So a
 **plain repo-root `.agents/skills/<name>/SKILL.md` is read directly**, no manifest
-required. (The repo path is built by joining `.agents` + `skills` at runtime, so it does
-*not* appear as a contiguous `.agents/skills` literal in the binary — a `strings`-based
-inspection will miss it and see only `.agents/plugins/marketplace.json`; confirm against
-the source, not binary strings.)
-**Plugins** are an *additional* distribution layer (installable units bundling skills +
-MCP servers — 90+ ship with Codex), declared in `.agents/plugins/marketplace.json` (also
-reads `.claude-plugin/marketplace.json`) — useful for *publishing a bundle*, but not
-needed to make a repo-local skill load.
+required. (The repo path is built by joining `.agents` and `skills` at runtime, so it
+does *not* appear as a contiguous `.agents/skills` literal in the binary — a
+`strings`-based inspection will miss it and see only `.agents/plugins/marketplace.json`;
+confirm against the source, not binary strings.)
+**Plugins** are an *additional* distribution layer (installable units bundling skills
+and MCP servers — 90+ ship with Codex), declared in `.agents/plugins/marketplace.json`
+(also reads `.claude-plugin/marketplace.json`) — useful for *publishing a bundle*, but
+not needed to make a repo-local skill load.
 Codex skills may carry a richer **`agents/openai.yaml`** companion (e.g.
 `interface.display_name`, icons, `dependencies.tools[]`,
 `policy.allow_implicit_invocation`); map the portable
@@ -431,7 +451,7 @@ sandboxed.
 This is the pattern for a richer tool: a CLI that is itself a skill, exposing many
 capabilities as subcommands while costing a single description slot.
 `tbd` is the reference implementation; **Beads/`bd`** (Steve Yegge), `tbd`’s lineage,
-follows the same shape (subcommands + `AGENTS.md` + `--json` + an optional MCP server).
+follows the same shape (subcommands, `AGENTS.md`, `--json`, and an optional MCP server).
 
 Use this when you have many capabilities, need cross-session state, or want a curated
 knowledge library the agent pulls from.
@@ -550,8 +570,39 @@ Rules: reference commands **explicitly** (`mycli command arg`, never “see the
 - **Actionable errors** that include the next command to run.
 - **Discoverable help**: an `IMPORTANT:` epilog pointing at a context-restore command
   (e.g., `mycli prime`), and a “Getting Started” one-liner.
-- **A `prime` command** (dashboard + status + rules) for session start and post-compact,
-  distinct from `skill` (pure documentation).
+- **A `prime` command** (dashboard, status, and rules) for session start and
+  post-compact, distinct from `skill` (pure documentation).
+  `prime` is **read-only**: it restores context but does not rewrite project files.
+  Because a `SessionStart` hook runs it on every session (§8), have `prime` print a
+  short reminder that the agent or user can run `setup` to refresh skills and settings
+  (for example after upgrading the tool).
+  That keeps the refresh **opt-in** rather than silently mutating the repo from a hook,
+  while still nudging stale installs forward.
+
+**Route, don’t restate: the skill is a thin pointer, not a copy of `--help`.** The most
+common failure when packaging a CLI as a skill is over-documentation, where the author
+(often an LLM, eagerly) copies the CLI’s help, flag lists, and command recipes wholesale
+into the skill body.
+Don’t. A self-documenting CLI already carries that detail in `mycli --help`,
+`mycli <command> --help`, and its informational subcommands (§6.1), so duplicating it
+only adds cost and drift (§3.1). The skill is a **knowledge, awareness, and routing
+layer**: it carries the focused context an agent needs to judge that the tool is
+relevant, names each key use case once, and gives the one command that reaches it, then
+trusts the agent to run that command (or its `--help`) for the specifics.
+
+| In the skill body (awareness and routing) | In the CLI’s own help (mechanics) |
+| --- | --- |
+| Each key capability or use case, named once | The full flag and argument reference |
+| The single command that reaches it (`mycli create`, `mycli guidelines <name>`) | Exact option syntax, defaults, and edge cases |
+| When to use the tool, and which command for which intent | Step-by-step recipes for a specific command |
+| Pointers: `mycli --help`, `mycli <cmd> --help`, `mycli <cmd> --list` | Examples and output formats |
+
+A quick test: if a line in the skill would become *wrong* when you add a flag or change
+behavior in the CLI, it belongs in the CLI’s help, not the skill.
+Mention every key use case, but push the “how exactly” (the sequence of commands and
+their options) down into the tool.
+Adequate beats exhaustive: a short skill that reliably routes the agent to the right
+command beats a long one that mirrors the manual.
 
 ### 6.6 Distribution & multi-agent install
 
@@ -621,14 +672,14 @@ project needs both.
 - **Fully generated install artifacts** (`.agents/skills/<tool>/SKILL.md`,
   `.claude/skills/<tool>/SKILL.md`, generated hook scripts, and the like): CLI-owned;
   mark them “DO NOT EDIT.” Pick **one of two modes** and be consistent:
-  - **Commit + dogfood** (what `tbd` does): check the generated artifacts in, and add a
-    **drift test** that regenerates them and fails if they differ.
+  - **Commit and dogfood** (what `tbd` does): check the generated artifacts in, and add
+    a **drift test** that regenerates them and fails if they differ.
     Pros: browsable on GitHub / skills.sh, the repo demonstrates its own output,
     reviewers see changes.
     Con: a regeneration shows up as a diff to commit.
     Keep generated output deterministic and formatter-stable (below) or the drift
     test/commits will churn.
-  - **Gitignore + regenerate** (what `metaproc` does): add `.../skills/*/SKILL.md` to
+  - **Gitignore and regenerate** (what `metaproc` does): add `.../skills/*/SKILL.md` to
     `.gitignore` and let `setup`/`--install` (re)create them on demand.
     Pros: zero commit churn, no drift to guard.
     Con: not browsable in the repo, and no committed artifact to diff in review.
@@ -660,6 +711,20 @@ hook commands (or leave a wrapper) so existing Claude hooks keep working.
 skill content evolves *will* leave older generated files in users’ repos.
 Treat generated integration files like config migrations:
 
+Reserve an `fNN` **format bump** for changes big enough to need an explicit migration: a
+different on-disk shape, a moved or renamed managed region, or a changed hook contract.
+Routine content edits (new skill text, an added shortcut, reworded guidance) are **not**
+a format change. They ship by regenerating the surface, a full overwrite on the next
+`setup` run, so they need no bump and no migration; bumping the format on every content
+tweak would force needless migrations and churn.
+
+The upgrade is also **opt-in, not silent**. A tool rewrites a user’s committed files
+only when the user or agent explicitly runs `setup`/`setup --auto`, never from a
+background hook or an ordinary read command.
+Stamping a format lets an explicit `setup` detect an older layout and offer to migrate
+it; it does not license the tool to mutate the repo on its own.
+(This is why a `SessionStart` hook should run a read-only `prime`, not `setup`.)
+
 - Version the generated surfaces with an `fNN` format code.
   Prefer **one format code for all the tool’s managed surfaces** — reuse the tool’s
   existing config/data-format version as the single source of truth (tbd stamps the
@@ -670,6 +735,16 @@ Treat generated integration files like config migrations:
   line (`<!-- BEGIN … format=fNN … -->`), the skill “DO NOT EDIT” marker, script
   headers, or an equivalent hook signature.
   Prefer one marker line over a separate metadata comment.
+- A **fully overwritten content surface** (a generated skill that is always rewritten
+  whole, never merged) does not strictly need its own stamp to upgrade cleanly: the next
+  `setup` replaces it outright.
+  It can lean on the single shared format code carried by a structural surface (such as
+  the `AGENTS.md` block).
+  But that only protects it if the forward-compatibility check runs **before** any
+  surface is written. If `setup` rewrites the skill first and only checks the `AGENTS.md`
+  format later, an older tool can partial-downgrade a newer committed skill before it
+  aborts. So either stamp and guard each generated surface, or run the format check up
+  front and write nothing until it passes.
 - On every `setup`/`setup --auto` run, **self-upgrade in place, safely and
   idempotently**: detect older formats and rewrite only the tool-owned regions (managed
   `AGENTS.md` block, generated skills, tool-owned hooks, `.codex/` config), re-running
@@ -732,7 +807,7 @@ The clean implementation is the host language’s plugin mechanism:
 
 Keep each registered skill a **spec** (name, two-part description, `allowed-tools`, a
 baseline source, and an optional dynamic catalog function) and run them all through the
-**same** `compose` + `--install` path, so every skill — first-party or third-party —
+**same** `compose` and `--install` path, so every skill — first-party or third-party —
 gets identical frontmatter, the `DO NOT EDIT`/format marker, and deterministic output.
 This keeps the “one tool, many self-injecting commands” model open for extension without
 the core tool taking a dependency on every plugin.
@@ -810,8 +885,8 @@ See `tbd guidelines supply-chain-hardening` for the cross-ecosystem policy.
   `uv tool install` / `pipx install`. `uvx` reuses a persistent install if one exists.
 - **Go**: `go run <module>@<ver>` (compiles on the fly) or `go install`.
 - **Rust**: no first-class zero-install runner — ship **prebuilt binaries** (GitHub
-  releases + a `curl … | sh` installer) or `cargo binstall`; `cargo install` compiles.
-- **Cross-language**: a prebuilt binary + install script, or a container image (Docker
+  releases and a `curl … | sh` installer) or `cargo binstall`; `cargo install` compiles.
+- **Cross-language**: a prebuilt binary and install script, or a container image (Docker
   is emerging as the production-grade distribution for MCP servers).
 
 This mirrors how the ecosystem ships agent tooling today: **MCP servers** are most often
@@ -821,7 +896,7 @@ configs; **CLIs** like Beads offer `brew` / `npm -g` / `curl` installers, while
 
 **Recommendation**: default the skill to a **pinned zero-install invocation**
 (`uvx`/`npx <pkg>@<version>`) for maximum reach across ephemeral and cloud agents; offer
-**global install + a `SessionStart` bootstrap** as the optimization for persistent
+**global install and a `SessionStart` bootstrap** as the optimization for persistent
 environments where the project wants lockfile-managed versions and warm-start speed.
 
 ### 6.8 Publishing & discovery — make the skill installable
@@ -832,15 +907,15 @@ and the ecosystem finds it.
 The landscape worth targeting:
 
 - **`skills.sh` / `npx skills add <owner/repo>`** (Vercel) — the cross-agent “npm for
-  skills”: one command installs into `.agents/skills/` + symlinks per agent (Claude
+  skills”: one command installs into `.agents/skills/` and symlinks per agent (Claude
   Code, Codex, Cursor, Copilot, Gemini, …). No review; ranked by install telemetry.
   **This is the highest-leverage target** and needs zero extra infra.
 - **GitHub-scraping indexers** (SkillsMP ~800k skills, ClaudeSkills.info, LobeHub,
   claudemarketplaces.com) — auto-list public repos that contain a `SKILL.md` (often
-  gated on ≥2 stars). You get listed for free just by being public + discoverable.
+  gated on ≥2 stars). You get listed for free just by being public and discoverable.
 - **Plugin marketplaces** — `.claude-plugin/marketplace.json` (Claude Code, the official
   Anthropic channel) and `.agents/plugins/marketplace.json` (Codex; Codex reads both).
-  These are *plugin* channels: bundles of skills + MCP + hooks + commands.
+  These are *plugin* channels: bundles of skills, MCP servers, hooks, and commands.
   They are **only for publishing a bundle** — a repo-local skill already loads from
   `.claude/skills/` (Claude Code) and `.agents/skills/` (Codex) **without any
   manifest**, so don’t add one just to be discovered.
@@ -873,10 +948,10 @@ itself. Generate this distribution `SKILL.md` from the same source as your in-re
 pushing.
 
 `tbd` does exactly this: `skills/tbd/SKILL.md` is generated at build time from the same
-baseline, carries `name: tbd` + a trigger-rich description, and opens with the
-`npm install -g get-tbd` + `tbd setup --auto` bootstrap — so `npx skills add jlevy/tbd`
-gives an agent a working landing page, and `tbd setup` then upgrades it to the full
-multi-agent install (§6.6).
+baseline, carries `name: tbd` and a trigger-rich description, and opens with the
+`npm install -g get-tbd` and `tbd setup --auto` bootstrap — so
+`npx skills add jlevy/tbd` gives an agent a working landing page, and `tbd setup` then
+upgrades it to the full multi-agent install (§6.6).
 
 * * *
 
@@ -1007,7 +1082,7 @@ going:
 - **Codex App-Server** — JSON-RPC (Thread/Turn/Item) decoupling Codex logic from client
   surfaces; relevant only for Codex-specific integration surfaces.
 - **Plugin marketplaces & `npx skills`** — distribution is consolidating: Claude Code
-  plugin marketplaces (official + community), Codex plugins, and Vercel’s
+  plugin marketplaces (official and community), Codex plugins, and Vercel’s
   `npx skills add` over the skills.sh directory (cross-agent symlinks).
 - **Routines / scheduled agents, background monitors, `/run` & `/verify` skills** —
   newer Claude Code capabilities for autonomous, event-triggered, and app-verifying
@@ -1031,6 +1106,10 @@ going:
 - Two-part rule: *what it does* + *when to use it*; third person; front-load keywords.
 - Progressive disclosure: metadata → body → supporting files; bundle scripts
   (output-only cost).
+- Route, don’t restate: name each capability and the command to run; let the CLI’s
+  `--help` and informational subcommands hold the flags and recipes.
+  Carry the focused context an agent needs to judge that the tool is relevant, but don’t
+  blindly copy help into the skill; that wastes context and goes stale (§3.1, §6.5).
 - Respect the budget; verify the current model for your target agent (Claude Code ≈ 1%
   of context window, not a flat char count).
 
@@ -1065,6 +1144,9 @@ going:
 **Baseline (every skill)**
 - [ ] `SKILL.md` with `name` + two-part `description`
 - [ ] Body < 500 lines; bulky material in supporting files one level deep
+- [ ] Body carries the essential context to judge whether the tool is relevant and to
+  name each key use case, but routes to `mycli <cmd> --help` or `--list` for flags and
+  recipes instead of copying help wholesale
 - [ ] Third-person description, trigger keywords front-loaded
 - [ ] Installable via commit to `.agents/skills/`, Claude mirror at `.claude/skills/`,
   and/or `npx skills add`
@@ -1174,3 +1256,7 @@ going:
 - Supply-chain / dependency currency: `tbd guidelines bun-monorepo-patterns` or
   `pnpm-monorepo-patterns`
 - Testing: `tbd guidelines general-testing-rules`
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/commit-conventions.md

@@ -77,3 +77,7 @@ ops: Update issue status for auth feature
 ops: Sync beads with remote
 process: Add TDD guidelines for agent workflows
 ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/common-doc-guidelines.md

@@ -0,0 +1,234 @@
+---
+title: Common Documentation Guidelines
+description: 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.
+author: Joshua Levy (github.com/jlevy) with LLM assistance
+---
+# Common Documentation Guidelines
+
+Version: v0.1 (last update 2026-05-11)\
+Joshua Levy (github.com/jlevy)
+
+## Purpose
+
+Both agents and humans benefit from accurate, maintained documentation.
+These are brief and general guidelines for humans and agents when writing and organizing
+code, text files, and documentation.
+
+See the [Practical Prose](https://github.com/jlevy/practical-prose) repository for more
+extensive guidelines and context.
+
+## Organizing Documentation
+
+1. **Organize documents for rapid orientation**
+
+   - All context for understanding a project should be efficiently discoverable.
+   - Documents should reference other documents whenever relevant.
+   - A reader should be able to navigate from an obvious root document to all other
+     documents relevant to a given need by following references.
+
+2. **Use self-evident filenames and concise references**
+
+   - For file naming, always follow existing project conventions.
+     If conventions are unclear, use the conventions here.
+   - Repos and key file folders should have a concise `README.md` as a root document
+     that points to other documents.
+   - Within the top-level repo or within key folders, a `docs/` folder should be added
+     with other key docs and referenced in the `README.md`.
+   - Whenever possible give documents brief but unique names.
+   - Include a hint of the *topic* as well as *purpose*, such as
+     `python-structural-quality-guidelines.md`.
+   - Documents that are likely to become less relevant over time should have *dates or
+     versions* as well, such as `plan-2026-04-28-browser-realtime-streaming.md`.
+   - Unless other rules forbid it, references within documents should be *maximally
+     concise* so they are easy to maintain:
+     - For URLs, use simple link text with the URL in Markdown format.
+     - For other documents, use the simplest unique reference, such as a title or
+       filename, that makes the document easy to find.
+     - Do not include unnecessary metadata, local paths, or other details readily
+       determined from a search.
+
+3. **Divide documents by ownership, audience, and cadence**
+
+   - Documents owned and maintained by different people or teams should usually be
+     distinct.
+   - Documents meant for different audiences (such as internal versus external, or team
+     docs versus sensitive docs) should be kept separate.
+   - Documents updated on different cadences (such as ad hoc, every sprint, or yearly)
+     should be distinct.
+   - Documents with the same ownership, audience, and update cadence should be
+     consolidated.
+
+4. **Organize documents for maintainability**
+
+   - Reference or include relevant guidelines for updates.
+   - Documents should be organized in a way that is compatible with typical update
+     processes.
+
+## Structuring Documents
+
+1. **Explain motivations and background**
+
+   - Assume readers have low context.
+   - Highest-level documents or introductory sections should explain *why* as well as
+     *what*.
+   - A key part of the *why* is explaining why some approaches are taken and their
+     benefits compared to alternate approaches or alternate tools.
+   - Cite external sources for all content that is best covered externally.
+
+2. **Give context gradually and efficiently**
+
+   - Documents should be as brief as possible while still preserving all relevant
+     detail.
+   - Add detail incrementally: start with summaries, link to deeper docs.
+
+3. **Keep details close to where they apply**
+
+   - For example, docstrings in code or descriptions within YAML are preferred to
+     separate documentation when the content directly relates to code or content in
+     those files.
+
+4. **Avoid duplication**
+
+   - Do *not* repeat content in higher-level docs if the details are in referenced
+     lower-level docs.
+   - For example, if `docs/design.md` is an overview of the design, do not repeat the
+     design in `README.md`; reference it instead.
+
+5. **Describe the present state, not what it replaced**
+
+   - By default, write as if the current work or referenced system or design always
+     existed. Most readers need to understand what *is*, not what *was*; replacement
+     history pollutes their context with deprecated concepts they would otherwise never
+     have to learn. When version control like Git is used, its history is the
+     authoritative record of what was removed.
+   - Agents are especially prone to retaining history notations that are no longer
+     relevant ( “this design was changed because of X,” “this function was previously
+     named X”, “removed Z”). When in doubt, cut it.
+   - Exceptions are allowed when the document’s purpose *includes* history: migration
+     guides, postmortems, deprecation notices, decision records, changelogs,
+     governance/versioning sections in standards and schemas, and one-line pointers when
+     a future reader needs to find a predecessor (for example, “see commit `abc123` for
+     the prior shape”). The test is whether the history serves the reader’s task or
+     simply records the author’s path.
+
+## Writing Style
+
+Stylistically, emphasize **clarity**, **depth**, **rigor**, and **warmth**.
+
+1. **Be clear and concise**
+
+   - Use direct and simple language.
+   - Eliminate unnecessary or extraneous words.
+   - Avoid obvious statements.
+   - Remove duplication where a document says the same thing in different places.
+   - If removing a sentence loses no information about the subject, cut it.
+
+2. **Be detailed and specific**
+
+   - Use data or facts instead of generalizations or adjectives.
+   - Avoid vagueness or generalities.
+   - Use concrete examples.
+   - Cite sources whenever possible.
+
+3. **Be rigorous and logical**
+
+   - Use structure, such as headings, subheadings, and lists, effectively.
+   - Keep structure logical and consistent.
+   - Make headings specific; cleave to the true contours of the subject matter.
+
+4. **Be engaging and warm**
+
+   - Be friendly in tone, avoiding unnecessary formality unless required by the
+     situation (such as in legal documents).
+   - Be gracious in acknowledging previous work, even if correcting it.
+   - Avoid unnecessary coldness, blame, condescension, or opacity when writing for
+     humans. For agent-facing documents, the equivalent is directness, explicit context,
+     and absence of performative fluff.
+     `practical-prose-rubric.md` cites this as a Tone / Reader Respect contextual
+     modifier rather than a scored dimension.
+
+## Effective Communication
+
+1. **Respect the reader’s intelligence**
+
+   - Write for a reader that is *100% intelligent and 100% ignorant*. This respects the
+     reader yet provides enough context.
+   - Either explain concepts fully and from first principles or point them to where they
+     can learn the concept.
+   - Never dumb things down, be vague, or skip important technicalities or details.
+
+2. **Calibrate confidence**
+
+   - Never make a confident statement without citations or reasoning that justify the
+     confidence.
+   - Judgments are allowed but must be calibrated, considering evidence for and against.
+   - Do *not* aim to be agreeable; aim to be accurate when certain and explicit about
+     uncertainties.
+   - Do *not* make sweeping claims or use extravagant language.
+     Avoid words like “incontrovertibly,” “emphatically,” “definitively,”
+     “unequivocally,” “massive,” “monumental,” “profound,” “transformational,”
+     “seismic,” “paradigm-shifting,” “will revolutionize,” “structurally outmaneuvered,”
+     “successfully executing,” or “crushing it.”
+
+3. **Cut pompousness, meta-commentary, and unnecessary formality**
+
+   - Avoid “talking about talking,” such as narrating what a doc covers or instructing
+     readers on how to read a document.
+     Exception: standards, rubrics, runbooks, and other process documents may include
+     structural commentary (how dimensions map to rules, how to score, when to apply a
+     pass) when that commentary is what the document is *for*.
+   - Eliminate common but unnecessary phrases, such as “due to the fact” or “at this
+     point in time.” Avoid adverbs and general adjectives, such as “quickly respond” or
+     “very good.”
+   - Avoid pedantry, such as calling documents “canonical,” or giving justifications for
+     word choices. Jargon like “load-bearing” is acceptable when the audience uses it and
+     the term is genuinely descriptive (for example, a sentence-craft discussion citing
+     Gopen and Swan’s notion of *load-bearing constraints on sentence structure*); avoid
+     it as a filler intensifier in ordinary prose.
+   - Cut acronyms and jargon unless they serve a clear purpose.
+   - When technical terms or jargon are used, define them or reference their definition.
+
+## Formatting
+
+> Block quotes like this should be used for meta-instructions, quotes, and epigraphs.
+
+- **Boldface:** Use boldface for defining **key words** or concepts.
+- **Italics:** Use italics for *general emphasis*.
+- **Itemized lists:** Use bulleted lists whenever it aids with clarity.
+  Do not include full stops on each item for short lists and sentence fragments.
+  For lists with multiple sentences on each bullet (like this one), consistently use
+  full stops on all items.
+- **Inline headings:** Inline headings, where the heading is on the same line as a
+  paragraph of text, should be formatted like this, using a boldfaced colon.
+  Use this format consistently for inline headings within itemized lists.
+- **Em dashes:** Use em dashes *only* when they are the best punctuation for the
+  sentence. Prefer full stops, commas, colons, or semicolons as appropriate.
+  When you do use em dashes—like this—follow American style, without spaces around the
+  em dash.
+- **Conjunctions:** Write “and” rather than `+` or `&` in prose, list separators, and
+  cross-references. Reserve `+` and `&` for code, identifiers, and proper names where
+  they are part of the canonical form (for example, “Strunk & White”).
+- **Section headings:** Use Title Case (Chicago Manual of Style rules) for H1 `#` and H2
+  `##` headings (as in this document).
+  For H3 `###` and H4 `####`, title case is optional but should be applied consistently.
+
+### Auto-Formatting and Emojis
+
+> These two conventions are tbd extensions not yet in upstream practical-prose; see the
+> PR addendum proposing them upstream.
+
+- **Auto-formatting:** Always use auto-formatting on every file type that supports it.
+  Defer to the language- or format-specific rules for exact style.
+- **Emojis:** Do not use emojis gratuitously — only when they add clarity through a
+  consistent semantic vocabulary.
+  Use ✅ and ❌ for success and failure (or ✔︎ and ✘ if the codebase already uses them),
+  and ⚠️ and ‼️ for user-facing warnings and errors (or ∆ and ‼︎ to match an existing
+  codebase). You may use 📈 for reports and quantitative summaries, ⏰ for timings and
+  scheduling, and 🧪 for tests and experiments.
+  Apply whatever set you choose consistently.
+  Do not put emojis in code comments, where they add distraction without systematic
+  meaning.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/convex-limits-best-practices.md

@@ -2215,3 +2215,7 @@ constraints:
 | **10-50 KB** | Separate document or file storage | Use detail tables for on-demand fetch |
 | **50-900 KB** | **Must** use detail table or file storage | Approaching 1 MiB document limit |
 | **>900 KB** | **Must** use file storage with compression | Brotli compression for HTML/text (3:1 ratio) |
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/convex-rules.md

@@ -941,3 +941,7 @@ const mockAgentId = '12345;agents' as Id<'agents'>;  // OK - looks like real Con
    entirely
 
 3. **Test IDs should follow Convex format** - if test ids `'12345;tableName'` pattern
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/electron-app-development-patterns.md

@@ -835,3 +835,7 @@ Avoid `unsafe-eval` and `unsafe-inline`.
 
 - [Launchpad #1944468: Electron applications all crash upon launch](https://bugs.launchpad.net/bugs/1944468)
   — Ubuntu-specific Electron issues
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/error-handling-rules.md

@@ -561,3 +561,7 @@ grep -rn -A2 "} catch {" --include="*.ts" | grep -B1 "throw new"
 **Problematic patterns**:
 - `throw new CLIError('Failed to do X')` - Loses WHY it failed
 - `throw new Error('Operation failed')` - Generic message hides root cause
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-coding-rules.md

@@ -35,3 +35,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
   // Usage:
   const tradeCount = Math.min(trades.length, EXECUTION_STATS_LIMITS.maxTradeCount);
   ```
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-comment-rules.md

@@ -94,3 +94,7 @@ These are language-agnostic rules on comments:
   and at the top of files.
 
 - See language-specific comment rules for more details.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-eng-assistant-rules.md

@@ -53,3 +53,7 @@ Therefore:
   That is useless generalization.
   Instead, specifically say what you’ve done, e.g., “I’ve added types, including
   generics, to all the methods in `Foo` and fixed all linter errors.”
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-tdd-guidelines.md

@@ -145,3 +145,7 @@ Tests in the project are broken down into three types:
    Are not run on every commit as they can have costs or side effects or be slow.
    Requires all API keys.
    File names end with e2e.test.ts
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/general-testing-rules.md

@@ -25,3 +25,7 @@ author: Joshua Levy (github.com/jlevy) with LLM assistance
 
 - Test edge cases and boundaries: Include tests for empty inputs, nulls, maximums,
   minimums, and error conditions—not just happy paths.
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->

package/dist/docs/guidelines/golden-testing-guidelines.md

@@ -812,3 +812,7 @@ Golden session testing works well alongside other testing strategies:
 - ScalaTest Matchers: https://www.scalatest.org/user_guide/using_matchers
 
 - Concordion (Java): https://concordion.org/
+
+<!-- This document follows common-doc-guidelines.md.
+See github.com/jlevy/practical-prose and review guidelines before editing.
+-->