DEV Community

Cover image for BMAD Method (Part 1): Spec-Driven Development Where the Human Stays in Control
rosidotidev
rosidotidev

Posted on Edited on

BMAD Method (Part 1): Spec-Driven Development Where the Human Stays in Control

As a software architect and senior software engineer, I keep watching the same change happen in the way we build software. In the first series I wrote about GitHub Spec Kit, and I stayed on one idea that I still think matters most: spec-driven development (SDD). Write the intent first, make it explicit, let the agent build against it, then check the result against what was written.

That idea does not depend on a framework. Spec Kit is one way to apply it, BMAD Method is another, and a markdown file in your repo is a third. In this series I look at BMAD Method, and in this first article I stay on the concepts and the commands. I do not show a finished result yet.

My angle is the same as before: not how fast an agent writes code, but who decides what gets built and who answers for what is produced. I think this is the question the industry is starting to ask. Anthropic has published a Claude Academy course, The AI-native SDLC playbook, which asks teams to capture the intent in a version-controlled file and to keep a person in charge at the approval gates. BMAD has been moving in that direction for a while. This is a personal view, not a verdict.

What Is Spec-Driven Development?

Let's start from the problem. Many developers have had the same experience with an AI coding tool. The agent writes code quickly, the code often runs, and yet nobody on the team can say why it was written that way. Two sessions later the intent is gone, buried in a chat history, and the next change starts from a guess.

I call this vibe coding. I do not think the problem is the model. The problem is where the context lives. If the intent exists only in a prompt, it disappears when the session ends. If it exists in a document that the agent reads and the human reviews, the team can inspect it, change it, and keep it.

SDD, for me, comes down to four points:

  • The intent is written down before the code. In a file, not in a chat.
  • The agent works inside that intent. It does not reinterpret it silently.
  • The human approves the intent and judges the result. The agent does not own the definition of done.
  • The spec is versioned with the code. When the intent changes, the change is visible.

As in the first article, I would say the rigor of the spec can vary (spec-first, spec-anchored, spec-as-source), and these four points hold at every level.

Mental Model: the framework is a way to apply the idea at scale, not the idea itself.

BMAD in a Nutshell

BMAD stands for Breakthrough Method of Agile AI-Driven Development. It maps familiar roles (analyst, product manager, UX designer, architect, developer) onto AI agents, and it keeps the work in documents that the agents read and the humans review.

Two ideas matter most for me. The first is that each document has one owner and one writing skill. The Product Requirements Document (PRD) is the source of the product definition, and nothing else claims to define it. The planning docs say that documents are "contracts between people first and input to the skills second". The second idea is a rule: nothing downstream reinterprets the PRD. If a story needs an answer the PRD does not have, the answer goes into the PRD first, and the derived documents are regenerated. This is the whole point of the design.

The other thing BMAD gives you is more than one path. The first decision is about size, not tools. A change of roughly 500 lines, across a few files, fits one build session. If the intent is already well defined, you hand it to a build, or to the epics and stories skill when the work is bigger. If it is not, you use the analysis skills first, in any order, until it is. The planning skills write the requirements down; they do not decide what you want.

Trivial, you review it yourself:   edit directly, no process
One session (about 500 lines):     intent -> /bmad-build -> result
Epic-sized:                        intent -> brief, PRD, UX, architecture, epics and stories -> one /bmad-build per story -> retrospective
Project-sized:                     several epics, shared decisions first, then the epic path for each
Enter fullscreen mode Exit fullscreen mode

The skills are grouped by phase: Analysis (optional, any order), Planning (PRD and UX), Solutioning (architecture, epics and stories, sprint status) and Build (one story at a time). One note: the version I have installed (6.12.4) labels its skills only plan and ship, so the four names are the grouping of the planning guide, not a label you will see in the tool.

Mental Model: size the process to the work, and make sure the intent is clear before anything is built.

Why It Is Built This Way

The BMAD docs describe what each piece is and how to use it. They say little about why it is built this way, so part of what follows is my reading, and I mark it as such.

  • Documents carry the whole picture across sessions. The planning guide says that the PRD, the architecture and each ticket's requirements "exist so later sessions can still see the whole", and it warns that "Dividing work can lose information". That is the trade: the work is cut into one-session units, and the documents keep the pieces from drifting apart. Each run starts in a fresh chat for a reason the build docs give: "Reusing a session from another workflow can mix contexts and confuse the run."
  • Shared decisions are written once, where they are shared. The stated purpose of the architecture step is: "Make the technical decisions that keep separately built parts consistent." I think this is why the architecture stays short: it records what several builders must follow and leaves the rest to each story. The docs do not say "only", so this part is my reading.
  • Human attention goes where a mistake gets copied. The build docs say that early stories "often settle the architecture, initial project structure, and repeated patterns", and that these decisions deserve human attention "before automating repetitions of them". I think the same logic explains the gates on the PRD and the architecture: an error there is not fixed once, it is built into every story.

One thing I did not find: a reason for splitting the work across roles in the first place. The closest statement is about people, not agents: "You make the calls, so you understand what you ship." I would not claim more than that.

Mental Model: the documents are the memory, and the human gates sit where a mistake gets copied.

Setting Up

The version I use is BMAD 6.12.4, the stable one. It installs from the project directory with one command:

npx bmad-method install
Enter fullscreen mode Exit fullscreen mode

The installer writes the skills for the coding tool I choose (Claude Code in my case) into .claude/skills/, and a _bmad/ folder with the configuration. The skills are typed in the slash form (/bmad-build, /bmad-prd), and that is the form I use here. When I am unsure where to start, there is /bmad-help. The online docs now describe a newer v7 preview with some different names. I follow the version I use, and I say where the docs differ.

A Simple Example: a Todo List

I use the same todo list as in the Spec Kit series, so the two approaches can be compared on the same problem. There are two situations, and they lead to two different paths. In both I show the commands and not the results.

Path One: Adding a Flag to a Todo List I Already Have

Suppose the todo list is already implemented, with add, edit and delete. I want to add a "done" flag to each item and toggle it from the list view. The change is small, clear and low risk, and it fits in one session. For this path I need only one skill: bmad-build. It takes an intent, investigates, plans, implements, reviews, and fixes what it finds.

Below is the flow from the build documentation (docs.bmad-method.org/build/build-a-change/), redrawn in my own style. The main line runs from top to bottom: intent, clarify, plan, implement, review, result. Dashed lines show where a human takes part, and the loops are the interesting part.

Step 1: Size the Work and Start Fresh (one session, no shared context):

/bmad-build Add a "done" flag to each todo item, toggle it from the list view, and keep the state after reload.
Enter fullscreen mode Exit fullscreen mode

The change touches a few files and far fewer than 500 lines, so bmad-build is the right tool. A trivial change that I will review myself does not need the process at all. I run the command in a new chat, because reusing a session from another workflow can mix contexts, and that is where wrong assumptions come from. The intent can be rough, and it can also be an issue link or a story (/bmad-build story 2.3, which I use in Path Two). I prefer to write it in full. A rough intent is allowed, but it moves the cost to the questions the agent asks later.

Step 2: Clarify and Plan (the human answers, the plan is the optional gate):

The agent reads the codebase and any planning documents. Anything the repository cannot settle becomes an open question, and I answer carefully, because wrong answers here are the costliest to fix later. In the todo case I would expect a question about whether done items stay in the list. That is my decision, not the agent's.

Then the agent checks three facts: intent gaps, irreversible actions, and the footprint of the change. If all three are clean, it takes the light path: a minimal plan and the implementation in the same session. If anything is flagged, it writes a full plan and waits for my approval. Fixing the plan is cheaper than fixing the code.

Step 3: Implement and Review (the agent's own gates):

The agent implements, checks the change against the acceptance criteria it recorded, and reviews its own work with three lenses: a Blind Hunter (problems without the bias of the implementation context), an Edge Cases Hunter (forgotten corner cases) and a Verification Gap Finder (do the tests really cover the change?). The review ends in a triage, and each outcome has a destination:

  • Patch. The issue belongs to this change, so it is fixed and the review runs again.
  • Bad plan. The code is wrong because the plan was weak, so the flow returns to Plan.
  • Intent gap. The plan is wrong because the goal was wrong, so it returns to Clarify.
  • Void. The change is rejected.
  • Defer. An unrelated pre-existing issue goes to deferred-work.md.

I like that the loops are explicit. A review that can only say fixed or not fixed hides the cause of the problem, and here the cause has to be named.

Step 4: Present and Review the Result (the human gate):

The agent gives a short summary and commits locally. I run the walkthrough or skim the diff, tell the agent what to fix, and when I am satisfied I ask it to push the commit and open the PR. Two things can still go wrong after this.

If the change turns out to be wrong after I accepted it. If I pushed the commit and then find a problem, the way back is the ordinary one in git, so the history stays intact:

git revert HEAD
Enter fullscreen mode Exit fullscreen mode

This creates a new commit that cancels exactly what the agent added. I do not patch the problem inside the old chat. I start a fresh chat and run /bmad-build again, with the intent rewritten to say what I missed (for instance: "the flag must survive a page reload"). The intent is the thing I correct, and the code follows it. This is a git practice that fits the flow, not a step that BMAD runs for me.

What the agent chose not to fix. An unrelated problem is not fixed silently and not dropped: it is written into deferred-work.md, with the story it came from, a one-line summary and the evidence. I read this file after every run. A backlog nobody reads is where problems go to be forgotten, so for each entry I decide whether it is a new change, a note to keep, or something to drop on purpose.

Path Two: Writing a Todo List From Scratch

Now suppose there is no todo list yet. I want a todo app with due dates and filters, kept in the browser. This is a body of work with several build units, so one /bmad-build is not enough. The planning documents become the contract, and each step reads the files that the previous step wrote. Every step runs in a fresh chat (/clear first). I show the real commands. What each step reads and writes is in one table, a few sections below.

Step 1: Brainstorm (optional, what and why, no technology):

/bmad-brainstorming A simple todo list web app. Explore features, UX ideas and what must stay out of version 1.
Enter fullscreen mode Exit fullscreen mode

A coach runs the session in the stance I choose: facilitator, creative partner, or ideate for me. My decisions are kept apart from the ideas the coach offered. If the idea is still half-formed, /bmad-forge-idea pressure-tests it and /bmad-deep-recon researches a competitor or a technology. A personal view, not a verdict: if I cannot write the intent in three sentences after this step, I am not ready for a PRD.

Step 2: Product Brief (what and why, in one page):

/bmad-product-brief Create a product brief for a simple todo list web app. Use the brainstorming result at <intent path> as the main input and treat its "Decisions" table as settled.
Enter fullscreen mode Exit fullscreen mode

The skill asks whether I want to create, update or validate, and whether I take the Fast path or the Coaching path. Every planning skill has the same three intents, and I run validate in a fresh chat before moving on (/bmad-product-brief validate the brief at <brief path>).

Step 3: PRD (what to build, not how):

/bmad-prd Create the PRD for the todo list using the brief at <brief path> and the brainstorming intent at <intent path>. Features in order: (F0) foundations and storage; (F1) the list: add, tick, delete; (F2) due dates, overdue sign and filters.
Enter fullscreen mode Exit fullscreen mode

The PRD is the source of the product definition, and every later document derives from it. Functional requirements get stable ids (FR-1, FR-2, ...), and what the skill inferred is tagged [ASSUMPTION] so that I can correct it. Edits belong in the PRD, not in the stories (/bmad-prd update the PRD at <prd path>: <what to change>), so the derived documents can be generated again.

Step 4: UX (optional, how it looks and how it behaves):

/bmad-ux Create the UX documents for the todo list from the PRD at <prd path>. Simple, calm, keyboard friendly, one screen.
Enter fullscreen mode Exit fullscreen mode

The skill captures my vision and does not impose its own. It writes two peer documents: DESIGN.md (how it looks) and EXPERIENCE.md (how it behaves). I would skip it only if I accept designing those details later, during the builds.

Step 5: Architecture (how, only where two builders could disagree):

/bmad-architecture Create the architecture for the todo list from the PRD at <prd path>, DESIGN.md and EXPERIENCE.md at <ux folder>. Decide: front-end framework, where tasks are stored, the task data model, the testing strategy.
Enter fullscreen mode Exit fullscreen mode

The output is not a full technical document. It is a short architecture spine that records only the decisions that two units, built independently, could make in incompatible ways. A decision gets a stable id (AD-1, AD-2, ...) only if it is non-obvious and a real trade-off. This is where my review matters most, because a wrong shared decision spreads to every story.

Step 6: Epics and Stories (work cut by user value):

/bmad-create-epics-and-stories Create the epics and stories list from the PRD, UX documents and architecture. Create exactly three epics, in this order: Epic 1 Foundations; Epic 2 Task list; Epic 3 Due dates and filters. Every story needs acceptance criteria.
Enter fullscreen mode Exit fullscreen mode

Every functional requirement is mapped to an epic, and every story has acceptance criteria in the Given, When, Then form and fits one build session. I check the epic and story numbers, because every build command from now on uses them.

Step 7: Readiness Check (the gate before the build):

/bmad-sprint-planning check implementation readiness
Enter fullscreen mode Exit fullscreen mode

The skill reads the planning documents the way a skeptic reads a handoff, and answers PASS, CONCERNS or FAIL. On CONCERNS or FAIL I fix the planning documents and run the check again. If something major changes later, there is /bmad-correct-course <description of the change>.

Step 8: Sprint Status (one file that says where every story is):

/bmad-sprint-planning run sprint planning
Enter fullscreen mode Exit fullscreen mode

It writes sprint-status.yaml, with every epic, story and retrospective as a key. All stories start as backlog, then move to ready-for-dev, in-progress, review and done.

Step 9: Build One Story at a Time (the implementation phase):

/bmad-build story 1.1
Enter fullscreen mode Exit fullscreen mode

/bmad-build does not pick the next story by itself: I give it the number each time, one story per fresh chat, in order. Each run follows the flow of Path One. The story moves to review in the sprint status, and the agent does not close its own work: I review, and I decide when a story is done. An optional extra check, in a fresh context, is /bmad-code-review. I would not use the unattended build skill for the first stories, because they set the patterns for the rest.

Step 10: Retrospective (close the epic):

/bmad-retrospective 1
Enter fullscreen mode Exit fullscreen mode

The skill reads the evidence the epic left (the specs, the diff, the commits, the sprint status) and judges the epic against the criteria it set for itself. Every finding carries a source, and a claim with no source is dropped. A failing epic never closes as quietly accepted.

Looking at these ten steps together, the pattern is always the same. Each skill writes one document or one piece of code. Each document has one writer. Each gate has a human decision. The agent works inside the boundaries that the earlier documents set.

What BMAD Writes to Disk

What makes the process work is the files, because each step reads what the previous one wrote. BMAD keeps two folders at the project root, and they have different jobs.

  • _bmad/ is the metadata. Installed version and modules, the skill list, the configuration, the team overrides, and the script that writes the logs. It holds no deliverable.
  • _bmad-output/ is the handoffs. Every document a skill produces, in one run folder per document, plus the sprint status and the build specs.

Here is the handoff chain in one table: what each step reads, and what it writes for the next one.

Step Reads Writes
Brainstorm nothing (the idea is in the command) brainstorm-intent.md
Brief brainstorm-intent.md brief.md, addendum.md
PRD brief, addendum, intent prd.md
UX prd.md DESIGN.md, EXPERIENCE.md
Architecture PRD, DESIGN.md, EXPERIENCE.md ARCHITECTURE-SPINE.md, plus SOLUTION-DESIGN.md in coaching mode
Epics and stories PRD, UX documents, spine epics.md
Readiness check epics.md and the documents behind it PASS, CONCERNS or FAIL
Sprint status epics.md sprint-status.yaml
Build, per story the story, the spine, UX documents for UI work code, spec-N-M-*.md, epic-N-context.md, deferred-work.md, status moved to review
Retrospective the specs of the epic, git history, sprint-status.yaml the retrospective and its decision

Each run folder also holds a .memlog.md. It is the memory of that document: an append-only log with one line per decision, assumption or change, written by a script and never edited by hand. This is the shape of one (the lines are illustrative, for the todo PRD):

- (decision) Working mode: Fast path, entry point Vision + Features
- (assumption) Selected filter survives a reload
- (event) PRD finalized
Enter fullscreen mode Exit fullscreen mode

Three things follow from this design:

  • A fresh chat can continue. A step reads files, not the history of the previous chat, so I can close the session and resume tomorrow.
  • Every decision has a trace. The memlog says what was decided and why, and which assumptions are still open.
  • A change starts at the source. If a story needs an answer the PRD does not have, the answer goes into the PRD first, and the later steps run again.

BMAD keeps one memlog per document, not one for all the sessions. If I want the view across the steps, I would keep a small file for it.

What the Method Gives You

  • Context that survives sessions. Decisions live in files, so a new chat starts from documents, not from memory.
  • Version control for decisions. The PRD, the architecture and the stories live in git, next to the code.
  • Predictability. I know the likely end state of a session, because it was written before the session started.
  • Several sizes of process. A one-session change and a whole product use the same vocabulary with very different amounts of ceremony.

The other side, with the same sincerity as before:

What the Method Does Not Give You

  • Correctness by default. An agent can implement the wrong thing precisely. A good spec reduces guessing, it does not remove it.
  • Zero overhead. For a typo or a CSS tweak, even the short path is too much.
  • Freedom from handoff problems. Agents with different roles can still make conflicting assumptions. The documents make the conflict visible, but a human has to resolve it.
  • Room in the context window. Specs, architecture and stories consume context, so they must stay concise.
  • A replacement for judgment. The framework tells you when to stop and ask. It does not tell you what the product should be.

The Role of the Human

In every path, the agent produces a lot, and the human is responsible for what is accepted. On the short path I answer the open questions, approve the plan when it is flagged, and review the result. On the long path there are moments where a human decision blocks the next step. These are the ones I meet in the version I use (the planning guide of the online docs lists five sign-off points for the newer version):

Moment What I judge What it blocks
Brainstorm intent Which directions survive, the Decisions table The brief and the PRD
PRD validation The findings report UX and architecture
Architecture validation The decisions that are mine, the corrections Epics and stories
Readiness check PASS, CONCERNS or FAIL Sprint planning and the first build
Plan approval and story review The plan when flagged, the diff, deferred-work.md Marking the story done
Retrospective decision Did the epic meet its criteria The next epic

Each of these leaves a written trace, in a memlog, a report or a status file. In a regulated company that is the audit trail, and in a small team it is the best record of why a decision was made. I think this is the clearest statement of responsibility I have seen in an agent workflow.

Mental Model: bounded autonomy, not full automation.

Takeaways

  1. A spec is a contract between people first, and input for agents second. If the intent is not clear to the people involved, no agent will make it clear for them.
  2. Size comes first. One session, one epic and one project need different amounts of process, and choosing between them is my call.
  3. The loops in the build flow are the point. A bad plan, an intent gap and a deferred problem each go back to the layer that caused them, so a wrong decision is not buried in the code.
  4. The human approves the plan and judges the result, and the agent works inside both. The responsibility for what is produced does not move. What changes is where I spend my attention: on the intent, the gates and the diff.
  5. The handoff between steps is a file, not a chat. That is what lets a fresh session continue, and what leaves a written trace of every decision.

What Comes Next

BMAD is one answer to a question that many people are asking at the same time: how do we give an agent enough written intent to work well, and keep a human in charge of what comes out? I do not think it is the only answer, and I would not want this series to be only about one tool.

In the next article I want to make the example more concrete. I also want to keep the radar on, because spec-driven development is moving fast: what the major players are doing about it, how the SDLC changes when an agent does part of the work, and which other approaches are worth exploring. Two that I already have on my list are OpenSpec by Fission-AI, and the agent-skills collection by Addy Osmani. I have not formed a view on them yet, and I would rather look before I write about them.

There will be at least one more article after this one. Stay tuned.

What is your experience with planning documents and agents? Do you keep the spec in the repo, in a tracker, or in the chat? I would love to read your experience in the comments.

Top comments (2)

Collapse
 
treb0r profile image
Rob Blake •

I was a big fan of BMAD.

Eventually I ran into some serious problems with it.

I found that Matt Pocock's development skills are far better.

Collapse
 
rosidotidev profile image
rosidotidev •

Hi Rob, thank you for your feedback! I'm evaluating AI sdlc/sdd frameworks. What kind of serious problems did you run?