| name | architecture-design |
| description | Use whenever a change needs a system-design decision — architecture, system design, data model, module/service boundaries, interface/API contracts, scale, or an ADR. The canonical discipline for designing systems: tradeoffs made explicit, the design sized to the 15 elicited context fields, one-way doors found by a five-flag checklist (one ADR each), every component earning its place through a two-cell subtraction walk, and every "start simple" seam carrying a concrete extraction trigger. Executed as checkpointed run steps (references/phase-*.md) that write into docs/architecture/ + docs/adr/ per scribe's documentation contract. |
architecture-design — tradeoffs, engineered, never over-engineered
There is no "correct" architecture — only one that fits the elicited context, with the
tradeoffs chosen open-eyed. This skill fills the gap between the PRD (the what) and tasks
(the build). Its judgment is compiled: elicitation is a fixed card, decisions are flag rows,
the challenge is pre-written probes; the one uncompiled step — synthesis — runs on the pinned
architect agent (ADR-0001).
1. The locked discipline (seven principles, compiled forms)
- Tradeoffs over best-practices. Every ≥1-flag decision lands as an ADR with the options
considered and what was given up. A pattern's popularity is never the stated reason.
- Present first, seams for change. Build each seam's cheap-now form only; define the
boundary today; the extraction happens when the trigger fires — never before.
- One-way vs two-way doors — the five-flag checklist. Per decision, five y/n cells:
reversing needs a data migration · public contract · defines data ownership · wrong =
corrupts/loses data · many dependents before revisit. ≥1
y → decide now, ADR required,
challenged at 5 votes. 0 y → pick a default, mark reversible, write a defer row.
- Scale is elicited, never assumed. The 15 typed fields of
references/scale-elicitation-card.md are the only scale inputs; every scale-table row in
the design cites one. Neither monolith nor microservices is a default.
- Subtraction — the two-cell earn walk. Every component row carries two earn cells: a PRD
requirement anchor, and a seam # + trigger. Both empty → the component is cut. A queue,
cache, or second service "to be safe" always has both cells empty.
- Risk is flags, not feelings.
money, pii_regime, residency, sla come typed from
the card; they justify decisions the same way scale numbers do — by being cited in a row.
- The evolution path is written. Every trigger passes four countable sub-checks (digit or
named event ·
Owner: · same string in the boundaries row · same string in the ADR) and the
weak-phrase deny-list grep (design-heuristics.md §F). A trigger that fails is a defect.
2. The method — checkpointed run steps (the commands are routers)
Every command is a run in the state store (references/run-state.md); each step re-orients
from its phase file and run-state row, never from conversation memory.
| Command | Steps (phase files under references/) |
|---|
architect:design | orient (phase-0-orient.md) → elicit (phase-1-elicit.md) → synthesize (phase-2-synthesize.md, pinned agent) → challenge (phase-3-challenge.md) → write (phase-4-write.md) → report (phase-5-report.md) |
architect:refine | orient (phase-0-orient.md) → driver (phase-r1-driver.md) → evolve (phase-2-synthesize.md) → challenge (phase-3-challenge.md) → write (phase-4-write.md, supersede table) → report (phase-5-report.md) |
architect:review | scope (phase-v1-scope.md) → verdict (phase-v2-verdict.md) → report (phase-v3-report.md) — read-only, advisory |
The challenge/verdict steps spawn the design-adversary per
references/lens-dispatch.md: six lenses, one lens per invocation, 5 votes on
boundary_leak/irreversible_mistake, 3 on the rest, mechanical aggregation, evidenced
dissent vetoing any holding majority. Probes are pre-written in references/lens-probes.md.
3. The output — scribe's docs/ contract
The architect owns docs/architecture/ and appends ADRs to docs/adr/, conforming to
scribe's documentation-discipline (references/docs-layout.md, templates/adr.md) exactly.
| File | Holds |
|---|
docs/architecture/README.md | the system at a glance; PRD link; the context statement verbatim; index |
docs/architecture/boundaries.md | boundaries table + seams table (cheap-now form · boundary · trigger · ADR) + hero-flow map |
docs/architecture/data-model.md | entity ownership table + the scale table (one row per numeric context field) |
docs/architecture/interfaces.md | the contracts flagged decisions expose; the versioning/auth shape clients see |
One docs/adr/NNNN-*.md per ≥1-flag decision — Status, Date, Owner, Context (links the PRD +
the context statement), Options considered, Decision, Consequences, Trigger to revisit (the
seam's trigger string verbatim). Architecture files are system facts: they must match the
code (drift = defect), anchored path:line on brownfield, tables over prose. Knock-ons:
unknowns/defers → open-questions.md (owned); planned extractions → roadmap.md (with
trigger); shipped behavior → one STATUS.md line.
References
| File | Load when |
|---|
references/run-state.md | any router finds no run, or a phase says "checkpoint" |
references/scale-elicitation-card.md | the elicit/driver step — the fixed 15 questions |
references/seam-catalog.md | placing or extracting a seam — 10 seams × 4 fixed fields |
references/design-heuristics.md | flag checklist, earn walk, decide-vs-defer, trigger lint |
references/lens-dispatch.md | spawning/aggregating adversary ensembles |
references/lens-probes.md | inside a design-adversary invocation only |
Relationship to other plugins
scribe owns the docs/ layout (read-first, write-after, stale = defect). prd-builder
owns docs/prd/ — the input; link, never restate. taskmanager decomposes and verifies
against docs/architecture/ + docs/adr/. The adversary standard here is maestro's, compiled
to probes.
