Skill Tracer
Skills › BMAD Method › bmad-architecture › spine-template.md

spine-template.md

78 lines · skills/bmad-architecture/assets/spine-template.md at bd70c64

Open on GitHub
1---
2name: '{name}'
3type: architecture-spine
4purpose: build-substrate # build-substrate (default) · discussion · report · deck
5altitude: feature # initiative (keeps features) · feature (keeps epics) · epic (keeps stories)
6paradigm: '{named design pattern, e.g. hexagonal, layered, pipes-and-filters, actor}'
7scope: '{what this spine governs}'
8status: draft # draft · final
9created: '{date}'
10updated: '{date}'
11binds: [] # the ticket's R ids or unit ids governed (at epic altitude, also the inherited parent AD ids)
12sources: [] # the ticket, plus any companion the spine read
13---
15# Architecture Spine — {name}
17<!-- TEMPLATE GUIDE — act on these comments, then delete them; never emit a comment in the finished spine. This is a shape, not a script: keep only the sections this spine needs and cut the rest (no empty headers). A small intent may be just paradigm + a few ADs + conventions; a platform earns more. An inherited epic spine is usually mostly Inherited Invariants + a thin Deferred. Decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams; prose only where it must. -->

Architecture Spine — {name}

<!-- TEMPLATE GUIDE — act on these comments, then delete them; never emit a comment in the finished spine. This is a shape, not a script: keep only the sections this spine needs and cut the rest (no empty headers). A small intent may be just paradigm + a few ADs + conventions; a platform earns more. An inherited epic spine is usually mostly Inherited Invariants + a thin Deferred. Decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams; prose only where it must. -->

Raw lines 1 to 18
19## Design Paradigm
21<!-- Name the pattern (a known one loads a whole model for free) and map its layers to namespaces/directories. The smallest, most durable thing here. -->

Design Paradigm

<!-- Name the pattern (a known one loads a whole model for free) and map its layers to namespaces/directories. The smallest, most durable thing here. -->

Raw lines 19 to 22
23## Inherited Invariants
25<!-- Only when this spine inherits a higher-altitude parent. The parent's ADs/conventions/paradigm that bind here, by their ORIGINAL ids — read-only, never renumbered, not re-derived. A local decision that contradicts one is a conflict to surface, not an override. Cut this section otherwise. -->
27| Inherited | From parent | Binds here |
28| --- | --- | --- |
29| {AD-id / convention} | {parent spine} | {what it constrains in this scope} |

Inherited Invariants

<!-- Only when this spine inherits a higher-altitude parent. The parent's ADs/conventions/paradigm that bind here, by their ORIGINAL ids — read-only, never renumbered, not re-derived. A local decision that contradicts one is a conflict to surface, not an override. Cut this section otherwise. -->

InheritedFrom parentBinds here
{AD-id / convention}{parent spine}{what it constrains in this scope}
Raw lines 23 to 30
31## Invariants & Rules
33<!-- The durable heart: calls a future builder can't read off compliant code. One block per decision: stable ascending id (never reused/renumbered), Binds, Prevents (the divergence), Rule (enforceable). Tag [ADOPTED] when the user or existing reality settled it. Include a dependency-direction diagram (who may depend on whom) — it IS a rule; author it as valid mermaid, never an empty graph. -->

Invariants & Rules

<!-- The durable heart: calls a future builder can't read off compliant code. One block per decision: stable ascending id (never reused/renumbered), Binds, Prevents (the divergence), Rule (enforceable). Tag [ADOPTED] when the user or existing reality settled it. Include a dependency-direction diagram (who may depend on whom) — it IS a rule; author it as valid mermaid, never an empty graph. -->

Raw lines 31 to 34
35### AD-1 — {decision}
37- **Binds:** {R ids / unit ids, areas, or `all`}
38- **Prevents:** {the divergence this stops}
39- **Rule:** {the constraint downstream must follow}

AD-1 — {decision}

  • Binds: {R ids / unit ids, areas, or all}
  • Prevents: {the divergence this stops}
  • Rule: {the constraint downstream must follow}
Raw lines 35 to 40
41## Consistency Conventions
43<!-- Defaults that bind where independent builders would drift. Cut rows that don't apply; add rows the project needs. -->
45| Concern | Convention |
46| --- | --- |
47| Naming (entities, files, interfaces, events) | |
48| Data & formats (ids, dates, error shapes, envelopes) | |
49| State & cross-cutting (mutation, errors, logging, config, auth) | |

Consistency Conventions

<!-- Defaults that bind where independent builders would drift. Cut rows that don't apply; add rows the project needs. -->

ConcernConvention
Naming (entities, files, interfaces, events)
Data & formats (ids, dates, error shapes, envelopes)
State & cross-cutting (mutation, errors, logging, config, auth)
Raw lines 41 to 50
51## Stack
53<!-- SEED — verified current at authoring; the code owns this once it exists. Name + version only; the why lives in the memlog. One row per language, framework, key dependency, platform, or chain that's pinned. -->
55| Name | Version |
56| --- | --- |
57| {language / framework / key dep / platform / chain} | {pinned version} |

Stack

<!-- SEED — verified current at authoring; the code owns this once it exists. Name + version only; the why lives in the memlog. One row per language, framework, key dependency, platform, or chain that's pinned. -->

NameVersion
{language / framework / key dep / platform / chain}{pinned version}
Raw lines 51 to 58
59## Structural Seed
61<!-- The shapes worth fixing at cold-start — not a fixed list. Include only what's non-obvious at this altitude, and use as many diagrams as convey it, each as VALID mermaid (never a placeholder or empty graph). Candidates: system/container/context view; DEPLOYMENT & ENVIRONMENTS and external provider/infra topology (cover the operational envelope here when this altitude owns it — don't let it fall through); core-entity ERD (names + relationships only; an attribute that's itself an invariant is an AD, not a diagram); a minimal source tree. The code owns the detail — this is scaffold, not a mirror to maintain. -->
63```text
64{root}/
65 {dir}/ # {what lives here}
66```

Structural Seed

<!-- The shapes worth fixing at cold-start — not a fixed list. Include only what's non-obvious at this altitude, and use as many diagrams as convey it, each as VALID mermaid (never a placeholder or empty graph). Candidates: system/container/context view; DEPLOYMENT & ENVIRONMENTS and external provider/infra topology (cover the operational envelope here when this altitude owns it — don't let it fall through); core-entity ERD (names + relationships only; an attribute that's itself an invariant is an AD, not a diagram); a minimal source tree. The code owns the detail — this is scaffold, not a mirror to maintain. -->

{root}/
  {dir}/   # {what lives here}
Raw lines 59 to 67
68## Capability → Architecture Map
70<!-- Present when a ticket drove this run. Bridges the ticket's requirements to where they live + what governs them; the consistency auditor's checklist. Cut otherwise. -->
72| Capability / Area | Lives in | Governed by |
73| --- | --- | --- |
74| {R-id / area} | {component / module} | {AD-id, convention, paradigm} |

Capability → Architecture Map

<!-- Present when a ticket drove this run. Bridges the ticket's requirements to where they live + what governs them; the consistency auditor's checklist. Cut otherwise. -->

Capability / AreaLives inGoverned by
{R-id / area}{component / module}{AD-id, convention, paradigm}
Raw lines 68 to 75
76## Deferred
78<!-- Decisions intentionally pushed down, each with the reason it can wait — including whole dimensions this altitude doesn't own yet. The half of the contract that keeps the spine lean. -->

Deferred

<!-- Decisions intentionally pushed down, each with the reason it can wait — including whole dimensions this altitude doesn't own yet. The half of the contract that keeps the spine lean. -->

Raw lines 76 to 78