bmad-method 6.6.1-next.9 → 6.7.1-next.0

package/{tools/installer/modules/registry-fallback.yaml → bmad-modules.yaml}

@@ -1,18 +1,31 @@
-# Fallback module registry — used only when the BMad Marketplace repo
-# (bmad-code-org/bmad-plugins-marketplace) is unreachable.
-# The remote registry/official.yaml is the source of truth.
+# Official module registry — the single source of truth for which modules
+# the BMad installer offers and how they are displayed.
+#
+# Order here determines display order in the installer picker (after the
+# built-in core and bmm entries, which are loaded from local module.yaml).
 #
 # default_channel (optional) — the install channel when the user does not
 # override with --channel/--pin/--next. Valid values: stable | next.
 # Omit to inherit the installer's hardcoded default (stable).
 
 modules:
+  bmad-method-test-architecture-enterprise:
+    url: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise
+    module-definition: src/module.yaml
+    code: tea
+    name: "BMad Test Architect"
+    description: "Quality strategy, test automation, and release gates for enterprise teams"
+    defaultSelected: false
+    type: bmad-org
+    npmPackage: bmad-method-test-architecture-enterprise
+    default_channel: stable
+
   bmad-builder:
     url: https://github.com/bmad-code-org/bmad-builder
     module-definition: skills/module.yaml
     code: bmb
     name: "BMad Builder"
-    description: "Agent and Builder"
+    description: "Build AI agents, workflows, and modules from a conversation"
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-builder
@@ -21,9 +34,9 @@ modules:
   bmad-automator:
     url: https://github.com/bmad-code-org/bmad-automator
     module-definition: skills/module.yaml
-    code: baut
-    name: "BMad Automator"
-    description: "Story automation skills"
+    code: automator
+    name: "BMad Automator Epic Builder Experimental"
+    description: "EXPERIMENTAL: only supports claude and codex currently"
     defaultSelected: false
     type: experimental
     npmPackage: bmad-story-automator
@@ -34,7 +47,7 @@ modules:
     module-definition: src/module.yaml
     code: cis
     name: "BMad Creative Intelligence Suite"
-    description: "Creative tools for writing, brainstorming, and more"
+    description: "Brainstorming, ideation, storytelling, design thinking, and problem-solving"
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-creative-intelligence-suite
@@ -45,19 +58,20 @@ modules:
     module-definition: src/module.yaml
     code: gds
     name: "BMad Game Dev Studio"
-    description: "Game development agents and workflows"
+    description: "Game design and development for Unity, Unreal, Godot, and Phaser."
     defaultSelected: false
     type: bmad-org
     npmPackage: bmad-game-dev-studio
     default_channel: stable
 
-  bmad-method-test-architecture-enterprise:
-    url: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise
+  bmad-method-wds-expansion:
+    url: https://github.com/bmad-code-org/bmad-method-wds-expansion
     module-definition: src/module.yaml
-    code: tea
-    name: "Test Architect"
-    description: "Master Test Architect for quality strategy, test automation, and release gates"
+    code: wds
+    plugin_name: bmad-wds # WDS marketplace.json declares the plugin under this name
+    name: "Whiteport Design Studio"
+    description: "Strategic UX and Design first planning methodology"
     defaultSelected: false
     type: bmad-org
-    npmPackage: bmad-method-test-architecture-enterprise
+    npmPackage: bmad-wds
     default_channel: stable

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.6.1-next.9",
+  "version": "6.7.1-next.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",

package/src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md

@@ -15,21 +15,21 @@ At the opening greeting, let the user know they can invoke `bmad-party-mode` for
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, surface the diagnostic and halt.
+1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
 2. Execute each entry in `{workflow.activation_steps_prepend}` in order.
 3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
-4. Note `{workflow.external_sources}` as a registry of external systems available for consultation when the conversation surfaces a relevant need — knowledge bases, internal MCP tools, reference systems. Do not query preemptively; consult each only when its directive matches the moment. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant.
+4. `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers in `## Discovery`, org tools preferred when their directive matches. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap when relevant.
 5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
-6. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`.
+6. Greet `{user_name}` in `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`.
 7. Execute each entry in `{workflow.activation_steps_append}` in order.
 
 ## Intent Operating Modes
 
-**Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `brief.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted.
+**Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.brief_output_path}/{workflow.run_folder_pattern}/` and write `brief.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted.
 
-**Update.** Reconcile an existing brief with a change signal. Before proposing changes, read the brief, addendum, `decision-log.md`, and original inputs — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching.
+**Update.** Reconcile an existing brief with a change signal. Before proposing changes, read the brief, addendum, `.decision-log.md`, and original inputs — and run the `## Discovery` posture against the change signal (a patch applied without context becomes drift). Surface conflicts with prior decisions before changing. Headless override: log the reversal to `.decision-log.md`, then apply; halt `blocked` if intent is ambiguous. If the change is fundamental, offer Create instead of patching.
 
-**Validate.** Honest critique against the brief's own purpose. Read the brief, the addendum if present, `decision-log.md`, and any original inputs first — a validation that ignores prior decisions, rejected ideas, or context the user supplied is shallow. Cite specific lines. Caveat what cannot be evaluated. Return inline — no separate file unless asked. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block.
+**Validate.** Honest critique against the brief's own purpose. Read the brief, the addendum if present, `.decision-log.md`, and any original inputs first — a validation that ignores prior decisions, rejected ideas, or context the user supplied is shallow. Cite specific lines. Caveat what cannot be evaluated. Return inline — no separate file unless asked. Always offer to roll findings into an Update, even in headless mode — include `"offer_to_update": true` in the JSON status block.
 
 ## Headless Mode
 
@@ -41,7 +41,7 @@ When invoked headless, do not ask. Complete the intent using what is provided, w
   "intent": "create",
   "brief": "{doc_workspace}/brief.md",
   "addendum": "{doc_workspace}/addendum.md",
-  "decision_log": "{doc_workspace}/decision-log.md",
+  "decision_log": "{doc_workspace}/.decision-log.md",
   "open_questions": [],
   "external_handoffs": [
     {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
@@ -61,20 +61,27 @@ Omit keys for artifacts that were not produced.
 
 ## Discovery
 
-Conversationally surface what the user brings, why this brief exists, and the domain — echo back how each shapes your approach. Open with space for the full picture: invite a brain dump and ask up front for any source material they already have (memo, deck, transcript, prior brief, slack thread). Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Get a read on stakes early (passion project, internal pitch, investor input, public launch), and let that calibrate how hard you push. Suggest research (web, competitive, market) only when the stakes warrant it.
+Conversationally surface what the user brings, why this brief exists, and the domain — echo back how each shapes your approach. Open with space for the full picture: invite a brain dump and ask up front for any source material they already have (memo, deck, transcript, prior brief, slack thread). Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot. Drill into specifics only after the broad shape is on the table; premature granular questions interrupt the dump and miss the room. Get a read on stakes early (passion project, internal pitch, investor input, public launch), and let that calibrate how hard you push. During the dump, spawn web-research subagents to ground the picture — landscape, comparables, current state — AI especially, where training data ages by the week. Subagent searches; parent gets a digest. Deep work (full market sizing, exhaustive teardowns) → suggest `bmad-market-research` or `bmad-domain-research`.
+
+Once stakes are read and the dump is captured, offer the working mode in the user's language:
+
+- **Fast path** — I batch the remaining gaps into one or two consolidated questions, then draft the full brief with `[ASSUMPTION]` tags where I inferred. You review and we iterate. Best for "I'm pitching tomorrow."
+- **Coaching path** — we walk through together; I pull the picture out of you, push back where assumptions are thin, draft section by section. Best for "I want a brief I'm proud of and time isn't the constraint."
+
+The workspace persists; stop and resume freely. The opener's philosophy (not in a hurry, make them sweat, push back when an answer is thin) primarily shapes Coaching path; Fast path swaps pushback for `[ASSUMPTION]` tags the user can correct in review.
 
 ## Constraints
 
 - **Right-size to purpose.** A passion project does not need investor-grade rigor. A VC pitch input does. Read the room.
-- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `brief.md` skeleton with `status: draft`, `decision-log.md`) exists on disk and the user knows the path.
-- **File roles.** `decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (PRD, architecture, solution design) or earned a place but does not fit the brief (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, in-depth personas, sizing data). Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum.
+- **Persistence is real-time.** Once Create intent is confirmed, the workspace (run folder, `brief.md` skeleton with `status: draft`, `.decision-log.md`) exists on disk and the user knows the path.
+- **File roles.** `.decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (PRD, architecture, solution design) or earned a place but does not fit the brief (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, in-depth personas, sizing data). Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum.
 - **Continuity across sessions.** If a prior in-progress draft for this project exists, the user is offered to resume.
 - **Extract, don't ingest.** Source artifacts (provided by the user or discovered during the run — transcripts, brainstorms, research reports, code, web results, prior briefs) enter the parent conversation as relevance-filtered extracts, not loaded wholesale. Subagents do the extraction against the user's stated focus; the parent context stays lean.
 - **Length and coherence.** Aim for 1-2 pages — if it is longer, the detail belongs in the addendum. Structure in service of the product; downstream consumers (PRD workflow, etc.) read this, so coherent shape matters.
 
 ## Finalize
 
-1. Decision log audit + addendum review: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the brief, captured in `addendum.md` (which may already hold detail captured during the conversation — see `## Constraints` for what belongs there), or set aside as process noise.
+1. Decision log audit + addendum review: the user ends this step with an explicit, shared accounting of how the meaningful contents of `.decision-log.md` were handled — captured in the brief, captured in `addendum.md` (which may already hold detail captured during the conversation — see `## Constraints` for what belongs there), or set aside as process noise.
 2. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `brief.md` (and `addendum.md` if it exists). Run passes as parallel subagents - apply all doc standards to `brief.md` first, then `addendum.md` so we present a high-quality draft for the user to review and finalize.
 3. External handoffs: execute each entry in `{workflow.external_handoffs}` to route artifacts beyond local files (Confluence, Notion, ticket systems, etc.) — each directive names the MCP tool and the fields it needs. Invoke the tool, capture any URLs or IDs returned, and surface them in the user message. If a named tool is unavailable, skip that handoff and flag it; local files always exist regardless.
 4. Tell the user it is ready: local paths and external destinations (URLs returned from handoffs). Invoke `bmad-help` to suggest what next steps make sense in the bmad method ecosystem.

package/src/bmm-skills/1-analysis/bmad-product-brief/customize.toml

@@ -23,11 +23,15 @@ activation_steps_append = []
 # (standards, compliance constraints, stylistic guardrails).
 # Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed path/glob
 # whose contents are loaded as facts.
-# Default is empty. Common opt-ins (set in your team/user override TOML):
-#   "file:{project-root}/_bmad-output/planning-artifacts/project-context.md"  # bmad-generate-project-context output
-#   "skill:acme-co:terms-and-conditions"                                      # a skill that contains some relevant info to the documents that may be generated
-#   "Elvis has left the building"                                             # generic agent instructions
-persistent_facts = []
+#
+# Default loads project-context.md if bmad-generate-project-context has produced one — this gives
+# the facilitator persistent awareness of the project's tech, domain, and constraints without
+# re-asking. Common opt-ins (set in team/user override TOML):
+#   "skill:acme-co:terms-and-conditions"                                      # a skill that contains some relevant info
+#   "Elvis has left the building"                                             # generic agent instruction
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
 
 # Executed when the workflow completes (after the user has been told the
 # brief is ready). Accepts either a string scalar (single instruction)
@@ -39,9 +43,10 @@ on_complete = ""
 # to enforce a different structure (e.g. regulated-industry, investor-deck).
 brief_template = "assets/brief-template.md"
 
-# Run folder location. The brief and optional addendum land inside `{output_dir}/{output_folder_name}/`.
-output_dir = "{planning_artifacts}/briefs"
-output_folder_name = "brief-{project_name}-{date}"
+# Run folder location. The brief and optional addendum land inside `{brief_output_path}/{run_folder_pattern}/`.
+# Resume-check scans `{brief_output_path}` for prior unfinished runs.
+brief_output_path = "{planning_artifacts}/briefs"
+run_folder_pattern = "brief-{project_name}-{date}"
 
 # Document standards applied to human-consumed docs at finalize. Each entry is
 # a `skill:`, `file:`, or plain-text directive; the parent LLM applies the

package/src/bmm-skills/2-plan-workflows/bmad-prd/SKILL.md

@@ -1,90 +1,87 @@
 ---
 name: bmad-prd
-description: Create, update, validate, or analyze a PRD. Use when the user wants help producing, editing, validating, or analyzing a PRD.
+description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.
 ---
 # BMad PRD
 
-## Overview
+You are a master facilitator and coach helping the user create, edit, or validate a high quality PRD scoped to the level and rigor appropriate to their stated needs. Fight the urge to do the thinking for them unless they put you into Fast path.
 
-You are an expert PM facilitator. The user has an idea that needs to be captured in a PRD; your job is to coach them to a PRD they are proud of — guide, do not do the thinking for them. Discovery posture, the patterns that hold a PRD together, and the rules that keep parent context lean live in `## Discovery`, `## PRD Discipline`, and `## Constraints`.
+## Conventions
 
-At the opening greeting, let the user know they can invoke the skills `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration at any point.
+- Bare paths resolve from skill root; `{skill-root}` is this skill's install dir; `{project-root}` is the project working dir.
+- `{workflow.<name>}` resolves to fields in `customize.toml`'s `[workflow]` table (overrides win per BMad merge rules).
+- `{doc_workspace}` is the bound run folder.
+- **File roles.** `.decision-log.md` is canonical memory and audit trail — every decision, change, and override (including headless overrides) is recorded there as the conversation unfolds. `addendum.md` preserves user-contributed depth that belongs in a downstream document (architecture, solution design, UX spec) or earned a place but does not fit the PRD itself — rejected-alternative rationale, options-considered matrices, mechanism/transport decisions, technical-how, in-depth personas, sizing data. Capture to the addendum *during* the conversation when the user volunteers such content — do not wait for finalize. Audit and override information never goes in the addendum.
 
 ## On Activation
 
-1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, surface the diagnostic and halt.
-2. Execute each entry in `{workflow.activation_steps_prepend}` in order.
-3. Treat every entry in `{workflow.persistent_facts}` as foundational context. Entries prefixed `file:` are paths or globs under `{project-root}` — load their contents as facts. All others are facts verbatim.
-4. Note `{workflow.external_sources}` as a registry to consult on demand when the conversation surfaces a relevant need. Do not query preemptively. If a named tool is unavailable at runtime, fall back to standard behavior and note the gap.
-5. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
-6. Detect mode and intent. If headless (no interactive user), read `references/headless.md` and follow it for the whole run with matched intent. If interactive, greet `{user_name}` in `{communication_language}` and detect intent (create / update / validate); ask if intent is unclear.
-7. Execute each entry in `{workflow.activation_steps_append}` in order.
+1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly and use defaults.
+2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (entries prefixed `file:` are loaded). `{workflow.external_sources}` is an org-configured registry of internal tools (knowledge bases, MCP tools); consult them alongside generic web research on the same triggers, org tools preferred when their directive matches. Research itself fires during Discovery — see **Research subagents**.
+3. Load `{project-root}/_bmad/bmm/config.yaml` (+ `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. Missing keys → neutral defaults; never block.
+4. If headless, follow `references/headless.md` for the whole run. Otherwise greet the user **by name** using `{user_name}` and **in their language** using `{communication_language}` — and stay in `{communication_language}` for every turn for the entire run, not just the greeting. In the greeting, let the user know that at any point they can invoke `bmad-party-mode` for multi-agent perspectives or `bmad-advanced-elicitation` for deeper exploration on a specific section. Then scan for misroute on the first message: if the signal points elsewhere (game → BMad GDS; express build → `bmad-quick-dev`; one-pager → `bmad-product-brief`; vet product idea → `bmad-prfaq`; agent skill or custom agent → `bmad-workflow-builder`), suggest they might want the other options before continuing.
+5. Detect intent: **Create** (no PRD), **Update** (existing PRD), **Validate** (critique only). If ambiguous, ask. For Create intent, before binding a fresh workspace, scan `{workflow.prd_output_path}` for prior in-progress runs (folders matching `{workflow.run_folder_pattern}` whose `prd.md` frontmatter `status` is not `final`); if any exist, offer to resume rather than starting over.
+6. Run `{workflow.activation_steps_append}`.
 
-## Intent Operating Modes
+## Intent Modes
 
-**Create.** A PRD the user is proud of, drawn out through real conversation. Discovery first, drafting second. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `prd.md` there with YAML frontmatter (title, created, updated). Version and state transitions live in `decision-log.md`. For Update and Validate, `{doc_workspace}` is the existing folder of the PRD being targeted. When drafting is complete, proceed to `## Finalize`.
+**Create.** Bind `{doc_workspace}` to `{workflow.prd_output_path}/{workflow.run_folder_pattern}/`. Write `prd.md` with YAML frontmatter (title, status, created, updated — initial `status: draft`), and create the `.decision-log.md` skeleton at the workspace root so subsequent decisions land in a known file. Tell the user the path. Run `## Discovery`, then `## Finalize`.
 
-**Update.** Reconcile an existing PRD with a change signal. Orient via source extractors (see `## Constraints` → Extract, don't ingest) against the PRD, addendum, `decision-log.md`, and original inputs — then run the `## Discovery` posture against the change signal. Surface conflicts with prior decisions before changing. If the change is fundamental, offer Create instead of patching. When changes are applied, proceed to `## Finalize`.
+**Update.** Reconcile the PRD with a change signal. Source-extract against PRD, addendum, `.decision-log.md`, and original inputs (extract, don't ingest). If `.decision-log.md` is missing, spawn a one-time bootstrap subagent to reverse-engineer a thin log from the PRD before continuing. Surface conflicts with prior decisions before applying. Then `## Finalize`.
 
-**Validate** (or *analyze*). Critique an existing PRD against `{workflow.validation_checklist}`. Standalone — does NOT enter `## Finalize`. Orient via source extractors against `decision-log.md` and any original inputs to give the validator context. Spawn the validator subagent against `prd.md` (and `addendum.md` if present); produce findings and a validation report per `references/validation-render.md`. Always offer to roll findings into an Update.
+**Validate** (or *analyze*). Critique without changing. Load `references/validate.md`.
 
 ## Discovery
 
-Open with space for the full picture: invite a brain dump, inputs, ideas, WHY they are doing this. Read what exists first; ask only what is missing. After the dump, a simple "anything else?" often surfaces what they almost forgot.
+Order: **Brain dump → Stakes calibration → Working mode → mode-scoped work.** Get to working mode fast — two or three turns, not ten. Users in a hurry must not be held hostage by upstream probing.
 
-Before drafting, read the situation across four dimensions — they determine the PRD's shape:
+**Brain dump.** Always the first move, even when the user opens with paragraphs of context (that is intake, not the dump). Ask for verbal context *and* any existing inputs they want you to read — product brief, research, customer transcripts, competitive analysis, prior PRD draft, design docs. Paths or paste; big docs are fine, you will subagent-extract. A simple "anything else?" surfaces what they almost forgot.
 
-- **Stakes.** Calibrates rigor, section depth, and which adapt-in clusters apply.
-- **Audience.** Drives tone, evidence requirements, and approval sections.
-- **Existing inputs.** Existing artifacts mean those parts of the PRD reference, not relitigate. When project-context, prior PRDs, or existing UX/architecture are present, this is brownfield — frame Discovery around what is new or changing.
-- **Downstream depth.** Whole spec for a small build, or top of a chain through UX → architecture → epics → stories? Affects how much the PRD encodes vs. defers.
+**Research subagents (default).** During Discovery, spawn web-research subagents to ground the picture: what exists in the space, how comparables position themselves, current landscape. Subagent does the search; parent receives a digest.
 
-**Right-skill check.** Once the situation is read, sanity-check that PRD is the best tool. Three cases where it isn't:
+**Elicitation, not direction.** Discovery pulls the user's vision out; it does not insert yours. Open-ended "tell me about X" beats multiple choice. When you find yourself naming wedges, picking MVP cuts, or proposing phases, stop — you have crossed from elicitation into authoring. Hand the pen back. Infer-and-confirm ("I'm assuming X works like Y — right?") is fine; quizzing the user through a tree of LLM-shaped choices is not.
 
-- **Games** → suggest `bmad-gds` for the Game Design Document.
-- **Small scope + wants a captured artifact** (small tweak to an existing codebase, single doc to point at) → stay here and produce an *all-inclusive document*: lean spine plus inline Stories via the adapt-in Stories cluster.
-- **Express implementation** (wants to build now, no planning chain or captured artifact needed) → suggest `bmad-quick-dev`.
+**Stakes calibration.** One short probe before working mode: hobby / internal / launch — enough to calibrate rigor and section depth. Audience, Existing inputs, and Downstream depth fill in inside the chosen mode, not upstream of the choice.
 
-Surface these honestly and let the user choose; if they prefer this skill anyway, proceed with the right-sized version.
+**Working mode.** Offer the choice in the user's language:
 
-Coach, do not quiz. Push hardest on PRD Discipline risks — unexamined assumptions, capability-vs-implementation confusion, term drift, scope creep, ambiguity for downstream readers. Suggest research if needed and have subagents use web search tools as needed.
+- **Fast path** — I batch remaining gaps into one or two consolidated questions, then draft the full PRD with `[ASSUMPTION]` tags where I inferred. You review and we iterate. The initial quality depends on how much you gave me upfront.
+- **Coaching path** — we walk PM-thinking sections together. Once chosen, I ask which entry point fits: **Vision + Features** (capability-first — for enterprise, dev products, internal tools, anyone who thinks in features), **Personas + Journeys** (user-first — for consumer, UX-heavy, multi-stakeholder products), or *let me suggest* based on what I heard. The chosen entry sets the section order.
 
-**Working mode.** Once the situational read is complete, offer the user a choice before proceeding — one sentence per option:
+The workspace persists; stop and resume freely.
 
-- **Express:** resolve any remaining critical gaps in a short batch, then draft the full PRD at once.
-- **Facilitative:** work through the sections that require PM thinking before drafting, using the techniques in `references/facilitation-guide.md`. Capture all decisions in the log, section to section. Draft after the key sections are walked. The goal is that the user has authored the thinking — not just answered intake questions.
+**Concern scan.** As you read what the user gave you, name the concerns this product actually carries — compliance, integration density, operational SLAs, hardware constraints, public-API contracts, monetization, data governance, whatever applies. The list is open; recognize what's there, do not classify into a fixed shape. These concerns drive which template sections to pull in from the Adapt-In Menu and which to invent when no cluster names them.
 
-In both modes, resolve decisions conversationally rather than silently deferring them into `[ASSUMPTION]` tags. Only use `[ASSUMPTION]` when the answer requires research or external input the PM cannot provide in the moment.
+**User Journeys are captured, not authored.** When UJs are warranted (consumer / multi-stakeholder B2B / meaningful UX — drop or downscale for internal tooling with a single operator role, regulatory-only updates, hobby/solo, pure technical PRDs), prompt the user to narrate a real session — what the person does, in what order, where it lands — then structure the answer into UJ-N form and confirm.
 
 ## PRD Discipline
 
-- **Features grouped, FRs nested.** Features open with behavioral description; FRs nested and numbered globally for stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices.
-- **Capabilities, not implementation.** FRs describe what users or systems can do, not how. Tech choices go in addendum.
-- **No innovation theater.** Don't fabricate novelty; add a differentiation section only when Discovery surfaced something genuinely novel.
-- **Personas, when used, are research-grounded or marked `[ILLUSTRATIVE]`.** Invented detail is *persona theater* — false specificity the team builds for. Personas must drive decisions; two to four max.
-- **Domain awareness.** Regulatory or compliance constraints surface in the PRD, not deferred to architecture.
-- **Right-size to purpose.** Section depth and adapt-in clusters follow project type and stakes — the template's adapt-in menu names the standard clusters.
-- **Non-Goals explicit.** Pair with inline `[NON-GOAL for MVP]` and `[v2 — out of MVP]` callouts so omissions aren't silently assumed.
-- **Never silently de-scope.** Nothing the user explicitly included drops without asking. Propose phasing; never impose it.
-- **Counter-metrics named.** When Success Metrics is present, name what NOT to optimize.
-- **Assumptions visible.** Inferences without direct user confirmation are tagged `[ASSUMPTION: ...]` inline and indexed at the end.
-- **`[NOTE FOR PM]` callouts** at decision points the user deferred or left tension on.
-
-## Constraints
-
-- **Persistence is near real-time.** Create the workspace (`prd.md` skeleton, `decision-log.md`) on disk the moment Create intent is confirmed; tell the user the path.
-- **File roles.** `decision-log.md` — every decision, change, and version transition, in real time. `addendum.md` — depth that doesn't fit PRD shape: rejected alternatives, technical detail, ops/cost, competitive analysis. Capture technical-how detail to addendum immediately when the user volunteers it.
-- **Continuity across sessions.** If a prior draft exists in `{workflow.output_dir}`, offer to resume; surface open items first.
-- **Extract, don't ingest.** Never load source documents into the parent context wholesale. Delegate to subagents to extract what's relevant; the parent assembles from extracts.
-- **Downstream workflows run in fresh context.** This skill's output is `prd.md` (and optional `addendum.md`). Never invoke downstream workflows or produce separate handoff artifacts.
+**Shape.** Features grouped; FRs nested with globally numbered stable IDs. Cross-cutting NFRs in their own section; skip traceability matrices. Capabilities, not implementation — tech choices live in `addendum.md`. Treat `{workflow.prd_template}` as expert prior knowledge, not a checklist. The **Essential Spine** is the expected default — present it unless the product genuinely doesn't need a section, and when you drop one, do so for a reason a reviewer would agree with. The **Adapt-In Menu** is conditional: pull in the clusters the product's concerns need to best define the requirements. When the product carries a concern the menu doesn't name, invent the section — name it well, decide what belongs in it, place it where it serves the reader or the PRD. Reorder and combine for readability. Never include a section because it appears; never skip a concern because no template section covered it. Counter-metrics named when Success Metrics exist.
+
+**Extract, don't ingest.** Source documents go to subagents for extraction; the parent assembles from extracts. Only load source documents into the parent context wholesale when no subagents are available.
+
+**Length scales with stakes.** Hobby / solo PRDs aim for about two pages. Internal tools land around five to eight. Launch and chain-top PRDs run as long as their FRs and concerns require. Whatever the length, detail that doesn't earn its place in the PRD's main narrative belongs in `addendum.md` — moving overflow there is correct; padding the PRD to look thorough is not.
+
+## Reviewer Gate
+
+Used by the Validate intent and at Finalize step 3.
+
+Assemble the menu: rubric walker against `{workflow.validation_checklist_template}` (the PRD quality rubric) + each entry in `{workflow.finalize_reviewers}` + any ad-hoc reviewers the artifact warrants. Stakes-calibrated — hobby/solo may run quietly or skip; higher stakes get the explicit all/subset/skip menu.
+
+Dispatch entries as parallel subagents against `prd.md` (and `addendum.md` if present) using the standard prefix convention (`skill:` / `file:` / plain text). Each writes its full review to `{doc_workspace}/review-{slug}.md` and returns ONLY a compact summary (verdict, top 2-5 findings, file path) — the parent never holds full review text. The rubric walker uses the prompt and output format in `references/validate.md`. If subagents are unavailable, run sequentially: write the file *before* anything else, then flush the review from working context.
+
+Surface findings tiered, never dumped. Lead with a one-sentence gate verdict, then walk critical + high findings; medium/low roll into a single tail ("plus N more in {file}"). Read the full `review-{slug}.md` only when the user drills into a specific finding. Per finding: autofix, discuss, defer to open items, or ignore.
+
+Under Validate intent, the parent additionally runs the synthesis pipeline in `references/validate.md` — folding every selected reviewer's output into a single HTML + markdown report and opening the HTML.
 
 ## Finalize
 
-1. Decision log audit: walk `decision-log.md` with the user — each entry captured in PRD, in addendum, or set aside.
-2. Input reconciliation: subagent per user-supplied input against `prd.md` + `addendum.md`; surface gaps, especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish.
-3. Discipline pass: validator subagent against `prd.md` with `{workflow.validation_checklist}`. Findings stay in-conversation — autofix obvious issues, ask on ambiguous ones. No report file is written. Resolve before polish.
-4. Open-items review: triage all Open Questions, `[ASSUMPTION]` tags, and `[NOTE FOR PM]` callouts. Surface only phase-blockers one at a time; resolve before calling the PRD ready. Log deferred items to `decision-log.md`. If phase-blocking count is high, flag it.
-5. Polish: apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` via parallel subagents.
-6. External handoffs: execute `{workflow.external_handoffs}` entries; surface returned URLs/IDs. Skip and flag unavailable tools.
-7. Record finalization to `decision-log.md`. Share all artifact paths. Invoke `bmad-help` to share possible steps.
+Tell the user the sequence in one sentence, then walk it. Polish goes last so it does not redo work after reviewer fixes.
+
+1. **Decision log audit.** Walk `.decision-log.md` with the user; each entry captured in PRD, in addendum, or set aside.
+2. **Input reconciliation.** Subagent per user-supplied input against `prd.md` + `addendum.md`. Each writes its extract to `{doc_workspace}/reconcile-{slug}.md` and returns ONLY a compact summary (input name, gaps 2-5, file path). Surface gaps — especially qualitative ideas (tone, voice, feel) the FR structure silently drops. Must happen before polish.
+3. **Reviewer pass.** Run `## Reviewer Gate`. Resolve before polish.
+4. **Triage open items.** All Open Questions, `[ASSUMPTION]` tags, `[NOTE FOR PM]` callouts. Phase-blockers (would make the PRD unsafe for UX/architecture/epics) surfaced one at a time and resolved; non-blockers deferred with owner + revisit condition logged to `.decision-log.md`. If phase-blocker count is high, flag it.
+5. **Polish.** Apply `{workflow.doc_standards}` to `prd.md` and `addendum.md` in declared order (structural passes before prose — prose should not polish soon-to-be-cut text). Parallelize across documents, sequential within.
+6. **External handoffs.** Execute `{workflow.external_handoffs}`; surface returned URLs/IDs. Skip and flag unavailable tools.
+7. **Close.** Set `prd.md` frontmatter `status: final` and `updated` to `{date}` so future invocations distinguish this PRD from in-progress drafts. Record finalization to `.decision-log.md`. Share artifact paths. Common next: `bmad-create-ux-design`, `bmad-create-architecture`, `bmad-create-epics-and-stories`; invoke `bmad-help` for authoritative routing.
 8. Run `{workflow.on_complete}` if non-empty.

package/src/bmm-skills/2-plan-workflows/bmad-prd/assets/headless-schemas.md

@@ -18,7 +18,7 @@ Every headless run ends with one of these payloads. Omit keys for artifacts not
   "intent": "create",
   "prd": "{doc_workspace}/prd.md",
   "addendum": "{doc_workspace}/addendum.md",
-  "decision_log": "{doc_workspace}/decision-log.md",
+  "decision_log": "{doc_workspace}/.decision-log.md",
   "open_questions": [],
   "assumptions": [],
   "external_handoffs": [
@@ -34,7 +34,7 @@ Every headless run ends with one of these payloads. Omit keys for artifacts not
   "status": "complete",
   "intent": "update",
   "prd": "{doc_workspace}/prd.md",
-  "decision_log": "{doc_workspace}/decision-log.md",
+  "decision_log": "{doc_workspace}/.decision-log.md",
   "changes_summary": "1-3 sentences describing what changed and why",
   "conflicts_with_prior_decisions": [],
   "open_questions": [],

package/src/bmm-skills/2-plan-workflows/bmad-prd/assets/prd-template.md

@@ -1,8 +1,4 @@
-# PRD Template — A Menu, Not a Skeleton
-
-This is a menu of sections the facilitator picks from based on what the product, the stakes, the audience, and the existing inputs actually need. Hobby projects use the essential spine and stop. Enterprise initiatives, regulated submissions, and consumer launches add clusters from the adapt-in menu below. **Never include a section just because it appears here.** Drop, reorder, rename, combine — whatever the PRD needs.
-
----
+# PRD Template
 
 ## Essential Spine *(almost always present)*
 
@@ -34,15 +30,30 @@ updated: {YYYY-MM-DD}
 [Who this is explicitly not for in v1.]
 
 ### 2.4 Key User Journeys
-*Named flows the product enables — one line each, numbered globally as UJ-1 through UJ-N for downstream traceability. Detailed flow design (steps, screens, edge flows) is the job of the UX workflow, not this PRD. Features in §4 may reference journeys by ID inline ("realizes UJ-3").*
+*Named-persona narratives the product enables. Numbered globally as UJ-1 through UJ-N. FRs reference journeys by ID inline ("realizes UJ-3"); SMs may also cross-reference. If a UX doc already exists, mirror its UJ IDs here and point to the source.*
+
+**Default shape:** a named scene with entry state, path, climax, and resolution. Each beat forces specificity the team would otherwise leave implicit — auth assumptions, screen order, what tells the user value landed. Read together as a short narrative; the example below shows the form.
 
-- **UJ-1** — [Named flow, one line: who does what, to what end.]
-- **UJ-2** — ...
+- **UJ-1. {One-line title — persona doing the thing.}**
+  - **Persona + context:** one line, grounded enough to explain the *why*.
+  - **Entry state:** authenticated? which surface? coming from where?
+  - **Path:** 3-5 concrete beats — taps, screens, decisions.
+  - **Climax:** the moment value is delivered and how the user knows.
+  - **Resolution:** state they're left in, what's next.
+  - **Edge case** *(optional)*: one real failure mode and what the user does next.
 
-[For hobby/utility projects, 1-3 journeys may be enough. For complex multi-feature products (onboarding, checkout, multi-step approvals), expand. For libraries/CLIs with minimal flow, reduce to a single line or collapse into §2.2 JTBD.]
+  *Written out, that becomes:*
+  > **UJ-3. Priya checks the trip damage before she's even home.**
+  > Priya, budgeting on a single income with a new baby, finishes a grocery run and gets in the car. Already authenticated via biometric on a previous session. She opens the app, taps the FAB camera, and scans the receipt. The app OCRs the total and shows a single-screen overlay: this trip $84.20, weekly cap $250, $172.10 remaining, three days left in the week. She closes the app and drives home. **Edge case:** if she scanned a receipt earlier today, the app asks whether this replaces or adds to that trip before counting it against the cap.
+
+- **UJ-2. ...**
+
+**Scope dial:**
+- **Lighter** — hobby/solo, library/CLI, or when the UJ is essentially a JTBD restated: a single sentence works (`{Persona}, {context}, {what they do and why}.`).
+- **Heavier** — auth, multi-device handoff, complex navigation, or anything feeding downstream UX/architecture: add a numbered Flow, an Edge cases list, and a capability → FR mapping (`The system must {capability}. → FR-N`).
 
 ## 3. Glossary
-*Downstream workflows and readers must use these terms exactly.*
+*Downstream workflows and readers must use these terms exactly. FRs, UJs, and SMs use Glossary terms verbatim; introducing a synonym anywhere in the PRD is a discipline violation. If §4 introduces a new domain noun, add it to the Glossary in the same pass.*
 
 - **Term** — Definition. Relationships to other Glossary terms. Cardinality where relevant.
 - **Term** — ...
@@ -53,11 +64,22 @@ updated: {YYYY-MM-DD}
 *Each subsection is a coherent feature: behavioral description first, FRs nested under it, optional feature-specific NFRs and notes. FRs are numbered globally (FR-1 through FR-N) so downstream artifacts have stable references even if features get reorganized. Reference user journeys by ID inline ("realizes UJ-2") where the chain matters.*
 
 ### 4.1 {Feature Name}
-**Description:** [Behavioral narrative — how this feature works, who uses it, the user experience, edge cases. Use Glossary terms exactly. Embed inline `[ASSUMPTION: ...]` tags where you inferred without confirmation.]
+**Description:** [Behavioral narrative — how this feature works, who uses it, the user experience, edge cases. Realizes UJ-X, UJ-Y. Use Glossary terms exactly. Embed inline `[ASSUMPTION: ...]` tags where you inferred without confirmation.]
 
 **Functional Requirements:**
-- **FR-1** — [Actor] can [capability] [under conditions / with measurement].
-- **FR-2** — ...
+
+#### FR-1: {Short capability name}
+
+[Actor] can [capability] [under conditions]. Realizes UJ-X.
+
+**Consequences (testable):**
+- {Specific testable condition, e.g. "System returns HTTP 429 when request rate exceeds 100/sec per merchant."}
+- {Another testable condition.}
+
+**Out of Scope:** *(optional — what this FR explicitly does NOT cover)*
+- {bound}
+
+#### FR-2: ...
 
 **Feature-specific NFRs:** *(only if any apply uniquely to this feature)*
 - Performance / security / accessibility / etc. specific to this feature.
@@ -80,14 +102,16 @@ updated: {YYYY-MM-DD}
 
 ## 7. Success Metrics
 
+*Each SM cross-references the FR(s) it validates. Counter-metrics counterbalance specific primary or secondary metrics.*
+
 **Primary**
-- Metric — definition, target.
+- **SM-1**: Metric — definition, target. Validates FR-X, FR-Y.
 
 **Secondary**
-- Metric — definition, target.
+- **SM-2**: Metric — definition, target. Validates FR-Z.
 
 **Counter-metrics (do not optimize)**
-- Metric — why this should *not* be optimized.
+- **SM-C1**: Metric — why this should *not* be optimized. Counterbalances SM-1.
 
 [Length scales with stakes. Hobby/utility PRD: a single sentence may be enough ("Success: I use this weekly and don't abandon it after a month"). Public launch / enterprise: full quantitative breakdown with measurement methods. Counter-metrics are as load-bearing as primary metrics — they prevent the architect from optimizing the wrong thing and the dev from gaming the wrong target.]
 
@@ -142,17 +166,3 @@ updated: {YYYY-MM-DD}
 ### Small-scope all-inclusive *(use when scope is 1-2 stories' worth and the user wants a single captured artifact — chosen during the Right-skill check in Discovery)*
 - **Stories** — story-level specs listed inline at the end of the doc. Each story: *"As a [persona], I can [action] [under conditions]. Acceptance: [testable criteria]."* Numbered Story-1, Story-2, ... for reference. Pair with very lean §1 Vision, §2 Target User (often just JTBD + one UJ), §3 Glossary (handful of terms), §4 Features (often a single feature), §6 MVP Scope (in/out very tight). The whole doc fits on a page or two and captures intent + implementable stories in one place. If the user doesn't want the captured artifact at all, `bmad-quick-dev` is the better path — this cluster is only for "I want a doc *and* the stories."
 
----
-
-## Notes for the facilitator
-
-- **The essential spine is the floor, not the ceiling.** A hobby PRD might keep all ten sections short. An enterprise PRD layers many clusters from the adapt-in menu.
-- **§3 Glossary before §4 Features.** Mechanics never introduce a new domain noun without adding it to the Glossary in the same pass. Persona, JTBD, and Journeys may use Glossary terms before §3 formally defines them — context is inferable; the Glossary is for downstream anchoring.
-- **§2.4 Key User Journeys are brief.** One line each. Numbered globally (UJ-1 through UJ-N) so architecture, epics, stories, and tickets can reference them by stable ID. Detailed flow design happens in the UX workflow — not here.
-- **§4 Features pattern at every scale.** Description → FRs nested → optional NFRs → optional notes. Hobby PRD: one short paragraph and three FRs per feature. Enterprise feature: multi-paragraph description, fifteen FRs, several feature-specific NFRs, open questions. Same shape, different depth.
-- **`[ASSUMPTION]`, `[NON-GOAL]`, `[v2 — out of MVP]`, `[NOTE FOR PM]` callouts are first-class.** They signal to downstream readers and the next session of work. Every `[ASSUMPTION]` lands in §9 Assumptions Index.
-- **When UX is *input* to the PRD** (journeys already designed elsewhere): §2.4 names the journeys by ID and points to the existing UX doc. Reference, do not duplicate.
-- **When UX is *output* of the PRD** (no UX work yet — downstream `bmad-create-ux-design` will produce it): §2.4 captures the PM's intent on which journeys exist; UX elaborates them into detailed flows downstream.
-- **§7 Success Metrics scales with stakes** but is always present. Counter-metrics matter as much as primary metrics — they shape what NOT to optimize.
-- **Small-scope all-inclusive option.** When scope is genuinely 1-2 stories and the user wants a single artifact instead of running a separate `bmad-create-story` workflow, add the adapt-in *Stories* cluster: lean §1-§6 plus inline §Stories at the end. The whole doc fits on a page or two. This is a valid PRD shape for tiny work — don't apologize for it.
-- **Adapt the section numbering.** The spine uses 0-9; adapt-in additions slot in wherever they read best (e.g., Aesthetic & Tone before §3 if branding is foundational, Compliance after §5 Non-Goals, Constraints & Guardrails between Features and Non-Goals, Stories at the very end after Assumptions Index).