agentharnesses.dev

A field guide to agentic coding harnesses, for teams that have been told to adopt one.


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.

MaintainerBrian Madison (BMad Code, LLC)
CategorySpec-driven toolkits
HostsClaude 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
Components28 skills
LicenseMIT
Version6.13.0-next
Source codehttps://github.com/bmad-code-org/BMAD-METHOD
Websitehttps://bmadcode.com
Docshttps://docs.bmad-method.org
DeepWikihttps://deepwiki.com/bmad-code-org/BMAD-METHOD
Last researched2026-09-28, at commit ec9a46e

Features

Definitions are on the compare page.

FeatureSupportedNotes
Stages of work it covers
Brainstormingyesbmad-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 plansyesEvery 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 firstpartialOnly 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 processpartialNo 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 reviewyesbmad-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.
VerificationyesPlans 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 capturepartialbmad-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 PRpartialbmad-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 pointyesThe bmad skill reads what is installed and written and recommends the next skill, invoking it if you ask. Nothing loads it automatically.
Automatic activationyesNo 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 hooknoNo hooks. The docs suggest restating key rules in CLAUDE.md or AGENTS.md.
Blocking hooksnoNo hooks. Render scripts halt on missing config, but nothing blocks the agent.
Subagentsyes
Parallel agentsyesReviewers launch together, and investigation, research, and repository scans fan out. Implementation is sequential.
Git worktreespartialThe 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 hostsyes
Per-project setupyesThe 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 extensionsyesbmad-customize writes TOML overrides for personas, facts, menus, templates, reviewers, and the implementation handoff. The separate BMad Builder module authors new skills.
No extra servicesyesNeeds 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:

  1. Obvious, low-risk edits (a typo, formatting, config) need no skill.
  2. One session of work goes straight to bmad-build, with no planning skill first.
  3. Bigger work with enough material (notes, a ticket, a brief, a PRD) goes to bmad-spec, then bmad-preview-ticketing with the spec folder, then one bmad-build per story.
  4. Bigger work without enough material first runs the skill that supplies what is missing: bmad-forge-idea or bmad-brainstorming when there is no clear customer or problem, bmad-prfaq when you doubt the idea, bmad-product-brief or bmad-prd for requirements, bmad-ux for screens and flows, bmad-architecture when separately built parts must fit together. Each result feeds bmad-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:

  1. 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.
  2. 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."
  3. 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.
  4. 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.
  5. Present. Marks the plan built and makes one local commit with a conventional message. It never pushes. It offers to open a pull request or start bmad-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

How it steers the agent

There are no hooks. Steering is written into the skills, with scripts for the mechanical parts:

Files it writes

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

When not to

Sources