# The BMAD Method: agile roles as agents

URL: https://developertoolkit.ai/en/ecosystem/frameworks/bmad-method/
Description: Run one feature through BMAD's PM, architect and developer agents in Claude Code, Codex and Cursor, and learn when bmad-build's sizing makes the roles worth it.

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.

**Versions on this page**

Checked on 2026-09-26 against `bmad-method` **6.12.0** (npm `latest`, released 2026-09-04): `npx bmad-method@6.12.0 install` run in a scratch repository for `claude-code`, `codex` and `cursor`, the 29 skills it wrote, their step files, and the v6.12.0 release notes. The plugin track (`bmad-method@bmad`, 6.13.0-next) was installed with Claude Code 2.1.283 and codex-cli 0.157.1. Popularity: 53.5k GitHub stars and 6.0k forks on [bmad-code-org/BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD), read 2026-09-26. Stars measure attention, not usage.

## 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 skill | Role (name in the default config) | Menu dispatches to | Leaves behind |
| ------------- | --------------------------------- | ------------------ | ------------- |
| `bmad-agent-analyst` | Business analyst (Mary) | `bmad-product-brief`, `bmad-prfaq`, `bmad-deep-recon`, `bmad-brainstorming`, `bmad-project-context` | A product brief, PRFAQ, research summary or `AGENTS.md` block |
| `bmad-agent-pm` | Product manager (John) | `bmad-prd`, `bmad-create-epics-and-stories`, `bmad-sprint-planning`, `bmad-correct-course` | PRD, `epics.md`, sprint change proposals |
| `bmad-agent-ux-designer` | UX designer (Sally) | `bmad-ux` | `DESIGN.md` and `EXPERIENCE.md` |
| `bmad-agent-architect` | System architect (Winston) | `bmad-architecture`, `bmad-sprint-planning` | A short architecture document |
| `bmad-agent-dev` | Senior software engineer (Amelia) | `bmad-build`, `bmad-code-review`, `bmad-qa-generate-e2e-tests`, `bmad-sprint-planning`, `bmad-retrospective` | Code, 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:

- _bmad/ installer-managed config, scripts and help catalog
  - bmm/config.yaml output paths, languages, skill level
  - custom/ your team overrides (`config.user.toml` stays personal)
- _bmad-output/
  - planning-artifacts/ brief, PRD, UX, architecture, `epics.md`
  - implementation-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
  - specs/spec-&lt;slug&gt;/ SPEC.md from `bmad-spec`
- .claude/skills/bmad-*/ Claude Code
- .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

BMAD needs Node.js for the installer and [`uv`](https://docs.astral.sh/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):

   ```bash
   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:

     **Claude Code**

       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`.

     **Codex**

       The installer writes the same 29 skills to `.agents/skills/`. Invoke one with `$bmad-help` or `$bmad-build`, or describe the task and let Codex pick the skill from its description.

     **Cursor**

       BMAD's installer targets `.agents/skills/` for Cursor too, and writes nothing under `.cursor/`. Confirm the `bmad-*` skills appear in Cursor's skills list before you rely on them; Cursor's skills docs (checked 2026-10-12) list `.agents/skills/` as a project location; this page did not verify how Cursor lists the `bmad-*` skills. Ask for a skill by name in Agent chat: "Use the bmad-build skill to …".

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:

**Claude Code**

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

**Codex**

    ```bash
    codex plugin marketplace add bmad-code-org/bmad-plugins
    codex plugin add bmad-method@bmad
    ```

**Cursor**

    No Cursor plugin install was verified on 2026-09-26: the `bmad-plugins` marketplace ships Claude Code and Codex manifests only. Use the npm installer above with `--tools cursor`.

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.

**BMAD traps from older tutorials (checked against 6.12.0)**

- v4 guides use `*agent` commands and a `bmad-core/` folder. None of that exists in v6.
- `bmad-quick-dev`, `bmad-create-prd`, `bmad-dev-story` and other v6.0-era IDs are deprecated shims. A fresh 6.12.0 install leaves them out unless you pass `--shims`; use `bmad-build` and `bmad-prd` instead.
- There is no npm package called `bmad`. The package is `bmad-method`; it installs two equivalent commands, `bmad` and `bmad-method`.
- The `main` README names a `bmad-core-tools` plugin. The marketplace ships `bmad-method@bmad` and `bmad-toolbox@bmad`.
- `bmad-preview-ticketing` appears in the `main` docs but not in the 6.12.0 install or the plugin. The epic step there is `bmad-create-epics-and-stories`.
- In 6.12.0, `persistent_facts` defaults to empty, so nothing like `project-context.md` loads unless you add it (see the customization section below).

## 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](https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v6.12.0) 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:

| Fact | What counts | Examples |
| ---- | ----------- | -------- |
| **Intent gaps** | Things the request does not say, the code cannot settle, and you would notice in the result | Which role may edit the budget; whether alerts repeat |
| **Irreversibles** | Anything that cannot be undone | A migration, deleting or rewriting data, sending email, a deploy or config trigger |
| **Footprint** | How many files change, and anything new that other code will call | A 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

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.

**Copy-paste prompt: a small change that should route one-shot**

```text
/bmad-build Show the workspace's monthly AI budget in the header of the workspace settings page, formatted with the workspace currency, e.g. "Budget: €2,000 / month". If no budget is set, show "No budget set". Read the value from the existing workspaces.monthly_budget_cents column; do not change the schema.
```

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

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.

   **Copy-paste prompt: PRD from a one-paragraph brief**

   ```text
   /bmad-agent-pm Let's write the PRD. Feature: spend alerts. Workspace owners set a monthly AI budget; when month-to-date agent spend crosses 80% and again at 100%, every owner gets one email per threshold per month. Admins can see the alert history. Out of scope: hard spend caps, Slack alerts, per-user budgets. Success signal: no owner is surprised by an invoice above budget. Ask me about anything you would otherwise have to assume, one question at a time, and list every assumption you made at the end of the PRD.
   ```

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.

   **Copy-paste prompt: architecture from the PRD and the codebase**

   ```text
   /bmad-agent-architect Create the architecture for the spend-alerts PRD in _bmad-output/planning-artifacts/. Read the existing billing code first (src/server/billing/ and the usage_events table). Decide and record: where month-to-date spend is computed, what runs the threshold check and how often, how duplicate emails are prevented across retries and concurrent runs, and which existing email service is reused. For each decision, give the rejected alternative and why. Keep it to the decisions stories depend on.
   ```

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:

   ```yaml
   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
   ```

   **Copy-paste prompt: readiness gate only**

   ```text
   /bmad-sprint-planning Check implementation readiness only; do not generate tracking yet. For every story in epics.md, name the PRD requirement it traces to, and for every PRD requirement, name the story that delivers it. List orphans in both directions, any decision a story relies on that is not recorded in the architecture document, and any conflict between documents. End with PASS, CONCERNS or FAIL.
   ```

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.

   **Copy-paste prompt: build a story with a test gate**

   ```text
   /bmad-build story 1-2-threshold-check from sprint-status.yaml.
   Before the checkpoint, make sure the I/O & Edge-Case Matrix covers: spend at 79.99% and 80.00%, both thresholds crossed in one run, a budget changed mid-month, a workspace with no budget, and two concurrent runs.
   Every matrix row needs a test that fails before the change and passes after. Verification commands: npm test -- src/server/billing and npm run typecheck.
   Do not edit anything under _bmad-output/planning-artifacts/. If a planning document looks wrong, stop and tell me which line and why.
   ```

   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.

   **Copy-paste prompt: evidence-based retrospective**

   ```text
   /bmad-retrospective Retro epic 1. Judge the final state against the epic's acceptance criteria using the specs, diffs, commits and sprint-status.yaml. For each criterion, cite the test that proves it, or mark it UNPROVEN. Record every deferred item from deferred-work.md and every review finding that was deferred, and give the acceptance verdict.
   ```

   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

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:

```toml
# _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:

```bash
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](/en/workflows/harness/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?

BMAD's own name uses the generic phrase [AI-driven development](/en/glossary/ai-driven-development/), which says who leads the work, not who checks it. Markdown proves nothing by itself, so give each gate an owner:

| Gate | What it proves | What it cannot prove | Signs off |
| ---- | -------------- | -------------------- | --------- |
| PRD with listed assumptions | The behaviour the business wants is written down | That it is the right product | Product owner |
| Architecture decisions | Stories will not contradict each other on shared concerns | That the code follows them | Tech lead |
| Readiness gate (`bmad-sprint-planning`) | Every story traces to a requirement and back | That the requirements are correct | Tech lead |
| Spec checkpoint in `bmad-build` | The I/O matrix and acceptance criteria describe the story | That the code meets them | Engineer who owns the story |
| Matrix test audit (build step 3) | Each matrix row has a test that ran and passed | Behaviour outside the matrix | CI re-runs the tests |
| Review layers and triage log | Findings were checked, with a verdict and evidence per finding | That nothing was missed | Engineer, then PR reviewer |
| Code review (`bmad-code-review`) → story `done` | No unresolved high or medium findings remain on the story | That the reviewers looked in the right places | Engineer who owns the story |
| Retrospective verdict | The epic met its acceptance criteria, with sources | Long-term production behaviour | Product 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](/en/workflows/ship/evidence-bundle/) a reviewer reads instead of the whole diff. Write criteria as [executable acceptance criteria](/en/workflows/plan/acceptance-criteria/), [protect the oracle](/en/workflows/test/protect-the-oracle/), and [review the agent's pull request](/en/workflows/ship/agent-pr-review/) 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?

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 situation | Use | Why |
| -------------- | --- | --- |
| Product work with a product owner, several epics and hand-offs between people | BMAD planning track | The 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 repository | BMAD | Its artifacts map to the ceremonies you already hold; see [agile workflows with agents](/en/workflows/plan/agile-workflows/) |
| A stream of bugs and small features on a working product | `bmad-build` alone, or [OpenSpec](/en/ecosystem/frameworks/openspec/) | The 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 trail | [Spec Kit](/en/ecosystem/frameworks/spec-kit/) | Constitution, clarify and analyze stages with explicit gates |
| A solo developer whose problem is agents skipping tests, not lost requirements | [Superpowers](/en/ecosystem/frameworks/superpowers/) | Discipline per task with less always-on context and no persona hand-offs |
| A one-line fix, a typo or a dependency bump | No framework | Since 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](/en/ecosystem/frameworks/spec-driven-frameworks/).

## 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](/en/workflows/plan/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

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