ad-architecture

<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> <instructions> 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. If this skill loaded from a different base directory (stated at the top of the skill load), substitute it — the script lives at `scripts/project-signals.mjs` inside it. 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. </instructions> <template path="ARCHITECTURE.md"> The `ARCHITECTURE.md` skeleton lives in [references/architecture-template.md](references/architecture-template.md) — fill its `<placeholders>` from the scan; omit sections with no signal. </template> <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-domain` when writing or auditing the architecture resolves project vocabulary. - `/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.