architecture-design

name

architecture-design

description

Use whenever a change needs a system-design decision — architecture, system design, data model, module/service boundaries, interface/API contracts, scalability/scale, or an ADR. The canonical discipline for designing systems: architecture is tradeoffs, engineered, never over-engineered. Right-size the present, place clean seams for likely futures with explicit extraction triggers, decide the irreversibles now and defer the reversible, elicit real scale/risk case-by-case, and trace every choice to the PRD. Writes its output into docs/architecture/ + docs/adr/ per scribe's documentation contract.

architecture-design — tradeoffs, engineered, never over-engineered

There is no "correct" architecture — only an architecture that fits this context, and the tradeoffs you chose with open eyes. This skill is the architect's locked discipline: it fills the gap between the PRD (the what) and tasks (the build), producing module/service boundaries, a data model, interface contracts, and the ADRs that justify them — right-sized to the present, with clean seams so the likely futures are cheap later.

Architecture is the set of decisions that are expensive to change. The job is to get the expensive ones right cheaply now, spend zero effort on the cheap (reversible) ones until the last responsible moment, and leave behind clean boundaries — seams — so the system can evolve without a rewrite.

The reference catalog of seams is references/seam-catalog.md; the operational checklists (elicitation, the irreversible-vs-reversible test, decide-now-vs-defer, the subtraction test, how to write a good trigger-to-revisit) are references/design-heuristics.md.

1. The locked discipline (seven principles)

1. Tradeoffs over best-practices. There is no universally correct architecture, only a context-fit one. "Best practice" is a starting hypothesis, never a justification. Every significant choice is a tradeoff made explicit in an ADR with the reasoning that tipped it — the options considered, what you gave up, and why it fits this context.

2. Right-size now, design seams for change (evolutionary architecture). Build the simplest thing that serves the present requirement — ZERO speculative complexity. But place clean boundaries (seams) where change is likely, so a future extraction (DB → managed/separate store, in-process jobs → worker queue, a module → its own service) is a swap, not a rewrite. The seam is the cheap hedge; the distributed implementation is the expensive thing you do not build yet. See the seam catalog.

3. Irreversible vs reversible (one-way vs two-way doors). Spend your design effort on the expensive-to-change decisions — the data model, the core boundaries, the key contracts — and get them right cheaply, now. Defer the reversible ones (which library, which queue vendor, which cache) to the last responsible moment, where you'll decide with more information. Treating a two-way door as one-way is how over-engineering starts.

4. Scale is elicited, case-by-case. Default to neither monolith nor microservices. One VPS may be exactly right; a fintech serving millions with compliance obligations may need to be born distributed. You do not know which until you elicit the real scale now, the plausible futures, the risk/compliance, and the team/ops constraints. Design to the elicited reality, not to a fashion.

5. "Simple is complex enough at scale" — subtraction discipline. Every component, layer, service, and abstraction must EARN its place by either (a) a present requirement, or (b) an irreversible-seam need. If it earns neither, remove it. A cache, a queue, a second service, a message bus added "to be safe" is over-engineering — it is complexity with no present payer.

6. Risk management. Architecture is managing risk over time: understand the present (what must work now), the future tradeoffs (where it will plausibly strain), and the cheap hedges available now (the seams). Name the risks; pick the hedges that cost almost nothing today and save a rewrite tomorrow; decline the ones that cost real complexity now for a future that may never arrive.

7. Document the evolution path. Every "start simple" decision records its extraction trigger — the concrete, observable signal that says "now extract X" (a measured latency, a row count, a team split, a compliance event). The future decision is pre-thought, not rushed: when the trigger fires, the path is already written down, so the extraction is a planned move rather than a 2 a.m. scramble.

2. The method

Run this in order. It is a focused intake, not an interrogation — a few decision-shaping questions, then design. Detailed question lists are in references/design-heuristics.md.

1. Read docs/ first. Per scribe's documentation-discipline: read docs/STATUS.md, the relevant docs/architecture/, and the open docs/adr/. For brownfield, also read the reverse-engineered baseline scribe bootstrapped (scribe:init via maestro deep-analysis) — you design within and against existing boundaries, not on a blank page.

2. Trace to the PRD. The PRD (owned by prd-builder, ingested at docs/prd/) is the input. The architecture serves the hero flow and the lean v1. Link to it; do not restate it. Nothing in the design exists that no requirement (present or seam-need) asks for.

3. Elicit context — a focused intake:

   • Scale now + plausible futures (users, data volume, request rate, growth shape).
   • Risk / compliance (money, PII, regulated domain, uptime/SLA, data residency).
   • Team / ops constraints (team size & shape, deploy/ops maturity, budget, existing stack). Use these to size the design. Default to neither monolith nor microservices until the answers point one way. (Elicitation question set: references/design-heuristics.md.)

4. Decide the irreversibles now. Identify the one-way doors (data model & ownership, core module/service boundaries, key public contracts) and decide them deliberately — these are where design effort belongs. One ADR per significant irreversible decision.

5. Right-size the present design. Build the simplest thing that serves the present requirement. Apply the subtraction test (references/design-heuristics.md): every component must EARN its place or be removed.

6. Place seams for likely futures, with explicit triggers. For each likely future extraction, define the boundary/interface now (the cheap hedge) and record the extraction trigger — but do not build the distributed version. Use references/seam-catalog.md for the cheap-now form, the boundary to define now, and the trigger for each common seam.

7. Adversarially challenge — hand to the design-adversary. Before writing the result, subject the design to an independent refute-first pass per maestro's adversarial-verify standard (refute don't affirm, fresh independent eyes, evidence over assertion, atomic claims, multi-vote). The adversary's lenses: Where does a boundary leak? At what scale does it break? What's the irreversible mistake we're about to bake in? What did we over-engineer — what component does not earn its place? Drop what gets overturned; deliver only what survives. (See references/design-heuristics.md for the challenge set.)

8. Write the result into docs/ per scribe's contract (§3 below).

3. The output — write into scribe's docs/ contract

The architect owns docs/architecture/ and writes its decisions as ADRs in docs/adr/, both per scribe's documentation-discipline skill, references/docs-layout.md, and the ADR template (templates/adr.md). Do not invent a layout — conform to scribe's.

Into docs/architecture/ (owned by the architect plugin):

File	Holds	Must include
docs/architecture/README.md	Overview / index of the architecture set	what the system is at a glance; link to PRD + baseline
docs/architecture/boundaries.md	Module / service boundaries + the seams between them	for each likely-extraction seam: its cheap-now form, the boundary defined now, and the extraction trigger
docs/architecture/data-model.md	Entities, relationships, ownership	the irreversible data decisions; what each boundary owns
docs/architecture/interfaces.md	API / interface contracts	the key contracts (one-way doors) the rest of the system depends on

Every architecture file is a system fact in scribe's typed-truth model — it must match the code (drift = defect), so anchor claims to the code (path:line or symbol) where the baseline exists, keep it lean (tables over prose), and write each seam with its seam + extraction trigger so the evolution path is documented (principle 7).

Into docs/adr/NNNN-*.md — one ADR per significant decision, using scribe's template exactly: context, options considered, decision, consequences, owner, date, status, and trigger-to-revisit. The trigger-to-revisit is non-negotiable — it is where the extraction trigger / scale threshold lives, giving the decision a defined expiry instead of silent staleness. Write a good one per references/design-heuristics.md.

Obligation contract (scribe §4): changing a boundary/data-model/interface updates docs/architecture/ and records an ADR; a choice that ships behavior also touches STATUS.md (scribe's domain). Deferred-but-undecided design questions go to open-questions.md with an owner; planned-not-yet-built extractions go to roadmap.md with their trigger. Brownfield: the architecture must trace to the reverse-engineered baseline, and any place the design departs from the existing system is itself a decision → an ADR.

Relationship to other processes

• scribe owns the docs/ contract; the architect writes docs/architecture/ + docs/adr/ through it and never invents its own layout. Read-first, write-after, stale = defect.
• prd-builder owns docs/prd/ — the architect's input; trace to it, never restate it.
• maestro is the canonical home of adversarial verification; the design-adversary pass (method step 7) embodies maestro's adversarial-verify standard. maestro is untouched.
• taskmanager decomposes and verifies against docs/architecture/ + docs/adr/ (design conformance), so the contracts written here become the spec downstream.

The mantra

Architecture is tradeoffs, engineered, never over-engineered: build the simplest thing that serves the present, get the irreversible decisions right cheaply now, place clean seams with explicit extraction triggers for the likely futures — and write down the evolution path so the next decision is pre-thought, not rushed.