@erclx/canon 5.33.0 → 5.35.0

package/README.md

@@ -65,7 +65,6 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | -------------- | ------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------- |
 | Plugin skills  | Skills that plan a feature, review a diff, sync the planning docs, and run the ship chain                                | Loaded live from the plugin, never copied                       |
 | Governance     | Coding and authoring rules that load into a Claude session when a matching path is edited                                | Installed per project by `canon gov install`, refreshed by sync |
-| Standards      | Authoring conventions for commits, branches, plans, tasks, and markdown                                                  | Opened by name, read by name with `canon standards <name>`      |
 | Tooling stacks | Golden configs, seeds, and a reference per framework                                                                     | Laid down by `canon init`, reconciled by `canon tooling sync`   |
 | Design system  | Ships a `DESIGN.md` token format, a skill that drafts one from an existing project or from scratch, and a render command | `canon design render`                                           |
 | Slides         | A folder of HTML slides per deck, drawn in the project's tokens and rebuilt as editable shapes                           | `canon slides render` writes PowerPoint                         |
@@ -74,7 +73,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 | Transcripts    | A YouTube transcript with metadata frontmatter                                                                           | `canon transcripts <url>` writes it into any repo               |
 | Sandbox        | Scenario scaffolds that provision an isolated project state for verifying each domain flow                               | `canon sandbox`                                                 |
 
-Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A standard stays here and is opened by name, so there is no copy in your repo to drift from this one.
+Those domains reach you in three shapes. A tooling stack lands as real files under version control, because a config is something your build reads and your project owns. A plugin skill and the references it carries are never copied, so there is no copy in your repo to drift from this one.
 
 Governance is the third shape. A rule with a path glob loads only when a matching path is edited, and a rule with none loads every session. Run `canon gov list` to see the glob beside each rule.
 
@@ -152,9 +151,9 @@ git init
 canon init
 ```
 
-`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/`. Each rule names the standard it answers to and reads it with `canon standards <name>`, so no corpus is copied into your project.
+`canon init` installs base tooling configs, Claude seeds, and governance rules in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the workflow and doc-authoring rules in `.claude/rules/`. Each rule names the skill it loads, so no corpus is copied into your project.
 
-Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
+Pass `--stack <name>` for a language stack such as `node` or `python`, or `--skip governance` to leave rules out. Run `canon tooling list --json` to see the catalog.
 
 For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target/projects.md).
 
@@ -164,7 +163,6 @@ Each domain carries an entry written for someone maintaining the toolkit rather
 
 - [Claude Code plugin](canon/context/claude-plugin/index.md)
 - [Governance rules](canon/context/governance/index.md)
-- [Standards](canon/context/standards/index.md)
 - [Tooling stacks](canon/context/tooling/index.md)
 - [Design system](canon/context/design/index.md)
 - [Slides](canon/context/features/slides.md)

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.33.0",
+  "version": "5.35.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -9,7 +9,7 @@ description: Why a session changing what a caller can see needs stated rules on
 
 Without this skill, a session changing a surface a caller depends on has nothing in front of it about what that caller can see or how a change lands without breaking it. It works for the one caller it opened, renames a field in place, returns whatever record it had in hand, and nothing in the toolkit answers before the change ships.
 
-The absence is measured across the shipped corpus. No folder under `claude/skills/` matches `api`, `interface`, or `contract`, and no file across `claude/`, `governance/`, and `standards/` carries `hyrum` or a form of `idempotent`. The only related lines are the two error bullets in the core code rule, which state that errors are structured and hide internals and say nothing about exposure, versioning, or retries.
+The absence is measured across the shipped corpus. No folder under `claude/skills/` matches `api`, `interface`, or `contract`, and no file across `claude/` and `governance/` carries `hyrum` or a form of `idempotent`. The only related lines are the two error bullets in the core code rule, which state that errors are structured and hide internals and say nothing about exposure, versioning, or retries.
 
 The one skill nearest the subject leaves the pointer open. `codebase-layout` excludes shaping "a module's interface and seams" in its description and names no skill to take it, so a session routed away from layout on that question lands nowhere.
 
@@ -19,7 +19,7 @@ The one skill nearest the subject leaves the pointer open. `codebase-layout` exc
 
 - State Hyrum's Law as design rules a session can act on: decide what is observable, and expose no storage type, internal identifier, ordering, or timing by accident
 - Tell the session to write the contract, being the signature, flags, output shape, or schema, before the body
-- State one error shape per surface with a stable code a caller can branch on, pointing at the core code rule for structured errors and hidden internals rather than restating it
+- State one error shape per surface with a stable code a caller can branch on, and own the hidden-internals clause in the body, since no project rule carries it for every code stack
 - State validation at the boundary, once, with the value trusted inside
 - State additive change as the default: new fields and flags optional, nothing renamed or removed in place, no change of meaning under an existing name, and the One-Version Rule for a caller that cannot pin
 - State the four idempotency rules: store and honor a caller's key, claim it in one atomic step under a unique constraint, fail loudly on a reused key with a different body, and keep a key past the longest retry window
@@ -30,7 +30,6 @@ The one skill nearest the subject leaves the pointer open. `codebase-layout` exc
 ## Must not
 
 - Name a framework, a protocol style, or a language in the body. Status codes, verbs, pagination, and schema languages stay out, so the body holds for a function, a command, a file format, and an endpoint alike.
-- Restate the two error bullets of the core code rule
 - Restate the consumer-listing axis `review-craft` carries for a finished change
 - Cover interface depth or the internals behind a boundary, which govern what sits behind a surface rather than what crosses it
 - Import an external skill's tone, such as a law stated as absolute, or an excuse row rebutting an objection no session has raised

package/claude/skills/api-design/SKILL.md

@@ -31,8 +31,8 @@ Every observable behavior becomes a dependency once there are enough callers, wh
 
 ## Keep one error shape per surface
 
-- Give every failure on one surface the same shape, carrying a stable code a caller can branch on and a message for the person reading it. Branching on message text breaks the first time the message is reworded.
-- Follow the project's own rule on structured errors and hidden internals where it states one, rather than inventing a second error convention beside it.
+- Give every failure on one surface the same shape, carrying a stable code a caller can branch on and a message for the person reading it. Branching on message text breaks the first time the message is reworded. Keep internal implementation details out of the message, since a caller reads it and cannot act on a stack frame.
+- Reuse the error type the project already throws or returns where one exists, rather than inventing a second error convention beside it.
 
 ## Validate at the boundary
 
@@ -98,7 +98,6 @@ Check each line against the surface the change produced. A line answering no is
 ## What this delegates
 
 - Where the file holding a surface sits on disk: `codebase-layout`
-- The structured error rule and hidden internals floor every code stack loads: `000-code`
 - Listing the consumers a finished change breaks, and the docs it made false, during review: `review-craft`
 - A visual interface, its layout, and its look: `design-taste`
 - Interface depth and the internals behind a boundary: `code-craft`

package/claude/skills/api-design/references/adopted.md

@@ -21,7 +21,7 @@ From `addyosmani/agent-skills@2686b620`, [`skills/api-and-interface-design/SKILL
 
 **Contract first.** Write the interface before the body. Adopted as its own group, widened from an endpoint to a signature, a flag set, an output shape, and a schema.
 
-**One error shape.** Every failure on one surface carries the same structure. Adopted with a stable code added for the caller to branch on, and pointed at the core code rule for the structured-error floor rather than restating it.
+**One error shape.** Every failure on one surface carries the same structure. Adopted with a stable code added for the caller to branch on, and a clause keeping internal implementation details out of the message, since no project rule carries either for every code stack.
 
 **Validation at the boundary.** Check input where it enters and trust it inside. Adopted, with a value read back from a file or another service counted as input.
 

package/claude/skills/auto-ship/references/draft-mark.md

@@ -29,4 +29,4 @@ The number crosses from that step's output into a command this session types, wh
 
 Report what the read returned rather than what the command printed, since the exit says the call ran and says nothing about the state. A `true` reports a draft. A `false` reports the pull request as opened ready and unsupervised, and the chain stops there. Never re-issue the mark on a disagreeing read, which fights whoever readied it instead of guarding anything.
 
-Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act belongs to the operator or to the controlling session that closed the review, whichever it is, taken directly on the pull request rather than delegated to a worker. `role-worker` states the mirroring refusal.
+Placement is why the call sits ahead of the watch rather than after it. Marking afterwards leaves the pull request unmarked for the whole CI run, which is the stretch an unattended worker's branch is least supervised. What the mark buys is a reader learning the pull request has had no review yet. It buys no bound on that stretch: readying a pull request to merge lifts the mark, GitHub requires it before a merge, and the act runs through `canon pr lift`, which a reviewer runs on its close and the controlling session runs as the fallback, or through the operator directly. `role-worker` states the mirroring refusal of an instruction to ready the pull request directly, whoever sends it.

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

@@ -27,15 +27,14 @@ Consult to pick the `canon` verb for a job, and before running a verb that write
 
 ## Domains
 
-| Job                                                             | Verb              |
-| --------------------------------------------------------------- | ----------------- |
-| Install or sync governance rules                                | `canon gov`       |
-| Read an authoring standard by name                              | `canon standards` |
-| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling`   |
-| Set up or sync the Claude workflow                              | `canon claude`    |
-| Scaffold a wiki                                                 | `canon wiki`      |
-| Regenerate the `index.md` files                                 | `canon indexes`   |
-| Read a toolkit reference doc                                    | `canon docs`      |
+| Job                                                             | Verb            |
+| --------------------------------------------------------------- | --------------- |
+| Install or sync governance rules                                | `canon gov`     |
+| Sync a tooling stack's configs and seeds, or read its reference | `canon tooling` |
+| Set up or sync the Claude workflow                              | `canon claude`  |
+| Scaffold a wiki                                                 | `canon wiki`    |
+| Regenerate the `index.md` files                                 | `canon indexes` |
+| Read a toolkit reference doc                                    | `canon docs`    |
 
 ## Author and render
 
@@ -84,12 +83,12 @@ Read the doc each line names before running one of these. `canon docs install-an
 
 - `canon sync` runs every installed domain's sync, so it carries each risk below.
 - `canon gov sync` replaces a rule you edited and deletes a rule the toolkit retired, edited or not.
-- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once and dictionaries merge. Nothing writes without the flag. See `canon docs sync`.
+- `canon tooling sync --write` replaces every golden config a stack ships. Seeds are copy-once. Nothing writes without the flag. See `canon docs sync`.
 - `canon design sync` replaces the shipped design files and leaves `.claude/design/project/` alone.
 - `canon migrate --write` rewrites files that cite a retired name or layout. It reports and writes nothing without the flag. See `canon docs migrate`.
 - `canon indexes regen` rewrites each generated `index.md` from the folder's current state, so a hand edit there is lost. See `canon docs indexes`.
 
-No command writes a standard into a project, so `canon standards` is safe to run. `CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
+`CLAUDE.md` and the other seed docs are copy-once, and no sync updates them. Merge those by hand against the toolkit copy.
 
 ## Source of truth
 

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

@@ -20,6 +20,7 @@ The last failure is the session's own effort. Asked to report, a session starts
 - Write the stated fallback for a field the session cannot fill, so an empty field reads as absent rather than as unreported
 - Open a GitHub issue on the toolkit repo through the CLI so the report lands where triage reads it, and print the returned URL on its own line
 - Surface the block and the reason when the issue call fails, since a failure that prints nothing leaves the report where nothing reads it
+- Carry the whole request in the issue body alone, since a comment is easy to miss and a body and a comment that differ leave triage choosing
 - Hold a report the operator marks sensitive, since the issue is public
 - Fall back to printing the block when the CLI is absent, so the report still exists
 

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

@@ -27,41 +27,23 @@ From the conversation so far, identify:
 - Repro details already in context (commands run, files touched), or `none`
 - Proposed fix, or `open` when the session settled on no direction
 
-Format as a single fenced markdown block, one `###` heading per field:
+**Fields the report omits when the session has none:**
 
-```markdown
-## Toolkit feedback
-
-### From project
-
-<name or kind>
-
-### Surface
-
-<type>, <file path or name>
-
-### Observed
-
-<one or two lines>
+- Suggested shape, when the session worked out what the change should look like, such as a template, a command's output, or a field list
+- Why, when the session has reasons for the fix beyond the observed failure
+- Links, when the session cites an issue, a pull request, or a document
 
-### Expected
+Format as a single fenced markdown block, one `###` heading per field. Read `${CLAUDE_SKILL_DIR}/references/template.md` on reaching this point for the block and each field's fallback.
 
-<one or two lines, or "unclear">
+`canon feedback` refuses a report missing `### Surface`, `### Observed`, or `### Proposed fix`, naming the one it did not find. `### From project`, `### Expected`, and `### Repro` are optional, so write the literal fallback the template shows rather than dropping the heading, which is what keeps a field the session cannot fill reading as absent instead of unreported.
 
-### Repro
-
-<commands or steps, or "none">
-
-### Proposed fix
-
-<one line, or "open">
-```
-
-`canon feedback` refuses a report missing `### Surface`, `### Observed`, or `### Proposed fix`, naming the one it did not find. The other three are optional, so write the literal fallback shown above rather than dropping the heading, which is what keeps a field the session cannot fill reading as absent instead of unreported.
+`### Suggested shape`, `### Why`, and `### Links` are optional the other way. Omit the heading when the session has nothing for it and write no fallback, since a report filed without them is complete and a placeholder would read as a reporter who had nothing to say.
 
 Headings rather than bold labels, because a GitHub issue form renders a submitted field as `### <label>`. One shape reaches the toolkit whichever route a report takes, and the CLI parses both with one parser. The retired `**Surface:**` form is refused rather than accepted, so a block carrying it has to be rewritten.
 
-Keep each field to one or two lines.
+Keep Observed and Expected to one or two lines each, so the report scans. Length belongs in Proposed fix, Suggested shape, and Why.
+
+The issue body is the request. Put everything the toolkit needs to act on it there, since a comment is easy to miss and a body and a comment that differ leave triage choosing. A comment carries only what happens after filing.
 
 ## Step 2: ship to the toolkit
 

package/claude/skills/canon-feedback/references/template.md

@@ -0,0 +1,53 @@
+---
+title: Feedback report template
+description: The fenced block canon-feedback fills, one heading per field, with each field's stated fallback
+---
+
+# Feedback report template
+
+Step 1 of `canon-feedback`. The session reads this file on reaching the point where it formats the block.
+
+```markdown
+## Toolkit feedback
+
+### From project
+
+<name or kind>
+
+### Surface
+
+<type>, <file path or name>
+
+### Observed
+
+<one or two lines>
+
+### Expected
+
+<one or two lines, or "unclear">
+
+### Repro
+
+<commands or steps, or "none">
+
+### Proposed fix
+
+<the direction in as many lines as it takes, or "open">
+
+### Suggested shape
+
+<details>
+<summary>Shape</summary>
+
+<the template, output, or field list, in a fence one backtick longer than any fence it holds>
+
+</details>
+
+### Why
+
+- <one reason per bullet>
+
+### Links
+
+<one link per line>
+```

package/claude/skills/canvas-board/SKILL.md

@@ -47,9 +47,11 @@ Hand the operator the address as a markdown link carrying the URL as its text an
 ## 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.
+- Follow the house style in `${CLAUDE_SKILL_DIR}/references/canvas.md` before drafting an explanation frame.
+- 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. The verb places the frame after the last one, and a position the operator asks for goes through `frame move`.
 - 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.
+- After an insert or a resize, re-lay the page with `canon canvas arrange <page> --json`. It keeps the rows the operator dragged, places each on the standard gap, and drops layout entries whose frame file is gone. `--check` reports without writing.
 
 ## Step 3: edit a frame through its file
 
@@ -57,6 +59,7 @@ Write the frame's whole document to the `path` the add verb reported. The open c
 
 - 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.
+- Fit the box to the content once the write lands: `canon canvas fit <page>/<frame> --json`. Read each row's `wide` and `font`. A `wide` frame needs its box widened, which fit never does, and a `font` frame names a family the canvas does not serve, so set its text to a served face and fit again. A fit that grew a frame leaves the rows below overlapped until `canvas arrange` runs.
 - 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.
 
 Mark the frame before the first write, so the operator sees which frame is being worked on before anything lands, and clear the mark once the edits to it are done:

package/claude/skills/canvas-board/references/canvas.md

@@ -15,6 +15,7 @@ The folder is gitignored, so nothing in a repository checks its shape and nothin
 - [What a working canvas looks like](#what-a-working-canvas-looks-like)
 - [Pages](#pages)
 - [Frames](#frames)
+- [House style](#house-style)
 - [Layout](#layout)
 - [Tokens](#tokens)
 - [What a frame must not assume](#what-a-frame-must-not-assume)
@@ -24,9 +25,11 @@ The folder is gitignored, so nothing in a repository checks its shape and nothin
 
 Governs the canvas content under `.canon/canvas/`: page folder names, frame files, the `layout.json` shape, how tokens reach a frame, and what a frame must not assume about where it renders.
 
+Also governs the house style of an explanation frame, being a diagram, a board of notes, or a comparison. A mockup of the project's own interface is not an explanation frame, and it follows the project's design document for type, color, and layout.
+
 Does not govern:
 
-- The design decisions a frame is drafting, such as type, color, and layout taste: the project's own design document
+- The design decisions a mockup frame is drafting, such as type, color, and layout taste: the project's own design document
 - The project's design document and the token module it renders from, which a picked direction is carried into: `design.md`
 - The procedure that starts the canvas, reads the operator's selection, and carries a pick back, which belongs to the surface driving the canvas
 - Voice, rhythm, and sentence construction in any text a frame shows: the `write-human` skill
@@ -59,6 +62,19 @@ A canvas failing these is non-conforming even when it satisfies every shape rule
 - Use the project's custom properties, `var(--<name>)`, for every value the token stylesheet defines. A literal copied from it shows the right color today and the wrong one after the next token change.
 - Edit a frame by rewriting its file. The file is the frame, and nothing else holds a copy of its markup.
 
+## House style
+
+Applies to an explanation frame only. A mockup of the project's interface renders at the app's own sizes and follows the project's design document instead.
+
+- Write text in sentence case. Use no all-caps text and no `text-transform: uppercase`.
+- Keep lines short, one fact a line.
+- Set body text at 20px or larger and headings at 44px or larger. Set nothing under 16px.
+- Render an explanation frame about 1100px wide.
+- Take colors from the project's custom properties. A frame that defines colors of its own sets the dark values on `:root` and the light ones under `[data-theme="light"]`, since the shell sets `data-theme` on each frame's root.
+- Name only the faces the canvas serves into every frame: `Geist Variable` for text, `Noto Sans Mono` for code, and `Excalifont` for a hand-drawn look. They render the same in a capture and in any browser, so a height fitted against them holds.
+- Make each box tall enough to show all its content, with no scrollbar and no clipped line. Run `canon canvas fit <page>/<frame>` rather than estimating, since it measures the content in the capture browser and sets the height.
+- Read frames left to right in reading order. Let `frame add` place each frame after the last with the standard gap, and move one only when the operator asks for a position.
+
 ## Layout
 
 - Keep one `layout.json` per page, beside its frames. It holds each frame's box and nothing else, so moving a frame never rewrites its markup.
@@ -89,8 +105,8 @@ The keys below are the ones a reader parses. The frame names are placeholders.
 
 - Do not assume a viewport. A frame renders at its layout width on the canvas and in a capture alike, so size it with media queries against that width rather than against the operator's window.
 - Do not assume the theme. The canvas theme toggle is the operator's own state, and a capture shows each frame in its default theme.
-- Do not assume a network. Name only fonts the machine has, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
-- Do not assume a default font. Set `font-family` with an installed family first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines.
+- Do not assume a network. Name a served face, or ship the font beside the frame, since a capture refuses a frame naming a font it cannot find.
+- Do not assume a default font. Set `font-family` with a served face first on an element the frame's text inherits from, since a capture checks the first family of the text it renders and the browser's default serif is absent from many machines. A frame naming a machine family such as `DejaVu Sans` renders at another height in another browser, which `canon canvas fit` reports.
 - Do not assume the frame is the source. A picked direction is carried into the project's design document or a plan, and the operator clears the frame once it has been carried.
 - Do not assume the canvas survives the checkout. The folder is gitignored, so a lost checkout loses every page in it.
 
@@ -113,6 +129,13 @@ A new frame starts from this skeleton. The names in it are placeholders.
         color: var(--color-text);
         background: var(--color-background);
       }
+      /* only a color the frame defines itself: dark on :root, light here */
+      :root {
+        --frame-accent: #7aa2ff;
+      }
+      [data-theme='light'] {
+        --frame-accent: #1f4fd8;
+      }
     </style>
   </head>
   <body>

package/claude/skills/code-craft/REQUIREMENT.md

@@ -30,7 +30,7 @@ Before this skill, two shipped pointers left interface depth unowned. `api-desig
 - State a tension as one side only, such as "never duplicate"
 - Name a language, a framework, or a type system feature in the body
 - Restate the red, green, refactor loop `test-first` runs, or the design review procedure `review-craft` carries for a finished diff
-- Restate the error and naming bullets of the core code rule
+- Restate error or naming bullets. The core code rule retired them on purpose, and the error shape lives in `api-design`.
 
 ## Guards
 

package/claude/skills/code-craft/SKILL.md

@@ -106,4 +106,3 @@ Check each line against the code the change produced. A line answering no is fix
 - Which layer a test belongs at: `test-craft`
 - The contract a caller depends on, being its exports, flags, output, and errors: `api-design`
 - Judging a finished diff, including a design review of it: `review-craft`
-- The error and naming floors every code stack loads: `000-code`

package/claude/skills/create-rule/SKILL.md

@@ -70,4 +70,4 @@ Title casing is sentence case, with proper nouns keeping their own casing (`# Ty
 
 ## After writing
 
-Emit the full path on its own line: `.claude/rules/project/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads a matching file, and always-on rules every session.
+Emit the full path on its own line: `.claude/rules/project/<subdir>/<n>-<slug>.md`. Remind the user that Claude Code loads path-scoped rules when it reads or writes a matching file, and always-on rules every session.

package/claude/skills/create-rule/references/rule.md

@@ -21,7 +21,9 @@ description: Rule frontmatter, body shape, and voice for .claude/rules files
 
 Rules give Claude Code coding constraints scoped to file paths. Claude Code discovers `.claude/rules/**/*.md` at session start.
 
-A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads a file matching the glob. Author one rule per topic so the scope stays precise.
+A rule with no `paths:` field always applies, at the same priority as `CLAUDE.md`. A rule with `paths:` applies when Claude reads or writes a file matching the glob. Author one rule per topic so the scope stays precise.
+
+A rule with `paths:` loads on a read or a write of a matching file, inside a linked worktree as in the main one. A session creating the first matching file gets the rule only after that write lands, so a rule meant to shape new files also belongs in the skill or the always-on rule a session reads before it writes. Revisit when Claude Code loads a path-scoped rule before a write to a matching path. Re-measure with two headless `claude -p` runs in a linked worktree, one reading a matching file and one reading a file that does not match, each asking whether the rule's content is in context.
 
 ## Scope
 

package/claude/skills/create-skill/SKILL.md

@@ -11,7 +11,8 @@ Read these files in parallel:
 
 - `${CLAUDE_SKILL_DIR}/references/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
 - `${CLAUDE_SKILL_DIR}/references/skill-requirement.md`: what `REQUIREMENT.md` must answer, its sections, and its template
-- `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites a standard
+- `${CLAUDE_SKILL_DIR}/references/skill-paths.md`: which root a path in the body resolves against, and how the body cites another skill's reference
+- `${CLAUDE_SKILL_DIR}/references/skill-reference.md`, when the skill carries a reference setting the shape of one artifact: its scope, success criterion, frontmatter, and rule phrasing
 - `${CLAUDE_SKILL_DIR}/../markdown-craft/references/markdown.md`: punctuation and formatting for skill body text
 - `${CLAUDE_SKILL_DIR}/references/skill-practice.md`, when the skill carries engineering practice: the closing sections a practice skill owes and the anatomy behind them
 - The `write-human` skill: voice, rhythm, and sentence construction for skill body text

package/claude/skills/create-skill/references/skill-paths.md

@@ -1,17 +1,17 @@
 ---
 title: Skill path reference
-description: Which root a file a skill body names resolves against, and how a body cites a standard
+description: Which root a file a skill body names resolves against, and how a body cites another skill's reference
 ---
 
 # Skill path reference
 
 Applies to every path a skill body names, under `skills/<name>/`. A skill reads from two roots, so the path it writes decides whether the file is found once the skill runs from another project.
 
-This is an attribute standard. It governs the path strings a body carries rather than a file of its own, so it carries no template.
+This is an attribute reference. It governs the path strings a body carries rather than a file of its own, so it carries no template.
 
 ## Scope
 
-Governs how a `SKILL.md` body or a file under its `references/` names a bundled asset, an installed shared doc, or a standard.
+Governs how a `SKILL.md` body or a file under its `references/` names a bundled asset, an installed shared doc, or another skill's reference.
 
 Does not govern:
 
@@ -23,7 +23,7 @@ Does not govern:
 A path in a skill body works when the skill resolves it from any project it runs in:
 
 - Does each bundled asset resolve against the skill's own directory rather than the session's working directory?
-- Does each cited standard resolve in a target that installed nothing but the plugin?
+- Does each cited reference resolve in a target that installed nothing but the plugin?
 - Does a procedure two skills share live in one place, with each body citing it?
 
 A body failing any of these is non-conforming even when every path resolves in this repository.
@@ -34,18 +34,15 @@ Know which root a file lives under before referencing it.
 
 - Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, which resolves against the session cwd and fails when a plugin skill runs from another project.
 - Installed shared docs (`.claude/rules/`, `canon/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
-- Do not hand-copy a standard into a skill. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
+- Do not hand-copy another skill's reference into a skill. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
 
-## Citing a standard
+## Citing another skill's reference
 
-No standard installs into a project, so a body cites one place rather than choosing between two.
+A reference shared across skills lives in the `references/` of the skill that owns it, so a body cites it by the sibling path.
 
-- Cite `${CLAUDE_SKILL_DIR}/../../standards/X.md`. The plugin ships the whole standards folder beside `skills/`, so the path resolves in every install.
-- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. A standard that moved into the skill owning it lives there, and the plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
-- Never cite `.claude/standards/X.md` from a shipped body. A target holds no such folder. <!-- audit-ignore-citations: .claude/standards/X.md -->
-- Name `canon standards X` instead where the body wants the document rather than a path to open, such as a value it captures or reports. That verb resolves `standards/` at the project root and then the corpus inside the package.
-- State the path once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
-- A guard on a standard's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
+- Cite another skill's reference as `${CLAUDE_SKILL_DIR}/../<skill>/references/<name>.md`. The plugin ships the skills side by side, so the sibling path resolves in every install. Name the owner skill rather than copying the file.
+- State the path once per body, at the site that reads the reference. A later mention of a reference the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
+- A guard on a reference's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
 - Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`, since only the first expands before the body reaches the model.
-- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in a standard and a citation in each body.
-- Keep the trigger in the body and the procedure in the standard. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the standard cannot know it.
+- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in its owner's reference and a citation in each body.
+- Keep the trigger in the body and the procedure in the reference. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the reference cannot know it.