With shallow clones (--depth 1), `origin/HEAD` becomes stale after the
initial clone. The update path used `git reset --hard origin/HEAD` which
never picked up new commits pushed to the default branch.
Resolve the default branch name via `git symbolic-ref refs/remotes/origin/HEAD`,
then fetch and reset against `origin/<branch>` explicitly. Falls back to
`main` if origin/HEAD is not set.
Co-authored-by: Brian <bmadcode@gmail.com>
loadExistingConfig only read from legacy _bmad/<module>/config.yaml files, but
the installer writes user-scoped answers (user_name, communication_language, etc.)
to _bmad/config.user.toml. On every subsequent reinstall those values were not
loaded back, so the user got re-prompted instead of seeing their prior answers as
defaults.
Adds parseCentralToml — a lightweight line scanner matching the installer's own
TOML output format — and updates loadExistingConfig to read config.toml and
config.user.toml first (merging both into the same section buckets). Legacy
per-module config.yaml files are kept as a fallback for pre-v6 installations.
Co-authored-by: RobertOcsko <robert.ocsko@;seon.io>
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* fix(installer): refresh custom-source cache on quick-update and persist channel marker
* fix(installer): persist real next ref and atomically dedupe custom refresh
* fix(installer): preserve custom-source cache when remote unreachable
When git fetch fails against an existing custom-module cache, cloneRepo
previously wiped the cache and attempted a fresh clone, which then also
failed for the same reason (network down, repo deleted/moved, auth
revoked) — leaving the user with no usable cache. With the new
quick-update refresh path calling cloneRepo for every cached custom
module, this turned transient remote outages into cache loss on every
quick-update.
- cloneRepo: on fetch failure with an existing cache, keep the previous
clone and surface a warning via prompts.log.warn instead of removing
the cache. The downstream metadata write uses the existing HEAD.
- _refreshRepoCacheOnce: update the comment to reflect that the common
"remote unreachable but cache exists" case is now handled inside
cloneRepo; warn on the remaining unrecoverable failures so they
aren't silent.
Tests: 349 passed, 0 failed.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
Make bmadcode.com/web-bundles/ the single supported install path. The
site keeps install steps current as Gemini and ChatGPT evolve, always
points at the newest tagged release, and turns one signup into the
notification channel for new bundles.
- README.md: drop direct-folder install reference, point to the site
- web-bundles/README.md: lead with Install (site), reframe folder as
source for the shelf rather than install target
- docs/explanation/web-bundles.md: replace the per-bundle INSTRUCTIONS.md
steer with the site, replace the dead how-to link
- docs/how-to/use-web-bundles.md: rewrite as a short pointer to the site
(kept the file so existing inbound links resolve), retain prerequisites,
persona customization, and build-your-own sections
* feat(web-bundles): add release packager + bundle manifest
Adds the infrastructure for shipping web bundles as downloadable ZIPs
attached to a GitHub Release, consumed by the upcoming
bmadcode.com/web-bundles/ page.
- web-bundles/bundles.json — manifest with persona, tagline, description,
accent color, motif key, knowledge files, and feature flags
(web-browsing, deep-research, stitch integration) for each of the 6
bundles. Top-level releaseTag and downloadUrlPattern so the
consuming page can construct download URLs without hardcoding.
- tools/bundle-web-bundles.js — packager that zips each bundle dir into
dist/web-bundles/{slug}.zip and prints the gh release create command.
Zero dependencies; uses system zip.
- .gitignore — exclude dist/web-bundles/ build artifacts.
The web-bundles-v1.0.0 release on GitHub is currently in draft state
with the 6 zips attached; it'll be published in coordination with the
Ghost site page going live.
* fix(web-bundles): single-source release tag, sharper bundle copy
- Remove downloadUrlPattern from bundles.json — the consuming page
derives the URL from releaseTag, so version bumps now touch one
field instead of two.
- product-brief-coach: drop "one-page" (briefs are whatever length
the product earns).
- brainstorming-coach: real numbers — 60 techniques across 10
categories — with concrete examples (SCAMPER, Drunk History
Retelling, Nature's Solutions, Six Thinking Hats, etc.) so the
card actually communicates the surprising breadth.
* fix(web-bundles): harden release script per PR review
- Verify the zip CLI is on PATH up front with a clear install
hint, instead of crashing mid-zip with an opaque execSync error.
- Wrap JSON.parse in try/catch; validate the manifest shape (bundles
array non-empty, releaseTag present, slug present per entry) before
trying to package, so config errors fail with a targeted message.
- Catch zip failures per-bundle and surface the failing slug.
- Refuse to print the gh release command when zero bundles were
packaged (would otherwise mislead the user into creating an empty
release).
- Derive --title from manifest.releaseTag so the printed command can
never drift from the actual tag (was previously hardcoded
"Web Bundles v1" while the tag had moved to v1.0.0).
- Remove the stale `web-bundles-v1` example from the file header.
Addresses augmentcode bot review comments on PR #2424.
* docs(web-bundles): rewrite copy to actually sell what each bundle does
The JSON drives the bmadcode.com/web-bundles/ page; previous copy
was generic and undersold the actual capabilities. Rewrote each
tagline + description to lead with concrete, differentiating facts
pulled directly from each bundle's SKILL.md:
- Brainstorming Coach: 60 techniques across 10 categories with
specific names (SCAMPER, Drunk History Retelling, Nature's
Solutions, Shadow Work Mining, Superposition Collapse); calls
out the 4 routes (browse, recommend, random, progressive) and
the ~100-idea quantity-unlocks-quality target.
- Product Brief Coach: names the three intent modes (Create /
Update / Validate) and the two working paths (Fast / Coaching);
surfaces the [ASSUMPTION] tag system and the Addendum.
- PRFAQ Coach: details the 4 stages (Ignition / Press Release /
Customer FAQ / Internal FAQ + Verdict), the 9 press release
sections, the weasel-word list ("best-in-class", "seamless"),
and that it adapts for commercial, internal, OSS, community.
- PRD Coach: spells out the two entry points (Vision+Features
vs Journey-led), named-protagonist journeys, glossary
discipline, stable ID system (FR-1..N, SM-C1..N), and the
7-dimension validation rubric.
- UX Coach: leads with the two-spine contract (DESIGN.md +
EXPERIENCE.md), Don Norman framing, named-protagonist
journeys, surface closure as the test, and Stitch integration.
- Market & Industry Research: leads with Deep Research as the
engine, names Porter and Christensen as anchors, lists the 6
deliverable sections, and frames the deliverable as synthesis
not a research dump.
* fix(web-bundles): security hardening + strict bundle validation
Two issues raised by coderabbit on the latest commit:
1. Shell injection surface: execSync was building the zip command
with a template literal that interpolated bundle.slug from JSON.
Even with our controlled inputs, a slug with shell metacharacters
would break quoting. Switched to execFileSync with an argument
array (no shell) and added a strict ^[a-z0-9][a-z0-9-]*$ slug
regex enforced before any FS or zip call.
2. Missing bundle directories were [SKIP]-warned but the script
still printed the release command, allowing an incomplete release
to ship cleanly. Now treated as fatal: any missing or invalid slug
blocks the printed gh command and exits non-zero with the offending
slugs listed.
* feat(docs): add sidebar order validator
Adds tools/validate-sidebar-order.js to validate sidebar.order values
in YAML frontmatter across English and translated docs.
Checks for duplicate orders, gaps in sequence, and missing order fields.
For translations, also warns on order drift from English counterparts.
Wired into the quality script as docs:validate-sidebar.
* fix(validate-sidebar): tighten language detection and drift guard, add docstrings
* fix(validate-sidebar): replace subdirectory heuristic with locale pattern matching
detectLanguageDirs() previously classified any top-level docs/ directory
containing subdirectories as a translation language. This was too broad —
if an English section ever gained nested subfolders it would be silently
excluded from validation.
Replaced with a BCP 47 locale-code regex (/^[a-z]{2}(?:-[a-zA-Z]{2})?$/)
that matches known patterns (cs, fr, vi-vn, zh-cn) and won't falsely
classify content sections like explanation/ or reference/.
* fix(validate-sidebar): guard drift check against undefined order values
extractSidebarOrder() returns { hasSidebar: false } when no sidebar block
exists, leaving order as undefined rather than null. The drift check only
guarded against null, allowing undefined values to emit noisy warnings
like "Order drift: ... order undefined".
Changed the guard to typeof === 'number' which correctly excludes both
undefined and null without relying on a specific sentinel value.
* chore(validate-sidebar): add JSDoc docstrings to all functions
Adds @param and @returns annotations to extractSidebarOrder,
detectLanguageDirs, getEnglishSections, checkDirectory,
checkTranslationDrift, and relativePath.
* fix(validate-sidebar): add to pre-commit hook
* refactor(validate-sidebar): harden parsing and edge-case handling
Refactor to main() wrapper with pure return-based APIs, single directory
scan, and shared reporting. Harden frontmatter parsing (anchored delimiter,
direct-child-only order extraction, flow mapping support) and validation
(Infinity/zero guard, gap flood cap, multi-segment locales, graceful ENOENT).
* docs: fix sidebar.order duplicates and gaps across all locales
Resolves all validator errors flagged by the new
tools/validate-sidebar-order.js check.
English (docs/{explanation,how-to,reference}/):
- Renumbered to remove duplicates; established reading order
for new explanation pages added since orders were last set.
Translations (cs, fr, vi-vn, zh-cn):
- Mirrored English structural ordering where files exist, then
compacted to 1..N within each directory to eliminate gaps
caused by missing translation files.
Non-blocking drift warnings remain where translation directories
have fewer files than English; these are expected per the
validator's design.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
* fix(skills): strengthen activation guardrails for all workflow skills
Add explicit "Activation is complete" boundary markers that require
confirming activation_steps_prepend and activation_steps_append were
fully executed before beginning the main workflow.
Previously, the guardrail was either missing (bmad-product-brief,
bmad-prd, bmad-investigate) or too weak ("Begin the workflow below").
LLM agents would short-circuit complex activation sequences (INCLUDE →
READ → RUN → CHECK → FILTER → CD) by guessing variables instead of
executing steps in order, causing append steps and on_complete hooks
to be silently skipped.
The new guardrail explicitly names both prepend and append steps,
requiring confirmation before proceeding. This prevents agents from
starting the main workflow in parallel with activation.
23 skills updated: bmad-product-brief, bmad-prd, bmad-prfaq,
bmad-investigate, bmad-create-story, bmad-dev-story,
bmad-quick-dev, bmad-code-review, bmad-correct-course,
bmad-sprint-planning, bmad-sprint-status, bmad-retrospective,
bmad-qa-generate-e2e-tests, bmad-checkpoint-preview,
bmad-check-implementation-readiness, bmad-create-architecture,
bmad-create-epics-and-stories, bmad-generate-project-context,
bmad-create-ux-design, bmad-document-project, bmad-market-research,
bmad-technical-research, bmad-domain-research.
* fix(skills): extend activation gate to agent + new skills, refine placement
- bmad-product-brief / bmad-prd: pull activation_steps_append out of
the numbered list so the sentinel reads as a paragraph break, not
as the next list item.
- bmad-investigate: move the sentinel above Step 7 (routing) — Step 7
is workflow routing, not activation; the gate must fire first.
- bmad-agent-{analyst,tech-writer,pm,ux-designer,architect,dev}: add
the same gate between Step 7 (append) and Step 8 (menu dispatch).
Persona skills had the same short-circuit risk but no sentinel.
- bmad-ux, bmad-spec: new skills introduced on main after this branch
forked; apply the same gate so the pattern stays consistent.
- removals.txt: register bmad-create-ux-design as renamed to bmad-ux.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
- Drop "one-click install" framing in README and explanation page; setup is
multi-step but consistent across the shelf.
- Drop "two files (sometimes three)" claim; honestly name SKILL.md,
INSTRUCTIONS.md, and any required data files (templates, CSVs,
validation checklists).
- Add explicit setup pattern in README (create Gem/GPT, upload knowledge,
paste instructions, save).
- Add "Updating and customizing" section to the explanation page covering
re-upload-the-attachments updates and the rule of thumb that custom
changes belong in the pasted instructions block, not the knowledge
files, so future updates don't clobber team customizations.
* feat(web-bundles): bring back V4 web bundles for V6
Restores the V4 web bundle pattern for V6. BMad planning skills are
repackaged as one-click installs for Google Gemini Gems and ChatGPT
Custom GPTs, so users can run analysis and planning conversations in
flat-rate web LLM subscriptions instead of metered IDE tokens.
Current shelf (6 bundles): brainstorming, product brief, PRFAQ, PRD,
UX, market and industry research. Each bundle ships a SKILL.md
protocol, an INSTRUCTIONS.md with a default persona and a contrasting
swap example, and any required data files.
New in this commit:
- Market & Industry Research bundle merging market and domain research
with Porter and Christensen anchors, Mary persona inherited from the
BMad analyst agent, Geoffrey Moore swap example, Deep Research mode
integrated as the default research path
- web-bundles/README.md folder index listing all 6 bundles
- README.md section announcing the V6 web bundle shelf
- docs/explanation/web-bundles.md concept page (what, why, when)
- docs/how-to/use-web-bundles.md install steps for Gemini Gems and
ChatGPT Custom GPTs
* docs(web-bundles): unindent admonition closer in use-web-bundles.md
The :::note[Prerequisites] closer was indented under the last bullet,
which can prevent the admonition from closing and break Starlight
rendering for the rest of the page. Flush left now.
The forensic investigation feature (commit 380590aa) added the IN menu
trigger and bmad-investigate skill, but several docs that enumerate
triggers and agent capabilities were not updated.
- agents.md: add IN trigger and Forensic Investigation to Amelia's row
- named-agents.md: add forensic investigation to Amelia's capabilities
Co-authored-by: Brian <bmadcode@gmail.com>
* feat(bmad-spec): add Spec kernel distiller skill
New 2-plan-workflows skill that distills any intent input (brain dump,
PRD, transcript, brief) into a spec.md carrying the five-field kernel:
Problem, Capabilities, Constraints, Non-goals, Success signal. Headless
callers receive JSON; interactive runs close conversationally with the
spec path and gap-coverage invitations.
Includes:
- SKILL.md with activation contract and conventions
- customize.toml exposing template path, output path, run-folder pattern
- assets/spec-template.md (five-field skeleton)
- assets/headless-schemas.md (JSON IO contracts)
* remove brain-dump fallback config from bmad-spec customize.toml
* refactor(bmad-spec): companions+sources model, routing tilt, flat output path
- Collapse `related:` into `companions:`; companion paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill), distinguished implicitly by path
- `sources:` reserved for fully-absorbed inputs; downstream does NOT read these
- Soften mutation contract: bmad-spec owns SPEC.md and spec-authored companions; adopted companions belong to their originating skill
- Add "when to spawn a companion" tilt: multi-item catalogs, tables, diagrams (always), editorial voice rules; sub-bullets in a kernel field signal it has outgrown the kernel
- Fix Spec Law rule 7 and Pass 2: load-bearing content lands in SPEC.md or a companion, not the decision log (the log records wrapper-drops only)
- Flatten output path to `{planning_artifacts}/specs/spec-{slug}-{date}/`, mirroring `prds/` and `ux-designs/`; drop `spec_folder_name` (no longer used)
- Extract Load-bearing definition into its own section above Spec Law
* chore(core): retire bmad-distillator, promote bmad-spec to core
- Delete bmad-distillator/ and all registry + doc references (superseded by bmad-spec; no skill or workflow in any BMad module invoked it)
- Add bmad-distillator to removals.txt so installer cleans it from existing IDE skill directories on update
- Move bmad-spec from bmm-skills/2-plan-workflows/ to core-skills/ (universal scope: game design, research hypotheses, editorial briefs, policy, business plans, not just software)
- Register bmad-spec in core module-help.csv and bmad-pro-skills marketplace plugin
- Drop bmad-distillator section from core-tools.md (en, vi-vn, cs, fr, zh-cn) and vi-vn dev guide; renumber subsequent sections
* refactor(bmad-spec): add lean-prose discipline + generalize help text
- Add Spec Law rule 8: lean prose. Every sentence carries load-bearing content; cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and decision log.
- Update Self-Validate Pass 1 to enforce rules 1-6 and 8 (rule 7 stays in Pass 2)
- Prime the operation up-front: write lean from the first pass, every sentence must earn its place
- Note in Companions section that companions follow the same lean discipline
- Generalize core module-help.csv entry: domain-agnostic framing (software, game design, research, editorial, policy, business, anything intent-bearing); call out succinct, no-fluff and "locks the WHAT before the HOW" as the value props
* fix(bmad-spec): address PR review findings (CodeRabbit + Augment)
- headless-schemas.md: rewrite spec_path examples to point at the spec folder (not a file), rename source_artifact to sources[] array, add companions[] array, update verdict from "six rules" to "eight rules", disambiguate reason requirement (only when status=blocked)
- SKILL.md activation: fix config path from {project-root}/_bmad/config.yaml to {project-root}/_bmad/core/config.yaml (matches other BMM skills)
- customize.toml + SKILL.md Workspace: drop {date} from default run_folder_pattern (spec-{slug}); same slug = same folder = trivial in-place update, no glob-and-pick-most-recent needed. Override available for users who want dated history.
- spec-template.md: rename "## Success signals" (plural) to "## Success signal" (singular) to match SKILL.md kernel naming
- SKILL.md Frontmatter conventions: fix adopted-companion example path from _bmad-output/ux-designs/foo-ux/DESIGN.md to ../../ux-designs/ux-foo-bar-2026-05-23/DESIGN.md (matches actual flat-output convention)
- SKILL.md Spec Law: fix double-period typo in rule 2 ((stack, conventions)..)
- SKILL.md Overview: fix awkward "bloat with expansive line item details the kernel" phrasing; drop software-flavored downstream consumer list since bmad-spec is now a core skill serving any domain
* fix(bmad-spec): drop {planning_artifacts} dependency; output to {output_folder}/specs
bmad-spec is a core skill but its default path used {planning_artifacts}, a bmm-module variable. Core-only installs (no bmm) would fail at activation when the resolver tried to expand the path.
Land specs directly under {output_folder}/specs/spec-{slug}/ instead. Works in any install regardless of installed modules, and aligns with the long-term BMad direction of grouping artifacts as siblings under {output_folder}/<type>/ rather than nested under planning vs implementation parents.
In bmm installs, adopted-companion paths from spec to UX/PRD pick up one extra .. (e.g., ../planning-artifacts/ux-designs/<run>/DESIGN.md) since the spec folder is now one level up from planning-artifacts. Examples in SKILL.md and headless-schemas.md updated. module-help.csv output-location updated and stale -{date} fragment removed.
* docs(bmad-spec): add reference docs, trim headless schema, tighten defaults
- Add full bmad-spec entry to docs/reference/core-tools.md and table-row
stubs to cs/fr/vi-vn/zh-cn (full translation pending).
- Strip headless-schemas.md to a minimal {status, files} success response
and {status, error_code, reason} blocked response. Drop spec_path,
capabilities, verdict, decision_log_path — all derivable from the files
themselves.
- Narrow customize.toml persistent_facts default from recursive glob to
single {project-root}/project-context.md; document override path.
- Drop unused {doc_workspace} convention line from SKILL.md.
- Clarify Self-Validate verdict handling for interactive vs headless.
- Document missing_slug error code in SKILL.md + headless schema.
* 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.
Documents the fix landed in #2391 and the manual step required for users
who installed the experimental BMad Automator module under its previous
`baut` code.
* fix(installer): preserve stale installed modules on update
* test: drop stale baut regression case
* fix(installer): preserve source-backed modules and configs
* fix(installer): retain preserved module config in quick update
* fix(installer): preserve module config blocks for retained modules
* fix(installer): preserve user-scope blocks for retained modules
* fix(installer): retain stale modules during updates
* feat(installer): bundle module registry, retire marketplace, refresh display names
Prepares v6.7.0 for release:
- Moves bundled module list from tools/installer/modules/registry-fallback.yaml
to bmad-modules.yaml at repo root; renames to reflect single-source-of-truth role.
- Retires the remote marketplace registry fetch in ExternalModuleManager; the
installer now reads the bundled YAML only.
- Adds WDS (Whiteport Design Studio) entry alongside BMM, BMB, BMA, CIS, GDS, TEA.
- Refreshes display names and descriptions on every bundled module; TEA
repositioned after BMM in the picker.
- Adds plugin_name override field on registry entries so modules whose
marketplace.json declares a plugin under a different name than the installer
code (e.g. WDS uses bmad-wds) match without falling back to the single-plugin
heuristic.
- Removes the community modules picker from the interactive installer; previously
installed community modules are preserved on update and can still be installed
via --custom-source.
- Renames the custom-source confirm prompt for clarity.
CHANGELOG.md updated with the full v6.7.0 entry.
* feat(installer): fully retire community catalog plumbing
Removes the last marketplace network connections from the installer.
The v6.7.0 first pass retired the official-registry fetch but left
CommunityModuleManager + RegistryClient in place, which still
fetched community-index.yaml and categories.yaml on every install
to support the channel-gate and update flows.
This commit:
- Deletes tools/installer/modules/community-manager.js and
registry-client.js entirely.
- Strips CommunityModuleManager calls from ui.js (channel gate +
update channels), core/manifest.js (getModuleVersionInfo),
core/installer.js (resolution + installed-modules listing), and
modules/official-modules.js (findModuleSource fallback +
pre-install plugin resolution + post-install manifest entry).
- Simplifies installFromResolution: community branch removed; all
non-external installs are now treated as custom-source.
- Removes corresponding test suites (CommunityModuleManager unit
tests and the entire RegistryClient suite).
- Updates CHANGELOG with the migration note.
After this commit, grep confirms zero references to the bmad-plugins-
marketplace registry from the installer. The only remaining 'marketplace'
references are about per-repo .claude-plugin/marketplace.json files,
which the installer reads from cloned custom-source repos.
* feat(bmad-prd): voice rules, probing reference, and operational hardening
- Session Posture section (voice prohibitions, record-as-you-go, anti-caving, register-matching)
- New references/probing.md: seven probing categories, six critical assumptions, PRD/solution-design boundary
- Intent detection signals (create/update/validate) on activation step 6
- Update intent: inline conflict-detection procedure against decision-log.md
- Activation step 1 falls back to customize.toml instead of halting on resolver failure
- Restructure Discovery into five sub-sections (Posture, Brain dump, Four-dimension read, Right-skill check, Working mode)
- Regroup PRD Discipline into three clusters (Artifact shape, Substance, Honesty about scope)
- Define phase-blockers in Finalize step 4
- Em-dash strip in prose; preserve [v2 — out of MVP] callout convention
- Move bmad-party-mode / bmad-advanced-elicitation mention into the greeting step
* feat(bmad-prd): funnel discipline, UJ depth, and UX reframing
Template discipline for downstream AI extraction:
- §3 Glossary: exact-use enforcement (FRs, UJs, SMs use Glossary terms verbatim)
- §4 Features: FRs now use "#### FR-N: Name" heading with Realizes UJ-X cross-reference, testable consequences, and optional per-FR Out of Scope
- §7 Success Metrics: SM-N / SM-CN numbering with Validates FR-X cross-reference
User journeys:
- §2.4 UJ format expanded from one-liner to named-persona mini-flow (persona, 3-5 steps, edge cases, optional capability surfacing); hobby can collapse to one-liners
- Strip "job of UX" / "not this PRD" gatekeeping from template; depth is the team's call
- Strengthen UX-as-input / UX-as-output patterns for bidirectional PRD <-> UX flow
- SKILL.md Discovery Posture: push for two to three named-persona UJs in non-trivial scope
Validation checklist:
- Q-3 Traceability tightened to require Realizes UJ-X on FRs and Validates FR-X on SMs
- Q-7 (new): FR testability — every FR has at least one testable consequence
- S-1 Glossary integrity: now covers FR descriptions, consequences, UJ flows, SM definitions
- S-2: SM added to ID continuity scope
- S-5 (new): UJ persona linkage — every UJ names a persona by exact §2 label
- STK-2 (new): UJ density gate — non-hobby scope needs at least two UJs
* docs(bmad-prd): anonymize validation-findings JSON example
Replace project-specific values (Plantsona prd_name, frozen timestamp, §16 location, premium-conversion finding) with generic placeholder content. Swap the example finding to demonstrate Q-7 FR testability so it doubles as a primer on the new checklist item.
* feat(bmad-prd): reviewer pass redesign and consolidate facilitation
- finalize_reviewers TOML field replaces inline review lenses; entries
follow the skill:/file:/plain-text prefix convention, resolved on-demand
so reviewer data has zero context cost on runs that skip the pass.
- Subagent contract: reviewers write to {doc_workspace}/review-{slug}.md
and return summary-only (verdict, top findings, file path); parent
never holds full review text.
- Section-by-section walk-through UX at Finalize and Validate; user
decides per finding whether to autofix, discuss, defer, or ignore.
- Finalize entry names the sequence in one sentence so users understand
the polish-last order.
- Template philosophy moved from prd-template.md to SKILL.md PRD
Discipline; template is now pure shape menu (preamble and Notes for
facilitator stripped).
- facilitation-guide.md content folded into SKILL.md Discovery posture
(story-shape UJ walk, four MVP types, state-inference-don't-quiz);
guide file deleted.
* feat(bmad-prd): tighten SKILL.md, extract Reviewer Gate and Validate playbook
- SKILL.md: trim activation/posture/discovery bloat; sharpen Right-skill
check; extract Reviewer Gate to its own section (dedup with Finalize
step 3 and Validate intent).
- references/validate.md: rename from validation-render.md and expand to
the full Validate intent playbook (orient, run gate, structural
validator pipeline, render, close).
- references/probing.md: drop stale facilitation-guide.md reference.
- assets/prd-template.md: redesign §2.4 User Journeys with named-scene
default shape, worked example, and scope dial.
* fix(bmad-prd): make Brain dump a hard first-move rule
Discovery was being skipped: the LLM treated the user's opening
message as the full picture and jumped to multiple-choice intake.
Strengthen the ordering so Brain dump always comes first for Create
and Update, before any questions or working-mode choices.
- Add explicit Discovery ordering at the section top.
- Rewrite Brain dump as a non-negotiable first move with an anti-
pattern callout naming the exact failure mode.
- Add timing prefix to Working mode reinforcing the order.
* refactor(bmad-prd): aggressive trim and quality fixes from analysis
SKILL.md cut 49% (143 -> 84 lines); references/validate.md 35%;
references/headless.md 22%. Package-wide ~21% reduction.
Customization sweep:
- {finalize_reviewers} -> {workflow.finalize_reviewers} (was a silent
override no-op)
- Add canonical ## Conventions block
- Rename decision-log.md -> .decision-log.md across SKILL, refs, schemas
- customize.toml: validation_checklist -> validation_checklist_template,
output_dir -> prd_output_path, output_folder_name -> run_folder_pattern;
lifecycle comments on external_sources / external_handoffs
New behavior:
- Activation step 4: explicit by-name greeting using {user_name},
{communication_language} persisted for every turn (not just greeting)
- Right-skill scan on first message before brain dump
- Neutral defaults when config.yaml is missing; never block on it
- Headless: Detection section + per-intent Inputs section + 'partial'
status semantics + Update conflict-override rationale
- Brownfield Update bootstraps .decision-log.md via subagent when absent
- Reviewer Gate findings-overwhelm fix: tiered surfacing
(verdict -> critical/high -> medium/low rolled into tail)
- Discovery edge cases: conditional MVP question, persona/UJ push
contextually triggered, working modes renamed as outcomes
(Fast path / Coaching path)
- Subagent discipline: Finalize step 2 return-format contract,
step 5 structure->prose ordering, explicit no-subagent fallback
Tests:
- scripts/tests/test_render_validation_html.py (17 passing, covers
grade thresholds, category mapping, stats, score-bar rendering)
* refactor(bmad-prd): replace mechanical checklist+renderer with quality rubric and LLM-synthesized report
The structural checklist + Python renderer produced mechanical pass/warn/fail
reports that didn't speak to actual PRD quality, and additional reviewers
(adversarial) wrote separate review-*.md files that never made it into the
HTML. Replaces that pipeline with:
- A judgment rubric across seven PRD-quality dimensions (decision-readiness,
substance over theater, strategic coherence, done-ness clarity, scope
honesty, downstream usability, shape fit) that adapts to stakes and PRD
shape. Rubric walker writes review-rubric.md with per-dimension verdicts.
- HTML skeleton with TEMPLATE_* placeholders the synthesis pass fills
directly — no substitution engine, no Python.
- Synthesis pipeline in references/validate.md: parent reads every
review-*.md, fills the skeleton, writes validation-report.html plus
markdown twin, opens via webbrowser. Folds every reviewer's findings
into one report; grade derives from rubric verdicts and severity counts.
- Drops scripts/render-validation-html.py and scripts/tests/ entirely.
- finalize_reviewers defaults to empty (adversarial removed from defaults —
too brutal and frequently wrong against PRDs; teams can append in
override TOML).
- Headless mode now writes both HTML and markdown; skips browser-open.
* refactor(bmad-prd): faster working-mode entry, elicitation discipline, drop probing.md
Discovery rewrite: Brain dump -> Stakes calibration -> Working mode -> mode-scoped
work. Users in a hurry reach the Fast/Coaching choice in two or three turns instead
of ten. Brain dump explicitly invites existing inputs (briefs, research,
transcripts, prior PRD draft, design docs) alongside verbal context.
Elicitation discipline made explicit: Discovery pulls the user's vision out, never
inserts the LLM's. UJs and phasing must be user-articulated, not strawman-proposed
for rubber-stamp.
Coaching path now offers entry-point choice: Vision+Features (capability-first),
Personas+Journeys (user-first), or let-me-suggest. Capability-thinkers walk
features directly.
Template framing in PRD Discipline: Essential Spine is the expected default,
Adapt-In Menu is conditional, and the LLM is authorized to invent sections when
concerns don't match any cluster. Concern scan beat in Discovery surfaces real
domain concerns without forcing a fixed shape.
Web grounding: light targeted use at load-bearing moments authorized; deep
research is suggested to the user via dedicated research skills, accepting
gracefully if declined.
references/probing.md deleted; its load-bearing content was either LLM-default
PM instincts or already covered by SKILL.md.
Misroute list now includes bmad-workflow-builder for agent/custom-agent signals.
* fix(bmad-prd): align opener with Fast path naming, normalize misroute list
* refactor(bmad-prd, bmad-product-brief): bring skills to parity, default-on web research
Cross-skill consistency fixes:
- Brief renames {workflow.output_dir} -> {workflow.brief_output_path} and
{workflow.output_folder_name} -> {workflow.run_folder_pattern} to match PRD's
naming pattern.
- Decision-log filename unified on .decision-log.md (dotfile convention) across
both skills.
- Brief picks up PRD's fallback on customization-resolve failure (read TOML
directly instead of halt).
- Brief picks up PRD's persistent_facts default that auto-loads
project-context.md.
- Brief greeting now enforces {communication_language} for the entire run, not
just the greeting.
PRD additions, propagated from brief:
- File-roles paragraph in Conventions (boundary rules for .decision-log.md vs
addendum.md; capture during conversation, not at finalize; audit/override
never goes in addendum).
- Greeting now tells the user they can invoke bmad-party-mode or
bmad-advanced-elicitation at any point.
- Create intent now writes prd.md with status: draft and creates the
.decision-log.md skeleton at workspace init.
- Resume-check on activation: scans prd_output_path for prior in-progress runs
(status not final) and offers to resume.
- Finalize Close sets status: final + updated date so resume-check can
distinguish finalized from in-progress.
- Stakes-calibrated length guidance in PRD Discipline.
Web research, default-on for any scope:
- Reframed external_sources lines in both skills to distinguish org-configured
registry (internal tools) from generic web research; both fire on the same
triggers.
- New Research subagents (default) beat in PRD Discovery: spawn web-research
subagents to ground the picture; AI especially where training data ages by
the week. Subagent searches; parent receives a digest. Deep work routes to
bmad-market-research / bmad-domain-research / bmad-technical-research.
- Brief Discovery picks up the same posture in lighter form.
* fix(bmad-prd, bmad-product-brief): drop phantom v2 callout, add Fast/Coaching to brief
- Drop `[v2 — out of MVP]` from PRD validation rubric Dimension 5. It was
flagged for absence but never instructed for use anywhere — the template uses
`[NOTE FOR PM]` for v2/v3 deferrals, which is the de-facto convention.
- Add Fast path / Coaching path working-mode choice to brief Discovery so the
"I'm pitching tomorrow" user has an express option. Note that the opener's
pressure-calibration philosophy primarily shapes Coaching path; Fast path
swaps pushback for [ASSUMPTION] tags the user can correct in review.
* refactor(bmad-prd): tighten Research subagents beat
* chore(deps): update @clack/core and @clack/prompts to latest versions and adjust Node.js engine requirement
* feat(prompts): add directory prompt with autocomplete and create-directory support
* chore(docs): update Node.js version requirement to 20.12+ across multiple documentation files
* fix(prompts): code review fixes
* feat(bmm): add bmad-prd skill and extend product-brief with external integrations
Consolidates the legacy create-prd/edit-prd/validate-prd trio into a single
lean facilitator with create/update/validate intent modes, following the
bmad-product-brief pattern. Both skills gain external_sources and
external_handoffs customize.toml fields for routing through corporate MCP
tools (Confluence, Jira, etc.) with graceful degradation, plus a File roles
constraint clarifying decision-log (audit trail) vs addendum (preserved
depth for downstream docs).
* refactor(bmad-prd): tighten SKILL.md and operationalize source-extractor pattern
- Compress Overview to remove coaching prose duplicated in Discovery
- Operationalize "Extract, don't ingest" with explicit subagent return contract; reference from Update, Validate, and Finalize input reconciliation instead of inline "read N documents"
- Fix Overview H1 -> H2 (was breaking pre-pass tooling)
- Move full headless JSON schemas to assets/headless-schemas.md; keep minimal example inline
- Compress File roles bullet; tighten Finalize step 1
SKILL.md: 124 -> 105 lines, ~4729 -> ~4467 tokens
* feat(bmad-prd): open-items gate, drop distillate, persona discipline, decision-log metadata
- Add Finalize "Open-items review" step (new step 4): counts OQs / [ASSUMPTION] / [NOTE FOR PM], walks them with user, flags high density as red flag against agreed stakes
- Validate now treats open-items density as a first-class finding category
- Resume / continuity surfaces open items deterministically as the first orientation step
- Drop the PRD's own distillate output and the bmad-distillator finalize step. Downstream workflows (UX, architecture, story creation) source-extract from prd.md directly via the canonical source-extractor pattern. Headless schemas, customize.toml comments, and template updated accordingly.
- Drop "status: draft" from PRD frontmatter and template; version/state transitions logged to decision-log.md instead. Finalize step 7 records the version transition entry.
- Add PRD Discipline bullet: personas must be research-grounded or marked [ILLUSTRATIVE]; must drive decisions; 2-4 personas max. Discipline pass enforces.
- Expand File roles bullet: competitive-analysis detail beyond a one-line landscape and operational/cost mechanics (rate-limiting, compression) belong in addendum
* feat(bmad-prd): outcome-driven trim, swappable validation checklist, HTML report
SKILL.md trim (4.7K -> ~3.2K tokens, 124 -> 93 lines):
- Cut anchor enumerations (HIPAA/PCI/NIST list, API/Mobile/Web list, hobby->regulated list, "fast/easy/scalable/intuitive", input enumerations, etc.) the LLM already knows
- Cut derivable reasoning (synonyms-cause-drift explanation, hobby-vs-enterprise examples, etc.)
- Cut good/bad examples that anchor LLM attention (password/SendGrid example, persona quote, "let me also add this nearby thing")
- Drop SMART-ceremony language from Measurable bullet (keep judgment-not-ritual; SMART principles fine)
Progressive disclosure to references/:
- Headless mode rules + JSON minimal example moved to references/headless.md (loaded only when invoked headless)
- On Activation step 6 gates mode detection: headless -> read references/headless.md and follow
Swappable validation checklist:
- New assets/prd-validation-checklist.md (15 items: Quality / Discipline / Structural / Stakes-gated, each one line)
- New customize.toml field validation_checklist (override per org)
- Used by Validate intent AND Finalize Step 3 -- same subagent, same checklist, two moments
- Replaces bmad-validate-prd's 13-step micro-file architecture; kept the valuable check dimensions (density, measurability, traceability, implementation leakage, etc.) and dropped the ceremony
HTML validation report:
- New scripts/render-validation-html.py (PEP 723, stdlib only, ~175 lines) renders structured findings JSON into a styled HTML report with pass/warn/fail grade, inline SVG score bar, category grouping
- New assets/validation-report-template.html (inline CSS, native <details>, no JS, no external deps) -- swappable via customize.toml validation_report_template
- New references/validation-render.md documents the subagent output contract and renderer invocation; loaded only when validate flow runs
- Auto-opens browser on interactive runs; headless skips the open
Mode flow consistency:
- Create and Update both now explicitly "proceed to ## Finalize"
- Validate / analyze is standalone -- explicit "does NOT enter ## Finalize"; renderer auto-opens the HTML
- analyze is a synonym for validate; intent detection routes both
- Update mode no longer has its own light-close validation step (Finalize Step 3 covers it)
* refactor(product-brief,bmad-prd): remove distillation from brief and PRD workflows
Drop bmad-distillator integration from bmad-product-brief (finalize step,
update mode, headless JSON, constraints) and clean up customize.toml comments.
Distillation is the wrong layer — story self-containment via epic solution
design docs is the right answer for downstream context.
Also commit pending bmad-prd changes: working mode selector (Express vs
Facilitative), open-items triage into phase-blocking/resolvable/deferred
buckets, persistence wording fix, and facilitation-guide reference.
* refactor(bmad-prd): aggressive SKILL.md compression, remove LLM-obvious content
* feat(bmad-prd,bmad-product-brief): surface party-mode and advanced-elicitation at opening
* refactor(bmm): retire bmad-create-prd/edit/validate, point docs and PM agent at bmad-prd
Removes the three separate PRD skills (create, edit, validate) in favor of the
unified bmad-prd skill. Updates module-help.csv, PM agent menu, workflow map,
getting-started tutorial, commands reference, customize/help SKILL.md examples,
and the website workflow-map diagram. Adds Recipe 6 (Advanced Integration
Patterns) to expand-bmad-for-your-org.md covering external_sources,
external_handoffs, doc_standards, and swappable templates.
* test(bmad-product-brief): drop distillate from evals
Distillate was removed from the product-brief workflow in 1a88f001
but the eval suite still checked for distillate.md artifacts, the
bmad-distillator subagent invocation, and the polish→distillate phase
ordering. Strip all distillate references from A1/A5/B1/B2/B3/B5/B6,
remove B4 (phase-ordering eval centered on distillate) and B8 (pure
distillate eval), update _design_notes, and delete the orphan
distillate.md fixture from the forkbird-brief input set. IDs preserved
(gaps at B4, B8) so existing references stay stable.
* fix(bmad-prd): validation report only on explicit analysis request
Reconciles a contradiction across SKILL.md, validation-render.md,
headless.md, and headless-schemas.md about when validation-report.{html,md}
gets written. Rule: a report file is only written when the user has
specifically asked for analysis — Validate intent, or a mid-session
"produce a report" request. The Finalize discipline pass during
Create/Update keeps findings in-conversation: autofix obvious issues,
ask on ambiguous ones, never write a file.
- SKILL.md: Finalize step 3 no longer renders a report; Validate intent
wording softened from "HTML report" to "validation report".
- references/validation-render.md: drops the severity-based conditional
for markdown emission. Script now always writes both HTML and MD
side-by-side when invoked; trigger gating happens upstream.
- assets/headless-schemas.md: drops the "may be omitted in interactive
mode" caveat; validation_report is required for Validate intent.
- scripts/render-validation-html.py: adds render_markdown_report()
emitting a severity-grouped markdown companion at output_path.with_suffix('.md').
Returns markdown path in the stdout JSON summary alongside HTML path.
* fix(bmm-skills): address remaining PR review nits
- headless-schemas.md: Update schema gains `external_handoffs` to match
SKILL.md which routes Update through Finalize (handoffs execute there).
- bmad-product-brief/SKILL.md: "Use the bmad-help skill" → "Invoke
bmad-help" to align with REF-03 and the bmad-prd phrasing.
- bmad-product-brief/SKILL.md: hyphenate "high-quality draft".
* feat(bmm): add deprecation shims for retired PRD skills
Re-adds bmad-create-prd, bmad-edit-prd, bmad-validate-prd as thin
compatibility shims so existing invocations by name and
_bmad/custom/bmad-{create,edit,validate}-prd.toml override files keep
working post-consolidation. Each shim contains only SKILL.md and
customize.toml — no steps, data, or templates.
On activation, each shim:
1. Resolves customization via resolve_customization.py, picking up any
legacy override files for the four legacy fields (activation_steps_*,
persistent_facts, on_complete).
2. Emits a one-time deprecation notice in {communication_language},
pointing at bmad-prd and the migration path for override files.
3. Invokes bmad-prd with the appropriate intent (create / update /
validate), passes through the resolved legacy customization with
instruction to use these values instead of re-resolving from
bmad-prd's own customize.toml, and forwards the original user input
verbatim.
bmad-prd continues to read its own customize.toml + bmad-prd.toml
overrides for the new-only fields (prd_template, validation_checklist,
doc_standards, output_dir, output_folder_name, external_sources,
external_handoffs, validation_report_template). Users wanting those
fields must migrate to invoking bmad-prd directly.
* polish(bmm): refine PRD deprecation shim wording
Three small revisions applied uniformly to all three shims
(bmad-create-prd, bmad-edit-prd, bmad-validate-prd):
- Tighten the frontmatter description to a single sentence naming the
intent and signaling v7 removal.
- Drop the redundant "On failure, surface the diagnostic and halt."
trailer from the resolve-customization step; resolve_customization.py
surfaces errors itself.
- Extend the user-facing deprecation notice to clarify that legacy
override fields still resolve under bmad-prd, so migration is for
unlocking new fields rather than restoring lost functionality.
* fix(bmad-prd): normalize status casing and add friendly file errors
- compute_stats: lower-case `status` before bucketing so findings with
any casing (e.g. "Pass") feed the stat buckets and the score bar
fills correctly. Matches the .lower() pattern already used in
render_finding and render_finding_md.
- main: wrap findings/template read_text calls; emit a one-line error
to stderr and return 1 on FileNotFoundError or JSONDecodeError
instead of dumping a raw traceback. Script is LLM-invoked, so a
clean diagnostic is the contract.
Addresses augmentcode review comments 3235100013 and 3235100018.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* docs(expand): refresh "five recipes" copy to reflect Recipe 6
Recipe 6 (Advanced Integration Patterns) was added but three earlier
mentions still said "five": the frontmatter description, the intro
sentence at line 8, and the "Combining Recipes" paragraph. Update all
three to "six" and extend the Combining-Recipes example to call out
Recipe 6 (external_sources / external_handoffs) alongside the others.
Addresses coderabbitai review comment 3235107194 and the two
outside-diff observations on lines 3 and 8.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(bmad-prd): utf-8 encoding on render script, correct workflow-map outputs
- render-validation-html.py reads findings/template and writes HTML/MD with
explicit utf-8 encoding so non-ASCII content (smart quotes, em-dashes,
non-English text under {document_output_language}) does not break on
platforms whose default encoding is not utf-8.
- workflow-map.md 'Produces' column for bmad-prd now distinguishes
Create/Update outputs from the Validate intent's validation-report
artifacts.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): throw descriptive error when module definition missing after clone
When a stable tag predates a module restructure (e.g. baut v1.14.0 had
payload/source dirs, but the registry pointed to skills/module.yaml which
only exists on main), findExternalModuleSource silently returned the
configured but non-existent path. This caused a confusing ENOENT inside
getFileList/copyModuleWithFiltering rather than a clear error.
Now throws with the version that was cloned and a --next hint when the
install channel was stable, so users know exactly how to recover.
Closes#2372
* style: fix prettier formatting in external-manager.js
* style: apply prettier formatting
* refactor(bmm): streamline bmad-product-brief into lean facilitator
Rewrites bmad-product-brief as an outcome-driven, intent-routed
facilitator with a configurable reviewer panel.
- Replace scripted prompt files with a concise SKILL.md
- Add brief-shape detection and intent routing
- Make the reviewer panel config-driven via customize.toml
- Harden the required-reviewer gate
- Add helper scripts and tests for panel resolution
- Replace embedded resources with a single brief-template asset
- Register skill metadata in module.yaml
* refactor(bmm): tighten bmad-product-brief discovery and polish flow
- Discovery now invites a brain dump and source material upfront,
followed by "anything else?" before drilling
- Create and Update modes explicitly invoke Discovery before drafting
- Calibrate "make them sweat" to ease as the brief firms up
- Update mode regenerates distillate.md when changes apply
- Replace polish_skills with polish_passes: polymorphic entries
(skill:/file:/plain-text), parallel subagents, applied automatically
so the user sees a polished draft, not a polish review
- Default persistent_facts to empty with opt-in examples instead of an
unbounded project-context.md glob
- Remove research-librarian, field-researcher, and skeptic agents no
longer needed with this rework
* refactor(bmm): make persistence and resume explicit in bmad-product-brief
- Replace "Hold a working memory" with "Persistence is real-time": the
workspace exists on disk and the user knows the path the moment Create
intent is confirmed; decision-log.md is canonical memory so walk-away
leaves nothing in the conversation
- Add "Continuity across sessions": prior in-progress drafts for this
project surface a resume offer
* test(bmm): scaffold evals for bmad-product-brief
Adds an eval suite for bmad-product-brief following the Anthropic skill-creator
schema, plus a new "Extract, don't ingest" constraint on the skill itself.
Skill change:
- New constraint: source artifacts (user-provided or run-discovered) enter the
parent conversation as relevance-filtered extracts via subagents, not loaded
wholesale. Keeps the parent context lean against transcripts, brainstorms,
research reports, code, web results, and prior briefs.
Evals (evals/bmm-skills/bmad-product-brief/):
- evals.json: 8 artifact/behavioral evals covering Create one-shot,
source-memo ingest, Update with contradiction surfacing, Validate inline,
Headless mode, brainstorm filtering, research-report filtering, persona
filtering. All scenarios use fictional entities (InsuLens, Branfield CC,
Forkbird Kitchen, Mossridge Library, Sproutkeeper, Hatchet & Loop Studio,
Brightway, Pantry Bridge).
- triggers.json: 15 description-firing checks (7 should-fire, 8 should-not-fire)
to catch under-triggering and adjacent-skill poaching.
- files/: realistic fixtures including a brainstorm with the relevant idea
buried at the end, a 3000-word market research report with the relevant
section in the middle, and customer interviews with the target persona in
position 3 of 4 — each shaped to test that filtering happens against the
user's stated focus regardless of where the relevant material sits.
Eval directory placement: top-level evals/ outside src/, matching the convention
in anthropics/skills (zero of 17 production skills include an evals/ subdir;
their skill-creator places dev workspaces as siblings to skill folders). Keeps
evals out of any installer or marketplace.json distribution path.
* refactor(bmm): rename brief workflow knobs and resolve PR review
- polish_passes -> doc_standards (TOML key + SKILL.md reference). Name
generalizes for every doc-producing skill: encodes standards applied at
finalize, not options.
- {run_folder} -> {doc_workspace}. Bound in Create to
{workflow.output_dir}/{workflow.output_folder_name}/; reused by Update,
Validate, Headless, and Finalize as the active brief's folder.
- On Activation Step 4 now resolves {date} explicitly (used by
output_folder_name default).
- Headless Mode: ambiguous-intent fallback is a `blocked` JSON status with
a `reason` field, no prompting. Resolves the activation/headless
contradiction flagged in review.
* test(bmm): overhaul product-brief evals into A/B/C pattern split
Refactor evals from 8 numbered single-shot tests into 16 typed evals:
- Pattern A (A1-A8): artifact-correctness tests with headless prompts and
precise, falsifiable expectations (no invented facts, right-sized output,
file boundary enforcement)
- Pattern B (B1-B8): process-discipline tests verifying decision-log fidelity,
polish phase ordering, contradiction detection, and distillate generation
- Pattern C (C1): config-compliance test for custom output paths and
document_output_language
Also tighten SKILL.md: add dependencies frontmatter, clarify headless override
autonomy in Update (proceed when intent is clear; block when ambiguous), and
make distillate skip explicit when bmad-distillator is not installed.
Two PR review fixes:
- Strip the surrounding markdown code fence from case-file-template.md
so initializing a case file doesn't nest the whole artifact inside a
code block. The template is now the structure directly, with usage
notes in an HTML comment that doesn't render. Matches the BMM idiom
used by bmad-create-story/template.md.
- Drop the stale `*-archaeology.md` reference from bmad-create-prd
step-01 discovery. The single-procedure restructure removed
archaeology as a distinct mode, so case files only carry the
`*-investigation.md` suffix. Tighten the glob accordingly.
Forensic case investigation under Amelia's menu (IN). Evidence-graded
findings (Confirmed / Deduced / Hypothesized), hypothesis discipline,
structured case-file artifact. Single procedure that calibrates between
defect-chasing and area-exploration based on the input.
Wires bmad-create-prd discovery to pick up case files as PRD input.
Public explainer doc, workflow-map Phase 4 row, EN + FR.
* refactor(catalog): rename after/before columns to preceded-by/followed-by
The bare prepositions `after` and `before` had no subject anchor, leaving
the dependency direction ambiguous: "X has Y in its `after` column" reads
plausibly as either "Y comes after X" or "X comes after Y". An LLM
catalog consumer just got the direction wrong because of this.
`preceded-by` / `followed-by` are passive-voice participles whose grammar
locks the subject (the skill in this row) and forces a single reading:
"X is preceded by Y" can only mean Y comes first.
Rename applied to:
- module-help.csv headers (bmm-skills, core-skills)
- bmad-help SKILL.md schema doc + descriptions
- installer.js mergeModuleHelpCatalogs header string
- plugin-resolver.js _buildSynthesizedHelpCsv header string
- bmad-manifest.json keys (bmad-product-brief, bmad-prfaq)
- distillate-format-reference.md example manifest
The separate `required` column continues to carry hard-gate semantics;
the renamed columns are pure soft sequencing hints, as already documented
in bmad-help.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* style(installer): wrap long header strings per prettier
* feat(installer): warn on non-canonical module-help.csv headers
mergeModuleHelpCatalogs now compares each per-module file's header
against the canonical schema and emits a one-shot prompts.log.warn per
module on drift, naming both the expected and actual header. Data
continues to load positionally so external modules built against the
old after/before schema still install cleanly — the warning is the
maintainer signal to rename their columns.
Centralize the canonical header in modules/module-help-schema.js so the
merger and the synthesizer (PluginResolver._buildSynthesizedHelpCsv)
read the same source of truth; future column renames are one edit.
Verified by installing all four bmad-org external modules
(bmb, cis, gds, tea) — every one ships the legacy after/before header
today and now fires an advisory warning while still merging cleanly
into _bmad/_config/bmad-help.csv with the canonical column names.
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): remove bmad-help from Copilot Custom Agents picker
Per @BMadCode's feedback after #2324 merged: every persona agent's
activation message already advertises bmad-help, so its picker entry is
redundant AND confusing (looks like a peer agent when it's actually the
meta-help). Removes the ALWAYS_AGENT_IDS allowlist exception that put it
there.
The toml-driven filter (the mechanism BMadCode endorsed in his PR review)
remains the sole signal: a skill is a persona iff its source
customize.toml has an [agent] section. bmad-help has no customize.toml,
so under the cleaned-up filter it's correctly excluded.
Tests: replaces the inclusion assertion in Suite 17 with an exclusion
assertion. Suite still covers persona / non-conventional persona /
workflow / meta-skill-with-`-agent-`-in-name cases.
Refs #2324
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* test: clarify Suite 17 fixture comment per PR review
The fixture creates no customize.toml at all for bmad-help, so the
exclusion path being exercised is the missing-file branch — not the
file-without-[agent]-section branch. Reword the comment accordingly.
Per @augmentcode review on #2359.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): generate OpenCode /<skill> slash commands
Adds .opencode/commands/<canonicalId>.md pointer files for each installed
skill so users can invoke skills directly (e.g. /bmad-quick-dev) instead
of going through the /skills menu.
- platform-codes.yaml: add commands_target_dir field for opencode
- _config-driven.js: installCommandPointers() with skip-if-exists default,
reserved-name collision guard, YAML-safe description quoting
- _config-driven.js: cleanupCommandPointers() for symmetric uninstall
- test-installation-components.js: extend OpenCode suite with assertions
covering pointer creation, content, and idempotency
OpenCode-only and opt-in via the new yaml field; other adapters unchanged.
Refs #2267
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): address PR #2324 review feedback
Six fixes from CodeRabbit + Augment review on the OpenCode command
pointer generation:
- skipTarget no longer suppresses installCommandPointers in multi-IDE
shared-target_dir batches. Pointers live in a per-IDE directory and
are not deduped across peers, so OpenCode must still generate them
even when a peer (e.g. openhands) won the .agents/skills write race.
- skipTarget no longer suppresses cleanupCommandPointers either, so
partial uninstalls leave no stale pointers when a peer remains.
- canonicalId is validated as a safe basename before being interpolated
into a file path (defense in depth against a malformed manifest entry
writing outside commands_target_dir).
- yamlSafeSingleLine now quotes descriptions starting with `[` or `{`
so YAML doesn't parse them as a sequence/map.
- Per-record fs.writeFile failures are caught and counted (writeFailures)
rather than aborting the whole IDE install — pointer files are a
non-essential adjunct to the skill copy.
- Generator-shaped pointer files are refreshed when the manifest
description changes; hand-modified files (body diverges from the
generator pattern) are still preserved unless forceCommands is set.
Tests: extends Suite 8 with description-update propagation; adds new
Suite 40c covering OpenCode + openhands batches in both orderings plus
partial-IDE uninstall pointer cleanup. 308 tests pass (was 296).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): address PR #2324 follow-up nitpicks
Four nitpicks from CodeRabbit's original review that were missed in the
first triage pass:
- Hand-edited pointers now survive the production install flow.
cleanupCommandPointers spares pointers for canonicalIds that are still
in the new manifest when called from the install/update flow (signal:
options.previousSkillIds is set). Uninstall and partial-IDE removal
flows still wipe pointers as before. The previous behavior wiped every
pointer in removalSet before installCommandPointers could run, so its
skip-if-exists guard never fired and hand edits were lost on every
reinstall — contradicting the docstring's preservation claim.
- RESERVED_OPENCODE_COMMANDS is now gated on this.name === 'opencode'
so future adapters opting into commands_target_dir don't silently
inherit OpenCode's reserved-name set.
- printSummary now surfaces results.commands so users see how many
pointers were created/refreshed/skipped per install, plus a warning
for any per-file write failures.
- Dropped a dead `typeof entry !== 'string'` check; fs.readdir without
withFileTypes always yields strings.
Tests: extends Suite 8 with a hand-edit-preservation regression that
calls setup with previousSkillIds (the production shape) and asserts a
sentinel byte sequence in the pointer body survives. 310 tests pass.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): extend command-pointer generation to Copilot Custom Agents
Re-scopes #2324 to cover the second user-facing pain: GitHub Copilot's
Custom Agents picker, where installed BMAD skills currently don't show up
even though slash commands work natively.
Generalizes the per-platform pointer-file mechanism so the same
installCommandPointers / cleanupCommandPointers code path serves both
OpenCode (slash commands palette) and Copilot (Custom Agents picker), with
all platform-specific shape pushed into platform-codes.yaml as data:
- commands_target_dir — where pointer files live (existing)
- commands_extension — file extension (default '.md'; Copilot uses
'.agent.md' per VS Code Custom Agents docs)
- commands_body_template — pointer body, supports {canonicalId} and
{target_dir} placeholders. Default matches
OpenCode's `@skills/<id>` resolver. Copilot
has no such resolver, so its template uses
the {project-root}/<target_dir>/<id>/SKILL.md
LOAD pattern (consistent with PR #1769).
OpenCode behavior is unchanged. Copilot users now get a per-skill
.github/agents/<canonicalId>.agent.md file that surfaces the skill in the
Custom Agents picker — addressing the "agents being gone" complaint
flagged by enterprise users.
Tests: extends Suite 17 with assertions for Copilot agent pointer
creation, body content (LOAD pattern with {project-root}-rooted path),
and idempotency. 318 tests pass (was 310).
Refs #2267
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): filter Copilot Custom Agents picker to persona agents only
Earlier commit naively wrote a `.github/agents/<id>.agent.md` for every
installed skill, which would clutter the Custom Agents picker with 90+
workflow/tool entries that don't belong there.
Adds an `agents-only` filter that gates the per-skill emission on whether
the canonical id signals a persona agent:
- Primary rule: id contains `-agent-` (e.g. `bmad-agent-pm`,
`gds-agent-game-dev`, `wds-agent-freya-ux`,
`bmad-cis-agent-storyteller`).
- Allowlist: `bmad-tea` — TEA's Murat persona uses the bare module code
rather than the `-agent-` convention. Listed explicitly so the rule
still surfaces it.
Verified against the full installed manifest (114 skills): catches all
20 description-confirmed personas across BMM, CIS, GDS, WDS, TEA;
excludes all 94 workflows/tools.
Wired through a new yaml field on github-copilot:
commands_filter: agents-only
OpenCode is unaffected — it has no `commands_filter` set, so the loop
behaves as before (every skill becomes a slash command).
Tests: extends Suite 17 with a multi-skill manifest fixture covering
persona/agent + bmad-tea + workflow cases; asserts persona agents and
bmad-tea get .agent.md files while workflows do not. 322 tests pass.
Refs #2267
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): detect personas via customize.toml [agent] section
Per maintainer review on PR #2324: the `-agent-` naming convention isn't
a load-bearing contract anywhere else in the codebase, and the bmad-tea
allowlist already shows it starting to break. A future persona that
doesn't follow the convention would silently disappear from the Copilot
Custom Agents picker.
Replaces the name-based filter with a behavior-based signal: read each
skill's source `customize.toml` and check for an `[agent]` section. This
is the actual configuration source of truth — every BMAD persona is
configured under `[agent]`, every workflow under `[workflow]`, every
standalone skill has no customize.toml.
Verified on disk against the full installed manifest (114 skills):
- 20 personas detected — exactly the description-confirmed count across
BMM, CIS, GDS, WDS, TEA. bmad-tea is caught natively (no allowlist).
- 94 workflows/tools correctly excluded.
- `bmad-agent-builder` (meta-skill that builds agent skills) is now
CORRECTLY excluded — its canonical id contains `-agent-` but its
customize.toml has [workflow], not [agent], because it isn't a
persona itself. The previous naming-based filter was including it in
the agents picker, which would have been a silent UX bug.
`NON_CONVENTIONAL_AGENT_IDS` constant is removed entirely — the toml
signal subsumes it.
Tests: extends Suite 17 with a 4-skill fixture that covers persona +
non-conventional persona + workflow + meta-skill cases. 388 tests pass.
Refs #2267
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* fix(installer): always include bmad-help in Copilot agents picker
Adds a single, deliberate exception to the toml-based agents-only filter:
`bmad-help` is the structural meta-skill across BMAD — the orientation
helper that points users at every other skill. Users invoke it
persona-style ("ask the helper") even though it has no `[agent]`
customize.toml of its own (it isn't a configurable persona).
Implemented as a one-element ALWAYS_AGENT_IDS set rather than a hardcode
in the function body so the exception is named, documented, and
discoverable. The skill is structurally unique — there is no second
meta-help skill — so this is not the start of a growing allowlist; it's
a one-off for the one orientation surface BMAD ships.
Verified on disk: agents picker now shows 21 entries (20 personas via
[agent] in customize.toml + bmad-help). bmad-agent-builder stays
correctly excluded (its customize.toml has [workflow], not [agent]).
Tests: extends Suite 17 with a `bmad-help` fixture (no customize.toml,
must still appear in agents picker). 389 tests pass.
Refs #2267
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-authored-by: Brian <bmadcode@gmail.com>
* fix(installer): handle deep-path URLs in custom module source parser
Rewrite parseSource() from host-specific regex to generic URL-based
parser so Azure DevOps _git paths and other multi-segment repo URLs
are preserved in cloneUrl and cacheKey.
Closes#2268
* test(installer): add Azure DevOps URL tests and wire into CI
- Add 18 assertions for dev.azure.com and visualstudio.com URLs
- Cover modern ADO, legacy ADO, .git suffix, ?path= subdir variants
- Add test:urls script to test and quality npm chains
---------
Co-authored-by: Brian <bmadcode@gmail.com>
Add Chinese translations for the two remaining untranslated docs
(named-agents, expand-bmad-for-your-org) and add i18n translations
for the BMad Ecosystem sidebar group and its items across all locales.
Co-authored-by: leon <leon.liang@hairobotics.com>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Closes#1663.
Adds two installer flags so module config options can be set without
interactive prompts. Designed for CI scripts, Dockerfiles, and
enterprise rollouts where the user wants to bake answers into the
install command rather than answer prompts.
`--set <module>.<key>=<value>` (repeatable) sets any module config
option. `--list-options [module]` lists every key the installer can
discover locally — built-in modules (`core`, `bmm`) plus any cached
official modules. One flag scales to every module without growing the
CLI surface per option.
```bash
npx bmad-method install --yes \
--modules bmm --tools claude-code \
--set bmm.project_knowledge=research \
--set bmm.user_skill_level=expert \
--set core.user_name=Brian
```
## How it works
`--set` is a post-install patch. The installer runs its normal flow
untouched, then `applySetOverrides` upserts each value into the
relevant config files:
- `_bmad/config.toml` (team scope, default)
- `_bmad/config.user.toml` (user scope, when the key already lives
there — so user-scope keys like `core.user_name` and
`bmm.user_skill_level` keep their proper file)
- `_bmad/<module>/config.yaml` (so declared schema keys carry forward
via the existingValue path on the next install)
A module without `_bmad/<module>/config.yaml` is skipped silently —
no orphan sections in `config.toml` for uninstalled modules.
## Tradeoffs documented in install-bmad.md
- **Verbatim values.** `--set bmm.project_knowledge=research` writes
`"research"`, not `"{project-root}/research"`. The `result:`
template is not applied. Pass it explicitly if you want the
rendered form: `--set bmm.project_knowledge='{project-root}/research'`.
- **Carry-forward, declared keys.** Free — values land in the
per-module `config.yaml`, so the next install reads them as
`existingValue` and they become the prompt default (accepted under
`--yes`).
- **Carry-forward, undeclared keys.** Best-effort. The value lives in
`config.toml` for the current install but won't be re-emitted on
the next install (the manifest writer's schema-strict partition
drops unknown keys). Re-pass `--set` if needed.
- **No "key not in schema" validation.** Whatever you assert is
written.
## Security
Prototype-pollution defense: `--set __proto__.x=1` would otherwise
reach `overrides.__proto__[x] = 1` and pollute `Object.prototype`,
cascading into every plain-object lookup in the process. Defense-in-
depth via parser-level reserved-name rejection (`__proto__`,
`prototype`, `constructor`) AND `Object.create(null)` for the
override maps. Verified the attack reproduces without the guard and
is blocked with it.
## What's intentionally NOT integrated
`--set` deliberately does not touch the prompt / template / schema
collection flow. No pre-seeding answers, no question filtering, no
function-default evaluation, no schema-strict partition exemption.
That earlier integration approach was tried and scrapped: it
spread state across `Config`, `OfficialModules`,
`manifest-generator`, both collection helpers, and required parallel
plumbing for quick-update — every bug fix touched a different layer.
The post-install patch model covers the actual user need (set a
config value from CI) in ~330 lines of `set-overrides.js` without
the schema gymnastics.
## Files
- `tools/installer/set-overrides.js` (new): parser, prototype-pollution
guard, `applySetOverrides` post-install patch, `upsertTomlKey` /
`tomlString` / `tomlHasKey` line-based TOML helpers
- `tools/installer/list-options.js` (new): module.yaml discovery +
formatter for `--list-options`
- `tools/installer/commands/install.js`: register `--set` /
`--list-options` flags, early validation, `--list-options` exit-code
handling (await `stream.write` callback then `process.exitCode` to
avoid truncating piped output), thread `setOverrides` through to
quick-update
- `tools/installer/core/config.js`: carry `setOverrides` field for
the post-install patch step
- `tools/installer/core/installer.js`: invoke `applySetOverrides`
after `writeCentralConfig` (covers regular install + quick-update
via the shared install path)
- `tools/installer/ui.js`: parse `--set` for early validation, warn
about overrides targeting modules not in `--modules`, drop those
entries before threading
- `docs/how-to/install-bmad.md`, `README.md`: usage, routing rules,
carry-forward semantics, tradeoffs
## Test plan
Suite 44 (24 cases): parser, prototype-pollution guard, `tomlString`
escaping, `upsertTomlKey` across insert/replace/missing-section/
empty-file/preserved-newline cases, `applySetOverrides` happy path +
uninstalled-module skip + missing-user-toml-creation + empty-input
no-op, `discoverOfficialModuleYamls` / `formatOptionsList` sanity
(hermetic via `BMAD_EXTERNAL_MODULES_CACHE` temp dir). 355 total
passing. Lint + prettier + markdownlint clean.
E2E smoke verified across:
- [x] `--set` writes correct files (team toml / user toml / per-module
yaml) for declared and undeclared keys
- [x] Quick-update without `--set` carries forward declared keys via
`existingValue` path
- [x] Quick-update WITH `--set` applies cleanly (uniform behavior
across action types)
- [x] `--set` for unselected module: warned, no orphan section
- [x] Prototype pollution: rejected with non-zero exit
- [x] `--list-options bmm` exit 0 with full output through pipe;
`--list-options nope` exit 1
- [x] Translated docs (`docs/{cs,fr,vi-vn,zh-cn}/`) intentionally not
touched — they'll lag behind English until the translation pipeline
runs
* fix(installer): preserve module-help.csv schema in merged bmad-help.csv (#2278)
The installer's mergeModuleHelpCatalogs was rewriting the merged catalog
under a different schema (module,phase,name,code,sequence,workflow-file,...)
than the documented source schema in every module's module-help.csv
(module,skill,display-name,menu-code,description,action,args,phase,...).
Worse, the parsing assumed the wrong source column order, so column data
was scrambled in the merged output. SKILL.md docs the source schema, so
the bmad-help skill was navigating a catalog whose actual columns no
longer matched its mental model.
Drop the transformation and the agent enrichment columns (which had no
consumers anywhere in the codebase). Emit rows verbatim in the source
schema, padding short rows and filling empty module fields. Sort by
module then phase, stable within phase to preserve authored order.
Closes#2278
* fix(catalog): normalize module-help.csv rows to documented 13-column schema
Many rows in core-skills/module-help.csv and bmm-skills/module-help.csv
were missing one column between description and phase, leaving them at
12 fields instead of 13. CSV consumers that read by header position
were silently mapping data into the wrong columns (description into
action, phase into args, required into before, etc).
Inserted an empty cell at column index 5 across all 31 affected rows
to restore alignment with the documented header
(module,skill,display-name,menu-code,description,action,args,phase,
after,before,required,output-location,outputs).
* fix(config): promote project_name to core, fixes#2279
project_name was a bmm-specific prompt despite being a universal
project-level concept used by every module — including core skills like
bmad-brainstorming, which loads from _bmad/core/config.yaml and was
silently broken because project_name lived under bmm. Users without bmm
installed could not run brainstorming at all.
Move:
- src/core-skills/module.yaml: declare project_name with prompt
"What is your project called?" and default {directory_name}, matching
what bmm previously had.
- src/bmm-skills/module.yaml: remove the bmm definition; add project_name
to the "Variables from Core Config inserted" header comment so
contributors can see what's inherited.
Migration for existing installs:
- tools/installer/modules/official-modules.js: after loadExistingConfig
reads each per-module config.yaml, hoist any keys that are now declared
in core but appear under non-core modules. Without this, the partition
logic in writeCentralConfig (which strips core keys from non-core
buckets) would silently drop the user's prior project_name on the next
quick-update. Generic — handles project_name today and any future
module→core promotions.
- The hoist preserves precedence: an existing core value beats a stale
module-side copy.
--yes seed:
- tools/installer/ui.js: add project_name to the hardcoded core seed
(using path.basename(directory) to match the {directory_name} default)
so non-interactive fresh installs populate it. Without this the seed
silently omits project_name and core skills fall back to literals.
Tests:
- test/test-installation-components.js Suite 43 (9 assertions) covers
the schema move, the loadExistingConfig hoist, and the precedence rule.
- Suite 35 fixture updated: project_name moved from bmm bucket to core,
with a stale bmm copy left in place to verify it gets stripped.
Verified manually:
- Fresh install -y: project_name lands in [core] of config.toml.
- Existing install with project_name in bmm/config.yaml: quick-update
hoists it to [core] and strips it from [modules.bmm].
* fix(installer): harden config-load against malformed config.yaml
Per augment review on #2348: loadExistingConfig stored any truthy
yaml.parse result (including scalars like '42'), which would later crash
_hoistCoreKeysFromLegacyModuleConfigs at \`key in cfg\` with
"Cannot use 'in' operator to search for ... in 42".
- loadExistingConfig: only keep parses that are plain objects (not
scalars or arrays). A corrupt config.yaml is now treated the same as
a parse error — skipped, not crashed-on.
- _hoistCoreKeysFromLegacyModuleConfigs: belt-and-suspenders type guards
on _existingConfig.core (in case it's populated by some other path)
and on each module cfg in the loop.
- Test Suite 43 adds 2 assertions covering a scalar core/config.yaml:
loadExistingConfig must not crash, and bmm.project_name must still
hoist into a clean core bucket.
step-07-validation template shipped with all 16 completeness checkboxes
pre-checked and Overall Status hard-coded to READY FOR IMPLEMENTATION,
defeating the gate. Reset checkboxes to unchecked, replace status with a
templated choice tied to the checklist and gap analysis, and instruct the
agent to only mark items the validation actually confirms.
Closes#2292
* fix(installer): require --tools for fresh --yes installs; remove --tools none (closes#2326)
Fresh non-interactive installs without --tools previously produced a
config-only install (~35 files vs ~1400 in the manifest) with no warning
and a "BMAD is ready to use" success card, leaving slash commands
unreachable. --tools none was an explicit opt-in for the same broken
state.
Now: fresh install + -y without --tools throws a helpful error pointing
at --list-tools. --tools none is rejected as an unknown ID. Empty and
typo'd tool IDs are also rejected. Existing-install paths (--action
update, quick-update, modify) are unchanged - they continue to reuse
previously-configured tools when --tools is omitted.
Adds --list-tools flag that prints all 42 supported tool IDs (id, name,
target_dir, preferred star) sourced from platform-codes.yaml.
English docs updated; localized docs (vi-vn, fr, cs, etc.) will sync via
the normal translation pass.
* fix(installer): address review for #2326 — single source of truth, drop dead code, add tests
- Refactor formatPlatformList to use IdeManager so --list-tools and --tools
validation see the same set of platforms. Eliminates the drift where suspended
platforms appeared in --list-tools but were rejected at validation.
- Drop unused getValidPlatformIds export.
- Flatten redundant block scope around the throw in the --yes-without-tools
branch (refactor leftover).
- Drop dead String() defensive cast (Commander always passes a string).
- Add Test Suite 42: 8 unit tests covering _parseToolsFlag empty/whitespace/
unknown/typo cases plus an integration check that --list-tools output and
--tools validation agree on the ID set.
* fix(installer): close --tools "" bypass and drop hardcoded tool count
- Replace truthy `if (options.tools)` guard with `!== undefined` in both
upgrade and fresh-install branches. Empty string now reaches
_parseToolsFlag and produces the specific "passed empty" error
instead of falling through to a generic message (fresh-install) or
being silently ignored (existing-install).
- Drop the hardcoded "42 supported tools" count from the prereqs in
install-bmad.md so the doc doesn't drift as platform-codes.yaml
changes.
Addresses augment / coderabbit review on #2346.
2026-04-27 23:01:23 -05:00
341 changed files with 11932 additions and 15726 deletions
* **Installer no longer errors when a previously installed module's source can no longer be found** — In v6.7.0 the experimental BMad Automator module's installer code (the value used for its `_bmad/<code>/` folder and manifest entry) was renamed from `baut` to `automator`. Anyone who had installed it under the old `baut` code saw `quick-update` fail with `Source for module 'baut' is not available` and risked having the existing install removed. The installer now detects installed modules that can no longer be resolved from any source, leaves them in place untouched, and continues the update. If you previously installed it as `baut` and want the renamed `automator` version, run `npx bmad-method install`, choose **Modify BMAD Installation**, and reselect **BMad Automator**; the old `_bmad/baut/` directory can then be deleted manually
## v6.7.0 - 2026-05-17
### ✨ Headline
**PRD and Product Brief rebuilt as lean, outcome-driven facilitators called bmad-prd and bmad-brief.** Both flagship planning skills now ship three first-class intents (Create / Update / Validate), support express and guided modes, drive elicitation rather than LLM-suggested filler, and adapt output to your needs. New PRD validation pipeline replaces the adversarial reviewer with a quality-rubric synthesis pass that emits both HTML and markdown reports. New **bmad-investigate** skill brings forensic, evidence-graded case files for bug triage, incident RCA, and unfamiliar-code exploration.
A new .decision-log pattern is implemented in this release that will track through workflows all decisions made from the start, allowing for easier continuation or later modifications, where memory of what was decided and why will be remembered.
The existing create, edit and validate prd skills still exist but internally will route to the single prd skill with the proper intent. These shims will be removed with the 7.0.0 release when similar updates are completed across all of v6.
The shape of the toml customizations is still the same, so if you make them for create already, it will still work. There are new fields supported also that can improve your experience with the new bmad-prd skill.
### 💥 Breaking Changes
* **Community modules picker removed from the interactive installer.** Previously installed community modules are preserved on update. Install community modules headlessly with `--custom-source <git-url-or-path>`, or wait for the forthcoming dedicated community installer.
* **Remote marketplace registry fully retired.** The installer makes zero network calls to `bmad-code-org/bmad-plugins-marketplace`. Both the official-registry fetch (`registry/official.yaml`) and the community-catalog fetch (`registry/community-index.yaml`, `categories.yaml`) are gone. `CommunityModuleManager` and `RegistryClient` are deleted. The bundled `bmad-modules.yaml` at the repo root is the single source of truth for which official modules appear in the picker. Per-module version bumps continue to happen in each module's own repo. **Migration note:** users with previously installed community modules will see them preserved in their manifest, but updates must be handled via `--custom-source <url>` going forward (a dedicated community installer is planned separately).
### 🎁 Features
* **WDS (Whiteport Design Studio) now bundled in the official module picker.** Selectable alongside BMM, BMB, BMA, CIS, GDS, and TEA without needing `--custom-source`.
* **Refreshed display names and hints across all bundled modules.** Shorter, clearer names; hints now describe what each module provides. TEA repositioned to sit directly after BMM in the picker.
* **Registry entries can declare a `plugin_name` override.** When a module's `.claude-plugin/marketplace.json` declares the plugin under a name different from the module's installer code (e.g., WDS uses `bmad-wds`), set `plugin_name: <name>` on the registry entry to match the marketplace plugin without falling back to the single-plugin heuristic.
* **bmad-prd overhaul** — Three intents (Create / Update / Validate); new Discovery shape (Brain dump → Stakes calibration → Working mode → mode-scoped work); capability-first or user-first modes; Essential Spine template plus Adapt-In Menu with authorized section invention for compliance, integration, hardware, SLAs, monetization, data governance; subagent web research default-on; rebuilt validation via PRD Quality Rubric → synthesis pass → HTML + markdown reports; cross-skill parity with `bmad-product-brief` (variable names, `.decision-log.md`, `persistent_facts` auto-loads `project-context.md`); headless mode with per-intent inputs and `partial` status (#2385, #2378)
* **bmad-product-brief refactor** — Streamlined from a five-stage scripted workflow to a single outcome-driven SKILL.md with Create / Update / Validate intents; inline discovery, elicitation, and review (no more scripted agent fan-outs); new `assets/brief-template.md` with adapt-aggressively guidance; finalize chain through `bmad-distillator` and `bmad-help`; JSON headless responses (#2370, #2371)
* **New bmad-investigate skill** — Forensic case investigation with evidence-graded findings (Confirmed / Deduced / Hypothesized), delegation discipline for large codebases, resume-on-collision logic; supports both defect-chasing and area-exploration modes (#2345 and follow-ups)
* **Interactive directory prompt in installer** — `@clack/core` AutocompletePrompt for install-path selection: Tab-cycles existing child dirs, accepts not-yet-created paths, validates raw input (#2387)
* **OpenCode and GitHub Copilot pointer files** — Generic `installCommandPointers()` mechanism driven by per-platform YAML. OpenCode gets `.opencode/commands/<id>.md` for every skill; Copilot gets `.github/agents/<id>.agent.md` for persona agents only (plus `bmad-tea` allowlist), keeping the Custom Agents picker uncluttered. Works for external modules automatically via `skill-manifest.csv` (#2324)
* **Clear installer error on missing module definition** — `findExternalModuleSource()` throws an actionable error naming the module, missing path, and channel, with a suggested `--next=<code>` recovery path, replacing a silent ENOENT in `getFileList` (#2377)
* **bmad-product-brief Update/Validate discipline** — Headless Update now requires decision-log entry + addendum before modifying `brief.md`; distillate regeneration is mandatory; Validate always returns `"offer_to_update": true`; eval expectations tightened (#2371)
* **Module help catalog directional clarity** — Renamed `after`/`before` columns (and JSON manifest keys) to `preceded-by`/`followed-by` to eliminate ambiguity that was causing dependency-direction flips; `required` retains hard-gate semantics (#2360)
* **bmad-help removed from Copilot Custom Agents picker** — Not a true agent; every persona already advertises it on activation (#2359)
* **Dependency security audit** — Lockfile-only fixes closed 12 of 14 open Dependabot alerts (`vite`, `postcss`, `h3`, `yaml`, `brace-expansion`, `picomatch`, `astro`, others). Two `astro <6.1.10` alerts and one `markdown-it` (via `markdownlint-cli2`) deferred pending major bumps (#2382)
### 📚 Docs
* New `docs/explanation/forensic-investigation.md` (EN + FR) explaining the bmad-investigate workflow and evidence-grading discipline; workflow maps updated in both languages
* Installer prerequisite docs updated across README, install/upgrade/non-interactive/tutorial guides and FR / CS / ZH-CN / VI-VN translations to advertise Node.js 20.12+ (#2387)
## v6.6.0 - 2026-04-28
### 💥 Breaking Changes
* `--tools none` is no longer accepted; fresh `--yes` installs now require an explicit `--tools <id>`. Existing-install flows are unchanged. Run `npx bmad-method --list-tools` to see supported IDs (#2346)
* `project_name` has moved from `[modules.bmm]` to `[core]` in `config.toml`. Existing installs are auto-migrated on next install/update — no manual action required (#2348)
### 🎁 Features
* **Non-interactive config for CI/Docker** — new `--set <module>.<key>=<value>` (repeatable) and `--list-options [module]` flags allow installer configuration without prompts. Routes values to the correct config file with prototype-pollution defenses (#2354)
* **Brownfield epic scoping** — Create Epics and Stories workflow now detects file-overlap between epics and applies an Implementation Efficiency principle plus a design completeness gate, reducing unnecessary file churn (#1826)
### 🐛 Fixes
* **Custom module installer** — Azure DevOps URLs now parse correctly with multi-segment paths and `_git` prefixes (#2269); HTTP (non-HTTPS) Git URLs are preserved for self-hosted servers (#2344); community installs route through `PluginResolver` so marketplace plugins with nested `module.yaml` install all skills (#2331); URL-source modules resolve from disk cache on re-install instead of warning (#2323); local `--custom-content` modules resolve correctly and `[modules.<code>]` TOML keys use the module code rather than display name (#2316); `--yes` with `--custom-source` now runs the full update path so version tags are respected (#2336)
* **Installer safety** — `--list-tools` flag added; empty/typo'd tool IDs rejected with specific errors (#2346)
* **Channel and dist-tag handling** — installer launched from a prerelease (e.g. `@next`) now defaults external module channels to `next` instead of silently downgrading to stable (#2321); stable publishes advance the `@next` dist-tag so prerelease users no longer leapfrog or miss update notifications (#2320)
* **Architecture validation gate** — step-07 validation template no longer ships pre-checked; status field is now templated against actual checklist completion (#2347)
* **bmad-help data integrity** — `bmad-help.csv` is no longer transformed at merge time and is emitted in its documented schema; 31 misaligned rows in core/bmm `module-help.csv` repaired (#2349)
* **Config robustness** — malformed `module.yaml` (scalars, arrays) is now rejected before crash (#2348)
* **Legacy cleanup** — pre-v6.2.0 wrapper skills (`bmad-bmm-*`, `bmad-agent-bmm-*`) are removed automatically on upgrade so they no longer error with missing-file warnings (#2315)
### 📚 Docs
* Complete Chinese (zh-CN) translations for `named-agents.md` and `expand-bmad-for-your-org.md`; localized BMad Ecosystem sidebar (CIS, BMB, TEA, WDS) across zh-cn, vi-vn, fr-fr, cs-cz (#2355)
Override any module config option with `--set <module>.<key>=<value>` (repeatable). Run `--list-options [module]` to see locally-known official keys (built-in modules plus any external officials cached on this machine):
```bash
npx bmad-method install --yes \
--modules bmm --tools claude-code \
--set bmm.project_knowledge=research \
--set bmm.user_skill_level=expert
```
[See all installation options](https://docs.bmad-method.org/how-to/non-interactive-installation/)
> **Not sure what to do?** Ask `bmad-help` — it tells you exactly what's next and what's optional. You can also ask questions like `bmad-help I just finished the architecture, what do I do next?`
@ -68,16 +77,26 @@ BMad Method extends with official modules for specialized domains. Available dur
| **[Game Dev Studio (BMGD)](https://github.com/bmad-code-org/bmad-module-game-dev-studio)** | Game development workflows (Unity, Unreal, Godot) |
V4 shipped web bundles. V6 brings them back, new and improved.
Web bundles package selected BMad skills for installation as **Google Gemini Gems** and **ChatGPT Custom GPTs**. Use them to do the upfront planning work (brainstorming, product briefs, PRDs, PRFAQs, UX specs, market and industry research) in your web LLM subscription, then bring the polished artifacts into your IDE for implementation. Planning runs on a flat-rate subscription instead of metered IDE tokens, which is a meaningful cost saver on longer engagements. Choose the best model available to you in Gemini or ChatGPT.
Current shelf: brainstorming, product brief, PRFAQ, PRD, UX, market & industry research.
**Browse and install at [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)**. One card per bundle, inline install steps for Gemini and ChatGPT, one-click ZIP download. See [the web bundles guide](https://docs.bmad-method.org/explanation/web-bundles/) for the concept.
## Documentation
[BMad Method Docs Site](https://docs.bmad-method.org) — Tutorials, guides, concepts, and reference
**Quick links:**
- [Getting Started Tutorial](https://docs.bmad-method.org/tutorials/getting-started/)
- [Upgrading from Previous Versions](https://docs.bmad-method.org/how-to/upgrade-to-v6/)
description: Přimějte LLM přehodnotit svou práci pomocí strukturovaných metod uvažování
sidebar:
order: 6
order: 3
---
Přimějte LLM přehodnotit, co právě vygeneroval. Vyberete metodu uvažování, LLM ji aplikuje na svůj vlastní výstup, a vy rozhodnete, zda si vylepšení ponecháte.
description: Jak architektura zabraňuje konfliktům, když více agentů implementuje systém
sidebar:
order: 4
order: 5
---
Když více AI agentů implementuje různé části systému, mohou dělat protichůdná technická rozhodnutí. Dokumentace architektury tomu zabraňuje stanovením sdílených standardů.
description: Jak project-context.md vede AI agenty s pravidly a preferencemi vašeho projektu
sidebar:
order: 7
order: 9
---
Soubor `project-context.md` je implementační průvodce vašeho projektu pro AI agenty. Podobně jako „ústava“ v jiných vývojových systémech zachycuje pravidla, vzory a preference, které zajišťují konzistentní generování kódu napříč všemi workflow.
description: Pochopení toho, proč je fáze solutioningu klíčová pro projekty s více epicy
sidebar:
order: 3
order: 4
---
Fáze 3 (Solutioning) překládá **co** budovat (z plánování) na **jak** to budovat (technický návrh). Tato fáze zabraňuje konfliktům agentů v projektech s více epicy tím, že dokumentuje architektonická rozhodnutí před zahájením implementace.
description: Reference BMad skills — co to je, jak fungují a kde je najít.
sidebar:
order: 3
order: 4
---
Skills jsou předpřipravené prompty, které načítají agenty, spouštějí workflow nebo provádějí úkoly ve vašem IDE. Instalátor BMad je generuje z vašich nainstalovaných modulů při instalaci. Pokud později přidáte, odeberete nebo změníte moduly, přeinstalujte pro synchronizaci skills (viz [Řešení problémů](#řešení-problémů)).
description: Reference všech vestavěných úkolů a workflow dostupných v každé instalaci BMad bez dalších modulů.
sidebar:
order: 2
order: 3
---
Každá instalace BMad zahrnuje sadu základních skills, které lze použít v kombinaci s čímkoli — samostatné úkoly a workflow, které fungují napříč všemi projekty, všemi moduly a všemi fázemi. Ty jsou vždy dostupné bez ohledu na to, které volitelné moduly nainstalujete.
@ -18,7 +18,7 @@ Spusťte jakýkoli základní nástroj zadáním jeho názvu skillu (např. `bma
| [`bmad-help`](#bmad-help) | Task | Kontextové poradenství, co dělat dál |
| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Task | Vyčerpávající analýza větvících cest pro neošetřené hraniční případy |
@ -97,32 +97,6 @@ Kouzlo se děje v nápadech 50–100. Workflow povzbuzuje generování 100+ náp
**Výstup:** Real-time multi-agentní konverzace s udržovanými osobnostmi agentů
## bmad-distillator
**Bezeztrátová LLM-optimalizovaná komprese zdrojových dokumentů.** — Produkuje husté, tokenově efektivní destiláty, které zachovávají všechny informace pro následné LLM zpracování. Ověřitelné prostřednictvím round-trip rekonstrukce.
**Použijte když:**
- Dokument je příliš velký pro kontextové okno LLM
- Potřebujete tokenově efektivní verze výzkumů, specifikací nebo plánovacích artefaktů
- Chcete ověřit, že během komprese nebyly ztraceny žádné informace
**Jak to funguje:**
1. **Analýza** — Čte zdrojové dokumenty, identifikuje hustotu informací a strukturu
3. **Ověření** — Kontroluje úplnost pro zajištění zachování všech informací
4. **Validace** (volitelné) — Round-trip rekonstrukční test dokazuje bezeztrátovou kompresi
**Vstup:**
- `source_documents` (povinné) — Cesty k souborům, složkám nebo glob vzory
- `downstream_consumer` (volitelné) — Co to konzumuje (např. „tvorba PRD“)
- `token_budget` (volitelné) — Přibližná cílová velikost
- `--validate` (příznak) — Spuštění round-trip rekonstrukčního testu
**Výstup:** Destilátové markdown soubory s reportem kompresního poměru (např. „3.2:1“)
## bmad-advanced-elicitation
**Iterativní zdokonalování LLM výstupu metodami elicitace.** — Vybírá z knihovny elicitačních technik pro systematické zlepšování obsahu více průchody.
description: Doplňkové moduly pro tvorbu vlastních agentů, kreativní inteligenci, vývoj her a testování
sidebar:
order: 4
order: 5
---
BMad se rozšiřuje prostřednictvím oficiálních modulů, které vyberete během instalace. Tyto doplňkové moduly poskytují specializované agenty, workflow a úkoly pro specifické domény nad rámec vestavěného jádra a BMM (Agile suite).
description: Srovnání vestavěného QA agenta (Quinn) s modulem Test Architect (TEA) pro automatizaci testů.
sidebar:
order: 5
order: 6
---
BMad poskytuje dvě testovací cesty: vestavěného QA agenta pro rychlé generování testů a instalovatelný modul Test Architect pro podnikovou testovací strategii.
@ -14,7 +14,7 @@ Vytvářejte software rychleji pomocí pracovních postupů řízených AI se sp
- Efektivně používat agenty a pracovní postupy
:::note[Předpoklady]
- **Node.js 20+** — Vyžadováno pro instalátor
- **Node.js 20.12+** — Vyžadováno pro instalátor
- **Git** — Doporučeno pro správu verzí
- **AI-powered IDE** — Claude Code, Cursor nebo podobné
- **Nápad na projekt** — I jednoduchý stačí pro učení
@ -150,7 +150,7 @@ Všechny workflow v této fázi jsou volitelné:
- Spusťte `bmad-quick-dev` — zvládne plánování i implementaci v jednom workflow, přeskočte k implementaci
:::note[UX Design (volitelné)]
Pokud má váš projekt uživatelské rozhraní, vyvolejte **UX-Designer agenta** (`bmad-agent-ux-designer`) a spusťte UX design workflow (`bmad-create-ux-design`) po vytvoření PRD.
Pokud má váš projekt uživatelské rozhraní, vyvolejte **UX-Designer agenta** (`bmad-agent-ux-designer`) a spusťte UX design workflow (`bmad-ux`) po vytvoření PRD.
description: Push the LLM to rethink its work using structured reasoning methods
sidebar:
order: 6
order: 4
---
Make the LLM reconsider what it just generated. You pick a reasoning method, it applies that method to its own output, you decide whether to keep the improvements.
description: What brainstorming, research, product briefs, and PRFAQs are — and when to use each
sidebar:
order: 1
order: 2
---
The Analysis phase (Phase 1) helps you think clearly about your product before committing to building it. Every tool in this phase is optional, but skipping analysis entirely means your PRD is built on assumptions instead of insight.
description: LLM-assisted human-in-the-loop review that guides you through a change from purpose to details
sidebar:
order: 3
order: 8
---
`bmad-checkpoint-preview` is an interactive, LLM-assisted human-in-the-loop review workflow. It walks you through a code change — from purpose and context into details — so you can make an informed decision about whether to ship, rework, or dig deeper.
They each have a hardcoded identity (name, title, domain) and a customizable layer (role, principles, communication style, icon, menu). You can rewrite Mary's principles or add menu items; you can't rename her — that's deliberate. Brand recognition survives customization so "hey Mary" always activates the analyst, regardless of how a team has shaped her behavior.
description: How architecture prevents conflicts when multiple agents implement a system
sidebar:
order: 4
order: 6
---
When multiple AI agents implement different parts of a system, they can make conflicting technical decisions. Architecture documentation prevents this by establishing shared standards.
description: How project-context.md guides AI agents with your project's rules and preferences
sidebar:
order: 7
order: 12
---
The `project-context.md` file is your project's implementation guide for AI agents. Similar to a "constitution" in other development systems, it captures the rules, patterns, and preferences that ensure consistent code generation across all workflows.
description: BMad skills packaged for Google Gemini Gems and ChatGPT Custom GPTs
---
Run the planning side of BMad in your web LLM subscription, then bring the artifacts into your IDE.
## What is a Web Bundle?
A web bundle is a BMad skill repackaged for installation as a **Google Gemini Gem** or **ChatGPT Custom GPT**. Each bundle includes a `SKILL.md` protocol you upload as a knowledge file, an `INSTRUCTIONS.md` block you paste into the Gem or GPT instructions, and any data files the skill needs (CSVs, templates, validation checklists, additionally progressively disclosed content). The persona lives in the pasted instructions; the protocol lives in the knowledge file. Swap personas without touching the protocol.
Setup is not one-click, but the steps are guided. **Install from [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)**. The site lists every bundle in a card grid, shows you the Gemini and ChatGPT install steps inline, and hands you the ZIP download. That is the supported install path; the pattern is the same across the shelf, so once you've installed one the next one is mechanical.
V4 of BMad shipped web bundles. V6 brings them back, rewritten for the current Gem and Custom GPT platforms with Canvas, Deep Research, and image generation in mind.
## Why use them
Planning work and implementation work want different tools. Web bundles let each use the right one.
| Concern | Web LLM (Gem or GPT) | IDE (Claude Code, Cursor) |
| --- | --- | --- |
| Cost model | Flat-rate subscription | Metered tokens |
| Strongest at | Conversation, Canvas, Deep Research, images | Files, terminal, codebase context |
| Best for | Brainstorming, briefs, PRDs, research | Implementation, refactoring, code review |
Running a full PRD or market research conversation in an IDE burns tokens that a Gem or Custom GPT handles for the price of your existing subscription. The polished artifact then drops into your repo and Claude Code or Cursor takes it from there.
:::tip[Plan in the web, build in the IDE]
The cost saving compounds on longer engagements. A PRFAQ pass and three rounds of research in a Gem cost zero marginal dollars; the same work in an IDE is real spend.
:::
## What's in the shelf
The current set of bundles covers the analysis and planning phases:
| PRFAQ Coach | Analysis | Working Backwards (Bezos) |
| PRD Coach | Planning | Cagan |
| UX Coach | Planning | Norman |
| Market & Industry Research | Analysis | Porter and Christensen |
Each bundle carries a default persona inherited from its owning BMad agent (where one exists) and a contrasting swap example to demonstrate the voice change pattern.
## How a session works
1. **Open the Gem or Custom GPT.** Persona greets in character and opens conversational discovery.
2. **Discover scope.** The persona asks what you're trying to do, what you have on hand, what constraints apply. No form fill.
3. **Do the work in Canvas.** The protocol opens Canvas at session start and updates it continuously. Mermaid diagrams and HTML tables go in alongside the prose.
4. **Hand off.** When you're done, you have a Canvas document you can export, paste into your repo, or feed to a BMad skill in your IDE for the next phase.
For bundles that integrate Deep Research (currently Market & Industry Research), the persona drafts a Deep Research brief mid-session for you to paste into Gemini's or ChatGPT's Deep Research mode, then ingests the returned report.
## When to use a web bundle
- You're doing the upfront thinking for a project and you want a focused tool with persona, Canvas, and Deep Research.
- You want to keep IDE token spend for actual coding.
- You're sharing the planning artifact with collaborators who don't have your IDE setup.
## When to stay in the IDE
- The work needs to read or modify code in your repo.
- You're already mid-implementation and want to keep context.
- You don't have a Gemini Advanced or ChatGPT Plus subscription.
## Updating and customizing
Bundles evolve. When you pull a newer version of a bundle, the typical update is to its knowledge files (the `SKILL.md` protocol and any attached templates, CSVs, or validation checklists). Re-upload those into your Gem or Custom GPT to take the update. The instructions block usually does not change.
If you want to customize a bundle for your team or your voice, do it in the **instructions block** you pasted into the Gem or GPT, not in the knowledge files. The instructions block is where the persona, preferences, and any local overrides live; the knowledge files are the protocol the bundle ships with. Keeping customization in the instructions block means future updates are a swap-the-attachments operation, not a merge-your-edits-back-in operation.
:::tip[Customize the instructions, attach the knowledge]
Persona swaps, default user name, team-specific guardrails, preferred phrasing: all of that belongs in the pasted instructions block. The knowledge files stay stock so you can refresh them without losing your changes.
:::
## Building your own
Web bundles are generated from BMad skills using the `bmad-os-skill-to-bundle` utility skill. Point it at any BMad skill folder and it produces the bundle files with persona inheritance from the owning agent.
Install any bundle from [bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/).
description: Pousser le LLM à repenser son travail en utilisant des méthodes de raisonnement structurées
sidebar:
order: 8
order: 3
---
Faites repenser au LLM ce qu'il vient de générer. Vous choisissez une méthode de raisonnement, il l'applique à sa propre sortie, et vous décidez de conserver ou non les améliorations.
description: Revue assistée par LLM, avec intervention humaine, qui vous guide à travers une modification, de son objectif jusqu’aux détails
sidebar:
order: 4
order: 7
---
`bmad-checkpoint-preview` est un workflow de revue interactif, assisté par LLM, avec intervention humaine. Il vous guide à travers une modification de code — de l'intention et du contexte jusqu'aux détails — afin que vous puissiez prendre une décision éclairée sur la mise en production, la refonte ou l'approfondissement.
description: Comment bmad-investigate traite chaque problème comme une scène d'enquête, classe les preuves et produit un dossier structuré sur lequel les ingénieurs peuvent agir
sidebar:
order: 9
---
Vous confiez à `bmad-investigate` un journal de plantage, une trace de pile, ou simplement un « ça marchait avant, plus
maintenant ». Le skill prend le relais avec la discipline d'enquête le temps de l'exécution. Il ne se met pas à
corriger. Il ouvre un dossier d'enquête.
Chaque constatation reçoit une note. Chaque hypothèse a un statut. Les fausses pistes sont conservées, pas effacées. Le
livrable est un document qu'un autre ingénieur peut reprendre à froid.
Cette page explique pourquoi l'enquête est une discipline à part entière, et ce que le skill apporte qu'un workflow de
développement classique n'apporte pas.
## Le problème du « débogue, c'est tout »
Le débogage classique mélange trois activités : examiner les preuves, raisonner sur la cause, et modifier le code pour
tester la théorie. Quand elles sont mélangées, deux modes de défaillance apparaissent.
Le premier est le **verrouillage narratif**[^1]. La première histoire plausible devient la théorie de travail, et chaque
observation est tordue pour la confirmer. Le bug reste non corrigé jusqu'à ce que quelqu'un abandonne et reparte de
zéro. Des heures plus tard.
Le second est l'**amnésie probatoire**. Vous avez tracé quelque chose, l'avez écarté, mais n'avez pas écrit pourquoi.
Deux jours plus tard, avec un regard frais, vous le retracez. Pire encore, un collègue reprend le bug et refait la même
impasse que vous aviez déjà éliminée.
La conception du skill est une réponse directe à ces deux modes.
## Classement des preuves
Chaque constatation dans une enquête appartient à l'une de trois catégories.
- **Confirmé.** Directement observé dans les logs, le code ou les dumps ; cité avec une référence spécifique (un
`chemin:ligne`, un horodatage de log, un hash de commit). Si quelqu'un demande « comment le sais-tu ? », vous pointez
la citation.
- **Déduit.** Découle logiquement de preuves confirmées ; la chaîne de raisonnement est explicite. Si une étape de la
chaîne est fausse, la déduction est fausse, et on peut voir précisément quelle étape.
- **Hypothétique.** Plausible mais non confirmé. Énonce quelle preuve confirmerait ou réfuterait, et déclare d'avance ce
qui le clôturerait. Les hypothèses sont explicitement *non factuelles*.
Le classement n'est pas une posture d'humilité. Il rend le dossier lisible. Un lecteur peut parcourir la section
Confirmé pour savoir ce qui est vrai, la section Déduit pour savoir ce qui en découle, et la section Hypothétique pour
savoir ce qui reste ouvert. Confondre les trois est la première raison pour laquelle les enquêtes dérapent.
## Tête de pont d'abord
L'enquête ne part jamais d'une théorie. Elle part d'une seule preuve confirmée et étend la zone à partir de là. Cette
preuve peut être un message d'erreur précis, une trame de pile, ou une entrée de log horodatée.
C'est l'inverse de la manière dont les enquêtes se déroulent souvent : quelqu'un a une intuition, construit une théorie,
puis cherche les preuves qui la soutiennent. L'intuition peut être correcte ; la *méthode* est fragile parce qu'elle
fait du biais de confirmation[^2] le comportement par défaut.
Une tête de pont est un fait sur lequel vous pouvez revenir quand le raisonnement devient flou. Si une déduction vous
emmène quelque part d'étrange, vous pouvez remonter jusqu'à la tête de pont et essayer une autre branche. Sans elle,
vous ne savez pas quelle étape annuler.
Quand les preuves sont rares, le skill le dit et bascule en exploration guidée par hypothèses : formuler des hypothèses
à partir de ce qui est disponible, identifier ce qui testerait chacune, présenter une liste priorisée de données à
collecter. L'absence de preuve est elle-même une constatation.
## Discipline des hypothèses
Les hypothèses ne sont jamais supprimées du dossier. Quand une preuve en confirme ou en réfute une, son champ **Statut**
passe d'Ouvert à Confirmé ou Réfuté, et une **Résolution** explique quelle preuve a tranché.
Cette règle a un coût réel : les dossiers grossissent. Le bénéfice est réel aussi. L'historique complet du raisonnement
fait partie du livrable. Six mois plus tard, quand un bug similaire surgit, le prochain enquêteur peut lire le dossier
original et voir quelles pistes ont déjà été éliminées et pourquoi. Sans cet historique, chaque nouvel enquêteur refait
les mêmes impasses.
Cela discipline aussi l'enquêteur du présent. Si vous ne pouvez pas supprimer une hypothèse fausse, vous devez la
réfuter avec une preuve citée. L'abandonner discrètement quand elle devient gênante n'est plus une option.
## Remettre en question la prémisse
La description du problème par l'utilisateur est une hypothèse, pas un fait. « Le cache est cassé » est quelque chose
que l'utilisateur *croit*. Avant que le skill ne construise une enquête autour, les affirmations techniques sont
vérifiées de manière indépendante. Si la preuve contredit la prémisse, le rapport le dit directement.
C'est l'instinct de l'enquêteur : le récit du témoin est une donnée, pas la vérité. Parfois le bug rapporté est réel
mais mal étiqueté. Parfois le symptôme décrit est en aval d'une cause différente. Les enquêtes qui prennent la prémisse
pour argent comptant diagnostiquent le mauvais défaut, et le bug revient sous une forme légèrement différente.
## Une marche calibrée
Le skill est une seule procédure, pas deux modes. Il calibre la part d'investigation de défaut versus la part
d'exploration de zone que l'entrée demande, sur une échelle continue.
Un cas piloté par symptôme (un ticket, un plantage, un message d'erreur, un « ça marchait avant ») penche vers le suivi
d'hypothèses, la reconstruction de la chronologie et une direction de correction. Un cas sans symptôme (comprendre un
module avant de le toucher, évaluer la réutilisabilité, bâtir un modèle mental) penche vers la cartographie
entrées/sorties, le filtrage du flux de contrôle et un plan de vérification. La plupart des cas réels se situent quelque
part entre les deux, et le dossier reflète l'équilibre que les preuves ont exigé.
La discipline est la même quel que soit l'endroit de l'échelle où se situe un cas : tête de pont d'abord, classement
des preuves, suivi des hypothèses, jamais effacer. La sortie est toujours
`{implementation_artifacts}/investigations/{slug}-investigation.md`, avec les sections qui ne s'appliquent pas à un cas
laissées vides ou omises.
Quand un bug profond exige de comprendre un sous-système plus large, la procédure intègre en ligne les techniques de
cartographie entrées/sorties, de filtrage du flux de contrôle, de raisonnement à rebours depuis les sorties et de
traçage des frontières inter-composants[^3]. Le modèle de la zone atterrit dans le même dossier. Pas de changement de
mode.
## La méthodologie vit dans le skill
La discipline d'enquête est une propriété du skill lui-même. Quiconque invoque `bmad-investigate` adopte la méthodologie
et le style de communication pour l'exécution : précision clinique, langage centré sur la preuve, pas de prudence
inutile, présentation en dossier de cas. Quand le skill se termine, l'appelant retrouve sa voix d'avant. Pas de
changement de persona, juste un déplacement de ton issu des principes du skill.
Cela compte parce que l'enquête et l'implémentation récompensent des instincts différents. Les enquêteurs sont lents et
précis. Les implémenteurs sont rapides et confiants. Le même cerveau faisant les deux dans une seule session finit par
mal faire les deux. Le skill délimite la posture d'enquête en ligne, sans changement de contexte vers une identité
séparée.
## Ce que vous obtenez
Un fichier d'enquête achevé :
- Sépare les constatations Confirmées (avec citations) des Déductions et des Hypothèses
- Préserve toutes les hypothèses jamais formulées, avec leur Statut final et leur Résolution
- Reconstruit une chronologie des événements à partir de plusieurs sources de preuves
- Identifie les lacunes de données et ce qu'elles résoudraient
- Fournit des conclusions actionnables ancrées dans les preuves
- Inclut un plan de reproduction quand une cause racine est identifiée
- Maintient un backlog d'enquête de pistes encore à explorer
Donnez-le à un ingénieur qui n'était pas là, et il comprend ce qui s'est passé, ce qui est connu, et ce qui reste
incertain. C'est la barre.
## L'idée plus large
La plupart du « débogage par IA » d'aujourd'hui mélange preuves, raisonnement et changements de code en un seul flux de
texte plausible. Le signal est difficile à trouver, les impasses se répètent, et le dossier, s'il en existe un, est un
journal de chat que personne ne veut lire.
`bmad-investigate` traite l'enquête comme une discipline avec son propre livrable. La preuve a une note. Les hypothèses
ont un statut. Les fausses pistes sont documentées, pas effacées. Le dossier survit à la session.
Quand le prochain bug ressemblant à un que vous avez déjà vu apparaîtra, vous aurez un point de départ qui ne sera pas
une invite vide.
## Glossaire
[^1]: **Verrouillage narratif** : phénomène cognitif par lequel un raisonnement adopte la première explication plausible
et l'enrichit progressivement, devenant de plus en plus difficile à abandonner même face à des preuves contraires.
[^2]: **Biais de confirmation** : tendance cognitive à rechercher, interpréter et favoriser les informations qui
confirment des croyances préexistantes, tout en ignorant ou minimisant celles qui les contredisent.
[^3]: **Passage de frontière** : transition entre deux zones d'exécution distinctes (langage, processus, machine,
client/serveur, code/configuration). Les frontières concentrent les bugs car chaque côté suppose que l'autre s'est
description: Comment l'architecture empêche les conflits lorsque plusieurs agents implémentent un système
sidebar:
order: 6
order: 5
---
Lorsque plusieurs agents IA implémentent différentes parties d'un système, ils peuvent prendre des décisions techniques contradictoires. La documentation d'architecture prévient cela en établissant des standards partagés.
description: Comment project-context.md guide les agents IA avec les règles et préférences de votre projet
sidebar:
order: 10
order: 11
---
Le fichier `project-context.md` est le guide d'implémentation de votre projet pour les agents IA. Similaire à une « constitution » dans d'autres systèmes de développement, il capture les règles, les patterns et les préférences qui garantissent une génération de code cohérente à travers tous les workflows.
description: Comprendre pourquoi la phase de solutioning est critique pour les projets multi-epics
sidebar:
order: 5
order: 4
---
La Phase 3 (Solutioning) traduit le **quoi** construire (issu de la Planification) en **comment** le construire (conception technique). Cette phase évite les conflits entre agents dans les projets multi-epics en documentant les décisions architecturales avant le début de l'implémentation.
@ -18,7 +18,7 @@ Exécutez n'importe quel outil principal en tapant son nom de compétence (par e
| [`bmad-help`](#bmad-help) | Tâche | Obtenir des conseils contextuels sur la prochaine étape |
| [`bmad-brainstorming`](#bmad-brainstorming) | Workflow | Faciliter des sessions de brainstorming interactives |
| [`bmad-party-mode`](#bmad-party-mode) | Workflow | Orchestrer des discussions de groupe multi-agents |
| [`bmad-distillator`](#bmad-distillator) | Tâche | Compression sans perte optimisée pour LLM de documents |
| [`bmad-spec`](#bmad-spec) | Workflow | Distill any intent input into a SPEC kernel and companions (translation pending) |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tâche | Pousser la sortie LLM à travers des méthodes de raffinement itératives |
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tâche | Revue cynique qui trouve ce qui manque et ce qui ne va pas |
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tâche | Analyse exhaustive des chemins de branchement pour les cas limites non gérés |
@ -97,33 +97,6 @@ La magie se produit dans les idées 50–100. Le workflow encourage la générat
**Sortie :** Conversation multi-agents en temps réel avec des personnalités d'agents maintenues
## bmad-distillator
**Compression sans perte optimisée pour LLM de documents sources.** — Produit des distillats denses et efficaces en tokens qui préservent toute l'information pour la consommation par des LLM en aval. Vérifiable par reconstruction aller-retour.
**Utilisez-le quand :**
- Un document est trop volumineux pour la fenêtre de contexte d'un LLM
- Vous avez besoin de versions économes en tokens de recherches, spécifications ou artefacts de planification
- Vous voulez vérifier qu'aucune information n'est perdue pendant la compression
- Les agents auront besoin de référencer et de trouver fréquemment des informations dedans
**Fonctionnement :**
1. **Analyser** — Lit les documents sources, identifie la densité d'information et la structure
2. **Compresser** — Convertit la prose en format dense de liste de points, supprime le formatage décoratif
3. **Vérifier** — Vérifie l'exhaustivité pour s'assurer que toute l'information originale est préservée
4. **Valider** (optionnel) — Le test de reconstruction aller-retour prouve la compression sans perte
**Entrée :**
- `source_documents` (requis) — Chemins de fichiers, chemins de dossiers ou motifs glob
- `downstream_consumer` (optionnel) — Ce qui va le consommer (par ex., "création de PRD")
- `--validate` (drapeau) — Exécuter le test de reconstruction aller-retour
**Sortie :** Fichier(s) markdown distillé(s) avec rapport de ratio de compression (par ex., "3.2:1")
## bmad-advanced-elicitation
**Passer la sortie du LLM à travers des méthodes de raffinement itératives.** — Sélectionne depuis une bibliothèque de techniques d'élicitation pour améliorer systématiquement le contenu à travers multiples passages.
La méthode BMad (BMM) est un module de l'écosystème BMad, conçu pour suivre les meilleures pratiques de l'ingénierie du contexte et de la planification. Les agents IA fonctionnent de manière optimale avec un contexte clair et structuré. Le système BMM construit ce contexte progressivement à travers 4 phases distinctes — chaque phase, et plusieurs workflows optionnels au sein de chaque phase, produisent des documents qui alimentent la phase suivante, afin que les agents sachent toujours quoi construire et pourquoi.
La méthode BMad (BMM) est un module de l'écosystème BMad, conçu pour suivre les meilleures pratiques de l'ingénierie du
contexte et de la planification. Les agents IA fonctionnent de manière optimale avec un contexte clair et structuré. Le
système BMM construit ce contexte progressivement à travers 4 phases distinctes — chaque phase, et plusieurs workflows
optionnels au sein de chaque phase, produisent des documents qui alimentent la phase suivante, afin que les agents
sachent toujours quoi construire et pourquoi.
La logique et les concepts proviennent des méthodologies agiles qui ont été utilisées avec succès dans l'industrie comme cadre mental de référence.
La logique et les concepts proviennent des méthodologies agiles qui ont été utilisées avec succès dans l'industrie comme
cadre mental de référence.
Si à tout moment vous ne savez pas quoi faire, le skill `bmad-help` vous aidera à rester sur la bonne voie ou à savoir quoi faire ensuite. Vous pouvez toujours vous référer à cette page également — mais `bmad-help` est entièrement interactif et beaucoup plus rapide si vous avez déjà installé la méthode BMad. De plus, si vous utilisez différents modules qui ont étendu la méthode BMad ou ajouté d'autres modules complémentaires non extensifs — `bmad-help` évolue pour connaître tout ce qui est disponible et vous donner les meilleurs conseils du moment.
Si à tout moment vous ne savez pas quoi faire, le skill `bmad-help` vous aidera à rester sur la bonne voie ou à savoir
quoi faire ensuite. Vous pouvez toujours vous référer à cette page également — mais `bmad-help` est entièrement
interactif et beaucoup plus rapide si vous avez déjà installé la méthode BMad. De plus, si vous utilisez différents
modules qui ont étendu la méthode BMad ou ajouté d'autres modules complémentaires non extensifs — `bmad-help` évolue
pour connaître tout ce qui est disponible et vous donner les meilleurs conseils du moment.
Note finale importante : Chaque workflow ci-dessous peut être exécuté directement avec l'outil de votre choix via un skill ou en chargeant d'abord un agent et en utilisant l'entrée du menu des agents.
Note finale importante : Chaque workflow ci-dessous peut être exécuté directement avec l'outil de votre choix via un
skill ou en chargeant d'abord un agent et en utilisant l'entrée du menu des agents.
<iframesrc="/workflow-map-diagram-fr.html"title="Diagramme de la carte des workflows de la méthode BMad"width="100%"height="100%"style="border-radius: 8px; border: 1px solid #334155; min-height: 900px;"></iframe>
@ -21,14 +31,15 @@ Note finale importante : Chaque workflow ci-dessous peut être exécuté directe
## Phase 1 : Analyse (Optionnelle)
Explorez l’espace problème et validez les idées avant de vous engager dans la planification. [**Découvrez ce que fait chaque outil et quand l’utiliser**](../explanation/analysis-phase.md).
Explorez l’espace problème et validez les idées avant de vous engager dans la planification. [**Découvrez ce que fait
chaque outil et quand l’utiliser**](../explanation/analysis-phase.md).
| `bmad-brainstorming` | Brainstormez des idées de projet avec l’accompagnement guidé d’un coach de brainstorming | `brainstorming-report.md` |
| `bmad-domain-research`, `bmad-market-research`, `bmad-technical-research` | Validez les hypothèses de marché, techniques ou de domaine | Rapport de recherches |
| `bmad-product-brief` | Capturez la vision stratégique — idéal lorsque votre concept est clair | `product-brief.md` |
| `bmad-prfaq` | Working Backwards — éprouvez et forgez votre concept produit | `prfaq-{project}.md`|
| `bmad-prfaq` | Working Backwards — éprouvez et forgez votre concept produit | `prfaq-{project}.md` |
## Phase 2 : Planification
@ -36,60 +47,75 @@ Définissez ce qu'il faut construire et pour qui.
| `bmad-quick-dev` | Flux rapide unifié — clarifie l'intention, planifie, implémente, révise et présente | `spec-*.md` + code |
## Gestion du Contexte
Chaque document devient le contexte de la phase suivante. Le PRD[^2] indique à l'architecte quelles contraintes sont importantes. L'architecture indique à l'agent de développement quels modèles suivre. Les fichiers de story fournissent un contexte focalisé et complet pour l'implémentation. Sans cette structure, les agents prennent des décisions incohérentes.
Chaque document devient le contexte de la phase suivante. Le PRD[^2] indique à l'architecte quelles contraintes sont
importantes. L'architecture indique à l'agent de développement quels modèles suivre. Les fichiers de story fournissent
un contexte focalisé et complet pour l'implémentation. Sans cette structure, les agents prennent des décisions
incohérentes.
### Contexte du Projet
:::tip[Recommandé]
Créez `project-context.md` pour vous assurer que les agents IA suivent les règles et préférences de votre projet. Ce fichier fonctionne comme une constitution pour votre projet — il guide les décisions d'implémentation à travers tous les workflows. Ce fichier optionnel peut être généré à la fin de la création de l'architecture, ou dans un projet existant il peut également être généré pour capturer ce qui est important de conserver aligné avec les conventions actuelles.
Créez `project-context.md` pour vous assurer que les agents IA suivent les règles et préférences de votre projet. Ce
fichier fonctionne comme une constitution pour votre projet — il guide les décisions d'implémentation à travers tous les
workflows. Ce fichier optionnel peut être généré à la fin de la création de l'architecture, ou dans un projet existant
il peut également être généré pour capturer ce qui est important de conserver aligné avec les conventions actuelles.
:::
**Comment le créer :**
- **Manuellement** — Créez `_bmad-output/project-context.md` avec votre pile technologique et vos règles d'implémentation
- **Générez-le** — Exécutez `bmad-generate-project-context` pour l'auto-générer à partir de votre architecture ou de votre codebase
- **Manuellement** — Créez `_bmad-output/project-context.md` avec votre pile technologique et vos règles
d'implémentation
- **Générez-le** — Exécutez `bmad-generate-project-context` pour l'auto-générer à partir de votre architecture ou de
votre codebase
[**En savoir plus sur project-context.md**](../explanation/project-context.md)
## Glossaire
[^1]: FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement **ce que le système doit faire** (fonctionnalités, comportements attendus) et **comment il doit le faire** (contraintes de performance, sécurité, fiabilité, ergonomie, etc.).
[^2]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur ce qui doit être construit et pourquoi.
[^3]: ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions techniques dans le temps.
[^1]: FR / NFR (Functional / Non-Functional Requirement) : exigences décrivant respectivement **ce que le système doit
faire** (fonctionnalités, comportements attendus) et **comment il doit le faire** (contraintes de performance, sécurité,
fiabilité, ergonomie, etc.).
[^2]: PRD (Product Requirements Document) : document de référence qui décrit les objectifs du produit, les besoins
utilisateurs, les fonctionnalités attendues, les contraintes et les critères de succès, afin d’aligner les équipes sur
ce qui doit être construit et pourquoi.
[^3]: ADR (Architecture Decision Record) : document qui consigne une décision d’architecture, son contexte, les options
envisagées, le choix retenu et ses conséquences, afin d’assurer la traçabilité et la compréhension des décisions
@ -14,7 +14,7 @@ Construisez des logiciels plus rapidement en utilisant des workflows propulsés
- Utiliser efficacement les agents et les workflows
:::note[Prérequis]
- **Node.js 20+** — Requis pour l'installateur
- **Node.js 20.12+** — Requis pour l'installateur
- **Git** — Recommandé pour le contrôle de version
- **IDE IA** — Claude Code, Cursor, ou similaire
- **Une idée de projet** — Même simple, elle fonctionne pour apprendre
@ -150,7 +150,7 @@ Tous les workflows de cette phase sont optionnels. [**Pas sûr de quel outil uti
- Exécutez `bmad-quick-dev` — il gère la planification et l'implémentation dans un seul workflow, passez directement à l'implémentation
:::note[Design UX (Optionnel)]
Si votre projet a une interface utilisateur, invoquez l'**agent Designer UX** (`bmad-agent-ux-designer`) et exécutez le workflow de design UX (`bmad-create-ux-design`) après avoir créé votre PRD.
Si votre projet a une interface utilisateur, invoquez l'**agent Designer UX** (`bmad-agent-ux-designer`) et exécutez le workflow de design UX (`bmad-ux`) après avoir créé votre PRD.
description: Five customization patterns that reshape BMad without forking — agent-wide rules, workflow conventions, external publishing, template swaps, and agent roster changes
description: Six customization patterns that reshape BMad without forking — agent-wide rules, workflow conventions, external publishing, template swaps, agent roster changes, and advanced integration patterns
sidebar:
order: 9
order: 11
---
BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through five recipes that cover most enterprise needs.
BMad's customization surface lets an organization reshape behavior without editing installed files or forking skills. This guide walks through six recipes that cover most enterprise needs.
:::note[Prerequisites]
@ -227,9 +227,79 @@ One sentence, loaded every session. It pairs with the `bmad-agent-dev.toml` cust
Keep the IDE file **succinct**. A dozen well-chosen lines are more effective than a sprawling list. Models read it every turn, and noise crowds out signal.
## Recipe 6: Advanced Integration Patterns
Several BMad workflows expose a richer configuration surface beyond the basics covered in Recipes 1–5. These patterns — on-demand knowledge sources, automatic output publishing, finalize-time doc standards, and swappable templates — appear across multiple workflows. Check a workflow's `customize.toml` to see which fields it exposes; the examples below use `bmad-prd` because it exposes all of them, but the same patterns apply wherever the field appears.
Connect the workflow to internal knowledge bases, competitive databases, or compliance references. The agent consults these on demand when the conversation surfaces a matching need — never preemptively.
```toml
# _bmad/custom/bmad-prd.toml (same pattern works in any workflow that exposes external_sources)
[workflow]
external_sources = [
"When the user mentions a competitor or market segment, query corp:competitive_db (category={project_name}) before drafting the differentiation section.",
Each entry is a natural-language directive naming the MCP tool, the trigger condition, and any fields the tool needs. If the tool is unavailable at runtime, the workflow falls back to standard behavior and notes the gap.
Route completed artifacts to external systems of record after the workflow finalizes. Unlike `on_complete` (Recipe 3), `external_handoffs` is a dedicated append array — team entries stack, and each handoff fires independently with graceful degradation if a tool is unavailable.
```toml
# _bmad/custom/bmad-prd.toml (same pattern works in any workflow that exposes external_handoffs)
[workflow]
external_handoffs = [
"After finalize, upload prd.md and addendum.md to Confluence via corp:confluence_upload (space_key='PROD', parent_page='PRDs', label='prd', author={user_name}). Capture and surface the returned page URL.",
"Mirror to Notion via notion:create_page (database_id='abc123', title='PRD: ' + {project_name}).",
]
```
If a named tool is unavailable, the handoff is skipped and flagged — local files always exist regardless.
### Finalize-time doc standards (`doc_standards`)
Apply org writing standards to human-consumed documents at finalize, after content is complete but before the user sees the output. Each entry is a `skill:`, `file:`, or plain-text directive; passes run as parallel subagents.
```toml
# _bmad/custom/bmad-prd.toml (same pattern works in any workflow that exposes doc_standards)
"All dates must use ISO 8601 format (YYYY-MM-DD).",
"Replace any use of 'leverage' with 'use'.",
]
```
`doc_standards` is an append array — team entries stack on top of whatever defaults the workflow ships with. Broader structural passes should come before narrower prose passes.
### Swappable templates and checklists
Workflows that produce structured documents typically expose template and checklist paths as overridable scalars. Point them at org-owned files under `{project-root}` to enforce a different structure without editing any source.
The agent adapts to whatever structure the template defines. Keep templates under `{project-root}/docs/` or `{project-root}/_bmad/custom/templates/` so they version alongside the override file. For multi-org repos, use `.user.toml` to let teams point at their own templates without touching the committed team file.
## Combining Recipes
All five recipes compose. A realistic enterprise override for `bmad-product-brief` might set `persistent_facts` (Recipe 2), `on_complete` (Recipe 3), and `brief_template` (Recipe 4) in one file. The agent-level rule (Recipe 1) lives in a separate file under the agent's name, central config (Recipe 5) pins the shared roster and team settings, and all four apply in parallel.
All six recipes compose. A realistic enterprise override for `bmad-product-brief` might set `persistent_facts` (Recipe 2), `on_complete` (Recipe 3), and `brief_template` (Recipe 4) in one file. The agent-level rule (Recipe 1) lives in a separate file under the agent's name, central config (Recipe 5) pins the shared roster and team settings, advanced integration patterns (Recipe 6) configure external sources and handoffs, and all layers apply in parallel.
| `--yes`, `-y` | Skip all prompts; accept flag values + defaults |
| `--directory <path>` | Install into this directory (default: current working dir) |
| `--modules <a,b,c>` | Exact module set. Core is auto-added. Not a delta — list everything you want kept. |
| `--tools <a,b>` | IDE/tool selection. Required for fresh `--yes` installs. Run `--list-tools` for valid IDs. |
| `--list-tools` | Print all supported tool/IDE IDs (with target directories) and exit. |
| `--action <type>` | `install`, `update`, or `quick-update`. Defaults based on existing install state. |
| `--custom-source <urls>` | Install custom modules from Git URLs or local paths |
| `--channel <stable\|next>` | Apply to all externals (aliased as `--all-stable` / `--all-next`) |
| `--all-stable` | Alias for `--channel=stable` |
| `--all-next` | Alias for `--channel=next` |
| `--next=<code>` | Put one module on next. Repeatable. |
| `--pin <code>=<tag>` | Pin one module to a specific tag. Repeatable. |
| `--set <module>.<key>=<value>` | Set any module config option non-interactively (preferred — see [Module config overrides](#module-config-overrides)). Repeatable. |
| `--list-options [module]` | Print every `--set` key for built-in and locally-cached official modules, then exit. Pass a module code to scope to one module. |
`--tools` is omitted intentionally — `--action update` reuses the tools configured during the first install.
**Mix channels — bmb on next, gds on stable:**
```bash
npx bmad-method install --yes --action update \
--modules bmm,bmb,cis,gds \
--next=bmb \
--tools none
--next=bmb
```
### Module config overrides
`--set <module>.<key>=<value>` lets you set any module config option non-interactively. It's repeatable and scales to every module — present and future. The flag is applied as a post-install patch: the installer runs its normal flow first, then `--set` upserts each value into `_bmad/config.toml` (team scope) or `_bmad/config.user.toml` (user scope), and into `_bmad/<module>/config.yaml` so declared values carry forward to the next install.
**Example — install bmm with explicit project knowledge and skill level:**
```bash
npx bmad-method install --yes \
--modules bmm \
--tools claude-code \
--set bmm.project_knowledge=research \
--set bmm.user_skill_level=expert
```
**Discover available keys for a module:**
```bash
npx bmad-method install --list-options bmm
```
`--list-options` (no argument) lists every key the installer can find locally — built-in modules (`core`, `bmm`) plus any currently cached official modules. The cache is per-machine and can be cleared, so previously installed officials won't appear on a fresh checkout or an ephemeral CI worker until they're installed again. Community and custom modules aren't enumerated here; read the module's `module.yaml` directly to see what keys it declares.
**How it works:**
- **Routing.** The patch step looks for `[modules.<module>] <key>` (or `[core] <key>`) in `config.user.toml` first; if found there, it updates that file. Otherwise it writes to the team-scope `config.toml`. So user-scope keys (e.g. `core.user_name`, `bmm.user_skill_level`) end up in `config.user.toml` and team-scope keys end up in `config.toml`, matching the partition the installer uses.
- **Verbatim values.** The value is written exactly as you provided it — no `result:` template rendering. To get the rendered form (e.g. `{project-root}/research`), pass it explicitly: `--set bmm.project_knowledge='{project-root}/research'`.
- **Carry-forward, declared keys.** Values for keys declared in `module.yaml` survive subsequent installs because they're also written to `_bmad/<module>/config.yaml`, which the installer reads as the prompt default on the next run.
- **Carry-forward, undeclared keys.** A value for a key the module's schema doesn't declare lands in `config.toml` for the current install but won't be re-emitted on the next install (the manifest writer's schema-strict partition drops unknown keys). Re-pass `--set` if you need it sticky, or edit `_bmad/config.toml` directly.
- **No validation.**`single-select` values aren't checked against the allowed choices, and unknown keys aren't rejected — whatever you assert is written.
- **Modules not in `--modules`.** Setting a value for a module you didn't include prints a warning and the value is dropped (no file gets created for an uninstalled module).
The legacy core shortcuts (`--user-name`, `--output-folder`, etc.) still work and remain documented for backward compatibility, but `--set core.user_name=...` is equivalent.
:::note[Works with quick-update]
`--set` is a post-install patch, so it applies the same way regardless of action type. Under `bmad install --action quick-update` (or `--yes` against an existing install, where quick-update is the default), `--set` patches the central config files at the end just like a regular install.
:::
:::caution[Rate limit on shared IPs]
Anonymous GitHub API calls are capped at 60/hour per IP. A single install hits the API once per external module to resolve the stable tag. Offices behind NAT, CI runner pools, and VPNs can collectively exhaust this.
@ -204,7 +244,7 @@ For cross-machine reproducibility, don't rely on rerunning the same `--modules`
@ -15,7 +15,7 @@ Use the BMad installer to add modules from the community registry, third-party G
- Installing modules from a private or self-hosted Git server
:::note[Prerequisites]
Requires [Node.js](https://nodejs.org) v20+ and `npx` (included with npm). Custom and community modules can be selected during a fresh install or added to an existing installation.
Requires [Node.js](https://nodejs.org) v20.12+ and `npx` (included with npm). Custom and community modules can be selected during a fresh install or added to an existing installation.
:::
## Community Modules
@ -68,7 +68,7 @@ Select **Yes**, then provide a source:
description: Install a BMad web bundle as a Google Gemini Gem or ChatGPT Custom GPT
---
Web bundles install from **[bmadcode.com/web-bundles](https://bmadcode.com/web-bundles/)**.
## Why a single front door
The site is the only supported install path for the shelf. It keeps the steps current as Gemini and ChatGPT evolve, always points at the newest tagged release, and lets one signup put you on the list for new bundles as they ship.
## What you'll do on the site
1. Pick a bundle from the card grid.
2. Open the install modal. Switch between the **Gemini Gem** and **ChatGPT GPT** tabs for the platform-specific steps.
3. Download the bundle ZIP (one click; one-time free signup for email-only members).
4. Follow the inline steps: create the Gem or Custom GPT, upload the knowledge files, paste the instructions block, save.
- For bundles that use **Deep Research** (currently Market & Industry Research), enable it from the prompt bar (Tools → Deep Research). Deep Research has its own plan limits.
## Customize the persona
Each bundle's `INSTRUCTIONS.md` (inside the ZIP) includes a **Persona Swap Example** above the paste boundary. Replace the `[persona]` block in your installed instructions with the swap example to change voice without changing the protocol. You can also write your own persona from scratch; the protocol stays the same.
## What you get
- A reusable Gem or Custom GPT scoped to one BMad planning capability.
- Polished artifacts (briefs, PRDs, research reports, UX specs) ready to drop into your IDE for implementation.
- Planning conversation runs on your existing web LLM subscription instead of metered IDE tokens.
:::caution[Persona drift]
Web LLMs occasionally drop persona partway through long sessions. If the model starts speaking out of character, remind it of its persona or start a fresh session.
:::
## Building your own
To turn an existing BMad skill into a web bundle, use the `bmad-os-skill-to-bundle` utility skill from [bmad-utility-skills](https://github.com/bmad-code-org/bmad-utility-skills). It produces the bundle files with persona inheritance from the owning agent and a swap-example contrast voice. Submit your bundle to the shelf by opening a PR on [BMAD-METHOD](https://github.com/bmad-code-org/BMAD-METHOD) that adds the bundle directory and an entry in `web-bundles/bundles.json`.
description: Reference for BMad skills — what they are, how they work, and where to find them.
sidebar:
order: 3
order: 4
---
Skills are pre-built prompts that load agents, run workflows, or execute tasks inside your IDE. The BMad installer generates them from your installed modules at install time. If you later add, remove, or change modules, re-run the installer to keep skills in sync (see [Troubleshooting](#troubleshooting)).
@ -52,7 +52,7 @@ Each skill is a directory containing a `SKILL.md` file. For example, a Claude Co
.claude/skills/
├── bmad-help/
│ └── SKILL.md
├── bmad-create-prd/
├── bmad-prd/
│ └── SKILL.md
├── bmad-agent-dev/
│ └── SKILL.md
@ -91,9 +91,9 @@ Workflow skills run a structured, multi-step process without loading an agent pe
| Example skill | Purpose |
| --- | --- |
| `bmad-product-brief` | Create a product brief — guided discovery when your concept is clear |
| `bmad-product-brief` | Create or update a product brief — guided discovery when your concept is clear |
| `bmad-prfaq` | [Working Backwards PRFAQ](../explanation/analysis-phase.md#prfaq-working-backwards) challenge to stress-test your product concept |
| `bmad-create-prd` | Create a Product Requirements Document |
| `bmad-prd` | Create, update, or validate a Product Requirements Document |
| `bmad-create-architecture` | Design system architecture |
| `bmad-create-epics-and-stories` | Create epics and stories |
| `bmad-dev-story` | Implement a story |
@ -124,7 +124,7 @@ The core module includes 11 built-in tools — reviews, compression, brainstormi
## Naming Convention
All skills use the `bmad-` prefix followed by a descriptive name (e.g., `bmad-agent-dev`, `bmad-create-prd`, `bmad-help`). See [Modules](./modules.md) for available modules.
All skills use the `bmad-` prefix followed by a descriptive name (e.g., `bmad-agent-dev`, `bmad-prd`, `bmad-help`). See [Modules](./modules.md) for available modules.
description: Reference for all built-in tasks and workflows available in every BMad installation without additional modules.
sidebar:
order: 2
order: 3
---
Every BMad installation includes a set of core skills that can be used in conjunction with any anything you are doing — standalone tasks and workflows that work across all projects, all modules, and all phases. These are always available regardless of which optional modules you install.
@ -18,7 +18,7 @@ Run any core tool by typing its skill name (e.g., `bmad-help`) in your IDE. No a
| [`bmad-help`](#bmad-help) | Task | Get context-aware guidance on what to do next |
@ -97,32 +97,36 @@ The magic happens in ideas 50–100. The workflow encourages generating 100+ ide
**Output:** Real-time multi-agent conversation with maintained agent personalities
## bmad-distillator
## bmad-spec
**Lossless LLM-optimized compression of source documents.** — Produces dense, token-efficient distillates that preserve all information for downstream LLM consumption. Verifiable through round-trip reconstruction.
**Distill any intent input into the canonical SPEC contract for downstream work.** Takes a brief, PRD, GDD, RFC, brain dump, transcript, UX folder, or mixed multi-source input and produces a `SPEC.md` carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit the kernel.
**Use it when:**
- A document is too large for an LLM's context window
- You need token-efficient versions of research, specs, or planning artifacts
- You want to verify no information is lost during compression
- Agents will need to frequently reference and find information in it
- You need to lock the WHAT before the HOW for any kind of work (software, game design, research, editorial, policy, business).
- You want a LLM Optimized succinct, no-fluff contract that downstream skills can consume without re-reading every upstream artifact.
- You want to validate or update an existing spec.
**How it works:**
1. **Analyze** — Reads source documents, identifies information density and structure
2. **Compress** — Converts prose to dense bullet-point format, strips decorative formatting
3. **Verify** — Checks completeness to ensure all original information is preserved
4. **Validate** (optional) — Round-trip reconstruction test proves lossless compression
1. Reads the input and any ancillary linked materials.
2. Distills into the five-field kernel using a configurable template; routes overflow into appropriately-named companions.
3. Runs a two-pass self-validate (coherence rules, then preservation of every load-bearing source claim).
4. Writes `SPEC.md`, sibling companions, and a `.decision-log.md` under `{output_folder}/specs/spec-{slug}/`.
Spec Law enforces eight rules: capabilities carry both intent and success; intents are WHAT not HOW; constraints actually bend decisions; non-goals are explicit; success signals are concrete; capability IDs are stable; every load-bearing source claim is preserved; prose is lean.
- `slug` (optional) — required only when input is sparse and no slug is derivable from a source filename.
- `target_spec_path` (optional) — set to update an existing spec instead of creating a new one.
**Output:** Distillate markdown file(s) with compression ratio report (e.g., "3.2:1")
**Output:** Spec folder containing `SPEC.md`, any companion files, and a `.decision-log.md`. Headless callers receive a JSON response with the result status and the list of files written or modified.
:::note[Mutation contract]
`bmad-spec` is the only writer of `SPEC.md` and of spec-authored companions. Other skills produce their own native artifacts and invoke `bmad-spec` headless when they need to express intent as the canonical contract or propose updates.
description: Add-on modules for building custom agents, creative intelligence, game development, and testing
sidebar:
order: 4
order: 5
---
BMad extends through official modules that you select during installation. These add-on modules provide specialized agents, workflows, and tasks for specific domains beyond the built-in core and BMM (Agile suite).
description: Comparing the built-in QA workflow with the Test Architect (TEA) module for test automation.
sidebar:
order: 5
order: 6
---
BMad provides two testing paths: a built-in QA workflow for fast test generation and an installable Test Architect module for enterprise-grade test strategy.
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 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.
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.
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.
Final important note: Every workflow below can be run directly with your tool of choice via skill or by loading an agent
@ -21,30 +30,43 @@ Final important note: Every workflow below can be run directly with your tool of
## 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).
Explore the problem space and validate ideas before committing to planning. [**Learn what each tool does and when to use
`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 `decision-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.
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.
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.
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.
| 4 | Implementation | Build epic by epic, story by story |
**[Open the Workflow Map](../reference/workflow-map.md)** to explore phases, workflows, and context management.
@ -100,6 +102,7 @@ If you want the newest prerelease build instead of the default release channel,
When prompted to select modules, choose **BMad Method**.
The installer creates two folders:
- `_bmad/` — agents, workflows, tasks, and configuration
- `_bmad-output/` — empty for now, but this is where your artifacts will be saved
@ -114,7 +117,7 @@ BMad-Help will detect what you've completed and recommend exactly what to do nex
:::
:::note[How to Load Agents and Run Workflows]
Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-create-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-agent-pm` for the PM agent).
Each workflow has a **skill** you invoke by name in your IDE (e.g., `bmad-prd`). Your AI tool will recognize the `bmad-*` name and run it — you don't need to load agents separately. You can also invoke an agent skill directly for general conversation (e.g., `bmad-agent-pm` for the PM agent).
:::
:::caution[Fresh Chats]
@ -134,6 +137,7 @@ Create it manually at `_bmad-output/project-context.md` or generate it after arc
### Phase 1: Analysis (Optional)
All workflows in this phase are optional. [**Not sure which to use?**](../explanation/analysis-phase.md)
- **Create** — coached discovery from scratch; the skill names the workspace folder and guides you to a PRD you're proud of
- **Update** — point it at an existing PRD and a change signal; it surfaces conflicts before applying changes
- **Validate** — critique a finished PRD against a checklist and produce an HTML findings report
:::
**For Quick Flow track:**
- Run `bmad-quick-dev` — it handles planning and implementation in a single workflow, skip to implementation
:::note[UX Design (Optional)]
If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-create-ux-design`) after creating your PRD.
If your project has a user interface, invoke the **UX-Designer agent** (`bmad-agent-ux-designer`) and run the UX design workflow (`bmad-ux`) after creating your PRD.
:::
### Phase 3: Solutioning (BMad Method/Enterprise)
**Create Architecture**
1. Invoke the **Architect agent** (`bmad-agent-architect`) in a new chat
2. Run `bmad-create-architecture` (`bmad-create-architecture`)
3. Output: Architecture document with technical decisions
@ -163,14 +176,15 @@ If your project has a user interface, invoke the **UX-Designer agent** (`bmad-ag
**Create Epics and Stories**
:::tip[V6 Improvement]
Epics and stories are now created *after* architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
Epics and stories are now created _after_ architecture. This produces better quality stories because architecture decisions (database, API patterns, tech stack) directly affect how work should be broken down.
:::
1. Invoke the **PM agent** (`bmad-agent-pm`) in a new chat
2. Run `bmad-create-epics-and-stories` (`bmad-create-epics-and-stories`)
3. The workflow uses both PRD and Architecture to create technically-informed stories
description: Buộc LLM xem xét lại kết quả của nó bằng các phương pháp lập luận có cấu trúc
sidebar:
order: 6
order: 4
---
Buộc LLM xem xét lại những gì nó vừa tạo ra. Bạn chọn một phương pháp lập luận, nó áp dụng phương pháp đó lên chính output của mình, rồi bạn quyết định có giữ các cải tiến hay không.
title: "Giai đoạn phân tích: từ ý tưởng đến nền tảng"
description: Động não, nghiên cứu, product brief và PRFAQ là gì, và nên dùng từng công cụ khi nào
sidebar:
order: 1
order: 2
---
Giai đoạn phân tích (giai đoạn 1) giúp bạn suy nghĩ rõ ràng về sản phẩm trước khi cam kết bắt tay vào xây dựng. Mọi công cụ trong giai đoạn này đều là tùy chọn, nhưng nếu bỏ qua toàn bộ phần phân tích thì PRD của bạn sẽ được dựng trên giả định thay vì hiểu biết thực chất.
description: Review có người trong vòng lặp với hỗ trợ của LLM, dẫn bạn đi qua thay đổi từ mục đích đến chi tiết
sidebar:
order: 3
order: 8
---
`bmad-checkpoint-preview` là một workflow review tương tác có người trong vòng lặp với hỗ trợ của LLM. Nó dẫn bạn đi qua một thay đổi mã nguồn, từ mục đích và bối cảnh đến các chi tiết quan trọng, để bạn có thể quyết định có nên phát hành, làm lại, hay đào sâu thêm.
description: Cách kiến trúc ngăn xung đột khi nhiều agent cùng triển khai một hệ thống
sidebar:
order: 4
order: 6
---
Khi nhiều agent AI cùng triển khai các phần khác nhau của hệ thống, chúng có thể đưa ra các quyết định kỹ thuật mâu thuẫn nhau. Tài liệu kiến trúc ngăn điều đó bằng cách thiết lập các tiêu chuẩn dùng chung.
description: Cách project-context.md định hướng các agent AI theo quy tắc và ưu tiên của dự án
sidebar:
order: 7
order: 11
---
Tệp `project-context.md` là kim chỉ nam cho việc triển khai của các agent AI trong dự án của bạn. Tương tự như một "bản hiến pháp" trong các hệ thống phát triển khác, nó ghi lại các quy tắc, pattern và ưu tiên giúp việc sinh mã được nhất quán trong mọi workflow.
description: Hiểu vì sao giai đoạn solutioning là tối quan trọng đối với dự án nhiều epic
sidebar:
order: 3
order: 5
---
Giai đoạn 3 (Solutioning) biến **xây gì** (từ giai đoạn Planning) thành **xây như thế nào** (thiết kế kỹ thuật). Giai đoạn này ngăn xung đột giữa các agent trong dự án nhiều epic bằng cách ghi lại các quyết định kiến trúc trước khi bắt đầu triển khai.
description: Năm mẫu tùy chỉnh giúp thay đổi BMad mà không cần fork, gồm quy tắc ở cấp agent, quy ước workflow, xuất bản ra hệ thống ngoài, thay template và điều chỉnh danh sách agent
sidebar:
order: 9
order: 11
---
Bề mặt tùy chỉnh của BMad cho phép một tổ chức định hình lại hành vi mà không phải sửa file đã cài hay fork skill. Hướng dẫn này trình bày năm công thức mẫu (recipe) bao phủ phần lớn nhu cầu ở môi trường doanh nghiệp.
@ -15,7 +15,7 @@ Sử dụng trình cài đặt BMad để thêm module từ kho cộng đồng (
- Cài module từ máy chủ Git riêng tư hoặc tự host
:::note[Điều kiện tiên quyết]
Yêu cầu [Node.js](https://nodejs.org) v20+ và `npx` đi kèm npm. Bạn có thể chọn module tùy chỉnh và module cộng đồng trong lúc cài mới, hoặc thêm chúng vào một bản cài hiện có.
Yêu cầu [Node.js](https://nodejs.org) v20.12+ và `npx` đi kèm npm. Bạn có thể chọn module tùy chỉnh và module cộng đồng trong lúc cài mới, hoặc thêm chúng vào một bản cài hiện có.
description: Tạo và duy trì project-context.md để định hướng cho các agent AI
sidebar:
order: 8
order: 9
---
Sử dụng tệp `project-context.md` để đảm bảo các agent AI tuân theo ưu tiên kỹ thuật và quy tắc triển khai của dự án trong suốt mọi workflow. Để đảm bảo tệp này luôn sẵn có, bạn cũng có thể thêm dòng `Important project context and conventions are located in [path to project context]/project-context.md` vào file context của công cụ hoặc file always rules của bạn (như `AGENTS.md`).
description: Tài liệu tham chiếu cho skill của BMad — skill là gì, hoạt động ra sao và tìm ở đâu.
sidebar:
order: 3
order: 4
---
Skills là các prompt dựng sẵn để nạp agent, chạy workflow hoặc thực thi task bên trong IDE của bạn. Trình cài đặt BMad sinh chúng từ các module bạn đã chọn tại thời điểm cài đặt. Nếu sau này bạn thêm, xóa hoặc thay đổi module, hãy chạy lại trình cài đặt để đồng bộ skills (xem [Khắc phục sự cố](#khắc-phục-sự-cố)).
description: Tài liệu tham chiếu cho mọi tác vụ và quy trình tích hợp sẵn có trong mọi bản cài BMad mà không cần module bổ sung.
sidebar:
order: 2
order: 3
---
Mọi bản cài BMad đều bao gồm một tập skill cốt lõi có thể dùng cùng với bất cứ việc gì bạn đang làm, các tác vụ và quy trình độc lập hoạt động xuyên suốt mọi dự án, mọi module và mọi giai đoạn. Chúng luôn có sẵn bất kể bạn cài những module tùy chọn nào.
@ -18,7 +18,7 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n
| [`bmad-help`](#bmad-help) | Tác vụ | Nhận hướng dẫn có ngữ cảnh về việc nên làm gì tiếp theo |
| [`bmad-brainstorming`](#bmad-brainstorming) | Quy trình | Tổ chức các phiên brainstorming có tương tác |
| [`bmad-party-mode`](#bmad-party-mode) | Quy trình | Điều phối thảo luận nhóm nhiều agent |
| [`bmad-distillator`](#bmad-distillator) | Tác vụ | Nén tài liệu tối ưu cho LLM mà không mất thông tin |
| [`bmad-spec`](#bmad-spec) | Quy trình | Distill any intent input into a SPEC kernel and companions, the canonical contract for downstream work (translation pending) |
| [`bmad-advanced-elicitation`](#bmad-advanced-elicitation) | Tác vụ | Đẩy đầu ra của LLM qua các vòng tinh luyện lặp |
| [`bmad-review-adversarial-general`](#bmad-review-adversarial-general) | Tác vụ | Rà soát hoài nghi để tìm chỗ thiếu và chỗ sai |
| [`bmad-review-edge-case-hunter`](#bmad-review-edge-case-hunter) | Tác vụ | Phân tích toàn bộ nhánh rẽ để tìm trường hợp biên chưa được xử lý |
@ -97,33 +97,6 @@ Chạy bất kỳ công cụ cốt lõi nào bằng cách gõ tên skill của n
**Đầu ra:** Cuộc hội thoại nhiều agent theo thời gian thực, vẫn giữ nguyên cá tính từng agent
## bmad-distillator
**Nén tài liệu nguồn tối ưu cho LLM mà không mất thông tin.** Công cụ này tạo ra các bản chưng cất dày đặc, tiết kiệm token nhưng vẫn giữ nguyên toàn bộ thông tin cho LLM dùng về sau. Có thể xác minh bằng tái dựng hai chiều.
**Dùng khi:**
- Một tài liệu quá lớn so với context window của LLM
- Bạn cần phiên bản tiết kiệm token của tài liệu nghiên cứu, đặc tả hoặc artifact lập kế hoạch
- Bạn muốn xác minh rằng không có thông tin nào bị mất trong quá trình nén
- Các agent sẽ cần tham chiếu và tìm thông tin trong đó thường xuyên
**Cách hoạt động:**
1. **Analyze** — Đọc tài liệu nguồn, nhận diện mật độ thông tin và cấu trúc
2. **Compress** — Chuyển văn xuôi thành dạng bullet dày đặc, bỏ trang trí không cần thiết
3. **Verify** — Kiểm tra tính đầy đủ để đảm bảo mọi thông tin gốc còn nguyên
4. **Validate***(tùy chọn)* — Tái dựng hai chiều để chứng minh nén không mất mát
**Đầu vào:**
- `source_documents`*(bắt buộc)* — Đường dẫn file, thư mục hoặc mẫu glob
- `downstream_consumer`*(tùy chọn)* — Thành phần sẽ dùng đầu ra này, ví dụ "PRD creation"
- `token_budget`*(tùy chọn)* — Kích thước mục tiêu gần đúng
- `--validate`*(cờ)* — Chạy kiểm tra tái dựng hai chiều
**Đầu ra:** Một hoặc nhiều file markdown distillate kèm báo cáo tỷ lệ nén, ví dụ `3.2:1`
## bmad-advanced-elicitation
**Đẩy đầu ra của LLM qua các phương pháp tinh luyện lặp.** Công cụ này chọn từ thư viện kỹ thuật elicitation để cải thiện nội dung một cách có hệ thống qua nhiều lượt.
description: Các module bổ sung để xây agent tùy chỉnh, tăng cường sáng tạo, phát triển game và kiểm thử
sidebar:
order: 4
order: 5
---
BMad được mở rộng thông qua các module chính thức mà bạn chọn trong quá trình cài đặt. Những module bổ sung này cung cấp agent, workflow và task chuyên biệt cho các lĩnh vực cụ thể, vượt ra ngoài phần lõi tích hợp sẵn và BMM (Agile suite).
description: So sánh workflow QA tích hợp sẵn với module Test Architect (TEA) cho tự động hóa kiểm thử.
sidebar:
order: 5
order: 6
---
BMad cung cấp hai hướng kiểm thử: workflow QA tích hợp sẵn để tạo test nhanh và module Test Architect có thể cài thêm cho chiến lược kiểm thử c<><63>p doanh nghiệp.
@ -14,7 +14,7 @@ Xây dựng phần mềm nhanh hơn bằng các workflow vận hành bởi AI, v
- Sử dụng agent và workflow hiệu quả
:::note[Điều kiện tiên quyết]
- **Node.js 20+** — Bắt buộc cho trình cài đặt
- **Node.js 20.12+** — Bắt buộc cho trình cài đặt
- **Git** — Khuyến nghị để quản lý phiên bản
- **IDE có AI** — Claude Code, Cursor hoặc công cụ tương tự
- **Một ý tưởng dự án** — Chỉ cần đơn giản cũng đủ để học
@ -150,7 +150,7 @@ Tất cả workflow trong phase này đều là tùy chọn. [**Chưa chắc nê
- Chạy `bmad-quick-dev` — workflow này gộp cả planning và implementation trong một lần, nên bạn có thể chuyển thẳng sang triển khai
:::note[Thiết kế UX (Tùy chọn)]
Nếu dự án của bạn có giao diện người dùng, hãy gọi **UX-Designer agent** (`bmad-agent-ux-designer`) và chạy workflow thiết kế UX (`bmad-create-ux-design`) sau khi tạo PRD.
Nếu dự án của bạn có giao diện người dùng, hãy gọi **UX-Designer agent** (`bmad-agent-ux-designer`) và chạy workflow thiết kế UX (`bmad-ux`) sau khi tạo PRD.
Brian
Jérôme Revillard
robertocsko-seon
SevenSteven
Farzad Rashidi
Emmanuel Atsé
Alex Verkhovsky
Dov Benyomin Sohacheski
Rayan Salhab
github-actions[bot]
Dicky Moore
Davor Racic
bmad
AJ Côté
jheyworth
Tankatronic
Leon