| name | ad-architecture |
| description | Generate ARCHITECTURE.md at the repo root by scanning the code first, pre-filling layers/patterns/observability/deployment from observed signals, then asking only the genuine gaps. Use when the user wants to bootstrap, scaffold, generate, document, or audit ARCHITECTURE.md (system-level patterns and boundaries, paired with ADRs in doc/adr/). |
| summary | Generate or audit `ARCHITECTURE.md` at the repo root. |
<background_information>
Produces ARCHITECTURE.md at the repo root. Pairs with ADRs in doc/adr/ — architecture is the binding pattern; ADRs are individual decisions with status.
Two modes detected from filesystem state:
ARCHITECTURE.md exists at the repo root → audit (do not rewrite, output drift list only)ARCHITECTURE.md absent → bootstrap (scan first, pre-fill, ask only gaps)
</background_information>
Step 0 — from the consumer repo root, run `node .agents/skills/ad-architecture/scripts/project-signals.mjs ARCHITECTURE.md --host codex` and parse its JSON. Its `mode` selects the filesystem-state branch above; use `stacks` to focus the code scan and surface every `unreadable[]` entry as a scan gap, never as an absent path.
Step 1 — scan the code. Read in this order, taking the first that exists for each category:
- Top-level directory listing — infer the layered/hexagonal/clean structure.
- Main entry points — servers, CLI binaries, background jobs.
- Boundary code —
handlers/, controllers/, repositories/, gateways/, middleware/.
- Config and env loading.
- Observability hooks — logger setup, metrics export, tracing init.
- Deploy config —
Dockerfile, docker-compose.yml, k8s/, terraform/, .github/workflows/, Procfile, serverless.yml.
doc/adr/ is the canonical ADR ledger. Read accepted ADRs to inform pattern descriptions; do not duplicate the index inside ARCHITECTURE.md.
Build a model of: layers and boundaries, data access pattern, HTTP middleware chain, async/messaging, error and validation patterns, naming conventions, logging/metrics/tracing, deployment topology.
Step 2 — pre-fill. For every <placeholder> in the template, fill from observed signals. No fabrication. If a section has no signal, write <TODO: not yet wired> in one line.
Step 3 — show only the gaps. Print:
- (a) placeholders without a code signal;
- (b) places where the code shows two competing patterns.
One question per gap.
Step 4 — write the file. On user confirmation, write ARCHITECTURE.md at the repo root. Cut every line that does not lock a binding pattern. List any decision that should become an ADR — flag, do not write the ADR yet (use the ad-adr skill for that).
Audit-mode override: do NOT write the file. Produce a drift list. Format each line as:
[file or section]: spec says X, code says Y. Suggested resolution: change spec / change code / discuss.
If something the user says contradicts what the code shows, surface the conflict. Don't silently trust the user; don't silently trust the code.
<output_contract>
A single ARCHITECTURE.md at the repo root. Every line locks a binding pattern. ADR candidates flagged in the response, not written. In audit mode: drift list only, no file written.
ARCHITECTURE.md is a narrative document, so the Documentation Discipline rules in WORKFLOW.md §2 apply at write time:
- No emoji anywhere in the file.
- No dates, version stamps,
DRAFT markers, or changelog blocks. Architecture is the current binding pattern; lifecycle lives in ADRs and git history.
Overview is the business-context-first paragraph — what the system does and what would break without it before layers and patterns.- One scope: system-level patterns and boundaries. Per-decision rationale lives in ADRs; per-project operations live in
AGENTS.md. Link, do not copy.
- No speculation. If a layer has no observed signal, write
<TODO: not yet wired> once; do not propose patterns absent from the code.
</output_contract>
Next
/ad-spec when starting a feature whose scope spans the patterns this document records./ad-adr for any binding decision that surfaced while writing or auditing this file (one decision per ADR)./ad-drift periodically to check pattern drift between this document and the code.
