@erclx/canon 4.0.0

package/standards/skill.md

@@ -0,0 +1,300 @@
+---
+title: Claude skill reference
+description: Claude skill structure and authoring rules
+---
+
+# Claude skill reference
+
+## Overview
+
+Skills give Claude Code domain-specific constraints and rules inline, so it can act immediately without reading all docs. Each skill body contains actionable rules for its domain. Full reference docs are the fallback for edge cases and deeper context. Skills use progressive disclosure: Claude reads only frontmatter at session start (~100 tokens each), matches a query against descriptions, then loads the full skill body.
+
+## Scope
+
+Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its siblings `REQUIREMENT.md` and `EVAL.md`, and the bundled reference, script, and asset folders beside them.
+
+Does not govern:
+
+- Path-scoped coding rules, which load on a file match rather than on a request match: `rule.md`
+- Single-purpose chat prompts carrying no frontmatter, references, or scripts: `snippets.md`
+- Voice, rhythm, and sentence construction in a skill body: the `write-human` skill
+- Punctuation, formatting, and word choice in a skill body: `markdown.md`
+- The transform from a branch name to a slug a skill carries in a filename: `slug.md`
+- The domain conventions a skill cites, each of which belongs to the standard that owns it
+- Whether a new skill earns its place: the three-question test in the `create-skill` skill and the clause in `570-skill.md`
+
+## Changing a skill
+
+Answer all four before editing, and carry the answers into wherever the change is proposed.
+
+- What problem does this solve? Name the run that went wrong, rather than the improvement the change makes.
+- Which surface owns the rule today? A rule already stated in a standard, a governance rule, or a sibling skill is cited or moved, never restated in the body.
+- What deterministic check catches a regression? Name it, or say none exists and the step holds on a session reading it.
+- What does this collide with? Name the sibling skill, rule, or requirement it contradicts, or state that nothing does.
+
+The second question is the one that decides between a body and a rule, which the next section tests in two parts.
+
+## Whether a rule belongs beside the skill
+
+A skill fires when a session invokes it or its description matches the request. A path-scoped rule fires when a session reads a file matching its glob, with no decision from the session at all. The two are layers rather than alternatives, so the rule is the floor and the skill is the depth.
+
+Run the two-part test over what the body states before calling the skill finished. Does the invariant fire when a specific path is edited, and does violating it ship silently? An invariant passing both halves belongs in a rule as well, because a session that never invoked the skill still edits that path and needs the floor under it. An invariant failing either half stays here, which is most of a body, since procedure and orientation are what a rule cannot carry.
+
+Write that rule to the shape `rule.md` sets and leave the procedure here, since the two carry one invariant at two depths rather than two copies of it. Nothing checks the split. The checkpoint is a judgment prompt rather than an invariant, so it ships as prose with no gate behind it, and a skill that skips it fails silently in the same way the invariants it is meant to catch do.
+
+## Skill types
+
+Pick the type before writing. It decides the body shape.
+
+- Reference: conventions, patterns, and domain knowledge Claude applies inline. The body is rule bullets grouped by concern.
+- Task: step-by-step workflows Claude executes as actions. The body is numbered steps plus the rules constraining them.
+
+Reference template:
+
+```markdown
+---
+name: <skill-name>
+description: <what it does, when to use it, trigger phrases>
+---
+
+# <Topic>
+
+## <Concern group>
+
+- <actionable constraint>
+- <preference in X over Y form>
+```
+
+Task template:
+
+```markdown
+---
+name: <skill-name>
+description: <the action and when to use it>
+allowed-tools: <tools required>
+---
+
+# <Action name>
+
+## Steps
+
+1. <action>
+2. <action>
+
+## Rules
+
+- <constraint on how the steps run>
+- <constraint on output format>
+```
+
+## Structure
+
+- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `EVAL.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- Name a file sitting directly in the skill folder in capitals and a bundled folder in lowercase, so the parts a reader opens are distinct from the ones a skill loads
+- `EVAL.md` holds prompts and a judging rubric a person runs by hand, which is the path open to everyone. `claude plugin eval` is the automated one and it is gated in early access, refusing before it parses a target, so write the hand-run rubric and know that the runner exists rather than that it does not
+- `SKILL.md` must start with YAML frontmatter between `---` delimiters
+- No `README.md` inside the skill folder
+- No spaces, capitals, or underscores in folder or skill name
+
+## Requirement
+
+`REQUIREMENT.md` states what a skill is for, so a proposed change can be argued against something and the corpus can be read to decide whether a skill should exist at all. This standard governs shape across the corpus and the requirement governs scope and behavior for one skill. Claude Code loads `SKILL.md` as the entry and ignores the sibling, so the file costs a target session nothing.
+
+The file serves a second purpose beside the argument. A skill body is procedural by design, so what the skill is for sits spread across its steps rather than stated in one place. The requirement is the compressed statement a reader gets before opening the body, and that purpose holds whether or not the skill's scope is contested.
+
+Read it before editing the skill. When a change closes no gap the requirement states, change the requirement first or drop the change.
+
+Write the gaps from what the skill is for, then compare the body against them. Deriving the requirement from the body is circular, because a requirement reverse-engineered from an overfitted skill records the overfitting as the requirement. That failure costs more under the orientation purpose than under the argument one, since a file summarizing the body misinforms whoever reads it in place of the body rather than merely failing to gate a change.
+
+Every skill carries one. Coverage was selective while the file existed only to disambiguate a contested boundary, and a file present for some skills and absent for others cannot be scanned, because an absence reads as a gap rather than as a verdict. A skill whose scope nobody contests still owes the statement, since the reader deciding whether a skill should exist reads the corpus rather than one entry. A new skill is created with the sibling beside it rather than acquiring one in a later sweep.
+
+### What a working requirement looks like
+
+A requirement works when a proposed change to the skill can be settled by reading it alone, without re-deriving what the skill is for:
+
+- Does this change close a gap the file states?
+- Does a line already in the body trace to one of those gaps?
+- Does this behavior belong to this skill or to a sibling the file names?
+
+A requirement that leaves any of the three open is non-conforming regardless of whether it satisfies every shape rule below. The third question is what makes a requirement worth more than a restated description, because a boundary stated only in prose is never checked against the skill on the other side of it.
+
+- State each gap as an observed failure, not an intent. "Without this skill a session invents its own filename" can be shown wrong. "This skill helps manage tasks" cannot fail, so it constrains nothing.
+- Trace everything under `## Must` to a stated gap. A `Must` with no gap behind it is the padding the file exists to prevent.
+- Keep it high level. A requirement that outgrows one file has stopped being a requirement, and `references/` already holds detail.
+- Use `name` and `description` frontmatter, matching `SKILL.md` so the pair is consistent.
+
+```markdown
+---
+name: <skill-name>
+description: <one line, distinct from the SKILL.md description>
+---
+
+# <Skill name> requirement
+
+## Gap
+
+Without this skill, a session <observed failure>, <observed failure>.
+
+## Must
+
+- <behavior that closes a named gap>
+
+## Must not
+
+- <behavior that would be wrong even though it closes a gap>
+
+## Guards
+
+- <the refusal condition and its message>
+
+## Out of scope
+
+- <the adjacent thing this deliberately does not cover, and what covers it>
+```
+
+## Frontmatter
+
+- `name` (required): kebab-case, matches folder name, no spaces or capitals
+- `description` (required): what it does + when to use it, under 1024 chars, no XML tags
+- `disable-model-invocation: true`: user-invoked only, Claude will not auto-trigger
+- `allowed-tools`: restrict tool access when the skill is active
+- `metadata`: optional key-value pairs (`author`, `version`, `mcp-server`)
+
+## Description
+
+- Structure: `[What it does] + [When to use it] + [Key trigger phrases]`
+- Include specific phrases users would say to trigger it
+- Be specific, not vague. Claude routes based on this field alone.
+- Add negative triggers if skill is over-triggering: `Do NOT use for X`
+
+## Body
+
+### Voice and headings
+
+- Use imperative voice throughout
+- Use sentence case for all headings (H1, H2, H3)
+
+### Rule content and scope
+
+- Front-load critical instructions
+- Contain only behavioral rules (what to do, what not to do) and pointers to reference docs. Narrative descriptions of what files are or how the system works belong in `docs/`, not in the skill body.
+- State rules, not inventories. Reference docs for lists that change, and phrase a rule as a ban on the forbidden shape rather than an enumeration of allowed options, so it stays stable as categories change.
+- Cut any rule that resists crisp one-line phrasing. Vague guidance is worse than none.
+- Group bullets under H2 headings by domain concern. Keep dos and don'ts together under the topic they belong to rather than splitting them into flat rules and constraints sections.
+- One actionable constraint per bullet. Prefer the `X over Y` form for preferences.
+- Do not include code examples unless a one to three line inline snippet captures a pattern the model cannot infer.
+- Do not duplicate general knowledge the model already has. Focus on project-specific conventions and preferences.
+
+### Progressive disclosure
+
+- Look at a body once it passes 150 lines. The number prompts a look rather than gating a build, so nothing enforces it and a body carrying nothing but procedure stays whole at any length.
+- Move a catalog, a table of cases, or a format spec running past roughly 15 lines to `references/`. Procedure prose stays, since a session sent to a reference for its own steps pays two reads for one job.
+- Name the branch that skips a block before moving it. Body lines are paid on every invocation and a reference only when the body sends the session to it, so a block every run dereferences costs a read and saves nothing.
+- Keep the trigger, the skip condition, and the guard in the body. A run that never reaches the block has to decide that without opening the reference.
+- Never point one skill at a sibling skill's folder for a reference both read. Each skill carries its own copy under `references/`, generated rather than hand-copied by the rule in `## Path resolution`.
+- Use progressive disclosure: `SKILL.md` for core instructions, `references/` for detail, `scripts/` for deterministic operations
+- Link to `references/` files explicitly so Claude knows to load them
+
+### Reading and running commands
+
+- Reference a bundled `references/` or `scripts/` file with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path. A bare path resolves against the session cwd and fails when a plugin skill runs from another project. `${CLAUDE_SKILL_DIR}` expands to the skill's own directory at render time and resolves from any cwd.
+- When referencing project files, include "from the project root" in the read instruction
+- When executing multiple independent operations (file reads, shell commands), run them in parallel to reduce latency
+
+### Anti-patterns to avoid
+
+- Avoid flags that dispatch between alternate flows. The model misreads them and runs the vanilla path. Dry-run-style toggles are fine. For alternate flows, prefer a separate skill or manual invocation of two skills in sequence.
+- When a skill should fire from multiple callers, rely on description matching with strong trigger phrases. Do not hardcode `Skill` calls in sibling skills that could trigger it naturally.
+- Before collapsing a manual multi-step flow into a skill, ask what the manual pauses do. Pauses that carry external timing, error-surfacing, or judgment weight are the feature. Prefer a snippet over a skill, or require explicit per-step confirmation.
+
+### Output and tuning
+
+- Skill success lines emit the full relative path from the project root (`<dir>/<file>`) for any file written, updated, or deleted. A bare filename names a file the reader cannot open. The `## Output` section of the project's instruction file sets the form that path takes, so a skill body states which path is emitted and leaves the form to that section.
+- Codify a skill's posted or generated output as a fenced template, and keep the body consistent with every capability the frontmatter description names.
+- When a skill gathers user input or pre-seeds a template, attach a concrete proposed default to every question, derived from project context. Accept "use defaults" as a bulk-confirm.
+- Separate correctness axes (routing, sourcing, escalation, decline) from shape axes (line count, formatting, variant sprawl) when tuning a skill. Tighten only on correctness regressions. Do not convert soft caps to hard caps for aesthetic drift when correctness passes.
+
+## Scripts
+
+- Use `scripts/` for operations that must be deterministic or repetitive
+- Claude executes scripts and receives stdout. Scripts are not loaded into context.
+- Use XML tags in script output for reliable parsing: `<SECTION>content</SECTION>`
+- Use `#!/usr/bin/env bash` shebang
+- Always include `2>/dev/null || echo "FALLBACK"` guards on git and shell commands
+
+## Path resolution
+
+A skill reads from two roots. Know which one a file lives under before referencing it.
+
+- Bundled skill assets (`references/`, `scripts/`, `assets/`) resolve against the skill's own directory in the source clone. Reference them with `${CLAUDE_SKILL_DIR}/<path>`, never a bare relative path, so a plugin skill running from another project still finds them.
+- Installed shared docs (`.claude/rules/`, `.claude/context/`) resolve against the target project cwd, where install placed them. Reference them by that path.
+- Do not hand-copy a standard into a skill. A hand-copied file drifts from its source and belongs to no owner. If a skill must carry its own copy, generate it from the single source and reference it through `${CLAUDE_SKILL_DIR}`, so one owner keeps every copy in sync.
+
+### Citing a standard
+
+No standard installs into a project, so a body cites one place rather than choosing between two.
+
+- Cite `${CLAUDE_SKILL_DIR}/../../standards/X.md`. The plugin ships the whole standards folder beside `skills/`, so the path resolves in every install and needs no fallback behind it.
+- Never cite `.claude/standards/X.md` from a shipped body. A target holds no such folder, and one left behind by an older toolkit is a stale copy no resolver reads. <!-- audit-ignore-citations: .claude/standards/X.md -->
+- Name `canon standards X` instead where the body wants the document rather than a path to open, such as a value it captures or reports. That verb resolves `standards/` at the project root and then the corpus inside the package.
+- State the path once per body, at the site that reads the standard. A later mention of a standard the body already read stays bare, since repeating the path at every mention is noise rather than instruction.
+- A guard on a standard's presence names the file rather than the folder holding it, since a folder test answers for a sibling that happens to be there.
+- Use `${CLAUDE_SKILL_DIR}`, never a bare `../../` and never `${CLAUDE_PLUGIN_ROOT}`. Only `${CLAUDE_SKILL_DIR}` is expanded before the body reaches the model. The other two leave the model to infer a base path, which it may resolve against the session cwd instead.
+- Cite a shared procedure, never restate it. A procedure two or more skills execute gets one definition in a standard and a citation in each body. Nothing catches a restatement that drifts, because the drift assertion covers generated copies and a hand-written one is not generated, so the guarantee is only that a single definition exists to correct.
+- Keep the trigger in the body and the procedure in the standard. The citing skill states when the procedure runs and what it runs against, since that varies per skill and the standard cannot know it.
+
+## Invocation
+
+- Skills auto-trigger when Claude matches the request against the description
+- Invoke manually with `/skill-name` or `/<plugin>:skill-name` for plugin skills
+- Plugin skills are namespaced: `plugin-name:skill-name`
+- Priority order when names conflict: enterprise > personal > project > plugin
+
+## Execution
+
+- Task skills with preview+execute patterns must execute commands immediately after outputting the preview. Do not include "confirm before running" language or pause for user input.
+- Claude Code's tool permission dialog is the confirmation gate. The user hits Enter to approve or Escape to interrupt and revise.
+
+## Examples
+
+### Correct
+
+```markdown
+---
+name: code-review
+description: Reviews code for bugs, clarity, and standards compliance. Use when asking to review code, check a PR, or asking "does this look right".
+---
+
+# Code review
+
+Before reviewing, read from the project root:
+
+- `CLAUDE.md`: project conventions and behavior rules
+- `.claude/rules/`: path-scoped coding rules
+
+## Guards
+
+- If no file or diff is provided, stop: `❌ No code to review. Provide a file or diff.`
+
+## Response format
+
+- **Issues found:** <count>
+- **Summary:** <one line>
+
+List each issue with file, line, and suggested fix.
+```
+
+### Incorrect
+
+```markdown
+---
+name: code-review
+description: Handles all code-related tasks in scripts/, src/, and lib/. Also activate when user mentions bugs, refactoring, testing, linting, formatting, or any file ending in .ts .js .py .sh. # path-focused + keyword-stuffed
+---
+
+# Code review
+
+A good code review should check for bugs, performance issues, security vulnerabilities,
+code style, naming conventions, test coverage, documentation, error handling,
+edge cases, and adherence to SOLID principles... # dumps everything inline instead of referencing standards
+```

package/standards/slug.md

@@ -0,0 +1,39 @@
+---
+title: Slug reference
+description: Transform from a git branch name to a slug, and the three responses to an empty result
+---
+
+# Slug reference
+
+## Scope
+
+Governs the transform from a git branch name to the slug a surface carries in a derived name, and the responses available when the transform returns empty. It is an attribute standard rather than a document-type one, so it applies wherever a branch-derived name is produced, and it carries no template because a string has no document to shape.
+
+Does not govern:
+
+- The format of the branch name the transform reads: `branch.md`
+- Where a surface writes what it names with the slug, and what goes in it, which is that surface's own subject
+
+## The transform
+
+Run `git branch --show-current`. Drop a leading segment naming one of the types `branch.md` defines when a further segment follows it, then replace every remaining `/` with `-`. The result is `<slug>`. Anything reading a branch-derived name uses this transform, so two surfaces cannot spell it differently.
+
+The type comes off because a plan takes its slug from the concern it covers and the branch executing that plan carries the same slug behind a type prefix. Keeping the prefix sends every surface that finds a plan from a branch name looking for `feat-jwt-expiration`, which no plan is filed under. A first segment matching no type stays, so `spike/parser` still yields `spike-parser`.
+
+A surface that persists output to a shared folder carries the slug in the filename, which is what keeps parallel worktrees from overwriting each other's output. Two branches differing only in type collapse onto one slug. That collision reaches the worktree directory as well, since it takes its name from the same string, so the branch is not where it would first surface.
+
+## An empty result
+
+The empty result is a detached HEAD, and the surface picks one of three responses rather than inheriting a default. State the choice where the transform is cited, since the transform is shared and this is not.
+
+- Fall back to `latest`, so a read-only pass still writes somewhere predictable
+- Stop, when the surface commits or opens a pull request. There is no branch to put the work on, so `latest` would bury the problem instead of reporting it. State the stop in the surface's guards.
+- Fall through to the next source, when the slug is one candidate among several rather than the name of an output file
+
+## Changing the transform
+
+A change here moves what the transform produces, and every declaration asserting the old output keeps asserting it. Nothing reports those, because a fixture carrying an old filename names neither this file nor the surface that reads it, so a diff over the change reaches none of them. Dropping the type segment is the change that proved it: four fixtures and three scenario scripts kept the type-carrying spelling, one surfaced as a red arm months later, and the other six were found by deriving from the rule.
+
+Run `canon gov superseded <old> <new>` in the same change, with the old output and the new one as the two arguments. The value is the only key both sides carry, and the sweep reads the whole tracked tree rather than a path someone predicted. Its output is a reading rather than a verdict, since a string appears for reasons unrelated to any convention, and a declaration disagreeing on purpose carries a `canon-allow-superseded: <reason>` marker on its own line or the one above.
+
+The sweep sees a value and nothing else. A prose reference that went stale without carrying it, such as a passage citing the wrong standard for the transform, is reached by reading rather than by any key.

package/standards/snippets.md

@@ -0,0 +1,76 @@
+---
+title: Snippet reference
+description: Snippet reference and authoring conventions
+---
+
+# Snippet reference
+
+## Scope
+
+Governs a snippet file: what one is for, whether a prompt qualifies as one, how it is invoked, and the structure of its body.
+
+Does not govern:
+
+- Skill folders, which carry frontmatter, references, and scripts a snippet has none of: `skill.md`
+- Voice, rhythm, and sentence construction in snippet prose: the `write-human` skill
+- Punctuation, formatting, and word choice in snippet prose: `markdown.md`
+
+## What a snippet is
+
+A snippet is a short, focused prompt stored as a plain markdown file. Invoke one to insert a prepared instruction into any AI chat without retyping it. Each snippet covers one purpose. If a prompt needs headers or multiple goals, use a system prompt instead.
+
+## Admission
+
+Two tests decide whether a prompt becomes a snippet, and both have to pass. Apply them when adding one and when auditing the catalog.
+
+- Cadence: a prompt invoked many times across sessions qualifies. A one-shot audit, migration, or bootstrap prompt does not, and belongs in notes outside the catalog.
+- Audience: a prompt the consuming project would invoke ships in `snippets/`. One only the authoring repository can run stays outside every installable folder, which is a rule for a repository that authors snippets for others rather than for one that only consumes them.
+
+A subfolder under `snippets/` names where a prompt is invoked rather than what it is about. A prompt that reads or writes the project's own files goes in a folder, and one carrying its whole context in the message goes at the root.
+
+Overlapping a skill that does the same job is not disqualifying on its own. A snippet fires when a person asks for it by name and a skill fires on a description match, so the two coexist when those paths differ and the outputs do. Record the reason where the project keeps its decisions, or drop the snippet.
+
+## Invocation channels
+
+- Chrome extension: type `>slug` in a supported chat UI (claude.ai, gemini.google.com) to insert the snippet text inline
+- Claude Code terminal: prefix the plugin path with `@` (e.g. `@claude/snippets/claude/feature-recap`). `claude/snippets` is a symlink to the authoring root, so the folder a snippet is written in is the folder it is invoked from
+
+## Use patterns
+
+- Run-as-is: invoke and send immediately. The snippet is self-contained and needs no extra context.
+- Invoke-then-add-context: invoke the snippet, then append specifics in the same message (e.g. invoke `claude-feature`, then add the feature name or extra constraints)
+- Invoke-on-history: invoke after a discussion. The snippet uses prior conversation as implicit context with no additional input needed (e.g. invoke `claude-figma` after discussing a design).
+
+## Authoring
+
+- One focused purpose per snippet. If it needs headers or multiple goals, use a system prompt instead.
+- Self-contained. No references to external files or assumed prior context.
+- No user fill-in placeholders. If a value depends on context, the user adds it after invocation.
+- Plain markdown only. No YAML frontmatter, no headers, no nested structure.
+- Filename is the slug: kebab-case, no capitals, no underscores
+
+## Structure
+
+- Lead with a verb. Open with an imperative that states the job immediately.
+- One instruction per sentence. Do not stack multiple actions into one sentence.
+- For sequential steps, use a numbered list with one action per item.
+- When the output has a fixed shape, show it in a fenced code block with a language identifier.
+- Put constraints and exclusions last, not inline with the main instructions.
+
+## Examples
+
+### Correct
+
+```markdown
+I want to implement the following. Scan relevant files and list conflicts. Do not implement. # user adds feature after invocation
+Scan relevant files and list conflicts. Do not implement. # run-as-is, no context needed
+```
+
+### Incorrect
+
+```markdown
+I want to implement: <feature or task name> # redundant fill-in, add context after invocation instead
+See ARCHITECTURE.md before starting. # external dependency, not self-contained
+
+## Overview\n## Steps # headers belong in a system prompt, not a snippet
+```

package/standards/standard.md

@@ -0,0 +1,170 @@
+---
+title: Standard reference
+description: Shape and content rules for authoring a standard
+---
+
+# Standard reference
+
+Applies to each authored standard in the folder. Skip for `index.md`, which is generated rather than authored.
+
+## Overview
+
+A standard is a target-facing authoring convention for one document type, or for one attribute carried across every document. Nothing installs it into a project, so a reader resolves it with `canon standards <name>` or reads it at `standards/<name>.md`, and skills and developers consume it alike. This file governs itself, so every rule below applies to it.
+
+## Scope
+
+Governs each authored standard under `standards/`: its stated jurisdiction, success criterion, frontmatter, structure, and rule phrasing.
+
+Does not govern:
+
+- The voice, rhythm, and sentence construction a standard is written in: the `write-human` skill
+- The punctuation, formatting, and word choice a standard is written in: `markdown.md`
+- The shape of any artifact a standard governs, which is that standard's own subject
+
+## What a working standard looks like
+
+A standard answers these questions. Each can be answered wrong, which is what makes them a test rather than a preamble.
+
+- Which single document type or attribute does this govern, and where does it apply?
+- Can an author who has seen no example produce a conforming document from this file alone?
+- Does every rule state a shape the document must have, rather than a fact about the repository that happens to store it?
+- What does a conforming document achieve, stated so a reviewer can call one non-conforming without appealing to taste?
+
+A standard failing these questions is non-conforming even when it satisfies every shape rule below.
+
+## Scoping rules
+
+### Declaring scope
+
+- Govern one document type per standard, or one attribute across every document. Split unrelated conventions into separate files.
+- Open with a `## Scope` section stating what the standard governs and what it does not, placed above the shape rules. A standard that specifies shape exhaustively and jurisdiction nowhere cannot refuse a rule, so the rule with no obvious owner lands in whichever standard sits nearest.
+- Write it as one line naming the artifact or attribute and where it applies, then a `Does not govern:` list. Give each entry the excluded concern and the owner it goes to. Name a sibling standard by bare filename, since the corpus is one flat folder, and name the surface instead where the owner is one, such as a coding rule, a project policy, or the code.
+- Put the governed path in backticks inside the first sentence of that line, anchored deep enough to resolve from a project root. A bare folder name matches a same-named folder elsewhere in the tree, and a path held back until a later sentence sits beside every other path the statement mentions, including the ones it excludes.
+- Say in that same sentence when the standard governs an attribute rather than a document type. An attribute is written across every document and has no path to name, so the silence reads as an omission unless the sentence claims it.
+- Cut an entry that names no owner at all. It is either excluding something nothing was going to claim, or it is a content exclusion, which the rule below sends to the shape rules instead.
+- Declare a boundary from both sides. A yield, an exemption, or a handoff stated in one standard alone is never checked against the standard on the other side of it, which is how two files come to claim the same rule or neither does.
+- Separate a jurisdiction exclusion from a content exclusion. The first names a concern another standard owns and belongs in `## Scope`. The second names what does not belong inside the document and stays with the shape rules. Merging them puts a boundary claim where no sibling will read it.
+- Stay silent on a section the standard holds today but should not own. Claiming it makes the scope statement false the moment it moves, and the mismatch is the evidence that moves it.
+
+### Naming the file
+
+- Name the file for the artifact the scope statement governs, taking the word from the deepest path segment that names the artifact rather than the folder holding it. `plan.md` over `.claude/plans/feature-<slug>.md` and `session.md` over `.claude/tasks/session-<slug>.md` both follow it.
+- Take the singular or the plural of that word, whichever reads as the artifact. A standard over one document takes the singular, and one over a set may take either.
+- Name an attribute standard for the attribute itself, since it governs no path to derive a word from.
+- Write the derived word alone. A standard installs as a sibling and is cited by bare filename, so a qualifier makes an outlier that every later citation has to carry.
+- Rename an outlier at the moment it is found, and state the reach in the change that does it. The name is installed in every target and cited in surfaces that never see the rename, so the cost only grows.
+
+### Staying inside it
+
+- Name no path, filename, or folder outside the document type the standard governs. A standard reaches projects whose layout is their own, so a path borrowed from the authoring repository is wrong in a target and nothing reports it.
+- State the rule, never the mechanism enforcing it. Hooks, scripts, checks, and skill catalogs are facts about one repository. Name the condition the document must meet and let the enforcing surface name its own case.
+- Invent inline examples rather than citing a real file elsewhere in the project. A cited file moves or is deleted and the standard goes stale in silence.
+
+## Frontmatter
+
+- Start the file with a frontmatter block carrying at least `title` and `description`. A consuming surface may require more.
+- `title`: names the doc type in sentence case, suffixed `reference` (`Commit reference`, `Branch reference`)
+- `description`: one line naming what the standard covers. It becomes the index link label on install.
+
+## Structure
+
+- Use sentence case for every heading
+- Flat `##` rule groups for a single-topic standard. Group `##` headers by concern for a multi-topic one.
+- When one `##` section covers more than one sub-concern, split its bullets into `###` subgroups, one subgroup per sub-concern. A flat bullet list under an `##` covers a single sub-concern. Roughly seven bullets is a signal to split, not a hard cap.
+- Order groups from the most-used rule down to the edge case
+
+## Rules
+
+- Write rules as imperative bullets: one rule per bullet, one concern per group
+- State the forbidden shape rather than enumerating allowed options, so a rule survives new categories
+- Cut any rule that resists a crisp one-line phrasing
+- Do not pad with filler prose. Every line earns its place as a usable reference entry.
+
+## Success criterion
+
+- State what a conforming artifact achieves, not only what shape it takes. A standard that specifies structure exhaustively and success nowhere cannot be argued against, only edited on taste.
+- Write the criterion as a small set of questions the artifact must answer, or a task a reader must be able to complete from it. Keep it checkable by a person in one sitting.
+- Place it near the top, above the shape rules it governs. The shape rules are the means and the criterion is the test.
+- Say that an artifact failing the criterion is non-conforming even when it satisfies every shape rule. Without that line the criterion reads as advice.
+- Add a criterion to an existing standard when that standard is next exercised, not in a sweep. A criterion written without a failure to point at is the taste-based edit this section exists to prevent, so a standard with no criterion yet is a known gap rather than a violation.
+
+## Changing a standard
+
+### The checkpoint
+
+Answer all four before editing, and carry the answers into wherever the change is proposed. This section governs itself, so the next edit to this file answers them too.
+
+- What problem does this solve? Name the artifact that went wrong, rather than the improvement the change makes.
+- Which surface owns the rule today? A rule already stated somewhere moves or is cited, never restated in a second place.
+- What deterministic check catches a regression? Name it, or say none exists and the rule holds on reading alone.
+- What does this collide with? Name the sibling standard, rule, or template it contradicts, or state that nothing does.
+
+### What justifies a change
+
+- Change a standard on a failure, not on a finding. A finding is that the docs say X or a paper suggests Y. A failure is a conforming artifact that satisfied every shape rule and still missed the success criterion.
+- Park findings wherever the project tracks pending work, or in the standard's own backlog section when it tracks none. They are hypotheses to test, not instructions to apply.
+- Cite the failing artifact in the change that fixes it, so the next reader can tell which rules were paid for by evidence.
+
+## Examples
+
+- Include examples only where a rule is non-obvious. A self-evident rule needs none.
+- When shown, label them `### Correct` and `### Incorrect` with an inline `# reason` on each entry
+- Keep to two or three entries. Show the pattern, not a catalog.
+- Keep each entry a short one-liner or command. Do not write multi-line correct and incorrect function blocks.
+
+## Template
+
+- Carry one fenced template of the document the standard governs, so an author copies a shape instead of reconstructing it from prose.
+- Bind this to a standard governing a document type. An attribute standard governs a scan, a string, or a label rather than a file, so it has no document to template and carries none.
+- State that exemption in the sentence declaring the standard an attribute standard. An exemption left to inference reads as an omission, and the next author writes a template that teaches nothing.
+- Place the template below the rules it satisfies, under a `## Template` heading or inside the section holding those rules. A reader arrives at it having already read what each part means.
+- Show the skeleton alone: every required section, one placeholder line for what each holds. A full worked document is a second document to maintain.
+- Write placeholders in angle brackets rather than copying a real document. A copied file goes stale, and its backticked filenames read as citations to anything parsing the standard.
+- Switch to a bare word where the fenced language reads `<` as syntax of its own, as Mermaid and HTML do, and say in the line above the fence that the names are placeholders. A template that does not parse in its own language teaches a shape the author cannot run.
+- Carry any header, key, or label a consuming tool parses verbatim. The template is the only place an author learns which strings are load-bearing, since prose calling them fixed does not say what they are.
+- Treat the template as authoritative where it and the prose disagree. An author copies the block, so a contradiction ships as the block, and naming the winner turns a drift into a visible defect rather than a silent one.
+
+````markdown
+---
+title: <Document type> reference
+description: <one line naming what this standard covers>
+---
+
+# <Document type> reference
+
+Applies to `<path/to/document>`. <One line on what the document is for and when it changes.>
+
+## Scope
+
+Governs `<path/to/document>`: <the aspects this standard sets>.
+
+Does not govern:
+
+- <excluded concern>: `<sibling>.md`
+- <excluded concern>: <the surface that owns it>
+
+## What a working <document type> looks like
+
+A <document type> works when <the task a reader completes from it alone>:
+
+- <question the document must answer>
+- <question the document must answer>
+
+A <document type> failing these is non-conforming even when it satisfies every shape rule below.
+
+## Frontmatter
+
+- `title` (required): <casing, and what it names>
+- `description` (required): <what the one line covers>
+
+## <Shape rule group>
+
+- <imperative rule, one concern per bullet>
+- <imperative rule, one concern per bullet>
+
+## Template
+
+```markdown
+<the skeleton of the governed document, placeholders throughout>
+```
+````