Architecture Doc

Generate or update a living ARCHITECTURE.md for the current codebase — a document that gives agents and engineers an instant, complete picture of how the system is structured, what it uses, and how it deploys.

NEVER Do When Writing Architecture Docs

• NEVER overwrite ARCHITECTURE.md without reading it first — existing sections contain human-authored context (deployment specifics, security decisions, roadmap notes) that codebase scanning cannot recover. Always read before touching.
• NEVER fabricate infrastructure details — if you cannot determine the cloud provider, deployment model, or data store from the codebase, mark it <!-- TODO: fill in --> rather than guessing. Wrong infrastructure docs cause real confusion during incidents.
• NEVER paste the entire directory tree verbatim — the Project Structure section should show meaningful architectural layers, not every file. Collapse noisy directories (node_modules, dist, .git, __pycache__) and annotate each entry with its architectural role.
• NEVER skip drift detection in refresh mode — scan the codebase for changed signals before running any interview. Asking questions about unchanged sections wastes the user's time.
• NEVER leave all 11 sections as <!-- TODO --> — scan aggressively first. Most sections can be at least partially filled through inference. A document full of TODOs appears complete but misleads every reader.
• NEVER document internal implementation details in the System Diagram (Section 2) — that section is a 10,000-foot view of components and data flow. Database schemas, function signatures, and module internals belong elsewhere.
• NEVER run discovery serially when subagents are available — Phase 1 spawns parallel subagents for different discovery domains. Serial scanning wastes time on codebases with many config files spread across directories.

Before Writing, Ask

Is this root or package level?

• Are we at the repo root or inside a monorepo package? Check for pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or workspaces field in package.json. If inside a package, check whether a root-level ARCHITECTURE.md already exists.
• Root-level docs cover the whole system — all services, shared infra, top-level architecture. Package-level docs focus on that package and reference the root.