@erclx/canon 4.0.0

package/claude/skills/session-resume/REQUIREMENT.md

@@ -0,0 +1,49 @@
+---
+name: session-resume
+description: Why resuming reads the handoff before the board, reads an index before task files, resolves scratch at the main root, and never mutates what it reports
+---
+
+# Session resume requirement
+
+## Gap
+
+Without this skill, a session picking up old work reconstructs state from the git log, which records what shipped and not what is queued, so finished work reads as pending and the actual next item goes unmentioned. The alternative failure is worse for a different reason. A session that reads every task file and every plan to be thorough spends the context the work needs before the work starts, and the summary arrives in a session with no room left to act on it.
+
+A compaction keeps conclusions and drops the reasoning that produced them, and the previous session can write that reasoning to a handoff before it goes. A resume that reads the board, the plans, and the memory index alone walks past that file, so the one artifact written to survive the compaction reaches nobody and the next session re-derives what it holds.
+
+The task index is a folder catalog rather than a task filter, so it carries a row for the ordering file and one for every handoff on the board. A session reporting each row as a backlog item queues work nobody filed, and the count grows with every session that ever wrote a handoff.
+
+From a linked worktree the shared scratch folders resolve against the worktree rather than the main root, where they are empty. That reports no tracked work on a repository carrying a full backlog, and the report is indistinguishable from the true empty case.
+
+A resume is a read, and a session that treats it as a cleanup pass offers to archive finished entries or refresh a memory it decided was stale. Both change tracked state on the strength of a summary the user has not confirmed yet.
+
+## Must
+
+- Read the newest handoff before the board, and report what it carries attributed to its writer
+- Resolve the handoff, plans, memory, and tasks folders at the main worktree root
+- Read the task index before any individual task file, and open only the task files the summary needs
+- Drop the board siblings from the index before reporting it as the backlog, since the catalog filters nothing and carries a row per handoff
+- Preserve the index's order in the report, since the order is the priority
+- Surface only the memory entries that inform the top item
+- Close with one recommendation naming the first item and whether a plan backs it
+
+## Must not
+
+- Read the whole tasks folder to build a summary
+- Report the absence of a handoff, which is the common case and would train a reader to skip the line on the run where one exists
+- Restate a handoff's counts, sizes, or costs as current. Each was true when written.
+- Offer to remove, archive, or reorder an entry. Resume reports and does not mutate.
+- Update memory, which changes when a recorded fact becomes wrong rather than on a resume
+
+## Guards
+
+- All four surfaces absent or empty reports no tracked work and stops, rather than inventing a next step from the repository
+- A handoff found beside an empty board recommends what the handoff leaves open, since the guard passes on the handoff alone and the recommendation has no backlog item to name
+
+## Out of scope
+
+- Writing a handoff, which happens at the close of a session rather than at its start. This skill names the standard that governs one and follows it no further.
+- The sections a role adds over the core handoff, which belong to that role's own surface
+- Archiving a shipped task out of the folder: `claude-tasks`
+- Archiving a plan and marking an outcome, which `claude-docs` does when the work ships
+- Implementing the item it recommends, which is the next request rather than part of this one

package/claude/skills/session-resume/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: session-resume
+description: Resumes a previous session by reading the handoff it left behind, tracked work, and relevant context. Use when starting a new session, or when asked to "pick up where we left off", "what was I working on", or "resume".
+---
+
+# Session resume
+
+## Step 1: read tracked work
+
+Resolve `.claude/plans/`, `.claude/memory/`, and `.claude/tasks/` at the main worktree root per Worktrees in `CLAUDE.md`.
+
+Read these in parallel, skipping any that do not exist:
+
+- the newest `.claude/tasks/session-*.md`: the handoff a previous session wrote before a compaction, per `${CLAUDE_SKILL_DIR}/../../standards/session.md`. It leads the report rather than the reads.
+- `.claude/tasks/index.md`: the folder catalog. Read this before any individual task file, and take the task list from it by dropping the `index`, `priority`, `backlog`, and `session-` rows, which are siblings rather than tasks.
+- `.claude/plans/*.md`: execution detail for in-progress tasks
+- `.claude/memory/index.md` and any memory files relevant to the top backlog item
+
+Then read only the task files the summary needs, typically the top one. Do not read the whole folder.
+
+Most projects carry no handoff. Say nothing about its absence, since a line reporting it every run trains a reader to skip the line on the run where a handoff exists.
+
+If all four surfaces are absent or empty, stop: `✅ No tracked work found. Start a new task.`
+
+## Step 2: summarize
+
+Output these sections, omitting the first when no handoff was found:
+
+**Carried over:** the reasoning the handoff holds, as its writer stated it. Attribute it to the map rather than restating it as fact, and re-measure any count, size, or cost before acting on one.
+
+**Up next:** one line per task row in `.claude/tasks/index.md`, preserving order. A board carrying handoffs has a row per session that wrote one, so a report listing every row queues work nobody filed.
+
+**Active plans:** one line per file in `.claude/plans/`, linking each to its task file in `.claude/tasks/`. Say "None" if empty.
+
+**Relevant context:** two or three memory entries that inform the top backlog item. Skip if none apply.
+
+## Step 3: recommend
+
+End with one line: `Start with: <first Up next item>` and note whether it has a linked plan.
+
+When the board is empty and a handoff was found, name what the handoff leaves open instead: `Start with: <the open thread the handoff names>`. A recommendation slot filled with nothing reads as a failed run, and a handoff on an empty board is the shape a session leaves when it was reasoning rather than shipping.
+
+Do not offer to remove entries. A completed task is archived out of `.claude/tasks/` when work ships. The git log is the authoritative record of shipped work. Plan files are archived per the plan lifecycle rule in `CLAUDE.md`.
+
+Memory is updated only when a recorded fact becomes wrong, never on resume. A domain fact reaches a session through `.claude/context/`, which `claude-memory-capture` routes to and the three-tier model loads on demand, so the memory folder read here is the residue no context entry owns.
+
+## Writing the next one
+
+This skill reads a handoff and never writes one. Reading and writing are two jobs, and the write happens at the close of a session rather than at its start.
+
+Name the standard when the session asks how to leave a handoff behind, and let the session follow it directly. Any session may write one, whatever role it holds, so nothing here routes the request to another skill. A role carrying sections of its own adds them over the core per that role's own runbook.

package/claude/skills/setup-gov/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: setup-gov
+description: Scope boundary for governance rule install and the authoring it refuses to do in a target
+---
+
+# Setup gov requirement
+
+## Gap
+
+Without this skill, a session picks a stack name from memory and installs rules written for a framework the project does not use, passes an extra the catalog does not carry so the install warns on a file it cannot resolve, and adds a rule the picked stack already pulls in.
+
+The two costly failures are quieter. An unmatched technology gets the nearest rule instead of a stop, so the project carries governance authored for something adjacent and nothing marks it as a guess. A rule written directly into the target lands where no sync will ever reach it, so it drifts from the toolkit copy that owns it.
+
+The last failure sits at a boundary rather than inside a run. `setup-init` turns away a project whose language it carries no stack for and sends it here, and a body stating only what this skill does not cover leaves that route running one way, so a person arriving on it reads a skill that never says it is the destination.
+
+## Must
+
+- Read the catalog at run time and resolve both the stack and every extra against it
+- Name the evidence file behind each detected technology in the preview, so a wrong match is visible before the install rather than after
+- Dedupe extras against the rules the picked stack already resolves
+- Run the install non-interactively, since the CLI picker blocks where no terminal is attached
+- State the inbound route from `setup-init`, so a project sent here for the language-neutral rule layer can tell it landed at the destination the chain named
+
+## Must not
+
+- Author a rule inside the target project. Rules are authored in the toolkit and reach a project by install or sync.
+- Install a stack or extra whose name did not come from the catalog read
+
+## Guards
+
+- An unmatched technology stops and presents the options rather than resolving to a nearby rule. Authoring the missing rule in the toolkit, installing the matching layers without the technology-specific one, and aborting are the three, and this skill picks none of them.
+
+## Out of scope
+
+- The rest of the onboarding chain. This skill installs governance and nothing else, and `setup-init` is the one-shot path that installs governance beside tooling, snippets, and the seeds.
+- Scaffolding the rule file an unmatched technology needs. `create-rule` writes one into a target project, and a rule the toolkit should ship is authored under `governance/rules/` against `canon standards rule`.
+- Updating rules a project already has, which `canon gov sync` owns

package/claude/skills/setup-gov/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: setup-gov
+description: Detects a project's stack from its files and installs matching toolkit governance rules into `.claude/rules/`. Use after scaffolding a new project, when asked to "install gov rules", "install governance", "set up governance", or when a target project has no `.claude/rules/` yet. Assumes the `canon` CLI is on PATH.
+---
+
+# Gov install
+
+Automates `canon gov install` by inferring the stack and extras from the current project, then shelling out to the CLI with the resolved arguments.
+
+## Scope
+
+- Governance rules and nothing else. `setup-init` is the one-shot chain that installs governance beside tooling, standards, snippets, and the seeds.
+- This is where `setup-init` sends a project whose language the toolkit carries no stack for. Rules install without the `base` development dependencies the tooling layer would drop on it. Resolve and stop exactly as below, since a language with no stack is the unmatched case `## Gap handling` already owns and arriving by that route changes none of it.
+
+## Read the catalog
+
+Run this first to load the current stacks and rules. Never hardcode names. The catalog is the source of truth.
+
+```bash
+canon gov list --json 2>/dev/null
+```
+
+## Detect the stack
+
+Read these from the project root in parallel:
+
+- `package.json`: dependencies and devDependencies
+- Root config files: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
+- `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md` if present
+- Directory structure via `ls -1` of the project root and `src/` if present
+
+## Match
+
+Match the detected evidence to the catalog:
+
+- Pick the closest stack. Match detected runtime or framework against stack names in the catalog.
+- Identify additional technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology, then add it via `--add`.
+- Dedupe extras against stack rules. Do not add a rule the stack already pulls in.
+
+## Gap handling
+
+If a detected technology has no matching rule, stop and surface the gap. Do not guess.
+
+Present four options:
+
+1. Author a new rule in the toolkit at `governance/rules/<domain>/<num>-<name>.md` following `${CLAUDE_SKILL_DIR}/../../standards/rule.md`, commit, then re-run install. Take this route when the toolkit should ship the rule to every project.
+2. Invoke `create-rule`, which scaffolds the file into the target project at a non-colliding number. Take this route when the rule is specific to this project and no sync should ever overwrite it.
+3. Install the matching non-<tech> rules and skip the tech-specific layer.
+4. Abort.
+
+This skill authors no rule itself. Option 1 writes in the toolkit repository, and option 2 hands the project-local file to `create-rule`.
+
+## Preview
+
+Before executing, output:
+
+- **Detected:** each technology with the file that evidenced it
+- **Stack:** picked stack name and total resolved rule count
+- **Extras:** each `--add` rule with a one-line reason
+- **Target:** resolved target path
+- **Command:** the exact shell command to run
+
+## Execute
+
+Run with `CANON_NON_INTERACTIVE=1` so no CLI picker prompts appear. Claude Code's tool permission dialog is the confirmation gate.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon gov install <stack> --add <extras> <target>
+```
+
+## Response
+
+After execution, report:
+
+- Rule count installed
+- Target path
+- Any rules that failed to resolve (the CLI warns on missing rule files)

package/claude/skills/setup-indexes/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: setup-indexes
+description: Why index bootstrap is all-or-nothing per folder, what the confirmation loop protects, and why the convention block is pasted rather than written
+---
+
+# Setup indexes requirement
+
+## Gap
+
+Without this skill, a session bootstrapping the index system writes `index.md` into a folder and leaves the sibling frontmatter for later, so the first regen hard-errors on the first file missing a `title`. Partial coverage is not a partial success. The folder is broken until every sibling carries both fields, and the error surfaces at regen rather than at the write that caused it.
+
+The scan is where the other failures start. A walk that does not prune reaches `node_modules`, gitignored output, and the snippets folder, which is invoked by reference rather than browsed and needs neither an index nor per-file frontmatter. A folder that already carries an `index.md` gets a second one written over the first.
+
+One failure predates the scan. `setup-init` declines an install that wants the Claude layer without the tooling chain and names this skill as where the index system gets bootstrapped, and a body that never states the inbound route leaves the person arriving on it unable to tell whether they landed at the destination or somewhere adjacent to it.
+
+Drafted frontmatter is a proposal, and a session that writes it before the user sees it turns a review into a cleanup. The convention block has the mirror failure. A session that paraphrases it into `CLAUDE.md` produces a copy that reads correctly and no longer matches its source, so the two drift with nothing reporting it. And a project with no `CLAUDE.md` gets one scaffolded to hold the block, which installs a file the project declined.
+
+## Must
+
+- Bootstrap all-or-nothing per chosen folder, since a folder carrying partial frontmatter hard-errors on regen
+- Prune the scan to folders a reader browses, and skip any folder already carrying an `index.md`
+- Surface every drafted `title` and `description` for the user to accept, edit, or reject before anything is written
+- Validate with a dry run and stop on the first reported error, before writing for real
+- Paste the convention block verbatim from its single source
+- Emit the closeout exactly once, whatever the seed step concluded
+- State the inbound route from `setup-init`, so an install wanting the Claude layer without the tooling chain can tell it landed at the destination the chain named
+
+## Must not
+
+- Write a draft the user has not confirmed
+- Index the snippets folder, which is read by reference rather than browsed
+- Create `CLAUDE.md` to hold the convention block. Name the skip and the command that installs the file.
+- Overwrite content below the frontmatter block, or touch a file the user rejected
+
+## Guards
+
+- A folder with fewer than the sibling threshold stays out of the candidate list unless the user names it explicitly, so the scan proposes and the user overrides
+- A `CLAUDE.md` already carrying the convention section skips the seed silently rather than appending a second copy
+
+## Out of scope
+
+- Regenerating an index in a project that already runs the system, which `canon indexes regen` does on its own
+- Wiring the lint-staged entry or the hook, which the closeout offers and the user opts into
+- Installing governance rules or scaffolding a project: `setup-gov` and `setup-init`
+- Writing the frontmatter conventions themselves, which the prose standard owns

package/claude/skills/setup-indexes/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: setup-indexes
+description: Bootstraps the toolkit's `index.md` system in a target project. Scans for markdown-heavy folders, drafts `title` and `description` frontmatter, scaffolds `index.md` per chosen folder, and runs `canon indexes regen` to validate. Use when asked to "set up indexes", "bootstrap indexes", "add index.md to this project", or "install indexes". Assumes the `canon` CLI is on PATH.
+---
+
+# Indexes install
+
+Adds the index.md system to a project that does not have it. Operates in the active Claude session: Claude reads files, drafts frontmatter, confirms with the user, and writes. The CLI handles validation and regeneration only.
+
+Read `.claude/context/indexes.md` from the toolkit if context on the system is needed before scanning.
+
+## Scope
+
+- Bootstrap un-indexed folders only. Skip folders that already contain an `index.md`.
+- All-or-nothing per chosen folder. Every `*.md` sibling in a chosen folder gets `title` and `description` injected, or none does. Partial migration creates folders that hard-error on regen.
+- This is where `setup-init` sends an install that wants the Claude layer without the tooling chain, once `canon claude init` has seeded the docs. The work is the same either way, since the scan below prunes `.claude` and reads the project's own documentation folders whichever route reached it.
+
+## Scan
+
+Walk the project root for folders containing three or more sibling `*.md` files. Prune `.git`, `node_modules`, `.claude`, `snippets`, anything matched by `.gitignore`, and any folder that already contains an `index.md`.
+
+Skip `.claude/snippets/`. Snippets are invoked by reference (`@snippet-name`) rather than browsed, so they need neither `index.md` nor per-file frontmatter. Adding them creates noise that targets keep reporting.
+
+For each candidate, capture:
+
+- Folder path relative to project root
+- Sibling count
+- Existing frontmatter coverage (how many siblings already carry `title` and `description`)
+
+## Present candidates
+
+Output one line per candidate:
+
+```plaintext
+- docs/         (8 files, 0/8 with frontmatter)
+- guides/       (5 files, 2/5 with frontmatter)
+- references/   (3 files, 0/3 with frontmatter)
+```
+
+Ask the user which to bootstrap. Accept folder paths, `all`, or `none`. The user can also force a folder with fewer than three siblings by naming it explicitly.
+
+## Draft frontmatter
+
+For each chosen folder, read every `*.md` sibling and draft frontmatter:
+
+- `title`: derived from the first H1. If absent, derive from the filename in sentence case.
+- `description`: one line summarizing the file's purpose, drawn from the first paragraph after the H1. Follow `${CLAUDE_SKILL_DIR}/../../standards/markdown.md` § Frontmatter descriptions for length and style.
+
+Surface every drafted entry to the user grouped by file:
+
+```plaintext
+docs/architecture.md
+  title: Architecture
+  description: System boundaries, data flow, and module responsibilities
+```
+
+The user accepts, edits, or rejects per file. Offer "accept all remaining" once the user confirms two in a row to keep the loop short.
+
+Never write drafts before the user confirms. Drafted text is a proposal, not a commit.
+
+## Scaffold the folder index
+
+Compose `index.md` for each chosen folder with:
+
+```markdown
+---
+title: <folder name in sentence case, user-editable>
+subtitle: <one-line folder purpose, user-editable>
+---
+```
+
+Surface the proposed `title` and `subtitle` and let the user edit before writing.
+
+## Inject
+
+After all confirmations, write frontmatter into each sibling and `index.md` into each folder. Use a single batched write per file.
+
+Preserve existing content below the frontmatter block. If a sibling already has frontmatter without `title` or `description`, merge in the missing fields. Do not touch files the user rejected.
+
+## Validate
+
+Run from the project root:
+
+```bash
+canon indexes regen --dry-run --json
+```
+
+Parse the JSON. On any `error` action, surface the file and reason and stop. On `would-write` for the bootstrapped folders, the dry-run is healthy. Run for real:
+
+```bash
+canon indexes regen --json
+```
+
+Count the `written` actions in that record and report the number. Read the real run the same way the dry run is read, since the exit carries nothing reliable back to a session. An operator's shell profile may wrap `canon` in a function that runs the binary and then a second command and takes the second status, so a regen that errored on a sibling missing `title` arrives here as a clean pass.
+
+## Offer the convention seed
+
+First check whether `CLAUDE.md` exists in the project root. If absent, do not scaffold one. Skip the seed install with this exact message:
+
+```plaintext
+No CLAUDE.md in the project. Skipping convention seed.
+To add the convention later, run `canon tooling sync` or `canon init`,
+then re-invoke this skill.
+```
+
+If `CLAUDE.md` exists, check it for an existing `## Indexes` section:
+
+```bash
+grep -l '^## Indexes' CLAUDE.md 2>/dev/null
+```
+
+If the section is present, skip the seed silently.
+
+If `CLAUDE.md` exists but has no `## Indexes` section, offer to install the canonical convention block. The text below is the source of truth and is mirrored in the toolkit's `tooling/claude/seeds/CLAUDE.md`. Paste it verbatim. Do not rewrite, paraphrase, condense, or add punctuation.
+
+```markdown
+- When a folder has an `index.md`, check it before reading individual files in that folder.
+- For folders where an agent browses to pick a document, `index.md` is regenerated from each file's frontmatter. Do not hand-edit `index.md`. Code folders and scratch folders do not need one.
+- Every `index.md` carries its own frontmatter (`title`, `subtitle`) that the walker preserves. To keep a folder's `index.md` hand-edited, add `auto: false` to its frontmatter.
+```
+
+Append a new `## Indexes` section at the end of the file containing the three lines. Do not touch any other section.
+
+## Closeout
+
+Always emit this block as the final message of the skill run. Do not skip it regardless of how the seed step concluded (installed, already present, declined, or skipped because no `CLAUDE.md` exists). Output exactly one closeout, even if the seed step paused for user input. Resume the flow after the user responds and emit the closeout next.
+
+Format:
+
+```plaintext
+Bootstrap complete.
+
+Folders bootstrapped:
+- <path> (<n> files)
+
+Drafts: <n> accepted, <n> edited, <n> rejected
+Convention seed: <installed | already present | declined | skipped (no CLAUDE.md)>
+
+Optional maintenance (opt in, the skill does not configure these):
+- lint-staged entry in .lintstagedrc.json:
+    "**/*.md": "canon indexes regen"
+- Claude Code PostToolUse hook on Edit and Write matching **/*.md running:
+    canon indexes regen
+```
+
+Replace bracketed values with the values from this run. Drop the "Folders bootstrapped" line if zero folders were chosen.
+
+## Reference
+
+Both pages sit in the toolkit and install nowhere, so a target reads them there rather than in its own tree.
+
+- The toolkit's `.claude/context/indexes.md`: system rationale, frontmatter contract, when to adopt
+- The toolkit's `docs/agents/indexes.md`: `canon indexes regen` flags, exit codes, JSON shape

package/claude/skills/setup-init/REQUIREMENT.md

@@ -0,0 +1,45 @@
+---
+name: setup-init
+description: Scope boundary for the one-shot onboarding chain and the setup steps it leaves to a caller
+---
+
+# Setup init requirement
+
+## Gap
+
+Without this skill, a session installs a stack whose name it recalled rather than read, hand-writes configs the tooling sync already ships as golden files, and re-runs the chain over a project that owns its configs already.
+
+Two failures are the expensive ones because both return success. A monorepo run drops husky into every subtree, git honors one `core.hooksPath`, and the extra hook directories go quiet with nothing reporting it. A caller reads the chain as onboarding complete when index bootstrap and plugin provisioning never ran, since no step states whether they belong to the chain.
+
+Two more start at the resolve step. A project whose language the toolkit carries no stack for resolves to `base`, and the preview reports the resolved name without marking it as a fallback, so `base` development dependencies, scripts, and hooks land on a project that will not use them and nobody had the moment to decline.
+
+The other is the refusal that ends rather than routes. An existing project, an install wanting the Claude layer without the tooling chain, and a language with no stack are the three states the chain does not serve, and each is declined by a declaration naming no destination, so the person who arrived with one reads a stop and goes no further.
+
+## Must
+
+- Resolve every domain argument against a catalog read at run time, so a stack, rule, snippet, or tooling name the catalog does not carry cannot reach the command line
+- Preview the resolved chain before the first command runs, naming the evidence file behind each detected technology
+- Pass `--skip base` on every subtree past the first in a monorepo, so the shared hook layer lands once
+- State which onboarding steps the chain does not run, so a caller knows what is left rather than inferring completeness from a clean report
+- Mark a stack reached by fallback as a fallback in the preview, and name what `base` carries, so the write can be declined at the one point it is still declinable
+- Name a destination for every state the chain does not serve, in this body rather than only in a reference doc the person would have to already know to open, and say for each whether the chain stops or runs on a default
+
+## Must not
+
+- Generate a config that tooling sync ships as a golden file. Generating from prose duplicates the installed file and the two drift.
+- Author a rule, stack, or snippet inside the target project when detection finds no match. Authoring happens in the toolkit and reaches a project by install or sync.
+- Grow an existing-project branch, a mode switch, or a clobber guard. The chain runs once against a fresh scaffold and the per-domain paths cover everything after that.
+
+## Guards
+
+- An unmatched technology stops for a decision. Surface the gap and either defer to rule authoring or proceed on the matched layer with the gap named in the report, rather than resolving to the nearest rule.
+
+## Out of scope
+
+- Installing governance rules alone: `setup-gov`. This skill installs governance beside tooling and the seeds.
+- Bootstrapping the `index.md` system: `setup-indexes`. Neither `canon init` nor this chain performs it.
+- Provisioning Claude Code plugins: `setup-plugins`. Those install once per machine rather than into a project, so no project-scoped chain can carry them.
+- Running the verification scripts, which `setup-verify` owns and this chain invokes as its last step
+- Re-installing into a project that already has the files, which the per-domain `canon <domain> install` and `canon sync` commands own
+- Deciding which of those per-domain commands an existing project needs: `canon-operator`. That skill reads the target before naming one, which this chain never does, so it is the destination rather than a guess made here.
+- Seeding the `.claude/` folder without the tooling chain, which `canon claude init` does on its own and `setup-indexes` finishes

package/claude/skills/setup-init/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: setup-init
+description: Detects a new project's type and runs `canon init` with a resolved stack in one shot. Use when bootstrapping a new project with the toolkit, or when asked to "init this project", "bootstrap the toolkit", "set up toolkit", or "one-shot install". Assumes the `canon` CLI is on PATH. Do NOT use when only installing governance rules. Use `setup-gov` instead.
+---
+
+# Init project
+
+Orchestrates the onboarding chain. Detects project type, resolves per-domain arguments, previews the chain, then runs `canon init` with flags. The CLI holds the install logic. This skill only resolves and previews.
+
+## Scope
+
+- This skill and `canon init` run once on a fresh scaffold, never on an existing project. They do not guard against clobbering existing configs. When tempted to add guards, mode switches, or an existing-project branch, stop. Extend the per-domain `canon <domain> install` or `canon sync` paths instead.
+- The chain does not bootstrap the `index.md` system and does not provision Claude Code plugins. `setup-indexes` owns the first. `setup-plugins` owns the second, which installs once per machine rather than into a project, so no project-scoped chain can carry it. Name both in the report so a clean result does not read as onboarding complete.
+
+## Declined states
+
+Three states reach this skill that the chain does not serve. Name the destination for each, so the refusal routes rather than ends. The first two stop the chain outright and the third runs it on a default the person may not want.
+
+- **An existing project.** Stop and hand off to `canon-operator`. It reads what the target already carries before it names a command, which this chain never does, so any per-domain install picked here is a guess against configs nobody read. The Scope bullet above names the same commands as the authoring alternative, and this is the destination a person takes.
+- **An install wanting the `.claude/` folder alone.** Stop. Run `canon claude init` for the seed docs, then invoke `setup-indexes` to bootstrap the `index.md` system over the project's own documentation folders. Neither needs the tooling sync this chain runs.
+- **A language the toolkit carries no stack for.** The chain still runs, on `base`, with the fallback marked in the preview. A project that wants none of what `base` carries declines there and takes `setup-gov` for the governance layer, which is language-neutral. Say so at the preview rather than resolving it here, since the fallback is a working default and only the person can say whether it fits.
+
+Do not add a stack, a mode switch, or an existing-project branch to satisfy one of these. Each destination already exists and routing to it costs a line.
+
+## Read catalogs
+
+Run in parallel. Never hardcode stack, rule, snippet, or standards names.
+
+Run from the target project's current directory. Do not cd into the toolkit source tree. The `canon` CLI is global.
+
+```bash
+canon gov list --json 2>/dev/null
+canon tooling list --json 2>/dev/null
+```
+
+## Detect
+
+Read these from the project root in parallel, skipping any that do not exist:
+
+- `package.json`: `dependencies` and `devDependencies`
+- Root configs: `astro.config.*`, `next.config.*`, `vite.config.*`, `tailwind.config.*`, `tsconfig.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`
+- `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md` if present
+- Directory structure via `ls -1` of the project root and `src/` if present
+
+## Resolve arguments
+
+- **Stack:** pick the closest governance stack by matching detected runtime or framework against stack names in the catalog. If nothing matches, fall back to `base` and carry the fallback into the preview.
+- **Tooling stack:** pick the closest tooling stack from `canon tooling list --json` (e.g. `vite-react`, `astro`). Distinct from the governance stack. Fall back to `base` if no framework match, and carry that fallback into the preview too.
+- **Extras:** identify technologies not already covered by the picked stack. For each, find a rule whose `description` or `paths` points at that technology and pass it via `--add`. Do not add a rule the stack already pulls in.
+- **Skip (`--skip`):** `wiki` installs by default. Add `--skip wiki` only when the user explicitly wants it left out.
+
+## Gap handling
+
+If a detected technology has no matching rule or stack, do not guess. Surface the gap and either:
+
+1. Defer to `setup-gov`. Author a rule in the toolkit, then re-run this skill.
+2. Proceed with the matched layer, listing the gap in the final report.
+
+Rules and stacks are authored in the toolkit repo, never in the target project on the fly.
+
+## Preview
+
+Before executing, output:
+
+- **Detected:** each technology with its evidence file
+- **Stack:** picked governance stack + resolved rule count. Mark it `fallback` when no detected runtime or framework matched a catalog name.
+- **Tooling stack:** picked tooling stack. Mark it `fallback` on the same test, and name what `base` lands: configs, seeds, and gitignore entries in every case, plus the JavaScript development dependencies, scripts, and hook activation wherever a `package.json` exists to carry them. A project outside that ecosystem runs none of the second group and keeps the first.
+- **Extras:** each `--add` rule with a one-line reason
+- **Skip:** any `--skip` entries with reason
+- **Target:** resolved target path
+- **Commands:** the full chain that will run
+
+A resolved name and a fallback read alike once written, so mark the fallback here rather than in the report. The preview is the last point before the first write, and the report runs after the files have landed.
+
+## Execute
+
+Run the chain in order, starting immediately after the preview. Each step's permission dialog is the confirmation gate. Do not pause for additional confirmation. Run from the target project's current directory.
+
+Step 1: `canon init` installs base tooling, claude seeds, governance rules, and wiki.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon init \
+  --stack <stack> \
+  --add <rules> \
+  <target>
+```
+
+Omit any flag whose resolved value is empty.
+
+Step 2: `canon tooling sync <tooling-stack> --write` installs stack deps, scripts, gitignore entries, seeds, golden configs, and drops the reference doc. The extends chain is walked, so syncing `vite-react` also pulls `web` and `base` configs. Skip if the tooling stack is `base` (already synced by `canon init`).
+
+`--write` is required. A headless run without it reports what it would replace and exits 1, since golden configs overwrite whatever the target holds at those paths. Scaffolding into a fresh target has nothing to lose, so pass it directly rather than reading a report first.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon tooling sync <tooling-stack> <target> --write
+```
+
+Monorepo with multiple language roots: run `canon init` once at the repo root so `base` (husky, prettier, cspell, commitlint, CI) lands single, then sync each subtree with `--skip base` so the shared layer is not re-dropped.
+
+```bash
+CANON_NON_INTERACTIVE=1 canon tooling sync vite-react ./frontend --skip base --write
+CANON_NON_INTERACTIVE=1 canon tooling sync python ./backend --skip base --write
+```
+
+Without `--skip base`, each subtree re-drops husky, and git honors only one `core.hooksPath`, so the extra hook dirs silently break. Each subtree keeps its own framework configs, and its own stack reference reads through `canon tooling reference <stack>`.
+
+Step 3: post-sync fixups. Golden configs arrive from sync, so no config generation is required. But a few items may need a one-time touch:
+
+- **ESLint version pin.** If `bun create vite` installed `eslint@^10` and the manifest pins `eslint@^9`, sync does not override a present dep. Run `bun add -d eslint@^9` if `bun run lint:fix` fails with `Class extends value undefined`.
+- **File naming.** `bun create vite`'s `App.tsx` violates the `KEBAB_CASE` rule. Rename to `app.tsx` and update the import in `main.tsx`.
+- **Docs.** Run `canon tooling reference <tooling-stack>` and `canon tooling reference web` for any stack-specific follow-ups (Chrome extension overrides, setup script details).
+
+Do not generate ESLint, Vitest, or Playwright configs. They ship as golden files. Generating from prose duplicates what sync already installed.
+
+Step 4: invoke `setup-verify`. Runs the `package.json` scripts and reports pass/fail.
+
+## Report
+
+After the chain, report:
+
+- Domains installed with a check per domain
+- Tooling stack synced (or skipped). Name the layers pulled via the extends chain.
+- Any post-sync fixups applied (ESLint pin, filename renames)
+- `setup-verify` outcome
+- Any domains or scripts that failed
+- Any detection gaps surfaced during resolve
+- Onboarding steps left to the caller: `setup-indexes` for the `index.md` system, `setup-plugins` for Claude Code plugins

package/claude/skills/setup-plugins/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: setup-plugins
+description: Why plugin installs read a curated catalog, install user-scoped, and never touch toolkit workflow skills
+---
+
+# Setup plugins requirement
+
+## Gap
+
+Without this skill, a session asked to install plugins invents marketplace sources and install strings from names it half remembers, and a plugin name that does not exist fails in a way that reads like a network problem. The catalog is the difference between an install and a guess.
+
+Scope is the failure that shows up later. A domain plugin installed into one project is missing from the next one, so the machine looks provisioned until the user opens another repository. The mirror mistake is treating toolkit workflow skills as plugins to install, when they load live through a plugin directory and a copied version goes stale the moment it lands.
+
+Two failures come from running the batch carelessly. A reinstall over a plugin already present costs time and can replace a working version. And a batch that aborts on the first failure leaves a partial install with no record of which rows ran, so the next attempt starts from an unknown state.
+
+## Must
+
+- Read the curated catalog through the skill's own directory, so the path resolves from any project
+- Detect what is already installed and skip those rows
+- Install user-scoped, since a domain plugin belongs to the machine rather than to one project
+- Run each install independently so one failure does not abort the batch
+- Preview the chosen rows, the scope, and the exact commands before executing
+- Report the failures with their CLI errors, the reload requirement, and the settings-level remedy for an over-triggering plugin
+
+## Must not
+
+- Install a plugin, marketplace, or command string that is not in the catalog
+- Install toolkit workflow skills, which load live rather than being copied
+- Reinstall a plugin already present
+- Pause for a confirmation beyond the tool permission dialog
+
+## Guards
+
+- The `claude` CLI absent from PATH stops before any install, since every step shells out to it
+- A catalog row that installs outside the plugin CLI runs its own installer verbatim rather than being forced through the marketplace path
+
+## Out of scope
+
+- Curating the catalog, which is an edit to the bundled reference rather than a run of this skill
+- Uninstalling, since an over-triggering plugin is tuned through settings rather than removed
+- Installing anything into a project, which every setup skill but this one does
+- First-time project scaffolding: `setup-init`