25 - BMAD
Build More Architect Dreams
(Business Methods and Development)
Build software faster using AI-powered workflows with specialized agents that guide you through planning, architecture, and implementation.
Helps you build software through the whole process from ideation and planning all the way through agentic implementation. It provides specialized AI agents, guided workflows, and intelligent planning that adapts to your project’s complexity, whether you’re fixing a bug or building an enterprise platform.
Install (in the project directory)
npx bmad-method install
All the command are to be used inside your agentic ide.
Main command and fallback when things get confusing: bmad-help
For example: bmad-help I want to create simple web based tic-tac-toe game. game state saved to localstorage. two player mode and single player mode with minimax and alpha-beta-pruning.
Answer:
Option A: Quick Dev (Recommended for this scope)
For a well-scoped project like this, the fastest path is:
Quick Dev — bmad-bmm-quick-dev
Unified intent-in code-out workflow: clarify, plan, implement, review, and present. Handles everything in one session.
This is ideal because your requirements are already clear:
Web-based tic-tac-toe
localStorage for game state
Two-player mode
Single-player with minimax + alpha-beta pruning
Option B: Full BMM Workflow (Structured planning)
If you want thorough documentation and a more structured approach, follow the full pipeline. Start with the optional analysis phase, then proceed through the required steps:
Phase Workflow Command Required
1-analysis Brainstorm Project bmad-brainstorming No
1-analysis Create Brief bmad-bmm-product-brief No
2-planning Create PRD bmad-bmm-create-prd Yes
2-planning Create UX bmad-bmm-create-ux-design No
3-solutioning Create Architecture bmad-bmm-create-architecture Yes
3-solutioning Create Epics & Stories bmad-bmm-create-epics-and-stories Yes
3-solutioning Check Implementation Readiness bmad-bmm-check-implementation-readiness Yes
4-implementation Sprint Planning bmad-bmm-sprint-planning Yes
4-implementation Create Story → Dev Story → Code Review cycle bmad-bmm-create-story / bmad-bmm-dev-story / bmad-bmm-code-review Yes
Recommendation
For a tic-tac-toe game, Option A (bmad-bmm-quick-dev) is the best fit — it will spec and build it in one go. Run it in a fresh context window.
Which path would you like to take?
Next prompt
bmad-bmm-quick-dev
Web-based tic-tac-toe
localStorage for game state
Two-player mode
Single-player with minimax + alpha-beta pruning
Produces spec-wip.md with full plan, asks confirmation, updates plas as needed, starts to implement.
Creates spec:
<frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
## Intent
**Problem:** No tic-tac-toe game exists in this project. The user wants a simple, self-contained web game with two play modes and persistent state.
**Approach:** Build a single-page TypeScript tic-tac-toe game with a mode selector (two-player or vs AI), a 3x3 interactive grid, win/draw detection, and minimax with alpha-beta pruning for the AI opponent. Persist game state to localStorage so refreshing the page resumes the game. Use `tsc` to compile TypeScript to JS.
## Boundaries & Constraints
**Always:**
- TypeScript for all game logic, compiled via `tsc`
- HTML + CSS for markup and styling — no UI frameworks
- AI uses minimax with alpha-beta pruning (not random or heuristic)
- Game state (board, mode, current turn, scores) saved to localStorage on every move
- Page reload restores the exact game state
**Ask First:**
- Adding difficulty levels (easy/medium/hard)
- Adding online multiplayer or any backend
**Never:**
- No UI frameworks (React, Vue, etc.)
- No server-side code
- No external API calls
## I/O & Edge-Case Matrix
| Scenario | Input / State | Expected Output / Behavior | Error Handling |
|----------|--------------|---------------------------|----------------|
| Two-player win | Player X completes a row/col/diagonal | Highlight winning line, display "X wins!", disable board | N/A |
| AI move | Human plays in single-player mode | AI responds immediately with optimal move via minimax | N/A |
| Draw | All 9 cells filled, no winner | Display "It's a draw!" | N/A |
| Page reload mid-game | Refresh browser during active game | Board, mode, turn, and scores restored from localStorage | If localStorage is corrupt/empty, start fresh |
| New game | Click "New Game" button | Clear board, keep mode and scores, save state | N/A |
| Mode switch | Change mode selector | Reset board and start new game in selected mode | N/A |
| Click occupied cell | Click a cell that already has X or O | No change — move is ignored | N/A |
| Click after game over | Click a cell after win/draw | No change — board is disabled until new game | N/A |
</frozen-after-approval>
## Code Map
- `index.html` -- Game page: loads compiled JS, contains mode selector, 3x3 grid, status display, score board, new game button
- `css/styles.css` -- Game styling: grid layout, animations, responsive design
- `src/ai.ts` -- Minimax with alpha-beta pruning: AI move computation for single-player mode
- `src/game.ts` -- Core game logic: board state, move handling, win/draw detection, localStorage, UI updates
- `tsconfig.json` -- TypeScript compiler config: strict mode, ES modules, output to `dist/`
- `package.json` -- Project metadata and build script (`tsc`)
## Tasks & Acceptance
**Execution:**
- [x] `package.json` -- Initialize with project name and `build` script that runs `tsc`
- [x] `tsconfig.json` -- Configure strict mode, target ES2020, module ES2020, outDir `dist/`, rootDir `src/`
- [x] `index.html` -- Create game page with mode selector (two-player / vs AI), 3x3 grid of clickable cells, status message area, scoreboard (X wins / O wins / draws), and New Game button. Load compiled JS from `dist/` as ES modules
- [x] `css/styles.css` -- Style the game: centered layout, grid with visible borders, hover effects, X/O markers, winning line highlight, responsive for mobile
- [x] `src/ai.ts` -- Implement minimax with alpha-beta pruning: evaluate terminal states (+10 win, -10 loss, 0 draw), recurse with alpha-beta bounds, export function returning optimal move index
- [x] `src/game.ts` -- Implement game controller: initialize board array, handle cell clicks, check win (8 lines) and draw, toggle turns, trigger AI in single-player mode, update DOM, save/load full state to localStorage, handle new game and mode switching
**Acceptance Criteria:**
- Given two-player mode, when players alternate clicking empty cells, then X and O markers appear and turns alternate correctly
- Given single-player mode, when the human plays a move, then the AI responds with an optimal move using minimax with alpha-beta pruning
- Given a winning position, when the last winning move is played, then the winning line is highlighted and the winner is announced
- Given a completed game, when "New Game" is clicked, then the board clears but scores persist
- Given an active game, when the page is refreshed, then the exact board state, mode, turn, and scores are restored
- Given localStorage is empty or corrupt, when the page loads, then a fresh game starts with default settings
- Given `npm run build`, when executed, then TypeScript compiles with no errors
## Design Notes
The minimax implementation should use alpha-beta pruning for efficiency, though on a 3x3 board the pruning is more for correctness of the requirement than performance necessity. The AI plays as O in single-player mode. Depth is used as a tiebreaker so the AI prefers faster wins and slower losses.
## Verification
**Commands:**
- `npm run build` -- expected: TypeScript compiles with zero errors
**Manual checks:**
- Open `index.html` in a browser — game renders with mode selector, grid, and controls
- Play a full two-player game — turns alternate, winner detected, score updates
- Play vs AI — AI never loses (minimax is optimal), AI responds immediately
- Refresh mid-game — state fully restored
- Fill all cells with no winner — draw detected
- Switch modes — board resets, new game starts
Implements, launches 3 code review agents (Blind hunter adversarial review, Edge case hunter review, Acceptance auditor review)
Review Classification
All three reviews in. Deduplicating and classifying:
# Finding Classification
1 AI move synchronous — human move not visible before AI responds patch
2 Board cell values not validated on localStorage load patch
3 Score values can be NaN/Infinity from corrupted localStorage patch
4 localStorage.setItem can throw (quota/privacy) patch
5 gameOver not re-derived from board on load patch
6 getOpponent(null) returns 'X' reject (unreachable)
7 findBestMove mutates board in-place reject (standard minimax, sync safe)
8 Non-null assertions on DOM reject (co-located fixed HTML)
9 Mode change doesn't reset scores reject (intentional per spec)
10 data-index parsed without validation reject (fixed HTML)
11 checkWinner not discriminated union reject (not a runtime bug)
No intent_gap or bad_spec findings. 5 patches to auto-fix. Applying now.
BMAD Method — Spec-Driven Agentic Development
What is BMAD?
Build More Architect Dreams — an open-source, AI-driven development framework that structures the entire software lifecycle using specialized AI agents and guided workflows.
Repository: https://github.com/bmad-code-org/BMAD-METHOD Docs: https://docs.bmad-method.org
BMAD is not a library or SDK. It is a set of agent definitions, workflow scripts, and document templates that you install into your project and invoke through an AI coding assistant (Claude Code, Cursor, Codex CLI). The agents are system prompts with personas, menus, and memory — not autonomous processes.
The Core Problem BMAD Solves
When you use a single AI chat for an entire project, you hit three problems:
- Context window exhaustion — one conversation accumulates too much irrelevant context, quality degrades
- Role confusion — the same AI instance tries to be PM, architect, and developer simultaneously, doing all of them poorly
- No structured handoffs — decisions made early in the conversation get lost or contradicted later
BMAD's answer: agent specialization + workflow isolation + document-driven handoffs.
Architecture: Agents, Workflows, Artifacts
Agents
Each agent is a system prompt defining:
| Component | Purpose |
|---|---|
| Persona | Role, identity, communication style, principles |
| Memories | Persistent project-specific context |
| Menu | Available actions and workflows |
| Critical actions | Startup instructions |
Available agents in the BMad Method module:
- Analyst — brainstorming, research
- PM — PRD creation, epic/story breakdown
- Architect — technical architecture, implementation readiness
- UX Designer — user experience design
- Scrum Master (SM) — sprint planning, story creation, retrospectives
- Dev — story implementation, code review
- BMad Master — orchestrator for party mode (multi-agent conversations)
Agents are customizable via .customize.yaml files — change name, persona, add memories, add menu items. Customizations survive installer updates.
Workflows
A workflow is a structured task that an agent executes. Invoked by name:
bmad-create-prd
bmad-create-architecture
bmad-dev-story
Critical rule: one fresh chat per workflow. This prevents context bleed between phases. The previous workflow's output is a document on disk, not conversation history.
Artifacts
Agents communicate through files, not through shared conversation context:
_bmad-output/
├── planning-artifacts/
│ ├── PRD.md # Requirements
│ ├── architecture.md # Technical decisions
│ └── epics/ # Epic and story files
├── implementation-artifacts/
│ └── sprint-status.yaml # Sprint tracking
└── project-context.md # Conventions for all agents
Each workflow reads the artifacts it needs and writes the artifacts the next workflow expects.
The Four Phases
Phase 1: Analysis (Optional)
Brainstorming, market/domain/technical research, product brief.
Workflows: bmad-brainstorming, bmad-market-research, bmad-domain-research, bmad-technical-research, bmad-create-product-brief
Phase 2: Planning (Required)
Create the Product Requirements Document.
Workflow: bmad-create-prd → outputs PRD.md
The PM agent drives this — asks questions, structures requirements, validates completeness.
Phase 3: Solutioning
Architecture decisions, then epic/story breakdown informed by those decisions.
Workflows:
bmad-create-architecture(Architect) → outputsarchitecture.mdbmad-create-epics-and-stories(PM) → reads both PRD and architecturebmad-check-implementation-readiness(Architect) → validates cohesion across all docs
V6 improvement: stories are created after architecture, so technical decisions (DB, API patterns, stack) directly affect story breakdown.
Phase 4: Implementation
Story-by-story build cycle:
| Step | Agent | Workflow | Purpose |
|---|---|---|---|
| 1 | SM | bmad-create-story | Create story file from epic |
| 2 | Dev | bmad-dev-story | Implement the story |
| 3 | Dev | bmad-code-review | Adversarial review |
Repeat per story. Retrospective per epic.
Three Complexity Tracks
| Track | Scope | What You Skip |
|---|---|---|
| Quick Flow | Bug fixes, small features, <15 stories | Everything — single workflow bmad-quick-dev handles plan + implement + review |
| BMad Method | Products, platforms, 10-50+ stories | Nothing skipped, full four phases |
| Enterprise | Compliance, multi-tenant, 30+ stories | Adds security and DevOps documentation |
Key Concepts for Agentic Development
1. Agent Specialization vs. Monolithic Prompting
A PM agent doesn't know how to write code. A Dev agent doesn't write requirements. Each agent loads only the context it needs, which means:
- Better quality output per task
- Smaller, more focused context windows
- Clear accountability per artifact
2. Workflow Isolation (Fresh Chat Per Task)
Why not reuse the same chat? Because after 50 messages of PRD discussion, your architecture conversation starts with 50 messages of irrelevant context consuming your window. Fresh chat = clean context = better output.
The cost: you lose conversational continuity. The solution: artifacts on disk carry state between workflows.
3. Document-Driven Handoffs
Agents don't share memory or conversation history. They share files:
PM writes PRD.md → Architect reads PRD.md, writes architecture.md
→ PM reads both, writes epics/ → Dev reads story file, writes code
This is the same principle as microservice contracts — agents are decoupled, documents are the API.
4. Adversarial Review
Standard AI reviews suffer from confirmation bias — "looks good, approved." BMAD's adversarial review forces the reviewer to find problems. Zero findings triggers a halt.
Why this matters: AI will rubber-stamp its own work unless explicitly instructed otherwise. The "must find issues" mandate forces genuine analysis.
Expect false positives. Human judgment filters what's real.
5. Advanced Elicitation
After generating an artifact, apply a named reasoning method as a second pass:
- Pre-mortem analysis — assume the project already failed, work backward
- First principles — strip assumptions, rebuild from ground truth
- Red team / blue team — attack your own work, then defend it
- Inversion — ask how to guarantee failure, then avoid those things
This is more effective than "make it better" because a named method forces a specific angle of attack.
6. Project Context Propagation
project-context.md contains tech stack, conventions, and rules that all agents load. Without it, agents make inconsistent decisions across stories (one uses callbacks, another uses async/await; one uses REST, another uses GraphQL).
Installation and Usage
# Install into any project
npx bmad-method install
# Select modules, AI tools, follow prompts
# Result: _bmad/ and _bmad-output/ directories
# Start working — bmad-help guides you
bmad-help
# Or invoke workflows directly
bmad-create-prd
bmad-create-architecture
bmad-dev-story
Works with Claude Code, Cursor, Codex CLI — anything that supports custom system prompts or project-level skills.
Comparison Points
When evaluating BMAD against other spec-driven frameworks (Spec-Kit, OpenSpec, SPARC, AWS Kiro, Agent OS, Pre.dev):
| Dimension | What to compare |
|---|---|
| Agent model | Named agents with personas vs. generic "AI assistant" vs. no agent concept |
| Workflow structure | Rigid phase ordering vs. flexible vs. single-pass |
| Context management | Fresh chat isolation vs. long-running context vs. RAG-based retrieval |
| Artifact format | Markdown files vs. structured YAML/JSON vs. proprietary format |
| Review gates | Adversarial review vs. optional review vs. none |
| Customization | Agent personas, menus, memories vs. prompt templates vs. fixed |
| Tool coupling | IDE-agnostic vs. locked to specific tool |
| Complexity scaling | Multiple tracks vs. one-size-fits-all |
Summary
BMAD demonstrates a mature pattern for agentic software development:
- Decompose the development lifecycle into specialized agent roles
- Isolate each workflow in a fresh context window
- Communicate between agents via versioned artifacts on disk
- Gate transitions with adversarial review
- Propagate project conventions through shared context documents
- Scale complexity through track selection (Quick Flow → Method → Enterprise)
These are not BMAD-specific ideas — they are general principles for any multi-agent development system. BMAD is one opinionated implementation of them.
BMAD Standard Workflow Guide
Overview
BMAD (Business Methods and Development) is a structured AI-assisted workflow framework that guides teams from product discovery through implementation. It maps closely to real Scrum ceremonies and artifacts, providing AI agents for each role in the process.
Folder Structure
| Folder | Purpose |
|---|---|
_bmad/ | Framework core — contains agent definitions, workflow specs, tasks, and configuration. Do not modify manually. |
_bmad/_config/ | BMAD catalog (bmad-help.csv) and global settings. |
_bmad/_memory/ | Agent memory files — agents store learned standards and preferences here across sessions. |
_bmad/bmm/ | BMM module — all business/product workflows (PRD, architecture, stories, implementation). |
_bmad/core/ | Core utilities — brainstorming, help, indexing, review, and other cross-cutting tools. |
_bmad-output/planning-artifacts/ | Output: All planning-phase documents (PRD, architecture, epics/stories, UX design, research). |
_bmad-output/implementation-artifacts/ | Output: All implementation-phase artifacts (sprint plan, story files, retrospectives). |
_bmad-output/ | General output folder for miscellaneous outputs (project context, etc.). |
docs/ | Project knowledge base — documentation files that AI agents read for context (architecture references, tech stack, onboarding guides). |
BMAD Standard Flow
The full flow consists of four sequential phases. Required steps must be completed before advancing to the next phase.
Phase 1 — Analysis
Scrum Equivalent: Pre-Sprint / Product Discovery
Establish context and understand the problem space before writing any requirements.
| Step | Command | Required | Output | Output Folder | Scrum Equivalent |
|---|---|---|---|---|---|
| Brainstorm Project | /bmad-brainstorming | No | Brainstorming session doc | _bmad-output/planning-artifacts/ | Pre-sprint ideation / product discovery workshop |
| Market Research | /bmad-bmm-market-research | No | Research documents | _bmad-output/planning-artifacts/ | Competitor analysis in discovery sprint |
| Domain Research | /bmad-bmm-domain-research | No | Research documents | _bmad-output/planning-artifacts/ | Domain knowledge deep-dive before backlog refinement |
| Technical Research | /bmad-bmm-technical-research | No | Research documents | _bmad-output/planning-artifacts/ | Technical spike / feasibility study |
| Create Product Brief | /bmad-bmm-create-product-brief | No | Product brief | _bmad-output/planning-artifacts/ | Product vision statement / elevator pitch doc |
All Phase 1 steps are optional. They feed context into the PRD in Phase 2.
Phase 2 — Planning
Scrum Equivalent: Product Backlog Creation & Refinement
Define what to build. The PRD is the central required artifact.
| Step | Command | Required | Output | Output Folder | Scrum Equivalent |
|---|---|---|---|---|---|
| Create PRD | /bmad-bmm-create-prd | Yes | Product Requirements Document | _bmad-output/planning-artifacts/ | Product Owner writing the product backlog / vision doc |
| Validate PRD | /bmad-bmm-validate-prd | No | PRD validation report | _bmad-output/planning-artifacts/ | Peer review / Definition of Ready check on backlog |
| Edit PRD | /bmad-bmm-edit-prd | No | Updated PRD | _bmad-output/planning-artifacts/ | Backlog refinement session — incorporating stakeholder feedback |
| Create UX Design | /bmad-bmm-create-ux-design | No | UX design specification | _bmad-output/planning-artifacts/ | UX/UI design sprint or prototype review |
Note: Create PRD is the only required step in this phase. Validate and Edit PRD are recommended for quality but not blocking.
Phase 3 — Solutioning
Scrum Equivalent: Sprint 0 / Technical Refinement
Define how to build it. Architecture and story decomposition must be complete before implementation begins.
| Step | Command | Required | Output | Output Folder | Scrum Equivalent |
|---|---|---|---|---|---|
| Create Architecture | /bmad-bmm-create-architecture | Yes | Architecture document | _bmad-output/planning-artifacts/ | Architecture design review / technical kick-off meeting |
| Create Epics & Stories | /bmad-bmm-create-epics-and-stories | Yes | Epics and stories list | _bmad-output/planning-artifacts/ | Backlog decomposition — breaking epics into user stories |
| Check Implementation Readiness | /bmad-bmm-check-implementation-readiness | Yes | Readiness report | _bmad-output/planning-artifacts/ | Definition of Ready check across PRD + UX + Architecture + Stories |
All three steps are required. The readiness check validates alignment across all prior artifacts before development starts.
Phase 4 — Implementation
Scrum Equivalent: Sprint Execution
Build and ship. Stories are worked one at a time through a defined cycle.
| Step | Command | Required | Output | Output Folder | Scrum Equivalent |
|---|---|---|---|---|---|
| Sprint Planning | /bmad-bmm-sprint-planning | Yes | Sprint status / plan | _bmad-output/implementation-artifacts/ | Sprint Planning ceremony — selecting stories and creating the sprint plan |
| Sprint Status | /bmad-bmm-sprint-status | No | Status summary | (inline) | Daily Standup / sprint burndown review |
| Create Story | /bmad-bmm-create-story | Yes | Enriched story file | _bmad-output/implementation-artifacts/ | Story kick-off — Scrum Master prepares story context for dev |
| Validate Story | /bmad-bmm-create-story (Validate Mode) | No | Story validation report | _bmad-output/implementation-artifacts/ | Pre-development story review / Three Amigos |
| Dev Story | /bmad-bmm-dev-story | Yes | Implemented code + tests | (codebase) | Sprint execution — developer implements the story |
| QA Automation Test | /bmad-bmm-qa-automate | No | Automated test suite | _bmad-output/implementation-artifacts/ | QA review / automated test coverage after implementation |
| Code Review | /bmad-bmm-code-review | No | Code review report | (inline) | Pull request code review |
| Retrospective | /bmad-bmm-retrospective | No | Retrospective doc | _bmad-output/implementation-artifacts/ | Sprint Retrospective at end of epic |
Story Cycle (per story):
Create Story → Validate Story → Dev Story → Code Review
↑ |
└── (if issues found, back to Dev Story) ───┘
|
(next story) → Create Story
(epic done) → Retrospective
Anytime Tools
These tools can be used at any phase, independent of workflow state.
| Tool | Command | Purpose |
|---|---|---|
| Quick Spec | /bmad-bmm-quick-spec | Lightweight spec for small/simple tasks without full planning |
| Quick Dev | /bmad-bmm-quick-dev | Implement small tasks directly without full process |
| Correct Course | /bmad-bmm-correct-course | Handle significant mid-sprint changes or pivots |
| Document Project | /bmad-bmm-document-project | Generate docs for an existing (brownfield) codebase → docs/ |
| Generate Project Context | /bmad-bmm-generate-project-context | Produce project-context.md for AI agent grounding → _bmad-output/ |
| Write Document | Load /bmad:DITA:agent:tech-writer, ask "WD" | Write any document following documentation standards → docs/ |
| BMAD Help | /bmad-help | Get guidance on what to do next at any point |
| Brainstorming | /bmad-brainstorming | Ideation session using creative techniques |
Summary: Output Locations
| Phase | Outputs Go To |
|---|---|
| Analysis | _bmad-output/planning-artifacts/ |
| Planning | _bmad-output/planning-artifacts/ |
| Solutioning | _bmad-output/planning-artifacts/ |
| Implementation | _bmad-output/implementation-artifacts/ |
| Project Knowledge / Docs | docs/ |
| General Output | _bmad-output/ |
Key Principles
- Run each workflow in a fresh context window — do not chain multiple workflows in the same conversation.
- Required steps block progress — you cannot skip Create PRD, Create Architecture, Create Epics & Stories, Check Implementation Readiness, Sprint Planning, Create Story, or Dev Story.
- Artifacts drive state — BMAD determines workflow state by looking for output files, not by tracking session history.
- Use a different LLM for validation steps — Validate PRD, Validate Story, and Check Implementation Readiness benefit from a separate high-quality model to avoid self-confirmation bias.
This content is summarized by /bmad-help, the agent that helps us with anything about BMAD. You can also ask it for more details about BMAD usage.
BMAD Agents
BMAD uses a team of specialized agents, each representing a distinct role in the software development lifecycle. Every agent has a unique persona, focused capabilities, and a set of workflows they execute. Load an agent by running its slash command in a fresh context window.
Part 1 — 📊 Mary, Business Analyst
Command: /bmad-agent-bmm-analyst
Code: analyst
Title: Business Analyst
Who She Is
Mary is a strategic business analyst with deep expertise in market research, competitive analysis, and requirements elicitation. She approaches every problem like a treasure hunter — thrilled by clues, energized when patterns emerge. She draws on Porter's Five Forces, SWOT analysis, root cause analysis, and competitive intelligence methodologies.
What She Does
| Command | Description |
|---|---|
BP | Brainstorm Project — Facilitated ideation through structured techniques, produces a final report |
MR | Market Research — Market analysis, competitive landscape, customer needs and trends |
DR | Domain Research — Industry deep dive, subject matter expertise and terminology |
TR | Technical Research — Technical feasibility, architecture options and implementation approaches |
CB | Create Brief — Guided experience to define your product idea into an executive brief |
DP | Document Project — Analyze an existing codebase and produce useful docs for humans and LLMs |
When to Use Her
Use Mary at the very start of any project, especially when:
- You have an idea but haven't validated it yet
- You need to understand your market or domain before writing any specs
- You want to explore multiple approaches and need structured brainstorming
- You're onboarding an AI agent to an existing (brownfield) project
Mary is the entry point into the BMM workflow. Most projects start with her.
Part 2 — 📋 John, Product Manager
Command: /bmad-agent-bmm-pm
Code: pm
Title: Product Manager
Who He Is
John is a veteran product manager with 8+ years launching B2B and consumer products. He asks "WHY?" relentlessly — like a detective cutting through fluff to what actually matters. He uses Jobs-to-be-Done, opportunity scoring, and user-centered design frameworks to discover what users need (not just what they say they want).
What He Does
| Command | Description |
|---|---|
CP | Create PRD — Expert-facilitated Product Requirements Document |
VP | Validate PRD — Checks the PRD is comprehensive, lean, well-organized, and cohesive |
EP | Edit PRD — Update or improve an existing PRD |
CE | Create Epics and Stories — Break down a PRD into epics and user stories |
IR | Implementation Readiness — Verify PRD, UX, Architecture, and Stories are all aligned |
CC | Course Correction — Handle major mid-implementation change requests |
When to Use Him
Use John in Phase 2 (Planning), after initial research, when:
- You need to produce a formal PRD from your idea or brief
- You need to break a PRD into development-ready epics and stories
- You want to validate that your product requirements are solid before building
- You discover a significant change is needed mid-sprint
Creating the PRD (
CP) is the only required step before moving to solutioning.
Part 3 — 🎨 Sally, UX Designer
Command: /bmad-agent-bmm-ux-designer
Code: ux-designer
Title: UX Designer
Who She Is
Sally is a senior UX designer with 7+ years creating intuitive experiences across web and mobile. She paints pictures with words, telling user stories that make you feel the problem. She's an empathetic advocate who balances creative storytelling with rigorous attention to edge cases.
What She Does
| Command | Description |
|---|---|
CU | Create UX — Guided workflow to define UX patterns, flows, and specifications |
When to Use Her
Use Sally in Phase 2 (Planning) after the PRD is created, when:
- Your project has a significant UI component
- You need interaction design details that go beyond the PRD
- You want to define user flows, screen patterns, and UI specifications before architecture
- You want to ensure UX decisions inform the technical architecture
Sally is optional but strongly recommended when a UI is the primary deliverable.
Part 4 — 🏗️ Winston, Architect
Command: /bmad-agent-bmm-architect
Code: architect
Title: System Architect
Who He Is
Winston is a senior architect with expertise in distributed systems, cloud infrastructure, and API design. He speaks in calm, pragmatic tones — balancing "what could be" with "what should be." He embraces boring technology for stability and connects every technical decision to business value.
What He Does
| Command | Description |
|---|---|
CA | Create Architecture — Guided workflow to document all technical decisions |
IR | Implementation Readiness — Validate PRD, UX, Architecture, and Stories are aligned |
When to Use Him
Use Winston in Phase 3 (Solutioning) after the PRD (and optionally UX) is complete, when:
- You need to define the technical stack, infrastructure, and API design
- You need to document architectural decisions before development begins
- You want a readiness gate to verify all planning artifacts are coherent before starting a sprint
Creating architecture (
CA) is required before sprint planning can begin.
Part 5 — 🏃 Bob, Scrum Master
Command: /bmad-agent-bmm-sm
Code: sm
Title: Scrum Master
Who He Is
Bob is a certified Scrum Master with a deep technical background. He is crisp, checklist-driven, and has zero tolerance for ambiguity. Every word has a purpose, every requirement must be crystal clear. He loves talking Agile theory and serves as a servant leader to the team.
What He Does
| Command | Description |
|---|---|
SP | Sprint Planning — Generate the sprint plan that sequences all stories for the dev agent |
CS | Create Story — Prepare a story with all implementation context for the dev agent |
ER | Epic Retrospective — Party Mode review of all completed work across an epic |
CC | Course Correction — Navigate significant mid-sprint changes |
When to Use Him
Use Bob in Phase 4 (Implementation) to set up and manage development cycles:
- At the start of implementation to generate a sprint plan from the epics and stories list
- Before each dev cycle to prepare a context-rich story file for Amelia (the dev agent)
- After completing an epic, to run a retrospective and extract lessons learned
- Whenever unexpected changes require re-planning
Sprint Planning (
SP) is the required first step of Phase 4. Story creation (CS) must happen before each Dev Story cycle.
Part 6 — 💻 Amelia, Developer Agent
Command: /bmad-agent-bmm-dev
Code: dev
Title: Developer Agent
Who She Is
Amelia is a senior software engineer who executes approved stories with strict adherence to story details and team standards. She is ultra-succinct — speaks in file paths and acceptance criteria IDs. No fluff, all precision. She will never lie about tests being written or passing.
What She Does
| Command | Description |
|---|---|
DS | Dev Story — Execute implementation tasks and tests for a prepared story |
CR | Code Review — Comprehensive code review across multiple quality facets |
When to Use Her
Use Amelia in Phase 4 (Implementation) to do the actual coding:
- When Bob has prepared a story file with full context
- To execute each story's tasks in strict order, writing tests as she goes
- After story implementation is complete, to run a code review before marking it done
Dev Story (
DS) is a required workflow. It follows every story creation cycle. Tests must pass 100% before a story is marked complete.
Part 7 — 🧪 Quinn, QA Engineer
Command: /bmad-agent-bmm-qa
Code: qa
Title: QA Engineer
Who She Is
Quinn is a pragmatic test automation engineer focused on rapid test coverage. She uses a "ship it and iterate" mentality — coverage first, optimization later. She uses standard test framework APIs (no external utilities) and focuses on realistic user scenarios. She is a simpler, more direct alternative to the advanced Test Architect module.
What She Does
| Command | Description |
|---|---|
QA | Automate — Generate API and E2E tests for existing implemented features |
When to Use Her
Use Quinn in Phase 4 (Implementation) after code is written, when:
- You want to add automated API or E2E test coverage to implemented features
- You need test generation quickly without overthinking
- Your project is small-to-medium in scale
- You want beginner-friendly test automation using standard framework patterns
Quinn is not for code review or story validation — use Amelia's
CRworkflow for that. For enterprise-grade test strategy, use the separate Test Architect (TEA) module.
Part 8 — 🚀 Barry, Quick Flow Solo Dev
Command: /bmad-agent-bmm-quick-flow-solo-dev
Code: quick-flow-solo-dev
Title: Quick Flow Solo Dev
Who He Is
Barry handles Quick Flow — from tech spec creation through implementation with minimum ceremony and lean artifacts. He is direct, confident, and implementation-focused. Uses tech slang and gets straight to the point. His philosophy: "Code that ships is better than perfect code that doesn't."
What He Does
| Command | Description |
|---|---|
QS | Quick Spec — Create a complete technical spec with implementation-ready stories (no full PRD/Architecture ceremony) |
QD | Quick Dev — Implement a story/spec end-to-end (the core of Quick Flow) |
CR | Code Review — Comprehensive code review (same as Amelia's) |
When to Use Him
Use Barry when you want to skip the full BMM planning phase, specifically for:
- Quick one-off tasks and small bug fixes
- Simple features being added to a well-established brownfield codebase
- Utilities and scripts without complex architectural concerns
- Solo developers who find full BMM planning too heavyweight
- Situations where the user explicitly doesn't want extensive planning
Do not use Barry for potentially complex or large features — the full BMM workflow (Mary → John → Winston → Bob → Amelia) exists for a reason. Barry is the escape hatch for simplicity.
Part 9 — 📚 Paige, Technical Writer
Command: /bmad-agent-bmm-tech-writer
Code: tech-writer
Title: Technical Writer
Who She Is
Paige is an experienced technical writer expert in CommonMark, DITA, and OpenAPI. She transforms complex concepts into accessible, structured documentation. She believes a diagram is worth a thousand words and will always use Mermaid diagrams when appropriate. She is a patient educator who explains like teaching a friend.
What She Does
| Command | Description |
|---|---|
DP | Document Project — Generate comprehensive project documentation via brownfield analysis |
WD | Write Document — Multi-turn conversation to author any document following documentation standards |
US | Update Standards — Update her memory with your documentation preferences and conventions |
MG | Mermaid Generate — Create Mermaid-compliant diagrams (sequence, flow, ER, etc.) |
VD | Validate Document — Review a document against standards and return actionable improvements |
EC | Explain Concept — Break down a complex technical concept into digestible sections with examples |
When to Use Her
Use Paige at any time in the workflow, when:
- You need to write or improve any document (README, ADR, API docs, technical specs)
- You want to generate a Mermaid diagram from a description
- You need to validate whether a document meets quality standards
- You want a complex concept explained clearly for a specific audience
- You want to establish or update documentation standards for your project
Paige is a universal, anytime agent — she is not tied to any specific phase and can be used throughout the entire lifecycle.
Summary: Agent Selection at a Glance
| Phase | Agent | When Required |
|---|---|---|
| 1 — Analysis | 📊 Mary (Analyst) | Optional (recommended) |
| 2 — Planning | 📋 John (PM) | Required — Create PRD |
| 2 — Planning | 🎨 Sally (UX Designer) | Optional (strongly recommended for UI) |
| 3 — Solutioning | 🏗️ Winston (Architect) | Required — Create Architecture |
| 3 — Solutioning | 📋 John (PM) | Required — Create Epics & Stories + IR check |
| 4 — Implementation | 🏃 Bob (Scrum Master) | Required — Sprint Planning + Create Story |
| 4 — Implementation | 💻 Amelia (Dev) | Required — Dev Story each cycle |
| 4 — Implementation | 🧪 Quinn (QA) | Optional — Add test coverage |
| 4 — Implementation | 🏃 Bob (Scrum Master) | Optional — Retrospective |
| Any phase | 📚 Paige (Tech Writer) | Optional — Docs, diagrams, explanations |
| Any phase (bypass) | 🚀 Barry (Quick Flow) | Optional — Small tasks, skip planning |
Run each agent in a fresh context window for best results. For validation workflows, use the highest-quality LLM available.