@erclx/aitk 0.38.0 → 0.40.0

package/README.md

@@ -65,7 +65,7 @@ Scaffolding your first project? Start with target projects, then the AI workflow
 - [Operating model](docs/operating-model.md): orchestrator and worker roles for building across parallel sessions
 - [Visual design workflow](docs/visual-design-workflow.md): tiered guide for design and wireframe authoring
 - [Target projects](docs/target-projects.md): scaffold, add a domain later, sync upstream drift
-- [Agents](docs/agents.md): CLI flags, exit codes, and JSON output shapes
+- [Agents](docs/agents/index.md): CLI flags, exit codes, and JSON output shapes
 - [Docs index](docs/index.md): every reference doc in this repo
 
 ## Development

package/claude/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "aitk",
   "description": "Automated governance, versioning, and discovery tools for Claude Code.",
-  "version": "0.38.0",
+  "version": "0.40.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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

@@ -36,7 +36,7 @@ Read these from the project root on both paths, skipping any that do not exist:
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
-On the source path, also read the UI surfaces matched in Step 1 plus `docs/agents.md` and `docs/index.md` for output shape or framing rules already documented.
+On the source path, also read the UI surfaces matched in Step 1 plus `docs/agents/output-shape.md` and `docs/index.md` for output shape or framing rules already documented.
 
 On the greenfield path, also read `.claude/ARCHITECTURE.md` for platform, tech stack, and surface type. Do not scan `src/`, stylesheets, or UI modules. Step 1 already established they hold nothing.
 

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

@@ -7,13 +7,14 @@ description: What feature planning is for, the gaps it closes, and why it stops
 
 ## Gap
 
-Without this skill, implementation starts before anyone knows what it touches. A session reads no project context and rediscovers a settled constraint halfway through, the file list emerges as the work goes rather than before it, and the ambiguities that needed a decision get resolved silently in whichever direction the first edit happened to go.
+Without this skill, implementation starts before anyone knows what it touches. A session reads no project context and rediscovers a settled constraint halfway through, the file list emerges as the work goes rather than before it, and the ambiguities that needed a decision get resolved silently in whichever direction the first edit happened to go. A constraint naming a surface to leave alone forbids two different acts at once, so the executing session picks one and the branch either grows an excluded concern or ships a reference to a file the change deleted.
 
 ## Must
 
 - Read the project's own Claude setup before scanning source, so the plan inherits decisions already made instead of reopening them
 - Name every file the work touches with the reason it is touched
 - Surface each unresolved ambiguity as a numbered question carrying a suggested answer and an empty answer slot, so the plan is decision-ready in one pass
+- State which act a constraint forbids when it names a surface to leave alone, since conforming that surface and retargeting a pointer into it are different acts and only one is out of scope
 - Scale the output to the work. A two-file change with nothing to decide should not produce a plan file.
 - Stop at the plan and wait to be told to continue
 

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

@@ -38,13 +38,21 @@ Measure against the tree rather than recall. Grep for each construct the plan wi
 Construct the plan with these sections:
 
 - **Summary:** three to five one-line bullets covering the goal, the main deliverables, and the key trade-off or decision. Aimed at humans scanning the plan, not agents executing it. Full mode only.
-- **Constraints:** durable rules the work must respect (patterns to reuse, surfaces not to touch, platform limits). Optional. Include when an orchestrator or prior context supplies them, omit the section otherwise.
+- **Constraints:** durable rules the work must respect (patterns to reuse, surfaces not to touch, platform limits). Optional. Include when an orchestrator or prior context supplies them, omit the section otherwise. A constraint naming a surface to leave alone carries the distinction under Constraints below.
 - **Files to touch:** each file with a one-line reason
 - **Risks:** conflicts, coupling, or tricky spots. When the plan establishes a resource with more than one consumer, list the consumers and mark each read or write, because a policy stated over that resource has to hold for the writers and not just the consumer that prompted it. If none, use `None identified.`
 - **Questions:** numbered list of things to resolve before starting. Each carries a `- Suggested:` line and an `- Answer:` slot (see Suggestions below). If none, use `None identified.`
 
 Prefer `None identified.` over low-signal fillers. A small feature should produce a short plan, not a padded one. Small mode skips the summary since the plan is already short enough to scan in full.
 
+### Constraints
+
+A constraint naming a surface to leave alone forbids two different acts. Name which one, since a constraint carrying only the surface leaves the executing session to guess.
+
+- Forbid conforming the surface to whatever shape the change introduces. This is the act a scope constraint means, and it keeps the branch from growing a second concern.
+- Never forbid retargeting a pointer the change breaks. A rename, a split, or a deletion that leaves a citation behind ships a dangling reference, so fixing it is required work rather than scope creep.
+- Decide both acts for every surface the constraint names. Carving the distinction out for one file and leaving its siblings under the bare wording is how a plan ships one correct call beside one broken reference.
+
 ### Suggestions
 
 Attach a `- Suggested:` line to every question, then an empty `- Answer:` slot below it. A blank answer means accept the suggestion at execution time. This makes the plan decision-ready in one pass, with no separate decision-help round.

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

@@ -39,4 +39,4 @@ The band gets picked by feel, so a UI copy rule lands in the always-on range and
 - 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 or a snippet, which `create-standard` owns
+- A standard, which `create-standard` owns, and a snippet, which `create-snippet` owns

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

@@ -9,16 +9,20 @@ description: What skill creation is for, the gaps it closes, and why it confirms
 
 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.
+
 ## Must
 
 - Read the authoring standard and the prose standard before drafting, so the draft starts conformant rather than getting corrected into shape
-- Confirm the name and the full body with the user before writing. The name is the routing key and a folder that disagrees with its frontmatter fails silently.
+- 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 before the user has seen the body
+- 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
 
 ## Guards
 

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

@@ -20,5 +20,8 @@ Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the pro
 ## Steps
 
 1. Draft the full `SKILL.md` from the user's description
-2. Confirm the skill name and full content with the user before writing
-3. Write to `.claude/skills/<name>/SKILL.md`
+2. 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.
+3. Confirm the skill name and both files with the user before writing
+4. 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.

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

@@ -0,0 +1,36 @@
+---
+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 holds only the installed copy under `.claude/snippets/`, 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.
+
+## 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
+- 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 `aitk 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

@@ -1,13 +1,31 @@
 ---
 name: create-snippet
-description: Retired. `create-standard` absorbed this skill and writes snippets as well as standards. Invoke `aitk:create-standard` instead.
-disable-model-invocation: true
+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
 
-Retired. `create-standard` absorbed the snippet surface, resolves `snippets/` or `.claude/snippets/` the same way it resolves the standards folders, and its description carries every trigger this skill used to route on.
+Creates one snippet file. Read these files in parallel:
 
-Invoke `aitk:create-standard` instead and ask for a snippet. The name understates what the skill covers, which is why its description names both surfaces.
+- `.claude/standards/prose.md` from the project root: prose conventions for all generated text
+- `${CLAUDE_SKILL_DIR}/references/snippets.md`: authoring conventions, invocation channels, use patterns
 
-This body exists so a project that installed the plugin before the merge keeps resolving the old name for one sync cycle. It ships in `0.18.0` and is removed in `0.19.0`.
+Read `${CLAUDE_SKILL_DIR}/../../standards/prose.md` instead when the project does not have it.
+
+## 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 target project's installed copy.
+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 to `<surface>/<category>/<slug>.md`, or to `<surface>/<slug>.md` when the snippet takes no category
+
+## 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. `aitk snippets sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. 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 → create-snippet}/references/snippets.md

@@ -1,7 +1,7 @@
 ---
 title: Snippet reference
 description: Snippet reference and authoring conventions
-consumers: create-standard
+consumers: create-snippet
 ---
 
 # Snippet reference

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

@@ -0,0 +1,38 @@
+---
+name: create-standard
+description: Why a standard needs its shape read from the meta-standard and its write surface resolved before anything is drafted
+---
+
+# 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 write surface is the second failure. The toolkit authors at `standards/` and a target project holds only the installed copy under `.claude/standards/`, so a session picks whichever folder it noticed first. A toolkit standard written into the consumed copy fails the drift assertion that regenerates that folder. A standard 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.
+
+A standard written at the root 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
+- Resolve the write surface from which standards folder the project has, rather than from whichever one the session noticed first
+- 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 and 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
+
+## Guards
+
+- Neither standards folder exists: stop, since there is nowhere for the standard to live
+
+## Out of scope
+
+- Editing a standard that already exists
+- A snippet, which `create-snippet` owns
+- A path-scoped coding rule, which `create-rule` owns
+- Installing and syncing the standards the toolkit ships, which the `aitk standards` commands own

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

@@ -1,29 +1,25 @@
 ---
 name: create-standard
-description: Creates a new standard file in `standards/` or `.claude/standards/`, or a new snippet file in `snippets/` or `.claude/snippets/`. Use when asked to create a standard, add a standard, write a new authoring convention, create a snippet, add a snippet, or make a new snippet. Do NOT use to edit an existing standard or snippet.
+description: Creates a new standard file in `standards/` or `.claude/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 authoring file on either surface. Read the user's request for which artifact they asked for, standard or snippet, and carry that choice through every step below. Ask only when the request names neither.
-
-Read these files in parallel:
+Creates one standard file. Read these files in parallel:
 
 - `.claude/standards/prose.md` from the project root: prose conventions for all generated text
-- `.claude/standards/standard.md` from the project root, for a standard: the meta-standard for shape, frontmatter, and structure
-- `${CLAUDE_SKILL_DIR}/references/snippets.md`, for a snippet: authoring conventions, invocation channels, use patterns
+- `.claude/standards/standard.md` from the project root: the meta-standard for shape, frontmatter, and structure
 
 Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
 
 ## Guards
 
-- For a standard, if neither `standards/` nor `.claude/standards/` exists, stop: `❌ No standards/ or .claude/standards/ directory found.`
-- For a snippet, if neither `snippets/` nor `.claude/snippets/` exists, stop: `❌ No snippets/ or .claude/snippets/ directory found.`
+- If neither `standards/` nor `.claude/standards/` exists, stop: `❌ No standards/ or .claude/standards/ directory found.`
 
 ## Steps
 
-1. Resolve the write surface for the chosen artifact: the root folder (`standards/` or `snippets/`) if present, the toolkit's own authoring source. Otherwise the `.claude/` folder, a target project's installed copy.
-2. Draft the content from the user's description. A standard follows `standard.md` for frontmatter, headings, and structure.
+1. Resolve the write surface: `standards/` at the root if present, which is the toolkit's own authoring source. Otherwise `.claude/standards/`, a target project's installed copy.
+2. Draft the content from the user's description. The meta-standard governs frontmatter, headings, and structure.
 3. Confirm the slug and full content with the user before writing
 4. Write the file to `<surface>/<slug>.md`
 
@@ -31,5 +27,5 @@ Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the pro
 
 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/`. For a standard, that pass also regenerates the `standards/index.md` entry, and the user adds a row to the standards table in `.claude/context/standards.md`.
-- `.claude/` surface: the file is project-local. `aitk standards sync` and `aitk snippets sync` leave it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md` or `snippets/<category>/<name>.md`, if it should ship to every project.
+- Root surface: this is the toolkit's 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.md`.
+- `.claude/` surface: the file is project-local. `aitk standards sync` leaves it alone, since sync only updates filenames it recognizes from the toolkit. Remind the user to copy it to the toolkit repo, under `standards/<slug>.md`, if it should ship to every project.

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

@@ -0,0 +1,41 @@
+---
+name: migration-claude-md
+description: Why a bloated CLAUDE.md is rebalanced by proposal rather than by edit, and what the seed baseline settles
+---
+
+# Migration claude md requirement
+
+## Gap
+
+Without this skill, a session asked to slim `CLAUDE.md` deletes sections it judges stale and writes the rest into files it creates in the same pass, so a classification the user disagrees with is no longer one command to undo. The file is always-load context, so a wrong move costs every later session rather than one.
+
+Three more failures share a cause. The session has no baseline for what belongs in `CLAUDE.md`, so it reads toolkit-seeded always-load behavior as bloat and proposes moving it, and the next seed sync puts it back. A section carrying a rule and a narrative together gets sorted whole into one bucket, which loses half of it either way. And a target that already exists gets written over, since a proposal blind to the folder cannot tell a create from a collision.
+
+The skill also writes into `.claude/context/`, a folder `migration-context` moves files into. A proposal drafted before those moves land cannot see the entries they create, so a move that should have resolved to an append reads as a create.
+
+## Must
+
+- Classify every `##` section against the three tiers in a fixed order, so the same section lands the same way twice
+- Treat a section matching the seed baseline as always-load by definition and propose no move for it
+- Read the existing rules and context folders before resolving a target, so an existing entry resolves to an append and a taken rule slot resolves to a conflict
+- Derive a rule's glob from the scope the section names rather than from the folder it describes
+- Propose and stop, leaving every file write and the `CLAUDE.md` edit to the user
+- Report the already-lean case as a pass rather than manufacturing moves to justify the run
+
+## Must not
+
+- Sort a section holding both a rule and a narrative into either bucket. Flag it for a manual split.
+- Create a rule file, create a context entry, or edit `CLAUDE.md`
+- Propose a move onto an existing rule path. Report it as a conflict and skip it.
+
+## Guards
+
+- No `CLAUDE.md` at the project root stops before any classification runs
+- Fewer than three `##` sections reports the file already lean, since a rebalance needs something to rebalance
+
+## Out of scope
+
+- Relocating `docs/` files, which `migration-context` proposes into this same `.claude/context/` folder. Run that skill first when both apply, so Step 3 reads a folder its moves have already populated.
+- Relocating root `standards/` and `snippets/`: `migration-standards`
+- Scaffolding the rule files it proposes, which `create-rule` does with the numbering and frontmatter
+- Regenerating `.claude/context/index.md`, which `aitk indexes regen` does once the user has applied the moves

package/claude/skills/migration-standards/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: migration-standards
+description: Why the root-to-.claude relocation ships as git mv commands the user runs, and which inbound references are worth fixing
+---
+
+# Migration standards requirement
+
+## Gap
+
+Without this skill, a project whose rules cite `.claude/standards/` while the files sit at the root gets fixed by hand, and the hand fix loses what version control was holding. A plain `mv` breaks the rename chain, so every relocated standard reads as a delete beside an unrelated add and its history stops at the move.
+
+Three failures follow from acting without looking first. A move onto an existing `.claude/standards/` copy overwrites the files already installed there, which is the case the relocation was supposed to be unnecessary for. A `git mv` on a dirty tree lands the relocation in the same commit as unrelated work, so neither can be reviewed or reverted alone. And a session that rewrites every inbound reference spends its effort on toolkit-owned rules and skills, which the next sync overwrites, while the author-owned lines that actually break go unmentioned.
+
+## Must
+
+- Detect an existing copy under `.claude/` and skip that folder's move rather than merging into it
+- Read the working tree state and require it clean before the moves, since the relocation has to be revertible on its own
+- Propose `git mv` so history follows each file
+- Report author-owned inbound references as TODO lines the user fixes, and leave the reference itself untouched
+- Name the re-sync commands that reinstall toolkit-owned content at the new path, since the move alone leaves the install stale
+- Report the already-relocated case as a pass
+
+## Must not
+
+- Run the moves, or edit `CLAUDE.md`, a rule file, or a doc
+- Surface references inside toolkit-owned rules and skills, which the next sync rewrites anyway
+
+## Guards
+
+- Neither root `standards/` nor root `snippets/` present stops, since there is nothing to relocate
+- A directory that is not a git work tree stops, since `git mv` needs version control and a plain move is the failure the skill exists to prevent
+
+## Out of scope
+
+- Classifying `CLAUDE.md` sections into the three-tier model: `migration-claude-md`
+- Relocating `docs/` files by audience: `migration-context`
+- Running the re-sync, which the user does after applying the moves
+- What each sync command overwrites once it runs: `toolkit-cli`

package/claude/skills/project-commands/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+name: project-commands
+description: Why running a documented command stops at the report, and what a single-file read buys over framework inference
+---
+
+# Project commands requirement
+
+## Gap
+
+Without this skill, a session asked to start the app infers a command from a framework it recognizes or a script name it likes the look of, and a project whose dev loop differs from the convention gets the convention anyway. The user cannot see it was a guess, because a guess and a read produce the same first line.
+
+The larger failure is the one past the launch. A session that starts a server keeps going into log reading, browser checks, and defects it noticed on the way, so a request that was one command becomes an open-ended investigation nobody asked for and the answer arrives buried. A request covering a frontend and a backend gets one of the two, which reports success on half an app.
+
+Two more failures are mechanical. A command that stays up run in the foreground blocks until the tool timeout, which reports as a service that never came up while nothing is left running. And a command whose effect outlives the process, such as a deploy or a migration, is not undone by stopping it, so running it to see what happens is not available.
+
+## Must
+
+- Read the documented dev loop and treat it as the only source, since a second file is a discovery chain and this skill has none
+- Match the request against the stated purpose rather than the command name, since a project documenting two similar commands means the distinction
+- Resolve every documented command the request covers, not the first one that matches
+- Background a command that stays up, and read its output back before checking anything against it
+- Report the port, URL, or exit status per command, then end the turn
+
+## Must not
+
+- Infer a command from a filename, a framework, or a second file
+- Stop, restart, or reconfigure a process the skill did not start, or tear down one it did
+- Continue past the report into a second check, a screenshot, or a defect report. Say in one line that one looks warranted and let the user decide.
+- Abandon the remaining commands when one fails
+
+## Guards
+
+- No documented dev loop stops by naming the missing file, since a reconstruction the user cannot see through is worse than a stop
+- A request matching nothing documented lists what is documented instead of inferring
+- A command whose effect outlives the process prints for the user to run rather than running, judged on the effect rather than the name
+
+## Out of scope
+
+- Confirming a change works in the running app, which is a verification request and needs the steps this skill refuses
+- Deploying, publishing, releasing, migrating, and resetting
+- Running the scaffold verification chain against `package.json` scripts: `setup-verify`
+- Writing the entry it reads, which belongs to the project's own development docs

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

@@ -0,0 +1,38 @@
+---
+name: session-resume
+description: Why resuming 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.
+
+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
+
+- Resolve the 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
+- 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
+- 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 three surfaces absent or empty reports no tracked work and stops, rather than inventing a next step from the repository
+
+## Out of scope
+
+- 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/setup-indexes/REQUIREMENT.md

@@ -0,0 +1,42 @@
+---
+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.
+
+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
+
+## 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 `aitk 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

@@ -145,4 +145,4 @@ Replace bracketed values with the values from this run. Drop the "Folders bootst
 ## Reference
 
 - `.claude/context/indexes.md`: system rationale, frontmatter contract, when to adopt
-- `docs/agents.md`: `aitk indexes regen` flags, exit codes, JSON shape
+- `docs/agents/indexes.md`: `aitk indexes regen` flags, exit codes, JSON shape

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`

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

@@ -0,0 +1,39 @@
+---
+name: setup-verify
+description: Why a fresh scaffold is checked with declared leaf scripts in a fixed order, and what the excluded stages would cost
+---
+
+# Setup verify requirement
+
+## Gap
+
+Without this skill, a freshly scaffolded project is handed over on the strength of the configs looking right, and the first typo surfaces when the user runs something. A scaffold is generated from a reference, so the errors it carries are wiring mistakes and missing dependencies, both of which any script run would have caught.
+
+The naive check fails two ways. A session that assumes script names runs `test` against a stack that exposes `test:run`, or invents a fallback command when a script is absent, and either result reports on something the project never declared. A session that runs a composite script gets one failure covering several stages, so the output names the wrapper rather than the break.
+
+The stages left out are the ones that lie. A dev server or a preview reads as failed when it starts slowly, a browser test needs an install and a running server before it can even fail correctly, and a CI workflow cannot be judged locally at all. Including any of them turns a scaffold check into a flaky one, and a flaky check gets ignored.
+
+## Must
+
+- Read the scripts the project declares and run only those
+- Run leaf scripts in a fixed order, so a failure points at the exact stage that broke
+- Stop at the first failure and surface its output rather than continuing to collect more
+- Report per script and close with one summary line naming the failing stage when there is one
+
+## Must not
+
+- Invent a fallback command for an absent script. Skip it.
+- Run a composite script, which hides which stage broke
+- Run a dev server, a preview, or a browser test
+
+## Guards
+
+- No `package.json` at the project root stops, since there are no declared scripts to read
+- A missing dependency folder installs first rather than letting every script fail on the same cause
+
+## Out of scope
+
+- Dev and preview smoke tests, which `project-commands` starts on request
+- Browser end-to-end tests, which need a browser install and a running server
+- CI workflow validation, which runs on the pull request rather than locally
+- Generating the configs it checks, which the tooling stack reference owns