chore(release): 4.23.0 [skip ci]

# [4.23.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.22.1...v4.23.0) (2025-07-01)

### Features

* VS Code Copilot integration ([#284](https://github.com/bmadcode/BMAD-METHOD/issues/284)) ([1a4ca4f](1a4ca4ffa6))

.gitignore

@@ -19,4 +19,9 @@ Thumbs.db
 CLAUDE.md
 .ai/*
 test-project-install/*
-sample-project/*
+sample-project/*
+.claude
+.bmad-core
+.bmad-creator-tools
+.gemini
+.bmad*/

CHANGELOG.md

@@ -1,3 +1,50 @@
+# [4.23.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.22.1...v4.23.0) (2025-07-01)
+
+
+### Features
+
+* VS Code Copilot integration ([#284](https://github.com/bmadcode/BMAD-METHOD/issues/284)) ([1a4ca4f](https://github.com/bmadcode/BMAD-METHOD/commit/1a4ca4ffa630c2d4156bdd7a040d4c2274801757))
+
+## [4.22.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.22.0...v4.22.1) (2025-06-30)
+
+
+### Bug Fixes
+
+* update expansion versions ([6905fe7](https://github.com/bmadcode/BMAD-METHOD/commit/6905fe72f6c2abefbfd65729d1be85752130a1d2))
+
+# [4.22.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.21.2...v4.22.0) (2025-06-30)
+
+
+### Features
+
+* create doc more explicit and readme improvement ([a1b30d9](https://github.com/bmadcode/BMAD-METHOD/commit/a1b30d9341d2ceff79db2c7e178860c5ef0d99e5))
+
+## [4.21.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.21.1...v4.21.2) (2025-06-30)
+
+
+### Bug Fixes
+
+* improve create-doc task clarity for template execution ([86d5139](https://github.com/bmadcode/BMAD-METHOD/commit/86d5139aea7097cc5d4ee9da0f7d3e395ce0835e))
+
+## [4.21.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.21.0...v4.21.1) (2025-06-30)
+
+
+### Bug Fixes
+
+* readme clarifies that the installer handles installs upgrades and expansion installation ([9371a57](https://github.com/bmadcode/BMAD-METHOD/commit/9371a5784f6a6f2ad358a72ea0cde9c980357167))
+
+# [4.21.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.20.0...v4.21.0) (2025-06-30)
+
+
+### Bug Fixes
+
+* remove unneeded files ([c48f200](https://github.com/bmadcode/BMAD-METHOD/commit/c48f200727384f37a42f4c6b1a946cb90f2445fe))
+
+
+### Features
+
+* massive installer improvement update ([c151bda](https://github.com/bmadcode/BMAD-METHOD/commit/c151bda93833aa310ccc7c0eabcf483376f9e82a))
+
 # [4.20.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.19.2...v4.20.0) (2025-06-29)
 
 

CONTRIBUTING.md

@@ -8,6 +8,11 @@ Thank you for considering contributing to this project! This document outlines t
 
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
+💬 **Discord Community**: Join our [Discord server](https://discord.gg/g6ypHytrCB) for real-time discussions:
+
+- **#general-dev** - Technical discussions, feature ideas, and development questions
+- **#bugs-issues** - Bug reports and issue discussions
+
 ## Code of Conduct
 
 By participating in this project, you agree to abide by our Code of Conduct. Please read it before participating.
@@ -16,16 +21,35 @@ By participating in this project, you agree to abide by our Code of Conduct. Ple
 
 ### Reporting Bugs
 
-- Check if the bug has already been reported in the Issues section
+1. **Check existing issues** first to avoid duplicates
-- Include detailed steps to reproduce the bug
+2. **Use the bug report template** when creating a new issue - it will guide you through providing:
-- Include any relevant logs or screenshots
+   - Clear bug description
+   - Steps to reproduce
+   - Expected vs actual behavior
+   - Model/IDE/BMad version details
+   - Screenshots or links if applicable
+3. **Consider discussing in Discord** (#bugs-issues channel) for quick help
+4. **Indicate if you're working on a fix** to avoid duplicate efforts
 
 ### Suggesting Features
 
-- Check if the feature has already been suggested in the Issues section, and consider using the discussions tab in GitHub also. Explain the feature in detail and why it would be valuable.
+1. **Discuss first in Discord** (#general-dev channel) - the feature request template asks if you've done this
+2. **Check existing issues and discussions** to avoid duplicates
+3. **Use the feature request template** when creating an issue - it will guide you through:
+   - Confirming Discord discussion
+   - Describing the problem it solves
+   - Explaining your solution
+   - Listing alternatives considered
+4. **Be specific** about why this feature would benefit the BMad community
 
 ### Pull Request Process
 
+⚠️ **Before starting work:**
+
+1. **For bugs**: Check if an issue exists (create one using the bug template if not)
+2. **For features**: Ensure you've discussed in Discord (#general-dev) AND created a feature request issue
+3. **For large changes**: Always open an issue first to discuss alignment
+
 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:
@@ -95,6 +119,15 @@ Example breakdown:
 6. Push to your branch (`git push origin feature/your-feature-name`)
 7. Open a Pull Request against the main branch
 
+## Issue Templates
+
+We use GitHub issue templates to ensure all necessary information is provided:
+
+- **Bug Reports**: Automatically guides you through providing reproduction steps, environment details, and expected behavior
+- **Feature Requests**: Requires Discord discussion confirmation and asks for problem/solution descriptions
+
+Using these templates helps maintainers understand and address your contribution faster.
+
 ## Pull Request Description Guidelines
 
 Keep PR descriptions short and to the point following this template:
@@ -111,6 +144,7 @@ Keep your PR description concise and focused. Use this template:
 ## Why
 
 [1-2 sentences explaining WHY this change is needed]
+Fixes #[issue number] (if applicable)
 
 ## How
 

README.md

@@ -13,7 +13,7 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
 
 ⭐ **If you find this project helpful or useful, please give it a star in the upper right hand corner!** It helps others discover BMad-METHOD and you will be notified of updates!
 
-## 🧭 Quick Navigation - Find Your Path
+## Quick Navigation
 
 ### 🚨 MUST READ: Understanding the BMAD Workflow
 
@@ -50,13 +50,14 @@ Foundations in Agentic Agile Driven Development, known as the Breakthrough Metho
 - **[Contributing](#contributing)** → Help improve BMAD
 - **[Support](#support)** → Get help and connect
 
-## 🔄 Important: Keeping Your BMad Installation Updated
+## Important: Keep Your BMad Installation Updated
 
 **Stay up-to-date effortlessly!** If you already have BMad-METHOD installed in your project, simply run:
 
 ```bash
 npx bmad-method install
 # OR
+git pull
 npm run install:bmad
 ```
 
@@ -69,32 +70,45 @@ This will:
 
 This makes it easy to benefit from the latest improvements, bug fixes, and new agents without losing your customizations! If for some reason this fails, you can rename or remove your .bmad-code folder and run the install again. The main thing to look out for is if you have set up custom modes that are not file driven (Cursor is the only one at this time that is not done through project files lagging behind) - you will want to ensure your sm and dev custom modes especially are kept up to date.
 
-## 🚀 Quick Start
+## Quick Start
 
-### Fastest Start: Web UI (2 minutes) 🏃‍♂️
+### One Command for Everything (IDE Installation)
+
+**Just run one of these commands:**
+
+```bash
+npx bmad-method install
+# OR if you already have BMad installed:
+git pull
+npm run install:bmad
+```
+
+This single command handles:
+
+- **New installations** - Sets up BMad in your project
+- **Upgrades** - Updates existing installations automatically
+- **Expansion packs** - Installs any expansion packs you've added to package.json
+
+> **That's it!** Whether you're installing for the first time, upgrading, or adding expansion packs - these commands do everything.
+
+**Prerequisites**: [Node.js](https://nodejs.org) v20+ required
+
+### Fastest Start: Web UI (2 minutes)
 
 1. **Get the bundle**: Copy `dist/teams/team-fullstack.txt` (from this repository)
 2. **Create AI agent**: Create a new Gemini Gem or CustomGPT
 3. **Upload & configure**: Upload the file and set instructions: "Your critical operating instructions are attached, do not break character as directed"
 4. **Start Ideating and Planning**: Start chatting! Type `*help` to see available commands or pick an agent like `*analyst` to start right in on creating a brief.
 
-> 💡 **All pre-built bundles are in the `dist/` folder** - ready to copy and use immediately!
+> **All pre-built bundles are in the `dist/` folder** - ready to copy and use immediately!
 
-### IDE Quick Start (5 minutes) 💻
+### Alternative: Clone and Build
-
-**Prerequisites**: Install [Node.js](https://nodejs.org) (v20 or higher)
-
-Run `npx bmad-method install`
-
-OR
 
 ```bash
 git clone https://github.com/bmadcode/bmad-method.git
 npm run install:bmad # build and install all to a destination folder
 ```
 
-This installs all agents and configures them for your IDE. If you have an existing v3 installation, it will offer to upgrade it automatically.
-
 ## Overview
 
 The BMad Method (Breakthrough Method of Agile Agentic-Driven Development) elevates 'Vibe Coding' by providing specialized AI agents for every role in an Agile team. Each agent has deep expertise in their domain helping you really plan and execute on your vision while keeping the agents on the rails even through complex application plans.
@@ -103,7 +117,25 @@ Unlike systems like Task Master, or inbuilt Task tool, the BMad Methods agile fl
 
 ## Installation
 
-### Method 1: Pre-Built Web Bundles (Fastest) 📦
+### Method 1: CLI Installer (For IDEs)
+
+**Just run one command:**
+
+```bash
+npx bmad-method install
+# OR if you already have BMad installed:
+npm run install:bmad
+```
+
+**This single command does everything:**
+
+- Installs BMad for the first time
+- Updates existing installations
+- Adds any expansion packs from your package.json
+
+**Prerequisites**: Install [Node.js](https://nodejs.org) v20+ first
+
+### Method 2: Pre-Built Web Bundles (For Web UI)
 
 For ChatGPT, Claude, or Gemini web interfaces:
 
@@ -114,12 +146,6 @@ For ChatGPT, Claude, or Gemini web interfaces:
 3. Set instructions: "Your critical operating instructions are attached, do not break character as directed"
 4. Type `/help` to see available commands
 
-### Method 2: CLI Installer (For IDEs) 🎯
-
-**Prerequisites**: Install [Node.js](https://nodejs.org) v20+ first
-
-Install directly into your project: `npx bmad-method install`
-
 **Supported IDEs:**
 
 The BMad Method works with any IDE, but has built-in integration for:
@@ -130,7 +156,7 @@ The BMad Method works with any IDE, but has built-in integration for:
 - `gemini-cli` - Gemini with @agent commands
 - `windsurf` - Windsurf with manual rule @agent commands
 - `roo` - Roo Code with custom modes (see `.roomodes`)
-- `windsurf` - Windsurf with @agent commands
+- `vs-code-copilot` - VS Code with GitHub Copilot agent mode integration
 
 ## Available Agents
 
@@ -264,6 +290,7 @@ See the **[Core Architecture](docs/core-architecture.md)** for the complete sour
 - 🦘 [Roo Code Guide](docs/agentic-tools/roo-code-guide.md) - Setup and usage for Roo Code
 - 🔧 [Cline Guide](docs/agentic-tools/cline-guide.md) - Setup and usage for Cline (VS Code)
 - ✨ [Gemini CLI Guide](docs/agentic-tools/gemini-cli-guide.md) - Setup and usage for Gemini CLI
+- 💻 [VS Code Copilot Guide](docs/agentic-tools/vs-code-copilot-guide.md) - Setup and usage for VS Code with GitHub Copilot
 
 ## 🌟 Beyond Software Development - Expansion Packs
 

bmad-core/core-config.yml

@@ -1,3 +1,4 @@
+version: 4.21.1
 markdownExploder: true
 prd:
   prdFile: docs/prd.md

bmad-core/data/bmad-kb.md

@@ -78,7 +78,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)
@@ -93,6 +93,7 @@ npx bmad-method install
   - **Windsurf**: Built-in AI capabilities
   - **Cline**: VS Code extension with AI features
   - **Roo Code**: Web-based IDE with agent support
+  - **VS Code Copilot**: AI-powered coding assistant
 
 **Note for VS Code Users**: BMAD-METHOD assumes when you mention "VS Code" that you're using it with an AI-powered extension like GitHub Copilot, Cline, or Roo. Standard VS Code without AI capabilities cannot run BMAD agents. The installer includes built-in support for Cline and Roo.
 
@@ -278,6 +279,7 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 - **Cursor**: `@agent-name` (e.g., `@bmad-master`)
 - **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
 - **Roo Code**: Select mode from mode selector (e.g., `bmad-bmad-master`)
+- **VS Code Copilot**: Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.
 
 **Chat Management Guidelines**:
 - **Claude Code, Cursor, Windsurf**: Start new chats when switching agents

common/tasks/create-doc.md

@@ -2,73 +2,70 @@
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.

dist/agents/analyst.txt

@@ -652,76 +652,73 @@ Present these numbered options to the user:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#advanced-elicitation ====================
@@ -2013,7 +2010,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

dist/agents/architect.txt

@@ -107,76 +107,73 @@ dependencies:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#create-deep-research-prompt ====================

dist/agents/bmad-master.txt

@@ -1173,76 +1173,73 @@ Present these numbered options to the user:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#document-project ====================
@@ -8399,7 +8396,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

dist/agents/bmad-orchestrator.txt

@@ -263,76 +263,73 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#kb-mode-interaction ====================
@@ -489,7 +486,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

dist/agents/dev.txt

@@ -83,7 +83,7 @@ task-execution:
   updates-ONLY:
     - 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
     - 'Debug Log: | Task | File | Change | Reverted? |'
-    - 'Completion Notes: Deviations only, <50 words'
+    - 'Completion Notes: Deviations from AC or tasks during execution only, <50 words'
     - 'Change Log: Requirement changes only'
     - 'File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation'
   blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations

dist/agents/pm.txt

@@ -104,76 +104,73 @@ dependencies:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#correct-course ====================

dist/agents/ux-expert.txt

@@ -464,76 +464,73 @@ Present these numbered options to the user:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#execute-checklist ====================

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

@@ -104,76 +104,73 @@ dependencies:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#execute-checklist ====================

dist/expansion-packs/bmad-2d-phaser-game-dev/teams/phaser-2d-nodejs-game-team.txt

@@ -977,76 +977,73 @@ Present these numbered options to the user:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#advanced-elicitation ====================

dist/expansion-packs/bmad-infrastructure-devops/agents/infra-devops-platform.txt

@@ -105,76 +105,73 @@ dependencies:
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#review-infrastructure ====================

dist/teams/team-all.txt

@@ -353,7 +353,7 @@ task-execution:
   updates-ONLY:
     - 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
     - 'Debug Log: | Task | File | Change | Reverted? |'
-    - 'Completion Notes: Deviations only, <50 words'
+    - 'Completion Notes: Deviations from AC or tasks during execution only, <50 words'
     - 'Change Log: Requirement changes only'
     - 'File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation'
   blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations
@@ -755,76 +755,73 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#kb-mode-interaction ====================
@@ -981,7 +978,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

dist/teams/team-fullstack.txt

@@ -599,76 +599,73 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#kb-mode-interaction ====================
@@ -825,7 +822,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

dist/teams/team-ide-minimal.txt

@@ -335,7 +335,7 @@ task-execution:
   updates-ONLY:
     - 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
     - 'Debug Log: | Task | File | Change | Reverted? |'
-    - 'Completion Notes: Deviations only, <50 words'
+    - 'Completion Notes: Deviations from AC or tasks during execution only, <50 words'
     - 'Change Log: Requirement changes only'
     - 'File List: CRITICAL - Maintain complete list of ALL files created/modified during implementation'
   blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations
@@ -499,76 +499,73 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#kb-mode-interaction ====================
@@ -725,7 +722,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

dist/teams/team-no-ui.txt

@@ -531,76 +531,73 @@ Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
 
 ## Purpose
 
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
 
-## Instructions
+## CRITICAL RULES
 
-### 1. Identify Template and Context
+1. **Templates are PROGRAMS** - Execute every [[LLM:]] instruction exactly as written
+2. **NEVER show markup** - Hide all [[LLM:]], {{placeholders}}, @{examples}, and template syntax
+3. **STOP and EXECUTE** - When you see "apply tasks#" or "execute tasks#", STOP and run that task immediately
+4. **WAIT for user input** - At review points and after elicitation tasks
 
-- Determine which template to use (user-provided or list available for selection to user)
+## Execution Flow
 
-  - Agent-specific templates are listed in the agent's dependencies under `templates`. For each template listed, consider it a document the agent can create. So if an agent has:
+### 1. Identify Template
 
-    @{example}
+- Load from `templates#*` or `{root}/templates directory`
-    dependencies:
+- Agent-specific templates are listed in agent's dependencies
-    templates: - prd-tmpl - architecture-tmpl
+- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
-    @{/example}
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+### 2. Ask Interaction Mode
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
+> 1. **Incremental** - Section by section with reviews
-- Understand the document purpose and target audience
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
-
-### 2. Determine Interaction Mode
-
-Confirm with the user their preferred interaction style:
-
-- **Incremental:** Work through chunks of the document.
-- **YOLO Mode:** Draft complete document making reasonable assumptions in one shot. (Can be entered also after starting incremental by just typing /yolo)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the `{root}/templates directory`
+- Replace {{placeholders}} with real content
-- Follow ALL embedded LLM instructions within the template
+- Execute [[LLM:]] instructions as you encounter them
-- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
-
-### 4. Template Processing Rules
-
-#### CRITICAL: Never display template markup, LLM instructions, or examples to users
-
-- Replace all {{placeholders}} with actual content
-- Execute all [[LLM: instructions]] internally
-- Process `<<REPEAT>>` sections as needed
-- Evaluate ^^CONDITION^^ blocks and include only if applicable
 - Use @{examples} for guidance but never output them
 
-### 5. Content Generation
+### 4. Key Execution Patterns
 
-- **Incremental Mode**: Present each major section for review before proceeding
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
-- **YOLO Mode**: Generate all sections, then review complete document with user
-- Apply any elicitation protocols specified in template
-- Incorporate user feedback and iterate as needed
 
-### 6. Validation
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
 
-If template specifies a checklist:
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
 
-- Run the appropriate checklist against completed document
+- Finish the section
-- Document completion status for each item
+- STOP and execute the task
-- Address any deficiencies found
+- Wait for user input
-- Present validation summary to user
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
+- No truncation or summarization
-- DO NOT truncate or summarize content
+- Begin directly with content (no preamble)
-- Begin directly with document content (no preamble)
+- Include any handoff prompts from template
-- Include any handoff prompts specified in template
 
-## Important Notes
+## Common Mistakes to Avoid
 
-- Template markup is for AI processing only - never expose to users
+❌ Skipping elicitation tasks
+❌ Showing template markup to users
+❌ Continuing past STOP signals
+❌ Combining multiple review points
+
+✅ Execute ALL instructions in sequence
+✅ Present only clean, formatted content
+✅ Stop at every elicitation point
+✅ Wait for user confirmation when instructed
+
+## Remember
+
+Templates contain precise instructions for a reason. Follow them exactly to ensure document quality and completeness.
 ==================== END: tasks#create-doc ====================
 
 ==================== START: tasks#kb-mode-interaction ====================
@@ -757,7 +754,7 @@ BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agent
 5. Type `/help` to see available commands
 
 #### Option 2: IDE Integration
-**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code, VS Code Copilot users
 
 ```bash
 # Interactive installation (recommended)

docs/bmad-workflow-guide.md

@@ -22,7 +22,7 @@ The BMAD Method follows a structured approach to AI-assisted software developmen
    ```
 
    - Choose "Complete installation"
-   - Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
+   - Select your IDE (Cursor, Claude Code, Windsurf, Roo Code, or VS Code Copilot)
 
 2. **Verify installation**:
    - `.bmad-core/` folder created with all agents
@@ -113,6 +113,7 @@ Follow the SM → Dev cycle for systematic story development:
 - **Cursor**: `@agent-name` (e.g., `@bmad-master`)
 - **Windsurf**: `@agent-name` (e.g., `@bmad-master`)
 - **Roo Code**: Select mode from mode selector (e.g., `bmad-bmad-master`)
+- **VS Code Copilot**: Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.
 
 ### Chat Management:
 

docs/core-architecture.md

@@ -292,7 +292,8 @@ bmad-method/
 │   │   ├── cline-guide.md
 │   │   ├── gemini-cli-guide.md
 │   │   ├── roo-code-guide.md
-│   │   └── windsurf-guide.md
+│   │   ├── windsurf-guide.md
+│   │   └── vs-code-copilot-guide.md
 │   ├── bmad-workflow-guide.md    # Universal workflow guide
 │   ├── core-architecture.md      # This document
 │   ├── expansion-packs.md        # Expansion pack guide

docs/how-to-contribute-with-pull-requests.md

@@ -8,7 +8,15 @@ A pull request (PR) is how you propose changes to a project on GitHub. Think of
 
 ## Before You Start
 
-⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change. If you're planning something big, please [open an issue](https://github.com/bmadcode/bmad-method/issues) or start a [discussion](https://github.com/bmadcode/bmad-method/discussions) first.
+⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change.
+
+**Required before submitting PRs:**
+
+- **For bug fixes**: Create an issue using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
+- **For new features**:
+  1. Discuss in Discord [#general-dev channel](https://discord.gg/g6ypHytrCB)
+  2. Create an issue using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
+- **For large changes**: Always open an issue first to discuss alignment
 
 ## Step-by-Step Guide
 
@@ -82,9 +90,15 @@ git push origin fix/typo-in-readme
 
 1. Go to your fork on GitHub
 2. You'll see a green "Compare & pull request" button - click it
-3. Fill out the PR template:
+3. Select the correct target branch:
-   - **Title**: Clear, descriptive title
+   - **`next` branch** for most contributions (features, docs, enhancements)
-   - **Description**: Explain what you changed and why
+   - **`main` branch** only for critical fixes
+4. Fill out the PR description using the template in CONTRIBUTING.md:
+   - **What**: 1-2 sentences describing what changed
+   - **Why**: 1-2 sentences explaining why
+   - **How**: 2-3 bullets on implementation
+   - **Testing**: How you tested
+5. Reference the related issue number (e.g., "Fixes #123")
 
 ### 8. Wait for Review
 
@@ -117,9 +131,12 @@ git push origin fix/typo-in-readme
 
 ## Need Help?
 
-- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help
+- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help:
-- 💬 Ask questions in [Discussions](https://github.com/bmadcode/bmad-method/discussions)
+  - **#general-dev** - Technical questions and feature discussions
-- 🐛 Report bugs in [Issues](https://github.com/bmadcode/bmad-method/issues)
+  - **#bugs-issues** - Get help with bugs before filing issues
+- 💬 Ask questions in [GitHub Discussions](https://github.com/bmadcode/bmad-method/discussions)
+- 🐛 Report bugs using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
+- 💡 Suggest features using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
 - 📖 Read the full [Contributing Guidelines](../CONTRIBUTING.md)
 
 ## Example: Good vs Bad PRs

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

@@ -1,5 +1,7 @@
 name: bmad-2d-phaser-game-dev
-version: 1.1.0
+version: 1.2.0
 short-title: 2D game development with Phaser 3 & TypeScript
-description: 2D Game Development expansion pack for BMAD Method - Phaser 3 & TypeScript focused
+description: >-
+  2D Game Development expansion pack for BMAD Method - Phaser 3 & TypeScript
+  focused
 author: Brian (BMad)

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

@@ -1,5 +1,5 @@
 name: bmad-creator-tools
-version: 1.0.0
+version: 1.1.0
 short-title: Tools for creating BMAD framework components
 description: Tools for creating and extending BMAD framework components.
 author: Brian (BMad)

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

@@ -1,5 +1,8 @@
 name: bmad-infrastructure-devops
-version: 1.0.0
+version: 1.1.0
 short-title: Infrastructure and DevOps capabilities
-description: This expansion pack extends BMAD Method with comprehensive infrastructure and DevOps capabilities. It's designed for teams that need to define, implement, and manage cloud infrastructure alongside their application development.
+description: >-
+  This expansion pack extends BMAD Method with comprehensive infrastructure and
+  DevOps capabilities. It's designed for teams that need to define, implement,
+  and manage cloud infrastructure alongside their application development.
 author: Brian (BMad)

package-lock.json

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

package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmad-method",
-  "version": "4.20.0",
+  "version": "4.23.0",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "main": "tools/cli.js",
   "bin": {
@@ -18,6 +18,20 @@
     "version:patch": "node tools/version-bump.js patch",
     "version:minor": "node tools/version-bump.js minor",
     "version:major": "node tools/version-bump.js major",
+    "version:core": "node tools/bump-core-version.js",
+    "version:core:major": "node tools/bump-core-version.js major",
+    "version:core:minor": "node tools/bump-core-version.js minor",
+    "version:core:patch": "node tools/bump-core-version.js patch",
+    "version:expansion": "node tools/bump-expansion-version.js",
+    "version:expansion:set": "node tools/update-expansion-version.js",
+    "version:all": "node tools/bump-all-versions.js",
+    "version:all:minor": "node tools/bump-all-versions.js minor",
+    "version:all:major": "node tools/bump-all-versions.js major",
+    "version:all:patch": "node tools/bump-all-versions.js patch",
+    "version:expansion:all": "node tools/bump-all-versions.js",
+    "version:expansion:all:minor": "node tools/bump-all-versions.js minor",
+    "version:expansion:all:major": "node tools/bump-all-versions.js major",
+    "version:expansion:all:patch": "node tools/bump-all-versions.js patch",
     "release": "semantic-release",
     "release:test": "semantic-release --dry-run --no-ci || echo 'Config test complete - authentication errors are expected locally'",
     "prepare": "husky"

test-ide-paths.js

@@ -1,41 +0,0 @@
-// Test script to verify IDE setup paths for expansion pack agents
-const path = require('path');
-const fs = require('fs-extra');
-
-// Simulate the findAgentPath logic
-function simulateFindAgentPath(agentId, installDir) {
-  const possiblePaths = [
-    path.join(installDir, ".bmad-core", "agents", `${agentId}.md`),
-    path.join(installDir, "agents", `${agentId}.md`),
-    // Expansion pack paths
-    path.join(installDir, ".bmad-2d-phaser-game-dev", "agents", `${agentId}.md`),
-    path.join(installDir, ".bmad-infrastructure-devops", "agents", `${agentId}.md`),
-    path.join(installDir, ".bmad-creator-tools", "agents", `${agentId}.md`)
-  ];
-  
-  // Simulate finding the agent in an expansion pack
-  if (agentId === 'game-developer') {
-    return path.join(installDir, ".bmad-2d-phaser-game-dev", "agents", `${agentId}.md`);
-  }
-  
-  // Default to core
-  return path.join(installDir, ".bmad-core", "agents", `${agentId}.md`);
-}
-
-// Test different scenarios
-const testDir = '/project';
-const agents = ['dev', 'game-developer', 'infra-devops-platform'];
-
-console.log('Testing IDE path references:\n');
-
-agents.forEach(agentId => {
-  const agentPath = simulateFindAgentPath(agentId, testDir);
-  const relativePath = path.relative(testDir, agentPath).replace(/\\/g, '/');
-  
-  console.log(`Agent: ${agentId}`);
-  console.log(`  Full path: ${agentPath}`);
-  console.log(`  Relative path: ${relativePath}`);
-  console.log(`  Roo customInstructions: CRITICAL Read the full YML from ${relativePath} ...`);
-  console.log(`  Cursor MDC reference: [${relativePath}](mdc:${relativePath})`);
-  console.log('');
-});

tools/bump-all-versions.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const args = process.argv.slice(2);
+const bumpType = args[0] || 'minor'; // default to minor
+
+if (!['major', 'minor', 'patch'].includes(bumpType)) {
+  console.log('Usage: node bump-all-versions.js [major|minor|patch]');
+  console.log('Default: minor');
+  process.exit(1);
+}
+
+function bumpVersion(currentVersion, type) {
+  const [major, minor, patch] = currentVersion.split('.').map(Number);
+  
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+    default:
+      return currentVersion;
+  }
+}
+
+async function bumpAllVersions() {
+  const updatedItems = [];
+  
+  // First, bump the core version
+  const coreConfigPath = path.join(__dirname, '..', 'bmad-core', 'core-config.yml');
+  try {
+    const coreConfigContent = fs.readFileSync(coreConfigPath, 'utf8');
+    const coreConfig = yaml.load(coreConfigContent);
+    const oldCoreVersion = coreConfig.version || '1.0.0';
+    const newCoreVersion = bumpVersion(oldCoreVersion, bumpType);
+    
+    coreConfig.version = newCoreVersion;
+    
+    const updatedCoreYaml = yaml.dump(coreConfig, { indent: 2 });
+    fs.writeFileSync(coreConfigPath, updatedCoreYaml);
+    
+    updatedItems.push({ type: 'core', name: 'BMad Core', oldVersion: oldCoreVersion, newVersion: newCoreVersion });
+    console.log(`✓ BMad Core: ${oldCoreVersion} → ${newCoreVersion}`);
+  } catch (error) {
+    console.error(`✗ Failed to update BMad Core: ${error.message}`);
+  }
+  
+  // Then, bump all expansion packs
+  const expansionPacksDir = path.join(__dirname, '..', 'expansion-packs');
+  
+  try {
+    const entries = fs.readdirSync(expansionPacksDir, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'README.md') {
+        const packId = entry.name;
+        const configPath = path.join(expansionPacksDir, packId, 'config.yml');
+        
+        if (fs.existsSync(configPath)) {
+          try {
+            const configContent = fs.readFileSync(configPath, 'utf8');
+            const config = yaml.load(configContent);
+            const oldVersion = config.version || '1.0.0';
+            const newVersion = bumpVersion(oldVersion, bumpType);
+            
+            config.version = newVersion;
+            
+            const updatedYaml = yaml.dump(config, { indent: 2 });
+            fs.writeFileSync(configPath, updatedYaml);
+            
+            updatedItems.push({ type: 'expansion', name: packId, oldVersion, newVersion });
+            console.log(`✓ ${packId}: ${oldVersion} → ${newVersion}`);
+            
+          } catch (error) {
+            console.error(`✗ Failed to update ${packId}: ${error.message}`);
+          }
+        }
+      }
+    }
+    
+    if (updatedItems.length > 0) {
+      const coreCount = updatedItems.filter(i => i.type === 'core').length;
+      const expansionCount = updatedItems.filter(i => i.type === 'expansion').length;
+      
+      console.log(`\n✓ Successfully bumped ${updatedItems.length} item(s) with ${bumpType} version bump`);
+      if (coreCount > 0) console.log(`  - ${coreCount} core`);
+      if (expansionCount > 0) console.log(`  - ${expansionCount} expansion pack(s)`);
+      
+      console.log('\nNext steps:');
+      console.log('1. Test the changes');
+      console.log('2. Commit: git add -A && git commit -m "chore: bump all versions (' + bumpType + ')"');
+    } else {
+      console.log('No items found to update');
+    }
+    
+  } catch (error) {
+    console.error('Error reading expansion packs directory:', error.message);
+    process.exit(1);
+  }
+}
+
+bumpAllVersions();

tools/bump-core-version.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const args = process.argv.slice(2);
+const bumpType = args[0] || 'minor'; // default to minor
+
+if (!['major', 'minor', 'patch'].includes(bumpType)) {
+  console.log('Usage: node bump-core-version.js [major|minor|patch]');
+  console.log('Default: minor');
+  process.exit(1);
+}
+
+function bumpVersion(currentVersion, type) {
+  const [major, minor, patch] = currentVersion.split('.').map(Number);
+  
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+    default:
+      return currentVersion;
+  }
+}
+
+async function bumpCoreVersion() {
+  try {
+    const coreConfigPath = path.join(__dirname, '..', 'bmad-core', 'core-config.yml');
+    
+    const coreConfigContent = fs.readFileSync(coreConfigPath, 'utf8');
+    const coreConfig = yaml.load(coreConfigContent);
+    const oldVersion = coreConfig.version || '1.0.0';
+    const newVersion = bumpVersion(oldVersion, bumpType);
+    
+    coreConfig.version = newVersion;
+    
+    const updatedYaml = yaml.dump(coreConfig, { indent: 2 });
+    fs.writeFileSync(coreConfigPath, updatedYaml);
+    
+    console.log(`✓ BMad Core: ${oldVersion} → ${newVersion}`);
+    console.log(`\n✓ Successfully bumped BMad Core with ${bumpType} version bump`);
+    console.log('\nNext steps:');
+    console.log('1. Test the changes');
+    console.log('2. Commit: git add -A && git commit -m "chore: bump core version (' + bumpType + ')"');
+    
+  } catch (error) {
+    console.error('Error updating core version:', error.message);
+    process.exit(1);
+  }
+}
+
+bumpCoreVersion();

tools/bump-expansion-version.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const args = process.argv.slice(2);
+
+if (args.length < 1 || args.length > 2) {
+  console.log('Usage: node bump-expansion-version.js <expansion-pack-id> [major|minor|patch]');
+  console.log('Default: minor');
+  console.log('Example: node bump-expansion-version.js bmad-creator-tools patch');
+  process.exit(1);
+}
+
+const packId = args[0];
+const bumpType = args[1] || 'minor'; // default to minor
+
+if (!['major', 'minor', 'patch'].includes(bumpType)) {
+  console.error('Error: Bump type must be major, minor, or patch');
+  process.exit(1);
+}
+
+function bumpVersion(currentVersion, type) {
+  const [major, minor, patch] = currentVersion.split('.').map(Number);
+  
+  switch (type) {
+    case 'major':
+      return `${major + 1}.0.0`;
+    case 'minor':
+      return `${major}.${minor + 1}.0`;
+    case 'patch':
+      return `${major}.${minor}.${patch + 1}`;
+    default:
+      return currentVersion;
+  }
+}
+
+async function updateVersion() {
+  try {
+    const configPath = path.join(__dirname, '..', 'expansion-packs', packId, 'config.yml');
+    
+    if (!fs.existsSync(configPath)) {
+      console.error(`Error: Expansion pack '${packId}' not found`);
+      console.log('\nAvailable expansion packs:');
+      const expansionPacksDir = path.join(__dirname, '..', 'expansion-packs');
+      const entries = fs.readdirSync(expansionPacksDir, { withFileTypes: true });
+      entries.forEach(entry => {
+        if (entry.isDirectory() && !entry.name.startsWith('.')) {
+          console.log(`  - ${entry.name}`);
+        }
+      });
+      process.exit(1);
+    }
+    
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = yaml.load(configContent);
+    const oldVersion = config.version || '1.0.0';
+    const newVersion = bumpVersion(oldVersion, bumpType);
+    
+    config.version = newVersion;
+    
+    const updatedYaml = yaml.dump(config, { indent: 2 });
+    fs.writeFileSync(configPath, updatedYaml);
+    
+    console.log(`✓ ${packId}: ${oldVersion} → ${newVersion}`);
+    console.log(`\n✓ Successfully bumped ${packId} with ${bumpType} version bump`);
+    console.log('\nNext steps:');
+    console.log('1. Test the changes');
+    console.log('2. Commit: git add -A && git commit -m "chore: bump ' + packId + ' version (' + bumpType + ')"');
+    
+  } catch (error) {
+    console.error('Error updating version:', error.message);
+    process.exit(1);
+  }
+}
+
+updateVersion();

tools/installer/bin/bmad.js

@@ -2,6 +2,8 @@
 
 const { program } = require('commander');
 const path = require('path');
+const fs = require('fs').promises;
+const yaml = require('js-yaml');
 
 // Dynamic imports for ES modules
 let chalk, inquirer;
@@ -45,17 +47,15 @@ program
 program
   .command('install')
   .description('Install BMAD Method agents and tools')
-  .option('-f, --full', 'Install complete .bmad-core folder')
+  .option('-f, --full', 'Install complete BMAD Method')
-  .option('-a, --agent <agent>', 'Install specific agent with dependencies')
-  .option('-t, --team <team>', 'Install specific team with required agents and dependencies')
   .option('-x, --expansion-only', 'Install only expansion packs (no bmad-core)')
-  .option('-d, --directory <path>', 'Installation directory (default: .bmad-core)')
+  .option('-d, --directory <path>', 'Installation directory')
-  .option('-i, --ide <ide...>', 'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, roo, cline, gemini, other)')
+  .option('-i, --ide <ide...>', 'Configure for specific IDE(s) - can specify multiple (cursor, claude-code, windsurf, roo, cline, gemini, vs-code-copilot, other)')
   .option('-e, --expansion-packs <packs...>', 'Install specific expansion packs (can specify multiple)')
   .action(async (options) => {
     try {
       await initializeModules();
-      if (!options.full && !options.agent && !options.team && !options.expansionOnly) {
+      if (!options.full && !options.expansionOnly) {
         // Interactive mode
         const answers = await promptInstallation();
         if (!answers._alreadyInstalled) {
@@ -64,15 +64,11 @@ program
       } else {
         // Direct mode
         let installType = 'full';
-        if (options.agent) installType = 'single-agent';
+        if (options.expansionOnly) installType = 'expansion-only';
-        else if (options.team) installType = 'team';
-        else if (options.expansionOnly) installType = 'expansion-only';
 
         const config = {
           installType,
-          agent: options.agent,
+          directory: options.directory || '.',
-          team: options.team,
-          directory: options.directory || '.bmad-core',
           ides: (options.ide || []).filter(ide => ide !== 'other'),
           expansionPacks: options.expansionPacks || []
         };
@@ -100,19 +96,6 @@ program
     }
   });
 
-program
-  .command('list')
-  .description('List available agents')
-  .action(async () => {
-    try {
-      await installer.listAgents();
-    } catch (error) {
-      if (!chalk) await initializeModules();
-      console.error(chalk.red('Error:'), error.message);
-      process.exit(1);
-    }
-  });
-
 program
   .command('list:expansions')
   .description('List available expansion packs')
@@ -145,7 +128,7 @@ async function promptInstallation() {
 
   const answers = {};
 
-  // Ask for installation directory
+  // Ask for installation directory first
   const { directory } = await inquirer.prompt([
     {
       type: 'input',
@@ -161,147 +144,85 @@ async function promptInstallation() {
   ]);
   answers.directory = directory;
 
-  // Check if this is an existing v4 installation
+  // Detect existing installations
-  const installDir = path.resolve(answers.directory);
+  const installDir = path.resolve(directory);
   const state = await installer.detectInstallationState(installDir);
-
+  
+  // Check for existing expansion packs
+  const existingExpansionPacks = state.expansionPacks || {};
+  
+  // Get available expansion packs
+  const availableExpansionPacks = await installer.getAvailableExpansionPacks();
+  
+  // Build choices list
+  const choices = [];
+  
+  // Load core config to get short-title
+  const coreConfigPath = path.join(__dirname, '..', '..', '..', 'bmad-core', 'core-config.yml');
+  const coreConfig = yaml.load(await fs.readFile(coreConfigPath, 'utf8'));
+  const coreShortTitle = coreConfig['short-title'] || 'BMad Agile Core System';
+  
+  // Add BMAD core option
+  let bmadOptionText;
   if (state.type === 'v4_existing') {
-    console.log(chalk.yellow('\n🔍 Found existing BMAD v4 installation'));
+    const currentVersion = state.manifest?.version || 'unknown';
-    console.log(`   Directory: ${installDir}`);
+    const newVersion = coreConfig.version || 'unknown'; // Use version from core-config.yml
-    console.log(`   Version: ${state.manifest?.version || 'Unknown'}`);
+    const versionInfo = currentVersion === newVersion 
-    console.log(`   Installed: ${state.manifest?.installed_at ? new Date(state.manifest.installed_at).toLocaleDateString() : 'Unknown'}`);
+      ? `(v${currentVersion} - reinstall)`
-
+      : `(v${currentVersion} → v${newVersion})`;
-    const { shouldUpdate } = await inquirer.prompt([
+    bmadOptionText = `Update ${coreShortTitle} ${versionInfo} .bmad-core`;
-      {
+  } else {
-        type: 'confirm',
+    bmadOptionText = `Install ${coreShortTitle} (v${coreConfig.version || version}) .bmad-core`;
-        name: 'shouldUpdate',
-        message: 'Would you like to update your existing BMAD v4 installation?',
-        default: true
-      }
-    ]);
-
-    if (shouldUpdate) {
-      // Skip other prompts and go directly to update
-      answers.installType = 'update';
-      answers._alreadyInstalled = true; // Flag to prevent double installation
-      await installer.install(answers);
-      return answers; // Return the answers object
-    }
-    // If user doesn't want to update, continue with normal flow
   }
-
+  
-  // Ask for installation type
+  choices.push({
-  const { installType } = await inquirer.prompt([
+    name: bmadOptionText,
+    value: 'bmad-core',
+    checked: true
+  });
+  
+  // Add expansion pack options
+  for (const pack of availableExpansionPacks) {
+    const existing = existingExpansionPacks[pack.id];
+    let packOptionText;
+    
+    if (existing) {
+      const currentVersion = existing.manifest?.version || 'unknown';
+      const newVersion = pack.version;
+      const versionInfo = currentVersion === newVersion 
+        ? `(v${currentVersion} - reinstall)`
+        : `(v${currentVersion} → v${newVersion})`;
+      packOptionText = `Update ${pack.description} ${versionInfo} .${pack.id}`;
+    } else {
+      packOptionText = `Install ${pack.description} (v${pack.version}) .${pack.id}`;
+    }
+    
+    choices.push({
+      name: packOptionText,
+      value: pack.id,
+      checked: false
+    });
+  }
+  
+  // Ask what to install
+  const { selectedItems } = await inquirer.prompt([
     {
-      type: 'list',
+      type: 'checkbox',
-      name: 'installType',
+      name: 'selectedItems',
-      message: 'How would you like to install BMAD?',
+      message: 'Select what to install/update (use space to select, enter to continue):',
-      choices: [
+      choices: choices,
-        {
+      validate: (selected) => {
-          name: 'Complete installation (recommended) - All agents and tools',
+        if (selected.length === 0) {
-          value: 'full'
+          return 'Please select at least one item to install';
-        },
-        {
-          name: 'Team installation - Install a specific team with required agents',
-          value: 'team'
-        },
-        {
-          name: 'Single agent - Choose one agent to install',
-          value: 'single-agent'
-        },
-        {
-          name: 'Expansion packs only - Install expansion packs without bmad-core',
-          value: 'expansion-only'
         }
-      ]
+        return true;
+      }
     }
   ]);
-  answers.installType = installType;
+  
-
+  // Process selections
-  // If single agent, ask which one
+  answers.installType = selectedItems.includes('bmad-core') ? 'full' : 'expansion-only';
-  if (installType === 'single-agent') {
+  answers.expansionPacks = selectedItems.filter(item => item !== 'bmad-core');
-    const agents = await installer.getAvailableAgents();
-    const { agent } = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'agent',
-        message: 'Select an agent to install:',
-        choices: agents.map(a => ({
-          name: `${a.id} - ${a.name} (${a.description})`,
-          value: a.id
-        }))
-      }
-    ]);
-    answers.agent = agent;
-  }
-
-  // If team installation, ask which team
-  if (installType === 'team') {
-    const teams = await installer.getAvailableTeams();
-    const { team } = await inquirer.prompt([
-      {
-        type: 'list',
-        name: 'team',
-        message: 'Select a team to install in your IDE project folder:',
-        choices: teams.map(t => ({
-          name: `${t.icon || '📋'} ${t.name}: ${t.description}`,
-          value: t.id
-        }))
-      }
-    ]);
-    answers.team = team;
-  }
-
-  // Ask for expansion pack selection
-  if (installType === 'full' || installType === 'team' || installType === 'expansion-only') {
-    try {
-      const availableExpansionPacks = await installer.getAvailableExpansionPacks();
-
-      if (availableExpansionPacks.length > 0) {
-        let choices;
-        let message;
-
-        if (installType === 'expansion-only') {
-          message = 'Select expansion packs to install (required):'
-          choices = availableExpansionPacks.map(pack => ({
-            name: `${pack.name} - ${pack.description}`,
-            value: pack.id
-          }));
-        } else {
-          message = 'Select expansion packs to install (press Enter to skip, or check any to install):';
-          choices = availableExpansionPacks.map(pack => ({
-            name: `${pack.name} - ${pack.description}`,
-            value: pack.id
-          }));
-        }
-
-        const { expansionPacks } = await inquirer.prompt([
-          {
-            type: 'checkbox',
-            name: 'expansionPacks',
-            message,
-            choices,
-            validate: installType === 'expansion-only' ? (answer) => {
-              if (answer.length < 1) {
-                return 'You must select at least one expansion pack for expansion-only installation.';
-              }
-              return true;
-            } : undefined
-          }
-        ]);
-
-        // Use selected expansion packs directly
-        answers.expansionPacks = expansionPacks;
-      } else {
-        answers.expansionPacks = [];
-      }
-    } catch (error) {
-      console.warn(chalk.yellow('Warning: Could not load expansion packs. Continuing without them.'));
-      answers.expansionPacks = [];
-    }
-  } else {
-    answers.expansionPacks = [];
-  }
 
   // Ask for IDE configuration
   const { ides } = await inquirer.prompt([
@@ -315,7 +236,8 @@ async function promptInstallation() {
         { name: 'Windsurf', value: 'windsurf' },
         { name: 'Roo Code', value: 'roo' },
         { name: 'Cline', value: 'cline' },
-        { name: 'Gemini CLI', value: 'gemini' }
+        { name: 'Gemini CLI', value: 'gemini' },
+        { name: 'VS Code Copilot', value: 'vs-code-copilot' }
       ]
     }
   ]);

tools/installer/config/install.config.yml

@@ -67,3 +67,16 @@ ide-configurations:
       # 2. It also configures .gemini/settings.json to load all agent files.
       # 3. Simply mention the agent in your prompt (e.g., "As @dev, ...").
       # 4. The Gemini CLI will automatically have the context for that agent.
+  vs-code-copilot:
+    name: VS Code Copilot
+    rule-dir: .github/chatmodes/
+    format: multi-file
+    command-suffix: .md
+    instructions: |
+      # To use BMAD agents with VS Code Copilot:
+      # 1. The installer creates a .github/chatmodes/ directory in your project
+      # 2. Open the Chat view (`⌃⌘I` on Mac, `Ctrl+Alt+I` on Windows/Linux) and select **Agent** from the chat mode selector.
+      # 3. The agent will adopt that persona for the conversation
+      # 4. Requires VS Code 1.99+ with `chat.agent.enabled: true` in settings
+      # 5. Agent files are stored in .github/chatmodes/
+      # 6. Use `/help` to see available commands and agents

tools/installer/lib/file-manager.js

@@ -83,12 +83,22 @@ class FileManager {
       this.manifestFile
     );
 
+    // Read version from core-config.yml
+    const coreConfigPath = path.join(__dirname, "../../../bmad-core/core-config.yml");
+    let coreVersion = "unknown";
+    try {
+      const coreConfigContent = await fs.readFile(coreConfigPath, "utf8");
+      const coreConfig = yaml.load(coreConfigContent);
+      coreVersion = coreConfig.version || "unknown";
+    } catch (error) {
+      console.warn("Could not read version from core-config.yml, using 'unknown'");
+    }
+
     const manifest = {
-      version: require("../../../package.json").version,
+      version: coreVersion,
       installed_at: new Date().toISOString(),
       install_type: config.installType,
       agent: config.agent || null,
-      ide_setup: config.ide || null,
       ides_setup: config.ides || [],
       expansion_packs: config.expansionPacks || [],
       files: [],
@@ -128,6 +138,21 @@ class FileManager {
     }
   }
 
+  async readExpansionPackManifest(installDir, packId) {
+    const manifestPath = path.join(
+      installDir,
+      `.${packId}`,
+      this.manifestFile
+    );
+
+    try {
+      const content = await fs.readFile(manifestPath, "utf8");
+      return yaml.load(content);
+    } catch (error) {
+      return null;
+    }
+  }
+
   async checkModifiedFiles(installDir, manifest) {
     const modified = [];
 
@@ -143,6 +168,33 @@ class FileManager {
     return modified;
   }
 
+  async checkFileIntegrity(installDir, manifest) {
+    const result = {
+      missing: [],
+      modified: []
+    };
+
+    for (const file of manifest.files) {
+      const filePath = path.join(installDir, file.path);
+      
+      // Skip checking the manifest file itself - it will always be different due to timestamps
+      if (file.path.endsWith('install-manifest.yml')) {
+        continue;
+      }
+      
+      if (!(await this.pathExists(filePath))) {
+        result.missing.push(file.path);
+      } else {
+        const currentHash = await this.calculateFileHash(filePath);
+        if (currentHash && currentHash !== file.hash) {
+          result.modified.push(file.path);
+        }
+      }
+    }
+
+    return result;
+  }
+
   async backupFile(filePath) {
     const backupPath = filePath + ".bak";
     let counter = 1;
@@ -183,6 +235,42 @@ class FileManager {
   async removeDirectory(dirPath) {
     await fs.remove(dirPath);
   }
+
+  async createExpansionPackManifest(installDir, packId, config, files) {
+    const manifestPath = path.join(
+      installDir,
+      `.${packId}`,
+      this.manifestFile
+    );
+
+    const manifest = {
+      version: config.expansionPackVersion || require("../../../package.json").version,
+      installed_at: new Date().toISOString(),
+      install_type: config.installType,
+      expansion_pack_id: config.expansionPackId,
+      expansion_pack_name: config.expansionPackName,
+      ides_setup: config.ides || [],
+      files: [],
+    };
+
+    // Add file information
+    for (const file of files) {
+      const filePath = path.join(installDir, file);
+      const hash = await this.calculateFileHash(filePath);
+
+      manifest.files.push({
+        path: file,
+        hash: hash,
+        modified: false,
+      });
+    }
+
+    // Write manifest
+    await fs.ensureDir(path.dirname(manifestPath));
+    await fs.writeFile(manifestPath, yaml.dump(manifest, { indent: 2 }));
+
+    return manifest;
+  }
 }
 
 module.exports = new FileManager();

tools/installer/lib/ide-setup.js

@@ -6,12 +6,16 @@ const configLoader = require("./config-loader");
 
 // Dynamic import for ES module
 let chalk;
+let inquirer;
 
 // Initialize ES modules
 async function initializeModules() {
   if (!chalk) {
     chalk = (await import("chalk")).default;
   }
+  if (!inquirer) {
+    inquirer = (await import("inquirer")).default;
+  }
 }
 
 class IdeSetup {
@@ -36,7 +40,7 @@ class IdeSetup {
     }
   }
 
-  async setup(ide, installDir, selectedAgent = null) {
+  async setup(ide, installDir, selectedAgent = null, spinner = null) {
     await initializeModules();
     const ideConfig = await configLoader.getIdeConfiguration(ide);
 
@@ -58,6 +62,8 @@ class IdeSetup {
         return this.setupCline(installDir, selectedAgent);
       case "gemini":
         return this.setupGeminiCli(installDir, selectedAgent);
+      case "vs-code-copilot":
+        return this.setupVsCodeCopilot(installDir, selectedAgent, spinner);
       default:
         console.log(chalk.yellow(`\nIDE ${ide} not yet supported`));
         return false;
@@ -507,6 +513,213 @@ class IdeSetup {
 
     return true;
   }
+
+  async setupVsCodeCopilot(installDir, selectedAgent, spinner = null) {
+    await initializeModules();
+    
+    // Configure VS Code workspace settings first to avoid UI conflicts with loading spinners
+    await this.configureVsCodeSettings(installDir, spinner);
+    
+    const chatmodesDir = path.join(installDir, ".github", "chatmodes");
+    const agents = selectedAgent ? [selectedAgent] : await this.getAllAgentIds(installDir);
+     
+    await fileManager.ensureDirectory(chatmodesDir);
+
+    for (const agentId of agents) {
+      // Find the agent file
+      const agentPath = await this.findAgentPath(agentId, installDir);
+      const chatmodePath = path.join(chatmodesDir, `${agentId}.chatmode.md`);
+
+      if (agentPath) {
+        // Create chat mode file with agent content
+        const agentContent = await fileManager.readFile(agentPath);
+        const agentTitle = await this.getAgentTitle(agentId, installDir);
+        
+        // Extract whenToUse for the description
+        const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)```/);
+        let description = `Activates the ${agentTitle} agent persona.`;
+        if (yamlMatch) {
+          const whenToUseMatch = yamlMatch[1].match(/whenToUse:\s*"(.*?)"/);
+          if (whenToUseMatch && whenToUseMatch[1]) {
+            description = whenToUseMatch[1];
+          }
+        }
+        
+        let chatmodeContent = `---
+description: "${description.replace(/"/g, '\\"')}"
+tools: ['changes', 'codebase', 'fetch', 'findTestFiles', 'githubRepo', 'problems', 'usages']
+---
+
+`;
+        chatmodeContent += agentContent;
+
+        await fileManager.writeFile(chatmodePath, chatmodeContent);
+        console.log(chalk.green(`✓ Created chat mode: ${agentId}.chatmode.md`));
+      }
+    }
+
+    console.log(chalk.green(`\n✓ VS Code Copilot setup complete!`));
+    console.log(chalk.dim(`You can now find the BMAD agents in the Chat view's mode selector.`));
+
+    return true;
+  }
+
+  async configureVsCodeSettings(installDir, spinner) {
+    await initializeModules(); // Ensure inquirer is loaded
+    const vscodeDir = path.join(installDir, ".vscode");
+    const settingsPath = path.join(vscodeDir, "settings.json");
+    
+    await fileManager.ensureDirectory(vscodeDir);
+    
+    // Read existing settings if they exist
+    let existingSettings = {};
+    if (await fileManager.pathExists(settingsPath)) {
+      try {
+        const existingContent = await fileManager.readFile(settingsPath);
+        existingSettings = JSON.parse(existingContent);
+        console.log(chalk.yellow("Found existing .vscode/settings.json. Merging BMAD settings..."));
+      } catch (error) {
+        console.warn(chalk.yellow("Could not parse existing settings.json. Creating new one."));
+        existingSettings = {};
+      }
+    }
+    
+    // Clear any previous output and add spacing to avoid conflicts with loaders
+    console.log('\n'.repeat(2));
+    console.log(chalk.blue("🔧 VS Code 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 VS Code 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'
+      }
+    ]);
+    
+    let bmadSettings = {};
+    
+    if (configChoice === 'skip') {
+      console.log(chalk.yellow("⚠️  Skipping VS Code settings configuration."));
+      console.log(chalk.dim("You can manually configure these settings in .vscode/settings.json:"));
+      console.log(chalk.dim("  • chat.agent.enabled: true"));
+      console.log(chalk.dim("  • chat.agent.maxRequests: 15"));
+      console.log(chalk.dim("  • github.copilot.chat.agent.runTasks: true"));
+      console.log(chalk.dim("  • chat.mcp.discovery.enabled: true"));
+      console.log(chalk.dim("  • github.copilot.chat.agent.autoFix: true"));
+      console.log(chalk.dim("  • chat.tools.autoApprove: false"));
+      return true;
+    }
+    
+    if (configChoice === 'defaults') {
+      // Use recommended defaults
+      bmadSettings = {
+        "chat.agent.enabled": true,
+        "chat.agent.maxRequests": 15,
+        "github.copilot.chat.agent.runTasks": true,
+        "chat.mcp.discovery.enabled": true,
+        "github.copilot.chat.agent.autoFix": true,
+        "chat.tools.autoApprove": false
+      };
+      console.log(chalk.green("✓ Using recommended BMAD defaults for VS Code Copilot settings"));
+    } else {
+      // Manual configuration
+      console.log(chalk.blue("\n📋 Let's configure each setting for your preferences:"));
+      
+      // Pause spinner during manual configuration prompts
+      let spinnerWasActive = false;
+      if (spinner && spinner.isSpinning) {
+        spinner.stop();
+        spinnerWasActive = true;
+      }
+      
+      const manualSettings = await inquirer.prompt([
+        {
+          type: 'input',
+          name: 'maxRequests',
+          message: 'Maximum requests per agent session (recommended: 15)?',
+          default: '15',
+          validate: (input) => {
+            const num = parseInt(input);
+            if (isNaN(num) || num < 1 || num > 50) {
+              return 'Please enter a number between 1 and 50';
+            }
+            return true;
+          }
+        },
+        {
+          type: 'confirm',
+          name: 'runTasks',
+          message: 'Allow agents to run workspace tasks (package.json scripts, etc.)?',
+          default: true
+        },
+        {
+          type: 'confirm',
+          name: 'mcpDiscovery',
+          message: 'Enable MCP (Model Context Protocol) server discovery?',
+          default: true
+        },
+        {
+          type: 'confirm',
+          name: 'autoFix',
+          message: 'Enable automatic error detection and fixing in generated code?',
+          default: true
+        },
+        {
+          type: 'confirm',
+          name: 'autoApprove',
+          message: 'Auto-approve ALL tools without confirmation? (⚠️  EXPERIMENTAL - less secure)',
+          default: false
+        }
+      ]);
+
+      // Restart spinner if it was active before prompts
+      if (spinner && spinnerWasActive) {
+        spinner.start();
+      }
+      
+      bmadSettings = {
+        "chat.agent.enabled": true, // Always enabled - required for BMAD agents
+        "chat.agent.maxRequests": parseInt(manualSettings.maxRequests),
+        "github.copilot.chat.agent.runTasks": manualSettings.runTasks,
+        "chat.mcp.discovery.enabled": manualSettings.mcpDiscovery,
+        "github.copilot.chat.agent.autoFix": manualSettings.autoFix,
+        "chat.tools.autoApprove": manualSettings.autoApprove
+      };
+      
+      console.log(chalk.green("✓ Custom settings configured"));
+    }
+    
+    // Merge settings (existing settings take precedence to avoid overriding user preferences)
+    const mergedSettings = { ...bmadSettings, ...existingSettings };
+    
+    // Write the updated settings
+    await fileManager.writeFile(settingsPath, JSON.stringify(mergedSettings, null, 2));
+    
+    console.log(chalk.green("✓ VS Code workspace settings configured successfully"));
+    console.log(chalk.dim("  Settings written to .vscode/settings.json:"));
+    Object.entries(bmadSettings).forEach(([key, value]) => {
+      console.log(chalk.dim(`  • ${key}: ${value}`));
+    });
+    console.log(chalk.dim(""));
+    console.log(chalk.dim("You can modify these settings anytime in .vscode/settings.json"));
+  }
 }
 
 module.exports = new IdeSetup();

tools/installer/lib/installer.js

@@ -16,6 +16,20 @@ async function initializeModules() {
 }
 
 class Installer {
+  async getCoreVersion() {
+    const yaml = require("js-yaml");
+    const fs = require("fs-extra");
+    const coreConfigPath = path.join(__dirname, "../../../bmad-core/core-config.yml");
+    try {
+      const coreConfigContent = await fs.readFile(coreConfigPath, "utf8");
+      const coreConfig = yaml.load(coreConfigContent);
+      return coreConfig.version || "unknown";
+    } catch (error) {
+      console.warn("Could not read version from core-config.yml, using 'unknown'");
+      return "unknown";
+    }
+  }
+
   async install(config) {
     // Initialize ES modules
     await initializeModules();
@@ -161,6 +175,7 @@ class Installer {
       hasBmadCore: false,
       hasOtherFiles: false,
       manifest: null,
+      expansionPacks: {},
     };
 
     // Check if directory exists
@@ -209,10 +224,14 @@ class Installer {
       state.hasOtherFiles = true;
     }
 
+    // Check for expansion packs (folders starting with .)
+    const expansionPacks = await this.detectExpansionPacks(installDir);
+    state.expansionPacks = expansionPacks;
+
     return state; // clean install
   }
 
-  async performFreshInstall(config, installDir, spinner) {
+  async performFreshInstall(config, installDir, spinner, options = {}) {
     // Ensure modules are initialized
     await initializeModules();
     spinner.text = "Installing BMAD Method...";
@@ -328,41 +347,13 @@ class Installer {
       const commonFiles = await this.copyCommonItems(installDir, ".bmad-core", spinner);
       files.push(...commonFiles);
     } else if (config.installType === "expansion-only") {
-      // Expansion-only installation - create minimal .bmad-core structure
+      // Expansion-only installation - DO NOT create .bmad-core
-      spinner.text = "Creating minimal .bmad-core structure for expansion packs...";
+      // Only install expansion packs
-      
+      spinner.text = "Installing expansion packs only...";
-      const bmadCoreDestDir = path.join(installDir, ".bmad-core");
-      await fileManager.ensureDirectory(bmadCoreDestDir);
-      
-      // Create basic directory structure
-      const dirs = ['agents', 'agent-teams', 'templates', 'tasks', 'checklists', 'workflows', 'data', 'utils', 'schemas'];
-      for (const dir of dirs) {
-        await fileManager.ensureDirectory(path.join(bmadCoreDestDir, dir));
-      }
-      
-      // Copy minimal required files (schemas, utils, etc.)
-      const sourceBase = configLoader.getBmadCorePath();
-      const essentialFiles = [
-        'schemas/**/*',
-        'utils/**/*'
-      ];
-      
-      for (const pattern of essentialFiles) {
-        const copiedFiles = await fileManager.copyGlobPattern(
-          pattern,
-          sourceBase,
-          bmadCoreDestDir
-        );
-        files.push(...copiedFiles.map(f => `.bmad-core/${f}`));
-      }
-      
-      // Copy common/ items to .bmad-core
-      spinner.text = "Copying common utilities...";
-      await this.copyCommonItems(installDir, ".bmad-core", spinner);
     }
 
     // Install expansion packs if requested
-    const expansionFiles = await this.installExpansionPacks(installDir, config.expansionPacks, spinner);
+    const expansionFiles = await this.installExpansionPacks(installDir, config.expansionPacks, spinner, config);
     files.push(...expansionFiles);
 
     // Install web bundles if requested
@@ -381,16 +372,18 @@ class Installer {
     if (ides.length > 0) {
       for (const ide of ides) {
         spinner.text = `Setting up ${ide} integration...`;
-        await ideSetup.setup(ide, installDir, config.agent);
+        await ideSetup.setup(ide, installDir, config.agent, spinner);
       }
     }
 
-    // Create manifest
+    // Create manifest (skip for expansion-only installations)
-    spinner.text = "Creating installation manifest...";
+    if (config.installType !== "expansion-only") {
-    await fileManager.createManifest(installDir, config, files);
+      spinner.text = "Creating installation manifest...";
+      await fileManager.createManifest(installDir, config, files);
+    }
 
     spinner.succeed("Installation complete!");
-    this.showSuccessMessage(config, installDir);
+    this.showSuccessMessage(config, installDir, options);
   }
 
   async handleExistingV4Installation(config, installDir, state, spinner) {
@@ -398,33 +391,137 @@ class Installer {
     await initializeModules();
     spinner.stop();
 
+    const currentVersion = state.manifest.version;
+    const newVersion = await this.getCoreVersion();
+    const versionCompare = this.compareVersions(currentVersion, newVersion);
+
     console.log(chalk.yellow("\n🔍 Found existing BMAD v4 installation"));
     console.log(`   Directory: ${installDir}`);
-    console.log(`   Version: ${state.manifest.version}`);
+    console.log(`   Current version: ${currentVersion}`);
+    console.log(`   Available version: ${newVersion}`);
     console.log(
       `   Installed: ${new Date(
         state.manifest.installed_at
       ).toLocaleDateString()}`
     );
 
+    // Check file integrity
+    spinner.start("Checking installation integrity...");
+    const integrity = await fileManager.checkFileIntegrity(installDir, state.manifest);
+    spinner.stop();
+    
+    const hasMissingFiles = integrity.missing.length > 0;
+    const hasModifiedFiles = integrity.modified.length > 0;
+    const hasIntegrityIssues = hasMissingFiles || hasModifiedFiles;
+    
+    if (hasIntegrityIssues) {
+      console.log(chalk.red("\n⚠️  Installation issues detected:"));
+      if (hasMissingFiles) {
+        console.log(chalk.red(`   Missing files: ${integrity.missing.length}`));
+        if (integrity.missing.length <= 5) {
+          integrity.missing.forEach(file => console.log(chalk.dim(`     - ${file}`)));
+        }
+      }
+      if (hasModifiedFiles) {
+        console.log(chalk.yellow(`   Modified files: ${integrity.modified.length}`));
+        if (integrity.modified.length <= 5) {
+          integrity.modified.forEach(file => console.log(chalk.dim(`     - ${file}`)));
+        }
+      }
+    }
+
+    // Show existing expansion packs
+    if (Object.keys(state.expansionPacks).length > 0) {
+      console.log(chalk.cyan("\n📦 Installed expansion packs:"));
+      for (const [packId, packInfo] of Object.entries(state.expansionPacks)) {
+        if (packInfo.hasManifest && packInfo.manifest) {
+          console.log(`   - ${packId} (v${packInfo.manifest.version || 'unknown'})`);
+        } else {
+          console.log(`   - ${packId} (no manifest)`);
+        }
+      }
+    }
+
+    let choices = [];
+    
+    if (versionCompare < 0) {
+      console.log(chalk.cyan("\n⬆️  Upgrade available for BMAD core"));
+      choices.push({ name: `Upgrade BMAD core (v${currentVersion} → v${newVersion})`, value: "upgrade" });
+    } else if (versionCompare === 0) {
+      if (hasIntegrityIssues) {
+        // Offer repair option when files are missing or modified
+        choices.push({ 
+          name: "Repair installation (restore missing/modified files)", 
+          value: "repair" 
+        });
+      }
+      console.log(chalk.yellow("\n⚠️  Same version already installed"));
+      choices.push({ name: `Force reinstall BMAD core (v${currentVersion} - reinstall)`, value: "reinstall" });
+    } else {
+      console.log(chalk.yellow("\n⬇️  Installed version is newer than available"));
+      choices.push({ name: `Downgrade BMAD core (v${currentVersion} → v${newVersion})`, value: "reinstall" });
+    }
+    
+    choices.push(
+      { name: "Add/update expansion packs only", value: "expansions" },
+      { name: "Cancel", value: "cancel" }
+    );
+
     const { action } = await inquirer.prompt([
       {
         type: "list",
         name: "action",
         message: "What would you like to do?",
-        choices: [
+        choices: choices,
-          { name: "Update existing installation", value: "update" },
-          { name: "Reinstall (overwrite)", value: "reinstall" },
-          { name: "Cancel", value: "cancel" },
-        ],
       },
     ]);
 
     switch (action) {
-      case "update":
+      case "upgrade":
         return await this.performUpdate(config, installDir, state.manifest, spinner);
+      case "repair":
+        // For repair, restore missing/modified files while backing up modified ones
+        return await this.performRepair(config, installDir, state.manifest, integrity, spinner);
       case "reinstall":
+        // For reinstall, don't check for modifications - just overwrite
         return await this.performReinstall(config, installDir, spinner);
+      case "expansions":
+        // Ask which expansion packs to install
+        const availableExpansionPacks = await this.getAvailableExpansionPacks();
+        
+        if (availableExpansionPacks.length === 0) {
+          console.log(chalk.yellow("No expansion packs available."));
+          return;
+        }
+        
+        const { selectedPacks } = await inquirer.prompt([
+          {
+            type: 'checkbox',
+            name: 'selectedPacks',
+            message: 'Select expansion packs to install/update:',
+            choices: availableExpansionPacks.map(pack => ({
+              name: `${pack.name} v${pack.version} - ${pack.description}`,
+              value: pack.id,
+              checked: state.expansionPacks[pack.id] !== undefined
+            }))
+          }
+        ]);
+        
+        if (selectedPacks.length === 0) {
+          console.log(chalk.yellow("No expansion packs selected."));
+          return;
+        }
+        
+        spinner.start("Installing expansion packs...");
+        const expansionFiles = await this.installExpansionPacks(installDir, selectedPacks, spinner, { ides: config.ides || [] });
+        spinner.succeed("Expansion packs installed successfully!");
+        
+        console.log(chalk.green("\n✓ Installation complete!"));
+        console.log(chalk.green(`✓ Expansion packs installed/updated:`));
+        for (const packId of selectedPacks) {
+          console.log(chalk.green(`  - ${packId} → .${packId}/`));
+        }
+        return;
       case "cancel":
         console.log("Installation cancelled.");
         return;
@@ -525,12 +622,20 @@ class Installer {
     spinner.start("Checking for updates...");
 
     try {
-      // Check for modified files
+      // Get current and new versions
-      spinner.text = "Checking for modified files...";
+      const currentVersion = manifest.version;
-      const modifiedFiles = await fileManager.checkModifiedFiles(
+      const newVersion = await this.getCoreVersion();
-        installDir,
+      const versionCompare = this.compareVersions(currentVersion, newVersion);
-        manifest
+      
-      );
+      // Only check for modified files if it's an actual version upgrade
+      let modifiedFiles = [];
+      if (versionCompare !== 0) {
+        spinner.text = "Checking for modified files...";
+        modifiedFiles = await fileManager.checkModifiedFiles(
+          installDir,
+          manifest
+        );
+      }
 
       if (modifiedFiles.length > 0) {
         spinner.warn("Found modified files");
@@ -570,35 +675,117 @@ class Installer {
       }
 
       // Perform update by re-running installation
-      spinner.text = "Updating files...";
+      spinner.text = versionCompare === 0 ? "Reinstalling files..." : "Updating files...";
       const config = {
         installType: manifest.install_type,
         agent: manifest.agent,
         directory: installDir,
-        ide: newConfig?.ide || manifest.ide_setup, // Use new IDE choice if provided
         ides: newConfig?.ides || manifest.ides_setup || [],
       };
 
-      await this.performFreshInstall(config, installDir, spinner);
+      await this.performFreshInstall(config, installDir, spinner, { isUpdate: true });
     } catch (error) {
       spinner.fail("Update failed");
       throw error;
     }
   }
 
+  async performRepair(config, installDir, manifest, integrity, spinner) {
+    spinner.start("Preparing to repair installation...");
+
+    try {
+      // Back up modified files
+      if (integrity.modified.length > 0) {
+        spinner.text = "Backing up modified files...";
+        for (const file of integrity.modified) {
+          const filePath = path.join(installDir, file);
+          if (await fileManager.pathExists(filePath)) {
+            const backupPath = await fileManager.backupFile(filePath);
+            console.log(chalk.dim(`  Backed up: ${file} → ${path.basename(backupPath)}`));
+          }
+        }
+      }
+
+      // Restore missing and modified files
+      spinner.text = "Restoring files...";
+      const sourceBase = configLoader.getBmadCorePath();
+      const filesToRestore = [...integrity.missing, ...integrity.modified];
+      
+      for (const file of filesToRestore) {
+        // Skip the manifest file itself
+        if (file.endsWith('install-manifest.yml')) continue;
+        
+        const relativePath = file.replace('.bmad-core/', '');
+        const destPath = path.join(installDir, file);
+        
+        // Check if this is a common/ file that needs special processing
+        const commonBase = path.dirname(path.dirname(path.dirname(path.dirname(__filename))));
+        const commonSourcePath = path.join(commonBase, 'common', relativePath);
+        
+        if (await fileManager.pathExists(commonSourcePath)) {
+          // This is a common/ file - needs template processing
+          const fs = require('fs').promises;
+          const content = await fs.readFile(commonSourcePath, 'utf8');
+          const updatedContent = content.replace(/\{root\}/g, '.bmad-core');
+          await fileManager.ensureDirectory(path.dirname(destPath));
+          await fs.writeFile(destPath, updatedContent, 'utf8');
+          spinner.text = `Restored: ${file}`;
+        } else {
+          // Regular file from bmad-core
+          const sourcePath = path.join(sourceBase, relativePath);
+          if (await fileManager.pathExists(sourcePath)) {
+            await fileManager.copyFile(sourcePath, destPath);
+            spinner.text = `Restored: ${file}`;
+          } else {
+            console.warn(chalk.yellow(`  Warning: Source file not found: ${file}`));
+          }
+        }
+      }
+      
+      spinner.succeed("Repair completed successfully!");
+      
+      // Show summary
+      console.log(chalk.green("\n✓ Installation repaired!"));
+      if (integrity.missing.length > 0) {
+        console.log(chalk.green(`  Restored ${integrity.missing.length} missing files`));
+      }
+      if (integrity.modified.length > 0) {
+        console.log(chalk.green(`  Restored ${integrity.modified.length} modified files (backups created)`));
+      }
+      
+      // Warning for Cursor custom modes if agents were repaired
+      const ides = manifest.ides_setup || [];
+      if (ides.includes('cursor')) {
+        console.log(chalk.yellow.bold("\n⚠️  IMPORTANT: Cursor Custom Modes Update Required"));
+        console.log(chalk.yellow("Since agent files have been repaired, you need to manually update your Cursor custom modes:"));
+        console.log(chalk.yellow("1. Open Cursor Settings (Cmd/Ctrl + ,)"));
+        console.log(chalk.yellow("2. Go to: Features > Cursor Tab > Custom Modes"));
+        console.log(chalk.yellow("3. Update each custom mode with the latest agent templates from:"));
+        console.log(chalk.yellow(`   ${path.join(installDir, '.bmad-core', 'agents')}`));
+        console.log(chalk.yellow("4. Copy the full content of each agent file into the corresponding custom mode"));
+      }
+      
+    } catch (error) {
+      spinner.fail("Repair failed");
+      throw error;
+    }
+  }
+
   async performReinstall(config, installDir, spinner) {
-    spinner.start("Reinstalling BMAD Method...");
+    spinner.start("Preparing to reinstall BMAD Method...");
 
     // Remove existing .bmad-core
     const bmadCorePath = path.join(installDir, ".bmad-core");
     if (await fileManager.pathExists(bmadCorePath)) {
+      spinner.text = "Removing existing installation...";
       await fileManager.removeDirectory(bmadCorePath);
     }
-
+    
-    return await this.performFreshInstall(config, installDir, spinner);
+    spinner.text = "Installing fresh copy...";
+    return await this.performFreshInstall(config, installDir, spinner, { isUpdate: true });
   }
 
-  showSuccessMessage(config, installDir) {
+  showSuccessMessage(config, installDir, options = {}) {
     console.log(chalk.green("\n✓ BMAD Method installed successfully!\n"));
 
     const ides = config.ides || (config.ide ? [config.ide] : []);
@@ -622,7 +809,9 @@ class Installer {
 
     // Information about installation components
     console.log(chalk.bold("\n🎯 Installation Summary:"));
-    console.log(chalk.green("✓ .bmad-core framework installed with all agents and workflows"));
+    if (config.installType !== "expansion-only") {
+      console.log(chalk.green("✓ .bmad-core framework installed with all agents and workflows"));
+    }
     
     if (config.expansionPacks && config.expansionPacks.length > 0) {
       console.log(chalk.green(`✓ Expansion packs installed:`));
@@ -668,6 +857,17 @@ class Installer {
         chalk.dim("Need everything? Run: npx bmad-method install --full")
       );
     }
+
+    // Warning for Cursor custom modes if agents were updated
+    if (options.isUpdate && ides.includes('cursor')) {
+      console.log(chalk.yellow.bold("\n⚠️  IMPORTANT: Cursor Custom Modes Update Required"));
+      console.log(chalk.yellow("Since agents have been updated, you need to manually update your Cursor custom modes:"));
+      console.log(chalk.yellow("1. Open Cursor Settings (Cmd/Ctrl + ,)"));
+      console.log(chalk.yellow("2. Go to: Features > Cursor Tab > Custom Modes"));
+      console.log(chalk.yellow("3. Update each custom mode with the latest agent templates from:"));
+      console.log(chalk.yellow(`   ${path.join(installDir, '.bmad-core', 'agents')}`));
+      console.log(chalk.yellow("4. Copy the full content of each agent file into the corresponding custom mode"));
+    }
   }
 
   // Legacy method for backward compatibility
@@ -767,8 +967,8 @@ class Installer {
       console.log(`  Agent:          ${manifest.agent}`);
     }
 
-    if (manifest.ide_setup) {
+    if (manifest.ides_setup && manifest.ides_setup.length > 0) {
-      console.log(`  IDE Setup:      ${manifest.ide_setup}`);
+      console.log(`  IDE Setup:      ${manifest.ides_setup.join(', ')}`);
     }
 
     console.log(`  Total Files:    ${manifest.files.length}`);
@@ -797,7 +997,7 @@ class Installer {
     return configLoader.getAvailableTeams();
   }
 
-  async installExpansionPacks(installDir, selectedPacks, spinner) {
+  async installExpansionPacks(installDir, selectedPacks, spinner, config = {}) {
     if (!selectedPacks || selectedPacks.length === 0) {
       return [];
     }
@@ -816,11 +1016,112 @@ class Installer {
           console.warn(`Expansion pack ${packId} not found, skipping...`);
           continue;
         }
+        
+        // Check if expansion pack already exists
+        let expansionDotFolder = path.join(installDir, `.${packId}`);
+        const existingManifestPath = path.join(expansionDotFolder, 'install-manifest.yml');
+        
+        if (await fileManager.pathExists(existingManifestPath)) {
+          spinner.stop();
+          const existingManifest = await fileManager.readExpansionPackManifest(installDir, packId);
+          
+          console.log(chalk.yellow(`\n🔍 Found existing ${pack.name} installation`));
+          console.log(`   Current version: ${existingManifest.version || 'unknown'}`);
+          console.log(`   New version: ${pack.version}`);
+          
+          // Check integrity of existing expansion pack
+          const packIntegrity = await fileManager.checkFileIntegrity(installDir, existingManifest);
+          const hasPackIntegrityIssues = packIntegrity.missing.length > 0 || packIntegrity.modified.length > 0;
+          
+          if (hasPackIntegrityIssues) {
+            console.log(chalk.red("   ⚠️  Installation issues detected:"));
+            if (packIntegrity.missing.length > 0) {
+              console.log(chalk.red(`     Missing files: ${packIntegrity.missing.length}`));
+            }
+            if (packIntegrity.modified.length > 0) {
+              console.log(chalk.yellow(`     Modified files: ${packIntegrity.modified.length}`));
+            }
+          }
+          
+          const versionCompare = this.compareVersions(existingManifest.version || '0.0.0', pack.version);
+          
+          if (versionCompare === 0) {
+            console.log(chalk.yellow('   ⚠️  Same version already installed'));
+            
+            const choices = [];
+            if (hasPackIntegrityIssues) {
+              choices.push({ name: 'Repair (restore missing/modified files)', value: 'repair' });
+            }
+            choices.push(
+              { name: 'Force reinstall (overwrite)', value: 'overwrite' },
+              { name: 'Skip this expansion pack', value: 'skip' },
+              { name: 'Cancel installation', value: 'cancel' }
+            );
+            
+            const { action } = await inquirer.prompt([{
+              type: 'list',
+              name: 'action',
+              message: `${pack.name} v${pack.version} is already installed. What would you like to do?`,
+              choices: choices
+            }]);
+            
+            if (action === 'skip') {
+              spinner.start();
+              continue;
+            } else if (action === 'cancel') {
+              console.log(chalk.red('Installation cancelled.'));
+              process.exit(0);
+            } else if (action === 'repair') {
+              // Repair the expansion pack
+              await this.repairExpansionPack(installDir, packId, pack, packIntegrity, spinner);
+              continue;
+            }
+          } else if (versionCompare < 0) {
+            console.log(chalk.cyan('   ⬆️  Upgrade available'));
+            
+            const { proceed } = await inquirer.prompt([{
+              type: 'confirm',
+              name: 'proceed',
+              message: `Upgrade ${pack.name} from v${existingManifest.version} to v${pack.version}?`,
+              default: true
+            }]);
+            
+            if (!proceed) {
+              spinner.start();
+              continue;
+            }
+          } else {
+            console.log(chalk.yellow('   ⬇️  Installed version is newer than available version'));
+            
+            const { action } = await inquirer.prompt([{
+              type: 'list',
+              name: 'action',
+              message: 'What would you like to do?',
+              choices: [
+                { name: 'Keep current version', value: 'skip' },
+                { name: 'Downgrade to available version', value: 'downgrade' },
+                { name: 'Cancel installation', value: 'cancel' }
+              ]
+            }]);
+            
+            if (action === 'skip') {
+              spinner.start();
+              continue;
+            } else if (action === 'cancel') {
+              console.log(chalk.red('Installation cancelled.'));
+              process.exit(0);
+            }
+          }
+          
+          // If we get here, we're proceeding with installation
+          spinner.start(`Removing old ${pack.name} installation...`);
+          await fileManager.removeDirectory(expansionDotFolder);
+        }
 
         const expansionPackDir = pack.packPath;
         
-        // Create dedicated dot folder for this expansion pack
+        // Ensure dedicated dot folder exists for this expansion pack
-        const expansionDotFolder = path.join(installDir, `.${packId}`);
+        expansionDotFolder = path.join(installDir, `.${packId}`);
         await fileManager.ensureDirectory(expansionDotFolder);
         
         // Define the folders to copy from expansion packs
@@ -888,9 +1189,28 @@ class Installer {
         // Check and resolve core agents referenced by teams
         await this.resolveExpansionPackCoreAgents(installDir, expansionDotFolder, packId, spinner);
 
+        // Create manifest for this expansion pack
+        spinner.text = `Creating manifest for ${packId}...`;
+        const expansionConfig = {
+          installType: 'expansion-pack',
+          expansionPackId: packId,
+          expansionPackName: pack.name,
+          expansionPackVersion: pack.version,
+          ides: config.ides || []  // Use ides_setup instead of ide_setup
+        };
+        
+        // Get all files installed in this expansion pack
+        const expansionPackFiles = glob.sync('**/*', {
+          cwd: expansionDotFolder,
+          nodir: true
+        }).map(f => path.join(`.${packId}`, f));
+        
+        await fileManager.createExpansionPackManifest(installDir, packId, expansionConfig, expansionPackFiles);
+
         console.log(chalk.green(`✓ Installed expansion pack: ${pack.name} to ${`.${packId}`}`));
       } catch (error) {
         console.error(chalk.red(`Failed to install expansion pack ${packId}: ${error.message}`));
+        console.error(chalk.red(`Stack trace: ${error.stack}`));
       }
     }
 
@@ -1034,7 +1354,8 @@ class Installer {
                           console.log(chalk.dim(`    Added agent dependency: ${depType}/${depFileName}`));
                         } else {
                           // Try common folder
-                          const commonDepPath = path.join(this.rootDir, 'common', depType, depFileName);
+                          const sourceBase = path.dirname(path.dirname(path.dirname(path.dirname(__filename)))); // Go up to project root
+                          const commonDepPath = path.join(sourceBase, 'common', depType, depFileName);
                           if (await fileManager.pathExists(commonDepPath)) {
                             const destDepPath = path.join(expansionDotFolder, depType, depFileName);
                             await fileManager.copyFile(commonDepPath, destDepPath);
@@ -1157,6 +1478,9 @@ class Installer {
   }
 
   async copyCommonItems(installDir, targetSubdir, spinner) {
+    // Ensure modules are initialized
+    await initializeModules();
+    
     const glob = require('glob');
     const fs = require('fs').promises;
     const sourceBase = path.dirname(path.dirname(path.dirname(path.dirname(__filename)))); // Go up to project root
@@ -1198,6 +1522,133 @@ class Installer {
     return copiedFiles;
   }
 
+  async detectExpansionPacks(installDir) {
+    const expansionPacks = {};
+    const glob = require("glob");
+    
+    // Find all dot folders that might be expansion packs
+    const dotFolders = glob.sync(".*", {
+      cwd: installDir,
+      ignore: [".git", ".git/**", ".bmad-core", ".bmad-core/**"],
+    });
+    
+    for (const folder of dotFolders) {
+      const folderPath = path.join(installDir, folder);
+      const stats = await fileManager.pathExists(folderPath);
+      
+      if (stats) {
+        // Check if it has a manifest
+        const manifestPath = path.join(folderPath, "install-manifest.yml");
+        if (await fileManager.pathExists(manifestPath)) {
+          const manifest = await fileManager.readExpansionPackManifest(installDir, folder.substring(1));
+          if (manifest) {
+            expansionPacks[folder.substring(1)] = {
+              path: folderPath,
+              manifest: manifest,
+              hasManifest: true
+            };
+          }
+        } else {
+          // Check if it has a config.yml (expansion pack without manifest)
+          const configPath = path.join(folderPath, "config.yml");
+          if (await fileManager.pathExists(configPath)) {
+            expansionPacks[folder.substring(1)] = {
+              path: folderPath,
+              manifest: null,
+              hasManifest: false
+            };
+          }
+        }
+      }
+    }
+    
+    return expansionPacks;
+  }
+
+  async repairExpansionPack(installDir, packId, pack, integrity, spinner) {
+    spinner.start(`Repairing ${pack.name}...`);
+    
+    try {
+      const expansionDotFolder = path.join(installDir, `.${packId}`);
+      
+      // Back up modified files
+      if (integrity.modified.length > 0) {
+        spinner.text = "Backing up modified files...";
+        for (const file of integrity.modified) {
+          const filePath = path.join(installDir, file);
+          if (await fileManager.pathExists(filePath)) {
+            const backupPath = await fileManager.backupFile(filePath);
+            console.log(chalk.dim(`  Backed up: ${file} → ${path.basename(backupPath)}`));
+          }
+        }
+      }
+      
+      // Restore missing and modified files
+      spinner.text = "Restoring files...";
+      const filesToRestore = [...integrity.missing, ...integrity.modified];
+      
+      for (const file of filesToRestore) {
+        // Skip the manifest file itself
+        if (file.endsWith('install-manifest.yml')) continue;
+        
+        const relativePath = file.replace(`.${packId}/`, '');
+        const sourcePath = path.join(pack.packPath, relativePath);
+        const destPath = path.join(installDir, file);
+        
+        // Check if this is a common/ file that needs special processing
+        const commonBase = path.dirname(path.dirname(path.dirname(path.dirname(__filename))));
+        const commonSourcePath = path.join(commonBase, 'common', relativePath);
+        
+        if (await fileManager.pathExists(commonSourcePath)) {
+          // This is a common/ file - needs template processing
+          const fs = require('fs').promises;
+          const content = await fs.readFile(commonSourcePath, 'utf8');
+          const updatedContent = content.replace(/\{root\}/g, `.${packId}`);
+          await fileManager.ensureDirectory(path.dirname(destPath));
+          await fs.writeFile(destPath, updatedContent, 'utf8');
+          spinner.text = `Restored: ${file}`;
+        } else if (await fileManager.pathExists(sourcePath)) {
+          // Regular file from expansion pack
+          await fileManager.copyFile(sourcePath, destPath);
+          spinner.text = `Restored: ${file}`;
+        } else {
+          console.warn(chalk.yellow(`  Warning: Source file not found: ${file}`));
+        }
+      }
+      
+      spinner.succeed(`${pack.name} repaired successfully!`);
+      
+      // Show summary
+      console.log(chalk.green(`\n✓ ${pack.name} repaired!`));
+      if (integrity.missing.length > 0) {
+        console.log(chalk.green(`  Restored ${integrity.missing.length} missing files`));
+      }
+      if (integrity.modified.length > 0) {
+        console.log(chalk.green(`  Restored ${integrity.modified.length} modified files (backups created)`));
+      }
+      
+    } catch (error) {
+      spinner.fail(`Failed to repair ${pack.name}`);
+      console.error(chalk.red(`Error: ${error.message}`));
+    }
+  }
+
+  compareVersions(v1, v2) {
+    // Simple semver comparison
+    const parts1 = v1.split('.').map(Number);
+    const parts2 = v2.split('.').map(Number);
+    
+    for (let i = 0; i < 3; i++) {
+      const part1 = parts1[i] || 0;
+      const part2 = parts2[i] || 0;
+      
+      if (part1 > part2) return 1;
+      if (part1 < part2) return -1;
+    }
+    
+    return 0;
+  }
+
   async findInstallation() {
     // Look for .bmad-core in current directory or parent directories
     let currentDir = process.cwd();

tools/installer/package.json

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

tools/update-expansion-version.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+const args = process.argv.slice(2);
+
+if (args.length < 2) {
+  console.log('Usage: node update-expansion-version.js <expansion-pack-id> <new-version>');
+  console.log('Example: node update-expansion-version.js bmad-creator-tools 1.1.0');
+  process.exit(1);
+}
+
+const [packId, newVersion] = args;
+
+// Validate version format
+if (!/^\d+\.\d+\.\d+$/.test(newVersion)) {
+  console.error('Error: Version must be in format X.Y.Z (e.g., 1.2.3)');
+  process.exit(1);
+}
+
+async function updateVersion() {
+  try {
+    // Update in config.yml
+    const configPath = path.join(__dirname, '..', 'expansion-packs', packId, 'config.yml');
+    
+    if (!fs.existsSync(configPath)) {
+      console.error(`Error: Expansion pack '${packId}' not found`);
+      process.exit(1);
+    }
+    
+    const configContent = fs.readFileSync(configPath, 'utf8');
+    const config = yaml.load(configContent);
+    const oldVersion = config.version || 'unknown';
+    
+    config.version = newVersion;
+    
+    const updatedYaml = yaml.dump(config, { indent: 2 });
+    fs.writeFileSync(configPath, updatedYaml);
+    
+    console.log(`✓ Updated ${packId}/config.yml: ${oldVersion} → ${newVersion}`);
+    console.log(`\n✓ Successfully updated ${packId} to version ${newVersion}`);
+    console.log('\nNext steps:');
+    console.log('1. Test the changes');
+    console.log('2. Commit: git add -A && git commit -m "chore: bump ' + packId + ' to v' + newVersion + '"');
+    
+  } catch (error) {
+    console.error('Error updating version:', error.message);
+    process.exit(1);
+  }
+}
+
+updateVersion();