Brian
57e70562e3
* Add bmad-project-context skill; husk document-project and generate-project-context - New bmad-project-context: one engine, three intents (ingest/query/audit) building a verified kernel + bundle context system; interactive default, auto/headless mode; works with a BMad install or standalone via bootstrap - context.py core runtime script (validate/index/map/sweep/resolve/compass/ sync/bootstrap/config) with 52 tests; config resolution delegates to the installed BMad resolver so script and session never disagree - bmad-document-project and bmad-generate-project-context reduced to 10-line deprecation shims forwarding to the new skill - Docs updated: project-context explanation/how-to rewritten, established projects guide + FAQ, agents references, workflow map; deprecation notes kept for old-name searches - module-help.csv single PC row; analyst menu DP -> PC - validate-file-refs: context.yaml is runtime-generated * refactor: remove map command from context.py — discovery is the model's job Real-repo testing showed map's descriptor pass grinding through large asset trees. Discovery is judgment work the model does better with its own tools; the script keeps only measurement, mutation, and resolution (validate/index/sweep/resolve/compass/sync/bootstrap/config). SKILL.md brownfield flow de-prescribed to outcome-driven wording; added a bounding-question rule for huge external sources. * feat: closing message when the harness may not load AGENTS.md 43+ harnesses make per-harness load verification impractical. Whenever AGENTS.md carries the kernel, the run now closes by telling the user: if your harness doesn't auto-load AGENTS.md, make the context file it does load pull this one in (e.g. a CLAUDE.md containing @AGENTS.md). Found in real-repo testing: the kernel sat unloaded under Claude Code until a CLAUDE.md pointer was hand-made. * docs: add The Theory of Project Context explanation Why the skill captures so little: the evidence against generated docs, the pruning test and what earns a place, the deliberate exclusions with their reasons, context-as-liability, and an honest comparison with the two replaced skills. * fix: address PR review findings - Force-add eval fixture files the repo gitignore silently dropped (pnpm-lock.yaml, _bmad/context.yaml, context/.memlog.md) - docs/reference/agents.md Analyst row: DP/Document Project -> PC/Project Context - context.py: cmd_index no longer crashes on an empty index.md (and allows overwriting one); inline # comments in frontmatter values are only stripped when preceded by whitespace (C#-style values survive); cache_lookup tolerates corrupt pointer files; pointer writes are atomic - triggers.json: positive trigger for the query intent
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]
Build your project context so AI agents follow your project's rules and preferences across all workflows: a small
always-loaded kernel plus a bundle of verified entries, maintained by bmad-project-context. Seed it from your
architecture at the end of planning, or mine it from an existing codebase at any time.
:::
How to create it:
- Run
bmad-project-context— greenfield (seeded from your spec or architecture) or brownfield (mined from the codebase, then confirmed with you). The earlierbmad-generate-project-contextis deprecated and forwards there; an existingproject-context.mdkeeps loading.