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