Brian
47bab7d15c
* feat(project-context): rewrite as prescriptive AGENTS.md generator Replace the kernel+bundle context system with a single product: a short verified agent guide (AGENTS.md). A field trial of the first version showed repo scanning produces polished-but-useless factoids; the rewrite fills a fixed section plan from ranked evidence channels (executable config and CI, targeted git history, session logs, human interview) and uses the repository only to verify claims, never as the source of knowledge. - Intents: bootstrap, refresh, record (capture an observed agent mistake), audit; query is gone with the bundle - Per-fact entry files, trust frontmatter, index, placement machinery, and the skill's context.py mechanics script are removed; accountability moves to one plain ledger file recording every candidate claim and its disposition - Skill directory only; docs, forwarding husks, and shared scripts untouched * refactor(project-context): per-section admission rules, two-tier guide Revisions from two end-to-end trials plus review: - Replace the global non-derivable test with per-section admission rules: brevity (orientation), authority (policy), universal need verified by execution (commands, verification), wrong-default-assumption (conventions), localization value (pointers), observed failure only (pitfalls) - Two-tier output: AGENTS.md (orientation + policy + pointer) for every session, AGENTS-dev.md for coding sessions; single file when tiny - Pitfalls can never be nominated by scans: sources are recorded lessons, maintainer recall, session evidence, and the writing session's own caught mistakes; retirement only when the guarded thing is gone or the human says so, since a working rule erases its own evidence - Interview ergonomics: recall questions, never review lists; testimony the repo contradicts is surfaced with evidence, never written or dropped - Trial-driven fixes: guide-to-filesystem link check, mutating-command go-ahead as the interview's first question, plain-English rewrite throughout * fix(project-context): bidirectional coverage trace, history-evidenced pitfalls Round-3 trial findings: an unsourced pitfall entered the guide at composition time because coverage only checked ledger-to-guide; and repeat-fix git history, the strongest pitfall evidence observed, was not an explicitly admitted source. * refactor(project-context): move Where-things-are to AGENTS.md, imperative lines Where-things-are pointers serve planning sessions as much as coding ones, so they belong in the always-loaded file. Shape rules now require every line to state an action (bare facts only as justification clauses) and stable contract headings across runs. * docs(project-context): session-kind guides as a third structural axis A maintainer-named frequent session kind (UX, manual testing, data work) may earn its own AGENTS-<kind>.md behind a pointer; module-level differences stay with scoped guides. * refactor(project-context): action-gated dev-guide pointer, two-file example The AGENTS-dev.md hop is the most common progressive-discovery trigger, so it is now gated on the first hands-on action rather than session self-classification, names its payoff, and names the exemption. The contract's worked example shows the two-file form with the pointer in situ. Scoped-guide discovery no longer assumes harness nearest-file loading: the root-guide pointer is the mechanism. * refactor(project-context): adopt shared memlog, drop unearned claims The run record is now a standard memlog kept with the shared memlog.py script — append-only typed entries, latest entry wins — replacing the bespoke ledger format; stale-disposition notes become structurally impossible. Two appeal-to-measurement assertions cut: the operative admission and exclusion rules carry that load. * docs(project-context): guard handwritten guides The skill never commits — its output stays as working-tree changes for the user. Headless runs never rewrite a guide the memlog doesn't record writing; they leave an AGENTS.md.proposed for an interactive merge. * docs(project-context): fold in prior-art research findings Five adoptions from the generator prior-art survey: prohibitions name their permitted alternative; an emphasis-marker budget; a git-log --diff-filter=DR drift check on refresh; TODO placeholders over guessed greenfield commands; commit and branch conventions mined from history. * docs(project-context): route candidates to enforcement before prose Compose now asks, per accepted candidate, whether a hook, lint rule, or CI check enforces it better than a guide line; the line is the fallback and a landed check deletes it. * docs(project-context): narrow refresh interview and contradiction flagging Refresh interviews shrink to one recall question — what changed since the last run. Cross-file contradictions are flagged only when they change behavior; rewording and overlap are not contradictions. * refactor(project-context): conversational skill, no script, AGENTS.md block Refine the skill into an implementation-layer capability: a conversation that produces one small verified block inside the repo's AGENTS.md. The human is in the loop for every write; there is no autonomous mode. - Drop src/scripts/context.py and its tests. Nothing it did is needed once the output is a single spliced block rather than a bundle of files. - Replace guide-contract.md and evidence.md with best-practices.md (admission, exclusion, retirement, retrieval, maintenance) and template.md (section list plus a worked example, no placeholders). - Collapse the two-file AGENTS.md/AGENTS-dev.md split into one block. A pointer the agent must choose to follow gets skipped; anything load-bearing goes in the always-loaded file. - Replace per-section admission rules with one test: anything derivable from source is read live, never stored. Commands stated in package.json, a Makefile, or CI config no longer earn a line; their caveats do. - Ask up front whether a run covers the root only or named sub-projects, gated on observable evidence (a workspace manifest, per-directory build manifests). - Husk bmad-document-project and bmad-generate-project-context onto setup intent, and say plainly that the deeper system-explanation altitude is a separate capability rather than shipping a thin substitute. - Align module-help.csv, bmad-correct-course, the analyst menu, and the docs set with the block as the output. --------- Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
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]
Set up your repo so AI agents follow your project's rules across all workflows: a small verified block in
AGENTS.md, maintained by bmad-project-context. Seed it from your architecture at the end of planning, or
discover 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 (discovered from the codebase, verified, then confirmed with you). The earlierbmad-generate-project-contextis deprecated and forwards there; an existingproject-context.mdis offered up for absorption.