opensource/BMAD-METHOD
3
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-08-28 19:20:41 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: clarify BMad development paths (#2669)

Browse Source 
* docs: clarify BMad development paths

* docs: add development path diagrams
This commit is contained in:
Alex Verkhovsky
2026-08-27 01:15:13 -06:00
committed by GitHub
parent 22c76e8ba2
commit 4d8dec79b9
12 changed files with 537 additions and 99 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/explanation/build.md
+61 -6
View File
@@ -1,20 +1,75 @@
---
title: "Build"
description: Reduce human-in-the-loop friction without giving up the checkpoints that protect output quality
title: 'Build'
description: Understand how the attentive Build workflow handles direct intent and planned stories.
sidebar:
order: 7
---
`bmad-build` is the canonical implementation workflow for all development work. It accepts anything from free-form intent or an issue to a fully planned story, and produces code changes with as few human-in-the-loop turns as safety allows.
`bmad-build` is the attentive Build workflow for one coherent,
session-sized unit of software work. It accepts anything from free-form intent
or an issue to a fully planned story, then clarifies, plans, implements, and
reviews that unit with as few human checkpoints as safety allows.
Upstream planning remains optional and variable. A clear change can enter directly; a larger initiative can arrive with a PRD, UX design, architecture, epics, stories, readiness results, and sprint plan. Those artifacts strengthen the implementation context rather than selecting a different development workflow.
Session-sized means that one implementation session can reasonably understand,
implement, review, and finish the intent. It is a scope boundary, not a time
estimate. A small change may require more planning because of its risk,
ambiguity, or architectural reach.
When a planned story enters Build, the story remains the upstream product and acceptance context. Build creates its own execution record for the current run so implementation decisions and review findings stay traceable without replacing the story.
Invoke the `bmad-build` skill directly. Upstream planning determines the
context Build receives; it does not require a different implementation agent.
It lets the model run longer between checkpoints, then brings the human back only when the task cannot safely continue without human judgment or when it is time to review the end result.
When a planned story enters Build, the story remains the product and acceptance
context. Build creates an implementation record for the current run so
decisions, completion state, and review findings remain traceable without
replacing the story.
![Build workflow diagram](/diagrams/build-diagram.png)
## Where Build Fits
Use the smallest planning path that safely produces a session-sized unit, then
give that unit to Build.
| Starting point | What Build receives | What preserves the larger intent |
| ----------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| Direct change | A request, issue, or intent file | The Build implementation record |
| Spec-backed epic | One entry from the spec folder's `stories.yaml` | `SPEC.md`, its companions, and prior story records |
| Full BMad project | One selected story | PRD, UX, architecture, epics, sprint tracking, and prior work |
An obvious, low-risk edit may not need Build. An epic or project needs more
planning around Build, but each implementation unit still uses the same workflow.
See [Choose a Development Path](../how-to/choose-a-development-path.md) for the
complete routing guide.
## How Larger Work Reaches Build
Larger intent becomes a sequence of session-sized units. That sequence can
change as implementation produces evidence. Later stories may need to absorb a
new constraint, reconcile a decision made by an earlier story, or be divided
differently.
The larger BMad flow reduces the risk of losing information when work is
divided. Parent specs and planning artifacts preserve shared intent; story
records carry decisions and completion state; integration checks judge the
combined behavior; and retrospectives compare the whole epic with its contract.
Build handles one unit in that lifecycle. It does not own the backlog, select
the next story, coordinate several epic streams, or replace integration and
retrospective review.
## Attentive and Unattended Work
Use Build for foundational, risky, or important stories where human decisions
may establish patterns for later work. Once those patterns are stable,
`bmad-build-auto` can execute one unit unattended. An AI coding session or
another orchestrator, such as bmad-loop, must still select and dispatch each
unit.
Both Build workflows write story records under the same spec folder,
so downstream integration and Retrospective can use their status regardless of
which Build workflow produced them. See
[Autonomous Development Loops](../reference/build-auto.md) for that contract.
## Why This Exists
Human-in-the-loop turns are necessary and expensive.
docs/explanation/retrospective.md
+33 -12
View File
@@ -1,11 +1,15 @@
---
title: "Retrospective"
title: 'Retrospective'
description: Close out a finished epic by reading the evidence it left — the diff, the commits, the specs — and judging the result instead of trusting memory.
sidebar:
order: 15
---
Run `bmad-retrospective` when an epic is done. It reads what the epic actually produced (the specs, the full diff, the per-story commits, the sprint status) and works from that evidence rather than anyone's recollection of how the work went. What comes back is a written review, a set of owned action items, and a verdict on whether the epic met its bar.
Run `bmad-retrospective` directly when an epic is done. It reads what the epic
produced—the specs, story records, full diff, commits, and tracking artifacts—and
uses that evidence instead of anyone's recollection. It produces a written
review, proposed action items, and a verdict on whether the epic met its
acceptance criteria.
## What it does
@@ -26,12 +30,26 @@ Each story passed its own review in isolation, so the bugs that survive to this
The retrospective reports what the diff, the commits, and the specs actually show. It won't manufacture a root cause or a pattern the code doesn't back up.
:::
## Two Epic Inputs
Retrospective accepts either full-flow sprint tracking or the lightweight spec
folder described in [Choose a Development Path](../how-to/choose-a-development-path.md).
| Epic input | Inventory and completion state | Retrospective output |
| ------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------- |
| Sprint-tracked epic | The selected epic in `sprint-status.yaml` and its story artifacts | A dated document in the implementation artifacts; sprint status is updated |
| Spec-backed epic | `SPEC.md`, ordered `stories.yaml`, and `stories/<id>-*.md` records | `RETROSPECTIVE.md` in the spec folder; no sprint-status file is created or changed |
In the spec-backed path, `stories.yaml` defines the epic inventory and each
story record's frontmatter defines its completion state. Retrospective uses the
same rule whether Build or Build Auto produced a record.
## What you get
Two artifacts and a decision:
You receive an evidence report and a decision:
- **A retrospective document** in your implementation artifacts — the evidence inventory, findings grouped with their sources, the verdict, and the action items.
- **An updated sprint status** — the epic's retrospective marked done, each action item appended with a stable id and a link back to its finding.
- **A retrospective document** with the evidence inventory, findings grouped with their sources, the verdict, and proposed action items.
- **In sprint mode, an updated sprint status** marks the retrospective as done and links action items to their findings. Spec-backed mode does not use sprint status.
- **A verdict** of `accepted`, `accepted-with-open-items`, or `rejected`, which tells you whether to start the next epic or hold and fix first. Unfinished stories for that epic make the machine verdict **rejected** (a human can still override interactively).
## What to do with the output
@@ -46,11 +64,14 @@ A failing epic never closes as quietly accepted. If the criteria aren't met, or
## Running it
Say "run a retrospective" or "let's retro epic 3." It finds the completed epic from sprint status, or takes the one you name, and by default stops at the written report and verdict.
Invoke `bmad-retrospective` with the epic number or spec folder. With no input,
it can find the completed epic from sprint status. By default, it stops at the
written report and verdict.
| You want | Do this |
| --- | --- |
| A standard review | "run a retrospective" |
| A specific epic | "retro epic 3" |
| The team to talk it over | Ask to "discuss it as a team" — it convenes [party mode](./party-mode.md) over the real findings, off by default |
| An unattended run for automation | `-H <epic>` — headless, verdict on the evidence alone |
| You want | Do this |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| A standard review | `/bmad-retrospective` |
| A specific epic | `/bmad-retrospective 3` |
| A spec-backed epic | `/bmad-retrospective _bmad-output/specs/spec-<slug>/` |
| The team to talk it over | Ask to "discuss it as a team" — it convenes [party mode](./party-mode.md) over the real findings, off by default |
| An unattended run for automation | `-H <epic>` — headless, verdict on the evidence alone |
docs/how-to/choose-a-development-path.md
+163
View File
@@ -0,0 +1,163 @@
---
title: 'Choose a Development Path'
description: Choose the smallest BMad path that safely fits a software change, from a trivial edit to a multi-epic project.
sidebar:
order: 3
---
Use this guide to choose the smallest amount of BMad that safely fits your
software change.
![The BMad loop lets vague notions enter at Clarify, clear ideas at Plan, and small changes at Build; Learn feeds back to Plan](../images/bmad-delivery-loop.svg)
Every path uses the same delivery loop. Larger work adds shared context around
the loop and repeats its implementation unit; it does not switch to a separate
delivery system.
## When to Use This
- Before starting a change when you are unsure how much planning it needs
- When one request has grown beyond a single implementation session
- When deciding which stories need your attention and which can run unattended
- When coordinating several epics without losing the shared product intent
:::note[Prerequisites]
Install BMad before using Build or another BMad workflow. You don't need BMad
for an obvious, low-risk edit.
:::
## Choose the Path
### 1. Find the Smallest Safe Unit
Start with the intent, not a preferred workflow. Ask whether one implementation
session can reasonably understand, implement, review, and finish the change.
Scope is only one signal. Use more planning when the work has high risk,
unclear requirements, broad architectural reach, cross-system effects, or
coordination between people or teams.
The session counts below are guidelines, not requirements. A small security
change may need more structure than a much larger routine update.
### 2. Choose a Path
| Path | Use it when | Start with |
| ------------------ | --------------------------------------------------------------------------------------- | -------------------------------------------------- |
| Trivial work | The edit is obvious, low-risk, and does not benefit from structured review | Make the edit directly |
| One-session work | One coherent intent fits an implementation session | `bmad-build` |
| Epic-sized work | One coherent outcome needs several implementation sessions | `bmad-spec`, then Story Breakdown |
| Project-sized work | The work spans several epics or likely needs roughly 20 or more implementation sessions | The [full BMad flow](../reference/workflow-map.md) |
![Four nested paths reuse the same unit: edit directly, run one Build, repeat Build across an epic, or repeat epic paths across a project](../images/development-paths.svg)
If a tiny change would benefit from explicit planning and review, use
`bmad-build` even though you could edit it directly.
## Run the Path
### 3. Start Trivial or One-Session Work
For trivial work, make the change with your normal development tools. Do not
add workflow steps that provide no useful safety or clarity.
For one-session work, invoke Build directly with the outcome you want:
```text
/bmad-build Add JSON output to the diffsettings command without changing its
existing formats.
```
Build accepts direct intent, an issue, an intent file, an existing Build spec,
or a planned story. It clarifies the unit, plans when needed, implements it,
reviews the result, and records what happened. See [Build](../explanation/build.md)
for the implementation model.
### 4. Start Epic-Sized Work
Use the lightweight epic path when the work needs several Build sessions but
still has one coherent outcome.
**Define and divide the epic**
1. Run `bmad-spec` with the epic intent.
2. Ask for Story Breakdown. This creates the ordered `stories.yaml` beside
`SPEC.md`.
3. Review the proposed order and decide which stories need checkpoints.
The story list is an execution plan, not a promise that nothing will change.
Update the spec and re-run Story Breakdown when earlier work reveals a missing
constraint, a better division, or a conflict between stories.
**Establish the implementation pattern**
Implement important, risky, or foundational stories with `bmad-build`. Early
stories often settle the architecture, initial project structure, and repeated
patterns that later stories will follow. Give those decisions human attention
before automating repetitions of them.
Run Build once per story. Build creates or resumes that story's implementation
record under the spec folder and keeps it linked to the parent spec.
**Finish the epic**
Verify the stories together, not only one at a time. Then run
`bmad-retrospective` with the spec folder. Retrospective reads `stories.yaml`
as the epic inventory and judges the combined result against the parent spec.
### 5. Start Project-Sized Work
Use the full BMad flow for a greenfield product, a multi-epic initiative, or
work likely to need roughly 20 or more implementation sessions.
Prepare the planning that the project actually needs: discovery, product
requirements, UX, architecture, epics, readiness, and sprint planning. These
artifacts create shared contracts and coordination around implementation. They
do not replace Build. Each epic still becomes a sequence of session-sized units.
Independent epic streams can proceed in parallel when their dependencies and
integration boundaries are explicit. Each stream needs an owner, and all
streams remain accountable to the same product intent and architecture. Run
integration checks and a retrospective at each epic boundary.
## Operate Larger Paths
### 6. Add Automation After Decisions Stabilize
`bmad-build-auto` runs one session-sized unit without waiting for human input.
It does not choose the next story or own the backlog.
Use it after the important implementation decisions are stable. An AI coding
session can act as the orchestrator, dispatch one Build Auto worker per story,
and revise later work when new evidence appears. The optional
[bmad-loop](https://github.com/bmad-code-org/bmad-loop) orchestrator can run an
ordered `stories.yaml` deterministically.
bmad-loop follows list order. It does not infer a dependency graph or provide
project-level parallel coordination. For the worker contract, story selection,
and status records, see
[Autonomous Development Loops](../reference/build-auto.md).
### 7. Protect the Larger Intent
Dividing work can lose information. A requirement may weaken, a constraint may
disappear, or two correct stories may fail when combined. Larger BMad paths add
controls for those risks:
- Product, UX, architecture, and epic artifacts preserve shared decisions.
- Every implementation unit remains traceable to its parent contract.
- Story records carry implementation decisions and completion state forward.
- Later units can incorporate evidence from earlier work.
- Integration checks judge the combined behavior.
- New evidence can update later units or the parent plan.
- Retrospectives judge the whole epic and feed lessons into later work.
Planning therefore continues during implementation. The sequence of units can
evolve as long as changes are reconciled with the parent intent.
## What You Get
You get a development path sized to the work: direct editing for the safest
trivial changes, one attentive Build run for a session-sized unit, a shared spec
and story records for an epic, or full project contracts and coordination for
several epics.
docs/how-to/get-answers-about-bmad.md
+1 -1
View File
@@ -2,7 +2,7 @@
title: 'How to Get Answers About BMad'
description: Use an LLM to quickly answer your own BMad questions
sidebar:
order: 3
order: 10
---
Use BMad's built-in help, source docs, or the community to get answers — from quickest to most thorough.
docs/how-to/quick-fixes.md
+19 -7
View File
@@ -5,7 +5,9 @@ sidebar:
order: 4
---
Bug fixes, refactorings, and small targeted changes can enter **Build** directly with little or no upstream planning. This is the same implementation workflow used for fully planned stories.
Use the `bmad-build` workflow for a small targeted change that benefits from
planning and structured review. This is the same attentive implementation
workflow used for planned stories.
## When to Use This
@@ -14,6 +16,13 @@ Bug fixes, refactorings, and small targeted changes can enter **Build** directly
- Minor feature tweaks or configuration changes
- Dependency updates
## When to Skip This
Make an obvious, low-risk edit directly when Build's planning and review would
not add useful safety or clarity. If the work no longer fits one implementation
session, use [Choose a Development Path](./choose-a-development-path.md) to add
the right planning context.
:::note[Prerequisites]
- BMad Method installed (`npx bmad-method install`)
@@ -31,25 +40,26 @@ Open a **fresh chat session** in your AI IDE. Reusing a session from a previous
Build accepts free-form intent — before, with, or after the invocation. Examples:
```text
run build — Fix the login validation bug that allows empty passwords.
/bmad-build Fix the login validation bug that allows empty passwords.
```
```text
run build — fix https://github.com/org/repo/issues/42
/bmad-build Fix https://github.com/org/repo/issues/42.
```
```text
run build — implement the intent in _bmad-output/implementation-artifacts/my-intent.md
/bmad-build Implement the intent in
_bmad-output/implementation-artifacts/my-intent.md.
```
```text
I think the problem is in the auth middleware, it's not checking token expiry.
Let me look at it... yeah, src/auth/middleware.ts line 47 skips
the exp check entirely. run build
the exp check entirely. /bmad-build
```
```text
run build
/bmad-build
> What would you like to do?
Refactor UserService to use async/await instead of callbacks.
```
@@ -93,4 +103,6 @@ Before running the same Build implementation loop, consider adding PRD, UX, arch
- You are unsure about the scope and need requirements discovery first
- You need documentation or architectural decisions recorded for the team
See [Build](../explanation/build.md) for how direct intent and planned work converge on the same implementation loop.
See [Choose a Development Path](./choose-a-development-path.md) for the
epic-sized and project-sized paths, or [Build](../explanation/build.md) for how
direct intent and planned work use the same Build workflow.
docs/images/development-paths.svg
+98
View File
@@ -0,0 +1,98 @@
<svg xmlns="http://www.w3.org/2000/svg" width="760" height="1040" viewBox="0 0 760 1040" role="img" aria-labelledby="title description">
<title id="title">Four development paths use the same delivery pattern</title>
<desc id="description">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.</desc>
<defs>
<linearGradient id="background" x1="0" y1="0" x2="1" y2="1">
<stop offset="0" stop-color="#041629"/>
<stop offset="1" stop-color="#0a2c47"/>
</linearGradient>
<marker id="arrow" viewBox="0 0 10 10" refX="8" refY="5" markerWidth="7" markerHeight="7" orient="auto-start-reverse">
<path d="M 0 0 L 10 5 L 0 10 z" fill="#39ccff"/>
</marker>
</defs>
<rect width="760" height="1040" rx="20" fill="url(#background)"/>
<path d="M0 80H760M0 160H760M0 240H760M0 320H760M0 400H760M0 480H760M0 560H760M0 640H760M0 720H760M0 800H760M0 880H760M0 960H760M95 0V1040M190 0V1040M285 0V1040M380 0V1040M475 0V1040M570 0V1040M665 0V1040" stroke="#38bdf8" stroke-opacity=".05"/>
<g font-family="Avenir Next, Avenir, Segoe UI, sans-serif">
<text x="380" y="45" fill="#ffe34f" font-size="17" font-weight="700" text-anchor="middle" letter-spacing="1.2">ONE DELIVERY PATTERN, RIGHT-SIZED FOUR WAYS</text>
<text x="380" y="70" fill="#9cc8e2" font-size="18" text-anchor="middle">Larger paths add context and repeat smaller units.</text>
<g transform="translate(20 90)">
<rect width="720" height="175" rx="16" fill="#0b253b" stroke="#39ccff" stroke-opacity=".28"/>
<text x="24" y="36" fill="#ffe34f" font-size="18" font-weight="700" letter-spacing="1">TRIVIAL</text>
<text x="24" y="62" fill="#9cc8e2" font-size="18">Obvious and low risk</text>
<path d="M310 110H345M505 110H540" stroke="#39ccff" stroke-width="3" stroke-linecap="round" marker-end="url(#arrow)"/>
<g text-anchor="middle">
<rect x="160" y="77" width="150" height="66" rx="11" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="235" y="118" fill="#ffffff" font-size="21" font-weight="600">Change</text>
<rect x="355" y="77" width="150" height="66" rx="11" fill="#112f49" stroke="#39ccff" stroke-width="2"/>
<text x="430" y="118" fill="#ffffff" font-size="21" font-weight="600">Edit</text>
<rect x="550" y="77" width="150" height="66" rx="11" fill="#112f49" stroke="#7ee787" stroke-width="2"/>
<text x="625" y="118" fill="#ffffff" font-size="21" font-weight="600">Verify</text>
</g>
</g>
<g transform="translate(20 285)">
<rect width="720" height="175" rx="16" fill="#0b253b" stroke="#39ccff" stroke-opacity=".28"/>
<text x="24" y="36" fill="#ffe34f" font-size="18" font-weight="700" letter-spacing="1">ONE SESSION</text>
<text x="24" y="62" fill="#9cc8e2" font-size="18">One coherent implementation unit</text>
<path d="M310 110H345M505 110H540" stroke="#39ccff" stroke-width="3" stroke-linecap="round" marker-end="url(#arrow)"/>
<g text-anchor="middle">
<rect x="160" y="77" width="150" height="66" rx="11" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="235" y="118" fill="#ffffff" font-size="21" font-weight="600">Intent</text>
<rect x="355" y="77" width="150" height="66" rx="11" fill="#12334e" stroke="#39ccff" stroke-width="3"/>
<text x="430" y="108" fill="#ffffff" font-size="21" font-weight="700">Build</text>
<text x="430" y="130" fill="#9cc8e2" font-size="14">plan · build · review</text>
<rect x="550" y="77" width="150" height="66" rx="11" fill="#112f49" stroke="#7ee787" stroke-width="2"/>
<text x="625" y="118" fill="#ffffff" font-size="21" font-weight="600">Result</text>
</g>
</g>
<g transform="translate(20 480)">
<rect width="720" height="250" rx="16" fill="#0b253b" stroke="#39ccff" stroke-opacity=".28"/>
<text x="24" y="36" fill="#ffe34f" font-size="18" font-weight="700" letter-spacing="1">EPIC-SIZED</text>
<text x="24" y="62" fill="#9cc8e2" font-size="18">One outcome, several Build units</text>
<path d="M260 105H290M430 105H460" stroke="#39ccff" stroke-width="3" stroke-linecap="round" marker-end="url(#arrow)"/>
<path d="M535 138V153H225V166" fill="none" stroke="#39ccff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#arrow)"/>
<path d="M335 199H395" stroke="#39ccff" stroke-width="3" stroke-linecap="round" marker-end="url(#arrow)"/>
<g text-anchor="middle">
<rect x="120" y="76" width="140" height="58" rx="10" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="190" y="112" fill="#ffffff" font-size="20" font-weight="600">Intent</text>
<rect x="300" y="76" width="130" height="58" rx="10" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="365" y="112" fill="#ffffff" font-size="20" font-weight="600">Spec</text>
<rect x="470" y="76" width="130" height="58" rx="10" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="535" y="112" fill="#ffffff" font-size="20" font-weight="600">Stories</text>
<rect x="115" y="166" width="220" height="66" rx="11" fill="#12334e" stroke="#39ccff" stroke-width="3"/>
<text x="225" y="195" fill="#ffffff" font-size="20" font-weight="700">Build × stories</text>
<text x="225" y="216" fill="#9cc8e2" font-size="16">one unit per story</text>
<rect x="405" y="166" width="260" height="66" rx="11" fill="#112f49" stroke="#7ee787" stroke-width="2"/>
<text x="535" y="195" fill="#ffffff" font-size="19" font-weight="600">Integrate → retrospect</text>
<text x="535" y="216" fill="#9cc8e2" font-size="16">judge the combined result</text>
</g>
</g>
<g transform="translate(20 750)">
<rect width="720" height="270" rx="16" fill="#0b253b" stroke="#39ccff" stroke-opacity=".28"/>
<text x="24" y="36" fill="#ffe34f" font-size="18" font-weight="700" letter-spacing="1">PROJECT-SIZED</text>
<text x="24" y="62" fill="#9cc8e2" font-size="18">Several epics or roughly 20+ sessions</text>
<path d="M250 112H280M455 112H485" stroke="#39ccff" stroke-width="3" stroke-linecap="round" marker-end="url(#arrow)"/>
<path d="M570 145V163H240V178" fill="none" stroke="#39ccff" stroke-width="3" stroke-linecap="round" stroke-linejoin="round" marker-end="url(#arrow)"/>
<path d="M365 213H410" stroke="#39ccff" stroke-width="3" stroke-linecap="round" marker-end="url(#arrow)"/>
<g text-anchor="middle">
<rect x="110" y="79" width="140" height="66" rx="10" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="180" y="119" fill="#ffffff" font-size="20" font-weight="600">Intent</text>
<rect x="290" y="79" width="165" height="66" rx="10" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="372" y="108" fill="#ffffff" font-size="18" font-weight="600">Shared contracts</text>
<text x="372" y="130" fill="#9cc8e2" font-size="14">product · UX · tech</text>
<rect x="495" y="79" width="150" height="66" rx="10" fill="#112f49" stroke="#9cc8e2" stroke-width="2"/>
<text x="570" y="119" fill="#ffffff" font-size="20" font-weight="600">Epics</text>
<rect x="115" y="178" width="250" height="70" rx="11" fill="#12334e" stroke="#39ccff" stroke-width="3"/>
<text x="240" y="207" fill="#ffffff" font-size="20" font-weight="700">Epic path × epics</text>
<text x="240" y="230" fill="#9cc8e2" font-size="15">spec · stories · Build · retro</text>
<rect x="420" y="178" width="245" height="70" rx="11" fill="#112f49" stroke="#7ee787" stroke-width="2"/>
<text x="542" y="220" fill="#ffffff" font-size="19" font-weight="600">Integrated product</text>
</g>
</g>
</g>
</svg>
Side by Side

After

Width:  |  Height:  |  Size: 7.9 KiB

docs/index.md
+6 -1
View File
@@ -23,6 +23,10 @@ You can use either group on its own. Many people run the thinking skills and
never ask BMad to write a line of code, and a small fix can go straight to
building with no planning at all.
Use the smallest path that safely fits the work.
[Choose a Development Path](./how-to/choose-a-development-path.md) is the
complete routing guide, from a trivial edit to a multi-epic project.
## Find Your Starting Point
**You want to see it work.**
@@ -39,7 +43,8 @@ Consider running `bmad-project-context`, then build as usual. See
**You are building a larger feature or a whole product.**
If you can give `bmad-spec` a complete intent, start there. If you need to
go through the ideation/planning paces first, choose a path in the
go through the ideation/planning paces first, choose a path in
[Choose a Development Path](./how-to/choose-a-development-path.md) or the
[Workflow Map](./reference/workflow-map.md).
**Your idea is still vague, or you are not sure it is a good one.**
docs/reference/build-auto.md
+67 -10
View File
@@ -5,23 +5,32 @@ sidebar:
order: 7
---
`bmad-build-auto` is the unattended automation surface for the canonical [Build](../explanation/build.md) 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.
`bmad-build-auto` is the unattended worker for one session-sized unit in the
canonical [Build](../explanation/build.md) implementation model. One invocation
clarifies, plans, implements, and reviews one intent or story, then exposes a
terminal status that a human or orchestrator can act on.
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.
Build Auto does not choose the next story, repeat across a backlog, coordinate
epics, or run a retrospective. It owns only its implementation run and the
record it creates or resumes. A human or an orchestrator, such as an AI coding
session or bmad-loop, owns backlog policy and dispatch.
## What It Does
`bmad-build-auto` performs one unattended development-loop iteration:
`bmad-build-auto` performs one unattended implementation run:
1. Clarify the incoming intent
2. Create (or find and resume) a spec file
3. Implement the change
4. Review the result
5. Finish by writing a terminal status to the spec file or fallback result artifact.
5. Finish by writing a terminal status to the spec file or fallback result artifact
## Prerequisites
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.
This skill relies on an ability to run subagents. If subagents are unavailable,
the workflow halts `blocked` with `no subagents`. An AI coding session that
orchestrates several stories must start one Build Auto worker per story. Each
worker must be able to start the review subagents used inside its own run.
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.
@@ -60,11 +69,11 @@ The workflow reads `<spec-folder>/stories.yaml` and looks up the entry whose `id
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. |
| 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`. |
| 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.
@@ -72,7 +81,55 @@ Whenever planning runs — on a first dispatch, or on a resume of interrupted pl
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.
### Context Inputs
The shared spec-backed epic layout is:
```text
<spec-folder>/
├── SPEC.md
├── stories.yaml
└── stories/
├── 1-<slug>.md
├── 2-<slug>.md
└── ...
```
`stories.yaml` is the ordered inventory. Build and Build Auto create or resume
the Markdown records under `stories/`, and each record carries its lifecycle
status in frontmatter. Downstream consumers use the location and status rather
than depending on which Build workflow produced the record.
## Orchestration Options
Build Auto is the worker in each option below. The orchestrator selects a unit,
starts one worker, reads its result, and decides what happens next.
### Run an ordered manifest with bmad-loop
The optional [bmad-loop](https://github.com/bmad-code-org/bmad-loop)
orchestrator processes a spec folder's `stories.yaml` in list order. It is a
linear scheduler: it does not infer a dependency graph. Arrange the list so
each story's prerequisites appear first.
Selecting one story runs only that story. It does not mean “start here and run
the remainder.” Retrospective is a separate epic-closing activity; bmad-loop
may recommend it, but `bmad-retrospective` performs it.
### Use an AI coding session as the orchestrator
An AI coding session can act as the orchestrator, dispatch one Build Auto
worker per unit, inspect the resulting evidence, and revise later work
when the parent spec or story list no longer fits what implementation revealed.
The orchestrating session remains responsible for keeping those revisions
consistent with the larger intent.
### Coordinate parallel epic streams
Project-level parallelism needs a higher coordination layer or separate epic
owners. Independent epic streams can run in parallel when dependencies and
integration boundaries are explicit. bmad-loop's ordered story scheduler does
not provide that project-level coordination.
## Context Inputs
On activation, the workflow resolves:
docs/reference/workflow-map.md
+49 -50
View File
@@ -1,26 +1,17 @@
---
title: "Workflow Map"
description: Visual reference for BMad Method workflow phases and outputs
title: 'Workflow Map'
description: Reference for BMad Method phases, workflows, and outputs.
sidebar:
order: 1
---
The BMad Method (BMM) is a module in the BMad Ecosystem, targeted at following the best practices of context engineering
and planning. AI agents work best with clear, structured context. The BMM system builds that context progressively
across 4 distinct phases - each phase, and multiple workflows optionally within each phase, produce documents that
inform the next, so agents always know what to build and why.
The BMad Method (BMM) organizes software delivery into four phases. Each phase
adds only the context the work needs, from optional discovery through planning,
solutioning, and implementation.
The rationale and concepts come from agile methodologies that have been used across the industry with great success as a
mental framework.
If at any time you are unsure what to do, the `bmad-help` skill will help you stay on track or know what to do next. You
can always refer to this for reference also - but `bmad-help` is fully interactive and much quicker if you have already
installed the BMad Method. Additionally, if you are using different modules that have extended the BMad Method or added
other complementary non-extension modules - `bmad-help` evolves to know all that is available to give you the best
in-the-moment advice.
Final important note: Every workflow below can be run directly with your tool of choice via skill or by loading an agent
first and using the entry from the agents menu.
Use [Choose a Development Path](../how-to/choose-a-development-path.md) to
decide how much of this map your change needs. Invoke the listed skills directly.
If you are unsure what to do next in an installed project, run `bmad-help`.
<iframe src="/workflow-map-diagram.html" title="BMad Method Workflow Map Diagram" width="100%" height="100%" style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
@@ -33,13 +24,13 @@ first and using the entry from the agents menu.
Explore the problem space and validate ideas before committing to planning. [**Learn what each tool does and when to use
it**](../explanation/analysis-phase.md).
| Workflow | Purpose | Produces |
|---------------------------------------------------------------------------|----------------------------------------------------------------------------|---------------------------|
| `bmad-brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorm.html` keepsake plus an optional `brainstorm-intent.md` |
| `bmad-forge-idea` | Pressure-test an idea until it hardens, proves out, or dies cheaply | `forge-report.html` every run; `forged-idea.md` when an idea hardens |
| `bmad-deep-recon` | Research any subject for a decision — draft a prompt for your deep-research tool, process its report, or run the research here; six typed packs, verified and cited | Research report or summary + optional HTML briefing |
| `bmad-product-brief` | Capture strategic vision — best when your concept is clear | `brief.md` + `addendum.md`, plus any desired HTML or presentation output |
| `bmad-prfaq` | Working Backwards — stress-test your product concept customer-first | `prfaq-{project}.md` |
| Workflow | Purpose | Produces |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| `bmad-brainstorming` | Brainstorm Project Ideas with guided facilitation of a brainstorming coach | `brainstorm.html` keepsake plus an optional `brainstorm-intent.md` |
| `bmad-forge-idea` | Pressure-test an idea until it hardens, proves out, or dies cheaply | `forge-report.html` every run; `forged-idea.md` when an idea hardens |
| `bmad-deep-recon` | Research any subject for a decision — draft a prompt for your deep-research tool, process its report, or run the research here; six typed packs, verified and cited | Research report or summary + optional HTML briefing |
| `bmad-product-brief` | Capture strategic vision — best when your concept is clear | `brief.md` + `addendum.md`, plus any desired HTML or presentation output |
| `bmad-prfaq` | Working Backwards — stress-test your product concept customer-first | `prfaq-{project}.md` |
For Deep Recon's three modes and how a research run works inside, see [Deep Recon](../explanation/deep-recon.md).
@@ -47,11 +38,11 @@ For Deep Recon's three modes and how a research run works inside, see [Deep Reco
Define what to build and for whom.
| Workflow | Purpose | Produces |
|-------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------|
| `bmad-prd` | Create, update, or validate a PRD — facilitated discovery, three intents in one skill | Create/Update: `prd.md`, `addendum.md`, `.memlog.md`; Validate: `validation-report.html` + `.md` |
| `bmad-ux` | Design user experience (when UX matters) — DESIGN.md (visual) + EXPERIENCE.md (behavioral) spine pair | `DESIGN.md`, `EXPERIENCE.md`, `.memlog.md` |
| `bmad-spec` | Distill any intent input (brief, PRD, transcript, brain dump, design folder) into a succinct SPEC.md contract + companions — locks the WHAT before the HOW | `SPEC.md` + companions under `{output_folder}/specs/spec-{slug}/`; optional `stories.yaml` |
| Workflow | Purpose | Produces |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `bmad-prd` | Create, update, or validate a PRD — facilitated discovery, three intents in one skill | Create/Update: `prd.md`, `addendum.md`, `.memlog.md`; Validate: `validation-report.html` + `.md` |
| `bmad-ux` | Design user experience (when UX matters) — DESIGN.md (visual) + EXPERIENCE.md (behavioral) spine pair | `DESIGN.md`, `EXPERIENCE.md`, `.memlog.md` |
| `bmad-spec` | Distill any intent input (brief, PRD, transcript, brain dump, design folder) into a succinct SPEC.md contract + companions — locks the WHAT before the HOW | `SPEC.md` + companions under `{output_folder}/specs/spec-{slug}/`; optional `stories.yaml` |
:::tip[Three intents in one skill]
`bmad-prd` handles the full PRD lifecycle. State your intent when invoking or the skill will ask:
@@ -59,10 +50,10 @@ Define what to build and for whom.
- **Create** — new PRD from scratch via coached discovery; produces `prd.md`, `addendum.md`, and `.memlog.md`
- **Update** — reconcile an existing PRD with a change signal, surfacing conflicts before applying changes
- **Validate** — critique a PRD against a configurable checklist and produce a structured HTML findings report
:::
:::
:::note[`bmad-spec`]
`bmad-spec` produces the canonical machine contract: a five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files, validated so every load-bearing source claim is preserved. It is the only writer of `SPEC.md`; other skills invoke it headless when they need to express or update intent. On request it can also break a spec into an ordered `stories.yaml` for autonomous dispatch — see [Autonomous Development Loops](./build-auto.md).
`bmad-spec` produces the canonical machine contract: a five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files, validated so every load-bearing source claim is preserved. It is the only writer of `SPEC.md`; other skills invoke it headless when they need to express or update intent. On request, Story Breakdown also creates the ordered `stories.yaml` used to implement an epic across several sessions. See [Choose a Development Path](../how-to/choose-a-development-path.md#4-start-epic-sized-work).
:::
:::tip[Upstream: `bmad-product-brief`]
@@ -73,38 +64,46 @@ Define what to build and for whom.
Decide how to build it and break work into stories.
| Workflow | Purpose | Produces |
|---------------------------------------|--------------------------------------------|-----------------------------|
| `bmad-architecture` | Make technical decisions explicit | `ARCHITECTURE-SPINE.md` is the spine by default but can hydrate to your desired output or presentation needs also |
| `bmad-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories |
| `bmad-sprint-planning` | Readiness gate before implementation, then story tracking and status view | PASS/CONCERNS/FAIL + `sprint-status.yaml` |
| Workflow | Purpose | Produces |
| ------------------------------- | ------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `bmad-architecture` | Make technical decisions explicit | `ARCHITECTURE-SPINE.md` is the spine by default but can hydrate to your desired output or presentation needs also |
| `bmad-create-epics-and-stories` | Break requirements into implementable work | Epic files with stories |
| `bmad-sprint-planning` | Readiness gate before implementation, then story tracking and status view | PASS/CONCERNS/FAIL + `sprint-status.yaml` |
For how the readiness gate, deterministic tracking, and status view work together, see [Sprint Planning](../explanation/sprint-planning.md).
## Phase 4: Implementation
Every implementation path converges on `bmad-build`. It accepts direct intent, an issue, a specification, or a planned story, then chooses the clarification, planning, implementation, and review depth needed for that input.
Implementation happens in session-sized units. `bmad-build` handles a unit
attentively; `bmad-build-auto` handles one unit unattended. Larger planning
paths create and preserve the context those units need.
| Workflow | Purpose | Produces |
|----------|---------|----------|
| `bmad-build` | Turn direct intent or a planned story into implemented, reviewed code | `spec-*.md` + code |
| `bmad-code-review` | Ad hoc review of any code change | Findings + applied patches |
| `bmad-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing |
| `bmad-retrospective` | Evidence-based review of a completed epic against its acceptance criteria | Retro document, action items, acceptance verdict |
| Workflow | Purpose | Produces |
| --------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------ |
| `bmad-build` | Implement and review one direct intent or planned story with human checkpoints | Implementation record + code |
| `bmad-build-auto` | Implement and review one unit unattended for a caller or orchestrator | Implementation record + code + terminal status |
| `bmad-code-review` | Ad hoc review of any code change | Findings + applied patches |
| `bmad-correct-course` | Handle significant mid-sprint changes | Updated plan or re-routing |
| `bmad-retrospective` | Evidence-based review of a completed epic against its acceptance criteria | Retro document, action items, acceptance verdict |
### Direct and Planned Entry
Clear work can enter `bmad-build` directly. Larger initiatives can first produce a PRD, UX design, architecture, epics, stories, readiness results, and sprint plan. Those artifacts add context; they do not select another implementation workflow.
Clear one-session work can enter `bmad-build` directly. A spec-backed epic uses
Story Breakdown to create several units under one `SPEC.md`. A multi-epic
project may add a PRD, UX, architecture, epics, readiness results, and sprint
tracking before selecting each unit.
`bmad-build-auto` can orchestrate unattended iterations of the same development model when autonomous execution is appropriate.
For the reference on unattended development loops with `bmad-build-auto`, see [Autonomous Development Loops](./build-auto.md).
Build Auto does not orchestrate those units. An AI coding session or another
orchestrator, such as bmad-loop, selects and dispatches one worker per unit. See
[Autonomous Development Loops](./build-auto.md) for the worker and orchestration
contracts.
## Context Management
Each document becomes context for the next phase. The PRD tells the architect what constraints matter. The architecture
tells the dev agent which patterns to follow. Spec files give focused, complete context for implementation. Without
this structure, agents make inconsistent decisions.
Each document becomes context for later decisions. The PRD records the product
requirements. The architecture records the patterns and boundaries that each
implementation unit must follow. Specs and story records preserve intent,
decisions, and completion state as work is divided and recombined.
### Project Context
docs/start/build-your-first-change.md
+5 -1
View File
@@ -12,7 +12,9 @@ repository, and run the installed `bmad-build` skill. Talk to it about the
change you want, and it will make it happen.
Otherwise, start here. You will make a working Python program in an empty
project.
project. This tutorial follows the
[one-session development path](../how-to/choose-a-development-path.md): one
coherent request goes directly to the `bmad-build` skill.
:::note[Before You Start]
Use a macOS or Linux shell with Node.js 20.12+, Python 3, and a coding tool
@@ -116,3 +118,5 @@ the program, and checked its work before showing you the result.
the `bmad-build` skill with a short description of a small change.
2. Continue to [Getting Deeper](../tutorials/getting-deeper.md) for a small change in a
mature codebase, followed by a larger change using a written spec.
3. Use [Choose a Development Path](../how-to/choose-a-development-path.md) when
your next change may need several implementation sessions or multiple epics.
docs/tutorials/getting-deeper.md
+22 -5
View File
@@ -7,7 +7,8 @@ sidebar:
You already know Build from small projects. Here, you will use it in a specific
version of Django: first for one bounded command change, then for three related
stories defined by one BMad Spec.
stories defined by one BMad Spec. The two exercises demonstrate the
[one-session and epic-sized development paths](../how-to/choose-a-development-path.md).
:::note[Prerequisites]
Use a macOS or Linux shell with Git, Node.js 20.12+ and `npx`,
@@ -166,7 +167,10 @@ Spec asks. Continue when they match the requirements above.
## 9. Build the Three Stories
Run Build once for each story, in order. Complete each Build run before moving
to the next one. Every run uses the same spec.
to the next one. Every run uses the same spec. You will run these stories
attentively because they establish how filtering, redaction, and exit behavior
fit together. Later epics with stable, repeated patterns may be better
candidates for automation.
### Story 1: Filters
@@ -243,8 +247,6 @@ The JSON contains only `SECRET_KEY`. Every current or default value exposed by
the JSON shape you chose earlier is `[REDACTED]`; neither original value
appears. The underlying values still differ, so the final line is `exit: 1`.
## 11. The Stories Work Together
The first exercise gave Build one bounded change directly. This exercise gave
three separate Build runs one spec. Filtering, redaction, and CI status still
work together at the end. You have extended a mature Django command, and the
@@ -253,7 +255,22 @@ final result still does what you asked for at the start.
If you want several perspectives on the result, `/bmad-party-mode` is an
optional final step. You do not need it to finish this tutorial.
## 11. Review the Epic
Run Retrospective against the spec folder:
```text
/bmad-retrospective _bmad-output/specs/spec-diffsettings-audit/
```
Retrospective treats `stories.yaml` as the epic inventory, reads each story's
implementation record, and checks the integrated result against `SPEC.md`. It
writes `RETROSPECTIVE.md` in the same spec folder. Review its evidence,
acceptance verdict, and any proposed follow-up work.
## 12. Keep Building
Now [install BMad in your own repository](../start/install-bmad.md), then use
the `bmad-build` skill to make a change you want.
the `bmad-build` skill to make a change you want. Use
[Choose a Development Path](../how-to/choose-a-development-path.md) to decide
when a change needs a spec, automation, or the full project flow.
website/public/workflow-map-diagram.html
+13 -6
View File
@@ -254,14 +254,21 @@
<div class="phase-title">Implementation</div>
</div>
<div class="workflows">
<div class="decision">Direct intent or planned context ↓</div>
<div class="decision">One session-sized unit from direct intent or planned context ↓</div>
<div class="workflow">
<div class="workflow-header">
<span class="workflow-name">build</span>
</div>
<div class="workflow-meta">
<div class="agent"><div class="agent-icon amelia">A</div><span class="agent-name">Amelia</span></div>
<span class="output">spec + code + review →</span>
<span class="output">attentive implementation + review →</span>
</div>
</div>
<div class="workflow">
<div class="workflow-header">
<span class="workflow-name">build-auto</span>
</div>
<div class="workflow-meta">
<span class="output">one unattended unit + status →</span>
</div>
</div>
<div class="workflow">
@@ -289,8 +296,7 @@
<span class="badge adhoc">per epic</span>
</div>
<div class="workflow-meta">
<div class="agent"><div class="agent-icon amelia">A</div><span class="agent-name">Amelia</span></div>
<span class="output">lessons</span>
<span class="output">epic evidence + verdict + lessons</span>
</div>
</div>
</div>
@@ -301,7 +307,8 @@
<div class="context-header">📚 Context Flow</div>
<p style="margin-bottom: 8px; color: var(--text-muted);">Available documents add context before implementation.</p>
<div class="context-items">
<span><code>build</code> <span>loads available intent, issue, spec, PRD, architecture, UX, epic, story, and sprint context</span></span>
<span><code>build</code> <span>handles one unit from direct intent or planned context; <code>build-auto</code> handles one unit unattended</span></span>
<span><code>spec + stories</code> <span>preserve the parent intent and carry decisions between implementation sessions</span></span>
<span><code>code-review</code> <span>adds independent validation when needed</span></span>
</div>
</div>