bmad-code-org/BMAD-METHOD v6.11.0 on GitHub

✨ Headline

Quick Dev becomes Build, the one official way BMad implements code. bmad-quick-dev → bmad-build, bmad-dev-auto → bmad-build-auto, the bmad-create-story → bmad-dev-story pair is deprecated, and Phase 4 is a single chain: bmad-sprint-planning → bmad-build → bmad-code-review.

The skill catalog gets a lot smaller. Core drops from fourteen skills to eight: three review skills and two editorial skills become lenses on one bmad-review, three research skills become bmad-deep-recon, and bmad-document-project plus bmad-generate-project-context become bmad-project-context. Every retired ID keeps working through a forwarding shim in v6-shims/ until the v7 cut.

Skills stop guessing and start reading evidence. bmad-retrospective judges an epic against its own artifacts, requires a source reference on every finding, and rejects an epic with unfinished stories instead of closing quietly. bmad-sprint-planning moves epic parsing, status merging, and summary computation into a tested Python script. bmad-project-context replaces generated documentation with one verified block in the repository's AGENTS.md.

Under the hood: a shared content-addressed snapshot renderer publishes an immutable, inspectable copy of exactly what ran; the bmm tree takes its verb-named shape, agents / plan / ship; and the installer's directory prompt no longer installs to a path you never typed. Across 560 files, the release deletes about 1,900 more lines than it adds.

💥 Breaking Changes

Quick Dev renamed to Build (#2651). bmad-quick-dev → bmad-build, bmad-dev-auto → bmad-build-auto; old IDs forward through shims. Dev agent (Amelia) menu QD → BD. Rename your customization files: _bmad/custom/bmad-quick-dev{,.user}.toml → bmad-build{,.user}.toml, same for bmad-dev-auto → bmad-build-auto. The shim offers the migration but requires explicit approval and never overwrites; declined or unavailable, it halts instead of forwarding, so unattended runs on the old name with a legacy customization file will refuse to start.
Build is the official Phase 4 loop; bmad-create-story and bmad-dev-story deprecated (#2637, #2641). The dev agent menu drops DS and CS, and both skills leave bmad-help recommendations and the workflow map. They move to v6-shims/ retained in full and still run when invoked by name. Removal rides the v7 cut.
Core cut to eight skills; review and editorial skills merge into bmad-review (#2603, #2608). bmad-review-adversarial-general, bmad-review-edge-case-hunter, bmad-review-verification-gap, bmad-editorial-review, bmad-editorial-review-prose, and bmad-editorial-review-structure become shims; their behavior becomes lenses set through [[workflow.lenses]], keyed by code. Shipped codes: adversarial, edge-case-hunter, verification-gap, structure, prose. bmad-spec moves from core into bmm, so core-only installs no longer get it. bmad-index-docs and bmad-shard-doc are removed outright.
Research trio consolidated into bmad-deep-recon (#2611). bmad-market-research, bmad-domain-research, and bmad-technical-research become shims forwarding with type pre-set; existing overrides are honored.
bmad-project-context replaces bmad-document-project and bmad-generate-project-context (#2674, #2698, #2700). Both become shims forwarding to setup intent. Analyst (Mary) menu DP → PC. Migrate overrides to _bmad/custom/bmad-project-context.toml. The deliverable changes shape: no generated overview, source-tree, or deep-dive pages and no project-context.md, just one verified block in AGENTS.md. An existing project-context.md still loads as a source. The deeper "explain this system and its rationale" altitude is a separate capability still to come.
bmad-check-implementation-readiness removed (#2659). Folded into bmad-sprint-planning, which opens with a readiness gate (PASS/CONCERNS/FAIL) that finds artifacts by content instead of the filename globs that missed SPEC.md and DESIGN.md. The IR trigger forwards there. Listed in removals.txt.
bmad-sprint-status deprecated to a forwarding shim (#2659). Forwards to bmad-sprint-planning's status view; SS survives by dispatching it with action=status. Migrate _bmad/custom/bmad-sprint-status.toml to bmad-sprint-planning.toml. Its unused data/validate modes (zero callers) are gone.
bmad-agent-tech-writer (Paige) retired (#2658). Paige's replacement joins soon as an optional installable agent. Listed in removals.txt.
Config moves to layered TOML, and uv with Python 3.11+ becomes a hard requirement for rendered skills (#2281, #2601). Config resolves _bmad/config.toml → config.user.toml → custom/config.toml → custom/config.user.toml; customization resolves {skill}/customize.toml → _bmad/custom/{skill}.toml → .user.toml. The per-module _bmad/bmm/config.yaml still ships and the older skills still read it, so this release is the migration, not the cutover. Rendered skills have no interpreter fallback: bmad-build and bmad-build-auto halt if uv is unavailable. Build drops its user_name greeting and user_skill_level tailoring, and document_output_language is now enforced on file writes.
Renderers halt on missing config keys and unreadable overrides (#2588). A {{.var}} absent from your merged config used to render as an empty string, and an unparseable _bmad/custom/<skill>.toml used to be ignored. Both now exit 1 with a clean halt: add the missing key, or fix or delete the override.
Build Auto contract: deferred-work.md and final_revision are gone (#2640, #2668). Deferred findings live in the spec's frontmatter deferred: list (Build keeps its ledger). ## Finalize sets status: done before the run's commit, so one commit covers the work and the finalized spec; compute a story's range as baseline_revision..<next story's baseline_revision>, or ..HEAD at exit.
Review layer labels and halt strings changed (#2550, #2564). Triage tags findings by review-layer id instead of the fixed blind / edge / vgap / auditor labels, and Build Auto's two intent-gap conditions unify to the single string intent gap.

🎁 Features

bmad-project-context — new skill (#2674, #2698, #2702). A conversation that produces one small verified block inside the repository's AGENTS.md instead of generated documentation. Four intents: setup, refresh, record (a mistake agents keep making), audit (re-verify and prune). You bring governance, standards, and frozen areas; the repo supplies the rest, verified. One admission test: anything derivable from source is read live and never stored, so pnpm test stays out while "the suite takes eleven minutes" goes in. Every write is shown first, it runs standalone with no BMad install, and it fires only when you name it — no routing on inferred intent.
bmad-deep-recon — research consolidated into one core skill (#2611). Three modes: draft a deep-research prompt for your own ChatGPT / Gemini / Grok / Perplexity subscription, process a finished report into a cited summary downstream skills reuse without reprocessing, or run the research here. Six type packs (market, domain, technical, competitive, user-voice, academic-lit) plus a select shape for choose-between decisions. Lives in core, so core-only and CIS installs get it. Analyst menu gains TS, CR, UV.
bmad-review — one review skill, many lenses (#2603, #2608). Document review and code review stop competing for the same trigger. Lenses are addable, replaceable, and disablable from _bmad/custom/bmad-review.toml, and bmad-prd, bmad-ux, bmad-architecture, and bmad-product-brief name explicit lenses in their doc_standards.
Verification-gap reviewer (#2535). A third parallel review layer asking "if this behavior broke, would any test fail?" rather than "is this wrong?", reporting untested behavior changes instead of bugs. Blind validation against seven real commits from a production HIPAA platform surfaced shipped regressions, including two its ground-truth rubric had missed.
Review layers are configurable (#2550). [[workflow.review_layers]] in bmad-code-review, bmad-build, and bmad-build-auto lets you add, replace, or disable a reviewer, including swapping in an external tool over bash and therefore a different model. An empty instruction disables a layer, a new id appends one, and defaults reproduce the previous prompts exactly.
Intent Alignment Auditor (#2560). A fourth default Build Auto review layer fed the verbatim invocation intent alongside the diff, with an intent-ambiguity halt in planning and a scope rule: only the intent, never the spec's own scope language, can justify deferring a finding. The post-implementation acceptance-criteria checkbox ritual is gone.
bmad-retrospective rebuilt as an evidence-based epic review (#2612, #2665). Five phases over the epic's real artifacts, with aggregate views no single diff hunk shows: architecture delta, duplication, god-class growth, pattern divergence, spec reconciliation. Team discussion is now opt-in, delegating to bmad-party-mode seeded with real findings. New -H / --headless flag, with -H <epic> as the stable orchestrator interface. It can also retro an epic that exists only as a spec folder, the shape unattended Build Auto runs leave behind, writing {spec-folder}/RETROSPECTIVE.md without touching sprint status.
sprint-planning rebuilt around a deterministic script core (#2659). scripts/sprint_plan.py (generate / status / validate, JSON-only output, 37 tests) owns epic parsing, ordering, preserve-never-downgrade status merging, story-file detection, action_items carry-over, atomic writes, drift checks, and the status summary. Legacy v6 statuses (drafted, contexted) are normalized rather than treated as illegal, and refresh preserves custom keys, comments, and project_key / tracking_system / story_location. Judgment stays with the LLM, and the skill falls back to reading the file directly if a script path fails. sprint-status.yaml format is unchanged, so Build's sprint sync is unaffected.
Sprint-status repair and validation (#2659). "Fix sprint status" rebuilds a broken or drifted file: subagents gather evidence, you confirm the proposed state, then one generate --fresh --set key=status ... writes a pristine file, the only path allowed to downgrade a status. "Validate sprint status" reports structural problems without writing.
Inspectable workflow snapshots (#2601, #2657). Skills render through a shared _bmad/scripts/render_skill.py publishing immutable, content-addressed snapshots under _bmad/render/, each with a manifest.json of renderer and source hashes, resolved values, and per-output hashes. Publishing is atomic, an existing generation is verified and reused, and a collision raises rather than overwrites.
stories.yaml contract between planning and execution (#2549, #2666). bmad-spec gains an optional Story Breakdown step emitting stories.yaml beside SPEC.md: an ordered sequence where list order is execution order, with id, title, description, spec_checkpoint, done_checkpoint, and invoke_dev_with, and deliberately no status. Build and Build Auto can both be dispatched by spec folder plus story id, so story specs live under {spec-folder}/stories/ with the spec that owns them.
The implementation handoff is a configuration key (#2561, #2629, #2635). [workflow] implementation_handoff holds the literal recipe passed to the coding subagent, so an organization can route implementation to a different model or an external CLI without forking the skill. The parent is barred from restating goals, listing files, or injecting acceptance criteria into the dispatch.
Configurable editor handoff at Build completion (#2652). The hard-coded VS Code launch becomes [workflow] open_spec, defaulting to the previous behavior; set it to an empty string to disable the launch without affecting spec generation. Examples ship for VS Code, Cursor, Windsurf, Zed, IntelliJ IDEA, Vim, and Emacs.
Matrix test coverage is audited (#2554). When a spec carries an I/O and Edge-Case Matrix, implementation checks every row has a covering test and that the test actually executed and passed: one that exists but was never registered, filtered in, or enabled counts as missing. Build Auto adds the blocked reasons matrix ambiguity and matrix test audit failed; Build halts and asks.
Antigravity CLI (AGY) as an installer target (#2551). A separate picker entry from the Antigravity IDE, installing to .agents/skills and ~/.gemini/antigravity-cli/skills, so the two never collide. Thanks to @bdsoha. Closes #2440.
Core-only installs are now possible (#2680). core was a locked, never-actionable checkbox in the module picker; it is no longer a row, and is still force-added and installed first.

🐛 Fixes

The installer could install to a directory you never typed (#2680). The directory prompt returned the focused autocomplete option rather than the typed text, and focus was sticky across edits, so a single stray ↑ silently selected the last directory in the list. Rebuilt on a plain text field whose value is the line.
--set core.<key> overrides were applied too late (#2671). They patched the TOML after install but never reached config collection, so artifact paths and the created directory still used _bmad-output/: exit code 0, no warning, and BMAD writing to the folder you had explicitly overridden. Core --set keys now fold into the option fields first.
Windows: persona resolver output is decoded as UTF-8 (#2687, #2688). Emoji-bearing persona data corrupted under a legacy locale such as cp1252, which broke bmad-party-mode outright. Fixed in party-mode and bmad-forge-idea, which share the resolver. Fixes #2682.
Verification-gap review stops demanding tests that verify nothing (#2646, #2647, #2662, #2663, #2683). No more pushing for tests that grep source or prompt files for wording, or that call a live model and judge its answer; exact-content assertions stay eligible when deterministic code constructs the output, and weakening a real test is still flagged. Across 16 reviewer runs, prompt-only diffs went from 2/2 false gaps to 0/2 with every genuine code finding preserved.
The adversarial reviewer drops its persona for a method (#2675). A/B piloting on Claude and Codex showed the "cynical, jaded reviewer" framing made no difference to residual-bug hit rate, while requiring at least ten concrete findings and asking what is missing did.
Phase 4 reviewers get their full contracts back (#2638, #2642). Routing the ship-path reviewers through bmad-review lenses had changed their semantics and output guarantees; bmad-code-review, bmad-build, and bmad-build-auto now own local review-prompts/*.md copies. Reviewers are dispatched by path to their prompt file instead of having the parent transcribe it, which was truncating instructions.
Review triage judges findings independently (#2555). Only findings with the same claim and the same required action are deduplicated, so similar-looking findings stop collapsing or being silently dropped.
Follow-up review is scored, not judged (#2580). followup_review_recommended is arithmetic over the final pass's patch-triaged findings: true if any high, or if 3 × medium + 1 × low ≥ 5. Patches route back to the implementation subagent and verification re-runs after they land, so runs converge.
Commits match the reviewed diff (#2563). Finalize commits every file in the reviewed diff, tracked and untracked, amends if short, and declares anything still dirty as residual artifacts. The implementation subagent must also declare files changed beyond the spec's tasks.
Intent-gap halts preserve the attempted change (#2564). The work is saved as a patch under {implementation_artifacts} and named in the halt output before the tree is reverted, so you can git apply it and set the spec to in-review to resume review instead of re-running.
Review fan-out is atomic (#2565). Every reviewer subagent is spawned before any output is read, removing an observed serialized fan-out of over two minutes.
Code review honors "no spec" (#2645). Declaring no spec is respected instead of prompting for one anyway, and omitting a spec path no longer silently drops you into no-spec mode.
No more epic and story reference comments in generated code (#2544). The dev agent stops writing # Epic: X / # Story: PROJ-42 markers and explanatory noise into source. This lands as constraints on bmad-agent-dev, so it covers Amelia-driven work rather than the bmad-build path. Fixes #2538.
Planning isolates deep exploration (#2557). The planner was duplicating exploration in parallel with the subagent it had just dispatched; it now reads narrow code inline and plans from returned summaries.
Deployed docs validation findings (#2644). Wide localized tables clipped on mobile, Phase 4 summary rows named a skill unnecessarily, and slash-terminated SITE_URL values produced double-slash canonical and LLM URLs.
Installer directory-prompt tests are deterministic (#2685). They no longer simulate a terminal, which was producing 11 false failures under TERM=dumb and showing contributors on plain shells a red run on a correct tree.
The installer called uv optional while Build already required it (#2704). It printed "becoming the de facto standard" as a Tip inside the "BMAD is ready to use!" box, and discarded the probe's result, so you could install, see green, and hit a halt on the first bmad-build. The warning now names the skills that halt and repeats in the post-install summary; a python3 probe runs only when uv is absent. Still never blocks — core-only and CI installs don't render skills.
src/ no longer assumes a system Python (#2704). The 25 remaining python3 resolve_customization.py call sites move to uv run; below 3.11 they had been failing into their hand-merge fallback silently. Four sites that spawned Python purely to open an HTML file now use the platform opener (open / xdg-open / start). With every script invoked through uv run, which provisions an interpreter from each script's own requires-python, Python leaves the prerequisites: you need Node and uv.

🗑️ Removed

bmad-index-docs and bmad-shard-doc (#2603). Retired with no replacement, listed in removals.txt so existing installs clean up. The "shard large documents" how-to is gone from all five locales.
Whiteport Design Studio retired from the module picker; key features will merge into the bmad-ux package coming soon (#2680). bmad-method-wds-expansion is marked deprecated and hidden from the picker when not installed. Existing installs still see it, still select it, and are never silently stripped. Deprecation warnings now fire on every flow, interactive and CLI alike, which also closes the same silent gap for bmad-automator.
Non-interactive installation pages (#2670). Removed in all five locales, with redirects to the regular installation guide.
The adversarial-review explanation page (#2679). Removed in all five locales; the material now lives with the lens itself.