bmad-method-quarkus 1.0.0

package/src/bmm-skills/plan/bmad-create-epics-and-stories/steps/step-03-create-stories.md

@@ -0,0 +1,255 @@
+# Step 3: Generate Epics and Stories
+
+## STEP GOAL:
+
+To generate all epics with their stories based on the approved epics_list, following the template structure exactly.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process epics sequentially
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring story creation and acceptance criteria expertise
+- ✅ User brings their implementation priorities and constraints
+
+### Step-Specific Rules:
+
+- 🎯 Generate stories for each epic following the template exactly
+- 🚫 FORBIDDEN to deviate from template structure
+- 💬 Each story must have clear acceptance criteria
+- 🚪 ENSURE each story is completable by a single dev agent
+- 🔗 **CRITICAL: Stories MUST NOT depend on future stories within the same epic**
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Generate stories collaboratively with user input
+- 💾 Append epics and stories to {planning_artifacts}/epics.md following template
+- 📖 Process epics one at a time in sequence
+- 🚫 FORBIDDEN to skip any epic or rush through stories
+
+## STORY GENERATION PROCESS:
+
+### 1. Load Approved Epic Structure
+
+Load {planning_artifacts}/epics.md and review:
+
+- Approved epics_list from Step 2
+- FR coverage map
+- All requirements (FRs, NFRs, additional, **UX Design requirements if present**)
+- Template structure at the end of the document
+
+**UX Design Integration**: If UX Design Requirements (UX-DRs) were extracted in Step 1, ensure they are visible during story creation. UX-DRs must be covered by stories — either within existing epics (e.g., accessibility fixes for a feature epic) or in a dedicated "Design System / UX Polish" epic.
+
+### 2. Explain Story Creation Approach
+
+**STORY CREATION GUIDELINES:**
+
+For each epic, create stories that:
+
+- Follow the exact template structure
+- Are sized for single dev agent completion
+- Have clear user value
+- Include specific acceptance criteria
+- Reference requirements being fulfilled
+
+**🚨 DATABASE/ENTITY CREATION PRINCIPLE:**
+Create tables/entities ONLY when needed by the story:
+
+- ❌ WRONG: Epic 1 Story 1 creates all 50 database tables
+- ✅ RIGHT: Each story creates/alters ONLY the tables it needs
+
+**🔗 STORY DEPENDENCY PRINCIPLE:**
+Stories must be independently completable in sequence:
+
+- ❌ WRONG: Story 1.2 requires Story 1.3 to be completed first
+- ✅ RIGHT: Each story can be completed based only on previous stories
+- ❌ WRONG: "Wait for Story 1.4 to be implemented before this works"
+- ✅ RIGHT: "This story works independently and enables future stories"
+
+**STORY FORMAT (from template):**
+
+```
+### Story {N}.{M}: {story_title}
+
+As a {user_type},
+I want {capability},
+So that {value_benefit}.
+
+**Acceptance Criteria:**
+
+**Given** {precondition}
+**When** {action}
+**Then** {expected_outcome}
+**And** {additional_criteria}
+```
+
+**✅ GOOD STORY EXAMPLES:**
+
+_Epic 1: User Authentication_
+
+- Story 1.1: User Registration with Email
+- Story 1.2: User Login with Password
+- Story 1.3: Password Reset via Email
+
+_Epic 2: Content Creation_
+
+- Story 2.1: Create New Blog Post
+- Story 2.2: Edit Existing Blog Post
+- Story 2.3: Publish Blog Post
+
+**❌ BAD STORY EXAMPLES:**
+
+- Story: "Set up database" (no user value)
+- Story: "Create all models" (too large, no user value)
+- Story: "Build authentication system" (too large)
+- Story: "Login UI (depends on Story 1.3 API endpoint)" (future dependency!)
+- Story: "Edit post (requires Story 1.4 to be implemented first)" (wrong order!)
+
+### 3. Process Epics Sequentially
+
+For each epic in the approved epics_list:
+
+#### A. Epic Overview
+
+Display:
+
+- Epic number and title
+- Epic goal statement
+- FRs covered by this epic
+- Any NFRs or additional requirements relevant
+- Any UX Design Requirements (UX-DRs) relevant to this epic
+
+#### B. Story Breakdown
+
+Work with user to break down the epic into stories:
+
+- Identify distinct user capabilities
+- Ensure logical flow within the epic
+- Size stories appropriately
+
+#### C. Generate Each Story
+
+For each story in the epic:
+
+1. **Story Title**: Clear, action-oriented
+2. **User Story**: Complete the As a/I want/So that format
+3. **Acceptance Criteria**: Write specific, testable criteria
+
+**AC Writing Guidelines:**
+
+- Use Given/When/Then format
+- Each AC should be independently testable
+- Include edge cases and error conditions
+- Reference specific requirements when applicable
+
+#### D. Collaborative Review
+
+After writing each story:
+
+- Present the story to user
+- Ask: "Does this story capture the requirement correctly?"
+- "Is the scope appropriate for a single dev session?"
+- "Are the acceptance criteria complete and testable?"
+
+#### E. Append to Document
+
+When story is approved:
+
+- Append it to {planning_artifacts}/epics.md following template structure
+- Use correct numbering (Epic N, Story M)
+- Maintain proper markdown formatting
+
+### 4. Epic Completion
+
+After all stories for an epic are complete:
+
+- Display epic summary
+- Show count of stories created
+- Verify all FRs for the epic are covered
+- Get user confirmation to proceed to next epic
+
+### 5. Repeat for All Epics
+
+Continue the process for each epic in the approved list, processing them in order (Epic 1, Epic 2, etc.).
+
+### 6. Final Document Completion
+
+After all epics and stories are generated:
+
+- Verify the document follows template structure exactly
+- Ensure all placeholders are replaced
+- Confirm all FRs are covered
+- **Confirm all UX Design Requirements (UX-DRs) are covered by at least one story** (if UX document was an input)
+- Check formatting consistency
+
+## TEMPLATE STRUCTURE COMPLIANCE:
+
+The final {planning_artifacts}/epics.md must follow this structure exactly:
+
+1. **Overview** section with project name
+2. **Requirements Inventory** with all three subsections populated
+3. **FR Coverage Map** showing requirement to epic mapping
+4. **Epic List** with approved epic structure
+5. **Epic sections** for each epic (N = 1, 2, 3...)
+   - Epic title and goal
+   - All stories for that epic (M = 1, 2, 3...)
+     - Story title and user story
+     - Acceptance Criteria using Given/When/Then format
+
+### 7. Present FINAL MENU OPTIONS
+
+After all epics and stories are complete:
+
+Display: "**Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue"
+
+#### Menu Handling Logic:
+
+- IF A: Invoke the `bmad-advanced-elicitation` skill
+- IF P: Invoke the `bmad-party-mode` skill
+- IF C: Save content to {planning_artifacts}/epics.md, update frontmatter, then read fully and follow: ./step-04-final-validation.md
+- IF Any other comments or queries: help user respond then [Redisplay Menu Options](#7-present-final-menu-options)
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- After other menu items execution, return to this menu
+- User can chat or ask questions - always respond and then end with display again of the menu options
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN [C continue option] is selected and [all epics and stories saved to document following the template structure exactly], will you then read fully and follow: `./step-04-final-validation.md` to begin final validation phase.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All epics processed in sequence
+- Stories created for each epic
+- Template structure followed exactly
+- All FRs covered by stories
+- Stories appropriately sized
+- Acceptance criteria are specific and testable
+- Document is complete and ready for development
+
+### ❌ SYSTEM FAILURE:
+
+- Deviating from template structure
+- Missing epics or stories
+- Stories too large or unclear
+- Missing acceptance criteria
+- Not following proper formatting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/bmm-skills/plan/bmad-create-epics-and-stories/steps/step-04-final-validation.md

@@ -0,0 +1,143 @@
+# Step 4: Final Validation
+
+## STEP GOAL:
+
+To validate complete coverage of all requirements and ensure stories are ready for development.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: Process validation sequentially without skipping
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a product strategist and technical specifications writer
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring validation expertise and quality assurance
+- ✅ User brings their implementation priorities and final review
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on validating complete requirements coverage
+- 🚫 FORBIDDEN to skip any validation checks
+- 💬 Validate FR coverage, story completeness, and dependencies
+- 🚪 ENSURE all stories are ready for development
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Validate every requirement has story coverage
+- 💾 Check story dependencies and flow
+- 📖 Verify architecture compliance
+- 🚫 FORBIDDEN to approve incomplete coverage
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete epic and story breakdown from previous steps
+- Focus: Final validation of requirements coverage and story readiness
+- Limits: Validation only, no new content creation
+- Dependencies: Completed story generation from Step 3
+
+## VALIDATION PROCESS:
+
+### 1. FR Coverage Validation
+
+Review the complete epic and story breakdown to ensure EVERY FR is covered:
+
+**CRITICAL CHECK:**
+
+- Go through each FR from the Requirements Inventory
+- Verify it appears in at least one story
+- Check that acceptance criteria fully address the FR
+- No FRs should be left uncovered
+
+### 2. Architecture Implementation Validation
+
+**Check for Starter Template Setup:**
+
+- Does Architecture document specify a starter template?
+- If YES: Epic 1 Story 1 must be "Set up initial project from starter template"
+- This includes cloning, installing dependencies, initial configuration
+
+**Database/Entity Creation Validation:**
+
+- Are database tables/entities created ONLY when needed by stories?
+- ❌ WRONG: Epic 1 creates all tables upfront
+- ✅ RIGHT: Tables created as part of the first story that needs them
+- Each story should create/modify ONLY what it needs
+
+### 3. Story Quality Validation
+
+**Each story must:**
+
+- Be completable by a single dev agent
+- Have clear acceptance criteria
+- Reference specific FRs it implements
+- Include necessary technical details
+- **Not have forward dependencies** (can only depend on PREVIOUS stories)
+- Be implementable without waiting for future stories
+
+### 4. Epic Structure Validation
+
+**Check that:**
+
+- Epics deliver user value, not technical milestones
+- Dependencies flow naturally
+- Foundation stories only setup what's needed
+- No big upfront technical work
+- **File Churn Check:** Do multiple epics repeatedly modify the same core files?
+  - Assess whether the overlap pattern suggests unnecessary churn or is incidental
+  - If overlap is significant: Validate that splitting provides genuine value (risk mitigation, feedback loops, context size limits)
+  - If no justification for the split: Recommend consolidation into fewer epics
+  - ❌ WRONG: Multiple epics each modify the same core files with no feedback loop between them
+  - ✅ RIGHT: Epics target distinct files/components, OR consolidation was explicitly considered and rejected with rationale
+
+### 5. Dependency Validation (CRITICAL)
+
+**Epic Independence Check:**
+
+- Does each epic deliver COMPLETE functionality for its domain?
+- Can Epic 2 function without Epic 3 being implemented?
+- Can Epic 3 function standalone using Epic 1 & 2 outputs?
+- ❌ WRONG: Epic 2 requires Epic 3 features to work
+- ✅ RIGHT: Each epic is independently valuable
+
+**Within-Epic Story Dependency Check:**
+For each epic, review stories in order:
+
+- Can Story N.1 be completed without Stories N.2, N.3, etc.?
+- Can Story N.2 be completed using only Story N.1 output?
+- Can Story N.3 be completed using only Stories N.1 & N.2 outputs?
+- ❌ WRONG: "This story depends on a future story"
+- ❌ WRONG: Story references features not yet implemented
+- ✅ RIGHT: Each story builds only on previous stories
+
+### 6. Complete and Save
+
+If all validations pass:
+
+- Update any remaining placeholders in the document
+- Ensure proper formatting
+- Save the final epics.md
+
+**Present Final Menu:**
+**All validations complete!** [C] Complete Workflow
+
+HALT — wait for user input before proceeding.
+
+When C is selected, the workflow is complete and the epics.md is ready for development.
+
+Epics and Stories complete. Invoke the `bmad-help` skill.
+
+Upon Completion of task output: offer to answer any questions about the Epics and Stories.
+
+## On Complete
+
+Run: `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolved `workflow.on_complete` is non-empty, follow it as the final terminal instruction before exiting.

package/src/bmm-skills/plan/bmad-create-epics-and-stories/templates/epics-template.md

@@ -0,0 +1,61 @@
+---
+stepsCompleted: []
+inputDocuments: []
+---
+
+# {{project_name}} - Epic Breakdown
+
+## Overview
+
+This document provides the complete epic and story breakdown for {{project_name}}, decomposing the requirements from the PRD, UX Design if it exists, and Architecture requirements into implementable stories.
+
+## Requirements Inventory
+
+### Functional Requirements
+
+{{fr_list}}
+
+### NonFunctional Requirements
+
+{{nfr_list}}
+
+### Additional Requirements
+
+{{additional_requirements}}
+
+### UX Design Requirements
+
+{{ux_design_requirements}}
+
+### FR Coverage Map
+
+{{requirements_coverage_map}}
+
+## Epic List
+
+{{epics_list}}
+
+<!-- Repeat for each epic in epics_list (N = 1, 2, 3...) -->
+
+## Epic {{N}}: {{epic_title_N}}
+
+{{epic_goal_N}}
+
+<!-- Repeat for each story (M = 1, 2, 3...) within epic N -->
+
+### Story {{N}}.{{M}}: {{story_title_N_M}}
+
+As a {{user_type}},
+I want {{capability}},
+So that {{value_benefit}}.
+
+**Acceptance Criteria:**
+
+<!-- for each AC on this story -->
+
+**Given** {{precondition}}
+**When** {{action}}
+**Then** {{expected_outcome}}
+**And** {{additional_criteria}}
+
+<!-- End story repeat -->

package/src/bmm-skills/plan/bmad-generate-project-context/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: bmad-generate-project-context
+description: 'Deprecated — forwards to bmad-project-context. Use when the user says "generate project context" or "create project context"'
+---
+
+# DEPRECATED — forwards to bmad-project-context
+
+Tell the user: this skill is deprecated — `bmad-project-context` now owns this job. Instead of one generated `project-context.md`, it writes a small verified block inside the repo's `AGENTS.md`, and any existing `project-context.md` is offered up for absorption rather than left orphaned. Invoke `bmad-project-context` next time.
+
+Then invoke `bmad-project-context` with **setup** intent, forwarding the user's original request and any inputs they supplied (architecture doc, spec, standards, preferences), verbatim. It takes the workflow from here.

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

@@ -0,0 +1,94 @@
+---
+name: bmad-prd
+description: Create, update, or validate a PRD. Use when the user wants help producing, editing, or validating a PRD.
+---
+# BMad PRD
+
+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.
+
+## Conventions
+
+- 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.** `.memlog.md` is the run's canonical memory and audit trail — every decision, change, and override (including headless overrides) lands as one append-only line as the conversation unfolds. All writes go through the shared script, never by hand: `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type <decision|change|override|assumption|event> --text "<one-line gist, reason included>"` (atomic; read it back only to resume or audit). The PRD is distilled toward it; whatever isn't logged is lost on resume. `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
+
+**Forwarded activation:** if a caller invoked you with a stated intent and pre-resolved customization fields (e.g. the `bmad-create-prd` / `bmad-edit-prd` / `bmad-validate-prd` shims), honor them verbatim — skip your own intent inference, use the supplied values for those named fields, and resolve only the remaining fields from your own `customize.toml`.
+
+1. Resolve customization: `uv run {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-build`; 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.
+
+Run `{workflow.activation_steps_append}`.
+
+Activation is complete. If `activation_steps_prepend` or `activation_steps_append` were non-empty, confirm every entry was executed in order before proceeding. Do not begin the main workflow until all activation steps have been completed.
+
+## Intent Modes
+
+**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 seed the memlog with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace} --field topic="<PRD/product name>"` so subsequent decisions land in a known file. Tell the user the path. Run `## Discovery`, then `## Finalize`.
+
+**Update.** Reconcile the PRD with a change signal. Source-extract against PRD, addendum, `.memlog.md`, and original inputs (extract, don't ingest). If `.memlog.md` is missing, init it with `uv run {project-root}/_bmad/scripts/memlog.py init --workspace {doc_workspace}`, then spawn a one-time bootstrap subagent to reverse-engineer a thin log from the PRD (one `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type decision --text "<recovered decision>"` per recovered decision) before continuing. Surface conflicts with prior decisions before applying. Then `## Finalize`.
+
+**Validate** (or *analyze*). Critique without changing. Load `references/validate.md`.
+
+## Discovery
+
+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.
+
+**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.
+
+**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.
+
+**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.
+
+**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.
+
+**Working mode.** Offer the choice in the user's language:
+
+- **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), **Journey-led** (user-first — for consumer, UX-heavy, multi-stakeholder products; journeys with named protagonists carry persona context inline, no standalone persona section), or *let me suggest* based on what I heard. The chosen entry sets the section order.
+
+The workspace persists; stop and resume freely.
+
+**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.
+
+**Form-factor.** If not stated in sources, probe — mobile / web / desktop / multi-surface / hardware / API.
+
+**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 with a named protagonist (Mary, mom of three — not "the user") — what the person does, in what order, where it lands — then structure the answer into UJ-N form and confirm. Persona context lives inline at the moments that matter; no standalone persona section.
+
+## PRD Discipline
+
+**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
+
+Tell the user the sequence in one sentence, then walk it. Polish goes last so it does not redo work after reviewer fixes.
+
+1. **Memlog audit.** Walk `.memlog.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 via `memlog.py append`. 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 via `uv run {project-root}/_bmad/scripts/memlog.py append --workspace {doc_workspace} --type event --text "PRD finalized"`. Share artifact paths. Common next: `bmad-ux`, `bmad-architecture`, `bmad-create-epics-and-stories`; invoke `bmad-help` for authoritative routing.
+8. Run `{workflow.on_complete}` if non-empty.

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

@@ -0,0 +1,76 @@
+# Headless Mode JSON Schemas
+
+Every headless run ends with one of these payloads. Omit keys for artifacts not produced.
+
+## Common fields
+
+- `status` — `"complete"`, `"blocked"`, or `"partial"`
+- `intent` — `"create"`, `"update"`, or `"validate"` (matches the detected intent)
+- `reason` — required when `status` is `"blocked"`; one-sentence explanation
+- `assumptions` — array of inferred values that were not directly confirmed by inputs
+- `open_questions` — array of items that need a human decision before the artifact can be considered final
+
+## Create
+
+```json
+{
+  "status": "complete",
+  "intent": "create",
+  "prd": "{doc_workspace}/prd.md",
+  "addendum": "{doc_workspace}/addendum.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "open_questions": [],
+  "assumptions": [],
+  "external_handoffs": [
+    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
+  ]
+}
+```
+
+## Update
+
+```json
+{
+  "status": "complete",
+  "intent": "update",
+  "prd": "{doc_workspace}/prd.md",
+  "memlog": "{doc_workspace}/.memlog.md",
+  "changes_summary": "1-3 sentences describing what changed and why",
+  "conflicts_with_prior_decisions": [],
+  "open_questions": [],
+  "external_handoffs": [
+    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/PROD/123", "status": "ok"}
+  ]
+}
+```
+
+## Validate
+
+```json
+{
+  "status": "complete",
+  "intent": "validate",
+  "validation_report": "{doc_workspace}/validation-report.md",
+  "findings_summary": {
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  },
+  "offer_to_update": true
+}
+```
+
+`validation_report` is always written for Validate intent — the path here is required, not optional.
+
+## Blocked
+
+```json
+{
+  "status": "blocked",
+  "intent": "update",
+  "reason": "Change signal ambiguous — could be a scope expansion or a clarification; no inferred direction"
+}
+```
+
+Always include the intent (best-guess if not certain) and a one-sentence `reason`.