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>

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.

System-level patterns and boundaries. Pair with ADRs in doc/adr/ for individual decisions.

Overview

<one paragraph: what the system does, key external dependencies, deployment shape>

Layers & Boundaries

<the layered/hexagonal/clean structure: what lives in each layer, what crosses boundaries, what doesn't>

Patterns

• Data access: <e.g., Repository pattern; raw SQL only inside internal/db/>
• HTTP handlers: <e.g., all go through middleware in src/middleware/>
• Async/messaging: <e.g., Kafka topics owned by their producer service>
• Error handling: <e.g., domain errors in errors/; HTTP mapping at handler edge>
• Validation: <e.g., Pydantic at boundary, never inside core>

Naming Conventions

<module/file/class naming rules that aren't obvious from language defaults>

Observability

• Logs: <format, level conventions, where they ship>
• Metrics: <library, dashboards>
• Traces: <provider, sampling strategy>

Deployment Topology

<how services run in prod: containers, orchestration, scaling rules>

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