Architecture Spine

What bmad-architecture

An intent-routed lean-spine model — Create, Update, or Validate — that fixes only the invariants a future builder can't read off compliant code, and produces ARCHITECTURE-SPINE.md as the single source of truth.

The bmad-architecture skill replaces the old fixed 11-step bmad-create-architecture flow (now a deprecated forwarding shim). Instead of marching through a fixed sequence of categories, it first detects which of three intents applies — Create a spine from scratch, Update an existing one, or Validate one without changing it — then routes into a Coaching path (open-ended elicitation, load-bearing calls shown not silently made) or a Fast path (draft the whole spine with [ASSUMPTION] tags for review).

Every decision, constraint, version, assumption, and open question is logged to an append-only .memlog.md as it's made — the run's working memory. ARCHITECTURE-SPINE.md is then distilled from that memlog: invariants first, seed kept minimal, every AD (architecture decision) carrying Binds/Prevents/Rule, and Deferred items naming what the spine deliberately does not decide. A breadth-coverage rubric plus a Reviewer Gate (deterministic lint + rubric walker + parallel subagent lenses) runs before the spine is marked final.

Skill ID

bmad-architecture — supersedes the deprecated bmad-create-architecture

Role

Architectural facilitator — coaches decisions out of the user rather than silently inventing them

Primary Output

ARCHITECTURE-SPINE.md — distilled from the memlog, not hand-edited directly

Secondary Outputs

ADRs/*.md (immutable, one file per major decision) · .memlog.md (append-only audit trail) · optional human-facing renderings

Session Resume

Detects an existing run folder under {workflow.spine_output_path} and offers to resume from its memlog instead of restarting

Activation Modes

Create new spine Update existing spine Validate spine without changing it

Why The case for structured architecture

Without a shared architectural blueprint, AI agents make independent decisions — and those decisions conflict.

When multiple AI agents implement different parts of a system without a single reference document, the same concept gets named differently across modules, API response formats diverge, error handling strategies clash, and the project structure becomes inconsistent. The first agent calls a table users; the second calls it User; the third stores user IDs as userId in one service and user_id in another.

The architecture document prevents this by establishing decisions once, collaboratively, before implementation begins. Every downstream agent reads the same document and implements within the same constraints.

Before Prerequisites & inputs

The input's shape decides the job — a SPEC.md + memlog is the richest, preferred start, but a raw idea, an existing codebase, or an existing spine to extend all route to a working session.

Required & Optional Documents

Skills & Knowledge Needed

How The 8-step architecture workflow

Steps 1–2 route the run; steps 3–6 build the spine from the memlog outward; step 7 is a hard gate; step 8 closes and hands off. ARCHITECTURE-SPINE.md is written from the memlog — never hand-patched directly.

Toolkit Techniques & frameworks used

The architecture skill draws on industry-standard frameworks — each applied at the right step to produce decisions that are defensible, traceable, and actionable.

Decision & Documentation Frameworks ADR · C4 · 12-Factor

Consistency Pattern Categories Breadth-coverage Rubric

The breadth-coverage rubric (Step 6) sweeps every area where independently-built units could diverge and requires each to be decided, deferred, or logged as an open question — never left silent. The categories below are typical structural dimensions it checks:

Validation & Quality Frameworks STRIDE · ATAM · FMEA

Coaching / Fast Path & Optional Enhancers memlog-gated, not menu-gated

Unlike the old per-step [A] / [P] / [C] menu, the gate is the memlog itself: nothing reaches ARCHITECTURE-SPINE.md until it's an append-only line in .memlog.md, written via memlog.py append. Advanced elicitation and party mode remain available as optional enhancers on either path.

Applied Toolkit Skills, frameworks & outputs

Frameworks Applied

• C4 Model (Simon Brown) — context, container, component, code diagrams
• ADR Format (Michael Nygard) — numbered, immutable architectural decision records
• STRIDE (Microsoft) — threat modeling for security decision coverage
• ATAM (SEI) — architecture tradeoff analysis and NFR validation
• FMEA — failure mode identification and risk mitigation planning
• 12-Factor App (Heroku) — deployment and configuration principles
• Reference-class forecasting — estimates grounded in comparable past projects
• Breadth-coverage Rubric — every structural dimension decided, deferred, or an open question, never silent
• Reviewer Gate — deterministic lint + rubric walker + parallel subagent lenses before status: final