skills/bmad-code-org__bmad-method
1
0
Fork 0
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git synced 2026-09-19 08:11:52 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
project-context-v2
bmad-code-org__bmad-method/docs/reference/workflow-map.md
T
Brian 57e70562e3 feat: bmad-project-context skill — verified kernel + bundle context system (#2674) 
* 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
2026-08-02 23:41:34 -05:00

122 lines
9.0 KiB
Markdown
Raw Permalink Blame History

---
title: "Workflow Map"
description: Visual reference for BMad Method workflow phases 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 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.
<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>
<p style="font-size: 0.8rem; text-align: right; margin-top: -0.5rem; margin-bottom: 1rem;">
<a href="/workflow-map-diagram.html" target="_blank" rel="noopener noreferrer">Open diagram in new tab ↗</a>
</p>
## 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**](../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` |
For Deep Recon's three modes and how a research run works inside, see [Deep Recon](../explanation/deep-recon.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`, `.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](./build-auto.md).
:::
:::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](../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.
| 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](./build-auto.md).
## 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 earlier `bmad-generate-project-context` is deprecated and forwards there; an existing `project-context.md` keeps loading.
[**Learn more about project-context.md**](../explanation/project-context.md)
Reference in New Issue View Git Blame Copy Permalink