In the previous articles of this series we covered SDD (Spec-Driven Development) and how to apply quality gates, tests, and templates. Now I’ll show something I haven’t found clearly documented anywhere: the complete BMAD workflow, step by step, showing how AI agents organize themselves to deliver production code.

What is BMAD?

BMAD (Breakthrough Method for Agile AI-Driven Development) is an open source framework that organizes AI agents as if they were an agile team. Each agent takes on a role, PM, Architect, Dev, QA and handles a specific part of the development workflow.

The key point is: you don’t just tell the AI “go do it”. You follow a workflow where each phase produces artifacts that feed the next, and each AI agent knows exactly what to do because it has structured context.

The Agents

Before diving into the workflow, let’s see who does what. Remember: these are all AI agents, not real people.

AI AgentRoleWhat it does
AnalystDiscoveryDomain, market, and competition research
PMPlanningCreates PRD with functional and non-functional requirements
UX DesignerDesignCreates UX specs, components, interaction patterns
ArchitectSolutioningMakes technical decisions (ADRs), validates readiness
Scrum MasterOrganizationPlans sprints, creates stories, runs retrospectives
DevImplementationExecutes stories using TDD
QAQualityTest strategy, automation
Solo DevQuick FlowHandles spec + dev + review for small changes

Two Paths: Full Method vs. Quick Flow

The first decision in BMAD is: how big is the change?

flowchart TB START([New change]) --> DECISION{How big is it?} DECISION -->|"Large"| FULL["Full Method"] DECISION -->|"Small"| QUICK["Quick Flow"] accTitle: BMAD scope decision accDescr: A scope decision showing that large changes go through the Full Method while small changes use the Quick Flow.
  • Full Method: goes through all phases, with multiple AI agents collaborating
  • Quick Flow: a single agent (Solo Dev) handles spec + dev + review

This separation is fundamental. Without it, you end up using the full process to fix a typo, or worse, building a complex feature without specs.

Full Method: The Complete Workflow

Greenfield (New Project)

When the project is new, we start from scratch, from analysis to implementation:

flowchart TB F1["1. Analysis"] F2["2. Planning"] F3["3. Solutioning"] F4["4. Implementation"] F1 --> F2 --> F3 --> F4 accTitle: Greenfield BMAD phases accDescr: A four-phase greenfield flow that starts with analysis, continues through planning and solutioning, and ends with implementation.

Phase 1 — Analysis (Analyst Agent)

The Analyst agent does the initial research: domain, market, competition, technical feasibility. It produces the Product Brief with vision, personas, and success metrics.

Phase 2 — Planning (PM and UX Designer Agents)

The PM agent creates the PRD (Product Requirements Document) with all functional requirements in Given/When/Then format. If the project has a UI, the UX Designer agent creates design specs: components, interaction patterns, design system.

Phase 3 — Solutioning (Architect Agent)

The Architect agent makes technical decisions and documents them as ADRs (Architecture Decision Records). Then it breaks the PRD into epics and stories. Finally, it runs a readiness validation to ensure everything is aligned before coding begins.

Phase 4 — Implementation (SM, Dev, and QA Agents)

This is where the code happens:

flowchart TB SM["Plan sprint"] STORY["Create story"] ARCH{"DoR ok?"} DEV["Implement with TDD"] QA{"Review ok?"} GATES{"Gates passed?"} COMMIT["Commit and sync"] SM --> STORY --> ARCH ARCH -->|OK| DEV ARCH -->|Failed| STORY DEV --> QA QA -->|OK| GATES QA -->|Fix| DEV GATES -->|Passed| COMMIT GATES -->|Failed| DEV accTitle: BMAD implementation loop accDescr: An implementation loop where sprint planning creates stories, readiness is checked, development proceeds with TDD, QA reviews the result, quality gates run, and successful work is committed.
  1. The Scrum Master agent plans the sprint and creates story files with full context
  2. The Architect agent validates the Definition of Ready for each story
  3. The Dev agent implements using TDD: RED -> GREEN -> REFACTOR per AC
  4. The QA agent does adversarial code review
  5. Quality gates: tests + build + type-check
  6. Commit and artifact sync

Brownfield (Existing Code)

When code already exists in production, the workflow changes. No Phase 1 (analysis) needed since the domain is already known. Context comes from the codebase itself:

flowchart TB START([Existing code]) --> CTX["Generate project context"] CTX --> DECISION{Needs PRD?} DECISION -->|Yes| P2["Phase 2: PRD"] DECISION -->|No| P3["Phase 3: Architecture"] P2 --> P3 P3 --> P4["Phase 4: Implementation"] P4 --> DONE([Code delivered]) accTitle: Brownfield BMAD flow accDescr: A brownfield delivery flow where existing code provides project context, optional PRD work happens when needed, architecture follows, and implementation delivers the code.

The key difference: before anything else, you generate a project context, a document describing the existing codebase’s patterns, stack, conventions, and structure. This allows AI agents to follow existing patterns rather than inventing new ones.

Quick Flow: The Fast Path

For small changes, bugs, config tweaks, simple features touching fewer than 3 files the Quick Flow is the way to go.

flowchart TB QS["Quick Spec"] --> QD["Quick Dev"] QD --> QR["Code Review"] QR --> DONE([Code delivered]) accTitle: Quick Flow path accDescr: A lightweight flow where a quick specification leads to quick development and then code review before delivery.

A single AI agent (the Solo Dev) handles everything:

  1. Quick Spec: creates a simplified tech-spec or story
  2. Quick Dev: implements the change
  3. Code Review: reviews its own code adversarially

Quick Flow doesn’t skip quality gates, tests, build, and type-check are still required. What it skips are the planning and solutioning phases that don’t make sense for small changes.

When to use Quick Flow vs. Full Method?

ScenarioPath
Isolated bug fixQuick Flow
Config changeQuick Flow
Simple feature (< 3 files)Quick Flow
New feature with multiple endpointsFull Method
Architecture refactorFull Method
New epic or moduleFull Method
Changes affecting security/authFull Method

When in doubt, use the Full Method. Better to have unnecessary specs than code without specs.

The Workflow’s Artifacts

Each phase produces artifacts that feed the next. This is what differentiates BMAD from simply asking the AI to “just do it”:

flowchart TB F1["Analysis"] --> A1["Product Brief"] A1 --> F2["Planning"] F2 --> A2["PRD + UX Specs"] A2 --> F3["Solutioning"] F3 --> A3["ADRs + Stories"] A3 --> F4["Implementation"] F4 --> A4["Code + Tests"] F4 --> A5["Sprint Status"] A4 -. Updates .-> A2 A4 -. Updates .-> A3 accTitle: BMAD artifact handoff chain accDescr: A handoff chain where analysis produces a product brief, planning produces PRD and UX specs, solutioning produces ADRs and stories, and implementation produces code, tests, and sprint status with feedback back to specs and architecture.

Artifacts are living documents. When implementation reveals that something needs to change in the specs, the specs get updated. This feedback loop is what keeps everything consistent.

Sprint Status as Source of Truth

Each story’s state is tracked in a central file:

development_status:
  # Epic 1: Authentication
  epic-1: in-progress
  1-1-user-registration: done
  1-2-user-login: in-progress
  1-3-password-reset: ready-for-dev
  1-4-oauth-integration: backlog

  # Epic 2: Dashboard
  epic-2: backlog
  2-1-dashboard-layout: backlog

The possible statuses follow a linear flow:

flowchart TB BACKLOG["backlog"] --> READY["ready-for-dev"] READY --> PROGRESS["in-progress"] PROGRESS --> REVIEW["review"] REVIEW --> DONE["done"] accTitle: Sprint status progression accDescr: A linear sprint status progression moving from backlog to ready-for-dev, then in-progress, review, and done.

The Complete Decision Flow

Putting it all together, the BMAD decision flow looks like this:

flowchart TB START([New change]) --> SCOPE{Scope?} SCOPE -->|Small| QF["Quick Flow"] SCOPE -->|Large| EXISTS{Does the project already exist?} EXISTS -->|No| GF["Greenfield"] EXISTS -->|Yes| BF["Brownfield"] QF --> DONE([Delivered]) GF --> DONE BF --> DONE accTitle: Complete BMAD decision flow accDescr: A complete decision flow where a new change is routed either to Quick Flow or, for larger work, to greenfield or brownfield delivery depending on whether the project already exists.

Final thoughts

BMAD isn’t a framework to make things more bureaucratic. It’s about making work with AI agents predictable and reliable. Without a structured workflow, every session is a lottery, sometimes the AI gets it right, sometimes it doesn’t.

With BMAD:

  • Small changes are fast (Quick Flow)
  • Large changes are well-planned (Full Method)
  • All code has specs, tests, and review
  • Context persists between sessions through living artifacts

If you read the other articles in this SDD series, you now have the full picture: the workflow (this article), the philosophy, and the practices.

Official BMAD Method repository.