Start
How BMad Works
Read this page to see how BMad’s skills fit together before you pick one. BMad takes an intent of any size through four stages, and keeps what was decided in one place, the ticket, so that each new session builds from the same spec. You start where your inputs are and skip what does not apply.
The Loop
Section titled “The Loop”
| Stage | Question it answers | It ends with | Main skills |
|---|---|---|---|
| Clarify | Why build it, and is it worth it? | A clear intent: what should be true, what must not change, what is out of scope | Mary (bmad-agent-analyst), who runs bmad-brainstorming and bmad-deep-recon; also bmad-ingest and bmad-forge-idea |
| Plan | What exactly, how, and in what order? | Requirements in the ticket, any decisions epics must share, and stories ready to build | John (bmad-agent-pm), Sofia (bmad-agent-po), and bmad-ux and bmad-architecture, which Sally and Winston run |
| Build and verify | Does it work as intended? | Reviewed, committed code that a person has marked done | bmad-build, bmad-build-auto, bmad-code-review, bmad-walkthrough |
| Learn and adjust | What should we change? | Each epic given a verdict and closed, and changes sent back to Plan | Sofia, then bmad-retrospective |
The stages describe the kind of help a skill gives, not a sequence to complete. A small fix starts at Build and verify, and a vague idea at Clarify. Most work never touches every skill.
At the end of an epic, mark its stories done, run the retrospective on the finished epic, then have Sofia validate and close it.
Who Does What
Section titled “Who Does What”Each role on a team has an agent to work through.
| Person on the team | Agent | What it runs or writes |
|---|---|---|
| Analyst | Mary (bmad-agent-analyst) | Runs bmad-brainstorming, bmad-deep-recon, and bmad-project-context; writes the documents that decide whether and why to go ahead, such as a brief, PRFAQ, or business case |
| Product manager | John (bmad-agent-pm) | Proposes the planning document your goal needs and writes it with you: a PRD, or another planning document when the work calls for one, such as a prototype plan, experiment card, or launch plan |
| Product owner | Sofia (bmad-agent-po) | Writes the initiative, its epics, and their stories; runs the board |
| UX designer | Sally (bmad-agent-ux-designer) | Runs bmad-ux |
| Architect | Winston (bmad-agent-architect) | Runs bmad-architecture |
| Developer | Amelia (bmad-agent-dev) | Runs bmad-build, bmad-code-review, bmad-qa-generate-e2e-tests, and bmad-retrospective |
Each agent runs the skills named, and calling a skill directly does the same work. Say what you want in plain words. Ask an agent what it can do and it answers in a few sentences, with its full list only if you ask for it.
Pick a Route
Section titled “Pick a Route”| You have | Route |
|---|---|
| An obvious, low-risk edit | Your agent, directly. No skill is needed |
| A change one session can build | Make a Small Change |
| A small new app, such as a to-do list | One bmad-build run: Build Your First Change |
| A clear idea bigger than one session, and no initiative yet | Sofia sizes it and writes the initiative or epic: Write and Slice the Initiative |
| A decision made in a conversation or a brainstorm, and one person who decides | Build from a Conversation |
| A quick prototype that proved an idea | Turn a Prototype into a Product |
| A feature several people must agree on | Plan a Feature as a Team |
| Code that works but has no written decisions | Change an Existing Codebase |
| Raw notes, a vague idea, or doubts that it is worth building | Clarify the Idea |
| An initiative already written | Ask Sofia “what’s next?”. The state of the initiative and its epics names the next step |
| An epic whose stories are all built, or a change mid-flight | Learn and Adjust |
BMad works beside other skills. Register one with a module and the bmad
skill recommends it next to its own; see
Modules and Registration.
The Ticket Is the Spec
Section titled “The Ticket Is the Spec”Tracked work lives in a ticket tree with three levels:
| Level | What it is | Holds |
|---|---|---|
| Initiative | An outcome bigger than one epic, such as a new product or a feature set | Its epics, in build order |
| Epic | One capability, or a tightly coupled pair, delivered and deployed together over several build sessions | Its stories, in build order |
| Story | One build session’s worth of work; also a spike or a bug | Nothing; a build plan records its progress |
Each initiative and epic file is the spec at its level. Its Requirements are
lines with stable ids, such as R1 (FR-1), each naming where it came from,
and its Constraints cite their sources too. A requirement is what the work
delivers; a constraint is what it must obey, whichever part it touches. The
file also says what done looks like (Done when), what is out of scope
(Boundaries), and which documents a build must read beside it (References).
Every skill that works on a ticket reads it first and trusts it. At the story
level, the entry, or the story file once it exists, is the spec the build
reads first.
Sofia, the Product Owner, writes and keeps those lines. Her sources can be a
PRD from John, the Product Manager; a brief from Mary, the Business Analyst;
meeting notes; or a design. She lifts what they say into the ticket and cites
them, and later skills read the ticket instead of the sources. UX files and
the architecture spine sit beside the ticket as References. A story is
usually just an entry in its epic’s tickets.toml: one line of what it
delivers and how it is verified.
The build writes its acceptance criteria when it starts.
A story marked hitl is one a person does part of. An after arrow points
from the story that must be built first.
_bmad-output/initiative-check-in/ initiative-check-in.md # the spec for the whole initiative prd-check-in/ ux-check-in/ architecture-check-in/ tickets/ tickets.toml # the epics, in build order epic-door-check-in/ epic-door-check-in.md # the spec for this epic tickets/ tickets.toml # the stories, in build order story-show-each-room-on-its-door-tablet-plan.md # a build's plan and statusExact layout, ids, and statuses are in The Ticket Tree.
The Example App
Section titled “The Example App”Examples on these pages use one made-up app, the room booker: an office’s meeting-room app, where staff book rooms by the hour. The feature most examples follow is called “Check in or lose the room”. It adds a tablet at each door where people check in, and frees a room nobody checks into within the no-show window, the minutes a booked room waits, so someone else can book it.
What the skills ask and write is shortened in the examples. Your runs will word things differently.
Size and Stakes
Section titled “Size and Stakes”Size decides how many build sessions the work needs. Stakes, from a hobby project to regulated or contracted work, decide how heavy the planning gets. A large hobby project keeps planning light; a small change to a regulated system may not. Write a PRD lists what each level changes. Risk, unclear requirements, broad architectural reach, or several people involved push work up from one session even when it is small.
Every size builds the same way: one build session per story. Epics are cut by outcome and deployment, not by who will build them. Once cut, one developer usually owns each, and BMad doesn’t record who. Larger work adds shared context around each build session and repeats it; it does not switch to a different way of delivering.
How Big Each Piece Is
Section titled “How Big Each Piece Is”| Piece | Size | When it is too big or too small |
|---|---|---|
| Build session | One goal: roughly 500 changed lines, not counting tests, in a handful of files, started in a fresh chat | The build offers to split a request with two independent goals; on a split it writes the rest to deferred-work.md |
| Story | One step toward the epic’s Done when, sized for one build session; it need not be something a user sees | Sofia merges a story whose setup outweighs its work, and splits rather than shrinks one that would leave something as a placeholder |
| Epic | One capability, delivered and deployed together; typically eight to twelve stories | Past that, Sofia offers to split the epic; an epic one session can build gets one story |
| Initiative | Several epics toward one outcome | Work bigger than one initiative gets a parent initiative over several initiatives, not epics inside epics |
Sofia sizes stories and epics by judgment, and tickets.py checks no size. A
story that turns out too big usually surfaces when the build offers a split.
Why BMad Works This Way
gives the reasons.
You Make the Calls
Section titled “You Make the Calls”The skills ask only what you alone know and find other facts themselves.
Where they fill a gap without you, they say so: an [ASSUMPTION] tag in a
document, an Assumption: or Open question: line in a ticket. Reading those
is your job, because the next session will treat whatever is written as
settled. At any point you can ask for bmad-advanced-elicitation to push
harder on a draft, or bmad-party-mode to have several agents discuss it.
A build stops at built; you, or a script or AI session you direct, mark a
story done. In an organization, people approve at five sign-offs before work
moves on; Plan Inside an Organization
names them.
For the reasoning behind these choices, see Why BMad Works This Way.