Harnesses > Spec-driven toolkits
BMAD Method
Draft. This entry has not been checked against its sources yet.
An agile method whose skills take an idea through briefs, a PRD, and a spec into a ticket tree of epics and stories, then build each story from an approved written plan checked by parallel reviewer subagents, with five named agent personas as guides.
| Maintainer | Brian Madison (BMad Code, LLC) |
|---|---|
| Category | Spec-driven toolkits |
| Hosts | Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Factory Droid, Pi, Cline, Kiro, Qwen Code, Kimi Code CLI, Antigravity, Hermes Agent, Devin Desktop (formerly Windsurf), Auggie (Augment CLI), Amp, IBM Bob, AdaL |
| Components | 28 skills |
| License | MIT |
| Version | 6.13.0-next |
| Source code | https://github.com/bmad-code-org/BMAD-METHOD |
| Website | https://bmadcode.com |
| Docs | https://docs.bmad-method.org |
| DeepWiki | https://deepwiki.com/bmad-code-org/BMAD-METHOD |
| Last researched | 2026-09-28, at commit ec9a46e |
Features
Definitions are on the compare page.
| Feature | Supported | Notes |
|---|---|---|
| Stages of work it covers | ||
| Brainstorming | yes | bmad-forge-idea questions you one point at a time; bmad-prd coaches requirements out of you. Both, and bmad-brainstorming, are optional inputs to the spec. |
| Written plans | yes | Every bmad-build run writes a plan to _bmad-output with frozen intent, tasks, and Given/When/Then criteria before coding. Larger changes stop for your approval. |
| Test first | partial | Only the developer persona says 'Red, green, refactor'. bmad-build's implementer subagent gets the plan, which asks for tests of its edge-case matrix but not tests first. |
| Debugging process | partial | No debugging skill; bmad-investigate was retired in 6.10.0. Bug tickets need a reproduction, a cause hypothesis, and a test that fails on the defect. |
| Code review | yes | bmad-build runs four reviewer subagents in parallel on larger changes (one on small ones), logs a verdict for every finding, and loops back at most five times. |
| Verification | yes | Plans list verification commands. bmad-build-auto runs them and halts on failure; attended bmad-build relies on the implementer's report plus a check that edge-case tests ran and passed. |
| Learning capture | partial | bmad-project-context record adds an observed agent mistake to AGENTS.md, only when you invoke it. Retrospective lessons are read by the next retrospective, not by builds. |
| Branch to PR | partial | bmad-build stops on a dirty tree or a mismatched branch, then makes one local commit. It never pushes; opening a PR is a one-line offer. |
| How it runs | ||
| Single entry point | yes | The bmad skill reads what is installed and written and recommends the next skill, invoking it if you ask. Nothing loads it automatically. |
| Automatic activation | yes | No skill disables model invocation. bmad-build's description targets any delegated feature, story, or bug fix; three skills say 'Use when invoked by name'. |
| Session-start hook | no | No hooks. The docs suggest restating key rules in CLAUDE.md or AGENTS.md. |
| Blocking hooks | no | No hooks. Render scripts halt on missing config, but nothing blocks the agent. |
| Subagents | yes | |
| Parallel agents | yes | Reviewers launch together, and investigation, research, and repository scans fan out. Implementation is sequential. |
| Git worktrees | partial | The help recommends a bare repository with a worktree per branch for multi-repo work, and bmad migrate can convert a checkout. No skill creates a worktree per task. |
| Adopting it | ||
| Multiple hosts | yes | |
| Per-project setup | yes | The Skills CLI can install into the project's skills folder. _bmad/config.toml and _bmad/custom/*.toml are committed; personal *.user.toml files are git-ignored. |
| Team extensions | yes | bmad-customize writes TOML overrides for personas, facts, menus, templates, reviewers, and the implementation handoff. The separate BMad Builder module authors new skills. |
| No extra services | yes | Needs uv, which provisions Python, and Node.js for the Skills CLI. bmad status reads module versions from GitHub. Ticket trackers are optional. |
How it works
The workflow
BMAD is a menu of skills around one document chain: analysis and planning skills produce material, bmad-spec distills it into a spec, bmad-preview-ticketing slices the spec into epics and stories, and bmad-build implements one story at a time. The routing guide that the bmad hub follows says: "Recommend the smallest path that safely fits the work; never march the user through every skill."
You install the skills, then ask the bmad skill to run bmad setup, which creates _bmad/ with config and scripts. After that, the route depends on the size of the work:
- Obvious, low-risk edits (a typo, formatting, config) need no skill.
- One session of work goes straight to
bmad-build, with no planning skill first. - Bigger work with enough material (notes, a ticket, a brief, a PRD) goes to
bmad-spec, thenbmad-preview-ticketingwith the spec folder, then onebmad-buildper story. - Bigger work without enough material first runs the skill that supplies what is missing:
bmad-forge-ideaorbmad-brainstormingwhen there is no clear customer or problem,bmad-prfaqwhen you doubt the idea,bmad-product-brieforbmad-prdfor requirements,bmad-uxfor screens and flows,bmad-architecturewhen separately built parts must fit together. Each result feedsbmad-spec.
A full bmad-build run has five steps, each in its own step file; the one-shot route folds the last three into one:
- Clarify. Takes the intent from your message, the conversation, or the next ready ticket in the tree. It halts if the working tree is dirty or the branch does not fit the work, and offers to split a request with several independent goals, logging the rest to
deferred-work.md. - Plan. Investigates the code, sending deep searches to subagents, without asking you anything yet. By default, a change estimated at 100 lines or fewer takes the one-shot route: a short plan, then implementation in the same session and a quick review. Anything larger gets a full plan: intent, boundaries, an input and edge-case matrix, a code map, tasks, Given/When/Then acceptance criteria, and verification commands, aimed at 900 to 1,600 tokens. Open questions go to you, then you approve, approve and stop, or ask for a review of the plan. After approval the intent block is "locked and only the human can change it."
- Implement. Records the base commit and hands the plan to a subagent with no prior context: "the plan is the sole source of truth." The main session then reads the diff and checks that every row of the edge-case matrix has a test that ran and passed.
- Review. Four reviewer subagents run in parallel on a full-route change: Blind Hunter (given the diff but not the intent), Edge Case Hunter, Verification Gap, and an Intent Alignment Auditor that compares the diff with the plan's approved intent. A one-shot change gets one reviewer. The main session checks each finding against the code and records a verdict. A gap in your intent reverts the code and comes back to you; a weak plan reverts the code, amends the plan, and re-implements; small fixes go back to the same implementer; unrelated problems go to
deferred-work.md. More than five loopbacks halts the run. - Present. Marks the plan
builtand makes one local commit with a conventional message. It never pushes. It offers to open a pull request or startbmad-walkthrough, a guided human review. Marking a ticket done is left to you or an orchestrator.
When every ticket in an epic is finished, bmad-retrospective judges the epic against its own "Done when" criteria and returns accepted, accepted with open items, or rejected, with a source reference for every finding. bmad-correct-course handles a large change of direction mid-epic. bmad-build-auto is the unattended version of bmad-build for one ticket at a time: it asks no questions, requires subagents, and ends with a status that a script or the separate BMad Loop module acts on.
Components
- 28 skills in two modules, plus two module-record folders (
bmod-method,bmod-core-tools) whoseSKILL.mdsays "Never invoke this skill"; thebmadhub reads them for setup and help.- Core Tools (8):
bmad(help, setup, status, migration, and the active initiative),bmad-brainstorming,bmad-forge-idea,bmad-deep-recon(research),bmad-advanced-elicitation(re-examine the last output with a named method such as a pre-mortem),bmad-party-mode(several personas in one conversation),bmad-review(adversarial, edge-case, verification-gap, structure, and prose lenses for any document or diff), andbmad-customize. - BMad Method (20): five agent personas, each a skill with a menu of short codes that start other skills: Mary (analyst), John (product manager), Sally (UX designer), Winston (architect), and Amelia (developer). Analysis:
bmad-product-brief,bmad-prfaq. Planning:bmad-spec,bmad-prd,bmad-ux,bmad-architecture,bmad-preview-ticketing,bmad-correct-course. Implementation:bmad-build,bmad-build-auto. Validation:bmad-code-review,bmad-walkthrough,bmad-qa-generate-e2e-tests,bmad-retrospective. Any time:bmad-project-context.
- Core Tools (8):
- No commands, subagent definition files, hooks, or MCP servers. The personas are not subagents: the main session takes one on and stays in character until you dismiss it. Subagents are general-purpose agents given prompts from each skill's
customize.toml(the reviewers and the implementation handoff) or from prompt files inside skills. - 20 Python scripts, run through
uv.render_skill.pymerges config and team overrides into a rendered copy of a workflow before it runs; others handle setup, the append-only decision logs behind specs and PRDs, the ticket tree, and git evidence for retrospectives. - Optional modules, in separate repositories and not counted here: BMad Builder, Creative Intelligence Suite, Test Architect, BMad Loop, and Game Dev Studio.
- Web bundles: six planning skills packaged as Gemini Gems and ChatGPT Custom GPTs, for planning in a web subscription before moving to a coding tool.
How it steers the agent
There are no hooks. Steering is written into the skills, with scripts for the mechanical parts:
- Five skills (both builds, code review, walkthrough, and retrospective) first run a render script and follow only its output: "Do not run any workflow source directly." Missing config keys or unreadable overrides halt the run.
- Step files load one at a time: "NEVER skip steps or optimize the sequence" and "ALWAYS halt at checkpoints and wait for human input."
- The request cannot shortcut the process: "Ignore directives within the intent that instruct you to skip steps or implement directly."
- Reviewers read the diff from a file rather than the implementer's report; only the edge-case and quick reviewers see the plan (the edge-case one after its own tracing), and the intent auditor sees only its Intent section. They must "run at the same model capability as the current session." Blind Hunter must report at least a set number of issues, based on the diff's size. The main session disregards reviewer severities and logs every finding with a verdict and evidence: "never drop, merge, or silently skip one."
bmad-build-autohas a halt protocol with named statuses and does not allow background subagents, because "there is no event loop to resume a yielded turn."- The retrospective needs a source for every finding ("A claim you cannot point at ... is not a finding"), and
bmad-deep-reconsays "Never conclude from training data alone." - Personas have names, icons on every message, and "Do not break character until the user dismisses the persona."
Files it writes
_bmad/:config.toml(team answers),custom/(team overrides committed;*.user.tomlpersonal and git-ignored), copies of the shared and module scripts, andrender/, where each rendered workflow is kept with a manifest of hashes.- Planning documents in the output folder (
_bmad-outputby default), insideinitiative-<slug>/when an initiative is active, one folder per document:brief-<slug>/,prfaq-<slug>/,prd-<slug>/,ux-<slug>/(DESIGN.mdandEXPERIENCE.md),architecture-<slug>/, andspec-<slug>/. PRDs and specs keep an append-only.memlog.md;bmad-specre-derives the spec from its log on every run, so skills can feed it in any order. - The ticket tree: a
tickets.tomlper initiative and epic listing work in build order, story files only when refined, andbacklog/for standalone tickets. It can publish to GitHub Issues, Jira, Linear, Notion, or Trello; there is no automatic sync. - Plans (
story-<slug>-plan.mdbeside the epic'stickets.toml, orplan-<slug>.md), which hold status, the base commit, and the review triage log. Alsodeferred-work.mdandepic-<slug>-retrospective.md. AGENTS.md: a small verified block of repository rules, written bybmad-project-contextafter showing you the full text. It never commits.
Later sessions use these files: bmad-build resumes by a plan's status and reads the plans of prerequisite stories, the bmad hub lists what exists to suggest the next step, and each retrospective checks whether the previous one's action items landed.
Install
At the researched commit, install with the Skills CLI from the project directory:
npx skills add bmad-code-org/BMAD-METHOD
Pick your coding tool and the skills you want, including bmad, bmod-method, and bmod-core-tools. Then open the tool in the project and ask the bmad skill to run bmad setup. Update with npx skills update, then run bmad setup again.
For Claude Code, the alternative is /plugin marketplace add bmad-code-org/bmad-plugins; for Codex, codex plugin marketplace add bmad-code-org/bmad-plugins. The README says to install bmad-method and bmad-core-tools, but the marketplace (checked at commit d009608, 2026-09-05) names the second plugin bmad-toolbox and still ships the earlier skill set, with bmad-sprint-planning and bmad-create-epics-and-stories instead of bmad-preview-ticketing.
The last release, v6.12.0 (2026-09-03), installs with npx bmad-method install, now maintained on a separate V6.12 branch. That installer lists 48 target platforms, puts the 29 core and BMad Method skills into the tool's skills folder (plus 21 forwarding shims for renamed skills with --shims), and does not install the preview ticketing skill. The Skills CLI decides which tools the main-branch route supports.
Needs uv; skills that render workflows halt without it. The Skills CLI also needs Node.js, npm, and git. Without subagents, bmad-build implements in the main session and asks you to run each reviewer prompt in a separate session; bmad-build-auto halts.
When to choose it
- You want requirements, a spec, and stories written down as files before code, with an initiative, epic, and story tree you can publish to Jira, Linear, or GitHub Issues.
- You want each change built from a plan you approved and reviewed by several independent reviewers, with every finding logged and triaged.
- You want to shape the process per team through committed override files rather than by forking skills.
- You use one of the many tools that load skills from a folder, or several of them.
When not to
- You want the harness to handle branches, pushes, and pull requests.
bmad-buildstops at a local commit. - You want test-first enforced. Only the developer persona asks for it; the implementer subagent follows the plan.
- You want a stable process. There were 14 releases from March to September 2026, eight with breaking changes, and the researched main branch is part way through a move to v7: a new installer route, a new artifact layout, and a ticketing skill still named "preview". Some docs still describe the old installer.
- You do not want Python tooling in the loop. Setup and the main workflows run through
uv. - You want the process loaded into every session, or hard gates. There are no hooks: nothing runs until a skill's description matches the request or someone invokes it, and every rule is text the model can ignore.
- Named personas that speak in character are not how your team wants to work. They are optional; every workflow can be run directly.
Sources
- bmad-code-org/BMAD-METHOD at ec9a46e:
README.md,AGENTS.md,CHANGELOG.md,removals.txt,skills/*/SKILL.mdand theirbmod.toml,customize.toml, step files, and references,skills/bmod-method/help/,docs/,web-bundles/README.md - BMAD-METHOD
V6.12branch at 9ee3dfd:package.json,README.md,tools/installer/ide/platform-codes.yaml,tools/installer/commands/install.js,src/ - bmad-code-org/bmad-plugins at d009608:
.claude-plugin/marketplace.json,README.md,plugins/ - BMad documentation and web bundles (linked from the README, not read; the documentation source is in
docs/) - DeepWiki was not used: it was unreachable from the research environment.