@erclx/aitk 0.8.0 → 0.10.0

package/README.md

@@ -13,29 +13,31 @@ claude plugin marketplace add https://github.com/erclx/aitk
 claude plugin install aitk@aitk
 ```
 
-The skills are then available as `/aitk:<name>`. Run `/reload-plugins` to pick them up inside a session that was already open. Updates arrive on release, so a push to this repo does not reach an installed copy.
+The skills land as `/aitk:<name>`. If your session was already open, run `/reload-plugins` to pick them up. Updates arrive on release, so a push to this repo won't reach your installed copy.
 
-Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin does not put it on your path. Install it from the registry.
+Several skills call the `aitk` CLI to read catalogs and run installs, and the plugin doesn't put it on your path. Install it from the registry.
 
 ```bash
 bun install --global @erclx/aitk
 ```
 
-[Bun](https://bun.sh) is the CLI runtime and has to be on the path first. Confirm the install by resolving `aitk --help`.
+[Bun](https://bun.sh) is the CLI runtime and has to be on your path first. Confirm the install by resolving `aitk --help`.
 
 ## Why
 
-Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Across enough projects the copies drift, and agents stop getting consistent signals.
+Every AI coding setup accumulates the same assets. Prompts to reuse, rules agents should follow, slash commands, skills, seed docs, sync scripts. Once you have enough projects, your copies drift and your agents stop getting consistent signals.
 
 Three design choices shape the toolkit.
 
 - Agent-first: every command has a non-interactive path and a JSON catalog. If a Claude Code skill or any other agent cannot drive the CLI without prompts, the design is wrong.
-- Text-native: conventions, rules, and prompts are authored as markdown that humans and agents read the same way. No hidden behavior, no compiled state.
-- One source, many consumers: this repo is the authoritative copy. Target projects install and sync on demand, never author in place.
+- Text-native: conventions, rules, and prompts are authored as markdown that you and your agents read the same way. No hidden behavior, no compiled state.
+- One source, many consumers: this repo is the authoritative copy. Your projects install and sync on demand, never author in place.
+
+Two limits worth knowing before you install. Claude Code is the only agent runtime the plugin targets, and the CLI needs Bun on your path. Snippets are the one surface that also travels to Gemini chat.
 
 ## What is inside
 
-Each domain has a canonical source in this repo and a thin install or sync CLI on the target side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it.
+Each domain has a canonical source in this repo and a thin install or sync CLI on your side. The links run to internal narrative, written for someone maintaining the toolkit rather than installing it, so skip them on a first pass.
 
 - [Claude Code plugin](.claude/context/claude-plugin.md): skills for planning, review, docs sync, and the git ship chain
 - [Governance rules](.claude/context/governance.md): Cursor rules and stacks, installable per project
@@ -49,6 +51,8 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 ## Documentation
 
+Scaffolding your first project? Start with target projects, then the AI workflow loop. Everything else answers questions that arrive later.
+
 - [AI workflow](docs/ai-workflow.md): feature-development loop inside a toolkit-managed project
 - [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
@@ -58,7 +62,7 @@ Each domain has a canonical source in this repo and a thin install or sync CLI o
 
 ## Development
 
-Working on the toolkit starts from a clone. Running the CLI does not, since it installs from the registry.
+Working on the toolkit starts from a clone. Running the CLI doesn't, since it installs from the registry. Skip this section unless you're changing the toolkit itself.
 
 ### Prerequisites
 
@@ -67,7 +71,7 @@ Working on the toolkit starts from a clone. Running the CLI does not, since it i
 - [GitHub CLI](https://cli.github.com) (optional) for ship flows
 - Shell: `zsh` or bash 4+ (`brew install bash` on macOS).
 
-Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and adds the Claude Code shell aliases to `~/.zshrc`.
+Clone the repo, then run the bootstrap script. It installs dependencies, links the CLI globally, and adds the Claude Code shell aliases to your `~/.zshrc`.
 
 ```bash
 git clone https://github.com/erclx/aitk.git
@@ -76,7 +80,7 @@ bun install
 bun run bootstrap
 ```
 
-The script is idempotent. Re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `aitk --help` on the last step. See [zshrc aliases](docs/zshrc-aliases.md) for what each alias does.
+The script is idempotent, so re-run it after pulling upstream changes without duplicating anything. It confirms the install by resolving `aitk --help` on the last step. See [zshrc aliases](docs/zshrc-aliases.md) for what each alias does.
 
 With the CLI linked, scaffold a fresh project.
 
@@ -86,13 +90,13 @@ git init
 aitk init
 ```
 
-`aitk init` installs base tooling configs, Claude seeds, governance rules, standards, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for the project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/` alongside the standards they route to. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
+`aitk init` installs base tooling configs, Claude seeds, governance rules, standards, and snippets in one pass, and scaffolds a `.claude/wiki/` stub for your project's own reference pages. Governance defaults to the `base` stack, so a bare init lands the coding and doc-authoring rules in `.claude/rules/` alongside the standards they route to. Pass `--stack <name>` for a framework stack, or `--skip governance` to leave rules out. Run `aitk tooling list --json` to see the catalog.
 
-For the full outsider journey (scaffold, add a domain later, sync upstream drift), see [target projects](docs/target-projects.md).
+For the full journey from scaffold through adding a domain later to syncing upstream drift, see [target projects](docs/target-projects.md).
 
 ## Contributing
 
-Portfolio project. Issues are welcome. Pull requests are accepted by invitation only. See the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention.
+Portfolio project. Issues are welcome. Pull requests are accepted by invitation only, so open an issue rather than a branch. Read the [contributing guidelines](CONTRIBUTING.md) for the local loop, the authoring split, and the commit convention before you file anything.
 
 ## License
 

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

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

package/claude/skills/claude-address-review/REQUIREMENT.md

@@ -0,0 +1,39 @@
+---
+name: claude-address-review
+description: What the review return leg is for, the gaps it closes, and why the push lands before the reply
+---
+
+# Claude address review requirement
+
+## Gap
+
+Without this skill, review findings are worked in whatever order the author read them and the thread never records which landed. A reply posted before the push describes code the remote does not have, so a reviewer checks the branch and finds the old version. A failing check gets treated as separate from the review, which produces a follow-up that answers every comment and leaves continuous integration red. One finding nobody can resolve stalls the rest.
+
+## Must
+
+- Treat a failing check as a finding alongside the review comments, so the follow-up closes both
+- Handle each finding independently, so one unresolved item does not block the others
+- Verify before pushing, since a red follow-up costs the reviewer a second pass
+- Push before replying, so the comment never runs ahead of the code it describes
+- Map every finding to what changed, or to a one-line reason when it is a question or a conscious accept
+- Post the terminal comment only when the findings are addressed and every check passes
+
+## Must not
+
+- Merge, or read the closing comment as an approval. The author cannot approve their own pull request.
+- Write a review. This skill consumes findings and does not produce them.
+- Post the closing comment while a check is failing
+- Reimplement the follow-up push or the doc refresh. Both have owners, and a second copy here drifts from them.
+- Edit silently. A finding answered without a reply leaves the reviewer re-deriving the change from the diff.
+
+## Guards
+
+- No open pull request for the current branch: stop
+- The pull request carries no review comments or threads: stop with a pass
+
+## Out of scope
+
+- Writing the review, which `claude-pr-review` owns. The split is by side of the channel: that one posts findings from an independent session and this one is the worker's return leg.
+- Staging, committing, and pushing the follow-up, which `git-followup` owns under this skill's direction
+- Refreshing the `.claude/` docs the fixes made stale, which `claude-docs` owns
+- Re-reviewing its own fixes, which hands back to the orchestrator

package/claude/skills/claude-address-review/SKILL.md

@@ -73,10 +73,9 @@ bullet per finding, each opening with the bolded finding identifier.
 Close the body with `🤖 Addressed by Claude Code` on its own line so the reply
 reads as an independent machine pass, not a human sign-off.
 
-Before posting, scan the reply for em dashes and semicolons and rewrite each,
-splitting into two sentences or using a comma. The standards-audit hook skips
-`.claude/.tmp/`, so this scan is the only gate on the published reply. Post it to
-the PR:
+Before posting, run the banned-character scan in `.claude/standards/prose.md`
+against the reply. The hook skips `.claude/.tmp/`, so this scan is the only gate
+on the published reply. Post it to the PR:
 
 ```bash
 gh pr comment <number> --body-file .claude/.tmp/address-review/reply-<number>.md

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

@@ -0,0 +1,41 @@
+---
+name: claude-autoship
+description: What the post-plan pipeline is for, the gaps it closes, and why every stop leaves the work recoverable
+---
+
+# Claude autoship requirement
+
+## Gap
+
+Without this skill, the run from an approved plan to an open pull request is a conversation. A session implements, then asks what comes next, and the answer varies by session. Review gets skipped on a diff that needed one, or spent on prose already gated by a hook. A run that halts leaves no stated resume point, so the user reconstructs how far it got from the working tree.
+
+## Must
+
+- Take the approved plan for the branch as the scope, and implement only what it describes
+- Give every step a stop condition, and leave the code on the branch and the receipts on disk at each one
+- Classify the changed-file list before review, so a prose-only diff skips a code review with no signal on it
+- Stop on any critical or should-fix finding rather than acting on it
+- Open the pull request as a draft, then watch continuous integration to a terminal state
+- Name the recovery for the stop it took, since the value of stopping is that the user knows where to resume
+
+## Must not
+
+- Expand past the plan, refactor a neighbor, or touch a file outside it without reason
+- Loop on a failed verify. One fix attempt against the reported errors, then stop.
+- Fix a review finding or a failing check. Both stops are deliberate, since a green pull request reached by auto-fix hides what broke.
+- Run the memory Apply phase. Promoting an entry changes how the agent operates and ships as its own change.
+- Read an empty changed-file list as prose-only. It satisfies that test vacuously and would route the branch past review instead of through it.
+
+## Guards
+
+- Detached HEAD: stop, no slug resolves
+- No approved plan at the branch's plan path: stop and route to the planning skill
+- Uncommitted changes unrelated to the plan: stop
+- No diff baseline against main: stop
+- Empty changed-file list: stop, and never advise removing the output from `.gitignore` to get past it
+
+## Out of scope
+
+- Writing the plan, which `claude-feature` owns. This chain starts from one already approved.
+- The behavior of each step, owned by the skill invoked. This skill owns the order and the stop conditions.
+- The resume path after a stop, which `git-ship` owns. That skill is the tail of this same sequence, which is why the two overlap by design.

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

@@ -11,7 +11,7 @@ Chain the post-plan pipeline in a single run. Every step has a stop condition. S
 ## Guards
 
 - All `.claude/plans/` and `.claude/review/` reads resolve at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`.
-- Run `git branch --show-current` and replace `/` with `-` to derive `<slug>`. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.`
+- Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. This skill takes the stop rather than the `latest` fallback, since it commits and opens a pull request. If empty, stop: `❌ Detached HEAD. Checkout the feature branch first.`
 - If `.claude/plans/feature-<slug>.md` does not exist at the main worktree root, stop: `❌ No approved plan at .claude/plans/feature-<slug>.md. Run /claude-feature first.`
 - If the working tree has uncommitted changes unrelated to the plan, stop: `❌ Uncommitted changes outside the plan. Commit or stash before autoshipping.`
 

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

@@ -1,53 +1,65 @@
 ---
 name: claude-diagram
-description: Drafts `.claude/DIAGRAMS.md` with one or more Mermaid diagrams describing the project's architecture, request flow, retrieval or data pipeline, and deployment. Reads `.claude/ARCHITECTURE.md` and `REQUIREMENTS.md` when present, falls back to a code-structure scan. Use when asked to "draw the architecture", "diagram the system", "show the components", "give me a flow chart", or "visualize the project". Do NOT use for design tokens (use `claude-design-extract`) or UI audits (use `claude-ux-audit`).
+description: Writes per-kind Mermaid diagram entries into `.claude/diagrams/`, covering system context, components, request flow, data pipeline, and deployment. Reads `.claude/ARCHITECTURE.md` and `REQUIREMENTS.md` when present, falls back to a code-structure scan. Use when asked to "draw the architecture", "diagram the system", "show the components", "give me a flow chart", "refresh the deploy diagram", or "visualize the project". Do NOT use for design tokens (use `claude-design-extract`) or UI audits (use `claude-ux-audit`).
 ---
 
 # Claude diagram
 
+Write one entry per diagram kind. Never rewrite the folder wholesale. A pass that refreshes the deploy view leaves the other four files byte-identical, which is the whole reason the surface is a folder.
+
 ## Guards
 
 - If no `.claude/ARCHITECTURE.md`, no `.claude/REQUIREMENTS.md`, and no top-level folder structure to scan, stop: `❌ No source signal. Add .claude/ARCHITECTURE.md or run inside a project folder.`
 
-## Step 1: read sources in parallel
+## Step 1: read sources and locate the surface
 
-Read these from the project root, skipping any that do not exist:
+Read these from the project root in parallel, skipping any that do not exist:
 
+- `.claude/diagrams/index.md` and every `.claude/diagrams/*.md`: which entries exist and what they already say
+- `.claude/REQUIREMENTS.md`: users, external dependencies, tech stack, MVP feature list
 - `.claude/ARCHITECTURE.md`: layered components, key technical decisions
-- `.claude/REQUIREMENTS.md`: tech stack, MVP feature list
 - `CLAUDE.md`: project type, conventions
 - `package.json`, `pyproject.toml`, `Cargo.toml`: language and framework markers
 - Top-level folder layout and root config files via `ls`: deploy targets, infrastructure config, component boundaries
 
-Run all reads in parallel. Do not recurse speculatively.
+Do not recurse speculatively.
 
-## Step 2: pick which diagrams to emit
+Follow `.claude/standards/diagrams.md` for frontmatter, entry kinds, layout, budgets, accessibility, verification, and explanation rules, or `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` when the project does not have it.
 
-Emit a diagram only when its source signal exists. Skip the rest, do not pad the file.
+### Migrating a pre-split flat file
 
-- **Components** (`flowchart TB` with `subgraph` boundaries): always, when any signal exists. Shows the layered structure of the system.
-- **Request flow** (`sequenceDiagram`): when prose describes a request lifecycle, an agent loop, or interaction between actors
-- **Data pipeline** (`flowchart TB`): when prose mentions retrieval, ranking, queues, ETL, or pipelines
-- **Deployment** (`flowchart TB`): when the top-level listing contains deploy or infrastructure config, or `.claude/ARCHITECTURE.md` has a deploy section
+When `.claude/diagrams/` holds no entry and `.claude/DIAGRAMS.md` exists, this pass converts it. An entry is any `*.md` in the folder other than `index.md`. The seed ships `index.md` alone, so a folder holding only the catalog is an empty set and still converts. Split each H2 section into the entry whose kind it matches, carry its mermaid body and explanation prose across unchanged, and add the frontmatter the standard requires. Leave `.claude/DIAGRAMS.md` on disk so the split can be compared against its source, and say in Step 7 that deleting it is the user's call.
 
-Stay inside `flowchart` and `sequenceDiagram`. Do not emit C4, state, ER, or class diagrams. They render inconsistently across viewers.
+Convert only. Do not redraw a diagram during a migration pass, since a rewrite and a move landing together leaves no way to tell which one broke a diagram.
 
-Follow `.claude/standards/diagrams.md` for layout, budgets, accessibility, verification, labeling, narrative, and explanation rules, or `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` when the project does not have it. `flowchart TB` is the default. Reach for `flowchart LR` only when a pipeline genuinely cannot read top-to-bottom, and call it out in the explanation paragraph.
+## Step 2: pick which entries this pass writes
 
-## Step 3: write the file
+Write an entry only when its source signal exists, and only when this pass has a reason to touch it. Skip the rest and leave their files alone.
 
-Read the existing `.claude/DIAGRAMS.md` from the project root when it is present, then write to that path. Always overwrite. The prior content is what tells Step 4 which mermaid bodies this pass actually changed.
+Count entries the way Step 1 does, excluding `index.md`. Counting the catalog as an entry sends a first pass down the compare branch with nothing to compare, and it writes nothing.
 
-File format:
+- The user named a kind: write that one.
+- The user asked broadly and the folder holds no entry: write every kind whose signal exists.
+- The user asked broadly and at least one entry exists: compare each entry against its source signal and write only the ones whose signal moved. Report the untouched ones as current.
 
-````markdown
-# Diagrams
+The standard fixes one filename and one `category` value per kind. Use them verbatim rather than inventing a name, since a refresh finds its target by filename and a new name writes a duplicate entry beside the old one. Emit `system-context.md` whenever `.claude/REQUIREMENTS.md` exists, since it is the entry a reader outside the team opens first and the set is incomplete without it.
+
+Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
+
+## Step 3: write the entries
+
+One file per kind at `.claude/diagrams/<kind>.md`. Write only the files Step 2 selected.
 
-<one-paragraph note on what this file contains and which sources drove it>
+````markdown
+---
+title: <what the entry answers, sentence case>
+description: <the question it settles and the signal that drives it>
+category: <the kind, matching the standard>
+---
 
-## <Section title>
+# <Same as title>
 
-<one-line description of what this diagram shows>
+<one-line statement of what the diagram shows>
 
 ```mermaid
 <diagram type>
@@ -56,22 +68,34 @@ File format:
   <body>
 ```
 
-## <Next section>
-
-...
+<one to three explanation paragraphs>
 ````
 
-When sources came from a code scan rather than planning prose, lead the intro paragraph with `Source: code.` and add `Fidelity is lower than prose-driven diagrams. Verify against the project's intent.`
+When sources came from a code scan rather than planning prose, lead the explanation with `Source: code.` and add `Fidelity is lower than prose-driven diagrams. Verify against the project's intent.`
 
 Quote node labels containing spaces or special characters with double quotes (`A["Web shell"]`). Avoid parentheses inside labels, they break some renderers. Use `<br/>` for line breaks inside labels.
 
-Apply the toolkit's prose bans to the entire file, including inside mermaid `subgraph` labels and node text. No em-dashes, no semicolons. Use a colon or split into two sentences instead. The standards-audit hook treats mermaid syntax as prose and will reject the file on every violation, forcing a retry per label.
+Run the banned-character scan in `.claude/standards/prose.md` against the whole file, including inside mermaid `subgraph` labels and node text, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md` when the project does not have it. A colon also works as a replacement inside a label. The pedagogical voice the diagram standard asks for is a yield on voice alone and buys no exemption from these bans.
+
+Nothing enforces the ban inside the diagram. The standards-audit hook toggles on a fence and skips every line within it, so a label carrying an em dash passes silently while the same character in the explanation paragraph below is caught. Check the labels by reading them. This is the one place in the file where the author is the only gate.
 
-## Step 4: render what this pass changed
+## Step 4: regenerate the catalog
+
+```bash
+aitk indexes regen
+```
+
+Run it after the last entry is written. It rebuilds `.claude/diagrams/index.md` from sibling frontmatter and groups entries under their `category`. Never hand-edit that file.
+
+When `aitk` is not on PATH, say so in Step 7 and name `.claude/diagrams/index.md` as stale rather than writing it by hand.
+
+Scaffold `.claude/diagrams/index.md` with `title` and `subtitle` frontmatter before the first regen when the folder is new and the seed did not provide one. The subtitle routes a first-time reader to the system context entry, since the catalog sorts categories alphabetically rather than in narrative order.
+
+## Step 5: render what this pass changed
 
 A source that satisfies every rule in the standard can still render as a picture that asserts something false about the system. Verification runs on the image.
 
-Render each diagram this pass wrote or changed. Skip any whose mermaid body is unchanged from the content read in Step 3, since an untouched diagram cannot develop a new render defect and the cost is linear in diagram count.
+Render each entry this pass wrote. Skip every entry Step 2 left alone, since an untouched diagram cannot develop a new render defect.
 
 Before the first render in a project, say what is about to block:
 
@@ -82,44 +106,50 @@ Rendering to verify layout. The first run downloads the Mermaid CLI and takes ab
 Write each diagram's mermaid body to its own scratch file, then render it:
 
 ```bash
-mkdir -p .claude/.tmp/diagrams && bunx -y @mermaid-js/mermaid-cli -i .claude/.tmp/diagrams/<slug>.mmd -o .claude/.tmp/diagrams/<slug>.png
+mkdir -p .claude/.tmp/diagrams && bunx -y @mermaid-js/mermaid-cli -i .claude/.tmp/diagrams/<kind>.mmd -o .claude/.tmp/diagrams/<kind>.png
 ```
 
 Render to PNG. An SVG export reads back as markup with no recoverable spatial meaning, so it cannot be verified. Use `bunx` when bun is available. Fall back to `npx -y @mermaid-js/mermaid-cli ...` otherwise.
 
 Renders are verification artifacts, not deliverables. They stay in `.claude/.tmp/diagrams/` and are never committed.
 
-When the render fails for any reason (no browser engine, no network, no package manager), continue to Step 6 and name the skipped check in the chat output. A missing renderer degrades the loop, it does not fail it.
+When the render fails for any reason (no browser engine, no network, no package manager), continue to Step 7 and name the skipped check in the chat output. A missing renderer degrades the loop, it does not fail it.
 
-## Step 5: read the render back
+## Step 6: read the renders back
 
-Read each PNG and judge the picture against what the diagram means to say. Follow the verification properties in `.claude/standards/diagrams.md`, or `${CLAUDE_SKILL_DIR}/../../standards/diagrams.md` when the project does not have it.
+Read each PNG and judge the picture against what the entry means to say. Apply the verification properties in the standard.
 
-Fix the source and re-render. Stop after two correction passes on a diagram.
+Fix the source and re-render. Stop after two correction passes on an entry.
 
-When a defect survives, write the diagram and name the defect in the chat output. A diagram whose author states the flaw is recoverable. A wrong diagram reported as verified is not.
+When a defect survives, keep the entry and name the defect in the chat output. A diagram whose author states the flaw is recoverable. A wrong diagram reported as verified is not.
 
-## Step 6: chat output
+## Step 7: chat output
 
 ```plaintext
-📝 Wrote .claude/DIAGRAMS.md with N diagrams.
+📝 Wrote N entries to .claude/diagrams/
+   .claude/diagrams/<kind>.md
+   <one line per entry written>
+
+Left untouched: <kind, kind> <omitted when the folder was empty>
 
 Verified N renders. <defect or skipped check, one line each, omitted when clean>
 
 Open in any viewer with native Mermaid support (VS Code with `bierner.markdown-mermaid`, GitHub, Cursor) to render. Ask to export if you want SVG or PNG files.
 ```
 
-Do not echo the diagram bodies in chat. Never report a clean verification when a render was skipped or a defect survived.
+Emit the full path for every file written. Do not echo the diagram bodies in chat. Never report a clean verification when a render was skipped or a defect survived. Never report an entry as written when this pass left it alone.
+
+After a migration pass, add: `Converted .claude/DIAGRAMS.md into N entries. The original is untouched, delete it once you have compared the split against it.`
 
-## Step 7: export on request
+## Step 8: export on request
 
 If the user asks to export the diagrams (`export to svg`, `give me images`, `render to png`), run:
 
 ```bash
-mkdir -p .claude/review/diagrams && bunx -y @mermaid-js/mermaid-cli -i .claude/DIAGRAMS.md -o .claude/review/diagrams/diagram.png
+mkdir -p .claude/review/diagrams && bunx -y @mermaid-js/mermaid-cli -i .claude/diagrams/<kind>.md -o .claude/review/diagrams/<kind>.png
 ```
 
-Export PNG by default. Swap `diagram.png` for `diagram.svg` only when the user asks for vector, and never for the Step 4 verification path. The CLI writes one file per `mermaid` block (`diagram-1.png`, `diagram-2.png`, ...). Output line:
+Export PNG by default. Swap the extension for `.svg` only when the user asks for vector, and never for the Step 5 verification path. The CLI writes one file per `mermaid` block, suffixing when an entry holds more than one. Export every entry when the user names no kind. Output line:
 
 ```plaintext
 📝 Wrote N files to .claude/review/diagrams/

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

@@ -0,0 +1,39 @@
+---
+name: claude-docs
+description: What the planning-doc reconcile is for, the gaps it closes, and why the diff decides completion alone
+---
+
+# Claude docs requirement
+
+## Gap
+
+Without this skill, the planning docs describe the scope the session opened with. An outcome the diff shipped stays unchecked, so the board reports finished work as open and the next session re-plans it. A requirement or architecture decision that changed mid-cycle lives only in the conversation and dies with it. Plans for closed tasks accumulate in the live folder, so the folder stops indicating what is in flight.
+
+## Must
+
+- Take completion from the diff and everything else from the session, since completion is a fact about the repository rather than about the conversation
+- Match an outcome on the behavior it names, never on a filename or a commit subject
+- Leave an outcome unchecked when the diff is ambiguous. An unmarked shipped outcome costs one manual edit and a wrongly marked one hides work that never happened.
+- Write tracked docs at the current worktree root and the task board at the main root, since only the first commits with the branch
+- Count every other citation before archiving a plan, comparing resolved targets rather than raw strings or bare filenames
+- Retarget a closed task at the archived plan, so the reasoning behind finished work stays reachable
+
+## Must not
+
+- Infer a new task from the diff. Only outcomes already on the board get marked.
+- Touch task files the session did not change, outside the board-wide plans sweep that exists to clear a missed archive
+- Widen what a writing step reads when the baseline is unusable. Widening a read is safe and widening a write stubs a surface for every file in the repository.
+- Edit `CLAUDE.md` inline. Every change there goes through a diff-and-approve gate, so this skill only flags.
+- Create a context entry or delete a plan
+
+## Guards
+
+- No `.claude/` directory: stop and name the command that sets one up
+- No session divergence and no queued outcome the diff shipped: stop with a pass, since both conditions have to hold
+
+## Out of scope
+
+- Creating a task file or moving one off the board, which `claude-tasks` owns
+- Public-facing docs, which `docs-sync` owns. This skill reconciles the `.claude/` planning surface.
+- Regenerating the task index, owned by a hook
+- Redrawing diagrams, which `claude-diagram` owns. This skill flags staleness and leaves the re-run to the author.

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

@@ -181,7 +181,7 @@ A plan can serve more than one task, and archiving on the first task to close st
 
 Write the retarget as a markdown link, `Plan: [feature-<slug>](../.tmp/plans-archive/feature-<slug>.md)`, updating both halves so the text and the target stay in step. This branch is the only writer that produces a `Plan:` line nobody authored by hand, so a retarget that emits a bare path converts every task to the old form as it closes and drifts the board back to two shapes on its own.
 
-**Reviews.** Derive `<slug>` from the current branch name (replace `/` with `-`). If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
+**Reviews.** Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result. If `.claude/review/review-<slug>.md` exists, delete it. `claude-review` writes with this convention. Do not sweep any other `review-*.md` file.
 
 Do not sweep `ui-checklist-*.md` (pending human verification) or `ux-audit-*.md` (standalone deliverable).
 

package/claude/skills/claude-memory-review/SKILL.md

@@ -78,7 +78,7 @@ Rules that resist crisp one-line phrasing default to **Delete** over promote. Ne
 
 ### Step 4: write the proposal to the review file
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace `/` with `-`. Fall back to `latest` on empty output.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full proposal to `.claude/review/memory-review-<slug>.md` at the main worktree root. Do not print it inline.
 

package/claude/skills/claude-pr-review/REQUIREMENT.md

@@ -0,0 +1,38 @@
+---
+name: claude-pr-review
+description: What the independent pull request review is for, the gaps it closes, and why it posts twice
+---
+
+# Claude PR review requirement
+
+## Gap
+
+Without this skill, a pull request is reviewed only by the session that wrote it, which cannot see the roadmap sequence or a sibling branch in flight. Findings land in chat, where they are read once and leave the thread with no record. A review that opens and never closes is worse than none, since a reader scanning the thread cannot tell an unanswered review from a confirmed one, and the author's claim that findings are fixed is the only evidence they are.
+
+## Must
+
+- Post both passes. A first pass opens the review against the whole change, and a close-out confirms the prior findings landed.
+- Detect the pass from the thread rather than taking it from the caller, matching the heading for equality so a neighboring comment cannot be read as a prior pass
+- Scope a close-out to the commits added since the prior pass, once that commit is confirmed to still reach the head
+- Apply the integration, contract, and consumer lenses a self-review structurally cannot
+- Post a close-out even with nothing to report, since a first pass left unanswered reads as a review nobody closed
+- Key the body file on both the pull request number and the head commit, so no two passes overwrite each other
+
+## Must not
+
+- Merge. Review and post, and leave the gate to the human.
+- Publish a claim the skill did not check. A failed fetch and a rebase both strand the prior commit, and only one of them is a rebase.
+- Invent a third heading, or append a number GitHub already renders
+- Review local uncommitted changes
+- Lecture on process. The lenses land as findings, not as asides.
+
+## Guards
+
+- No open pull request for the target branch: stop and route to the local review skill
+- The fetch of the pull request head fails: stop rather than falling through to a full pass
+
+## Out of scope
+
+- Fixing what it finds, which `claude-address-review` owns. The split is by side of the channel: this one posts findings from an independent session and that one consumes them.
+- Reviewing local uncommitted work, which `claude-review` owns. That one writes to disk for the session that wrote the code, and this one posts to a pull request it did not write.
+- Merging, which stays the human's decision

package/claude/skills/claude-pr-review/SKILL.md

@@ -131,7 +131,7 @@ The `What is right` section is optional, capped at three bullets, and included o
 
 Close the body with `🤖 Reviewed by Claude Code` on its own line so the review reads as an independent machine pass, not a human sign-off.
 
-Before posting, scan the body for em dashes and semicolons and rewrite each, splitting into two sentences or using a comma. The standards-audit hook skips `.claude/.tmp/`, so this scan is the only gate on the published comment.
+Before posting, run the banned-character scan in `.claude/standards/prose.md` against the body. The hook skips `.claude/.tmp/`, so this scan is the only gate on the published comment.
 
 ```bash
 gh pr review <number> --comment --body-file .claude/.tmp/pr-review/body-<number>-<short-sha>.md

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

@@ -0,0 +1,39 @@
+---
+name: claude-review
+description: What local review is for, the gaps it closes, and why it reports without fixing
+---
+
+# Claude review requirement
+
+## Gap
+
+Without this skill, a branch ships on the confidence of the session that wrote it. Review happens in chat and evaporates, so the ship step has no receipt to gate on. What review does happen mixes style opinion with real defects at one severity, and a reader cannot tell which blocks the merge. Worst, a diff that resolves empty against a stale base reports a clean branch instead of admitting the skill could not see the work.
+
+## Must
+
+- Read the project's own context before the diff, so a decision already settled is not reported as a defect
+- Resolve the base ref once, preferring the remote over local `main`, and reuse it in the guard and the read
+- Say when the baseline is unusable and name the narrowed scope, rather than letting a clean summary read as a clean branch
+- Flag only what will cause incorrect behavior or break a documented rule
+- Grade every finding, since the caller gates on the counts rather than on the prose
+- Write the report to disk under a branch-derived slug, so what the ship step reads outlives the session
+
+## Must not
+
+- Fix, rewrite, or suggest a refactor outside a finding. Reporting is the whole job.
+- Flag style, linter territory, or anything resting on unverified state. A false positive erodes trust in the pass.
+- Substitute the whole tree for a missing baseline
+- Repeat the full report in chat. The file is the report and a chat copy of it goes stale immediately.
+- Stage or commit the receipt, which is gitignored scratch
+- Auto-trigger on a vague signal. Require an explicit request or a pipeline invocation.
+
+## Guards
+
+- The staged set, the branch set, and the working set are all empty: stop with a pass
+- Baseline unusable: continue on the uncommitted set and lead the report with the warning
+
+## Out of scope
+
+- Reviewing an open pull request, which `claude-pr-review` owns. The split is by vantage: this one reviews local work for the session that wrote it and writes to disk.
+- Deciding whether the findings block the ship. This skill grades and the caller gates.
+- Fixing anything it found, which `claude-address-review` owns once the work is on a pull request

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

@@ -116,7 +116,7 @@ If nothing is wrong, use: `✅ No findings.`
 
 ### Persist
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full report directly to `.claude/review/review-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
 

package/claude/skills/claude-seed-sync/SKILL.md

@@ -52,7 +52,7 @@ Before proposing an Update, grep the target section for the seed text's keywords
 
 ## Step 4: write the proposal to the review file
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace `/` with `-`. Fall back to `latest` on empty output.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full proposal to `.claude/review/seed-audit-<slug>.md` at the main worktree root. Do not print the proposal inline.
 

package/claude/skills/claude-ui-test/SKILL.md

@@ -57,7 +57,7 @@ If all changes are automatable, skip the manual checklist:
 
 ### Persist the checklist
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 When a manual checklist is produced, write it directly to `.claude/review/ui-checklist-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.
 

package/claude/skills/claude-ux-audit/SKILL.md

@@ -58,7 +58,7 @@ If nothing is wrong, use: `✅ No observations.`
 
 ### Persist
 
-Derive a slug from the current git branch: run `git branch --show-current` and replace any `/` with `-`. If the result is empty (detached HEAD), use `latest`.
+Derive `<slug>` per Deriving the branch slug in `.claude/standards/skill.md`, or `${CLAUDE_SKILL_DIR}/../../standards/skill.md` when the project does not have it. Fall back to `latest` on an empty result.
 
 Write the full report directly to `.claude/review/ux-audit-<slug>.md` at the main worktree root, not the current worktree. See Worktrees in `CLAUDE.md`. Create the directory if it does not exist. Always overwrite.