# Architecture Audit > Repo Architecture Audit - Skill: `martinplarsen/architecture-audit` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add martinplarsen/architecture-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/martinplarsen/architecture-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Security - Author: MartinPLarsen (https://skillmd.com/u/martinplarsen) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/martinplarsen/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-.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.