The standalone bmad-module skill only understood the new plugin.json#bmad
spec, so installing a legacy repo (marketplace.json + module.yaml, e.g.
bmad-code-org/bmad-module-game-dev-studio) failed with exit 20. Legacy
support existed only in the full installer's PluginResolver, which the
skill can't import (it ships self-contained under .claude/skills/).
Port that resolver into lib/legacy-resolver.mjs (strategies 1-5): when a
repo has no plugin.json#bmad but has a marketplace.json, resolve it into a
synthetic manifest of the same shape readAndValidateManifest produces, then
run it through the existing buildCopyPlan -> rewrite -> stage -> swap
pipeline unchanged. buildCopyPlan already copies marketplace.json verbatim,
flattens arbitrary skill paths to skills/<basename>, and flattens
moduleDefinition/moduleHelpCsv, so almost no downstream change is needed.
- plugin-json.mjs: extract validateManifestObject(m, {allowReserved}) and
add hasBmadPluginJson(dir). Legacy installs pass allowReserved:true so
first-party codes (gds, bmm, ...) install; new-spec authors still get
exit 21.
- install.mjs: detect new-spec -> legacy -> neither in §3; write
synthesized module.yaml/module-help.csv into the temp clone for the
strategy-5 fallback.
- cli.mjs: add --module <code> to disambiguate a multi-module marketplace
(otherwise exit 20 lists the available codes).
- help-catalog.mjs: export MODULE_HELP_CSV_HEADER for the synthesizer.
- tests: legacy fixtures (strategy-1, reserved code, synthesize fallback)
+ integration assertions. SKILL.md/README updated.
Verified: full install of the real game-dev-studio repo resolves gds and
lands 250 files under _bmad/gds/. Integration suite 97/0, installer
component tests 374/0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- Remove EXIT.FILE_OVERLAP (40): never thrown anywhere; its docs
described code 70 (path traversal). Dropped from exit.mjs and the
cli.mjs --help listing.
- Document --channel on the update verb (already wired through the
scripts for both install and update).
- Trim the SKILL.md exit-code table to the codes that change what the
agent tells the user (5, 10, 80, 90); defer the full list to the
script's --help, removing the triplicated/drifting table.
- Lightly tighten the intro and script-path prose loaded on every
skill activation; no behavioral change.
Integration suite 73 pass / 0 fail; validate:refs clean.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
When the ancestor walk added in the previous commit finds more than one
module.yaml + module-help.csv pair between the skills' common parent and
the repo root, the deepest one was chosen silently. That could surprise a
user whose repo legitimately carries module definitions at multiple levels.
PluginResolver.resolve now accepts an optional chooseModuleDefinition
callback. When >1 candidate is found it is invoked with each candidate
enriched with its relativePath + module.yaml code/name/description, and its
selection wins. Headless callers (the --custom-source CLI flow, tests,
re-resolution lookups) omit the callback and keep the deterministic
deepest-first default, so nothing blocks. The interactive custom-module
flow supplies a prompt, pausing/resuming its spinner around the choice.
Threads options through CustomModuleManager.resolvePlugin and wires the
prompt into both resolve sites of _addCustomUrlModules. Adds tests for the
deepest-first default, candidate enrichment, and chooser override.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
PluginResolver strategy 1 only checked the skills' common parent for
module.yaml + module-help.csv. For the canonical BMad layout (module
files at src/, skills under src/skills/<name>/) the common parent is
src/skills, so the files were missed and the resolver fell through to
strategy 5 — synthesizing a degenerate module named after the marketplace
plugin (e.g. bmad-creative-intelligence-suite) and discarding the real
`code` (cis) and `agents:` roster. That mismatch then made
resolveInstalledModuleYaml fail, emitting the collectAgentsFromModuleYaml
and writeCentralConfig "could not locate module.yaml" warnings.
Strategy 1 now walks up from the skills' common parent to the repo root
(bounded, deepest-first) and uses the first directory with both files, so
src/module.yaml resolves correctly. Also match on `pluginName` in
resolveInstalledModuleYaml's resolution-cache fallback so a module tracked
under its marketplace plugin name still resolves. Adds a regression test
mirroring the bmad-creative-intelligence-suite layout.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This work was developed in a separate bmad-marketplace repo and is now
landing directly in BMAD-METHOD, so the migration framing is obsolete:
- remove links to docs/spec.md (only existed in the temp repo) and the
bmad-marketplace / 'upstream patch' / 'sibling checkout' references in
README, the integration test, and the acme-md-lint fixture
- drop dead 'spec §N' pointers in install.mjs, install-plan.mjs, and
plugin-json.mjs (including a user-facing reserved-code error message)
- reword the manifest-generator 'patch' note as in-repo behavior
- correct the documented install path from _bmad/ to the IDE skills
directories the installer now distributes skills to (.claude/skills/, etc.)
No behavior change. Integration suite: 73 pass / 0 fail.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Step 4 pointed at _bmad/core/skills/bmad-module/, but the new module
system distributes skills verbatim into the selected IDE directories
(.claude/skills/, .agents/skills/, etc.). Resolve the script relative
to SKILL.md instead, and route the missing-script case to the existing
exit-code-5 reinstall guidance.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Add Strategy 0 to PluginResolver: detect a .claude-plugin/plugin.json
carrying a bmad{} block at the module root and resolve+validate it via
the bmad-module skill's own libs (new bmad-module-lib bridge), so the
installer and runtime skill agree on what a module is. Every resolved
module now carries a format discriminator ('plugin-json' | 'legacy').
OfficialModules routes 'plugin-json' resolutions through a new
_installFromPluginJson path that reuses the skill's copy-plan/flatten/
rewrite/atomic-swap libs, producing an on-disk layout byte-identical to
a bmad-module install while leaving legacy installs untouched. Direct
mode in ui.js prefers a root plugin.json#bmad manifest over SKILL.md
scanning. Adds Test Suite 45 covering detection, legacy fall-through,
and end-to-end install.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The skill validator walks all of src/ recursively, so the bmad-module skill's
reference and negative example modules under tests/fixtures/ (intentionally
non-bmad-* names and deliberately-malformed fixtures) were validated as
production skills and tripped HIGH SKILL-04 name-format findings, failing
`validate:skills --strict`.
Exclude a `fixtures/` directory whose parent is `tests/` from discovery so the
validator judges only real skills. No production skill lives under tests/fixtures/.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The bmad-module skill copied a module's files and distributed skills to IDEs,
but skipped four post-copy steps the full `bmad install --custom-source` path
performs, leaving modules incompletely installed:
- Merge each module's module-help.csv into _bmad/_config/bmad-help.csv (the
catalog bmad-help reads) — new lib/help-catalog.mjs
- Generate [modules.<code>] / [agents.<code>] blocks in config.toml /
config.user.toml from module.yaml (defaults + --set overrides), via a
targeted merge that preserves [core] and sibling modules — new lib/config-gen.mjs
- Create the working directories a module declares under `directories:`
(with move-on-path-change and wds_folders) — new lib/module-dirs.mjs
- Run `npm install --omit=dev` in place when a module ships package.json
(opt out via bmad.install.skipNpm) — new lib/npm-deps.mjs
All four run as a shared finishModuleInstall step wired into install, update,
and remove; every step is non-fatal so a module already committed to _bmad/
isn't lost to a post-copy hiccup. Adds a repeatable --set <code>.<key>=<value>
flag mirroring the installer.
Also fixes two latent issues in the manifest-driven copy that the new steps
depend on:
- moduleDefinition / moduleHelpCsv are now flattened to the module root even
when they live inside a declared skill dir (the setup-skill assets pattern);
previously claimedSrc dedup skipped them and the rewritten plugin.json
pointed at a non-existent ./module.yaml.
- package.json / package-lock.json are now copied so npm deps can install.
Tests: extends the integration suite with config/agent-roster, --set,
directory-creation, help-catalog, removal-cleanup, and npm assertions
(73/73 pass); adds a minimal-npm fixture and rewrites the comprehensive
fixture's module-help.csv to the canonical schema.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The bmad-module skill staged community modules under _bmad/<code>/ but never
pushed their skills out to the coding assistants the user selected at
`bmad install` time, so a freshly installed module was invisible to Claude
Code / Cursor / Copilot / etc. until a full reinstall; remove left skills
orphaned in the IDE dirs.
install/update/remove now distribute (or prune) skills to every IDE listed in
_bmad/_config/manifest.yaml and clean the redundant skill dirs from _bmad/,
matching how official modules end up.
Single engine, three callers — no fork:
- New tools/installer/core/ide-sync.js (syncIdes) wraps the real
IdeManager.setupBatch + platform-codes engine. The full installer
(_setupIdes/_cleanupSkillDirs), the new `bmad ide-sync` command, and the
skill all route through it, so new IDEs and engine changes propagate
everywhere automatically.
Local, dependency-free delivery — no npx/network at runtime:
- build-ide-sync.mjs esbuild-bundles the engine into vendor/ide-sync.mjs
(+ platform-codes.yaml), aliasing ../prompts and ../project-root to small
shims so @clack and the installer graph are dropped. The bundle ships inside
the skill tree (like yaml.mjs); the skill execs it locally. It's
generated-from-source and gated by vendor:check, refreshed on every install.
update/remove pass --prune with the module's canonicalIds so skills dropped
between versions (or on uninstall) are removed from IDE dirs + command
pointers. Graceful degradation: if the bundle is unreachable, the verb still
succeeds and points the user at `bmad ide-sync`.
Tests: new test/test-ide-sync.js drift-guard (engine == bundle, incl. prune),
integration.test.sh IDE-distribution section (offline), bundle self-check in
the build. All gates green (vendor:check, lint, format, test:install 349/349).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Formatting-only; no content changes. Brings both docs in line with the
repo's prettier config (a leftover from the .js→.mjs migration).
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The suite resolved its reference modules from `<repo>/examples`, which
existed only in the sibling bmad-marketplace checkout — so after the
skill moved into BMAD-METHOD core every install/list/remove assertion
failed with "local source not a directory".
Vendor the two reference modules (acme-md-lint, acme-devlog) under
tests/fixtures/examples/ and point EXAMPLES there; drop the now-unused
REPO_DIR. Also correct the comprehensive-install assertion: hooks are
flattened to the canonical root slot (hooks.json), matching .mcp.json
and rewriteManifestPaths — not a hooks/ subdir.
Suite now passes 41/41.
Note: these fixtures are copies of the bmad-marketplace examples and
must be re-synced if those reference modules change.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The copy planner treated every skills/agents/commands entry as a
directory and ran it through addDirRecursive, which lists files *under*
the path. For a subagent declared as a file (e.g.
`"agents": ["./agents/foo.md"]` — a standard Claude-Code shape) that
listed nothing, so the agent was silently dropped from the install even
though rewriteManifestPaths already remapped it to `./agents/foo.md`.
Stat each entry and branch: directories recurse as before, files are
queued directly (honoring the ignore matcher). Verified by the
comprehensive fixture's changelog-archivist.md agent.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
The bmad-module skill installed but was absent from the core help
registry, so it never surfaced in the bmad-help menu (every other core
skill has a row). Add it as menu-code MM ("Manage Modules").
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Replace the flat copy-list staging with a manifest-driven copy plan:
- buildCopyPlan maps declared skills/agents/commands and string-typed
Claude-Code surfaces into canonical install slots, copies conventional
top-level metadata, and drops anything not covered (no more leaking of
tools/, website/, .github/, etc.).
- rewriteManifestPaths emits a plugin.json whose paths point at the
canonical post-install locations, keeping the on-disk manifest
self-consistent inside _bmad/<code>/.
- stageCopyPlan stages the plan plus synthesized files (rewritten
plugin.json) into the tmp dir for the atomic swap.
install.mjs and update.mjs switch to the new plan/skillDestDirs flow and
drop the now-unused copy-list helpers.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
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.
The skill is copied into _bmad/core/skills/bmad-module/ by the installer,
which strips node_modules, ships no package.json under the skill, and never
runs npm install there. Bare `import 'yaml'`/`import 'semver'` therefore
crashed at module load (ERR_MODULE_NOT_FOUND, exit 1) before any structured
exit code could fire. Every other installed script is zero-third-party-dep.
- Vendor the real yaml@2.8.4 as a deterministic esbuild single-file bundle
(scripts/lib/vendor/yaml.mjs), imported by relative path. Guarantees
byte-identical manifest.yaml round-trips with BMAD core's writer, which uses
the same library + options (tools/installer/core/manifest.js).
- Drop semver for a node:-only semver-lite.mjs (valid/validRange),
parity-tested against the real semver across 469 cases (400 fuzzed).
- Fix a third bare yaml import that the original report missed (frontmatter.mjs).
- Make bmad-module.mjs a zero-import launcher that maps any load failure to a
new documented EXIT.TOOLING (5) with reinstall guidance instead of leaking a
raw ESM stack trace; the verb dispatcher moves to cli.mjs.
- Enforce vendor freshness so a yaml/esbuild bump can't ship a stale bundle:
build-vendor.mjs --check is wired into npm test (pre-commit), npm run quality,
and the quality.yaml CI validate job. Adds vendor:build / vendor:check scripts.
- Ignore the generated vendor/ dir in eslint + prettier; document the rationale
in SKILL.md, README.md, and vendor/README.md.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* 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>
pbean
Brian Madison
github-actions[bot]
hanhnt2-hblab
Jacob du Toit
Jérôme Revillard
robertocsko-seon
SevenSteven
Farzad Rashidi
Emmanuel Atsé
Alex Verkhovsky
Dov Benyomin Sohacheski
Rayan Salhab
Dicky Moore
Davor Racic