Skip to content

Build and Verify

Build and Verify

Use this page to see how a story, or a small change with no ticket, becomes reviewed, committed code. Build and verify checks that the change works as intended. Every size of work builds the same way, one session at a time.

Build and verify
You start withA change one session can finish, or a story that is ready to start: its prerequisites met and no refinement pending
You produceChanged code and tests, one local commit, and a plan recording the run and the story’s status
It is done whenYou have checked the result and marked the story done; the build itself stops at built
Skip it whenThe edit is obvious and low risk: ask your agent directly
What comes nextThe next ready story. When every ticket is done or dropped, the retrospective runs and Sofia closes the epic: Learn and Adjust

In a fresh chat with a clean working tree, name the story, here the first story of the second epic:

/bmad-build 2.1

Named directly, a story is built whether or not it is ready: the build does not check its after or a pending refinement. Ask Sofia what's next? first, or run bmad-build with nothing else to take the first ready story.

A story is sized for one session. If the build finds two independent goals in it, it offers to split, and if you accept it writes the rest to deferred-work.md, as in Build a Change.

With nothing else named, it first offers any build you left unfinished. It reads the story’s entry or file and its epic, and opens the documents they reference when the story needs them. Then it plans, implements, reviews its own work, and commits locally. A change with no ticket works the same way: describe it. See Build a Change.

A small change goes straight from your answers to code. A larger one gets a written plan that waits for your approval; choose Approve and stop to leave it ready-for-dev and build it in a fresh session. As it works, the plan moves from draft to ready-for-dev at approval, then to in-progress, in-review, and built; a small change goes straight to in-progress. Run bmad-build on the story again to resume from its status.

The build’s review is quick by default. For work with production consequences, get a thorough review of every change before it ships: ask bmad-build for a thorough review, run bmad-code-review, or use your PR review bot. At the end of an epic, the retrospective is the thorough pass over the epic’s whole diff.

For an independent review before you accept a story, run bmad-code-review in a fresh chat. It offers the stories at in-review or built, adds its findings to the plan, and leaves the status alone. For another pass on a story at built, you can also hand bmad-build its plan again; for a done story, a PR, or a branch, use bmad-code-review.

When you have checked the result, tell Sofia:

/bmad-agent-po mark story 2.1 done

Only you mark a story done: through Sofia, or through a script or AI session you direct that runs tickets.py mark on the repo store. On a tracker, Sofia moves the card. A story at built already unblocks the stories that wait on it, so builds can follow one another while acceptance stays a deliberate act. Build a hitl story with bmad-build, and mark it done when the person’s part is finished. Keep the plans: they hold each story’s status and the evidence the retrospective reads.

You wantRunPage
A story or a change built, with you presentbmad-buildBuild a Change
An independent review of a built story, a PR, or a branchbmad-code-reviewReview a Change
To understand a change or existing code yourself, block by block, or see it runbmad-walkthroughWalk Through a Change
API and end-to-end tests for finished workbmad-qa-generate-e2e-testsTest Completed Work
A story built with nobody watching, one run per storybmad-build-autoAutonomous Development Loops

Build the early, foundational stories with bmad-build and give their decisions your attention. Once the patterns are stable, bmad-build-auto can build the stories the plan fully settles. It never picks the next story: you, or an AI coding session you direct, start each run. The optional bmad-loop orchestrator does not dispatch from the ticket tree yet. Review the stories with Sofia first, because nobody answers its questions during a run.

Start each run on a clean working tree, on a branch that fits the epic, in a tool with subagents; otherwise the run halts blocked.

bmad-build-auto does not read hitl, so whoever starts unattended runs skips those stories. tickets.py next, the list behind Sofia’s what's next?, flags hitl stories and any checkpoints.

For bmad-build-auto, name the story as a ticket, as in ticket 2.3. Without the word ticket, the run treats the number as a loose description, and its plan and status never reach the tree. bmad-build takes the bare number, such as 1.2.

The run never reads checkpoints; whoever starts it honors them. For a plan_checkpoint on a story Sofia has refined, approve its story file before the run. On one she has not refined, start the run with Halt after planning.:

/bmad-build-auto ticket 2.3. Halt after planning.

Approve the plan, then start it again:

/bmad-build-auto ticket 2.3

For a done_checkpoint, pause after that run until a person says to continue. See Autonomous Development Loops.

A run on a ticket from the tree that halts blocked marks the ticket’s plan blocked, creating the plan if the run halted before planning, and Sofia’s next list shows why. A run on a loose description puts the reason under its plan’s ## Auto Run Result, or, with no plan, in bmad-build-auto-result-<slug-or-timestamp>.md in the initiative folder. Settle the reason, then follow Autonomous Development Loops to clear it and run again.