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 been talking about an AI Native Playbook, and 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.

The other thing BMAD gives you is more than one path. The first decision is about size, not tools. The build documentation says a change of roughly 500 lines, across a few files, fits one build session. The planning guide asks the question from the other side: is the intent already well defined? If it is, 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

BMAD also names its skills by phase. The planning guide groups them as Analysis, Planning and Solutioning, and Build is the phase that follows (the older dev.to articles call it Implementation). Analysis is optional, and its skills run in any order. Planning is where the PRD and the UX documents are written. Solutioning is where the architecture is decided, and where the epics and stories and the sprint status are produced. Build takes one story at a time. I use these four names in the rest of the article. One note: the skill catalog of the version I have installed (6.12.4) labels its skills only plan and ship, so the four names are the guide's grouping, 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.

Setting Up

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

npx bmad-method install

The installer sets up the modules and the skills for the coding tool I choose (Claude Code in my case). It writes the skills into .claude/skills/ and a _bmad/ folder with the configuration. In Claude Code the skills are typed in the slash form (/bmad-build, /bmad-prd), and that is the form I use in this article. When I am unsure where to start, there is /bmad-help.

The online docs now describe a newer v7 preview, installed with the Skills CLI, with some different names (for example a product owner skill called bmad-agent-po). 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. This is the short path, and 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, redrawn in my own style with the same structure (source: docs.bmad-method.org/build/build-a-change/). I walk through it node by node, because each node is a decision that somebody has to own.

How to read the diagram. The main line runs from top to bottom: Initial intent, Clarify and route, Plan, Approved plan, Implement, the "Fits AC?" check, Review, Present, Result. Dashed lines show where a human takes part: the interview during clarification, the optional plan review, and the review of the result. A one-shot mode skips the planning nodes and goes from Clarify and route straight to Implement. The loops are the interesting part: a patch goes back to Review, a bad plan goes back to Plan, an intent gap goes back to Clarify and route, a rejected change goes to the bin (Void), and anything unrelated is deferred to a file.

Step 0: Size the Work (is it one session?):

For this change the answer is yes: a few files and far fewer than 500 lines. The docs give the rule. If it fits, use bmad-build. If it is too big, plan first. If you are unsure, ask bmad. A trivial change that you will review yourself does not need the process at all, and I would not use it for a one-line typo.

Step 1: Start a Fresh Chat (no shared context):

I open a new chat in the AI IDE. The docs warn that reusing a session from another workflow can mix contexts, and in my experience that is where wrong assumptions come from. A fresh chat means the agent starts from the files, not from what we said about the previous feature.

Step 2: Give the Intent (rough is fine):

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

This is the Initial intent node. The docs say the intent can be rough, and it can come before, with, or after the command. It can also be an issue link, or a story from the epics list (/bmad-build story 2.3 builds story 3 of epic 2, and I use that form in Path Two). I prefer to write the intent in full for a change like this one. A rough intent is allowed, but it moves the cost to the questions the agent asks later.

Step 3: Clarify and Route (resolve the intent from evidence):

This is the Clarify and route node. The agent reads the codebase and any planning documents. Clear requests go ahead without a turn of questions. Anything the repository cannot settle becomes an open question on a finished design, not an interview before work starts. The human part is to answer those questions 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 or move to a separate view. That is my decision, not the agent's.

Step 4: Plan and Approve (the optional gate):

The agent evaluates the settled design on 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, reviewed afterwards. If anything is flagged, it writes a full plan, and each intent gap becomes a question I must answer before approval. I approve the plan if it describes the right thing, and I push back if not, because fixing the plan is cheaper than fixing the code. For the todo flag, I would expect the light path. If the agent flags a migration of the stored data, the plan is where I decide it.

Step 5: Implement, Check, Review (the agent's own gates):

The Implement node is the agent's work. The "Fits AC?" check compares the change with the acceptance criteria that the build plan recorded. Then the Review node starts, and the agent reviews its own work with independent reviewers. The diagram names three lenses:

• Blind Hunter: finds problems without the bias of the implementation context.
• Edge Cases Hunter: looks for forgotten corner cases.
• Verification Gap Finder: asks whether the tests really cover the change.

The review ends in a triage, and the diagram shows where each outcome goes. A patch fixes issues that belong to this change and returns to Review. If the code is wrong because the plan was weak, the flow returns to Plan. If the plan is wrong because the goal was wrong, it returns to Clarify and route. A rejected change goes to Void. Unrelated pre-existing issues are deferred to deferred-work.md (the diagram spells the name with an underscore, the file in the project uses a hyphen). Then the agent commits locally, and runs the test suite if the project has one.

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 6: Present and Review the Result (the human gate):

The Present node is the agent's short summary, with next steps: create a pull request, walk through the change, or make another change. The Result node is mine. I run the walkthrough or skim the diff, I tell the agent what to fix (it can iterate in the same session), and when I am satisfied I ask it to push the commit and open the PR.

Two things can still go wrong after this step, and I think it is worth being clear about both.

If the change turns out to be wrong after I accepted it. The agent works on my local copy and commits there. If I pushed that commit and then find a problem, the way back is the ordinary one in git: undo the commit with a new commit, so the history stays intact and nobody has to rewrite what is already shared:

git revert HEAD

HEAD is the last commit, so this creates a new commit that cancels exactly what the agent added (in our example, the "done" flag). I do not try to 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 the first time (for instance: "the flag must survive a page reload"). This is the same idea as the rest of the article: 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. During review the agent can find a real problem that does not belong to the current change. It does not fix it silently and it does not drop it: it writes it into deferred-work.md (the DEFER outcome in the diagram). Each entry names the story it came from, a one-line summary and the evidence. I read this file after every run. It is a backlog written by the agent, and a backlog nobody reads is where problems go to be forgotten. Reading it is part of my responsibility as the human who controls the result: for each entry I decide whether it is a new change to run later, 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 no longer one change. It 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 files that the previous step wrote.

Every step runs in a fresh chat (/clear first). I show the real commands, and I name the files each step reads and writes. I do not show what is inside them: that is for the next article.

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.

A coach runs the session in the stance I choose: facilitator (no ideas from the coach), creative partner (ideas traded) or ideate for me. It reads nothing, because the idea is in the command. It writes a run folder under _bmad-output/brainstorming/ with brainstorm-intent.md (my decisions, kept apart from the ideas the coach offered) and a .memlog.md. If the idea is still half-formed there are two more analysis skills, /bmad-forge-idea to pressure-test it and /bmad-deep-recon to research 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 _bmad-output/brainstorming/brainstorm-todo_list-<date>/brainstorm-intent.md as the main input and treat its "Decisions" table as settled.

The skill asks whether I want to create, update or validate, and whether I take the Fast path or the Coaching path. It reads brainstorm-intent.md and writes brief.md, addendum.md (the depth that does not belong in the brief) and a .memlog.md, in _bmad-output/planning-artifacts/briefs/. Then, in a fresh chat, I validate it 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.

The PRD is the source of the product definition, and every later document derives from it. The skill has three intents, create, update and validate, and a Fast path or a Coaching path. Functional requirements get stable ids (FR-1, FR-2, ...), and what the skill inferred is tagged [ASSUMPTION] so that I can correct it. It reads the brief, the addendum and the intent, and writes prd.md and a .memlog.md in _bmad-output/planning-artifacts/prds/. Validate and update are two more commands:

/bmad-prd validate the PRD at <prd path>

/bmad-prd update the PRD at <prd path>: <what to change>

Edits belong in the PRD, not in the stories, so the documents derived from it can be generated again. This is the whole point of the design.

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.

The skill captures my vision and does not impose its own. It reads the PRD and writes two peer documents, DESIGN.md (how it looks) and EXPERIENCE.md (how it behaves), in _bmad-output/planning-artifacts/ux-designs/, with mockups when I ask to see options. It is optional: I would skip it only if I accept designing those details later, during the builds. A fresh chat validates it:

/bmad-ux validate the UX documents at <ux folder>

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.

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. The skill gives a decision a stable id (AD-1, AD-2, ...) only if the call is non-obvious and a real trade-off. In coaching mode it shows me the alternatives and I choose. In coaching mode it also writes SOLUTION-DESIGN.md, a plain-language companion for people who read the project without building it (the spine wins if the two differ). It writes ARCHITECTURE-SPINE.md, that companion and a .memlog.md in _bmad-output/planning-artifacts/architecture/. This is where my review matters most, because a wrong shared decision spreads to every story:

/bmad-architecture validate the architecture at <architecture path>

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.

It reads the PRD, the UX documents and the spine, and writes one file, _bmad-output/planning-artifacts/epics.md. 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

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 (/bmad-prd update, /bmad-ux, /bmad-architecture, or /bmad-create-epics-and-stories again) and run the check again. If something major changes later, there is a command for that too:

/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

It reads epics.md and writes _bmad-output/implementation-artifacts/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

/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, with the diagram as the guide. It reads the story in epics.md, the architecture spine and, for UI work, DESIGN.md and EXPERIENCE.md. It writes the code, a local commit, a spec file for the story (spec-1-1-<slug>.md), an epic-1-context.md on the first story of the epic, and it appends what does not belong to the story to deferred-work.md. It also syncs sprint-status.yaml: the story moves to review. 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: they set the patterns for the rest.

Step 10: Retrospective (close the epic):

/bmad-retrospective 1

When the stories of the epic are finished, 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. The result is a retrospective with findings, action items and an acceptance decision. 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

So far I have shown commands. 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. The installed version and modules, one row per skill, the user and project names, the output folders, 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.

This is the layout BMAD leaves on disk for the todo list.

<prj_root>/_bmad/
  _config/manifest.yaml          installed version, modules, coding tools
  _config/skill-manifest.csv     one row per installed skill
  core/config.yaml               user name, project name, languages, output folders
  bmm/config.yaml
  custom/config.toml             team overrides, committed to the repo
  custom/bmad-build.toml         facts every build session treats as context
  scripts/memlog.py              the script that appends to the .memlog.md files

<prj_root>/_bmad-output/
  brainstorming/brainstorm-todo_list-<date>/
    brainstorm-intent.md
    .memlog.md
  planning-artifacts/
    briefs/brief-todo_list-<date>/            brief.md, addendum.md, .memlog.md
    prds/prd-todo_list-<date>/                prd.md, .memlog.md
    ux-designs/ux-todo_list-<date>/           DESIGN.md, EXPERIENCE.md, .memlog.md
    architecture/architecture-todo_list-<date>/
      ARCHITECTURE-SPINE.md, SOLUTION-DESIGN.md (coaching mode), .memlog.md
      reviews/VALIDATION-REPORT.md
    epics.md
  implementation-artifacts/
    sprint-status.yaml
    epic-1-context.md
    spec-1-1-create-the-project-with-the-quality-gate.md
    deferred-work.md

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 through the memlog.py script and never edited by hand. This is the shape of one (the lines are illustrative, for the todo PRD):

---
topic: Todo List PRD
updated: 2026-11-01T12:10
---

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

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 does not keep one log for all the sessions: each document has its own memlog. If I want the view across the steps (which session ran which skill, and what it read and wrote), 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. Writing it down is where the work starts.
2. Size comes first. One session, one epic and one project need different amounts of process. BMAD gives me a single command for the small change and a planning path for the large one, 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. That is what keeps a wrong decision from being 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. A change starts in the source document, so the later ones can be regenerated.

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.