iamcoolvivek007/morpheus-brain
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
morpheus-brain/research/tech-study/2026-06-10-bmad-method.md

9 KiB
Raw Blame History

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:

---
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:

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