Level 9Lesson 77⏱️ 50 min

BMAD Part 2 - The Workflow

The full BMAD process, step by step: from a one-line idea to merged, tested, fully-documented code - with humans steering at every gate

The Whole Workflow at a Glance

BMAD formalizes building software into eight steps across its two phases. Each step has an owner (an agent), produces an artifact (a document or code), and waits for your approval before the next begins. Here's the whole flow:

PHASE 1 - AGENTIC PLANNING (no code yet)
  1. Brief          Analyst       → scope, users, constraints, risks
  2. PRD            PM            → FRs, NFRs, epics, draft stories
  3. Architecture   Architect     → components, contracts, tech choices
  4. Alignment      Product Owner → run checklists, resolve conflicts, shard

PHASE 2 - CONTEXT-ENGINEERED DEVELOPMENT
  5. Story drafting Scrum Master  → one rich story file at a time
  6. Implementation Developer     → build the story + tests, on a branch
  7. Review / QA    QA + checks   → automated scans, review, refactor
  8. Merge & iterate              → story done, next story begins
The rhythm: plan everything once (steps 1-4), then loop steps 5-8 one story at a time until the app is built. Each loop is small, checked, and traceable.

Phase 1 - Planning, Step by Step

1 - Brief (Analyst)

The Analyst interviews you about the idea and writes a brief: who it's for, what problem it solves, the constraints, and the risks. This is the "why" before any "what."

2 - PRD (Product Manager)

The PM turns the brief into a Product Requirements Document: functional requirements, non-functional requirements, grouped into epics with draft stories. (Your EARS skills from Lesson 74 live here.)

3 - Architecture (Architect)

The Architect designs the system: components, how they talk, the data model, and the tech stack - and writes it down as a document, not just a vibe.

4 - Alignment (Product Owner)

The Product Owner runs a checklist to catch contradictions between the PRD and the architecture, resolves them, and shards big specs into bite-size pieces ready for development.

Gate before code: nothing gets built until these four documents agree and you've approved them. This is where intent gaps die - on paper, cheaply.

Phase 2 - Development, Step by Step

5 - Story drafting (Scrum Master)

The Scrum Master writes one story file at a time - and this is the clever part. Each story is self-contained: the rationale, the exact constraints, embedded acceptance tests, and links back to the PRD and architecture. The Developer agent gets everything it needs in one tight package.

6 - Implementation (Developer)

The Developer agent builds that one story on its own branch, writing tests as it goes, guided only by the story's context - no wandering into the rest of the codebase.

7 - Review & QA

A pull request kicks off automated checks (tests, quality scans, security analysis) plus review by the QA agent (and humans). It refactors if needed, always staying tied to the original intent.

8 - Merge & iterate

Story marked done, merged. The next story begins. The cadence repeats until the PRD is fully built.

Why the Story File Is the Secret Sauce

The single most important BMAD idea for quality is the sharded, context-rich story file. Instead of telling the Developer agent "build the whole app," you hand it one tightly-scoped story with everything it needs and nothing it doesn't.

# Story: Add a task

## Why (links to PRD)
FR-3: users can add tasks. See prd.md#tasks.

## Constraints (links to architecture)
- Save via the TaskStore module (architecture.md#data). No inline SQL.
- New tasks go to the top of the list.

## Acceptance tests (embedded)
- Submitting a task adds it without a page reload.
- It persists after refresh.
- Empty submit shows a validation error.

## Out of scope
- Editing or deleting tasks (separate stories).
This is Levels 7 and 8 fused: the story is a perfect tight context window (Level 8) and the unit of a loop (Level 7). BMAD is the agile wrapper that makes producing good story files routine.

Governance: The Control Manifest

Because everything is documents in Git, a BMAD project has a complete, auditable history - every requirement, decision, and code change traceable. Teams add one more guardrail: a control manifest committed before generation starts.

# Control manifest (the guardrails humans set)
- Allowed libraries: React, Zod, Prisma. Ask before adding others.
- Performance budget: pages under 200KB JS.
- Exclusion zones: never touch /payments without human sign-off.
- All code must pass the security scan before merge.
Humans own the flight plan; AI flies within it. The control manifest is how you stay in charge - the agents execute fast, but only inside boundaries you set. For regulated work (SOC 2, HIPAA), this versioned trail is your compliance evidence.

Hands-On: Draft One Story File

Hands-on (15 min): For your app idea, write one complete story file using the template above: a title, the "why" (which requirement it satisfies), the constraints, 2-3 embedded acceptance tests, and an explicit "out of scope" list. The out-of-scope section is where most people's quality comes from - it stops the agent from sprawling. You'll generate a whole set of these in the next lesson's worked example.
Lesson 77 Quick Reference
The 8 steps

Brief → PRD → Architecture → Alignment (plan), then Story → Implement → Review/QA → Merge (build), looped per story

Gate before code

No code until the four planning docs agree and you approve - intent gaps die cheaply on paper

Sharded story file

One self-contained story: rationale, constraints, embedded tests, links to PRD/architecture, out-of-scope

One story at a time

The Developer builds a single sharded story on its own branch - a tight context, not the whole app

Control manifest

Human-set guardrails (allowed libs, perf budget, exclusion zones) committed before generation

Auditable by default

Every doc, decision, and change in Git becomes a compliance trail (SOC 2 / HIPAA)

← BMAD Part 1 - Your AI Product Team
Unlocks in ~13 min of reading