Modules, phases, personas, and the workflow map

This is the map of BMAD as a whole. If the install page got you running and the anatomy page showed you the files, this page shows you the moving parts those files configure: the modules that ship the skills, the four phases they organize into, the six named agents who run them, and the workflow map that ties phase to output. The command reference then lists every skill exhaustively.

On this page

• Modules: a small core plus opt-in add-ons
• The four phases
• The three tracks (scale-adaptive)
• The six named agents
• The workflow map
• Hands-on: drive a persona through one phase
• Under Claude Code: personas as skills and subagents

Modules: a small core plus opt-in add-ons

BMAD ships a tiny core and the flagship BMM (the BMad Method itself) bundled inside the installer; everything else is an installable module you select with --modules or the wizard. Versions below are current as of this writing; core and bmm have no independent version because they ship with the installer binary.

The add-ons prove BMAD is a pattern reinstantiated per domain, not one fixed pipeline. Game Dev Studio rebuilds the whole roster and workflow chain for games (Game Brief, then a Game Design Document, then architecture); Whiteport rebuilds it as a UX-and-design-first methodology. The extending page covers building your own with BMad Builder, and a community marketplace is on the roadmap. Most of this guide focuses on core + BMM, which is BMAD proper.

The four phases

BMM organizes work into four phases, each producing documents the next consumes. The doc chain is the point: it is "context engineering," building an agent's understanding progressively so it always knows what to build and why.

Phase 1            Phase 2              Phase 3               Phase 4
ANALYSIS       →   PLANNING         →   SOLUTIONING       →   IMPLEMENTATION
(optional)         (what & why)         (how, then what      (build it, one
explore & validate PRD, UX spines       units of work)        story at a time)
                                        architecture, stories code, tests, review
Mary / Paige       John / Sally         Winston → John        Amelia

Phase 1 is optional but load-bearing: "skipping analysis entirely means your PRD is built on assumptions instead of insight." Phase 3 matters most when several epics might be implemented by different agents, because that is where conflicting technical decisions get pre-empted (the pitfalls page returns to this). The official line: catching an alignment issue in solutioning is about 10x cheaper than discovering it during implementation.

The three tracks (scale-adaptive)

BMAD is "scale-adaptive": you run only the ceremony the work justifies. The story counts are guidance, not hard rules.

bmad-help picks a track for you from a description of the work. A bugfix is Quick Flow; a new product is the full method. This is why BMAD does not feel heavy on small work: the method scales down as deliberately as it scales up.

The six named agents

Analysis, planning, solutioning, and implementation are each led by a persona with a fixed identity and a customizable layer. These are the default BMM agents, their skill ids, and their menu triggers (short codes you type once an agent is loaded).

Two ways to start work with them:

• Direct skill: type bmad-prd and the workflow runs, no persona loaded.
• Agent menu: load bmad-agent-pm (or say "hey John"), then type a trigger like PRD. The agent interprets the code while staying in character.

Use direct skills in runbooks and automation (bmad-create-story is self-describing; CS depends on knowing Amelia's menu). Use the persona when you want an exploratory conversation across an agent's related jobs. Most triggers run a structured workflow; a few (Paige's WD, MG, VD, EC) are conversational and expect you to describe what you need.

Other modules add their own casts: Murat (TEA's Master Test Architect); the Game Dev Studio ensemble (Cloud Dragonborn the architect, Samus Shepard the designer, Link Freeman the developer, Indie the solo dev, plus Paige); the CIS coaches (Carson for brainstorming, Maya for design thinking, Victor for innovation, Sophia for storytelling, and more); and Whiteport's Norse trio (Saga, Freya, Mimir).

A persona is policy, not a second model

Loading an agent does not start a separate process. It runs an eight-step activation that reloads a fixed identity plus your customizations into the current chat:

1 resolve the agent block   merge shipped defaults <- team <- personal overrides
2 run prepend steps
3 adopt the persona          hardcoded identity + your role/style/principles
4 load persistent facts      org rules, compliance notes, file: references
5 load config                your name, languages, artifact paths
6 greet                      by name, in your language, with the agent's emoji
7 run append steps
8 dispatch or show the menu  jump straight to a workflow, or wait for a trigger

The identity (name, title, domain) is hardcoded on purpose so "hey Mary" always reaches the analyst, however heavily a team has customized her. Everything else, her principles, communication style, menu, and standing facts, is yours to shape through _bmad/custom/ (see team collaboration). This is the "three-legged stool": a skill provides capability, a named agent provides persona continuity, and customization provides your org's shaping. The result is a teammate who already knows the work, that you can reshape without forking.

The workflow map

Every workflow below runs directly (type the skill) or through an agent's menu. This is the canonical phase-to-output map for core + BMM.

Phase 1, Analysis (optional):

Phase 2, Planning:

Phase 3, Solutioning:

Phase 4, Implementation:

Quick Flow (parallel track):

Hands-on: drive a persona through one phase

Let us start Phase 2 the persona way. Load John, the PM, and dispatch one job by number. Run this in a repo where BMAD is installed:

/bmad-agent-pm

Activation runs the eight steps above (resolve, adopt, load facts, load config, greet, show menu) and lands on John's menu. Each row is one workflow: a Code you can type instead of a number, a Description, and the Action (the skill it dispatches to).

Illustrative (run it in your own repo; not machine-verified here).

📋 John, Product Manager. Planning phase. What are we building?

  #  Code  Description                          Action
  1  PRD   Create / Update / Validate a PRD     bmad-prd
  2  CE    Break the PRD into epics + stories   bmad-create-epics-and-stories
  3  IR    Check implementation readiness       bmad-check-implementation-readiness
  4  CC    Correct course after a change        bmad-correct-course

Type a number, a code (e.g. PRD), or just describe what you need.

Pick "Create PRD" by its number. The PRD skill carries three intents, so John asks which, then opens the workflow's first elicitation.

Illustrative (run it in your own repo; not machine-verified here).

> 1
Running bmad-prd. Intent?  (1) Create  (2) Update  (3) Validate
> 1
Creating prd.md. Let us frame the problem first: who is this for, and what
breaks for them today?

You are now inside the PRD workflow, and Phase 2 has begun. Two things are worth separating. Continuity is the reloaded identity plus this menu: type PRD tomorrow and "John" reaches the same skill with the same character, whatever your team customized underneath. Project state is what the run writes to disk. This one lands prd.md plus addendum.md and a .memlog.md intent log (see the workflow map above); those files, not the chat, are what Phase 3 reads next.

So a persona is a skill with a menu you dispatch by number. Same three-legged stool as before: the number picks the skill, John supplies the continuity, _bmad/custom/ supplies your shaping. The direct route, typing bmad-prd straight, reaches the identical workflow with no persona loaded (see page 5 for the full skill list).

Under Claude Code: personas as skills and subagents

This chapter's cast (the six BMM personas plus each add-on's roster) has two natural homes on Claude Code, and the choice sets what "loading John" costs.

As a skill. Drop a .claude/skills/<name>/SKILL.md (project-committed) or ~/.claude/skills/<name>/SKILL.md (personal). It runs when Claude matches its description, or when you type /<name>. The body loads just in time on that first invocation and then stays in the current context, matching BMAD's eight-step activation earlier on this page: a persona is policy folded into the running chat, not a second process. Frontmatter can pin model: and effort: for the turn.

As a subagent. Drop a .claude/agents/<name>.md with frontmatter name, description, tools, model, effort. The Agent tool spawns it in a fresh, isolated context window; only its final result returns to the main conversation, so Winston's exploration never crowds the parent window. model/effort override per subagent (Amelia on claude-opus-4-8 for dev-story, Mary on sonnet for a research pass). Manage the roster with /agents.

Progressive disclosure is why a big cast is cheap: at session start only each name and description sit in context (roughly 50 tokens each), and the full persona and its phase workflows cost nothing until something is invoked. The four phases are then just skills run in sequence, each reading the artifacts the last one wrote, which is the doc chain the next paragraph names.

The rule that makes the map cohere: each document becomes the context for the next. The PRD tells the architect what constraints matter; the architecture tells the dev agent which patterns to follow; the story file gives focused, complete context for one unit of work. Remove that structure and agents make inconsistent decisions. That is the whole thesis, and the next page gives you the full skill inventory to execute it. 👉