/architecture

Own the decision, not the code

architecture owns the Shape stage — the consequential, hard-to-reverse decisions between product (what to build and why) and the build skills (the production code): service boundaries, public API shape, data-store and consistency choice, the auth model, SLO targets. It hands those decisions down as a contract, a budget, a threat model, and a durable record — and recommends the build skills by name rather than silently doing their work.

Own the shape, not the implementation behind it. When compatible upstream artifacts are supplied — a PRD, a product handoff, an existing ADR log — architecture uses them without silently overriding decisions already made.

The faceted router

SKILL.md is a router, not a script. Requirements are gated first; then every request selects the smallest sufficient route: one primary job — the eight below — combined with at most one surface overlay that reshapes boundaries, contracts, and budgets for the system type. Read the selected references completely; load two or three at most, never the whole pack. Eight jobs and five surfaces compose into 8 × 5 = 40 routes — from a single-ADR two-file read to a full architecture pass — without ever reading all fourteen references at once.

The eight primary jobs

Each job is one reference, read fully only when its route is selected — grounded in named canon, producing a checkable artifact. This is the whole surface, not a headline slice.

Full router table & invariants: SKILL.md.

Five surface overlays

One overlay, at most, reshapes the job for the system type — the same contract job is bounded differently for a multi-tenant SaaS than for a data platform. Agentic is the first-class differentiator, expanded below.

The agentic flagship

Generic system design is well-covered; agentic-system architecture is the open frontier. When a model acts under uncertainty, the architecture questions change: reliability is empirical, the topology is a decision, context is a finite budget, and the eval set is what gates release. The reference carries the 2026 primary material — thin-model / thick-harness, multi-agent economics, agent memory tiers, agent security — that the textbooks don't yet.

# the model is thin; the harness is where the reliability lives
topology:   workflow       # workflow | single-agent | multi-agent
context:    finite budget  # compaction + JIT retrieval, not a dump
memory:     [episodic, semantic, procedural]
retrieval:  RAG + reranker # topology is an architecture choice
eval_gate:  40-case set   # blocks release on regression
hitl:       approve on irreversible action
security:   [prompt-injection, tool-scope, exfil]

The universal invariants

Six rules govern every route, whichever references it loads — the behavioral spine, condensed.

• Requirements-gate before solutioningNo design until functional requirements and NFRs are captured and every contradiction is surfaced and resolved. Ask one question at a time; mark unknowns TBD; never invent a number the requester hasn't approved.
• Don't over-architectDefault to a modular monolith and the lightest sufficient artifact. Add a service split, event sourcing, or a platform team only when a named disintegrator justifies it — applying mature-stage architecture to an MVP is the failure mode.
• Weight analysis by reversibilityTreat each decision as a one-way door (data store, public API, org boundary) or a two-way door. One-way doors earn deep analysis and an ADR; two-way doors earn a quick call. Name options and "would choose X if {trigger}."
• A pick, a "don't build," a trade-offEvery recommendation is a concrete choice, an explicit statement of what not to build, and a stated trade-off. Cap each pass at 3–5 decisions — more reads as a document dump, not a decision set.
• Exhaustive checklists are tablesAny "cover N items" task — Well-Architected pillars, STRIDE per element, the API checklist — is a uniform table with a self-audit count, never a narrative. A narrative pass reliably drops rows and stops citing findings before full coverage.
• Distinguish facts, decisions, assumptions & proposalsPreserve upstream decisions and user constraints, or flag the conflict explicitly; prefer repository and artifact evidence over generic defaults; and name the border — recommend the sibling skills, never silently do their work.

What a pass produces

Architecture's deliverables are decisions made durable. A full pass emits up to five downstream artifacts — plus the DDD canvases and arc42 skeleton where the job calls for them. Each records the decision and options, the trade-off accepted, facts/decisions/assumptions distinguished, and the reversibility lens on any hard-to-reverse call. Fillable templates ship in the pack.

The handoff seam

When downstream build work is expected, architecture emits a compact handoff.yaml beside the human artifacts — a routing index into the solution doc, contracts, budgets, ADRs, and threat model, never a copy of them. Standalone by default; the companion appears only in pipeline mode, when a consumer will actually read it.

skill: architecture
status: complete
objective: ""   # only required field
artifacts_created: [contracts,
  nfr-budgets, adrs, threat-model]
decisions: · assumptions: · constraints:
risks: [R-01, R-04]  # pointers, by id
validation: performed / remaining
recommended_next: frontend · backend
  · data · ai · quality

Seam discipline. The human artifacts are the real deliverables; if a consumer needs more than the index gives, the artifact itself is incomplete — the yaml never grows to compensate. Every downstream skill tolerates every field but objective being absent.

Start here

Install once. It's a plain SKILL.md router — no flags, no config, no scripts — so it activates on natural-language phrasing ("design the system", "should this be a microservice", "write an ADR", "threat-model this") rather than a fixed command.

The same install runs on any Agent Skills host. Codex installs to ${CODEX_HOME:-$HOME/.codex}/skills and triggers with $architecture; agents remains a separate cross-agent installation target.