225 lines
9 KiB
Markdown
225 lines
9 KiB
Markdown
# 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
|