Architecture Audit

Repo Architecture Audit

What this does and why it works

Produce one self-contained Markdown document that explains an entire codebase start-to-finish, with Mermaid flowcharts as the primary medium, grounded in path:line evidence, and verified against the real code before it is handed over. The output is a decision aid: someone reads it and knows how the system connects and where to edit things, without re-reading the repo.

The method is subagent-driven for a reason. A whole-repo audit is too much for one context to hold well, and one reader is blind to the seams between subsystems. Fanning out one reader per subsystem in parallel covers more ground, keeps each reader's context focused, and surfaces contradictions between subsystems that a single pass misses. A dedicated verify pass then catches the failure mode that matters most here: a confident synthesis claiming something the code does not actually do (planned work shown as shipped, wrong gate order, invented field mappings).

You are the orchestrator. Scout first so the fan-out is informed, then run the phases below. Default to the Workflow tool (this skill is explicit opt-in for it). If Workflow is unavailable, fall back to parallel Agent calls; if subagents are unavailable entirely, run the phases inline and sequentially, which is slower and lower-coverage but still works.

Phase 0 — Scout inline (do not fan out blind)

Spend a few cheap tool calls building the work-list before spawning anything. You cannot pick good subsystem boundaries until you have seen the shape of the repo.

• Map the tree and file sizes, excluding vendored/generated noise: node_modules, .git, dist/build/out, vendor, .next, target, lockfiles, and any worktrees/mirror copies (read each file once, from the canonical tree only).
• Read the entry points and the docs that explain intent: README, package.json/pyproject/go.mod/Cargo.toml/etc., any CLAUDE.md/ARCHITECTURE/docs/, migrations, and config.
• Identify the subsystems — the natural seams along which to split readers. These are repo-specific; derive them, do not assume. Common seams:
  • agents / services / workers (the active units of work)
  • executable pipeline or business-logic code (what actually runs, vs specs)
  • data layer (schema, migrations, state model, storage)
  • the domain's core transform (the thing this system exists to do: image/media generation, schema mapping, ETL, model inference, payment flow)
  • external integrations / publishing (APIs, third-party services, webhooks)
  • frontend / presentation / rendering
  • orchestration / control plane / scheduling / cost or rate guards
  • governance / rules / config / requirements contracts
• Decide reader count from repo size: small repo → 4-5 readers, medium → 6-8, large/monorepo → 9-12 (and consider one reader per package). Note language and conventions (so output language matches the repo).

Tell the user the subsystem split you chose in one line, then launch.

Phase 1 — Map (parallel readers, one per subsystem)

Spawn one reader per subsystem in parallel. Each reader reads its files fully (cite path:line), ignores the excluded dirs, and returns structured notes — not a chat reply, raw data for synthesis. Give every reader the same output template so the synthesizer can merge them; see references/doc-template.md for the template and the full diagram catalog.

The exact orchestration that works — a Workflow script with a Map → Synthesize → Verify → Fix pipeline — is in references/workflow-skeleton.js. Read it, fill in the scouted subsystem list and per-reader prompts, and run it with Workflow({script}). It is parameterized; you only edit the READERS array and the date.

Each reader extracts, for its subsystem: a summary; components (name, status: shipped / parked / planned, role, inputs, outputs, key files path:line, services used); data and control flow with the trigger and handoff contract; rules/gates enforced; diagram hints as A --> B: label edges; and gotchas/stale/contradictory findings. The status field is load-bearing: the single most useful and most error-prone thing an architecture doc does is distinguish what is built from what is only specified.

Phase 2 — Synthesize (write the document)

One agent takes all reader notes and writes the audit doc to docs/ARCHITECTURE-AUDIT-<YYYY-MM-DD>.md (or the repo's docs convention). Write to a new dated file — never overwrite an existing architecture.md or any doc that may be locked; reference the old one instead. Prose in the user's/repo's language, identifiers/paths/table names in their original form.

The doc follows the section + diagram catalog in references/doc-template.md. Every major section carries at least one valid Mermaid diagram (flowchart, sequenceDiagram, stateDiagram-v2, erDiagram). Keep node labels short and put detail in the surrounding prose. The non-negotiable diagrams: a system-context graph, an end-to-end primary-flow flowchart with every gate/decision drawn as a decision node, and a "where do I edit X" cheatsheet table. Adapt the rest to what the repo actually has.

Phase 3 — Verify (adversarial, against the code)

Spawn a verifier that reads the written doc, then checks its load-bearing claims against the actual files. Focus on the claims most likely to be wrong: stage/flow order and which module owns each step; every gate and threshold; data model / state machine values; the core-transform details (model names, field mappings, formats); shipped-vs-planned labels; and that Mermaid blocks are syntactically valid. It returns findings as {severity, location, claim, reality (path:line), fix} and a one-line verdict. This pass is what makes the doc trustworthy rather than plausible.

Phase 4 — Fix

Apply the real corrections (blockers/majors and clearly-correct minors) with surgical edits to the doc, preserving what was right and keeping Mermaid valid. Return a short changelog.

After the run

Relay to the user, briefly: where the doc is, how many diagrams, the handful of facts that should change their mental model (especially shipped-vs-planned surprises and anything stale/contradictory found), and offer one clear next action (commonly: reconcile the stale docs the audit surfaced). Do not invent recommendations the audit does not support.

Quality bar (the few things that make or break this)

• Evidence over assertion. Every claim traces to path:line. "The code shows X" beats "the system does X".
• Honest status. Never present specs/planned work as shipped. When sources disagree, say so in the doc rather than silently picking one.
• Diagrams carry the load. The user asked to see it. Lead with flowcharts; prose annotates them.
• Verify before handover. The Fix phase is not optional; an unverified audit is plausible fiction.
• Don't clobber. New dated file. Locked/append-only docs are read, not rewritten.