Merge bee45a6d58 into 7b4875be79

Subtract agents from total skill directories so the summary shows
non-agent skills and agents as distinct counts (e.g. 34 skills, 10
agents) instead of double-counting agents in the skill total.

.github/workflows/quality.yaml

@@ -112,5 +112,8 @@ jobs:
       - name: Test agent compilation components
         run: npm run test:install
 
+      - name: Test module extension installer
+        run: npm run test:install:extensions
+
       - name: Validate file references
         run: npm run validate:refs

.npmignore

@@ -0,0 +1,40 @@
+# Development & Testing
+test/
+.husky/
+.github/
+.vscode/
+.augment/
+coverage/
+test-output/
+
+# Documentation site (users access docs online)
+docs/
+website/
+
+# Configuration files (development only)
+.coderabbit.yaml
+.markdownlint-cli2.yaml
+.prettierignore
+.nvmrc
+eslint.config.mjs
+prettier.config.mjs
+
+# Build tools (not needed at runtime)
+tools/build-docs.mjs
+tools/fix-doc-links.js
+tools/validate-doc-links.js
+tools/validate-file-refs.js
+tools/validate-agent-schema.js
+
+# Images (branding/marketing only)
+banner-bmad-method.png
+Wordmark.png
+
+# Repository metadata
+CONTRIBUTING.md
+CONTRIBUTORS.md
+SECURITY.md
+TRADEMARK.md
+CHANGELOG.md
+CNAME
+CODE_OF_CONDUCT.md

docs/reference/agents.md

@@ -26,3 +26,33 @@ This page lists the default BMM (Agile suite) agents that install with BMad Meth
 | Quick Flow Solo Dev (Barry) | `bmad-master`        | `QS`, `QD`, `CR`                   | Quick Spec, Quick Dev, Code Review                                                                  |
 | UX Designer (Sally)         | `bmad-ux-designer`   | `CU`                               | Create UX Design                                                                                    |
 | Technical Writer (Paige)    | `bmad-tech-writer`   | `DP`, `WD`, `US`, `MG`, `VD`, `EC` | Document Project, Write Document, Update Standards, Mermaid Generate, Validate Doc, Explain Concept |
+
+## Trigger Types
+
+Agent menu triggers use two different invocation types. Knowing which type a trigger uses helps you provide the right input.
+
+### Workflow triggers (no arguments needed)
+
+Most triggers load a structured workflow file. Type the trigger code and the agent starts the workflow, prompting you for input at each step.
+
+Examples: `CP` (Create PRD), `DS` (Dev Story), `CA` (Create Architecture), `QS` (Quick Spec)
+
+### Conversational triggers (arguments required)
+
+Some triggers start a free-form conversation instead of a structured workflow. These expect you to describe what you need alongside the trigger code.
+
+| Agent | Trigger | What to provide |
+| --- | --- | --- |
+| Technical Writer (Paige) | `WD` | Description of the document to write |
+| Technical Writer (Paige) | `US` | Preferences or conventions to add to standards |
+| Technical Writer (Paige) | `MG` | Diagram description and type (sequence, flowchart, etc.) |
+| Technical Writer (Paige) | `VD` | Document to validate and focus areas |
+| Technical Writer (Paige) | `EC` | Concept name to explain |
+
+**Example:**
+
+```text
+WD Write a deployment guide for our Docker setup
+MG Create a sequence diagram showing the auth flow
+EC Explain how the module system works
+```

docs/reference/testing.md

@@ -95,11 +95,11 @@ TEA also supports P0-P3 risk-based prioritization and optional integrations with
 
 ## How Testing Fits into Workflows
 
-Quinn's Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. A typical sequence:
+Quinn's Automate workflow appears in Phase 4 (Implementation) of the BMad Method workflow map. It is designed to run **after a full epic is complete** — once all stories in an epic have been implemented and code-reviewed. A typical sequence:
 
-1. Implement a story with the Dev workflow (`DS`)
-2. Generate tests with Quinn (`QA`) or TEA's Automate workflow
-3. Validate implementation with Code Review (`CR`)
+1. For each story in the epic: implement with Dev (`DS`), then validate with Code Review (`CR`)
+2. After the epic is complete: generate tests with Quinn (`QA`) or TEA's Automate workflow
+3. Run retrospective (`bmad-retrospective`) to capture lessons learned
 
 Quinn works directly from source code without loading planning documents (PRD, architecture). TEA workflows can integrate with upstream planning artifacts for traceability.
 

package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.0.4",
+  "version": "6.0.5",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -40,9 +40,10 @@
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
     "rebundle": "node tools/cli/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:schemas && npm run test:refs && npm run test:install && npm run test:install:extensions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
     "test:install": "node test/test-installation-components.js",
+    "test:install:extensions": "node test/test-installation-extensions.js",
     "test:refs": "node test/test-file-refs-csv.js",
     "test:schemas": "node test/test-agent-schema.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

src/bmm/workflows/1-analysis/create-product-brief/steps/step-02-vision.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 2: Product Vision Discovery

src/bmm/workflows/1-analysis/create-product-brief/steps/step-03-users.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 3: Target Users Discovery

src/bmm/workflows/1-analysis/create-product-brief/steps/step-04-metrics.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 4: Success Metrics Definition

src/bmm/workflows/1-analysis/create-product-brief/steps/step-05-scope.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/product-brief-{{project_name}}-{{date}}.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 5: MVP Scope Definition

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02-discovery.md

@@ -12,7 +12,7 @@ domainComplexityCSV: '../data/domain-complexity.csv'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 2: Project Discovery

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02b-vision.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 2b: Product Vision Discovery

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-02c-executive-summary.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 2c: Executive Summary Generation

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-03-success.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 3: Success Criteria Definition

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-04-journeys.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 4: User Journey Mapping

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-05-domain.md

@@ -9,7 +9,7 @@ domainComplexityCSV: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 5: Domain-Specific Requirements (Optional)

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-06-innovation.md

@@ -11,7 +11,7 @@ projectTypesCSV: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 6: Innovation Discovery

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-07-project-type.md

@@ -11,7 +11,7 @@ projectTypesCSV: '../data/project-types.csv'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 7: Project-Type Deep Dive

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-08-scoping.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 8: Scoping Exercise - MVP & Future Features

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-09-functional.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 9: Functional Requirements Synthesis

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-10-nonfunctional.md

@@ -8,7 +8,7 @@ outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 10: Non-Functional Requirements

src/bmm/workflows/2-plan-workflows/create-prd/steps-c/step-11-polish.md

@@ -9,7 +9,7 @@ purposeFile: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/dat
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step 11: Document Polish
@@ -99,6 +99,22 @@ Review the entire document with PRD purpose principles in mind:
 - Are technical terms used appropriately?
 - Would stakeholders find this easy to understand?
 
+### 2b. Brainstorming Reconciliation (if brainstorming input exists)
+
+**Check the PRD frontmatter `inputDocuments` for any brainstorming document** (e.g., `brainstorming-session*.md`, `brainstorming-report.md`). If a brainstorming document was used as input:
+
+1. **Load the brainstorming document** and extract all distinct ideas, themes, and recommendations
+2. **Cross-reference against the PRD** — for each brainstorming idea, check if it landed in any PRD section (requirements, success criteria, user journeys, scope, etc.)
+3. **Identify dropped ideas** — ideas from brainstorming that do not appear anywhere in the PRD. Pay special attention to:
+   - Tone, personality, and interaction design ideas (these are most commonly lost)
+   - Design philosophy and coaching approach ideas
+   - "What should this feel like" ideas (UX feel, not just UX function)
+   - Qualitative/soft ideas that don't map cleanly to functional requirements
+4. **Present findings to user**: "These brainstorming ideas did not make it into the PRD: [list]. Should any be incorporated?"
+5. **If user wants to incorporate dropped ideas**: Add them to the most appropriate PRD section (success criteria, non-functional requirements, or a new section if needed)
+
+**Why this matters**: Brainstorming documents are often long, and the PRD's structured template has an implicit bias toward concrete/structural ideas. Soft ideas (tone, philosophy, interaction feel) frequently get silently dropped because they don't map cleanly to FR/NFR format.
+
 ### 3. Optimization Actions
 
 Make targeted improvements:
@@ -193,6 +209,7 @@ When user selects 'C', replace the entire document content with the polished ver
 ✅ User's voice and intent preserved
 ✅ Document is more readable and professional
 ✅ A/P/C menu presented and handled correctly
+✅ Brainstorming reconciliation completed (if brainstorming input exists)
 ✅ Polished document saved when C selected
 
 ## FAILURE MODES:

src/bmm/workflows/2-plan-workflows/create-prd/steps-e/step-e-01-discovery.md

@@ -6,7 +6,7 @@ description: 'Discovery & Understanding - Understand what user wants to edit and
 altStepFile: './step-e-01b-legacy-conversion.md'
 prdPurpose: '{project-root}/_bmad/bmm/workflows/2-plan-workflows/create-prd/data/prd-purpose.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 ---
 
 # Step E-1: Discovery & Understanding

src/bmm/workflows/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md

@@ -5,7 +5,7 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 prdPurpose: '../data/prd-purpose.md'
 ---
 

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-02-discovery.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-03-core-experience.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -169,7 +169,7 @@ Show the generated core experience content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current core experience definition
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current core experience definition
 - Process the collaborative experience improvements that come back
 - Ask user: "Accept these changes to the core experience definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-04-emotional-response.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -172,7 +172,7 @@ Show the generated emotional response content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current emotional response definition
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current emotional response definition
 - Process the collaborative emotional insights that come back
 - Ask user: "Accept these changes to the emotional response definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-05-inspiration.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -187,7 +187,7 @@ Show the generated inspiration analysis content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current inspiration analysis
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current inspiration analysis
 - Process the collaborative pattern insights that come back
 - Ask user: "Accept these changes to the inspiration analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-06-design-system.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -205,7 +205,7 @@ Show the generated design system content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current design system choice
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design system choice
 - Process the collaborative design system insights that come back
 - Ask user: "Accept these changes to the design system decision? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-07-defining-experience.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -207,7 +207,7 @@ Show the generated defining experience content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current defining experience
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current defining experience
 - Process the collaborative experience insights that come back
 - Ask user: "Accept these changes to the defining experience? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-08-visual-foundation.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -177,7 +177,7 @@ Show the generated visual foundation content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current visual foundation
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current visual foundation
 - Process the collaborative visual insights that come back
 - Ask user: "Accept these changes to the visual foundation? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-09-design-directions.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -177,7 +177,7 @@ Show the generated design direction content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current design direction
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design direction
 - Process the collaborative design insights that come back
 - Ask user: "Accept these changes to the design direction? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-10-user-journeys.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -195,7 +195,7 @@ Show the generated user journey content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current user journeys
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current user journeys
 - Process the collaborative journey insights that come back
 - Ask user: "Accept these changes to the user journeys? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-11-component-strategy.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -201,7 +201,7 @@ Show the generated component strategy content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current component strategy
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current component strategy
 - Process the collaborative component insights that come back
 - Ask user: "Accept these changes to the component strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-12-ux-patterns.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -190,7 +190,7 @@ Show the generated UX patterns content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current UX patterns
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current UX patterns
 - Process the collaborative pattern insights that come back
 - Ask user: "Accept these changes to the UX patterns? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/2-plan-workflows/create-ux-design/steps/step-13-responsive-accessibility.md

@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -217,7 +217,7 @@ Show the generated responsive and accessibility content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current responsive/accessibility strategy
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current responsive/accessibility strategy
 - Process the collaborative insights that come back
 - Ask user: "Accept these changes to the responsive/accessibility strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-02-context.md

@@ -32,7 +32,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -178,7 +178,7 @@ Show the generated content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with the current project context
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current project context
 - Process the collaborative improvements to architectural understanding
 - Ask user: "Accept these changes to the project context analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-03-starter.md

@@ -32,7 +32,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -284,7 +284,7 @@ Show the generated content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with starter evaluation context
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with starter evaluation context
 - Process collaborative insights about starter trade-offs
 - Ask user: "Accept these changes to the starter template evaluation? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-04-decisions.md

@@ -33,7 +33,7 @@ This step will generate content and present choices for each decision category:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -272,7 +272,7 @@ Show the generated decisions content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with architectural decisions context
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with architectural decisions context
 - Process collaborative insights about decision trade-offs
 - Ask user: "Accept these changes to the architectural decisions? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-05-patterns.md

@@ -33,7 +33,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -313,7 +313,7 @@ Show the generated patterns content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with implementation patterns context
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with implementation patterns context
 - Process collaborative insights about potential conflicts
 - Ask user: "Accept these changes to the implementation patterns? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-06-structure.md

@@ -33,7 +33,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -333,7 +333,7 @@ Show the generated project structure content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with project structure context
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with project structure context
 - Process collaborative insights about organization trade-offs
 - Ask user: "Accept these changes to the project structure? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-architecture/steps/step-07-validation.md

@@ -33,7 +33,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md
+- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
@@ -313,7 +313,7 @@ Show the validation results and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/party-mode/workflow.md with validation context
+- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with validation context
 - Process collaborative insights on implementation readiness
 - Ask user: "Accept these changes to the validation results? (y/n)"
 - If yes: Update content, then return to A/P/C menu

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-01-validate-prerequisites.md

@@ -14,7 +14,7 @@ epicsTemplate: '{workflow_path}/templates/epics-template.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
@@ -154,20 +154,31 @@ Review the Architecture document for technical requirements that impact epic and
 ...
 ```
 
-### 6. Extract Additional Requirements from UX (if exists)
+### 6. Extract UX Design Requirements (if UX document exists)
 
-Review the UX document for requirements that affect epic and story creation:
+**IMPORTANT**: The UX Design Specification is a first-class input document, not supplementary material. Requirements from the UX spec must be extracted with the same rigor as PRD functional requirements.
+
+Read the FULL UX Design document and extract ALL actionable work items:
 
 **Look for:**
 
-- Responsive design requirements
-- Accessibility requirements
-- Browser/device compatibility
-- User interaction patterns that need implementation
-- Animation or transition requirements
-- Error handling UX requirements
+- **Design token work**: Color systems, spacing scales, typography tokens that need implementation or consolidation
+- **Component proposals**: Reusable UI components identified in the UX spec (e.g., ConfirmActions, StatusMessage, EmptyState, FocusIndicator)
+- **Visual standardization**: Semantic CSS classes, consistent color palette usage, design pattern consolidation
+- **Accessibility requirements**: Contrast audit fixes, ARIA patterns, keyboard navigation, screen reader support
+- **Responsive design requirements**: Breakpoints, layout adaptations, mobile-specific interactions
+- **Interaction patterns**: Animations, transitions, loading states, error handling UX
+- **Browser/device compatibility**: Target platforms, progressive enhancement requirements
 
-**Add these to Additional Requirements list.**
+**Format UX Design Requirements as a SEPARATE section (not merged into Additional Requirements):**
+
+```
+UX-DR1: [Actionable UX design requirement with clear implementation scope]
+UX-DR2: [Actionable UX design requirement with clear implementation scope]
+...
+```
+
+**🚨 CRITICAL**: Do NOT reduce UX requirements to vague summaries. Each UX-DR must be specific enough to generate a story with testable acceptance criteria. If the UX spec identifies 6 reusable components, list all 6 — not "create reusable components."
 
 ### 7. Load and Initialize Template
 
@@ -178,7 +189,8 @@ Load {epicsTemplate} and initialize {outputFile}:
 3. Replace placeholder sections with extracted requirements:
    - {{fr_list}} → extracted FRs
    - {{nfr_list}} → extracted NFRs
-   - {{additional_requirements}} → extracted additional requirements
+   - {{additional_requirements}} → extracted additional requirements (from Architecture)
+   - {{ux_design_requirements}} → extracted UX Design Requirements (if UX document exists)
 4. Leave {{requirements_coverage_map}} and {{epics_list}} as placeholders for now
 
 ### 8. Present Extracted Requirements
@@ -197,12 +209,17 @@ Display to user:
 - Display key NFRs
 - Ask if any constraints were missed
 
-**Additional Requirements:**
+**Additional Requirements (Architecture):**
 
 - Summarize technical requirements from Architecture
-- Summarize UX requirements (if applicable)
 - Verify completeness
 
+**UX Design Requirements (if applicable):**
+
+- Show count of UX-DRs found
+- Display key UX Design requirements (design tokens, components, accessibility)
+- Verify each UX-DR is specific enough for story creation
+
 ### 9. Get User Confirmation
 
 Ask: "Do these extracted requirements accurately represent what needs to be built? Any additions or corrections?"
@@ -216,6 +233,7 @@ After extraction and confirmation, update {outputFile} with:
 - Complete FR list in {{fr_list}} section
 - Complete NFR list in {{nfr_list}} section
 - All additional requirements in {{additional_requirements}} section
+- UX Design requirements in {{ux_design_requirements}} section (if UX document exists)
 
 ### 10. Present MENU OPTIONS
 

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-02-design-epics.md

@@ -13,7 +13,7 @@ outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-03-create-stories.md

@@ -13,7 +13,7 @@ outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
@@ -66,9 +66,11 @@ Load {outputFile} and review:
 
 - Approved epics_list from Step 2
 - FR coverage map
-- All requirements (FRs, NFRs, additional)
+- 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:**
@@ -146,6 +148,7 @@ Display:
 - 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
 
@@ -207,6 +210,7 @@ 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:

src/bmm/workflows/3-solutioning/create-epics-and-stories/steps/step-04-final-validation.md

@@ -12,7 +12,7 @@ outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
 advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'

src/bmm/workflows/3-solutioning/create-epics-and-stories/templates/epics-template.md

@@ -23,6 +23,10 @@ This document provides the complete epic and story breakdown for {{project_name}
 
 {{additional_requirements}}
 
+### UX Design Requirements
+
+{{ux_design_requirements}}
+
 ### FR Coverage Map
 
 {{requirements_coverage_map}}

src/bmm/workflows/4-implementation/code-review/workflow.md

@@ -13,7 +13,7 @@ description: 'Perform adversarial code review finding specific issues. Use when
 - Generate all documents in {document_output_language}
 - Your purpose: Validate story file claims against actual implementation
 - Challenge everything: Are tasks marked [x] actually done? Are ACs really implemented?
-- Find 3-10 specific issues in every review minimum - no lazy "looks good" reviews - YOU are so much better than the dev agent that wrote this slop
+- Be thorough and specific — find real issues, not manufactured ones. If the code is genuinely good after fixes, say so
 - Read EVERY file in the File List - verify implementation against story requirements
 - Tasks marked complete but not done = CRITICAL finding
 - Acceptance Criteria not implemented = HIGH severity finding
@@ -136,17 +136,14 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
     5. **Test Quality**: Are tests real assertions or placeholders?
   </action>
 
-  <check if="total_issues_found lt 3">
-    <critical>NOT LOOKING HARD ENOUGH - Find more problems!</critical>
-    <action>Re-examine code for:
+  <check if="total_issues_found == 0">
+    <action>Double-check by re-examining code for:
       - Edge cases and null handling
       - Architecture violations
-      - Documentation gaps
       - Integration issues
       - Dependency problems
-      - Git commit message quality (if applicable)
     </action>
-    <action>Find at least 3 more specific, actionable issues</action>
+    <action>If still no issues found after thorough re-examination, that is a valid outcome — report a clean review</action>
   </check>
 </step>
 

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bmad-quick-dev-new-preview
-description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the projects existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
+description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
 ---
 
 Follow the instructions in [workflow.md](workflow.md).

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-04-review.md

@@ -43,13 +43,11 @@ Do NOT `git add` anything — this is read-only inspection.
    - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
    - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
 3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review.
-   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve, then re-run steps 2–4.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./steps/step-02-plan.md` to re-run steps 2–4.
    - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./steps/step-03-implement.md` to re-derive the code, then this step will run again.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks.
    - **defer** — Append to `{deferred_work_file}`.
    - **reject** — Drop silently.
-4. Commit.
-
 ## NEXT
 
 Read fully and follow `./steps/step-05-present.md`

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/steps/step-05-present.md

@@ -12,8 +12,8 @@ description: 'Present findings, get approval, create PR'
 
 ## INSTRUCTIONS
 
-1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
-2. Change `{spec_file}` status to `done` in the frontmatter.
+1. Change `{spec_file}` status to `done` in the frontmatter.
+2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
 3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
 
 Workflow complete.

src/bmm/workflows/bmad-quick-flow/bmad-quick-dev-new-preview/workflow.md

@@ -1,9 +1,5 @@
 ---
 main_config: '{project-root}/_bmad/bmm/config.yaml'
-
-# Related workflows
-advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
 ---
 
 # Quick Dev New Preview Workflow

src/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md

@@ -40,7 +40,7 @@ Load config from `{project-root}/_bmad/bmm/config.yaml` and resolve:
 ### Related Workflows
 
 - `quick_spec_workflow` = `{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md`
-- `party_mode_exec` = `{project-root}/_bmad/core/workflows/party-mode/workflow.md`
+- `party_mode_exec` = `{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md`
 - `advanced_elicitation` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md`
 
 ---

src/bmm/workflows/bmad-quick-flow/quick-spec/workflow.md

@@ -5,7 +5,7 @@ main_config: '{project-root}/_bmad/bmm/config.yaml'
 
 # Checkpoint handler paths
 advanced_elicitation: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-party_mode_exec: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+party_mode_exec: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
 quick_dev_workflow: '{project-root}/_bmad/bmm/workflows/bmad-quick-flow/quick-dev/workflow.md'
 ---
 

src/bmm/workflows/generate-project-context/steps/step-02-generate.md

@@ -30,7 +30,7 @@ This step will generate content and present choices for each rule category:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md
-- When 'P' selected: Execute {project-root}/_bmad/core/workflows/party-mode
+- When 'P' selected: Execute {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 

src/core/module-help.csv

@@ -1,10 +1,10 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
 core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,,"Generate diverse ideas through interactive techniques. Use early in ideation phase or when stuck generating ideas.",{output_folder}/brainstorming/brainstorming-session-{{date}}.md,,
-core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
+core,anytime,Party Mode,PM,,skill:bmad-party-mode,bmad-party-mode,false,party-mode facilitator,,"Orchestrate multi-agent discussions. Use when you need multiple agent perspectives or want agents to collaborate.",,
 core,anytime,bmad-help,BH,,skill:bmad-help,bmad-help,false,,,"Get unstuck by showing what workflow steps come next or answering BMad Method questions.",,
-core,anytime,Index Docs,ID,,_bmad/core/tasks/index-docs.xml,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
-core,anytime,Shard Document,SD,,_bmad/core/tasks/shard-doc.xml,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
-core,anytime,Editorial Review - Prose,EP,,_bmad/core/tasks/editorial-review-prose.xml,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
-core,anytime,Editorial Review - Structure,ES,,_bmad/core/tasks/editorial-review-structure.xml,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
+core,anytime,Index Docs,ID,,skill:bmad-index-docs,bmad-index-docs,false,,,"Create lightweight index for quick LLM scanning. Use when LLM needs to understand available docs without loading everything.",,
+core,anytime,Shard Document,SD,,skill:bmad-shard-doc,bmad-shard-doc,false,,,"Split large documents into smaller files by sections. Use when doc becomes too large (>500 lines) to manage effectively.",,
+core,anytime,Editorial Review - Prose,EP,,skill:bmad-editorial-review-prose,bmad-editorial-review-prose,false,,,"Review prose for clarity, tone, and communication issues. Use after drafting to polish written content.",report located with target document,"three-column markdown table with suggested fixes",
+core,anytime,Editorial Review - Structure,ES,,skill:bmad-editorial-review-structure,bmad-editorial-review-structure,false,,,"Propose cuts, reorganization, and simplification while preserving comprehension. Use when doc produced from multiple subprocesses or needs structural improvement.",report located with target document,
 core,anytime,Adversarial Review (General),AR,,skill:bmad-review-adversarial-general,bmad-review-adversarial-general,false,,,"Review content critically to find issues and weaknesses. Use for quality assurance or before finalizing deliverables. Code Review in other modules run this automatically, but its useful also for document reviews",,
 core,anytime,Edge Case Hunter Review,ECH,,skill:bmad-review-edge-case-hunter,bmad-review-edge-case-hunter,false,,,"Walk every branching path and boundary condition in code, report only unhandled edge cases. Use alongside adversarial review for orthogonal coverage - method-driven not attitude-driven.",,

src/core/tasks/bmad-editorial-review-prose/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-editorial-review-prose
+description: 'Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/core/tasks/bmad-editorial-review-prose/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/core/tasks/bmad-editorial-review-prose/workflow.md

@@ -0,0 +1,81 @@
+# Editorial Review - Prose
+
+**Goal:** Review text for communication issues that impede comprehension and output suggested fixes in a three-column table.
+
+**Your Role:** You are a clinical copy-editor: precise, professional, neither warm nor cynical. Apply Microsoft Writing Style Guide principles as your baseline. Focus on communication issues that impede comprehension — not style preferences. NEVER rewrite for preference — only fix genuine issues. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
+
+**CONTENT IS SACROSANCT:** Never challenge ideas — only clarify how they're expressed.
+
+**Inputs:**
+- **content** (required) — Cohesive unit of text to review (markdown, plain text, or text-heavy XML)
+- **style_guide** (optional) — Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
+- **reader_type** (optional, default: `humans`) — `humans` for standard editorial, `llm` for precision focus
+
+
+## PRINCIPLES
+
+1. **Minimal intervention:** Apply the smallest fix that achieves clarity
+2. **Preserve structure:** Fix prose within existing structure, never restructure
+3. **Skip code/markup:** Detect and skip code blocks, frontmatter, structural markup
+4. **When uncertain:** Flag with a query rather than suggesting a definitive change
+5. **Deduplicate:** Same issue in multiple places = one entry with locations listed
+6. **No conflicts:** Merge overlapping fixes into single entries
+7. **Respect author voice:** Preserve intentional stylistic choices
+
+> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including the Microsoft Writing Style Guide baseline and reader_type-specific priorities). The ONLY exception is CONTENT IS SACROSANCT — never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
+
+
+## STEPS
+
+### Step 1: Validate Input
+
+- Check if content is empty or contains fewer than 3 words
+  - If empty or fewer than 3 words: **HALT** with error: "Content too short for editorial review (minimum 3 words required)"
+- Validate reader_type is `humans` or `llm` (or not provided, defaulting to `humans`)
+  - If reader_type is invalid: **HALT** with error: "Invalid reader_type. Must be 'humans' or 'llm'"
+- Identify content type (markdown, plain text, XML with text)
+- Note any code blocks, frontmatter, or structural markup to skip
+
+### Step 2: Analyze Style
+
+- Analyze the style, tone, and voice of the input text
+- Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)
+- Calibrate review approach based on reader_type:
+  - If `llm`: Prioritize unambiguous references, consistent terminology, explicit structure, no hedging
+  - If `humans`: Prioritize clarity, flow, readability, natural progression
+
+### Step 3: Editorial Review (CRITICAL)
+
+- If style_guide provided: Consult style_guide now and note its key requirements — these override default principles for this review
+- Review all prose sections (skip code blocks, frontmatter, structural markup)
+- Identify communication issues that impede comprehension
+- For each issue, determine the minimal fix that achieves clarity
+- Deduplicate: If same issue appears multiple times, create one entry listing all locations
+- Merge overlapping issues into single entries (no conflicting suggestions)
+- For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change
+- Preserve author voice — do not "improve" intentional stylistic choices
+
+### Step 4: Output Results
+
+- If issues found: Output a three-column markdown table with all suggested fixes
+- If no issues found: Output "No editorial issues identified"
+
+**Output format:**
+
+| Original Text | Revised Text | Changes |
+|---------------|--------------|---------|
+| The exact original passage | The suggested revision | Brief explanation of what changed and why |
+
+**Example:**
+
+| Original Text | Revised Text | Changes |
+|---------------|--------------|---------|
+| The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb agreement ("will processes" to "processes"); removed redundant "it" |
+| Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in 3 locations) |
+
+
+## HALT CONDITIONS
+
+- HALT with error if content is empty or fewer than 3 words
+- HALT with error if reader_type is not `humans` or `llm`
+- If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)

src/core/tasks/bmad-editorial-review-structure/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-editorial-review-structure
+description: 'Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/core/tasks/bmad-editorial-review-structure/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/core/tasks/bmad-editorial-review-structure/workflow.md

@@ -0,0 +1,174 @@
+# Editorial Review - Structure
+
+**Goal:** Review document structure and propose substantive changes to improve clarity and flow -- run this BEFORE copy editing.
+
+**Your Role:** You are a structural editor focused on HIGH-VALUE DENSITY. Brevity IS clarity: concise writing respects limited attention spans and enables effective scanning. Every section must justify its existence -- cut anything that delays understanding. True redundancy is failure. Follow ALL steps in the STEPS section IN EXACT ORDER. DO NOT skip steps or change the sequence. HALT immediately when halt-conditions are met. Each action within a step is a REQUIRED action to complete that step.
+
+> **STYLE GUIDE OVERRIDE:** If a style_guide input is provided, it overrides ALL generic principles in this task (including human-reader-principles, llm-reader-principles, reader_type-specific priorities, structure-models selection, and the Microsoft Writing Style Guide baseline). The ONLY exception is CONTENT IS SACROSANCT -- never change what ideas say, only how they're expressed. When style guide conflicts with this task, style guide wins.
+
+**Inputs:**
+- **content** (required) -- Document to review (markdown, plain text, or structured content)
+- **style_guide** (optional) -- Project-specific style guide. When provided, overrides all generic principles in this task (except CONTENT IS SACROSANCT). The style guide is the final authority on tone, structure, and language choices.
+- **purpose** (optional) -- Document's intended purpose (e.g., 'quickstart tutorial', 'API reference', 'conceptual overview')
+- **target_audience** (optional) -- Who reads this? (e.g., 'new users', 'experienced developers', 'decision makers')
+- **reader_type** (optional, default: "humans") -- 'humans' (default) preserves comprehension aids; 'llm' optimizes for precision and density
+- **length_target** (optional) -- Target reduction (e.g., '30% shorter', 'half the length', 'no limit')
+
+## Principles
+
+- Comprehension through calibration: Optimize for the minimum words needed to maintain understanding
+- Front-load value: Critical information comes first; nice-to-know comes last (or goes)
+- One source of truth: If information appears identically twice, consolidate
+- Scope discipline: Content that belongs in a different document should be cut or linked
+- Propose, don't execute: Output recommendations -- user decides what to accept
+- **CONTENT IS SACROSANCT: Never challenge ideas -- only optimize how they're organized.**
+
+## Human-Reader Principles
+
+These elements serve human comprehension and engagement -- preserve unless clearly wasteful:
+
+- Visual aids: Diagrams, images, and flowcharts anchor understanding
+- Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place
+- Reader's Journey: Organize content biologically (linear progression), not logically (database)
+- Mental models: Overview before details prevents cognitive overload
+- Warmth: Encouraging tone reduces anxiety for new users
+- Whitespace: Admonitions and callouts provide visual breathing room
+- Summaries: Recaps help retention; they're reinforcement, not redundancy
+- Examples: Concrete illustrations make abstract concepts accessible
+- Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff" -- they maintain attention
+
+## LLM-Reader Principles
+
+When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:
+
+- Dependency-first: Define concepts before usage to minimize hallucination risk
+- Cut emotional language, encouragement, and orientation sections
+- IF concept is well-known from training (e.g., "conventional commits", "REST APIs"): Reference the standard -- don't re-teach it. ELSE: Be explicit -- don't assume the LLM will infer correctly.
+- Use consistent terminology -- same word for same concept throughout
+- Eliminate hedging ("might", "could", "generally") -- use direct statements
+- Prefer structured formats (tables, lists, YAML) over prose
+- Reference known standards ("conventional commits", "Google style guide") to leverage training
+- STILL PROVIDE EXAMPLES even for known standards -- grounds the LLM in your specific expectation
+- Unambiguous references -- no unclear antecedents ("it", "this", "the above")
+- Note: LLM documents may be LONGER than human docs in some areas (more explicit) while shorter in others (no warmth)
+
+## Structure Models
+
+### Tutorial/Guide (Linear)
+**Applicability:** Tutorials, detailed guides, how-to articles, walkthroughs
+- Prerequisites: Setup/Context MUST precede action
+- Sequence: Steps must follow strict chronological or logical dependency order
+- Goal-oriented: clear 'Definition of Done' at the end
+
+### Reference/Database
+**Applicability:** API docs, glossaries, configuration references, cheat sheets
+- Random Access: No narrative flow required; user jumps to specific item
+- MECE: Topics are Mutually Exclusive and Collectively Exhaustive
+- Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)
+
+### Explanation (Conceptual)
+**Applicability:** Deep dives, architecture overviews, conceptual guides, whitepapers, project context
+- Abstract to Concrete: Definition to Context to Implementation/Example
+- Scaffolding: Complex ideas built on established foundations
+
+### Prompt/Task Definition (Functional)
+**Applicability:** BMAD tasks, prompts, system instructions, XML definitions
+- Meta-first: Inputs, usage constraints, and context defined before instructions
+- Separation of Concerns: Instructions (logic) separate from Data (content)
+- Step-by-step: Execution flow must be explicit and ordered
+
+### Strategic/Context (Pyramid)
+**Applicability:** PRDs, research reports, proposals, decision records
+- Top-down: Conclusion/Status/Recommendation starts the document
+- Grouping: Supporting context grouped logically below the headline
+- Ordering: Most critical information first
+- MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive
+- Evidence: Data supports arguments, never leads
+
+## STEPS
+
+### Step 1: Validate Input
+
+- Check if content is empty or contains fewer than 3 words
+- If empty or fewer than 3 words, HALT with error: "Content too short for substantive review (minimum 3 words required)"
+- Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")
+- If reader_type is invalid, HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"
+- Identify document type and structure (headings, sections, lists, etc.)
+- Note the current word count and section count
+
+### Step 2: Understand Purpose
+
+- If purpose was provided, use it; otherwise infer from content
+- If target_audience was provided, use it; otherwise infer from content
+- Identify the core question the document answers
+- State in one sentence: "This document exists to help [audience] accomplish [goal]"
+- Select the most appropriate structural model from Structure Models based on purpose/audience
+- Note reader_type and which principles apply (Human-Reader Principles or LLM-Reader Principles)
+
+### Step 3: Structural Analysis (CRITICAL)
+
+- If style_guide provided, consult style_guide now and note its key requirements -- these override default principles for this analysis
+- Map the document structure: list each major section with its word count
+- Evaluate structure against the selected model's primary rules (e.g., 'Does recommendation come first?' for Pyramid)
+- For each section, answer: Does this directly serve the stated purpose?
+- If reader_type='humans', for each comprehension aid (visual, summary, example, callout), answer: Does this help readers understand or stay engaged?
+- Identify sections that could be: cut entirely, merged with another, moved to a different location, or split
+- Identify true redundancies: identical information repeated without purpose (not summaries or reinforcement)
+- Identify scope violations: content that belongs in a different document
+- Identify burying: critical information hidden deep in the document
+
+### Step 4: Flow Analysis
+
+- Assess the reader's journey: Does the sequence match how readers will use this?
+- Identify premature detail: explanation given before the reader needs it
+- Identify missing scaffolding: complex ideas without adequate setup
+- Identify anti-patterns: FAQs that should be inline, appendices that should be cut, overviews that repeat the body verbatim
+- If reader_type='humans', assess pacing: Is there enough whitespace and visual variety to maintain attention?
+
+### Step 5: Generate Recommendations
+
+- Compile all findings into prioritized recommendations
+- Categorize each recommendation: CUT (remove entirely), MERGE (combine sections), MOVE (reorder), CONDENSE (shorten significantly), QUESTION (needs author decision), PRESERVE (explicitly keep -- for elements that might seem cuttable but serve comprehension)
+- For each recommendation, state the rationale in one sentence
+- Estimate impact: how many words would this save (or cost, for PRESERVE)?
+- If length_target was provided, assess whether recommendations meet it
+- If reader_type='humans' and recommendations would cut comprehension aids, flag with warning: "This cut may impact reader comprehension/engagement"
+
+### Step 6: Output Results
+
+- Output document summary (purpose, audience, reader_type, current length)
+- Output the recommendation list in priority order
+- Output estimated total reduction if all recommendations accepted
+- If no recommendations, output: "No substantive changes recommended -- document structure is sound"
+
+Use the following output format:
+
+```markdown
+## Document Summary
+- **Purpose:** [inferred or provided purpose]
+- **Audience:** [inferred or provided audience]
+- **Reader type:** [selected reader type]
+- **Structure model:** [selected structure model]
+- **Current length:** [X] words across [Y] sections
+
+## Recommendations
+
+### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
+**Rationale:** [One sentence explanation]
+**Impact:** ~[X] words
+**Comprehension note:** [If applicable, note impact on reader understanding]
+
+### 2. ...
+
+## Summary
+- **Total recommendations:** [N]
+- **Estimated reduction:** [X] words ([Y]% of original)
+- **Meets length target:** [Yes/No/No target specified]
+- **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
+```
+
+## HALT CONDITIONS
+
+- HALT with error if content is empty or fewer than 3 words
+- HALT with error if reader_type is not "humans" or "llm"
+- If no structural issues found, output "No substantive changes recommended" (this is valid completion, not an error)

src/core/tasks/bmad-index-docs/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-index-docs
+description: 'Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/core/tasks/bmad-index-docs/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/core/tasks/bmad-index-docs/workflow.md

@@ -0,0 +1,61 @@
+# Index Docs
+
+**Goal:** Generate or update an index.md to reference all docs in a target folder.
+
+
+## EXECUTION
+
+### Step 1: Scan Directory
+
+- List all files and subdirectories in the target location
+
+### Step 2: Group Content
+
+- Organize files by type, purpose, or subdirectory
+
+### Step 3: Generate Descriptions
+
+- Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the filename
+
+### Step 4: Create/Update Index
+
+- Write or update index.md with organized file listings
+
+
+## OUTPUT FORMAT
+
+```markdown
+# Directory Index
+
+## Files
+
+- **[filename.ext](./filename.ext)** - Brief description
+- **[another-file.ext](./another-file.ext)** - Brief description
+
+## Subdirectories
+
+### subfolder/
+
+- **[file1.ext](./subfolder/file1.ext)** - Brief description
+- **[file2.ext](./subfolder/file2.ext)** - Brief description
+
+### another-folder/
+
+- **[file3.ext](./another-folder/file3.ext)** - Brief description
+```
+
+
+## HALT CONDITIONS
+
+- HALT if target directory does not exist or is inaccessible
+- HALT if user does not have write permissions to create index.md
+
+
+## VALIDATION
+
+- Use relative paths starting with ./
+- Group similar files together
+- Read file contents to generate accurate descriptions - don't guess from filenames
+- Keep descriptions concise but informative (3-10 words)
+- Sort alphabetically within groups
+- Skip hidden files (starting with .) unless specified

src/core/tasks/bmad-shard-doc/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-shard-doc
+description: 'Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/core/tasks/bmad-shard-doc/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/core/tasks/bmad-shard-doc/workflow.md

@@ -0,0 +1,100 @@
+# Shard Document
+
+**Goal:** Split large markdown documents into smaller, organized files based on level 2 sections using `npx @kayvan/markdown-tree-parser`.
+
+## CRITICAL RULES
+
+- MANDATORY: Execute ALL steps in the EXECUTION section IN EXACT ORDER
+- DO NOT skip steps or change the sequence
+- HALT immediately when halt-conditions are met
+- Each action within a step is a REQUIRED action to complete that step
+
+## EXECUTION
+
+### Step 1: Get Source Document
+
+- Ask user for the source document path if not provided already
+- Verify file exists and is accessible
+- Verify file is markdown format (.md extension)
+- If file not found or not markdown: HALT with error message
+
+### Step 2: Get Destination Folder
+
+- Determine default destination: same location as source file, folder named after source file without .md extension
+  - Example: `/path/to/architecture.md` --> `/path/to/architecture/`
+- Ask user for the destination folder path (`[y]` to confirm use of default: `[suggested-path]`, else enter a new path)
+- If user accepts default: use the suggested destination path
+- If user provides custom path: use the custom destination path
+- Verify destination folder exists or can be created
+- Check write permissions for destination
+- If permission denied: HALT with error message
+
+### Step 3: Execute Sharding
+
+- Inform user that sharding is beginning
+- Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`
+- Capture command output and any errors
+- If command fails: HALT and display error to user
+
+### Step 4: Verify Output
+
+- Check that destination folder contains sharded files
+- Verify index.md was created in destination folder
+- Count the number of files created
+- If no files created: HALT with error message
+
+### Step 5: Report Completion
+
+- Display completion report to user including:
+  - Source document path and name
+  - Destination folder path
+  - Number of section files created
+  - Confirmation that index.md was created
+  - Any tool output or warnings
+- Inform user that sharding completed successfully
+
+### Step 6: Handle Original Document
+
+> **Critical:** Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion.
+
+Present user with options for the original document:
+
+> What would you like to do with the original document `[source-document-name]`?
+>
+> Options:
+> - `[d]` Delete - Remove the original (recommended - shards can always be recombined)
+> - `[m]` Move to archive - Move original to a backup/archive location
+> - `[k]` Keep - Leave original in place (NOT recommended - defeats sharding purpose)
+>
+> Your choice (d/m/k):
+
+#### If user selects `d` (delete)
+
+- Delete the original source document file
+- Confirm deletion to user: "Original document deleted: [source-document-path]"
+- Note: The document can be reconstructed from shards by concatenating all section files in order
+
+#### If user selects `m` (move)
+
+- Determine default archive location: same directory as source, in an `archive` subfolder
+  - Example: `/path/to/architecture.md` --> `/path/to/archive/architecture.md`
+- Ask: Archive location (`[y]` to use default: `[default-archive-path]`, or provide custom path)
+- If user accepts default: use default archive path
+- If user provides custom path: use custom archive path
+- Create archive directory if it does not exist
+- Move original document to archive location
+- Confirm move to user: "Original document moved to: [archive-path]"
+
+#### If user selects `k` (keep)
+
+- Display warning to user:
+  - Keeping both original and sharded versions is NOT recommended
+  - The discover_inputs protocol may load the wrong version
+  - Updates to one will not reflect in the other
+  - Duplicate content taking up space
+  - Consider deleting or archiving the original document
+- Confirm user choice: "Original document kept at: [source-document-path]"
+
+## HALT CONDITIONS
+
+- HALT if npx command fails or produces no output files

src/core/tasks/bmad-skill-manifest.yaml

@@ -1,19 +0,0 @@
-editorial-review-prose.xml:
-  canonicalId: bmad-editorial-review-prose
-  type: task
-  description: "Clinical copy-editor that reviews text for communication issues"
-
-editorial-review-structure.xml:
-  canonicalId: bmad-editorial-review-structure
-  type: task
-  description: "Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension"
-
-index-docs.xml:
-  canonicalId: bmad-index-docs
-  type: task
-  description: "Generates or updates an index.md to reference all docs in the folder"
-
-shard-doc.xml:
-  canonicalId: bmad-shard-doc
-  type: task
-  description: "Splits large markdown documents into smaller, organized files based on sections"

src/core/tasks/editorial-review-prose.xml

@@ -1,102 +0,0 @@
-<task id="_bmad/core/tasks/editorial-review-prose.xml"
-  name="Editorial Review - Prose"
-  description="Clinical copy-editor that reviews text for communication issues. Use when user says review for prose or improve the prose">
-
-  <objective>Review text for communication issues that impede comprehension and output suggested fixes in a three-column table</objective>
-
-  <inputs>
-    <input name="content" required="true" desc="Cohesive unit of text to review (markdown, plain text, or text-heavy XML)" />
-    <input name="style_guide" required="false"
-      desc="Project-specific style guide. When provided, overrides all generic
-        principles in this task (except CONTENT IS SACROSANCT). The style guide
-        is the final authority on tone, structure, and language choices." />
-    <input name="reader_type" required="false" default="humans" desc="'humans' (default) for standard editorial, 'llm' for precision focus" />
-  </inputs>
-
-  <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
-    <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
-
-    <i>You are a clinical copy-editor: precise, professional, neither warm nor cynical</i>
-    <i>Apply Microsoft Writing Style Guide principles as your baseline</i>
-    <i>Focus on communication issues that impede comprehension - not style preferences</i>
-    <i>NEVER rewrite for preference - only fix genuine issues</i>
-
-    <i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only clarify how they're expressed.</i>
-
-    <principles>
-      <i>Minimal intervention: Apply the smallest fix that achieves clarity</i>
-      <i>Preserve structure: Fix prose within existing structure, never restructure</i>
-      <i>Skip code/markup: Detect and skip code blocks, frontmatter, structural markup</i>
-      <i>When uncertain: Flag with a query rather than suggesting a definitive change</i>
-      <i>Deduplicate: Same issue in multiple places = one entry with locations listed</i>
-      <i>No conflicts: Merge overlapping fixes into single entries</i>
-      <i>Respect author voice: Preserve intentional stylistic choices</i>
-    </principles>
-    <i critical="true">STYLE GUIDE OVERRIDE: If a style_guide input is provided,
-      it overrides ALL generic principles in this task (including the Microsoft
-      Writing Style Guide baseline and reader_type-specific priorities). The ONLY
-      exception is CONTENT IS SACROSANCT—never change what ideas say, only how
-      they're expressed. When style guide conflicts with this task, style guide wins.</i>
-  </llm>
-
-  <flow>
-    <step n="1" title="Validate Input">
-      <action>Check if content is empty or contains fewer than 3 words</action>
-      <action if="empty or fewer than 3 words">HALT with error: "Content too short for editorial review (minimum 3 words required)"</action>
-      <action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
-      <action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
-      <action>Identify content type (markdown, plain text, XML with text)</action>
-      <action>Note any code blocks, frontmatter, or structural markup to skip</action>
-    </step>
-
-    <step n="2" title="Analyze Style">
-      <action>Analyze the style, tone, and voice of the input text</action>
-      <action>Note any intentional stylistic choices to preserve (informal tone, technical jargon, rhetorical patterns)</action>
-      <action>Calibrate review approach based on reader_type parameter</action>
-      <action if="reader_type='llm'">Prioritize: unambiguous references, consistent terminology, explicit structure, no hedging</action>
-      <action if="reader_type='humans'">Prioritize: clarity, flow, readability, natural progression</action>
-    </step>
-
-    <step n="3" title="Editorial Review" critical="true">
-      <action if="style_guide provided">Consult style_guide now and note its key requirements—these override default principles for this
-        review</action>
-      <action>Review all prose sections (skip code blocks, frontmatter, structural markup)</action>
-      <action>Identify communication issues that impede comprehension</action>
-      <action>For each issue, determine the minimal fix that achieves clarity</action>
-      <action>Deduplicate: If same issue appears multiple times, create one entry listing all locations</action>
-      <action>Merge overlapping issues into single entries (no conflicting suggestions)</action>
-      <action>For uncertain fixes, phrase as query: "Consider: [suggestion]?" rather than definitive change</action>
-      <action>Preserve author voice - do not "improve" intentional stylistic choices</action>
-    </step>
-
-    <step n="4" title="Output Results">
-      <action if="issues found">Output a three-column markdown table with all suggested fixes</action>
-      <action if="no issues found">Output: "No editorial issues identified"</action>
-
-      <output-format>
-        | Original Text | Revised Text | Changes |
-        |---------------|--------------|---------|
-        | The exact original passage | The suggested revision | Brief explanation of what changed and why |
-      </output-format>
-
-      <example title="Correct output format">
-        | Original Text | Revised Text | Changes |
-        |---------------|--------------|---------|
-        | The system will processes data and it handles errors. | The system processes data and handles errors. | Fixed subject-verb
-        agreement ("will processes" to "processes"); removed redundant "it" |
-        | Users can chose from options (lines 12, 45, 78) | Users can choose from options | Fixed spelling: "chose" to "choose" (appears in
-        3 locations) |
-      </example>
-    </step>
-  </flow>
-
-  <halt-conditions>
-    <condition>HALT with error if content is empty or fewer than 3 words</condition>
-    <condition>HALT with error if reader_type is not "humans" or "llm"</condition>
-    <condition>If no issues found after thorough review, output "No editorial issues identified" (this is valid completion, not an error)</condition>
-  </halt-conditions>
-
-</task>

src/core/tasks/editorial-review-structure.xml

@@ -1,208 +0,0 @@
-<?xml version="1.0"?>
-<!-- if possible, run this in a separate subagent or process with read access to the project, 
-  but no context except the content to review -->
-<task id="_bmad/core/tasks/editorial-review-structure.xml"
-  name="Editorial Review - Structure"
-  description="Structural editor that proposes cuts, reorganization, and simplification while preserving comprehension. Use when user requests structural review or editorial review of structure">
-  <objective>Review document structure and propose substantive changes
-    to improve clarity and flow-run this BEFORE copy editing</objective>
-  <inputs>
-    <input name="content" required="true"
-      desc="Document to review (markdown, plain text, or structured content)" />
-    <input name="style_guide" required="false"
-      desc="Project-specific style guide. When provided, overrides all generic
-        principles in this task (except CONTENT IS SACROSANCT). The style guide
-        is the final authority on tone, structure, and language choices." />
-    <input name="purpose" required="false"
-      desc="Document's intended purpose (e.g., 'quickstart tutorial',
-        'API reference', 'conceptual overview')" />
-    <input name="target_audience" required="false"
-      desc="Who reads this? (e.g., 'new users', 'experienced developers',
-        'decision makers')" />
-    <input name="reader_type" required="false" default="humans"
-      desc="'humans' (default) preserves comprehension aids;
-        'llm' optimizes for precision and density" />
-    <input name="length_target" required="false"
-      desc="Target reduction (e.g., '30% shorter', 'half the length',
-        'no limit')" />
-  </inputs>
-  <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
-    <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
-    <i>You are a structural editor focused on HIGH-VALUE DENSITY</i>
-    <i>Brevity IS clarity: Concise writing respects limited attention spans and enables effective scanning</i>
-    <i>Every section must justify its existence-cut anything that delays understanding</i>
-    <i>True redundancy is failure</i>
-    <principles>
-      <i>Comprehension through calibration: Optimize for the minimum words needed to maintain understanding</i>
-      <i>Front-load value: Critical information comes first; nice-to-know comes last (or goes)</i>
-      <i>One source of truth: If information appears identically twice, consolidate</i>
-      <i>Scope discipline: Content that belongs in a different document should be cut or linked</i>
-      <i>Propose, don't execute: Output recommendations-user decides what to accept</i>
-      <i critical="true">CONTENT IS SACROSANCT: Never challenge ideas—only optimize how they're organized.</i>
-    </principles>
-    <i critical="true">STYLE GUIDE OVERRIDE: If a style_guide input is provided,
-      it overrides ALL generic principles in this task (including human-reader-principles,
-      llm-reader-principles, reader_type-specific priorities, structure-models selection,
-      and the Microsoft Writing Style Guide baseline). The ONLY exception is CONTENT IS
-      SACROSANCT—never change what ideas say, only how they're expressed. When style
-      guide conflicts with this task, style guide wins.</i>
-    <human-reader-principles>
-      <i>These elements serve human comprehension and engagement-preserve unless clearly wasteful:</i>
-      <i>Visual aids: Diagrams, images, and flowcharts anchor understanding</i>
-      <i>Expectation-setting: "What You'll Learn" helps readers confirm they're in the right place</i>
-      <i>Reader's Journey: Organize content biologically (linear progression), not logically (database)</i>
-      <i>Mental models: Overview before details prevents cognitive overload</i>
-      <i>Warmth: Encouraging tone reduces anxiety for new users</i>
-      <i>Whitespace: Admonitions and callouts provide visual breathing room</i>
-      <i>Summaries: Recaps help retention; they're reinforcement, not redundancy</i>
-      <i>Examples: Concrete illustrations make abstract concepts accessible</i>
-      <i>Engagement: "Flow" techniques (transitions, variety) are functional, not "fluff"-they maintain attention</i>
-    </human-reader-principles>
-    <llm-reader-principles>
-      <i>When reader_type='llm', optimize for PRECISION and UNAMBIGUITY:</i>
-      <i>Dependency-first: Define concepts before usage to minimize hallucination risk</i>
-      <i>Cut emotional language, encouragement, and orientation sections</i>
-      <i>
-        IF concept is well-known from training (e.g., "conventional
-        commits", "REST APIs"): Reference the standard-don't re-teach it
-        ELSE: Be explicit-don't assume the LLM will infer correctly
-      </i>
-      <i>Use consistent terminology-same word for same concept throughout</i>
-      <i>Eliminate hedging ("might", "could", "generally")-use direct statements</i>
-      <i>Prefer structured formats (tables, lists, YAML) over prose</i>
-      <i>Reference known standards ("conventional commits", "Google style guide") to leverage training</i>
-      <i>STILL PROVIDE EXAMPLES even for known standards-grounds the LLM in your specific expectation</i>
-      <i>Unambiguous references-no unclear antecedents ("it", "this", "the above")</i>
-      <i>Note: LLM documents may be LONGER than human docs in some areas
-        (more explicit) while shorter in others (no warmth)</i>
-    </llm-reader-principles>
-    <structure-models>
-      <model name="Tutorial/Guide (Linear)" applicability="Tutorials, detailed guides, how-to articles, walkthroughs">
-        <i>Prerequisites: Setup/Context MUST precede action</i>
-        <i>Sequence: Steps must follow strict chronological or logical dependency order</i>
-        <i>Goal-oriented: clear 'Definition of Done' at the end</i>
-      </model>
-      <model name="Reference/Database" applicability="API docs, glossaries, configuration references, cheat sheets">
-        <i>Random Access: No narrative flow required; user jumps to specific item</i>
-        <i>MECE: Topics are Mutually Exclusive and Collectively Exhaustive</i>
-        <i>Consistent Schema: Every item follows identical structure (e.g., Signature to Params to Returns)</i>
-      </model>
-      <model name="Explanation (Conceptual)"
-        applicability="Deep dives, architecture overviews, conceptual guides,
-          whitepapers, project context">
-        <i>Abstract to Concrete: Definition to Context to Implementation/Example</i>
-        <i>Scaffolding: Complex ideas built on established foundations</i>
-      </model>
-      <model name="Prompt/Task Definition (Functional)"
-        applicability="BMAD tasks, prompts, system instructions, XML definitions">
-        <i>Meta-first: Inputs, usage constraints, and context defined before instructions</i>
-        <i>Separation of Concerns: Instructions (logic) separate from Data (content)</i>
-        <i>Step-by-step: Execution flow must be explicit and ordered</i>
-      </model>
-      <model name="Strategic/Context (Pyramid)" applicability="PRDs, research reports, proposals, decision records">
-        <i>Top-down: Conclusion/Status/Recommendation starts the document</i>
-        <i>Grouping: Supporting context grouped logically below the headline</i>
-        <i>Ordering: Most critical information first</i>
-        <i>MECE: Arguments/Groups are Mutually Exclusive and Collectively Exhaustive</i>
-        <i>Evidence: Data supports arguments, never leads</i>
-      </model>
-    </structure-models>
-  </llm>
-  <flow>
-    <step n="1" title="Validate Input">
-      <action>Check if content is empty or contains fewer than 3 words</action>
-      <action if="empty or fewer than 3 words">HALT with error: "Content
-        too short for substantive review (minimum 3 words required)"</action>
-      <action>Validate reader_type is "humans" or "llm" (or not provided, defaulting to "humans")</action>
-      <action if="reader_type is invalid">HALT with error: "Invalid reader_type. Must be 'humans' or 'llm'"</action>
-      <action>Identify document type and structure (headings, sections, lists, etc.)</action>
-      <action>Note the current word count and section count</action>
-    </step>
-    <step n="2" title="Understand Purpose">
-      <action>If purpose was provided, use it; otherwise infer from content</action>
-      <action>If target_audience was provided, use it; otherwise infer from content</action>
-      <action>Identify the core question the document answers</action>
-      <action>State in one sentence: "This document exists to help [audience] accomplish [goal]"</action>
-      <action>Select the most appropriate structural model from structure-models based on purpose/audience</action>
-      <action>Note reader_type and which principles apply (human-reader-principles or llm-reader-principles)</action>
-    </step>
-    <step n="3" title="Structural Analysis" critical="true">
-      <action if="style_guide provided">Consult style_guide now and note its key requirements—these override default principles for this
-        analysis</action>
-      <action>Map the document structure: list each major section with its word count</action>
-      <action>Evaluate structure against the selected model's primary rules
-        (e.g., 'Does recommendation come first?' for Pyramid)</action>
-      <action>For each section, answer: Does this directly serve the stated purpose?</action>
-      <action if="reader_type='humans'">For each comprehension aid (visual,
-        summary, example, callout), answer: Does this help readers
-        understand or stay engaged?</action>
-      <action>Identify sections that could be: cut entirely, merged with
-        another, moved to a different location, or split</action>
-      <action>Identify true redundancies: identical information repeated
-        without purpose (not summaries or reinforcement)</action>
-      <action>Identify scope violations: content that belongs in a different document</action>
-      <action>Identify burying: critical information hidden deep in the document</action>
-    </step>
-    <step n="4" title="Flow Analysis">
-      <action>Assess the reader's journey: Does the sequence match how readers will use this?</action>
-      <action>Identify premature detail: explanation given before the reader needs it</action>
-      <action>Identify missing scaffolding: complex ideas without adequate setup</action>
-      <action>Identify anti-patterns: FAQs that should be inline, appendices
-        that should be cut, overviews that repeat the body verbatim</action>
-      <action if="reader_type='humans'">Assess pacing: Is there enough
-        whitespace and visual variety to maintain attention?</action>
-    </step>
-    <step n="5" title="Generate Recommendations">
-      <action>Compile all findings into prioritized recommendations</action>
-      <action>Categorize each recommendation: CUT (remove entirely),
-        MERGE (combine sections), MOVE (reorder), CONDENSE (shorten
-        significantly), QUESTION (needs author decision), PRESERVE
-        (explicitly keep-for elements that might seem cuttable but
-        serve comprehension)</action>
-      <action>For each recommendation, state the rationale in one sentence</action>
-      <action>Estimate impact: how many words would this save (or cost, for PRESERVE)?</action>
-      <action>If length_target was provided, assess whether recommendations meet it</action>
-      <action if="reader_type='humans' and recommendations would cut
-        comprehension aids">Flag with warning: "This cut may impact
-        reader comprehension/engagement"</action>
-    </step>
-    <step n="6" title="Output Results">
-      <action>Output document summary (purpose, audience, reader_type, current length)</action>
-      <action>Output the recommendation list in priority order</action>
-      <action>Output estimated total reduction if all recommendations accepted</action>
-      <action if="no recommendations">Output: "No substantive changes recommended-document structure is sound"</action>
-      <output-format>
-        ## Document Summary
-        - **Purpose:** [inferred or provided purpose]
-        - **Audience:** [inferred or provided audience]
-        - **Reader type:** [selected reader type]
-        - **Structure model:** [selected structure model]
-        - **Current length:** [X] words across [Y] sections
-
-        ## Recommendations
-
-        ### 1. [CUT/MERGE/MOVE/CONDENSE/QUESTION/PRESERVE] - [Section or element name]
-        **Rationale:** [One sentence explanation]
-        **Impact:** ~[X] words
-        **Comprehension note:** [If applicable, note impact on reader understanding]
-
-        ### 2. ...
-
-        ## Summary
-        - **Total recommendations:** [N]
-        - **Estimated reduction:** [X] words ([Y]% of original)
-        - **Meets length target:** [Yes/No/No target specified]
-        - **Comprehension trade-offs:** [Note any cuts that sacrifice reader engagement for brevity]
-      </output-format>
-    </step>
-  </flow>
-  <halt-conditions>
-    <condition>HALT with error if content is empty or fewer than 3 words</condition>
-    <condition>HALT with error if reader_type is not "humans" or "llm"</condition>
-    <condition>If no structural issues found, output "No substantive changes
-      recommended" (this is valid completion, not an error)</condition>
-  </halt-conditions>
-</task>

src/core/tasks/index-docs.xml

@@ -1,65 +0,0 @@
-<task id="_bmad/core/tasks/index-docs" name="Index Docs"
-  description="Generates or updates an index.md to reference all docs in the folder. Use if user requests to create or update an index of all files in a specific folder">
-  <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
-    <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
-    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
-  </llm>
-
-  <flow>
-    <step n="1" title="Scan Directory">
-      <i>List all files and subdirectories in the target location</i>
-    </step>
-
-    <step n="2" title="Group Content">
-      <i>Organize files by type, purpose, or subdirectory</i>
-    </step>
-
-    <step n="3" title="Generate Descriptions">
-      <i>Read each file to understand its actual purpose and create brief (3-10 word) descriptions based on the content, not just the
-        filename</i>
-    </step>
-
-    <step n="4" title="Create/Update Index">
-      <i>Write or update index.md with organized file listings</i>
-    </step>
-  </flow>
-
-  <output-format>
-    <example>
-      # Directory Index
-
-      ## Files
-
-      - **[filename.ext](./filename.ext)** - Brief description
-      - **[another-file.ext](./another-file.ext)** - Brief description
-
-      ## Subdirectories
-
-      ### subfolder/
-
-      - **[file1.ext](./subfolder/file1.ext)** - Brief description
-      - **[file2.ext](./subfolder/file2.ext)** - Brief description
-
-      ### another-folder/
-
-      - **[file3.ext](./another-folder/file3.ext)** - Brief description
-    </example>
-  </output-format>
-
-  <halt-conditions critical="true">
-    <i>HALT if target directory does not exist or is inaccessible</i>
-    <i>HALT if user does not have write permissions to create index.md</i>
-  </halt-conditions>
-
-  <validation>
-    <i>Use relative paths starting with ./</i>
-    <i>Group similar files together</i>
-    <i>Read file contents to generate accurate descriptions - don't guess from filenames</i>
-    <i>Keep descriptions concise but informative (3-10 words)</i>
-    <i>Sort alphabetically within groups</i>
-    <i>Skip hidden files (starting with .) unless specified</i>
-  </validation>
-</task>

src/core/tasks/shard-doc.xml

@@ -1,108 +0,0 @@
-<task id="_bmad/core/tasks/shard-doc" name="Shard Document"
-  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document">
-  <objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
-
-  <llm critical="true">
-    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
-    <i>DO NOT skip steps or change the sequence</i>
-    <i>HALT immediately when halt-conditions are met</i>
-    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
-    <i>Sections outside flow (validation, output, critical-context) provide essential context - review and apply throughout execution</i>
-  </llm>
-
-  <critical-context>
-    <i>Uses `npx @kayvan/markdown-tree-parser` to automatically shard documents by level 2 headings and generate an index</i>
-  </critical-context>
-
-  <flow>
-    <step n="1" title="Get Source Document">
-      <action>Ask user for the source document path if not provided already</action>
-      <action>Verify file exists and is accessible</action>
-      <action>Verify file is markdown format (.md extension)</action>
-      <action if="file not found or not markdown">HALT with error message</action>
-    </step>
-
-    <step n="2" title="Get Destination Folder">
-      <action>Determine default destination: same location as source file, folder named after source file without .md extension</action>
-      <action>Example: /path/to/architecture.md → /path/to/architecture/</action>
-      <action>Ask user for the destination folder path ([y] to confirm use of default: [suggested-path], else enter a new path)</action>
-      <action if="user accepts default">Use the suggested destination path</action>
-      <action if="user provides custom path">Use the custom destination path</action>
-      <action>Verify destination folder exists or can be created</action>
-      <action>Check write permissions for destination</action>
-      <action if="permission denied">HALT with error message</action>
-    </step>
-
-    <step n="3" title="Execute Sharding">
-      <action>Inform user that sharding is beginning</action>
-      <action>Execute command: `npx @kayvan/markdown-tree-parser explode [source-document] [destination-folder]`</action>
-      <action>Capture command output and any errors</action>
-      <action if="command fails">HALT and display error to user</action>
-    </step>
-
-    <step n="4" title="Verify Output">
-      <action>Check that destination folder contains sharded files</action>
-      <action>Verify index.md was created in destination folder</action>
-      <action>Count the number of files created</action>
-      <action if="no files created">HALT with error message</action>
-    </step>
-
-    <step n="5" title="Report Completion">
-      <action>Display completion report to user including:</action>
-      <i>- Source document path and name</i>
-      <i>- Destination folder path</i>
-      <i>- Number of section files created</i>
-      <i>- Confirmation that index.md was created</i>
-      <i>- Any tool output or warnings</i>
-      <action>Inform user that sharding completed successfully</action>
-    </step>
-
-    <step n="6" title="Handle Original Document">
-      <critical>Keeping both the original and sharded versions defeats the purpose of sharding and can cause confusion</critical>
-      <action>Present user with options for the original document:</action>
-
-      <ask>What would you like to do with the original document `[source-document-name]`?
-
-        Options:
-        [d] Delete - Remove the original (recommended - shards can always be recombined)
-        [m] Move to archive - Move original to a backup/archive location
-        [k] Keep - Leave original in place (NOT recommended - defeats sharding purpose)
-
-        Your choice (d/m/k):</ask>
-
-      <check if="user selects 'd' (delete)">
-        <action>Delete the original source document file</action>
-        <action>Confirm deletion to user: "✓ Original document deleted: [source-document-path]"</action>
-        <note>The document can be reconstructed from shards by concatenating all section files in order</note>
-      </check>
-
-      <check if="user selects 'm' (move)">
-        <action>Determine default archive location: same directory as source, in an "archive" subfolder</action>
-        <action>Example: /path/to/architecture.md → /path/to/archive/architecture.md</action>
-        <ask>Archive location ([y] to use default: [default-archive-path], or provide custom path):</ask>
-        <action if="user accepts default">Use default archive path</action>
-        <action if="user provides custom path">Use custom archive path</action>
-        <action>Create archive directory if it doesn't exist</action>
-        <action>Move original document to archive location</action>
-        <action>Confirm move to user: "✓ Original document moved to: [archive-path]"</action>
-      </check>
-
-      <check if="user selects 'k' (keep)">
-        <action>Display warning to user:</action>
-        <output>⚠️ WARNING: Keeping both original and sharded versions is NOT recommended.
-
-          This creates confusion because:
-          - The discover_inputs protocol may load the wrong version
-          - Updates to one won't reflect in the other
-          - You'll have duplicate content taking up space
-
-          Consider deleting or archiving the original document.</output>
-        <action>Confirm user choice: "Original document kept at: [source-document-path]"</action>
-      </check>
-    </step>
-  </flow>
-
-  <halt-conditions critical="true">
-    <i>HALT if npx command fails or produces no output files</i>
-  </halt-conditions>
-</task>

src/core/workflows/bmad-party-mode/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: bmad-party-mode
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

src/core/workflows/bmad-party-mode/bmad-skill-manifest.yaml

@@ -0,0 +1 @@
+type: skill

src/core/workflows/bmad-party-mode/steps/step-03-graceful-exit.md

@@ -93,7 +93,6 @@ Final workflow completion steps:
 ```yaml
 ---
 stepsCompleted: [1, 2, 3]
-workflowType: 'party-mode'
 user_name: '{{user_name}}'
 date: '{{date}}'
 agents_loaded: true

src/core/workflows/bmad-party-mode/workflow.md

@@ -1,5 +1,5 @@
 ---
-name: party-mode
+name: bmad-party-mode
 description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.'
 ---
 
@@ -36,7 +36,6 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 
 ### Paths
 
-- `installed_path` = `{project-root}/_bmad/core/workflows/party-mode`
 - `agent_manifest_path` = `{project-root}/_bmad/_config/agent-manifest.csv`
 - `standalone_mode` = `true` (party mode is an interactive workflow)
 
@@ -115,7 +114,6 @@ Load step: `./steps/step-02-discussion-orchestration.md`
 ```yaml
 ---
 stepsCompleted: [1]
-workflowType: 'party-mode'
 user_name: '{{user_name}}'
 date: '{{date}}'
 agents_loaded: true

src/core/workflows/party-mode/bmad-skill-manifest.yaml

@@ -1,3 +0,0 @@
-canonicalId: bmad-party-mode
-type: workflow
-description: "Orchestrates group discussions between all installed BMAD agents"

test/fixtures/file-refs-csv/valid/core-style.csv

@@ -1,3 +1,3 @@
 module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs
 core,anytime,Brainstorming,BSP,,_bmad/core/workflows/brainstorming/workflow.md,bmad-brainstorming,false,analyst,,"Generate ideas",{output_folder}/brainstorming.md,
-core,anytime,Party Mode,PM,,_bmad/core/workflows/party-mode/workflow.md,bmad-party-mode,false,facilitator,,"Multi-agent discussion",,
+core,anytime,Party Mode,PM,,_bmad/core/workflows/bmad-party-mode/workflow.md,bmad-party-mode,false,facilitator,,"Multi-agent discussion",,

test/test-file-refs-csv.js

@@ -71,7 +71,7 @@ test('core-style.csv: extracts refs from core module-help format', () => {
   const refs = extractCsvRefs(fullPath, content);
   assert(refs.length === 2, `Expected 2 refs, got ${refs.length}`);
   assert(refs[0].raw === '_bmad/core/workflows/brainstorming/workflow.md', `Wrong raw[0]: ${refs[0].raw}`);
-  assert(refs[1].raw === '_bmad/core/workflows/party-mode/workflow.md', `Wrong raw[1]: ${refs[1].raw}`);
+  assert(refs[1].raw === '_bmad/core/workflows/bmad-party-mode/workflow.md', `Wrong raw[1]: ${refs[1].raw}`);
 });
 
 test('minimal.csv: extracts refs from minimal 3-column CSV', () => {

test/test-installation-components.js

@@ -81,6 +81,60 @@ async function createTestBmadFixture() {
   return fixtureDir;
 }
 
+async function createSkillCollisionFixture() {
+  const fixtureRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-skill-collision-'));
+  const fixtureDir = path.join(fixtureRoot, '_bmad');
+  const configDir = path.join(fixtureDir, '_config');
+  await fs.ensureDir(configDir);
+
+  await fs.writeFile(
+    path.join(configDir, 'agent-manifest.csv'),
+    [
+      'name,displayName,title,icon,capabilities,role,identity,communicationStyle,principles,module,path,canonicalId',
+      '"bmad-master","BMAD Master","","","","","","","","core","_bmad/core/agents/bmad-master.md","bmad-master"',
+      '',
+    ].join('\n'),
+  );
+
+  await fs.writeFile(
+    path.join(configDir, 'workflow-manifest.csv'),
+    [
+      'name,description,module,path,canonicalId',
+      '"help","Workflow help","core","_bmad/core/workflows/help/workflow.md","bmad-help"',
+      '',
+    ].join('\n'),
+  );
+
+  await fs.writeFile(path.join(configDir, 'task-manifest.csv'), 'name,displayName,description,module,path,standalone,canonicalId\n');
+  await fs.writeFile(path.join(configDir, 'tool-manifest.csv'), 'name,displayName,description,module,path,standalone,canonicalId\n');
+  await fs.writeFile(
+    path.join(configDir, 'skill-manifest.csv'),
+    [
+      'canonicalId,name,description,module,path,install_to_bmad',
+      '"bmad-help","bmad-help","Native help skill","core","_bmad/core/tasks/bmad-help/SKILL.md","true"',
+      '',
+    ].join('\n'),
+  );
+
+  const skillDir = path.join(fixtureDir, 'core', 'tasks', 'bmad-help');
+  await fs.ensureDir(skillDir);
+  await fs.writeFile(
+    path.join(skillDir, 'SKILL.md'),
+    ['---', 'name: bmad-help', 'description: Native help skill', '---', '', 'Use this skill directly.'].join('\n'),
+  );
+
+  const agentDir = path.join(fixtureDir, 'core', 'agents');
+  await fs.ensureDir(agentDir);
+  await fs.writeFile(
+    path.join(agentDir, 'bmad-master.md'),
+    ['---', 'name: BMAD Master', 'description: Master agent', '---', '', '<agent name="BMAD Master" title="Master">', '</agent>'].join(
+      '\n',
+    ),
+  );
+
+  return { root: fixtureRoot, bmadDir: fixtureDir };
+}
+
 /**
  * Test Suite
  */
@@ -1770,6 +1824,50 @@ async function runTests() {
 
   console.log('');
 
+  // ============================================================
+  // Test 31: Skill-format installs report unique skill directories
+  // ============================================================
+  console.log(`${colors.yellow}Test Suite 31: Skill Count Reporting${colors.reset}\n`);
+
+  let collisionFixtureRoot = null;
+  let collisionProjectDir = null;
+
+  try {
+    clearCache();
+    const collisionFixture = await createSkillCollisionFixture();
+    collisionFixtureRoot = collisionFixture.root;
+    collisionProjectDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-antigravity-test-'));
+
+    const ideManager = new IdeManager();
+    await ideManager.ensureInitialized();
+    const result = await ideManager.setup('antigravity', collisionProjectDir, collisionFixture.bmadDir, {
+      silent: true,
+      selectedModules: ['core'],
+    });
+
+    assert(result.success === true, 'Antigravity setup succeeds with overlapping skill names');
+    assert(result.detail === '2 agents', 'Installer detail reports agents separately from skills');
+    assert(result.handlerResult.results.skillDirectories === 2, 'Result exposes unique skill directory count');
+    assert(result.handlerResult.results.agents === 2, 'Result retains generated agent write count');
+    assert(result.handlerResult.results.workflows === 1, 'Result retains generated workflow count');
+    assert(result.handlerResult.results.skills === 1, 'Result retains verbatim skill count');
+    assert(
+      await fs.pathExists(path.join(collisionProjectDir, '.agent', 'skills', 'bmad-agent-bmad-master', 'SKILL.md')),
+      'Agent skill directory is created',
+    );
+    assert(
+      await fs.pathExists(path.join(collisionProjectDir, '.agent', 'skills', 'bmad-help', 'SKILL.md')),
+      'Overlapping skill directory is created once',
+    );
+  } catch (error) {
+    assert(false, 'Skill-format unique count test succeeds', error.message);
+  } finally {
+    if (collisionProjectDir) await fs.remove(collisionProjectDir).catch(() => {});
+    if (collisionFixtureRoot) await fs.remove(collisionFixtureRoot).catch(() => {});
+  }
+
+  console.log('');
+
   // ============================================================
   // Summary
   // ============================================================

test/test-installation-extensions.js

@@ -0,0 +1,302 @@
+/**
+ * Extension Module Merge Tests — Issue #1667
+ *
+ * Verifies that a custom extension module with `code: bmm` in its module.yaml
+ * merges its files into the base BMM installation instead of replacing the
+ * entire directory.
+ *
+ * Expected behavior (file-level merge):
+ *   - Files with the same name → extension overrides base
+ *   - Files with unique names  → extension adds alongside base
+ *
+ * Usage: node test/test-installation-extensions.js
+ */
+
+const path = require('node:path');
+const os = require('node:os');
+const fs = require('fs-extra');
+const { ModuleManager } = require('../tools/cli/installers/lib/modules/manager');
+
+// ANSI colors (match existing test files)
+const colors = {
+  reset: '\u001B[0m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  yellow: '\u001B[33m',
+  cyan: '\u001B[36m',
+  dim: '\u001B[2m',
+};
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, testName, errorMessage = '') {
+  if (condition) {
+    console.log(`${colors.green}✓${colors.reset} ${testName}`);
+    passed++;
+  } else {
+    console.log(`${colors.red}✗${colors.reset} ${testName}`);
+    if (errorMessage) console.log(`  ${colors.dim}${errorMessage}${colors.reset}`);
+    failed++;
+  }
+}
+
+/**
+ * Build a minimal compiled agent .md file (no YAML compilation needed).
+ */
+function minimalAgentMd(name) {
+  return ['---', `name: "${name}"`, `description: "Test agent: ${name}"`, '---', '', `You are ${name}.`].join('\n');
+}
+
+/**
+ * Create a fake base module source directory that looks like src/bmm/.
+ * Only files relevant to the merge test are created (agents directory).
+ */
+async function createBaseModuleSource(tmpDir) {
+  const src = path.join(tmpDir, 'src-base');
+
+  // module.yaml
+  await fs.ensureDir(src);
+  await fs.writeFile(path.join(src, 'module.yaml'), 'name: BMM\ncode: bmm\nversion: 6.0.0\n');
+
+  // agents: analyst + pm (standard base agents)
+  await fs.ensureDir(path.join(src, 'agents'));
+  await fs.writeFile(path.join(src, 'agents', 'analyst.md'), minimalAgentMd('analyst'));
+  await fs.writeFile(path.join(src, 'agents', 'pm.md'), minimalAgentMd('pm'));
+
+  return src;
+}
+
+/**
+ * Create a fake extension module source directory (simulates a user's
+ * custom module with code: bmm in its module.yaml).
+ *
+ * Includes:
+ *   - pm.md       → should OVERRIDE the base pm.md
+ *   - my-agent.md → unique name, should be ADDED alongside base agents
+ */
+async function createExtensionModuleSource(tmpDir) {
+  const src = path.join(tmpDir, 'src-extension');
+
+  await fs.ensureDir(src);
+  await fs.writeFile(path.join(src, 'module.yaml'), 'name: My Extension\ncode: bmm\nversion: 1.0.0\n');
+
+  await fs.ensureDir(path.join(src, 'agents'));
+  await fs.writeFile(path.join(src, 'agents', 'pm.md'), minimalAgentMd('pm-override'));
+  await fs.writeFile(path.join(src, 'agents', 'my-agent.md'), minimalAgentMd('my-agent'));
+
+  return src;
+}
+
+async function runTests() {
+  console.log(`${colors.cyan}========================================`);
+  console.log('Extension Module Merge — Issue #1667');
+  console.log(`========================================${colors.reset}\n`);
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test 1: isExtension:false (default) — second install replaces directory
+  // (confirms the bug existed: without the fix, extension would wipe base)
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log(`${colors.yellow}Scenario A: install without isExtension (replacement mode)${colors.reset}\n`);
+
+  {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-ext-test-'));
+    try {
+      const baseSrc = await createBaseModuleSource(tmpDir);
+      const extSrc = await createExtensionModuleSource(tmpDir);
+      const bmadDir = path.join(tmpDir, '_bmad');
+      const targetPath = path.join(bmadDir, 'bmm');
+
+      const manager = new ModuleManager();
+      // Register extension as the 'bmm' custom module path
+      manager.setCustomModulePaths(new Map([['bmm', extSrc]]));
+
+      // Simulate base install (not custom)
+      await fs.ensureDir(path.join(targetPath, 'agents'));
+      await fs.copy(path.join(baseSrc, 'agents', 'analyst.md'), path.join(targetPath, 'agents', 'analyst.md'));
+      await fs.copy(path.join(baseSrc, 'agents', 'pm.md'), path.join(targetPath, 'agents', 'pm.md'));
+
+      // Simulate extension install WITHOUT isExtension flag (old/broken behavior)
+      if (await fs.pathExists(targetPath)) {
+        await fs.remove(targetPath); // This is what the old code did unconditionally
+      }
+      await fs.ensureDir(path.join(targetPath, 'agents'));
+      await fs.copy(path.join(extSrc, 'agents', 'pm.md'), path.join(targetPath, 'agents', 'pm.md'));
+      await fs.copy(path.join(extSrc, 'agents', 'my-agent.md'), path.join(targetPath, 'agents', 'my-agent.md'));
+
+      const analystExists = await fs.pathExists(path.join(targetPath, 'agents', 'analyst.md'));
+      const myAgentExists = await fs.pathExists(path.join(targetPath, 'agents', 'my-agent.md'));
+
+      assert(!analystExists, 'Without fix: base analyst.md is GONE (replacement behavior confirmed)');
+      assert(myAgentExists, 'Without fix: extension my-agent.md is present');
+    } finally {
+      await fs.remove(tmpDir);
+    }
+  }
+
+  console.log('');
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test 2: isExtension:true (the fix) — extension merges on top of base
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log(`${colors.yellow}Scenario B: install with isExtension:true (merge mode — the fix)${colors.reset}\n`);
+
+  {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-ext-test-'));
+    try {
+      const baseSrc = await createBaseModuleSource(tmpDir);
+      const extSrc = await createExtensionModuleSource(tmpDir);
+      const bmadDir = path.join(tmpDir, '_bmad');
+      const targetPath = path.join(bmadDir, 'bmm');
+
+      const manager = new ModuleManager();
+      manager.setCustomModulePaths(new Map([['bmm', extSrc]]));
+
+      // Step 1: Install base module (normal, no isExtension)
+      await fs.ensureDir(path.join(targetPath, 'agents'));
+      await fs.copy(path.join(baseSrc, 'agents', 'analyst.md'), path.join(targetPath, 'agents', 'analyst.md'));
+      await fs.copy(path.join(baseSrc, 'agents', 'pm.md'), path.join(targetPath, 'agents', 'pm.md'));
+
+      // Step 2: Install extension with isExtension:true → should MERGE
+      // (reproduce what manager.install does: skip removal, then copy)
+      const skipRemoval = true; // isExtension:true skips fs.remove
+      if ((await fs.pathExists(targetPath)) && !skipRemoval) {
+        await fs.remove(targetPath);
+      }
+      // Copy extension files over (overwrite same-named, add unique)
+      await fs.copy(path.join(extSrc, 'agents', 'pm.md'), path.join(targetPath, 'agents', 'pm.md'), { overwrite: true });
+      await fs.copy(path.join(extSrc, 'agents', 'my-agent.md'), path.join(targetPath, 'agents', 'my-agent.md'));
+
+      const analystExists = await fs.pathExists(path.join(targetPath, 'agents', 'analyst.md'));
+      const myAgentExists = await fs.pathExists(path.join(targetPath, 'agents', 'my-agent.md'));
+      const pmContent = await fs.readFile(path.join(targetPath, 'agents', 'pm.md'), 'utf8');
+
+      assert(analystExists, 'Base analyst.md is PRESERVED after extension install');
+      assert(myAgentExists, 'Extension my-agent.md is ADDED alongside base agents');
+      assert(pmContent.includes('pm-override'), 'Extension pm.md OVERRIDES base pm.md (same-name wins)');
+    } finally {
+      await fs.remove(tmpDir);
+    }
+  }
+
+  console.log('');
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test 3: ModuleManager.install() with isExtension:true via options
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log(`${colors.yellow}Scenario C: ModuleManager.install() respects isExtension option${colors.reset}\n`);
+
+  {
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-ext-test-'));
+    try {
+      const bmadDir = path.join(tmpDir, '_bmad');
+      const targetPath = path.join(bmadDir, 'bmm');
+
+      // Pre-populate target with base files (simulates base module already installed)
+      await fs.ensureDir(path.join(targetPath, 'agents'));
+      await fs.writeFile(path.join(targetPath, 'agents', 'analyst.md'), minimalAgentMd('analyst'));
+      await fs.writeFile(path.join(targetPath, 'agents', 'pm.md'), minimalAgentMd('pm-base'));
+
+      // Verify pre-condition
+      assert(
+        await fs.pathExists(path.join(targetPath, 'agents', 'analyst.md')),
+        'Pre-condition: base analyst.md exists before extension install',
+      );
+
+      // Now check that isExtension:true in options causes skip of fs.remove
+      // by reading the manager source and verifying the condition
+      const managerSrc = await fs.readFile(path.join(__dirname, '../tools/cli/installers/lib/modules/manager.js'), 'utf8');
+
+      const hasExtensionGuard = managerSrc.includes('!options.isExtension');
+      assert(
+        hasExtensionGuard,
+        'manager.js guards fs.remove with !options.isExtension',
+        'Expected: if ((await fs.pathExists(targetPath)) && !options.isExtension)',
+      );
+    } finally {
+      await fs.remove(tmpDir);
+    }
+  }
+
+  console.log('');
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Test 4 (E2E): installModuleWithDependencies → base install, then
+  //               moduleManager.install with isExtension:true → merge
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log(
+    `${colors.yellow}Scenario D: E2E install — base via installModuleWithDependencies, extension via moduleManager.install${colors.reset}\n`,
+  );
+
+  {
+    const { Installer } = require('../tools/cli/installers/lib/core/installer');
+    const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'bmad-e2e-test-'));
+    try {
+      const baseSrc = await createBaseModuleSource(tmpDir);
+      const extSrc = await createExtensionModuleSource(tmpDir);
+      const bmadDir = path.join(tmpDir, '_bmad');
+
+      // Pre-create a minimal manifest so moduleManager.install can record the module
+      await fs.ensureDir(path.join(bmadDir, '_config'));
+      await fs.writeFile(
+        path.join(bmadDir, '_config', 'manifest.yaml'),
+        'installation:\n  version: "0.0.0"\n  installDate: "2026-01-01T00:00:00.000Z"\n  lastUpdated: "2026-01-01T00:00:00.000Z"\nmodules: []\nides: []\n',
+      );
+
+      const installer = new Installer();
+
+      // Stub the resolver: point 'bmm' at the fake base source
+      installer.moduleManager.setCustomModulePaths(new Map([['bmm', baseSrc]]));
+
+      // Step 1: Install base module via the public installModuleWithDependencies
+      await installer.installModuleWithDependencies('bmm', bmadDir, {});
+
+      const targetPath = path.join(bmadDir, 'bmm');
+      assert(
+        await fs.pathExists(path.join(targetPath, 'agents', 'analyst.md')),
+        'E2E: after base install via installModuleWithDependencies — analyst.md is present',
+      );
+      assert(
+        await fs.pathExists(path.join(targetPath, 'agents', 'pm.md')),
+        'E2E: after base install via installModuleWithDependencies — pm.md is present',
+      );
+
+      // Step 2: Re-stub the resolver to point to the extension source, then install
+      // the extension with isExtension:true so it merges on top of the base
+      installer.moduleManager.setCustomModulePaths(new Map([['bmm', extSrc]]));
+      await installer.moduleManager.install('bmm', bmadDir, null, {
+        isExtension: true,
+        skipModuleInstaller: true,
+        silent: true,
+      });
+
+      // Assert merged output: base files preserved, extension files added/overridden
+      assert(
+        await fs.pathExists(path.join(targetPath, 'agents', 'analyst.md')),
+        'E2E: base analyst.md is PRESERVED after extension install (merge, not replace)',
+      );
+      assert(
+        await fs.pathExists(path.join(targetPath, 'agents', 'my-agent.md')),
+        'E2E: extension my-agent.md is ADDED alongside base agents',
+      );
+      const pmContent = await fs.readFile(path.join(targetPath, 'agents', 'pm.md'), 'utf8');
+      assert(pmContent.includes('pm-override'), 'E2E: extension pm.md OVERRIDES base pm.md (same-name wins)');
+    } finally {
+      await fs.remove(tmpDir);
+    }
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Summary
+  // ─────────────────────────────────────────────────────────────────────────
+  console.log(`\n${colors.cyan}========================================${colors.reset}`);
+  console.log(`Results: ${colors.green}${passed} passed${colors.reset}, ${failed > 0 ? colors.red : ''}${failed} failed${colors.reset}`);
+  console.log(`${colors.cyan}========================================${colors.reset}\n`);
+
+  if (failed > 0) process.exit(1);
+}
+
+runTests().catch((error) => {
+  console.error(`${colors.red}Unexpected error:${colors.reset}`, error);
+  process.exit(1);
+});

tools/cli/external-official-modules.yaml

@@ -2,15 +2,15 @@
 # allowing us to keep the source of these projects in separate repos.
 
 modules:
-  bmad-builder:
-    url: https://github.com/bmad-code-org/bmad-builder
-    module-definition: src/module.yaml
-    code: bmb
-    name: "BMad Builder"
-    description: "Agent, Workflow and Module Builder"
-    defaultSelected: false
-    type: bmad-org
-    npmPackage: bmad-builder
+  # bmad-builder:
+  #   url: https://github.com/bmad-code-org/bmad-builder
+  #   module-definition: src/module.yaml
+  #   code: bmb
+  #   name: "BMad Builder"
+  #   description: "Agent, Workflow and Module Builder"
+  #   defaultSelected: false
+  #   type: bmad-org
+  #   npmPackage: bmad-builder
 
   bmad-creative-intelligence-suite:
     url: https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite

tools/cli/installers/lib/core/installer.js

@@ -999,6 +999,40 @@ class Installer {
                   this.moduleManager.setCustomModulePaths(customModulePaths);
                 }
 
+                // Check if this custom module extends a built-in/external base module.
+                // If a base source exists at a different path, install it first so the
+                // extension merges on top instead of replacing the entire directory (#1667).
+                const customSourcePath = customModulePaths.get(moduleName);
+                const baseSourcePath = getModulePath(moduleName);
+                const hasBaseModule =
+                  customSourcePath &&
+                  baseSourcePath !== customSourcePath &&
+                  (await fs.pathExists(path.join(baseSourcePath, 'module.yaml')));
+
+                if (hasBaseModule) {
+                  // Temporarily clear custom path so findModuleSource resolves to the base
+                  customModulePaths.delete(moduleName);
+                  this.moduleManager.setCustomModulePaths(customModulePaths);
+
+                  // Install the base module first (clean install, removes any prior version)
+                  if (resolution && resolution.byModule && resolution.byModule[moduleName]) {
+                    await this.installModuleWithDependencies(moduleName, bmadDir, resolution.byModule[moduleName]);
+                  } else {
+                    await this.moduleManager.install(
+                      moduleName,
+                      bmadDir,
+                      (filePath) => {
+                        this.installedFiles.add(filePath);
+                      },
+                      { installer: this, silent: true },
+                    );
+                  }
+
+                  // Restore the custom path for the extension overlay
+                  customModulePaths.set(moduleName, customSourcePath);
+                  this.moduleManager.setCustomModulePaths(customModulePaths);
+                }
+
                 const collectedModuleConfig = moduleConfigs[moduleName] || {};
                 await this.moduleManager.install(
                   moduleName,
@@ -1008,6 +1042,7 @@ class Installer {
                   },
                   {
                     isCustom: true,
+                    isExtension: hasBaseModule, // merge on top of base when extending
                     moduleConfig: collectedModuleConfig,
                     isQuickUpdate: isQuickUpdate,
                     installer: this,
@@ -1153,12 +1188,6 @@ class Installer {
             preservedModules: modulesForCsvPreserve,
           });
 
-          addResult(
-            'Manifests',
-            'ok',
-            `${manifestStats.workflows} workflows, ${manifestStats.agents} agents, ${manifestStats.tasks} tasks, ${manifestStats.tools} tools`,
-          );
-
           // Merge help catalogs
           message('Generating help catalog...');
           await this.mergeModuleHelpCatalogs(bmadDir);
@@ -1379,10 +1408,27 @@ class Installer {
    */
   async renderInstallSummary(results, context = {}) {
     const color = await prompts.getColor();
+    const selectedIdes = new Set((context.ides || []).map((ide) => String(ide).toLowerCase()));
 
     // Build step lines with status indicators
     const lines = [];
     for (const r of results) {
+      let stepLabel = null;
+
+      if (r.status !== 'ok') {
+        stepLabel = r.step;
+      } else if (r.step === 'Core') {
+        stepLabel = 'BMAD';
+      } else if (r.step.startsWith('Module: ')) {
+        stepLabel = r.step;
+      } else if (selectedIdes.has(String(r.step).toLowerCase())) {
+        stepLabel = r.step;
+      }
+
+      if (!stepLabel) {
+        continue;
+      }
+
       let icon;
       if (r.status === 'ok') {
         icon = color.green('\u2713');
@@ -1392,7 +1438,11 @@ class Installer {
         icon = color.red('\u2717');
       }
       const detail = r.detail ? color.dim(` (${r.detail})`) : '';
-      lines.push(`  ${icon}  ${r.step}${detail}`);
+      lines.push(`  ${icon}  ${stepLabel}${detail}`);
+    }
+
+    if ((context.ides || []).length === 0) {
+      lines.push(`  ${color.green('\u2713')}  No IDE selected ${color.dim('(installed in _bmad only)')}`);
     }
 
     // Context and warnings
@@ -1415,8 +1465,10 @@ class Installer {
       `    Join our Discord: ${color.dim('https://discord.gg/gk8jAdXWmj')}`,
       `    Star us on GitHub: ${color.dim('https://github.com/bmad-code-org/BMAD-METHOD/')}`,
       `    Subscribe on YouTube: ${color.dim('https://www.youtube.com/@BMadCode')}`,
-      `    Invoke the ${color.cyan('bmad-help')} skill in your IDE Agent to get started`,
     );
+    if (context.ides && context.ides.length > 0) {
+      lines.push(`    Invoke the ${color.cyan('bmad-help')} skill in your IDE Agent to get started`);
+    }
 
     await prompts.note(lines.join('\n'), 'BMAD is ready to use!');
   }

tools/cli/installers/lib/ide/_config-driven.js

@@ -129,6 +129,7 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup {
 
     const selectedModules = options.selectedModules || [];
     const results = { agents: 0, workflows: 0, tasks: 0, tools: 0, skills: 0 };
+    this.skillWriteTracker = config.skill_format ? new Set() : null;
 
     // Install standard artifacts (agents, workflows, tasks, tools)
     if (!skipStandardArtifacts) {
@@ -159,9 +160,11 @@ class ConfigDrivenIdeSetup extends BaseIdeSetup {
     // Install verbatim skills (type: skill)
     if (config.skill_format) {
       results.skills = await this.installVerbatimSkills(projectDir, bmadDir, targetPath, config);
+      results.skillDirectories = this.skillWriteTracker ? this.skillWriteTracker.size : 0;
     }
 
     await this.printSummary(results, target_dir, options);
+    this.skillWriteTracker = null;
     return { success: true, results };
   }
 
@@ -495,6 +498,7 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
     // Create skill directory
     const skillDir = path.join(targetPath, skillName);
     await this.ensureDir(skillDir);
+    this.skillWriteTracker?.add(skillName);
 
     // Transform content: rewrite frontmatter for skills format
     const skillContent = this.transformToSkillFormat(content, skillName);
@@ -667,6 +671,7 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
       const skillDir = path.join(targetPath, canonicalId);
       await fs.remove(skillDir);
       await fs.ensureDir(skillDir);
+      this.skillWriteTracker?.add(canonicalId);
 
       // Copy all skill files, filtering OS/editor artifacts recursively
       const skipPatterns = new Set(['.DS_Store', 'Thumbs.db', 'desktop.ini']);
@@ -707,11 +712,11 @@ LOAD and execute from: {project-root}/{{bmadFolderName}}/{{path}}
   async printSummary(results, targetDir, options = {}) {
     if (options.silent) return;
     const parts = [];
+    const totalDirs =
+      results.skillDirectories || (results.workflows || 0) + (results.tasks || 0) + (results.tools || 0) + (results.skills || 0);
+    const skillCount = totalDirs - (results.agents || 0);
+    if (skillCount > 0) parts.push(`${skillCount} skills`);
     if (results.agents > 0) parts.push(`${results.agents} agents`);
-    if (results.workflows > 0) parts.push(`${results.workflows} workflows`);
-    if (results.tasks > 0) parts.push(`${results.tasks} tasks`);
-    if (results.tools > 0) parts.push(`${results.tools} tools`);
-    if (results.skills > 0) parts.push(`${results.skills} skills`);
     await prompts.log.success(`${this.name} configured: ${parts.join(', ')} → ${targetDir}`);
   }
 

tools/cli/installers/lib/ide/manager.js

@@ -162,10 +162,10 @@ class IdeManager {
         // Config-driven handlers return { success, results: { agents, workflows, tasks, tools } }
         const r = handlerResult.results;
         const parts = [];
+        const totalDirs = r.skillDirectories || (r.workflows || 0) + (r.tasks || 0) + (r.tools || 0) + (r.skills || 0);
+        const skillCount = totalDirs - (r.agents || 0);
+        if (skillCount > 0) parts.push(`${skillCount} skills`);
         if (r.agents > 0) parts.push(`${r.agents} agents`);
-        if (r.workflows > 0) parts.push(`${r.workflows} workflows`);
-        if (r.tasks > 0) parts.push(`${r.tasks} tasks`);
-        if (r.tools > 0) parts.push(`${r.tools} tools`);
         detail = parts.join(', ');
       }
       // Propagate handler's success status (default true for backward compat)

tools/cli/installers/lib/modules/manager.js

@@ -554,7 +554,10 @@ class ModuleManager {
     }
 
     // Check if already installed
-    if (await fs.pathExists(targetPath)) {
+    // When isExtension is true, the caller is merging an extension module on top
+    // of an already-installed base module (same code). Skip removal so that base
+    // files are preserved and the extension's files overlay at the file level.
+    if ((await fs.pathExists(targetPath)) && !options.isExtension) {
       await fs.remove(targetPath);
     }
 

tools/cli/lib/agent/compiler.js

@@ -157,7 +157,7 @@ function buildMenuXml(menuItems) {
     }
   }
 
-  xml += `    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/party-mode/workflow.md">[PM] Start Party Mode</item>\n`;
+  xml += `    <item cmd="PM or fuzzy match on party-mode" exec="{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md">[PM] Start Party Mode</item>\n`;
   xml += `    <item cmd="DA or fuzzy match on exit, leave, goodbye or dismiss agent">[DA] Dismiss Agent</item>\n`;
 
   xml += '  </menu>\n';