# Bmad Architecture

Work out and record the architecture decisions that keep separately built parts of a...

- Repository: https://github.com/bmad-code-org/BMAD-METHOD (54863 stars)
- Category: Design
- License: see repository
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-architecture -g -a claude-code -y`
Codex: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-architecture -g -a codex -y`
Cursor: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-architecture -g -a cursor -y`
Gemini CLI: `npx skills add bmad-code-org/BMAD-METHOD --skill bmad-architecture -g -a gemini-cli -y`

## Description

Work out and record the architecture decisions that keep separately built parts of a system consistent, in a short architecture document. Creates, updates, or validates one; works from a ticket file, with an existing codebase or architecture document beside it. Use when the user says "create the architecture", "create technical architecture", "architecture spine", or "create a solution design

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# BMad Architecture

## Overview

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, the durable calls a future builder *can't* read off compliant code. Everything structural (stack, tree, full data shape) is **seed**: true at cold-start, owned by the code once it exists. 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.

## How you work

The rest: https://github.com/bmad-code-org/BMAD-METHOD/blob/HEAD/skills/bmad-architecture/SKILL.md