Brian
ee47e30cf6
* refactor(bmad-ux): replace bmad-create-ux-design with lean spine-based bmad-ux
* refactor(bmad-ux): adopt DESIGN.md spec, split into two-file spine, align prd/brief
DESIGN.md (visual identity per the Google Labs spec) and EXPERIENCE.md
(behavior, flow, IA) replace the single design.md spine. EXPERIENCE.md
cross-references DESIGN.md tokens via the spec's {path.to.token} syntax.
Example suite restructure
- 3 DESIGN.md examples: editorial (Stitch source / Linen & Logic), calm
native mobile (Quill), shadcn-on-Tailwind web SaaS (Drift)
- 2 paired EXPERIENCE.md examples (Quill, Drift); Linen & Logic unpaired
to model the Stitch handoff scenario
- Replaces the prior 2-example combined spine set
Discovery additions (outcome-driven, one line each)
- Source scan: glob {planning_artifacts}/ for candidates, parent never reads
- Form-factor: resolve before IA closes; journeys often derive it
- Surface closure: every stated need has a surface, every surface a journey
- Named-protagonist journeys (Mary, not "the user")
- Design handoff working mode (extensible producer registry, default: Stitch)
PRD and brief alignment with same insights
- bmad-prd: dropped standalone Primary Persona section from template;
renamed "Personas + Journeys" entry to "Journey-led"; named-protagonist
rule on UJs; form-factor probe; validation checklist updated
- bmad-product-brief: form-factor surfaced in Discovery topics
Quality scan fixes
- Added ## Overview heading; renamed ## Activation to ## On Activation
- Replaced ../ paths in example assets with {planning_artifacts}/
- Sources section compressed (abstract delta-only rule)
- Working mode aligned to "Fast path" / "Coaching path" BMad-wide convention
New
- references/design-md-spec.md: working summary of the spec for the LLM
- customize.toml: design_md_examples, experience_md_examples,
design_handoffs registries
- .prettierignore: ignore .analysis/ quality-scan artifacts repo-wide
* refactor(bmad-ux): activation parity with prd/brief, opt-in reviewer gate, no headline grade
- Restructure On Activation as numbered six-step list mirroring bmad-prd
and bmad-product-brief, restoring the explicit key-resolution list that
earlier crammed-paragraph form had dropped (planning_artifacts and
friends were silently unresolved at Create).
- Make Reviewer Gate opt-in and lens-selectable. At Finalize, ask before
spending tokens on parallel reviewer subagents; at Validate intent,
skip that question but still confirm lens picks. Stops the auto-run
WCAG audit on hobby-stakes work.
- Drop the overall validation grade. Per-category verdicts and severity
counts already say what is true; a single headline grade conflated
design rigor with release readiness and led "POOR" pills landing on
reports whose own bodies described the work as strong. Removed from
references/validate.md (ladder rule + markdown twin), HTML template
(grade pill div + CSS vars + classes).
- Trim creative-tools.md: drop the Custom entries section. Runtime
prompt files should only carry what the LLM needs to act in this
moment; how-to-extend-via-TOML is setup-time human documentation
already covered by customize.toml comments.
* fix(bmad-ux): align validation report template with 8-category rubric
Template placeholders referenced 'Decision-readiness' and 'seven dimensions'
from the prior rubric. Replace with TEMPLATE_CATEGORY_NAME and inline the
eight canonical categories from references/validate.md so the synthesis pass
names them verbatim.
* fix(validate-skills): remove stale WF-01/WF-02 rules
WF-01/WF-02 were originally scoped to workflow.md files (now mostly gone)
but had been generalized to flag name/description in any non-SKILL.md
markdown. That over-captured legitimate spec files — e.g. DESIGN.md
examples in bmad-ux/assets/ that carry name/description per the Google
Labs DESIGN.md spec.
Step files are already covered by STEP-06. Rule count: 14 → 12.
* fix(bmad-ux): address PR review followups
- validation-report-template.html: severity badge class is badge-sev-*,
not sev-* (the comment misled the synthesis pass).
- Sweep dangling bmad-create-ux-design references: module-help.csv,
bmad-agent-ux-designer/customize.toml, bmad-prd/SKILL.md handoff list,
workflow-map.md (en + 4 translations), getting-started.md (en + 4
translations). Workflow-map output column updated to DESIGN.md +
EXPERIENCE.md.
- references/validate.md: Markdown capitalized as a proper noun.
8.3 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 | brainstorming-report.md |
bmad-domain-research, bmad-market-research, bmad-technical-research |
Validate market, technical, or domain assumptions | Research findings |
bmad-product-brief |
Capture strategic vision — best when your concept is clear | product-brief.md |
bmad-prfaq |
Working Backwards — stress-test and forge your product concept | prfaq-{project}.md |
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, decision-log.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, .decision-log.md |
:::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, anddecision-log.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 :::
:::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-create-architecture |
Make technical decisions explicit | architecture.md with ADRs |
bmad-create-epics-and-stories |
Break requirements into implementable work | Epic files with stories |
bmad-check-implementation-readiness |
Gate check before implementation | PASS/CONCERNS/FAIL decision |
Phase 4: Implementation
Build it, one story at a time. Coming soon, full phase 4 automation!
| Workflow | Purpose | Produces |
|---|---|---|
bmad-sprint-planning |
Initialize tracking (once per project to sequence the dev cycle) | sprint-status.yaml |
bmad-create-story |
Prepare next story for implementation | story-[slug].md |
bmad-dev-story |
Implement the story | Working code + tests |
bmad-code-review |
Validate implementation quality | Approved or changes requested |
bmad-correct-course |
Handle significant mid-sprint changes | Updated plan or re-routing |
bmad-sprint-status |
Track sprint progress and story status | Sprint status update |
bmad-retrospective |
Review after epic completion | Lessons learned |
bmad-investigate |
Forensic case investigation with evidence-graded findings, calibrated to the input | {slug}-investigation.md |
Quick Flow (Parallel Track)
Skip phases 1-3 for small, well-understood work.
| Workflow | Purpose | Produces |
|---|---|---|
bmad-quick-dev |
Unified quick flow — clarify intent, plan, implement, review, and present | spec-*.md + code |
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. Story 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