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).