Start
Why BMad Works This Way
This page gives the reasons behind the way BMad works, in the words the team used when it made each change. Every section ends with links to the pull requests and commits that state the choice.
The Ticket Is the Spec
Section titled “The Ticket Is the Spec”Specs and tickets used to be separate documents written by three skills. They drifted apart, and readers had to decide which one to trust. Now the initiative, epic or story file is the spec at its level, so there is one source per level. Every skill that works on a ticket reads it first and in full and trusts it; only Sofia re-reads its sources, when she updates it.
Where it’s decided: PR #3100, commit 0f20b63.
Start Anywhere, Right-Sized
Section titled “Start Anywhere, Right-Sized”The four stages describe what kind of help a skill gives; they are not a mandatory sequence to complete. BMad recommends the smallest path that safely fits the work. The skills are independent tools, so BMad never marches you through all of them, and the work is complete when the intent is satisfied and its chosen checks pass, whether or not every skill has run.
Where it’s decided: commit b284c68, PR #2916.
Size the Work Before Planning It
Section titled “Size the Work Before Planning It”Sofia sizes new work first and says which path it takes: one bug or story on its own, one epic, an initiative of several epics, or a parent initiative when the work is more than one initiative’s worth. Work that fits one epic stays one epic unless a distinct outcome or an early-usable part splits it. Epics are split by outcome, deployment and slice size, not by who builds them. An epic typically holds eight to twelve stories; past that, Sofia offers a split first, and you decide.
Where it’s decided: PR #2932, commit 49fd27e, commit f6ffa35.
One Story, One Build Session
Section titled “One Story, One Build Session”A story is sized for one agent session: one goal, roughly 500 changed lines, started in a fresh chat from its ticket. The build aims its plan at 900 to 1,600 tokens, because a shorter plan risks ambiguity and a longer one risks context rot in the agent that implements it; a second goal is offered as a split. A story too small to repay its setup is merged into another. A story that would leave work for now, as a placeholder, or wired later is split, never shrunk.
Where it’s decided: PR #1807, PR #2884, PR #2916, commit 2522f6a.
Plan Thin, Refine When It Pays
Section titled “Plan Thin, Refine When It Pays”Slicing writes each epic thin, with refined: false: its scope is agreed, not
its detail. Refining it is its own stage, run on request or before its stories
are planned. A story is an entry in tickets.toml and gets its own file only
when it is reviewed, refined or published. The build plans a story’s
acceptance criteria from the epic’s Requirements and Done when; full criteria
come first only for a bug, a ticket with no epic, or on request.
Where it’s decided: PR #2932, PR #2934, PR #2986, commit 49fd27e.
You Mark Work Done
Section titled “You Mark Work Done”Builds stop at built and never write done. Only you, or a script or AI
session you direct, mark a ticket done. An unattended worker must not choose
its own work: bmad-build-auto builds only what it is given, and given
nothing it halts with unclear intent. Something else chooses each ticket:
you, a script, or an AI session that starts one worker per ticket.
Where it’s decided: PR #2944.
Review Depth Follows the Stakes
Section titled “Review Depth Follows the Stakes”A build reviews quick by default, which suits the inner loop. thorough
suits a change that is unusually risky or makes many design decisions, and
work with production consequences should get a thorough review of every change
before it ships. The depth a build ran at is your choice, not a reason for another
pass. At the end of an epic, bmad-retrospective is the thorough pass over the
epic’s diff.
Where it’s decided: PR #2975, PR #2982, PR #2985.
Research Reports What the Code Does
Section titled “Research Reports What the Code Does”Codebase research in bmad-deep-recon says how the relevant code works at one
commit and how it got that way, every claim cited to a line or a commit, with
no recommendation in it. Its researchers see only factual questions, never the
goal, because a researcher who knows what is being built reports what should
be instead of what is. What to change is yours to decide.
Where it’s decided: PR #3085.
One Facilitator for Planning Documents
Section titled “One Facilitator for Planning Documents”One engine with templates replaces a separate skill per document type: Mary
and John write every planning document through bmad-facilitate. A PRD is
optional: a described intent is valid input too, and a single builder or a
small team that already agrees needs none. Each document fits the level the
work sits at and is sized to the stakes.
Where it’s decided: PR #3172, PR #3176, commit fb28c03.
Change Goes Back to the Plan
Section titled “Change Goes Back to the Plan”A change mid-flight goes to Sofia, who replans so that the remaining tickets
stay true and nothing already built is rewritten. She updates what is required
first, re-slices, drops what no longer belongs, and records the reason as a
dated Decision: line. On a team, the requirements are updated before the
architecture spine. To start, tell Sofia that something changed and ask what
now.
Where it’s decided: commit 3a67c86, commit 1c55fed.
Done and Dropped Work Is the Record
Section titled “Done and Dropped Work Is the Record”A done or dropped ticket is left as written and is not reshaped to a newer
template. An entry is never deleted from an approved tickets.toml; it is
marked dropped, with a Dropped: line that says why, so its id is not reused.
Plans stay as evidence after the work is done, and deleting them can turn
completed entries back into planned work.
Where it’s decided: PR #2944, PR #2986, commit f6ffa35.
Ask in Plain Words
Section titled “Ask in Plain Words”An agent runs the item that fits your request, and a request that fits nothing becomes a conversation. With no request it says in one line what it does. Asked what it can do, it answers in a few sentences and offers its list; the full table appears only when you ask for it. Items are words, not two-letter codes.