Brian
cf54f4d76d
* refactor(bmm): move sprint-planning and sprint-status to plan/ They sit at the plan/ship boundary and their outputs are planning artifacts of the dev cycle; next commit makes sprint-planning the readiness gate, which is plan-side work. * refactor(bmm): fold readiness gate into sprint-planning, retire check-implementation-readiness The old skill was 1,154 lines of legacy numbered-step ceremony whose document discovery hardcoded filename globs (*prd*, *ux*, *epic*) that miss what current skills produce (SPEC.md, DESIGN.md) and still treated retired sharded docs as first-class. Sprint-planning now opens with a lean readiness gate: generic artifact discovery by content, forward/back traceability, PASS/CONCERNS/FAIL, stop on FAIL with findings. The IR trigger on John's and Winston's menus dispatches sprint-planning, so 'check implementation readiness' still works everywhere it used to. * refactor(bmm): modernize sprint-planning with deterministic script core SKILL.md drops the legacy XML step dialect for the product-brief style (~100 lines, uv run, headless contract). New scripts/sprint_plan.py owns the mechanical work — epic parsing, key derivation, ordering, preserve- never-downgrade merge, story-file detection, action_items carry-over, atomic writes, drift checks — with 11 tests wired in as test:sprint-planning. Judgment stays with the LLM: epic discovery, the readiness gate, and reconciling script-reported orphans and unparsed headings. checklist.md retired (the script performs that checklist); sprint-status-template.yaml is the single source for the status vocabulary. Output stays byte-compatible with build's sprint sync and retrospective's tooling. * refactor(bmm): fold sprint-status into sprint-planning's status view sprint_plan.py gains a status subcommand: counts (legacy values mapped), risk flags, open action items, and a priority-ordered next-action recommendation — the old skill's inference-driven summary, computed deterministically and covered by 9 new tests. bmad-sprint-status becomes a v6-shims husk that forwards with status-view intent and a deprecation notice; its dead data/validate modes had zero callers and are gone. If a hand-edited status file defeats the script, the skill falls back to reading it directly and summarizing by best judgment. New explanation page docs/explanation/sprint-planning.md covers the consolidated skill; workflow maps and references updated across all languages. * docs: changelog entries for skill reorg and sprint consolidation * fix(bmm): harden sprint_plan.py per review; add validate/fix intents with full progressive disclosure Review fixes (PR #2659 findings, bot + internal review): - Normalize legacy v6 statuses (drafted/contexted) on every read — merged by meaning and reported, never treated as illegal or reset - dropped_orphans carry their old status; transplant renames via --set - project_key/tracking_system/story_location preserved from the existing file unless overridden; refresh round-trips custom keys and user comments - Hardened write path: dump-to-bytes, fsync, permission-preserving atomic write inside the guarded block, explicit checks (no asserts), atomic restore - JSON-only argparse (errors and -h emit JSON); unicode-aware slugs with hash fallback; fenced code blocks ignored when parsing epics - Odd retro keys, date-typed stamps, and non-mapping YAML report cleanly instead of crashing; unparseable timestamps warn instead of silently disabling the staleness check; malformed action items flagged, not dropped - Dead check subcommand removed; generate --dry-run reports drift/in_sync - test:sprint-planning wired into quality and CI (was test-only) - Retro tests use a vendored template fixture (PATH-05); repo-level test-template-sync.js keeps it byte-identical to the source; template example timestamps and story_location fixed; header block pinned to the template by test New capability: - validate subcommand + reference: structural validation, never writes - fix flow: evidence-gathering subagents -> user-confirmed state table -> generate --fresh --set writes a pristine file (the one path allowed to downgrade); universal script-failure fallback to inference for every intent - SKILL.md is now a lean router: gate, tracking, status, fix, and validate each load as progressive-disclosure references Docs: explanation page gains Repair section; workflow-map and getting-started across all five languages mention the status view; headless payload nests under 'report' to avoid the status key collision; changelog updated. Test suite grows 20 -> 37; retro suite 91/91; docs build and validators green. * docs: mention repair in sprint-planning explanation description
9.0 KiB
title, description, sidebar
| title | description | sidebar | ||
|---|---|---|---|---|
| Workflow Map | Visual reference for BMad Method workflow phases and outputs |
|
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 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.
Phase 1: Analysis (Optional)
Explore the problem space and validate ideas before committing to planning. Learn what each tool does and when to use it.
| 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.
Phase 2: Planning
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 |
:::tip[Three intents in one skill]
bmad-prd handles the full PRD lifecycle. State your intent when invoking or the skill will ask:
- 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.
:::
:::tip[Upstream: bmad-product-brief]
bmad-product-brief (Phase 1) produces a product-brief.md that bmad-prd can source-extract during Discovery, reducing re-explanation and keeping the two documents aligned. Neither skill requires the other — start with bmad-prd directly if you already know what you're building.
:::
Phase 3: Solutioning
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 |
For how the readiness gate, deterministic tracking, and status view work together, see Sprint Planning.
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.
| 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 |
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.
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.
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.
Project Context
:::tip[Recommended]
Create project-context.md to ensure AI agents follow your project's rules and preferences. This file works like a
constitution for your project — it guides implementation decisions across all workflows. This optional file can be
generated at the end of Architecture Creation, or in an existing project it can be generated also to capture whats
important to keep aligned with current conventions.
:::
How to create it:
- Manually — Create
_bmad-output/project-context.mdwith your technology stack and implementation rules - Generate it — Run
bmad-generate-project-contextto auto-generate from your architecture or codebase