Skip to content
AI Developer Toolkit

The BMAD Method: agile roles as agents

The BMAD Method (Breakthrough Method of Agile AI-driven Development) is an open-source framework from BMad Code that installs agile roles, from analyst to developer, as agent skills in Claude Code, Codex and Cursor. Planning skills write a PRD, architecture and epics; bmad-build implements each story. Since v6.12.0, it investigates before deciding how much spec and review a change needs.

Your product manager wants a PRD before anyone writes code, your architect wants decisions written down, and your developers want to hand a story to an agent and get back a tested pull request. Without a shared process, each person prompts the agent differently, the PRD never reaches the agent that writes the code, and a one-line fix gets the same ceremony as a new billing feature.

This page is for the developer who runs BMAD and the tech lead who decides whether to adopt it. It takes one feature, spend alerts for workspace owners, from PRD to retrospective, with a pinned install, copy-paste prompts, a table of which gate proves what, and a rule for when a lighter framework wins.

Which agents does BMAD install, and what does each one write?

Section titled “Which agents does BMAD install, and what does each one write?”

Persona skills (bmad-agent-*) give the agent a name, a voice and a menu. Workflow skills do the work. You can call a workflow skill directly; the persona adds conversation style, not capability.

Persona skillRole (name in the default config)Menu dispatches toLeaves behind
bmad-agent-analystBusiness analyst (Mary)bmad-product-brief, bmad-prfaq, bmad-deep-recon, bmad-brainstorming, bmad-project-contextA product brief, PRFAQ, research summary or AGENTS.md block
bmad-agent-pmProduct manager (John)bmad-prd, bmad-create-epics-and-stories, bmad-sprint-planning, bmad-correct-coursePRD, epics.md, sprint change proposals
bmad-agent-ux-designerUX designer (Sally)bmad-uxDESIGN.md and EXPERIENCE.md
bmad-agent-architectSystem architect (Winston)bmad-architecture, bmad-sprint-planningA short architecture document
bmad-agent-devSenior software engineer (Amelia)bmad-build, bmad-code-review, bmad-qa-generate-e2e-tests, bmad-sprint-planning, bmad-retrospectiveCode, a spec per story, review and retro records

BMAD writes into two output folders, set in _bmad/bmm/config.yaml, plus the skill folders for each tool:

  • Directory_bmad/ installer-managed config, scripts and help catalog
    • bmm/config.yaml output paths, languages, skill level
    • Directorycustom/ your team overrides (config.user.toml stays personal)
      • …
  • Directory_bmad-output/
    • Directoryplanning-artifacts/ brief, PRD, UX, architecture, epics.md
      • …
    • Directoryimplementation-artifacts/
      • sprint-status.yaml story states: backlog → ready-for-dev → in-progress → review → done
      • spec-1-2-threshold-check.md one spec per story, written by bmad-build
      • deferred-work.md goals split off during planning
    • Directoryspecs/spec-<slug>/ SPEC.md from bmad-spec
      • …
  • Directory.claude/skills/bmad-*/ Claude Code
    • …
  • Directory.agents/skills/bmad-*/ Codex and Cursor
    • …

bmad-help reads the catalog in _bmad/_config/ and your artifacts, then names the next skill to run.

Install BMAD and wire it into your agent

Section titled “Install BMAD and wire it into your agent”

BMAD needs Node.js for the installer and uv on the PATH: bmad-build renders its workflow with uv run and stops if uv is missing. Persona skills work without it, which hides the problem until the first build.

  1. Install into the repository root, pinned, for every agent your team uses (terminal):

    Terminal window
    uv --version                     # bmad-build halts without it
    npx bmad-method@6.12.0 install --directory . --modules bmm \
      --tools claude-code,codex,cursor --yes

    --modules bmm is the BMad Method module; the core module comes with it. --tools is required for a non-interactive --yes install; npx bmad-method@6.12.0 install --list-tools prints every supported ID and its target folder.

  2. Check where your tool found the skills:

    The installer writes 29 skills to .claude/skills/. Type /bmad-help in a session to confirm they load; each skill is also a slash command, such as /bmad-build.

  3. Commit _bmad/, .claude/skills/bmad-* and .agents/skills/bmad-*, so every teammate runs the same version. Upgrade on purpose, in its own pull request: rerun npx bmad-method@<version> install in the repository and choose the update path the installer offers.

The plugin track follows BMAD’s main branch (6.13.0-next on 2026-09-26) and ships 21 skills rather than 29:

/plugin marketplace add bmad-code-org/bmad-plugins
/plugin install bmad-method@bmad

Pick one track for the whole team. The npm installer pins a version per repository; the plugin moves with main, where skill names are still changing.

How does bmad-build decide how much ceremony a change needs?

Section titled “How does bmad-build decide how much ceremony a change needs?”

Before 6.12.0, Build chose a path before looking at the code, so rigour followed how a change looked, not what it was. The v6.12.0 release notes put the change in one sentence: “Build decides how much ceremony a change needs after investigating it, not before.”

Step 2 of bmad-build searches the codebase first, without asking you anything, and then records three facts:

FactWhat countsExamples
Intent gapsThings the request does not say, the code cannot settle, and you would notice in the resultWhich role may edit the budget; whether alerts repeat
IrreversiblesAnything that cannot be undoneA migration, deleting or rewriting data, sending email, a deploy or config trigger
FootprintHow many files change, and anything new that other code will callA new table, a new public function, a new endpoint

The route follows from those facts:

  • One-shot. No intent gaps, nothing irreversible, and a small footprint. The spec keeps two sections, ## Intent and ## Implementation Notes, and the agent implements, reviews and commits in one session. If implementation uncovers a gap, an irreversible step or growing scope, the agent stops, restores the full spec sections and routes back to planning.
  • Dispatch. Anything else. The agent writes the full spec: intent, boundaries, an I/O and edge-case matrix, a code map, tasks with Given/When/Then acceptance criteria, and verification commands. Every intent gap becomes an open question you must answer. You approve the spec at a checkpoint; a fresh subagent implements it with the spec as its only source of truth; then three review layers run in parallel.

Every spec targets one user-facing goal and 900–1,600 tokens; above that, BMAD offers to split secondary goals into deferred-work.md. Neither limit is a hard gate.

Run a small change through the one-shot path

Section titled “Run a small change through the one-shot path”

Start small to see the routing. The repository is a Next.js and Postgres SaaS app; the change adds a budget line to the workspace settings header.

In Codex, start the prompt with $bmad-build; in Cursor, start it with “Use the bmad-build skill to”. Expect the agent to report its investigation, find no intent gaps and nothing irreversible, and write _bmad-output/implementation-artifacts/spec-workspace-budget-header.md with route: 'oneshot'. It then implements, runs its review layers, and creates a local commit. It never pushes.

If the agent routes this to dispatch instead, read why: “No budget set” versus a hidden header is a real intent gap.

Run a feature through the planning track

Section titled “Run a feature through the planning track”

The real feature is bigger: workspace owners get an email when agent spend passes 80% of the monthly budget. It touches billing data, sends email (irreversible) and needs a scheduled job, so it takes the planning track. Each step below is a separate session; the files carry the context between them.

  1. Write the PRD with the product manager. bmad-prd interviews you, then writes the PRD under _bmad-output/planning-artifacts/. Answer as the product owner would; the agent’s questions are the value.

  2. Record the architecture decisions. bmad-architecture writes a short document of the decisions that keep separately built stories consistent: where spend is aggregated, what triggers the check, and how “one email per threshold per month” is made idempotent.

  3. Break the work into epics and stories. Run bmad-create-epics-and-stories. It writes epics.md. For this feature, expect one epic with three stories: store the budget, check thresholds, send and log the alert.

  4. Pass the readiness gate before any code. bmad-sprint-planning asks one question of the whole plan: could a developer implement these stories without inventing decisions that nothing records? It answers PASS, CONCERNS or FAIL. On PASS it generates sprint-status.yaml, which tracks every story. Partway through the epic, it looks like this:

    development_status:
      epic-1: in-progress
      1-1-workspace-budget-setting: done
      1-2-threshold-check: ready-for-dev
      1-3-alert-email-and-log: backlog
      epic-1-retrospective: optional

  5. Build one story at a time. bmad-build recognises an epic story, compiles epic-1-context.md once from the planning documents, and writes spec-1-2-threshold-check.md. Story 1-2 sends nothing but decides when email goes out, so expect the dispatch route, a spec with an I/O matrix, and open questions at the checkpoint.

    At the checkpoint, choose Approve and stop if you want implementation in a fresh session, or Approve and continue to keep going. After approval, everything inside <frozen-after-approval> (intent, boundaries and the I/O matrix) is locked, and only you can change it.

  6. Review and hand over. Build finishes with its review layers, marks the spec done, moves the story to review and makes a local commit. It never marks the story done. Run bmad-walkthrough for a guided human review, then run bmad-code-review on each story: it is the step that closes a story, setting it to done once no unresolved high or medium findings remain. If your team reviews in the pull request instead, set the story to done in sprint-status.yaml by hand after the pull request merges.

  7. Close the epic with evidence. When all three stories are done, run the retrospective.

    The verdict is accepted, accepted-with-open-items or rejected. Any story that is not done forces rejected unless a human overrides it.

For a smaller scope, skip the PRD: bmad-spec condenses a brief into _bmad-output/specs/spec-<slug>/SPEC.md and optional stories.yaml, which bmad-build then takes with a story ID. Do not mix the two tracks in one epic.

Adapt bmad-build to your repository

Section titled “Adapt bmad-build to your repository”

Team overrides live in _bmad/custom/, which the installer never touches. Lists append to the defaults and strings replace them. This file makes every build load your testing conventions and your agent instructions, and records the pull-request hand-off:

# _bmad/custom/bmad-build.toml — committed, applies to the whole team
[workflow]
persistent_facts = [
  "file:AGENTS.md",
  "file:docs/testing.md",
]
on_complete = "Print the exact gh pr create command for this branch, with the spec path in the body. Do not run it."

Personal preferences, such as opening each finished spec in your editor, go in _bmad/custom/bmad-build.user.toml. Run bmad-customize to author overrides interactively; it knows every customizable field.

To stop the implementing agent from editing the plan, deny writes to the planning folder in build sessions only. Planning sessions (bmad-prd, bmad-architecture, bmad-create-epics-and-stories, bmad-ux) and bmad-correct-course write to that folder, so a team-wide deny in .claude/settings.json would break them. In Claude Code, start each build session at the repository root (the ./ path is relative to it) with the rule on the command line. An Edit rule covers every built-in file-editing tool:

Terminal window
claude --disallowedTools "Edit(./_bmad-output/planning-artifacts/**)"

This blocks the edit tools, not shell writes such as sed or echo, so in every tool, not only Codex and Cursor, enforce the boundary in review with a CODEOWNERS rule on _bmad-output/planning-artifacts/, as described in permissions and sandboxing. Leave implementation-artifacts/ writable, because bmad-build updates its own spec and sprint-status.yaml.

How do you verify BMAD’s output without reading every line?

Section titled “How do you verify BMAD’s output without reading every line?”

Markdown proves nothing by itself, so give each gate an owner:

GateWhat it provesWhat it cannot proveSigns off
PRD with listed assumptionsThe behaviour the business wants is written downThat it is the right productProduct owner
Architecture decisionsStories will not contradict each other on shared concernsThat the code follows themTech lead
Readiness gate (bmad-sprint-planning)Every story traces to a requirement and backThat the requirements are correctTech lead
Spec checkpoint in bmad-buildThe I/O matrix and acceptance criteria describe the storyThat the code meets themEngineer who owns the story
Matrix test audit (build step 3)Each matrix row has a test that ran and passedBehaviour outside the matrixCI re-runs the tests
Review layers and triage logFindings were checked, with a verdict and evidence per findingThat nothing was missedEngineer, then PR reviewer
Code review (bmad-code-review) → story doneNo unresolved high or medium findings remain on the storyThat the reviewers looked in the right placesEngineer who owns the story
Retrospective verdictThe epic met its acceptance criteria, with sourcesLong-term production behaviourProduct owner

The matrix audit counts a test that did not run as missing and forbids editing an expectation to match the code. Review triage logs every finding in the spec’s ## Review Triage Log with a verdict (high, medium, low, false or maybe-false) and its evidence. Neither replaces CI: the pull request carries the spec path, the matrix-to-test mapping and a green test run, the evidence bundle a reviewer reads instead of the whole diff. Write criteria as executable acceptance criteria, protect the oracle, and review the agent’s pull request by opening code only where a matrix row has no test or a file sits outside the code map.

When does BMAD’s role overhead pay for itself?

Section titled “When does BMAD’s role overhead pay for itself?”

BMAD costs you three things. Context: claude plugin details measures the plugin at ~1,676 tokens per session, and bmad-toolbox@bmad adds ~975. By our own count on 6.12.0 (2026-09-26), the npm install’s 29 skill descriptions total about 8,000 characters. Documents: a PRD, an architecture document, epics.md and one spec per story, each needing a human read. Churn: BMAD has been redesigned several times (v4 *agent commands, v6 skills, now the plugin route on main), so upgrades need their own pull request.

The roles earn that cost when a decision made in planning would otherwise be lost before implementation. Use this table to decide:

Your situationUseWhy
Product work with a product owner, several epics and hand-offs between peopleBMAD planning trackThe PRD, architecture and readiness gate carry decisions to the agent that writes the code
A team that already runs Scrum and wants stories, sprint status and retros in the repositoryBMADIts artifacts map to the ceremonies you already hold; see agile workflows with agents
A stream of bugs and small features on a working productbmad-build alone, or OpenSpecThe one-shot route keeps small changes cheap; OpenSpec also keeps a living spec of the system
A new service or feature that needs a gated, per-stage trailSpec KitConstitution, clarify and analyze stages with explicit gates
A solo developer whose problem is agents skipping tests, not lost requirementsSuperpowersDiscipline per task with less always-on context and no persona hand-offs
A one-line fix, a typo or a dependency bumpNo frameworkSince 6.12.0, bmad-build no longer starts itself for formatting, git tasks or interactive edits

A rule of thumb for the tech lead: adopt the planning track only when different people own the “what” and the “how”. When one developer owns both, bmad-build alone gives the sizing and review without the hand-offs. Compare every option side by side in spec-driven frameworks compared.

What breaks when you run BMAD on a real team?

Section titled “What breaks when you run BMAD on a real team?”

bmad-build halts at activation. Symptom: a failed uv run … render_skill.py command. uv is missing from the agent’s PATH. Recovery: install uv, restart the agent session, and run the skill again. Do not ask the agent to run the workflow directly: unrendered step files still contain template placeholders.

Old skill names do nothing. Symptom: /bmad-quick-dev or /bmad-create-prd is unknown after a fresh install. Deprecated shims are opt-in since 6.12.0. Recovery: use bmad-build and bmad-prd, or reinstall with --shims while you migrate.

Review asks you to paste prompts by hand. Symptom: build writes reviewer prompts under implementation-artifacts/ and halts, because the runtime could not launch subagents. Recovery: run each prompt in a separate session and paste the findings back, or build in Claude Code or Codex, which both have subagents.

Every review finds something. Symptom: a trivial change comes back with several findings. The Blind Hunter reviewer must report a minimum number of issues, scaled to the diff; triage is where findings are rejected. Recovery: read the triage log and check that each false verdict cites evidence.

The agent edits the plan to fit its code. Symptom: a story commit changes the PRD, the architecture or the frozen block of a spec, and the tests pass. Recovery: start build sessions with the --disallowedTools rule above, add the CODEOWNERS entry, and require that any change under planning-artifacts/ goes through bmad-correct-course in a planning session with write access, which produces a sprint change proposal instead of a silent edit.

Planning documents drift after the epic. Symptom: months later the PRD describes a feature that has since changed. Recovery: treat the retro as the end of the PRD’s life, and keep current behaviour in tests and a living spec (spec-driven development).

Two developers run two different BMADs. Symptom: one teammate’s agent offers skills the other’s lacks, because one installed the plugin from main. Recovery: pin one npm version and record it in AGENTS.md.

Where to go next with BMAD

Section titled “Where to go next with BMAD”
Agentic development frameworks compared BMAD next to every other framework, with context costs and where each fits.
Spec-driven frameworks compared Spec Kit, OpenSpec, BMAD and Superpowers on the same feature.
Agile workflows with agents Plan sprints to review capacity and bring flow data to the retrospective.
Executable acceptance criteria Turn each Given/When/Then criterion into a failing test before the build.
OpenSpec The lighter choice for a stream of changes to an existing system, with a living spec.
Evidence bundle What the pull request must carry so a reviewer can trust it without reading every line.

Written by

See what's new on the platform.

Privacy Policy Terms of Service Cookie settings