chore(release): 4.29.0 [skip ci]

# [4.29.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.28.0...v4.29.0) (2025-07-13)

### Features

* Claude Code slash commands for Tasks and Agents! ([e9e541a](e9e541a52e))

CHANGELOG.md

@@ -1,3 +1,52 @@
+# [4.29.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.28.0...v4.29.0) (2025-07-13)
+
+
+### Features
+
+* Claude Code slash commands for Tasks and Agents! ([e9e541a](https://github.com/bmadcode/BMAD-METHOD/commit/e9e541a52e45f6632b2f8c91d10e39c077c1ecc9))
+
+# [4.28.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.6...v4.28.0) (2025-07-12)
+
+
+### Features
+
+* bmad-master can load kb properly ([3c13c56](https://github.com/bmadcode/BMAD-METHOD/commit/3c13c564988f9750e043939dd770aea4196a7e7a))
+
+## [4.27.6](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.5...v4.27.6) (2025-07-08)
+
+
+### Bug Fixes
+
+* installer improvement ([db30230](https://github.com/bmadcode/BMAD-METHOD/commit/db302309f42da49daa309b5ba1a625c719e5bb14))
+
+## [4.27.5](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.4...v4.27.5) (2025-07-08)
+
+
+### Bug Fixes
+
+* installer for github copilot asks follow up questions right away now so it does not seem to hang, and some minor doc improvements ([cadf8b6](https://github.com/bmadcode/BMAD-METHOD/commit/cadf8b6750afd5daa32eb887608c614584156a69))
+
+## [4.27.4](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.3...v4.27.4) (2025-07-07)
+
+
+### Bug Fixes
+
+* doc updates ([1b86cd4](https://github.com/bmadcode/BMAD-METHOD/commit/1b86cd4db3644ca2b2b4a94821cc8b5690d78e0a))
+
+## [4.27.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.2...v4.27.3) (2025-07-07)
+
+
+### Bug Fixes
+
+* remove test zoo folder ([908dcd7](https://github.com/bmadcode/BMAD-METHOD/commit/908dcd7e9afae3fd23cd894c0d09855fc9c42d0e))
+
+## [4.27.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.1...v4.27.2) (2025-07-07)
+
+
+### Bug Fixes
+
+* improve output ([a5ffe7b](https://github.com/bmadcode/BMAD-METHOD/commit/a5ffe7b9b209ae02a9d97adf60fe73c0bc9701e4))
+
 ## [4.27.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.27.0...v4.27.1) (2025-07-07)
 
 

CONTRIBUTING.md

@@ -4,7 +4,7 @@ Thank you for considering contributing to this project! This document outlines t
 
 🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
 
-📋 **Before contributing**, please read our [Guiding Principles](GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
+📋 **Before contributing**, please read our [Guiding Principles](docs/GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
 
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
@@ -52,7 +52,7 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
 
 Please only propose small granular commits! If its large or significant, please discuss in the discussions tab and open up an issue first. I do not want you to waste your time on a potentially very large PR to have it rejected because it is not aligned or deviates from other planned changes. Communicate and lets work together to build and improve this great community project!
 
-**Important**: All contributions must align with our [Guiding Principles](GUIDING-PRINCIPLES.md). Key points:
+**Important**: All contributions must align with our [Guiding Principles](docs/GUIDING-PRINCIPLES.md). Key points:
 
 - Keep dev agents lean - they need context for coding, not documentation
 - Web/planning agents can be larger with more complex tasks

bmad-core/agents/analyst.md

@@ -1,11 +1,10 @@
 # analyst
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/architect.md

@@ -1,11 +1,10 @@
 # architect
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/bmad-master.md

@@ -1,62 +1,42 @@
 # BMad Master
 
-CRITICAL: Read the full YAML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Greet the user with your name and role, and inform of the *help command.
-  - Check for active workflow plan using the utils plan-management
-  - If plan exists: Show brief status - Active plan {workflow} in progress
-  - If plan exists: Suggest next step based on plan
   - CRITICAL: Do NOT scan filesystem or load any resources during startup, ONLY when commanded
   - CRITICAL: Do NOT run discovery tasks automatically
+  - CRITICAL: NEVER LOAD {root}/data/bmad-kb.md UNLESS USER TYPES *kb
 agent:
   name: BMad Master
   id: bmad-master
   title: BMad Master Task Executor
   icon: 🧙
-  whenToUse: Use when you need comprehensive expertise across all domains or rapid context switching between multiple agent capabilities
+  whenToUse: Use when you need comprehensive expertise across all domains, running 1 off tasks that do not require a persona, or just wanting to use the same agent for many things.
 persona:
   role: Master Task Executor & BMad Method Expert
-  style: Efficient, direct, action-oriented. Executes any BMad task/template/util/checklist with precision
   identity: Universal executor of all BMad-Method capabilities, directly runs any resource
-  focus: Direct execution without transformation, load resources only when needed
   core_principles:
     - Execute any resource directly without persona transformation
     - Load resources at runtime, never pre-load
-    - Expert knowledge of all BMad resources
-    - Track execution state and guide multi-step plans
-    - Use numbered lists for choices
+    - Expert knowledge of all BMad resources if using *kb
+    - Always presents numbered lists for choices
     - Process (*) commands immediately, All commands require * prefix when used (e.g., *help)
 
 commands:
   - help: Show these listed commands in a numbered list
-  - kb: Toggle KB mode off (default) or on, when on will load and reference the data/bmad-kb and converse with the user answering his questions with this informational resource
+  - kb: Toggle KB mode off (default) or on, when on will load and reference the {root}/data/bmad-kb.md and converse with the user answering his questions with this informational resource
   - task {task}: Execute task, if not found or none specified, ONLY list available dependencies/tasks listed below
-  - list {task|template|util|checklist|workflow}: List resources by type ONLY from the corresponding dependencies sub item below
   - create-doc {template}: execute task create-doc (no template = ONLY show available templates listed under dependencies/templates below)
-  - create-prd-alpha: Execute task create-doc2 with .bmad-core/templates/prd-tmpl2.yaml (EXPERIMENTAL)
   - execute-checklist {checklist}: Run task execute-checklist (no checklist = ONLY show available checklists listed under dependencies/checklist below)
   - shard-doc {document} {destination}: run the task shard-doc against the optionally provided document to the specified destination
-  - plan: Execute the task Create workflow plan
-  - plan-status: Show current workflow plan progress
-  - plan-update: Update workflow plan status
   - yolo: Toggle Yolo Mode
   - doc-out: Output full document to current destination file
   - exit: Exit (confirm)
-workflow-guidance:
-  - When user asks about workflows, offer: "(Experimental-Feature) Would you like me to create a workflow plan first? (*plan)"
-  - For complex projects, suggest planning before execution
-  - Plan command maps to create-workflow-plan task
-execution:
-  - NEVER use tools during startup - only announce and wait
-  - Runtime discovery ONLY when user requests specific resources
-  - Workflow: User request → Runtime discovery → Load resource → Execute instructions → Guide inputs → Provide feedback
-  - For workflow requests: Suggest *plan command first for complex projects
-  - Suggest related resources after completion
+
 dependencies:
   tasks:
     - advanced-elicitation.md
@@ -66,14 +46,12 @@ dependencies:
     - correct-course.md
     - create-deep-research-prompt.md
     - create-doc.md
-    - create-workflow-plan.md
     - document-project.md
     - create-next-story.md
     - execute-checklist.md
     - generate-ai-frontend-prompt.md
     - index-docs.md
     - shard-doc.md
-    - update-workflow-plan.md
   templates:
     - architecture-tmpl.yaml
     - brownfield-architecture-tmpl.yaml
@@ -91,10 +69,6 @@ dependencies:
     - brainstorming-techniques.md
     - elicitation-methods.md
     - technical-preferences.md
-  utils:
-    - plan-management.md
-    - template-format.md
-    - workflow-management.md
   workflows:
     - brownfield-fullstack.md
     - brownfield-service.md

bmad-core/agents/bmad-orchestrator.md

@@ -1,18 +1,14 @@
 # BMad Web Orchestrator
 
-CRITICAL: Read the full YAML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Announce: Introduce yourself as the BMad Orchestrator, explain you can coordinate agents and workflows
   - IMPORTANT: Tell users that all commands start with * (e.g., *help, *agent, *workflow)
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using {root}/utils/plan-management.md
-  - "If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details."
-  - "If plan exists: Suggest next action based on plan progress"
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -118,7 +114,6 @@ workflow-guidance:
   - Understand each workflow's purpose, options, and decision points
   - Ask clarifying questions based on the workflow's structure
   - Guide users through workflow selection when multiple options exist
-  - For complex projects, offer to create a workflow plan using create-workflow-plan task
   - When appropriate, suggest: "Would you like me to create a detailed workflow plan before starting?"
   - For workflows with divergent paths, help users choose the right path
   - Adapt questions to the specific domain (e.g., game dev vs infrastructure vs web dev)
@@ -128,14 +123,10 @@ dependencies:
   tasks:
     - advanced-elicitation.md
     - create-doc.md
-    - create-workflow-plan.md
     - kb-mode-interaction.md
-    - update-workflow-plan.md
   data:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```

bmad-core/agents/dev.md

@@ -1,11 +1,10 @@
 # dev
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Announce: Greet the user with your name and role, and inform of the *help command.
   - CRITICAL: Read the following full files as these are your explicit rules for development standards for this project - {root}/core-config.yaml devLoadAlwaysFiles list

bmad-core/agents/pm.md

@@ -1,11 +1,10 @@
 # pm
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/po.md

@@ -1,11 +1,10 @@
 # po
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/qa.md

@@ -1,11 +1,10 @@
 # qa
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/agents/sm.md

@@ -1,11 +1,10 @@
 # sm
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.yaml), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - The customization field ALWAYS takes precedence over any conflicting instructions

bmad-core/agents/ux-expert.md

@@ -1,11 +1,10 @@
 # ux-expert
 
-CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start and follow exactly your activation-instructions to alter your state of being, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-core
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

bmad-core/core-config.yaml

@@ -18,8 +18,4 @@ devLoadAlwaysFiles:
   - docs/architecture/source-tree.md
 devDebugLog: .ai/debug-log.md
 devStoryLocation: docs/stories
-workflow:
-  planFile: docs/workflow-plan.md
-  trackProgress: true
-  enforceSequence: false
-  updateOnCompletion: true
+slashPrefix: BMad

bmad-core/data/bmad-kb.md

@@ -162,8 +162,8 @@ npx bmad-method install
 
 **CRITICAL RULE for Development**:
 
-- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
-- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
+- **ALWAYS use SM agent for story creation** - Never use bmad-master or bmad-orchestrator
+- **ALWAYS use Dev agent for implementation** - Never use bmad-master or bmad-orchestrator
 - **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
 - **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
 
@@ -403,17 +403,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -733,7 +726,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -803,8 +796,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines

bmad-core/tasks/correct-course.md

@@ -2,9 +2,9 @@
 
 ## Purpose
 
-- Guide a structured response to a change trigger using the `change-checklist`.
+- Guide a structured response to a change trigger using the `{root}/checklists/change-checklist`.
 - Analyze the impacts of the change on epics, project artifacts, and the MVP, guided by the checklist's structure.
-- Explore potential solutions (e.g., adjust scope, rollback elements, rescope features) as prompted by the checklist.
+- Explore potential solutions (e.g., adjust scope, rollback elements, re-scope features) as prompted by the checklist.
 - Draft specific, actionable proposed updates to any affected project artifacts (e.g., epics, user stories, PRD sections, architecture document sections) based on the analysis.
 - Produce a consolidated "Sprint Change Proposal" document that contains the impact analysis and the clearly drafted proposed edits for user review and approval.
 - Ensure a clear handoff path if the nature of the changes necessitates fundamental replanning by other core agents (like PM or Architect).
@@ -16,19 +16,16 @@
 - **Acknowledge Task & Inputs:**
   - Confirm with the user that the "Correct Course Task" (Change Navigation & Integration) is being initiated.
   - Verify the change trigger and ensure you have the user's initial explanation of the issue and its perceived impact.
-  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `change-checklist` (e.g., `change-checklist`).
+  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `{root}/checklists/change-checklist`.
 - **Establish Interaction Mode:**
   - Ask the user their preferred interaction mode for this task:
-    - **"Incrementally (Default & Recommended):** Shall we work through the `change-checklist` section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
+    - **"Incrementally (Default & Recommended):** Shall we work through the change-checklist section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
     - **"YOLO Mode (Batch Processing):** Or, would you prefer I conduct a more batched analysis based on the checklist and then present a consolidated set of findings and proposed changes for a broader review? This can be quicker for initial assessment but might require more extensive review of the combined proposals."
-  - Request the user to select their preferred mode.
-  - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed.
-- **Explain Process:** Briefly inform the user: "We will now use the `change-checklist` to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
-  <rule>When asking multiple questions or presenting multiple points for user input at once, number them clearly (e.g., 1., 2a., 2b.) to make it easier for the user to provide specific responses.</rule>
+  - Once the user chooses, confirm the selected mode and then inform the user: "We will now use the change-checklist to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
 
 ### 2. Execute Checklist Analysis (Iteratively or Batched, per Interaction Mode)
 
-- Systematically work through Sections 1-4 of the `change-checklist` (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
+- Systematically work through Sections 1-4 of the change-checklist (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
 - For each checklist item or logical group of items (depending on interaction mode):
   - Present the relevant prompt(s) or considerations from the checklist to the user.
   - Request necessary information and actively analyze the relevant project artifacts (PRD, epics, architecture documents, story history, etc.) to assess the impact.
@@ -51,7 +48,7 @@
 
 ### 4. Generate "Sprint Change Proposal" with Edits
 
-- Synthesize the complete `change-checklist` analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the `change-checklist` (Proposal Components).
+- Synthesize the complete change-checklist analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the change-checklist.
 - The proposal must clearly present:
   - **Analysis Summary:** A concise overview of the original issue, its analyzed impact (on epics, artifacts, MVP scope), and the rationale for the chosen path forward.
   - **Specific Proposed Edits:** For each affected artifact, clearly show or describe the exact changes (e.g., "Change Story X.Y from: [old text] To: [new text]", "Add new Acceptance Criterion to Story A.B: [new AC]", "Update Section 3.2 of Architecture Document as follows: [new/modified text or diagram description]").
@@ -68,6 +65,6 @@
 ## Output Deliverables
 
 - **Primary:** A "Sprint Change Proposal" document (in markdown format). This document will contain:
-  - A summary of the `change-checklist` analysis (issue, impact, rationale for the chosen path).
+  - A summary of the change-checklist analysis (issue, impact, rationale for the chosen path).
   - Specific, clearly drafted proposed edits for all affected project artifacts.
-- **Implicit:** An annotated `change-checklist` (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
+- **Implicit:** An annotated change-checklist (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.

bmad-core/tasks/create-brownfield-story.md

@@ -22,20 +22,7 @@ Create detailed, implementation-ready stories for brownfield projects where trad
 
 ## Task Execution Instructions
 
-### 0. Check Workflow Plan and Documentation Context
-
-[[LLM: Check for workflow plan first, then available documentation]]
-
-#### 0.1 Check Workflow Plan
-
-- Load core-config.yaml and check if `workflow.trackProgress: true`
-- If yes, check for active plan at `workflow.planFile`
-- If plan exists:
-  - Verify story creation aligns with current plan step
-  - If out of sequence, warn user (enforce based on config)
-  - Note which step this story creation corresponds to
-
-#### 0.2 Determine Documentation Context
+### 0. Documentation Context
 
 Check for available documentation in this order:
 
@@ -68,7 +55,7 @@ Based on available documentation:
 
 #### 1.2 Gather Essential Context
 
-[[LLM: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.]]
+CRITICAL: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.
 
 **Required Information Checklist:**
 
@@ -78,21 +65,7 @@ Based on available documentation:
 - [ ] What technical constraints exist?
 - [ ] Are there any "gotchas" or workarounds to know about?
 
-If any required information is missing, ask the user:
-
-```
-I need additional context for this brownfield story:
-
-Missing Information:
-- [List specific missing items]
-
-Please provide:
-1. [Specific question about integration]
-2. [Specific question about patterns]
-3. [Specific question about constraints]
-
-Or point me to documentation that contains this information.
-```
+If any required information is missing, list the missing information and ask the user to provide it.
 
 ### 2. Extract Technical Context from Available Sources
 
@@ -117,8 +90,6 @@ If using brownfield PRD:
 
 #### 2.3 From User Documentation
 
-[[LLM: When working with non-BMad documentation, actively extract and organize the information into categories the Dev agent will need]]
-
 Ask the user to help identify:
 
 - Relevant technical specifications
@@ -138,12 +109,13 @@ Start with the story template, filling in what's known:
 ## Status: Draft
 
 ## Story
+
 As a {{user_type}},
 I want {{enhancement_capability}},
 so that {{value_delivered}}.
 
 ## Context Source
-[[LLM: Document where story requirements came from]]
+
 - Source Document: {{document name/type}}
 - Enhancement Type: {{single feature/bug fix/integration/etc}}
 - Existing System Impact: {{brief assessment}}
@@ -151,7 +123,7 @@ so that {{value_delivered}}.
 
 #### 3.2 Develop Acceptance Criteria
 
-[[LLM: For brownfield, ALWAYS include criteria about maintaining existing functionality]]
+Critical: For brownfield, ALWAYS include criteria about maintaining existing functionality
 
 Standard structure:
 
@@ -163,7 +135,7 @@ Standard structure:
 
 #### 3.3 Gather Technical Guidance
 
-[[LLM: This is where you'll need to be interactive with the user if information is missing]]
+Critical: This is where you'll need to be interactive with the user if information is missing
 
 Create Dev Technical Guidance section with available information:
 
@@ -180,22 +152,8 @@ Create Dev Technical Guidance section with available information:
 [From documentation or user input]
 
 ### Missing Information
-[[LLM: List anything you couldn't find that dev will need]]
-- [ ] {{missing item 1}}
-- [ ] {{missing item 2}}
-```
 
-If critical information is missing, pause and ask:
-
-```
-To complete the technical guidance for this story, I need:
-
-1. **{{Missing Category}}**: 
-   - Specifically: {{what you need to know}}
-   - Why needed: {{how it impacts implementation}}
-   
-Can you provide this information or point me to relevant code/docs?
-```
+Critical: List anything you couldn't find that dev will need and ask for the missing information
 
 ### 4. Task Generation with Safety Checks
 
@@ -236,7 +194,7 @@ Example task structure for brownfield:
 
 ### 5. Risk Assessment and Mitigation
 
-[[LLM: CRITICAL for brownfield - always include risk assessment]]
+CRITICAL: for brownfield - always include risk assessment
 
 Add section for brownfield-specific risks:
 
@@ -324,15 +282,6 @@ Next Steps:
 4. Dev agent can then implement with safety checks
 ```
 
-### 9. Update Workflow Plan (if applicable)
-
-[[LLM: After successful story creation]]
-
-- If workflow plan tracking is enabled and story was created successfully:
-  - Call update-workflow-plan task to mark step complete
-  - Parameters: task: create-brownfield-story, step_id: {from plan check}, status: complete
-  - If plan shows next recommended step, include it in handoff message
-
 ## Success Criteria
 
 The brownfield story creation is successful when:
@@ -348,7 +297,7 @@ The brownfield story creation is successful when:
 ## Important Notes
 
 - This task is specifically for brownfield projects with non-standard documentation
-- Always prioritize existing system safety over new features
+- Always prioritize existing system stability over new features
 - When in doubt, add exploration and verification tasks
 - It's better to ask the user for clarification than make assumptions
 - Each story should be self-contained for the dev agent

bmad-core/tasks/create-deep-research-prompt.md

@@ -14,7 +14,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -77,15 +77,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -118,11 +116,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -131,7 +129,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -147,8 +145,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -165,8 +161,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -183,8 +177,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -253,8 +245,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -276,8 +266,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities

bmad-core/tasks/create-next-story.md

@@ -8,10 +8,9 @@ To identify the next logical story based on project progress and epic definition
 
 ### 0. Load Core Configuration and Check Workflow
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `{root}/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 
@@ -103,12 +102,11 @@ ALWAYS cite source documents: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft" and save the story file
-- If `workflow.trackProgress: true` and `workflow.updateOnCompletion: true`, call update-workflow-plan task to mark story creation step complete
-- Execute `tasks/execute-checklist` `checklists/story-draft-checklist`
+- Execute `{root}/tasks/execute-checklist` `{root}/checklists/story-draft-checklist`
 - Provide summary to user including:
   - Story created: `{devStoryLocation}/{epicNum}.{storyNum}.story.md`
   - Status: Draft
   - Key technical components included from architecture docs
   - Any deviations or conflicts noted between epic and architecture
   - Checklist Results
-  - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `validate-next-story`
+  - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `{root}/tasks/validate-next-story`

bmad-core/tasks/create-workflow-plan.md

@@ -1,289 +0,0 @@
-# Create Workflow Plan Task
-
-## Purpose
-
-Guide users through workflow selection and create a detailed plan document that outlines the selected workflow steps, decision points, and expected outputs. This task helps users understand what will happen before starting a complex workflow and provides a checklist to track progress.
-
-## Task Instructions
-
-### 1. Understand User's Goal
-
-[[LLM: Start with discovery questions to understand what the user wants to accomplish]]
-
-Ask the user:
-
-1. **Project Type**:
-   - Are you starting a new project (greenfield) or enhancing an existing one (brownfield)?
-   - What type of application? (web app, service/API, UI only, full-stack)
-
-2. **For Greenfield**:
-   - Do you need a quick prototype or production-ready application?
-   - Will this have a UI component?
-   - Single service or multiple services?
-
-3. **For Brownfield**:
-   - What's the scope of the enhancement?
-     - Single bug fix or small feature (few hours)
-     - Small enhancement (1-3 stories)
-     - Major feature requiring coordination
-     - Architectural changes or modernization
-   - Do you have existing documentation?
-   - Are you following existing patterns or introducing new ones?
-
-### 2. Recommend Appropriate Workflow
-
-Based on the answers, recommend:
-
-**Greenfield Options:**
-
-- `greenfield-fullstack` - Complete web application
-- `greenfield-service` - Backend API/service only
-- `greenfield-ui` - Frontend only
-
-**Brownfield Options:**
-
-- `brownfield-create-story` - Single small change
-- `brownfield-create-epic` - Small feature (1-3 stories)
-- `brownfield-fullstack` - Major enhancement
-
-**Simplified Option:**
-
-- For users unsure or wanting flexibility, suggest starting with individual agent tasks
-
-### 3. Explain Selected Workflow
-
-[[LLM: Once workflow is selected, provide clear explanation]]
-
-For the selected workflow, explain:
-
-1. **Overview**: What this workflow accomplishes
-2. **Duration**: Estimated time for planning phase
-3. **Outputs**: What documents will be created
-4. **Decision Points**: Where user input will be needed
-5. **Requirements**: What information should be ready
-
-### 4. Create Workflow Plan Document
-
-[[LLM: Generate a comprehensive plan document with the following structure]]
-
-```markdown
-# Workflow Plan: {{Workflow Name}}
-
-<!-- WORKFLOW-PLAN-META
-workflow-id: {{workflow-id}}
-status: active
-created: {{ISO-8601 timestamp}}
-updated: {{ISO-8601 timestamp}}
-version: 1.0
--->
-
-**Created Date**: {{current date}}
-**Project**: {{project name}}
-**Type**: {{greenfield/brownfield}}
-**Status**: Active
-**Estimated Planning Duration**: {{time estimate}}
-
-## Objective
-
-{{Clear description of what will be accomplished}}
-
-## Selected Workflow
-
-**Workflow**: `{{workflow-id}}`
-**Reason**: {{Why this workflow fits the user's needs}}
-
-## Workflow Steps
-
-### Planning Phase
-
-- [ ] Step 1: {{step name}} <!-- step-id: 1.1, agent: {{agent}}, task: {{task}} -->
-  - **Agent**: {{agent name}}
-  - **Action**: {{what happens}}
-  - **Output**: {{what's created}}
-  - **User Input**: {{if any}}
-
-- [ ] Step 2: {{step name}} <!-- step-id: 1.2, agent: {{agent}}, task: {{task}} -->
-  - **Agent**: {{agent name}}
-  - **Action**: {{what happens}}
-  - **Output**: {{what's created}}
-  - **Decision Point**: {{if any}} <!-- decision-id: D1 -->
-
-{{Continue for all planning steps}}
-
-### Development Phase (IDE)
-
-- [ ] Document Sharding <!-- step-id: 2.1, agent: po, task: shard-doc -->
-  - Prepare documents for story creation
-
-- [ ] Story Development Cycle <!-- step-id: 2.2, repeats: true -->
-  - [ ] Create story (SM agent) <!-- step-id: 2.2.1, agent: sm, task: create-next-story -->
-  - [ ] Review story (optional) <!-- step-id: 2.2.2, agent: analyst, optional: true -->
-  - [ ] Implement story (Dev agent) <!-- step-id: 2.2.3, agent: dev -->
-  - [ ] QA review (optional) <!-- step-id: 2.2.4, agent: qa, optional: true -->
-  - [ ] Repeat for all stories
-
-- [ ] Epic Retrospective (optional) <!-- step-id: 2.3, agent: po, optional: true -->
-
-## Key Decision Points
-
-1. **{{Decision Name}}** (Step {{n}}): <!-- decision-id: D1, status: pending -->
-   - Trigger: {{what causes this decision}}
-   - Options: {{available choices}}
-   - Impact: {{how it affects the workflow}}
-   - Decision Made: _Pending_
-
-{{List all decision points}}
-
-## Expected Outputs
-
-### Planning Documents
-- [ ] {{document 1}} - {{description}}
-- [ ] {{document 2}} - {{description}}
-{{etc...}}
-
-### Development Artifacts
-- [ ] Stories in `docs/stories/`
-- [ ] Implementation code
-- [ ] Tests
-- [ ] Updated documentation
-
-## Prerequisites Checklist
-
-Before starting this workflow, ensure you have:
-
-- [ ] {{prerequisite 1}}
-- [ ] {{prerequisite 2}}
-- [ ] {{prerequisite 3}}
-{{etc...}}
-
-## Customization Options
-
-Based on your project needs, you may:
-- Skip {{optional step}} if {{condition}}
-- Add {{additional step}} if {{condition}}
-- Choose {{alternative}} instead of {{default}}
-
-## Risk Considerations
-
-{{For brownfield only}}
-- Integration complexity: {{assessment}}
-- Rollback strategy: {{approach}}
-- Testing requirements: {{special needs}}
-
-## Next Steps
-
-1. Review this plan and confirm it matches your expectations
-2. Gather any missing prerequisites
-3. Start workflow with: `*task workflow {{workflow-id}}`
-4. Or begin with first agent: `@{{first-agent}}`
-
-## Notes
-
-{{Any additional context or warnings}}
-
----
-*This plan can be updated as you progress through the workflow. Check off completed items to track progress.*
-```
-
-### 5. Save and Present Plan
-
-1. Save the plan as `docs/workflow-plan.md`
-2. Inform user: "Workflow plan created at docs/workflow-plan.md"
-3. Offer options:
-   - Review the plan together
-   - Start the workflow now
-   - Gather prerequisites first
-   - Modify the plan
-
-### 6. Plan Variations
-
-[[LLM: Adjust plan detail based on workflow complexity]]
-
-**For Simple Workflows** (create-story, create-epic):
-
-- Simpler checklist format
-- Focus on immediate next steps
-- Less detailed explanations
-
-**For Complex Workflows** (full greenfield/brownfield):
-
-- Detailed step breakdowns
-- All decision points documented
-- Comprehensive output descriptions
-- Risk mitigation sections
-
-**For Brownfield Workflows**:
-
-- Include existing system impact analysis
-- Document integration checkpoints
-- Add rollback considerations
-- Note documentation dependencies
-
-### 7. Interactive Planning Mode
-
-[[LLM: If user wants to customize the workflow]]
-
-If user wants to modify the standard workflow:
-
-1. Present workflow steps as options
-2. Allow skipping optional steps
-3. Let user reorder certain steps
-4. Document customizations in plan
-5. Warn about dependencies if steps are skipped
-
-### 8. Execution Guidance
-
-After plan is created, provide clear guidance:
-
-```text
-Your workflow plan is ready! Here's how to proceed:
-
-1. **Review the plan**: Check that all steps align with your goals
-2. **Gather prerequisites**: Use the checklist to ensure you're ready
-3. **Start execution**:
-   - Full workflow: `*task workflow {{workflow-id}}`
-   - Step by step: Start with `@{{first-agent}}`
-4. **Track progress**: Check off steps in the plan as completed
-
-Would you like to:
-a) Review the plan together
-b) Start the workflow now
-c) Gather prerequisites first
-d) Modify the plan
-```
-
-## Success Criteria
-
-The workflow plan is successful when:
-
-1. User clearly understands what will happen
-2. All decision points are documented
-3. Prerequisites are identified
-4. Expected outputs are clear
-5. User feels confident to proceed
-6. Plan serves as useful progress tracker
-
-## Integration with BMad Master and Orchestrator
-
-When used by BMad Master or BMad Orchestrator, this task should:
-
-1. Be offered when user asks about workflows
-2. Be suggested before starting complex workflows
-3. Create a plan that the agent can reference during execution
-4. Allow the agent to track progress against the plan
-
-## Example Usage
-
-```text
-User: "I need to add a payment system to my existing app"
-
-BMad Orchestrator: "Let me help you create a workflow plan for that enhancement. I'll ask a few questions to recommend the best approach..."
-
-[Runs through discovery questions]
-
-BMad Orchestrator: "Based on your answers, I recommend the brownfield-fullstack workflow. Let me create a detailed plan for you..."
-
-[Creates and saves plan]
-
-BMad Orchestrator: "I've created a workflow plan at docs/workflow-plan.md. This shows all the steps we'll go through, what documents will be created, and where you'll need to make decisions. Would you like to review it together?"
-```

bmad-core/tasks/doc-migration-task.md

@@ -1,143 +0,0 @@
-# Document Migration Task
-
-## Purpose
-
-Simple document migration that cleans up heading formats and adds epic structure for PRDs.
-
-## Task Requirements
-
-1. **Input**: User specifies the document to migrate (e.g., `docs/prd.md`)
-2. **Detection**: Automatically determine if it's a PRD or other document type
-3. **Migration**: Apply appropriate transformations
-4. **Backup**: Create backup with `.bak` extension
-
-## Migration Rules
-
-### For PRDs
-
-- Find all level 3 headings that appear to be epics
-- Add a level 2 heading "## Epic #" (incrementing number) before each epic
-- Also apply the heading cleanup rules below
-
-### For All Documents
-
-- Find all level 2 headings (`## ...`)
-- Remove leading numbers and symbols
-- Keep only alphabetic characters and spaces
-- **CRITICAL**: Do not lose any information - preserve all content under appropriate headings
-- Examples:
-  - `## 1. Foo & Bar` → `## Foo Bar`
-  - `## 2.1 Technical Overview` → `## Technical Overview`
-  - `## 3) User Experience` → `## User Experience`
-
-### For Architecture Documents
-
-- **PRIMARY GOAL**: Align level 2 headings to match template level 2 titles exactly
-- **PRESERVE EVERYTHING**: Do not lose any information during migration
-- Map existing content to the closest matching template section
-- If content doesn't fit template sections, create appropriate level 3 subsections
-
-## Detection Logic
-
-A document is considered a PRD if:
-
-- Filename contains "prd" (case insensitive)
-- OR main title contains "Product Requirements" or "PRD"
-- OR contains sections like "User Stories", "Functional Requirements", "Acceptance Criteria"
-
-## Implementation Steps
-
-1. **Backup Original**: Copy `filename.md` to `filename.md.bak`
-2. **Detect Type**: Check if document is a PRD
-3. **Process Headings**:
-   - Clean all level 2 headings
-   - If PRD: Add epic structure before level 3 headings that look like epics
-4. **Write Result**: Overwrite original file with migrated content
-
-## Epic Detection for PRDs
-
-Level 3 headings are treated as epics if they:
-
-- Describe features or functionality
-- Are substantial sections (not just "Overview" or "Notes")
-- Common epic patterns: "User Management", "Payment Processing", "Reporting Dashboard"
-
-The epic numbering starts at 1 and increments for each epic found.
-
-## Example
-
-### Before (PRD):
-
-```markdown
-# Product Requirements Document
-
-## 1. Executive Summary
-
-Content here...
-
-## 2.1 Functional Requirements & Specs
-
-Content here...
-
-### User Management System
-
-Epic content...
-
-### Payment Processing
-
-Epic content...
-
-## 3) Success Metrics
-
-Content here...
-
-```
-
-### After (PRD):
-
-```markdown
-# Product Requirements Document
-
-## Executive Summary
-Content here...
-
-## Functional Requirements Specs
-Content here...
-
-## Epic 1
-### User Management System
-Epic content...
-
-## Epic 2
-### Payment Processing
-Epic content...
-
-## Success Metrics
-Content here...
-
-```
-
-### Before (Non-PRD):
-
-```markdown
-# Architecture Document
-
-## 1. System Overview
-Content...
-
-## 2.1 Technical Stack & Tools
-Content...
-```
-
-### After (Non-PRD):
-
-```markdown
-# Architecture Document
-
-## System Overview
-Content...
-
-## Technical Stack Tools
-Content...
-
-```

bmad-core/tasks/document-project.md

@@ -8,9 +8,9 @@ Generate comprehensive documentation for existing projects optimized for AI deve
 
 ### 1. Initial Project Analysis
 
-[[LLM: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
+**CRITICAL:** First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
 
-**IF PRD EXISTS**: 
+**IF PRD EXISTS**:
 
 - Review the PRD to understand what enhancement/feature is planned
 - Identify which modules, services, or areas will be affected
@@ -56,11 +56,10 @@ Ask the user these elicitation questions to better understand their needs:
 - Are there any existing documentation standards or formats you prefer?
 - What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
 - Is there a specific feature or enhancement you're planning? (This helps focus documentation)
-  ]]
 
 ### 2. Deep Codebase Analysis
 
-[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
+CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase:
 
 1. **Explore Key Areas**:
    - Entry points (main files, index files, app initializers)
@@ -83,13 +82,14 @@ Ask the user these elicitation questions to better understand their needs:
    - Document workarounds and technical debt
    - Note areas that differ from standard patterns
 
-**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
+**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement
 
 ### 3. Core Documentation Generation
 
 [[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
 
 **CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
+
 - Technical debt and workarounds
 - Inconsistent patterns between different parts
 - Legacy code that can't be changed
@@ -101,13 +101,16 @@ Ask the user these elicitation questions to better understand their needs:
 # [Project Name] Brownfield Architecture Document
 
 ## Introduction
+
 This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
 
 ### Document Scope
+
 [If PRD provided: "Focused on areas relevant to: {enhancement description}"]
 [If no PRD: "Comprehensive documentation of entire system"]
 
 ### Change Log
+
 | Date | Version | Description | Author |
 |------|---------|-------------|--------|
 | [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
@@ -115,6 +118,7 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 ## Quick Reference - Key Files and Entry Points
 
 ### Critical Files for Understanding the System
+
 - **Main Entry**: `src/index.js` (or actual entry point)
 - **Configuration**: `config/app.config.js`, `.env.example`
 - **Core Business Logic**: `src/services/`, `src/domain/`
@@ -123,22 +127,25 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 - **Key Algorithms**: [List specific files with complex logic]
 
 ### If PRD Provided - Enhancement Impact Areas
+
 [Highlight which files/modules will be affected by the planned enhancement]
 
 ## High Level Architecture
 
 ### Technical Summary
-[Real assessment of architecture - mention if it's well-structured or has issues]
 
 ### Actual Tech Stack (from package.json/requirements.txt)
+
 | Category | Technology | Version | Notes |
 |----------|------------|---------|--------|
 | Runtime | Node.js | 16.x | [Any constraints] |
 | Framework | Express | 4.18.2 | [Custom middleware?] |
 | Database | PostgreSQL | 13 | [Connection pooling setup] |
-| [etc...] |
+
+etc...
 
 ### Repository Structure Reality Check
+
 - Type: [Monorepo/Polyrepo/Hybrid]
 - Package Manager: [npm/yarn/pnpm]
 - Notable: [Any unusual structure decisions]
@@ -146,7 +153,8 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 ## Source Tree and Module Organization
 
 ### Project Structure (Actual)
-```
+
+```text
 project-root/
 ├── src/
 │   ├── controllers/     # HTTP request handlers
@@ -160,6 +168,7 @@ project-root/
 ```
 
 ### Key Modules and Their Purpose
+
 - **User Management**: `src/services/userService.js` - Handles all user operations
 - **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
 - **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
@@ -168,12 +177,14 @@ project-root/
 ## Data Models and APIs
 
 ### Data Models
+
 Instead of duplicating, reference actual model files:
 - **User Model**: See `src/models/User.js`
 - **Order Model**: See `src/models/Order.js`
 - **Related Types**: TypeScript definitions in `src/types/`
 
 ### API Specifications
+
 - **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
 - **Postman Collection**: `docs/api/postman-collection.json`
 - **Manual Endpoints**: [List any undocumented endpoints discovered]
@@ -181,12 +192,14 @@ Instead of duplicating, reference actual model files:
 ## Technical Debt and Known Issues
 
 ### Critical Technical Debt
+
 1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
 2. **User Service**: Different pattern than other services, uses callbacks instead of promises
 3. **Database Migrations**: Manually tracked, no proper migration tool
 4. **[Other significant debt]**
 
 ### Workarounds and Gotchas
+
 - **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
 - **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
 - **[Other workarounds developers need to know]**
@@ -194,13 +207,16 @@ Instead of duplicating, reference actual model files:
 ## Integration Points and External Dependencies
 
 ### External Services
+
 | Service | Purpose | Integration Type | Key Files |
 |---------|---------|------------------|-----------|
 | Stripe | Payments | REST API | `src/integrations/stripe/` |
 | SendGrid | Emails | SDK | `src/services/emailService.js` |
-| [etc...] |
+
+etc...
 
 ### Internal Integration Points
+
 - **Frontend Communication**: REST API on port 3000, expects specific headers
 - **Background Jobs**: Redis queue, see `src/workers/`
 - **[Other integrations]**
@@ -208,11 +224,13 @@ Instead of duplicating, reference actual model files:
 ## Development and Deployment
 
 ### Local Development Setup
+
 1. Actual steps that work (not ideal steps)
 2. Known issues with setup
 3. Required environment variables (see `.env.example`)
 
 ### Build and Deployment Process
+
 - **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
 - **Deployment**: Manual deployment via `scripts/deploy.sh`
 - **Environments**: Dev, Staging, Prod (see `config/environments/`)
@@ -220,12 +238,14 @@ Instead of duplicating, reference actual model files:
 ## Testing Reality
 
 ### Current Test Coverage
+
 - Unit Tests: 60% coverage (Jest)
 - Integration Tests: Minimal, in `tests/integration/`
 - E2E Tests: None
 - Manual Testing: Primary QA method
 
 ### Running Tests
+
 ```bash
 npm test           # Runs unit tests
 npm run test:integration  # Runs integration tests (requires local DB)
@@ -234,6 +254,7 @@ npm run test:integration  # Runs integration tests (requires local DB)
 ## If Enhancement PRD Provided - Impact Analysis
 
 ### Files That Will Need Modification
+
 Based on the enhancement requirements, these files will be affected:
 - `src/services/userService.js` - Add new user fields
 - `src/models/User.js` - Update schema
@@ -241,11 +262,13 @@ Based on the enhancement requirements, these files will be affected:
 - [etc...]
 
 ### New Files/Modules Needed
+
 - `src/services/newFeatureService.js` - New business logic
 - `src/models/NewFeature.js` - New data model
 - [etc...]
 
 ### Integration Considerations
+
 - Will need to integrate with existing auth middleware
 - Must follow existing response format in `src/utils/responseFormatter.js`
 - [Other integration points]
@@ -253,6 +276,7 @@ Based on the enhancement requirements, these files will be affected:
 ## Appendix - Useful Commands and Scripts
 
 ### Frequently Used Commands
+
 ```bash
 npm run dev         # Start development server
 npm run build       # Production build
@@ -261,14 +285,13 @@ npm run seed        # Seed test data
 ```
 
 ### Debugging and Troubleshooting
+
 - **Logs**: Check `logs/app.log` for application logs
 - **Debug Mode**: Set `DEBUG=app:*` for verbose logging
 - **Common Issues**: See `docs/troubleshooting.md`]]
 
 ### 4. Document Delivery
 
-[[LLM: After generating the complete architecture document:
-
 1. **In Web UI (Gemini, ChatGPT, Claude)**:
    - Present the entire document in one response (or multiple if too long)
    - Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
@@ -280,6 +303,7 @@ npm run seed        # Seed test data
    - Can be sharded later using PO agent if desired
 
 The document should be comprehensive enough that future agents can understand:
+
 - The actual state of the system (not idealized)
 - Where to find key files and logic
 - What technical debt exists
@@ -288,7 +312,7 @@ The document should be comprehensive enough that future agents can understand:
 
 ### 5. Quality Assurance
 
-[[LLM: Before finalizing the document:
+CRITICAL: Before finalizing the document:
 
 1. **Accuracy Check**: Verify all technical details match the actual codebase
 2. **Completeness Review**: Ensure all major system components are documented
@@ -296,7 +320,7 @@ The document should be comprehensive enough that future agents can understand:
 4. **Clarity Assessment**: Check that explanations are clear for AI agents
 5. **Navigation**: Ensure document has clear section structure for easy reference
 
-Apply the advanced elicitation task after major sections to refine based on user feedback.]]
+Apply the advanced elicitation task after major sections to refine based on user feedback.
 
 ## Success Criteria
 

bmad-core/tasks/facilitate-brainstorming-session.md

@@ -1,6 +1,6 @@
 ---
 docOutputLocation: docs/brainstorming-session-results.md
-template: brainstorming-output-tmpl
+template: "{root}/templates/brainstorming-output-tmpl.md"
 ---
 
 # Facilitate Brainstorming Session Task

bmad-core/tasks/generate-ai-frontend-prompt.md

@@ -6,7 +6,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi
 
 ## Inputs
 
-- Completed UI/UX Specification (`front-end-spec`)
+- Completed UI/UX Specification (`front-end-spec.md`)
 - Completed Frontend Architecture Document (`front-end-architecture`) or a full stack combined architecture such as `architecture.md`
 - Main System Architecture Document (`architecture` - for API contracts and tech stack to give further context)
 

bmad-core/tasks/kb-mode-interaction.md

@@ -1,6 +1,7 @@
 # KB Mode Interaction Task
 
 ## Purpose
+
 Provide a user-friendly interface to the BMad knowledge base without overwhelming users with information upfront.
 
 ## Instructions
@@ -8,11 +9,11 @@ Provide a user-friendly interface to the BMad knowledge base without overwhelmin
 When entering KB mode (*kb-mode), follow these steps:
 
 ### 1. Welcome and Guide
-Announce entering KB mode with a brief, friendly introduction:
 
-"I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method."
+Announce entering KB mode with a brief, friendly introduction.
 
 ### 2. Present Topic Areas
+
 Offer a concise list of main topic areas the user might want to explore:
 
 **What would you like to know more about?**
@@ -29,19 +30,23 @@ Offer a concise list of main topic areas the user might want to explore:
 Or ask me about anything else related to BMad-Method!
 
 ### 3. Respond Contextually
+
 - Wait for user's specific question or topic selection
 - Provide focused, relevant information from the knowledge base
 - Offer to dive deeper or explore related topics
 - Keep responses concise unless user asks for detailed explanations
 
 ### 4. Interactive Exploration
+
 - After answering, suggest related topics they might find helpful
 - Maintain conversational flow rather than data dumping
 - Use examples when appropriate
 - Reference specific documentation sections when relevant
 
 ### 5. Exit Gracefully
+
 When user is done or wants to exit KB mode:
+
 - Summarize key points discussed if helpful
 - Remind them they can return to KB mode anytime with *kb-mode
 - Suggest next steps based on what was discussed
@@ -67,4 +72,4 @@ Or ask me about anything else related to BMad-Method!
 
 **User**: Tell me about workflows
 
-**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]

bmad-core/tasks/review-story.md

@@ -1,8 +1,6 @@
 # review-story
 
-When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
-
-[[LLM: QA Agent executing review-story task as Senior Developer]]
+When a developer agent marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
 
 ## Prerequisites
 
@@ -131,6 +129,7 @@ After review and any refactoring, append your results to the story file in the Q
 ## Blocking Conditions
 
 Stop the review and request clarification if:
+
 - Story file is incomplete or missing critical sections
 - File List is empty or clearly incomplete
 - No tests exist when they were required
@@ -140,6 +139,7 @@ Stop the review and request clarification if:
 ## Completion
 
 After review:
+
 1. If all items are checked and approved: Update story status to "Done"
 2. If unchecked items remain: Keep status as "Review" for dev to address
 3. Always provide constructive feedback and explanations for learning

bmad-core/tasks/shard-doc.md

@@ -8,20 +8,20 @@
 
 ## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+[[LLM: First, check if markdownExploder is set to true in {root}/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
 
 If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
 
 If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
 
 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in bmad-core/core-config.yaml
+2. Or set markdownExploder to false in {root}/core-config.yaml
 
 **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
 
 If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
 
-1. Set markdownExploder to true in bmad-core/core-config.yaml
+1. Set markdownExploder to true in {root}/core-config.yaml
 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
 
 I will now proceed with the manual sharding process."
@@ -61,8 +61,6 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 ## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
 
-[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
-
 ### Task Instructions
 
 1. Identify Document and Target Location
@@ -73,7 +71,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 2. Parse and Extract Sections
 
-[[LLM: When sharding the document:
+CRITICAL AEGNT SHARDING RULES:
 
 1. Read the entire document content
 2. Identify all level 2 sections (## headings)
@@ -134,8 +132,6 @@ Create an `index.md` file in the sharded folder that:
 
 ### 5. Preserve Special Content
 
-[[LLM: Pay special attention to preserving:
-
 1. **Code blocks**: Must capture complete blocks including:
 
    ```language
@@ -157,7 +153,7 @@ Create an `index.md` file in the sharded folder that:
 
 6. **Links and references**: Keep all markdown links intact
 
-7. **Template markup**: If documents contain {{placeholders}} or [[LLM instructions]], preserve exactly]]
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
 
 ### 6. Validation
 

bmad-core/tasks/update-workflow-plan.md

@@ -1,248 +0,0 @@
-# Update Workflow Plan Task
-
-## Purpose
-
-Update the status of steps in an active workflow plan, mark completions, add notes about deviations, and maintain an accurate record of workflow progress. This task can be called directly by users or automatically by other tasks upon completion.
-
-## Task Instructions
-
-### 0. Load Plan Configuration
-
-[[LLM: First load core-config.yaml to get plan settings]]
-
-Check workflow configuration:
-
-- `workflow.planFile` - Location of the plan (default: docs/workflow-plan.md)
-- `workflow.trackProgress` - Whether tracking is enabled
-- `workflow.updateOnCompletion` - Whether to auto-update on task completion
-
-If tracking is disabled, inform user and exit.
-
-### 1. Verify Plan Exists
-
-[[LLM: Check if workflow plan exists at configured location]]
-
-If no plan exists:
-
-```
-No active workflow plan found at {location}.
-Would you like to create one? Use *plan command.
-```
-
-### 2. Determine Update Type
-
-[[LLM: Ask user what type of update they want to make]]
-
-Present options:
-
-```
-What would you like to update in the workflow plan?
-
-1. Mark step as complete
-2. Update current step
-3. Add deviation note
-4. Mark decision point resolution
-5. Update overall status
-6. View current plan status only
-
-Please select an option (1-6):
-```
-
-### 3. Parse Current Plan
-
-[[LLM: Read and parse the plan to understand current state]]
-
-Extract:
-
-- All steps with their checkbox status
-- Step IDs from comments (if present)
-- Current completion percentage
-- Any existing deviation notes
-- Decision points and their status
-
-### 4. Execute Updates
-
-#### 4.1 Mark Step Complete
-
-If user selected option 1:
-
-1. Show numbered list of incomplete steps
-2. Ask which step to mark complete
-3. Update the checkbox from `[ ]` to `[x]`
-4. Add completion timestamp: `<!-- completed: YYYY-MM-DD HH:MM -->`
-5. If this was the current step, identify next step
-
-#### 4.2 Update Current Step
-
-If user selected option 2:
-
-1. Show all steps with current status
-2. Ask which step is now current
-3. Add/move `<!-- current-step -->` marker
-4. Optionally add note about why sequence changed
-
-#### 4.3 Add Deviation Note
-
-If user selected option 3:
-
-1. Ask for deviation description
-2. Ask which step this relates to (or general)
-3. Insert note in appropriate location:
-
-```markdown
-> **Deviation Note** (YYYY-MM-DD): {user_note}
-> Related to: Step X.Y or General workflow
-```
-
-#### 4.4 Mark Decision Resolution
-
-If user selected option 4:
-
-1. Show pending decision points
-2. Ask which decision was made
-3. Record the decision and chosen path
-4. Update related steps based on decision
-
-#### 4.5 Update Overall Status
-
-If user selected option 5:
-
-1. Show current overall status
-2. Provide options:
-   - Active (continuing with plan)
-   - Paused (temporarily stopped)
-   - Abandoned (no longer following)
-   - Complete (all steps done)
-3. Update plan header with new status
-
-### 5. Automatic Updates (When Called by Tasks)
-
-[[LLM: When called automatically by another task]]
-
-If called with parameters:
-
-```
-task: {task_name}
-step_id: {step_identifier}
-status: complete|skipped|failed
-note: {optional_note}
-```
-
-Automatically:
-
-1. Find the corresponding step
-2. Update its status
-3. Add completion metadata
-4. Add note if provided
-5. Calculate new progress percentage
-
-### 6. Generate Update Summary
-
-After updates, show summary:
-
-```
-✅ Workflow Plan Updated
-
-Changes made:
-- {change_1}
-- {change_2}
-
-New Status:
-- Progress: {X}% complete ({completed}/{total} steps)
-- Current Step: {current_step}
-- Next Recommended: {next_step}
-
-Plan location: {file_path}
-```
-
-### 7. Integration with Other Tasks
-
-[[LLM: How other tasks should call this]]
-
-Other tasks can integrate by:
-
-1. **After Task Completion**:
-
-```
-At end of task execution:
-- Check if task corresponds to a plan step
-- If yes, call update-workflow-plan with:
-  - task: {current_task_name}
-  - step_id: {matching_step}
-  - status: complete
-```
-
-2. **On Task Failure**:
-
-```
-If task fails:
-- Call update-workflow-plan with:
-  - task: {current_task_name}
-  - status: failed
-  - note: {failure_reason}
-```
-
-### 8. Plan Status Display
-
-[[LLM: When user selects view status only]]
-
-Display comprehensive status:
-
-```markdown
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Status: {Active|Paused|Complete}
-Progress: {X}% complete ({completed}/{total} steps)
-Last Updated: {timestamp}
-
-✅ Completed Steps:
-- [x] Step 1.1: {description} (completed: {date})
-- [x] Step 1.2: {description} (completed: {date})
-
-🔄 Current Step:
-- [ ] Step 2.1: {description} <!-- current-step -->
-  Agent: {agent_name}
-  Task: {task_name}
-
-📌 Upcoming Steps:
-- [ ] Step 2.2: {description}
-- [ ] Step 3.1: {description}
-
-⚠️ Deviations/Notes:
-{any_deviation_notes}
-
-📊 Decision Points:
-- Decision 1: {status} - {choice_made}
-- Decision 2: Pending
-
-💡 Next Action:
-Based on the plan, you should {recommended_action}
-```
-
-## Success Criteria
-
-The update is successful when:
-
-1. Plan accurately reflects current workflow state
-2. All updates are clearly timestamped
-3. Deviations are documented with reasons
-4. Progress calculation is correct
-5. Next steps are clear to user
-6. Plan remains readable and well-formatted
-
-## Error Handling
-
-- **Plan file not found**: Offer to create new plan
-- **Malformed plan**: Attempt basic updates, warn user
-- **Write permission error**: Show changes that would be made
-- **Step not found**: Show available steps, ask for clarification
-- **Concurrent updates**: Implement simple locking or warn about conflicts
-
-## Notes
-
-- Always preserve plan history (don't delete old information)
-- Keep updates atomic to prevent corruption
-- Consider creating backup before major updates
-- Updates should enhance, not complicate, the workflow experience
-- If plan becomes too cluttered, suggest creating fresh plan for next phase

bmad-core/tasks/validate-next-story.md

@@ -8,7 +8,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:

bmad-core/templates/architecture-tmpl.yaml

@@ -629,7 +629,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -640,19 +639,12 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow

bmad-core/templates/prd-tmpl.yaml

@@ -194,9 +194,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.

bmad-core/utils/plan-management.md

@@ -1,219 +0,0 @@
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search

bmad-core/workflows/brownfield-fullstack.yaml

@@ -182,7 +182,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/brownfield-service.yaml

@@ -128,7 +128,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/brownfield-ui.yaml

@@ -135,7 +135,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/greenfield-fullstack.yaml

@@ -160,7 +160,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

bmad-core/workflows/greenfield-ui.yaml

@@ -155,7 +155,7 @@ workflow:
         All stories implemented and reviewed!
         Project development phase complete.
         
-        Reference: data#bmad-kb:IDE Development Workflow
+        Reference: {root}/data/bmad-kb.md#IDE Development Workflow
 
   flow_diagram: |
     ```mermaid

common/tasks/create-doc.md

@@ -1,5 +1,9 @@
 # Create Document from Template (YAML Driven)
 
+## Critical: Template Discovery
+
+If a YAML Template has not been provided, list all templates from {root}/templates or ask the user to provide another.
+
 ## CRITICAL: Mandatory Elicitation Format
 
 **When `elicit: true`, ALWAYS use this exact format:**

common/utils/template-format.md

@@ -1,26 +0,0 @@
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates

dist/agents/analyst.txt

@@ -107,7 +107,7 @@ dependencies:
 ==================== START: .bmad-core/tasks/facilitate-brainstorming-session.md ====================
 ---
 docOutputLocation: docs/brainstorming-session-results.md
-template: brainstorming-output-tmpl
+template: ".bmad-core/templates/brainstorming-output-tmpl.md"
 ---
 
 # Facilitate Brainstorming Session Task
@@ -260,7 +260,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -323,15 +323,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -364,11 +362,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -377,7 +375,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -393,8 +391,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -411,8 +407,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -429,8 +423,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -499,8 +491,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -522,8 +512,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities
@@ -760,9 +748,9 @@ Generate comprehensive documentation for existing projects optimized for AI deve
 
 ### 1. Initial Project Analysis
 
-[[LLM: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
+**CRITICAL:** First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
 
-**IF PRD EXISTS**: 
+**IF PRD EXISTS**:
 
 - Review the PRD to understand what enhancement/feature is planned
 - Identify which modules, services, or areas will be affected
@@ -808,11 +796,10 @@ Ask the user these elicitation questions to better understand their needs:
 - Are there any existing documentation standards or formats you prefer?
 - What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
 - Is there a specific feature or enhancement you're planning? (This helps focus documentation)
-  ]]
 
 ### 2. Deep Codebase Analysis
 
-[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
+CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase:
 
 1. **Explore Key Areas**:
    - Entry points (main files, index files, app initializers)
@@ -835,13 +822,14 @@ Ask the user these elicitation questions to better understand their needs:
    - Document workarounds and technical debt
    - Note areas that differ from standard patterns
 
-**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
+**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement
 
 ### 3. Core Documentation Generation
 
 [[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
 
 **CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
+
 - Technical debt and workarounds
 - Inconsistent patterns between different parts
 - Legacy code that can't be changed
@@ -853,13 +841,16 @@ Ask the user these elicitation questions to better understand their needs:
 # [Project Name] Brownfield Architecture Document
 
 ## Introduction
+
 This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
 
 ### Document Scope
+
 [If PRD provided: "Focused on areas relevant to: {enhancement description}"]
 [If no PRD: "Comprehensive documentation of entire system"]
 
 ### Change Log
+
 | Date | Version | Description | Author |
 |------|---------|-------------|--------|
 | [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
@@ -867,6 +858,7 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 ## Quick Reference - Key Files and Entry Points
 
 ### Critical Files for Understanding the System
+
 - **Main Entry**: `src/index.js` (or actual entry point)
 - **Configuration**: `config/app.config.js`, `.env.example`
 - **Core Business Logic**: `src/services/`, `src/domain/`
@@ -875,22 +867,25 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 - **Key Algorithms**: [List specific files with complex logic]
 
 ### If PRD Provided - Enhancement Impact Areas
+
 [Highlight which files/modules will be affected by the planned enhancement]
 
 ## High Level Architecture
 
 ### Technical Summary
-[Real assessment of architecture - mention if it's well-structured or has issues]
 
 ### Actual Tech Stack (from package.json/requirements.txt)
+
 | Category | Technology | Version | Notes |
 |----------|------------|---------|--------|
 | Runtime | Node.js | 16.x | [Any constraints] |
 | Framework | Express | 4.18.2 | [Custom middleware?] |
 | Database | PostgreSQL | 13 | [Connection pooling setup] |
-| [etc...] |
+
+etc...
 
 ### Repository Structure Reality Check
+
 - Type: [Monorepo/Polyrepo/Hybrid]
 - Package Manager: [npm/yarn/pnpm]
 - Notable: [Any unusual structure decisions]
@@ -898,7 +893,8 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 ## Source Tree and Module Organization
 
 ### Project Structure (Actual)
-```
+
+```text
 project-root/
 ├── src/
 │   ├── controllers/     # HTTP request handlers
@@ -912,6 +908,7 @@ project-root/
 ```
 
 ### Key Modules and Their Purpose
+
 - **User Management**: `src/services/userService.js` - Handles all user operations
 - **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
 - **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
@@ -920,12 +917,14 @@ project-root/
 ## Data Models and APIs
 
 ### Data Models
+
 Instead of duplicating, reference actual model files:
 - **User Model**: See `src/models/User.js`
 - **Order Model**: See `src/models/Order.js`
 - **Related Types**: TypeScript definitions in `src/types/`
 
 ### API Specifications
+
 - **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
 - **Postman Collection**: `docs/api/postman-collection.json`
 - **Manual Endpoints**: [List any undocumented endpoints discovered]
@@ -933,12 +932,14 @@ Instead of duplicating, reference actual model files:
 ## Technical Debt and Known Issues
 
 ### Critical Technical Debt
+
 1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
 2. **User Service**: Different pattern than other services, uses callbacks instead of promises
 3. **Database Migrations**: Manually tracked, no proper migration tool
 4. **[Other significant debt]**
 
 ### Workarounds and Gotchas
+
 - **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
 - **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
 - **[Other workarounds developers need to know]**
@@ -946,13 +947,16 @@ Instead of duplicating, reference actual model files:
 ## Integration Points and External Dependencies
 
 ### External Services
+
 | Service | Purpose | Integration Type | Key Files |
 |---------|---------|------------------|-----------|
 | Stripe | Payments | REST API | `src/integrations/stripe/` |
 | SendGrid | Emails | SDK | `src/services/emailService.js` |
-| [etc...] |
+
+etc...
 
 ### Internal Integration Points
+
 - **Frontend Communication**: REST API on port 3000, expects specific headers
 - **Background Jobs**: Redis queue, see `src/workers/`
 - **[Other integrations]**
@@ -960,11 +964,13 @@ Instead of duplicating, reference actual model files:
 ## Development and Deployment
 
 ### Local Development Setup
+
 1. Actual steps that work (not ideal steps)
 2. Known issues with setup
 3. Required environment variables (see `.env.example`)
 
 ### Build and Deployment Process
+
 - **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
 - **Deployment**: Manual deployment via `scripts/deploy.sh`
 - **Environments**: Dev, Staging, Prod (see `config/environments/`)
@@ -972,12 +978,14 @@ Instead of duplicating, reference actual model files:
 ## Testing Reality
 
 ### Current Test Coverage
+
 - Unit Tests: 60% coverage (Jest)
 - Integration Tests: Minimal, in `tests/integration/`
 - E2E Tests: None
 - Manual Testing: Primary QA method
 
 ### Running Tests
+
 ```bash
 npm test           # Runs unit tests
 npm run test:integration  # Runs integration tests (requires local DB)
@@ -986,6 +994,7 @@ npm run test:integration  # Runs integration tests (requires local DB)
 ## If Enhancement PRD Provided - Impact Analysis
 
 ### Files That Will Need Modification
+
 Based on the enhancement requirements, these files will be affected:
 - `src/services/userService.js` - Add new user fields
 - `src/models/User.js` - Update schema
@@ -993,11 +1002,13 @@ Based on the enhancement requirements, these files will be affected:
 - [etc...]
 
 ### New Files/Modules Needed
+
 - `src/services/newFeatureService.js` - New business logic
 - `src/models/NewFeature.js` - New data model
 - [etc...]
 
 ### Integration Considerations
+
 - Will need to integrate with existing auth middleware
 - Must follow existing response format in `src/utils/responseFormatter.js`
 - [Other integration points]
@@ -1005,6 +1016,7 @@ Based on the enhancement requirements, these files will be affected:
 ## Appendix - Useful Commands and Scripts
 
 ### Frequently Used Commands
+
 ```bash
 npm run dev         # Start development server
 npm run build       # Production build
@@ -1013,14 +1025,13 @@ npm run seed        # Seed test data
 ```
 
 ### Debugging and Troubleshooting
+
 - **Logs**: Check `logs/app.log` for application logs
 - **Debug Mode**: Set `DEBUG=app:*` for verbose logging
 - **Common Issues**: See `docs/troubleshooting.md`]]
 
 ### 4. Document Delivery
 
-[[LLM: After generating the complete architecture document:
-
 1. **In Web UI (Gemini, ChatGPT, Claude)**:
    - Present the entire document in one response (or multiple if too long)
    - Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
@@ -1032,6 +1043,7 @@ npm run seed        # Seed test data
    - Can be sharded later using PO agent if desired
 
 The document should be comprehensive enough that future agents can understand:
+
 - The actual state of the system (not idealized)
 - Where to find key files and logic
 - What technical debt exists
@@ -1040,7 +1052,7 @@ The document should be comprehensive enough that future agents can understand:
 
 ### 5. Quality Assurance
 
-[[LLM: Before finalizing the document:
+CRITICAL: Before finalizing the document:
 
 1. **Accuracy Check**: Verify all technical details match the actual codebase
 2. **Completeness Review**: Ensure all major system components are documented
@@ -1048,7 +1060,7 @@ The document should be comprehensive enough that future agents can understand:
 4. **Clarity Assessment**: Check that explanations are clear for AI agents
 5. **Navigation**: Ensure document has clear section structure for easy reference
 
-Apply the advanced elicitation task after major sections to refine based on user feedback.]]
+Apply the advanced elicitation task after major sections to refine based on user feedback.
 
 ## Success Criteria
 
@@ -2409,17 +2421,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -2739,7 +2744,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -2809,8 +2814,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines

dist/agents/architect.txt

@@ -200,7 +200,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -263,15 +263,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -304,11 +302,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -317,7 +315,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -333,8 +331,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -351,8 +347,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -369,8 +363,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -439,8 +431,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -462,8 +452,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities
@@ -498,9 +486,9 @@ Generate comprehensive documentation for existing projects optimized for AI deve
 
 ### 1. Initial Project Analysis
 
-[[LLM: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
+**CRITICAL:** First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
 
-**IF PRD EXISTS**: 
+**IF PRD EXISTS**:
 
 - Review the PRD to understand what enhancement/feature is planned
 - Identify which modules, services, or areas will be affected
@@ -546,11 +534,10 @@ Ask the user these elicitation questions to better understand their needs:
 - Are there any existing documentation standards or formats you prefer?
 - What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
 - Is there a specific feature or enhancement you're planning? (This helps focus documentation)
-  ]]
 
 ### 2. Deep Codebase Analysis
 
-[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:
+CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase:
 
 1. **Explore Key Areas**:
    - Entry points (main files, index files, app initializers)
@@ -573,13 +560,14 @@ Ask the user these elicitation questions to better understand their needs:
    - Document workarounds and technical debt
    - Note areas that differ from standard patterns
 
-**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]
+**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement
 
 ### 3. Core Documentation Generation
 
 [[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
 
 **CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
+
 - Technical debt and workarounds
 - Inconsistent patterns between different parts
 - Legacy code that can't be changed
@@ -591,13 +579,16 @@ Ask the user these elicitation questions to better understand their needs:
 # [Project Name] Brownfield Architecture Document
 
 ## Introduction
+
 This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
 
 ### Document Scope
+
 [If PRD provided: "Focused on areas relevant to: {enhancement description}"]
 [If no PRD: "Comprehensive documentation of entire system"]
 
 ### Change Log
+
 | Date | Version | Description | Author |
 |------|---------|-------------|--------|
 | [Date] | 1.0 | Initial brownfield analysis | [Analyst] |
@@ -605,6 +596,7 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 ## Quick Reference - Key Files and Entry Points
 
 ### Critical Files for Understanding the System
+
 - **Main Entry**: `src/index.js` (or actual entry point)
 - **Configuration**: `config/app.config.js`, `.env.example`
 - **Core Business Logic**: `src/services/`, `src/domain/`
@@ -613,22 +605,25 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 - **Key Algorithms**: [List specific files with complex logic]
 
 ### If PRD Provided - Enhancement Impact Areas
+
 [Highlight which files/modules will be affected by the planned enhancement]
 
 ## High Level Architecture
 
 ### Technical Summary
-[Real assessment of architecture - mention if it's well-structured or has issues]
 
 ### Actual Tech Stack (from package.json/requirements.txt)
+
 | Category | Technology | Version | Notes |
 |----------|------------|---------|--------|
 | Runtime | Node.js | 16.x | [Any constraints] |
 | Framework | Express | 4.18.2 | [Custom middleware?] |
 | Database | PostgreSQL | 13 | [Connection pooling setup] |
-| [etc...] |
+
+etc...
 
 ### Repository Structure Reality Check
+
 - Type: [Monorepo/Polyrepo/Hybrid]
 - Package Manager: [npm/yarn/pnpm]
 - Notable: [Any unusual structure decisions]
@@ -636,7 +631,8 @@ This document captures the CURRENT STATE of the [Project Name] codebase, includi
 ## Source Tree and Module Organization
 
 ### Project Structure (Actual)
-```
+
+```text
 project-root/
 ├── src/
 │   ├── controllers/     # HTTP request handlers
@@ -650,6 +646,7 @@ project-root/
 ```
 
 ### Key Modules and Their Purpose
+
 - **User Management**: `src/services/userService.js` - Handles all user operations
 - **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
 - **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
@@ -658,12 +655,14 @@ project-root/
 ## Data Models and APIs
 
 ### Data Models
+
 Instead of duplicating, reference actual model files:
 - **User Model**: See `src/models/User.js`
 - **Order Model**: See `src/models/Order.js`
 - **Related Types**: TypeScript definitions in `src/types/`
 
 ### API Specifications
+
 - **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
 - **Postman Collection**: `docs/api/postman-collection.json`
 - **Manual Endpoints**: [List any undocumented endpoints discovered]
@@ -671,12 +670,14 @@ Instead of duplicating, reference actual model files:
 ## Technical Debt and Known Issues
 
 ### Critical Technical Debt
+
 1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
 2. **User Service**: Different pattern than other services, uses callbacks instead of promises
 3. **Database Migrations**: Manually tracked, no proper migration tool
 4. **[Other significant debt]**
 
 ### Workarounds and Gotchas
+
 - **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
 - **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
 - **[Other workarounds developers need to know]**
@@ -684,13 +685,16 @@ Instead of duplicating, reference actual model files:
 ## Integration Points and External Dependencies
 
 ### External Services
+
 | Service | Purpose | Integration Type | Key Files |
 |---------|---------|------------------|-----------|
 | Stripe | Payments | REST API | `src/integrations/stripe/` |
 | SendGrid | Emails | SDK | `src/services/emailService.js` |
-| [etc...] |
+
+etc...
 
 ### Internal Integration Points
+
 - **Frontend Communication**: REST API on port 3000, expects specific headers
 - **Background Jobs**: Redis queue, see `src/workers/`
 - **[Other integrations]**
@@ -698,11 +702,13 @@ Instead of duplicating, reference actual model files:
 ## Development and Deployment
 
 ### Local Development Setup
+
 1. Actual steps that work (not ideal steps)
 2. Known issues with setup
 3. Required environment variables (see `.env.example`)
 
 ### Build and Deployment Process
+
 - **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
 - **Deployment**: Manual deployment via `scripts/deploy.sh`
 - **Environments**: Dev, Staging, Prod (see `config/environments/`)
@@ -710,12 +716,14 @@ Instead of duplicating, reference actual model files:
 ## Testing Reality
 
 ### Current Test Coverage
+
 - Unit Tests: 60% coverage (Jest)
 - Integration Tests: Minimal, in `tests/integration/`
 - E2E Tests: None
 - Manual Testing: Primary QA method
 
 ### Running Tests
+
 ```bash
 npm test           # Runs unit tests
 npm run test:integration  # Runs integration tests (requires local DB)
@@ -724,6 +732,7 @@ npm run test:integration  # Runs integration tests (requires local DB)
 ## If Enhancement PRD Provided - Impact Analysis
 
 ### Files That Will Need Modification
+
 Based on the enhancement requirements, these files will be affected:
 - `src/services/userService.js` - Add new user fields
 - `src/models/User.js` - Update schema
@@ -731,11 +740,13 @@ Based on the enhancement requirements, these files will be affected:
 - [etc...]
 
 ### New Files/Modules Needed
+
 - `src/services/newFeatureService.js` - New business logic
 - `src/models/NewFeature.js` - New data model
 - [etc...]
 
 ### Integration Considerations
+
 - Will need to integrate with existing auth middleware
 - Must follow existing response format in `src/utils/responseFormatter.js`
 - [Other integration points]
@@ -743,6 +754,7 @@ Based on the enhancement requirements, these files will be affected:
 ## Appendix - Useful Commands and Scripts
 
 ### Frequently Used Commands
+
 ```bash
 npm run dev         # Start development server
 npm run build       # Production build
@@ -751,14 +763,13 @@ npm run seed        # Seed test data
 ```
 
 ### Debugging and Troubleshooting
+
 - **Logs**: Check `logs/app.log` for application logs
 - **Debug Mode**: Set `DEBUG=app:*` for verbose logging
 - **Common Issues**: See `docs/troubleshooting.md`]]
 
 ### 4. Document Delivery
 
-[[LLM: After generating the complete architecture document:
-
 1. **In Web UI (Gemini, ChatGPT, Claude)**:
    - Present the entire document in one response (or multiple if too long)
    - Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
@@ -770,6 +781,7 @@ npm run seed        # Seed test data
    - Can be sharded later using PO agent if desired
 
 The document should be comprehensive enough that future agents can understand:
+
 - The actual state of the system (not idealized)
 - Where to find key files and logic
 - What technical debt exists
@@ -778,7 +790,7 @@ The document should be comprehensive enough that future agents can understand:
 
 ### 5. Quality Assurance
 
-[[LLM: Before finalizing the document:
+CRITICAL: Before finalizing the document:
 
 1. **Accuracy Check**: Verify all technical details match the actual codebase
 2. **Completeness Review**: Ensure all major system components are documented
@@ -786,7 +798,7 @@ The document should be comprehensive enough that future agents can understand:
 4. **Clarity Assessment**: Check that explanations are clear for AI agents
 5. **Navigation**: Ensure document has clear section structure for easy reference
 
-Apply the advanced elicitation task after major sections to refine based on user feedback.]]
+Apply the advanced elicitation task after major sections to refine based on user feedback.
 
 ## Success Criteria
 
@@ -1535,7 +1547,6 @@ sections:
       After completing the architecture:
       
       1. If project has UI components:
-      - Recommend engaging Design Architect agent
       - Use "Frontend Architecture Mode"
       - Provide this document as input
       
@@ -1546,22 +1557,15 @@ sections:
       
       3. Include specific prompts for next agents if needed
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
+      - id: architect-prompt
+        title: Architect Prompt
         condition: Project has UI components
         instruction: |
-          Create a brief prompt to hand off to Design Architect for Frontend Architecture creation. Include:
+          Create a brief prompt to hand off to Architect for Frontend Architecture creation. Include:
           - Reference to this architecture document
           - Key UI requirements from PRD
           - Any frontend-specific decisions made here
           - Request for detailed frontend architecture
-      - id: developer-handoff
-        title: Developer Handoff
-        instruction: |
-          Create a brief prompt for developers starting implementation. Include:
-          - Reference to this architecture and coding standards
-          - First epic/story to implement
-          - Key technical decisions to follow
 ==================== END: .bmad-core/templates/architecture-tmpl.yaml ====================
 
 ==================== START: .bmad-core/templates/front-end-architecture-tmpl.yaml ====================

dist/agents/bmad-orchestrator.txt

@@ -47,9 +47,6 @@ CRITICAL: Read the full YAML, start activation to alter your state of being, fol
 ```yaml
 activation-instructions:
   - Mention *help shows all available commands and options
-  - Check for active workflow plan using .bmad-core/utils/plan-management.md
-  - 'If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details.'
-  - 'If plan exists: Suggest next action based on plan progress'
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -154,7 +151,6 @@ workflow-guidance:
   - Understand each workflow's purpose, options, and decision points
   - Ask clarifying questions based on the workflow's structure
   - Guide users through workflow selection when multiple options exist
-  - For complex projects, offer to create a workflow plan using create-workflow-plan task
   - When appropriate, suggest: Would you like me to create a detailed workflow plan before starting?
   - For workflows with divergent paths, help users choose the right path
   - Adapt questions to the specific domain (e.g., game dev vs infrastructure vs web dev)
@@ -164,16 +160,12 @@ dependencies:
   tasks:
     - advanced-elicitation.md
     - create-doc.md
-    - create-workflow-plan.md
     - kb-mode-interaction.md
-    - update-workflow-plan.md
   data:
     - bmad-kb.md
     - elicitation-methods.md
   utils:
-    - plan-management.md
     - workflow-management.md
-    - template-format.md
 ```
 ==================== END: .bmad-core/agents/bmad-orchestrator.md ====================
 
@@ -379,302 +371,11 @@ User can type `#yolo` to toggle to YOLO mode (process all sections at once).
 - End with "Select 1-9 or just type your question/feedback:"
 ==================== END: .bmad-core/tasks/create-doc.md ====================
 
-==================== START: .bmad-core/tasks/create-workflow-plan.md ====================
-# Create Workflow Plan Task
-
-## Purpose
-
-Guide users through workflow selection and create a detailed plan document that outlines the selected workflow steps, decision points, and expected outputs. This task helps users understand what will happen before starting a complex workflow and provides a checklist to track progress.
-
-## Task Instructions
-
-### 1. Understand User's Goal
-
-[[LLM: Start with discovery questions to understand what the user wants to accomplish]]
-
-Ask the user:
-
-1. **Project Type**:
-   - Are you starting a new project (greenfield) or enhancing an existing one (brownfield)?
-   - What type of application? (web app, service/API, UI only, full-stack)
-
-2. **For Greenfield**:
-   - Do you need a quick prototype or production-ready application?
-   - Will this have a UI component?
-   - Single service or multiple services?
-
-3. **For Brownfield**:
-   - What's the scope of the enhancement?
-     - Single bug fix or small feature (few hours)
-     - Small enhancement (1-3 stories)
-     - Major feature requiring coordination
-     - Architectural changes or modernization
-   - Do you have existing documentation?
-   - Are you following existing patterns or introducing new ones?
-
-### 2. Recommend Appropriate Workflow
-
-Based on the answers, recommend:
-
-**Greenfield Options:**
-
-- `greenfield-fullstack` - Complete web application
-- `greenfield-service` - Backend API/service only
-- `greenfield-ui` - Frontend only
-
-**Brownfield Options:**
-
-- `brownfield-create-story` - Single small change
-- `brownfield-create-epic` - Small feature (1-3 stories)
-- `brownfield-fullstack` - Major enhancement
-
-**Simplified Option:**
-
-- For users unsure or wanting flexibility, suggest starting with individual agent tasks
-
-### 3. Explain Selected Workflow
-
-[[LLM: Once workflow is selected, provide clear explanation]]
-
-For the selected workflow, explain:
-
-1. **Overview**: What this workflow accomplishes
-2. **Duration**: Estimated time for planning phase
-3. **Outputs**: What documents will be created
-4. **Decision Points**: Where user input will be needed
-5. **Requirements**: What information should be ready
-
-### 4. Create Workflow Plan Document
-
-[[LLM: Generate a comprehensive plan document with the following structure]]
-
-```markdown
-# Workflow Plan: {{Workflow Name}}
-
-<!-- WORKFLOW-PLAN-META
-workflow-id: {{workflow-id}}
-status: active
-created: {{ISO-8601 timestamp}}
-updated: {{ISO-8601 timestamp}}
-version: 1.0
--->
-
-**Created Date**: {{current date}}
-**Project**: {{project name}}
-**Type**: {{greenfield/brownfield}}
-**Status**: Active
-**Estimated Planning Duration**: {{time estimate}}
-
-## Objective
-
-{{Clear description of what will be accomplished}}
-
-## Selected Workflow
-
-**Workflow**: `{{workflow-id}}`
-**Reason**: {{Why this workflow fits the user's needs}}
-
-## Workflow Steps
-
-### Planning Phase
-
-- [ ] Step 1: {{step name}} <!-- step-id: 1.1, agent: {{agent}}, task: {{task}} -->
-  - **Agent**: {{agent name}}
-  - **Action**: {{what happens}}
-  - **Output**: {{what's created}}
-  - **User Input**: {{if any}}
-
-- [ ] Step 2: {{step name}} <!-- step-id: 1.2, agent: {{agent}}, task: {{task}} -->
-  - **Agent**: {{agent name}}
-  - **Action**: {{what happens}}
-  - **Output**: {{what's created}}
-  - **Decision Point**: {{if any}} <!-- decision-id: D1 -->
-
-{{Continue for all planning steps}}
-
-### Development Phase (IDE)
-
-- [ ] Document Sharding <!-- step-id: 2.1, agent: po, task: shard-doc -->
-  - Prepare documents for story creation
-
-- [ ] Story Development Cycle <!-- step-id: 2.2, repeats: true -->
-  - [ ] Create story (SM agent) <!-- step-id: 2.2.1, agent: sm, task: create-next-story -->
-  - [ ] Review story (optional) <!-- step-id: 2.2.2, agent: analyst, optional: true -->
-  - [ ] Implement story (Dev agent) <!-- step-id: 2.2.3, agent: dev -->
-  - [ ] QA review (optional) <!-- step-id: 2.2.4, agent: qa, optional: true -->
-  - [ ] Repeat for all stories
-
-- [ ] Epic Retrospective (optional) <!-- step-id: 2.3, agent: po, optional: true -->
-
-## Key Decision Points
-
-1. **{{Decision Name}}** (Step {{n}}): <!-- decision-id: D1, status: pending -->
-   - Trigger: {{what causes this decision}}
-   - Options: {{available choices}}
-   - Impact: {{how it affects the workflow}}
-   - Decision Made: _Pending_
-
-{{List all decision points}}
-
-## Expected Outputs
-
-### Planning Documents
-- [ ] {{document 1}} - {{description}}
-- [ ] {{document 2}} - {{description}}
-{{etc...}}
-
-### Development Artifacts
-- [ ] Stories in `docs/stories/`
-- [ ] Implementation code
-- [ ] Tests
-- [ ] Updated documentation
-
-## Prerequisites Checklist
-
-Before starting this workflow, ensure you have:
-
-- [ ] {{prerequisite 1}}
-- [ ] {{prerequisite 2}}
-- [ ] {{prerequisite 3}}
-{{etc...}}
-
-## Customization Options
-
-Based on your project needs, you may:
-- Skip {{optional step}} if {{condition}}
-- Add {{additional step}} if {{condition}}
-- Choose {{alternative}} instead of {{default}}
-
-## Risk Considerations
-
-{{For brownfield only}}
-- Integration complexity: {{assessment}}
-- Rollback strategy: {{approach}}
-- Testing requirements: {{special needs}}
-
-## Next Steps
-
-1. Review this plan and confirm it matches your expectations
-2. Gather any missing prerequisites
-3. Start workflow with: `*task workflow {{workflow-id}}`
-4. Or begin with first agent: `@{{first-agent}}`
-
-## Notes
-
-{{Any additional context or warnings}}
-
----
-*This plan can be updated as you progress through the workflow. Check off completed items to track progress.*
-```
-
-### 5. Save and Present Plan
-
-1. Save the plan as `docs/workflow-plan.md`
-2. Inform user: "Workflow plan created at docs/workflow-plan.md"
-3. Offer options:
-   - Review the plan together
-   - Start the workflow now
-   - Gather prerequisites first
-   - Modify the plan
-
-### 6. Plan Variations
-
-[[LLM: Adjust plan detail based on workflow complexity]]
-
-**For Simple Workflows** (create-story, create-epic):
-
-- Simpler checklist format
-- Focus on immediate next steps
-- Less detailed explanations
-
-**For Complex Workflows** (full greenfield/brownfield):
-
-- Detailed step breakdowns
-- All decision points documented
-- Comprehensive output descriptions
-- Risk mitigation sections
-
-**For Brownfield Workflows**:
-
-- Include existing system impact analysis
-- Document integration checkpoints
-- Add rollback considerations
-- Note documentation dependencies
-
-### 7. Interactive Planning Mode
-
-[[LLM: If user wants to customize the workflow]]
-
-If user wants to modify the standard workflow:
-
-1. Present workflow steps as options
-2. Allow skipping optional steps
-3. Let user reorder certain steps
-4. Document customizations in plan
-5. Warn about dependencies if steps are skipped
-
-### 8. Execution Guidance
-
-After plan is created, provide clear guidance:
-
-```text
-Your workflow plan is ready! Here's how to proceed:
-
-1. **Review the plan**: Check that all steps align with your goals
-2. **Gather prerequisites**: Use the checklist to ensure you're ready
-3. **Start execution**:
-   - Full workflow: `*task workflow {{workflow-id}}`
-   - Step by step: Start with `@{{first-agent}}`
-4. **Track progress**: Check off steps in the plan as completed
-
-Would you like to:
-a) Review the plan together
-b) Start the workflow now
-c) Gather prerequisites first
-d) Modify the plan
-```
-
-## Success Criteria
-
-The workflow plan is successful when:
-
-1. User clearly understands what will happen
-2. All decision points are documented
-3. Prerequisites are identified
-4. Expected outputs are clear
-5. User feels confident to proceed
-6. Plan serves as useful progress tracker
-
-## Integration with BMad Master and Orchestrator
-
-When used by BMad Master or BMad Orchestrator, this task should:
-
-1. Be offered when user asks about workflows
-2. Be suggested before starting complex workflows
-3. Create a plan that the agent can reference during execution
-4. Allow the agent to track progress against the plan
-
-## Example Usage
-
-```text
-User: "I need to add a payment system to my existing app"
-
-BMad Orchestrator: "Let me help you create a workflow plan for that enhancement. I'll ask a few questions to recommend the best approach..."
-
-[Runs through discovery questions]
-
-BMad Orchestrator: "Based on your answers, I recommend the brownfield-fullstack workflow. Let me create a detailed plan for you..."
-
-[Creates and saves plan]
-
-BMad Orchestrator: "I've created a workflow plan at docs/workflow-plan.md. This shows all the steps we'll go through, what documents will be created, and where you'll need to make decisions. Would you like to review it together?"
-```
-==================== END: .bmad-core/tasks/create-workflow-plan.md ====================
-
 ==================== START: .bmad-core/tasks/kb-mode-interaction.md ====================
 # KB Mode Interaction Task
 
 ## Purpose
+
 Provide a user-friendly interface to the BMad knowledge base without overwhelming users with information upfront.
 
 ## Instructions
@@ -682,11 +383,11 @@ Provide a user-friendly interface to the BMad knowledge base without overwhelmin
 When entering KB mode (*kb-mode), follow these steps:
 
 ### 1. Welcome and Guide
-Announce entering KB mode with a brief, friendly introduction:
 
-"I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method."
+Announce entering KB mode with a brief, friendly introduction.
 
 ### 2. Present Topic Areas
+
 Offer a concise list of main topic areas the user might want to explore:
 
 **What would you like to know more about?**
@@ -703,19 +404,23 @@ Offer a concise list of main topic areas the user might want to explore:
 Or ask me about anything else related to BMad-Method!
 
 ### 3. Respond Contextually
+
 - Wait for user's specific question or topic selection
 - Provide focused, relevant information from the knowledge base
 - Offer to dive deeper or explore related topics
 - Keep responses concise unless user asks for detailed explanations
 
 ### 4. Interactive Exploration
+
 - After answering, suggest related topics they might find helpful
 - Maintain conversational flow rather than data dumping
 - Use examples when appropriate
 - Reference specific documentation sections when relevant
 
 ### 5. Exit Gracefully
+
 When user is done or wants to exit KB mode:
+
 - Summarize key points discussed if helpful
 - Remind them they can return to KB mode anytime with *kb-mode
 - Suggest next steps based on what was discussed
@@ -744,257 +449,6 @@ Or ask me about anything else related to BMad-Method!
 **Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
 ==================== END: .bmad-core/tasks/kb-mode-interaction.md ====================
 
-==================== START: .bmad-core/tasks/update-workflow-plan.md ====================
-# Update Workflow Plan Task
-
-## Purpose
-
-Update the status of steps in an active workflow plan, mark completions, add notes about deviations, and maintain an accurate record of workflow progress. This task can be called directly by users or automatically by other tasks upon completion.
-
-## Task Instructions
-
-### 0. Load Plan Configuration
-
-[[LLM: First load core-config.yaml to get plan settings]]
-
-Check workflow configuration:
-
-- `workflow.planFile` - Location of the plan (default: docs/workflow-plan.md)
-- `workflow.trackProgress` - Whether tracking is enabled
-- `workflow.updateOnCompletion` - Whether to auto-update on task completion
-
-If tracking is disabled, inform user and exit.
-
-### 1. Verify Plan Exists
-
-[[LLM: Check if workflow plan exists at configured location]]
-
-If no plan exists:
-
-```
-No active workflow plan found at {location}.
-Would you like to create one? Use *plan command.
-```
-
-### 2. Determine Update Type
-
-[[LLM: Ask user what type of update they want to make]]
-
-Present options:
-
-```
-What would you like to update in the workflow plan?
-
-1. Mark step as complete
-2. Update current step
-3. Add deviation note
-4. Mark decision point resolution
-5. Update overall status
-6. View current plan status only
-
-Please select an option (1-6):
-```
-
-### 3. Parse Current Plan
-
-[[LLM: Read and parse the plan to understand current state]]
-
-Extract:
-
-- All steps with their checkbox status
-- Step IDs from comments (if present)
-- Current completion percentage
-- Any existing deviation notes
-- Decision points and their status
-
-### 4. Execute Updates
-
-#### 4.1 Mark Step Complete
-
-If user selected option 1:
-
-1. Show numbered list of incomplete steps
-2. Ask which step to mark complete
-3. Update the checkbox from `[ ]` to `[x]`
-4. Add completion timestamp: `<!-- completed: YYYY-MM-DD HH:MM -->`
-5. If this was the current step, identify next step
-
-#### 4.2 Update Current Step
-
-If user selected option 2:
-
-1. Show all steps with current status
-2. Ask which step is now current
-3. Add/move `<!-- current-step -->` marker
-4. Optionally add note about why sequence changed
-
-#### 4.3 Add Deviation Note
-
-If user selected option 3:
-
-1. Ask for deviation description
-2. Ask which step this relates to (or general)
-3. Insert note in appropriate location:
-
-```markdown
-> **Deviation Note** (YYYY-MM-DD): {user_note}
-> Related to: Step X.Y or General workflow
-```
-
-#### 4.4 Mark Decision Resolution
-
-If user selected option 4:
-
-1. Show pending decision points
-2. Ask which decision was made
-3. Record the decision and chosen path
-4. Update related steps based on decision
-
-#### 4.5 Update Overall Status
-
-If user selected option 5:
-
-1. Show current overall status
-2. Provide options:
-   - Active (continuing with plan)
-   - Paused (temporarily stopped)
-   - Abandoned (no longer following)
-   - Complete (all steps done)
-3. Update plan header with new status
-
-### 5. Automatic Updates (When Called by Tasks)
-
-[[LLM: When called automatically by another task]]
-
-If called with parameters:
-
-```
-task: {task_name}
-step_id: {step_identifier}
-status: complete|skipped|failed
-note: {optional_note}
-```
-
-Automatically:
-
-1. Find the corresponding step
-2. Update its status
-3. Add completion metadata
-4. Add note if provided
-5. Calculate new progress percentage
-
-### 6. Generate Update Summary
-
-After updates, show summary:
-
-```
-✅ Workflow Plan Updated
-
-Changes made:
-- {change_1}
-- {change_2}
-
-New Status:
-- Progress: {X}% complete ({completed}/{total} steps)
-- Current Step: {current_step}
-- Next Recommended: {next_step}
-
-Plan location: {file_path}
-```
-
-### 7. Integration with Other Tasks
-
-[[LLM: How other tasks should call this]]
-
-Other tasks can integrate by:
-
-1. **After Task Completion**:
-
-```
-At end of task execution:
-- Check if task corresponds to a plan step
-- If yes, call update-workflow-plan with:
-  - task: {current_task_name}
-  - step_id: {matching_step}
-  - status: complete
-```
-
-2. **On Task Failure**:
-
-```
-If task fails:
-- Call update-workflow-plan with:
-  - task: {current_task_name}
-  - status: failed
-  - note: {failure_reason}
-```
-
-### 8. Plan Status Display
-
-[[LLM: When user selects view status only]]
-
-Display comprehensive status:
-
-```markdown
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Status: {Active|Paused|Complete}
-Progress: {X}% complete ({completed}/{total} steps)
-Last Updated: {timestamp}
-
-✅ Completed Steps:
-- [x] Step 1.1: {description} (completed: {date})
-- [x] Step 1.2: {description} (completed: {date})
-
-🔄 Current Step:
-- [ ] Step 2.1: {description} <!-- current-step -->
-  Agent: {agent_name}
-  Task: {task_name}
-
-📌 Upcoming Steps:
-- [ ] Step 2.2: {description}
-- [ ] Step 3.1: {description}
-
-⚠️ Deviations/Notes:
-{any_deviation_notes}
-
-📊 Decision Points:
-- Decision 1: {status} - {choice_made}
-- Decision 2: Pending
-
-💡 Next Action:
-Based on the plan, you should {recommended_action}
-```
-
-## Success Criteria
-
-The update is successful when:
-
-1. Plan accurately reflects current workflow state
-2. All updates are clearly timestamped
-3. Deviations are documented with reasons
-4. Progress calculation is correct
-5. Next steps are clear to user
-6. Plan remains readable and well-formatted
-
-## Error Handling
-
-- **Plan file not found**: Offer to create new plan
-- **Malformed plan**: Attempt basic updates, warn user
-- **Write permission error**: Show changes that would be made
-- **Step not found**: Show available steps, ask for clarification
-- **Concurrent updates**: Implement simple locking or warn about conflicts
-
-## Notes
-
-- Always preserve plan history (don't delete old information)
-- Keep updates atomic to prevent corruption
-- Consider creating backup before major updates
-- Updates should enhance, not complicate, the workflow experience
-- If plan becomes too cluttered, suggest creating fresh plan for next phase
-==================== END: .bmad-core/tasks/update-workflow-plan.md ====================
-
 ==================== START: .bmad-core/data/bmad-kb.md ====================
 # BMad Knowledge Base
 
@@ -1401,17 +855,10 @@ The BMad-Method is built around a modular architecture centered on the `bmad-cor
 
 BMad employs a sophisticated template system with three key components:
 
-1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
-2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
+1. **Template Format** (`utils/bmad-doc-template.md`): Defines markup language for variable substitution and AI processing directives from yaml templates
+2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction to transform yaml spec to final markdown output
 3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
 
-**Template Features**:
-
-- **Self-contained**: Templates embed both output structure and processing instructions
-- **Variable Substitution**: `{{placeholders}}` for dynamic content
-- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
-- **Interactive Refinement**: Built-in elicitation processes for quality improvement
-
 ### Technical Preferences Integration
 
 The `technical-preferences.md` file serves as a persistent technical profile that:
@@ -1731,7 +1178,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 - Atomic commits - one logical change per commit
 - Must align with guiding principles
 
-**Core Principles** (from GUIDING-PRINCIPLES.md):
+**Core Principles** (from docs/GUIDING-PRINCIPLES.md):
 
 - **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
 - **Natural Language First**: Everything in markdown, no code in core
@@ -1801,8 +1248,8 @@ Use the **expansion-creator** pack to build your own:
 
 ## Getting Help
 
-- **Commands**: Use `/help` in any environment to see available commands
-- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Commands**: Use `*/*help` in any environment to see available commands
+- **Agent Switching**: Use `*/*switch agent-name` with orchestrator for role changes
 - **Documentation**: Check `docs/` folder for project-specific context
 - **Community**: Discord and GitHub resources available for support
 - **Contributing**: See `CONTRIBUTING.md` for full guidelines
@@ -1945,228 +1392,6 @@ Use the **expansion-creator** pack to build your own:
 - Prepare to continue without additional elicitation
 ==================== END: .bmad-core/data/elicitation-methods.md ====================
 
-==================== START: .bmad-core/utils/plan-management.md ====================
-# Plan Management Utility
-
-## Purpose
-
-Provides utilities for agents and tasks to interact with workflow plans, check progress, update status, and ensure workflow steps are executed in the appropriate sequence.
-
-## Core Functions
-
-### 1. Check Plan Existence
-
-Check for workflow plan:
-
-1. Look for docs/workflow-plan.md (default location)
-2. Return plan status to user (exists/not exists) - if not exists then HALT.
-
-### 2. Parse Plan Status
-
-[[LLM: Extract current progress from the plan document]]
-
-**Plan Parsing Logic:**
-
-1. **Identify Step Structure**:
-   - Look for checkbox lines: `- [ ]` or `- [x]`
-   - Extract step IDs from comments: `<!-- step-id: X.Y -->`
-   - Identify agent assignments: `<!-- agent: pm -->`
-
-2. **Determine Current State**:
-   - Last completed step (highest numbered `[x]`)
-   - Next expected step (first `[ ]` after completed steps)
-   - Overall progress percentage
-
-3. **Extract Metadata**:
-   - Workflow type from plan header
-   - Decision points and their status
-   - Any deviation notes
-
-### 3. Sequence Validation
-
-[[LLM: Check if requested action aligns with plan sequence]]
-
-**Validation Rules:**
-
-1. **Strict Mode** (enforceSequence: true):
-   - Must complete steps in exact order
-   - Warn and block if out of sequence
-   - Require explicit override justification
-
-2. **Flexible Mode** (enforceSequence: false):
-   - Warn about sequence deviation
-   - Allow with confirmation
-   - Log deviation reason
-
-**Warning Templates:**
-
-```text
-SEQUENCE WARNING: 
-The workflow plan shows you should complete "{expected_step}" next.
-You're attempting to: "{requested_action}"
-
-In strict mode: Block and require plan update
-In flexible mode: Allow with confirmation
-```
-
-### 4. Plan Update Operations
-
-[[LLM: Provide consistent way to update plan progress]]
-
-**Update Actions:**
-
-1. **Mark Step Complete**:
-   - Change `- [ ]` to `- [x]`
-   - Add completion timestamp comment
-   - Update any status metadata
-
-2. **Add Deviation Note**:
-   - Insert note explaining why sequence changed
-   - Reference the deviation in plan
-
-3. **Update Current Step Pointer**:
-   - Add/move `<!-- current-step -->` marker
-   - Update last-modified timestamp
-
-### 5. Integration Instructions
-
-[[LLM: How agents and tasks should use this utility]]
-
-**For Agents (startup sequence)**:
-
-```text
-1. Check if plan exists using this utility
-2. If exists:
-   - Parse current status
-   - Show user: "Active workflow plan detected. Current step: {X}"
-   - Suggest: "Next recommended action: {next_step}"
-3. Continue with normal startup
-```
-
-**For Tasks (pre-execution)**:
-
-```text
-1. Check if plan exists
-2. If exists:
-   - Verify this task aligns with plan
-   - If not aligned:
-     - In strict mode: Show warning and stop
-     - In flexible mode: Show warning and ask for confirmation
-3. After task completion:
-   - Update plan if task was a planned step
-   - Add note if task was unplanned
-```
-
-### 6. Plan Status Report Format
-
-[[LLM: Standard format for showing plan status]]
-
-```text
-📋 Workflow Plan Status
-━━━━━━━━━━━━━━━━━━━━
-Workflow: {workflow_name}
-Progress: {X}% complete ({completed}/{total} steps)
-
-✅ Completed:
-- {completed_step_1}
-- {completed_step_2}
-
-🔄 Current Step:
-- {current_step_description}
-
-📌 Upcoming:
-- {next_step_1}
-- {next_step_2}
-
-⚠️ Notes:
-- {any_deviations_or_notes}
-```
-
-### 7. Decision Point Handling
-
-[[LLM: Special handling for workflow decision points]]
-
-When encountering a decision point in the plan:
-
-1. **Identify Decision Marker**: `<!-- decision: {decision_id} -->`
-2. **Check Decision Status**: Made/Pending
-3. **If Pending**: 
-   - Block progress until decision made
-   - Show options to user
-   - Record decision when made
-4. **If Made**: 
-   - Verify current path aligns with decision
-   - Warn if attempting alternate path
-
-### 8. Plan Abandonment
-
-[[LLM: Graceful handling when user wants to stop following plan]]
-
-If user wants to abandon plan:
-
-1. Confirm abandonment intent
-2. Add abandonment note to plan
-3. Mark plan as "Abandoned" in header
-4. Stop plan checking for remainder of session
-5. Suggest creating new plan if needed
-
-## Usage Examples
-
-### Example 1: Agent Startup Check
-
-```text
-BMad Master starting...
-
-[Check for plan]
-Found active workflow plan: brownfield-fullstack
-Progress: 40% complete (4/10 steps)
-Current step: Create PRD (pm agent)
-
-Suggestion: Based on your plan, you should work with the PM agent next.
-Use *agent pm to switch, or *plan-status to see full progress.
-```
-
-### Example 2: Task Sequence Warning
-
-```text
-User: *task create-next-story
-
-[Plan check triggered]
-⚠️ SEQUENCE WARNING: 
-Your workflow plan indicates the PRD hasn't been created yet.
-Creating stories before the PRD may lead to incomplete requirements.
-
-Would you like to:
-1. Continue anyway (will note deviation in plan)
-2. Switch to creating PRD first (*agent pm)
-3. View plan status (*plan-status)
-```
-
-### Example 3: Automatic Plan Update
-
-```text
-[After completing create-doc task for PRD]
-
-✅ Plan Updated: Marked "Create PRD" as complete
-📍 Next step: Create Architecture Document (architect agent)
-```
-
-## Implementation Notes
-
-- This utility should be lightweight and fast
-- Plan parsing should be resilient to format variations
-- Always preserve user agency - warnings not blocks (unless strict mode)
-- Plan updates should be atomic to prevent corruption
-- Consider plan versioning for rollback capability
-
-## Error Handling
-
-- Missing plan: Return null, don't error
-- Malformed plan: Warn but continue, treat as no plan
-- Update failures: Log but don't block task completion
-- Parse errors: Fallback to basic text search
-==================== END: .bmad-core/utils/plan-management.md ====================
-
 ==================== START: .bmad-core/utils/workflow-management.md ====================
 # Workflow Management
 
@@ -2238,32 +1463,3 @@ Handle conditional paths by asking clarifying questions when needed.
 
 Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.
 ==================== END: .bmad-core/utils/workflow-management.md ====================
-
-==================== START: .bmad-core/utils/template-format.md ====================
-# Template Format Conventions
-
-Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
-
-## Template Markup Elements
-
-- **{{placeholders}}**: Variables to be replaced with actual content
-- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
-- **REPEAT** sections: Content blocks that may be repeated as needed
-- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
-- **@{examples}**: Example content for guidance (never output to users)
-
-## Processing Rules
-
-- Replace all {{placeholders}} with project-specific content
-- Execute all [[LLM: instructions]] internally without showing users
-- Process conditional and repeat blocks as specified
-- Use examples for guidance but never include them in final output
-- Present only clean, formatted content to users
-
-## Critical Guidelines
-
-- **NEVER display template markup, LLM instructions, or examples to users**
-- Template elements are for AI processing only
-- Focus on faithful template execution and clean output
-- All template-specific instructions are embedded within templates
-==================== END: .bmad-core/utils/template-format.md ====================

dist/agents/dev.txt

@@ -193,7 +193,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:

dist/agents/pm.txt

@@ -185,9 +185,9 @@ User can type `#yolo` to toggle to YOLO mode (process all sections at once).
 
 ## Purpose
 
-- Guide a structured response to a change trigger using the `change-checklist`.
+- Guide a structured response to a change trigger using the `.bmad-core/checklists/change-checklist`.
 - Analyze the impacts of the change on epics, project artifacts, and the MVP, guided by the checklist's structure.
-- Explore potential solutions (e.g., adjust scope, rollback elements, rescope features) as prompted by the checklist.
+- Explore potential solutions (e.g., adjust scope, rollback elements, re-scope features) as prompted by the checklist.
 - Draft specific, actionable proposed updates to any affected project artifacts (e.g., epics, user stories, PRD sections, architecture document sections) based on the analysis.
 - Produce a consolidated "Sprint Change Proposal" document that contains the impact analysis and the clearly drafted proposed edits for user review and approval.
 - Ensure a clear handoff path if the nature of the changes necessitates fundamental replanning by other core agents (like PM or Architect).
@@ -199,19 +199,16 @@ User can type `#yolo` to toggle to YOLO mode (process all sections at once).
 - **Acknowledge Task & Inputs:**
   - Confirm with the user that the "Correct Course Task" (Change Navigation & Integration) is being initiated.
   - Verify the change trigger and ensure you have the user's initial explanation of the issue and its perceived impact.
-  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `change-checklist` (e.g., `change-checklist`).
+  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `.bmad-core/checklists/change-checklist`.
 - **Establish Interaction Mode:**
   - Ask the user their preferred interaction mode for this task:
-    - **"Incrementally (Default & Recommended):** Shall we work through the `change-checklist` section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
+    - **"Incrementally (Default & Recommended):** Shall we work through the change-checklist section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
     - **"YOLO Mode (Batch Processing):** Or, would you prefer I conduct a more batched analysis based on the checklist and then present a consolidated set of findings and proposed changes for a broader review? This can be quicker for initial assessment but might require more extensive review of the combined proposals."
-  - Request the user to select their preferred mode.
-  - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed.
-- **Explain Process:** Briefly inform the user: "We will now use the `change-checklist` to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
-  <rule>When asking multiple questions or presenting multiple points for user input at once, number them clearly (e.g., 1., 2a., 2b.) to make it easier for the user to provide specific responses.</rule>
+  - Once the user chooses, confirm the selected mode and then inform the user: "We will now use the change-checklist to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
 
 ### 2. Execute Checklist Analysis (Iteratively or Batched, per Interaction Mode)
 
-- Systematically work through Sections 1-4 of the `change-checklist` (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
+- Systematically work through Sections 1-4 of the change-checklist (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
 - For each checklist item or logical group of items (depending on interaction mode):
   - Present the relevant prompt(s) or considerations from the checklist to the user.
   - Request necessary information and actively analyze the relevant project artifacts (PRD, epics, architecture documents, story history, etc.) to assess the impact.
@@ -234,7 +231,7 @@ User can type `#yolo` to toggle to YOLO mode (process all sections at once).
 
 ### 4. Generate "Sprint Change Proposal" with Edits
 
-- Synthesize the complete `change-checklist` analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the `change-checklist` (Proposal Components).
+- Synthesize the complete change-checklist analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the change-checklist.
 - The proposal must clearly present:
   - **Analysis Summary:** A concise overview of the original issue, its analyzed impact (on epics, artifacts, MVP scope), and the rationale for the chosen path forward.
   - **Specific Proposed Edits:** For each affected artifact, clearly show or describe the exact changes (e.g., "Change Story X.Y from: [old text] To: [new text]", "Add new Acceptance Criterion to Story A.B: [new AC]", "Update Section 3.2 of Architecture Document as follows: [new/modified text or diagram description]").
@@ -251,9 +248,9 @@ User can type `#yolo` to toggle to YOLO mode (process all sections at once).
 ## Output Deliverables
 
 - **Primary:** A "Sprint Change Proposal" document (in markdown format). This document will contain:
-  - A summary of the `change-checklist` analysis (issue, impact, rationale for the chosen path).
+  - A summary of the change-checklist analysis (issue, impact, rationale for the chosen path).
   - Specific, clearly drafted proposed edits for all affected project artifacts.
-- **Implicit:** An annotated `change-checklist` (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
+- **Implicit:** An annotated change-checklist (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
 ==================== END: .bmad-core/tasks/correct-course.md ====================
 
 ==================== START: .bmad-core/tasks/create-deep-research-prompt.md ====================
@@ -273,7 +270,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -336,15 +333,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -377,11 +372,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -390,7 +385,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -406,8 +401,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -424,8 +417,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -442,8 +433,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -512,8 +501,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -535,8 +522,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities
@@ -980,20 +965,20 @@ The LLM will:
 
 ## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+[[LLM: First, check if markdownExploder is set to true in .bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
 
 If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
 
 If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
 
 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in bmad-core/core-config.yaml
+2. Or set markdownExploder to false in .bmad-core/core-config.yaml
 
 **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
 
 If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
 
-1. Set markdownExploder to true in bmad-core/core-config.yaml
+1. Set markdownExploder to true in .bmad-core/core-config.yaml
 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
 
 I will now proceed with the manual sharding process."
@@ -1033,8 +1018,6 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 ## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
 
-[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
-
 ### Task Instructions
 
 1. Identify Document and Target Location
@@ -1045,7 +1028,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 2. Parse and Extract Sections
 
-[[LLM: When sharding the document:
+CRITICAL AEGNT SHARDING RULES:
 
 1. Read the entire document content
 2. Identify all level 2 sections (## headings)
@@ -1106,8 +1089,6 @@ Create an `index.md` file in the sharded folder that:
 
 ### 5. Preserve Special Content
 
-[[LLM: Pay special attention to preserving:
-
 1. **Code blocks**: Must capture complete blocks including:
 
    ```language
@@ -1129,7 +1110,7 @@ Create an `index.md` file in the sharded folder that:
 
 6. **Links and references**: Keep all markdown links intact
 
-7. **Template markup**: If documents contain {{placeholders}} or [[LLM instructions]], preserve exactly]]
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
 
 ### 6. Validation
 
@@ -1360,9 +1341,9 @@ sections:
   - id: next-steps
     title: Next Steps
     sections:
-      - id: design-architect-prompt
-        title: Design Architect Prompt
-        instruction: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.
+      - id: ux-expert-prompt
+        title: UX Expert Prompt
+        instruction: This section will contain the prompt for the UX Expert, keep it short and to the point to initiate create architecture mode using this document as input.
       - id: architect-prompt
         title: Architect Prompt
         instruction: This section will contain the prompt for the Architect, keep it short and to the point to initiate create architecture mode using this document as input.

dist/agents/po.txt

@@ -209,20 +209,20 @@ The LLM will:
 
 ## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+[[LLM: First, check if markdownExploder is set to true in .bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
 
 If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
 
 If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
 
 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in bmad-core/core-config.yaml
+2. Or set markdownExploder to false in .bmad-core/core-config.yaml
 
 **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
 
 If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
 
-1. Set markdownExploder to true in bmad-core/core-config.yaml
+1. Set markdownExploder to true in .bmad-core/core-config.yaml
 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
 
 I will now proceed with the manual sharding process."
@@ -262,8 +262,6 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 ## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
 
-[[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
-
 ### Task Instructions
 
 1. Identify Document and Target Location
@@ -274,7 +272,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 2. Parse and Extract Sections
 
-[[LLM: When sharding the document:
+CRITICAL AEGNT SHARDING RULES:
 
 1. Read the entire document content
 2. Identify all level 2 sections (## headings)
@@ -335,8 +333,6 @@ Create an `index.md` file in the sharded folder that:
 
 ### 5. Preserve Special Content
 
-[[LLM: Pay special attention to preserving:
-
 1. **Code blocks**: Must capture complete blocks including:
 
    ```language
@@ -358,7 +354,7 @@ Create an `index.md` file in the sharded folder that:
 
 6. **Links and references**: Keep all markdown links intact
 
-7. **Template markup**: If documents contain {{placeholders}} or [[LLM instructions]], preserve exactly]]
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
 
 ### 6. Validation
 
@@ -397,9 +393,9 @@ Document sharded successfully:
 
 ## Purpose
 
-- Guide a structured response to a change trigger using the `change-checklist`.
+- Guide a structured response to a change trigger using the `.bmad-core/checklists/change-checklist`.
 - Analyze the impacts of the change on epics, project artifacts, and the MVP, guided by the checklist's structure.
-- Explore potential solutions (e.g., adjust scope, rollback elements, rescope features) as prompted by the checklist.
+- Explore potential solutions (e.g., adjust scope, rollback elements, re-scope features) as prompted by the checklist.
 - Draft specific, actionable proposed updates to any affected project artifacts (e.g., epics, user stories, PRD sections, architecture document sections) based on the analysis.
 - Produce a consolidated "Sprint Change Proposal" document that contains the impact analysis and the clearly drafted proposed edits for user review and approval.
 - Ensure a clear handoff path if the nature of the changes necessitates fundamental replanning by other core agents (like PM or Architect).
@@ -411,19 +407,16 @@ Document sharded successfully:
 - **Acknowledge Task & Inputs:**
   - Confirm with the user that the "Correct Course Task" (Change Navigation & Integration) is being initiated.
   - Verify the change trigger and ensure you have the user's initial explanation of the issue and its perceived impact.
-  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `change-checklist` (e.g., `change-checklist`).
+  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `.bmad-core/checklists/change-checklist`.
 - **Establish Interaction Mode:**
   - Ask the user their preferred interaction mode for this task:
-    - **"Incrementally (Default & Recommended):** Shall we work through the `change-checklist` section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
+    - **"Incrementally (Default & Recommended):** Shall we work through the change-checklist section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
     - **"YOLO Mode (Batch Processing):** Or, would you prefer I conduct a more batched analysis based on the checklist and then present a consolidated set of findings and proposed changes for a broader review? This can be quicker for initial assessment but might require more extensive review of the combined proposals."
-  - Request the user to select their preferred mode.
-  - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed.
-- **Explain Process:** Briefly inform the user: "We will now use the `change-checklist` to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
-  <rule>When asking multiple questions or presenting multiple points for user input at once, number them clearly (e.g., 1., 2a., 2b.) to make it easier for the user to provide specific responses.</rule>
+  - Once the user chooses, confirm the selected mode and then inform the user: "We will now use the change-checklist to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
 
 ### 2. Execute Checklist Analysis (Iteratively or Batched, per Interaction Mode)
 
-- Systematically work through Sections 1-4 of the `change-checklist` (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
+- Systematically work through Sections 1-4 of the change-checklist (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
 - For each checklist item or logical group of items (depending on interaction mode):
   - Present the relevant prompt(s) or considerations from the checklist to the user.
   - Request necessary information and actively analyze the relevant project artifacts (PRD, epics, architecture documents, story history, etc.) to assess the impact.
@@ -446,7 +439,7 @@ Document sharded successfully:
 
 ### 4. Generate "Sprint Change Proposal" with Edits
 
-- Synthesize the complete `change-checklist` analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the `change-checklist` (Proposal Components).
+- Synthesize the complete change-checklist analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the change-checklist.
 - The proposal must clearly present:
   - **Analysis Summary:** A concise overview of the original issue, its analyzed impact (on epics, artifacts, MVP scope), and the rationale for the chosen path forward.
   - **Specific Proposed Edits:** For each affected artifact, clearly show or describe the exact changes (e.g., "Change Story X.Y from: [old text] To: [new text]", "Add new Acceptance Criterion to Story A.B: [new AC]", "Update Section 3.2 of Architecture Document as follows: [new/modified text or diagram description]").
@@ -463,9 +456,9 @@ Document sharded successfully:
 ## Output Deliverables
 
 - **Primary:** A "Sprint Change Proposal" document (in markdown format). This document will contain:
-  - A summary of the `change-checklist` analysis (issue, impact, rationale for the chosen path).
+  - A summary of the change-checklist analysis (issue, impact, rationale for the chosen path).
   - Specific, clearly drafted proposed edits for all affected project artifacts.
-- **Implicit:** An annotated `change-checklist` (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
+- **Implicit:** An annotated change-checklist (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
 ==================== END: .bmad-core/tasks/correct-course.md ====================
 
 ==================== START: .bmad-core/tasks/brownfield-create-epic.md ====================
@@ -792,7 +785,7 @@ To comprehensively validate a story draft before implementation begins, ensuring
 
 ### 0. Load Core Configuration and Inputs
 
-- Load `.bmad-core/core-config.yaml` from the project root
+- Load `.bmad-core/core-config.yaml`
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story validation."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`
 - Identify and load the following inputs:

dist/agents/qa.txt

@@ -96,9 +96,7 @@ dependencies:
 ==================== START: .bmad-core/tasks/review-story.md ====================
 # review-story
 
-When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
-
-[[LLM: QA Agent executing review-story task as Senior Developer]]
+When a developer agent marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
 
 ## Prerequisites
 
@@ -227,6 +225,7 @@ After review and any refactoring, append your results to the story file in the Q
 ## Blocking Conditions
 
 Stop the review and request clarification if:
+
 - Story file is incomplete or missing critical sections
 - File List is empty or clearly incomplete
 - No tests exist when they were required
@@ -236,6 +235,7 @@ Stop the review and request clarification if:
 ## Completion
 
 After review:
+
 1. If all items are checked and approved: Update story status to "Done"
 2. If unchecked items remain: Keep status as "Review" for dev to address
 3. Always provide constructive feedback and explanations for learning

dist/agents/sm.txt

@@ -98,7 +98,6 @@ To identify the next logical story based on project progress and epic definition
 - Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy it from GITHUB bmad-core/core-config.yaml and configure it for your project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure core-config.yaml before proceeding."
 - Extract key configurations: `devStoryLocation`, `prd.*`, `architecture.*`, `workflow.*`
-- If `workflow.trackProgress: true`, use `utils/plan-management.md` to check plan sequence and warn if out of order
 
 ### 1. Identify Next Story for Preparation
 
@@ -190,15 +189,14 @@ ALWAYS cite source documents: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft" and save the story file
-- If `workflow.trackProgress: true` and `workflow.updateOnCompletion: true`, call update-workflow-plan task to mark story creation step complete
-- Execute `tasks/execute-checklist` `checklists/story-draft-checklist`
+- Execute `.bmad-core/tasks/execute-checklist` `.bmad-core/checklists/story-draft-checklist`
 - Provide summary to user including:
   - Story created: `{devStoryLocation}/{epicNum}.{storyNum}.story.md`
   - Status: Draft
   - Key technical components included from architecture docs
   - Any deviations or conflicts noted between epic and architecture
   - Checklist Results
-  - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `validate-next-story`
+  - Next steps: For Complex stories, suggest the user carefully review the story draft and also optionally have the PO run the task `.bmad-core/tasks/validate-next-story`
 ==================== END: .bmad-core/tasks/create-next-story.md ====================
 
 ==================== START: .bmad-core/tasks/execute-checklist.md ====================
@@ -302,9 +300,9 @@ The LLM will:
 
 ## Purpose
 
-- Guide a structured response to a change trigger using the `change-checklist`.
+- Guide a structured response to a change trigger using the `.bmad-core/checklists/change-checklist`.
 - Analyze the impacts of the change on epics, project artifacts, and the MVP, guided by the checklist's structure.
-- Explore potential solutions (e.g., adjust scope, rollback elements, rescope features) as prompted by the checklist.
+- Explore potential solutions (e.g., adjust scope, rollback elements, re-scope features) as prompted by the checklist.
 - Draft specific, actionable proposed updates to any affected project artifacts (e.g., epics, user stories, PRD sections, architecture document sections) based on the analysis.
 - Produce a consolidated "Sprint Change Proposal" document that contains the impact analysis and the clearly drafted proposed edits for user review and approval.
 - Ensure a clear handoff path if the nature of the changes necessitates fundamental replanning by other core agents (like PM or Architect).
@@ -316,19 +314,16 @@ The LLM will:
 - **Acknowledge Task & Inputs:**
   - Confirm with the user that the "Correct Course Task" (Change Navigation & Integration) is being initiated.
   - Verify the change trigger and ensure you have the user's initial explanation of the issue and its perceived impact.
-  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `change-checklist` (e.g., `change-checklist`).
+  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `.bmad-core/checklists/change-checklist`.
 - **Establish Interaction Mode:**
   - Ask the user their preferred interaction mode for this task:
-    - **"Incrementally (Default & Recommended):** Shall we work through the `change-checklist` section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
+    - **"Incrementally (Default & Recommended):** Shall we work through the change-checklist section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
     - **"YOLO Mode (Batch Processing):** Or, would you prefer I conduct a more batched analysis based on the checklist and then present a consolidated set of findings and proposed changes for a broader review? This can be quicker for initial assessment but might require more extensive review of the combined proposals."
-  - Request the user to select their preferred mode.
-  - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed.
-- **Explain Process:** Briefly inform the user: "We will now use the `change-checklist` to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
-  <rule>When asking multiple questions or presenting multiple points for user input at once, number them clearly (e.g., 1., 2a., 2b.) to make it easier for the user to provide specific responses.</rule>
+  - Once the user chooses, confirm the selected mode and then inform the user: "We will now use the change-checklist to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
 
 ### 2. Execute Checklist Analysis (Iteratively or Batched, per Interaction Mode)
 
-- Systematically work through Sections 1-4 of the `change-checklist` (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
+- Systematically work through Sections 1-4 of the change-checklist (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
 - For each checklist item or logical group of items (depending on interaction mode):
   - Present the relevant prompt(s) or considerations from the checklist to the user.
   - Request necessary information and actively analyze the relevant project artifacts (PRD, epics, architecture documents, story history, etc.) to assess the impact.
@@ -351,7 +346,7 @@ The LLM will:
 
 ### 4. Generate "Sprint Change Proposal" with Edits
 
-- Synthesize the complete `change-checklist` analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the `change-checklist` (Proposal Components).
+- Synthesize the complete change-checklist analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the change-checklist.
 - The proposal must clearly present:
   - **Analysis Summary:** A concise overview of the original issue, its analyzed impact (on epics, artifacts, MVP scope), and the rationale for the chosen path forward.
   - **Specific Proposed Edits:** For each affected artifact, clearly show or describe the exact changes (e.g., "Change Story X.Y from: [old text] To: [new text]", "Add new Acceptance Criterion to Story A.B: [new AC]", "Update Section 3.2 of Architecture Document as follows: [new/modified text or diagram description]").
@@ -368,9 +363,9 @@ The LLM will:
 ## Output Deliverables
 
 - **Primary:** A "Sprint Change Proposal" document (in markdown format). This document will contain:
-  - A summary of the `change-checklist` analysis (issue, impact, rationale for the chosen path).
+  - A summary of the change-checklist analysis (issue, impact, rationale for the chosen path).
   - Specific, clearly drafted proposed edits for all affected project artifacts.
-- **Implicit:** An annotated `change-checklist` (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
+- **Implicit:** An annotated change-checklist (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
 ==================== END: .bmad-core/tasks/correct-course.md ====================
 
 ==================== START: .bmad-core/templates/story-tmpl.yaml ====================

dist/agents/ux-expert.txt

@@ -101,7 +101,7 @@ To generate a masterful, comprehensive, and optimized prompt that can be used wi
 
 ## Inputs
 
-- Completed UI/UX Specification (`front-end-spec`)
+- Completed UI/UX Specification (`front-end-spec.md`)
 - Completed Frontend Architecture Document (`front-end-architecture`) or a full stack combined architecture such as `architecture.md`
 - Main System Architecture Document (`architecture` - for API contracts and tech stack to give further context)
 
@@ -163,7 +163,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -226,15 +226,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -267,11 +265,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -280,7 +278,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -296,8 +294,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -314,8 +310,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -332,8 +326,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -402,8 +394,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -425,8 +415,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities

dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.txt

@@ -603,7 +603,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -666,15 +666,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -707,11 +705,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -720,7 +718,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -736,8 +734,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -754,8 +750,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -772,8 +766,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -842,8 +834,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -865,8 +855,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities

dist/expansion-packs/bmad-creator-tools/agents/bmad-the-creator.txt

@@ -1455,7 +1455,7 @@ Generate well-structured research prompts that:
 
 ## Research Type Selection
 
-[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+CRITICAL: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.
 
 ### 1. Research Focus Options
 
@@ -1518,15 +1518,13 @@ Present these numbered options to the user:
    - Consider regulatory and legal implications
 
 9. **Custom Research Focus**
-   [[LLM: Allow user to define their own specific research focus.]]
+
    - User-defined research objectives
    - Specialized domain investigation
    - Cross-functional research needs
 
 ### 2. Input Processing
 
-[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
-
 **If Project Brief provided:**
 
 - Extract key product concepts and goals
@@ -1559,11 +1557,11 @@ Present these numbered options to the user:
 
 ### 3. Research Prompt Structure
 
-[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+CRITICAL: collaboratively develop a comprehensive research prompt with these components.
 
 #### A. Research Objectives
 
-[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+CRITICAL: collaborate with the user to articulate clear, specific objectives for the research.
 
 - Primary research goal and purpose
 - Key decisions the research will inform
@@ -1572,7 +1570,7 @@ Present these numbered options to the user:
 
 #### B. Research Questions
 
-[[LLM: Develop specific, actionable research questions organized by theme.]]
+CRITICAL: collaborate with the user to develop specific, actionable research questions organized by theme.
 
 **Core Questions:**
 
@@ -1588,8 +1586,6 @@ Present these numbered options to the user:
 
 #### C. Research Methodology
 
-[[LLM: Specify appropriate research methods based on the type and objectives.]]
-
 **Data Collection Methods:**
 
 - Secondary research sources
@@ -1606,8 +1602,6 @@ Present these numbered options to the user:
 
 #### D. Output Requirements
 
-[[LLM: Define how research findings should be structured and presented.]]
-
 **Format Specifications:**
 
 - Executive summary requirements
@@ -1624,8 +1618,6 @@ Present these numbered options to the user:
 
 ### 4. Prompt Generation
 
-[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
-
 **Research Prompt Template:**
 
 ```markdown
@@ -1694,8 +1686,6 @@ Present these numbered options to the user:
 
 ### 5. Review and Refinement
 
-[[LLM: Present the draft research prompt for user review and refinement.]]
-
 1. **Present Complete Prompt**
 
    - Show the full research prompt
@@ -1717,8 +1707,6 @@ Present these numbered options to the user:
 
 ### 6. Next Steps Guidance
 
-[[LLM: Provide clear guidance on how to use the research prompt.]]
-
 **Execution Options:**
 
 1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities

docs/GUIDING-PRINCIPLES.md

@@ -15,7 +15,7 @@ The BMad Method is a natural language framework for AI-assisted software develop
 
 - **Everything is markdown**: Agents, tasks, templates - all written in plain English
 - **No code in core**: The framework itself contains no programming code, only natural language instructions
-- **Self-contained templates**: Templates include their own generation instructions using `[[LLM: ...]]` markup
+- **Self-contained templates**: Templates are defined as YAML files with structured sections that include metadata, workflow configuration, and detailed instructions for content generation
 
 ### 3. Agent and Task Design
 
@@ -60,22 +60,28 @@ See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples an
    - This keeps context overhead minimal
 6. **Reuse common tasks** - Don't create new document creation tasks
    - Use the existing `create-doc` task
-   - Pass the appropriate template with embedded LLM instructions
+   - Pass the appropriate YAML template with structured sections
    - This maintains consistency and reduces duplication
 
 ### Template Rules
 
-1. Include generation instructions with `[[LLM: ...]]` markup
-2. Provide clear structure for output
-3. Make templates reusable across agents
-4. Use standardized markup elements:
-   - `{{placeholders}}` for variables to be replaced
-   - `[[LLM: instructions]]` for AI-only processing (never shown to users)
-   - `REPEAT` sections for repeatable content blocks
-   - `^^CONDITION^^` blocks for conditional content
-   - `@{examples}` for guidance examples (never output to users)
-5. NEVER display template markup or LLM instructions to users
-6. Focus on clean output - all processing instructions stay internal
+Templates follow the [BMad Document Template](common/utils/bmad-doc-template.md) specification using YAML format:
+
+1. **Structure**: Templates are defined in YAML with clear metadata, workflow configuration, and section hierarchy
+2. **Separation of Concerns**: Instructions for LLMs are in `instruction` fields, separate from content
+3. **Reusability**: Templates are agent-agnostic and can be used across different agents
+4. **Key Components**:
+   - `template` block for metadata (id, name, version, output settings)
+   - `workflow` block for interaction mode configuration
+   - `sections` array defining document structure with nested subsections
+   - Each section has `id`, `title`, and `instruction` fields
+5. **Advanced Features**:
+   - Variable substitution using `{{variable_name}}` syntax
+   - Conditional sections with `condition` field
+   - Repeatable sections with `repeatable: true`
+   - Agent permissions with `owner` and `editors` fields
+   - Examples arrays for guidance (never included in output)
+6. **Clean Output**: YAML structure ensures all processing logic stays separate from generated content
 
 ## Remember
 

docs/agentic-tools/claude-code-guide.md

@@ -7,7 +7,7 @@ For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.
 When running `npx bmad-method install`, select **Claude Code** as your IDE. This creates:
 
 - `.bmad-core/` folder with all agents
-- `.claude/commands/` folder with agent command files (`.md`)
+- `.claude/commands/BMad` folder with agent command files (`.md`)
 
 ## Using BMad Agents in Claude Code
 

docs/agentic-tools/gemini-cli-guide.md

@@ -6,23 +6,22 @@ For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.
 
 When running `npx bmad-method install`, select **Gemini CLI** as your IDE. This creates:
 
-- `.gemini/agents/` directory with all agent context files
-- `.gemini/settings.json` configured to load all agents automatically
+- `.gemini/bmad-method/` directory with all agent context in GEMINI.md file
 
 ## Using BMad Agents with Gemini CLI
 
 Simply mention the agent in your prompt:
 
-- "As @dev, implement the login feature"
-- "Acting as @architect, review this system design"
-- "@sm, create the next story for our project"
+- "As \*dev, implement the login feature"
+- "Acting as \*architect, review this system design"
+- "\*sm, create the next story for our project"
 
 The Gemini CLI automatically loads the appropriate agent context.
 
 ## Gemini CLI-Specific Features
 
-- **Context files**: All agents loaded as context in `.gemini/agents/`
-- **Automatic loading**: Settings.json ensures agents are always available
+- **Context files**: All agents loaded as context in `.gemini/bmad-method/GEMINI.md`
+- **Automatic loading**: GEMINI.md ensures agents are always available
 - **Natural language**: No special syntax needed, just mention the agent
 
 ## Tips for Gemini CLI Users

docs/bmad-workflow-guide.md

@@ -111,6 +111,7 @@ Follow the SM → Dev cycle for systematic story development:
 
 - **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
 - **Cursor**: `@agent-name` (e.g., `@bmad-master`)
+- **Gemini CLI**: `*agent-name` (e.g., `*bmad-master`)
 - **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
 - **Trae**: `@agent-name` (e.g., `@bmad-master`)
 - **Roo Code**: Select mode from mode selector (e.g., `bmad-bmad-master`)

docs/template-markup-references.md

@@ -0,0 +1,86 @@
+# Old Template Markup System References
+
+This document catalogs all references to the old template markup system found in the BMAD-METHOD documentation and codebase.
+
+## Summary of Old Markup Patterns
+
+The old template markup system used the following patterns:
+
+- `[[LLM: ...]]` - LLM-only processing directives
+- `{{placeholders}}` - Variable substitution
+- `<<REPEAT section="name">>` - Repeatable sections
+- `^^CONDITION: condition_name^^` - Conditional blocks
+- `@{examples}` - Example content markers
+
+## Files Containing References
+
+### 1. Primary Documentation Files
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/docs/user-guide.md`
+
+- **Lines 149-155**: Describes template structure with placeholders and LLM instructions
+- **Lines 229-230**: References advanced elicitation with embedded LLM instructions
+- **Lines 527-549**: Shows custom template creation with LLM instructions and placeholders
+- **Lines 590-632**: Detailed template patterns including variables, AI processing, and conditionals
+- **Lines 619-623**: References to `@{example}` patterns and `[[LLM:]]` instructions
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/docs/core-architecture.md`
+
+- **Lines 93-104**: Describes templates as self-contained with embedded LLM instructions
+- **Lines 97-104**: Mentions template-format.md specification with placeholders and LLM directives
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/CLAUDE.md`
+
+- **Lines 37, 262**: References to template instructions using `[[LLM: ...]]` markup
+- **Line 38**: Mentions templates with embedded LLM instructions
+
+### 2. Common Utilities
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/common/utils/bmad-doc-template.md`
+
+- **Lines 296-324**: Migration section describes converting from legacy markdown+frontmatter templates
+- **Lines 319-323**: Specific conversion instructions for old markup patterns
+
+### 3. Task Files
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/bmad-core/tasks/shard-doc.md`
+
+- **Lines 11-30**: Contains LLM instructions embedded in the task
+- **Line 160**: References preserving template markup including `{{placeholders}}` and `[[LLM instructions]]`
+
+#### `/Users/brianmadison/dev-bmc/BMAD-METHOD/expansion-packs/bmad-creator-tools/tasks/generate-expansion-pack.md`
+
+- **Lines 10-14**: Describes template systems with LLM instruction embedding
+- **Lines 107-118**: Template section planning with LLM instructions
+- **Lines 229-245**: Detailed LLM instruction patterns for templates
+- **Lines 569-593**: Advanced template design patterns
+- **Lines 229, 573**: Specific examples of `[[LLM:]]` usage
+- **Line 574**: References conditional content with `^^CONDITION:^^`
+- **Line 576**: Mentions iteration controls with `<<REPEAT>>`
+
+### 4. Agent and Template Files
+
+Multiple agent and task files contain actual usage of the old markup system (22 files found with `[[LLM:]]` patterns), including:
+
+- Story templates
+- Checklists
+- Task definitions
+- Workflow plans
+
+## Key Observations
+
+1. **Documentation vs Implementation**: The documentation heavily references the old markup system, while the new YAML-based template system (`bmad-doc-template.md`) is already defined but not yet reflected in the main documentation.
+
+2. **Migration Path**: The `bmad-doc-template.md` file includes a migration section (lines 316-324) that explicitly maps old patterns to new YAML structures.
+
+3. **Active Usage**: Many core tasks and templates still actively use the old markup patterns, particularly `[[LLM:]]` instructions embedded within markdown files.
+
+4. **Inconsistency**: Some files reference a `template-format.md` file that doesn't exist in the expected locations, suggesting incomplete migration or documentation updates.
+
+## Recommendations
+
+1. **Update User Guide**: The user guide needs significant updates to reflect the new YAML-based template system
+2. **Update Core Architecture Docs**: Remove references to embedded LLM instructions in templates
+3. **Create Template Migration Guide**: A comprehensive guide for converting existing templates
+4. **Update Extension Pack Documentation**: The bmad-creator-tools expansion pack documentation needs updates
+5. **Audit Active Templates**: Review and migrate templates that still use the old markup system

expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-2d-phaser-game-dev
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-2d-phaser-game-dev/config.yaml

@@ -5,3 +5,4 @@ description: >-
   2D Game Development expansion pack for BMad Method - Phaser 3 & TypeScript
   focused
 author: Brian (BMad)
+slashPrefix: bmad2dp

expansion-packs/bmad-creator-tools/agents/bmad-the-creator.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-creator-tools
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-creator-tools/config.yaml

@@ -3,3 +3,4 @@ version: 1.7.0
 short-title: Tools for creating BMad framework components
 description: Tools for creating and extending BMad framework components.
 author: Brian (BMad)
+slashPrefix: bmadCreator

expansion-packs/bmad-infrastructure-devops/agents/infra-devops-platform.md

@@ -3,9 +3,8 @@
 CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
-root: .bmad-infrastructure-devops
-IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name} where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
+IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}, type=folder (tasks/templates/checklists/data/utils), name=file-name.
+REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), ALWAYS ask for clarification if no clear match.
 activation-instructions:
   - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
   - Only read the files/tasks listed here when user selects them for execution to minimize context usage

expansion-packs/bmad-infrastructure-devops/config.yaml

@@ -6,3 +6,4 @@ description: >-
   DevOps capabilities. It's designed for teams that need to define, implement,
   and manage cloud infrastructure alongside their application development.
 author: Brian (BMad)
+slashPrefix: bmadInfraDevOps

expansion-packs/bmad-infrastructure-devops/data/bmad-kb.md

@@ -1,3 +1,308 @@
-# Usage Information
+# BMad Infrastructure DevOps Expansion Pack Knowledge Base
 
-TODO
+## Overview
+
+The BMad Infrastructure DevOps expansion pack extends the BMad Method framework with comprehensive infrastructure and DevOps capabilities. It enables teams to design, implement, validate, and maintain modern cloud-native infrastructure alongside their application development efforts.
+
+**Version**: 1.7.0  
+**BMad Compatibility**: v4+  
+**Author**: Brian (BMad)
+
+## Core Purpose
+
+This expansion pack addresses the critical need for systematic infrastructure planning and implementation in modern software projects. It provides:
+
+- Structured approach to infrastructure architecture design
+- Platform engineering implementation guidance
+- Comprehensive validation and review processes
+- Integration with core BMad development workflows
+- Support for cloud-native and traditional infrastructure patterns
+
+## When to Use This Expansion Pack
+
+Use the BMad Infrastructure DevOps expansion pack when your project involves:
+
+- **Cloud Infrastructure Design**: AWS, Azure, GCP, or multi-cloud architectures
+- **Kubernetes and Container Orchestration**: Container platform design and implementation
+- **Infrastructure as Code**: Terraform, CloudFormation, Pulumi implementations
+- **GitOps Workflows**: ArgoCD, Flux, or similar continuous deployment patterns
+- **Platform Engineering**: Building internal developer platforms and self-service capabilities
+- **Service Mesh Implementation**: Istio, Linkerd, or similar service mesh architectures
+- **DevOps Transformation**: Establishing or improving DevOps practices and culture
+
+## Key Components
+
+### 1. DevOps Agent: Alex
+
+**Role**: DevOps Infrastructure Specialist  
+**Experience**: 15+ years in infrastructure and platform engineering
+
+**Core Principles**:
+
+- Infrastructure as Code (IaC) First
+- Automation and Repeatability
+- Reliability and Scalability
+- Security by Design
+- Cost Optimization
+- Developer Experience Focus
+
+**Commands**:
+
+- `*help` - Display available commands and capabilities
+- `*chat-mode` - Interactive conversation mode for infrastructure discussions
+- `*create-doc` - Generate infrastructure documentation from templates
+- `*review-infrastructure` - Conduct systematic infrastructure review
+- `*validate-infrastructure` - Validate infrastructure against comprehensive checklist
+- `*checklist` - Access the 16-section infrastructure validation checklist
+- `*exit` - Return to normal context
+
+### 2. Infrastructure Templates
+
+#### Infrastructure Architecture Template
+
+**Purpose**: Design comprehensive infrastructure architecture  
+**Key Sections**:
+
+- Infrastructure Overview (providers, regions, environments)
+- Infrastructure as Code approach and tooling
+- Network Architecture with visual diagrams
+- Compute Resources planning
+- Security Architecture design
+- Monitoring and Observability strategy
+- CI/CD Pipeline architecture
+- Disaster Recovery planning
+- BMad Integration points
+
+#### Platform Implementation Template
+
+**Purpose**: Implement platform infrastructure based on approved architecture  
+**Key Sections**:
+
+- Foundation Infrastructure Layer
+- Container Platform (Kubernetes) setup
+- GitOps Workflow implementation
+- Service Mesh configuration
+- Developer Experience Platform
+- Security hardening procedures
+- Platform validation and testing
+
+### 3. Tasks
+
+#### Review Infrastructure Task
+
+**Purpose**: Systematic infrastructure review process  
+**Features**:
+
+- Incremental or rapid assessment modes
+- Architectural escalation for complex issues
+- Advanced elicitation for deep analysis
+- Prioritized findings and recommendations
+- Integration with BMad Architecture phase
+
+#### Validate Infrastructure Task
+
+**Purpose**: Comprehensive infrastructure validation  
+**Features**:
+
+- 16-section validation checklist
+- Architecture Design Review Gate
+- Compliance percentage tracking
+- Remediation planning
+- BMad integration assessment
+
+### 4. Infrastructure Validation Checklist
+
+A comprehensive 16-section checklist covering:
+
+**Foundation Infrastructure (Sections 1-12)**:
+
+1. Security Foundation - IAM, encryption, compliance
+2. Infrastructure as Code - Version control, testing, documentation
+3. Resilience & High Availability - Multi-AZ, failover, SLAs
+4. Backup & Disaster Recovery - Strategies, testing, RTO/RPO
+5. Monitoring & Observability - Metrics, logging, alerting
+6. Performance & Scalability - Auto-scaling, load testing
+7. Infrastructure Operations - Patching, maintenance, runbooks
+8. CI/CD Infrastructure - Pipelines, environments, deployments
+9. Networking & Connectivity - Architecture, security, DNS
+10. Compliance & Governance - Standards, auditing, policies
+11. BMad Integration - Agent support, workflow alignment
+12. Architecture Documentation - Diagrams, decisions, maintenance
+
+**Platform Engineering (Sections 13-16)**: 13. Container Platform - Kubernetes setup, RBAC, networking 14. GitOps Workflows - Repository structure, deployment patterns 15. Service Mesh - Traffic management, security, observability 16. Developer Experience - Self-service, documentation, tooling
+
+## Integration with BMad Flow
+
+### Workflow Integration Points
+
+1. **After Architecture Phase**: Infrastructure design begins after application architecture is defined
+2. **Parallel to Development**: Infrastructure implementation runs alongside application development
+3. **Before Production**: Infrastructure validation gates before production deployment
+4. **Continuous Operation**: Ongoing infrastructure reviews and improvements
+
+### Agent Collaboration
+
+- **With Architect (Sage)**: Joint planning sessions, design reviews, architectural alignment
+- **With Developer (Blake)**: Platform capabilities, development environment setup
+- **With Product Manager (Finley)**: Infrastructure requirements, cost considerations
+- **With Creator Agents**: Infrastructure for creative workflows and asset management
+
+## Best Practices
+
+### Infrastructure Design
+
+1. **Start with Requirements**: Understand application needs before designing infrastructure
+2. **Design for Scale**: Plan for 10x growth from day one
+3. **Security First**: Implement defense in depth at every layer
+4. **Cost Awareness**: Balance performance with budget constraints
+5. **Document Everything**: Maintain comprehensive documentation
+
+### Implementation Approach
+
+1. **Incremental Rollout**: Deploy infrastructure in stages with validation gates
+2. **Automation Focus**: Automate repetitive tasks and deployments
+3. **Testing Strategy**: Include infrastructure testing in CI/CD pipelines
+4. **Monitoring Setup**: Implement observability before production
+5. **Team Training**: Ensure team understanding of infrastructure
+
+### Validation Process
+
+1. **Regular Reviews**: Schedule periodic infrastructure assessments
+2. **Checklist Compliance**: Maintain high compliance with validation checklist
+3. **Performance Baselines**: Establish and monitor performance metrics
+4. **Security Audits**: Regular security assessments and penetration testing
+5. **Cost Optimization**: Monthly cost reviews and optimization
+
+## Common Use Cases
+
+### 1. New Project Infrastructure
+
+**Scenario**: Starting a new cloud-native application  
+**Process**:
+
+1. Use Infrastructure Architecture template for design
+2. Review with Architect agent
+3. Implement using Platform Implementation template
+4. Validate with comprehensive checklist
+5. Deploy incrementally with monitoring
+
+### 2. Infrastructure Modernization
+
+**Scenario**: Migrating legacy infrastructure to cloud  
+**Process**:
+
+1. Review existing infrastructure
+2. Design target architecture
+3. Plan migration phases
+4. Implement with validation gates
+5. Monitor and optimize
+
+### 3. Platform Engineering Initiative
+
+**Scenario**: Building internal developer platform  
+**Process**:
+
+1. Assess developer needs
+2. Design platform architecture
+3. Implement Kubernetes/GitOps foundation
+4. Build self-service capabilities
+5. Enable developer adoption
+
+### 4. Multi-Cloud Strategy
+
+**Scenario**: Implementing multi-cloud architecture  
+**Process**:
+
+1. Define cloud strategy and requirements
+2. Design cloud-agnostic architecture
+3. Implement with IaC abstraction
+4. Validate cross-cloud functionality
+5. Establish unified monitoring
+
+## Advanced Features
+
+### GitOps Workflows
+
+- **Repository Structure**: Organized by environment and application
+- **Deployment Patterns**: Progressive delivery, canary deployments
+- **Secret Management**: External secrets operator integration
+- **Policy Enforcement**: OPA/Gatekeeper for compliance
+
+### Service Mesh Capabilities
+
+- **Traffic Management**: Load balancing, circuit breaking, retries
+- **Security**: mTLS, authorization policies
+- **Observability**: Distributed tracing, service maps
+- **Multi-Cluster**: Cross-cluster communication
+
+### Developer Self-Service
+
+- **Portal Features**: Resource provisioning, environment management
+- **API Gateway**: Centralized API management
+- **Documentation**: Automated API docs, runbooks
+- **Tooling**: CLI tools, IDE integrations
+
+## Troubleshooting Guide
+
+### Common Issues
+
+1. **Infrastructure Drift**
+
+   - Solution: Implement drift detection in IaC pipelines
+   - Prevention: Restrict manual changes, enforce GitOps
+
+2. **Cost Overruns**
+
+   - Solution: Implement cost monitoring and alerts
+   - Prevention: Resource tagging, budget limits
+
+3. **Performance Problems**
+
+   - Solution: Review monitoring data, scale resources
+   - Prevention: Load testing, capacity planning
+
+4. **Security Vulnerabilities**
+   - Solution: Immediate patching, security reviews
+   - Prevention: Automated scanning, compliance checks
+
+## Metrics and KPIs
+
+### Infrastructure Metrics
+
+- **Availability**: Target 99.9%+ uptime
+- **Performance**: Response time < 100ms
+- **Cost Efficiency**: Cost per transaction trending down
+- **Security**: Zero critical vulnerabilities
+- **Automation**: 90%+ automated deployments
+
+### Platform Metrics
+
+- **Developer Satisfaction**: NPS > 50
+- **Self-Service Adoption**: 80%+ platform usage
+- **Deployment Frequency**: Multiple per day
+- **Lead Time**: < 1 hour from commit to production
+- **MTTR**: < 30 minutes for incidents
+
+## Future Enhancements
+
+### Planned Features
+
+1. **AI-Driven Optimization**: Automated infrastructure tuning
+2. **Enhanced Security**: Zero-trust architecture templates
+3. **Edge Computing**: Support for edge infrastructure patterns
+4. **Sustainability**: Carbon footprint optimization
+5. **Advanced Compliance**: Industry-specific compliance templates
+
+### Integration Roadmap
+
+1. **Cloud Provider APIs**: Direct integration with AWS, Azure, GCP
+2. **IaC Tools**: Native support for Terraform, Pulumi
+3. **Monitoring Platforms**: Integration with Datadog, New Relic
+4. **Security Tools**: SIEM and vulnerability scanner integration
+5. **Cost Management**: FinOps platform integration
+
+## Conclusion
+
+The BMad Infrastructure DevOps expansion pack provides a comprehensive framework for modern infrastructure and platform engineering. By following its structured approach and leveraging the provided tools and templates, teams can build reliable, scalable, and secure infrastructure that accelerates application delivery while maintaining operational excellence.
+
+For support and updates, refer to the main BMad Method documentation or contact the BMad community.

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method",
-  "version": "4.27.1",
+  "version": "4.29.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method",
-      "version": "4.27.1",
+      "version": "4.29.0",
       "license": "MIT",
       "dependencies": {
         "@kayvan/markdown-tree-parser": "^1.5.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.27.1",
+  "version": "4.29.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {

tools/installer/bin/bmad.js

@@ -224,6 +224,58 @@ async function promptInstallation() {
   answers.installType = selectedItems.includes('bmad-core') ? 'full' : 'expansion-only';
   answers.expansionPacks = selectedItems.filter(item => item !== 'bmad-core');
 
+  // Ask sharding questions if installing BMad core
+  if (selectedItems.includes('bmad-core')) {
+    console.log(chalk.cyan('\n📋 Document Organization Settings'));
+    console.log(chalk.dim('Configure how your project documentation should be organized.\n'));
+    
+    // Ask about PRD sharding
+    const { prdSharded } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'prdSharded',
+        message: 'Will the PRD (Product Requirements Document) be sharded into multiple files?',
+        default: true
+      }
+    ]);
+    answers.prdSharded = prdSharded;
+    
+    // Ask about architecture sharding
+    const { architectureSharded } = await inquirer.prompt([
+      {
+        type: 'confirm',
+        name: 'architectureSharded',
+        message: 'Will the architecture documentation be sharded into multiple files?',
+        default: true
+      }
+    ]);
+    answers.architectureSharded = architectureSharded;
+    
+    // Show warning if architecture sharding is disabled
+    if (!architectureSharded) {
+      console.log(chalk.yellow.bold('\n⚠️  IMPORTANT: Architecture Sharding Disabled'));
+      console.log(chalk.yellow('With architecture sharding disabled, you should still create the files listed'));
+      console.log(chalk.yellow('in devLoadAlwaysFiles (like coding-standards.md, tech-stack.md, source-tree.md)'));
+      console.log(chalk.yellow('as these are used by the dev agent at runtime.'));
+      console.log(chalk.yellow('\nAlternatively, you can remove these files from the devLoadAlwaysFiles list'));
+      console.log(chalk.yellow('in your core-config.yaml after installation.'));
+      
+      const { acknowledge } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'acknowledge',
+          message: 'Do you acknowledge this requirement and want to proceed?',
+          default: false
+        }
+      ]);
+      
+      if (!acknowledge) {
+        console.log(chalk.red('Installation cancelled.'));
+        process.exit(0);
+      }
+    }
+  }
+
   // Ask for IDE configuration
   const { ides } = await inquirer.prompt([
     {
@@ -246,6 +298,37 @@ async function promptInstallation() {
   // Use selected IDEs directly
   answers.ides = ides;
 
+  // Configure GitHub Copilot immediately if selected
+  if (ides.includes('github-copilot')) {
+    console.log(chalk.cyan('\n🔧 GitHub Copilot Configuration'));
+    console.log(chalk.dim('BMad works best with specific VS Code settings for optimal agent experience.\n'));
+    
+    const { configChoice } = await inquirer.prompt([
+      {
+        type: 'list',
+        name: 'configChoice',
+        message: chalk.yellow('How would you like to configure GitHub Copilot settings?'),
+        choices: [
+          {
+            name: 'Use recommended defaults (fastest setup)',
+            value: 'defaults'
+          },
+          {
+            name: 'Configure each setting manually (customize to your preferences)',
+            value: 'manual'
+          },
+          {
+            name: 'Skip settings configuration (I\'ll configure manually later)',
+            value: 'skip'
+          }
+        ],
+        default: 'defaults'
+      }
+    ]);
+    
+    answers.githubCopilotConfig = { configChoice };
+  }
+
   // Ask for web bundles installation
   const { includeWebBundles } = await inquirer.prompt([
     {

tools/installer/config/install.config.yaml

@@ -21,7 +21,7 @@ ide-configurations:
       # 3. The agent will adopt that persona for the conversation
   claude-code:
     name: Claude Code
-    rule-dir: .claude/commands/
+    rule-dir: .claude/commands/BMad/
     format: multi-file
     command-suffix: .md
     instructions: |
@@ -68,13 +68,14 @@ ide-configurations:
       # 4. Rules are stored in .clinerules/ directory in your project
   gemini:
     name: Gemini CLI
-    rule-dir: .gemini/agents/
-    format: context-files
+    rule-dir: .gemini/bmad-method/
+    format: single-file
+    command-suffix: .md
     instructions: |
       # To use BMad agents with the Gemini CLI:
-      # 1. The installer creates a .gemini/ directory in your project.
-      # 2. It also configures .gemini/settings.json to load all agent files.
-      # 3. Simply mention the agent in your prompt (e.g., "As @dev, ...").
+      # 1. The installer creates a .gemini/bmad-method/ directory in your project.
+      # 2. It concatenates all agent files into a single GEMINI.md file.
+      # 3. Simply mention the agent in your prompt (e.g., "As *dev, ...").
       # 4. The Gemini CLI will automatically have the context for that agent.
   github-copilot:
     name: Github Copilot

tools/installer/lib/file-manager.js

@@ -47,7 +47,7 @@ class FileManager {
     }
   }
 
-  async copyGlobPattern(pattern, sourceDir, destDir) {
+  async copyGlobPattern(pattern, sourceDir, destDir, rootValue = null) {
     const files = glob.sync(pattern, { cwd: sourceDir });
     const copied = [];
 
@@ -55,7 +55,17 @@ class FileManager {
       const sourcePath = path.join(sourceDir, file);
       const destPath = path.join(destDir, file);
 
-      if (await this.copyFile(sourcePath, destPath)) {
+      // Use root replacement if rootValue is provided and file needs it
+      const needsRootReplacement = rootValue && (file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml'));
+      
+      let success = false;
+      if (needsRootReplacement) {
+        success = await this.copyFileWithRootReplacement(sourcePath, destPath, rootValue);
+      } else {
+        success = await this.copyFile(sourcePath, destPath);
+      }
+
+      if (success) {
         copied.push(file);
       }
     }
@@ -271,6 +281,99 @@ class FileManager {
 
     return manifest;
   }
+
+  async modifyCoreConfig(installDir, config) {
+    const coreConfigPath = path.join(installDir, '.bmad-core', 'core-config.yaml');
+    
+    try {
+      // Read the existing core-config.yaml
+      const coreConfigContent = await fs.readFile(coreConfigPath, 'utf8');
+      const coreConfig = yaml.load(coreConfigContent);
+      
+      // Modify sharding settings if provided
+      if (config.prdSharded !== undefined) {
+        coreConfig.prd.prdSharded = config.prdSharded;
+      }
+      
+      if (config.architectureSharded !== undefined) {
+        coreConfig.architecture.architectureSharded = config.architectureSharded;
+      }
+      
+      // Write back the modified config
+      await fs.writeFile(coreConfigPath, yaml.dump(coreConfig, { indent: 2 }));
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to modify core-config.yaml:`), error.message);
+      return false;
+    }
+  }
+
+  async copyFileWithRootReplacement(source, destination, rootValue) {
+    try {
+      // Read the source file content
+      const fs = require('fs').promises;
+      const content = await fs.readFile(source, 'utf8');
+      
+      // Replace {root} with the specified root value
+      const updatedContent = content.replace(/\{root\}/g, rootValue);
+      
+      // Ensure directory exists
+      await this.ensureDirectory(path.dirname(destination));
+      
+      // Write the updated content
+      await fs.writeFile(destination, updatedContent, 'utf8');
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to copy ${source} with root replacement:`), error.message);
+      return false;
+    }
+  }
+
+  async copyDirectoryWithRootReplacement(source, destination, rootValue, fileExtensions = ['.md', '.yaml', '.yml']) {
+    try {
+      await initializeModules(); // Ensure chalk is initialized
+      await this.ensureDirectory(destination);
+      
+      // Get all files in source directory
+      const files = glob.sync('**/*', { 
+        cwd: source, 
+        nodir: true 
+      });
+      
+      let replacedCount = 0;
+      
+      for (const file of files) {
+        const sourcePath = path.join(source, file);
+        const destPath = path.join(destination, file);
+        
+        // Check if this file type should have {root} replacement
+        const shouldReplace = fileExtensions.some(ext => file.endsWith(ext));
+        
+        if (shouldReplace) {
+          if (await this.copyFileWithRootReplacement(sourcePath, destPath, rootValue)) {
+            replacedCount++;
+          }
+        } else {
+          // Regular copy for files that don't need replacement
+          await this.copyFile(sourcePath, destPath);
+        }
+      }
+      
+      if (replacedCount > 0) {
+        console.log(chalk.dim(`  Processed ${replacedCount} files with {root} replacement`));
+      }
+      
+      return true;
+    } catch (error) {
+      await initializeModules();
+      console.error(chalk.red(`Failed to copy directory ${source} with root replacement:`), error.message);
+      return false;
+    }
+  }
 }
 
 module.exports = new FileManager();

tools/installer/lib/ide-setup.js

@@ -41,7 +41,7 @@ class IdeSetup {
     }
   }
 
-  async setup(ide, installDir, selectedAgent = null, spinner = null) {
+  async setup(ide, installDir, selectedAgent = null, spinner = null, preConfiguredSettings = null) {
     await initializeModules();
     const ideConfig = await configLoader.getIdeConfiguration(ide);
 
@@ -66,7 +66,7 @@ class IdeSetup {
       case "gemini":
         return this.setupGeminiCli(installDir, selectedAgent);
       case "github-copilot":
-        return this.setupGitHubCopilot(installDir, selectedAgent, spinner);
+        return this.setupGitHubCopilot(installDir, selectedAgent, spinner, preConfiguredSettings);
       default:
         console.log(chalk.yellow(`\nIDE ${ide} not yet supported`));
         return false;
@@ -131,19 +131,64 @@ class IdeSetup {
   }
 
   async setupClaudeCode(installDir, selectedAgent) {
-    const commandsDir = path.join(installDir, ".claude", "commands");
-    const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
+    // Setup bmad-core commands
+    const coreSlashPrefix = await this.getCoreSlashPrefix(installDir);
+    const coreAgents = selectedAgent ? [selectedAgent] : await this.getCoreAgentIds(installDir);
+    const coreTasks = await this.getCoreTaskIds(installDir);
+    await this.setupClaudeCodeForPackage(installDir, "core", coreSlashPrefix, coreAgents, coreTasks, ".bmad-core");
 
-    await fileManager.ensureDirectory(commandsDir);
+    // Setup expansion pack commands
+    const expansionPacks = await this.getInstalledExpansionPacks(installDir);
+    for (const packInfo of expansionPacks) {
+      const packSlashPrefix = await this.getExpansionPackSlashPrefix(packInfo.path);
+      const packAgents = await this.getExpansionPackAgents(packInfo.path);
+      const packTasks = await this.getExpansionPackTasks(packInfo.path);
+      
+      if (packAgents.length > 0 || packTasks.length > 0) {
+        // Use the actual directory name where the expansion pack is installed
+        const rootPath = path.relative(installDir, packInfo.path);
+        await this.setupClaudeCodeForPackage(installDir, packInfo.name, packSlashPrefix, packAgents, packTasks, rootPath);
+      }
+    }
 
-    for (const agentId of agents) {
-      // Find the agent file
-      const agentPath = await this.findAgentPath(agentId, installDir);
-      const commandPath = path.join(commandsDir, `${agentId}.md`);
+    return true;
+  }
+
+  async setupClaudeCodeForPackage(installDir, packageName, slashPrefix, agentIds, taskIds, rootPath) {
+    const commandsBaseDir = path.join(installDir, ".claude", "commands", slashPrefix);
+    const agentsDir = path.join(commandsBaseDir, "agents");
+    const tasksDir = path.join(commandsBaseDir, "tasks");
+
+    // Ensure directories exist
+    await fileManager.ensureDirectory(agentsDir);
+    await fileManager.ensureDirectory(tasksDir);
+
+    // Setup agents
+    for (const agentId of agentIds) {
+      // Find the agent file - for expansion packs, prefer the expansion pack version
+      let agentPath;
+      if (packageName !== "core") {
+        // For expansion packs, first try to find the agent in the expansion pack directory
+        const expansionPackPath = path.join(installDir, rootPath, "agents", `${agentId}.md`);
+        if (await fileManager.pathExists(expansionPackPath)) {
+          agentPath = expansionPackPath;
+        } else {
+          // Fall back to core if not found in expansion pack
+          agentPath = await this.findAgentPath(agentId, installDir);
+        }
+      } else {
+        // For core, use the normal search
+        agentPath = await this.findAgentPath(agentId, installDir);
+      }
+      
+      const commandPath = path.join(agentsDir, `${agentId}.md`);
 
       if (agentPath) {
         // Create command file with agent content
-        const agentContent = await fileManager.readFile(agentPath);
+        let agentContent = await fileManager.readFile(agentPath);
+        
+        // Replace {root} placeholder with the appropriate root path for this context
+        agentContent = agentContent.replace(/{root}/g, rootPath);
 
         // Add command header
         let commandContent = `# /${agentId} Command\n\n`;
@@ -151,13 +196,50 @@ class IdeSetup {
         commandContent += agentContent;
 
         await fileManager.writeFile(commandPath, commandContent);
-        console.log(chalk.green(`✓ Created command: /${agentId}`));
+        console.log(chalk.green(`✓ Created agent command: /${agentId}`));
       }
     }
 
-    console.log(chalk.green(`\n✓ Created Claude Code commands in ${commandsDir}`));
+    // Setup tasks
+    for (const taskId of taskIds) {
+      // Find the task file - for expansion packs, prefer the expansion pack version
+      let taskPath;
+      if (packageName !== "core") {
+        // For expansion packs, first try to find the task in the expansion pack directory
+        const expansionPackPath = path.join(installDir, rootPath, "tasks", `${taskId}.md`);
+        if (await fileManager.pathExists(expansionPackPath)) {
+          taskPath = expansionPackPath;
+        } else {
+          // Fall back to core if not found in expansion pack
+          taskPath = await this.findTaskPath(taskId, installDir);
+        }
+      } else {
+        // For core, use the normal search
+        taskPath = await this.findTaskPath(taskId, installDir);
+      }
+      
+      const commandPath = path.join(tasksDir, `${taskId}.md`);
 
-    return true;
+      if (taskPath) {
+        // Create command file with task content
+        let taskContent = await fileManager.readFile(taskPath);
+        
+        // Replace {root} placeholder with the appropriate root path for this context
+        taskContent = taskContent.replace(/{root}/g, rootPath);
+
+        // Add command header
+        let commandContent = `# /${taskId} Task\n\n`;
+        commandContent += `When this command is used, execute the following task:\n\n`;
+        commandContent += taskContent;
+
+        await fileManager.writeFile(commandPath, commandContent);
+        console.log(chalk.green(`✓ Created task command: /${taskId}`));
+      }
+    }
+
+    console.log(chalk.green(`\n✓ Created Claude Code commands for ${packageName} in ${commandsBaseDir}`));
+    console.log(chalk.dim(`  - Agents in: ${agentsDir}`));
+    console.log(chalk.dim(`  - Tasks in: ${tasksDir}`));
   }
 
   async setupWindsurf(installDir, selectedAgent) {
@@ -311,6 +393,49 @@ class IdeSetup {
     return [...new Set(allAgentIds)];
   }
 
+  async getCoreAgentIds(installDir) {
+    const allAgentIds = [];
+    
+    // Check core agents in .bmad-core or root only
+    let agentsDir = path.join(installDir, ".bmad-core", "agents");
+    if (!(await fileManager.pathExists(agentsDir))) {
+      agentsDir = path.join(installDir, "bmad-core", "agents");
+    }
+    
+    if (await fileManager.pathExists(agentsDir)) {
+      const glob = require("glob");
+      const agentFiles = glob.sync("*.md", { cwd: agentsDir });
+      allAgentIds.push(...agentFiles.map((file) => path.basename(file, ".md")));
+    }
+    
+    return [...new Set(allAgentIds)];
+  }
+
+  async getCoreTaskIds(installDir) {
+    const allTaskIds = [];
+    
+    // Check core tasks in .bmad-core or root only
+    let tasksDir = path.join(installDir, ".bmad-core", "tasks");
+    if (!(await fileManager.pathExists(tasksDir))) {
+      tasksDir = path.join(installDir, "bmad-core", "tasks");
+    }
+    
+    if (await fileManager.pathExists(tasksDir)) {
+      const glob = require("glob");
+      const taskFiles = glob.sync("*.md", { cwd: tasksDir });
+      allTaskIds.push(...taskFiles.map((file) => path.basename(file, ".md")));
+    }
+    
+    // Check common tasks
+    const commonTasksDir = path.join(installDir, "common", "tasks");
+    if (await fileManager.pathExists(commonTasksDir)) {
+      const commonTaskFiles = glob.sync("*.md", { cwd: commonTasksDir });
+      allTaskIds.push(...commonTaskFiles.map((file) => path.basename(file, ".md")));
+    }
+    
+    return [...new Set(allTaskIds)];
+  }
+
   async getAgentTitle(agentId, installDir) {
     // Try to find the agent file in various locations
     const possiblePaths = [
@@ -350,6 +475,194 @@ class IdeSetup {
     ).join(' ');
   }
 
+  async getAllTaskIds(installDir) {
+    const glob = require("glob");
+    const allTaskIds = [];
+    
+    // Check core tasks in .bmad-core or root
+    let tasksDir = path.join(installDir, ".bmad-core", "tasks");
+    if (!(await fileManager.pathExists(tasksDir))) {
+      tasksDir = path.join(installDir, "bmad-core", "tasks");
+    }
+    
+    if (await fileManager.pathExists(tasksDir)) {
+      const taskFiles = glob.sync("*.md", { cwd: tasksDir });
+      allTaskIds.push(...taskFiles.map((file) => path.basename(file, ".md")));
+    }
+    
+    // Check common tasks
+    const commonTasksDir = path.join(installDir, "common", "tasks");
+    if (await fileManager.pathExists(commonTasksDir)) {
+      const commonTaskFiles = glob.sync("*.md", { cwd: commonTasksDir });
+      allTaskIds.push(...commonTaskFiles.map((file) => path.basename(file, ".md")));
+    }
+    
+    // Also check for expansion pack tasks in dot folders
+    const expansionDirs = glob.sync(".*/tasks", { cwd: installDir });
+    for (const expDir of expansionDirs) {
+      const fullExpDir = path.join(installDir, expDir);
+      const expTaskFiles = glob.sync("*.md", { cwd: fullExpDir });
+      allTaskIds.push(...expTaskFiles.map((file) => path.basename(file, ".md")));
+    }
+    
+    // Check expansion-packs folder tasks
+    const expansionPacksDir = path.join(installDir, "expansion-packs");
+    if (await fileManager.pathExists(expansionPacksDir)) {
+      const expPackDirs = glob.sync("*/tasks", { cwd: expansionPacksDir });
+      for (const expDir of expPackDirs) {
+        const fullExpDir = path.join(expansionPacksDir, expDir);
+        const expTaskFiles = glob.sync("*.md", { cwd: fullExpDir });
+        allTaskIds.push(...expTaskFiles.map((file) => path.basename(file, ".md")));
+      }
+    }
+    
+    // Remove duplicates
+    return [...new Set(allTaskIds)];
+  }
+
+  async findTaskPath(taskId, installDir) {
+    // Try to find the task file in various locations
+    const possiblePaths = [
+      path.join(installDir, ".bmad-core", "tasks", `${taskId}.md`),
+      path.join(installDir, "bmad-core", "tasks", `${taskId}.md`),
+      path.join(installDir, "common", "tasks", `${taskId}.md`)
+    ];
+    
+    // Also check expansion pack directories
+    const glob = require("glob");
+    
+    // Check dot folder expansion packs
+    const expansionDirs = glob.sync(".*/tasks", { cwd: installDir });
+    for (const expDir of expansionDirs) {
+      possiblePaths.push(path.join(installDir, expDir, `${taskId}.md`));
+    }
+    
+    // Check expansion-packs folder
+    const expansionPacksDir = path.join(installDir, "expansion-packs");
+    if (await fileManager.pathExists(expansionPacksDir)) {
+      const expPackDirs = glob.sync("*/tasks", { cwd: expansionPacksDir });
+      for (const expDir of expPackDirs) {
+        possiblePaths.push(path.join(expansionPacksDir, expDir, `${taskId}.md`));
+      }
+    }
+    
+    for (const taskPath of possiblePaths) {
+      if (await fileManager.pathExists(taskPath)) {
+        return taskPath;
+      }
+    }
+    
+    return null;
+  }
+
+  async getCoreSlashPrefix(installDir) {
+    try {
+      const coreConfigPath = path.join(installDir, ".bmad-core", "core-config.yaml");
+      if (!(await fileManager.pathExists(coreConfigPath))) {
+        // Try bmad-core directory
+        const altConfigPath = path.join(installDir, "bmad-core", "core-config.yaml");
+        if (await fileManager.pathExists(altConfigPath)) {
+          const configContent = await fileManager.readFile(altConfigPath);
+          const config = yaml.load(configContent);
+          return config.slashPrefix || "BMad";
+        }
+        return "BMad"; // fallback
+      }
+      
+      const configContent = await fileManager.readFile(coreConfigPath);
+      const config = yaml.load(configContent);
+      return config.slashPrefix || "BMad";
+    } catch (error) {
+      console.warn(`Failed to read core slashPrefix, using default 'BMad': ${error.message}`);
+      return "BMad";
+    }
+  }
+
+  async getInstalledExpansionPacks(installDir) {
+    const expansionPacks = [];
+    
+    // Check for dot-prefixed expansion packs in install directory
+    const glob = require("glob");
+    const dotExpansions = glob.sync(".bmad-*", { cwd: installDir });
+    
+    for (const dotExpansion of dotExpansions) {
+      if (dotExpansion !== ".bmad-core") {
+        const packPath = path.join(installDir, dotExpansion);
+        const packName = dotExpansion.substring(1); // remove the dot
+        expansionPacks.push({
+          name: packName,
+          path: packPath
+        });
+      }
+    }
+    
+    // Check for expansion-packs directory style
+    const expansionPacksDir = path.join(installDir, "expansion-packs");
+    if (await fileManager.pathExists(expansionPacksDir)) {
+      const packDirs = glob.sync("*", { cwd: expansionPacksDir });
+      
+      for (const packDir of packDirs) {
+        const packPath = path.join(expansionPacksDir, packDir);
+        if ((await fileManager.pathExists(packPath)) && 
+            (await fileManager.pathExists(path.join(packPath, "config.yaml")))) {
+          expansionPacks.push({
+            name: packDir,
+            path: packPath
+          });
+        }
+      }
+    }
+    
+    return expansionPacks;
+  }
+
+  async getExpansionPackSlashPrefix(packPath) {
+    try {
+      const configPath = path.join(packPath, "config.yaml");
+      if (await fileManager.pathExists(configPath)) {
+        const configContent = await fileManager.readFile(configPath);
+        const config = yaml.load(configContent);
+        return config.slashPrefix || path.basename(packPath);
+      }
+    } catch (error) {
+      console.warn(`Failed to read expansion pack slashPrefix from ${packPath}: ${error.message}`);
+    }
+    
+    return path.basename(packPath); // fallback to directory name
+  }
+
+  async getExpansionPackAgents(packPath) {
+    const agentsDir = path.join(packPath, "agents");
+    if (!(await fileManager.pathExists(agentsDir))) {
+      return [];
+    }
+    
+    try {
+      const glob = require("glob");
+      const agentFiles = glob.sync("*.md", { cwd: agentsDir });
+      return agentFiles.map(file => path.basename(file, ".md"));
+    } catch (error) {
+      console.warn(`Failed to read expansion pack agents from ${packPath}: ${error.message}`);
+      return [];
+    }
+  }
+
+  async getExpansionPackTasks(packPath) {
+    const tasksDir = path.join(packPath, "tasks");
+    if (!(await fileManager.pathExists(tasksDir))) {
+      return [];
+    }
+    
+    try {
+      const glob = require("glob");
+      const taskFiles = glob.sync("*.md", { cwd: tasksDir });
+      return taskFiles.map(file => path.basename(file, ".md"));
+    } catch (error) {
+      console.warn(`Failed to read expansion pack tasks from ${packPath}: ${error.message}`);
+      return [];
+    }
+  }
+
   async setupRoo(installDir, selectedAgent) {
     const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
 
@@ -509,15 +822,56 @@ class IdeSetup {
     return true;
   }
 
-  async setupGeminiCli(installDir, selectedAgent) {
+  async setupGeminiCli(installDir) {
     await initializeModules();
     const geminiDir = path.join(installDir, ".gemini");
-    const agentsContextDir = path.join(geminiDir, "agents");
-    await fileManager.ensureDirectory(agentsContextDir);
+    const bmadMethodDir = path.join(geminiDir, "bmad-method");
+    await fileManager.ensureDirectory(bmadMethodDir);
+
+    // Update logic for existing settings.json
+    const settingsPath = path.join(geminiDir, "settings.json");
+    if (await fileManager.pathExists(settingsPath)) {
+      try {
+        const settingsContent = await fileManager.readFile(settingsPath);
+        const settings = JSON.parse(settingsContent);
+        let updated = false;
+        
+        // Handle contextFileName property
+        if (settings.contextFileName && Array.isArray(settings.contextFileName)) {
+          const originalLength = settings.contextFileName.length;
+          settings.contextFileName = settings.contextFileName.filter(
+            (fileName) => !fileName.startsWith("agents/")
+          );
+          if (settings.contextFileName.length !== originalLength) {
+            updated = true;
+          }
+        }
+        
+        if (updated) {
+          await fileManager.writeFile(
+            settingsPath,
+            JSON.stringify(settings, null, 2)
+          );
+          console.log(chalk.green("✓ Updated .gemini/settings.json - removed agent file references"));
+        }
+      } catch (error) {
+        console.warn(
+          chalk.yellow("Could not update .gemini/settings.json"),
+          error
+        );
+      }
+    }
+
+    // Remove old agents directory
+    const agentsDir = path.join(geminiDir, "agents");
+    if (await fileManager.pathExists(agentsDir)) {
+      await fileManager.removeDirectory(agentsDir);
+      console.log(chalk.green("✓ Removed old .gemini/agents directory"));
+    }
 
     // Get all available agents
     const agents = await this.getAllAgentIds(installDir);
-    const agentContextFiles = [];
+    let concatenatedContent = "";
 
     for (const agentId of agents) {
       // Find the source agent file
@@ -525,52 +879,55 @@ class IdeSetup {
 
       if (agentPath) {
         const agentContent = await fileManager.readFile(agentPath);
-        const contextFilePath = path.join(agentsContextDir, `${agentId}.md`);
-
-        // Copy the agent content directly into its own context file
-        await fileManager.writeFile(contextFilePath, agentContent);
-
-        // Store the relative path for settings.json
-        const relativePath = path.relative(geminiDir, contextFilePath);
-        agentContextFiles.push(relativePath.replace(/\\/g, '/')); // Ensure forward slashes for consistency
-        console.log(chalk.green(`✓ Created context file for @${agentId}`));
+        
+        // Create properly formatted agent rule content (similar to trae)
+        let agentRuleContent = `# ${agentId.toUpperCase()} Agent Rule\n\n`;
+        agentRuleContent += `This rule is triggered when the user types \`*${agentId}\` and activates the ${await this.getAgentTitle(
+          agentId,
+          installDir
+        )} agent persona.\n\n`;
+        agentRuleContent += "## Agent Activation\n\n";
+        agentRuleContent +=
+          "CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:\n\n";
+        agentRuleContent += "```yaml\n";
+        // Extract just the YAML content from the agent file
+        const yamlContent = extractYamlFromAgent(agentContent);
+        if (yamlContent) {
+          agentRuleContent += yamlContent;
+        }
+        else {
+          // If no YAML found, include the whole content minus the header
+          agentRuleContent += agentContent.replace(/^#.*$/m, "").trim();
+        }
+        agentRuleContent += "\n```\n\n";
+        agentRuleContent += "## File Reference\n\n";
+        const relativePath = path.relative(installDir, agentPath).replace(/\\/g, '/');
+        agentRuleContent += `The complete agent definition is available in [${relativePath}](${relativePath}).\n\n`;
+        agentRuleContent += "## Usage\n\n";
+        agentRuleContent += `When the user types \`*${agentId}\`, activate this ${await this.getAgentTitle(
+          agentId,
+          installDir
+        )} persona and follow all instructions defined in the YAML configuration above.\n`;
+        
+        // Add to concatenated content with separator
+        concatenatedContent += agentRuleContent + "\n\n---\n\n";
+        console.log(chalk.green(`✓ Added context for @${agentId}`));
       }
     }
 
-    console.log(chalk.green(`\n✓ Created individual agent context files in ${agentsContextDir}`));
-
-    // Add GEMINI.md to the context files array
-    agentContextFiles.push("GEMINI.md");
-
-    // Create or update settings.json
-    const settingsPath = path.join(geminiDir, "settings.json");
-    let settings = {};
-
-    if (await fileManager.pathExists(settingsPath)) {
-      try {
-        const existingSettings = await fileManager.readFile(settingsPath);
-        settings = JSON.parse(existingSettings);
-        console.log(chalk.yellow("Found existing .gemini/settings.json. Merging settings..."));
-      } catch (e) {
-        console.error(chalk.red("Error parsing existing settings.json. It will be overwritten."), e);
-        settings = {};
-      }
-    }
-
-    // Set contextFileName to our new array of files
-    settings.contextFileName = agentContextFiles;
-
-    await fileManager.writeFile(settingsPath, JSON.stringify(settings, null, 2));
-    console.log(chalk.green(`✓ Configured .gemini/settings.json to load all agent context files.`));
+    // Write the concatenated content to GEMINI.md
+    const geminiMdPath = path.join(bmadMethodDir, "GEMINI.md");
+    await fileManager.writeFile(geminiMdPath, concatenatedContent);
+    console.log(chalk.green(`\n✓ Created GEMINI.md in ${bmadMethodDir}`));
 
     return true;
   }
 
-  async setupGitHubCopilot(installDir, selectedAgent, spinner = null) {
+  async setupGitHubCopilot(installDir, selectedAgent, spinner = null, preConfiguredSettings = null) {
     await initializeModules();
     
     // Configure VS Code workspace settings first to avoid UI conflicts with loading spinners
-    await this.configureVsCodeSettings(installDir, spinner);
+    await this.configureVsCodeSettings(installDir, spinner, preConfiguredSettings);
     
     const chatmodesDir = path.join(installDir, ".github", "chatmodes");
     const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
@@ -616,7 +973,7 @@ tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems
     return true;
   }
 
-  async configureVsCodeSettings(installDir, spinner) {
+  async configureVsCodeSettings(installDir, spinner, preConfiguredSettings = null) {
     await initializeModules(); // Ensure inquirer is loaded
     const vscodeDir = path.join(installDir, ".vscode");
     const settingsPath = path.join(vscodeDir, "settings.json");
@@ -636,34 +993,42 @@ tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems
       }
     }
     
-    // Clear any previous output and add spacing to avoid conflicts with loaders
-    console.log('\n'.repeat(2));
-    console.log(chalk.blue("🔧 Github Copilot Agent Settings Configuration"));
-    console.log(chalk.dim("BMad works best with specific VS Code settings for optimal agent experience."));
-    console.log(''); // Add extra spacing
-    
-    const { configChoice } = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'configChoice',
-        message: 'How would you like to configure Github Copilot settings?',
-        choices: [
-          {
-            name: 'Use recommended defaults (fastest setup)',
-            value: 'defaults'
-          },
-          {
-            name: 'Configure each setting manually (customize to your preferences)',
-            value: 'manual'
-          },
-          {
-            name: 'Skip settings configuration (I\'ll configure manually later)\n',
-            value: 'skip'
-          }
-        ],
-        default: 'defaults'
-      }
-    ]);
+    // Use pre-configured settings if provided, otherwise prompt
+    let configChoice;
+    if (preConfiguredSettings && preConfiguredSettings.configChoice) {
+      configChoice = preConfiguredSettings.configChoice;
+      console.log(chalk.dim(`Using pre-configured GitHub Copilot settings: ${configChoice}`));
+    } else {
+      // Clear any previous output and add spacing to avoid conflicts with loaders
+      console.log('\n'.repeat(2));
+      console.log(chalk.blue("🔧 Github Copilot Agent Settings Configuration"));
+      console.log(chalk.dim("BMad works best with specific VS Code settings for optimal agent experience."));
+      console.log(''); // Add extra spacing
+      
+      const response = await inquirer.prompt([
+        {
+          type: 'list',
+          name: 'configChoice',
+          message: chalk.yellow('How would you like to configure GitHub Copilot settings?'),
+          choices: [
+            {
+              name: 'Use recommended defaults (fastest setup)',
+              value: 'defaults'
+            },
+            {
+              name: 'Configure each setting manually (customize to your preferences)',
+              value: 'manual'
+            },
+            {
+              name: 'Skip settings configuration (I\'ll configure manually later)',
+              value: 'skip'
+            }
+          ],
+          default: 'defaults'
+        }
+      ]);
+      configChoice = response.configChoice;
+    }
     
     let bmadSettings = {};
     

tools/installer/lib/installer.js

@@ -244,7 +244,7 @@ class Installer {
       spinner.text = "Copying complete .bmad-core folder...";
       const sourceDir = configLoader.getBmadCorePath();
       const bmadCoreDestDir = path.join(installDir, ".bmad-core");
-      await fileManager.copyDirectory(sourceDir, bmadCoreDestDir);
+      await fileManager.copyDirectoryWithRootReplacement(sourceDir, bmadCoreDestDir, ".bmad-core");
       
       // Copy common/ items to .bmad-core
       spinner.text = "Copying common utilities...";
@@ -263,7 +263,7 @@ class Installer {
       // Single agent installation
       spinner.text = `Installing ${config.agent} agent...`;
 
-      // Copy agent file
+      // Copy agent file with {root} replacement
       const agentPath = configLoader.getAgentPath(config.agent);
       const destAgentPath = path.join(
         installDir,
@@ -271,7 +271,7 @@ class Installer {
         "agents",
         `${config.agent}.md`
       );
-      await fileManager.copyFile(agentPath, destAgentPath);
+      await fileManager.copyFileWithRootReplacement(agentPath, destAgentPath, ".bmad-core");
       files.push(`.bmad-core/agents/${config.agent}.md`);
 
       // Copy dependencies
@@ -284,15 +284,16 @@ class Installer {
         spinner.text = `Copying dependency: ${dep}`;
 
         if (dep.includes("*")) {
-          // Handle glob patterns
+          // Handle glob patterns with {root} replacement
           const copiedFiles = await fileManager.copyGlobPattern(
             dep.replace(".bmad-core/", ""),
             sourceBase,
-            path.join(installDir, ".bmad-core")
+            path.join(installDir, ".bmad-core"),
+            ".bmad-core"
           );
           files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
         } else {
-          // Handle single files
+          // Handle single files with {root} replacement if needed
           const sourcePath = path.join(
             sourceBase,
             dep.replace(".bmad-core/", "")
@@ -302,7 +303,16 @@ class Installer {
             dep
           );
 
-          if (await fileManager.copyFile(sourcePath, destPath)) {
+          const needsRootReplacement = dep.endsWith('.md') || dep.endsWith('.yaml') || dep.endsWith('.yml');
+          let success = false;
+          
+          if (needsRootReplacement) {
+            success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, ".bmad-core");
+          } else {
+            success = await fileManager.copyFile(sourcePath, destPath);
+          }
+
+          if (success) {
             files.push(dep);
           }
         }
@@ -325,19 +335,29 @@ class Installer {
         spinner.text = `Copying team dependency: ${dep}`;
         
         if (dep.includes("*")) {
-          // Handle glob patterns
+          // Handle glob patterns with {root} replacement
           const copiedFiles = await fileManager.copyGlobPattern(
             dep.replace(".bmad-core/", ""),
             sourceBase,
-            path.join(installDir, ".bmad-core")
+            path.join(installDir, ".bmad-core"),
+            ".bmad-core"
           );
           files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
         } else {
-          // Handle single files
+          // Handle single files with {root} replacement if needed
           const sourcePath = path.join(sourceBase, dep.replace(".bmad-core/", ""));
           const destPath = path.join(installDir, dep);
           
-          if (await fileManager.copyFile(sourcePath, destPath)) {
+          const needsRootReplacement = dep.endsWith('.md') || dep.endsWith('.yaml') || dep.endsWith('.yml');
+          let success = false;
+          
+          if (needsRootReplacement) {
+            success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, ".bmad-core");
+          } else {
+            success = await fileManager.copyFile(sourcePath, destPath);
+          }
+
+          if (success) {
             files.push(dep);
           }
         }
@@ -373,10 +393,17 @@ class Installer {
     if (ides.length > 0) {
       for (const ide of ides) {
         spinner.text = `Setting up ${ide} integration...`;
-        await ideSetup.setup(ide, installDir, config.agent, spinner);
+        const preConfiguredSettings = ide === 'github-copilot' ? config.githubCopilotConfig : null;
+        await ideSetup.setup(ide, installDir, config.agent, spinner, preConfiguredSettings);
       }
     }
 
+    // Modify core-config.yaml if sharding preferences were provided
+    if (config.installType !== "expansion-only" && (config.prdSharded !== undefined || config.architectureSharded !== undefined)) {
+      spinner.text = "Configuring document sharding settings...";
+      await fileManager.modifyCoreConfig(installDir, config);
+    }
+
     // Create manifest (skip for expansion-only installations)
     if (config.installType !== "expansion-only") {
       spinner.text = "Creating installation manifest...";
@@ -1165,32 +1192,41 @@ class Installer {
               nodir: true
             });
 
-            // Copy each file to the expansion pack's dot folder
+            // Copy each file to the expansion pack's dot folder with {root} replacement
             for (const file of files) {
               const sourcePath = path.join(sourceFolder, file);
               const destPath = path.join(expansionDotFolder, folder, file);
               
-              if (await fileManager.copyFile(sourcePath, destPath)) {
+              const needsRootReplacement = file.endsWith('.md') || file.endsWith('.yaml') || file.endsWith('.yml');
+              let success = false;
+              
+              if (needsRootReplacement) {
+                success = await fileManager.copyFileWithRootReplacement(sourcePath, destPath, `.${packId}`);
+              } else {
+                success = await fileManager.copyFile(sourcePath, destPath);
+              }
+              
+              if (success) {
                 installedFiles.push(path.join(`.${packId}`, folder, file));
               }
             }
           }
         }
 
-        // Copy config.yaml
+        // Copy config.yaml with {root} replacement
         const configPath = path.join(expansionPackDir, 'config.yaml');
         if (await fileManager.pathExists(configPath)) {
           const configDestPath = path.join(expansionDotFolder, 'config.yaml');
-          if (await fileManager.copyFile(configPath, configDestPath)) {
+          if (await fileManager.copyFileWithRootReplacement(configPath, configDestPath, `.${packId}`)) {
             installedFiles.push(path.join(`.${packId}`, 'config.yaml'));
           }
         }
         
-        // Copy README if it exists
+        // Copy README if it exists with {root} replacement
         const readmePath = path.join(expansionPackDir, 'README.md');
         if (await fileManager.pathExists(readmePath)) {
           const readmeDestPath = path.join(expansionDotFolder, 'README.md');
-          if (await fileManager.copyFile(readmePath, readmeDestPath)) {
+          if (await fileManager.copyFileWithRootReplacement(readmePath, readmeDestPath, `.${packId}`)) {
             installedFiles.push(path.join(`.${packId}`, 'README.md'));
           }
         }
@@ -1251,7 +1287,7 @@ class Installer {
       const yamlContent = extractYamlFromAgent(agentContent);
       if (yamlContent) {
         try {
-          const agentConfig = yaml.parse(yamlContent);
+          const agentConfig = yaml.load(yamlContent);
           const dependencies = agentConfig.dependencies || {};
           
           // Check for core dependencies (those that don't exist in the expansion pack)
@@ -1270,9 +1306,9 @@ class Installer {
                 if (await fileManager.pathExists(coreDepPath)) {
                   spinner.text = `Copying core dependency ${dep} for ${packId}...`;
                   
-                  // Copy from core to expansion pack dot folder
+                  // Copy from core to expansion pack dot folder with {root} replacement
                   const destPath = path.join(expansionDotFolder, depType, depFileName);
-                  await fileManager.copyFile(coreDepPath, destPath);
+                  await fileManager.copyFileWithRootReplacement(coreDepPath, destPath, `.${packId}`);
                   
                   console.log(chalk.dim(`  Added core dependency: ${depType}/${depFileName}`));
                 } else {
@@ -1314,7 +1350,7 @@ class Installer {
       const teamContent = await fs.readFile(teamPath, 'utf8');
       
       try {
-        const teamConfig = yaml.parse(teamContent);
+        const teamConfig = yaml.load(teamContent);
         const agents = teamConfig.agents || [];
         
         // Add bmad-orchestrator if not present (required for all teams)
@@ -1331,9 +1367,9 @@ class Installer {
             if (await fileManager.pathExists(coreAgentPath)) {
               spinner.text = `Copying core agent ${agentId} for ${packId}...`;
               
-              // Copy agent file
+              // Copy agent file with {root} replacement
               const destPath = path.join(expansionDotFolder, 'agents', `${agentId}.md`);
-              await fileManager.copyFile(coreAgentPath, destPath);
+              await fileManager.copyFileWithRootReplacement(coreAgentPath, destPath, `.${packId}`);
               existingAgents.add(agentId);
               
               console.log(chalk.dim(`  Added core agent: ${agentId}`));
@@ -1345,7 +1381,7 @@ class Installer {
               if (yamlContent) {
                 try {
                   
-                  const agentConfig = yaml.parse(yamlContent);
+                  const agentConfig = yaml.load(yamlContent);
                   const dependencies = agentConfig.dependencies || {};
                   
                   // Copy all dependencies for this agent
@@ -1363,7 +1399,7 @@ class Installer {
                         
                         if (await fileManager.pathExists(coreDepPath)) {
                           const destDepPath = path.join(expansionDotFolder, depType, depFileName);
-                          await fileManager.copyFile(coreDepPath, destDepPath);
+                          await fileManager.copyFileWithRootReplacement(coreDepPath, destDepPath, `.${packId}`);
                           console.log(chalk.dim(`    Added agent dependency: ${depType}/${depFileName}`));
                         } else {
                           // Try common folder

tools/installer/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.27.1",
+  "version": "4.29.0",
   "description": "BMad Method installer - AI-powered Agile development framework",
   "main": "lib/installer.js",
   "bin": {

tools/upgraders/v3-to-v4-upgrader.js

@@ -558,7 +558,7 @@ class V3ToV4Upgrader {
     try {
       const ideMessages = {
         cursor: "Rules created in .cursor/rules/",
-        "claude-code": "Commands created in .claude/commands/",
+        "claude-code": "Commands created in .claude/commands/BMad/",
         windsurf: "Rules created in .windsurf/rules/",
         trae: "Rules created in.trae/rules/",
         roo: "Custom modes created in .roomodes",