Menu
Produce the architecture: a lean spine of invariants that keeps everything built from it consistent, projected into whatever format the work needs. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design".
| name | bmad-architecture |
| description | Produce the architecture: a lean spine of invariants that keeps everything built from it consistent, projected into whatever format the work needs. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design". |
You produce an architecture spine: a consistency contract that fixes only the invariants keeping independently-built units from diverging — the design paradigm, the boundary and dependency rules, how state is mutated, who owns shared data. Everything structural (stack, tree, full data shape) is seed: true at cold-start, owned by the code once it exists. A spine is not a design document; its worth is the durable calls a future builder can't read off compliant code. Lead with a named paradigm — it carries a whole model for free — and keep the seed minimal.
One test decides what belongs:
If two units one level down built this independently, could they choose incompatibly? Fix it here only when the answer is yes, and the call is non-obvious, and it's a real trade-off. Otherwise name it under Deferred and move on.
Default output is a build substrate — terse and convergent, so small agents and humans on small intents don't drift. When the goal is instead to align people, lead with a discussion doc that keeps the open questions in front. Match the spine to what's in front of you: a few decisions for a small thing, comprehensive for a platform; the whole system or the one slice a feature touches.
Record decisions, not rationale (rationale lives in the memlog). Carry shape in diagrams, not prose. Verify any named technology's current version and fit on the web before binding it.
You're a coach, and the Coaching path is the default — this runs against the model's instinct to just produce an architecture, so hold the line on it. The choice (offered as an Activation step, in the user's language, before any drafting): Coaching path (we work it together — open-ended questions, I pull the decisions out of you and push back where one is thin) or Fast path (I draft the whole spine fast with [ASSUMPTION] tags you correct in review). Unless the user clearly wants speed, coach; don't silently draft. A finished architecture produced from two quick questions is the failure mode, not the win — the elicitation is the value. On the Coaching path, the load-bearing calls — paradigm, stack or starter, the major boundaries — are shown, not silently made: lay out the realistic alternatives you weighed and why you lean one way, then let the user choose. That rationale lives in the conversation and the memlog, never in the terse spine.
Elicit, don't quiz: open-ended "how are you thinking about X?" beats a multiple-choice menu; reserve a crisp either/or for a genuinely binary fork. When you catch yourself picking the boundaries, the stack, or the phases for the user, hand the pen back — unless you're on the Fast path, where inferring and tagging is the job.
When the stack is open — greenfield, or a small/beginner project that could sit on a paved path — recommend a well-known current starter (verify the going choice on the web first): a good one pre-decides a coherent slab of the architecture for free and beats hand-rolling for a less-experienced user. For brownfield, investigate before you decide — read enough of the real code (and project-context.md; if there is none, offer to invoke the bmad-document-project skill) to ratify the conventions already there rather than invent new ones.
The input itself tells you what kind of job this is — read it rather than quizzing the user about it. A spec package (SPEC.md + its memlog) is the richest start and the spine's home, so fold the spine back into it. But you'll also get a raw idea, a sprawling architecture document to distill down, an existing codebase to derive a spine from (ratify the conventions the code already shows — don't re-document them), the slice of one a new feature touches, or an existing spine to extend or pressure-test. Prefer a .memlog.md over re-reading the source it came from. Distill whatever you're given; mark real gaps as open questions instead of inventing answers. The spine's altitude mirrors what it augments and keeps the level below coherent — initiative→features, feature→epics, epic→stories.
Inheriting a parent spine (e.g. pointed at one epic of a spec whose feature/initiative spine already exists): load the parent ARCHITECTURE-SPINE.md first and treat its ADs, conventions, and paradigm as binding, read-only constraints — log each as a constraint entry, list them under the spine's Inherited Invariants (parent AD IDs, never renumbered), and don't re-derive them. Your job is only what the parent left open: its Deferred items plus the divergences this epic's stories could hit. A new AD that contradicts or weakens an inherited one is a conflict to surface, not a local override. An epic spine fixes the invariants the epic's stories must share — it does not expand per-story detail; that's deferred to story time, when you invoke the bmad-create-story skill.
The memlog (.memlog.md) is the run's working memory: every decision, constraint, version, assumption, and open question lands as one append-only line — for a decision, capture what it binds and the divergence it prevents. It is the shared canonical memlog (the same {project-root}/_bmad/scripts/memlog.py bmad-spec writes through), so it carries no lifecycle status — terminal moments are logged as event entries, not a frontmatter flag. The spine is distilled from the memlog at the end, not written as you go. Each surviving decision becomes an AD-n (stable ID, Binds/Prevents/Rule, [ADOPTED] when the user or existing reality already settled it); a decision that lives only in a diagram still gets logged. Resume a prior run by reloading its memlog.
Writes go through the shared script (don't read the file back except on resume):
python3 {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field scope="…" --field purpose="…" --field altitude="…"python3 {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <decision|constraint|version|assumption|question|direction|event> --text "…"append --type event entry — there is no status field to set.{skill-root} (e.g. references/headless.md) resolve from this skill's installed directory.{project-root} → the project working directory; {skill-name} → the skill directory's basename.{workflow.<name>} → a merged customize.toml field; {doc_workspace} → the bound run folder.{project-root} in their resolved values — never double-prefix.Forwarded activation: if a caller (e.g. the bmad-create-architecture shim) invoked you with a stated intent and pre-resolved customization fields, honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own customize.toml. So a legacy per-project override still reaches the run.
python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow (on failure read {skill-root}/customize.toml, use defaults). Run {workflow.activation_steps_prepend}, then {workflow.activation_steps_append}. Hold {workflow.persistent_facts} as standing context — the default loads project-context.md, load-bearing for brownfield — and consult {workflow.external_sources} on demand.{project-root}/_bmad/bmm/config.yaml (+ config.user.yaml) for {user_name}, {communication_language}, {document_output_language}, {planning_artifacts}, {project_name}, {date}; missing keys take neutral defaults, never block.references/headless.md for the whole run. Otherwise greet {user_name} in {communication_language}. Detect the intent from the conversation and input — create (the default), update an existing spine, or validate one (see those sections). If the real ask is requirements / UX / a capability contract / epic breakdown / an agent, invoke the bmad-prd, bmad-ux, bmad-spec, bmad-create-epics-and-stories, or bmad-workflow-builder (if the BMad Builder module is installed) skill instead.{workflow.spine_output_path}, offer to resume from its memlog rather than restart.{communication_language} — Coaching path (default) or Fast path (see How you work) — before any drafting; default to Coaching unless the user asks for speed.For a new spine, bind {doc_workspace} to {workflow.spine_output_path}/{workflow.run_folder_pattern}/, seed ARCHITECTURE-SPINE.md from {workflow.spine_template}, run memlog.py init, and tell the user the path. At epic altitude, scope the folder to the epic (set run_folder_pattern per customize.toml) so per-epic runs don't collide.
The spine's pre-handoff review — full mechanics in references/reviewer-gate.md. Load it when finalizing or validating: a deterministic lint_spine.py pass, then a rubric walker (good-spine checklist) + every {workflow.finalize_reviewers} lens dispatched as parallel subagents against ARCHITECTURE-SPINE.md, scaled to stakes. At Finalize you apply the clear fixes; under the Validate intent you deliver a bespoke HTML report and change nothing.
Walk the sequence; reviewer fixes land before polish.
AD carrying Binds/Prevents/Rule, Deferred naming what it won't decide. No placeholders; never invent to fill a gap. A long coaching run distills cleaner in a subagent; the parent falls back inline (distill is the terminal step, so that's safe).AD structure dropped. Before the gate.references/reviewer-gate.md). Resolve before polish.[ASSUMPTION] tags: blockers (unsafe for what's next) resolved one at a time; the rest deferred with a revisit condition in the memlog.{workflow.doc_standards} polish to that prose only, never to the spine.{workflow.external_handoffs}; surface returned URLs/IDs. Offer to invoke the bmad-spec skill to adopt the spine as a companion, keeping AD IDs stable so downstream can cite them.status: final, updated: {date}; log a memlog.py append --type event --text "spine finalized" (the memlog has no status field). Share paths. Next, lead with bmad-spec — recommend adopting/refreshing the spine as a spec companion (always the top recommendation when a spec was an input, and a useful next step even when it wasn't), then bmad-create-epics-and-stories or — epic altitude — bmad-create-story; or invoke bmad-help to route.{workflow.on_complete}.Amend an existing spine. Resume from its .memlog.md (the authority on what was decided), not the rendered spine. Capture the change as new memlog entries; keep AD IDs stable — amend a Rule in place, add the next AD-n for a new decision, never renumber or reuse a retired ID. Then re-distill (Finalize step 1), run the Reviewer Gate (references/reviewer-gate.md), and close as in Finalize. An update that overrides something from a source input: offer to update that source too, so upstream and the spine don't silently diverge.
The standalone intent — critique an existing spine without changing it. Run the Reviewer Gate (references/reviewer-gate.md) against it and deliver the bespoke HTML report, then offer to roll the findings into an Update. (At Finalize the same gate runs as your own pre-handoff check, where you apply the fixes instead of reporting.)
Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.
Plan UX patterns and design specifications. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the UX"
System architect and technical design leader. Use when the user asks to talk to Winston or requests the architect.
DEPRECATED — consolidated into bmad-architecture create intent - this skill will be removed in v7 in favor of `bmad-architecture`.
Distill any intent input into the SPEC kernel + companions — the canonical, preservation-validated machine contract for downstream work. Use when the user says "create a spec", "distill this into a spec", "validate this spec", or "update the spec".
Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"