From f1400efe86566efac69624891984bd4796a6aa44 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Sun, 2 Aug 2026 22:46:52 -0700 Subject: [PATCH] docs: add development path diagrams --- docs/how-to/choose-a-development-path.md | 8 ++ docs/images/development-paths.svg | 98 ++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100644 docs/images/development-paths.svg diff --git a/docs/how-to/choose-a-development-path.md b/docs/how-to/choose-a-development-path.md index 4f348df01..286f6748a 100644 --- a/docs/how-to/choose-a-development-path.md +++ b/docs/how-to/choose-a-development-path.md @@ -8,6 +8,12 @@ sidebar: 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 @@ -43,6 +49,8 @@ change may need more structure than a much larger routine update. | 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. diff --git a/docs/images/development-paths.svg b/docs/images/development-paths.svg new file mode 100644 index 000000000..d0f0d6a0b --- /dev/null +++ b/docs/images/development-paths.svg @@ -0,0 +1,98 @@ + + 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 + + + +