@erclx/canon 4.0.0

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

@@ -0,0 +1,102 @@
+---
+name: claude-design-extract
+description: Drafts `.claude/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 `.claude/DESIGN.md`.
+---
+
+# Design extract
+
+## Guards
+
+- If `.claude/DESIGN.md` already exists and has content beyond the seed template, stop: `❌ .claude/DESIGN.md already populated. Edit directly or archive the existing file first.`
+- If `canon` is not on PATH, stop: `❌ canon CLI not found.`
+
+Step 1 carries two more stops that apply to one path only. Do not evaluate them before the path is picked.
+
+## Step 1: pick the path from what the project already has
+
+Check the project root for UI surfaces: `src/ui.ts`, `src/ui.tsx`, `src/components/**`, `scripts/lib/ui.sh`, and any `*.css`, `tailwind.config.*`, or `theme.*`.
+
+- Any match takes the source path. Existing code defines the system, so every filled cell traces to a value already in the tree.
+- No match takes the greenfield path. Nothing anchors a value, so every filled cell is a proposal and carries the tag that says so.
+
+The project decides this, never a user flag or an argument. Announce which path ran in one line before Step 2, since the two produce different-looking output from the same skill.
+
+The greenfield path needs a personality paragraph to propose against, and stops without one. The source path needs neither file and skips both stops.
+
+- If `.claude/REQUIREMENTS.md` is missing, stop: `❌ .claude/REQUIREMENTS.md not found. Write requirements before proposing a design system.`
+- If `.claude/REQUIREMENTS.md` has no `## Personality` section, stop: `❌ .claude/REQUIREMENTS.md missing ## Personality section. Add a paragraph describing voice and tone before running this skill.`
+
+## Step 2: read source signals in parallel
+
+Read these on both paths, skipping any that do not exist:
+
+- `CLAUDE.md`: voice and personality
+- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: word, punctuation, and formatting constraints
+- The `write-human` skill: tone and sentence construction constraints
+
+On the source path, also read the UI surfaces matched in Step 1 plus any `docs/agents/output-shape.md` and `docs/index.md` the project itself carries, for output shape or framing rules already documented. Those two are the toolkit's own spelling, so a project keeping its framing rules elsewhere is read there instead.
+
+On the greenfield path, also read `.claude/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
+
+Run these reads in parallel. Do not speculatively recurse into every directory.
+
+## Step 3: fetch the seed template
+
+Run this from the project root:
+
+```bash
+canon claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md") | .content'
+```
+
+Use the returned content as the target shape. Keep every section heading and every table header intact. The `canon design render` parser depends on them.
+
+## Step 4: fill the template
+
+Walk each section once. Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` for punctuation and word choice throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
+
+Mark any cell not traced to a source value by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` after the row breaks the parser. A prose section takes its uncertainty inline instead, for example `Proposed 150ms ease-out, not yet confirmed.`, because a trailing tag on a sentence renders raw in the preview.
+
+On the source path, the tag marks the exception. On the greenfield path it marks nearly every cell, since the values are speculative until code or a designer anchors them.
+
+### Source path
+
+- **Personality**: one paragraph. Transcribe what `CLAUDE.md` and `.claude/REQUIREMENTS.md` say about voice, tone, and visual feeling. Do not invent rules the source does not state. If nothing matches, write a one-sentence placeholder ending in `? verify`.
+- **Color**: one row per role. Source hex values from the CLI UI files or stylesheets. If a role has no source signal, leave `Value` blank rather than guessing.
+- **Typography**: one row per role. Source families and sizes from stylesheet or theme config. Leave cells blank when no signal exists.
+- **Spacing**: fill the base unit and multipliers from stylesheet tokens or obvious repeated values in the UI code.
+- **Borders**: one row per role. Source from stylesheet or CSS variables.
+- **Motion** and **Iconography**: one line each. Default to `No animation.` and `No custom icons.` when no evidence exists.
+
+### Greenfield path
+
+Anchor every proposal to a signal, never to a default. "Calm and dense" pins muted grays and tight spacing. A requirements non-goal of "no motion" makes Motion read `No animation.` with no tag. A CLI-only surface leans Typography monospaced and keeps Borders minimal.
+
+- **Personality**: transcribe the `## Personality` paragraph from `.claude/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
+- **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values matching the personality. Dense and calm gives low saturation and high text contrast. Playful gives saturated accents. Every Intent and Value cell gets `? verify`.
+- **Typography**: one row per role. Propose families fitting the platform, system UI for web, monospaced for CLI tools, serif for editorial, and a harmonious scale. Every cell gets `? verify`.
+- **Spacing**: propose a base unit matching density intent. Dense gives a 4px base, roomy gives 8px. Keep the Multiplier column as the seed ships it, no tag. Only the Value column gets `? verify`.
+- **Borders**: propose radius and width per role. Sharp and technical gives a small radius, soft gives a larger one. Every Radius and Width cell gets `? verify`.
+- **Motion**: one line. Write `No animation.` when the requirements forbid motion. Otherwise phrase the uncertainty inline.
+- **Iconography**: one line. Propose style and source library matching personality, phrasing the uncertainty inline.
+
+Do not invent non-goals. A proposed motion line is fine when neither the personality paragraph nor the requirements rule motion out.
+
+## Step 5: write and render
+
+Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
+
+```bash
+canon design render
+```
+
+The command writes an HTML plus CSS preview to `.claude/review/design/`. Output the path in chat so the user can open it.
+
+## Response format
+
+```plaintext
+📝 Wrote .claude/DESIGN.md
+📝 Wrote .claude/review/design/index.html
+
+Ran the <source|greenfield> path. N cells marked `? verify`. Open the preview and confirm before committing.
+```

package/claude/skills/claude-diagram/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: claude-diagram
+description: Why diagrams are a folder of per-kind entries rather than one file, and why the verified marker is spent only on a render that was read back
+---
+
+# Claude diagram requirement
+
+## Gap
+
+Without this skill, a session asked to refresh one view rewrites the whole surface, so four diagrams nobody checked change in the same commit and the reviewer cannot tell which one the pass was about. It picks a filename of its own, and the next refresh writes a duplicate beside the old entry instead of finding it. It reaches for C4, state, or class diagrams that render differently in every viewer.
+
+The verification failure is the expensive one. A mermaid source can satisfy every rule in the standard and still render as a picture that asserts something false about the system, so a session that judges the source and stamps the entry as verified has spent the only signal a reader has on a diagram nobody looked at. The standards hook toggles off inside a fenced block, so a banned character in a node label passes silently while the same character one line below is caught.
+
+## Must
+
+- Write one entry per kind under the filename and category the standard fixes, so a later refresh finds its target
+- Pick which entries this pass writes from whether the source signal exists and whether the pass has reason to touch it
+- Stay inside `flowchart` and `sequenceDiagram`
+- Render every entry this pass wrote and read the image back against what the entry means to say
+- Stamp the verified marker only on an entry whose render was read back and judged correct
+- Name every skipped render and every surviving defect in the output
+- Regenerate the catalog from sibling frontmatter after the last entry is written
+- Read the node labels by hand, since no hook checks inside a fence
+
+## Must not
+
+- Rewrite an entry this pass had no reason to touch, or report one as written when it was left alone
+- Stamp an untouched entry, a skipped render, or an entry whose defect survived
+- Report a clean verification when a check did not run
+- Commit a render, which is a verification artifact rather than a deliverable
+- Redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke it
+- Loop on a defect past two correction passes
+
+## Guards
+
+- No architecture file, no requirements file, and no folder structure to scan: stop, because nothing anchors a diagram
+- Render fails for any reason: continue to the output and name the skipped check. A missing renderer degrades the loop rather than failing it.
+- `canon` not on PATH: report the catalog as stale rather than hand-editing it
+
+## Out of scope
+
+- Design tokens and the visual system, which `claude-design-extract` owns
+- UI roughness, which `claude-ux-audit` owns
+- Writing the catalog file, which the index regen owns from frontmatter
+- Deleting a pre-split flat diagrams file after a migration, which stays the user's call

package/claude/skills/claude-diagram/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: claude-diagram
+description: Writes per-kind Mermaid diagram entries into `.claude/diagrams/`, covering system context, components, request flow, data pipeline, and deployment. Reads `.claude/ARCHITECTURE.md` and `REQUIREMENTS.md` when present, falls back to a code-structure scan. Use when asked to "draw the architecture", "diagram the system", "show the components", "give me a flow chart", "refresh the deploy diagram", or "visualize the project". Do NOT use for design tokens (use `claude-design-extract`) or UI audits (use `claude-ux-audit`).
+---
+
+# Claude diagram
+
+Write one entry per diagram kind. Never rewrite the folder wholesale. A pass that refreshes the deploy view leaves the other four files byte-identical, which is the whole reason the surface is a folder.
+
+## Guards
+
+- If no `.claude/ARCHITECTURE.md`, no `.claude/REQUIREMENTS.md`, and no top-level folder structure to scan, stop: `❌ No source signal. Add .claude/ARCHITECTURE.md or run inside a project folder.`
+
+## Step 1: read sources and locate the surface
+
+Read these from the project root in parallel, skipping any that do not exist:
+
+- `.claude/diagrams/index.md` and every `.claude/diagrams/*.md`: which entries exist and what they already say
+- `.claude/REQUIREMENTS.md`: users, external dependencies, tech stack, MVP feature list
+- `.claude/ARCHITECTURE.md`: layered components, key technical decisions
+- `CLAUDE.md`: project type, conventions
+- `package.json`, `pyproject.toml`, `Cargo.toml`: language and framework markers
+- Top-level folder layout and root config files via `ls`: deploy targets, infrastructure config, component boundaries
+
+Do not recurse speculatively.
+
+Follow `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` for frontmatter, entry kinds, layout, budgets, accessibility, verification, and explanation rules.
+
+### Migrating a pre-split flat file
+
+When `.claude/diagrams/` holds no entry and `.claude/DIAGRAMS.md` exists, this pass converts it. An entry is any `*.md` in the folder other than `index.md`. The seed ships `index.md` alone, so a folder holding only the catalog is an empty set and still converts.
+
+Split each H2 section into the entry whose kind it matches, carry its mermaid body and explanation prose across unchanged, and add the frontmatter the standard requires. Leave `.claude/DIAGRAMS.md` on disk so the split can be compared against its source, and say in Step 7 that deleting it is the user's call.
+
+Convert only. Do not redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke a diagram.
+
+## Step 2: pick which entries this pass writes
+
+Write an entry only when its source signal exists, and only when this pass has a reason to touch it. Skip the rest and leave their files alone.
+
+Count entries the way Step 1 does, excluding `index.md`. Counting the catalog as an entry sends a first pass down the compare branch with nothing to compare, and it writes nothing.
+
+- The user named a kind: write that one.
+- The user asked broadly and the folder holds no entry: write every kind whose signal exists.
+- The user asked broadly and at least one entry exists: compare each entry against its source signal and write only the ones whose signal moved. Report the untouched ones as current.
+
+The standard fixes one filename and one `category` value per kind. Use them verbatim rather than inventing a name, since a refresh finds its target by filename and a new name writes a duplicate entry beside the old one. Emit `system-context.md` whenever `.claude/REQUIREMENTS.md` exists, since it is the entry a reader outside the team opens first and the set is incomplete without it.
+
+Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
+
+## Step 3: write the entries
+
+One file per kind at `.claude/diagrams/<kind>.md`. Write only the files Step 2 selected.
+
+````markdown
+---
+title: <what the entry answers, sentence case>
+description: <the question it settles and the signal that drives it>
+category: <the kind, matching the standard>
+verified: 'TODO: never verified'
+---
+
+# <Same as title>
+
+<one-line statement of what the diagram shows>
+
+```mermaid
+<diagram type>
+  accTitle: <what the diagram answers>
+  accDescr: <the structure in one sentence>
+  <body>
+```
+
+<one to three explanation paragraphs>
+````
+
+Write `verified` as the literal `TODO: never verified` here, quoted so the colon parses. Step 6 replaces it once a render has been read back, so a SHA written beside the diagram would assert a check that has not run yet. The placeholder is what keeps a render-less project conforming, since Step 5 sends a failed render past Step 6 and nothing stamps the entry. Carry an existing entry's current value across untouched when this pass is rewriting one, and let Step 6 replace that instead.
+
+When sources came from a code scan rather than planning prose, lead the explanation with `Source: code.` and add `Fidelity is lower than prose-driven diagrams. Verify against the project's intent.`
+
+A reader deciding whether the entry still holds starts from the code paths the explanation cites, so cite paths that exist and spell them exactly.
+
+Quote node labels containing spaces or special characters with double quotes (`A["Web shell"]`). Avoid parentheses inside labels, they break some renderers. Use `<br/>` for line breaks inside labels.
+
+Run the scan in `${CLAUDE_SKILL_DIR}/../../standards/publish.md` against the whole file, including inside mermaid `subgraph` labels and node text. The file lands in the repository rather than on a remote, so the scan's destination scoping leaves the character checks and not the phase-label one, and the `pull_request` check the git-pr surface carries reads only a pull request's own title and body, never a file the diff carries. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
+
+Nothing enforces the ban inside the diagram. The standards-audit hook toggles on a fence and skips every line within it, so a label carrying an em dash passes silently while the same character in the explanation paragraph below is caught. Check the labels by reading them. This is the one place in the file where the author is the only gate.
+
+## Step 4: regenerate the catalog
+
+```bash
+canon indexes regen
+```
+
+Run it after the last entry is written. It rebuilds `.claude/diagrams/index.md` from sibling frontmatter and groups entries under their `category`. Never hand-edit that file.
+
+When `canon` is not on PATH, say so in Step 7 and name `.claude/diagrams/index.md` as stale rather than writing it by hand.
+
+Scaffold `.claude/diagrams/index.md` with `title` and `subtitle` frontmatter before the first regen when the folder is new and the seed did not provide one. The subtitle routes a first-time reader to the system context entry, since the catalog sorts categories alphabetically rather than in narrative order.
+
+## Step 5: render what this pass changed
+
+A source that satisfies every rule in the standard can still render as a picture that asserts something false about the system. Verification runs on the image.
+
+Render each entry this pass wrote. Skip every entry Step 2 left alone, since an untouched diagram cannot develop a new render defect.
+
+Before the first render in a project, say what is about to block:
+
+```plaintext
+Rendering to verify layout. The first run downloads the Mermaid CLI and takes about 15 seconds.
+```
+
+Write each diagram's mermaid body to its own scratch file, then render it:
+
+```bash
+mkdir -p .claude/.tmp/diagrams && bunx -y @mermaid-js/mermaid-cli -i .claude/.tmp/diagrams/<kind>.mmd -o .claude/.tmp/diagrams/<kind>.png
+```
+
+Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning, so it cannot be verified. Use `bunx` when bun is available. Fall back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
+
+Renders are verification artifacts, not deliverables. They stay in `.claude/.tmp/diagrams/` and are never committed.
+
+When the render fails for any reason (no browser engine, no network, no package manager), continue to Step 7 and name the skipped check in the chat output. A missing renderer degrades the loop, it does not fail it.
+
+## Step 6: read the renders back
+
+Read each PNG and judge the picture against what the entry means to say. Apply the verification properties in the standard.
+
+Fix the source and re-render. Stop after two correction passes on an entry.
+
+When a defect survives, keep the entry and name the defect in the chat output. A diagram whose author states the flaw is recoverable. A wrong diagram reported as verified is not.
+
+### Stamp the marker
+
+Stamp every entry that passed. Set `verified` to the short SHA of `HEAD` and today's ISO date, and delete any `stale` key the entry carries:
+
+```bash
+git rev-parse --short HEAD
+```
+
+The result is one line, `<sha> <date>`, as in `73e9a3f8 2026-08-02`.
+
+Stamp nothing else. An entry Step 2 left alone was never re-checked, an entry whose defect survived is known wrong, and an entry whose render was skipped was never seen. All three keep the marker they already carry, and Step 7 names the last two. The field means a render was read back and judged correct, so stamping any of these spends the only signal a reader has on a diagram nobody confirmed.
+
+A migration pass stamps on the same rule. Conversion writes entries, Step 5 renders them, and this step reads them back, so the marker records the commit the split was checked against rather than the commit the flat file was written at.
+
+## Step 7: chat output
+
+```plaintext
+📝 Wrote N entries to .claude/diagrams/
+   .claude/diagrams/<kind>.md
+   <one line per entry written>
+
+Left untouched: <kind, kind> <omitted when the folder was empty>
+
+Verified N renders. <defect or skipped check, one line each, omitted when clean>
+
+Open in any viewer with native Mermaid support (VS Code with `bierner.markdown-mermaid`, GitHub, Cursor) to render. Ask to export if you want SVG or PNG files.
+```
+
+Emit the full path for every file written. Do not echo the diagram bodies in chat. Never report a clean verification when a render was skipped or a defect survived. Never report an entry as written when this pass left it alone.
+
+After a migration pass, add: `Converted .claude/DIAGRAMS.md into N entries. The original is untouched, delete it once you have compared the split against it.`
+
+## Step 8: export on request
+
+If the user asks to export the diagrams (`export to svg`, `give me images`, `render to png`), run:
+
+```bash
+mkdir -p .claude/review/diagrams && bunx -y @mermaid-js/mermaid-cli -i .claude/diagrams/<kind>.md -o .claude/review/diagrams/<kind>.png
+```
+
+Export PNG by default. Swap the extension for `.svg` only when the user asks for vector, and never for the Step 5 verification path. The CLI writes one file per `mermaid` block, suffixing when an entry holds more than one. Export every entry when the user names no kind. Output line:
+
+```plaintext
+📝 Wrote N files to .claude/review/diagrams/
+```

package/claude/skills/claude-docs/REQUIREMENT.md

@@ -0,0 +1,60 @@
+---
+name: claude-docs
+description: What the planning-doc reconcile is for, the gaps it closes, and why the diff decides completion alone
+---
+
+# Claude docs requirement
+
+## Gap
+
+Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. A requirement or architecture decision that changed mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
+
+A decision's verification anchor has the same shape of gap in the other direction. The reasoning keeps reading as current while the number it cites moves underneath, and an amendment written without an anchor leaves nothing recording which numbers were checked and which nobody has read since.
+
+A handoff file has the same shape of gap as an unmarked outcome. A page a learning workspace produced and an operator already picked a destination for sits in gitignored scratch until something lands it, and the session that produced it is gone by the time a branch exists to carry the write. Left unfolded it reads as promoted while the destination holds nothing.
+
+The receipt half of that sweep was missing entirely. A review receipt was deleted per shipped branch and a memory-review receipt was skipped, because the exclusion protecting the checklist and audit prefixes caught a third by accident. Nothing but an operator asking collected it, and a collection that waits on someone remembering to ask is one a folder outgrows, so the skipped population grew per shipped branch and never shrank until it was most of the folder.
+
+The trigger side carries a gap of its own. "Sync the docs" names either corpus to the person saying it, so a description leaving its corpus to the opening clause alone competes with its public-facing sibling on nothing the routing field states, and the planning surface the request was about goes untouched.
+
+## Must
+
+- Name the `.claude/` corpus in a trigger phrase rather than in the opening clause alone, so a bare request to sync the docs separates this skill from `docs-sync` on something both descriptions state
+- Take completion from the diff and everything else from the session, since completion is a fact about the repository rather than about the conversation
+- Match an outcome on the behavior it names, never on a filename or a commit subject
+- Leave an outcome unchecked when the diff is ambiguous. An unmarked shipped outcome costs one manual edit and a wrongly marked one hides work that never happened.
+- Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
+- Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
+- Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
+- Anchor a decision entry this run writes or amends whose reasoning cites a measured number, re-reading the number against the tree before writing the marker
+- Report an anchored decision whose cited path the diff touched, since the number was read before the branch moved what it counted
+- Scan every memory-review receipt rather than the one matching this slug, since the skill that writes them runs after this one in the ship chain and a slug is unique per feature
+- Collect a memory-review receipt whose items are all decided, folding each skip into its memory entry first, since a declined item is recorded nowhere else and a promoted one is already in git
+- Leave a memory-review receipt holding a pending item, and report the count. A branch shipping is not an operator deciding what the receipt proposed.
+- Leave the current branch's review receipt alone, since the chain that wrote it cites it in its own closing line and this skill cannot read whether that citation is still live
+- Land each block of a promotion handoff at the destination its heading names, then delete the file so a later run does not fold it twice
+- Take a promotion destination as already decided, since the operator confirmed it where the page was produced
+
+## Must not
+
+- Infer a new task from the diff. Only outcomes already on the board get marked.
+- Touch task files the session did not change, outside the board-wide plans sweep that exists to clear a missed archive
+- Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
+- Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
+- Create a context entry or delete a plan
+- Overwrite a file a promotion block routes to. A destination that already holds a page is a merge for a person, and folding over it discards work this skill never read.
+- Write an anchor onto a decision the run did not amend, or refresh one without re-reading the number. A date from a pass that measured nothing is the false confidence the marker exists to prevent.
+- Anchor an entry written before the rule, which dates it by blame rather than by a read
+
+## Guards
+
+- No `.claude/` directory: stop and name the command that sets one up
+- No session divergence and no queued outcome the diff shipped: stop with a pass, since both conditions have to hold
+
+## Out of scope
+
+- Creating a task file or moving one off the board, which `claude-tasks` owns
+- Public-facing docs, which `docs-sync` owns, apart from landing a page a promotion handoff already carries a confirmed destination for. This skill reconciles the `.claude/` planning surface, and both descriptions name their corpus in the trigger so a request saying only "sync the docs" lands on one of the pair rather than on either.
+- Deciding where a promoted page belongs, which is settled with the operator by the surface that produced the page
+- Regenerating the task index, owned by a hook
+- Re-measuring an architecture claim to decide whether its number moved. The sweep keys on a cited path entering the diff, so a claim whose number moved with no cited path in the diff goes unflagged.