@erclx/aitk 0.38.0 → 0.39.0

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.39.0",
   "author": {
     "name": "Eric Le",
     "url": "https://github.com/erclx"

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-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

package/claude/skills/systematic-debugging/REQUIREMENT.md

@@ -0,0 +1,41 @@
+---
+name: systematic-debugging
+description: Why a fix is blocked until investigation completes, and what the three-attempt stop is measuring
+---
+
+# Systematic debugging requirement
+
+## Gap
+
+Without this skill, a session handed a failure proposes a fix from the first plausible reading of the error, and the fix is judged by whether the symptom moved. A symptom that moves is the normal result of changing something near it, so the session reports success and the cause is still there.
+
+The compounding failures come next. Several changes go in at once, so a pass says nothing about which one mattered. A fix that fails gets another fix stacked on top of it rather than a new hypothesis, and the code accumulates changes nobody can trace to a reason. A bad value gets corrected where it was observed rather than where it was produced, which moves the failure downstream instead of removing it.
+
+Two failures are about stopping rather than about fixing. A session that never counts its attempts keeps fixing through the pattern where each fix reveals a problem elsewhere, which is architectural and cannot be reached from inside the loop. And a session that concludes an issue is environmental usually has an incomplete investigation rather than an environmental issue, because that conclusion is available at any point and is never contradicted by evidence.
+
+## Must
+
+- Complete the investigation before any fix is proposed, reading the failure in full and reproducing it
+- Trace a bad value back to where it was produced and fix there
+- Compare the broken code against working code in the same codebase before hypothesizing
+- State one hypothesis and change one variable to test it
+- Write the failing test before the fix, so the fix is judged against a reproduction rather than against the symptom
+- Stop after three failed attempts and hand the architectural question to the user
+
+## Must not
+
+- Stack a second fix on a failed one rather than forming a new hypothesis
+- Bundle a refactor or an unrelated improvement into the fix
+- Accept an environmental or timing conclusion before the investigation is exhausted
+- Claim an understanding it does not have
+
+## Guards
+
+- An incomplete investigation blocks the fix proposal, which is the skill's one refusal and the reason it exists
+- Three failed attempts stop the loop, since the pattern is evidence about the design rather than about the bug
+
+## Out of scope
+
+- A typo fix and a cause already agreed on, where the phases cost more than they return
+- Reviewing a change for defects it has not yet exhibited: `claude-review`
+- Deciding whether the architecture should change, which the three-attempt stop hands to the user rather than answering

package/claude/skills/toolkit-cli/REQUIREMENT.md

@@ -0,0 +1,37 @@
+---
+name: toolkit-cli
+description: Why the overwrite contract is stated before a sync runs, and why the skill reads rather than executes
+---
+
+# Toolkit cli requirement
+
+## Gap
+
+Without this skill, a session runs an `aitk` sync and finds out afterward what it did. The command names give nothing away. `install` and `sync` differ per domain, some surfaces overwrite unconditionally, some merge, some are written once and never touched again, and none of that is visible from the command line the user typed.
+
+The damage lands on the files a project owns. A golden config carrying local edits is replaced without a warning anyone saw, and a standards install overwrites every standard in a project that only needed the two it had drifted on. The user learns which category a file was in by losing the edit.
+
+The inverse failure is quieter. A session that assumes a sync will pick up a change edits a seed and waits for an update that never comes, because the seed is copy-once and no sync command writes it again. Both failures are one missing fact available before the command runs.
+
+## Must
+
+- State per surface and per command whether an existing file is overwritten, merged, written once, or left alone
+- Warn about a destructive run before it happens, naming the surface that will be lost
+- Name the section-preserving path for a standard or seed the project has customized
+- Defer to the toolkit's own context docs when they and this summary disagree, since the summary is a copy and they are the source
+
+## Must not
+
+- Run any `aitk` command. The skill is read before acting.
+- Restate the full semantics. It is a target-session summary and the detail lives with its owner.
+
+## Guards
+
+- A surface or command the contract does not cover routes to the context docs rather than to an inference from a similar row
+
+## Out of scope
+
+- Executing the sync, which the user runs or `toolkit-operator` routes
+- Reconciling a customized seed section by section: `claude-seed-sync`
+- Relocating a project's folders into the layout a newer version expects: `migration-standards`
+- Deciding which stack, rule, or standard a project should install, which the setup skills resolve from live catalogs

package/claude/skills/toolkit-feedback/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: toolkit-feedback
+description: Why a toolkit defect is reported from session context alone, and what shipping through the CLI replaces
+---
+
+# Toolkit feedback requirement
+
+## Gap
+
+Without this skill, a toolkit defect noticed inside a target project dies with the session. The user is told to mention it in the toolkit repository later, which means retyping a report they no longer have the context to write, so the defect is either reported badly or not at all.
+
+The report itself fails two ways. A block printed in chat needs a copy-paste into another repository, and a step that manual is skipped under any time pressure. A report that names no surface cannot be routed, because the toolkit acts on a plugin skill, a snippet, a CLI command, and a seed through different paths, and the difference is not recoverable from the symptom.
+
+The last failure is the session's own effort. Asked to report, a session starts diagnosing instead, searching the toolkit and reading its surfaces to find the cause. That spends the context the report was meant to capture cheaply, and it produces a diagnosis from a project that cannot see the toolkit's current source.
+
+## Must
+
+- Build the report from what the session already holds
+- Name the surface and its type, since the toolkit routes on that rather than on the symptom
+- Write the stated fallback for a field the session cannot fill, so an empty field reads as absent rather than as unreported
+- Ship through the CLI so the report lands without a copy-paste, and print the returned path on its own line
+- Offer the durable route for a report worth keeping across sessions and machines
+- Fall back to printing the block when the CLI is absent, so the report still exists
+
+## Must not
+
+- Probe the project, list files, grep, or read toolkit surfaces to enrich the report
+- Guess the surface type when the session is ambiguous. Ask one line.
+- Diagnose or fix, which needs the toolkit's source rather than the target's
+
+## Guards
+
+- Nothing in session context pointing at a toolkit issue stops, since a report assembled from nothing wastes the triage it reaches
+
+## Out of scope
+
+- Fixing the defect, which happens in the toolkit repository against its own source
+- Draining the queue this fills: `toolkit-triage`
+- Filing an issue against the current project: `git-issue`
+- Complaints about tooling the toolkit does not own

package/claude/skills/toolkit-operator/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: toolkit-operator
+description: Why the toolkit has one front door, what orienting on live catalogs prevents, and where it hands off
+---
+
+# Toolkit operator requirement
+
+## Gap
+
+Without this skill, using the toolkit means knowing which skill to pick, and the user who most needs it is the one who cannot. A plain-language intent has no obvious owner among a dozen setup and sync skills, so the session guesses a command instead of resolving one, and a wrong guess installs into a project rather than reporting a mismatch.
+
+Two failures come from acting on memory. A session that names a stack, rule, or snippet from what it remembers rather than from the live catalog runs against an entry that has been renamed or removed. And a session that edits a managed file by hand produces a change the next sync overwrites, which reads as the toolkit undoing work rather than as the edit having been made in the wrong place.
+
+The last failure is duplication. A front door that answers everything itself reimplements first-time detection and seed diffing inline, badly, beside the skills that already do both. The value of a router is that it stops at the handoff.
+
+## Must
+
+- Orient on the toolkit's own docs and the live catalogs before acting
+- Map the stated intent to one lifecycle phase, then either run the simplest command that satisfies it or hand off
+- Resolve every stack, rule, snippet, and standard name from a catalog at runtime
+- Run the CLI non-interactively and report the command run, what changed, and the full path of anything written
+
+## Must not
+
+- Edit a managed file by hand instead of running the CLI that owns it
+- Reimplement a flow another skill owns
+- Hardcode a catalog name
+- Auto-trigger. It is a door the user opens, and a router that fires on its own routes requests nobody made.
+
+## Guards
+
+- An intent matching a deep flow hands off rather than running a shallow version of it, since a partial scaffold is harder to recover from than none
+
+## Out of scope
+
+- First-time scaffold of a fresh project: `setup-init`
+- Seed and preamble drift in installed files: `claude-seed-sync`
+- Governance rule install and index bootstrap: `setup-gov` and `setup-indexes`
+- What a given sync overwrites once it runs: `toolkit-cli`

package/claude/skills/toolkit-triage/REQUIREMENT.md

@@ -0,0 +1,40 @@
+---
+name: toolkit-triage
+description: Why the feedback queue is read from GitHub rather than local scratch, and why triage routes instead of implementing
+---
+
+# Toolkit triage requirement
+
+## Gap
+
+Without this skill, the feedback queue fills and nothing drains it. Reports arrive from projects the toolkit never sees, and a queue nobody reads on a schedule is the same as no queue. The local review folder looks like the right place to read, and it is the wrong one, because that content is per-machine session scratch that any cleanup removes.
+
+Triage fails three ways once it starts. Unrelated issues get batched into one branch, so review has to judge several unconnected changes at once and can approve none of them cleanly. An issue needing a plan gets implemented inline from a paragraph of description, which skips the step where scope is argued. And an issue whose report contradicts itself gets a guess rather than a question, so the fix addresses a defect nobody confirmed.
+
+The queue also fails to drain even when the work ships. A fix merged with no link back leaves its issue open, and the next triage re-reads work already done.
+
+## Must
+
+- Read the durable queue rather than local session scratch
+- Classify each issue in a fixed order and stop at the first match, stating the class and its one-line reason before routing
+- Route to the skills that own planning, branch naming, and the pull request body rather than restating them
+- Keep one issue to one branch and one pull request
+- Link a fix to its issue so merge closes it, and preserve that link when the body is regenerated
+- Ask on the issue when the report is unreadable, then move on rather than blocking the batch
+
+## Must not
+
+- Batch unrelated fixes into one branch
+- Implement a plan-worthy issue, which stops at the plan handed back to the user
+- Close an issue whose pull request has yet to merge
+
+## Guards
+
+- The `gh` CLI absent or unauthenticated stops, since the queue is unreachable
+- An empty queue reports nothing open rather than widening the label to find work
+
+## Out of scope
+
+- Filing new feedback: `toolkit-feedback`
+- Writing the plan a plan-worthy issue needs: `claude-feature`
+- Triage of issues carrying any other label, which surface here by design only under the feedback label

package/claude/skills/youtube-transcripts/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: youtube-transcripts
+description: Why the transcript fetch stays in the CLI, and why fetching stops short of reading
+---
+
+# Youtube transcripts requirement
+
+## Gap
+
+Without this skill, a pasted video link turns into captions printed in chat, which persist nowhere and cannot be cited by a later session. The file is the point. A transcript saved with its metadata is context the repository holds, and a transcript in a message is context that ends with the turn.
+
+A session that fetches on its own gets the shape wrong. Raw captions carry timing cues and duplicated lines, and a file written without frontmatter has no title, no source URL, and no way to tell which video it came from. Reimplementing the cleanup also duplicates logic the CLI already owns, so the two drift and the drift shows up as inconsistent files rather than as an error.
+
+Two smaller failures follow the fetch. A video with no captions produces a file that looks empty rather than one reported as having none, so the user reads it as a failed fetch. And a session that summarizes what it fetched answers a question nobody asked, spending context on a reading the user may not want yet.
+
+## Must
+
+- Run the CLI, which owns the fetch, the caption cleanup, and the frontmatter
+- Surface the written path as a full relative path so the terminal makes it clickable
+- Report a video with no captions as a fact about the video, since the file still exists and carries its metadata
+- Name the missing external binary and stop, leaving the install to the user
+
+## Must not
+
+- Reimplement the fetch or the cleanup
+- Summarize or annotate the transcript unasked, which is a separate request against the file
+- Install the external binary the command shells out to
+
+## Guards
+
+- No URL stops, since there is nothing to fetch
+- A link that is not a YouTube URL stops rather than attempting a generic fetch the command cannot do
+
+## Out of scope
+
+- Downloading the video or its audio
+- Summarizing a transcript already on disk, which is a read of that file
+- Choosing where transcripts live, which the command defaults and a flag overrides

package/docs/agents.md

@@ -466,10 +466,11 @@ one malformed file cannot hide the rest of the catalog. `--names` emits skill
 names one per line.
 
 Each entry also carries `requirement`, whether the folder holds a sibling
-`REQUIREMENT.md`. Coverage of that file is selective by design, so a `false` is
-not a gap to close and the flag answers which skills carry one without a caller
-listing the directory itself. It says nothing about why, which is a judgment the
-toolkit records against its own corpus rather than in the catalog.
+`REQUIREMENT.md`. Every skill is meant to carry one, so a `false` is a gap to
+close rather than a recorded exemption, and the flag answers which skills are
+missing theirs without a caller listing the directory itself. Nothing gates the
+rule yet, which is why the flag is worth reading against the shipped corpus after
+a merge.
 
 ## Non-interactive examples
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@erclx/aitk",
   "type": "module",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Infrastructure and quality tooling for developer workflows",
   "license": "MIT",
   "bin": {

package/scripts/manage-sandbox.sh

@@ -296,6 +296,10 @@ inject_changed_skills() {
   [ -z "$combined" ] && return
 
   while IFS= read -r skill_path; do
+    # The diff against main lists a deleted skill alongside a changed one, and
+    # there is nothing left to inject for a name this branch removed.
+    [ -f "$PROJECT_ROOT/$skill_path" ] || continue
+
     local skill_name
     skill_name=$(basename "$(dirname "$skill_path")")
     local target_dir="$SANDBOX/.claude/skills/$skill_name"

package/src/sandbox/census.ts

@@ -70,7 +70,7 @@ export function listSkills(root: string): string[] {
  * Maps a scenario to the skill it drives, trying two spellings in order.
  *
  * `<category>-<command>` is the rule `.claude/context/sandbox/coverage.md` states, and it
- * alone pairs 29 of 55 skills. The bare `<command>` fallback is what reaches the
+ * alone pairs 29 of 54 skills. The bare `<command>` fallback is what reaches the
  * rest: `claude/setup-init.sh` drives the `setup-init` skill, not a
  * `claude-setup-init` that does not exist. Stating one spelling and shipping two
  * is what let the audit report a paired skill as unpaired.

package/standards/bundled/snippets.md

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

package/standards/skill.md

@@ -11,7 +11,7 @@ Skills give Claude Code domain-specific constraints and rules inline, so it can
 
 ## Scope
 
-Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its optional sibling `REQUIREMENT.md`, and the bundled reference, script, and asset folders beside them.
+Governs a skill folder under `skills/` as one artifact: `SKILL.md`, its sibling `REQUIREMENT.md`, and the bundled reference, script, and asset folders beside them.
 
 Does not govern:
 
@@ -68,14 +68,14 @@ allowed-tools: <tools required>
 
 ## Structure
 
-- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (optional), `scripts/` (optional), `references/` (optional), `assets/` (optional)
+- Skill is a folder named in kebab-case containing `SKILL.md` (required), `REQUIREMENT.md` (required), `scripts/` (optional), `references/` (optional), `assets/` (optional)
 - `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. This standard governs shape across the corpus and the requirement governs scope for one skill. Claude Code loads `SKILL.md` as the entry and ignores the sibling, so the file costs a target session nothing.
+`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.
 
@@ -83,7 +83,7 @@ Read it before editing the skill. When a change closes no gap the requirement st
 
 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.
 
-A skill earns one when a reader cannot recover what the skill is for from the body alone. Apply the test to a skill nobody in the session has read before: read the body once, then state both the failures the skill exists to prevent and the nearest thing it deliberately does not do. A body answering both is its own specification and needs no sibling, and a body leaving either open earns one. Length is a weak proxy for that, since a short skill with a contested boundary earns one and a long skill doing one plain thing may not.
+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
 

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

@@ -1,15 +0,0 @@
----
-name: claude-design-propose
-description: Retired. `claude-design-extract` absorbed this skill and now takes the greenfield path itself. Invoke `aitk:claude-design-extract` instead.
-disable-model-invocation: true
----
-
-# Design propose
-
-Retired. `claude-design-extract` absorbed the greenfield path, picks it from what the project has, and its description carries every trigger this skill used to route on.
-
-Invoke `aitk:claude-design-extract` instead. It reads `.claude/REQUIREMENTS.md` for the `## Personality` paragraph and `.claude/ARCHITECTURE.md` for platform signals when the project has no UI code, which is what this skill did.
-
-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`.
-
-`scripts/sandbox/claude/design-propose.sh` goes at the same time, but its fixture does not. That scenario is the only greenfield coverage the survivor has, so `0.19.0` folds it into `scripts/sandbox/claude/design-extract.sh` as a second arm rather than deleting it. Removing the file outright drops the greenfield path from the catalog.