docs/reference/build-auto.md
bmad-build-auto is the unattended automation surface for the canonical Build implementation model. It accepts the same range of direct intent and planned work, and preserves the clarify, plan, implement, and review stages while exposing terminal statuses an orchestrator can act on. It automates the implementation loop; it does not define a second implementation path.
The important architectural boundary is this: bmad-build-auto owns the implementation run and the spec artifact it produces, but it does not own your backlog policy. When review finds something real that is not this story's problem, the skill records that finding in the spec it owns and stops there. Deciding whether to queue it, deduplicate it, escalate it, or ignore it is the orchestrator's responsibility.
bmad-build-auto performs one unattended development-loop iteration:
This skill relies on an ability to run subagents. If subagents are unavailable, the workflow halts blocked with no subagents. If you invoke the skill itself in a subagent session, e.g. "hey, Claude, implement stories 2-10, using a subagent running bmad-build-auto skill for each story", that session will need to spawn its own subagents.
Version control, while optional, is strongly recommended. If present, the working tree must be clean and the agent must be able to update repository metadata.
The main input is the invocation prompt. bmad-build-auto treats that prompt as workflow input, not as a finished implementation plan.
Supported intent shapes include:
If the invocation points to an existing spec file with one of the known status values in the frontmatter, the workflow resumes from that state:
| Spec status | Entry point |
|---|---|
draft | plan |
ready-for-dev | implement |
in-progress | implement |
in-review | review |
done | review again as a fresh follow-up pass |
blocked | halt immediately |
Instead of a spec-file path, the invocation prompt can supply a spec folder and a story id, with no specific spec file path. Any further prompt text (e.g. invoke_dev_with guidance a caller appends) is carried forward as extra planning context, not a competing description of the work.
The workflow reads <spec-folder>/stories.yaml and looks up the entry whose id matches. It takes only that entry's title and description — spec_checkpoint, done_checkpoint, and invoke_dev_with are the dispatching caller's fields and are never read from the file itself.
It then checks <spec-folder>/stories/<story-id>-*.md (id-prefix match) to tell a first dispatch from a resume:
| On-disk match | Outcome |
|---|---|
| None | First dispatch. Requires <spec-folder>/SPEC.md to exist (otherwise halts blocked / no epic spec found). Loads SPEC.md and its companions, then proceeds to planning. |
| Exactly one | Resume: routes on that file's status exactly like the Resume Input table above. A blocked status here reports blocking condition story already blocked, not blocked spec supplied — build-auto discovered the file by id, the caller didn't hand it a blocked spec. A missing or unrecognized status halts blocked / unrecognized status in existing story file. |
| More than one | Halts blocked / ambiguous story file match. |
A blocked story file is permanent: every later dispatch of that id halts with story already blocked, even after the cause is fixed. To retry, delete the story file — the id then reads as pending and the next dispatch starts fresh.
Whenever planning runs — on a first dispatch, or on a resume of interrupted planning (draft) — the workflow also loads every other file matching <spec-folder>/stories/*.md and carries forward each one's Code Map, Design Notes, Spec Change Log, Tasks & Acceptance checklist state, and Auto Run Result details as extra planning context, so planning for one story can see what other stories in the same folder have already decided or produced. Resumes that skip planning skip this too.
Exactly one stories.yaml entry is dispatched per invocation: the workflow never reads another entry or advances to a different story id, regardless of outcome.
On activation, the workflow resolves:
_bmad/config.toml, _bmad/config.user.toml, and optional team/user overrides under _bmad/custom/customize.toml, team overrides, and user overridesproject-context.md files, if presentIt may also look at:
stories/*.md records in the same spec folder, under folder+id dispatch (see Folder+ID Dispatch above)The spec frontmatter status is the main machine-readable state for orchestration:
| Spec Status | Meaning |
|---|---|
draft | Spec exists but has not passed ready-for-dev validation |
ready-for-dev | Spec is complete enough to implement |
in-progress | Implementation is underway |
in-review | Review/triage is underway |
done | Workflow completed successfully |
blocked | Workflow cannot safely continue unattended |
deferred is where the skill reports real findings that are not this story's problem. Each item contains:
summary — one-sentence description of the deferred issueevidence — why the finding is reallocation — optional file:line or component hintseverity — optional final triage severity (high, medium, low)This is intentionally not a backlog. It is a machine-readable review output. The orchestrator has to decide what happens next: create a ticket, append to a central queue, correlate duplicates across runs, or do nothing.
ready-for-devready-for-dev is normally a resume state the workflow passes straight through on its way to implementation. It becomes a genuine halt outcome when the invocation prompt directs a halt after planning: once the spec passes the READY FOR DEVELOPMENT gate, the workflow sets status ready-for-dev and stops there instead of continuing to implementation. Re-dispatching the same spec (or the same spec folder and story id) resumes at implementation via the routing above.
doneOn successful completion, the workflow writes or updates the spec with:
status: doneAuto Run Result section containing:
followup_review_recommended flag. True if LLM decided another review pass seems worthwhile. It's a suggestion, not a must. Simplest way to give it a second review pass is to re-run the skill pointing it at the spec file.baseline_revision — the full canonical revision before implementation. NO_VCS without version control.deferred frontmatter entries for review findings triaged defer. Each item records summary, evidence, and, when known, location plus severity.The workflow commits but does not push. The working copy is clean at exit.
blockedOn blocked completion, the workflow writes:
status: blocked when a spec existsTypical blocking conditions include:
unclear intentintent gapno subagentsmissing spec_file before implementationimplementation verification failedreview repair loop exceeded 5 iterations (non-convergence)blocked spec supplied (a directly-invoked spec file already had status: blocked)no stories.yaml foundstory id not found in stories.yamlno epic spec foundambiguous story file matchunrecognized status in existing story filestory already blocked (folder+id dispatch only — contrast with blocked spec supplied above)An intent gap means the captured intent cannot answer a question the run hit — it can halt the planning step (before any code exists) or the review step. When review halts on it, the working tree is reverted as usual, but the attempted change is first saved as a patch file in {implementation_artifacts}, referenced from the spec's triage log and the halt output. The patch shows which reading of the intent the run implemented — concrete evidence for repairing the intent. If the attempted reading turns out to be correct, git apply the patch and set the spec status to in-review to resume review on it instead of re-running from scratch.
The workflow always tries to leave behind a durable artifact describing what happened.
For new work, the workflow creates:
{implementation_artifacts}/spec-<slug>.md
That spec is the contract between planning, implementation, and review. It contains:
followup_review_recommended, warnings, deferred, revision markers)<intent-contract> blockUnder folder+id dispatch, the workflow writes to <spec-folder>/stories/<story-id>-<slug>.md instead of the primary spec or fallback result paths — including for halts before planning starts. The fallback result artifact below is never used in this mode.
When a halt happens before a slug can be derived from the story's title, the write-back falls back to a fixed slug segment instead:
| Situation | Slug segment used |
|---|---|
stories.yaml missing/unparseable, or no entry matches the story id | unresolved |
More than one on-disk file already matches <story-id>-*.md | ambiguous |
| Entry resolved and no on-disk ambiguity | slug derived from title (and description if needed) |
If the resolved path already exists, the workflow updates its status frontmatter and appends result details under ## Auto Run Result, same as the primary spec artifact. If it doesn't exist, the workflow creates a skeletal story spec: frontmatter status, a heading (the entry's title, or Story <story_id> if the entry couldn't be resolved or the on-disk match was ambiguous), and an ## Auto Run Result section.
If the workflow halts before it has a valid spec_file (outside folder+id dispatch — see above), it writes:
{implementation_artifacts}/bmad-build-auto-result-<slug-or-timestamp>.md
This records the terminal status and blocking condition.
Depending on the route, the workflow may also write:
{implementation_artifacts}/epic-<N>-context.mdintent gap (path recorded in the spec's triage log)An orchestrator integrating bmad-build-auto should:
status, blocking condition, and followup_review_recommended rather than inferring success from chat output alonedeferred: listbaseline_revision..<next story's baseline_revision> to identify a story's commits, or baseline_revision..HEAD at exit when there is no next story yetblocked as a routing signal, not just a failure signalIn practice, blocked usually means the workflow ran into a situation where unattended execution would be unsafe. That is often the point where a higher-level orchestrator, another workflow, or a human should take over.
After resolving a blocked run, the orchestrator should usually start a fresh bmad-build-auto run. If it reuses prior work, it should pass an explicit known-good spec path rather than relying on implicit discovery.