# BMAD Method — Architecture Deep-Dive

**Date:** 2026-06-10
**Repo:** https://github.com/bmad-code-org/BMAD-METHOD
**Version:** 6.8.0

---

## What It Is

BMAD (Breakthrough Method for Agile AI Driven Development) is an open-source framework that turns AI coding assistants (Claude Code, Cursor, etc.) into a **structured team of specialized agents** that collaborate through defined workflows — from brainstorming to deployment.

**Core thesis:** Traditional AI tools do the thinking for you → average results. BMAD agents act as expert collaborators who guide you through structured processes → better thinking, better output.

---

## Architecture — How It's Built

### 1. The Skill System (Everything is a Skill)

The fundamental unit is a **SKILL.md** file. Each skill is a self-contained markdown file with YAML frontmatter that defines:

```yaml
---
name: bmad-agent-dev
description: Senior software engineer for story execution...
---
```

Skills are just **markdown instructions** that the AI reads and follows. No code execution — it's all prompt engineering. The AI *becomes* the skill by reading it.

**Why this matters:** It's incredibly simple. No plugins, no APIs, no runtime. Just structured text files that tell the AI what persona to adopt, what steps to follow, and what outputs to produce.

### 2. The Agent Roster

Agents are defined in `module.yaml` with minimal metadata:

```yaml
agents:
  - code: bmad-agent-dev
    name: Amelia
    title: Senior Software Engineer
    icon: "💻"
    description: "Test-first discipline..."
```

Each agent has a **persona** (name, personality, communication style) and a **skill** (the SKILL.md that defines their behavior). The agent's full behavior lives in `customize.toml` — a TOML file that defines:

- `role` — what they do
- `identity` — who they are
- `communication_style` — how they talk
- `principles` — what they believe
- `activation_steps_prepend/append` — setup/teardown
- `persistent_facts` — context they always carry
- `menu` — what actions they offer

**Pattern:** Separation of *identity* (who) from *workflow* (what). The same agent can have different behaviors in different contexts via TOML overrides.

### 3. The Installer (Node.js CLI)

`tools/installer/bmad-cli.js` — a Commander.js CLI that:

1. **Prompts** the user for configuration (project name, skill level, output paths)
2. **Resolves** modules from a registry (`bmad-modules.yaml`)
3. **Copies** skill files into the project at `_bmad/`
4. **Creates** directory structure for artifacts
5. **Generates** config files (`config.yaml`, `user-config.yaml`)

The installer is **declarative** — `module.yaml` defines directories to create, variables to prompt for, and agents to register. The CLI just executes the declaration.

**Key insight:** The installer doesn't install code — it installs *markdown files and config*. The "runtime" is the AI reading those files.

### 4. The Workflow Engine (It's Just Markdown)

There is no workflow engine. Workflows are **markdown instruction files** that the AI reads and follows step-by-step. Example structure:

```
src/bmm-skills/3-solutioning/bmad-create-architecture/
├── SKILL.md                    # Main entry point
├── steps/
│   ├── step-01-init.md
│   ├── step-02-context.md
│   ├── step-03-starter.md
│   ├── step-04-decisions.md
│   ├── step-05-patterns.md
│   ├── step-06-structure.md
│   ├── step-07-validation.md
│   └── step-08-complete.md
├── architecture-decision-template.md
└── data/
    ├── domain-complexity.csv
    └── project-types.csv
```

Each step is a markdown file with instructions. The AI reads the main SKILL.md, which tells it to execute steps in order. Each step can have its own logic, templates, and data files.

**Pattern:** Declarative workflow as a directory of markdown files. The AI is the interpreter.

### 5. The Config Resolution System

A Python script (`resolve_customization.py`) handles config merging:

```
customize.toml (defaults)
  → _bmad/custom/{skill}.toml (team overrides)
    → _bmad/custom/{skill}.user.toml (personal overrides)
```

Merge rules:
- Scalars override
- Tables deep-merge
- Arrays of tables keyed by `code`/`id` replace matching + append new
- Other arrays append

**Pattern:** Layered configuration with predictable merge semantics. Same pattern used for agent customization, workflow settings, and skill parameters.

### 6. The Help System (State Machine)

`bmad-help` reads a CSV catalog of all installed skills:

```
module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
```

It determines:
1. **Where you are** — by checking which output files exist
2. **What's next** — by reading `preceded-by`/`followed-by` relationships
3. **What's required** — by checking the `required` flag

**Pattern:** A lightweight state machine defined in CSV. The "state" is the presence/absence of artifact files on disk.

### 7. Party Mode (Multi-Agent Orchestration)

Party mode is the most architecturally interesting piece. It has **two strategies:**

**Strategy A: Voice the room** — The orchestrator AI plays all personas itself in one response. Fast, conversational, but limited by single-model context.

**Strategy B: Spawn subagents** — Each persona is spawned as a separate AI subagent with its own context. Slower but genuinely independent thinking.

The orchestrator decides which to use based on the situation:
- Casual discussion → voice it
- Deep analysis / independent review → spawn subagents
- User explicitly requests subagents → always spawn

**Pattern:** Graceful degradation between speed and independence. The same "party" can run in two modes depending on the stakes.

### 8. The Module System

Modules are self-contained packages with:

```
module.yaml          # Module definition (agents, config vars, directories)
skills/              # SKILL.md files for each capability
  module-help.csv    # Help catalog
  module.yaml        # Skill-level config
```

The core module (`bmm`) provides 34+ workflows across 4 phases:
1. **Analysis** — research, briefs, PRFAQs
2. **Planning** — PRDs, UX design
3. **Solutioning** — architecture, epics, stories
4. **Implementation** — dev, code review, QA, sprint management

Additional modules (Test Architect, Game Dev, Creative Suite) plug in via the same structure.

---

## Key Design Patterns

### 1. **Markdown as Code**
Everything — agents, workflows, configs, templates — is markdown or YAML/TOML. No custom DSL, no runtime. The AI is the interpreter.

### 2. **File System as State**
Workflow progress is tracked by the presence of output files. No database, no API. If the file exists, the step is done.

### 3. **Persona + Workflow Separation**
Agents have identity (persona) separate from behavior (skill). You can customize how Amelia talks without changing what Amelia does.

### 4. **Declarative over Imperative**
Modules declare what they contain. Workflows declare their steps. The AI figures out how to execute them.

### 5. **Progressive Disclosure**
Skills load context on activation — they don't carry everything in the system prompt. Each skill reads its own files when needed.

### 6. **Layered Configuration**
Base → team → user overrides. Same pattern everywhere. Predictable, composable.

---

## Why This Architecture Works

1. **Simplicity** — No runtime, no APIs, no complex infrastructure. Just files.
2. **Portability** — Works with any AI that can read markdown (Claude Code, Cursor, etc.)
3. **Customizability** — Override anything via TOML files without touching core code
4. **Composability** — Modules plug in cleanly via the same interface
5. **Transparency** — Every "decision" the framework makes is readable in a text file
6. **Version-controllable** — Everything is text → git-friendly

---

## Potential Issues

1. **Token-heavy** — Reading full SKILL.md files + step files + config for every action burns context
2. **No real state machine** — File-based progress tracking is fragile; no rollback, no transactions
3. **Single-AI bottleneck** — Even with subagents, everything flows through one orchestrator
4. **No validation at rest** — Skills are markdown; no schema validation until the AI reads them
5. **Context window limits** — Large projects with many artifacts will overflow context

---

## Relevance to Our Setup

- Could integrate with OpenClaw for structured development workflows
- The skill system is similar to OpenClaw's own skill system (SKILL.md pattern)
- Party mode concept could be adapted for multi-agent code reviews
- The workflow patterns (analysis → planning → solutioning → implementation) are directly applicable to how we build features on the VPS stack

---

## Action Items

- [ ] Consider installing BMAD for structured project development
- [ ] Evaluate if OpenClaw's skill system can interoperate with BMAD skills
- [ ] Study the `bmad-help` state machine pattern for workflow tracking
- [ ] Look at the test architect module for QA automation ideas