Human-facing documentation, architecture docs, and mermaid diagrams for a codebase, a module, or a feature — "draw me the architecture, with receipts." Fans out read-only sub-agents to build a grounded component graph first: every node is a real path, every edge backed by a grep-verified import or call — unverifiable edges are dropped, not drawn. Diagrams render from that verified table per a fixed checklist (never freehand mermaid), capped at 5–8 top-level components with drill-down pages; every doc section cites its sources as file:line. Drafts in chat, writes docs/blueprint/ only on your yes, and stamps a manifest with date + commit so /blueprint refresh regenerates only what the diff touched. Use for "generate an architecture diagram", "document this codebase or module for people", "create a mermaid diagram of this feature" — e.g. "/blueprint", "/blueprint the payment flow", "/blueprint refresh". For agent-facing orientation (AGENTS.md) use map; blueprint is the human-facing sibling.
Human-facing documentation, architecture docs, and mermaid diagrams for a codebase, a module, or a feature — "draw me the architecture, with receipts." Fans out read-only sub-agents to build a grounded component graph first: every node is a real path, every edge backed by a grep-verified import or call — unverifiable edges are dropped, not drawn. Diagrams render from that verified table per a fixed checklist (never freehand mermaid), capped at 5–8 top-level components with drill-down pages; every doc section cites its sources as file:line. Drafts in chat, writes docs/blueprint/ only on your yes, and stamps a manifest with date + commit so /blueprint refresh regenerates only what the diff touched. Use for "generate an architecture diagram", "document this codebase or module for people", "create a mermaid diagram of this feature" — e.g. "/blueprint", "/blueprint the payment flow", "/blueprint refresh". For agent-facing orientation (AGENTS.md) use map; blueprint is the human-facing sibling.
blueprint — architecture the team can read, with receipts
/blueprint — whole-repo architecture doc + top-level mermaid diagram
/blueprint <module|feature> — scoped doc + diagram for one area
/blueprint refresh — regenerate only what the diff since the stamp touched
Answer one question: what does a person need to see to understand how this
code is put together — and can every box and arrow be defended? The
documented failure mode of AI-generated architecture docs is confident
fiction: diagrams with components that don't exist and arrows nobody can
trace. The countermeasure is structural, not stylistic — no edge without a
locator, no mermaid the checklist didn't render, no write without a yes.
Step 0 — Scope, and respect what exists
Look before generating:
Existing output? Check for docs/blueprint/ and its manifest.md.
The explicit command wins: a scope argument runs SCOPED and
/blueprint refresh runs REFRESH regardless. A bare with
existing output defaults to REFRESH — read the manifest first and jump to
the refresh path in Step 5; offer a full regenerate only if the user asks
or the manifest looks obsolete. An existing
hand-written file is context to read and link, never
to overwrite. Whichever mode wins, if the manifest's stamp trails HEAD,
state the drift in one line — "blueprint is N commits behind (touched:
X, Y)" via + over
— and offer the refresh unless this run already
is one. A stamp that no longer resolves (rebase, shallow clone) is itself
the staleness signal: report it and offer a full regenerate. Staleness
surfaces at every touch, not only on a remembered refresh.
/blueprint
docs/architecture*
git rev-list --count
git diff --stat
<stamped-commit>..HEAD
Orient cheaply first. Read AGENTS.md/CLAUDE.md/README if present
(the map skill writes the first) — they answer in seconds what fan-out
answers in minutes. No AGENTS.md in a large repo? Offer /map first; its
output makes this run better and the repo better oriented for every later
agent.
Size the repo (git ls-files | wc -l, top-level layout) to scale the
fan-out: a small repo graphs in one pass inline; a large or polyglot one
gets one Explore agent per area.
A scope argument (/blueprint the payment flow) narrows everything to
that module or feature: the graph, the doc, and the diagram cover that
area and its direct boundaries — not the whole repo.
State the mode picked (FULL / SCOPED / REFRESH) and why.
Step 1 — Fan out, gather the raw graph
Dispatch read-only Explore sub-agents — grep/glob/read, keyless, no
index to go stale — one per area (FULL) or one per boundary (SCOPED). Each
agent returns, for its area:
Candidate components — the directories/modules that act as units,
each with its entry file and one line on its job.
Candidate edges — imports, calls, route registrations, queue
producers/consumers, config wiring — each with the file:line where it
was seen. An edge the agent "believes" but didn't see is reported as
a question, not an edge.
The story — how execution flows through the area, as prose pointing
at files.
Lossless hand-off: each agent writes full findings to
out/blueprint/.work/<area>.md and returns a summary; synthesize from the
files, not the relay.
Step 2 — The verified graph (before any diagram)
Distill the findings into a node/edge table — the single source of truth
everything downstream renders from:
Nodes: 5–8 top-level components (≤30 nodes total including
sub-nodes). Each row: stable ID (comp-<slug>, survives renames), display
name, the real path it lives at, one-line job. A node whose path doesn't
exist doesn't enter the table. Utilities/logging don't get boxes — they're
noise at this altitude.
Edges: each row: from-ID, to-ID, verb ("calls", "imports", "publishes
to"), and the locator — the file:line of the import/call/route that
proves it. Before an edge enters the table, grep the claimed locator: the
cited line must actually contain the relation. Unverifiable edge →
dropped and listed under "unverified candidates" in the work notes —
never softened into the diagram.
Collapse first. When the table exceeds the caps, roll nodes up to
their parent component rather than shrinking the boxes — a hairball
communicates nothing (the decade-long lesson of every dependency-graph
tool). Scoped runs may drill one level deeper per component page.
Step 3 — Render the diagram (never freehand)
Read references/mermaid-checklist.md now and follow it exactly. The rules
in brief: the mermaid is rendered mechanically from the table — short
IDs from the node rows, quoted labels, no raw parentheses/brackets in label
text, click links to each node's real path, flowchart TD, size caps
honored. The LLM never composes mermaid prose-first; two independent
projects (gitdiagram, deepwiki-open) proved prompt rules alone don't stop
syntax breakage — structure does.
Validate before it ships: re-parse the output against the checklist's
failure list. On a broken render, repair with max 3 attempts, each
fixing only the itemized issues — then degrade to a simpler diagram
(fewer nodes, no subgraphs) rather than attempt a fourth. A plain diagram
that renders beats a rich one that doesn't.
Step 4 — Write the docs (grounded prose)
Read references/output-template.md now for the exact layout. The doc set:
docs/blueprint/README.md (overview + top-level diagram), one
<component>.md per drill-down (SCOPED runs and large components), and
manifest.md (the node table + stamp). Prose rules, non-negotiable:
Every section ends with Sources: <file>:<start>-<end>, … — the
files the section was written from. A section that can't cite sources
gets rewritten from files it can cite, or cut.
Verb-first, no filler. "Routes payments to the gateway
(src/pay/router.ts:40)" — never "This file is responsible for…". No
personas, no marketing adjectives, no claims the code doesn't show.
Explain the why where the code can't. The prose earns its place by
saying what a diagram can't: why the boundary sits here, what invariant
the arrow protects. Anything a read trivially reveals is cut.
Step 5 — Approve, write, stamp — and refresh
The output lands in the user's repo, so nothing is written without a yes:
Show the full draft in chat — diagram and docs — and invite edits; cuts
count as much as additions.
On approval, write docs/blueprint/, stamping manifest.md with
today's date +%F and the current commit (git rev-parse --short HEAD)
— never a guessed date.
Offer, don't perform, the commit.
Auto mode (under autopilot): the draft→approve gate becomes
write-and-log, per the run's charter — same as map.
On REFRESH:git diff --name-only <stamped-commit>..HEAD, map the
changed paths to component IDs via the manifest's node table, and
regenerate only the pages and diagram sections those IDs own; re-stamp.
Component identity is the stable ID, not the display name — a renamed
component updates in place instead of forking a new page. Pages whose
components saw no diff are left byte-identical. Changed paths that map to
no node (new, moved, or deleted territory) mean the graph itself moved:
re-derive the affected part of the node table and regenerate the overview
and manifest, not just member pages.
Guardrails
No edge without a locator. An arrow nobody can trace to a file:line
is fiction wearing a diagram — dropped, not drawn. (The one habit that
separates this from every "AI architecture diagram" complaint thread.)
Collapse beats shrink. 5–8 boxes that mean something over 50 that
don't; drill-down pages carry the detail.
The table is the diagram's source. Mermaid is rendered from the
verified node/edge table per the checklist — composing it freehand is how
syntax errors and invented components get in.
Never write or commit unprompted. Draft → approve → write; commit
only on an explicit yes. (Auto mode logs instead of asks, per charter.)
Refresh regenerates the minimum. Untouched components keep
byte-identical pages — churn-free diffs are what make the docs
re-runnable, and re-runnable is what keeps them alive.
Out of scope, on purpose: HTML viewers, CI auto-regeneration,
static-analysis engines, multi-repo, and non-mermaid formats (dot, d2,
images) — machinery this repo's axis (keyless, zero-dependency,
prose-only) exists to avoid.
