Skip to content

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 BMad delivery loop Three kinds of input enter the delivery loop at different points: a vague notion enters at Clarify, a big clear idea enters at Plan, and a small change goes straight to Build and verify. The loop continues through Learn and adjust, which feeds back into planning as the work evolves. START ANYWHERE RIGHT-SIZED FOR THE WORK IN FRONT OF YOU ? Vague notion Big clear idea Small change Clarify Plan Build and verify Learn and adjust

StageQuestion it answersIt ends withMain skills
ClarifyWhy build it, and is it worth it?A clear intent: what should be true, what must not change, what is out of scopeMary (bmad-agent-analyst), who runs bmad-brainstorming and bmad-deep-recon; also bmad-ingest and bmad-forge-idea
PlanWhat exactly, how, and in what order?Requirements in the ticket, any decisions epics must share, and stories ready to buildJohn (bmad-agent-pm), Sofia (bmad-agent-po), and bmad-ux and bmad-architecture, which Sally and Winston run
Build and verifyDoes it work as intended?Reviewed, committed code that a person has marked donebmad-build, bmad-build-auto, bmad-code-review, bmad-walkthrough
Learn and adjustWhat should we change?Each epic given a verdict and closed, and changes sent back to PlanSofia, 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.

Each role on a team has an agent to work through.

Person on the teamAgentWhat it runs or writes
AnalystMary (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 managerJohn (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 ownerSofia (bmad-agent-po)Writes the initiative, its epics, and their stories; runs the board
UX designerSally (bmad-agent-ux-designer)Runs bmad-ux
ArchitectWinston (bmad-agent-architect)Runs bmad-architecture
DeveloperAmelia (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.

You haveRoute
An obvious, low-risk editYour agent, directly. No skill is needed
A change one session can buildMake a Small Change
A small new app, such as a to-do listOne bmad-build run: Build Your First Change
A clear idea bigger than one session, and no initiative yetSofia 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 decidesBuild from a Conversation
A quick prototype that proved an ideaTurn a Prototype into a Product
A feature several people must agree onPlan a Feature as a Team
Code that works but has no written decisionsChange an Existing Codebase
Raw notes, a vague idea, or doubts that it is worth buildingClarify the Idea
An initiative already writtenAsk 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-flightLearn 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.

Tracked work lives in a ticket tree with three levels:

LevelWhat it isHolds
InitiativeAn outcome bigger than one epic, such as a new product or a feature setIts epics, in build order
EpicOne capability, or a tightly coupled pair, delivered and deployed together over several build sessionsIts stories, in build order
StoryOne build session’s worth of work; also a spike or a bugNothing; 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.

The room booker's check-in feature as a ticket tree One initiative, Check in or lose the room, is the spec for the feature. It has two epics, door check-in and freeing no-show rooms, each built and deployed as one unit. Each epic holds its stories in build order. Story 1.1, showing each room on its door tablet, is marked hitl because a person does part of it. Story 2.1 waits on story 1.2. Check in or lose the room initiative · the spec for the whole feature 1 · Door check-in epic · built and deployed together 2 · Free no-show rooms epic · built and deployed together 1.1 Show each room on its tablet hitl 1.2 Check in at the door 1.3 Show the day's bookings 2.1 Start the no-show timer 2.2 Free it after the window 2.3 Keep the rest of a series after … more stories, in build order … more stories, in build order

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 status

Exact layout, ids, and statuses are in The Ticket Tree.

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

Four development paths use the same delivery pattern Trivial work moves from a change through an edit to verification. One-session work moves from intent through Build to a result. Epic-sized work adds a spec and stories, repeats Build for each story, then integrates and runs a retrospective. Project-sized work adds shared contracts and repeats the epic path before producing an integrated product. ONE DELIVERY PATTERN, RIGHT-SIZED FOUR WAYS Larger paths add context and repeat smaller units. TRIVIAL Obvious and low risk Change Edit Verify ONE SESSION One coherent implementation unit Intent Build plan · build · review Result EPIC-SIZED One outcome, several Build units Intent Spec Stories Build × stories one unit per story Integrate → retrospect judge the combined result PROJECT-SIZED Several epics or roughly 20+ sessions Intent Shared contracts product · UX · tech Epics Epic path × epics spec · stories · Build · retro Integrated product

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.

PieceSizeWhen it is too big or too small
Build sessionOne goal: roughly 500 changed lines, not counting tests, in a handful of files, started in a fresh chatThe build offers to split a request with two independent goals; on a split it writes the rest to deferred-work.md
StoryOne step toward the epic’s Done when, sized for one build session; it need not be something a user seesSofia merges a story whose setup outweighs its work, and splits rather than shrinks one that would leave something as a placeholder
EpicOne capability, delivered and deployed together; typically eight to twelve storiesPast that, Sofia offers to split the epic; an epic one session can build gets one story
InitiativeSeveral epics toward one outcomeWork 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.

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.