The Complete BMAD Field Guide

This is a comprehensive, version-current reference for BMAD (Build More Architect Dreams), the open-source framework for building software with AI agents. It is meant to be the one place you look for everything about the framework: what it is and where it came from, how to install and run it on any machine, every module and skill, the full lifecycle, complete project runs, memory and measurement, models and tokens, benchmarking every dimension, team collaboration, extension, and the pitfalls to avoid.

Everything here tracks the latest stable release, v6.10.0 (July 3, 2026), and is grounded in the framework's own source and documentation.

On this page

• What this guide covers, and what it defers
• How to read it

What this guide covers, and what it defers

BMAD's research skill, Deep Recon, is deep enough to deserve its own set of documents, and they already exist in the companion Notes & gists collection: Foundations, Concept-by-concept how-to, Complete guide, and the Research reference. This field guide is the rest of the framework, and it references those four whenever research comes up rather than repeating them.

How to read it

The pages build on each other, but each stands alone as a reference. Start with Overview & invention for what BMAD is and the five-layer model that the rest of the guide leans on, then SDD vs agile for the idea that makes the whole method make sense. If you just want to get running, jump to Install & first run.

BMAD is host-agnostic: it runs on Claude Code, Cursor, Codex, and other agents. This guide's worked host is Claude Code, so every chapter closes with an "Under Claude Code" section that decodes how the chapter's idea lands on the host's real mechanics and internals (skills and progressive disclosure, subagents, plan mode, hooks, MCP, settings precedence, memory and compaction, prompt caching, and headless runs). The method stays portable; those sections are where it meets the machine. 👉

BMAD: what it is, and where it came from

This is the opening of a complete field guide to BMAD, the framework for building software with AI agents. It is meant to be the one reference you need for everything except the research skill (Deep Recon), which four earlier gists already cover in depth (foundation, how-to, complete guide, research reference). This guide is the rest of the framework: its history and philosophy, how to install and run it on any machine, every module and skill, the full lifecycle, complete project runs, memory and measurement, team collaboration, extension, and the pitfalls to avoid.

Everything here tracks the latest stable release, v6.10.0 (July 3, 2026).

On this page

• What BMAD is, in one paragraph
• The five-layer model
• Where it came from
• Version lineage
• How to read this guide
• Hands-on: prove BMAD is just files
• Under Claude Code: the harness BMAD rides on

What BMAD is, in one paragraph

BMAD is a packaged context-and-process layer for AI-driven development. It is not a model, a router, a database, or a hosted service. It is a set of installable skills, named agent personas, reviewable document templates, and configuration that makes an ordinary coding agent (Claude Code, Cursor, Codex, and others) behave like a disciplined cross-functional team. It does that by controlling what the agent loads, what it asks you, what it writes to disk, when it stops for review, and what the next agent receives. The whole thing is open source (MIT) and runs entirely inside your existing AI tool.

The five-layer model

The most useful mental model, and one later pages lean on, separates five things that the word "agent" usually blurs together:

5  Product work     research.md -> brief -> PRD -> architecture -> stories -> code
4  BMAD method      personas, workflows, steps, gates, templates
3  Skill adapter    bmad-* SKILL.md files in your IDE's discovery folder
2  AI host          Claude Code, Codex, Cursor, Gemini CLI, ...
1  Capabilities     filesystem, shell, git, web, subagents, MCP

Three consequences fall out immediately. Installing BMAD gives the model no new tools; it teaches a procedure for the tools your host already has (layer 1). The same BMAD skill can behave differently in two IDEs, because layers 1 and 2 changed under it. And the documents (layer 5) matter more than any persona's memory, because they carry state between agents that never share a context window. That last point is the engine of the whole method.

Where it came from

BMAD was created by Brian Madison, who goes by "BMad" (the acronym honors him). His background is unusually systems-heavy for a dev-tooling author: 25-plus years in software, spanning NASA simulations and military systems at Northrop Grumman, IoT at Siemens, and leading AI-native transformation at Extend, plus service as a U.S. Army veteran. He runs the project as BMad Code, LLC.

The origin story is the reason the method looks the way it does. Madison spent a year on late-night experiments with Cursor's agent mode and found that "vibe coding" (open the agent, describe what you want, let it generate) hit a wall on anything non-trivial: agents hallucinated APIs, made contradictory architectural decisions, fell into "death spirals" of failing tests, and threw away working code. What fixed it was structure: constraint files, prompt files, PRDs, and granular work breakdown. He brought the approach to his team at Extend, where it only took hold after a two-week "permission to fail" sprint in which engineers independently converged on the same answer, specs plus context. His stance, verbatim in interviews, is that agents are "facilitators, not oracles," and that "AI agents don't understand vibes; they need precision, crystal-clear specs, explicit instructions and defined tech stacks." He calls BMAD "the antithesis of vibe coding," which the next page unpacks.

The name

Two official expansions are in circulation, both legitimate: the original "Breakthrough Method for Agile AI-Driven Development" (still the repo's tagline) and the newer framework-level "Build More Architect Dreams." A third you may see online, "Building Modern Apps Decisively," is community drift, not official.

Version lineage

BMAD is a 2025-origin project (the original repo was created April 13, 2025), not a 2024 one; the 2024 date some sources cite conflates it with the earlier context-engineering and PRP ideas it shares DNA with. The arc:

Two v6 changes are worth internalizing because they shape everything else. The move to the Agent Skills / SKILL.md format (v6.1 to v6.2) made skills portable across 40-plus AI tools, "write once, run everywhere." And the config directory was renamed .bmad-method/ to _bmad/ because dot-folders get filtered out of IDE indexing and LLM context, the same reasoning that keeps _bmad-output/ visible. As of late July 2026, v7 is not released or formally announced; the roadmap lists themes (a universal skills architecture, a skill marketplace, adaptive per-tool skill variants, and optional dev-loop autopilot) rather than a version.

BMAD has grown fast: from roughly 37,000 GitHub stars in February 2026 to about 49,000 by June, with a release cadence of several BMM releases per month through the spring. It is, by adoption, one of the most-used spec-driven frameworks of the 2026 cohort.

How to read this guide

The pages build on each other, but each stands alone as a reference:

Hands-on: prove BMAD is just files

Layer 3 in the model above claims a skill is "markdown in a discovery folder." Don't take it on faith. In five minutes you can build one by hand and watch the host surface it as a slash command. A real BMAD skill is the same shape, just larger and cross-referenced.

Make a scratch repo and author one skill folder:

mkdir -p /tmp/bmad-scratch && cd /tmp/bmad-scratch
git init -q
mkdir -p .claude/skills/hello-bmad

Write the skill. It is one file, SKILL.md, with a small YAML frontmatter block (name, description) and a body. That is the entire contract:

---
name: hello-bmad
description: Prove a skill is a folder with a SKILL.md. Greet, then stop.
---

When invoked, print exactly: hello from a markdown skill.
Do nothing else.

Confirm the folder is on disk:

ls .claude/skills/

Illustrative (run it in your own repo; not machine-verified here).

hello-bmad

Now open Claude Code in that directory. The host scans .claude/skills/ at startup, so /skills lists what it found, and the skill is callable by its frontmatter name:

Illustrative (run it in your own repo; not machine-verified here).

> /skills
Available skills:
  hello-bmad   Prove a skill is a folder with a SKILL.md. Greet, then stop.

> /hello-bmad
hello from a markdown skill

Three facts are now visible with your own eyes. The skill is a directory, not a binary or a plugin. The host discovered it with zero registration, from the folder alone. And the frontmatter description is the only thing the model reads until you invoke it, which is why BMAD's descriptions are written to be self-selecting.

Delete the folder and /hello-bmad disappears from the next session. Nothing was installed and nothing persists outside the file. A BMAD install (page 2) writes dozens of these folders under _bmad/, each a SKILL.md plus the prompt and template files it references. Same shape, same discovery, more of it.

Under Claude Code: the harness BMAD rides on

Layer 2 in the five-layer model is an "AI host." This guide's is Claude Code, so it helps to name what that host actually is. Claude Code is an agentic harness: a loop wrapped around a model. Each turn the model reads its context, thinks, calls one tool, reads the tool result, and repeats until the task is done or it stops for you. The tools it can call are built in: Read, Edit, Write for files; Bash for the shell; Glob and Grep for search; WebSearch and WebFetch for the network; Task (also surfaced as Agent) to spawn a subagent with its own context window; Skill to run a skill in the current conversation; and TodoWrite to track a checklist. That set is layer 1's capabilities (filesystem, shell, web, subagents) exposed as callable tools.

BMAD adds nothing to that list. It ships no binary and no server of its own. What the installer writes is markdown: a directory per skill, each with a SKILL.md, plus the prompt and template files those skills reference. Claude Code discovers them and surfaces each as a /bmad-* slash command; a persona invoked mid-run becomes a subagent through the same Task tool any other work uses. So "running the PM agent" (one of the six personas page 4 covers) is Claude Code loading a SKILL.md into its loop, not launching a separate program.

Because the method is just files and prompts, the same skills load on Cursor, Codex, or Gemini CLI: layer 2 swaps, layers 4 and 5 do not. Every chapter that follows closes with an "Under Claude Code" note pinning the concept to this host's real mechanics.

Start with the next page for the idea that makes the whole method make sense: why writing the spec first is not a return to waterfall, but the discipline that keeps an AI agent from building the wrong thing at machine speed. 👉

Spec-driven development vs agile, scrum, and vibe coding

BMAD is one instance of a broader idea: spec-driven development (SDD). To use BMAD well you have to understand the idea it implements, why that idea exists specifically because of AI coding agents, and how it relates to the software process you already know. This page is the concept and the comparison; the rest of the guide is the mechanics.

On this page

• What spec-driven development is
• The problem it solves, specifically for agents
• The four eras, and where BMAD sits
• SDD vs vibe coding
• BMAD vs agile and scrum
• BMAD vs other spec-driven tools
• Hands-on: the same feature, spec-first vs vibe
• Under Claude Code: plan mode as the spec gate

What spec-driven development is

In SDD, a well-crafted specification is the primary artifact, and code is generated from it. The spec is not documentation written after the fact; it is the contract that drives requirements, design, the implementation plan, the tests, and the docs downstream. You write down what should exist and why, get that reviewed, and only then have an agent produce the code. Every line of code traces back to a line of intent.

That inverts the habit of the last two decades, where code was the source of truth and documents (if they existed) trailed behind it. SDD works because of a blunt fact about LLM coding agents: an agent amplifies whatever you give it. Hand a strong model a vague sentence and it generates confident code for some interpretation of your words, compounding the ambiguity at machine speed. Hand it a reviewed spec and the same amplification runs in your favor. The spec is context engineering: the difference between the agent guessing your constraints and reading them.

The problem it solves, specifically for agents

SDD is not new (requirements engineering is a whole discipline), but AI agents revived it because they fail in a specific, expensive way without it. This is the exact wall BMAD's creator hit, and the failure modes are worth naming because they are what a spec prevents:

• Hallucination: the agent invents APIs, files, or behavior that were never specified.
• Contradiction: two parts of the work make incompatible decisions because nothing wrote the decision down.
• Death spirals: the agent thrashes on failing tests, "fixing" one thing by breaking another, because it has no fixed target.
• Drift and discard: it wanders from the intent and eventually throws away code that no longer fits a goal it never really had.

A machine-readable spec removes the ambiguity these feed on and makes every change traceable, which is what practitioners mean by eliminating "AI drift." The whole of BMAD is an apparatus for producing, reviewing, and preserving that spec at the right level of detail for each stage.

The four eras, and where BMAD sits

It helps to place SDD against the processes it is reacting to:

SDD is often mistaken for a return to waterfall, and the critique has a name in the 2026 commentary: "the Waterfall Strikes Back," the worry that heavy up-front Markdown buries agility. It is a fair caution and a real pitfall (see page 10), but it mistakes writing a spec first for writing the whole spec once. BMAD threads the needle three ways: it is scale-adaptive (a bugfix skips almost all of it), its phases are iterative and revisable (the PRD has an Update intent; bmad-correct-course reconciles mid-sprint), and it breaks work into small stories, not one big design. The counter-view in the same commentary is that agents actually supercharge agile, because the backlog can be built and rebuilt in real time. Both are true; the discipline is to spend spec effort where uncertainty and blast radius justify it, and nowhere else.

SDD vs vibe coding

"Vibe coding" was coined by Andrej Karpathy in February 2025 to describe letting an agent generate from a loose prompt and going with the flow. About a year later he described that era as ending, giving way to "agentic engineering": orchestrating agents against detailed specs with human oversight. SDD is the disciplined form of that shift, and BMAD's creator is blunt about the relationship: "I don't consider BMad vibe coding. I think of it as the antithesis of vibe coding." Vibe coding is genuinely fine for throwaway prototypes; it is a liability for anything you have to maintain, integrate, or trust. The dividing line is whether the code has a future.

BMAD vs agile and scrum

BMAD is explicitly agile-inspired, not opposed to agile. Its personas mirror a Scrum team, an Analyst, a Product Manager, an Architect, a developer, a QA or Test Architect, and it produces PRDs and sprint-style stories tracked in a status file. What it changes is who does the work between the ceremonies: an AI agent, which needs the intent written down far more precisely than a human teammate who can ask a question at standup. So BMAD keeps agile's cadence (short cycles, working software, feedback, retrospectives) and adds the artifact rigor that keeps agents consistent across those cycles. It is agile with the implicit knowledge made explicit, because the new team member cannot read the room.

BMAD vs other spec-driven tools

BMAD is the most architecturally ambitious of the 2026 SDD tools, which makes it the strongest fit for complex, multi-team, regulated work and heavier than necessary for small, fast work. The honest comparison, by where each tool puts the spec and research:

A rough decision heuristic from the comparison write-ups: brownfield-heavy and small, reach for something light like OpenSpec or BMAD's Quick Flow; scaling teams standardizing process, Spec Kit or BMAD full method; multi-team or regulated, BMAD. They are also interoperable at the document level: a research report or spec produced one way feeds another tool's pipeline, because they are all just Markdown.

One caveat applies to the entire category, BMAD included: none of these tools automatically keep the spec and the code in sync. Code drifts from its spec, and every tool needs a deliberate reconciliation step (BMAD's PRD Update intent and bmad-correct-course, Spec Kit's reconcile command, OpenSpec's sync). Treat spec-code divergence as a permanent maintenance task, not a solved problem; it is the single most common way SDD projects quietly rot.

Hands-on: the same feature, spec-first vs vibe

One task, two runs, on a repo that already has a limiter. Goal: rate-limit POST /login. The repo has app/ratelimit.py (a TokenBucket used by /search and /export) and an unprotected /login in app/routes/auth.py. Start both runs from the same clean tree:

git switch -c ratelimit-experiment

Run A, vibe. No plan, edits allowed, one loose prompt:

claude --permission-mode acceptEdits

Illustrative (run it in your own repo; not machine-verified here).

> add rate limiting to the login endpoint

I'll add rate limiting. Steps:
- pip install slowapi
- add Limiter middleware in app/main.py
- decorate login() with @limiter.limit("10/minute") in app/routes/auth.py
- add SLOWAPI_ENABLED to app/config.py

Edited 3 files. Done.

Three files touched, a second limiter library installed, and /login now guarded by slowapi while every other route uses the in-house TokenBucket. Two limiters, two configs, one drift you will debug later. Nothing pointed the agent at the code already in the repo.

Run B, spec-first. Same task, but gate it. Press Shift+Tab to reach plan mode (or launch claude --permission-mode plan), then ask. Claude reads first and proposes:

Plan: rate-limit POST /login

Findings
- app/ratelimit.py exports TokenBucket, used by /search and /export.
- /login in app/routes/auth.py has no limiter.

Approach
1. Reuse TokenBucket. No new dependency.
2. Guard login(): key = client_ip, 10 attempts / 60s, return 429 + Retry-After.
3. Add app/tests/test_login_ratelimit.py: 11th attempt in window -> 429.

Out of scope: no middleware, no config for other endpoints.

You disagree with one assumption and say so before approving:

Illustrative (run it in your own repo; not machine-verified here).

> key on f"{ip}:{username}", so one IP can't lock a user out. Then go.

[ExitPlanMode] approved
Edited app/routes/auth.py and added test_login_ratelimit.py. Test passes.

One file changed plus a test, the existing limiter reused, the keying decision made by you, not guessed.

The difference was not a better model. It was the ExitPlanMode approval: a five-second read that caught the wrong assumption (a fresh library, the wrong key) before a single edit landed. That checkpoint is the cheap one. The three-file cleanup in Run A is the expensive one. This is exactly the SDD trade this page argues, enforced at the tool layer.

Under Claude Code: plan mode as the spec gate

This page argues spec before code. Claude Code has a host primitive that makes the same move: plan mode. Press Shift+Tab to cycle the permission mode (manual to acceptEdits to plan to auto), or start in it with claude --permission-mode plan, which works headless in claude -p too. In plan mode Claude may read files and run search tools, but it may not edit source or run side-effecting Bash (no git push, no rm, no curl). It explores, proposes an approach, and exits only through the ExitPlanMode tool, which presents the plan for your approval before any implementation.

That approval is the spec gate. Nothing gets built until you agree the approach, which is SDD's move (agree the spec, then generate) enforced at the tool layer instead of in a document. Reject the plan and Claude refines and re-enters plan mode; the amplification stays pointed at a target you signed off on.

Two supporting pieces map cleanly. CLAUDE.md (project root or .claude/CLAUDE.md, loaded every session) is the always-on constitution, the way a BMAD project-context travels with the work; put standing constraints there so every plan starts from them. And the permission modes are a ceremony dial you turn to fit the blast radius:

Spec-heavy work sits at plan; a throwaway prototype can run at acceptEdits. It is the same discipline the four-eras table draws: spend the ceremony where blast radius earns it, and nowhere else.

With the concept in place, and BMAD located among its peers, the rest of this guide is mechanics. The next page gets you installed on your machine. 👉

Installing BMAD and starting work (any machine)

This page takes you from a clean machine to a working BMAD install you can run in your IDE. It is exact: every command, flag, and prerequisite is drawn from the v6.10 installer and docs. If you only read one page to get running, read this one, then jump to the anatomy page to learn what the installer wrote and what to commit.

On this page

• Prerequisites
• The one command
• Where your skills landed (per IDE)
• Non-interactive and CI installs
• Adding, updating, and pinning later
• Upgrading from v4
• Planning on a flat rate: web bundles
• Hands-on: install BMAD and run your first skill in 10 minutes
• Under Claude Code: where BMAD lands and how it is discovered

Prerequisites

BMAD is an npm package (bmad-method) that generates skill files into your project. It needs three things on the machine, whatever the OS:

Two version notes worth knowing before you hit them:

• The README badges say Python 3.10+, but the customization resolver needs 3.11+ (tomllib landed in 3.11). On macOS without Homebrew and on Ubuntu 22.04, python3 often defaults to 3.10, so install 3.11+ separately or rely on uv, which provisions its own Python.
• Node must be 20.12 or newer or the installer refuses to run.

Per-OS setup, briefly

The installer itself is OS-agnostic; the only per-OS work is getting Node, uv, and Python present.

• macOS: brew install node uv python@3.12 (or use the official Node and astral.sh/uv installers). Apple Silicon and Intel are both fine.
• Linux: install Node 20.12+ from NodeSource or your distro, curl -LsSf https://astral.sh/uv/install.sh | sh for uv, and Python 3.11+ from your package manager (Ubuntu 22.04 users: add deadsnakes or use uv).
• Windows: install Node from nodejs.org, uv via the PowerShell installer, and run inside WSL2 or a normal PowerShell/terminal that your AI tool can reach. Everything below works unchanged under WSL2.

The one command

From inside your project directory:

npx bmad-method install

That single command handles first installs, upgrades, channel switching, and scripted CI runs. On a fresh project it runs an interactive wizard; on a project that already has a _bmad/ folder it offers to update instead.

The interactive wizard asks five things

1. Install directory (defaults to the current directory).
2. Which modules to install: checkboxes for core, bmm, bmb, cis, gds, tea. (core and bmm are the method itself; the rest are add-ons, covered on the map page.)
3. "Ready to install (all stable)?" Yes takes the latest released tag of every external module.
4. Which AI tools / IDEs to integrate with (Claude Code, Cursor, and others).
5. Per-module config: your name, language, and output folder.

When it finishes you have two new folders, _bmad/ (the method) and _bmad-output/ (where artifacts land), and a set of bmad-* skills registered for your IDE. Start with:

bmad-help

which inspects the project and tells you the next step. From a blank project that is usually "create a PRD" or, for a small change, "run quick-dev."

Where your skills landed (per IDE)

The installer writes one skill directory per agent, workflow, task, and tool into an IDE-specific folder. The directory name is the skill name.

Some platforms require you to enable skills in settings before they appear, and a few need an IDE reload. The canonical list of what you have is always the directories themselves:

find .claude/skills -maxdepth 1 -type d -name 'bmad-*' | sort

Non-interactive and CI installs

For reproducible, scripted installs, pass flags. Two are effectively required for a fresh --yes run: --modules (the exact set to install, not a delta, so list everything you want) and --tools (which IDE to wire up).

# Latest stable, everything wired for Claude Code
npx bmad-method install --yes --modules bmm,bmb,cis --tools claude-code

The flags that matter most:

Precedence when they conflict: --pin beats --next= beats --channel/--all-* beats the registry default (stable).

Two channels are in play, and they are independent. The external-module channel (stable, next, or a pinned tag) is per module. The installer binary itself has @latest (npx bmad-method install) and @next (npx bmad-method@next install, a prerelease published on every push to main). Because core and bmm ship inside the installer binary, they have no channel: the installer version determines them, and --pin bmm=... is silently ignored with a warning.

An enterprise-grade, fully reproducible install pins each external module:

npx bmad-method install --yes \
  --modules bmm,bmb,cis \
  --pin bmb=v1.7.0 --pin cis=v0.2.0 \
  --tools claude-code

Heads-up for orgs and CI: resolving each external module's "stable" tag makes one anonymous GitHub API call, and anonymous calls are capped at 60 per hour per IP. Shared NAT, VPNs, and CI pools exhaust that fast. Set GITHUB_TOKEN=<any public-repo-read PAT> to raise the limit to 5000/hour; no scopes are required.

Adding, updating, and pinning later

Running the installer again on an existing project gives you two paths:

• Quick Update reuses your recorded settings, refreshes files, applies patch and minor upgrades, and refuses majors. Fast and non-interactive.
• Modify Install is the full wizard again: add or remove modules, reconfigure, review channels.

To add a module to an existing install without re-selecting your IDE (update reuses the configured tools):

npx bmad-method install --yes --action update --modules bmm,bmb,gds

Upgrade defaults are patch = yes, minor = yes, major = no. Under --yes, patches and minors auto-apply and majors stay frozen; to accept a major non-interactively, pin the new tag: --pin <code>=<new-tag>.

Upgrading from v4

If a project has a legacy .bmad-method folder, npx bmad-method install detects it and offers to back it up and remove it. Then:

1. Let the installer remove .bmad-method (or exit and clean manually; custom-named folders must be removed by hand).
2. Delete legacy v4 IDE commands. For Claude Code, remove the nested bmad folders under .claude/commands/; v6 installs to .claude/skills/.
3. Move planning docs into _bmad-output/planning-artifacts/ with descriptive names (include PRD, brief, architecture, or ux-design in the filename so the auto-scanner finds them).
4. For in-progress dev, drop your epics.md (or epics/epic*.md) into planning-artifacts, run bmad-sprint-planning, and tell the agent which stories are already done.

There is no supported v4/v6 coexistence; the compatibility shims that keep old skill names resolving are the intended bridge.

Planning on a flat rate: web bundles

Long planning conversations (brainstorm, brief, PRD, UX, research) can run on a flat-rate chat subscription instead of metered IDE tokens, then come back to the IDE for implementation. BMAD packages these as Gemini Gems and ChatGPT Custom GPTs. The only supported source is bmadcode.com/web-bundles: pick a bundle, download the ZIP, create a Gem or Custom GPT, upload the knowledge files, and paste the instructions block. Gemini Gems need Gemini Advanced; Custom GPTs need a paid ChatGPT plan; the research bundles need Deep Research enabled. Details are on the team page.

Hands-on: install BMAD and run your first skill in 10 minutes

Empty repo to a working skill. Every command is exact; anything the tool prints back is labeled illustrative.

1. Check prerequisites. Confirm the three from the table above:

node --version
python3 --version
uv --version

Illustrative (run it in your own repo; not machine-verified here).

v20.12.2
Python 3.12.4
uv 0.5.11

If node is below 20.12 the installer aborts; if python3 is below 3.11, let uv provide Python rather than fighting the system one.

2. Run the installer from inside a git repo:

cd my-project
npx bmad-method install

The wizard prompts through the five questions from the section above. Pick Claude Code as the IDE and core + bmm as the modules for a first run:

? Install directory  .
? Modules  (*) core  (*) bmm  ( ) bmb  ( ) cis  ( ) gds  ( ) tea
? Ready to install (all stable)?  Yes
? AI tools / IDEs  (*) Claude Code
? Your name  Sam

Illustrative (run it in your own repo; not machine-verified here).

3. See what landed. Two folders plus the Claude Code skills tree:

ls -R _bmad | head
ls .claude/skills

Illustrative (run it in your own repo; not machine-verified here).

_bmad:
core  bmm  _cfg

_bmad/core:
agents  workflows  tasks

.claude/skills:
bmad-help  bmad-brainstorming  bmad-create-prd  bmad-quick-dev  bmad-sprint-planning

4. Confirm discovery. In Claude Code, list what registered:

/skills

Illustrative (run it in your own repo; not machine-verified here).

bmad-help            Inspect the project and suggest the next step
bmad-brainstorming   Facilitated idea generation for a new feature or product
bmad-create-prd      Draft a product requirements document

No registration step: the host reads each SKILL.md frontmatter directly (see the next section).

5. Run your first skill.

/bmad-brainstorming

Illustrative (run it in your own repo; not machine-verified here).

> What problem or opportunity are we brainstorming today?
you: a CLI that lints commit messages
> Good. Let us diverge first. Give me three user types who would care...

That is the loop: invoke a bmad-* skill, answer its questions, get a drafted artifact under _bmad-output/.

6. Commit the right files. Check in the shared config and skills; keep personal settings out:

git add _bmad .claude/skills .claude/settings.json .mcp.json
echo '.claude/settings.local.json' >> .gitignore
echo '_bmad-output/' >> .gitignore

The exact commit-versus-ignore list, and why _bmad-output/ is generated rather than committed, is on page 3.

Under Claude Code: where BMAD lands and how it is discovered

This page is about install and what to commit. On Claude Code the mapping is direct: a --tools claude-code run drops one directory per agent, workflow, and task under .claude/skills/<name>/SKILL.md, and the host discovers them with no registration step.

Discovery reads the description line in each SKILL.md frontmatter. Progressive disclosure keeps only the name and description in context (about 50 tokens each) until a skill is invoked, so even a large bmad-* install stays cheap; the full body loads on first use. /skills lists what you have and toggles each one on, name-only, or off.

Where a skill lives sets its scope and its commit story:

Precedence when a name collides: enterprise-managed > personal (~/.claude) > project (.claude) > plugin.

The chapter's commit rule (share the config, gitignore the personal bits) maps onto Claude Code's settings split. .claude/settings.json is committed and team-shared; .claude/settings.local.json is gitignored and personal. Project MCP servers, if BMAD wires any, go in a committed .mcp.json. So a checked-in .claude/skills/ plus .claude/settings.json and .mcp.json reproduce the install for a teammate on clone.

BMAD can also arrive as a plugin bundle installed via /plugin from a marketplace. Then its skills namespace as /bmad:<skill> and live inside the plugin, not in your .claude/, which changes nothing about how discovery or progressive disclosure work.

With BMAD installed and running, the next page opens the box: exactly what the installer wrote to disk, how its configuration layers resolve, and which files belong in your repository's main branch. 👉

Anatomy of an install: files, config, and what to commit

The install page got you running. This page opens the box: what the installer wrote, how BMAD's configuration layers resolve, and, the question every team asks on day one, which files belong in git and which stay local. Get this right once and the rest of BMAD is calm.

On this page

• The two folders
• Inside _bmad/
• Inside _bmad-output/
• Three copies of “BMAD,” and only one is yours
• Configuration resolution: two override stacks
• What to commit, and what to keep local
• project-context.md: the constitution
• Hands-on: inspect what got installed and set up commit hygiene
• Under Claude Code: the .claude/ tree and settings precedence

The two folders

A fresh install creates two top-level folders in your project:

your-project/
├── _bmad/            the method: modules, config, scripts (installer-owned + your overrides)
└── _bmad-output/     the work: research, briefs, PRD, architecture, stories, sprint state

The rule of thumb behind everything below: _bmad/ is machinery, _bmad-output/ is product. You rarely touch the machinery by hand except in one place (_bmad/custom/), and the product is the reviewable artifact chain your team reads in pull requests.

Inside _bmad/

_bmad/
├── core/                     built-in core framework (bundled in the installer)
├── bmm/                      the BMad Method module (bundled)
├── bmb/  cis/  ...           each installed add-on module
├── _config/
│   ├── manifest.yaml         every module: version, channel, source, sha
│   └── agents/               agent customization files
├── config.toml               installer-owned, TEAM scope (install answers + agent roster)
├── config.user.toml          installer-owned, USER scope (your name, language, skill level)
├── custom/                   YOUR overrides (starts empty; the only folder you hand-edit)
│   ├── config.toml           team overrides
│   ├── config.user.toml      personal overrides
│   ├── bmad-agent-dev.toml    a per-agent override
│   └── bmad-prd.toml          a per-workflow override
├── <module>/config.yaml      per-module config (prompt defaults, carry-forward)
└── scripts/                  resolvers (resolve_customization.py, memlog.py, ...)

manifest.yaml is worth knowing, because it is your reproducibility record. It lists every module with its resolved version, channel (stable, next, or pinned), source, and git sha:

modules:
  - name: bmb
    version: v1.7.0        # the tag, or "main" for the next channel
    channel: stable
    sha: 86033fc9aeae2ca6d52c7cdb675c1f4bf17fc1c1
    source: external
    repoUrl: https://github.com/bmad-code-org/bmad-builder

A "stable" install resolves to the newest tag at install time, so to reproduce an install on another machine you convert manifest.yaml's tags into explicit --pin flags rather than trusting --modules to resolve the same way twice.

Inside _bmad-output/

_bmad-output/
├── planning-artifacts/        research/, brief, PRD, ux (DESIGN.md/EXPERIENCE.md), architecture, epics/
├── implementation-artifacts/  sprint-status.yaml, story specs, deferred-work.md
└── project-context.md         optional; your project's implementation "constitution"

The output folder is configurable (it is the output_folder core setting, with planning_artifacts under the bmm module), but _bmad-output/ is the default. This is the chain the SDD page describes, made real on disk: each file is a reviewable, greppable message from one phase to the next.

Three copies of "BMAD," and only one is yours

The single most common source of confusion, and update pain, is editing the wrong copy. There are three:

Treat the installer-owned files as generated code. Editing _bmad/config.toml or a generated SKILL.md directly works today and is silently overwritten on the next npx bmad-method install. All durable behavior changes go in _bmad/custom/; all durable content goes in the output folder. The installation is deliberately inspectable, not an opaque service: manifest.yaml, the skill directories, and git diff after an update answer almost every "what do I actually have?" question.

Configuration resolution: two override stacks

BMAD separates central configuration (cross-cutting: paths, the agent roster, install answers) from per-skill behavior (one agent or workflow). Each has its own layered resolution, highest layer wins.

Central configuration, four layers:

highest  _bmad/custom/config.user.toml   personal, durable   (gitignored)
         _bmad/custom/config.toml        team, durable       (committed)
         _bmad/config.user.toml          installer-generated personal
lowest   _bmad/config.toml               installer-generated team/base

Per-skill behavior, three layers:

highest  _bmad/custom/bmad-prd.user.toml   personal   (gitignored)
         _bmad/custom/bmad-prd.toml         team       (committed)
lowest   .claude/skills/bmad-prd/customize.toml   the shipped schema/defaults (never edit)

The resolver merges by the shape of each value, and knowing the four rules is what lets you keep overrides sparse:

There is deliberately no deletion operator. To neutralize a shipped item, override it by code with a no-op; to remove behavior wholesale, fork the skill. Copying an entire shipped customize.toml into your override freezes old defaults and masks every future improvement, so change only the handful of fields you mean to. The resolver is a small stdlib script (tomllib, hence Python 3.11+), and every skill falls back to reading the three TOML files directly if the script is unavailable.

What to commit, and what to keep local

This is the answer to "what BMAD files do I push to main." BMAD encodes the team-vs-personal split directly in the filename, and the rule is mechanical:

*.user.toml is personal and gitignored. Every other *.toml in _bmad/custom/ is team-shared and committed. BMAD gitignores the .user.toml files for you automatically.

Applied to the whole install:

A pragmatic .gitignore that most teams converge on:

# BMAD: keep team overrides, shared config, and all product artifacts;
# ignore personal overrides and regenerable machinery.
_bmad/**/*.user.toml
_bmad/core/
_bmad/bmm/
_bmad/cis/
_bmad/bmb/
.claude/skills/bmad-*/     # if you prefer to regenerate skills per machine

Two teams reasonably differ on one point: whether to commit the installed module source and generated skills. Committing them makes the repo fully self-contained and pins exact behavior, at the cost of large, noisy diffs on every upgrade. Ignoring them keeps the repo clean and treats BMAD like any other dependency, resolved from manifest.yaml and a one-line install command in the README. Either is defensible; pick one and write it down. What is not optional is committing the _bmad-output/ spec chain and the team *.toml overrides: those are the shared brain, and a teammate who clones the repo without them gets a different BMAD.

project-context.md: the constitution

One output file deserves special mention because it is the highest-value file a team keeps. project-context.md is "your project's implementation guide for AI agents, similar to a constitution in other development systems." Every implementation workflow loads it automatically if it exists: bmad-architecture, bmad-create-story, bmad-dev-story, bmad-code-review, bmad-quick-dev, bmad-sprint-planning, bmad-retrospective, and bmad-correct-course.

It holds two things: your technology stack with specific versions, and your critical implementation rules, the patterns an agent might miss from reading code. The official guidance is to focus on the unobvious:

## Technology Stack
- Node 20.x, TypeScript 5.3, React 18.2
- State: Zustand (not Redux)
- Testing: Vitest, Playwright, MSW

## Critical Implementation Rules
- No `any` types without explicit approval.
- All API calls go through the `apiClient` singleton; never `fetch` directly.
- Feature flags via `featureFlag()` from `@/lib/flags`.
- All offline splits are chronological; random interaction splits are forbidden.

Create it manually at _bmad-output/project-context.md, or generate it with bmad-generate-project-context (which scans your architecture doc or, for an existing codebase, the code itself). Workflows look there and also match **/project-context.md anywhere in the tree. Keep it living: update it when the architecture changes or when you notice an agent repeating a mistake it should have known better than to make. The memory page returns to this file as one of BMAD's three kinds of durable memory.

Hands-on: inspect what got installed and set up commit hygiene

Ten minutes in a repo that already ran npx bmad-method install. No new concepts, just the exact commands to see what landed on disk and stage the right subset, so you know which files to commit and why.

1. Walk the two folders. List the top of each tree before you touch anything.

ls _bmad
ls _bmad/custom
ls _bmad-output/planning-artifacts

Illustrative (run it in your own repo; not machine-verified here).

$ ls _bmad
core  bmm  bmb  cis  _config  config.toml  config.user.toml  custom  scripts
$ ls _bmad/custom
config.toml  config.user.toml
$ ls _bmad-output/planning-artifacts
research  brief.md  PRD.md  architecture.md  epics

One rule: _bmad/ is machinery, _bmad-output/ is product. Inside the machinery, _bmad/custom/ is the only folder you hand-edit.

2. Read a skill's schema. Each generated skill ships a customize.toml documenting its overridable fields. Open one and skim the [workflow] and [agent] tables.

sed -n '1,40p' .claude/skills/bmad-prd/customize.toml

Illustrative (run it in your own repo; not machine-verified here).

[workflow]
instructions = "..."
elicitation = true
output_file = "{output_folder}/planning-artifacts/PRD.md"

[agent]
name = "John"
role = "Product Manager"

These are the shipped defaults, the lowest layer. Never edit this file; mirror only the fields you want to change into _bmad/custom/bmad-prd.toml.

3. Author the .gitignore. Commit the shared config and the product chain; ignore personal overrides and runtime junk.

# BMAD: commit shared config + the spec chain; ignore personal + runtime.
_bmad/**/*.user.toml
_bmad/core/
_bmad/bmm/
_bmad/cis/
_bmad/bmb/
_bmad-output/**/.cache/
**/__pycache__/
*.log

Note what this does not touch: _bmad/**/*.toml (your team overrides), _bmad/_config/manifest.yaml (the reproducibility record), and everything under _bmad-output/planning-artifacts/. Those stay tracked.

4. Stage the shared config.

git add .gitignore \
        _bmad/custom/*.toml \
        _bmad/_config/manifest.yaml \
        _bmad-output/
git status --short

The *.toml glob skips *.user.toml because git already ignores it, so even a stray git add -A will not leak personal settings.

5. Confirm the merge before you trust it. Committing an override is committing its effect. page 11 runs resolve_customization.py to print the three-layer merge (shipped customize.toml, then team .toml, then personal .user.toml) so you stage config whose resolved value you have actually seen, not guessed.

Under Claude Code: the .claude/ tree and settings precedence

This chapter is BMAD's on-disk layout, its layered config, and the commit rule. The worked host has a parallel tree of its own. Claude Code reads everything from a project .claude/ directory: settings.json (committed), settings.local.json (gitignored), and the subdirectories skills/, agents/, commands/, rules/, and output-styles/, plus a project-root .mcp.json. Prose memory lives in CLAUDE.md (project, committed) and CLAUDE.local.md (gitignored), with the user-scoped copies under ~/.claude/.

Settings resolve by a five-level precedence, highest first:

CLAUDE.md is a hierarchy too (managed, user ~/.claude/CLAUDE.md, project, local, then nested per-subdir loaded on demand). It supports @path imports up to four levels deep, and a # at the prompt appends a line to memory.

The mapping is direct. BMAD's commit rule ("commit *.toml, gitignore *.user.toml") is Claude Code's rule one layer up: commit .claude/settings.json, gitignore .claude/settings.local.json. Same committed-shared versus local-personal split, encoded in the filename. The two systems stack rather than compete: BMAD's TOML merge (the four shape rules above) runs to produce a skill's effective config, and that skill sits inside a .claude/ tree whose own settings resolve by the five levels here. Two override stacks, one on top of the other.

With the files understood, the next page lays out the moving parts they configure: every module, the four phases, the six named agents, and the workflow map that ties them together. 👉

Modules, phases, personas, and the workflow map

This is the map of BMAD as a whole. If the install page got you running and the anatomy page showed you the files, this page shows you the moving parts those files configure: the modules that ship the skills, the four phases they organize into, the six named agents who run them, and the workflow map that ties phase to output. The command reference then lists every skill exhaustively.

On this page

• Modules: a small core plus opt-in add-ons
• The four phases
• The three tracks (scale-adaptive)
• The six named agents
• The workflow map
• Hands-on: drive a persona through one phase
• Under Claude Code: personas as skills and subagents

Modules: a small core plus opt-in add-ons

BMAD ships a tiny core and the flagship BMM (the BMad Method itself) bundled inside the installer; everything else is an installable module you select with --modules or the wizard. Versions below are current as of this writing; core and bmm have no independent version because they ship with the installer binary.

The add-ons prove BMAD is a pattern reinstantiated per domain, not one fixed pipeline. Game Dev Studio rebuilds the whole roster and workflow chain for games (Game Brief, then a Game Design Document, then architecture); Whiteport rebuilds it as a UX-and-design-first methodology. The extending page covers building your own with BMad Builder, and a community marketplace is on the roadmap. Most of this guide focuses on core + BMM, which is BMAD proper.

The four phases

BMM organizes work into four phases, each producing documents the next consumes. The doc chain is the point: it is "context engineering," building an agent's understanding progressively so it always knows what to build and why.

Phase 1            Phase 2              Phase 3               Phase 4
ANALYSIS       →   PLANNING         →   SOLUTIONING       →   IMPLEMENTATION
(optional)         (what & why)         (how, then what      (build it, one
explore & validate PRD, UX spines       units of work)        story at a time)
                                        architecture, stories code, tests, review
Mary / Paige       John / Sally         Winston → John        Amelia

Phase 1 is optional but load-bearing: "skipping analysis entirely means your PRD is built on assumptions instead of insight." Phase 3 matters most when several epics might be implemented by different agents, because that is where conflicting technical decisions get pre-empted (the pitfalls page returns to this). The official line: catching an alignment issue in solutioning is about 10x cheaper than discovering it during implementation.

The three tracks (scale-adaptive)

BMAD is "scale-adaptive": you run only the ceremony the work justifies. The story counts are guidance, not hard rules.

bmad-help picks a track for you from a description of the work. A bugfix is Quick Flow; a new product is the full method. This is why BMAD does not feel heavy on small work: the method scales down as deliberately as it scales up.

The six named agents

Analysis, planning, solutioning, and implementation are each led by a persona with a fixed identity and a customizable layer. These are the default BMM agents, their skill ids, and their menu triggers (short codes you type once an agent is loaded).

Two ways to start work with them:

• Direct skill: type bmad-prd and the workflow runs, no persona loaded.
• Agent menu: load bmad-agent-pm (or say "hey John"), then type a trigger like PRD. The agent interprets the code while staying in character.

Use direct skills in runbooks and automation (bmad-create-story is self-describing; CS depends on knowing Amelia's menu). Use the persona when you want an exploratory conversation across an agent's related jobs. Most triggers run a structured workflow; a few (Paige's WD, MG, VD, EC) are conversational and expect you to describe what you need.

Other modules add their own casts: Murat (TEA's Master Test Architect); the Game Dev Studio ensemble (Cloud Dragonborn the architect, Samus Shepard the designer, Link Freeman the developer, Indie the solo dev, plus Paige); the CIS coaches (Carson for brainstorming, Maya for design thinking, Victor for innovation, Sophia for storytelling, and more); and Whiteport's Norse trio (Saga, Freya, Mimir).

A persona is policy, not a second model

Loading an agent does not start a separate process. It runs an eight-step activation that reloads a fixed identity plus your customizations into the current chat:

1 resolve the agent block   merge shipped defaults <- team <- personal overrides
2 run prepend steps
3 adopt the persona          hardcoded identity + your role/style/principles
4 load persistent facts      org rules, compliance notes, file: references
5 load config                your name, languages, artifact paths
6 greet                      by name, in your language, with the agent's emoji
7 run append steps
8 dispatch or show the menu  jump straight to a workflow, or wait for a trigger

The identity (name, title, domain) is hardcoded on purpose so "hey Mary" always reaches the analyst, however heavily a team has customized her. Everything else, her principles, communication style, menu, and standing facts, is yours to shape through _bmad/custom/ (see team collaboration). This is the "three-legged stool": a skill provides capability, a named agent provides persona continuity, and customization provides your org's shaping. The result is a teammate who already knows the work, that you can reshape without forking.

The workflow map

Every workflow below runs directly (type the skill) or through an agent's menu. This is the canonical phase-to-output map for core + BMM.

Phase 1, Analysis (optional):

Phase 2, Planning:

Phase 3, Solutioning:

Phase 4, Implementation:

Quick Flow (parallel track):

Hands-on: drive a persona through one phase

Let us start Phase 2 the persona way. Load John, the PM, and dispatch one job by number. Run this in a repo where BMAD is installed:

/bmad-agent-pm

Activation runs the eight steps above (resolve, adopt, load facts, load config, greet, show menu) and lands on John's menu. Each row is one workflow: a Code you can type instead of a number, a Description, and the Action (the skill it dispatches to).

Illustrative (run it in your own repo; not machine-verified here).

📋 John, Product Manager. Planning phase. What are we building?

  #  Code  Description                          Action
  1  PRD   Create / Update / Validate a PRD     bmad-prd
  2  CE    Break the PRD into epics + stories   bmad-create-epics-and-stories
  3  IR    Check implementation readiness       bmad-check-implementation-readiness
  4  CC    Correct course after a change        bmad-correct-course

Type a number, a code (e.g. PRD), or just describe what you need.

Pick "Create PRD" by its number. The PRD skill carries three intents, so John asks which, then opens the workflow's first elicitation.

Illustrative (run it in your own repo; not machine-verified here).

> 1
Running bmad-prd. Intent?  (1) Create  (2) Update  (3) Validate
> 1
Creating prd.md. Let us frame the problem first: who is this for, and what
breaks for them today?

You are now inside the PRD workflow, and Phase 2 has begun. Two things are worth separating. Continuity is the reloaded identity plus this menu: type PRD tomorrow and "John" reaches the same skill with the same character, whatever your team customized underneath. Project state is what the run writes to disk. This one lands prd.md plus addendum.md and a .memlog.md intent log (see the workflow map above); those files, not the chat, are what Phase 3 reads next.

So a persona is a skill with a menu you dispatch by number. Same three-legged stool as before: the number picks the skill, John supplies the continuity, _bmad/custom/ supplies your shaping. The direct route, typing bmad-prd straight, reaches the identical workflow with no persona loaded (see page 5 for the full skill list).

Under Claude Code: personas as skills and subagents

This chapter's cast (the six BMM personas plus each add-on's roster) has two natural homes on Claude Code, and the choice sets what "loading John" costs.

As a skill. Drop a .claude/skills/<name>/SKILL.md (project-committed) or ~/.claude/skills/<name>/SKILL.md (personal). It runs when Claude matches its description, or when you type /<name>. The body loads just in time on that first invocation and then stays in the current context, matching BMAD's eight-step activation earlier on this page: a persona is policy folded into the running chat, not a second process. Frontmatter can pin model: and effort: for the turn.

As a subagent. Drop a .claude/agents/<name>.md with frontmatter name, description, tools, model, effort. The Agent tool spawns it in a fresh, isolated context window; only its final result returns to the main conversation, so Winston's exploration never crowds the parent window. model/effort override per subagent (Amelia on claude-opus-4-8 for dev-story, Mary on sonnet for a research pass). Manage the roster with /agents.

Progressive disclosure is why a big cast is cheap: at session start only each name and description sit in context (roughly 50 tokens each), and the full persona and its phase workflows cost nothing until something is invoked. The four phases are then just skills run in sequence, each reading the artifacts the last one wrote, which is the doc chain the next paragraph names.

The rule that makes the map cohere: each document becomes the context for the next. The PRD tells the architect what constraints matter; the architecture tells the dev agent which patterns to follow; the story file gives focused, complete context for one unit of work. Remove that structure and agents make inconsistent decisions. That is the whole thesis, and the next page gives you the full skill inventory to execute it. 👉

The complete command and skill reference

This is the inventory: every skill in core and BMM, every default agent trigger, and every skill each official module ships. It is a reference to scan, not a narrative. Deep Recon (bmad-deep-recon, the research skill) is listed here but documented in depth in the existing recon gists (foundation, how-to, complete guide, research reference); this page does not repeat them.

On this page

• How commands work
• Core module (8 tools, always installed)
• BMM workflows by phase
• BMM agent triggers
• Module skills
• Installer and orchestration commands
• Hands-on: a five-command tour on one small feature
• Under Claude Code: how a big skill surface stays cheap

How commands work

There are two ways to start work, and the difference matters:

Every skill uses the bmad- prefix (module skills sometimes add their code, like bmad-cis- or gds-). The installer generates skills from your installed modules, so the canonical list for your machine is always the installed skill directories, not any published list:

find .claude/skills -maxdepth 1 -type d -name 'bmad-*' | sort   # Claude Code
find .agents/skills -maxdepth 1 -type d | sort                  # Cursor / Windsurf

bmad-help reads that installed set and recommends the next step; it is the one command to run whenever you are unsure.

Core module (8 tools, always installed)

The core module is a small set of tools that work in any phase, any module, no agent session required.

The four kernel tools:

The four thinking skills:

Some earlier IDs now forward to these: the three research workflows (bmad-market-research, bmad-domain-research, bmad-technical-research) into bmad-deep-recon; the separate editorial and adversarial review skills into bmad-review. bmad-shard-doc and bmad-index-docs were removed; bmad-spec moved into BMM as a Phase 2 workflow.

BMM workflows by phase

The full four-phase inventory. See the workflow map for what each produces.

BMM agent triggers

Once an agent is loaded, these short codes start its workflows.

Module skills

Installed only when you select the module. Names are exact; descriptions are one line each.

BMad Builder (bmb, v2.1.0)

The meta-module: build your own agents, workflows, and modules.

It also ships sample agents you can study or use (bmad-agent-code-coach, bmad-agent-creative-muse, bmad-agent-diagram-reviewer, bmad-agent-dream-weaver, bmad-agent-sentinel, bmad-excalidraw).

Creative Intelligence Suite (cis, v0.2.1)

Six coaches and four workflows for the fuzzy front end.

Test Architect (tea, v1.19.1)

Murat (bmad-tea), plus nine workflows under bmad-testarch-* (and bmad-teach-me-testing):

Supports P0-P3 risk prioritization and optional Playwright Utils and MCP browser automation.

Game Dev Studio (gds, v0.6.0)

Five agents and 28 workflows; the largest module. Agents: gds-agent-game-architect (Cloud Dragonborn), gds-agent-game-designer (Samus Shepard), gds-agent-game-dev (Link Freeman, also QA and scrum), gds-agent-game-solo-dev (Indie), gds-agent-tech-writer (Paige). Workflows span preproduction (gds-brainstorm-game, gds-create-game-brief, gds-domain-research), design (gds-gdd, gds-create-narrative, gds-prd, gds-ux), technical (gds-game-architecture, gds-create-epics-and-stories, gds-check-implementation-readiness, gds-generate-project-context), production (gds-create-story, gds-dev-story, gds-code-review, gds-investigate, gds-sprint-planning, gds-sprint-status, gds-correct-course, gds-retrospective), a seven-workflow game-test suite (gds-test-design, gds-test-automate, gds-playtest-plan, gds-performance-test, gds-e2e-scaffold, gds-test-framework, gds-test-review), and quick-flow (gds-quick-dev, gds-document-project).

Whiteport Design Studio (wds, v0.4.3)

Three "Norse" agents (wds-agent-saga-analyst Saga, wds-agent-freya-ux Freya, wds-agent-mimir-builder Mimir) driving a numbered pipeline: wds-0-project-setup, wds-0-alignment-signoff, wds-1-project-brief, wds-2-trigger-mapping, wds-3-scenarios, wds-4-ux-design, wds-5-agentic-development, wds-6-asset-generation, wds-7-design-system, wds-8-product-evolution.

BMad Loop (bmad-loop, v0.9.0)

A deterministic Python orchestrator (not an LLM persona) for unattended dev loops. Skills: bmad-loop-setup (install), bmad-loop-resolve (human-in-the-loop escalation), bmad-loop-sweep (triage the deferred-work ledger). It drives the upstream bmad-dev-auto skill from a CLI:

bmad-loop run | resume | attach | status | list | stop | sweep | resolve
             | init | tui | mux | plugin | skill | validate | diagnose
             | decisions | archive | clean | delete | probe-adapter

It requires Python 3.11+, a terminal multiplexer (tmux; psmux on Windows), and a BMAD v6 project on BMAD-METHOD 6.10.0+. Its tmux adapter can drive claude, codex, gemini, copilot, antigravity, or opencode, mixing agents per stage. The end-to-end page walks a run.

Installer and orchestration commands

The npx bmad-method install flags are on the install page; the ones you reach for most:

npx bmad-method install                                   # interactive wizard / update
npx bmad-method install --yes --modules bmm --tools claude-code   # scripted
npx bmad-method install --list-tools                      # supported IDEs
npx bmad-method install --list-options bmm                # every --set key for a module
npx bmad-method install --yes --action update --modules bmm,bmb   # add a module

Hands-on: a five-command tour on one small feature

The command surface reads best as a pipeline: each skill drops a file, and the next skill reads it. Here is one toy feature, saved search filters (name and re-run a search), walked through five skills. Run each in a fresh chat so no step leans on the previous conversation, only on the file it left behind. Nothing below is machine-verified; BMAD and Claude Code are not installed on this box.

1. Ideate. bmad-brainstorming pulls options out of you onto one HTML canvas.

/bmad-brainstorming "saved search filters for our list view"

Illustrative (run it in your own repo; not machine-verified here).

docs/brainstorm.html
  <h2>Saved search filters</h2>
  <li>name + pin a set · share via URL · "recent" auto-list · per-user vs team scope</li>

2. Plan. bmad-prd, Create intent, reads that canvas and writes the PRD.

/bmad-prd    # choose: Create

Illustrative (run it in your own repo; not machine-verified here).

docs/prd.md
  ## FR1  A user can save the current filter set under a name.
  ## FR2  Saved filters appear in a per-user list and re-apply on click.

3. Distill. bmad-spec collapses the PRD into a SPEC.md kernel, the machine contract: five fields.

/bmad-spec

Illustrative (run it in your own repo; not machine-verified here).

SPEC.md
  intent:      persist and re-apply named filter sets, per user
  inputs:      { name, filters[], userId }
  outputs:     SavedFilter record; list endpoint
  behavior:    unique name per user; re-apply sets query state
  acceptance:  save, reload, list shows it, click re-applies

4. Build. bmad-dev-story reads SPEC.md, writes tests first, then the code, and records a story file.

/bmad-dev-story

Illustrative (run it in your own repo; not machine-verified here).

docs/stories/story-1.md   status: Ready for Review
+++ src/filters/saved.ts
+ export function saveFilter(name, filters, userId) { ... }
+++ src/filters/saved.test.ts   (3 passing)

5. Review. bmad-code-review reads the diff and the story and returns a findings list (zero findings is a valid result).

/bmad-code-review

Illustrative (run it in your own repo; not machine-verified here).

[HIGH]  saveFilter: no uniqueness check on (userId, name), SPEC violated
[LOW]   test.ts: missing empty-filters case

Five commands, five files, one chain: brainstorm.html to prd.md to SPEC.md to story plus diff to findings. Each step's input is the last step's output on disk, which is why fresh chats work. Full runs of this shape, end to end, are the next page.

Under Claude Code: how a big skill surface stays cheap

On Claude Code every BMAD skill installs as a slash command, /<skill> (/bmad-help, /bmad-prd, /bmad-dev-story). You start one two ways: type it, or let Claude read the SKILL.md description and pick the match. That is the same split this page draws between a skill and an agent-menu trigger.

Dozens of commands stay affordable because of progressive disclosure. At session start only each skill's name plus description enter context, on the order of 50 tokens each. The full SKILL.md body loads only when the skill is invoked, and then it stays in context for the rest of the session. The whole listing is budget-capped: skillListingBudgetFraction defaults to roughly 1% of the context window, so a large install cannot crowd out your work. Under auto-compaction Claude keeps only about the first 5k tokens of the most recent invocation per skill, under a shared budget; older skills can drop entirely.

Arguments feed a skill by substitution: $ARGUMENTS (everything), $0/$1 (positional), or named $name once you declare arguments: in frontmatter. argument-hint shows in autocomplete, the way a trigger like DS in the table above hints its input.

Author your own one-off command as .claude/commands/<name>.md (the filename becomes the name) or the newer skill form. /help lists everything installed; /skills toggles each one's visibility (full / name-only / off), which mirrors filtering the installed skill directories this page tells you to find. What each skill produces is on the workflow map (page 4).

Net: BMAD's full inventory costs its descriptions, not its bodies, until you run a command.

That is the full working surface for core, BMM, and the official modules. The next page stops listing and starts doing: four complete project runs, from a blank idea to shipped code. 👉

End to end: four complete project runs

The map and the command reference are the pieces; this page assembles them. Four runs, start to finish: a greenfield product through the full method, a change to an existing codebase, a one-file quick fix, and an unattended autonomous loop. Each is a real sequence of commands with the artifact each step leaves behind.

One discipline threads through all four: a fresh chat per workflow. State lives in files, not in the conversation, so a clean context window costs nothing and stale conversational residue costs correctness. Start each bmad-* step in a new session and let it read what it needs from disk.

On this page

• Run 1: greenfield, idea to shipped (full BMad Method)
• Run 2: brownfield, a feature in an existing codebase
• Run 3: a quick fix (Quick Flow)
• Run 4: the autonomous loop (human on the loop)
• Hands-on: the greenfield flow, command by command
• Under Claude Code: running the four flows

Run 1: greenfield, idea to shipped (full BMad Method)

The scenario: a new "team task tracker with a public API," a project big enough to have several epics, so it earns the full four phases. The path, phase by phase.

Phase 1, Analysis: turn a hunch into evidence

bmad-help  I have an idea for a team task tracker, where do I start?

bmad-help recommends a starting point. For a fuzzy idea, brainstorm first, then pressure-test the survivor, then research what the decision rests on:

bmad-brainstorming     # 60+ techniques; pulls 100+ ideas out of you, then organizes
bmad-forge-idea        # interrogate the favorite until it hardens (forged-idea.md) or dies
bmad-deep-recon        # decision-grade research on the contested claims (research.md)

Then consolidate into a brief (collaborative) or a PRFAQ (a gauntlet):

bmad-product-brief     # brief.md: a 1-2 page executive summary
# or
bmad-prfaq             # prfaq-{project}.md: write the press release before any code

You leave Phase 1 with research.md, forged-idea.md, and brief.md in _bmad-output/planning-artifacts/, each a reviewed file the next phase reads. (Research itself is the subject of the recon gists; this run just uses it.)

Phase 2, Planning: what to build, and for whom

bmad-prd     # Create intent: coached discovery -> prd.md (FRs, NFRs) + .memlog.md
bmad-ux      # DESIGN.md (visual tokens) + EXPERIENCE.md (behavior, states, journeys)

bmad-prd source-extracts the brief so you do not re-explain the product. It runs in one of three intents: Create (new PRD), Update (reconcile a change, surfacing conflicts first), Validate (critique against a checklist, producing an HTML findings report). The PRD is the contract the architect reads next.

Phase 3, Solutioning: how, then in what units

This is the phase that pays for itself on multi-epic work, because it pre-empts the conflicting decisions that different agents would otherwise make.

bmad-architecture                    # ARCHITECTURE-SPINE.md: explicit decisions (ADRs)
bmad-generate-project-context        # project-context.md from the architecture
bmad-create-epics-and-stories        # epic files, each with implementable stories
bmad-check-implementation-readiness  # PASS / CONCERNS / FAIL gate over the whole chain

The readiness gate is the last cheap checkpoint. A CONCERNS like "story 3 has no guardrail metric" is caught here as a paragraph, not later in code review. Do not start Phase 4 on a FAIL.

Phase 4, Implementation: one story at a time

bmad-sprint-planning     # once: sprint-status.yaml sequences the cycle
# then, per story, each in a fresh chat:
bmad-create-story        # story-{slug}.md with full, focused context
bmad-dev-story           # working code + tests, test-first
bmad-code-review         # approved, or changes requested
# after the epic:
bmad-qa-generate-e2e-tests   # API/E2E tests once the epic's stories are done
bmad-retrospective           # lessons learned

If something big shifts mid-sprint (a requirement changes, an assumption breaks), do not patch downstream files by hand. Run bmad-correct-course, which reconciles the plan and re-routes, then let the change propagate through the artifacts.

The full greenfield trace, in one column:

brainstorm.html/-intent -> forged-idea.md -> research.md -> brief.md
  -> prd.md (+ DESIGN.md/EXPERIENCE.md)
  -> ARCHITECTURE-SPINE.md + project-context.md + epics/
  -> readiness PASS
  -> sprint-status.yaml -> story-*.md -> code+tests -> review -> QA -> retrospective

Run 2: brownfield, a feature in an existing codebase

The scenario: add "saved filters" to an app that already exists and was not built with BMAD. The extra work up front is teaching BMAD your codebase so its research and stories refer to the real system, not an imagined one.

# 1. Make the codebase a source the agents can cite
bmad-document-project            # scans and documents the current system
bmad-generate-project-context    # project-context.md: stack, versions, conventions

# 2. Then plan the change at whatever depth it needs
bmad-prd                         # Update intent if a PRD exists, else Create, scoped to the feature
bmad-architecture                # only if the change crosses epic boundaries
bmad-create-epics-and-stories
bmad-check-implementation-readiness

# 3. Implement as in Run 1
bmad-sprint-planning -> bmad-create-story -> bmad-dev-story -> bmad-code-review

Two brownfield specifics. First, bmad-quick-dev (Run 3) works on existing projects too: it auto-detects the stack, reads existing patterns, and asks "should I follow these existing conventions?" Answer yes to stay consistent, no to establish new standards (and document why in the spec). BMAD respects the choice; it will not force modernization but it will offer it. Second, if you are unsure whether you even need document-project, run it anyway; it is safe to run at any time to keep docs current, and cheap insurance against agents inventing an architecture you do not have.

Run 3: a quick fix (Quick Flow)

The scenario: a bug, or a one-file feature, small and well understood. The full method would be ceremony. Quick Flow compresses clarify, plan, implement, review, and present into a single skill that runs longer between checkpoints.

bmad-quick-dev
> Fix the off-by-one in pagination: the last page shows one duplicate row.

Intent can be a phrase, a bug-tracker link, a GitHub issue URL, output from plan mode, or a story number from epics.md. Quick Dev then:

1. Compresses intent into one coherent, contradiction-free goal, asking clarifying questions if needed. (Intent clarification is one of its three high-value human moments.)
2. Routes to the smallest safe path. A zero-blast-radius change can go straight to implementation; anything larger gets a spec first, which becomes the boundary it executes against. (Spec approval is the second human moment.)
3. Implements and self-reviews, deferring incidental findings not tied to the change into deferred-work.md rather than flooding you with nitpicks.
4. Commits locally and offers a push or PR. (Reviewing the result is the primary, third human moment.)

To hand the finished change to a human reviewer in comprehension order rather than file order, say checkpoint: bmad-checkpoint-preview walks the change by concern, flags the two to five highest-blast-radius spots, and suggests how to observe the change manually. Roll back a Quick Dev with git revert HEAD.

Run 4: the autonomous loop (human on the loop)

The scenario: an epic of well-specified stories you want implemented unattended, with a human watching rather than approving each step. This is the third of BMAD's "three flows" (Full Method, Quick Dev, and BMad Loop), and it shifts you from human in the loop to human on the loop.

The unit of unattended work is bmad-dev-auto: one iteration that clarifies intent, creates or resumes a spec, implements, reviews, and writes a terminal status to the spec's frontmatter. It requires the ability to spawn subagents, and (strongly recommended) a clean git tree. Its spec status is the machine-readable state an orchestrator drives on:

To run a whole epic, first break the spec into an ordered stories.yaml (produced on request by bmad-spec), then dispatch each story. You can do this by hand ("implement stories 2 to 10, using a subagent running bmad-dev-auto for each"), or let the BMad Loop module drive it deterministically:

bmad-loop-setup            # one-time: install the orchestrator and per-project hooks
bmad-loop run              # deterministic Python drives pick -> implement -> review -> verify -> commit
bmad-loop status | tui     # watch it; sprint-status.yaml is the single ledger
bmad-loop resolve <story>  # step in when a run pauses on a CRITICAL escalation

The loop keeps no LLM in the control path: plain Python sequences the steps while fresh-context coding-agent sessions do the creative work, dev and review in separate sessions so no anchoring bias carries over. You set how much oversight you want with gates.mode: none runs whole epics unattended, per-epic pauses between epics, per-story-spec-approval pauses for you to approve each spec before code. blocked is a routing signal, not just a failure: it usually means unattended execution would be unsafe and a human should look.

Hands-on: the greenfield flow, command by command

Pick a genuinely small project, one epic's worth, so the loop finishes in an afternoon. Open a fresh chat for each bmad-* line below, in this order. State lives on disk, so every new session reads the files the last one wrote; the comment on each line names the file it produces.

# Phase 1, Analysis (fresh chat each)
bmad-brainstorming                   # brainstorm.html: raw ideas, then organized
bmad-forge-idea                      # forged-idea.md: the survivor, pressure-tested

# Phase 2, Planning
bmad-prd                             # prd.md (+ .memlog.md): FRs, NFRs
bmad-ux                              # DESIGN.md + EXPERIENCE.md: tokens + behavior

# Phase 3, Solutioning
bmad-architecture                    # ARCHITECTURE-SPINE.md: decisions as ADRs
bmad-generate-project-context        # project-context.md: stack, conventions
bmad-create-epics-and-stories        # epics/ + stories: the work, in units
bmad-check-implementation-readiness  # readiness-report.md: PASS / CONCERNS / FAIL

# Phase 4, Implementation (per story, fresh chat each)
bmad-create-story                    # stories/story-{slug}.md: focused context
bmad-dev-story                       # working code + tests, test-first
bmad-code-review                     # approved, or changes requested

# Close the epic
bmad-retrospective                   # retrospective.md: lessons learned

For a project this small the sequence drops three optional steps from Run 1: bmad-deep-recon (research.md) and bmad-product-brief (brief.md) earn their place only when a decision needs evidence, and bmad-sprint-planning (sprint-status.yaml) pays off once there is more than one story stream to sequence. Add them back the moment the scope grows. Note that bmad-check-implementation-readiness writes no code; it emits a verdict, so stop and fix on a FAIL before any story starts.

After a clean run over three stories, _bmad-output/ looks like this:

Illustrative (run it in your own repo; not machine-verified here).

_bmad-output/
├── planning-artifacts/
│   ├── brainstorm.html
│   ├── forged-idea.md
│   ├── prd.md
│   ├── .memlog.md
│   ├── DESIGN.md
│   ├── EXPERIENCE.md
│   ├── ARCHITECTURE-SPINE.md
│   ├── project-context.md
│   └── readiness-report.md
├── epics/
│   └── epic-1-core-tasks.md
├── stories/
│   ├── story-create-task.md
│   ├── story-list-tasks.md
│   └── story-public-api.md
└── retrospective.md

Read the tree top to bottom and you are reading the method: each file is the reviewed input to the workflow below it, from a raw brainstorm down to the retrospective that closes the epic. Paste the sequence, and watch the chain grow one reviewed file at a time.

Under Claude Code: running the four flows

The four runs map onto one control: the permission mode, the per-phase autonomy dial. It goes from default (read tools only) up through acceptEdits, plan, auto, to bypassPermissions (every tool, no prompt). Shift+Tab cycles it live.

Greenfield. Run the planning phases in plan mode: Shift+Tab to plan, where Claude reads and proposes but edits nothing until you approve the ExitPlanMode plan. Analysis, PRD, and architecture all fit that read-and-propose shape. When one story is genuinely hard, escalate the model for that session with /model opus, then drop back.

Brownfield. The existing monolith sits outside the project root, so grant access with /add-dir <path> (or launch with --add-dir <path>). Claude can then cite the real system, and it also loads that directory's .claude/skills/.

Quick fix. Launch with --permission-mode acceptEdits so file edits land without a prompt while you review; Bash still gates by command.

Autonomous. Go headless:

claude -p "run the story" --bare --permission-mode acceptEdits \
  --max-budget-usd 5 --max-turns 40 --output-format json

--bare strips hooks, skills, MCP, and CLAUDE.md for a clean run; --max-budget-usd and --max-turns bound it; the JSON result carries per-turn token usage.

Between phases, /clear opens a fresh window (state lives in files) or --resume <id> / --continue carries context forward. A wrong turn rewinds with /rewind, which restores Claude's file edits and the conversation but not committed git history or Bash side effects. For those, use git.

Whichever run you are on, the through-line is the same: a reviewed artifact at every boundary, with the human's attention spent where it counts most, framing the work and judging the result, not typing every step. The next page is about the files that make that possible across sessions: how BMAD saves memory, and how to measure whether it is actually helping. 👉

Memory and measurement in BMAD

Two questions this page answers. How does BMAD remember anything across sessions, given that a chat's context window is gone the moment you close it? And how do you tell whether the method is earning its overhead, rather than becoming ceremony? The first is about state; the second is about metrics. Both come down to files.

On this page

• The one principle: externalized state
• Four kinds of memory
• Resuming: how work picks back up
• Measuring whether BMAD helps
• Improving the workflow over time
• Hands-on: write a project-context.md, then watch memory work
• Under Claude Code: CLAUDE.md, compaction, and where BMAD’s files fit

The one principle: externalized state

BMAD's design rule is that every result that must affect a later phase becomes a file. The conversation is a control channel, never the store. A fresh chat then becomes a quality feature (clean context, no stale residue) rather than a reset, because everything that matters was written down. This is why the docs insist on a fresh chat per workflow: the cost of losing the conversation is zero when the state is on disk.

Concretely, here is what survives a fresh chat and what does not:

Four kinds of memory

BMAD keeps memory in four distinct places, and confusing them is the root of most "the agent forgot" complaints.

1. The memlog: process memory for one piece of work. Skills that run a long session (PRD, brainstorm, deep-recon) keep a .memlog.md: an append-only, chronological log written through a shared script (_bmad/scripts/memlog.py). Every decision, idea, question, and assumption is one line, recorded in the order it happened; the chronology itself is the structure. It is not a deliverable, it is working memory that persists across sessions, so a fresh session can read the last few lines and continue. Downstream artifacts (a brief, a PRD, a report) are derived from it on demand. Three invariants make it trustworthy: it is append-only (history is never rewritten), write-only (each command echoes state so the caller never re-reads the file mid-session), and status-free (whether work is done, blocked, or paused is itself just another logged event, so the log never has to mutate).

2. project-context.md: durable memory for the whole project. The constitution from the anatomy page. It is not session memory; it is standing memory that every implementation workflow reloads, so a convention you record once ("all API calls go through the apiClient singleton") is enforced across every future story, forever, without re-explaining. Treat it as a living file: when you catch an agent repeating a mistake, the fix is usually a line here.

3. The artifact chain: memory between phases. research.md, brief.md, prd.md, ARCHITECTURE-SPINE.md, and each story-*.md are typed, reviewable messages from one context to the next. Winston (the architect) can run in a fresh chat weeks after John (the PM) because John's decisions are in the PRD, not in a scrollback John no longer has. The artifact metadata (frontmatter with type, dates, source, status) is what lets a downstream skill trust an upstream one without reprocessing it. Deep Recon's staleness map is a specialized form of this: a per-claim record of when evidence needs re-checking, so research becomes a thing you maintain rather than redo.

4. Config and roster: memory of how the team works. The _bmad/custom/*.toml overrides and the agent roster in central config are standing memory of your org's conventions, applied on every activation. Party Mode adds a fifth, narrow form: each saved party keeps its own memory of past sessions (dynamics, open threads, where a conversation landed), which is "memory, not a transcript," carrying only the few things worth remembering.

Resuming: how work picks back up

Because state is on disk, resuming is reading, not remembering. A few concrete mechanisms:

• Any workflow re-reads its inputs and its own .memlog.md on activation, so you can close a PRD session and reopen it days later.
• bmad-dev-auto resumes from a spec's frontmatter status (draft -> plan, ready-for-dev/in-progress -> implement, in-review -> review, blocked -> halt). An orchestrator reads status, the blocking condition, and baseline_revision..final_revision to know exactly what a run produced, rather than inferring success from chat output.
• bmad-sprint-planning writes sprint-status.yaml, the single ledger the whole cycle (and the BMad Loop orchestrator) reads to know which stories are done, in review, or pending.
• Deep Recon writes every digest to its run folder the moment it lands, so a run that dies mid-flight resumes from disk with nothing lost.

The practical takeaway: if you want something to be remembered, make sure a skill wrote it to a file. If a decision lives only in a chat you closed, BMAD did not externalize it, and the next agent will not know it.

Measuring whether BMAD helps

A method that is never measured drifts into ceremony: more documents, not better decisions. The honest question is not "did we follow the process" but "did the process change outcomes." A scorecard worth tracking:

Two of these have mechanical support already. Deep Recon's recon_kit.py tally counts claims by verification status straight from the memlog, so "share of claims verified" is a script, not a vibe. And bmad-dev-auto's baseline_revision..final_revision bracket gives you exact per-run diffs to measure rework against. The rest you instrument yourself, but the discipline is simply to write the numbers down rather than allocate effort by enthusiasm.

The anti-metric to avoid is "number of artifacts produced." A two-page PRD that prevents a wrong database schema is worth more than fifty polished pages nobody reads. Optimize for decisions changed and mistakes prevented, not pages shipped.

Improving the workflow over time

BMAD gives you four levers to tune the method to your team, each backed by a file:

• Retrospectives. bmad-retrospective after an epic captures what the process got right and wrong. Feed its lessons back into project-context.md and your overrides so the next epic starts smarter.
• Course correction. When reality diverges from the plan, bmad-correct-course reconciles the artifacts instead of letting documents quietly contradict each other. Do not patch downstream files by hand; fix the upstream owner and let it propagate.
• Deferred work. Quick Dev and the loop write incidental findings to deferred-work.md rather than flooding a review, and bmad-loop-sweep triages that ledger later. The workflow optimizes for signal quality over exhaustive recall on purpose: it is usually better to defer some findings than to bury a human in low-value comments.
• Customization. Every recurring correction you make by hand is a candidate for a _bmad/custom/*.toml override (see team collaboration and extending). A rule you state once in an override is a rule you never re-type.

And one dial worth naming: gates.mode sets how much you stay in the loop, per-story-spec-approval, per-epic, or none. Start careful and loosen it as your trust in the pipeline (measured, per the scorecard above) grows. That is the shift from human in the loop to human on the loop, earned with evidence rather than assumed.

Hands-on: write a project-context.md, then watch memory work

This exercise separates the two memories that get conflated: project-context.md (durable, reloaded every workflow) and .memlog.md (per-run, append-only). You author the first by hand, let a dev story populate the second, then feed a lesson back up.

1. Author the durable file. Keep it lean. Record only rules an agent could not infer from the code in front of it: the queue rule, the tenancy rule, the no-ad-hoc-threads rule, the naming convention. Obvious conventions are noise.

# Project context: billing-svc

## Rules (non-obvious only; obvious ones omitted)
- Async work goes through the single RQ queue `bill.default`. No raw `Thread`, no `asyncio.create_task` in request handlers.
- Every table carries `tenant_id`; every query filters on it. There is no global read.
- Money is `Decimal` stored as integer cents. Never `float`.
- Module naming: services are `verb_noun.py`; RQ jobs are `noun.verb` (`invoice.finalize`).
- Idempotency keys are required on every mutating endpoint; replay returns the stored result.
- Stripe webhooks are the source of truth for payment state, not our own writes.

Write it to _bmad-output/project-context.md and commit it. From now, every implementation workflow reloads these, so you never re-explain them.

2. Or let BMAD draft one. To start from the codebase instead, the skill scans it and proposes rules for you to prune:

# In the BMAD agent chat, invoke the workflow:
bmad-generate-project-context

Illustrative (run it in your own repo; not machine-verified here).

Scanned 214 files. Proposed project-context.md (7 rules):
1. Async work uses RQ, not raw threads (rq imported in 9 handlers)
2. All models include tenant_id (present on 18/18 tables)
3. Money stored as integer cents (Decimal in ledger.py)
4. Service modules follow verb_noun.py naming
5. Idempotency keys on POST/PUT (found on 11/14 routes; 3 missing, flagged)
6. Stripe webhooks drive payment state
7. Config via pydantic Settings, not direct os.environ reads
Wrote draft to _bmad-output/project-context.md. Review and prune.

Treat the draft as a candidate list. Delete anything obvious; the value is the four or five rules that are not.

3. Run a dev story; watch per-run memory fill. Kick off bmad-dev-auto on a spec. As the dev agent makes choices it appends one line each to that run's .memlog.md through the shared script (the real logger is dissected on page 11):

bmad-dev-auto story-042
tail -f _bmad-output/implementation-artifacts/story-042/.memlog.md

Illustrative (run it in your own repo; not machine-verified here).

- (decision by dev) all async work goes through the single RQ queue `bill.default`; rejected a per-request thread
- (assumption by dev) the Stripe webhook lands before the client polls; retry covers the gap
- (question by dev) does `invoice.finalize` need its own idempotency key, or reuse the request's?

This is working memory for one story. It resumes a paused run; it is not a standing rule.

4. Feed a lesson back. After the epic, bmad-retrospective surfaces what recurred. Turn each durable lesson into one project-context line so it never repeats:

bmad-retrospective

Then append the distilled rule (not the story) to project-context.md:

- Webhook handlers must be idempotent by event id; a re-delivery double-charged once.

The memlog line was about one story; the project-context line changes every future story. That is the loop: per-run memory records what happened, the retrospective distills it, durable memory enforces it forever.

Under Claude Code: CLAUDE.md, compaction, and where BMAD's files fit

Claude Code has its own memory layers, and BMAD's externalized state maps onto them cleanly. CLAUDE.md is the always-on constitution: a managed policy file, then user (~/.claude/CLAUDE.md), project (./CLAUDE.md or .claude/CLAUDE.md), local (CLAUDE.local.md, gitignored), and nested per-subdirectory files, all loaded at session start. That is the slot BMAD's project-context.md plays (see the anatomy page): standing rules reloaded every session, no re-explaining. You extend it with @path imports (resolved relative to the file, up to 4 levels deep), append a single line with #, or edit through /memory.

Auto memory is a separate store at ~/.claude/projects/<slug>/memory/, indexed by MEMORY.md (only its first 200 lines or 25KB load at session start) with topic files pulled on demand. That is the closest native analog to BMAD's .memlog.md: process notes that carry across sessions, except Claude Code decides what to write, whereas the memlog is append-only and script-driven.

/context shows the live budget by category (system prompt, CLAUDE.md, loaded files, conversation, skills). As the window nears roughly 95%, Claude Code auto-compacts: it drops older tool outputs first, then summarizes earlier conversation, keeping CLAUDE.md, skills, and recent messages. /compact [focus] does the same on demand, and a PreCompact hook can fire first.

The load-bearing point matches this chapter exactly. BMAD's artifacts, memlog, and project-context.md live on disk and are re-read at the start of each workflow, so they survive compaction and /clear; anything living only in the conversation does not. --resume carries a window forward, a fresh session drops it, both by design.

Memory and measurement are what make BMAD a team practice rather than a solo one. The next page is about the team itself: shared config, who runs which phase, and how BMAD keeps several people (and several agents) from stepping on each other. 👉

Team collaboration

BMAD started as a solo practice and most of its machinery assumes one human driving one project. Using it with a team works well for the parts BMAD models directly (shared conventions, a reviewed artifact chain, consistent agents) and requires you to supply the parts it does not (assigning who runs which phase, coordinating several humans). This page covers both honestly.

On this page

• What coordinates a team: files, not agents
• The three customization layers, and who owns each
• Six things a team commits once
• Who runs which phase
• Preventing conflicts between agents (and people)
• The honest gap: multiple humans
• Web bundles: planning on a flat rate
• Hands-on: make a repo team-ready in five files
• Under Claude Code: shared config, scopes, and policy

What coordinates a team: files, not agents

The coordination layer in BMAD is the artifact chain in git, not any messaging between agents. A PRD, an architecture doc, and a story file are how one person's decisions reach another person (and another person's agent). This is the same externalized-state principle from the memory page, applied to people: if it is in _bmad-output/ and committed, the whole team (and every agent) sees it; if it is in someone's chat, it does not exist. So the first rule of team BMAD is the commit rule from the anatomy page: commit the _bmad-output/ spec chain and the team *.toml overrides; the *.user.toml files stay personal and gitignored.

The three customization layers, and who owns each

Team behavior is shaped through three override scopes, and knowing which is which keeps personal preferences out of shared config:

Each has a .user.toml sibling for personal overrides, always gitignored. The resolver merges shipped defaults, then the team file, then the personal file, at every activation, so an individual can adjust an agent's tone without disturbing the team's rules.

Six things a team commits once

The highest-value team setup is a handful of overrides checked into main. These are the recurring org recipes:

1. Shape an agent across every workflow. Put standing rules in an agent's persistent_facts and they apply to every workflow it runs. Example: tell Amelia (dev) in bmad-agent-dev.toml to always look up library docs via your Context7 MCP tool and fall back to Linear when a story is not in the local epics. Every dev-story, quick-dev, create-story, and code-review inherits it. This is the single highest-impact pattern.
2. Enforce conventions in a workflow. A bmad-product-brief.toml or bmad-prd.toml persistent_facts entry can require certain fields or point at a conventions doc with a file: reference.
3. Publish outputs to external systems. A workflow's on_complete (runs once at the terminal step) can push the finished artifact to Confluence or open a Jira issue via MCP. Use on_complete for the one-time publish and activation_steps_append for something that should run on every activation.
4. Swap templates. Override a scalar like brief_template or prd_template to point at your enterprise template instead of the shipped one.
5. Customize the roster. In central config, rebrand an agent's description, add a fictional or specialist agent (a descriptor with no skill folder is enough for Party Mode to include it), or pin team-wide install settings like [core] document_output_language and [modules.bmm] planning_artifacts. Personal settings (user_name, communication_language, user_skill_level) stay in each developer's _bmad/config.user.toml.
6. Advanced integration. Some workflows expose external_sources (on-demand MCP knowledge lookups), external_handoffs (publish steps that degrade gracefully if a tool is offline), and doc_standards (finalize-time writing standards). bmad-prd exposes all of them; check a skill's customize.toml to see its surface.

Reinforce the load-bearing rules a second time in your IDE session file (CLAUDE.md, AGENTS.md, .cursor/rules/, or .github/copilot-instructions.md), which loads before any skill each session. Keep it short; the overrides are the source of truth, the session file is the reminder.

Who runs which phase

The common division of labor mirrors a Scrum team, which is not an accident: BMAD's personas are modeled on one.

• Planning phases in a web subscription. Brainstorm, brief, PRFAQ, PRD, UX, and research are conversation-heavy and cheap on a flat rate. Run them as web bundles (Gemini Gems or ChatGPT Custom GPTs) or in a browser agent, then commit the artifacts.
• Solutioning and implementation in the IDE. Architecture, stories, dev, and review need the codebase and the terminal, so they run where the code is.
• One owner per artifact. Assign each document an owner the way you assign code ownership: a PM owns the PRD, an architect owns the architecture spine, a dev owns a story. The owner runs the workflow; the team reviews the output in a PR.

Preventing conflicts between agents (and people)

When different people (or different agents) implement different epics, they can make incompatible technical decisions: one builds REST, another GraphQL; one uses snake_case columns, another camelCase. BMAD prevents this the same way a good team does, with shared, written decisions:

• Architecture and ADRs are the shared context every implementer reads first. Document the decisions that cross epic boundaries (API style, database, auth, state management, styling, testing) as ADRs with context, options, decision, and consequences. This is exactly why solutioning matters: an alignment issue caught here is about 10x cheaper than one found mid-sprint.
• project-context.md is the per-project constitution every implementation workflow loads, so naming, testing, and framework conventions are consistent across whoever (or whatever) is implementing.
• Review with fresh context. BMAD's review skills run adversarially and, where the platform allows, in context-free subagents that see the artifact but not the author's reasoning, so they judge the work, not the intent. That is a feature for a team: a reviewer who cannot see "what you meant" catches what a charitable reader misses.

The honest gap: multiple humans

BMAD does not yet have first-class multi-human coordination. Agents work in isolation with no central coordination point built in, and the maintainers acknowledge this openly in community discussions; an enterprise collaboration playbook has been in progress but is not finalized. Until it lands, the working patterns are:

• Coordinate through git and PRs, not through BMAD. Branch per epic or story, review the artifact chain and the code together, and resolve conflicts the ordinary way.
• Put hand-off notes in the artifacts themselves (the community workaround): an epic or story that another person or agent will pick up should say so in its text, since there is no automatic inter-agent messaging.
• Keep sprint-status.yaml as the single shared ledger of what is done, in review, and pending, and commit it so everyone (and the BMad Loop orchestrator) reads the same state.
• Treat manifest.yaml plus a documented install command as the way to keep everyone on the same BMAD version; a teammate on a different version gets subtly different behavior.

Community MCP servers (see extending) partly close the gap by exposing BMAD's agents as shared, install-once tools rather than per-project file copies, but they are third-party, not official.

Web bundles: planning on a flat rate

For teams, the economics of planning matter: a PRFAQ pass and three rounds of research in a chat subscription cost zero marginal dollars, while the same work in a metered IDE session is real spend. BMAD packages its planning skills as Gemini Gems and ChatGPT Custom GPTs for exactly this.

• Install only from bmadcode.com/web-bundles: pick a bundle, download the ZIP, create a Gem or Custom GPT, upload the knowledge files, and paste the instructions block. The current shelf covers brainstorming, product brief, PRFAQ, PRD, UX, and market/industry research.
• A bundle is a SKILL.md protocol (a knowledge file) plus an INSTRUCTIONS.md persona block (pasted into the Gem/GPT). Because "the persona lives in the pasted instructions and the protocol lives in the knowledge file," you customize the persona for your org without touching the protocol, and updates are a swap-the-attachments operation.
• Prerequisites: Gemini Gems need Gemini Advanced; Custom GPTs need a paid ChatGPT plan; the research bundle needs Deep Research enabled. Web LLMs drop a persona in long sessions, so remind or restart. The work happens in Canvas and comes back to the repo as the committed artifact.
• Build your own from any BMAD skill with the bmad-os-skill-to-bundle utility.

Hands-on: make a repo team-ready in five files

Goal: paste these files, commit, and every clone activates with the same model, the same pre-approved commands, and a hook that mechanically blocks a direct push to main. This is the commit-the-team-overrides, gitignore-the-personal-ones rule from the top of this page, in Claude Code's own config.

The shared policy lives in .claude/settings.json. It pins the model, pre-approves a read-and-test command set (so no one re-approves git status every session), and wires the push guard:

{
  "model": "claude-opus-4-8",
  "includeCoAuthoredBy": true,
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(git add:*)",
      "Bash(npm test:*)",
      "Bash(npm run lint:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-direct-push-main.sh"
          }
        ]
      }
    ]
  }
}

The guard is the hook. Claude Code runs a PreToolUse hook as a shell command: it receives the tool call as JSON on stdin and returns a decision on stdout. .claude/hooks/no-direct-push-main.sh reads .tool_input.command, and if it is a git push to main or master, emits a deny:

#!/usr/bin/env bash
# PreToolUse(Bash) hook: block a direct push to main/master.
# Reads the tool call as JSON on stdin; writes a decision as JSON on stdout.
set -euo pipefail

cmd=$(cat | jq -r '.tool_input.command // ""')

if printf '%s' "$cmd" | grep -Eq 'git[[:space:]]+push' &&
   printf '%s' "$cmd" | grep -Eq '(^|[[:space:]])(origin[[:space:]]+)?(main|master)([[:space:]]|:|$)'; then
  jq -n '{
    hookSpecificOutput: {
      hookEventName: "PreToolUse",
      permissionDecision: "deny",
      permissionDecisionReason: "Direct push to main is blocked. Open a PR."
    }
  }'
fi

# No output = no decision: normal permission flow continues.
exit 0

It needs jq and the executable bit:

chmod +x .claude/hooks/no-direct-push-main.sh

Keep personal state out of the shared tree with .gitignore:

.claude/settings.local.json
CLAUDE.local.md

settings.local.json holds a developer's own model or extra allows; CLAUDE.local.md is a personal scratchpad. Both stay off main. The one shared reminder every session loads is CLAUDE.md; keep it short, since settings.json is the source of truth:

# Team baseline
Direct pushes to `main` are blocked by a hook. Open a PR. Run `npm test` before committing.

Commit the four shared paths:

git add .claude/settings.json .claude/hooks/no-direct-push-main.sh .gitignore CLAUDE.md
git commit -m "chore: shared Claude Code team baseline"

Confirm the guard by asking the agent to git push origin main:

Illustrative (run it in your own repo; not machine-verified here).

PreToolUse:Bash hook denied Bash: Direct push to main is blocked. Open a PR.

The honest limit is the one this page opened with. This baseline coordinates one developer's agent: it makes that agent obey the team's model, allowlist, and push rule. It does not coordinate the humans. Two teammates whose agents both honor the hook still reconcile through branches and PRs. The hook enforces the floor; running the review is still yours.

Under Claude Code: shared config, scopes, and policy

BMAD's team discipline (commit the shared overrides, gitignore the personal ones) maps directly onto how Claude Code splits config across a precedence stack. The same "in git or it does not exist" rule applies. A team shares its setup by committing five paths so every clone activates identically: .claude/settings.json (permissions, hooks, model), .claude/skills/, .claude/agents/ (subagents), .claude/rules/, and .mcp.json (MCP servers). Personal deviations go in .claude/settings.local.json and CLAUDE.local.md, both gitignored, so a tone tweak or a machine path never lands in shared config. That is BMAD's *.toml (team, committed) versus *.user.toml (personal, gitignored) split, one layer up.

Org-wide guardrails that no clone may override live in the enterprise managed policy: a settings.json and a CLAUDE.md at a system path (/Library/Application Support/ClaudeCode/ on macOS, /etc/claude-code/ on Linux). It sits at the top of precedence and cannot be overridden locally, unlike BMAD's overrides, which any developer can shadow with a .user.toml. Where BMAD relies on written convention, Claude Code can enforce mechanically: a PreToolUse hook inspects the tool call and returns permissionDecision: "deny" to block a git push or a deploy for everyone on the repo. includeCoAuthoredBy controls the commit trailer. The honest gap from this chapter survives the mapping intact: Claude Code drives one developer's agent, so multi-human coordination stays in git and PRs, not in the tool.

The team layer is really just the file-and-override discipline applied to more than one person. The next page goes the other direction: making BMAD do more, through customization, MCP, custom skills, and whole new modules. 👉

Extending BMAD: customization, MCP, skills, and modules

BMAD is built to be shaped. This page is the extension ladder: from a one-line override, through wiring in your own tools over MCP, up to authoring whole new skills and modules. The guiding rule is to use the smallest mechanism that expresses the need, so you gain behavior without gaining a fork you can never upgrade.

On this page

• The extension ladder
• Customization in practice
• MCP: wiring your tools into BMAD
• Building your own with BMad Builder
• Custom and community modules
• Choosing the right surface
• Hands-on: extend BMAD with an MCP server, a hook, and a skill
• Under Claude Code: MCP, hooks, skills, and plugins in depth

The extension ladder

Most needs are satisfied at the top of the ladder. "All our recommender claims must name a baseline and population" is a one-line override; "a reusable offline-evaluation workflow with its own templates" is a custom skill or module; forking to add one evidence column is disproportionate.

Customization in practice

Overrides are sparse TOML files under _bmad/custom/ (see the resolution rules on the anatomy page). The surfaces you will reach for, across agents and workflows:

• persistent_facts (append array): literal sentences or file: references that load on every activation. The workhorse for org rules and MCP routing.
• activation_steps_prepend / _append (append arrays): instructions to run before or after the standard activation flow.
• on_complete (scalar or array): runs once at the terminal step, for publishing or a final review pass.
• [[agent.menu]] (merged by code): add or replace menu items, each bound to a skill or a prompt.
• template and checklist swaps (scalars like prd_template, validation_checklist): point at your own files.
• external_sources / external_handoffs / doc_standards: on-demand knowledge lookups, publish steps that degrade gracefully, and finalize-time writing standards.

You can hand-author these, but bmad-customize scans the installed skills, picks the right scope, writes the file, and verifies the merged result, which is safer than guessing which surface a field belongs to. Two specialized customizations worth knowing: Deep Recon takes custom research packs (a new research type defined in an override, encoding your source hierarchy and freshness rules, see the recon how-to), and both Party Mode and bmad-review take custom personas and lenses the same way, so you can ship a review panel or a focus-group cast your whole team shares.

MCP: wiring your tools into BMAD

MCP (the Model Context Protocol) is how BMAD reaches tools and data your AI host does not have built in: your documentation index, your issue tracker, your database, a web-search backend. There are two directions, and the official one is the first.

Consuming MCP tools inside workflows

BMAD does not install MCP servers; your AI host does. Once a server is connected in your host, you point BMAD's workflows at its tools through the override surfaces above, by their exact tool names. A team override that makes the dev agent always consult your docs server and file tickets on completion:

# _bmad/custom/bmad-agent-dev.toml  (committed; applies to every dev workflow)
[agent]
persistent_facts = [
  "For any external library, resolve docs via mcp__context7__resolve_library_id then mcp__context7__get_library_docs before writing code.",
  "If a story is not in the local epics, look it up with mcp__linear__search_issues.",
]

# _bmad/custom/bmad-prd.toml  (publish the finished PRD)
[workflow]
on_complete = "Publish prd.md to Confluence with mcp__atlassian__confluence_create_page; on approval, open a tracking issue with mcp__atlassian__jira_create_issue."
external_sources = [
  "Company handbook (notion): consult for policy questions only when a requirement touches compliance.",
]

The one caveat that bites people: hardcoded tool names only work if the MCP server is actually connected in the session. Use the exact names the server exposes (they vary by server), and expect graceful skips rather than hard failures when a tool is absent; external_handoffs in particular is designed to degrade if a tool is offline. Deep Recon also discovers installed search-shaped MCP tools at its plan gate and can route to them, with external_sources adding guidance the discovery cannot infer (see the recon how-to).

BMAD packaged as an MCP server (community)

The reverse pattern exists too: several community projects package BMAD's agents and workflows as an MCP server, so any MCP client (Claude Desktop, VS Code with Copilot, Cline) can call BMAD's personas as tools, installed once and used across every project rather than copied into each repo. These are third-party, not official, so vet them like any dependency, but they are the current answer to "install BMAD once, use it everywhere," a capability the official roadmap lists as "Centralized Skills" but has not yet shipped.

Building your own with BMad Builder

BMad Builder (bmb) is the meta-module for extending the framework itself. It ships five skills:

Everything BMad Builder produces sits on the Agent Skills open standard (the same SKILL.md format Claude Code and 40+ other tools use), so a skill you build is portable, not BMAD-locked. The workflow is conversational: describe the agent or workflow you want, the builder scaffolds it, and bmad-eval-runner grades it against evals so you ship something tested rather than hoped. When a skill is worth reusing across projects, wrap it in a module and publish it.

Custom and community modules

A module is a family of skills, agents, and config distributed as a unit. You add them at install time:

# From a Git URL or local path (repeatable, comma-separated)
npx bmad-method install --directory . --custom-source https://github.com/org/my-module --tools claude-code --yes
npx bmad-method install --directory . --custom-source /path/to/local-module --tools claude-code --yes

The installer resolves a source two ways. If it contains a .claude-plugin/marketplace.json, discovery mode lists every plugin in the manifest and you pick; otherwise direct mode scans the directory for skills (subdirs with a SKILL.md) and installs it as one module. That manifest file is a cross-tool convention, not a Claude-specific one, so a module works across hosts. Local sources are referenced by path and re-read on update, so deleting the source keeps installed files but skips it until the path returns.

For discovering community work, the interactive installer offers a browse step over the curated plugins marketplace (organized by category, pinned to approved commits for safety), and a first-party marketplace with one-command install is on the roadmap. To publish your own, build it with bmad-module-builder, include a marketplace.json for discovery mode, push it to Git, and share the --custom-source URL.

Choosing the right surface

A quick decision guide for "the model can't do X":

• If the model knows the data exists but cannot reach it, add an MCP server or connector.
• If it can reach the data but uses it inconsistently, add or customize a skill (an override, usually).
• If a whole domain needs its own agents, workflows, and standards, build a module.
• If work decomposes into independent searches, use subagents (already how Deep Recon and the review skills parallelize); do not install a module just for parallelism.
• If an operation must be deterministic and testable, prefer a real CLI or API over asking the model to imitate it, which is exactly why BMad Loop is Python and Deep Recon hands its counting to a script.

Hands-on: extend BMAD with an MCP server, a hook, and a skill

Three artifacts, one per rung: a tool source over MCP, a deterministic gate over a hook, a method over a skill. Each command is real; run them in your own repo.

1. Add a docs tool over MCP. Context7 serves current library documentation. Add it at project scope so the config commits and every teammate inherits it:

claude mcp add --transport http --scope project context7 https://mcp.context7.com/mcp

That writes .mcp.json:

{
  "mcpServers": {
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp"
    }
  }
}

Its tools now namespace as mcp__context7__resolve_library_id and mcp__context7__get_library_docs. Route the dev agent to them with one line on the persistent_facts surface of its override (see the resolution rules on the anatomy page):

# _bmad/custom/bmad-agent-dev.toml   (the customize.toml surface)
[agent]
persistent_facts = [
  "For any external library, resolve docs via mcp__context7__resolve_library_id then mcp__context7__get_library_docs before writing code.",
]

2. Gate prod deploys with a hook. A PreToolUse hook sees every tool call before it runs, reads the tool JSON on stdin, and answers on stdout. Author .claude/hooks/block-prod-deploy.sh:

#!/usr/bin/env bash
# PreToolUse hook: deny Bash commands that target prod, allow everything else.
set -euo pipefail

input=$(cat)
tool=$(printf '%s' "$input" | jq -r '.tool_name // ""')
cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // ""')

if [ "$tool" = "Bash" ] && printf '%s' "$cmd" | grep -Eiq 'deploy.*(prod|production)|--env[= ]prod'; then
  printf '{"permissionDecision":"deny","permissionDecisionReason":"Prod deploy blocked by BMAD policy; ship through the staging workflow or an approval gate."}'
else
  printf '{"permissionDecision":"allow"}'
fi

Wire it in .claude/settings.json under hooks.PreToolUse, matched to Bash:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": ".claude/hooks/block-prod-deploy.sh" }
        ]
      }
    ]
  }
}

A deploy --env prod from any agent, BMAD or not, is now denied deterministically; the model never has to remember the rule.

3. Ship a method as a skill. .claude/skills/release-notes/SKILL.md gives you a /release-notes command on the same Agent Skills standard bmad-agent-builder emits:

---
name: release-notes
description: Draft release notes from merged PRs and the changelog since the last tag. Use when the user asks for release notes or a changelog summary.
---

# Release notes

1. Read `CHANGELOG.md` and `git log <last-tag>..HEAD --oneline`.
2. Group entries into Features, Fixes, and Breaking.
3. Write a dated section, one imperative line per change.

Make the hook executable and confirm the server connected:

chmod +x .claude/hooks/block-prod-deploy.sh
claude mcp list

Illustrative (run it in your own repo; not machine-verified here).

context7: https://mcp.context7.com/mcp (HTTP) - ✓ Connected

Inside a session, /mcp shows the connection and OAuth state, /release-notes invokes the skill, and a deploy --env prod draws the deny. The three surfaces are independent: remove any one and the others still work. That is the extension ladder made concrete, one artifact per rung, before the deep dive below.

Under Claude Code: MCP, hooks, skills, and plugins in depth

BMAD's extension ladder is host-agnostic; Claude Code implements it across four concrete surfaces, one per rung.

Tools over MCP. You do not install servers from inside BMAD; you run claude mcp add <name> <target> at local, user, or project scope. Project scope writes a committed .mcp.json whose mcpServers map holds a command/args pair for type: "stdio" or a url for type: "http" (SSE included). /mcp manages connections and OAuth sign-in. Tools then namespace as mcp__<server>__<tool>, exactly the mcp__context7__resolve_library_id and mcp__linear__search_issues strings the override above hardcodes. A server exposing dozens of tools does not flood context: schemas are deferred by default and pulled on demand through ToolSearch (ENABLE_TOOL_SEARCH auto-loads all only when they fit in about 10% of the window, else defers).

Method over SKILL.md. The chapter's "an MCP server supplies tools, a skill supplies method" is literal here. Author .claude/skills/<name>/SKILL.md (or .claude/agents/<name>.md for a subagent) and the method arrives portably, on the same Agent Skills standard bmad-agent-builder emits.

Enforcement over hooks. Between tools and method sits the deterministic layer. Wire shell commands in settings under hooks.<Event> (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, PreCompact). They trade JSON on stdin/stdout; a PreToolUse hook returns permissionDecision allow/deny plus a rewritten tool_input, so a BMAD policy (block a command, redact output, gate a deploy) holds without trusting the model to remember it.

Distribution over plugins. Bundle skills, agents, hooks, and a .mcp.json behind plugin.json and share via /plugin marketplace; BMAD itself can ship this way, the tools arriving over .mcp.json and the method over SKILL.md.

An MCP server supplies tools, not a method; a BMAD skill supplies a method, not credentials. Together they give you disciplined work over your own systems, which is the whole point of extending BMAD rather than replacing it. The next pages go deeper: first under the hood, into how BMAD actually works from its own source. 👉

BMAD internals, from the source

This page opens BMAD v6.10.0 and reads how it actually works, from the source tree, not the docs. When you type a skill, a specific sequence of file reads, Python resolver calls, and just-in-time step loads happens; this is that sequence, with the real file paths and the load-bearing rules quoted from the code. It is the deepest page in the guide and assumes the map and anatomy pages. Paths are relative to the BMAD repo root; line references are from the v6.10.0 tree.

On this page

• The one structural fact: everything is a skill
• SKILL.md anatomy
• Just-in-time step loading
• The resolver scripts
• module.yaml and central config
• The installer
• quick-dev and dev-auto: two flavors of one pipeline
• v6-shims: how old skill names keep working
• Two things that will trip an expert
• The design invariants worth stealing
• Hands-on: run the resolver and the memlog yourself
• Under Claude Code: two just-in-time systems, stacked

The one structural fact: everything is a skill

There is no separate "agent type" or "workflow type" in the source. Agents, workflows, tasks, and tools are all skills: a directory containing a SKILL.md. Modules (src/core-skills/, src/bmm-skills/) are just groupings of skill directories. The installer copies these into a project and generates config; at runtime the model reads a SKILL.md, shells out to small Python resolvers to merge configuration, and for complex skills loads numbered step files one at a time. There is no workflow.yaml anywhere in the tree (confirmed: find . -name workflow.yaml returns nothing); the old workflow-engine schema was replaced by the [workflow] table in customize.toml plus a step-file architecture.

SKILL.md anatomy

The frontmatter is the discovery gate

Every SKILL.md opens with YAML frontmatter carrying exactly name and description. The installer's parseSkillMd (tools/installer/core/manifest-generator.js) requires both to be non-empty and enforces a hard rule: the frontmatter name must equal the directory basename, or the skill is rejected (SKILL.md name "..." does not match directory name "..." — skipping). The description is where trigger phrases live, e.g. bmad-dev-story's description embeds Use when the user says "dev this story [story file]". That is how a host matches your natural language to a skill.

The path-variable vocabulary

A near-identical ## Conventions block appears across skills and defines the placeholder namespace. From bmad-dev-story/SKILL.md, verbatim:

- Bare paths (e.g. `steps/step-01-init.md`) resolve from the skill root.
- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
- `{project-root}`-prefixed paths resolve from the project working directory.
- `{skill-name}` resolves to the skill directory's basename.

Workflow skills add {workflow.<name>} (a field from customize.toml's [workflow] table) and {doc_workspace} (the bound run folder). Config-sourced variables ({user_name}, {communication_language}, {document_output_language}, {planning_artifacts}, {implementation_artifacts}, {project_name}, {user_skill_level}, {output_folder}, {date}) are filled in the "Load config" activation step. Two placeholder syntaxes coexist: single-curly {workflow.x}, resolved at runtime by the model or inlined by a renderer, and double-curly {{.var}}, used only in quick-dev's pre-rendered step files (below), baked at compile time.

The activation ladder

The ## On Activation sequence is where a skill boots. The canonical ladder (from bmad-agent-dev/SKILL.md):

1. Resolve the customization block by running a script: python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent (workflows use --key workflow). Every skill ships a verbatim fallback: if the script fails, read the three TOML layers yourself in base → team → user order and apply the same merge rules.
2. Execute prepend steps (activation_steps_prepend).
3. Adopt the persona (agents) and load persistent facts (entries prefixed file: load the referenced file's contents; all others are literal facts).
4. Load config from {project-root}/_bmad/bmm/config.yaml and resolve the config variables.
5. Greet the user by name, in their language (agents lead with the persona's icon).
6. Execute append steps (activation_steps_append).
7. A closing invariant repeated in every skill: "Do not begin the main workflow until all activation steps have been completed."

Agents add step 8, render the menu ({agent.menu} as a numbered Code / Description / Action table) and dispatch on a number, a menu code, or a fuzzy match. bmad-prd adds a Forwarded activation clause: if a caller (a shim, or Mary's menu) supplied a stated intent and pre-resolved fields, honor them verbatim and skip its own inference. That clause is the receiving half of the v6-shims (below).

What a skill directory contains

The contract is SKILL.md (required) plus customize.toml (the customization surface) plus any of steps/, templates/, assets/, references/, checklist.md, scripts/, render.py. Three real shapes:

• bmad-prd/ inlines its logic in SKILL.md and carries assets/ (templates, checklist, HTML report template) and references/. No steps/.
• bmad-create-epics-and-stories/ is step-sharded: steps/step-01-... through step-04-... plus a template.
• bmad-dev-story/ embeds its whole procedure as an inline XML <workflow> in SKILL.md and carries only a checklist.md.

Just-in-time step loading

The clearest statement is bmad-create-epics-and-stories/SKILL.md's ## WORKFLOW ARCHITECTURE block, verbatim:

- Micro-file Design: Each step is a self-contained instruction file
- Just-In-Time Loading: Only 1 current step file will be loaded ... never load
  future step files until told to do so
- Sequential Enforcement: ... no skipping or optimization allowed
...
- NEVER load multiple step files simultaneously
- ALWAYS read entire step file before execution
- NEVER create mental todo lists from future steps

The mechanism: SKILL.md hands off to ./steps/step-01-...; the instruction to load the next step is embedded at the bottom of each step file, behind a menu gate ("ONLY WHEN C is selected and all requirements are saved ... will you then read fully and follow ./step-02-..."). State is tracked in the output document's frontmatter, not the step files (SAVE STATE: Update stepsCompleted in frontmatter before loading next step). This is virtual memory for an agent: keep the active working set to one step, persist completed work to disk, load the next dependency only when control reaches it.

bmad-dev-story is the other flavor: instead of separate files, its whole procedure is an inline XML <workflow> with <step n="1..10">, <check if=...>, <action>, <goto step=...>, <ask>, <output>, and <critical> tags. It is just-in-time in the sense of <goto> control flow (step 8 loops back with <goto step="5">), not file loading.

The resolver scripts

Three stdlib-only Python scripts under src/scripts/ do the deterministic work the model should never do by hand. resolve_customization.py and resolve_config.py need Python 3.11+ (tomllib); memlog.py targets 3.8+.

resolve_customization.py: the three-layer merge

It merges a skill's customization from three layers, lowest to highest:

{skill-root}/customize.toml                       skill defaults   (lowest)
{project-root}/_bmad/custom/{name}.toml            team, committed
{project-root}/_bmad/custom/{name}.user.toml       personal, gitignored (highest)

The merge is structural, by value shape (no field-name special-casing):

• both dicts → deep-merge (recurse);
• both lists → _merge_arrays: if every item is a dict with a code (or every item has an id), merge by that key (matching key replaces in place, new keys append); otherwise plain append;
• otherwise → the override wins (scalars replace).

The load-bearing invariant, from the docstring: "No removal mechanism, overrides cannot delete base items. To suppress a default, fork the skill or override the item by code with a no-op." This is why every customize.toml says "DO NOT EDIT" and why overrides append rather than replace wholesale. Project-root discovery walks up until it finds a directory containing _bmad or .git, explicitly to avoid a stray _bmad/ in an ancestor of the cwd.

resolve_config.py: the four-layer central config

Same merge code, four layers (highest last):

{project-root}/_bmad/config.toml              installer team   (base, required)
{project-root}/_bmad/config.user.toml         installer user
{project-root}/_bmad/custom/config.toml       human team, committed
{project-root}/_bmad/custom/config.user.toml  human user, gitignored (highest)

This reads [core], [modules.<code>], and [agents.<code>] tables. It is the resolver the party-mode and forge scripts call with --key agents to get the installed roster.

memlog.py: append-only run memory

The ledger behind .memlog.md (see the memory page), with three invariants stated in its docstring: append-only ("There is no edit or delete subcommand by design; history is never rewritten"), write-only/blind (every command is atomic and echoes state as one JSON line, so the caller never re-reads mid-session), and no lifecycle status (completion is a logged event, never mutated frontmatter). Writes are atomic (temp file, flush, os.fsync, os.replace). Subcommands: init (errors if the file exists, --field KEY=VALUE seeds frontmatter), append (--text required, optional --type and --by, collapsed to one line), set (replace one frontmatter field). Skills invoke it as uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <...> --text "...".

Two runner conventions coexist in the source: newer skills (bmad-prd, bmad-party-mode) call uv run ...; others (bmad-dev-story, bmad-dev-auto, epics) call python3 .... Both scripts document uv as the standardization target with python3 as the transitional fallback.

module.yaml and central config

A module declares its config prompts and (for BMM) its agent roster. src/core-skills/module.yaml declares five prompts, each with a prompt, optional scope (user vs team-default), default, and result: user_name, project_name, communication_language, document_output_language, and output_folder (default _bmad-output, with result: "{project-root}/{value}" baking an absolute path). It creates exactly one directory at install (output_folder); everything else is "created lazily by the first skill that writes there." src/bmm-skills/module.yaml adds user_skill_level (beginner/intermediate/expert), planning_artifacts, implementation_artifacts, and project_knowledge (default docs), plus the six-agent roster as essence only (code, name, title, icon, team, description); the full persona lives in each agent's customize.toml, and party-mode / retrospective / help read these descriptors "to route, display, and embody agents."

At install, each prompt's scope routes the answer: scope: user lands in config.user.toml, everything else in config.toml. Core keys are stripped from non-core module buckets (a workflow reads {user_name} from [core] and {implementation_artifacts} from [modules.bmm]).

The installer

Entry point tools/installer/bmad-cli.js (a commander CLI aliased bmad / bmad-method). The pipeline (core/installer.js):

1. Build config, detect any existing install, back up custom/modified files by comparing against _config/files-manifest.csv hashes.
2. Install shared scripts (wipe and re-copy src/scripts/*, excluding tests and caches; seed _bmad/custom/.gitignore with *.user.toml on a fresh install).
3. Install each module's skills; resolve each external module's version/channel (GitHub-API tag fetching lives in modules/channel-resolver.js, which refuses silent major bumps).
4. Generate configs: per-module config.yaml (legacy), then the central config.toml / config.user.toml and manifests, then apply --set overrides.
5. Copy skills into per-IDE directories, then _cleanupSkillDirs removes the skill copies from _bmad/ ("Skills are now in IDE directories, remove redundant copies"). _bmad/ keeps only module-level files, _config/, and scripts/.

Two findings worth internalizing. First, the installer does not generate SKILL.md from templates, the source SKILL.md files are the shipped artifacts, copied verbatim; collectSkills discovers a directory as a skill iff its SKILL.md frontmatter validates and the name matches the directory. Second, files-manifest.csv carries sha256 hashes, which is how a re-install detects files you modified and backs them up before overwriting. This is the mechanism behind the "installer-owned vs yours" rule on the anatomy page.

quick-dev and dev-auto: two flavors of one pipeline

Both run the same spec → implement → review pipeline; quick-dev is interactive (human checkpoints, five step files plus a one-shot branch), dev-auto is one unattended iteration (no human, a HALT-with-status protocol).

quick-dev's render.py is unique. Its SKILL.md is a stub that runs uv run {skill-root}/render.py, a compile-time template renderer. render.py finds the project root, four-layer-merges the central config, resolves the skill's [workflow] block with the same structural merge as the resolver, substitutes {{.var}} (config) and {workflow.<key>} (customization) into every .md except SKILL.md, writes the rendered files to _bmad/render/bmad-quick-dev/, and prints read and follow .../workflow.md. It HALTs before rendering if any referenced {{.var}} is missing ("a corrupted workflow"). Notably, _render_review_layers materializes each [[workflow.review_layers]] table into an invocation block, and a layer with an empty instruction is dropped, which is how an override turns off a default reviewer. dev-auto has no render.py; it must run unattended, so it resolves customization at runtime in its own activation.

The spec's frozen kernel. Both write a spec file whose intent section is human-owned and read-only. The tag differs (dev-auto uses <intent-contract>, quick-dev uses <frozen-after-approval reason="human-owned intent">) but the content is the same three parts: Intent (Problem, Approach), Boundaries (Always / Block-If-or-Ask-First / Never), and an I/O and Edge-Case Matrix. Outside the frozen block: a Code Map, Tasks and Acceptance (Given/When/Then), an append-only Spec Change Log, Design Notes, and Verification. Both target 900 to 1600 tokens ("above 1600 = high risk of context rot"), and every downstream step re-states that the frozen block is read-only.

Status lifecycle. Frontmatter status: draft → ready-for-dev → in-progress → in-review → done (dev-auto adds blocked). Step 1 routes an existing spec by its status. dev-auto's HALT protocol replaces human checkpoints: it writes a terminal status and a blocking condition back to the spec, runs any on_complete, and stops. Blocking conditions are enumerated throughout (unclear intent, intent gap, no subagents, review repair loop exceeded 5 iterations (non-convergence), no epic spec found, ...).

The review loop is the core mechanism. Set in-review, build a diff since the baseline revision (read-only, "do NOT git add"), run the resolved review_layers in parallel, then classify each finding by consequence (discarding the subagent's own severity, since reviewers run under deliberate information asymmetry) and route it into exactly one of five triage categories:

Findings cascade (an intent_gap moots lower findings; a bad_spec moots them because the code will be re-derived), and the loopback counter HALTs after 5 iterations to guarantee convergence. dev-auto also runs a Matrix Test Audit: every I/O-matrix row must have a covering test that actually ran and passed ("a covering test that exists but did not run ... counts as missing ... never edit the expectation to match the code").

Subagents. dev-auto: "Using subagents when instructed is mandatory. If you cannot, HALT with status blocked and blocking condition no subagents," and it requires synchronous invocation, no detached/background execution, because "there is no event loop to resume a yielded turn" in an unattended run. quick-dev degrades to inline execution on hosts without subagents, or writes prompt files for the human to run.

v6-shims: how old skill names keep working

src/*/v6-shims/ hold forwarders: skills with no logic that forward to their replacement. bmad-create-prd / bmad-edit-prd / bmad-validate-prd forward to bmad-prd (create/update/validate intents); bmad-market-research / bmad-domain-research / bmad-technical-research forward to bmad-deep-recon; bmad-create-architecture forwards to bmad-architecture. A forwarder resolves its own (legacy) customization, emits a deprecation notice, then "invokes the target with a stated intent and pre-resolved fields, skip[ping] the target's own intent detection." The folder is grouping only, the installer discovers each forwarder under its own name, so nesting does not change any installed path. Their removal "rides the v7 cut, never a 6.x minor."

Two things that will trip an expert

The dual-config transition. There are two live config systems. SKILL.md activation steps say "Load config from _bmad/bmm/config.yaml" (the legacy per-module YAML), but the resolver scripts and render.py read the central config.toml + config.user.toml + custom/config.toml + custom/config.user.toml (the newer four-layer TOML). Both are generated from the same install answers so they agree; the TOML path is the newer, resolver-backed one that agent-roster consumers (party-mode, forge) rely on. When something reads stale config, know which of the two it is looking at.

The party/forge persona resolvers (resolve_party.py, resolve_personas.py) are the pattern to copy if you build your own multi-agent skill: Python does the deterministic roster resolution once (shelling into resolve_config.py --key agents for the installed roster and resolve_customization.py for custom personas, projecting only what a moment needs), and the LLM orchestrator consumes the resolved JSON instead of re-deriving the roster every session.

The design invariants worth stealing

Reading the source, the same handful of moves recur, and they are the real lessons for anyone building agent tooling:

• customize.toml is machine-owned; overrides are sparse and append-only. There is no delete operator, on purpose.
• Append-only artifacts everywhere. The memlog, the Spec Change Log, the Review Triage Log, and deferred-work.md are all append-only; resume state is learned by reading the tail, never by mutating history.
• Extract, don't ingest. Source documents go to subagents; the parent context assembles from digests. The 900-to-1600-token spec ceiling and quick-dev's cached epic context are the same context-budget discipline.
• Deterministic work goes to Python; judgment stays in the model. The resolvers, memlog.py, render.py, and recon_kit.py are all exact, repeatable jobs pulled out of the LLM's hands.

Hands-on: run the resolver and the memlog yourself

The two Python scripts this page describes are stdlib-only, so you can run them against a real BMAD checkout and watch the deterministic layer work. Everything below was run against the v6.10.0 tree from the repo root; the output is real, not illustrative.

The three-layer merge. Point resolve_customization.py at any skill directory and it prints the merged customization as JSON. Against bmad-forge-idea with no project overrides, you get the skill's own defaults:

python3 src/scripts/resolve_customization.py --skill src/core-skills/bmad-forge-idea

{
  "workflow": {
    "activation_steps_prepend": [],
    "activation_steps_append": [],
    "persistent_facts": [
      "file:{project-root}/**/project-context.md"
    ],
    "on_complete": [],
    "forge_output_path": "{output_folder}/forge",
    "run_folder_pattern": "{slug}"
  }
}

Now add the two override layers an installed project would have, a committed team file and a gitignored personal file, both under the project's _bmad/custom/:

# _bmad/custom/bmad-forge-idea.toml        (team, committed)
[workflow]
forge_output_path = "{output_folder}/team-forge"
persistent_facts = ["Our kill-criteria template lives at docs/kill-criteria.md"]

# _bmad/custom/bmad-forge-idea.user.toml   (personal, gitignored)
[workflow]
forge_output_path = "{output_folder}/my-forge"

The resolver walks up from the skill directory to find the project root (the nearest ancestor with a _bmad/ or .git/), so with those two files in place the same command returns the merged result, and the merge rules from earlier fire: the persistent_facts array is unioned (base glob plus the team fact), and the scalar forge_output_path takes the highest layer present (yours):

{
  "workflow": {
    "activation_steps_prepend": [],
    "activation_steps_append": [],
    "persistent_facts": [
      "file:{project-root}/**/project-context.md",
      "Our kill-criteria template lives at docs/kill-criteria.md"
    ],
    "on_complete": [],
    "forge_output_path": "{output_folder}/my-forge",
    "run_folder_pattern": "{slug}"
  }
}

That is the whole override system in one command: arrays merge, scalars take the top layer, nothing is deleted. Ask for a single field with --key:

python3 src/scripts/resolve_customization.py \
  -s src/core-skills/bmad-forge-idea -k workflow.forge_output_path

{
  "workflow.forge_output_path": "{output_folder}/my-forge"
}

The append-only memlog. The other script is the working memory a skill keeps during a run. Initialize a run folder, append entries the way a skill would, and read the ledger:

python3 src/scripts/memlog.py init --workspace run/ --field title="Forge: transcribe-on-ingest"
python3 src/scripts/memlog.py append --workspace run/ --type idea --by user \
  --text "Transcribe every saved episode on ingest"
python3 src/scripts/memlog.py append --workspace run/ --type decision --by coach \
  --text "Too costly on a solo budget; transcribe on first open instead"
python3 src/scripts/memlog.py append --workspace run/ --type event --text "session complete"

Each command echoes the new state as one line of JSON ({"ok": true, ..., "entries": N}) so the caller never re-reads the file mid-run. The result, run/.memlog.md:

---
title: Forge: transcribe-on-ingest
updated: 2026-07-26T16:55
---

- (idea by user) Transcribe every saved episode on ingest
- (decision by coach) Too costly on a solo budget; transcribe on first open instead
- (event) session complete

There is no edit or delete subcommand by design: history is appended, never rewritten, which is what lets a resume trust it. Run these two scripts once and the rest of this page stops being abstract: at runtime the model is just calling them and consuming the JSON they print.

Under Claude Code: two just-in-time systems, stacked

Read this page's mechanics against the harness and a pattern falls out: BMAD's design mirrors the host it runs on, so two just-in-time layers stack. Claude Code loads a SKILL.md the same way BMAD loads a step. At session start only the frontmatter name and description sit in context (progressive disclosure, about 50 tokens each); the body loads the moment the skill is invoked, then persists for the rest of the session. Under later auto-compaction it keeps roughly the first 5k tokens per skill against a shared 25k budget. So BMAD's one-step-at-a-time step loading runs inside Claude Code's one-skill-at-a-time skill loading: JIT nested in JIT.

The rest lines up nearly one to one:

The agent loop is what walks BMAD's markdown procedure step by step: the "load the next step file only when control reaches it" rule holds because each turn is a real read, decide, act cycle, not a plan built up front. When a step says run resolve_customization.py, that is a literal Bash invocation; the three-layer TOML merge happens in Python on disk and the model consumes the JSON it prints. When dev-auto demands a synchronous subagent, the host's Agent tool supplies the isolated window and the results-only return that the "extract, don't ingest" discipline (above) assumes.

Net: BMAD is a markdown-and-Python method that borrows its loading, execution, and isolation from whatever host runs it. On Claude Code those primitives happen to line up almost exactly, which is why the source reads like a description of the harness underneath it.

That is BMAD with the lid off: a set of markdown procedures over a thin deterministic Python spine, resolved through layered TOML, loaded just in time, and persisted to append-only files. The next page turns to how you spend model capability and tokens across all of this: which model per phase, and at what thinking level. 👉

Models, tokens, and thinking levels

BMAD does not pick a model. Your host does: Claude Code, Cursor, Codex, or whatever agent you installed it into runs the model, and BMAD rides on top as a procedure. So "use the best model at the best thinking level" is not a BMAD setting you flip; it is a set of decisions you make at the host, plus the few places BMAD does expose model and effort control. This page is how to spend model capability and tokens well across a BMAD project: which model per phase, what thinking effort, and how to move expensive work to where it is cheap.

Model facts here are current as of this writing (Claude family); the strategy is durable even as the specific IDs and prices move, so treat the numbers as dated and the shape as the point.

On this page

• The model tiers
• Thinking and effort
• Choosing the model per phase and role
• Shifting tokens to where they are cheap
• A worked cost picture
• Pitfalls
• Hands-on: measure a real run’s cost and cache
• Under Claude Code: /model, effort, and automatic caching internals

The model tiers

The Claude family spans roughly three tiers by capability and price. Pick per job, not per project.

The rule of thumb: judgment work on the strongest tier, mechanical work on the cheapest. A PRD or an architecture decision is judgment; extracting claims from a report or renaming symbols across a story is mechanical. Running everything on the biggest model is the most common way to overspend; running everything on the cheapest is the most common way to ship a wrong schema.

Thinking and effort

Current Claude models use adaptive thinking (thinking: {type: "adaptive"}): the model decides when and how much to think, and you tune the depth with an effort knob rather than a fixed token budget. Effort has five levels:

Two facts shape how this maps onto BMAD. First, effort matters more on the current models than it used to, so it is worth setting per phase rather than leaving at the default. Second, BMAD's phases sort cleanly by how much thinking they deserve:

In Claude Code you set the model with /model and effort via its settings (it defaults to xhigh); fast mode (/fast, Opus 4.8) trades premium price for ~2.5x output speed on the same model when latency matters in an interactive loop. Other hosts expose their own controls; the mapping above is what to aim for whatever the knob is called.

Choosing the model per phase and role

BMAD's four phases have different work profiles, so the ideal model shifts across a project. A sensible default portfolio:

• Analysis and Planning (Mary, John). Research framing, briefs, PRDs, and architecture are judgment calls where a wrong turn is expensive downstream. Run the planning personas on the strongest tier (Opus 4.8, or Fable 5 for the genuinely hardest problems). These are also the phases you can run as web bundles on a flat-rate subscription.
• Solutioning (Winston). Architecture is judgment; keep it on Opus. Cutting epics and stories is more mechanical and can drop a tier.
• Implementation (Amelia). Dev stories are coding-and-agentic work: Opus 4.8 or Sonnet 5 at xhigh. High-volume, well-specified stories are exactly where Sonnet 5 earns its lower price. QA generation and mechanical fixes can drop to a cheaper tier.

BMAD exposes model choice directly in two places:

Deep Recon's subagent_models. The research skill lets you set an ordered model preference for its spawned research assistants (see the recon how-to). The shipped guidance is exactly the judgment-vs-mechanical split: keep the lead on the strongest model, run researchers at most one tier down, never drop judgment work to the smallest tier, and let mechanical extraction use a fast tier. That single override turns a deep research run from "everything on Opus" into a right-sized fleet.

The BMad Loop's per-stage mux. The autonomous loop drives fresh coding-agent sessions through a terminal multiplexer and can point different stages at different agents (claude, codex, gemini, copilot, antigravity, opencode), mixing per stage. That means you can run implementation on your strongest coding model and the adversarial review on a different one for independent perspective, deterministically, without a human in the loop.

Everywhere else, the model is whatever your host is set to, so the lever is the host's model selector plus a fresh chat per workflow (which lets you switch model between phases without dragging one model's context into the next).

Shifting tokens to where they are cheap

Token spend in a BMAD project concentrates in a few places, and each has a lever:

Research fan-out is the biggest single cost. Parallel research burns roughly an order of magnitude more tokens than a single-agent chat (the multi-agent research design that beats a single agent does so at ~15x tokens). Deep Recon's effort knobs are the dial: the quick/standard/deep presets set subagents (2/3/6), sources per round (5/8/12), and rounds (1/2/3). Run quick for a question you half-know and deep only when the decision genuinely warrants it. Depth and sources are caps, not quotas, so a dimension stops early on coverage.

Rent someone else's crawler. Deep Recon's Draft mode and BMAD's web bundles move the expensive part of research (long agentic browsing) onto a flat-rate chat subscription instead of metered IDE tokens, then Process the report back. For a team, a PRFAQ pass and three rounds of research in a Gem cost zero marginal dollars; the same work in the IDE is real spend. This is the highest-leverage token shift BMAD offers.

Prompt caching pays for the file-first design. BMAD re-reads its state from disk on every workflow, and a stable prefix (a frozen system prompt, a fixed tool list, a large project-context.md) caches: reads cost about a tenth of the base input price, writes a small premium. The discipline that makes caching work is the same discipline BMAD already enforces: keep the stable stuff first and the volatile stuff (the current question) last. A fresh chat per workflow does not throw caching away, because the cache is keyed on the reused prefix, not the conversation.

Batch the mechanical. Bulk, non-interactive work (classify a backlog, extract from many documents) runs at half price through the Batch API. If a BMAD step fans out over many independent items and does not need to be interactive, that is a batch job.

Cap the agentic loops. For autonomous work, a task budget gives the model a token ceiling for a whole loop so it paces itself and finishes gracefully instead of being cut off, distinct from the hard per-response max_tokens limit. The BMad Loop and dev-auto are where this matters; the efficiency page returns to it.

A worked cost picture

For a greenfield project, the token budget is dominated by two phases: research (if the decision is uncertain) and implementation (always). A cost-aware run:

1. Frame cheaply. Brainstorm and forge on your default model; they are short.
2. Research at the right depth. standard preset by default; quick if you half-know the answer; Draft-to-a-web-bundle for broad public sweeps. Set subagent_models so researchers run a tier below the lead.
3. Plan on the strong tier. PRD, UX, and architecture are judgment; Opus/Fable at high. Consider running these as web bundles on a flat rate.
4. Implement on the value tier. Sonnet 5 at xhigh for the bulk of dev stories; escalate a genuinely hard story to Opus. QA and mechanical fixes on a cheaper tier or in batch.
5. Automate with a budget. If you run the loop unattended, set a task budget and a gates.mode you trust, and let the mux put review on a second model.

The through-line: match the model and the effort to the stakes of the step, and move browsing and bulk off the metered path. Most overspend is one of three mistakes: max effort everywhere, the biggest model for mechanical work, or a deep research run for a question a quick run would have answered.

Pitfalls

• Effort maxed everywhere. max on routine work burns tokens for no gain and can cause overthinking. Default to high, xhigh for coding, max only when correctness dominates cost.
• One model for everything. The biggest model for mechanical extraction is waste; the cheapest for architecture is risk. Use subagent_models and the loop mux to split the work.
• deep research by reflex. The preset is a token multiplier; reach for it only when the decision warrants six assistants and three rounds.
• Ignoring the flat-rate path. Running long research browsing on metered IDE tokens when a web bundle would do it for a flat fee is the most common avoidable cost.
• Cache-blind prompts. Interpolating a timestamp or a per-run ID into the front of a workflow's context silently defeats caching. Keep the stable prefix stable.

Hands-on: measure a real run's cost and cache

Read your own numbers before you theorize about them. This is a five-minute session you can replay in any BMAD repo.

Set the model and effort for the session, then run one dev story:

/model claude-opus-4-8
/effort xhigh
# ... run a dev-story workflow to completion ...
/usage

/usage reports cost and two durations, wall-clock and API time, plus a per-model breakdown of input, output, cache-read, and cache-write tokens. The number to watch is the cache-read share. On the first workflow the stable prefix (system prompt, tool list, project-context.md) is written, so cache-write is high. On the second workflow in the same session that same prefix is a read, so cache-read dominates:

Illustrative (run it in your own repo; not machine-verified here).

/usage
  Session cost:      $1.84
  Duration (wall):   22m 41s
  Duration (API):    6m 12s
  claude-opus-4-8
    input           18,204
    output          31,077
    cache read     412,900   (89%)
    cache write     41,880

Wall-clock far above API time is you reading and typing while the model sits idle. The 89% cache-read share is the file-first design paying off: re-reading state each workflow bills at about a tenth of input, not a full re-read.

To log the same numbers for a harness, run headless and pull them with jq. --output-format json returns total_cost_usd and usage_by_model:

claude -p "implement story 2.3 per the acceptance criteria" \
  --model claude-sonnet-5 --output-format json \
  | jq '{cost: .total_cost_usd, usage: .usage_by_model}'

Illustrative (run it in your own repo; not machine-verified here).

{
  "cost": 0.4123,
  "usage": {
    "claude-sonnet-5": {
      "input": 9102,
      "output": 15330,
      "cache_read": 388120,
      "cache_write": 40210
    }
  }
}

Append that object per story and you have the raw feed for the benchmark harness on page 17: cost per story, cache-hit rate, and output tokens, all comparable across model and effort settings.

The payoff is one substitution you can now see instead of guess. Switch the bulk dev stories from claude-opus-4-8 to claude-sonnet-5 and watch cost per story fall in /usage while the cache-read share holds steady.

Under Claude Code: /model, effort, and automatic caching internals

BMAD names the strategy; the host holds the knobs and decides what persists. In Claude Code the scoping is precise.

Aliases opus, sonnet, haiku, fable resolve to full IDs (opus to claude-opus-4-8). So a fresh chat per BMAD workflow keeps your /model choice but drops a one-off /effort high; put effort in the settings effort key if you want it to stick per phase. A dev-story subagent or the deep-recon skill can carry its own model:/effort: frontmatter, which is how BMAD's per-role split lands without touching the session default.

Prompt caching is automatic, with breakpoints at four boundaries: the system prompt, the tools-and-skill-descriptions block, the CLAUDE.md-and-loaded-files block, and the conversation prefix. Cache reads bill at about a tenth of input (the write is a small premium). TTL is 1 hour on a subscription, 5 minutes on an API key or cloud provider, so idle time between BMAD phases costs more on metered access. /usage breaks out cache read and cache write so you can watch the ratio. --exclude-dynamic-system-prompt-sections moves per-machine content (environment info, MCP tool names) out of the system prompt so the cache reuses across machines on the same repo.

BMAD's file-first design is what keeps these breakpoints warm: a fixed system prompt, a large but unchanging project-context.md, a tool list stated once. Re-reading state each workflow is then a cache read, not a re-bill. Interpolate a timestamp or per-run id into that prefix and every breakpoint downstream goes cold.

With models and tokens handled, the next page makes efficiency systematic: the levers that cut cost, context bloat, and rework across a whole BMAD project. 👉

Efficiency and optimization

BMAD's speed, cost, and quality all trace to one thing: how well you manage the model's attention and your own. Waste shows up as context bloat, redundant work, ceremony the task did not justify, the wrong model at the wrong effort, and rework from mistakes caught late. This page is the systematic way to find and remove each, building on the model and token strategy from page 12 and the memory and measurement model from page 7.

On this page

• The one idea
• Lever 1: context discipline
• Lever 2: caching
• Lever 3: parallelism, where it helps
• Lever 4: right-size the ceremony
• Lever 5: model tiering
• Lever 6: reduce rework (the compounding one)
• Lever 7: move work off the metered path
• Lever 8: extend precisely
• Lever 9: measure, then tune
• The inefficiency anti-patterns
• Hands-on: cut a workflow’s context and measure it
• Under Claude Code: context-management internals

The one idea

Everything below is a special case of: keep the working set small, do each unit of work once, and spend capability in proportion to stakes. BMAD is already built around this (just-in-time step loading, externalized state, a fresh chat per workflow, scale-adaptive tracks); optimization is mostly using those on purpose rather than fighting them.

Lever 1: context discipline

The cheapest tokens are the ones you never load. BMAD's internals (page 11) already do most of this; your job is not to undo it.

• Let just-in-time loading work. Complex workflows load one step file at a time rather than the whole procedure up front. Do not paste an entire epic into one chat "so the agent has context"; give it the story, and let it read what it needs.
• A fresh chat per workflow is an optimization, not a chore. It keeps stale reasoning out of the window, and because state is on disk, nothing is lost. Mixing three workflows in one chat both bloats context and risks contradictory documents.
• Keep project-context.md lean and unobvious. It loads on every implementation workflow, so every line is a recurring tax. Record the patterns an agent would miss, not standard practice it already knows.

Lever 2: caching

BMAD re-reads its state from files each workflow, and a stable prefix (frozen system prompt, fixed tool list, a large but unchanging project-context.md) caches: reads cost about a tenth of base input price. The discipline that makes it work is the same the method already teaches, keep the stable content first and the volatile content (today's question) last. The way to lose it is to interpolate a timestamp, a per-run id, or a per-user string into the front of a workflow's context. A fresh chat does not throw the cache away, because the cache is keyed on the reused prefix, not the conversation. (See page 12 for the economics.)

Lever 3: parallelism, where it helps

Parallel agents buy wall-clock and independent perspectives, at a large token premium (research fan-out runs roughly an order of magnitude more tokens than a single-agent chat). Use it where work genuinely decomposes and skip it where it does not:

• Deep Recon's fan-out parallelizes a research sweep across independent sub-questions; the effort preset is the dial (2 / 3 / 6 assistants).
• The BMad Loop and dev-auto dispatch independent stories to concurrent fresh-context sessions.
• Party mode is not parallelism for throughput in its default (session) mode; it is one context voicing several personas. Use subagent mode when you need genuinely independent opinions, and accept the token cost.

The rule: parallelize sweeps and independent items; serialize judgment. Six assistants on a question one focused assistant could answer is pure waste.

Lever 4: right-size the ceremony

The single biggest efficiency lever is running only the phases the work justifies.

• Pick the track by stakes. Quick Flow for a bugfix; the full method for a multi-epic feature; enterprise gates only for regulated or high-blast-radius work. Running the enterprise track on a one-file change is the most common over-spend of human time.
• Set effort per phase, not globally. xhigh for coding and agentic work, high for most judgment, medium/low for mechanical or scoped work, max only when correctness dominates cost. Effort maxed everywhere burns tokens and can cause overthinking (see page 12).
• Loosen gates.mode as trust grows. Start at per-story approval; move toward per-epic or unattended as your measured defect rate earns it. Every gate is human latency; keep the ones that catch real mistakes and drop the ones that only rubber-stamp.

Lever 5: model tiering

Judgment on the strong tier, mechanical work on the cheap tier. The two BMAD surfaces that expose this are Deep Recon's subagent_models (lead strong, researchers a tier down, mechanical extraction on a fast tier) and the BMad Loop's per-stage mux (implementation on your best coding model, review on another). Everywhere else it is the host's model selector plus a fresh chat between phases so you can switch model without dragging context. Full guidance on page 12.

Lever 6: reduce rework (the compounding one)

Every mistake caught late is paid twice: once to make it, once to unwind it. The method's cheap checkpoints exist to move that catch earlier.

• Frame before you build. A forge-idea kill criterion kills a bad idea in one exchange instead of a shipped quarter. This is the highest-return minute in the whole process.
• Run the readiness gate. A CONCERNS caught as a paragraph is free; the same defect caught in code review costs a dev-story round trip.
• Reconcile upstream, not downstream. When documents disagree, fix the owning document (bmad-prd Update, bmad-correct-course) and let it propagate; do not hand-patch every downstream file.
• project-context.md is the compounding asset. Every mistake you turn into a line here is a mistake no future story repeats. A team that feeds retrospective and correct-course lessons back into it gets monotonically more efficient; one that does not repeats the same corrections forever.

Lever 7: move work off the metered path

• Draft mode and web bundles run the expensive part of research (long agentic browsing) on a flat-rate chat subscription, then Process the report back into the repo. For a team this is often the largest single cost saving.
• Batch the mechanical. Bulk, non-interactive work runs at half price through the Batch API.
• Deterministic work belongs in code, not prose. Deep Recon hands its counting to recon_kit.py and the BMad Loop is plain Python for exactly this reason: never pay model tokens to imitate something a script does exactly and free (page 11).

Lever 8: extend precisely

The right external tool removes tokens rather than adding them. A symbol-level code tool like Serena lets a dev-story edit by symbol instead of reading whole files into context; an up-to-date-docs tool like Context7 stops the model guessing (and re-generating) an API; a deterministic AST tool applies a change across a codebase without a per-file round trip. Wire these in over MCP where they pay for themselves, and skip the ones that just add another chatty surface. The tool ecosystem page is the catalog and the when-to-add decision matrix.

Lever 9: measure, then tune

Optimization without measurement is superstition. Track the scorecard from page 7 (time to first falsifiable experiment, readiness defects caught early, story rework rate, token cost per workflow, stale claims refreshed), then run a tight loop:

1. Measure where time and tokens actually go across a real cycle.
2. Find the single biggest waste (usually one of: over-effort, a deep research run that should have been quick, ceremony on a small change, or rework from a skipped gate).
3. Apply the matching lever above.
4. Re-measure. Keep the change if the number moved; revert it if it did not.

Two facts make this measurable rather than vibes: Deep Recon's recon_kit.py tally counts claims by status straight from the ledger, and dev-auto's baseline_revision..final_revision brackets exactly what a run produced, so "how much did we redo?" is a git log, not a guess.

The inefficiency anti-patterns

Hands-on: cut a workflow's context and measure it

Lever 1 is only real once you can see the tax. This is a five-minute session that measures your window, removes the biggest recurring line, and confirms the drop.

1. Measure. In a repo, before starting a bmad-dev-story workflow, run /context. It prints the live window by category.

Illustrative (run it in your own repo; not machine-verified here).

Context usage: 48.2k / 200k tokens (24%)

  System prompt        3.1k
  System tools        12.4k
  CLAUDE.md            2.1k
  Skills               1.9k
  MCP tools            4.6k
  project-context.md   6.8k
  Messages            17.3k
  Free space         151.8k

Two lines are yours to move. project-context.md (6.8k) reloads on every implementation workflow, so it is a recurring cost, not a one-off. Skills (1.9k) is capped near 1% of the window; leave it.

2. Trim the recurring line. Open project-context.md and keep only what the model would miss. Before:

## Coding standards
Write clear names, keep functions small, add a test for new
behavior, handle errors explicitly, and log at the boundaries.

## Queues
Every job goes through `enqueue()`; never call `worker.run()`
directly. The retry and backoff wrapper lives in `enqueue`.

After:

## Queues
Every job goes through `enqueue()`; never call `worker.run()`
directly. The retry and backoff wrapper lives in `enqueue`.

The coding-standards paragraph is standard practice the model already applies; the queue rule is the non-obvious one it would miss. Dropping the paragraph subtracts those tokens from every future implementation workflow, not just this one.

3. Drop stale conversation. Before the next workflow, /clear. It resets the window, and because BMAD state is on disk (page 7), nothing is lost. This zeroes the Messages line.

4. Shrink the scripted baseline. For a non-interactive batch, --bare strips hooks, skills, MCP, and CLAUDE.md:

claude -p "run bmad-dev-story for STORY-142" --bare

Every run in the batch then starts from the smaller baseline.

5. Re-measure. Run /context again after the trim and /clear.

Illustrative (run it in your own repo; not machine-verified here).

Context usage: 26.6k / 200k tokens (13%)

  System prompt        3.1k
  System tools        12.4k
  CLAUDE.md            2.1k
  Skills               1.9k
  MCP tools            4.6k
  project-context.md   2.5k
  Messages             0.0k
  Free space         173.4k

project-context.md fell 6.8k to 2.5k and Messages went to zero: about 22k of window handed back, repeated on every workflow. That is the loop in Lever 9, made concrete on one knob.

Under Claude Code: context-management internals

BMAD is host-agnostic, but each lever above lands on a concrete Claude Code knob. Start by seeing the live budget: /context prints a per-category breakdown (system prompt, CLAUDE.md, skills, loaded files, conversation, MCP tools), so "context discipline" (Lever 1) stops being a guess.

When the window nears ~95%, Claude Code auto-compacts: it clears older tool outputs first, then summarizes earlier conversation. /compact [focus] triggers that manually with a focus string, and a PreCompact hook can fire before it. /clear is the chapter's "fresh chat per workflow" made literal, and it is safe for exactly the chapter's reason: BMAD state lives in files, so nothing is lost when the window resets.

Subagents launched through the Agent tool run in their own windows and return only a final result, so their intermediate context never counts against the parent. That is Lever 3's parallelism with a real cost boundary. --bare strips hooks, skills, MCP, and CLAUDE.md to cut baseline tokens for a scripted, non-interactive run.

Two budgets shape what to keep. The skills listing is capped at roughly 1% of the window, and compaction preserves a bounded per-skill budget, so a lean, unobvious project context (only what the model would miss, per Lever 1) is the highest-value line to hold. And Lever 2 is literal here: a stable prefix keeps the cache warm; a volatile one (a timestamp, a per-run id) throws it away.

Efficiency, in the end, is the same discipline as quality: spend attention where it has the most leverage and nowhere else. The next page is the toolbox that several of these levers reach for, the open-source memory and code tools that extend a BMAD agent, and exactly when each one earns its place. 👉

Extending BMAD: the open-source tool ecosystem

BMAD supplies a method and its own memory (the memlog, project-context.md, and the artifact chain from page 7). It does not supply precise code navigation, cross-session agent memory, up-to-date library knowledge, context compression, or corpus-scale research. Those come from a thriving open-source ecosystem, most of it exposed over MCP, that you wire into a BMAD agent using the mechanisms from the extending page.

This page is the catalog and the decision matrix: what each tool is, how it pairs with BMAD, and where it overlaps (or conflicts with) BMAD's own memory. Facts below (stars, versions, licenses) are dated to mid-2026; treat them as a snapshot. Vendor benchmark claims are flagged as such.

On this page

• Code and context tools
• Memory tools
• The overlap question: what to add vs what BMAD already has
• Wiring and pitfalls
• Hands-on: wire Serena and do a symbol-level rename
• Under Claude Code: how these tools attach and route

Code and context tools

Serena, symbol-level code tools (the one to reach for first)

Serena (oraios/serena, MIT, ~27k stars, v1.6.x) is an MCP server that gives a coding agent IDE-grade semantic tools backed by the Language Server Protocol, so it edits code by symbol instead of by reading and patching whole files. Its own tagline is "the IDE for your agent." This is the single highest-value tool to pair with BMAD's implementation phase, because dev-story's cost and error rate both come largely from shoveling whole files through the context window.

What it exposes (several dozen tools across categories):

• Symbol tools (the point): find_symbol, find_referencing_symbols, find_declaration, find_implementations, get_symbols_overview, replace_symbol_body, insert_after_symbol, insert_before_symbol, rename_symbol, safe_delete_symbol, plus get_diagnostics_for_file / _for_symbol. An agent can rename a symbol across a codebase, or replace one function body, as a single atomic call rather than a read-edit-write cycle per file.
• File utilities: search_for_pattern, replace_content (regex/literal), list_dir, find_file, read_file, create_text_file, and friends. Inside Claude Code or Codex these are "typically disabled by default, since the surrounding harness already provides overlapping file, search, and shell capabilities," so you keep the symbol tools and let the host own plain file ops.
• Memory: write_memory, read_memory, list_memories, delete_memory, edit_memory, rename_memory, backed by markdown files in .serena/memories/. An onboarding flow runs on first use of a project and seeds memories describing the project's conventions.
• Meta/config: onboarding, activate_project, get_current_config, open_dashboard, and so on.

Under the hood the LSP layer is solidlsp, a synchronous client library derived from Microsoft's multilspy, giving direct support for 40+ (docs say 60+) languages via their real language servers (Pyright, typescript-language-server, Eclipse JDT, rust-analyzer, gopls, clangd, and so on). Configuration is a per-project .serena/project.yml (which languages, which modes, which tools to disable) and a global ~/.serena/serena_config.yml; behavior is shaped by an immutable context (claude-code, codex, ide, ...) and composable modes (planning, editing, no-onboarding, no-memories, ...).

Run it (current canonical commands; ignore older marketplace snippets):

uv tool install -p 3.13 serena-agent
# register it with Claude Code (verified command):
claude mcp add --scope user serena -- \
  serena start-mcp-server --context claude-code --project-from-cwd
# or run the MCP server yourself and point any MCP client at it:
serena start-mcp-server --context claude-code --project-from-cwd

One caveat matters specifically for a Claude-based BMAD stack: Serena's own docs warn that recent Claude Code and Opus-line updates cut the model's adherence to its tool instructions, and recommend launching with a system-prompt override (claude --system-prompt="$(serena prompts print-cc-system-prompt-override)") plus hooks to keep the agent reaching for the symbol tools. Serena's own token claim (that a cross-file rename which would otherwise cost many careful steps collapses into one atomic call) is a vendor quote, not a measured percentage; the direction is real (symbol edits are far leaner than whole-file rewrites) and the number is marketing.

How it pairs with BMAD. Add Serena over MCP and reference its symbol tools from Amelia's bmad-agent-dev.toml persistent_facts ("For code navigation and edits, prefer Serena's find_symbol / replace_symbol_body over reading whole files"). dev-story then edits precisely and cheaply. One overlap to manage deliberately: Serena's .serena/memories/ and BMAD's project-context.md both store durable project knowledge. Pick one as the source of truth (BMAD's project-context.md is the better choice, since every BMAD workflow already loads it) and let Serena's memories hold LSP-flavored specifics, or disable Serena's memory with its no-memories mode to avoid two drifting copies.

The rest of the code/context toolbox

Headroom, context/token compression

Headroom (headroomlabs-ai/headroom, Apache-2.0, ~62k stars as of mid-2026, v0.32.x) is what "headroom" refers to in this space: a context-optimization layer that compresses what flows into the window (tool outputs, logs, files, RAG chunks, JSON, code) before it reaches the model. It ships three ways, a library, a proxy, and an MCP server (tools headroom_compress, headroom_retrieve, headroom_stats), so you can route Claude Code, Cursor, or any MCP client through it. Its "CCR" mode is reversible: originals are cached locally and the model calls headroom_retrieve to pull full content back on demand, and its "SharedContext" carries compressed context across a multi-agent workflow.

Headroom is also a memory tool, which is why it belongs in this chapter: it keeps categorized memories (preferences, facts, decisions, entities) with embeddings and timestamps in a local project database (.headroom/memory.db: SQLite plus a vector index plus full-text search, no external service), and it can share that memory across agents through the proxy with provenance (which agent and provider wrote each fact), so a Claude session and a Codex session can see each other's memories. Where it fits BMAD: a research or dev run that drags large tool outputs and logs through context is exactly what it targets; route the host through its proxy or point the agent at its MCP. Its headline numbers ("20% fewer tokens for coding agents, 60 to 95% for JSON," equivalent answers on public QA sets) are vendor benchmarks, the README itself hedges output-token savings as hard to guarantee, and the star count climbed unusually fast, so re-verify both before you quote them. Mind the naming trap: the old chopratejas/headroom path redirects to headroomlabs-ai/headroom, and unrelated repos share the name; the LLM-context one is headroomlabs-ai.

Memory tools

BMAD's memory is per-run (memlog) plus per-project (project-context.md) plus per-phase (artifacts). It has no cross-session, cross-tool agent memory ("the model remembers me and my preferences across every session and tool"). That is what this category adds.

A few notes an expert will want:

• mem0's 2026 pivot is real: v3 replaced the older ADD/UPDATE/DELETE/NOOP reconciliation with a single-pass append-only extraction, and moved external graph DBs out of the OSS SDK (built-in entity linking now; graph + time-decay are Platform-only). Every mem0 benchmark number is vendor-authored.
• Letta's sleep-time compute (background agents that consolidate memory while the main agent is idle) and its .af format (serialize a whole stateful agent, secrets nulled, for checkpoint/version-control) are the two ideas worth stealing even if you do not adopt Letta.
• Zep's bi-temporal model (event time vs ingestion time, with automatic fact invalidation on contradiction) is the most sophisticated "facts that change over time" story; its benchmark numbers are self-reported.
• GraphRAG is corpus research, not agent memory. It answers "what are the themes across this whole corpus?" via community summaries, the same shape as Deep Recon's coverage query at corpus scale. Its own README warns indexing is expensive; LazyGraphRAG defers the cost to query time. Use it when the sweep is too big to hold in one run, and contrast it with bmad-deep-recon for external-source, cited research.
• The Cline / Cursor "memory bank" is not a tool at all; it is a pattern, a set of markdown files (projectbrief.md, activeContext.md, progress.md, ...) the agent reads at session start. It is essentially what BMAD already gives you with project-context.md plus the artifact chain, so if you run BMAD you do not also need a memory bank; the concepts are the same.

The overlap question: what to add vs what BMAD already has

The most common mistake is stacking redundant memory layers. Map each need to the right layer before adding anything:

Start here: for almost every BMAD team, the highest-value single addition is Serena (precise, cheap dev edits) plus Context7 (stop the agent guessing APIs). Add a cross-session memory tool (mem0 or Letta) only if you genuinely need the agent to remember a user across projects, which is a different need from remembering a project (that is project-context.md). Add GraphRAG only when a research sweep is too large for a Deep Recon run. Add Headroom when tool-output bloat is a measured cost.

Wiring and pitfalls

Wire any of these over MCP using the mechanics on the extending page: connect the server in your host, then reference its tools by exact name in the relevant BMAD agent's customize.toml (persistent_facts for standing routing, external_sources for on-demand lookups). Serena is the exception that also registers itself, via the claude mcp add ... serena ... command shown above.

The pitfalls are consistent:

• Redundant memory layers. Two systems both claiming to hold "project knowledge" drift apart and confuse the agent. Pick one source of truth per kind of memory (the matrix above).
• Too many chatty MCP surfaces. Every connected server adds tool schemas to context and a decision the model must make. Add the ones that remove work (Serena replaces file reads; Context7 replaces guessing) and skip the ones that just add another thing to consider.
• Believing the marketing. The token-savings and accuracy numbers on Headroom, mem0, Zep, and GraphRAG are almost all vendor-authored and often not apples-to-apples. Adopt for the mechanism, then measure the effect yourself with the scorecard from page 7 and the benchmark harness on the next page.
• Sending secrets or PII into memory tools. Cross-session memory persists and is replayed into future contexts; never store credentials there, and check data regulations before persisting user data.

Hands-on: wire Serena and do a symbol-level rename

This turns "Serena helps" into a rename you can run today. Install the server and register it with Claude Code:

uv tool install -p 3.13 serena-agent
claude mcp add --scope user serena -- \
  serena start-mcp-server --context claude-code --project-from-cwd

Index the project once so the language server answers symbol queries without a cold scan on every call (worth it on any non-trivial repo):

cd ~/src/your-project
serena project index

Point dev-story at the symbol tools by adding one standing fact to Amelia's dev agent. Append to bmad-agent-dev's customize.toml:

persistent_facts = "For code navigation and edits, prefer Serena's mcp__serena__find_symbol, mcp__serena__find_referencing_symbols, and mcp__serena__rename_symbol over reading and patching whole files."

Now the session. Say a fetch helper normalize_url should become canonicalize_url across the codebase. Locate it, list its callers, then rename in one atomic edit:

Illustrative (run it in your own repo; not machine-verified here).

mcp__serena__find_symbol {"name_path": "normalize_url"}
  -> src/fetch/url.py:42   def normalize_url(raw: str) -> str

mcp__serena__find_referencing_symbols
    {"name_path": "normalize_url", "relative_path": "src/fetch/url.py"}
  -> src/fetch/client.py:88     normalize_url(resp.url)
  -> src/crawl/frontier.py:15   from ..fetch.url import normalize_url
  -> tests/test_url.py:7        normalize_url("HTTP://A/b")

mcp__serena__rename_symbol
    {"name_path": "normalize_url", "relative_path": "src/fetch/url.py",
     "new_name": "canonicalize_url"}
  -> updated 4 files, 6 occurrences, one change set

Three calls: one to find the definition, one to see exactly who calls it, one to rename the symbol and every reference to it together. The LSP resolves references by binding, so it skips a same-named local in another module and never touches the string "normalize_url" sitting in a log line.

Contrast the whole-file path this replaces: grep the name, read each hit's full file into context, edit each one, write it back, then re-read to confirm nothing else matched by accident. That is one read-edit-write cycle per file, several thousand tokens of file bodies through the window, and a real chance of a missed caller or a clobbered look-alike. The symbol rename moves only the definition and its true references, so it is both cheaper and safer. Wire it once; every subsequent dev-story edit rides the same path.

Under Claude Code: how these tools attach and route

Every server in this chapter attaches the same way: as an MCP server the host connects to. claude mcp add at project scope writes a committed .mcp.json at the repo root (an mcpServers map of command / args for stdio, or url for http), so the whole team gets the same servers on clone. /mcp lists connection status and runs the OAuth sign-in for servers that need it (tokens land in ~/.claude.json, not in the repo). Once connected, each tool is exposed under a fixed name, mcp__<server>__<tool>, so Serena's find_symbol is mcp__serena__find_symbol, and that exact string is what you reference in a BMAD agent's persistent_facts and in permission rules.

A big server does not have to crowd out the rest of the context. Schemas are deferred by default: only tool names load, and full schemas are pulled on demand through ToolSearch. ENABLE_TOOL_SEARCH governs the choice:

Since Serena exposes dozens of tools, auto usually defers them, so one large server stays cheap until its tools are actually needed.

Route the agent toward the right tool two ways. First, disable the host's overlapping built-in file tools (Read, Grep, Glob, via a disallowedTools entry or a deny rule) so it stops reaching for a whole-file read when a symbol tool is better. Second, add a PreToolUse hook to nudge or block a choice, or a permission rule (mcp__serena__* in allow / deny) that scopes a server's tools exactly like any built-in. The chapter's "wire it in over MCP" is, concretely, those three pieces: .mcp.json, deferred schemas, and a routing hook or rule.

That completes the toolbox. But should you trust these tools' numbers, or BMAD's own? The next page is how you benchmark the method and everything you bolt onto it, across every dimension, so the answer is a measurement rather than a hunch. 👉

Benchmarking BMAD: measuring every dimension

You cannot improve what you do not measure, and you cannot trust a method, or any of the tools from the previous page, on its marketing. This page is how to benchmark BMAD across every dimension a subject-matter expert cares about: token utilization, cache and context efficiency, cost, speed, accuracy, response quality, rework, human effort, and the one metric that actually decides whether the method pays for itself. It builds on the measurement scorecard from page 7 and the levers from page 14, and it hosts the guide's one runnable lab.

On this page

• The honest starting point
• The dimensions, and how to measure each
• Two kinds of metric, and why the distinction matters
• The instruments: what to actually run
• The protocol: A/B done right
• The harness
• Reading the results: BMAD’s actual shape
• Running the benchmark with Claude Code
• Hands-on: capture one real trial and score it
• Vanity metrics and Goodhart’s law
• Pitfalls of benchmarking

The honest starting point

Two facts have to sit at the front, because ignoring either produces numbers that lie.

There is no rigorous, independent public BMAD benchmark. The claims you will find (BMAD's own, and every memory or code tool from the last page) are anecdotal or vendor-authored. Distrust any single number, including your own first run.

Benchmarking an agentic method is genuinely hard, for three reasons that never go away:

• Non-determinism. The same prompt yields different outputs run to run, so one trial is a data point, not a verdict.
• One-shot tasks. You cannot re-run a real project; the second time, the team and the agent both know the answer.
• Confounds. Model version, task difficulty, and the human in the loop all move the result independently of the method.

So a benchmark is an A/B comparison on matched tasks, with repeated trials and honest error bars, not a single figure. Everything below is built to survive those three problems.

The dimensions, and how to measure each

Two kinds of metric, and why the distinction matters

Deterministic metrics you can trust straight away, tokens, cost, wall-clock, cache-hit, git-derived rework, come from usage blocks, timestamps, and git. Read them directly; no judgment involved.

Judged metrics are noisy and need a fixed rubric, accuracy against acceptance criteria, and response quality. Grade them with a stable rubric and a blind judge (a claude-opus-4-8 structured-output call that scores the artifact without being told which condition produced it), the same LLM-judge pattern the recon skill uses for verification. If the grader can see the condition, the score is contaminated.

The instruments: what to actually run

• Tokens and cost: count_tokens before a workflow, the usage block after, or the transcript ledger for a whole session. Multiply by a dated price sheet.
• Cache: compare cache_read to fresh input in the usage block; that ratio is your context-reuse efficiency.
• Research: recon_kit tally counts claims by status straight from the ledger, so research coverage is a number, not a vibe (page 11).
• Rework: git log --stat, the baseline_revision..final_revision bracket a dev-auto run records, revert count, and line churn. This is the most honest quality proxy you have, because redo is expensive and visible.
• Speed: artifact and commit timestamps; CI duration.
• Accuracy: the qa-generate-e2e-tests suite pass rate and the acceptance- criteria checklist from the story.
• Quality: the blind rubric judge over the readiness and code-review artifacts.

If your host is Claude Code, all of these become one repeatable command; the section Running the benchmark with Claude Code below turns each instrument into an exact recipe.

The protocol: A/B done right

1. Pick matched tasks representative of your real work: a feature, an epic, a bugfix. Same tasks for both conditions.
2. Two conditions. BMAD (the track you would actually use) versus a baseline: ad-hoc "vibe" coding, or BMAD track X versus track Y when you are tuning ceremony.
3. Hold constant everything you can: model, effort level, a fresh context per workflow, pinned tool and module versions.
4. Repeat. Run k trials per cell and randomize the order, so learning and time-of-day do not masquerade as the method.
5. Blind the grader to the condition.
6. Report deltas with spread and a matched-pair sign test, never a point estimate.
7. Mind the baseline problem. The honest baseline is "the same team without the method," which you almost never get cleanly. The usable proxies are track A versus track B, or method-on versus method-off for a sprint.

The harness

A from-scratch, stdlib-only harness that takes matched trials and reports every dimension, plus cost-per-correct-outcome and a matched-pair verdict. Drop your own measured trials into TRIALS and it does the arithmetic. The fixture shipped with it is synthetic and illustrative (clearly labeled so), because the value here is the method, not invented scores.

"""
benchmark_harness.py  —  a from-scratch A/B scorecard for a spec-driven method.

Pure stdlib. It ingests a set of matched *trials* (the same task run under two
conditions, "bmad" and "adhoc") and reports every dimension a subject-matter
expert cares about: token utilization, cache/context efficiency, cost, speed,
accuracy, response quality, rework, and human effort. It also computes the metric
that actually decides the trade, cost per *correct* outcome, and flags whether a
difference is a real signal or just noise by checking whether the two conditions'
observed ranges overlap.

IMPORTANT: the TRIALS below are a small, SYNTHETIC teaching fixture, not measured
BMAD results. There is no rigorous public BMAD benchmark; the point of this file
is the *method* and the harness, so you can drop your own measured trials in and
get an honest comparison. Treat every number in the fixture as illustrative.
"""

from statistics import mean

# --- price sheet (Claude Opus 4.8, USD per token; dated, edit for your model) ---
PRICE = {
    "in":     5.00 / 1_000_000,   # base input
    "out":   25.00 / 1_000_000,   # output
    "cread":  0.50 / 1_000_000,   # cache read  (~0.1x input)
    "cwrite": 6.25 / 1_000_000,   # cache write (~1.25x input, 5-minute TTL)
}

# --- the fixture: matched tasks, two conditions, repeated trials -----------------
# tokens are absolute counts; wall is wall-clock minutes; tests is (passed, total);
# rework is redo commits; quality is a 0-5 rubric; approvals is human gate touches.
TRIALS = [
    # task, cond, in, out, cread, cwrite, wall, (passed,total), rework, quality, approvals
    ("auth-feature",  "bmad",  180_000,  95_000, 1_200_000, 220_000, 210, (24, 24), 1, 4.6, 6),
    ("auth-feature",  "bmad",  175_000,  90_000, 1_150_000, 210_000, 195, (23, 24), 2, 4.4, 6),
    ("auth-feature",  "adhoc", 140_000, 120_000,    90_000,  40_000, 150, (18, 24), 7, 3.2, 1),
    ("auth-feature",  "adhoc", 150_000, 135_000,    80_000,  45_000, 165, (17, 24), 9, 3.0, 1),

    ("billing-epic",  "bmad",  320_000, 160_000, 2_400_000, 380_000, 430, (41, 42), 3, 4.5, 11),
    ("billing-epic",  "bmad",  310_000, 155_000, 2_300_000, 360_000, 410, (42, 42), 2, 4.7, 11),
    ("billing-epic",  "adhoc", 260_000, 240_000,   160_000,  70_000, 360, (28, 42), 18, 2.8, 2),
    ("billing-epic",  "adhoc", 275_000, 255_000,   150_000,  75_000, 380, (31, 42), 15, 3.0, 2),

    ("typo-fix",      "bmad",   14_000,   3_000,    60_000,  12_000,  12, (2, 2), 0, 4.8, 1),
    ("typo-fix",      "bmad",   13_500,   2_800,    58_000,  11_500,  11, (2, 2), 0, 4.8, 1),
    ("typo-fix",      "adhoc",   6_000,   1_500,     2_000,   1_000,   4, (2, 2), 0, 4.7, 0),
    ("typo-fix",      "adhoc",   6_500,   1_400,     1_800,     900,   5, (2, 2), 0, 4.6, 0),
]

FIELDS = ["task", "cond", "in", "out", "cread", "cwrite", "wall", "tests",
          "rework", "quality", "approvals"]


def row(t):
    return dict(zip(FIELDS, t))


def cost(r):
    return (r["in"] * PRICE["in"] + r["out"] * PRICE["out"]
            + r["cread"] * PRICE["cread"] + r["cwrite"] * PRICE["cwrite"])


def total_tokens(r):
    return r["in"] + r["out"] + r["cread"] + r["cwrite"]


def cache_hit(r):
    # share of *input* that was served from cache: context-reuse efficiency
    served = r["cread"]
    fresh = r["in"] + r["cwrite"]
    return served / (served + fresh) if (served + fresh) else 0.0


def accuracy(r):
    p, tot = r["tests"]
    return p / tot if tot else 0.0


# metric -> (extractor, "higher"|"lower" is better, formatter)
METRICS = [
    ("tokens/task (k)",     lambda r: total_tokens(r) / 1000, "info",  "{:.0f}"),
    ("cache hit ratio",     cache_hit,                        "higher", "{:.0%}"),
    ("cost/task ($)",       cost,                             "lower",  "{:.2f}"),
    ("wall-clock (min)",    lambda r: r["wall"],              "lower",  "{:.0f}"),
    ("accuracy (tests)",    accuracy,                         "higher", "{:.0%}"),
    ("quality (0-5)",       lambda r: r["quality"],           "higher", "{:.2f}"),
    ("rework (commits)",    lambda r: r["rework"],            "lower",  "{:.1f}"),
    ("human approvals",     lambda r: r["approvals"],         "lower",  "{:.1f}"),
]


def cond_mean(rows, cond, fn):
    vals = [fn(r) for r in rows if r["cond"] == cond]
    return mean(vals) if vals else 0.0


def task_list(rows):
    seen = []
    for r in rows:
        if r["task"] not in seen:
            seen.append(r["task"])
    return seen


def winner(a_mean, b_mean, direction):
    if direction == "info" or a_mean == b_mean:
        return "-"
    a_better = (a_mean > b_mean) if direction == "higher" else (a_mean < b_mean)
    return "bmad" if a_better else "adhoc"


def consistency(rows, fn, direction, champ):
    # matched-pair sign test: on how many tasks does the pooled winner also win?
    # tasks differ in scale, so pooling ranges is misleading; agreement is not.
    agree = total = 0
    for task in task_list(rows):
        b = [fn(r) for r in rows if r["task"] == task and r["cond"] == "bmad"]
        a = [fn(r) for r in rows if r["task"] == task and r["cond"] == "adhoc"]
        if not b or not a:
            continue
        total += 1
        bm, am = mean(b), mean(a)
        if bm == am:
            continue
        task_champ = "bmad" if ((bm > am) == (direction == "higher")) else "adhoc"
        if task_champ == champ:
            agree += 1
    return agree, total


def scorecard(rows):
    print("Dimension            bmad        adhoc       winner   agree")
    print("-" * 60)
    for name, fn, direction, fmt in METRICS:
        a = cond_mean(rows, "bmad", fn)
        b = cond_mean(rows, "adhoc", fn)
        w = winner(a, b, direction)
        if direction == "info" or w == "-":
            tag = "-"
        else:
            ag, tot = consistency(rows, fn, direction, w)
            tag = "{}/{}".format(ag, tot)
        print("{:<20} {:>10} {:>11}   {:<8} {}".format(
            name, fmt.format(a), fmt.format(b), w, tag))


def cost_per_correct(rows):
    print("\nCost per *correct* outcome, by task (the metric that decides it)")
    print("-" * 62)
    print("Task            bmad $/correct   adhoc $/correct   pays back?")
    print("-" * 62)
    tasks = []
    for r in rows:
        if r["task"] not in tasks:
            tasks.append(r["task"])
    for task in tasks:
        out = {}
        for cond in ("bmad", "adhoc"):
            trs = [r for r in rows if r["task"] == task and r["cond"] == cond]
            total_cost = sum(cost(r) for r in trs)
            correct = sum(accuracy(r) for r in trs)  # expected tasks-worth passing
            out[cond] = total_cost / correct if correct else float("inf")
        pays = "yes" if out["bmad"] < out["adhoc"] else "no"
        print("{:<15} {:>13.2f}   {:>15.2f}   {}".format(
            task, out["bmad"], out["adhoc"], pays))


if __name__ == "__main__":
    rows = [row(t) for t in TRIALS]
    print("A/B benchmark: spec-driven (bmad) vs ad-hoc (adhoc)")
    print("Fixture: {} trials over {} tasks (SYNTHETIC, illustrative)\n".format(
        len(rows), len({r["task"] for r in rows})))
    scorecard(rows)
    cost_per_correct(rows)

Running it prints the scorecard and the decider table:

A/B benchmark: spec-driven (bmad) vs ad-hoc (adhoc)
Fixture: 12 trials over 3 tasks (SYNTHETIC, illustrative)

Dimension            bmad        adhoc       winner   agree
------------------------------------------------------------
tokens/task (k)            1647         384   -        -
cache hit ratio             74%         28%   bmad     3/3
cost/task ($)              4.79        4.12   adhoc    3/3
wall-clock (min)            211         177   adhoc    3/3
accuracy (tests)            99%         81%   bmad     2/3
quality (0-5)              4.63        3.55   bmad     3/3
rework (commits)            1.3         8.2   bmad     2/3
human approvals             6.0         1.0   adhoc    3/3

Cost per *correct* outcome, by task (the metric that decides it)
--------------------------------------------------------------
Task            bmad $/correct   adhoc $/correct   pays back?
--------------------------------------------------------------
auth-feature             5.24              5.79   yes
billing-epic             9.11             11.47   yes
typo-fix                 0.24              0.07   no

The agree column is a matched-pair sign test: on how many of the tasks the pooled winner also wins. It replaces a naive range check, because pooling a two-line fix with a multi-epic feature inflates the spread and would hide real differences. The 2/3 on accuracy and rework is the trivial task tying (both perfect, zero redo), which is the honest result, not a defect.

Reading the results: BMAD's actual shape

Read the (synthetic) output as the shape to expect and then verify on your own work:

• BMAD spends more raw tokens (about 4x here) but most are cheap cache reads (74% hit versus 28%), because it re-reads a stable project-context.md and the artifact chain each workflow. So the 4x token count is only a modest cost bump.
• BMAD wins where quality lives: rubric quality (3/3), accuracy (2/3), and rework (2/3, tied only on the trivial task). Fewer redo commits is the clearest signal, because redo is expensive and hard to fake.
• Ad-hoc wins wall-clock and human approvals, both 3/3. Ceremony has a real human-latency cost, the gates, and pretending otherwise is dishonest.
• The decider is cost per correct outcome. BMAD pays back on the feature and the epic and does not on the typo-fix, where ad-hoc is several times cheaper. That single row is the entire argument for Quick Flow: do not run the full method on a one-liner.

The trade in one sentence: BMAD buys lower rework and higher first-pass correctness with higher up-front spend and more gate latency; it wins when the task is large enough for rework to dominate, and loses when it is not. Your benchmark job is to find, for your work, where that crossover sits.

Running the benchmark with Claude Code

The harness above needs real trials, and if BMAD runs inside Claude Code, that is where you generate them. Claude Code's headless mode turns one A/B cell into one command whose JSON output already carries the cost and token numbers, so a shell loop produces the rows you feed to benchmark_harness.py. The flags below are current as of Claude Code v2.1.x; treat them as dated and check claude --help, since the CLI moves.

Instrument a single run. claude -p (print/headless) runs non-interactively; --output-format json returns a structured result instead of prose.

time claude -p "implement STORY-42 per docs/stories/STORY-42.md" \
  --model claude-opus-4-8 --effort xhigh --bare \
  --allowedTools "Read,Edit,Bash" --permission-mode acceptEdits \
  --max-budget-usd 5 --output-format json > run.json

Two flags matter for honest measurement here. --effort is the thinking dial from page 12 (low/medium/high/xhigh/ max), so you benchmark a specific effort, not a default. --bare strips hooks, skills, MCP servers, auto-memory, and CLAUDE.md from the run, which removes confounds you did not mean to measure; keep it on and hold it constant across cells (turn it off only when the thing you are benchmarking is one of those surfaces). --max-budget-usd caps a runaway trial so one outlier cannot skew the batch.

The JSON result carries the deterministic metrics directly (field names as documented; parse with jq):

jq '{cost: .total_cost_usd, usage: .usage_by_model}' run.json

The shape you get back (illustrative, one entry per model queried):

{
  "result": "...response text...",
  "session_id": "b3f1...",
  "total_cost_usd": 4.79,
  "usage_by_model": {
    "claude-opus-4-8": {
      "input_tokens": 180000,
      "output_tokens": 95000,
      "cache_read_input_tokens": 1200000,
      "cache_creation_input_tokens": 220000,
      "cost": 4.79
    }
  }
}

Those four token fields map one-to-one onto the harness row (in, out, cread, cwrite), and total_cost_usd cross-checks the harness's own price-sheet math. One caveat: total_cost_usd is computed at list rates and ignores any discount, so for billing truth use the Console usage page; for benchmarking, list rates are the right apples-to-apples number as long as both conditions use them.

Speed. The published JSON does not guarantee a wall-clock field, so time the process yourself (time, or a date delta around the call). In an interactive session, /usage reports both API and wall duration plus per-model tokens, and /context shows what is filling the window.

A matched A/B loop. Run the same task under two conditions, k trials each, and append one JSONL row per run:

for cond in bmad adhoc; do
  for i in 1 2 3; do
    start=$(date +%s)
    claude -p "$(cat prompt_$cond.md)" \
      --model claude-opus-4-8 --effort xhigh --bare \
      --output-format json > /tmp/run.json
    wall=$(( $(date +%s) - start ))
    jq -c --arg cond "$cond" --argjson wall "$wall" \
      '{cond:$cond, wall:$wall, cost:.total_cost_usd, u:.usage_by_model}' \
      /tmp/run.json >> trials.jsonl
  done
done

Feed trials.jsonl to the harness by replacing its synthetic TRIALS fixture with a few-line loader that reads each row and maps the fields; everything downstream (the scorecard, the matched-pair verdict, cost-per-correct) is unchanged.

The judged metrics need two more steps per run. After a trial finishes:

• Accuracy: run the story's tests and capture pass/total, e.g. pytest -q | tail -1, and write it into the row.

• Quality, judged blind: score the change with a separate headless call, a different model so the judge is independent, fed the diff without the condition label, and constrained to structured output:

  git diff main...HEAD > change.diff
  claude -p "Score this diff 0-5 on correctness, clarity, and test coverage. \
    Return JSON matching the schema." \
    --model claude-sonnet-5 --bare \
    --json-schema rubric.schema.json --output-format json < change.diff \
    | jq '.structured_output'
  

  --json-schema validates the judge's output and returns it under structured_output; a different --model and a label-free prompt are what keep the score honest (the blind rubric judge from earlier, made concrete).

Two dimensions Claude Code will not hand you for free. Rework comes from git, not the run (git log, revert count, churn over baseline..final). And human approvals vanish in headless mode, because --permission-mode acceptEdits (or bypassPermissions) removes the human, so a fully headless A/B measures the autonomous path and reports zero gate latency. To benchmark the gated workflow's human cost, run that arm interactively and count the approvals, or model the gate latency separately; do not let "headless was faster" quietly drop the dimension that headless deleted.

Reproducibility knobs. Use a fresh session per trial (the default) so runs do not contaminate each other, matching the fresh-context discipline from page 14; --session-id <uuid> pins an id when you need to find a transcript later, and --no-session-persistence skips writing one. For per-turn token granularity beyond the summary JSON, enable OpenTelemetry (CLAUDE_CODE_ENABLE_TELEMETRY=1 with an OTLP endpoint) and read the claude_code.token.usage metric. Do not parse the ~/.claude/projects/… transcript JSONL for numbers; that format is internal and shifts between releases, which is exactly the kind of silent breakage a benchmark must avoid.

Hands-on: capture one real trial and score it

The harness is real; its fixture is synthetic. Here is the loop that swaps one synthetic cell for numbers you measured, end to end, on a single story. Nothing in this section is verified on this box (BMAD and Claude Code are not installed); run it in your own repo.

Pick one story that has a test suite. Write two prompts for the same task: prompt_bmad.md (the spec-driven track) and prompt_adhoc.md (a bare "just build it"). Run each arm once, timed, headless:

time claude -p "$(cat prompt_bmad.md)" \
  --model claude-opus-4-8 --bare --output-format json > run.json

time prints the wall-clock to stderr; keep that number. Pull the deterministic metrics out of the result:

jq '{cost:.total_cost_usd, usage:.usage_by_model}' run.json

Illustrative (run it in your own repo; not machine-verified here).

{
  "cost": 4.79,
  "usage": {
    "claude-opus-4-8": {
      "input_tokens": 180000,
      "output_tokens": 95000,
      "cache_read_input_tokens": 1200000,
      "cache_creation_input_tokens": 220000
    }
  }
}

Those four token fields are the harness's in, out, cread, cwrite, and total_cost_usd cross-checks its price-sheet math. Now the metric headless will not hand you: run the story's tests and record pass/total.

pytest -q | tail -1   # "47 passed" -> tests 47/47

Append one JSONL row per trial, then repeat both commands for prompt_adhoc.md:

jq -c '{cond:"bmad", cost:.total_cost_usd, u:.usage_by_model, tests:"47/47", wall:198}' \
  run.json >> trials.jsonl

Point the few-line loader from the section above at trials.jsonl (it replaces the synthetic TRIALS), then print the scorecard:

python3 benchmark_harness.py

You get the same scorecard and cost-per-correct-outcome table shown earlier, now over your two real rows. One trial per arm is a data point, not a verdict; loop each arm three times before you trust the agree column. The point is that the numbers came off your own machine.

Vanity metrics and Goodhart's law

• Tokens-saved is a vanity metric if rework rises. Measure cost per correct outcome, not cost. A run that is 30% cheaper and redone twice is a loss.
• Do not optimize the metric; optimize the outcome. The moment a number becomes a target it stops measuring what it measured (Goodhart). Cross-check any single metric against a second one that would move the opposite way if you were gaming it.
• Speed without accuracy is fast wrong answers. Never report latency alone.

Pitfalls of benchmarking

• Single-run conclusions. Non-determinism means one trial proves nothing; repeat and report spread.
• Unmatched tasks. Different difficulty across conditions is the most common way a benchmark lies to you.
• Grader leakage. A judge that knows the condition scores the label, not the work.
• Cross-version comparisons. A model upgrade between conditions is a confound; pin the model.
• Means without spread. A point estimate hides whether the difference is real.
• Trusting vendor numbers, including BMAD's and every tool's. Regenerate them yourself with this harness before you quote them.

Benchmarking is what turns "the method feels better" into a number you can defend and a crossover you can act on. The next page is the operations cookbook, the exact recipes for the work whose cost and quality you now know how to measure. 👉

Operations cookbook

A reference of recipes for the things you actually do day to day: generate and compare ideas, drive the planning documents, create epics and stories, run research, and (the part every guide skips) undo, revert, and recover from mistakes. Each recipe is goal, exact commands, and the notes that keep you out of trouble. Skills run in a fresh chat unless noted; commands are exact.

On this page

• Generating and comparing ideas
• Planning documents
• Solutioning: architecture, epics, stories
• Implementation
• Fixing mistakes: undo, revert, recover
• Research
• Maintenance
• Hands-on: break something, then recover three ways
• Under Claude Code: the host commands behind each recipe

Generating and comparing ideas

Generate a lot of ideas from scratch.

bmad-brainstorming
> Topic: ways to cut our onboarding drop-off

The coach pulls ideas out of you with a 60+ technique library, shifts creative domain every 10 ideas to avoid clustering, and targets 100+ before organizing. Output: brainstorm.html plus an optional brainstorm-intent.md for downstream skills. The magic is in ideas 50 to 100, so do not stop at the first dozen.

Run several ideas in parallel and pick one. There are three distinct moves, and choosing the right one saves days:

• Widen, then narrow each: brainstorm to get the candidates, then run bmad-forge-idea on each serious contender to harden or kill it. Forge takes exactly one idea, so run it once per candidate.

• Debate them together: bmad-party-mode puts your agents (PM, Architect, Dev, UX) in one room to argue the tradeoffs. Use --mode subagent for honest, independent opinions rather than one model voicing everyone.

  /bmad-party-mode --mode subagent "compare build-vs-buy for our search feature"
  

• Choose between named options on evidence: bmad-deep-recon in its select shape produces a weighted decision matrix you can re-weight.

  bmad-deep-recon
  > help me choose between Postgres full-text, OpenSearch, and Typesense for our search
  

Pressure-test the favorite before spending on it.

bmad-forge-idea
> Idea: replace our REST API with GraphQL. Goal: decide whether it deserves a spike.

An interrogator drives one question at a time in dependency order, brings two voices to every branch, and lands the idea as Hardened (writes forged-idea.md), Killed (records the cause of death), or Clearer. Reach for the adversarial on this gear to attack a specific claim to destruction while you defend it.

Refine an output that feels shallow. At any workflow pause, or on demand:

bmad-advanced-elicitation

It offers five best-fit methods for the content (pre-mortem, first principles, inversion, red-team, Socratic). Pre-mortem is the reliable first pick for any spec or plan; it finds gaps a normal review misses.

Planning documents

Pick the entry into planning. Product Brief is collaborative discovery (the gentle path); PRFAQ is Amazon Working Backwards (a gauntlet that stress-tests the concept customer-first).

bmad-product-brief        # brief.md + addendum.md, a 1-2 page summary
bmad-prfaq                # prfaq-{project}.md, press release then hard questions

Write, update, or validate a PRD. One skill, three intents; state the intent or it will ask.

bmad-prd
> Create a PRD for the saved-filters feature      # coached discovery -> prd.md + .memlog.md
bmad-prd
> Update the PRD: legal now requires audit logging  # reconciles, surfaces conflicts FIRST
bmad-prd
> Validate the PRD against our checklist            # HTML findings report, no edits

Update is the correct tool when requirements change. It reconciles the change against the existing PRD and surfaces conflicts before applying anything, which is how you avoid two documents that quietly disagree.

Design the UX (when it matters).

bmad-ux     # DESIGN.md (visual tokens) + EXPERIENCE.md (behavior, states, journeys)

Distill any intent into a machine contract.

bmad-spec
> distill this PRD (and the Slack thread) into a spec, then break it into stories

Produces SPEC.md (a five-field kernel: Why, Capabilities, Constraints, Non-goals, Success signal) plus companions, and on request an ordered stories.yaml that the autonomous loop can dispatch.

Solutioning: architecture, epics, stories

bmad-architecture                    # ARCHITECTURE-SPINE.md: explicit ADRs
bmad-generate-project-context        # project-context.md (the constitution)
bmad-create-epics-and-stories        # epic files, each with implementable stories
bmad-check-implementation-readiness  # PASS / CONCERNS / FAIL over the whole chain

Create epics and stories the right size. One story is one unit of focused context, not a whole feature. If a story's diff would be unreviewable, it is two stories. The readiness gate is the last cheap checkpoint; do not start implementation on a FAIL, and treat CONCERNS as a to-fix list, not a suggestion.

Implementation

bmad-sprint-planning   # once: sprint-status.yaml sequences the cycle
# then per story, each in a fresh chat:
bmad-create-story  ->  bmad-dev-story  ->  bmad-code-review
# after the epic:
bmad-qa-generate-e2e-tests   ->   bmad-retrospective

Small, well-understood change? Skip the ceremony:

bmad-quick-dev
> Add a --json flag to the export command

It compresses intent, routes to the smallest safe path, implements, self-reviews, commits locally, and offers a push or PR. Say checkpoint to have bmad-checkpoint-preview walk a reviewer through the change by concern.

Fixing mistakes: undo, revert, recover

This is where BMAD's file-first design pays off: almost everything is recoverable because state is on disk and changes are committed, not hidden in a chat.

Undo the last Quick Dev change. Quick Dev commits locally; roll it back with git:

git revert HEAD          # safe: makes a new commit that undoes it
# or, if not yet shared and you want it gone entirely:
git reset --hard HEAD~1

Undo an autonomous (dev-auto / loop) run. The run records baseline_revision and final_revision in the spec frontmatter, bracketing exactly what it produced. Inspect, then revert the range:

git log <baseline_revision>..<final_revision>     # what the run actually did
git revert <baseline_revision>..<final_revision>  # undo the whole run

Equal baseline and final means it made no commits. The loop commits but never pushes, so nothing left your machine.

A plan went wrong mid-sprint. Do not hand-patch the downstream files. Run:

bmad-correct-course
> the auth approach changed from sessions to JWT; reconcile the plan

It reconciles the plan and re-routes, then you let the change propagate through the artifacts.

Two documents contradict each other. Find the first divergent decision, then run Update on the upstream owner (usually the PRD) and let it flow down. Reconcile the source, do not patch every downstream file independently:

rg -n "sessions|JWT|FR-12" _bmad-output docs
bmad-prd   > Update: reconcile the auth decision   # then re-run architecture/stories as needed

A workflow "forgot" an earlier answer. It was not externalized. Check whether the answer is in the artifact or its .memlog.md; if it lived only in a closed chat, BMAD never wrote it down. The fix is to put durable facts in project-context.md or an override so they load every time.

An autonomous run came back blocked. That is a routing signal, not just a failure: unattended execution would have been unsafe. Read the blocking condition, fix the cause, and re-dispatch a fresh run. A blocked story file is permanent (later dispatches halt with story already blocked); to retry, delete the story file so the id reads as pending again.

Research went stale or a claim was wrong. Do not re-run the world:

bmad-deep-recon
> refresh the market research      # re-verifies only stale claims, appends a delta

Refresh delivers confirmed / changed / overturned, and an overturned load-bearing claim triggers a warning naming the downstream artifacts that consumed it.

A long run (research, PRD) died mid-flight. Just reopen it. Files-first design means it resumes from disk: bmad-deep-recon picks up its run folder, bmad-prd re-reads its .memlog.md, dev-auto resumes from the spec status.

Research

The research skill is its own deep dive (see the companion Deep Recon docs), but the everyday shape:

bmad-deep-recon
> competitive research on Linear and Height                # Run mode, native fan-out
> draft a deep research prompt about X for Gemini          # Draft: run it in your own tool
> there's a report at ~/Downloads/r.pdf, process it        # Process: distill into research.md
> refresh the domain research / deepen the pricing dimension

Explore is the default; add "help me choose between" for the select shape. Match the mode to the money: Draft when you have a flat-rate chat subscription, Run when you need the firewall and the staleness map, Process to unify whatever came back.

Maintenance

npx bmad-method install --yes --action update --modules bmm,bmb   # update / add a module
bmad-customize                                                     # author a sparse override
npx bmad-method install --list-options bmm                        # discover config keys

Re-run the installer after adding or removing modules so the skill set stays in sync, and remove stale skill directories from a removed module by hand (the installer does not delete them).

Hands-on: break something, then recover three ways

Three failures, three different undo tools. Reaching for the wrong one is how a two-minute recovery becomes an afternoon. Work the drill in a scratch repo.

Case 1: Quick Dev committed the wrong thing. You ran a small change (see bmad-quick-dev above), it self-reviewed clean, and it committed locally. Later you find it wrong. Quick Dev never pushed, so this is purely local history.

bmad-quick-dev
> Add a --json flag to the export command

Confirm what landed, then undo it with a new commit that reverses the diff (safe: history stays intact and the mistake stays auditable):

git log --oneline -1
git revert HEAD

a1b9f4c (HEAD) Revert "Add --json flag to export command"
7e2c0d1 Add --json flag to export command

Illustrative (run it in your own repo; not machine-verified here).

Prefer git revert HEAD over git reset --hard HEAD~1 unless the commit is unshared and you want it gone with no trace.

Case 2: Claude edited files but did not commit. No commit exists, so git has nothing to revert. This is session state, so use the checkpoint system: /rewind (or double-Esc on an empty prompt), then pick a checkpoint from before the bad turn.

/rewind
  Restore conversation only
> Restore code and conversation      <- pick this
  Restore code only

Illustrative menu.

"Restore code and conversation" rolls back Claude's Read/Edit/Write edits and the transcript together, within the last ~100 checkpoints. What it will NOT bring back: committed git history (that is Case 1's job), any Bash side effect such as a rm or mv a step already ran, and edits made by a background subagent. For those, reach for git or restore the file yourself.

Case 3: a dev-auto run to unwind. The run committed a series, never pushed, and recorded its brackets in the spec frontmatter:

baseline_revision: 7e2c0d1
final_revision:    c4d5e6f

Revert the exact range it produced, in one shot:

git revert 7e2c0d1..c4d5e6f

Illustrative.

Equal baseline and final means the run committed nothing, so there is nothing to undo. The rule underneath all three: match the undo to who owns the change. Committed goes to git; a live uncommitted edit goes to /rewind; a whole autonomous run goes to a git range read from the frontmatter.

Under Claude Code: the host commands behind each recipe

BMAD stays host-agnostic; the recipes above are moves you make through whatever runs the skills. On Claude Code each move maps to one primitive. A skill runs when you type its /<skill> command (or when Claude matches your description to it, see page 11). The rest are host mechanics.

The /rewind caveat is the load-bearing one: it is session undo, not version control. It restores Claude's Read/Edit/Write changes and the transcript within the last 100 checkpoints, but it does not touch committed git history, Bash side effects (rm, mv, a git commit), external API calls, or edits made by a background subagent. So /rewind handles the "Claude just edited the wrong file" case; anything BMAD already committed (Quick Dev, dev-auto, the loop) comes back only through git revert, exactly as the recipes prescribe. Reach for the host primitive that owns the change: checkpoints for live edits, git for history.

These recipes are the vocabulary; the next page puts them to work in four full, narrated end-to-end scenarios. 👉

End-to-end development scenarios

The end-to-end page gave the command skeletons. This page gives the stories: four realistic development runs narrated turn by turn, with the decisions, the mistakes, the recoveries, and the model and token choices a subject-matter expert actually makes. They assume you know the skills (from the command reference) and the recipes (from the cookbook); here we watch them used under real conditions.

On this page

• Scenario 1: a solo founder ships a SaaS MVP (greenfield)
• Scenario 2: a team adds a feature to a legacy monolith (brownfield)
• Scenario 3: a production hotfix under pressure
• Scenario 4: an autonomous overnight epic (the loop)
• The common thread
• Hands-on: reproduce the 11pm hotfix, command by command
• Under Claude Code: the four runs, host-side

Scenario 1: a solo founder ships a SaaS MVP (greenfield)

The situation. One developer, a two-week runway, an idea for a "read-later for podcasts" app: save episodes, auto-transcribe, get a searchable feed. Enough epics (accounts, ingestion, transcription, search, billing) that it earns the full method, but a small enough team that ceremony has to earn its place.

Day 1, framing. She opens a fresh chat and, rather than describing the app to the PRD skill cold, starts wider:

bmad-brainstorming
> How should a "read-later for podcasts" differentiate from Snipd and Airr?

The coach pulls forty ideas out of her before organizing; the useful ones cluster around "transcription quality is the moat." She forges the riskiest assumption:

bmad-forge-idea
> Idea: auto-transcribe every saved episode on ingest. Goal: decide if this is
> viable on a solo budget.

The interrogator lands it as Clearer, not Hardened: transcribing everything on ingest is too expensive; transcribe on first open instead. That one exchange saved a month of the wrong architecture. She does not even keep the artifact; the value was the decision.

Day 1, research. The open question is transcription cost and quality. She has a flat-rate chat subscription, so she uses Draft mode rather than burning IDE tokens:

bmad-deep-recon draft a technical research prompt comparing self-hosted Whisper,
OpenAI, Deepgram, and AssemblyAI on cost-per-hour, accuracy, and latency, for Gemini

She runs the drafted prompt in her chat tool, brings the report back, and Processes it into research.md. The report's staleness map flags the pricing claims as aging fast (a technical pack sets versions and pricing to short windows), which she notes for later. Cost so far in IDE tokens: almost nothing.

Days 2 to 3, planning. PRD on the strong tier (Opus), coached discovery, source-extracting the brief. She runs UX too, because how the transcript reads on a phone is the product:

bmad-prd        # Create -> prd.md, FR-4 "transcribe on first open"
bmad-ux         # DESIGN.md + EXPERIENCE.md; the reading journey is the climax beat

Day 4, solutioning, and the first mistake. She skips architecture ("it's just CRUD plus a job queue") and jumps to stories. Halfway through implementing ingestion, the dev agent picks a different job-queue pattern than the one the transcription story assumed, because nothing wrote the decision down. She catches it in code review, and the fix is not to patch two stories: it is to do the solutioning she skipped.

bmad-architecture                    # ARCHITECTURE-SPINE.md: ADR "one queue, Redis+RQ"
bmad-generate-project-context        # project-context.md: the queue rule, the transcribe-on-open rule
bmad-create-epics-and-stories        # re-cut, now consistent
bmad-check-implementation-readiness  # PASS

The lesson she writes into project-context.md: "All async work goes through the single RQ queue; no ad-hoc threads." Every future dev story now inherits it. This is why solutioning matters, learned the expensive way.

Days 5 to 12, implementation. Sprint planning once, then per story in a fresh chat: create-story, dev-story at xhigh, code-review. She runs the bulk of stories on Sonnet 5 to stretch the budget and escalates the one genuinely hard story (the search ranker) to Opus. After the epic, bmad-qa-generate-e2e-tests and a retrospective. The retrospective's lesson ("transcription jobs need idempotency keys; a retry double-charged the API") goes straight into project-context.md.

Day 12, the moving target. The transcription vendor she chose repriced. Rather than re-researching, she refreshes:

bmad-deep-recon
> refresh the technical research

Refresh re-verifies only the stale pricing claims and appends a delta: the vendor is now 20% cheaper, no decision change. It warns that the overturned price fed FR-4's cost model, so she re-opens the PRD under Update, bumps one number, and moves on. Research-to-spec-to-refresh, the whole loop, on a Tuesday afternoon.

What made it work. Framing before searching killed the expensive idea early; Draft mode kept research nearly free; skipping architecture cost a day and taught her why the phase exists; project-context.md turned each mistake into a permanent guardrail. She shipped in twelve days with a spec chain a future hire can read.

Scenario 2: a team adds a feature to a legacy monolith (brownfield)

The situation. Four engineers, a five-year-old Rails monolith nobody fully understands, a mandate to add "team workspaces" (multi-tenant data isolation across a schema that assumed single tenants). High blast radius; several epics that different engineers will implement in parallel. This is exactly where uncoordinated agents make incompatible decisions.

Week 1, ground truth. Before any planning, they make the codebase a citable source:

bmad-document-project            # scans the monolith, writes orientation docs
bmad-generate-project-context    # captures the real conventions: Sequel not AR, service objects, etc.

They commit both. Now every engineer's BMAD refers to the actual system, and a teammate who clones the repo gets the same understanding.

Week 1, research the invisible part. Multi-tenancy in a shared schema is a minefield of options (row-level, schema-per-tenant, database-per-tenant) with real security stakes. They Run a domain-and-technical recon with high validation, and because it is a build-vs-approach decision, the select shape:

bmad-deep-recon
> help me choose between row-level tenancy, schema-per-tenant, and db-per-tenant
> for a Rails+Sequel monolith at our scale; verification high

The selection matrix, re-weightable, lands on row-level with a Postgres RLS policy, with the runner-up (schema-per-tenant) and the conditions under which it would win instead. The red-team pass surfaces the strongest counter-argument (RLS is easy to bypass with a raw connection), which becomes an architecture constraint rather than a surprise in production.

Week 2, plan and pre-empt conflicts. The PRD (John) turns the decision into requirements; the architecture (Winston) writes the ADRs that keep four engineers consistent: the tenancy key, where it is injected, the RLS policy, the naming convention for tenant-scoped tables. These ADRs are the shared context every implementer reads first, so engineer A's epic and engineer C's epic make the same choices without a meeting. The readiness gate returns CONCERNS ("no story covers the raw-connection bypass the red-team found"); they add one, and it goes to PASS.

Weeks 3 to 4, parallel implementation. Each engineer owns an epic, branches per story, and runs create-story / dev-story / code-review in their own IDE. They coordinate through git and PRs, not through BMAD (which has no built-in multi-human coordination), and put hand-off notes in the stories themselves. The shared sprint-status.yaml, committed, is the one ledger everyone reads. Mid-sprint, product changes the requirement ("workspaces need per-seat billing too"). Instead of four engineers patching four epics, the PM runs:

bmad-correct-course
> add per-seat billing to the workspaces epic; reconcile the plan

which reconciles the PRD and re-routes the stories, then the change propagates. One engineer's half-built story is now wrong; they revert it (git revert HEAD) and re-create it from the corrected plan.

What made it work. document-project stopped the agents from inventing an architecture; the select-shape recon with a red-team pass turned a security minefield into written constraints; the architecture ADRs let four people (and their agents) build in parallel without colliding; correct-course absorbed the mid-sprint change at the source instead of in four places.

Scenario 3: a production hotfix under pressure

The situation. 11pm page: the feed is returning duplicate items after a deploy. One on-call engineer, needs a fix now, cannot afford a wrong one. This is Quick Flow territory, not the full method.

The fix. Fresh chat, intent as a bug-tracker link:

bmad-quick-dev
> https://linear.app/acme/issue/FEED-812  (feed shows duplicates since the 10pm deploy)

Quick Dev compresses the intent, asks one clarifying question ("dedup by item id or by story cluster?"), and because the change touches the ranker (not zero-blast-radius) it writes a short spec, gets her one-line approval, then implements against that boundary. It self-reviews, defers an unrelated nit it noticed (a slow query) to deferred-work.md rather than scope-creeping the hotfix, and commits locally.

The review, in comprehension order. At 11pm she does not want to read a diff in file order. She says:

checkpoint

bmad-checkpoint-preview walks her through the change by concern ("the dedup key now includes story_id"), flags the one highest-blast-radius spot ([ranking] the change to the sort comparator), and suggests how to observe it manually (hit the staging feed, confirm no dupes). She verifies, approves, and it helps open the PR.

The recovery that wasn't needed, and the one that was. The fix deploys clean. Two days later the deferred slow-query note surfaces in bmad-loop-sweep's triage of the deferred ledger, and becomes a proper story in the next sprint. Had the hotfix itself gone wrong, the recovery was one command away: git revert HEAD undoes a Quick Dev change cleanly because it committed as one unit.

What made it work. Quick Flow skipped the ceremony a page couldn't wait for, the spec boundary kept the fix from wandering, checkpoint-preview made the 11pm review fast and safe, and deferral kept the hotfix a hotfix instead of a refactor.

Scenario 4: an autonomous overnight epic (the loop)

The situation. A well-specified epic of twelve small, independent stories (add API endpoints for a dozen resource types, all following the same pattern). The team wants them implemented overnight, human on the loop rather than in it.

Setup. They already have the epic's stories as an ordered stories.yaml (produced by bmad-spec). They install the loop and choose an oversight level they trust for this low-risk, repetitive work:

bmad-loop-setup
# gates.mode = per-epic  (pause between epics, not between stories)
bmad-loop run

The loop is deterministic Python driving the sequence pick -> implement -> adversarially review -> verify -> commit, with each step a fresh coding-agent session so no anchoring bias carries between dev and review. Via the mux they point implementation at their strongest coding model and the adversarial review at a different agent, so the reviewer is genuinely independent. They set a task budget so the loop paces itself and cannot run away with tokens.

Overnight. Ten stories go green. Story 7 comes back blocked: an intent gap (the resource has a soft-delete the spec did not mention). The loop does the right thing: it halts that story, saves the attempted change as a patch, and moves on to the stories that do not depend on it. blocked is a routing signal, not a crash, so the run does not die; it parks the ambiguous one and keeps going.

Morning. The engineer reads sprint-status.yaml: ten done, one blocked, one pending on it. He resolves the escalation:

bmad-loop-resolve FEED-807
> soft-delete: exclude deleted rows from list, 404 on get, hard-delete after 30 days

which disambiguates the frozen spec; the loop re-dispatches story 7 and the one that waited on it. He reviews the ten committed stories with bmad-checkpoint-preview (the loop committed but never pushed), spot-checks the independent review's findings, and pushes. The retrospective notes the missing soft-delete convention, which goes into project-context.md so the next batch generates it correctly from the start.

What made it work. A deterministic control loop with no LLM in the driver's seat made it debuggable and free to run; fresh context per step kept review honest; the mux gave real reviewer independence; blocked parked the one ambiguous story instead of failing the batch; and the human's attention went where it mattered (one disambiguation and a morning review) rather than to twelve identical implementations.

The common thread

Hands-on: reproduce the 11pm hotfix, command by command

Scenario 3 as an exact sequence. Paste it, swap the URL, and you have a disciplined hotfix under pressure. BMAD and Claude Code are not installed on the box that wrote this page, so commands are given verbatim and every transcript is labeled illustrative.

1. Fresh chat, fresh branch. A page-time change should not inherit a stale context window. Cut a branch first so the revert later is clean:

git switch -c hotfix/FEED-812

2. State the intent as the ticket. Open a new chat, invoke bmad-quick-dev (the Quick Flow entry from the command reference), and hand it the bug-tracker URL rather than a paraphrase; the ticket carries the repro:

bmad-quick-dev
> https://linear.app/acme/issue/FEED-812  (feed shows duplicates since the 10pm deploy)

3. Answer the one question; approve the spec. Because the change touches the ranker (not zero-blast-radius), Quick Dev asks one disambiguation, writes a short spec, and waits:

Illustrative (run it in your own repo; not machine-verified here).

Q: dedup by item id, or by story cluster?
> by story cluster

Spec: add story_id to the dedup key in rank_feed(); no other call sites touched.
Approve? (one line)
> approved

4. Let it implement and commit locally. It works against that spec boundary, self-reviews, defers the unrelated slow-query nit to deferred-work.md rather than scope-creeping, and commits as one unit. Do not push yet.

5. Review by concern, not by file. At 11pm you read for blast radius:

checkpoint

bmad-checkpoint-preview walks the diff grouped by concern and flags the hot spot:

Illustrative (run it in your own repo; not machine-verified here).

[dedup]   dedup key now includes story_id      low risk
[ranking] sort comparator changed              HIGHEST blast radius  (verify)
observe:  hit staging feed, confirm no dupes

6. Confirm on staging, then open the PR.

curl -s https://staging.acme.internal/feed | jq '[.items[].id] | length - (unique | length)'  # want 0
gh pr create --fill --base main

7. Safety net. If it regresses in prod, one command undoes it cleanly, because the fix is a single commit:

git revert HEAD

What makes it safe: the spec boundary stops the fix wandering, deferral keeps a hotfix a hotfix, checkpoint-preview puts the riskiest line first, and single-commit discipline makes git revert HEAD a guaranteed undo.

Under Claude Code: the four runs, host-side

BMAD's four runs map onto Claude Code the same way; the end-to-end skeletons stay, dialed by host controls.

Solo SaaS greenfield. Frame and plan in plan mode: Shift+Tab cycles to plan (or launch claude --permission-mode plan), read-only exploration that proposes before it edits any source. Run the bulk stories cheap and escalate the search ranker with /model (/model sonnet for volume, /model opus for the hard one; the switch saves to user settings, so flip it back after). Watch spend with /usage (the old /cost): session cost, wall-vs-API duration, and a per-model breakdown.

Team brownfield monolith. Pull the legacy tree into scope with /add-dir <path> (or claude --add-dir at launch), which also loads that directory's .claude/skills/. Commit a shared .claude/: settings.json, skills/, agents/, rules/, .mcp.json, so four engineers' agents inherit one set of conventions from git. Make the raw-connection ban enforced, not advisory: a PreToolUse hook matching Bash returns {"permissionDecision":"deny"} on the bypass command.

11pm hotfix. Fast local loop with claude --permission-mode acceptEdits: edits and common filesystem commands auto-approve while you review. If it goes wrong, /rewind (Esc-Esc on an empty prompt) restores Claude's own Read/Edit/Write changes; it is session undo, not git, so land one commit and keep git revert HEAD as the real fallback (rewind touches neither committed history nor bash side effects).

Overnight epic. Headless: claude -p "..." --bare --permission-mode acceptEdits --max-budget-usd N --max-turns M, one story per run, so a stuck story cannot drain the whole budget. Chain with --resume or start a fresh session between stories. In the morning, read the cost with /usage and the run itself from the transcript (/export).

Across all four: frame before you build, spend model capability and effort in proportion to the stakes, catch wrong turns at the cheapest layer, and turn every mistake into a line in project-context.md. The method is the same tool dialed from a one-command hotfix to an overnight autonomous epic; what changes is how much of it the work justifies. The last thing that separates a team that gets value from BMAD from one that drowns in it is knowing which mistakes to avoid, which is the next and final page. 👉

Pitfalls, best practices, and recommendations

The closing page: the mistakes that make BMAD feel like overhead, the practices that make it pay, when to reach for it and when to skip it, and a day-one setup you can copy. Everything here is framework-wide; the research-specific anti-pattern catalog lives in the recon guide.

On this page

• The meta-pitfall: ceremony for its own sake
• Framework-wide pitfalls
• Best practices
• When NOT to use BMAD
• Recommendations by team shape
• A day-one setup
• The one-line summary
• Hands-on: reproduce and fix two traps
• Under Claude Code: host-specific pitfalls

The meta-pitfall: ceremony for its own sake

Every other pitfall is a special case of one: producing documents instead of changing decisions. BMAD's value is not the artifacts, it is the wrong turns caught while they are still paragraphs. A two-page PRD that prevents a bad schema beats fifty polished pages nobody reads. If you cannot point to a decision a document changed or a mistake it prevented, that document was ceremony. Measure outcomes (see the scorecard on the memory page), not page count.

Framework-wide pitfalls

Best practices

The short list that prevents most of the above:

1. Frame before you build. A question with a kill criterion (what forge-idea produces) is worth ten open-ended prompts. A PRD claim with an evidence label is worth ten confident guesses.
2. A fresh chat per workflow. Non-negotiable. It is a quality feature, not an inconvenience, because the state that matters is on disk.
3. Pick the track by risk, not prestige. Quick Flow for small and understood; full method for multi-epic; add TEA and gates for regulated or high-stakes. Running the enterprise track on a bugfix is as wrong as vibe-coding a payments system.
4. Solutioning before multi-agent implementation. If several epics could be built by different agents or people, write the architecture first. Catching an alignment issue there is roughly 10x cheaper than in implementation.
5. Commit the shared brain. The _bmad-output/ spec chain and the team *.toml overrides go in git; personal *.user.toml stays local. A teammate who clones without them gets a different BMAD.
6. Keep project-context.md living. Every time an agent repeats a mistake it should have known better than to make, the fix is usually a line here.
7. Run the readiness gate. bmad-check-implementation-readiness is the last cheap checkpoint before code. Do not start Phase 4 on a FAIL.
8. Reconcile upstream, not downstream. When documents disagree, fix the owning document and let the change propagate; do not hand-patch every downstream file.
9. Verify load-bearing claims adversarially. For anything a spec will rely on, have a skeptic try to refute it. This is where real research errors die.
10. Measure, then loosen the gates. Track decisions changed and mistakes prevented; move from per-story-spec-approval toward none only as the evidence earns your trust. Human on the loop is earned, not assumed.

When NOT to use BMAD

The method is honest about its own boundaries:

• The prototype is the answer. When a 30-line experiment settles the question faster than a document chain, run the experiment.
• The change is small. A bugfix or one-file feature is Quick Flow, or no method at all.
• The decision is already made. Skip the analysis theater; de-risk execution instead.
• The work is throwaway. A demo you will delete tomorrow does not need a spec chain. (This is the one place plain "vibe coding" is genuinely fine.)

Recommendations by team shape

BMAD is not the only spec-driven tool, and the honest fit depends on scale. The 2026 consensus across comparison write-ups:

BMAD is the most architecturally ambitious of the SDD tools, which is its strength for complex, multi-team, long-lived work and its cost for small, fast work. Use the track system to place yourself: it is the same tool dialed up or down, not a different tool.

A day-one setup

A sensible starting configuration for a team adopting BMAD on a real project:

# 1. Install core + method + builder + creative suite, pinned for reproducibility
npx bmad-method install --yes \
  --modules bmm,bmb,cis \
  --tools claude-code

# 2. Commit the shared brain, ignore personal + regenerable machinery
cat >> .gitignore <<'EOF'
_bmad/**/*.user.toml
_bmad/core/
_bmad/bmm/
EOF
git add _bmad/_config/manifest.yaml _bmad/custom/ _bmad-output/ .gitignore

Then, before real work:

1. Generate project-context.md (bmad-generate-project-context) and commit it.
2. Write one team override that encodes your non-negotiables (test-first, your MCP docs tool, your naming conventions) in the dev agent's persistent_facts.
3. Restate the two or three load-bearing rules in CLAUDE.md / AGENTS.md.
4. Decide your gates.mode (start at per-story-spec-approval) and write it down.

The one-line summary

Hands-on: reproduce and fix two traps

Two traps above are worth provoking on purpose so the fix sticks. Do both in a scratch repo.

Trap 1: context bloat

Reproduce it. In one long-lived chat, run several workflows back to back without clearing:

> run bmad-prd for the checkout epic
> run bmad-create-epics-and-stories
> run bmad-quick-dev on the coupon bug

Now inspect the window. /context prints it by category:

Illustrative (run it in your own repo; not machine-verified here).

> /context
Context usage: 186k / 200k tokens (93%)
  System prompt + tools    18.4k
  MCP tools                 9.1k
  Memory (CLAUDE.md)        2.1k
  Messages (transcript)   156.4k
  Free space               14k   (auto-compact fires near 95%)

At 93% you are one workflow from auto-compaction quietly dropping early detail. Fix it in two moves. /compact summarizes the transcript in place; give it a focus so it keeps what matters within the current workflow:

> /compact focus on the current story

At a workflow boundary do not summarize, start clean (state lives in files, not scrollback):

> /clear

Re-check and watch it drop:

Illustrative (run it in your own repo; not machine-verified here).

> /context
Context usage: 31k / 200k tokens (15%)
  Messages (transcript)     1.4k

/compact when you want continuity inside one workflow; /clear at every workflow boundary.

Trap 2: permission fatigue

Reproduce it. A single bmad-quick-dev loop makes you approve npm test and git status on every iteration. By the fifth prompt you are rubber-stamping, which is the real hazard: the approval you stop reading is the one that mattered.

Fix it. Pre-authorize the safe, high-frequency calls in .claude/settings.json (project-scoped, so commit it and the team inherits it):

{
  "permissions": {
    "allow": [
      "Bash(npm test *)",
      "Bash(git status)"
    ],
    "defaultMode": "acceptEdits"
  }
}

Each allow rule stops the prompt for exactly those calls; defaultMode: acceptEdits auto-accepts file edits while still gating new commands. You can add the same rules interactively with /permissions. Now the whitelisted calls run prompt-free, and the prompts that remain are the ones worth reading.

Do not reach for bypassPermissions to silence the noise. It disables every check and belongs only on a throwaway sandbox you can delete, never on a real repo.

Under Claude Code: host-specific pitfalls

Every trap above has a host-specific twin. Running BMAD on Claude Code adds its own failure modes, all avoidable once you know the mechanic behind each one.

• Permission fatigue. Clicking approve on every tool call trains you to stop reading them. Set a defaultMode (for example acceptEdits) and write precise allow rules like Bash(npm test *) and Read(src/**) instead of rubber-stamping. Reserve bypassPermissions for throwaway sandboxes; never point it at a real repo.
• Context bloat. Never running /compact or /clear lets the window fill until auto-compaction fires near 95% and silently drops early detail. Watch /context, and /clear between workflows (the one-fresh-chat-per-workflow rule is yours to enforce here).
• Cache-defeating prefixes. A timestamp or per-run id near the front of the context breaks the automatic prefix cache and reprices the whole session (see page 12).
• MCP overload. Connecting many servers so their tool schemas crowd context. Prune servers; rely on deferred schemas and ToolSearch (see page 13).
• Skipping plan mode. Starting a risky change in acceptEdits means edits land before you have seen the approach. Enter plan mode (Shift+Tab) for anything you would want to review first.
• Over-trusting /rewind. It restores Claude's own file edits, not committed history, Bash side effects, or background-subagent edits; those live in git. It is a 100-checkpoint, session-scoped buffer, not version control.
• Parsing the transcript. Scripts that read ~/.claude/projects/.../*.jsonl break on the next release; the format is internal. Use --output-format json or /export.

None of these are BMAD's fault; they are the cost of a powerful host used carelessly. The discipline is the one BMAD asks for everywhere: know where state lives, and spend attention where it changes a decision.

BMAD works when you treat it as bounded context, explicit procedure, externalized state, typed artifact handoffs, source and tool boundaries, human decision gates, and inspectable customization, applied at the scale the work justifies. It stops working the moment it becomes a folder of documents nobody reads. Keep it as the spine, let specialized tools (and the Deep Recon research skill) do what they are good at, make every handoff a file with an owner and a consumer, and spend human attention where it counts most: framing the work and judging the result. That is how "research before code" becomes an operating system for decisions rather than another layer of ceremony. 🎓