Architecture Doc

Generate or update a living ARCHITECTURE.md for the current codebase. It should give agents and engineers a fast, complete view of the system structure, tech stack, and deployment model.

Architecture-Doc Guardrails

• MUST NOT overwrite ARCHITECTURE.md without reading it first — existing sections may contain human-authored context such as deployment specifics, security decisions, and roadmap notes that codebase scanning cannot recover. Always read the file before you touch it.
• MUST NOT 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.
• MUST NOT 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.
• MUST NOT skip drift detection in refresh mode — scan the codebase for changed signals before you run any interview. Questions about unchanged sections waste the user's time.
• MUST NOT leave all 11 sections as <!-- TODO --> — scan aggressively first. Most sections can be filled at least partially through inference. A document full of TODOs appears complete but misleads every reader.
• MUST NOT 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.
• MUST use parallel subagents for Stage 2 discovery when subagents are available — spawn them simultaneously across discovery domains. Do not scan serially. If subagents are unavailable, use focused inline discovery instead.

Before Writing, Ask

Check these points before you start. Do them in order.