@erclx/aitk 0.8.0 → 0.9.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.8.0",
+  "version": "0.9.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-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-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.
+Apply the toolkit's prose bans to the whole file, including inside mermaid `subgraph` labels and node text. No em-dashes, no semicolons. Use a colon or split into two sentences instead. The pedagogical voice the 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-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-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/docs/ai-workflow.md

@@ -131,7 +131,7 @@ Before the first feature session on a UI-heavy project, pick a design tier. The
 | `aitk:claude-feature`        | Before implementation, scan for conflicts and ambiguities                                                              |
 | `aitk:claude-roadmap`        | Sequence MVP scope into ordered versions in `.claude/ROADMAP.md`                                                       |
 | `aitk:claude-orchestrate`    | Assert the orchestrator role, refill the ready queue, and dispatch the roadmap, feature, and review skills             |
-| `aitk:claude-diagram`        | Draft `.claude/DIAGRAMS.md` with mermaid diagrams from architecture and code, then verify each rendered image          |
+| `aitk:claude-diagram`        | Draft per-kind mermaid entries under `.claude/diagrams/` from architecture and code, then verify each rendered image   |
 | `aitk:claude-design-propose` | Day one on a UI project, draft `.claude/DESIGN.md` from requirements. Use `claude-design-extract` if UI already exists |
 | `aitk:claude-review`         | In a fresh session, review all changes since main                                                                      |
 | `aitk:claude-pr-review`      | Review an open PR from an independent session, then close the review out against the commits added since               |

package/docs/target-projects.md

@@ -57,7 +57,7 @@ Scaffold installs tooling and seeds. It does not fill the planning docs or the d
 
 1. Fill `.claude/REQUIREMENTS.md` and `.claude/ARCHITECTURE.md`. The seed provides the files, the scope and decisions are yours to write.
 2. For a UI project, invoke `aitk:claude-design-propose` to draft `.claude/DESIGN.md` from the requirements and a `## Personality` section. Skip for non-UI projects.
-3. Optionally invoke `aitk:claude-diagram` to draft `.claude/DIAGRAMS.md` from the architecture. It renders each diagram to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped.
+3. Optionally invoke `aitk:claude-diagram` to draft entries under `.claude/diagrams/` from the architecture and the requirements. One file per diagram kind, so a later refresh of one kind leaves the others untouched. It renders each diagram it writes to verify the layout, which downloads the Mermaid CLI on first use and takes about 15 seconds. A machine without a renderer still gets the diagrams and is told which check was skipped.
 4. Start the feature loop. See [AI workflow](ai-workflow.md) for the per-feature sequence.
 
 ### Stack decision

package/governance/rules/claude/560-diagrams.md

@@ -1,6 +1,7 @@
 ---
-description: Route .claude/DIAGRAMS.md edits to the diagrams standard for Mermaid conventions
+description: Route .claude/diagrams edits to the diagrams standard for Mermaid conventions
 paths:
+  - '.claude/diagrams/**'
   - '.claude/DIAGRAMS.md'
 ---
 
@@ -8,4 +9,11 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, labeling, and narrative. It is the single source.
+- Follow `.claude/standards/diagrams.md` for Mermaid diagram layout, budgets, accessibility, verification, and explanation prose. It is the single source.
+- A diagram entry carries structure and flow, not implementation. Read the standard before adding or revising a kind.
+
+## Scope
+
+- Write a new diagram to `.claude/diagrams/<kind>.md`, never to `.claude/DIAGRAMS.md`
+- Convert a `.claude/DIAGRAMS.md` left by an older install into per-kind entries before editing it
+- Refresh only the entries whose source signal moved. Do not rewrite the folder wholesale.

package/governance/rules/claude/570-skill.md

@@ -15,4 +15,4 @@ paths:
 
 ## Authority
 
-- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, and invocation rules. It is the single source.
+- Follow `.claude/standards/skill.md` for skill structure, frontmatter fields, invocation rules, and the shape a `REQUIREMENT.md` states. It is the single source.

package/package.json

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

package/scripts/core/install-check.sh

@@ -75,7 +75,7 @@ log_step "Assert scaffold"
 # no assertion can truncate silently: init still exits 0 because run_domain
 # catches a failed domain, and the gate stays green while the target is
 # missing everything that domain provides.
-for path in "CLAUDE.md" ".claude/snippets/compact-summary.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" \
+for path in "CLAUDE.md" ".claude/snippets/compact-summary.md" ".claude/standards/prose.md" ".claude/wiki/index.md" ".claude" ".claude/context/index.md" ".claude/wireframes/index.md" ".claude/diagrams/index.md" \
   ".prettierrc" ".editorconfig" ".lintstagedrc" ".husky/pre-commit" ".github/workflows/verify.yml" "scripts/verify.sh" \
   ".claude/rules/core/000-constitution.md"; do
   if [ ! -e "$TARGET_DIR/$path" ]; then

package/src/claude/seeds.ts

@@ -7,7 +7,13 @@ const SEEDS_DIR = join('tooling', 'claude', 'seeds')
 const CLAUDE_DIR = '.claude'
 const CLAUDE_MD = 'CLAUDE.md'
 const HOOKS = 'hooks'
-const SUBDIRS: readonly string[] = [HOOKS, 'context', 'tasks', 'wireframes']
+const SUBDIRS: readonly string[] = [
+  HOOKS,
+  'context',
+  'diagrams',
+  'tasks',
+  'wireframes',
+]
 
 export type SeedScope = 'claude' | 'root'
 

package/standards/diagrams.md

@@ -1,34 +1,83 @@
 ---
 title: Diagram reference
-description: Conventions for Mermaid diagrams in .claude/DIAGRAMS.md
+description: Shape and content rules for .claude/diagrams/<kind>.md files
 ---
 
 # Diagram reference
 
-Applies to Mermaid diagrams in `.claude/DIAGRAMS.md`. Goal: diagrams that render cleanly in narrow-column renderers (VS Code preview, GitHub PR view, Cursor) and read pedagogically without surrounding prose.
+Applies to per-kind entries under `.claude/diagrams/`. Skip for `index.md`, which is regenerated by `aitk indexes regen`.
+
+A diagram entry answers one question about the system with one or more Mermaid diagrams and the prose that makes them readable. It is not a rendering of the file tree. The check for any single line: does it tell a reader something the code layout would not have told them? If not, it belongs in `.claude/context/`.
+
+## What a working entry looks like
+
+An entry works when a reader who has not opened the repository can answer its question:
+
+- What are the parts, and which ones talk to each other?
+- Which direction does the work flow, and where does it start?
+- What would break if one box were removed?
+
+An entry that fails these is non-conforming regardless of whether it satisfies every section rule below. The fences are the means. These three questions are the test.
+
+## Frontmatter
+
+- `title` (required): sentence case, names what the entry answers (`System context`, `Request flow`), not what it draws.
+- `description` (required): one line on which question the entry settles and which source signal drives it.
+- `category` (required): the diagram kind, one of the five in Entry kinds. It is the grouping field `aitk indexes regen` renders headings from.
+
+All three feed `.claude/diagrams/index.md` when regenerated. The catalog sorts categories alphabetically rather than in narrative order, so an entry cannot rely on its position to introduce another. Each entry names its own starting point, and the catalog's subtitle routes a first-time reader to the system context entry.
+
+## Entry kinds
+
+Five kinds, each with a fixed filename and a fixed `category` value. Write a kind only when its source signal exists, and leave the rest absent rather than padding the folder.
+
+- `system-context.md`, category `System context` (`flowchart TB`): who uses the system, what it talks to, and where its boundary sits. Drawn from `.claude/REQUIREMENTS.md`. This is the entry a reader outside the team opens first, and the only kind that draws the world outside the boundary.
+- `components.md`, category `Components` (`flowchart TB` with `subgraph` boundaries): the layered structure inside the boundary. Drawn from `.claude/ARCHITECTURE.md`.
+- `request-flow.md`, category `Request flow` (`sequenceDiagram`): a request lifecycle, an agent loop, or an interaction between actors.
+- `data-pipeline.md`, category `Data pipeline` (`flowchart TB`): retrieval, ranking, queues, or ETL.
+- `deployment.md`, category `Deployment` (`flowchart TB`): hosts, services, and infrastructure config.
+
+The filenames are fixed rather than free, so a session refreshing one kind finds the file it is meant to overwrite instead of writing a second entry beside it under a name of its own.
+
+Stay inside `flowchart` and `sequenceDiagram`. C4, state, ER, and class diagrams render inconsistently across viewers.
+
+The kinds drift at rates spanning roughly an order of magnitude, which is why they are separate files. A deploy change rewrites one entry and leaves the other four untouched.
+
+A second entry for one kind takes a suffixed name (`request-flow-admin.md`) and repeats the kind's `category` verbatim, which is what the grouping field is for. One entry per kind is the ordinary case, so most catalogs show one entry under each heading.
 
 ## Layout
 
 - Declare `flowchart TB` by default. Mermaid ignores a subgraph's direction whenever that subgraph links outward, and an architecture diagram links across its subgraphs as the normal case, so top-bottom is a declaration rather than a guarantee.
 - Restructure a diagram that renders diagonal or left-to-right. Repeating the direction keyword does not fix it.
-- Render a component, context, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
+- Render a context, component, or pipeline diagram taller than wide. A `sequenceDiagram` is wide by construction and is exempt.
 - Do not let independent nodes render in a row. A row of siblings reads as a sequential chain and asserts a pipeline the system does not have.
 - Do not converge many edges on one node from one side. A crossing bundle is unreadable whatever it encodes.
 - Keep node labels short. Three or four words max. Detail goes in the paragraph below the diagram.
 - Use `<br/>` for a second short line on a node when the label is two ideas, never for a sentence.
-- Subgraphs are for grouping unrelated lanes (offline versus online, browser versus server). Do not subgraph a single linear flow.
+- Subgraphs are for grouping unrelated lanes such as offline versus online or browser versus server. Do not subgraph a single linear flow.
 
 ## Budgets
 
 - Hold a diagram to roughly 5 to 10 nodes. Split it past 15.
 - Watch edge count harder than node count. It binds first, and a diagram whose edges outnumber its nodes is already too dense to read.
 - Treat a diagram that cannot be described in one sentence as two diagrams.
+- Keep an entry to one diagram by default. A second fence in the same file needs its own H2 naming what it adds, and a third is a sign the entry covers two kinds.
 - Warn rather than refuse on a budget, and name the split that would fix it. These numbers come from published Mermaid practice rather than from a measurement in this repository, so a hard refusal on them will be wrong sometimes and unarguable when it is.
 
 ## Accessibility
 
 - Give every diagram `accTitle` and `accDescr`. `accTitle` names what the diagram answers. `accDescr` states the structure in one sentence for a reader who cannot see the render.
 
+## Explanation
+
+- One to three short paragraphs below each diagram. Plain English and pedagogical.
+- Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
+- Reference one or two specific code paths the reader can open. Do not enumerate every file.
+- Do not duplicate prose across entries. An entry that restates its neighbor has taken the neighbor's job.
+- The audience is mixed, so vocabulary runs as a gradient across the set. `System context` assumes no knowledge of the repository. `Deployment` may assume the reader has read the others.
+
+This section states the voice for the surface, which is what claims the yield `standards/prose.md` grants to a surface whose own standard sets it. Explanation prose is pedagogical here and the default developer-facing voice does not apply. The yield covers voice alone. Punctuation, formatting, and language bans stay in force, and the standards-audit hook enforces them on every write.
+
 ## Verification
 
 - Judge a diagram from its rendered image, not from its source. Direction, sibling rows, and edge bundles are visible only in the output.
@@ -36,20 +85,21 @@ Applies to Mermaid diagrams in `.claude/DIAGRAMS.md`. Goal: diagrams that render
 - Apply four tests as a reviewer, the same ones the author applied: direction held, no sibling row reading as a chain, no crossing edge bundle, taller than wide outside a sequence diagram.
 - State which verification was skipped when no renderer is available. A diagram written without a render is still shippable, and one reported as verified without a render is not.
 
-## Narrative
+## What moves to .claude/context/
 
-- Build a narrative arc across the file, not a parallel list of unrelated views. Start with the whole system in five or six boxes. Drill into one phase per section.
-- Order sections chronologically when possible: framing, then setup, then a query travels through, then measurement.
-- One H2 per diagram. The H2 names what the diagram answers, not what it shows ("How the corpus gets populated", not "Corpus ingestion").
+Implementation detail that answers how a component is built belongs in a `.claude/context/` entry, not a diagram:
 
-## Explanation
+- Function names, call signatures, and lifecycle ordering
+- Library versions, config keys, and environment variable names
+- Retry counts, timeouts, and batch sizes
+- Workarounds and rejected approaches that need more than one sentence
 
-- One to three short paragraphs below each diagram. Plain English, pedagogical, no marketing copy.
-- Lead with what the diagram shows. Follow with why this shape was chosen and what alternative was rejected, when the choice was non-obvious.
-- Reference one or two specific code paths the reader can open. Do not enumerate every file.
-- Do not duplicate prose between sections. Each paragraph earns its line.
+Reference the context entry by path when a reader needs the mechanism. The diagram stays answerable on its own for structure and flow.
 
 ## Maintenance
 
-- When the system changes (new layer, new provider, new deploy posture), audit `.claude/DIAGRAMS.md` in the same PR. A diagram showing a defunct host or library is worse than no diagram.
-- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraph below is still prose. Follow `standards/prose.md`.
+- When the system changes, update the entries whose source signal changed and leave the rest alone. Rewriting the folder wholesale reproduces the defect the per-kind split exists to end.
+- A diagram showing a defunct host or library is worse than no diagram. Audit the affected entry in the same PR.
+- `System context` has no named source signal beyond `.claude/REQUIREMENTS.md`, so nothing tells a session it went stale. Re-read it when the boundary or the set of external dependencies moves.
+- Mermaid blocks are inside fenced code, so the prose-standards hook ignores them. The explanation paragraphs around them are still prose. Follow `standards/prose.md`.
+- The punctuation bans still apply to node and subgraph labels, and nothing checks them there. An em dash in a label passes every gate the repository has, so read the labels before shipping the entry.

package/standards/index.md

@@ -10,7 +10,7 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Architecture reference](architecture.md): Shape and content rules for .claude/ARCHITECTURE.md
 - [Context entry reference](context.md): Shape and content rules for .claude/context/<domain>.md entries
 - [Design reference](design.md): Shape and content rules for .claude/DESIGN.md
-- [Diagram reference](diagrams.md): Conventions for Mermaid diagrams in .claude/DIAGRAMS.md
+- [Diagram reference](diagrams.md): Shape and content rules for .claude/diagrams/<kind>.md files
 - [Prose reference](prose.md): Voice, structure, formatting, and language rules for reference markdown
 - [Readme reference](readme.md): Readme structure and content conventions
 - [Requirements reference](requirements.md): Shape and content rules for .claude/REQUIREMENTS.md

package/standards/prose.md

@@ -5,7 +5,7 @@ description: Voice, structure, formatting, and language rules for reference mark
 
 # Prose reference
 
-Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages.
+Applies to markdown reference docs, READMEs, and inline documentation in repos. It is the default voice for `.md` files and yields to any surface with its own voice, such as blogs, emails, changelogs, or commit messages. It also yields wherever another standard states the voice for the surface it governs, which is how a surface claims the exemption without this file having to name it. The yield covers voice alone. Punctuation, formatting, and language rules below stay in force on every surface, since the standards-audit hook is the only gate on published text.
 
 ## Voice
 

package/tooling/claude/reference.md

@@ -14,6 +14,7 @@ The claude stack installs the `.claude/` workflow directory into a project. Stat
 ├── ARCHITECTURE.md    ← seeded. Technical design decisions and open questions
 ├── DESIGN.md          ← seeded. Visual intent and the decisions behind it
 ├── wireframes/        ← seeded. Per-surface ASCII layouts. `index.md` is the discovery anchor; `<surface>.md` files hold the sketches and behavior bullets.
+├── diagrams/          ← seeded. Per-kind Mermaid views. `index.md` is the discovery anchor. `<kind>.md` files hold one diagram each, grouped by the `category` frontmatter field.
 ├── GOV.md             ← retired. Removed by `aitk gov sync` if present from a prior install
 ├── settings.json      ← seeded. Project-level Claude Code config (PreToolUse and PostToolUse hooks). User-level config installed separately via `aitk claude setup`.
 ├── plans/             ← execution detail for multi-step tasks, gitignored. `feature-*.md` entries swept by claude-docs.
@@ -32,6 +33,10 @@ Convert by hand, once per project:
 2. Run `aitk indexes regen --no-stage --root . .claude/tasks/<any-task>.md` to build the catalog.
 3. Delete `.claude/TASKS.md`, and swap its `.gitignore` entry for `.claude/tasks/`.
 
+## Upgrading from a single-file diagram set
+
+A project installed before the diagram surface became a folder still holds `.claude/DIAGRAMS.md`. Unlike the board, this one migrates itself. The `claude-diagram` skill reads the flat file when `.claude/diagrams/` holds no entries, splits it by kind into the folder, and reports what it wrote. The old file stays on disk so the split can be compared against its source, and deleting it is a manual step once that check passes.
+
 ## Gitignore
 
 - `# Claude`: `.claude/.tmp/`, `.claude/memory/`, `.claude/plans/`, `.claude/review/`, `.claude/worktrees/`, `.claude/tasks/`

package/tooling/claude/seeds/.claude/diagrams/index.md

@@ -0,0 +1,8 @@
+---
+title: Diagrams
+subtitle: Per-kind Mermaid views loaded on demand. Start with system context.
+---
+
+# Diagrams
+
+Per-kind Mermaid views loaded on demand. Start with system context.