@erclx/canon 5.23.0 → 5.25.0

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "canon",
   "description": "Runs your agent's work and keeps its code good, on one setup for every repo.",
-  "version": "5.23.0",
+  "version": "5.25.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

package/claude/skills/backlog-triage/REQUIREMENT.md

@@ -9,12 +9,12 @@ description: Why the backlog gets a measured verdict per row with a lean toward
 
 Without this skill, the backlog only grows. `task-board` declines or archives one named task, and nothing reads the backlog as a whole, so a row stays until somebody happens to remember it and decides by hand. The orchestrator's backlog re-test only clears a row upward onto the board, so no sweep ever takes one off. A backlog past fifty rows had no surface that could say which of them still mattered.
 
-Three failure modes cost more than the rest. A pass that judges a row by what its task file says rather than by the tree keeps every row, since a task file reads as live the day it was written and every day after. A pass that applies its own verdicts decides rows on silence, which ships a decline nobody approved on a board with no history to restore it from. And a keep that carries no measurement is the default nobody argues with, so a triage without a lean toward decline ends with the same backlog it started with.
+Four failure modes cost more than the rest. A pass that judges a row by what its task file says rather than by the tree keeps every row, since a task file reads as live the day it was written and every day after. A pass that applies its own verdicts decides rows on silence, which ships a decline nobody approved on a board with no history to restore it from. A keep that carries no measurement is the default nobody argues with, so a triage without a lean toward decline ends with the same backlog it started with. And a keep that measures only that the defect still exists keeps nearly everything, since a row filed against the tree almost always still reproduces. One pass suggested keeping 24 of 27 rows that way, where the operator kept 6 and promoted 1.
 
 ## Must
 
 - Measure every row against the tree and the log during the pass, carrying a count, a path, or a commit rather than the task file's own claim
-- Suggest decline for any row this pass cannot argue for, putting the burden of proof on keep and promote
+- Suggest keep or promote only for a row that names a cost, being a wrong result the pass observed or a case someone hit, including a user asking for a feature or working around its absence, or a reach, being a defect on a path the project ships that changes what its users or targets receive, hit or not, and suggest decline for a row whose defect merely still exists
 - Name the commit or pull request per outcome position before suggesting archive
 - File into an ordinary intake folder, so the intake list and answer verbs read and write it unchanged
 - Carry the verdict in the suggestion line and the task stem in the item heading, rather than in new fields

package/claude/skills/backlog-triage/SKILL.md

@@ -45,18 +45,31 @@ A row whose link resolves to no file gets an item anyway, carrying `decline` and
 
 Measure every claim the task makes against the tree and `git log` during this pass. Grep for the construct its defect names and count the sites, check whether each open outcome's behavior exists, and search the log for a commit or pull request that shipped it under another task. Never carry a figure from the task file forward as current, since the task states what was true when it was filed.
 
+Then gather the evidence Step 5 reads for each row that reproduces. Check whether its origin line or `## Findings` names an issue, a run, or a person it bit. Search the log for a commit or pull request that worked around it rather than fixing it. For a defect in something the project ships, whether a route or a page its users call or a rule, a seed, a scaffold, or a verb other repositories copy or run, name the shipped path it sits on. Record each one that is absent as absent rather than inferring it.
+
 Name the commit the pass measured against in the overview body.
 
 ### Step 5: pick the verdict
 
-Keep and promote carry the burden of proof. A row nobody can argue for from this pass's measurement is declined.
+Keep and promote carry the burden of proof, and a defect that still exists does not meet it. A row filed against the tree nearly always still reproduces, so a test of reproduction alone keeps almost every row.
+
+A row earns keep or promote only by naming one of two things from the evidence Step 4 gathered:
+
+- **A cost**: the defect gives a wrong result that this pass observed, by running the verb that carries it or reading the committed output that shows it, or that the row's evidence shows an issue, a run, or a person hit, a workaround commit included. A hit counts only while the pass does not measure it as fixed or as no longer recurring.
+- **A reach**: the defect sits on a path the project ships, and everyone who reaches that path, whether a user calling it or a target copying or running it, receives the defect as a wrong instruction, a broken, failing, or unbounded behavior, or a wrong output. Reach needs no hit, since the path's users meet the defect whether or not anyone reported it.
+
+A plausible cost names nothing. A row arguing what could go wrong off a shipped path, with no observed output and no hit, is declined however likely the argument sounds. Three things are not a reach: a missing feature on a shipped surface, a defect that changes nothing a user or a target receives, such as dead code on a shipped path, and a defect that shows only in this repository's own config, workflows, scripts, or fixtures.
+
+A missing protection is a defect, not a missing feature. Read a row as a missing protection when the shipped path lacks a bound, a check, or a guard on what it does at run time, such as a limit, a timeout, or input validation, so that the path can fail, run unbounded, or return a wrong output for every user who reaches it. That is a reach. A missing feature leaves the path working as it does today and adds a capability, a document kind, or a sentence of guidance, and it is not a reach.
+
+A missing feature can still earn keep or promote through the cost arm. A user asking for it in an issue or a report, or working around its absence on their side, is a case someone hit, so that row is never declined for being a feature. A feature nobody asked for is declined. A passing mention is not a request, and neither is one the project's own planning records filed with no user behind it.
 
-- **keep**: the defect or gap reproduces this pass, stated with a count or a path.
-- **promote**: it reproduces, and the thing it was waiting on has cleared, naming what cleared it.
+- **keep**: the defect reproduces this pass, stated with a count or a path, and the row names a cost or a reach, stated with the observation, the hit, or the shipped path.
+- **promote**: it qualifies for keep, and the thing it was waiting on has cleared, naming what cleared it.
 - **archive**: every open outcome is measured shipped, naming the commit or pull request per outcome position.
-- **decline**: anything else, including a defect the tree no longer holds, work superseded by another task, and a row whose argument rests only on its original filing.
+- **decline**: anything else, including a defect that reproduces but names no cost and no reach, a defect the tree no longer holds, work superseded by another task, and a row whose argument rests only on its original filing.
 
-Age is evidence in neither direction. A row untouched for months is not more declinable than one filed yesterday, and a row filed yesterday is not more worth keeping.
+Age is evidence in neither direction. A row untouched for months is not more declinable than one filed yesterday, and a row filed yesterday is not more worth keeping. An old hit is read the same way as a new one, by whether the pass measures it as still able to recur.
 
 ### Step 6: write the items
 
@@ -64,7 +77,7 @@ Write one item per row in the intake item format, one cluster file per domain th
 
 - `Problem:` states what this pass measured, with the count, path, or commit behind it
 - `Fix:` states what applying the verdict does to the board
-- `Worth it:` carries the verdict's reason in one clause
+- `Worth it:` names the cost or the reach the verdict rests on in one clause, or says the row names neither. A `yes` or a `later` carries no verdict on its own, so a decline can follow either word
 - `Open:` reads `decline, archive, keep, or promote?` on every item
 - `Suggested:` opens with exactly one of the four verdict tokens, then the reason. An archive suggestion lists every outcome position it closes, as `archive 1, 3: shipped in #NNN`
 - `Overlaps:` names a live board task that already carries the work, where one does

package/claude/skills/canon-operator/REQUIREMENT.md

@@ -27,6 +27,7 @@ The last failure is a section no route reaches. `## Route` maps an intent or a d
 - Run the CLI non-interactively and report the command run, what changed, and the full path of anything written
 - Read the overwrite contract from the body before any install or sync, and name each surface it lists as overwritten before running one
 - Read the reverse walk beside the forward sections, so a folder the toolkit stopped shipping reaches the user
+- Read `unmovedSurfaces` from the report itself, since the drift status ignores it by design, and name `canon migrate surface-roots` without running either form
 - Name an unmigrated domain's root and install path for the user to move themselves, since no skill covers the move
 - Route a measurement intent to the audit offers from the route table itself, rather than leaving the section reachable only by reading past the table
 - Rank a lifecycle row against the audit offers where the route table itself states it, so a session acting on the lifecycle row reads the ranking without opening the section being ranked

package/claude/skills/canon-operator/SKILL.md

@@ -22,10 +22,11 @@ Load a domain doc with `canon docs <topic>` only when the intent touches that do
 
 Run `canon sync --check . --json` before routing. It reports what a target is behind on across every surface, so the intent comes from the project state rather than from the user having to know it already. Skip only when the user named a single operation to run.
 
-Read seven fields off the report and carry each to `## Route`:
+Read eight fields off the report and carry each to `## Route`:
 
 - `unmigrated`: a domain sitting at the root layout with nothing under `.claude/`. The most urgent finding, because that domain reports no drift of its own while being entirely behind
 - `superseded`: a file a newer seed folder replaced. No command moves it, since the content is the project's own, so this routes to `canon:target-check` for the full per-domain reading rather than ending at the report
+- `unmovedSurfaces`: a surface held only at its `.claude/` spelling, each entry carrying `rel` and `movesTo`. Every other field reads clean for such a target, and the report's drift status ignores it by design, so read the array itself rather than an exit status
 - `seeds`: entries are `matching`, `stale`, `drifted`, or `missing`. Anything but `matching` needs the seed handoff
 - `domains[].entries`: per-file `stale`, `customized`, `stranded`, and `orphaned` as before, plus `retired` for a rule the toolkit no longer ships, which the next sync deletes
 - `reverse`: what the target holds that no live catalog claims. `unclaimed` lists folders at roots the toolkit stopped shipping, each with an `attribution` of `dropped`, `unattributed`, or `project`. Act on the first two and leave `project` alone, which history proved the project owns
@@ -34,6 +35,8 @@ Read seven fields off the report and carry each to `## Route`:
 
 State what the report found in one line per finding before acting on any of it.
 
+An `unmovedSurfaces` key the report does not carry at all is likewise a CLI predating the field rather than a target with nothing to move. Say the section was unread and name the installed CLI version as the cause.
+
 A `reverse` key the report does not carry at all is a CLI predating the field rather than a target with nothing unclaimed. Say the walk did not run and name the CLI version as the cause. Reading the absent key as an empty answer reports a clean target to a project nobody has looked at, and answering it from a filesystem walk of your own is worse, since that reaches a verdict the attribution the field carries is the only thing entitled to make.
 
 ## Route
@@ -44,6 +47,7 @@ The two can name different rows, and a reply answers both rather than picking on
 
 - A domain in `unmigrated`: name it, the root path, and the install path. No command moves it, so the user runs the relocation themselves
 - Anything in `superseded`: name which files and what replaced them, then hand off to `canon:target-check`, which reports and never moves or deletes the file
+- Anything in `unmovedSurfaces`: name `canon migrate surface-roots`, which only reports its plan until `--write` is passed, with each entry's `rel` and `movesTo`, and run neither form, since the move rewrites tracked paths
 - A folder in `unclaimed`: name it and the attribution it carries. No command moves it and the content may be the project's own, so the decision is the user's
 
 - First-time scaffold of a fresh project: hand off to `target-setup`

package/claude/skills/canvas/REQUIREMENT.md

@@ -0,0 +1,49 @@
+---
+name: canvas
+description: Scope boundary for driving the local design canvas, and the line between a drafted frame and the design it feeds
+---
+
+# Canvas requirement
+
+## Gap
+
+Without this skill, a session asked to draw on the canvas writes frames into a folder nothing is serving, so the operator sees nothing and the session reports the frames as drawn. When the server is running, the session trusts a passing capture as proof the canvas works. Captures go through the frame route, so a shell that answers its address with an empty page passes every capture while the operator looks at a blank tab.
+
+It reads "this one" from the conversation rather than from the operator's selection, and when it does read the selection it acts on an element index recorded against an earlier version of the file, which lands the edit on a different element. It restyles through a class while the operator's inspector edit sits on the element as inline style, so the change never shows and the session reports it as made.
+
+It writes frames from a linked worktree with the file tools, which refuse the main-root path and offer a worktree copy the canvas never serves. It captures after every edit, filling session scratch with images of drafts nobody picked.
+
+When the operator picks a frame, the session leaves the decision on the canvas and cites the frame as the design, so the project's design document never learns it and a gitignored file becomes the only record.
+
+## Must
+
+- Start the canvas when it is not serving, before writing any frame
+- Confirm the live shell loads at the address the server reported, rather than trusting a capture
+- Read the address off the server's record rather than composing one
+- Make pages and frames through the verbs, so a box and the operator's drags share one locked writer
+- Name the main-root write route for a frame written from a linked worktree
+- Read the operator's selection when they point at something, and treat a stale element pick as unknown
+- Read a frame's inline styles before restyling it, and say which operator edits were kept and which dropped
+- Capture once per finished frame or page rather than after every edit
+- Carry a picked direction into the project's design document or wireframes
+
+## Must not
+
+- Present the canvas as the project's source of truth for design
+- Promise the canvas survives a lost checkout
+- Name any third-party design tool, or the canvas's predecessor surface
+- Be invoked only by the author typing its name. A request to draw, select, or capture on the canvas should reach it by description, and a run where it never fires on such a request is a defect in the description
+
+## Guards
+
+- No `canon` on PATH, or an installed CLI with no canvas command, stop rather than writing files nothing serves
+- A server that refuses to start, or a shell that answers blank, stop and report it rather than drawing into it
+
+## Out of scope
+
+- What the canvas verbs do internally, which is the CLI's own contract
+- The content format a frame and a layout take, which the canvas standard fixes
+- Drafting candidates for a taste decision and taking the pick, which `draft-and-pick` runs on its own render path
+- Tracing reference images into design values, which is `sketch-design`
+- Writing the design document itself, which is `design-extract`
+- Backing up the canvas folder off one disk

package/claude/skills/canvas/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: canvas
+description: Drives the local design canvas, where pages hold HTML frames the operator sees, drags, selects, and edits in the browser. Starts the canvas when it is not running, confirms the live shell loads, makes pages and frames, edits a frame through its file, reads what the operator selected or restyled, captures finished frames, and carries a picked direction into the project's design document. Use when asked to "open the canvas", "put this on the canvas", "draw a frame for X", "change the one I selected", "what did I pick", "capture this frame", or "move that frame on the canvas". Do NOT use to trace reference images into design values, which is `sketch-design`, or to write the design document from code, which is `design-extract`.
+---
+
+# Canvas
+
+Drive the canvas the operator is looking at. A page is a folder of HTML frames and a frame is one file, so a session draws by writing files and the operator sees each write land in the browser. The content format is fixed by `${CLAUDE_SKILL_DIR}/../../standards/canvas.md`. Read it before writing a frame.
+
+Every verb below is `canon canvas`. Run `canon docs canvas` for the full verb reference, its records, and its refusals.
+
+## Guards
+
+- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
+- If `canon canvas --help` reports no such command, stop: `❌ The installed canon carries no canvas command. Update the CLI and re-run.`
+- Write no frame before the canvas is serving and the shell has loaded. A frame nobody can see is a draft reported as delivered.
+- Never present a frame as the project's design. The canvas is a drafting surface and the project's design document or wireframes hold what was decided.
+- Never promise the canvas survives a lost checkout. Its folder is gitignored and nothing backs it up.
+
+## Step 1: start the canvas and confirm the shell
+
+Read the pages first, which also proves the verb resolves:
+
+```bash
+canon canvas list --json
+```
+
+The record carries `content`, the folder every page lives in. It sits at the main worktree root whichever worktree the session runs in, so write through that path rather than one composed from the current directory.
+
+Start the server in the background unless the operator named an address that already answers, since it runs until interrupted. No verb reports a running server, and a second one is harmless, since it walks to the next free port and serves the same folder:
+
+```bash
+canon canvas serve --json
+```
+
+Read `url` off the record rather than composing one, since the server walks past a port already in use. Report the refusal and its `reason` when `ok` is false, and stop there.
+
+Then fetch the printed address and check the shell itself, not a capture:
+
+- The body is non-empty and carries a `<script` tag. An empty `200` means the shell failed to build, usually a dependency missing from the canvas tool's install, and every capture still passes because captures go through the frame route alone. Report it as a blank shell and stop.
+- `<url>/api/pages` answers with JSON listing the pages.
+
+Hand the operator the address as a markdown link carrying the URL as its text and its target.
+
+## Step 2: make pages and frames
+
+- Add a page for each decision being drafted: `canon canvas page add <page> --json`.
+- Add each frame through the verb, which writes the starting file and its box in one locked step: `canon canvas frame add <page> <frame> --width <px> --height <px> --json`. Give the width the frame should render at, since a capture and the canvas both render at it.
+- Lay frames out with `canon canvas frame move <page> <frame> --x <px> --y <px> --json` rather than writing `layout.json` by hand, since the operator's drags write the same file under a lock.
+- Name pages and frames for what they hold, such as `pricing` and `pricing-dense`, so the operator can say which one by name.
+
+## Step 3: edit a frame through its file
+
+Write the frame's whole document to the `path` the add verb reported. The open canvas reloads the frame when its file changes.
+
+- From a linked worktree, `Edit` and `Write` refuse a main-root path. Write the whole file through one plain `Bash` heredoc instead, the route `session-worktree` states for a main-root write, and never take the redirect to a worktree copy.
+- Change one property of one element with `canon canvas edit <page>/<frame> --element <index> --set <property>=<value> --json` when the set it accepts covers the change, since it leaves every other byte as it was.
+- Use the project's custom properties for every value the token stylesheet defines. The record from `serve` names the token source under `tokens`, and a `none` source means frames render unstyled, so say so rather than inventing values to cover it.
+
+## Step 4: read what the operator pointed at
+
+Read the selection when the operator says "this one", "the selected frame", or "that button":
+
+```bash
+canon canvas selection --json
+```
+
+- `selection: null` means nothing is selected or the selected frame is gone. Ask which one rather than guessing.
+- An `element` carrying `stale: true` was picked against an earlier version of the file, so its `index` may now land on a different element. Treat the pick as unknown and ask the operator to pick again, rather than acting on the index or matching its `tag` and `text` by eye.
+- A fresh `element` gives the `index` that `canvas edit` takes.
+
+## Step 5: respect the operator's inspector edits
+
+The operator restyles elements from the inspector, and each edit lands as inline `style` on the element. Inline style beats a class, so a class change made afterwards does not show.
+
+- Read the frame's inline `style` attributes before restyling anything in it.
+- Keep an inline property the operator set unless the change replaces it, and drop it, through `canvas edit` with an empty value or by rewriting the file, when it does.
+- Say which operator edits were kept and which were dropped.
+
+## Step 6: capture finished work
+
+- Capture a frame once it is finished: `canon canvas capture <page>/<frame> --json`. Each PNG is the frame's whole document, so its height follows the content rather than the box.
+- Capture a whole page once its frames are finished: `canon canvas capture <page> --composite --json`. The image shows each frame clipped to its box at its layout position.
+- Capture once per finished frame or page, not after every edit. The live canvas is the working view, and a capture is the record handed on.
+- Read each `path` off the record rather than composing one.
+- A capture refused because a font is not installed names the family it read off the frame's `html` element. Set that element's `font-family` to a family the machine has and capture again, rather than reporting the frame as captured.
+
+## Step 7: carry a picked direction back
+
+When the operator picks a frame, the decision leaves the canvas.
+
+- Carry visual values, being color, type, spacing, and radius, into the project's design document, through the skill that owns it. Carry structure and layout into the project's wireframes.
+- Name the frame the decision came from in the reply, and leave the frame on the canvas until the operator clears it.
+- Never cite a frame path from a tracked file. The folder is gitignored, so the citation resolves on this machine alone.
+
+## Output
+
+```plaintext
+✅ Canvas: <url the serve verb reported>
+Page:     <page>, <n> frames
+Selected: <page>/<frame>, element <index>, or none, or stale
+Capture:  <path of each capture written>
+Carried:  <the design document or wireframe the pick went to, or not yet>
+```
+
+Write the canvas line's URL as a markdown link. Omit the capture line when nothing was captured and the carried line when no direction was picked. Emit every path from the project root.

package/claude/skills/design-extract/REQUIREMENT.md

@@ -39,4 +39,4 @@ The greenfield case is the one that fails quietly. A project with no UI code sti
 - Mutating an existing design system, which is a direct edit of the file rather than a skill
 - Producing the HTML and CSS preview, which `canon design render` owns
 - Auditing the implemented UI against the tokens, which `ux-audit` owns
-- Architecture and flow diagrams, which `draft-diagram` owns
+- Architecture and flow diagrams, which `draft-figure` owns

package/claude/skills/draft-doc/REQUIREMENT.md

@@ -19,6 +19,7 @@ The same procedure ran as five skills, one per kind, each restating the read, th
 - Check the catalog by exact name and by title and description, since a subject can be covered under a name the request does not guess
 - Confirm the resolved path, the kind's detections, and the full content with the user before writing, since placement and detection are judgment calls with no diff to preview them against
 - Regenerate the catalog of the folder the document landed in, where the kind keeps one, so the next run's collision check sees it
+- Draft a README from the template for every detected project type and combine them, never the closest one, since a project that is a CLI and a plugin owes its reader both
 - Carry each kind's own musts in its reference: the root check for context and wireframes, tier detection and the two modes for wireframes, both placement tests and a fetched source for the wiki, and project detection and rendered-value badges for the readme
 
 ## Must not
@@ -41,5 +42,5 @@ The same procedure ran as five skills, one per kind, each restating the read, th
 - Rewriting or syncing an existing `docs/` page or an authored README against a diff: `docs-sync`
 - Refreshing an existing context entry or wireframe, or stubbing a surface a diff touched: `context-fold`
 - Drafting a standard or a governance rule: `create-standard`, `create-rule`
-- Drawing a figure or a diagram for a document: `draft-figure`, `draft-diagram`
+- Drawing a figure or a diagram for a document: `draft-figure`
 - Voice, rhythm, punctuation, and formatting in the drafted document: the `write-human` skill and the markdown standard

package/claude/skills/draft-doc/references/readme/agent-facing.md

@@ -0,0 +1,59 @@
+![<Project name> logo](<committed logo path>)
+
+# <Project name>
+
+[![<build status>](<badge image URL>)](<run history URL>)
+[![<license>](<badge image URL>)](<license URL>)
+
+<One-line claim taken from the repository description.>
+
+<Two or three sentences expanding the claim: the conventions or tooling an agent working here picks up, and what a session gains from them.>
+
+## Installation
+
+### Requirements
+
+- <Agent tool and minimum version>
+- <Runtime the listing command needs>
+
+### Set up
+
+```bash
+<clone command>
+<setup command, when a session needs one>
+```
+
+## Usage
+
+### What an agent loads first
+
+`<file an agent reads at session start>` carries <what that file holds>. It points at <the files it imports or links>.
+
+### List what the project exposes
+
+```bash
+<command that lists skills, rules, or commands>
+```
+
+### Where things live
+
+| Path       | Holds        |
+| ---------- | ------------ |
+| `<folder>` | <What it is> |
+
+## Documentation
+
+<Link to the full conventions reference.>
+
+## Support
+
+- <Where to open an issue>
+- <Where to ask a question>
+
+## Contributing
+
+See the [contributing guidelines](<CONTRIBUTING.md path>).
+
+## License
+
+[<License name>](<LICENSE path>)

package/claude/skills/draft-doc/references/readme/application.md

@@ -0,0 +1,66 @@
+![<Project name> logo](<committed logo path>)
+
+# <Project name>
+
+[![<build status>](<badge image URL>)](<run history URL>)
+[![<license>](<badge image URL>)](<license URL>)
+
+<One-line claim taken from the manifest or repository description.>
+
+[<Live site name>](<live URL>)
+
+![<What the screenshot depicts>](<committed image path>)
+
+<Two or three sentences expanding the claim: who the product is for, then what they do with it.>
+
+## Features
+
+- <Benefit the user gets>
+- <Benefit the user gets>
+
+## Installation
+
+### Requirements
+
+- <Runtime and version>
+- <Service the app depends on>
+
+### Set up
+
+```bash
+<clone command>
+<dependency install command>
+```
+
+## Usage
+
+### Run locally
+
+```bash
+<dev server command>
+```
+
+<Address the app serves on.>
+
+### Configuration
+
+| Variable | Purpose            | Default     |
+| -------- | ------------------ | ----------- |
+| `<NAME>` | <What it controls> | `<default>` |
+
+### Deploy
+
+<Where the app deploys and the command or workflow that does it.>
+
+## Support
+
+- <Where to open an issue>
+- <Where to ask a question>
+
+## Contributing
+
+See the [contributing guidelines](<CONTRIBUTING.md path>).
+
+## License
+
+[<License name>](<LICENSE path>)

package/claude/skills/draft-doc/references/readme/cli.md

@@ -0,0 +1,64 @@
+![<Project name> logo](<committed logo path>)
+
+# <Project name>
+
+[![<package version>](<badge image URL>)](<registry page URL>)
+[![<build status>](<badge image URL>)](<run history URL>)
+[![<license>](<badge image URL>)](<license URL>)
+
+<One-line claim taken from the manifest description.>
+
+<Two or three sentences expanding the claim: the task a reader repeats by hand, then what the command does about it.>
+
+## Features
+
+- <Benefit the reader gets>
+- <Benefit the reader gets>
+
+## Installation
+
+```bash
+<global install or one-shot run command>
+```
+
+<Runtime or platform requirement, when one exists.>
+
+## Usage
+
+### Run a command
+
+```bash
+<command> <argument>
+```
+
+### Flags
+
+```bash
+<command> --<flag> <value>
+<command> --<flag>
+```
+
+| Flag       | Effect         |
+| ---------- | -------------- |
+| `--<flag>` | <What it does> |
+
+### Exit codes
+
+<What each non-zero exit means, when a script depends on it.>
+
+## Documentation
+
+<Link to the full command reference.>
+
+## Support
+
+- <Where to open an issue>
+- <Where to ask a question>
+
+## Contributing
+
+See the [contributing guidelines](<CONTRIBUTING.md path>).
+
+## License
+
+[<License name>](<LICENSE path>)

package/claude/skills/draft-doc/references/readme/library.md

@@ -0,0 +1,57 @@
+![<Project name> logo](<committed logo path>)
+
+# <Project name>
+
+[![<package version>](<badge image URL>)](<registry page URL>)
+[![<build status>](<badge image URL>)](<run history URL>)
+[![<license>](<badge image URL>)](<license URL>)
+
+<One-line claim taken from the manifest description.>
+
+[<Live site name>](<live URL>)
+
+![<What the screenshot depicts>](<committed image path>)
+
+<Two or three sentences expanding the claim: the problem a reader recognizes, then what the library does about it.>
+
+## Features
+
+- <Benefit the reader gets>
+- <Benefit the reader gets>
+
+## Installation
+
+```bash
+<install command for the package manager the project uses>
+```
+
+## Usage
+
+### Quickstart
+
+```<language>
+<Import and one call that shows the core behavior>
+```
+
+### <Second common task>
+
+```<language>
+<Snippet for the task>
+```
+
+## Documentation
+
+<Link to the full API reference.>
+
+## Support
+
+- <Where to open an issue>
+- <Where to ask a question>
+
+## Contributing
+
+See the [contributing guidelines](<CONTRIBUTING.md path>).
+
+## License
+
+[<License name>](<LICENSE path>)

package/claude/skills/draft-doc/references/readme/plugin.md

@@ -0,0 +1,66 @@
+![<Project name> logo](<committed logo path>)
+
+# <Project name>
+
+[![<build status>](<badge image URL>)](<run history URL>)
+[![<license>](<badge image URL>)](<license URL>)
+
+<One-line claim taken from the plugin manifest description.>
+
+<Two or three sentences expanding the claim: the work a session repeats, then what the plugin adds to it.>
+
+## Features
+
+- <Skill, command, or hook and what it gives the user>
+- <Skill, command, or hook and what it gives the user>
+
+## Installation
+
+### <First channel name>
+
+```bash
+<install command for this channel>
+```
+
+### <Second channel name>
+
+```bash
+<install command for this channel>
+```
+
+### Update
+
+```bash
+<update command>
+```
+
+## Usage
+
+### Invoke a skill
+
+```text
+/<plugin name>:<skill name> <argument>
+```
+
+### What the plugin adds
+
+| Name     | Kind                      | Purpose        |
+| -------- | ------------------------- | -------------- |
+| `<name>` | <skill, command, or hook> | <What it does> |
+
+### Configuration
+
+<Setting the plugin reads and where the user sets it, when one exists.>
+
+## Support
+
+- <Where to open an issue>
+- <Where to ask a question>
+
+## Contributing
+
+See the [contributing guidelines](<CONTRIBUTING.md path>).
+
+## License
+
+[<License name>](<LICENSE path>)