* 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>
* 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.
* 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
* 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>
* refactor(bmm): streamline bmad-product-brief into lean facilitator
Rewrites bmad-product-brief as an outcome-driven, intent-routed
facilitator with a configurable reviewer panel.
- Replace scripted prompt files with a concise SKILL.md
- Add brief-shape detection and intent routing
- Make the reviewer panel config-driven via customize.toml
- Harden the required-reviewer gate
- Add helper scripts and tests for panel resolution
- Replace embedded resources with a single brief-template asset
- Register skill metadata in module.yaml
* refactor(bmm): tighten bmad-product-brief discovery and polish flow
- Discovery now invites a brain dump and source material upfront,
followed by "anything else?" before drilling
- Create and Update modes explicitly invoke Discovery before drafting
- Calibrate "make them sweat" to ease as the brief firms up
- Update mode regenerates distillate.md when changes apply
- Replace polish_skills with polish_passes: polymorphic entries
(skill:/file:/plain-text), parallel subagents, applied automatically
so the user sees a polished draft, not a polish review
- Default persistent_facts to empty with opt-in examples instead of an
unbounded project-context.md glob
- Remove research-librarian, field-researcher, and skeptic agents no
longer needed with this rework
* refactor(bmm): make persistence and resume explicit in bmad-product-brief
- Replace "Hold a working memory" with "Persistence is real-time": the
workspace exists on disk and the user knows the path the moment Create
intent is confirmed; decision-log.md is canonical memory so walk-away
leaves nothing in the conversation
- Add "Continuity across sessions": prior in-progress drafts for this
project surface a resume offer
* test(bmm): scaffold evals for bmad-product-brief
Adds an eval suite for bmad-product-brief following the Anthropic skill-creator
schema, plus a new "Extract, don't ingest" constraint on the skill itself.
Skill change:
- New constraint: source artifacts (user-provided or run-discovered) enter the
parent conversation as relevance-filtered extracts via subagents, not loaded
wholesale. Keeps the parent context lean against transcripts, brainstorms,
research reports, code, web results, and prior briefs.
Evals (evals/bmm-skills/bmad-product-brief/):
- evals.json: 8 artifact/behavioral evals covering Create one-shot,
source-memo ingest, Update with contradiction surfacing, Validate inline,
Headless mode, brainstorm filtering, research-report filtering, persona
filtering. All scenarios use fictional entities (InsuLens, Branfield CC,
Forkbird Kitchen, Mossridge Library, Sproutkeeper, Hatchet & Loop Studio,
Brightway, Pantry Bridge).
- triggers.json: 15 description-firing checks (7 should-fire, 8 should-not-fire)
to catch under-triggering and adjacent-skill poaching.
- files/: realistic fixtures including a brainstorm with the relevant idea
buried at the end, a 3000-word market research report with the relevant
section in the middle, and customer interviews with the target persona in
position 3 of 4 — each shaped to test that filtering happens against the
user's stated focus regardless of where the relevant material sits.
Eval directory placement: top-level evals/ outside src/, matching the convention
in anthropics/skills (zero of 17 production skills include an evals/ subdir;
their skill-creator places dev workspaces as siblings to skill folders). Keeps
evals out of any installer or marketplace.json distribution path.
* refactor(bmm): rename brief workflow knobs and resolve PR review
- polish_passes -> doc_standards (TOML key + SKILL.md reference). Name
generalizes for every doc-producing skill: encodes standards applied at
finalize, not options.
- {run_folder} -> {doc_workspace}. Bound in Create to
{workflow.output_dir}/{workflow.output_folder_name}/; reused by Update,
Validate, Headless, and Finalize as the active brief's folder.
- On Activation Step 4 now resolves {date} explicitly (used by
output_folder_name default).
- Headless Mode: ambiguous-intent fallback is a `blocked` JSON status with
a `reason` field, no prompting. Resolves the activation/headless
contradiction flagged in review.
* test(bmm): overhaul product-brief evals into A/B/C pattern split
Refactor evals from 8 numbered single-shot tests into 16 typed evals:
- Pattern A (A1-A8): artifact-correctness tests with headless prompts and
precise, falsifiable expectations (no invented facts, right-sized output,
file boundary enforcement)
- Pattern B (B1-B8): process-discipline tests verifying decision-log fidelity,
polish phase ordering, contradiction detection, and distillate generation
- Pattern C (C1): config-compliance test for custom output paths and
document_output_language
Also tighten SKILL.md: add dependencies frontmatter, clarify headless override
autonomy in Update (proceed when intent is clear; block when ambiguous), and
make distillate skip explicit when bmad-distillator is not installed.
* feat(skills): TOML-based agent customization with stdlib Python resolver
Re-applies PR #2282's three-layer customization model (skill defaults →
team → user) but swaps YAML for TOML and uv for stdlib tomllib. Users
no longer need uv, pip, or a virtualenv — plain python3 (3.11+) is
sufficient, since tomllib shipped in the standard library.
## Schema changes vs PR #2282
- Flat agent schema: fields live directly under [agent], no nested
metadata/persona sub-tables. Easier to author, less indentation.
- Non-configurable identity: name and title are declared in
customize.toml as source-of-truth metadata (for future skill-manifest
generation) but SKILL.md ignores overrides there — identity is
hardcoded to preserve brand recognition.
- role redefined: now describes what the skill does for the user
within its module phase, not a restatement of the title.
- persistent_facts replaces the activation-time file-context load AND
the old memories concept. Entries can be literal sentences or
file: prefixed paths/globs; avoids collision with the upcoming
runtime memory sidecar.
- activation_steps_prepend / activation_steps_append harmonized across
agents and workflows (replaces agent-specific critical_actions).
- [workflow] namespace mirrors [agent] for workflow customization.
Same four structural rules, same field vocabulary.
## Resolver (src/scripts/resolve_customization.py)
Four purely structural merge rules, zero field-name hardcoding:
- Scalars: override wins
- Tables: deep merge
- Arrays of tables where every item has `code` or `id`: merge by
that key (matching keys replace, new keys append)
- Any other array: append
No removal mechanism — overrides cannot delete base items. Fork the
skill or override by code with a no-op value to suppress defaults.
## Agents ported (6)
All six BMad agents now ship customize.toml + rewritten SKILL.md:
analyst (Mary), tech-writer (Paige), pm (John), ux-designer (Sally),
architect (Winston), dev (Amelia). Each uses the same 8-step
activation template: resolve → execute prepend → adopt persona →
load persistent facts → load config → greet (with {agent.icon}) →
execute append → dispatch or present menu.
Step 8 supports fast-path invocation: "hey Mary, let's brainstorm"
dispatches the matching menu item directly after greeting, skipping
the menu render when intent is clear. Chat, clarifying questions,
and bmad-help remain available when nothing on the menu fits.
## Installer + tooling
- _bmad/scripts/ provisioned on install (copies src/scripts/)
- _bmad/custom/ seeded with .gitignore for *.user.toml on fresh install
- Non-module-dir filter extended to skip _memory, memory, docs,
scripts, and custom when scanning for modules
- Dead _config/agents/ directory no longer created
- metadata.capabilities removed from agent-manifest.csv and schema
- eslint config extended to cover src/scripts/**
- validate-file-refs.js knows about custom/ as install-only
## Deferred for follow-up
- bmad-product-brief workflow port (the pilot that demonstrates
[workflow] + on_complete)
- Translated docs (cs/fr/vi-vn/zh-cn) — regenerate from English
* feat(skills): port bmad-product-brief to TOML workflow customization
Completes the customization surface rollout by giving the product-brief
workflow the same override model as the six BMad agents, under the
[workflow] namespace instead of [agent].
## customize.toml
Mirrors the agent shape under [workflow] with:
- activation_steps_prepend / activation_steps_append (harmonized across
agents and workflows — same field names, same append semantics)
- persistent_facts with the file: convention, seeded with
file:{project-root}/**/project-context.md
- on_complete scalar (renamed from PR #2282's skill_end for clarity —
reads cleaner as "what runs when the workflow completes")
## SKILL.md
7-step workflow activation:
1. Resolve workflow block
2. Execute prepend steps
3. Load persistent facts (file: or literal)
4. Load config
5. Greet if not already
6. Execute append steps
7. Stage 1 — Understand Intent
python3 + stdlib tomllib invocation; no uv required.
## Prompt file changes
- Path normalization: ../agents/ → agents/, ../resources/ → resources/,
bare foo.md → prompts/foo.md. All references now resolve from the
skill root (matches the convention documented in SKILL.md).
- Paths: meta-line added to each of the 4 prompt files that reference
other files, reinforcing "bare paths resolve from skill root" so the
LLM doesn't lose the convention when operating two hops into a
prompt chain.
- finalize.md terminal stage now calls the resolver for
workflow.on_complete — non-empty values run as the final step.
## Validation
- Resolver output verified: 4 workflow fields returned cleanly.
- validate-file-refs.js: 254 files scanned, 139 refs checked, 0 broken.
- test:refs: passing.
* docs(skills): enterprise customization recipes + workflow template variable
Three independent improvements bundled because they share the same
surface (workflow/agent customization) and landed from the same design
discussion:
## Fallback sentence disambiguated (7 SKILL.md files)
The "if the script fails" fallback used to say `{project-root}/_bmad/
custom/{skill-name}.toml` for the team override and then just `{skill-
name}.user.toml` for the user override, leaving the user file's
location implicit. LLMs could reasonably guess skill root or project
root instead. Replaced with an unambiguous numbered list that spells
out the full path for every file in the merge chain.
## Product-brief: stage promotion + brief_template variable
- Promoted `## Stage 1: Understand Intent` from a nested step inside
"On Activation" to a top-level section. The previous "Step 7: Stage
1 — Understand Intent → Proceed to Stage 1 below" was mechanical
numbering pretending to be a step. Activation now ends cleanly at
Step 6; Stage 1 is a peer section.
- Added `brief_template` as a workflow-level scalar customization
defaulting to `resources/brief-template.md`. Stage 4 reads
`{workflow.brief_template}` instead of the hardcoded path, so orgs
can point at their own template under `{project-root}/...` without
forking the skill.
## New doc: docs/how-to/extend-bmad-for-your-org.md
Four worked recipes that together cover most enterprise scenarios:
1. Shape an agent across every workflow it dispatches (dev agent +
Context7 MCP + Linear search — the highest-leverage pattern)
2. Enforce org conventions inside a specific workflow (product-brief
+ compliance-field persistent_facts)
3. Publish completed outputs to external systems (product-brief +
Confluence + Jira via MCP, gated on user confirmation for Jira)
4. Swap in your own output template (product-brief + brief_template
variable swap)
Opens with the two-layer mental model (agent spans workflows,
workflow is local) so readers pick the right granularity before
reading any recipe. Closes with a "Combining Recipes" section
showing all four composed. Cross-linked from customize-bmad.md.
## Validation
- Resolver: workflow.brief_template returns the default cleanly.
- validate-file-refs.js: 254 files scanned, 146 refs checked
(+7 from this commit), 0 broken.
* docs(skills): encourage CLAUDE.md/AGENTS.md reinforcement of critical rules
Added a "Reinforce Global Rules in Your IDE's Session File" section to
extend-bmad-for-your-org.md. BMad customizations only load when a
skill activates, but IDE session files (CLAUDE.md, AGENTS.md, cursor
rules, copilot-instructions) load every turn — worth restating the
most critical rules there too so they survive ad-hoc chat outside a
BMad skill.
Includes a one-line example reinforcing the Recipe 1 Context7 rule,
plus a scope table that clarifies what each layer is for:
- IDE session file: universal, every session, keep succinct
- Agent customization: persona-specific, every dispatched workflow
- Workflow customization: one workflow run
Emphasizes brevity — noise in the session file crowds out signal.
* docs(skills): add Named Agents explanation doc
New docs/explanation/named-agents.md walking through the three-legged
stool (skills + named agents + customization) with the "Hey Mary,
let's brainstorm" activation flow as the narrative thread.
Covers:
- Why named agents vs menu-driven or prompt-driven alternatives
- The 8-step activation flow and what each step contributes
- How customization scales the model beyond a single developer
- Cross-links to the how-to docs for implementation details
Sits alongside brainstorming.md, quick-dev.md, party-mode.md in the
explanation folder — feature narratives for users who want to
understand why BMad is designed the way it is, not just how to use it.
* docs(skills): clarify that keyed-merge requires a single identifier key per array
Review feedback (PR #2284) flagged that the merge-rules wording was
ambiguous: "every item has a `code` or `id` field" could reasonably
be read as "each item individually has at least one of the two",
allowing arrays to mix `code` and `id` across items.
The resolver has always required all items share the *same* identifier
key (all `code`, or all `id`). Mixed arrays fall through to append —
intentional, because mixing identifier keys within one array is a
schema smell and any guess about which key should merge creates a
worse trap than the append-fallback.
Clarified in three places:
- Merge-rules table in customize-bmad.md: "every item shares the
**same** identifier field"
- `code`/`id` convention paragraph: "pick **one** convention ... and
stick with it across the whole array"
- Resolver docstring and `_detect_keyed_merge_field` docstring:
explicit note that mixed arrays fall through with rationale
No behavior change.
* docs(skills): address CodeRabbit review — fallback rules, OS claim, headless greeting
Three fixes from PR #2284 review feedback:
## 1. Fallback merge wording (7 SKILL.md files)
Every SKILL.md told the LLM to merge the three customization files
"in priority order (later wins)" when the resolver fails. That reads
as shallow last-write-wins — but the resolver does structural merge
(scalars override, tables deep-merge, code/id-keyed arrays merge by
key, other arrays append). Following the old wording manually would
have silently stripped base `principles`, `persistent_facts`, and
`menu` items whenever a team override was present.
Expanded the fallback sentence to restate the four structural rules
explicitly, matching the resolver's behavior.
Applied to all 6 agents + bmad-product-brief workflow.
## 2. Python 3.11 / OS shipping claim (customize-bmad.md)
The docs claimed "macOS 13+, Ubuntu 22.04+, Debian 12+, Fedora 37+
all ship 3.11 or newer." Inaccurate — Ubuntu 22.04 defaults `python3`
to 3.10.6 (3.11 is a separate package), and macOS doesn't really
ship Python by default anymore.
Replaced with honest guidance: check `python3 --version` and note
that macOS without Homebrew and Ubuntu 22.04 default to 3.10 or
earlier.
## 3. Autonomous mode greeting gate (bmad-product-brief)
Product-brief's activation-mode detection documents autonomous mode
as "produce complete brief without interaction" — but Step 5 greeted
unconditionally, adding conversational output before the headless
artifact. Gated the greeting on `{mode}` != `autonomous`.
## Dismissed (replied on thread)
- `.gitignore` migration from *.user.yaml to *.user.toml: YAML
installer code was in reverted #2282, never released. No users
affected. Same rationale as Augment's earlier thread.
Validated: 254 files, 146 refs, 0 broken. test:refs 7/7,
test:install 242/242.
* docs: rename Extend to Expand throughout customization docs
Three-layer customization (skill defaults → team → user) for BMad agents
and any skill that opts in. Users edit `_bmad/custom/{skill-name}.yaml`
(team, committed) or `{skill-name}.user.yaml` (personal, gitignored);
customizations survive updates.
Resolver is a Python script using PEP 723 inline metadata, invoked via
`uv run` so deps auto-install into a cached isolated env on first call.
This aligns with Anthropic's Agent Skills spec and BMB conventions, and
keeps the dependency declared (scannable by pip-audit/Dependabot) rather
than vendored.
## Design choices
- **Agent identity is hardcoded** in SKILL.md (name, title, Overview prose)
so skills can be invoked reliably by role *or* default name. Brand
recognition is preserved; customization shapes behavior, not identity.
- **Luminary-anchored personas** (e.g. "Channels Martin Fowler's
pragmatism and Werner Vogels's cloud-scale realism") deliver ~55%
token savings per agent while preserving distinctive voice beats.
- **Universal per-field merge rules** with v6.1-compatible agent
semantics: metadata shallow-merge, persona replace, critical_actions
and memories append, menu merge-by-code, all else deep-merge.
- **Workflow customization** shares the same surface — `bmad-product-brief`
pilots `activation_steps_prepend`, `activation_steps_append`, and
`skill_end` hooks that any workflow-style skill can adopt.
## Infrastructure
- `_bmad/scripts/` houses shared Python scripts (resolver + future).
- `_bmad/custom/` is provisioned empty with a seeded `.gitignore` for
`*.user.yaml` on fresh installs.
- Installer filters ensure `scripts/`, `custom/`, and sidecar-generated
`memory/` directories are never treated as modules.
- Dead v6.1 code cleaned up: `_config/agents/` no longer created,
`metadata.capabilities` removed from schema and CSV manifest.
* refactor: remove bmad-init skill and standardize config loading across all skills
Remove the bmad-init core skill entirely — all agents and workflow skills now
load config directly from their module's config.yaml instead of delegating to
bmad-init as an intermediary. This eliminates the Python script dependency and
simplifies the activation path for every skill.
Changes across all skill types:
- Agents (9 skills): Replace "Load config via bmad-init skill" block with
direct config loading from `{project-root}/_bmad/bmm/config.yaml`, resolving
user_name, communication_language, document_output_language,
planning_artifacts, and project_knowledge
- Workflow skills (12 skills): Standardize INITIALIZATION/Configuration Loading
sections to a consistent Activation format matching the agent pattern
- bmad-prfaq: Align activation to standard config pattern, convert scripted
dialogue to outcome-focused instructions (no direct quotes)
- bmad-product-brief: Remove External Skills section referencing bmad-init
- bmad-party-mode: Standardize initialization to Activation format
- bmad-advanced-elicitation: Inline agent_party path instead of config var
- bmad-distillator: Remove unused argument-hint frontmatter
- Delete legacy create-prd/ directory (superseded by bmad-create-prd)
- Delete bmad-init skill entirely: SKILL.md, bmad_init.py, core-module.yaml,
and test suite
* fix: remove remaining bmad-init references from marketplace.json and distillate examples
Clean up missed references: remove bmad-init from marketplace.json skills
list, replace bmad-init examples in distillate-format-reference.md with
bmad-help/bmad-setup to keep examples valid without referencing a removed skill.
* fix: update broken file references in bmad-edit-prd after create-prd deletion
Point prdPurpose refs from deleted create-prd/data/ to bmad-create-prd/data/
and validationWorkflow ref from create-prd/steps-v/ to bmad-validate-prd/steps-v/.
Replace bmad-create-product-brief (step-based wizard) and
bmad-product-brief-preview (multi-agent) with a single unified
bmad-product-brief skill. Remove accidentally duplicated market
research step files and template. Update research skill
descriptions to use more natural trigger language.
Jérôme Revillard
Brian