@erclx/aitk 0.8.0

package/claude/skills/ci-workflow/references/workflows.md

@@ -0,0 +1,74 @@
+# CI workflow template
+
+Copy this base template and adapt it to the project's stack, test commands, and build output. Add or remove jobs as needed while preserving the parallel and gated structure.
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  static:
+    name: '🛡️ Static Checks'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run check
+
+  unit:
+    name: '🧪 Unit Tests'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run test
+
+  build:
+    name: '📦 Build Check'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - run: bun run build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+
+  e2e:
+    name: '🎭 E2E Tests'
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+      - run: bun install --frozen-lockfile
+      - uses: actions/download-artifact@v4
+        with:
+          name: build-output
+          path: dist/
+      - run: bun run test:e2e
+      - uses: actions/upload-artifact@v4
+        if: failure()
+        with:
+          name: e2e-results
+          path: test-results/
+          retention-days: 7
+```

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

@@ -0,0 +1,107 @@
+---
+name: claude-address-review
+description: Pulls review findings and CI status on the current branch's open PR, fixes each in the working tree, refreshes any stale `.claude/` docs, replies with a summary comment, and pushes a follow-up commit. The worker's return leg after `claude-pr-review`. Use when asked to "address the review", "fix the PR comments", "respond to review", or after an orchestrator posts findings. Do NOT use to write a review. That is `claude-pr-review`.
+---
+
+# Claude address review
+
+The worker's half of the review channel. `claude-pr-review` posts findings to
+the PR from an independent session. This skill consumes them: fix, reply, push.
+
+## Guards
+
+- If no open PR resolves for the current branch via `gh pr view`, stop: `❌ No open PR. Nothing to address.`
+- If the PR has no review comments or threads, stop: `✅ No review findings to address.`
+- Fix findings. Do not merge.
+
+## Step 1: pull the review findings and CI status
+
+Read the review comments and threads on the PR:
+
+```bash
+gh pr view --json number,reviews,comments
+```
+
+For inline review comments, read them via `gh api` on the PR's review comments. Collect each finding with its file, location, and body.
+
+Also read the CI check status so the fixes cover failing checks, not only review comments:
+
+```bash
+gh pr checks <number>
+```
+
+Treat a failing check as a finding to resolve alongside the review comments. When no checks are configured, `gh pr checks` reports none and the flow continues on the review findings alone.
+
+## Step 2: address each finding
+
+For each finding, implement the fix in the working tree. When a finding is a
+question or a conscious-accept rather than a defect, note the reply text instead
+of editing. Handle each finding independently. Do not let one unresolved finding
+block the others.
+
+## Step 3: verify
+
+Run the project check (`bun run check` or the project's documented equivalent).
+Do not push a red follow-up.
+
+## Step 4: refresh stale docs
+
+The fixes may have changed or added behavior that `.claude/` context entries, docs, or wireframes describe. Refresh them with the `claude-docs` skill, which maps the changed files to the entries that reference them and rewrites the stale sections. Do not reimplement that mapping here. When a fix adds a new capability with no existing entry, `claude-docs` flags it rather than creating one.
+
+## Step 5: push, then reply
+
+Push the fixes before posting the reply so the comment never runs ahead of the
+code it describes. Ship the fixes as a follow-up commit on the same branch with
+the `git-followup` skill, invoked with `reply-owned` so it stages, commits,
+pushes, and refreshes the open PR body without posting its own comment. This
+skill owns the reply. Do not reimplement that flow here. For in-place fixes to
+files the PR body already covers, `git-followup` leaves the body untouched and
+the reply comment carries the fix log.
+
+Then write a summary reply to `.claude/.tmp/address-review/reply-<number>.md`
+mapping each finding to what changed, or to a one-line reason when it is a
+conscious-accept rather than a defect. Key the filename on the PR number so two
+sessions addressing different pull requests never overwrite each other between
+the write and the post. Note any `.claude/` docs refreshed as a result of the
+fixes. The reply is a rendered-for-human GitHub surface, so follow
+`.claude/standards/prose.md` for voice, or `${CLAUDE_SKILL_DIR}/../../standards/prose.md`
+when the project does not have it, and keep each mapping to a line or two.
+Open the body with the `## Review response` heading so it anchors as a section
+distinct from human threads and stays subordinate to the `## Review` heading the
+review itself carries. Follow it with a one-line summary sentence, then one
+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:
+
+```bash
+gh pr comment <number> --body-file .claude/.tmp/address-review/reply-<number>.md
+```
+
+## Step 6: confirm resolution
+
+After the follow-up push, watch CI on the PR. Poll `gh pr checks <number>`
+until no check is pending, then read the final status. When every finding is
+addressed and all checks pass, post one closing comment so the thread has a
+clear terminal state:
+
+```bash
+gh pr comment <number> --body "✅ All review findings addressed, CI green."
+```
+
+If any check fails, do not post the closing comment. Report the failing check
+so it can be fixed first. This is a resolution signal, not a formal approval,
+since the PR author cannot approve their own PR.
+
+## Step 7: output
+
+```plaintext
+Addressed <N> findings on PR #<number>. Follow-up pushed.
+```
+
+Name any finding left as a reply rather than a code change, with its one-line
+reason. Do not merge. Hand back to the orchestrator for re-review.

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

@@ -0,0 +1,137 @@
+---
+name: claude-autoship
+description: Chains implement → verify → review → ship after a feature plan is approved. Reads the plan for the current branch, runs the full pipeline in one session, and stops on any failure or non-minor review finding. Use when asked to "autoship", "ship this feature end to end", or "run the chain". Do NOT auto-trigger. Requires an approved plan file.
+disable-model-invocation: true
+---
+
+# Claude autoship
+
+Chain the post-plan pipeline in a single run. Every step has a stop condition. State is always recoverable on stop: code lives on the branch, review output on disk, plan still linked.
+
+## 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.`
+- 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.`
+
+## Diff baseline
+
+Step 5 classifies the changed-file list to decide whether review runs. Resolve the base ref once:
+
+```bash
+git merge-base HEAD origin/main 2>/dev/null || git merge-base HEAD main 2>/dev/null
+```
+
+Prefer `origin/main` over local `main`. A local `main` trailing the remote pulls other people's merged commits into the list, so the classifier decides against files this branch never touched.
+
+The baseline is unusable when no merge base resolves against either ref. Stop: `❌ No diff baseline against main. Fetch origin, then re-run autoship.`
+
+The base equalling HEAD stays usable here, unlike in the four read-only siblings carrying this section. Step 5 runs before anything is committed, since `git-stage` commits at Step 7, so the base equals HEAD on every ordinary run. The classifier diffs the base against the working tree rather than against HEAD, which keeps the uncommitted work in the set at correct scope. Do not port the sibling `base == HEAD` stop into this skill.
+
+## Step 0: enter a worktree
+
+If `git rev-parse --git-dir` equals `git rev-parse --git-common-dir`, the session is in the main worktree. Invoke `aitk:claude-worktree` before continuing. The wrapper handles name derivation and branch alignment. Do not call `EnterWorktree` directly.
+
+If neither command resolves, stop: `❌ Not a git repository. Autoship needs git or a WorktreeCreate hook.`
+
+If the two commands differ, the session is already in a linked worktree. Continue.
+
+## Step 1: read the plan
+
+Read `.claude/plans/feature-<slug>.md` at the main worktree root. This file is the scope for this run.
+
+## Step 2: implement
+
+Implement only what the plan describes. Do not expand scope. Do not refactor neighbors. Do not touch files outside the plan's "Files to touch" list without reason.
+
+## Step 3: verify
+
+Run the verify commands defined in `CLAUDE.md` (lint, typecheck, tests). On failure:
+
+- Make **one** fix attempt targeting the reported errors
+- Re-run only the failing command
+- If it still fails, stop: `❌ Verify failed after one fix attempt. Review logs and retry manually.`
+
+Do not loop. Do not bypass hooks.
+
+## Step 4: UI test (conditional)
+
+If the diff touches UI files (JSX, TSX, Vue, Svelte, HTML, or CSS under `src/`), invoke `aitk:claude-ui-test`.
+
+If `claude-ui-test` produces a manual checklist, stop: `❌ UI requires visual verification. Checklist at .claude/review/ui-checklist-<slug>.md. Verify manually, then run /git-ship.`
+
+If all UI changes are covered by e2e tests, continue.
+
+## Step 5: review
+
+Classify the diff first. Take the union of `git diff --name-only <base>` and `git ls-files --others --exclude-standard`, resolving `<base>` per Diff baseline. The classifier reads names only.
+
+An empty list stops the chain: `❌ No changed files to classify. Re-run when the plan has yet to produce its output. When the output is gitignored by design, autoship cannot ship it, so take the work out of the chain.` An empty list satisfies the prose-only test vacuously, so reading it as prose-only routes the branch past review instead of through it.
+
+The two causes want different responses. A plan that has yet to produce its output is a re-run once it has. A plan whose output is gitignored by design, such as a read pass writing to `.claude/.tmp/`, is work the chain cannot carry at all, since `git-stage` finds nothing to commit six steps later. Never advise removing the output from `.gitignore`, which trades a stopped run for scratch committed into the repository.
+
+If every changed file matches `*.md` or `*.txt`, skip review entirely and continue to Step 7. Prose-only changes are already gated by `docs-sync`, `claude-standards-audit`, and pre-push hooks. Running a code-style review on them burns tokens with no signal.
+
+Otherwise invoke `aitk:claude-review`.
+
+## Step 6: evaluate findings
+
+Skip this step if Step 5 was skipped (prose-only diff). Otherwise read `.claude/review/review-<slug>.md` at the main worktree root. Parse the summary line (`X critical, Y should-fix, Z minor`):
+
+- Any critical or should-fix count greater than zero, stop: `❌ Review found non-minor issues. See .claude/review/review-<slug>.md. Fix and run /git-ship.`
+- Zero critical and zero should-fix, continue. The minor findings stay in the on-disk review receipt. Fold any a reviewer needs into the PR's `## Technical Context`. Do not add a separate review-notes section to the PR body.
+
+Do not auto-fix findings. The stop here is deliberate.
+
+## Step 7: ship
+
+Invoke each sub-skill in order via the Skill tool. After each returns, invoke the next immediately. Do not output text between steps.
+
+1. `aitk:claude-docs`: sync `.claude/` planning docs against session decisions
+2. `aitk:docs-sync`: sync public docs against changes since main
+3. Run `git add -A` to stage files the sync skills wrote
+4. `aitk:git-stage`: group staged changes and commit by concern
+5. `aitk:git-branch`: rename the branch to conventional format
+6. `aitk:git-pr`: push and open the pull request
+
+After the PR is created, mark it as draft:
+
+```bash
+gh pr ready --undo
+```
+
+After marking draft, watch CI. Poll `gh pr checks <number>` until no check is pending, then read the final status. On all-pass, continue. On any failure, stop and report the failing check with its URL. Do not auto-fix.
+
+7. `aitk:claude-memory-capture`: extract durable patterns from the session into `.claude/memory/`
+8. `aitk:claude-memory-review`: if `claude-memory-capture` wrote or updated at least one entry this session, propose fixes scoped to those entries, writing the decision-ready receipt while session context is fresh. Skip when capture wrote nothing.
+
+Stop at the Propose phase. Do not run Apply. Promoting an entry to `CLAUDE.md` or a skill body mutates how the agent operates and ships as its own change, separate from this feature.
+
+## Output
+
+Respond with up to four lines:
+
+```plaintext
+✅ Autoshipped (draft): <PR url>
+<N minor findings kept in .claude/review/review-<slug>.md>
+<N memories captured in .claude/memory/>
+<Memory proposal at .claude/review/memory-review-<slug>.md>
+```
+
+Omit the second line if there were no minor findings. Omit the third and fourth lines if `claude-memory-capture` wrote nothing this session, since no captures means no scoped review and no proposal.
+
+## Failure recovery
+
+Every stop point leaves recoverable state. The user resumes manually from the appropriate step.
+
+| Stop point                         | Recovery                                                                                                                                       |
+| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
+| No plan                            | Run `/claude-feature` to create one                                                                                                            |
+| No diff baseline                   | Fetch origin so a merge base resolves against `main`, then re-run autoship                                                                     |
+| Empty changed-file list            | Re-run once the plan produces tracked output. Ship gitignored output outside the chain, never by tracking it.                                  |
+| Branch collision on worktree entry | `claude-worktree` Step 5 found `<slug>` already as a local branch. Resolve manually (rename or delete the stale branch), then re-run autoship. |
+| Verify fails                       | Read logs, fix manually, run `/git-ship`                                                                                                       |
+| UI checklist                       | Verify visually, run `/git-ship`                                                                                                               |
+| Review findings                    | Fix findings, run `/git-ship`                                                                                                                  |
+| git-ship fails                     | Inspect hook or remote error, run again                                                                                                        |

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

@@ -0,0 +1,69 @@
+---
+name: claude-design-extract
+description: Drafts `.claude/DESIGN.md` from a project's existing prose and shell UI surfaces using the toolkit seed template. Reads CLAUDE.md, standards, docs, and CLI UI modules to codify visual intent already implicit in the project. Use when asked to "extract the design system", "draft DESIGN.md", "bootstrap design tokens", or "capture the visual system". Do NOT use to mutate an existing `.claude/DESIGN.md`.
+---
+
+# Design extract
+
+## Guards
+
+- If `.claude/DESIGN.md` already exists and has content beyond the seed template, stop: `❌ .claude/DESIGN.md already populated. Edit directly or archive the existing file first.`
+- If `aitk` is not on PATH, stop: `❌ aitk CLI not found.`
+
+## Step 1: read source signals in parallel
+
+Read these from the project root, skipping any that do not exist:
+
+- `CLAUDE.md`: voice, personality, spelling rules
+- `.claude/REQUIREMENTS.md`: worldview and non-goals that shape visual intent
+- `.claude/standards/prose.md`: tone constraints
+- `src/ui.ts`, `src/ui.tsx`, `src/components/**`: color codes, typography, spacing constants
+- `scripts/lib/ui.sh`, `scripts/lib/*.sh`: ANSI color codes, frame glyphs, spacing conventions
+- `docs/agents.md`, `docs/index.md`: any output shape or framing rules already documented
+- Any `*.css`, `tailwind.config.*`, or `theme.*` file at the project root
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+Run these reads in parallel. Do not speculatively recurse into every directory.
+
+## Step 2: fetch the seed template
+
+Run this from the project root:
+
+```bash
+aitk claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md") | .content'
+```
+
+Use the returned content as the target shape. Keep every section heading and every table header intact. The `aitk design render` parser depends on them.
+
+## Step 3: fill the template
+
+Walk each section once, pulling concrete signals from Step 1:
+
+- **Personality**: one paragraph. Transcribe what `CLAUDE.md` and `.claude/REQUIREMENTS.md` say about voice, tone, and visual feeling. Do not invent rules the source does not state. Follow `.claude/standards/prose.md`: no em dashes, no semicolons, no marketing buzzwords. If nothing matches, write a one-sentence placeholder ending in `? verify`.
+- **Color**: one row per role. Source hex values from the CLI UI files or stylesheets. If a role has no source signal, leave `Value` blank rather than guessing.
+- **Typography**: one row per role. Source families and sizes from stylesheet or theme config. Leave cells blank when no signal exists.
+- **Spacing**: fill the base unit and multipliers from stylesheet tokens or obvious repeated values in the UI code.
+- **Borders**: one row per role. Source from stylesheet or CSS variables.
+- **Motion** and **Iconography**: one line each. Default to `No animation.` and `No custom icons.` when no evidence exists.
+
+Mark any inferred cell by appending ` ? verify` inside the cell value, never as a trailing column. The cell stays inside the table shape: `| display ? verify | | | | |`. A trailing `| ? verify` after the row breaks the parser.
+
+## Step 4: write and render
+
+Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
+
+```bash
+aitk design render
+```
+
+The command writes an HTML plus CSS preview to `.claude/review/design/`. Output the path in chat so the user can open it.
+
+## Response format
+
+```plaintext
+📝 Wrote .claude/DESIGN.md
+📝 Wrote .claude/review/design/index.html
+
+N cells marked `? verify`. Open the preview and confirm before committing.
+```

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

@@ -0,0 +1,75 @@
+---
+name: claude-design-propose
+description: Drafts `.claude/DESIGN.md` on day one of a project from `REQUIREMENTS.md`, `ARCHITECTURE.md`, and a `## Personality` section, with token values proposed by the agent. Use when asked to "propose a design system", "bootstrap DESIGN.md from scratch", "draft tokens for a greenfield project", or "replace Claude Design onboarding". Do NOT use when UI code or stylesheets already exist. Reach for `claude-design-extract` instead.
+---
+
+# Design propose
+
+## Guards
+
+- If `.claude/DESIGN.md` already exists and has content beyond the seed template, stop: `❌ .claude/DESIGN.md already populated. Edit directly or archive the existing file first.`
+- If `.claude/REQUIREMENTS.md` is missing, stop: `❌ .claude/REQUIREMENTS.md not found. Write requirements before proposing a design system.`
+- If `.claude/REQUIREMENTS.md` has no `## Personality` section, stop: `❌ .claude/REQUIREMENTS.md missing ## Personality section. Add a paragraph describing voice and tone before running this skill.`
+- If `aitk` is not on PATH, stop: `❌ aitk CLI not found.`
+
+## Step 1: read source signals in parallel
+
+Read these from the project root, skipping any that do not exist:
+
+- `.claude/REQUIREMENTS.md`: the `## Personality` paragraph, worldview, non-goals
+- `.claude/ARCHITECTURE.md`: platform, tech stack, surface type (CLI, web, desktop)
+- `CLAUDE.md`: voice rules, spelling, conventions
+- `.claude/standards/prose.md`: tone constraints if present
+
+Read a standard from `${CLAUDE_SKILL_DIR}/../../standards/` instead when the project does not have it.
+
+Do not scan `src/`, stylesheets, or UI modules. This skill runs before code exists. If those files are present, the scenario is wrong and `claude-design-extract` is the correct tool.
+
+## Step 2: fetch the seed template
+
+Run this from the project root:
+
+```bash
+aitk claude seeds list --json | jq -r '.[] | select(.path == ".claude/DESIGN.md") | .content'
+```
+
+Use the returned content as the target shape. Keep every section heading and every table header intact. The `aitk design render` parser depends on them.
+
+## Step 3: propose tokens from personality and requirements
+
+Walk each section once. Follow `.claude/standards/prose.md` throughout: no em dashes, no semicolons, no marketing buzzwords. Use commas or separate sentences instead.
+
+Every proposed table cell is speculative, so every filled table cell gets a trailing `? verify` tag inside the cell value, never as a trailing column.
+
+Anchor proposals to signals, not defaults. If the personality says "calm and dense", that pins muted grays and tight spacing. If the requirements say "no motion", Motion writes `No animation.` with no tag. If the architecture names a CLI-only surface, Typography leans monospaced and Borders stays minimal.
+
+- **Personality**: transcribe the `## Personality` paragraph from `.claude/REQUIREMENTS.md` verbatim. This is the one section that is not a proposal. No tag.
+- **Color**: one row per role. Rewrite the Intent cell in personality language, for example `warm off-white page canvas` instead of the seed default `page canvas`. Propose hex values that match the personality. Dense and calm → low saturation, high text contrast. Playful → saturated accents. Every Intent and Value cell gets `? verify`.
+- **Typography**: one row per role. Propose families that fit the platform (system UI for web, monospaced for CLI tools, serif for editorial) and a harmonious scale. Every cell gets `? verify`.
+- **Spacing**: propose a base unit that matches density intent. Dense → 4px base. Roomy → 8px base. Keep the Multiplier column as the seed ships it, no tag. Only the Value column gets `? verify`.
+- **Borders**: propose radius and width per role. Sharp and technical → small radius. Soft → larger radius. Every Radius and Width cell gets `? verify`.
+- **Motion**: one line. If the requirements forbid motion, write `No animation.` If motion is allowed, phrase uncertainty inline, for example `Proposed 150ms ease-out, not yet confirmed.` Do not append a trailing `? verify` tag to a prose sentence. It renders raw in the preview.
+- **Iconography**: one line. Propose style and source library matching personality. Phrase uncertainty inline, for example `Proposed outline style, source library not yet chosen.` Do not append a trailing `? verify` tag.
+
+Do not invent non-goals. If the personality paragraph does not mention motion and the requirements do not forbid it, a proposed motion line is acceptable.
+
+A cell marked `? verify` must stay inside the table shape: `| #ffffff ? verify |`. A trailing `| ? verify` column breaks the parser.
+
+## Step 4: write and render
+
+Write the filled template to `.claude/DESIGN.md` from the project root. Then run:
+
+```bash
+aitk design render
+```
+
+The command writes an HTML plus CSS preview to `.claude/review/design/`. Output the path in chat so the user can open it.
+
+## Response format
+
+```plaintext
+📝 Wrote .claude/DESIGN.md
+📝 Wrote .claude/review/design/index.html
+
+N cells marked `? verify`. Open the preview, confirm the personality read as intended, then edit DESIGN.md directly to lock values.
+```

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

@@ -0,0 +1,126 @@
+---
+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`).
+---
+
+# Claude diagram
+
+## 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
+
+Read these from the project root, skipping any that do not exist:
+
+- `.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.
+
+## Step 2: pick which diagrams to emit
+
+Emit a diagram only when its source signal exists. Skip the rest, do not pad the 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
+
+Stay inside `flowchart` and `sequenceDiagram`. Do not emit C4, state, ER, or class diagrams. They render inconsistently across viewers.
+
+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 3: write the file
+
+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.
+
+File format:
+
+````markdown
+# Diagrams
+
+<one-paragraph note on what this file contains and which sources drove it>
+
+## <Section title>
+
+<one-line description of what this diagram shows>
+
+```mermaid
+<diagram type>
+  accTitle: <what the diagram answers>
+  accDescr: <the structure in one sentence>
+  <body>
+```
+
+## <Next section>
+
+...
+````
+
+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.`
+
+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.
+
+## Step 4: 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.
+
+Before the first render in a project, say what is about to block:
+
+```plaintext
+Rendering to verify layout. The first run downloads the Mermaid CLI and takes about 15 seconds.
+```
+
+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
+```
+
+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.
+
+## Step 5: read the render 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.
+
+Fix the source and re-render. Stop after two correction passes on a diagram.
+
+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.
+
+## Step 6: chat output
+
+```plaintext
+📝 Wrote .claude/DIAGRAMS.md with N diagrams.
+
+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.
+
+## Step 7: 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
+```
+
+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:
+
+```plaintext
+📝 Wrote N files to .claude/review/diagrams/
+```