Fixes#2437 for French.
- agents.md: update PM triggers CP/VP/EP → PRD, remove stale US trigger
from Technical Writer, align PRD description to create/update/validate
- commands.md: fix Cursor/Windsurf skill paths to .agents/skills/,
update core tools count to 12, align PRD description
- core-tools.md: add missing bmad-customize tool entry and section with
link to customize-bmad how-to
- party-mode.md: replace stale "BMad Master orchestre" with "Le Party
Mode orchestre la discussion"
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(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>
- 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.
Continuation of 27002100. Systematic pass across all French documentation
assisted by an automated French typography linter:
- Replace regular space with NBSP (U+00A0) before colons per French
typographic convention
- Align table separator rows to match column widths
- Fix thousands separator in install-bmad.md (5000 → 5 000)
- Correct glossary example code block rendering in _STYLE_GUIDE.md
Broader pass across all sections of core-tools.md for more idiomatic
French: consistent section headers (À utiliser quand, Fonctionnement),
natural verb choices, fluid sentence construction and corrected
punctuation.
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.
Apply ee47e30c (refactor(bmad-ux): spine-based UX skill) to French docs.
Rename skill bmad-create-ux-design → bmad-ux and update outputs
from ux-spec.md to DESIGN.md + EXPERIENCE.md.
* 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.
The agent skill identifiers in agents.md and commands.md were missing
the -agent- segment of the namespace (e.g. bmad-pm instead of
bmad-agent-pm). All agent launchers use the bmad-agent-* naming
convention since the installer generates skill directories under that
prefix.
- agents.md: fix bmad-dev, bmad-analyst, bmad-pm, bmad-architect,
bmad-ux-designer, bmad-tech-writer
- commands.md: fix bmad-pm, bmad-architect
The forensic investigation feature added the IN menu trigger and
bmad-investigate skill, but the French docs that enumerate triggers
and agent capabilities were not updated.
- agents.md: add IN trigger and Enquête de code to Amelia's row
- named-agents.md: add Enquête de code to Amelia's capabilities
regex-based pass followed by AI + manual review of all 34 source files
Rules applied:
- Apostrophe: ASCII ' → curly ’ (U+2019) in all French prose
- Guillemets: ASCII "..." → « … » with narrow no-break space (U+202F) on both sides
- Narrow no-break space (U+202F): before ; ? ! and after « / before »
- No-break space (U+00A0): before : in French prose
- Thousands separator: narrow no-break space (U+202F) in 4+ digit numbers
Additional review fixes: remaining ASCII quotes in _STYLE_GUIDE.md
checklist items, testing.md, and party-mode.md numbering.
Preserved exclusions: YAML frontmatter delimiters, code blocks,
backtick inline code, URLs, footnote syntax, and English UI text.
* 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>
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.
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): 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.
* fix(installer): preserve http protocol in custom module clone URLs
Previously, parseSource() hardcoded 'https://' when building cloneUrl,
forcing http:// Git URLs (e.g., internal LAN hosts) to upgrade to https.
This broke cloning for self-hosted Git servers that only serve over HTTP.
- Capture the protocol from the regex match instead of discarding it
- Update JSDoc and inline comments to document HTTP support
- Update install-custom-modules docs (EN, ZH, VN) to list HTTP URL type
Fixes the --custom-source flag for http:// addresses.
* docs(installer): update JSDoc to mention HTTP support in cloneRepo
Add HTTP to the cloneRepo method's JSDoc param description.
Also fixes minor spacing in empty arrow functions (formatting).
* docs(installer): fix JSDoc annotation for cloneRepo param
Correct @param backtick escaping in cloneRepo JSDoc.
Also documents HTTP as a supported protocol alongside HTTPS and SSH.
---------
Co-authored-by: 关惠民 <9155544@qq.com>
* refactor(installer): replace legacy_targets auto-cleanup with upgrade warnings
Removes the legacy_targets YAML field and its install-time auto-migration
of pre-v6.1.0 directories (.claude/commands, .opencode/agents, etc.). On
install, surface a warning instead: read manifest version and scan 24
known legacy paths, then print rm -rf commands the user can run themselves.
Also deletes orphan tools/platform-codes.yaml (never loaded by any code)
and fixes a stale URL in the cs translation.
* feat(installer): consolidate to .agents/skills and add global_target_dir for all platforms
Updates platform-codes.yaml against verified primary docs for all 24 supported
platforms. 14 platforms (auggie, codex, crush, cursor, gemini, github-copilot,
kilo, kimi-code, opencode, pi, roo, rovo-dev, windsurf) move their project
target_dir to the cross-tool .agents/skills/ standard. Junie moves from the
broken .agents/skills/ to its own .junie/skills/ per JetBrains docs.
Adds global_target_dir to every platform: 11 share ~/.agents/skills/, Crush
uses XDG ~/.config/agents/skills/, Codex global stays ~/.codex/skills/, the
rest are tool-specific. Ona and Trae omit global (no documented home path).
Note: installer logic does not yet dedupe writes for platforms sharing a
target_dir — users installing multiple .agents/skills/ tools together will
overwrite the same files (harmless on install, but uninstalling one clears
the dir for the others). Coordination logic is the next step.
* feat(installer): add 18 new platforms, dedup shared target_dir, ownership-aware cleanup
Adds 18 platforms from the verified Vercel list (adal, amp, bob, command-code,
cortex, droid, firebender, goose, kode, mistral-vibe, mux, neovate, openclaw,
openhands, pochi, replit, warp, zencoder). Marks codex and github-copilot as
preferred alongside claude-code and cursor.
Coordination for platforms sharing a target_dir:
- IdeManager.setupBatch dedups skill writes when multiple selected platforms
point at the same target_dir (e.g. .agents/skills/). The first platform
writes, peers skip the redundant wipe-and-rewrite. Result reports the same
count and target dir for every member so the install summary is consistent.
- IdeManager.cleanupByList accepts remainingIdes; when removing one platform
from a shared dir while another co-installed platform still owns it, the
target_dir wipe is skipped. Platform-specific hooks (copilot markers, kilo
modes, rovodev prompts) still run.
- _setupIdes uses setupBatch; _removeDeselectedIdes passes remainingIdes so
partial reconfigure preserves shared skills.
Skill ownership now uses skill-manifest.csv canonicalIds, not the bmad- prefix.
This unblocks custom modules that ship skills with non-bmad names (e.g.
fred-cool-skill). Affected sites:
- _config-driven.detect: reads canonicalIds from the project's bmadDir
- _config-driven.findAncestorConflict: reads canonicalIds from the ancestor's
own bmadDir, falling back to the prefix only when no manifest exists
- legacy-warnings.findStaleLegacyDirs: same canonicalId-based detection
Migration warnings: LEGACY_SKILL_PATHS adds 12 skill dirs that moved to the
.agents/skills/ standard (cursor, gemini, github-copilot, kimi, opencode, pi,
roo, rovodev, windsurf, plus their globals). Users with stale skills in those
locations get a one-line warning with the rm command per dir.
New shared helper tools/installer/ide/shared/installed-skills.js exposes
getInstalledCanonicalIds(bmadDir) and isBmadOwnedEntry(entry, canonicalIds).
Tests: 9 new assertions across two suites covering dedup, partial uninstall
preservation, and custom-module skill detection. All 286 tests pass.
* fix(installer): setupBatch must not claim a shared target_dir on failure
If the first platform's setup throws or returns success: false, the dedup map
previously still recorded the claim with skillCount: 0, causing every peer
sharing the target_dir to skip its install — leaving the dir empty/broken
behind a cascade of misleading "shares with X" rows.
Now the claim is only recorded when the install succeeded and wrote skills.
On failure, the next peer becomes the new first writer and recovers.
Adds Suite 40b regression test that monkey-patches cursor.setup to throw
and verifies gemini still populates the shared dir.
* fix(installer): address PR #2313 review findings
Three issues raised by augmentcode and coderabbit bot reviewers:
1. _removeDeselectedIdes silently swallowed cleanup failures after the
refactor to cleanupByList. The old per-IDE try/catch logged a warning;
the new path discarded the result array. Now logs a warning per failed
ide so failures stay visible.
2. The legacy-dir cleanup hint printed `rm -rf "<path>"/bmad*` which both
matched bmad-os-* utility skills the user should keep AND missed the
custom-module skills (e.g. fred-cool-skill) that the new canonical-id
detection now finds. Findings now carry the exact entry names from the
scan, and the warning prints one precise rm line per entry.
3. warnPreNativeSkillsLegacy did unguarded fs reads at install start. A
permission/IO error would have aborted the whole install. Wrapped the
call site in try/catch so legacy-scan failures only emit a warning.
* feat(installer): channel-based version resolution for external modules
Adds stable/next/pinned channel resolution so external/community modules
install at released git tags by default instead of tracking main HEAD.
Manifest now records channel, resolved version, and SHA per module for
reproducible installs.
CLI flags: --channel, --all-stable, --all-next, --next=CODE (repeatable),
--pin CODE=TAG (repeatable). Precedence: pin > next > channel > registry
default > stable. --yes accepts patch/minor upgrades but refuses majors.
Interactive "Ready to install (all stable)?" gate with a per-module
picker (stable/next/pin) when declined. Re-install prompts classify tag
diffs as patch/minor/major with semver-class-dependent defaults.
Legacy version:null manifests get a one-time migration prompt.
Custom modules gain an optional @<ref> URL suffix for pinning (https,
ssh, /tree/<ref>/subdir forms supported; local paths rejected).
Community modules honor --next/--pin overrides with a curator-bypass
warning; default path still enforces the approved SHA.
Quick-update now reads the manifest's recorded channel per module so
pinned installs don't silently roll forward.
* feat(installer): interactive channel switch, upgrade refusal, unified docs
Builds on the channel-resolution foundation. The installer now lets users
flip a module between stable, next, and pinned after install — either
interactively via a "Review channel assignments?" gate, or by flag. Quick
and modify re-installs classify stable upgrades; under non-interactive
flows, patches and minors apply automatically but majors are refused with
a pointer to --pin.
Fallback behavior for GitHub rate-limit / network failures is now cache-
aware: re-installs reuse the recorded ref silently; fresh installs abort
with actionable guidance (set GITHUB_TOKEN or use --next/--pin). Bundled
modules (core, bmm) warn when targeted by --pin or --next so users aren't
left wondering why the flag had no effect.
Install summary labels no longer mangle "main" into "vmain"; next-channel
entries render as "main @ <short-sha>" instead. Bundled modules are now
correctly skipped from all channel prompts and tag-API lookups.
Docs consolidated into a single how-to. install-bmad.md now covers the
interactive flow, the channel model (stable/next/pinned plus the npm
dist-tag axis for core/bmm), the re-install upgrade prompts, the full
flag reference, copy-paste recipes, and troubleshooting. The old
non-interactive-installation.md is reduced to a redirect stub.
* fix(installer): review fixes + unit tests for channel resolution
- ui.js: import parseGitHubRepo; fixes ReferenceError in the
interactive channel picker's stable-tag pre-resolve path.
- community-manager: pinned modules now fetch+checkout the pin tag
on cache refresh instead of resetting to origin/HEAD (was silently
drifting to main on re-install).
- channel-plan: parseChannelOptions returns acceptBypass so --yes
auto-confirms the curator-bypass prompt; headless --next/--pin
installs of community modules no longer hang.
- community-manager: simplify recordedVersion (dead ternary branch).
- custom-module-manager: drop "or sha" from the @<ref> comment
(git clone --branch rejects raw SHAs); update-path fetches
origin <ref> so /tree/<branch>/ URLs work too.
- install-bmad.md: rename "Headless / CI installs" to "Headless CI
installs" so the stub's #headless-ci-installs anchor resolves.
- test/test-installer-channels.js: 83 unit tests for channel-plan
and channel-resolver pure modules; wired into npm test as
test:channels.
* fix(installer): address CodeRabbit review findings
- ui.js: skip stable-channel upgrade classification when the user has
already declared intent via --pin/--next=/--channel or the review
gate. Prevents the decline / major-refused / fetch-error branches
from silently overwriting an explicit pin with prev.version.
- external-manager.js: short-circuit cloneExternalModule when the
requested plan matches an existing in-process resolution and the
cache is valid. Avoids redundant resolveChannel() + git fetch on
every same-plan lookup in a single install.
- installer.js: fall back to CommunityModuleManager.getResolution()
when no external resolution exists, so community module result
rows carry newChannel/newSha instead of null under --next/--pin.
- installer.js: don't label a module as "no change" when its version
string is 'main'/'HEAD' — the SHA may have moved and preVersions
doesn't track the prior SHA. Show "(refreshed)" instead.
- official-modules.js: match versionInfo.version to the manifest's
cloneRef || (hasGitClone ? 'main' : version) expression so summary
lines report the cloned ref for git-backed custom installs.
- install-bmad.md: clarify that sha is only written for git-backed
modules and that rerunning the same --modules on another machine
does not reproduce stable-channel installs — convert recorded tags
into explicit --pin flags for cross-machine reproducibility.
Emmanuel Atsé
Loic Duong
Emmanuel Atsé
Brian
Davor Racic
AJ Côté
Leon
LanyGuan
miendinh