@erclx/canon 5.26.0 → 5.28.0

package/README.md

@@ -43,8 +43,8 @@ claude plugin install canon@canon
 ```
 
 <picture>
- <source media="(prefers-color-scheme: dark)" srcset="assets/evidence/install.png">
- <img src="assets/evidence/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
+ <source media="(prefers-color-scheme: dark)" srcset="assets/frames/install.png">
+ <img src="assets/frames/install-light.png" alt="Adding the canon marketplace and installing the plugin in Claude Code">
 </picture>
 
 The skills land as `/canon:<name>`. If your session was already open, run `/reload-plugins` to pick them up.

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

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

@@ -1,6 +1,8 @@
 ---
 name: api-design
 description: Carries the rules for shaping what a caller of code can see and come to depend on, being a function's exports, a command's flags and output, a file format, an endpoint, or a module boundary, so a change keeps every existing caller working and exposes nothing by accident. Use when adding or changing a public function, a flag, an output shape, a schema, an error a caller handles, or a retried write, or when asked "is this a breaking change", "can I rename this field", "what should this return", "how do I make this safe to retry", or "how should I version this". Do NOT use for a visual interface, which is `design-taste`, to decide where a file sits, which is `codebase-layout`, or to list the consumers a finished change breaks during review, which is `review-craft`.
+metadata:
+  family: build
 ---
 
 # API design

package/claude/skills/auto-ship/SKILL.md

@@ -2,6 +2,8 @@
 name: auto-ship
 description: Chains implement → verify → review → ship after a feature plan is approved. Reads the plan the caller names, the plan a named task points at, or the plan for the current branch when none is named, runs the full pipeline in one session, and stops on any failure or non-minor review finding. Use when asked to "autoship", "ship this feature end to end", or "run the chain". Do NOT auto-trigger. Requires an approved plan file.
 disable-model-invocation: true
+metadata:
+  family: build
 ---
 
 # Auto ship
@@ -121,17 +123,7 @@ Never read an absent subcommand as a skip, since failing open would ship every b
 
 ## Step 7: evaluate findings
 
-Skip this step when Step 6 skipped review. Otherwise read `.canon/review/branch-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited.
-
-- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop or offer the fix as a choice.
-- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
-
-Read origin as causation rather than authorship, so staleness this run induced in a file it never opened is a finding it caused.
-
-Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
-
-This chain owns the receipt's lifetime. The `context-fold` sweep under Step 8 reaches only reports whose branch is gone, so it collects this one a branch later.
+Skip this step when Step 6 skipped review. Otherwise read `${CLAUDE_SKILL_DIR}/references/review-findings.md` before opening the review receipt. It carries how every finding splits by origin, which ones this run repairs and which stop the chain, and the one-pass bound on the repair.
 
 ## Step 8: ship
 

package/claude/skills/auto-ship/references/review-findings.md

@@ -0,0 +1,20 @@
+---
+title: Review findings
+description: How auto-ship Step 7 splits the review receipt's findings by origin, which ones it repairs in place and which stop the chain, and the one-pass bound on the repair
+---
+
+# Evaluate the review findings
+
+Step 7 of `auto-ship`. The session reads this file when Step 6 ran review rather than skipping it.
+
+Read `.canon/review/branch-<slug>.md` at the main worktree root. Split every finding by origin before parsing the summary line (`X critical, Y should-fix, Z minor`), since the stop exists for a defect the branch inherited.
+
+- **This run caused it, at any severity.** Fix it, re-run the Step 3 verify commands, re-read the fixed file against what the finding claimed, and continue. Do not report it as a stop or offer the fix as a choice.
+- **It predates this run, critical or should-fix.** Stop: `❌ Review found non-minor issues that predate this run. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
+- **It predates this run, minor only.** Continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
+
+Read origin as causation rather than authorship, so staleness this run induced in a file it never opened is a finding it caused.
+
+Bound the repair at one pass, the way Step 3 bounds verify. When that re-read shows the finding still standing, stop: `❌ A self-introduced finding survived one fix pass. See .canon/review/branch-<slug>.md. Fix and run /git-ship.`
+
+This chain owns the receipt's lifetime. The `context-fold` sweep under Step 8 reaches only reports whose branch is gone, so it collects this one a branch later.

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

@@ -1,6 +1,8 @@
 ---
 name: backlog-triage
 description: Files a measured verdict for every backlog row into an intake folder, suggesting decline, archive, keep, or promote and leaning toward decline, then applies the verdicts the operator approved through the task verbs. Use when asked to "triage the backlog", "prune the backlog", "which backlog rows are still worth doing", "clear out the backlog", or "apply the backlog triage". Do NOT use to file a brain dump, which is `plan-intake`, to answer the filed items, which is `plan-intake-answer`, or to create, archive, or decline one named task, which is `task-board`.
+metadata:
+  family: decide
 ---
 
 # Backlog triage

package/claude/skills/bash-cli-script/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: bash-cli-script
 description: Generates a small non-interactive Bash wrapper for automation, CI, and agent-run tasks, with strict mode, logs on stderr, a clean stdout, and explicit exit codes. Stops at 100 lines and routes the work to TypeScript on Bun. Use when asked for "a shell script", "a wrapper script", an automation or CI script, a cron job, or a pipeline helper. Do NOT use for a tool that prompts a person or draws a terminal UI, or for a script that will run past 100 lines. Both are written in TypeScript on Bun.
+metadata:
+  family: generate
 ---
 
 # Bash CLI script

package/claude/skills/build-in-slices/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: build-in-slices
 description: Carries how a building session works through an approved plan in thin slices, each one tested, committed, and left green before the next starts, and how it records what it noticed outside the plan rather than fixing it. Use before implementing a plan that touches more than one behavior or file, when a branch is piling up uncommitted work, or when asked "how should I build this", "how do I avoid one giant diff", "should I commit this now", or "should I fix this while I'm here". Do NOT use for the red, green, refactor loop inside one behavior, which is `test-first`, to shape the code a slice writes, which is `code-craft`, or to decide what a worker may write, which is `role-worker`.
+metadata:
+  family: build
 ---
 
 # Build in slices

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

@@ -1,6 +1,8 @@
 ---
 name: canon-cli
 description: Reference for what a canon verb does before you run it. Run `canon docs agents` for the full command catalog, `canon docs` for any other reference doc, and read this skill's own table for what a sync or install command overwrites, merges, or leaves untouched in a target project. Use when asked "which canon command do I run", "is there a doc for X", "will this overwrite my changes", or before running `canon tooling`, `canon standards`, `canon claude sync`, or `canon init`. Do NOT use to execute a sync, an install, or a docs lookup, only to know which command answers the question.
+metadata:
+  family: answer
 ---
 
 # Toolkit CLI contract

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

@@ -1,6 +1,8 @@
 ---
 name: canon-feedback
 description: Format a report about something broken, missing, or off in canon and open it as a GitHub issue on the toolkit repo via `canon feedback --github`, where the toolkit's triage reads it. Use when asked to "send this to the toolkit", "report this to canon", "file toolkit feedback", or "give the toolkit feedback about X". Do NOT use for general complaints about other tooling, IDE issues, or in-project bugs that do not implicate canon surfaces.
+metadata:
+  family: upkeep
 ---
 
 # Canon feedback

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

@@ -1,6 +1,8 @@
 ---
 name: canon-feedback-triage
 description: Triage open GitHub issues labeled `feedback` in the toolkit repo. List them, pick one, classify it as a direct fix or plan-worthy work, route to the right skill, and link the issue for close-out. Use when asked to "triage toolkit feedback", "work through the feedback issues", "process feedback issues", or "what feedback is open". Do NOT use to file new feedback (that is `canon-feedback`), or for general GitHub issue triage unrelated to toolkit feedback.
+metadata:
+  family: upkeep
 ---
 
 # Canon feedback triage

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

@@ -2,6 +2,8 @@
 name: canon-operator
 description: Front door to the toolkit in a target project. Orients on the toolkit's own docs and live `canon` catalogs, then runs or routes any toolkit operation from a plain-language intent. Use when you want one entry point instead of picking a specific setup or sync skill, or when asked to "use the toolkit", "what can the toolkit do", "sync my standards", "install rules", or "help me set up this project". User-invoked only. Defers first-time scaffold to setup and seed drift to seed-sync.
 disable-model-invocation: true
+metadata:
+  family: setup
 ---
 
 # Canon operator

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

@@ -2,6 +2,8 @@
 name: canon-rollout
 description: Takes one toolkit change out to every consuming project and brings each to a mergeable pull request. Carries an orchestrator role that enumerates the targets, dispatches a worker into each, reviews every pull request, and routes what each review posts, and a worker role that builds inside one target and answers its review. Use when asked to "roll this out to the targets", "take this change to every project", "run a rollout wave", "update the consuming projects", or when a session was dispatched into a target by a wave. Do NOT use for this repository's own board, which is `role-orchestrator`, and merge nothing.
 disable-model-invocation: true
+metadata:
+  family: upkeep
 ---
 
 # Canon rollout
@@ -135,14 +137,4 @@ Report a target whose `reviewReadable` reads `false` as unread rather than as cl
 
 ## Failure recovery
 
-| Stop point                              | Recovery                                                                                      |
-| --------------------------------------- | --------------------------------------------------------------------------------------------- |
-| `gh` absent                             | Install it and authenticate, then re-run the wave                                             |
-| Target index unknown                    | Re-run with `--sweep <root...>` and read the `bound` before trusting the count                |
-| Every clone of a target is behind       | Pull that clone, or name a current one, then dispatch that target alone                       |
-| Claim check refuses or reads unverified | Launch that target's worker by hand and report that it went out outside the check             |
-| Branch already claimed in a target      | Resolve what holds `chore/agents` there, then dispatch that target alone                      |
-| A target refuses the pull read          | Read the `reason`, repair it, and re-poll that target. Never record it as having no work      |
-| Diff too large to review here           | Dispatch a reviewer into that clone and route its findings back through Phase 3               |
-| Two sessions hold one branch            | Report both and stop. Sending findings to either puts two sessions on one ref                 |
-| A target fails to converge              | Stop that target's loop, report the rounds it took and what each pass found, and hand it over |
+Read `${CLAUDE_SKILL_DIR}/references/failure-recovery.md` on a stop for the recovery that stop point takes.

package/claude/skills/canon-rollout/references/failure-recovery.md

@@ -0,0 +1,20 @@
+---
+title: Failure recovery
+description: The recovery canon-rollout takes at each stop point, from an absent gh to a target that fails to converge
+---
+
+# Failure recovery
+
+The stops of `canon-rollout`. The session reads this file on any stop, for the recovery that stop point takes.
+
+| Stop point                              | Recovery                                                                                      |
+| --------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `gh` absent                             | Install it and authenticate, then re-run the wave                                             |
+| Target index unknown                    | Re-run with `--sweep <root...>` and read the `bound` before trusting the count                |
+| Every clone of a target is behind       | Pull that clone, or name a current one, then dispatch that target alone                       |
+| Claim check refuses or reads unverified | Launch that target's worker by hand and report that it went out outside the check             |
+| Branch already claimed in a target      | Resolve what holds `chore/agents` there, then dispatch that target alone                      |
+| A target refuses the pull read          | Read the `reason`, repair it, and re-poll that target. Never record it as having no work      |
+| Diff too large to review here           | Dispatch a reviewer into that clone and route its findings back through Phase 3               |
+| Two sessions hold one branch            | Report both and stop. Sending findings to either puts two sessions on one ref                 |
+| A target fails to converge              | Stop that target's loop, report the rounds it took and what each pass found, and hand it over |

package/claude/skills/canvas/SKILL.md

@@ -1,6 +1,8 @@
 ---
 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`.
+metadata:
+  family: decide
 ---
 
 # Canvas
@@ -57,6 +59,17 @@ Write the frame's whole document to the `path` the add verb reported. The open c
 - 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.
 
+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:
+
+```bash
+canon canvas editing <page>/<frame> --json
+canon canvas editing <page>/<frame> --done --json
+```
+
+- A mark lapses after five minutes, so mark the frame again during a longer edit.
+- Clear it on every exit from the edit, including one that stopped on a refusal. Clearing a frame that holds no mark succeeds.
+- When the mark call fails with `unknown command 'editing'`, the installed CLI predates the mark, so go on without it rather than stopping. Never run `canvas edit` in its place, whatever the error suggests, since that verb writes the frame.
+
 ## Step 4: read what the operator pointed at
 
 Read the selection when the operator says "this one", "the selected frame", or "that button":

package/claude/skills/ci-workflow/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: ci-workflow
 description: Generates GitHub Actions CI workflow files with parallel jobs, emoji job names, and gated deploy stages. Use when asked to "write a CI workflow", add GitHub Actions, set up a CI pipeline, or create a `.github/workflows` file.
+metadata:
+  family: generate
 ---
 
 # CI workflow

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

@@ -1,6 +1,8 @@
 ---
 name: code-craft
 description: Carries the rules for shaping code while it is being written, being a function, a class, or a module's internals, so a session picks the shape the next change needs rather than copying its neighbor, splitting by step, or building for a case nobody asked for. Use before writing a new function, class, or module, when deciding whether to extract duplicated code, add an abstraction, a pattern, or a seam, or when asked "should I extract this", "is this abstraction worth it", "should this be a strategy", "is this class doing too much", or "should I just copy this". Do NOT use for the red, green, refactor loop, which is `test-first`, to decide where a file sits, which is `codebase-layout`, to shape what a caller sees, which is `api-design`, or to judge a finished diff, which is `review-craft`.
+metadata:
+  family: build
 ---
 
 # Code craft

package/claude/skills/codebase-layout/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: codebase-layout
 description: Carries the rules that decide where a new file goes, when a folder splits, and when a file moves from its one consumer to shared code, so a plan places each new path by role and feature with a one-clause reason rather than beside its nearest neighbor. Use when a plan names a file or folder that does not exist yet, when `plan-feature` reaches its placement step, or when asked "where should this file go", "this folder is flat", "restructure this folder", or "should this be its own folder". Do NOT use to choose which layer a test belongs at, which is `test-craft`, or to shape what a module's interface exposes, which is `api-design`.
+metadata:
+  family: decide
 ---
 
 # Codebase layout

package/claude/skills/context-fold/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: context-fold
 description: Folds a session into the project's context entries, architecture, and wireframes, marks the outcomes the diff shipped `[x]` on the task board, and archives the plans those tasks cite. Use when asked to "fold the session into context", "update the context entries", "sync the planning records", when design or requirements changed mid-cycle, after a pivot, or before shipping. Do NOT use for `README.md` or `docs/`, which is `docs-sync`, or to create or archive a task file, which is `task-board`.
+metadata:
+  family: ship
 ---
 
 # Context fold
@@ -145,20 +147,4 @@ Otherwise read `${CLAUDE_SKILL_DIR}/references/classify.md` for the invocation,
 
 ## After completion
 
-Output one line per file updated:
-
-`✅ Updated: <path written>`
-
-When Step 3 met the architecture record's cap, add one line naming what it did there:
-
-`↪ Architecture at cap: merged <heading> into <heading>` or `↪ Architecture at cap: retired <heading> to <context entry>`
-
-When Step 2 noted a requirements change: `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`
-
-Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
-
-If no files were updated and nothing was swept, output:
-
-`✅ No changes needed.`
-
-Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.
+Read `${CLAUDE_SKILL_DIR}/references/completion-report.md` before printing anything, for the line each outcome prints, the lines Step 3, Step 2, and Step 10 add, and when the closing line is suppressed.

package/claude/skills/context-fold/references/completion-report.md

@@ -0,0 +1,26 @@
+---
+title: Completion report
+description: The lines context-fold prints once every step has run, being one per file updated, the architecture cap and direction-change notes, Step 10's own lines, and the closing line with when it is suppressed
+---
+
+# Completion report
+
+The close of `context-fold`. The session reads this file once every step has run, before printing anything.
+
+Output one line per file updated:
+
+`✅ Updated: <path written>`
+
+When Step 3 met the architecture record's cap, add one line naming what it did there:
+
+`↪ Architecture at cap: merged <heading> into <heading>` or `↪ Architecture at cap: retired <heading> to <context entry>`
+
+When Step 2 noted a requirements change: `↪ Direction changed this session: run document-health on canon/REQUIREMENTS.md`
+
+Step 10 adds its own lines when it applied or reported a finding, in the exact shape `${CLAUDE_SKILL_DIR}/references/classify.md` gives them under its own Report section. Do not shorten or paraphrase those lines here or in the reply, since the quote and the reason are what a reader checks the finding against.
+
+If no files were updated and nothing was swept, output:
+
+`✅ No changes needed.`
+
+Suppress that line when Step 2 already reported no doc updates. It closes the run on its own, and emitting both leaves a quiet session reporting success twice for one outcome.

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

@@ -1,6 +1,8 @@
 ---
 name: create-rule
 description: Scaffolds a project-specific governance rule into `.claude/rules/project/<subdir>/<n>-<slug>.md` with correct frontmatter and a non-colliding number. Use when asked to "add a rule", "create a governance rule", "write a project rule", or when a project needs a coding rule the toolkit does not ship. Do NOT use to edit toolkit source rules under `governance/rules/`.
+metadata:
+  family: generate
 ---
 
 # Create rule

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

@@ -1,6 +1,8 @@
 ---
 name: create-skill
 description: Creates a new `SKILL.md` in `.claude/skills/`. Use when asked to "create a skill", add a skill, or make a new skill.
+metadata:
+  family: generate
 ---
 
 # Create skill

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

@@ -1,6 +1,8 @@
 ---
 name: create-standard
 description: Creates a new standard file in `standards/`. Use when asked to "create a standard", add a standard, or write a new authoring convention. Do NOT use to edit an existing standard.
+metadata:
+  family: generate
 ---
 
 # Create standard

package/claude/skills/decision-escalate/SKILL.md

@@ -2,6 +2,8 @@
 name: decision-escalate
 description: Collects every open decision whose answer turns on the operator's preference, since only they know what they need, puts them as one batch of questions each carrying options and a recommended default, then waits. Use when asked to "escalate this", "ask me the open questions", "batch the open decisions", "what do you need from me", or "stop and ask before you pick". Do NOT use for a judgment call the session can settle, which is a pick with the tradeoff stated in one sentence.
 disable-model-invocation: true
+metadata:
+  family: decide
 ---
 
 # Decision escalate

package/claude/skills/deploy-app/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: deploy-app
 description: Sets up a deploy for the current project on Cloudflare Pages or Vercel by picking the host the project already carries, creating the host's project, setting the IDs it needs as repository secrets, and stopping for the operator to issue the API token and attach the custom domain. Calls `wrangler`, `vercel`, and `gh` rather than reimplementing them. Use when asked to "set up the deploy", "deploy this to Cloudflare Pages", "deploy this to Vercel", "set up the Pages project", "set up a Vercel project", or "connect this repo to Cloudflare". Do NOT use to run an already-configured deploy, which the host's own push trigger does, or to reconfigure an existing project's build settings.
+metadata:
+  family: setup
 ---
 
 # Deploy app

package/claude/skills/deprecation-migration/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: deprecation-migration
 description: Carries how a session retires a function, a flag, a field, a file, or a command without stranding whoever still calls it, from deciding whether to deprecate at all through proving no caller remains, migrating callers through an adapter or a strangler, and removing the old surface in its own change after the new one has carried every caller. Use when deleting or replacing code something may still call, when a deprecated path has lingered with no date, when finding dead or unowned code, or when asked "can I delete this", "how do I retire this", "how do I migrate callers off X", or "is anything still using this". Do NOT use to move or rename a file with no caller change, which is `codebase-layout`, to migrate a database schema, which the project's persistence rule governs, or to shape a new field or flag added beside an old one, which is `api-design`.
+metadata:
+  family: build
 ---
 
 # Deprecation and migration

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

@@ -1,6 +1,8 @@
 ---
 name: design-extract
 description: Drafts `canon/DESIGN.md` from a project's existing prose and shell UI surfaces, or proposes token values from `REQUIREMENTS.md` and a `## Personality` section when no UI code exists yet. Use when asked to "extract the design system", "draft DESIGN.md", "bootstrap design tokens", "capture the visual system", "propose a design system", "bootstrap DESIGN.md from scratch", "draft tokens for a greenfield project", or "replace Claude Design onboarding". Do NOT use to mutate an existing `canon/DESIGN.md`.
+metadata:
+  family: setup
 ---
 
 # Design extract

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

@@ -1,6 +1,8 @@
 ---
 name: design-taste
 description: Carries the layer model that decides which design decision settles first, the rules that keep a surface coherent across sections, and the catalog of defaults a model reaches for when nothing states a direction. Use when drafting or judging an interface, a page, or any rendered surface, when output reads generic or templated, when redesigning something that already exists, or when asked to "make this look designed", "why does this look like AI made it", "give it taste", "what layer is this decision at", or "grey-box this first". Do NOT use for accessibility, forms, or state coverage, which the `ui` governance rules carry, for the shape of the project's design document, which `design.md` governs, to run the candidate loop, which is `draft-and-pick`, or to trace a reference's values, which is `sketch-design`.
+metadata:
+  family: build
 ---
 
 # Design taste

package/claude/skills/docs-sync/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: docs-sync
 description: Rewrites stale `README.md` and `docs/*.md` sections based on changes since main. Use before staging, or when asked to "sync the public docs", "update the docs in docs/", or "update the README". Do NOT use for the context entries, planning records, or task board, which `context-fold` owns, or for changelog and `CLAUDE.md` updates.
+metadata:
+  family: ship
 ---
 
 # Docs sync

package/claude/skills/document-health/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: document-health
 description: Reports which of a project's documents have rotted, one section per document, across length, placement, and staleness. Reads each axis through the verb that owns it and marks the evidence class each answer carries. Use when asked to "check document health", "which docs have gone stale", "audit the docs for rot", "are these documents still accurate", "which docs are too long", or after a target check reports the structural side. Do NOT use to repair a finding, which the owning command or skill does, and do NOT use to check whether a document exists or holds the right sections, which is `target-check`.
+metadata:
+  family: check
 ---
 
 # Document health

package/claude/skills/draft-and-pick/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-and-pick
 description: Drafts several candidates for a decision judged by looking, renders them side by side on one page, hands the operator the addresses, takes the pick through the structured question surface, and loops on the pick until they stop. Use when asked to "draft some options", "show me a few versions", "try a few variations", "mock up alternatives", "give me candidates for X", or when a choice is taste rather than correctness. Do NOT use when the request already names the answer and asks for it to be built, which is `plan-feature`. Do NOT use to read source for roughness, which is `ux-audit`, to measure what a running interface costs to paint, which is `ux-measure`, to write what to look at on a change already made, which is `ui-checklist`, to script a recording, which is `draft-screencast`, or to inspect a running app across many findings, which is `ux-walkthrough`.
+metadata:
+  family: decide
 ---
 
 # Draft and pick

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

@@ -1,6 +1,8 @@
 ---
 name: draft-doc
 description: Drafts one brand-new project document from scratch against the standard for its kind, picking the kind from where it lands, a `docs/` page, a `canon/context/` entry, a `canon/wireframes/` surface, a wiki reference page, or a README.md. Checks the catalog for a name or topic collision, places it, confirms with the user, then writes. Use when asked to "write a new docs page for X", "write a context entry for X", "draft a wireframe for X", "write a wiki page for X", or "write a README" where none exists yet. Do NOT use to rewrite or sync an existing page or README against a diff, which is `docs-sync`, or to refresh a context entry or wireframe, which is `context-fold`.
+metadata:
+  family: generate
 ---
 
 # Doc draft

package/claude/skills/draft-doc/references/wiki.md

@@ -39,7 +39,7 @@ The standard forbids working from training knowledge, so the draft is built on a
 
 ## Draft
 
-- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:`, then the reference sections.
+- Draft `title` and `description` frontmatter against the standard's contract, then the intro paragraph closing on `Source:` as a short orientation, then the lesson sections. Let the read of the source decide what is a lesson: keep a fact only when the source page does not state it, and leave reference detail to the source.
 - Write what the fetch returned rather than what the subject is assumed to do.
 - Answer one question per section and stop. A reader arrives to settle something specific rather than to read the page through.
 - Mark a claim the fetch left unsettled rather than smoothing over it. An unmarked gap reads as a checked fact.

package/claude/skills/draft-figure/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-figure
 description: Drafts one hand-drawn figure for a document, deciding whether the subject is Mermaid-shaped, an architecture view, or needs freehand SVG, then draws it. Renders the Mermaid path through Mermaid's own hand-drawn look, reads the render back, and fixes what it exposes. Wraps every path in the figure standard's caption, color, and accessibility rules. Use when asked to "draw a figure", "add a hand-drawn diagram", "draft a figure for this doc", "draw this relationship as a figure", "draw the architecture", "diagram the system", or "show the components". Do NOT use for a UI wireframe, which is `draft-doc`, or for design tokens, which is `design-extract`.
+metadata:
+  family: generate
 ---
 
 # Draft figure

package/claude/skills/draft-identity/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-identity
 description: Drafts a project's logo mark through draft-and-pick's render-and-pick loop, then composes the picked mark into an icon sequence and a 1200x630 social card. Use when asked to "make a logo", "design a logo mark", "create a favicon", "build the icon set", "generate a social card", "make an og:image", or "draft the logo and social card together". Do NOT use to mutate an existing logo file directly, which is a plain edit, or to record the mark's construction rules in DESIGN.md, which is out of scope.
+metadata:
+  family: generate
 ---
 
 # Draft identity

package/claude/skills/draft-ready/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-ready
 description: Writes a ready folder for finished files, its `00-overview.md`, the thin plan that points at it, and the task with a board row placed, reported to an orchestrator, or left to the operator, in one invocation. Use when asked to "write a ready folder", "hand these files to a worker", "package these finished files for a worker", "make a ready handoff", or when a session already holds the exact text of a skill, rule, or doc and a worker should copy it rather than author it. Do NOT use to plan a change nobody has written yet, which is `plan-feature`, to copy a folder into a worktree and ship it, which is `role-worker`, or to file a task with no finished files behind it, which is `task-board`.
+metadata:
+  family: generate
 ---
 
 # Draft ready
@@ -77,7 +79,9 @@ canon tasks plan-link <task-stem> .canon/plans/feature-<slug>.md --json
 
 Branch on the record rather than on the exit. The `Ready:` line orients a worker reading the task, and `canon tasks archive` reads it to move the folder on ship.
 
-A task file with no row is a dropped task, so place the row in the same pass. The plan exists, so the row takes `## Run now` when `canon tasks plan-reach` reports nothing claimed and `## Up next` otherwise, with the held path in its `Waiting on` cell, per the tests in `${CLAUDE_SKILL_DIR}/../../standards/board.md`. Check the roster the way `canon:task-board` Step 4 does, reading `canon sessions list --self --json` for this session and `canon sessions list --json` for a row from the same repository, under another `sessionId`, whose `name` starts with `orchestrator-`. Treat a refused read as a roster read that failed.
+A task file with no row is a dropped task, so place the row in the same pass. The plan exists, so the row takes `## Run now`, per the tests in `${CLAUDE_SKILL_DIR}/../../standards/board.md`. A path `canon tasks plan-reach` reports as claimed is a shared file rather than a hold. Name each one and its holder wherever the row is reported below, so whoever controls the board decides whether a contract, a relocation, or a sweep moves the row to `## Up next`.
+
+Check the roster the way `canon:task-board` Step 4 does, reading `canon sessions list --self --json` for this session and `canon sessions list --json` for a row from the same repository, under another `sessionId`, whose `name` starts with `orchestrator-`. Treat a refused read as a roster read that failed.
 
 - **Orchestrator found.** Write neither file. Message that session with the row's title, the plan link, and the group with its reason, so it places the row itself rather than two sessions writing the board at once.
 - **Not found, and this session's name starts with `worker-` or `planner-`.** Write neither file, since both role bodies ban a board write with no exception. Report the row and its group in Step 8.

package/claude/skills/draft-screencast/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-screencast
 description: Drafts a screencast script with pre-seeded beats, defaults, and decisions to `demos/<slug>/beats.md`. Reads project context, asks four discovery questions with proposed defaults, then writes a shippable draft. Use when asked to "draft a screencast", "write a recording script", "plan a demo video", or "scaffold a screencast for X". Do NOT re-invoke to refine an existing draft. Re-running overwrites. Edit the draft file directly.
+metadata:
+  family: generate
 ---
 
 # Draft screencast

package/claude/skills/draft-slides/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: draft-slides
 description: Draws a deck as HTML slides in the project's own design, one folder under `.canon/slides/` per deck, then renders it to an editable PowerPoint file via `canon slides render`. Use when asked to "draft slides", "make a deck", "build a presentation", "turn this into slides", or "render the deck". Holds the deck design rules. Do NOT reimplement the conversion. The CLI owns layout into PowerPoint shapes, the master, and packaging. Assumes the `canon` CLI is on PATH.
+metadata:
+  family: generate
 ---
 
 # Draft slides

package/claude/skills/git-branch/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-branch
 description: Generates and validates conventional branch names. Use for any branch naming or renaming, such as when asked to "name this branch".
+metadata:
+  family: ship
 ---
 
 # Git branch

package/claude/skills/git-commit/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-commit
 description: Generates one conventional commit message from the staged changes and commits them exactly as staged, so a hunk-level selection survives. Use when asked to "commit this" or "commit the staged changes" and the staged set covers one concern, or whenever the selection was staged hunk by hand. Do NOT use when the staged changes span several concerns and need separate commits. That is `git-stage`.
+metadata:
+  family: ship
 ---
 
 # Git commit

package/claude/skills/git-followup/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-followup
 description: Ships a small self-review edit on the current PR branch by staging, committing, pushing, and syncing the open PR, replying on the PR when it carries review comments. Use when asked to "ship a followup", "push the PR fix", "followup", or "commit and push this small change". Do NOT use when there is no open PR for the branch (use git-ship instead).
+metadata:
+  family: after-pr
 ---
 
 # Git followup

package/claude/skills/git-issue/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-issue
 description: Format a bug or task from the current session into a GitHub issue and file it on the current repo via `gh issue create`. Use when asked to "file an issue", "open an issue", "log this bug", "raise an issue", or "track this as an issue". Do NOT use to report a toolkit defect from a target project (that is `canon-feedback`), or to open a pull request (that is `git-pr`).
+metadata:
+  family: after-pr
 ---
 
 # Git issue

package/claude/skills/git-pr/SKILL.md

@@ -1,6 +1,8 @@
 ---
 name: git-pr
 description: Generates pull request titles and descriptions from git diffs. Use for any PR creation or update, such as when asked to "open a pull request".
+metadata:
+  family: ship
 ---
 
 # Git PR