The BMAD map: modules, phases, personas, and the skill surface

Chapter 30 argued why research belongs at the head of spec-driven development and where BMAD fits among the tools. This chapter is the map. When you type bmad-prd or bmad-deep-recon, there is an organization behind that one command: a module it came from, a phase it belongs to, a persona that owns it, a configuration that shapes it, and a document it is about to write. Learn the map once here and the walkthrough in Chapter 33 reads like watching a team you already know.

Everything below was inspected against the installed v6.10 source. BMAD ships minor releases roughly monthly, so treat command names as dated claims: the ground truth is always the skill directories on your own disk, and bmad-help reads that installed set and recommends from it.

The five-layer model: what BMAD actually is

The single most useful sentence about BMAD:

BMAD is a packaged context-and-process layer. Your AI host is the runtime; project files are the durable state; installed skills are the procedures; external tools supply capabilities; reviewed artifacts are the contracts between stages.

It is not a second model, a model router, a database, a web crawler, or a daemon running a deterministic graph. It makes a capable coding/research agent behave like a disciplined cross-functional team by controlling what the agent loads, what it asks, what it writes, when it stops, and what the next agent receives. Five layers, often collapsed into the one word "agent":

┌─────────────────────────────────────────────────────────────────────┐
│ 5  Product work                                                     │
│    research.md -> brief -> PRD -> architecture -> stories -> code   │
├─────────────────────────────────────────────────────────────────────┤
│ 4  BMAD method                                                      │
│    personas · workflow instructions · steps · gates · templates     │
├─────────────────────────────────────────────────────────────────────┤
│ 3  Installed skill adapter                                          │
│    bmad-* SKILL.md files in the host's discovery directory          │
├─────────────────────────────────────────────────────────────────────┤
│ 2  AI host / runtime                                                │
│    Claude Code · Codex · Cursor · Gemini CLI · another agent host    │
├─────────────────────────────────────────────────────────────────────┤
│ 1  Capabilities                                                     │
│    filesystem · shell · Git · web · subagents · MCP · data systems  │
└─────────────────────────────────────────────────────────────────────┘

Three common surprises fall out of the separation immediately:

• Installing BMAD does not give a model new tools; it teaches the model a procedure for using tools the host already exposes. If the host has no web search, BMAD cannot browse by wishing harder.
• Running the same BMAD skill in two hosts can produce different speed, tool reach, and quality, because layers 1 and 2 changed under it.
• The documents matter more than persona continuity. Mary and Winston run in separate fresh chats because the report and the PRD carry state between them, not because a character remembers.

Modules on a core

BMAD ships a small core and the flagship BMM module (the BMad Method itself) built in; everything else is an installable module you add with --modules. The registry as of v6.10:

Two housekeeping notes the installer enforces. The older bmad-automator module is deprecated and points users to bmad-loop instead; and external modules install from their own npm packages and channels, so a reproducible install records each one's tag and SHA in _bmad/_config/manifest.yaml. The core and BMM are what the rest of this part uses; the others are proof the method is a pattern, reinstantiated per domain (the Game Dev Studio section returns to this).

The four phases

BMM organizes work as Analysis → Planning → Solutioning → Implementation. Each phase produces documents the next phase consumes; the official docs put the contract in one line: "The PRD tells the architect what constraints matter. The architecture tells the dev agent which patterns to follow."

Analysis            Planning              Solutioning            Implementation
research, brief  -> PRD, UX spines     -> architecture,       -> stories, code,
(what's true,       (what to build       epics & stories        tests, reviews,
 what to build)      and why)             (how to build it)      sprint state
   Mary               John / Sally         Winston                Amelia

Analysis is optional for a small change and load-bearing for an expensive one; the method is designed to scale down (a bugfix skips almost all of it) as well as up. That is the whole point of the readiness gate and bmad-help: they let you run only the phases the decision's stakes justify.

The six personas (policy, not another model)

Analysis, planning, solutioning, and implementation are each led by a persona with a fixed identity and a customizable layer. These are the exact identities from the installed agent skills:

Two more personas live in installed modules: Murat, TEA's Master Test Architect and Quality Advisor (risk-based P0-P3 prioritization, ATDD, CI governance, requirements traceability, across nine testing workflows); and the Game Dev Studio cast, which rebuilds the whole roster for games (Samus Shepard the Game Designer, Cloud Dragonborn the Game Architect, Link Freeman the Game Developer, Indie the solo-dev generalist, Max the Scrum Master, GLaDOS for QA, and Paige again for docs).

The persona is not decoration. Loading bmad-agent-pm does not start a separate "John" process; it loads a stable identity, role, principles, communication style, and menu into the current conversation. "John" is valuable because the same product standards are re-established without you rebuilding a PM system prompt each session. The result is continuity of behavior, not magical continuity of memory:

persona continuity = reloaded identity + rules + menu
project continuity = files on disk
conversation memory = current host context only

If John makes a decision and it exists only in chat, Winston will not reliably know it in a fresh architecture session. If the decision is in the PRD or its decision sidecar, Winston can read it. That is why BMAD's document contracts are more fundamental than its character names, and why a fresh chat per workflow is a feature: state that matters is on disk.

Don't be confused: a direct skill vs. a persona menu. Both reach the same workflow. user -> bmad-prd -> PRD workflow is direct; user -> bmad-agent-pm -> John's menu -> PRD trigger -> PRD workflow goes through the persona. Use the direct skill when the job is known; load the persona when you want an exploratory conversation across John's related jobs. In runbooks and automation, prefer the direct names: bmad-create-story says what it does, while CS depends on knowing Amelia's menu.

The command atlas

"Show every BMAD command" needs a boundary, because BMAD generates skills from the modules and IDE adapters you install: TEA adds nine testing workflows, CIS and GDS add their own, and a private module can add anything. The canonical list for your checkout is the installed skill directories. For Claude Code:

find .claude/skills -maxdepth 1 -type d -name 'bmad-*' -print | sort

Cursor and Windsurf normally use .agents/skills/; other adapters print their destination during installation. The leading slash is UI syntax, not part of the skill's ID: Claude Code shows /bmad-prd, another agent may accept bmad-prd in natural language, and the installed directory is named bmad-prd either way. The tables below are the complete core + BMM surface for the v6.10-era snapshot.

Installer and discovery commands

Core skills (available to every module)

Older review IDs such as bmad-review-adversarial-general forward to bmad-review; likewise bmad-market-research, bmad-domain-research, and bmad-technical-research forward to bmad-deep-recon. Prefer the consolidated names in new documentation.

BMM workflow skills by phase

bmad-qa-generate-e2e-tests is the lightweight built-in path; install TEA when the decision needs risk-based priorities, ATDD, traceability, NFR assessment, CI design, or formal release gates.

Agent launchers (optional)

You do not need to load a persona before a workflow skill, but launchers are useful for exploratory discussion: bmad-agent-analyst (Mary), bmad-agent-tech-writer (Paige), bmad-agent-pm (John), bmad-agent-ux-designer (Sally), bmad-agent-architect (Winston), bmad-agent-dev (Amelia). Agent-menu codes (Amelia's DS for Dev Story, John's PRD) are shortcuts scoped to an active persona, not global commands; prefer full skill names in runbooks.

For the recommendation feature of Chapter 33, the full evidence-to-code path is a subset of the above:

bmad-document-project → bmad-brainstorming → bmad-forge-idea →
bmad-deep-recon → bmad-product-brief → bmad-prd → bmad-architecture →
bmad-create-epics-and-stories → bmad-check-implementation-readiness →
bmad-sprint-planning → bmad-create-story → bmad-dev-story → bmad-code-review

Do not run every command merely because it exists: bmad-help and the readiness gate exist to make the method scale down.

What the installer writes, and where to change it

The installer performs four jobs: resolve the requested module sources, collect configuration and record installed versions, write shared configuration and resolver scripts under _bmad/, and copy/register the selected bmad-* skills into the host's discovery directory. A rough layout (exact names vary by release and host):

project/
├── _bmad/
│   ├── _config/manifest.yaml        what was installed: version/channel/SHA
│   ├── config.toml                  installer-generated team config + roster
│   ├── config.user.toml             installer-generated personal config
│   ├── custom/                      YOUR durable overrides (survive updates)
│   │   ├── config.toml              team overrides
│   │   ├── config.user.toml         personal overrides
│   │   └── bmad-deep-recon.toml     one workflow's override
│   └── scripts/                     resolvers (resolve_config.py, memlog.py, …)
├── .claude/skills/bmad-*/SKILL.md   the installed skills (Claude Code)
└── {planning_artifacts}/            research, briefs, PRD, architecture, stories

Three copies of "BMAD" get confused, and only one is yours to edit:

Treat installer-owned files as generated code. Editing _bmad/config.toml directly is not customization; it is update debt. Put behavior overrides in _bmad/custom/ and business artifacts in the output folder. The installation is deliberately inspectable: manifest.yaml, the skill directories, and git diff after an update answer almost every "what do I really have?" question.

Configuration resolution: two override stacks

Central configuration (cross-cutting paths and the agent roster) resolves in four layers, highest wins:

highest  _bmad/custom/config.user.toml   personal durable override
         _bmad/custom/config.toml        team durable override
         _bmad/config.user.toml          installer-generated personal
lowest   _bmad/config.toml               installer-generated team/base

Per-skill behavior resolves in three: the skill's shipped customize.toml at the bottom, then _bmad/custom/<skill>.toml (team), then _bmad/custom/<skill>.user.toml (personal). The resolver merges by value shape, and the rule is worth knowing because it is why overrides should be sparse:

There is deliberately no deletion operator. Copy the whole shipped customize.toml into your override and you freeze old defaults and mask future improvements; keep overrides to the handful of fields you actually changed. Chapter 32 uses this to give the research skill a recommender-specific evidence pack in about ten lines.

project-context.md is the other durable file worth naming: it holds implementation policy (temporal-split rules, profile idempotency, privacy SLOs, required evaluation guardrails), not fast-changing research claims, which belong in dated research artifacts.

State: what survives a fresh chat

BMAD uses several kinds of state, and treating them as one bucket causes most resume failures:

The strong principle is externalized state: every result that must affect a later phase becomes a file. A fresh chat then becomes a quality feature rather than a reset, because the reviewed artifacts, not the chat scrollback, are the contract between stages. Those artifacts are typed messages with schemas: research.md carries claims/citations/confidence/ staleness for the analyst and PM; the PRD carries FRs/NFRs/constraints for the architect; a story carries one implementable intent plus acceptance criteria for the developer.

The rest of the box

Four corners a research-focused tour would otherwise skip, each of which sharpens the SDD picture.

bmad-spec, the distiller. Where bmad-prd coaches a sparse idea into requirements, bmad-spec runs the opposite direction: it compresses existing intent material (a PRD, a game design doc, an RFC, a Slack thread, a meeting transcript, a research report) into SPEC.md, a five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for detail that would bloat the kernel. Together they are "the machine contract every downstream BMad skill consumes." Multiple skills can call it to update the same spec over time, and its optional story breakdown emits a stories.yaml an unattended dev loop can dispatch, which closes a loop this part cares about: a research report can flow, through distillation, all the way to autonomous implementation, with the human checkpoints concentrated where they were placed on purpose.

bmad-ux, the two-spine contract. Sally's skill produces not one UX document but two peer contracts. DESIGN.md follows the open Google Labs design.md spec (tokenized colors, typography, spacing, components in YAML frontmatter) and owns how it looks. EXPERIENCE.md owns how it works: information architecture, states, interactions, accessibility, and named-protagonist journeys, and it cross-references DESIGN.md tokens by name with {path.to.token} syntax. Both spines win on conflict with any mock or import. That is the SDD thesis applied to design: the handoff from design into engineering is a sealed file contract, not a translation layer. For our feed, how repetition feels across a session is an EXPERIENCE.md journey, not just a ranker metric.

Game Dev Studio, the portability proof. GDS rebuilds the whole method for Unity, Unreal, Godot, and Phaser, with its own persona cast (above). Two details matter beyond the novelty. The document chain keeps its shape but swaps the centerpiece: Game Brief, then a GDD (game design document, with dozens of game-type templates) as the primary design document, then architecture. And preproduction ships its own research workflows (game-flavored brainstorming, domain research with competitive and technical-trends steps) rather than reusing the core research skill: evidence that BMAD treats research standards as per-domain, the same conclusion the evidence-kinds table of Chapter 30 reached.

Version mechanics, for teams landing mid-stream. The npm package resolves latest to v6 and next to prereleases. The documented v4 story is a frozen V4 branch (critical patches only) and a migration page: the v6 installer detects a legacy .bmad-method/ folder, offers a backup-and-remove, and moves old planning artifacts into the v6 output layout. There is no supported v4/v6 coexistence; the shims that keep old skill names working are the intended bridge. Record manifest.yaml for team reproducibility, because a "stable" install resolves to the newest release at install time.

With the board laid out, the next chapter zooms all the way in on the one skill this part exists for: bmad-deep-recon, the research director, down to the folder it writes and the Python it runs. 👉