* 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>
* feat(core-skills): add bmad-customize for authoring _bmad/custom overrides
A conversational guide skill that helps users author or update TOML overrides
in _bmad/custom/ for customizable BMad agents and workflows. Covers per-skill
agent and workflow surfaces; central config is out of scope for v1.
- SKILL.md: six-step flow (intent, discover, route, compose, team-vs-user,
show-confirm-write-verify) with baked-in agent-vs-workflow routing heuristic
and a template-swap subroutine
- scripts/list_customizable_skills.py: stdlib-only scanner that enumerates
customizable skills across standard IDE install paths, reports surface type
and override status, PEP 723, 10 unit tests
- Reuses _bmad/scripts/resolve_customization.py for post-write verification
- Registered in core-skills/module-help.csv with menu code BC
* refactor(bmad-customize): apply QA pass (top 3 recommendations)
Applies the three highest-payoff themes from the quality analysis:
- Labeling + completion contracts: rename ## Purpose to ## Overview,
add domain framing (what customization means in BMad, typical user
arrival shapes), add an explicit Completion block with testable
conditions for "skill run is done"
- Hostile-environment robustness: add On-Activation preflight that
classifies no-BMad / BMad-without-resolver / full-install states,
instruct Step 2 to surface scanner errors[] and scanned_roots on
empty results, add resolver-missing fallback to Step 6.4, add a
re-enter-Step-4 recovery loop when verify shows the override didn't
take effect
- Returning-user and iteration experience: add "Audit / iterate"
intent class in Step 1, lead discovery with already-overridden
skills for that intent, read existing overrides in Step 3 before
composing, frame Step 4 as additive-on-top rather than fresh
authoring, give Cross-cutting intent an explicit Step 3 branch
that walks agent-vs-workflow with the user
Resolves 12 of 18 observations from the quality report. Lint clean
(scan-path-standards and scan-scripts both 0 findings). Unit tests
still 10/10.
* refactor(bmad-customize): derive skills root from install location
Previously the scanner hardcoded a list of IDE skill directories
(.claude/skills, .cursor/skills, .cline/skills, .continue/skills) and
scanned them relative to the project root. That was wrong: skills can
be installed either project-local or user-global, the IDE determines
the convention, and the set of valid locations is open-ended.
The scanner now derives its primary skills root from __file__ — the
running skill's own install directory is the authoritative location
for finding siblings. --skills-root overrides the default; --extra-root
(repeatable) adds additional locations for the rare mixed-install case.
Changes:
- list_customizable_skills.py: remove SKILL_ROOTS constant, add
default_skills_root() derived from __file__, rename scan_project
to scan_skills(skills_roots, project_root), add --skills-root and
--extra-root flags, de-dupe skills when the same name appears in
multiple roots (first wins)
- SKILL.md: update Step 2 to describe the scanner's derive-from-install
behavior and when to use --extra-root; drop the hardcoded IDE path
list from Notes
- tests: refactor setUp to place skills under a generic skills root
(not .claude/skills), add 3 new tests for multiple-roots merge,
duplicate-name precedence, and missing-root error reporting
* docs(customization): point users at bmad-customize as the guided path
Surface the new bmad-customize skill across the three customization
docs so users know they don't need to hand-author TOML to benefit
from the surface:
- customize-bmad.md: prominent tip at the top introducing the skill
as the guided authoring helper; updated the "Need to see what's
customizable?" troubleshooting tip to recommend the skill first
- expand-bmad-for-your-org.md: tip under prereqs noting every recipe
can be applied via the skill, with the recipes remaining the
reference for what to override
- named-agents.md: short paragraph in the customization section and a
link entry under the references list
Hand-authoring still works the same way; the skill is additive.
Central-config overrides are flagged as the current exception.
* docs(bmad-customize): steer users at bmad-builder instead of 'forking'
* fix(bmad-customize): reword description to pass file-ref validator
* refactor(bmad-customize): tighten description and expand module-help entry
- SKILL.md description: drop the catch-all 'or asks how to change the
behavior of a specific BMad skill' trigger clause that would fire in
casual discussion; keep the four explicit phrase triggers.
- module-help.csv: rewrite the description so bmad-help has real
routing material — names the concrete capabilities (persistent
facts, template swaps, activation hooks, menus), the scope routing,
and the value prop (no TOML hand-authoring). Matches the 'Use
when...' pattern other Core entries use.
* fix(module-help): quote bmad-customize description field that contains commas
* fix(bmad-customize): address PR #2289 review findings
- SKILL.md preflight: load root config from _bmad/config.toml and
config.user.toml (not .yaml) — the installer emits TOML; the YAML
references would have made the skill silently miss real user config
- SKILL.md resolver fallback (Step 6.4): read all three merge layers
when present (base / team / user) and describe the merge in
base → team → user order; the prior wording could describe the wrong
effective merge when the user wrote .user.toml on top of an existing
team .toml
- SKILL.md: replace bare 'docs/how-to/customize-bmad.md' references
(3 locations) with the public docs URL so users installing the skill
aren't pointed at a path they don't have locally
- list_customizable_skills.py: catch UnicodeDecodeError in
read_frontmatter_description so a non-UTF-8 SKILL.md can't abort
the whole scan
- list_customizable_skills.py: clarify exit-code contract in the
module docstring — errors[] is non-fatal by design, exit 2 is
reserved for invocation errors
- customize-bmad.md: tighten the tip to scope bmad-customize to the
per-skill surface; central-config is out of scope v1
- expand-bmad-for-your-org.md: same scoping — Recipes 1-4 can be
applied by the skill; Recipe 5 (central config) stays hand-authored
* fix(bmad-customize): markdownlint MD034 and validate-file-refs
- Wrap the three docs.bmad-method.org references as
[text](url) markdown links instead of bare URLs (MD034)
- Drop the {project-root}/ prefix on line 41's config.toml
references. validate-file-refs strips the template prefix and
tries to resolve 'config.toml' as 'src/config.toml'; sibling
skills (party-mode, retrospective, advanced-elicitation) all
reference '_bmad/config.toml' bare and pass CI — match that
pattern. The '(root level under {project-root}, installer-owned)'
parenthetical preserves the disambiguation.
* refactor(bmad-customize): cut token-wasting prose from SKILL.md
Down from 175 lines to 110. Removed:
- 'What customization means in BMad' architecture backgrounder — the
LLM reads the live customize.toml in Step 3; doesn't need the lore
- 'Desired Outcomes' section — retrospective narration of what the
6 steps already instruct
- 'Role' section — fluff; the flow itself defines the role
- 'Notes' section — sparse-override rule already in Step 4, IDE-path
note is commentary, docs link duplicates the out-of-scope section
- 'The scanner derives its skills directory from...' and 'returns JSON
with...' — commentary the LLM doesn't need; it runs the script and
sees the output
- 'that file IS the schema' and similar editorial asides throughout
- Explanatory clauses like 'silently drifts on every release' and
'trust the user's domain knowledge'
Kept everything that's load-bearing: preflight conditionals, intent
classification, routing heuristic, merge semantics, template-swap
subroutine, team-vs-user defaults, verify fallback and recovery loop,
completion conditions, out-of-scope list.
Brian