@erclx/canon 4.0.0

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

@@ -0,0 +1,136 @@
+---
+name: claude-worktree
+description: Enters a Claude Code worktree at `.claude/worktrees/<name>/` with a name derived from the active plan or branch. Use when asked to "enter a worktree", "start a worktree", "work in a worktree", or at the plan-to-execute boundary after `/claude-feature`. Do NOT use to list, clean up, or rotate worktrees (use `git-worktree`).
+---
+
+# Claude worktree
+
+Wrap the `EnterWorktree` entry path with name derivation so the user does not pick a name by hand.
+
+## Guards
+
+- If `git rev-parse --git-dir` and `git rev-parse --git-common-dir` differ, the session is already inside a linked worktree. Stop: `❌ Already in a worktree. Run ExitWorktree first.`
+- If neither command resolves, the session is not in a git repo and no `WorktreeCreate` hook is configured. Stop: `❌ Not a git repository. EnterWorktree needs git or a WorktreeCreate hook.`
+- If the two match and `git rev-parse --show-superproject-working-tree` prints a path, the session is inside a submodule checkout. Stop: `❌ Inside a submodule of <path>. Run this from there instead.`
+
+The submodule guard sits on the matching branch rather than ahead of the first one, and a measurement decided that. Inside a submodule at git 2.43.0 both reads return the same absorbed path under the superproject's `.git/modules/`, so the first guard does not fire and the session proceeds. Every derivation below then reads the submodule as the project: Step 1 resolves the main root to the submodule, the plan lookup reads a `.claude/plans/` the project never wrote, and entry builds `.claude/worktrees/` inside a tree the superproject tracks as a commit. The superproject read is empty in a linked worktree of a submodule and in one of the superproject alike, which is why it separates the two states rather than qualifying the first guard.
+
+## Step 1: resolve the main worktree root
+
+Run in parallel:
+
+- `git worktree list --porcelain | awk '/^worktree /{print $2; exit}' 2>/dev/null || pwd`
+- `git branch --show-current 2>/dev/null || echo ""`
+- `git config --get core.bare 2>/dev/null || echo false`
+
+Plans always live at the main root, never inside a linked worktree. See Worktrees in `CLAUDE.md`.
+
+`EnterWorktree` writes `core.bare = true` into the shared config, and nothing restores it, so the repository can already be broken before this session arrives. Repair it before entering when the value is `true` and `<main-root>/.git` is a directory:
+
+```bash
+git config core.bare false
+```
+
+The directory test separates the defect from a genuinely bare repository, which keeps its objects at the root and has no `.git` directory. Announce the repair in one line naming the flag. Leave the file alone when the value is already `false`.
+
+## Step 2: derive the worktree name
+
+Try each source in order. Stop at the first match.
+
+0. **Caller-supplied.** The invocation carried an argument. Take it as the name and infer nothing further. Accept `<name>` or `<type>/<name>`, where a leading segment matching a type in `${CLAUDE_SKILL_DIR}/../../standards/branch.md` sets `<type>` and the rest is `<name>`. A bare `<name>` falls to the default type below.
+1. **Plan matched to current branch.** Derive `<slug>` per `${CLAUDE_SKILL_DIR}/../../standards/slug.md`. An empty result falls through to the next source here rather than becoming `latest`, since the slug is one candidate among several. If `<main-root>/.claude/plans/feature-<slug>.md` exists, use `<slug>`.
+2. **Single plan file.** List `<main-root>/.claude/plans/feature-*.md`. If exactly one match, derive `<slug>` from the filename.
+3. **Multiple plan files, no branch match.** Ask the user which plan. Show the candidate slugs as a numbered list. Do not pick.
+4. **Current branch.** When no plan exists, use the `<slug>` from step 1 if it is not `main` or `master`.
+   4b. **Session context.** When on `main` or `master` with no matching plan, read the current conversation to infer a kebab slug from the topic being discussed. Propose it: `Infer: <slug>. Confirm or rename?` Do not enter the worktree until the user confirms or provides a corrected name.
+5. **Ask.** None of the above applies. Ask the user for a name. Do not invent one.
+
+Tier 0 sits ahead of the inference because every tier below it answers from state the caller cannot set, and a caller that already knows the name has no way to say so. That gap is what a dispatched worker meets. It starts on `main`, so tier 1 cannot match, and a board carrying more than one plan puts tier 2 out of reach too, which lands the run on tier 3 and its instruction to ask somebody who is not there. A prompt naming the branch does not reach any of them, since no tier reads the prompt.
+
+Validate the result: letters, digits, dots, underscores, dashes only, max 64 chars (`/` separators are also allowed). If the derived name violates the rule, sanitize by replacing invalid chars with `-` and truncating. Show the sanitized name in the preview before invoking.
+
+Resolve `<type>` here as well, since Step 3 previews it and Step 5 renames onto it, drawing the value from the type vocabulary in `${CLAUDE_SKILL_DIR}/../../standards/branch.md`. A type the caller spelled in tier 0 wins outright and no reading overrides it. A name from a plan takes the type that plan's own work carries, read off its `## Summary` and `**Files to touch:**` lines. Every other case takes `feat`, which covers a name from a branch, a bare name from the user, and a plan whose lines settle nothing.
+
+The caller's type wins because reading it off a plan is the half that has already disagreed in production. One dispatch checked `fix/path-form-hook` and the worker took `feat/path-form-hook`, both sides reading the same plan and grading it differently.
+
+A wrong type is cheap. `git-branch` renames to conventional format later in the same chain and runs ahead of `git-pr`, so a `feat/` written over a fix is corrected before any pull request opens.
+
+Then test both names the entry is about to claim. Neither read needs a worktree, and a stop after Step 4 leaves one built with the session sitting inside it, so both belong here rather than beside the rename:
+
+- Branch. `git for-each-ref --format='%(refname)' refs/heads/<type>/<name> refs/remotes/origin/<type>/<name>` printing any ref means the name is taken. Stop: `❌ Branch <type>/<name> already exists. Resolve manually before continuing.` A non-zero exit is a read that failed rather than a free name, so stop on that too and say the read failed.
+- Directory. `<main-root>/.claude/worktrees/<name>/` existing means an earlier entry claimed the name. Stop: `❌ Worktree .claude/worktrees/<name>/ already exists. Resolve manually before continuing.`
+
+Leave both in place. Resolving either automatically risks the wrong one.
+
+The two tests catch different collisions. The branch test misses the one `${CLAUDE_SKILL_DIR}/../../standards/slug.md` records, where two branches differing only in type collapse onto one name: `feat/foo` and `fix/foo` are distinct refs and reach one directory. The directory test is the only read that sees it.
+
+The branch test fires on the tier 1 and tier 4 sources whenever the branch the session started on is already conventional, since a name derived from that branch resolves back onto it. Stopping is the answer there. The concern already has a branch, git refuses a second under the same name, and the bare-name rename this replaces only carried the collision forward to the `git-branch` step. It fires on tier 0 as well, where a caller handed a name something already holds.
+
+It reads both ref spaces rather than the local head alone, and it reads them the way `checkClaim` does, so a name this skill clears and a branch a dispatcher cleared are one answer. `git show-ref --verify` is what that replaces. It sees no remote-tracking ref, so a branch pushed from elsewhere passed the test and collided at the first push, and its exit code cannot separate an absent ref from a tree it could not read, which reports a failed read as a free name.
+
+## Step 3: preview
+
+Output exactly:
+
+```plaintext
+Worktree: .claude/worktrees/<name>/
+Branch:   <type>/<name>
+Source:   <plan|branch|user>
+```
+
+Step 2 resolved `<type>`. Show it, since it is the one part of the entry the user cannot read off the name they supplied.
+
+## Step 4: enter
+
+Call `EnterWorktree` with `name: "<name>"`. Claude Code's tool permission dialog is the confirmation gate. Do not pause for additional confirmation.
+
+## Step 5: align the branch name and repair the shared config
+
+`EnterWorktree` creates a branch named `worktree-<name>`, which diverges from `<name>` and breaks downstream slug derivation in `claude-autoship` and any skill that reads `git branch --show-current`. A bare `<name>` fixes that and fails the branch-format guard in `git-pr`, which requires `<type>/<description>`. Rename to the conventional form, which satisfies both:
+
+```bash
+git branch -m worktree-<name> <type>/<name>
+```
+
+The slug transform drops a leading type segment, so `<name>` is what every downstream derivation reads back out of the typed branch. See `${CLAUDE_SKILL_DIR}/../../standards/slug.md`.
+
+Step 2 already cleared the target name, so the rename runs unguarded here. Do not repeat the test. A ref created between the two points is a second session racing this one, which a re-read narrows rather than closes.
+
+Skip the rename if the worktree was entered via `path` rather than `name`, since the branch already exists under its own identity.
+
+Entry also sets `core.bare = true` in the shared config, which strands the main worktree. Every later command run there fails with `fatal: this operation must be run in a work tree` while the files sit untouched on disk. The linked worktree keeps working, so nothing surfaces until the operator returns to the main checkout. Repeat the Step 1 repair, which writes the parent's config even from inside the linked worktree:
+
+```bash
+git config core.bare false
+```
+
+The flag is not set on every entry, so read before writing and announce only when the write happened. Tracked upstream as `anthropics/claude-code#58345`, closed as not planned, so the repair stays until the tool changes.
+
+## Step 6: report whether the tree can run
+
+A linked worktree is a second working directory over one repository, and every ecosystem installs its dependencies into a folder git ignores. Nothing copies that folder across, so a fresh worktree arrives without it and the session learns as much from whichever command needs it first, which reports a missing module rather than an empty working directory.
+
+Report the state on one line. Do not install. Entering a worktree to read is as common as entering one to run, and an install is slow, needs a network, and picks an ecosystem on the session's behalf.
+
+Read the worktree root and emit the first line that matches:
+
+- `package.json` present, `node_modules/` missing: `Dependencies are not installed. Run <install> before any build, test, or server command.` Take `<install>` from the lockfile beside the manifest, and use `bun install` when no lockfile names one.
+- A `pyproject.toml` or `requirements.txt` present, `.venv/` missing: `No virtual environment. Create and populate one before running anything.`
+- A manifest present with its folder alongside it: `Dependencies are installed.`
+- No package manifest of either kind: `No package manifest, so there is nothing to install.`
+
+The last line is what keeps the step honest on a stack this skill cannot read. Entry is not stack-aware, and silence is indistinguishable from a check that passed.
+
+Then report the port this worktree derives, on a second line:
+
+- `scripts/worktree-port.sh` present and exiting zero: run `bash scripts/worktree-port.sh` and emit `Port offset <n>. Every served port adds it to the stack default.`
+- Present and exiting non-zero: emit `The port helper refuses this directory, so no server here has a port. <its stderr>`
+- Absent: `No port derivation installed, so every served port is the stack default.`
+
+Branch on the exit rather than on the output, since the helper prints nothing to stdout when it refuses and reading that as a number reports an offset of zero, which is the main checkout's.
+
+The helper refuses a folder left behind after its worktree was removed, which Step 4 cannot land on, since it registers whatever it creates. The branch is here so a refusal is never read back as an offset of zero, which is the main checkout's port and the collision the helper exists to prevent.
+
+The offset is what `claude-orchestrate` sends a reader here to read rather than assign, and what an operator overrides through `WORKTREE_PORT_OFFSET` when two worktrees derive the same value. Deriving it correctly and printing it nowhere leaves both instructions naming a number no surface emits.
+
+Do not invoke `ExitWorktree` from this skill. Exit is the user's call.

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

@@ -0,0 +1,45 @@
+---
+name: create-rule
+description: Why a project-local rule needs a subdir, a number from the band reserved for one, and a scope key that decides when it fires
+---
+
+# Create rule requirement
+
+## Gap
+
+Without this skill, a project rule is written straight into the rules folder on a number already taken, so two rules collide and one loses. The subtler collision was with the toolkit itself: a number free in the target today could be the number a shipped rule landed on tomorrow, and the next install double-booked it, so a rule the project wrote got overwritten by one it never chose. Writing under `.claude/rules/project/` closes that half regardless of the number, since the sync engine orphans the file by location before it ever compares names.
+
+Numbering in `900-999` closes the other half. A number scanned against today's toolkit catalog goes stale on the next release, and a reserved band does not.
+
+The subdir gets picked by feel, so a UI copy rule lands in the always-on folder and loads on every session for the rest of the project's life. The scope key fails in both directions. An always-on rule carrying a path scope fires only on files it was never about, and a path-scoped rule missing it loads constantly. Written from memory rather than from the rule standard, the body comes out in a shape the rest of the catalog does not share.
+
+## Must
+
+- Resolve what the rule enforces and where it applies, asking only for what the request leaves missing
+- Pick the subdir from the topic and take the folder from that choice
+- Write under `.claude/rules/project/`, the subfolder the sync engine reads as project-authored by location
+- Take the lowest free number at or above `900`, scanning every project subdir the target holds rather than one
+- Read the rule standard before writing the body
+- Emit the path scope for a path-scoped rule and omit the key entirely for an always-on one
+- Preview the resolved path, subdir, number, and frontmatter, then write without pausing
+- Say when the rule loads, since path-scoped and always-on rules behave differently
+
+## Must not
+
+- Edit a toolkit source rule, which is authored in the toolkit and would be overwritten here
+- Work the body shape or the frontmatter from memory
+- Take a number below `900`, which a later toolkit release can ship into
+- Write more than one topic into a single rule
+
+## Guards
+
+- No project Claude directory: stop, since there is nowhere for the rule to live
+- The request names no behavior to enforce: stop rather than inventing one
+- The reserved band holds no free number: stop rather than reaching below `900`
+
+## Out of scope
+
+- Editing a rule that already exists
+- Toolkit source rules, which are authored in the toolkit rather than in a target
+- Installing the rules the toolkit ships, which the governance setup path owns
+- A standard, which `create-standard` owns, and a snippet, which `create-snippet` owns

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

@@ -0,0 +1,68 @@
+---
+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/`.
+---
+
+# Create rule
+
+Author a project-local governance rule. The rule lives in the target project, not the toolkit, so `canon gov sync` never overwrites it: the sync engine orphans anything under `.claude/rules/project/` by location, before it ever checks the rule's name against the toolkit catalog. A rule written anywhere else under `.claude/rules/` survives the sync too, and the report offers it the path under the project subfolder it would take.
+
+## Guards
+
+- If no `.claude/` directory exists, stop: `❌ No .claude/ directory found. Run canon init first.`
+- If the request names no behavior to enforce, stop: `❌ Describe what the rule should enforce and which files it applies to.`
+
+## Step 1: gather intent
+
+Resolve both from the request, and ask only for what is missing. Attach a proposed default derived from the request.
+
+- What the rule enforces: one topic, phrased as a standard (`<topic> conventions`).
+- Scope: a path glob relative to the project root (`<dir>/**/*.<ext>`) for a path-scoped rule, or always-on when the rule states a global principle with no file scope.
+
+## Step 2: resolve the subdir
+
+Pick the subdir from the topic. It sits under `.claude/rules/project/` and names the rule's domain:
+
+- `core/`: global persona, testing, error handling, planning. Always-on, no `paths:`.
+- `lang/`: one programming language.
+- `framework/`: one framework.
+- `lib/`: one library or tool.
+- `ui/`: UI copy, accessibility, forms.
+- `claude/`: `.claude/` authoring surfaces.
+
+## Step 3: pick a free number
+
+A project-authored rule numbers in `900-999`, the band reserved for one. `000-899` belongs to the toolkit, so a number free in the target today is one a later release can ship into.
+
+- Scan every `.claude/rules/project/<subdir>/` in the target for used prefixes, not only the subdir this rule lands in. The band runs as one sequence across all of them.
+- Take the lowest unused number at or above `900`.
+- Stop and say so if the band is full, rather than reaching below `900`.
+
+## Step 4: write the rule
+
+Read `${CLAUDE_SKILL_DIR}/../../standards/rule.md` for frontmatter, body shape, and voice before writing the body. Do not work the shape from memory.
+
+Write `.claude/rules/project/<subdir>/<n>-<slug>.md` where `<slug>` is a 1-to-3-word kebab topic. Preview the resolved path, subdir, number, and frontmatter, then write immediately. The tool permission dialog is the confirmation gate.
+
+Frontmatter carries the Claude shape. Path-scoped rules emit one `paths:` entry per glob. Always-on rules omit `paths:` entirely.
+
+```markdown
+---
+description: <one line, what the rule enforces and where>
+paths:
+  - '<glob>'
+---
+
+# <Topic> standards
+
+## <Group>
+
+- <imperative rule>
+- <imperative rule>
+```
+
+Title casing is sentence case, with proper nouns keeping their own casing (`# TypeScript standards`). `${CLAUDE_SKILL_DIR}/../../standards/rule.md` owns the rest of the body shape.
+
+## 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.

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

@@ -0,0 +1,38 @@
+---
+name: create-skill
+description: What skill creation is for, the gaps it closes, and why it confirms before writing
+---
+
+# Create skill requirement
+
+## Gap
+
+Without this skill, a new skill lands in the wrong shape and the wrong place. A session writes `SKILL.md` from its own idea of the format, writes malformed frontmatter that Claude Code routes on, and never opens the authoring standard that already answers every question it guessed at.
+
+A skill born without its requirement is the second failure, and it surfaces much later. Coverage of the corpus is what the operator reads to decide whether a skill should exist, so every skill created without the sibling decays that reading, and the sweep that closes the gap has to reconstruct what the skill was for from the body it already shipped.
+
+A third failure is a folder created for a moment a rule, a verb, or an existing skill already reaches, or for a procedure no session would get wrong from first principles. Nothing caught that before the folder existed, so the corpus grew by a skill an inward audit later had to argue for removing, with only a commit body recording the argument.
+
+## Must
+
+- Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
+- Answer, in writing, whether a rule, a verb, or an existing skill already reaches this moment, and whether the body carries a procedure a session would get wrong from first principles. A folder that fails either belongs to the surface that already covers it, not to a new skill.
+- Draft the sibling `REQUIREMENT.md` beside the body, from what the skill is for rather than from the drafted body
+- Confirm the name and both files with the user before writing. The name is the routing key and a folder that disagrees with its frontmatter fails silently.
+- Write to the conventional skills path, so discovery finds it without configuration
+
+## Must not
+
+- Auto-trigger. Creation is a deliberate act and a skill invented from an ambiguous request is worse than none.
+- Write either file before the user has seen it
+- Derive the requirement from the drafted body, which records the draft's overfitting as the requirement
+- Gate creation on whether anything will invoke the new skill beyond the author typing its name. That question has no answer yet.
+
+## Guards
+
+- The authoring standard is not installed: stop and name the command that installs it
+
+## Out of scope
+
+- Editing an existing skill, which the authoring standard and the skill's own requirement govern
+- Whether anything ends up invoking the new skill: the usage census in `.claude/context/claude-plugin/skill-strategy.md`, read once the skill has run

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

@@ -0,0 +1,32 @@
+---
+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.
+disable-model-invocation: true
+---
+
+# Create skill
+
+Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/skill.md`: skill structure, skill types, frontmatter fields, invocation rules
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for skill body text
+- The `write-human` skill: voice, rhythm, and sentence construction for skill body text
+
+## Guards
+
+- If `${CLAUDE_SKILL_DIR}/../../standards/skill.md` is not present, stop: `❌ skill.md standard not found. Reinstall the canon plugin.`
+
+## Steps
+
+1. Answer three questions in writing before drafting anything. Tell the user and stop if a rule, a verb, or an existing skill already reaches this moment, or if the body carries no procedure a session would get wrong from first principles:
+   - Does a rule, a verb, or an existing skill already reach this moment? A folder that only wraps something already reachable duplicates it rather than adding to the catalog.
+   - Does the body carry a procedure a session would get wrong from first principles? A one-line wrapper around a single command needs no skill.
+   - Will anything invoke it other than the author typing its name? Carry this one into the drafted `REQUIREMENT.md`'s `Must not` section as a review criterion instead, since nothing can answer it before the skill has run.
+2. Draft the full `SKILL.md` from the user's description
+3. Draft the sibling `REQUIREMENT.md` from what the skill is for, in the shape the standard states. Write the gaps from the user's description rather than from the drafted body, since a requirement derived from the body records whatever the draft overfitted to.
+4. Confirm the skill name and both files with the user before writing
+5. Write to `.claude/skills/<name>/SKILL.md` and `.claude/skills/<name>/REQUIREMENT.md`
+
+Every skill carries a requirement. A skill created without one is a gap someone closes in a later sweep, and the sweep has to reconstruct what the skill was for from the body it already shipped.
+
+The two-question check has a shipped precedent. Pull request `#516` dropped `git-stash` for wrapping a single git command that needed no skill body, and `release-changelog` for being low-frequency and invoked by no other skill. The first is question one, and the second is question three read back after the fact, which is why it stays a review criterion rather than something this skill can gate on.

package/claude/skills/create-snippet/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: create-snippet
+description: Why a snippet needs its shape read from the reference and its write surface resolved before anything is drafted
+---
+
+# Create snippet requirement
+
+## Gap
+
+Without this skill, a snippet is drafted the way any other markdown file is drafted, so it arrives carrying frontmatter, headings, and a fill-in placeholder. None of the invocation channels strip those. Typing `>slug` in a chat inserts the scaffolding verbatim, and the file that was meant to be one instruction reads as a document.
+
+The write surface is the second failure. The toolkit authors at `snippets/` and a target project may still hold a stale `.claude/snippets/` copy from before that domain's install channel retired, so a session picks whichever folder it noticed first. A toolkit snippet written into the consumed copy fails the drift assertion that regenerates that folder. A snippet written there in a target project is correct and looks identical, which is why the surface has to be resolved from what the project has rather than guessed.
+
+Inside the project surface, a third failure sits one level deeper. A project-authored snippet sharing a name with a toolkit one used to be indistinguishable from it, back when `canon snippets sync` walked that folder and could not tell which side owned the file. That verb retired with the domain's install channel, so nothing reads ownership by location there any more, but the `project/` subfolder still separates the two by eye, which is worth keeping even with no sync left to protect from.
+
+## Must
+
+- Read the bundled snippet reference before drafting, since the shape rules are what the invocation channels depend on
+- Resolve the write surface from which snippet folder the project has, rather than from whichever one the session noticed first
+- On the project surface, write under its `project/` subfolder, keeping a project-authored file visually apart from a toolkit-installed one
+- Confirm the slug and the full body with the user before writing
+- Emit the written path in full, so the terminal can resolve it
+- State what the resolved surface implies after writing, since a root file needs the consumed copy regenerated and a project-local one needs copying to the toolkit to ship
+
+## Must not
+
+- Restate the snippet authoring conventions in the body, which the bundled reference owns and which would drift from it
+- Write a standard, which answers to a different authoring contract
+
+## Guards
+
+- Neither snippet folder exists: stop, since there is nowhere for the snippet to live
+
+## Out of scope
+
+- Editing a snippet that already exists
+- A standard, which `create-standard` owns
+- Installing and syncing the snippets the toolkit ships, which the `canon snippets` commands own
+- What a snippet is and how it is invoked, which the bundled snippet reference states

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

@@ -0,0 +1,30 @@
+---
+name: create-snippet
+description: Creates a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to "create a snippet", add a snippet, write a reusable prompt, or make a new snippet. Do NOT use to edit an existing snippet.
+---
+
+# Create snippet
+
+Creates one snippet file. Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+- `${CLAUDE_SKILL_DIR}/../../standards/snippets.md`: authoring conventions, invocation channels, use patterns
+
+## Guards
+
+- If neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
+
+## Steps
+
+1. Resolve the write surface: `snippets/` at the root if present, which is the toolkit's own authoring source. Otherwise `.claude/snippets/`, a stale copy a target project holds from before its install channel retired.
+2. Draft the content from the user's description. The snippet reference governs structure, invocation, and authoring conventions.
+3. Confirm the slug and full content with the user before writing
+4. Write the file. On the root surface: `<surface>/<category>/<slug>.md`, or `<surface>/<slug>.md` when the snippet takes no category. On the `.claude/` surface: the same shape nested one level deeper under `project/`, a convention kept for its own sake now that nothing syncs that folder.
+
+## After writing
+
+Emit the full path on its own line.
+
+- Root surface: this is the toolkit's authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`.
+- `.claude/` surface: the file is project-local, under `.claude/snippets/project/`. Remind the user to copy it to the toolkit repo, under `snippets/<category>/<name>.md`, if it should ship to every project.

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

@@ -0,0 +1,35 @@
+---
+name: create-standard
+description: Why a standard needs its shape read from the meta-standard before anything is drafted, and why the follow-up depends on who owns the folder it landed in
+---
+
+# Create standard requirement
+
+## Gap
+
+Without this skill, a standard is written from memory of what other standards look like. It arrives without the scope section that says what the file does not govern, so the next author cannot tell whether a rule belongs to it or to a sibling, and two standards end up claiming the same subject with no way to settle which one wins.
+
+The second write surface is the second failure. A standard put under `.claude/standards/` looks like a correct file and reaches no resolver, since nothing installs the corpus into a project and no repository generates a copy there. One write surface removes the choice: `standards/` is what the resolver reads first and what every author writes to, in the toolkit and in a project alike.
+
+A standard written and left there is the third. The index entry and the context table are both generated or maintained downstream of the write, so a file that ships without them is catalogued nowhere and reached only by whoever already knew the path.
+
+## Must
+
+- Read the meta-standard before drafting, since the shape is what makes the file arguable against a sibling
+- Write to `standards/`, creating it when absent, since it is the one root the resolver reads and the only surface either kind of author has
+- Confirm the slug and the full body with the user before writing
+- Emit the written path in full, so the terminal can resolve it
+- State what the write implies for whoever owns the folder, since a toolkit standard needs the index regenerated and a project-local one needs copying to the toolkit to ship
+
+## Must not
+
+- Work the standard's shape or frontmatter from memory
+- Write a snippet, which carries no frontmatter and answers to a different authoring contract
+- Write into `.claude/standards/`, which no repository generates and no resolver reads
+
+## Out of scope
+
+- Editing a standard that already exists
+- A snippet, which `create-snippet` owns
+- A path-scoped coding rule, which `create-rule` owns
+- Reading a standard the toolkit ships, which `canon standards <name>` owns

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

@@ -0,0 +1,29 @@
+---
+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.
+---
+
+# Create standard
+
+Creates one standard file. Read these files in parallel:
+
+- `${CLAUDE_SKILL_DIR}/../../standards/markdown.md`: banned words, punctuation, and formatting for all generated text
+- The `write-human` skill: voice, rhythm, and sentence construction for all generated text
+- `${CLAUDE_SKILL_DIR}/../../standards/standard.md`: the meta-standard for shape, frontmatter, and structure
+
+## Steps
+
+1. Draft the content from the user's description. The meta-standard governs frontmatter, headings, and structure.
+2. Confirm the slug and full content with the user before writing
+3. Write the file to `standards/<slug>.md`, creating the folder when it is absent
+
+`standards/` is the one write surface. It is the toolkit's authoring source in this repository and a project's own folder anywhere else, and both are the root `canon standards <name>` resolves against first. No corpus installs into a project, so there is no second surface to pick between and no guard on a folder the skill can create itself.
+
+## After writing
+
+Emit the full path on its own line.
+
+- In the toolkit: this is the authoring source. Remind the user to run `bun run check` to regenerate the consumed copy under `.claude/`. That pass also regenerates the `standards/index.md` entry, and the user adds a row to the standards table in `.claude/context/standards/overview.md`.
+- In a project: the file is project-local and no toolkit command touches it. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md`, if it should ship to every project.
+
+Separate the two by whether the folder already held toolkit-authored standards before this write, since a project authoring its own uses the same path.

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

@@ -0,0 +1,45 @@
+---
+name: decision-escalate
+description: Scope boundary for handing a decision back to the operator, and the batching contract that keeps the handoff to one turn
+---
+
+# Decision escalate requirement
+
+## Gap
+
+Without this skill, a session facing a decision that belongs to the operator asks about it one question at a time across several turns, so the operator answers each without knowing how many are open and cannot trade one against another. It asks in prose with no options attached, so the operator has to invent the alternatives before picking one. It names an option and omits what the other one buys, so the pick is made blind. It escalates a call it could have settled from the repository or from its own judgment, which spends the operator's attention on work the session owed.
+
+It also empties a long backlog into one turn, so the questions past the first few arrive in no order and the operator cannot tell which ones the work is actually stalled on. It carries on with work the unanswered questions govern, so an answer arrives against output already built the other way. It takes the answer, acts, and leaves the plan, task, or record that posed the question reading as open, so the next session re-asks a decision the operator already made.
+
+A body written around a named tool fails a third way. A session on a surface carrying no structured question tool reads an instruction it cannot execute and falls back to whatever it would have done unaided, which is the per-decision ask this file exists against.
+
+The opposite failure is the one that ships silently. A session that takes a preference decision itself produces work the operator did not ask for and never learns a choice was made, because nothing in the output says a fork was passed.
+
+`CLAUDE.md` states both branches of the rule, sending an ordinary judgment call to a pick with the tradeoff in one sentence and a preference-deciding call to the operator. The first branch has the toolkit's `snippets/decision-help.md` behind it, which installs into a project that took snippets as `.claude/snippets/decision-help.md`. The second branch now states how a question is shaped and where it is put, so this skill inherits both and adds only what a batch needs on top of one question.
+
+## Must
+
+- Collect every open decision before asking any of them, so the operator sees the set rather than the first one
+- Put the whole batch in one turn, since a batch split across turns is the per-decision ask this skill exists to replace
+- Give each question a short axis header and two to four options, taking the shape of an option from `CLAUDE.md` rather than restating it
+- Test the surface rather than the project's instruction file when choosing where the batch goes, so a target whose `CLAUDE.md` predates the rule still reaches the tool and loses only the shape
+- Cap a batch at four questions and say how many are held, since a structured question tool takes four and an uncapped batch hides the overflow
+- Hold every escalated decision until it is answered, and continue only the work depending on none of them
+- Route a pick that changes a written artifact into that artifact under the standard owning it, rather than leaving it in the session
+
+## Must not
+
+- Answer on the operator's behalf, or treat the recommendation as the answer because no reply arrived
+- Escalate a decision the session can settle from its own judgment or from reading the repository, which is the first branch of the rule and belongs to the session
+- Escalate a decision already taken, which goes to the record that holds it rather than back to the operator
+
+## Guards
+
+- Nothing open, stop rather than manufacturing a question to justify the invocation
+
+## Out of scope
+
+- Making the ordinary judgment call, which is a pick plus a one-sentence tradeoff and needs no surface
+- The chat-side pick with no repository behind it, which the toolkit's `snippets/decision-help.md` covers and reaches a different reader
+- Writing the decision into a plan, task, or architecture record, which each owning standard governs and this skill only routes to
+- Deciding when to fire. The skill is user-invoked through `disable-model-invocation`, so escalating is the operator's call rather than a description match.

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

@@ -0,0 +1,79 @@
+---
+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
+---
+
+# Decision escalate
+
+Put every open decision that belongs to the operator as one batch, each carrying its options and a recommended default, then stop until the batch is answered.
+
+One batch is the whole point. A session that asks one question, acts, then asks the next spends the operator's attention once per decision and hides how many are open.
+
+## Guards
+
+- If nothing is open, stop: `❌ Nothing to escalate. Every open call is one this session can make.`
+- Escalate only a decision whose answer turns on the operator's preference. A judgment call with two or three reasonable options the session can weigh is a pick with the tradeoff stated in one sentence, taken without asking.
+- Escalate only what is open now. A decision already taken this session goes to the artifact that records it rather than back to the operator.
+- Do not act on any decision in the batch before it is answered. Continue the work that depends on none of them.
+- Do not escalate a question the session can answer by reading the repository. Read first, and escalate what the tree does not settle.
+
+## Step 1: collect what is open
+
+Sweep the session for every decision still unmade. The usual sources:
+
+- A plan question whose answer turns on preference rather than measurement
+- A fork the session parked to keep moving, where both branches still ship
+- A default the session took silently that changes what the operator receives
+- A scope boundary the request left ambiguous, where the two readings produce different work
+
+Drop anything the session can settle. What survives is the batch.
+
+## Step 2: shape each question
+
+Each entry carries a short header naming the axis, the question itself, and two to four options. `CLAUDE.md` states what an option carries and how the set is ranked, so follow it rather than a second copy here. The header is what a batch adds. An operator scanning four questions needs an axis on each to tell one from the next.
+
+Cap the batch at four. A structured question tool takes four, and a batch past that is a session asking to be redesigned rather than answered. When more than four are open, send the four blocking the most work and say in one line how many are held.
+
+## Step 3: put the batch
+
+Put every question in one turn. Never split the batch across turns and never ask the first while the rest stay unstated.
+
+Send the batch through a structured question tool wherever the session runs on one, and write the shape below where it does not. What a batch adds is that one call carries the whole set, with one entry per decision, so the operator answers them together instead of one per turn.
+
+The test is the surface rather than the project's instruction file. A target scaffolded before the rule shipped still reaches the tool, and what it loses is the option shape `CLAUDE.md` states, which the example below carries instead.
+
+Batch shape on the fallback surface:
+
+```plaintext
+<N> open decisions. <M> held.
+
+1. <axis>: <question>
+   a. <option> (recommended): <what it means>, <what it costs>
+   b. <option>: <what it means>, <what it costs>
+
+2. <axis>: <question>
+   a. <option> (recommended): <what it means>, <what it costs>
+   b. <option>: <what it means>, <what it costs>
+```
+
+## Step 4: wait
+
+Stop after the batch. Do not answer on the operator's behalf, do not act on the recommendation because it is the recommendation, and do not fill the wait with work the batch would invalidate.
+
+An operator who answers some and not others has answered those. Continue on the answered ones and hold the rest.
+
+## Step 5: record and continue
+
+Restate each pick in one line, then continue the work.
+
+A pick that changes a written artifact goes into that artifact under the rule its own standard sets. An answer to an open plan question rewrites that question's `- Suggested:` line to the pick and names the operator as its source, leaving the `- Answer:` slot blank, per `${CLAUDE_SKILL_DIR}/../../standards/plan.md`. The standard bars a session from filling that slot even when the operator supplied the pick, and the blank slot resolves to the rewritten suggestion, so the record carries the operator's decision either way. A pick that settles nothing written stays in the session.
+
+Output after the answers land:
+
+```plaintext
+✅ <N> decisions answered
+<axis>: <pick>
+<axis>: <pick>
+<M held, restated in one line each>
+```