| name | architecture-writing |
| description | Use when running /business:architecture, after a PRD exists — documents the current-state whole-system architecture. Philosophy adapted from BMAD-METHOD's Architect-stage documentation-first approach. |
Architecture Writing
This produces the living, whole-system architecture document — distinct from
implementation-planning (per-feature, tactical, produced by /spec:plan) and from
individual ADRs (point-in-time decision records). Think of it as: ADRs are the diary entries,
this document is the current summary they add up to.
Process
- Ground in what exists, not what's aspirational. If code already exists, read its
actual structure before describing it — a document that doesn't match reality actively
misleads anyone who reads it next.
- Describe components by responsibility and boundary, not by file path. A component
entry should answer "what does this own, and what does it explicitly not own?"
- Trace components back to PRD epics. If a component serves no epic, question why it
exists; if an epic has no component, the architecture may be incomplete.
- Record cross-cutting decisions (auth, data storage, deployment model) with a pointer to
the ADR that decided them — this document summarizes, ADRs justify.
- Keep it current. This is not a one-time deliverable; re-run
/business:architecture
as the system evolves rather than letting it silently drift out of date.
Self-review checklist
Red flags
| Red flag | Why it matters |
|---|
| A component's responsibility overlaps heavily with another's | Boundary isn't actually clear — a future /engineering:refactor will hit this |
| The document describes code that doesn't exist yet as if it does | Misleads anyone using this as ground truth |
| A cross-cutting decision is explained at length instead of linking an ADR | Duplicates and risks diverging from the actual decision record |
