chore(release): 4.24.6 [skip ci]

## [4.24.6](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.5...v4.24.6) (2025-07-04)

### Bug Fixes

* version bump and web build fix ([1c845e5](1c845e5b2c))

.github/FUNDING.yaml

@@ -0,0 +1,15 @@
+# These are supported funding model platforms
+
+github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+polar: # Replace with a single Polar username
+buy_me_a_coffee: bmad
+thanks_dev: # Replace with a single thanks.dev username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,32 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ""
+labels: ""
+assignees: ""
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Steps to Reproduce**
+What lead to the bug and can it be reliable recreated - if so with what steps.
+
+**PR**
+If you have an idea to fix and would like to contribute, please indicate here you are working on a fix, or link to a proposed PR to fix the issue. Please review the contribution.md - contributions are always welcome!
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Please be Specific if relevant**
+Model(s) Used:
+Agentic IDE Used:
+WebSite Used:
+Project Language:
+BMad Method version:
+
+**Screenshots or Links**
+If applicable, add screenshots or links (if web sharable record) to help explain your problem.
+
+**Additional context**
+Add any other context about the problem here. The more information you can provide, the easier it will be to suggest a fix or resolve

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,22 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ""
+labels: ""
+assignees: ""
+---
+
+**Did you discuss the idea first in Discord Server (#general-dev)**
+Yes/No - Link to thread. If no, please after posting request also share the link in the channel so it can be easily discussed.
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.gitignore

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

.prettierignore

@@ -9,7 +9,7 @@ dist/
 *.log
 *.lock
 
-# BMAD core files (have their own formatting)
+# BMad core files (have their own formatting)
 bmad-core/**/*.md
 
 # Specific files that need custom formatting

.vscode/extensions.json

@@ -1,6 +0,0 @@
-{
-	"recommendations": [
-		"davidanson.vscode-markdownlint",
-		"streetsidesoftware.code-spell-checker"
-	]
-}

.vscode/settings.json

@@ -1,77 +1,13 @@
 {
-	"cSpell.words": [
-		"agentic",
-		"Axios",
-		"biomimicry",
-		"BMAD",
-		"Brainwriting",
-		"Centricity",
-		"cicd",
-		"dataclass",
-		"docstrings",
-		"emergently",
-		"explorative",
-		"fintech",
-		"firmographic",
-		"firmographics",
-		"frontends",
-		"gamedev",
-		"golint",
-		"Goroutines",
-		"hotspots",
-		"HSTS",
-		"httpx",
-		"Immer",
-		"implementability",
-		"Inclusivity",
-		"kayvan",
-		"Luxon",
-		"MERN",
-		"mgmt",
-		"nodir",
-		"Nuxt",
-		"overcommitting",
-		"pasteable",
-		"pentest",
-		"PESTEL",
-		"Pino",
-		"Polyrepo",
-		"psychographics",
-		"Pydantic",
-		"pyproject",
-		"reqs",
-		"rescope",
-		"roadmaps",
-		"roleplay",
-		"roomodes",
-		"runbooks",
-		"Serilog",
-		"shadcn",
-		"structlog",
-		"subfolders",
-		"Supabase",
-		"Systemization",
-		"taskroot",
-		"Testcontainers",
-		"tmpl",
-		"tmplv",
-		"touchpoints",
-		"trpc",
-		"Turborepo",
-		"Underserved",
-		"unredacted",
-		"upgrader",
-		"upgraders",
-		"VARCHAR",
-		"venv",
-		"vercel",
-		"Vite",
-		"WCAG",
-		"wireframes"
-	],
-	"markdownlint.config": {
-		"MD033": {
-			"allowed_elements": ["br", "div", "img", "rule", "sub"]
-		}
-	}
-}
+  "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,
+  "cSpell.words": [
+    "Agentic",
+    "elicitations",
+    "Shardable"
+  ]
+}

CHANGELOG.md

@@ -1,3 +1,168 @@
+## [4.24.6](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.5...v4.24.6) (2025-07-04)
+
+
+### Bug Fixes
+
+* version bump and web build fix ([1c845e5](https://github.com/bmadcode/BMAD-METHOD/commit/1c845e5b2c77a77d887d8216152ba09110c72e40))
+
+## [4.24.5](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.4...v4.24.5) (2025-07-04)
+
+
+### Bug Fixes
+
+* yaml standardization in files and installer actions ([094f9f3](https://github.com/bmadcode/BMAD-METHOD/commit/094f9f3eabf563c9a89ecaf360fed63386b46ed4))
+
+## [4.24.4](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.3...v4.24.4) (2025-07-04)
+
+
+### Bug Fixes
+
+* documentation updates ([2018ad0](https://github.com/bmadcode/BMAD-METHOD/commit/2018ad07c7d4c68efb3c24d85ac7612942c6df9c))
+
+## [4.24.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.2...v4.24.3) (2025-07-04)
+
+
+### Bug Fixes
+
+* update YAML library from 'yaml' to 'js-yaml' in resolveExpansionPackCoreAgents for consistency ([#295](https://github.com/bmadcode/BMAD-METHOD/issues/295)) ([03f30ad](https://github.com/bmadcode/BMAD-METHOD/commit/03f30ad28b282fbb4fa5a6ed6b57d0327218cce0))
+
+## [4.24.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.1...v4.24.2) (2025-07-03)
+
+
+### Bug Fixes
+
+* version bump and restore dist folder ([87c451a](https://github.com/bmadcode/BMAD-METHOD/commit/87c451a5c3161fbc86f88619a2bfcfc322eb247e))
+
+## [4.24.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.0...v4.24.1) (2025-07-03)
+
+
+### Bug Fixes
+
+* centralized yamlExtraction function and all now fix character issues for windows ([e2985d6](https://github.com/bmadcode/BMAD-METHOD/commit/e2985d6093136575e8d8c91ce53c82abc4097de6))
+* filtering extension stripping logic update ([405954a](https://github.com/bmadcode/BMAD-METHOD/commit/405954ad924d8bd66f94c918643f6e9c091d4d09))
+* standardize on file extension .yaml instead of a mix of yml and yaml ([a4c0b18](https://github.com/bmadcode/BMAD-METHOD/commit/a4c0b1839d12d2ad21b7949aa30f4f7d82ec6c9c))
+
+# [4.24.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.23.0...v4.24.0) (2025-07-02)
+
+
+### Bug Fixes
+
+* corrected cursor agent update instructions ([84e394a](https://github.com/bmadcode/BMAD-METHOD/commit/84e394ac11136d9cf8164cefc9ca8e298e8ef0ec))
+
+
+### Features
+
+* workflow plans introduced, preliminary feature under review ([731589a](https://github.com/bmadcode/BMAD-METHOD/commit/731589aa287c31ea120e232b4dcc07e9790500ff))
+
+# [4.23.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.22.1...v4.23.0) (2025-07-01)
+
+
+### Features
+
+* Github 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)
+
+
+### Features
+
+* Massive documentation refactor, added explanation of the new expanded role of the QA agent that will make your code quality MUCH better. 2 new diagram clearly explain the role of the pre dev ideation cycle (prd and architecture) and the details of how the dev cycle works. ([c881dcc](https://github.com/bmadcode/BMAD-METHOD/commit/c881dcc48ff827ddfe8653aa364a021a66ce66eb))
+
+## [4.19.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.19.1...v4.19.2) (2025-06-28)
+
+
+### Bug Fixes
+
+* docs update and correction ([2408068](https://github.com/bmadcode/BMAD-METHOD/commit/240806888448bb3a42acfd2f209976d489157e21))
+
+## [4.19.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.19.0...v4.19.1) (2025-06-28)
+
+
+### Bug Fixes
+
+* discord link ([2ea806b](https://github.com/bmadcode/BMAD-METHOD/commit/2ea806b3af58ad37fcb695146883a9cd3003363d))
+
+# [4.19.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.18.0...v4.19.0) (2025-06-28)
+
+
+### Bug Fixes
+
+* expansion install config ([50d17ed](https://github.com/bmadcode/BMAD-METHOD/commit/50d17ed65d40f6688f3b6e62732fb2280b6b116e))
+
+
+### Features
+
+* install for ide now sets up rules also for expansion agents! ([b82978f](https://github.com/bmadcode/BMAD-METHOD/commit/b82978fd38ea789a799ccc1373cfb61a2001c1e0))
+
+# [4.18.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.17.0...v4.18.0) (2025-06-28)
+
+
+### Features
+
+* expansion teams can now include core agents and include their assets automatically ([c70f1a0](https://github.com/bmadcode/BMAD-METHOD/commit/c70f1a056b0f6e3c805096ee5d27f0a3640fb00c))
+* remove hardcoding from installer for agents, improve expansion pack installation to its own locations, common files moved to common folder ([95e833b](https://github.com/bmadcode/BMAD-METHOD/commit/95e833beebc3a60f73a7a1c67d534c8eb6bf48fd))
+
+# [4.17.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.16.1...v4.17.0) (2025-06-27)
+
+
+### Features
+
+* add GEMINI.md to agent context files ([#272](https://github.com/bmadcode/BMAD-METHOD/issues/272)) ([b557570](https://github.com/bmadcode/BMAD-METHOD/commit/b557570081149352e4efbef8046935650f6ecea1))
+
+## [4.16.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.16.0...v4.16.1) (2025-06-26)
+
+
+### Bug Fixes
+
+* remove accidental folder add ([b1c2de1](https://github.com/bmadcode/BMAD-METHOD/commit/b1c2de1fb58029f68e021faa90cd5d5faf345198))
+
+# [4.16.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.15.0...v4.16.0) (2025-06-26)
+
+
+### Features
+
+* repo builds all rules sets for supported ides for easy copy if desired ([ea945bb](https://github.com/bmadcode/BMAD-METHOD/commit/ea945bb43f6ea50594910b954c72e79f96a8504c))
+
 # [4.15.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.14.1...v4.15.0) (2025-06-26)
 
 
@@ -92,7 +257,7 @@
 
 ### Features
 
-* dev can use debug log configured in core-config.yml ([0e5aaf0](https://github.com/bmadcode/BMAD-METHOD/commit/0e5aaf07bbc6fd9f2706ea26e35f5f38fd72147a))
+* dev can use debug log configured in core-config.yaml ([0e5aaf0](https://github.com/bmadcode/BMAD-METHOD/commit/0e5aaf07bbc6fd9f2706ea26e35f5f38fd72147a))
 
 # [4.8.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.7.0...v4.8.0) (2025-06-19)
 

CONTRIBUTING.md

@@ -4,10 +4,15 @@ Thank you for considering contributing to this project! This document outlines t
 
 🆕 **New to GitHub or pull requests?** Check out our [beginner-friendly Pull Request Guide](docs/how-to-contribute-with-pull-requests.md) first!
 
-📋 **Before contributing**, please read our [Guiding Principles](GUIDING-PRINCIPLES.md) to understand the BMAD Method's core philosophy and architectural decisions.
+📋 **Before contributing**, please read our [Guiding Principles](GUIDING-PRINCIPLES.md) to understand the BMad Method's core philosophy and architectural decisions.
 
 Also note, we use the discussions feature in GitHub to have a community to discuss potential ideas, uses, additions and enhancements.
 
+💬 **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
-- Include detailed steps to reproduce the bug
-- Include any relevant logs or screenshots
+1. **Check existing issues** first to avoid duplicates
+2. **Use the bug report template** when creating a new issue - it will guide you through providing:
+   - 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
 

GUIDING-PRINCIPLES.md

@@ -1,6 +1,6 @@
-# BMAD Method Guiding Principles
+# BMad Method Guiding Principles
 
-The BMAD Method is a natural language framework for AI-assisted software development. These principles ensure contributions maintain the method's effectiveness.
+The BMad Method is a natural language framework for AI-assisted software development. These principles ensure contributions maintain the method's effectiveness.
 
 ## Core Principles
 

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 Brian AKA BMad AKA Bmad Code
+Copyright (c) 2025 Brian AKA BMad AKA BMad Code
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,76 +1,141 @@
-# BMAD-METHOD
+# BMad-Method: Universal AI Agent Framework
 
 [![Version](https://img.shields.io/npm/v/bmad-method?color=blue&label=version)](https://www.npmjs.com/package/bmad-method)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 [![Node.js Version](https://img.shields.io/badge/node-%3E%3D20.0.0-brightgreen)](https://nodejs.org)
-[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/g6ypHytrCB)
+[![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 
-**AI-Powered Agile Development Framework** - Transform your software development with specialized AI agents that work as your complete Agile team.
+Foundations in Agentic Agile Driven Development, known as the Breakthrough Method of Agile AI-Driven Development, but it is so much more. Transform any domain with specialized AI expertise: software development, entertainment, creative writing, business strategy to personal wellness just to name a few.
 
-📺 **[Subscribe to BMadCode on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)** - V4 walkthrough and comprehensive guide coming soon!
+**[Subscribe to BMadCode on YouTube](https://www.youtube.com/@BMadCode?sub_confirmation=1)**
 
-⭐ **If you find this project helpful or useful, please give it a star!** It helps others discover BMAD-METHOD and you will be notified of updates!
+**[Join our Discord Community](https://discord.gg/gk8jAdXWmj)** - A growing community for AI enthusiasts! Get help, share ideas, explore AI agents & frameworks, collaborate on tech projects, enjoy hobbies, and help each other succeed. Whether you're stuck on BMad, building your own agents, or just want to chat about the latest in AI - we're here for you!
 
-## 🔄 Important: Keeping Your BMAD Installation Updated
+⭐ **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!
 
-**Stay up-to-date effortlessly!** If you already have BMAD-METHOD installed in your project, simply run:
+## Quick Navigation
+
+### 🚨 MUST READ: Understanding the BMad Workflow
+
+**Before diving in, review these critical workflow diagrams that explain how BMad works:**
+
+1. **[Planning Workflow (Web UI)](docs/user-guide.md#the-planning-workflow-web-ui)** - How to create PRD and Architecture documents
+2. **[Core Development Cycle (IDE)](docs/user-guide.md#the-core-development-cycle-ide)** - How SM, Dev, and QA agents collaborate through story files
+
+> ⚠️ **These diagrams explain 90% of BMad Method Agentic Agile flow confusion** - Understanding the PRD+Architecture creation and the SM/Dev/QA workflow and how agents pass notes through story files is essential - and also explains why this is NOT taskmaster or just a simple task runner!
+
+### What would you like to do?
+
+- **[Build software with Full Stack Agile AI Team](quick-start)** → Quick Start Instruction
+- **[Learn how to use BMad](docs/user-guide.md)** → Complete user guide and walkthrough
+- **[See available AI agents](#available-agents)** → Specialized roles for your team
+- **[Explore non-technical uses](#-beyond-software-development---expansion-packs)** → Creative writing, business, wellness, education
+- **[Create my own AI agents](#creating-your-own-expansion-pack)** → Build agents for your domain
+- **[Browse ready-made expansion packs](expansion-packs/)** → Game dev, DevOps, infrastructure and get inspired with ideas and examples
+- **[Understand the architecture](docs/core-architecture.md)** → Technical deep dive
+- **[Join the community](https://discord.gg/g6ypHytrCB)** → Get help and share ideas
+
+### Popular Use Cases
+
+- **Software Development** - [Quick Start](quick-start) | [User Guide](docs/user-guide.md) | [Workflow Guides](#documentation--guides)
+- **Game Development** - [2D Phaser Pack](expansion-packs/bmad-2d-phaser-game-dev/)
+- **Business Strategy** - [Full Guide](docs/expansion-packs.md#business-strategy-pack)
+- **Creative Writing** - [Full Guide](docs/expansion-packs.md#creative-writing-pack)
+- **DevOps/Infrastructure** - [Infrastructure Pack](expansion-packs/bmad-infrastructure-devops/)
+
+### Quick Links
+
+- **[Installation](#installation)** → Get started in minutes
+- **[Documentation](#documentation--guides)** → All guides and references
+- **[Contributing](#contributing)** → Help improve BMad
+- **[Support](#support)** → Get help and connect
+
+## 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
 ```
 
-The installer will:
+This will:
 
 - ✅ Automatically detect your existing v4 installation
-- ✅ Update only the files that have changed
+- ✅ Update only the files that have changed and add new files
 - ✅ Create `.bak` backup files for any custom modifications you've made
 - ✅ Preserve your project-specific configurations
 
-This makes it easy to benefit from the latest improvements, bug fixes, and new agents without losing your customizations!
+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`
-
-This installs all agents and configures them for your IDE. If you have an existing v3 installation, it will offer to upgrade it automatically.
-
-## 📋 Table of Contents
-
-- [Overview](#overview)
-- [Installation](#installation)
-- [Available Agents](#available-agents)
-- [Usage](#usage)
-- [Project Structure](#project-structure)
-- [Contributing](#contributing)
+```bash
+git clone https://github.com/bmadcode/bmad-method.git
+npm run install:bmad # build and install all to a destination folder
+```
 
 ## Overview
 
-BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) revolutionizes software development by providing specialized AI agents for every role in an Agile team. Each agent has deep expertise in their domain and can collaborate to deliver complete software projects.
+The BMad Method (Breakthrough Method of Agile Agentic-Driven Development) elevates 'Vibe Coding' by utilizing advanced prompt engineering techniques and critical context management at the most critical stages of development implementation. 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.
 
-### Why BMAD?
-
-- **🎯 Specialized Expertise**: Each agent is an expert in their specific role
-- **🔄 True Agile Workflow**: Follows real Agile methodologies and best practices
-- **📦 Modular Design**: Use one agent or an entire team
-- **🛠️ IDE Integration**: Works seamlessly with Cursor, Claude Code, and Windsurf
-- **🌐 Platform Agnostic**: Use with ChatGPT, Claude, Gemini, or any AI platform
+Unlike systems like Task Master, or inbuilt Task tools, the BMad Methods agile flow does so much more. With most systems, you give your idea, and the system churns out a plan, task list, lets you review it and then starts executing. Where the BMad agile flow is different is you can choose to have more upfront planning and architecture specification to ensure the system is built in a sustainable way, not a vibe coded spaghetti mess. When producing the PRD and Architectures (full stack, front end and or backend), the Agents work with you back and forth using advanced proven LLM prompt engineering advanced techniques to produce anything beyond what the average slop LLMs and Task generators will produce on their own. This truly is a system of Human in the Loop producing markedly better results.
 
 ## 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:
 
@@ -81,49 +146,73 @@ 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:
 
-- `cursor` - Cursor IDE with @agent commands
+- `cursor` - Cursor IDE with manual rule @agent commands
 - `claude-code` - Claude Code with /agent commands
-- `windsurf` - Windsurf with @agent commands
+- `cline` - Cline Rules integration
+- `gemini-cli` - Gemini with @agent commands
+- `windsurf` - Windsurf with manual rule @agent commands
 - `roo` - Roo Code with custom modes (see `.roomodes`)
-- More coming soon - BUT ITS easy to use with ANY IDE - just copy the bmad-code folder to your project, and rename it .bmad-code.
+- `github-copilot` - GitHub Copilot agent mode integration
 
 ## Available Agents
 
 ### Core Development Team
 
-| Agent       | Role               | Specialty                                     |
-| ----------- | ------------------ | --------------------------------------------- |
-| `analyst`   | Business Analyst   | market analysis, brainstorming, project brief |
-| `pm`        | Product Manager    | Product strategy, roadmaps, PRDs              |
-| `architect` | Solution Architect | System design, technical architecture         |
-| `dev`       | Developer          | Code implementation across all technologies   |
-| `qa`        | QA Specialist      | Testing strategies, quality assurance         |
-| `ux-expert` | UX Designer        | User experience, UI design, prototypes        |
-| `po`        | Product Owner      | Backlog management, story validation          |
-| `sm`        | Scrum Master       | Sprint planning, story creation               |
+| Agent       | Role               | Specialty                                                                                    |
+| ----------- | ------------------ | -------------------------------------------------------------------------------------------- |
+| `analyst`   | Business Analyst   | market analysis, brainstorming, project brief creation                                       |
+| `pm`        | Product Manager    | Product strategy, MVP Decisioning, PRD creation with Epics                                   |
+| `architect` | Solution Architect | System design, technical full stack, front end or backend architecture                       |
+| `ux-expert` | UX Designer        | User experience, UI design, prompts for V0, Lovable, and others                              |
+| `po`        | Product Owner      | Ensure PRD and Architecture are aligned, and changes from architecture end up in PRD stories |
+| `sm`        | Scrum Master       | High level epics and stories transformed into detailed dev stories with tasks and subtasks   |
+| `dev`       | Developer          | Code implementation across all technologies - follows the detailed SM created story          |
+| `qa`        | QA Specialist      | Detailed review of the devs ready for review story, refactor and propose issues and changes  |
 
-### Meta Agents
+### BMad Agents
 
-| Agent               | Role             | Specialty                                                           |
-| ------------------- | ---------------- | ------------------------------------------------------------------- |
-| `bmad-orchestrator` | Team Coordinator | Multi-agent workflows, role switching, is part of every team bundle |
-| `bmad-master`       | Universal Expert | All capabilities without switching                                  |
+| Agent               | Role             | Specialty                                                                                                                |
+| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `bmad-orchestrator` | Team Coordinator | Helps guide you and answers your questions with its massive knowledge base, and guides you through Multi-agent workflows |
+| `bmad-master`       | Universal Expert | All capabilities without switching (Except Dev)                                                                          |
+
+## Advanced Features
+
+### Dynamic Dependencies
+
+Each agent only loads the resources it needs, keeping context windows lean.
+
+### Template System
+
+Rich templates for all document types:
+
+- Product Requirements (PRD)
+- Architecture Documents
+- User Stories
+- Test Plans
+- And more...
+
+Templates are unique in that they are embedded with the LLM instructions also for further working with you to prompt and elicit the best from you and your agile agent team member - allowing for unique coaching and customization options. While there is a single create-doc task, the possibilities are endless when you expand the templates into more doc types, or customize with your own docs embedded with the templating markup and LLM instruction framework that is core to the BMad Method.
+
+### Slash Star Commands
+
+Ask the agent you are using for help with /help (in the web) or \*help in the ide to see what commands are available!
+
+### Advanced Elicitation
+
+Many of the Agents and Templates for docs, and some tasks, include Advanced Elicitation directives based on the latest in LLM interactions and pro level prompt engineering guidance. With this, you can push the Agents further than ever before. If an agent proposes an idea, or an architecture - you can push it further with optional elicitations where it will have to really expand on, defend, or produce other options and prove its suggestion was better. This is a necessary step if you want the absolute best beyond accepting the generated average responses the LLMs think you want to hear for their first response. Some of this is interactive, and some of this is baked into the core prompting engine that powers the LLM progression through various tasks and template flows.
 
 ## Usage
 
-### With IDE Integration
+The BMad Method follows a structured Agile workflow with specialized AI agents. For complete usage instructions and walkthroughs, see the **[User Guide](docs/user-guide.md)**.
 
-After installation with `--ide` flag:
+### Quick Start Examples
+
+#### With IDE Integration
 
 ```bash
 # In Cursor
@@ -136,118 +225,29 @@ After installation with `--ide` flag:
 @dev Implement story 1.3
 ```
 
-### With Web UI (ChatGPT/Claude/Gemini)
+#### With Web UI
 
-After uploading a bundle you can ask /help of the agent to learn what it can do
+After uploading a bundle, type `/help` to see available commands.
 
-### CLI Commands
+### Key Resources
 
-```bash
-# List all available agents
-npx bmad-method list
-
-# Install or update (automatically detects existing installations)
-npx bmad-method install
-
-# Check installation status
-npx bmad-method status
-```
-
-### Upgrading from V3 to V4
-
-If you have an existing BMAD-METHOD V3 project, simply run the installer in your project directory:
-
-```bash
-npx bmad-method install
-# The installer will automatically detect your V3 installation and offer to upgrade
-```
-
-The upgrade process will:
-
-1. Create a backup of your V3 files in `.bmad-v3-backup/`
-2. Install the new V4 `.bmad-core/` structure
-3. Migrate your documents (PRD, Architecture, Stories, Epics)
-4. Set up IDE integration for all V4 agents
-5. Create an install manifest for future updates
-
-After upgrading:
-
-1. Review your documents in the `docs/` folder - if you had a PRD or architecture in your old project, copy it from the backup to the docs folder if they are not there.
-2. Optionally run the `doc-migration-task` to align your documents with V4 templates - you can do this with your agent my saying something like: 'run {drag in task} against {drag prd or arch file from docs} to align with {drag the template from .bmad-core/templates/full-stack-architecture.md}
-3. If you have separate front-end and backend architecture docs you can modify step 2 to merge both into a single full stack architecture or separate Front and Back end.
-
-The reason #2 and 3 are optional is because now BMad V4 makes sharding optional for the SM. See [Core Configuration](#-core-configuration-new-in-v4)
-
-**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/` - you can remove the backup folder versions.
-
-### 🔧 Core Configuration (NEW in V4)
-
-**Critical**: V4 introduces `bmad-core/core-config.yml` - a powerful configuration file that enables BMAD to work seamlessly with any project structure, whether it's V4-optimized or legacy. You can even now use non-standard PRDs and architectures!
-
-#### What is core-config.yml?
-
-This configuration file tells BMAD agents exactly where to find your project documents and how they're structured. It's the key to V4's flexibility and backwards compatibility.
-
-#### Key Features
-
-- **Version Awareness**: Agents understand if your PRD/Architecture follows V4 conventions or earlier versions
-- **Flexible Document Locations**: Works whether your epics are embedded in PRD or properly sharded
-- **Developer Context**: Define which files the dev agent should always load
-- **Debug Support**: Built-in logging for troubleshooting story implementation
-
-#### Why It Matters
-
-- **Use BMAD with ANY project structure** - V3, V4, or custom layouts
-- **No forced migrations** - Keep your existing document organization
-- **Customize developer workflow** - Specify exactly which files provide context
-- **Seamless upgrades** - Start with V3 docs and gradually adopt V4 patterns
-
-See the [detailed core-config.yml guide](docs/user-guide.md#core-configuration-coreconfigyml) for configuration examples and best practices.
-
-## Teams & Workflows
-
-### Pre-Configured Teams
-
-Save context by using specialized teams:
-
-- **Team All**: Complete Agile team with all 10 agents
-- **Team Fullstack**: Frontend + Backend development focus
-- **Team No-UI**: Backend/API development without UX
-
-### Workflows
-
-Structured approaches for different scenarios:
-
-- **Greenfield**: Starting new projects (fullstack/service/UI)
-- **Brownfield**: Enhancing existing projects
-- **Simple**: Quick prototypes and MVPs
-- **Complex**: Enterprise and large-scale projects
+- **[Complete User Guide](docs/user-guide.md)** - Full walkthrough from project inception to completion
+- **[CLI Commands](docs/user-guide.md#cli-commands)** - Installation, updates, and management
+- **[Upgrading from V3](docs/user-guide.md#upgrading-from-v3-to-v4)** - Migration instructions
+- **[Core Configuration](docs/user-guide.md#core-configuration)** - V4's flexible project structure support
+- **[Teams & Workflows](docs/user-guide.md#team-configurations)** - Pre-configured agent teams
 
 ## Project Structure
 
-```plaintext
-.bmad-core/
-├── agents/          # Individual agent definitions
-├── agent-teams/     # Team configurations
-├── workflows/       # Development workflows
-├── templates/       # Document templates (PRD, Architecture, etc.)
-├── tasks/           # Reusable task definitions
-├── checklists/      # Quality checklists
-├── data/            # Knowledge base
-└── web-bundles/     # Optional can be added if you use the install command and select this folder as a destination for the build bundle files
+See the **[Core Architecture](docs/core-architecture.md)** for the complete source tree and detailed explanations of each component.
 
-tools/
-├── cli.js           # Build tool
-├── installer/       # NPX installer
-└── lib/             # Build utilities
+### Key Directories
 
-expansion-packs/     # Domain-specific add-ons (Technical & Non-Technical)
-
-dist/                # 📦 PRE-BUILT BUNDLES (Ready to use!)
-├── agents/          # Individual agent bundles (.txt files)
-├── teams/           # Team bundles (.txt files)
-└── expansion-packs/ # Expansion pack bundles
-```
+- **`.bmad-core/`** - Heart of the framework (agents, templates, workflows)
+- **`dist/`** - Pre-built bundles ready for web UI use
+- **`expansion-packs/`** - Domain-specific extensions
+- **`tools/`** - Build and installation utilities
+- **`docs/`** - Your project documentation (PRD, architecture, stories)
 
 ### 📦 Pre-Built Bundles (dist/ folder)
 
@@ -269,105 +269,62 @@ dist/                # 📦 PRE-BUILT BUNDLES (Ready to use!)
 
 **For Web UI usage**: Simply copy any `.txt` file from `dist/` and upload to your AI platform!`
 
-## Advanced Features
+## Documentation & Guides
 
-### Dynamic Dependencies
+### Architecture & Technical
 
-Each agent only loads the resources it needs, keeping context windows lean.
+- 🏗️ [Core Architecture](docs/core-architecture.md) - Complete technical architecture and system design
+- 📖 [User Guide](docs/user-guide.md) - Comprehensive guide to using BMad-Method effectively
+- 🚀 [Expansion Packs Guide](docs/expansion-packs.md) - Extend BMad to any domain beyond software development
 
-### Template System
+### Workflow Guides
 
-Rich templates for all document types:
+- 📚 [Universal BMad Workflow Guide](docs/bmad-workflow-guide.md) - Core workflow that applies to all IDEs
+- 🏗️ [Working in the Brownfield Guide](docs/working-in-the-brownfield.md) - Complete guide for enhancing existing projects
 
-- Product Requirements (PRD)
-- Architecture Documents
-- User Stories
-- Test Plans
-- And more...
+### IDE-Specific Guides
 
-### Slash Star Commands
+- 🎯 [Cursor Guide](docs/agentic-tools/cursor-guide.md) - Setup and usage for Cursor
+- 🤖 [Claude Code Guide](docs/agentic-tools/claude-code-guide.md) - Setup and usage for Claude Code
+- 🌊 [Windsurf Guide](docs/agentic-tools/windsurf-guide.md) - Setup and usage for Windsurf
+- 🦘 [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
+- 💻 [Github Copilot Guide](docs/agentic-tools/github-copilot-guide.md) - Setup and usage for VS Code with GitHub Copilot
 
-Ask the agent you are using for help with /help (in the web) or \*help in the ide to see what commands are available!
+## 🌟 Beyond Software Development - Expansion Packs
 
-## Expansion Packs - Beyond Software Development
+While BMad excels at software development, its natural language framework can structure expertise in ANY domain. Expansion packs transform BMad into a universal AI agent system for creative writing, business strategy, health & wellness, education, and much more.
 
-BMAD Method's natural language framework isn't limited to software development. Create specialized agents for ANY domain:
+### Available Expansion Packs
 
-### Technical Expansion Packs
+#### Technical Domains
 
-- 🎮 **Game Development** - Game designers, level creators, narrative writers
-- 🏗️ **Infrastructure/DevOps** - Cloud architects, security specialists, SRE agents
-- 📱 **Mobile Development** - iOS/Android specialists, UX designers
+- 🎮 **[Game Development](expansion-packs/bmad-2d-phaser-game-dev/)** - Complete game studio team with designers, developers, and narrative writers
+- 🏗️ **[Infrastructure/DevOps](expansion-packs/bmad-infrastructure-devops/)** - Cloud architects, security specialists, SRE experts
+- 📱 **Mobile Development** - iOS/Android specialists, mobile UX designers
 - 🔗 **Blockchain/Web3** - Smart contract developers, DeFi architects
 
-### Non-Technical Expansion Packs
+#### Non-Technical Domains
 
 - 💼 **Business Strategy** - Strategic planners, market analysts, business coaches
 - 💪 **Health & Wellness** - Fitness coaches, nutrition advisors, meditation guides
 - 🎨 **Creative Arts** - Story writers, world builders, character developers
 - 📚 **Education** - Curriculum designers, tutors, learning coaches
 - 🧠 **Personal Development** - Life coaches, goal setters, habit builders
-- 🏢 **Professional Services** - Legal advisors, medical protocols, research assistants
+- 🏢 **Professional Services** - Legal advisors, content creators, research assistants
 
 ### Creating Your Own Expansion Pack
 
-The BMAD framework can support any domain where structured AI assistance is valuable:
+Transform your expertise into AI agents:
 
-1. Define specialized agents with domain expertise
-2. Create task procedures for common workflows
-3. Build templates for domain-specific outputs
-4. Package as an expansion pack for others to use
+1. **Identify your domain** - What knowledge do you want to share?
+2. **Design specialized agents** - Each with unique expertise and personality
+3. **Create reusable tasks** - Standard procedures in your field
+4. **Build professional templates** - Structured outputs for consistency
+5. **Share with the community** - Help others benefit from your expertise
 
-📖 **[Read the full Expansion Packs Guide](docs/expansion-packs.md)** for detailed examples and inspiration!
-
-🛠️ **[Use the Expansion Pack Creator](expansion-packs/expansion-creator/README.md)** to build your own!
-
-## Contributing
-
-**We're excited about contributions and welcome your ideas, improvements, and expansion packs!** 🎉
-
-### Before Contributing - MUST READ
-
-To ensure your contribution aligns with the BMAD Method and gets merged smoothly:
-
-1. 📋 **Read [CONTRIBUTING.md](CONTRIBUTING.md)** - Our contribution guidelines, PR requirements, and process
-2. 🎯 **Read [GUIDING-PRINCIPLES.md](GUIDING-PRINCIPLES.md)** - Core principles that keep BMAD powerful through simplicity
-3. 🆕 **New to GitHub?** Start with our [Pull Request Guide](docs/how-to-contribute-with-pull-requests.md)
-
-### Key Points to Remember
-
-- Keep dev agents lean (save context for coding!)
-- Use small, focused files over large branching ones
-- Reuse existing tasks (like `create-doc`) instead of creating duplicates
-- Consider expansion packs for domain-specific features
-- All contributions must follow our natural language, markdown-based approach
-
-We're building something amazing together - let's keep it simple, powerful, and focused! 💪
-
-### Development Setup
-
-```bash
-git clone https://github.com/bmadcode/bmad-method.git
-cd bmad-method
-npm install
-```
-
-## Documentation & Guides
-
-### Architecture & Technical
-
-- 🏗️ [Core Architecture](docs/core-architecture.md) - Complete technical architecture and system design
-- 📖 [User Guide](docs/user-guide.md) - Comprehensive guide to using BMAD-METHOD effectively
-- 🚀 [Expansion Packs Guide](docs/expansion-packs.md) - Extend BMAD to any domain beyond software development
-
-### Workflow Guides
-
-- 📚 [Universal BMAD Workflow Guide](docs/bmad-workflow-guide.md) - Core workflow that applies to all IDEs
-- 🏗️ [Working in the Brownfield Guide](docs/working-in-the-brownfield.md) - Complete guide for enhancing existing projects
-- 🎯 [Cursor Guide](docs/cursor-guide.md) - Complete workflow for Cursor users
-- 🤖 [Claude Code Guide](docs/claude-code-guide.md) - Complete workflow for Claude Code users
-- 🌊 [Windsurf Guide](docs/windsurf-guide.md) - Complete workflow for Windsurf users
-- 🦘 [Roo Code Guide](docs/roo-code-guide.md) - Complete workflow for Roo Code users
+📖 **[Read the full Expansion Packs Guide](docs/expansion-packs.md)** - Detailed examples, inspiration, and technical details
 
 ## Support
 
@@ -384,9 +341,9 @@ MIT License - see [LICENSE](LICENSE) for details.
 
 - **Current**: [v4](https://github.com/bmadcode/bmad-method) - Complete framework rewrite with CLI installer, dynamic dependencies, and expansion packs
 - **Previous Versions**:
-  - [Version 3](https://github.com/bmadcode/BMAD-METHOD/tree/V3) - Introduced the unified BMAD Agent and Gemini optimization
-  - [Version 2](https://github.com/bmadcode/BMAD-METHOD/tree/V2) - Added web agents and template separation
-  - [Version 1](https://github.com/bmadcode/BMAD-METHOD/tree/V1) - Original 7-file proof of concept
+  - [Version 3](https://github.com/bmadcode/BMad-Method/tree/V3) - Introduced the unified BMad Agent and Gemini optimization
+  - [Version 2](https://github.com/bmadcode/BMad-Method/tree/V2) - Added web agents and template separation
+  - [Version 1](https://github.com/bmadcode/BMad-Method/tree/V1) - Original 7-file proof of concept
 
 See [versions.md](docs/versions.md) for detailed version history and migration guides.
 
@@ -394,7 +351,39 @@ See [versions.md](docs/versions.md) for detailed version history and migration g
 
 Created by Brian (BMad) Madison
 
----
+## Contributing
+
+**We're excited about contributions and welcome your ideas, improvements, and expansion packs!** 🎉
+
+### Before Contributing - MUST READ
+
+To ensure your contribution aligns with the BMad Method and gets merged smoothly:
+
+1. 📋 **Read [CONTRIBUTING.md](CONTRIBUTING.md)** - Our contribution guidelines, PR requirements, and process
+2. 🎯 **Read [GUIDING-PRINCIPLES.md](GUIDING-PRINCIPLES.md)** - Core principles that keep BMad powerful through simplicity
+3. 🆕 **New to GitHub?** Start with our [Pull Request Guide](docs/how-to-contribute-with-pull-requests.md)
+
+### Key Points to Remember
+
+- Keep dev agents lean (save context for coding!)
+- Use small, focused files over large branching ones
+- Reuse existing tasks (like `create-doc`) instead of creating duplicates
+- Consider expansion packs for domain-specific features and not improvements to the core system (those belong in the core system)
+- All contributions must follow our natural language, markdown-based templating approach with template embedded LLM instructions and elicitations
+
+We're building something amazing together - let's keep it simple, powerful, and focused! 💪
+
+### Development Setup
+
+Want to help improve the BMad Method. Fork n' Clone the repo
+
+```bash
+git clone https://github.com/bmadcode/bmad-method.git
+cd bmad-method
+
+npm run build # rebuild the dist folder
+npm run install:bmad # build and install all to a destination folder
+```
 
 [![Contributors](https://contrib.rocks/image?repo=bmadcode/bmad-method)](https://github.com/bmadcode/bmad-method/graphs/contributors)
 

bmad-core/agents/analyst.md

@@ -1,6 +1,6 @@
 # analyst
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 root: .bmad-core

bmad-core/agents/architect.md

@@ -1,6 +1,6 @@
 # architect
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 root: .bmad-core

bmad-core/agents/bmad-master.md

@@ -1,31 +1,34 @@
 # bmad-master
 
-CRITICAL: Read the full YML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 root: .bmad-core
 IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
 agent:
   name: BMad Master
   id: bmad-master
-  title: BMAD Master Task Executor
+  title: BMad Master Task Executor
   icon: 🧙
   whenToUse: Use when you need comprehensive expertise across all domains or rapid context switching between multiple agent capabilities
 persona:
-  role: Master Task Executor & BMAD Method Expert
-  style: Efficient, direct, action-oriented. Executes any BMAD task/template/util/checklist with precision
-  identity: Universal executor of all BMAD-METHOD capabilities, directly runs any resource
+  role: Master Task Executor & BMad Method Expert
+  style: Efficient, direct, action-oriented. Executes any BMad task/template/util/checklist with precision
+  identity: Universal executor of all BMad-Method capabilities, directly runs any resource
   focus: Direct execution without transformation, load resources only when needed
   core_principles:
     - Execute any resource directly without persona transformation
     - Load resources at runtime, never pre-load
-    - Expert knowledge of all BMAD resources
+    - Expert knowledge of all BMad resources
     - Track execution state and guide multi-step processes
     - Use numbered lists for choices
     - Process (*) commands immediately
 startup:
   - Greet the user with your name and role, and inform of the *help command.
+  - Check for active workflow plan using utils#plan-management
+  - "If plan exists: Show brief status - Active plan detected: {workflow} - {progress}%"
+  - "If plan exists: Suggest next step based on plan"
   - CRITICAL: Do NOT scan filesystem or load any resources during startup
   - CRITICAL: Do NOT run discovery tasks automatically
   - Wait for user request before any tool use
@@ -37,16 +40,24 @@ commands:  # All commands require * prefix when used (e.g., *help)
   - status: Current context
   - task {template|util|checklist|workflow}: Execute
   - list {task|template|util|checklist|workflow}: List resources by type
+  - plan: Create workflow plan (for complex projects)
+  - plan-status: Show current workflow plan progress
+  - plan-update: Update workflow plan status
   - exit: Exit (confirm)
   - yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
   - doc-out: Output full document
 fuzzy-matching:
   - 85% confidence threshold
   - Show numbered list if unsure
+workflow-guidance:
+  - When user asks about workflows, offer: "Would you like me to create a workflow plan first? (*plan)"
+  - For complex projects, suggest planning before execution
+  - Plan command maps to create-workflow-plan task
 execution:
   - NEVER use tools during startup - only announce and wait
   - Runtime discovery ONLY when user requests specific resources
   - Workflow: User request → Runtime discovery → Load resource → Execute instructions → Guide inputs → Provide feedback
+  - For workflow requests: Suggest *plan command first for complex projects
   - Suggest related resources after completion
 dependencies:
   tasks:
@@ -54,18 +65,18 @@ dependencies:
     - brainstorming-techniques
     - brownfield-create-epic
     - brownfield-create-story
-    - core-dump
     - correct-course
     - create-deep-research-prompt
     - create-doc
+    - create-workflow-plan
     - document-project
     - create-next-story
     - execute-checklist
     - generate-ai-frontend-prompt
     - index-docs
     - shard-doc
+    - update-workflow-plan
   templates:
-    - agent-tmpl
     - architecture-tmpl
     - brownfield-architecture-tmpl
     - brownfield-prd-tmpl
@@ -81,7 +92,7 @@ dependencies:
     - bmad-kb
     - technical-preferences
   utils:
-    - agent-switcher.ide
+    - plan-management
     - template-format
     - workflow-management
   workflows:

bmad-core/agents/bmad-orchestrator.md

@@ -1,6 +1,6 @@
 # bmad
 
-CRITICAL: Read the full YML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML to understand your operating params, start activation to alter your state of being, follow startup instructions, stay in this being until told to exit this mode:
 
 ```yaml
 root: .bmad-core
@@ -9,13 +9,13 @@ REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (
 agent:
   name: BMad Orchestrator
   id: bmad-orchestrator
-  title: BMAD Master Orchestrator
+  title: BMad Master Orchestrator
   icon: 🎭
   whenToUse: Use for workflow coordination, multi-agent tasks, role switching guidance, and when unsure which specialist to consult
 persona:
-  role: Master Orchestrator & BMAD Method Expert
-  style: Knowledgeable, guiding, adaptable, efficient, encouraging, technically brilliant yet approachable. Helps customize and use BMAD Method while orchestrating agents
-  identity: Unified interface to all BMAD-METHOD capabilities, dynamically transforms into any specialized agent
+  role: Master Orchestrator & BMad Method Expert
+  style: Knowledgeable, guiding, adaptable, efficient, encouraging, technically brilliant yet approachable. Helps customize and use BMad Method while orchestrating agents
+  identity: Unified interface to all BMad-Method capabilities, dynamically transforms into any specialized agent
   focus: Orchestrating the right agent/capability for each need, loading resources only when needed
   core_principles:
     - Become any agent on demand, loading files only when needed
@@ -28,9 +28,12 @@ persona:
     - Process commands starting with * immediately
     - Always remind users that commands require * prefix
 startup:
-  - Announce: Introduce yourself as the BMAD Orchestrator, explain you can coordinate agents and workflows
+  - Announce: Introduce yourself as the BMad Orchestrator, explain you can coordinate agents and workflows
   - IMPORTANT: Tell users that all commands start with * (e.g., *help, *agent, *workflow)
   - Mention *help shows all available commands and options
+  - Check for active workflow plan using utils#plan-management
+  - "If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details."
+  - "If plan exists: Suggest next action based on plan progress"
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -38,25 +41,28 @@ startup:
 commands:  # All commands require * prefix when used (e.g., *help, *agent pm)
   help: Show this guide with available agents and workflows
   chat-mode: Start conversational mode for detailed assistance  
-  kb-mode: Load full BMAD knowledge base
+  kb-mode: Load full BMad knowledge base
   status: Show current context, active agent, and progress
   agent: Transform into a specialized agent (list if name not specified)
   exit: Return to BMad or exit session
   task: Run a specific task (list if name not specified)
   workflow: Start a specific workflow (list if name not specified)
   workflow-guidance: Get personalized help selecting the right workflow
+  plan: Create detailed workflow plan before starting
+  plan-status: Show current workflow plan progress
+  plan-update: Update workflow plan status
   checklist: Execute a checklist (list if name not specified)
   yolo: Toggle skip confirmations mode
   party-mode: Group chat with all agents
   doc-out: Output full document
 help-display-template: |
-  === BMAD Orchestrator Commands ===
+  === BMad Orchestrator Commands ===
   All commands must start with * (asterisk)
   
   Core Commands:
   *help ............... Show this guide
   *chat-mode .......... Start conversational mode for detailed assistance
-  *kb-mode ............ Load full BMAD knowledge base
+  *kb-mode ............ Load full BMad knowledge base
   *status ............. Show current context, active agent, and progress
   *exit ............... Return to BMad or exit session
   
@@ -68,6 +74,9 @@ help-display-template: |
   Workflow Commands:
   *workflow [name] .... Start specific workflow (list if no name)
   *workflow-guidance .. Get personalized help selecting the right workflow
+  *plan ............... Create detailed workflow plan before starting
+  *plan-status ........ Show current workflow plan progress
+  *plan-update ........ Update workflow plan status
   
   Other Commands:
   *yolo ............... Toggle skip confirmations mode
@@ -95,7 +104,7 @@ transformation:
   - Announce transformation
   - Operate until exit
 loading:
-  - KB: Only for *kb-mode or BMAD questions
+  - KB: Only for *kb-mode or BMad questions
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
@@ -109,6 +118,8 @@ workflow-guidance:
   - Understand each workflow's purpose, options, and decision points
   - Ask clarifying questions based on the workflow's structure
   - Guide users through workflow selection when multiple options exist
+  - For complex projects, offer to create a workflow plan using create-workflow-plan task
+  - When appropriate, suggest: "Would you like me to create a detailed workflow plan before starting?"
   - For workflows with divergent paths, help users choose the right path
   - Adapt questions to the specific domain (e.g., game dev vs infrastructure vs web dev)
   - Only recommend workflows that actually exist in the current bundle
@@ -117,10 +128,13 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - create-workflow-plan
     - kb-mode-interaction
+    - update-workflow-plan
   data:
     - bmad-kb
   utils:
+    - plan-management
     - workflow-management
     - template-format
 ```

bmad-core/agents/dev.md

@@ -1,8 +1,8 @@
 # dev
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 root: .bmad-core
 IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
@@ -16,7 +16,7 @@ agent:
 
 startup:
   - Announce: Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Load .bmad-core/core-config.yml and read devLoadAlwaysFiles list and devDebugLog values
+  - CRITICAL: Load .bmad-core/core-config.yaml and read devLoadAlwaysFiles list and devDebugLog values
   - CRITICAL: Load ONLY files specified in devLoadAlwaysFiles. If any missing, inform user but continue
   - CRITICAL: Do NOT load any story files during startup unless user requested you do
   - CRITICAL: Do NOT begin development until told to proceed
@@ -50,7 +50,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"

bmad-core/agents/pm.md

@@ -1,8 +1,8 @@
 # pm
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 root: .bmad-core
 IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.

bmad-core/agents/po.md

@@ -1,8 +1,8 @@
 # po
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 root: .bmad-core
 IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.

bmad-core/agents/qa.md

@@ -1,6 +1,6 @@
 # qa
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 root: .bmad-core

bmad-core/agents/sm.md

@@ -1,6 +1,6 @@
 # sm
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 root: .bmad-core
@@ -41,7 +41,7 @@ dependencies:
   tasks:
     - create-next-story
     - execute-checklist
-    - course-correct
+    - correct-course
   templates:
     - story-tmpl
   checklists:

bmad-core/agents/ux-expert.md

@@ -1,6 +1,6 @@
 # ux-expert
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 root: .bmad-core

bmad-core/checklists/change-checklist.md

@@ -1,6 +1,6 @@
 # Change Navigation Checklist
 
-**Purpose:** To systematically guide the selected Agent and user through the analysis and planning required when a significant change (pivot, tech issue, missing requirement, failed story) is identified during the BMAD workflow.
+**Purpose:** To systematically guide the selected Agent and user through the analysis and planning required when a significant change (pivot, tech issue, missing requirement, failed story) is identified during the BMad workflow.
 
 **Instructions:** Review each item with the user. Mark `[x]` for completed/confirmed, `[N/A]` if not applicable, or add notes for discussion points.
 
@@ -75,7 +75,7 @@ Think about both immediate and downstream effects.]]
 
 ## 3. Artifact Conflict & Impact Analysis
 
-[[LLM: Documentation drives development in BMAD. Check each artifact:
+[[LLM: Documentation drives development in BMad. Check each artifact:
 
 1. Does this change invalidate documented decisions?
 2. Are architectural assumptions still valid?

bmad-core/core-config.yaml

@@ -1,3 +1,4 @@
+version: 4.24.0
 markdownExploder: true
 prd:
   prdFile: docs/prd.md
@@ -17,4 +18,8 @@ devLoadAlwaysFiles:
   - docs/architecture/source-tree.md
 devDebugLog: .ai/debug-log.md
 devStoryLocation: docs/stories
-agentCoreDump: .ai/core-dump{n}.md
+workflow:
+  planFile: docs/workflow-plan.md
+  trackProgress: true
+  enforceSequence: false
+  updateOnCompletion: true

bmad-core/data/bmad-kb.md

@@ -1,8 +1,8 @@
-# BMAD Knowledge Base
+# BMad Knowledge Base
 
 ## Overview
 
-BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework that combines AI agents with Agile development methodologies. The v4 system introduces a modular architecture with improved dependency management, bundle optimization, and support for both web and IDE environments.
+BMad-Method (Breakthrough Method of Agile AI-driven Development) is a framework that combines AI agents with Agile development methodologies. The v4 system introduces a modular architecture with improved dependency management, bundle optimization, and support for both web and IDE environments.
 
 ### Key Features
 
@@ -12,7 +12,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
 - **Reusable Resources**: Portable templates, tasks, and checklists
 - **Slash Command Integration**: Quick agent switching and control
 
-### When to Use BMAD
+### When to Use BMad
 
 - **New Projects (Greenfield)**: Complete end-to-end development
 - **Existing Projects (Brownfield)**: Feature additions and enhancements
@@ -20,11 +20,11 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
 - **Quality Assurance**: Structured testing and validation
 - **Documentation**: Professional PRDs, architecture docs, user stories
 
-## How BMAD Works
+## How BMad Works
 
 ### The Core Method
 
-BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
+BMad transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
 
 1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
 2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
@@ -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, Github Copilot users
 
 ```bash
 # Interactive installation (recommended)
@@ -93,15 +93,16 @@ npx bmad-method install
   - **Windsurf**: Built-in AI capabilities
   - **Cline**: VS Code extension with AI features
   - **Roo Code**: Web-based IDE with agent support
+  - **Github 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.
+**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.
 
 **Verify Installation**:
 - `.bmad-core/` folder created with all agents
 - IDE-specific integration files created
 - All agent commands/rules/modes available
 
-**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
+**Remember**: At its core, BMad-Method is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMad - the framework provides the structured prompts and workflows that make AI development effective
 
 ### Environment Selection Guide
 
@@ -160,13 +161,13 @@ npx bmad-method install
 5. **MUST switch to Dev agent** for implementation
 6. Keep planning and coding in separate chat sessions
 
-## Core Configuration (core-config.yml)
+## Core Configuration (core-config.yaml)
 
-**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+**New in V4**: The `bmad-core/core-config.yaml` file is a critical innovation that enables BMad to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
 
-### What is core-config.yml?
+### What is core-config.yaml?
 
-This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+This configuration file acts as a map for BMad agents, telling them exactly where to find your project documents and how they're structured. It enables:
 
 - **Version Flexibility**: Work with V3, V4, or custom document structures
 - **Custom Locations**: Define where your documents and shards live
@@ -195,7 +196,7 @@ This configuration file acts as a map for BMAD agents, telling them exactly wher
 
 1. **No Forced Migrations**: Keep your existing document structure
 2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
-3. **Custom Workflows**: Configure BMAD to match your team's process
+3. **Custom Workflows**: Configure BMad to match your team's process
 4. **Intelligent Agents**: Agents automatically adapt to your configuration
 
 ### Common Configurations
@@ -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`)
+- **Github 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
@@ -323,7 +325,7 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 
 ### System Overview
 
-The BMAD-Method is built around a modular architecture centered on the `bmad-core` directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).
+The BMad-Method is built around a modular architecture centered on the `bmad-core` directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).
 
 ### Key Architectural Components
 
@@ -335,7 +337,7 @@ The BMAD-Method is built around a modular architecture centered on the `bmad-cor
 
 #### 2. Agent Teams (`bmad-core/agent-teams/`)
 - **Purpose**: Define collections of agents bundled together for specific purposes
-- **Examples**: `team-all.yml` (comprehensive bundle), `team-fullstack.yml` (full-stack development)
+- **Examples**: `team-all.yaml` (comprehensive bundle), `team-fullstack.yaml` (full-stack development)
 - **Usage**: Creates pre-packaged contexts for web UI environments
 
 #### 3. Workflows (`bmad-core/workflows/`)
@@ -367,7 +369,7 @@ The BMAD-Method is built around a modular architecture centered on the `bmad-cor
 
 ### Template Processing System
 
-BMAD employs a sophisticated template system with three key components:
+BMad employs a sophisticated template system with three key components:
 
 1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
 2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
@@ -396,7 +398,7 @@ The `web-builder.js` tool creates web-ready bundles by:
 3. Concatenating content into single text files with clear separators
 4. Outputting ready-to-upload bundles for web AI interfaces
 
-This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMAD powerful.
+This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMad powerful.
 
 ## Complete Development Workflow
 
@@ -657,7 +659,7 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
 - **Keep conversations focused** - One agent, one task per conversation
 - **Review everything** - Always review and approve before marking complete
 
-## Contributing to BMAD-METHOD
+## Contributing to BMad-Method
 
 ### Quick Contribution Guidelines
 
@@ -686,7 +688,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 
 ### What Are Expansion Packs?
 
-Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
+Expansion packs extend BMad-Method beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
 
 ### Why Use Expansion Packs?
 
@@ -719,7 +721,7 @@ Expansion packs extend BMAD-METHOD beyond traditional software development into
 ### Using Expansion Packs
 
 1. **Browse Available Packs**: Check `expansion-packs/` directory
-2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
+2. **Get Inspiration**: See `docs/expansion-packs.md` for detailed examples and ideas
 3. **Install via CLI**: 
    ```bash
    npx bmad-method install

bmad-core/tasks/core-dump.md

@@ -1,74 +0,0 @@
-# Core Dump Task
-
-## Purpose
-
-To create a concise memory recording file (`.ai/core-dump-n.md`) that captures the essential context of the current agent session, enabling seamless continuation of work in future agent sessions. This task ensures persistent context across agent conversations while maintaining minimal token usage for efficient context loading.
-
-## Inputs for this Task
-
-- Current session conversation history and accomplishments
-- Files created, modified, or deleted during the session
-- Key decisions made and procedures followed
-- Current project state and next logical steps
-- User requests and agent responses that shaped the session
-
-## Task Execution Instructions
-
-### 0. Check Existing Core Dump
-
-Before proceeding, check if `.ai/core-dump.md` already exists:
-
-- If file exists, ask user: "Core dump file exists. Should I: 1. Overwrite, 2. Update, 3. Append or 4. Create new?"
-- **Overwrite**: Replace entire file with new content
-- **Update**: Merge new session info with existing content, updating relevant sections
-- **Append**: Add new session as a separate entry while preserving existing content
-- **Create New**: Create a new file, appending the next possible -# to the file, such as core-dump-3.md if 1 and 2 already exist.
-- If file doesn't exist, proceed with creation of `core-dump-1.md`
-
-### 1. Analyze Session Context
-
-- Review the entire conversation to identify key accomplishments
-- Note any specific tasks, procedures, or workflows that were executed
-- Identify important decisions made or problems solved
-- Capture the user's working style and preferences observed during the session
-
-### 2. Document What Was Accomplished
-
-- **Primary Actions**: List the main tasks completed concisely
-- **Story Progress**: For story work, use format "Tasks Complete: 1-6, 8. Next Task Pending: 7, 9"
-- **Problem Solving**: Document any challenges encountered and how they were resolved
-- **User Communications**: Summarize key user requests, preferences, and discussion points
-
-### 3. Record File System Changes (Concise Format)
-
-- **Files Created**: `filename.ext` (brief purpose/size)
-- **Files Modified**: `filename.ext` (what changed)
-- **Files Deleted**: `filename.ext` (why removed)
-- Focus on essential details, avoid verbose descriptions
-
-### 4. Capture Current Project State
-
-- **Project Progress**: Where the project stands after this session
-- **Current Issues**: Any blockers or problems that need resolution
-- **Next Logical Steps**: What would be the natural next actions to take
-
-### 5. Create/Update Core Dump File
-
-Based on user's choice from step 0, handle the file accordingly:
-
-### 6. Optimize for Minimal Context
-
-- Keep descriptions concise but informative
-- Use abbreviated formats where possible (file sizes, task numbers)
-- Focus on actionable information rather than detailed explanations
-- Avoid redundant information that can be found in project documentation
-- Prioritize information that would be lost without this recording
-- Ensure the file can be quickly scanned and understood
-
-### 7. Validate Completeness
-
-- Verify all significant session activities are captured
-- Ensure a future agent could understand the current state
-- Check that file changes are accurately recorded
-- Confirm next steps are clear and actionable
-- Verify user communication style and preferences are noted

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

@@ -0,0 +1,355 @@
+# Create Brownfield Story Task
+
+## Purpose
+
+Create detailed, implementation-ready stories for brownfield projects where traditional sharded PRD/architecture documents may not exist. This task bridges the gap between various documentation formats (document-project output, brownfield PRDs, epics, or user documentation) and executable stories for the Dev agent.
+
+## When to Use This Task
+
+**Use this task when:**
+
+- Working on brownfield projects with non-standard documentation
+- Stories need to be created from document-project output
+- Working from brownfield epics without full PRD/architecture
+- Existing project documentation doesn't follow BMad v4+ structure
+- Need to gather additional context from user during story creation
+
+**Use create-next-story when:**
+
+- Working with properly sharded PRD and v4 architecture documents
+- Following standard greenfield or well-documented brownfield workflow
+- All technical context is available in structured format
+
+## Task Execution Instructions
+
+### 0. Check Workflow Plan and Documentation Context
+
+[[LLM: Check for workflow plan first, then available documentation]]
+
+#### 0.1 Check Workflow Plan
+
+- Load core-config.yaml and check if `workflow.trackProgress: true`
+- If yes, check for active plan at `workflow.planFile`
+- If plan exists:
+  - Verify story creation aligns with current plan step
+  - If out of sequence, warn user (enforce based on config)
+  - Note which step this story creation corresponds to
+
+#### 0.2 Determine Documentation Context
+
+Check for available documentation in this order:
+
+1. **Sharded PRD/Architecture** (docs/prd/, docs/architecture/)
+   - If found, recommend using create-next-story task instead
+
+2. **Brownfield Architecture Document** (docs/brownfield-architecture.md or similar)
+   - Created by document-project task
+   - Contains actual system state, technical debt, workarounds
+
+3. **Brownfield PRD** (docs/prd.md)
+   - May contain embedded technical details
+
+4. **Epic Files** (docs/epics/ or similar)
+   - Created by brownfield-create-epic task
+
+5. **User-Provided Documentation**
+   - Ask user to specify location and format
+
+### 1. Story Identification and Context Gathering
+
+#### 1.1 Identify Story Source
+
+Based on available documentation:
+
+- **From Brownfield PRD**: Extract stories from epic sections
+- **From Epic Files**: Read epic definition and story list
+- **From User Direction**: Ask user which specific enhancement to implement
+- **No Clear Source**: Work with user to define the story scope
+
+#### 1.2 Gather Essential Context
+
+[[LLM: For brownfield stories, you MUST gather enough context for safe implementation. Be prepared to ask the user for missing information.]]
+
+**Required Information Checklist:**
+
+- [ ] What existing functionality might be affected?
+- [ ] What are the integration points with current code?
+- [ ] What patterns should be followed (with examples)?
+- [ ] What technical constraints exist?
+- [ ] Are there any "gotchas" or workarounds to know about?
+
+If any required information is missing, ask the user:
+
+```
+I need additional context for this brownfield story:
+
+Missing Information:
+- [List specific missing items]
+
+Please provide:
+1. [Specific question about integration]
+2. [Specific question about patterns]
+3. [Specific question about constraints]
+
+Or point me to documentation that contains this information.
+```
+
+### 2. Extract Technical Context from Available Sources
+
+#### 2.1 From Document-Project Output
+
+If using brownfield-architecture.md from document-project:
+
+- **Technical Debt Section**: Note any workarounds affecting this story
+- **Key Files Section**: Identify files that will need modification
+- **Integration Points**: Find existing integration patterns
+- **Known Issues**: Check if story touches problematic areas
+- **Actual Tech Stack**: Verify versions and constraints
+
+#### 2.2 From Brownfield PRD
+
+If using brownfield PRD:
+
+- **Technical Constraints Section**: Extract all relevant constraints
+- **Integration Requirements**: Note compatibility requirements
+- **Code Organization**: Follow specified patterns
+- **Risk Assessment**: Understand potential impacts
+
+#### 2.3 From User Documentation
+
+[[LLM: When working with non-BMad documentation, actively extract and organize the information into categories the Dev agent will need]]
+
+Ask the user to help identify:
+
+- Relevant technical specifications
+- Existing code examples to follow
+- Integration requirements
+- Testing approaches used in the project
+
+### 3. Story Creation with Progressive Detail Gathering
+
+#### 3.1 Create Initial Story Structure
+
+Start with the story template, filling in what's known:
+
+```markdown
+# Story {{Enhancement Title}}
+
+## Status: Draft
+
+## Story
+As a {{user_type}},
+I want {{enhancement_capability}},
+so that {{value_delivered}}.
+
+## Context Source
+[[LLM: Document where story requirements came from]]
+- Source Document: {{document name/type}}
+- Enhancement Type: {{single feature/bug fix/integration/etc}}
+- Existing System Impact: {{brief assessment}}
+```
+
+#### 3.2 Develop Acceptance Criteria
+
+[[LLM: For brownfield, ALWAYS include criteria about maintaining existing functionality]]
+
+Standard structure:
+
+1. New functionality works as specified
+2. Existing {{affected feature}} continues to work unchanged  
+3. Integration with {{existing system}} maintains current behavior
+4. No regression in {{related area}}
+5. Performance remains within acceptable bounds
+
+#### 3.3 Gather Technical Guidance
+
+[[LLM: This is where you'll need to be interactive with the user if information is missing]]
+
+Create Dev Technical Guidance section with available information:
+
+```markdown
+## Dev Technical Guidance
+
+### Existing System Context
+[Extract from available documentation]
+
+### Integration Approach
+[Based on patterns found or ask user]
+
+### Technical Constraints
+[From documentation or user input]
+
+### Missing Information
+[[LLM: List anything you couldn't find that dev will need]]
+- [ ] {{missing item 1}}
+- [ ] {{missing item 2}}
+```
+
+If critical information is missing, pause and ask:
+
+```
+To complete the technical guidance for this story, I need:
+
+1. **{{Missing Category}}**: 
+   - Specifically: {{what you need to know}}
+   - Why needed: {{how it impacts implementation}}
+   
+Can you provide this information or point me to relevant code/docs?
+```
+
+### 4. Task Generation with Safety Checks
+
+#### 4.1 Generate Implementation Tasks
+
+Based on gathered context, create tasks that:
+
+- Include exploration tasks if system understanding is incomplete
+- Add verification tasks for existing functionality
+- Include rollback considerations
+- Reference specific files/patterns when known
+
+Example task structure for brownfield:
+
+```markdown
+## Tasks / Subtasks
+
+- [ ] Task 1: Analyze existing {{component/feature}} implementation
+  - [ ] Review {{specific files}} for current patterns
+  - [ ] Document integration points
+  - [ ] Identify potential impacts
+
+- [ ] Task 2: Implement {{new functionality}}
+  - [ ] Follow pattern from {{example file}}
+  - [ ] Integrate with {{existing component}}
+  - [ ] Maintain compatibility with {{constraint}}
+
+- [ ] Task 3: Verify existing functionality
+  - [ ] Test {{existing feature 1}} still works
+  - [ ] Verify {{integration point}} behavior unchanged
+  - [ ] Check performance impact
+
+- [ ] Task 4: Add tests
+  - [ ] Unit tests following {{project test pattern}}
+  - [ ] Integration test for {{integration point}}
+  - [ ] Update existing tests if needed
+```
+
+### 5. Risk Assessment and Mitigation
+
+[[LLM: CRITICAL for brownfield - always include risk assessment]]
+
+Add section for brownfield-specific risks:
+
+```markdown
+## Risk Assessment
+
+### Implementation Risks
+- **Primary Risk**: {{main risk to existing system}}
+- **Mitigation**: {{how to address}}
+- **Verification**: {{how to confirm safety}}
+
+### Rollback Plan
+- {{Simple steps to undo changes if needed}}
+
+### Safety Checks
+- [ ] Existing {{feature}} tested before changes
+- [ ] Changes can be feature-flagged or isolated
+- [ ] Rollback procedure documented
+```
+
+### 6. Final Story Validation
+
+Before finalizing:
+
+1. **Completeness Check**:
+   - [ ] Story has clear scope and acceptance criteria
+   - [ ] Technical context is sufficient for implementation
+   - [ ] Integration approach is defined
+   - [ ] Risks are identified with mitigation
+
+2. **Safety Check**:
+   - [ ] Existing functionality protection included
+   - [ ] Rollback plan is feasible
+   - [ ] Testing covers both new and existing features
+
+3. **Information Gaps**:
+   - [ ] All critical missing information gathered from user
+   - [ ] Remaining unknowns documented for dev agent
+   - [ ] Exploration tasks added where needed
+
+### 7. Story Output Format
+
+Save the story with appropriate naming:
+
+- If from epic: `docs/stories/epic-{n}-story-{m}.md`
+- If standalone: `docs/stories/brownfield-{feature-name}.md`
+- If sequential: Follow existing story numbering
+
+Include header noting documentation context:
+
+```markdown
+# Story: {{Title}}
+
+<!-- Source: {{documentation type used}} -->
+<!-- Context: Brownfield enhancement to {{existing system}} -->
+
+## Status: Draft
+[Rest of story content...]
+```
+
+### 8. Handoff Communication
+
+Provide clear handoff to the user:
+
+```text
+Brownfield story created: {{story title}}
+
+Source Documentation: {{what was used}}
+Story Location: {{file path}}
+
+Key Integration Points Identified:
+- {{integration point 1}}
+- {{integration point 2}}
+
+Risks Noted:
+- {{primary risk}}
+
+{{If missing info}}: 
+Note: Some technical details were unclear. The story includes exploration tasks to gather needed information during implementation.
+
+Next Steps:
+1. Review story for accuracy
+2. Verify integration approach aligns with your system
+3. Approve story or request adjustments
+4. Dev agent can then implement with safety checks
+```
+
+### 9. Update Workflow Plan (if applicable)
+
+[[LLM: After successful story creation]]
+
+- If workflow plan tracking is enabled and story was created successfully:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-brownfield-story, step_id: {from plan check}, status: complete
+  - If plan shows next recommended step, include it in handoff message
+
+## Success Criteria
+
+The brownfield story creation is successful when:
+
+1. Story can be implemented without requiring dev to search multiple documents
+2. Integration approach is clear and safe for existing system
+3. All available technical context has been extracted and organized
+4. Missing information has been identified and addressed
+5. Risks are documented with mitigation strategies
+6. Story includes verification of existing functionality
+7. Rollback approach is defined
+
+## Important Notes
+
+- This task is specifically for brownfield projects with non-standard documentation
+- Always prioritize existing system safety over new features
+- When in doubt, add exploration and verification tasks
+- It's better to ask the user for clarification than make assumptions
+- Each story should be self-contained for the dev agent
+- Include references to existing code patterns when available

bmad-core/tasks/create-doc.md

@@ -1,74 +0,0 @@
-# Create Document from Template Task
-
-## Purpose
-
-- Generate documents from any specified template following embedded instructions from the perspective of the selected agent persona
-
-## Instructions
-
-### 1. Identify Template and Context
-
-- Determine which template to use (user-provided or list available for selection to user)
-
-  - 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:
-
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
-
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
-
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
-
-### 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 /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
-
-- **Incremental Mode**: Present each major section for review before proceeding
-- **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
-
-If template specifies a checklist:
-
-- Run the appropriate checklist against completed document
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
-
-### 7. Final Presentation
-
-- Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
-
-## Important Notes
-
-- Template markup is for AI processing only - never expose to users

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

@@ -10,12 +10,12 @@ To identify the next logical story based on project progress and epic definition
 
 [[LLM: CRITICAL - This MUST be your first step]]
 
-- Load `.bmad-core/core-config.yml` from the project root
+- Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist:
-  - HALT and inform the user: "core-config.yml not found. This file is required for story creation. You can:
-    1. Copy it from GITHUB BMAD-METHOD/bmad-core/core-config.yml and configure it for your project
-    2. Run the BMAD installer against your project to upgrade and add the file automatically
-    Please add and configure core-config.yml before proceeding."
+  - HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can:
+    1. Copy it from GITHUB BMad-Method/bmad-core/core-config.yaml and configure it for your project
+    2. Run the BMad installer against your project to upgrade and add the file automatically
+    Please add and configure core-config.yaml before proceeding."
 - Extract the following key configurations:
   - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
@@ -26,6 +26,22 @@ To identify the next logical story based on project progress and epic definition
   - `architecture.architectureSharded`: Whether architecture is sharded
   - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
+  - `workflow.trackProgress`: Whether workflow plan tracking is enabled
+  - `workflow.planFile`: Location of workflow plan (if tracking enabled)
+
+### 0.5 Check Workflow Plan (if configured)
+
+[[LLM: Check if workflow plan tracking is enabled]]
+
+- If `workflow.trackProgress: true`, check for active plan at `workflow.planFile`
+- If plan exists:
+  - Parse plan to check if story creation is the expected next step
+  - If out of sequence and `workflow.enforceSequence: true`:
+    - Show warning: "The workflow plan indicates you should complete {expected_step} before creating stories."
+    - Block execution unless user explicitly overrides
+  - If out of sequence and `workflow.enforceSequence: false`:
+    - Show warning but allow continuation with confirmation
+- Continue with story identification after plan check
 
 ### 1. Identify Next Story for Preparation
 
@@ -249,4 +265,13 @@ Provide a summary to the user including:
 - Recommendations for story review before approval
 - Next steps: Story should be reviewed by PO for approval before dev work begins
 
+### 10. Update Workflow Plan (if applicable)
+
+[[LLM: After successful story creation]]
+
+- If `workflow.trackProgress: true` and `workflow.updateOnCompletion: true`:
+  - Call update-workflow-plan task to mark story creation step complete
+  - Parameters: task: create-next-story, step_id: {from plan}, status: complete
+  - If plan shows next step, mention it in completion message
+
 [[LLM: Remember - The success of this task depends on extracting real, specific technical details from the architecture shards. The dev agent should have everything they need in the story file without having to search through multiple documents.]]

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

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

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

@@ -1,7 +1,7 @@
 # KB Mode Interaction Task
 
 ## Purpose
-Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+Provide a user-friendly interface to the BMad knowledge base without overwhelming users with information upfront.
 
 ## Instructions
 
@@ -10,23 +10,23 @@ When entering KB mode (*kb-mode), follow these steps:
 ### 1. Welcome and Guide
 Announce entering KB mode with a brief, friendly introduction:
 
-"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+"I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method."
 
 ### 2. Present Topic Areas
 Offer a concise list of main topic areas the user might want to explore:
 
 **What would you like to know more about?**
 
-1. **Setup & Installation** - Getting started with BMAD
+1. **Setup & Installation** - Getting started with BMad
 2. **Workflows** - Choosing the right workflow for your project
 3. **Web vs IDE** - When to use each environment
 4. **Agents** - Understanding specialized agents and their roles
 5. **Documents** - PRDs, Architecture, Stories, and more
-6. **Agile Process** - How BMAD implements Agile methodologies
-7. **Configuration** - Customizing BMAD for your needs
-8. **Best Practices** - Tips for effective BMAD usage
+6. **Agile Process** - How BMad implements Agile methodologies
+7. **Configuration** - Customizing BMad for your needs
+8. **Best Practices** - Tips for effective BMad usage
 
-Or ask me about anything else related to BMAD-METHOD!
+Or ask me about anything else related to BMad-Method!
 
 ### 3. Respond Contextually
 - Wait for user's specific question or topic selection
@@ -50,20 +50,20 @@ When user is done or wants to exit KB mode:
 
 **User**: *kb-mode
 
-**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+**Assistant**: I've entered KB mode and have access to the full BMad knowledge base. I can help you with detailed information about any aspect of BMad-Method.
 
 **What would you like to know more about?**
 
-1. **Setup & Installation** - Getting started with BMAD
+1. **Setup & Installation** - Getting started with BMad
 2. **Workflows** - Choosing the right workflow for your project
 3. **Web vs IDE** - When to use each environment
 4. **Agents** - Understanding specialized agents and their roles
 5. **Documents** - PRDs, Architecture, Stories, and more
-6. **Agile Process** - How BMAD implements Agile methodologies
-7. **Configuration** - Customizing BMAD for your needs
-8. **Best Practices** - Tips for effective BMAD usage
+6. **Agile Process** - How BMad implements Agile methodologies
+7. **Configuration** - Customizing BMad for your needs
+8. **Best Practices** - Tips for effective BMad usage
 
-Or ask me about anything else related to BMAD-METHOD!
+Or ask me about anything else related to BMad-Method!
 
 **User**: Tell me about workflows
 

bmad-core/tasks/shard-doc.md

@@ -8,20 +8,20 @@
 
 ## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
 
 If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
 
 If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
 
 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in bmad-core/core-config.yml
+2. Or set markdownExploder to false in bmad-core/core-config.yaml
 
 **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
 
 If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
 
-1. Set markdownExploder to true in bmad-core/core-config.yml
+1. Set markdownExploder to true in bmad-core/core-config.yaml
 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
 
 I will now proceed with the manual sharding process."

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

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

bmad-core/templates/architecture-tmpl.md

@@ -396,7 +396,7 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 {{project-root}}/
 ├── .github/                    # CI/CD workflows
 │   └── workflows/
-│       └── main.yml
+│       └── main.yaml
 ├── .vscode/                    # VSCode settings (optional)
 │   └── settings.json
 ├── build/                      # Compiled output (git-ignored)

bmad-core/templates/brownfield-prd-tmpl.md

@@ -22,34 +22,45 @@ Do not proceed with any recommendations until the user has validated your unders
 
 ### Existing Project Overview
 
-[[LLM: If working in IDE with project loaded, analyze the project structure and existing documentation. If working in web interface, request project upload or detailed project information from user.]]
+[[LLM: Check if document-project analysis was already performed. If yes, reference that output instead of re-analyzing.]]
 
-**Project Location**: [[LLM: Note if this is IDE-based analysis or user-provided information]]
+**Analysis Source**: [[LLM: Indicate one of the following:
+- Document-project output available at: {{path}}
+- IDE-based fresh analysis
+- User-provided information
+]]
 
-**Current Project State**: [[LLM: Brief description of what the project currently does and its primary purpose]]
+**Current Project State**: [[LLM: 
+- If document-project output exists: Extract summary from "High Level Architecture" and "Technical Summary" sections
+- Otherwise: Brief description of what the project currently does and its primary purpose
+]]
 
 ### Available Documentation Analysis
 
-[[LLM: Check for existing documentation in docs folder or provided by user. List what documentation is available and assess its completeness. Required documents include:
+[[LLM: 
+If document-project was run:
+- Note: "Document-project analysis available - using existing technical documentation"
+- List key documents created by document-project
+- Skip the missing documentation check below
 
-- Tech stack documentation
-- Source tree/architecture overview
-- Coding standards
-- API documentation or OpenAPI specs
-- External API integrations
-- UX/UI guidelines or existing patterns]]
+Otherwise, check for existing documentation:
+]]
 
 **Available Documentation**:
 
-- [ ] Tech Stack Documentation
-- [ ] Source Tree/Architecture
-- [ ] Coding Standards
-- [ ] API Documentation
-- [ ] External API Documentation
-- [ ] UX/UI Guidelines
+- [ ] Tech Stack Documentation [[LLM: If from document-project, check ✓]]
+- [ ] Source Tree/Architecture [[LLM: If from document-project, check ✓]]
+- [ ] Coding Standards [[LLM: If from document-project, may be partial]]
+- [ ] API Documentation [[LLM: If from document-project, check ✓]]
+- [ ] External API Documentation [[LLM: If from document-project, check ✓]]
+- [ ] UX/UI Guidelines [[LLM: May not be in document-project]]
+- [ ] Technical Debt Documentation [[LLM: If from document-project, check ✓]]
 - [ ] Other: \***\*\_\_\_\*\***
 
-[[LLM: If critical documentation is missing, STOP and recommend: "I recommend running the document-project task first to generate baseline documentation including tech-stack, source-tree, coding-standards, APIs, external-APIs, and UX/UI information. This will provide the foundation needed for a comprehensive brownfield PRD."]]
+[[LLM: 
+- If document-project was already run: "Using existing project analysis from document-project output."
+- If critical documentation is missing and no document-project: "I recommend running the document-project task first..."
+]]
 
 ### Enhancement Scope Definition
 
@@ -139,13 +150,19 @@ Do not proceed with any recommendations until the user has validated your unders
 
 ### Existing Technology Stack
 
-[[LLM: Document the current technology stack that must be maintained or integrated with]]
+[[LLM: 
+If document-project output available:
+- Extract from "Actual Tech Stack" table in High Level Architecture section
+- Include version numbers and any noted constraints
 
-**Languages**: [[LLM: Current programming languages in use]]
-**Frameworks**: [[LLM: Current frameworks and their versions]]
-**Database**: [[LLM: Current database technology and schema considerations]]
-**Infrastructure**: [[LLM: Current deployment and hosting infrastructure]]
-**External Dependencies**: [[LLM: Current third-party services and APIs]]
+Otherwise, document the current technology stack:
+]]
+
+**Languages**: [[LLM: From document-project or fresh analysis]]
+**Frameworks**: [[LLM: From document-project or fresh analysis]]
+**Database**: [[LLM: From document-project or fresh analysis]]
+**Infrastructure**: [[LLM: From document-project or fresh analysis]]
+**External Dependencies**: [[LLM: From document-project "External Services" section or fresh analysis]]
 
 ### Integration Approach
 
@@ -176,12 +193,19 @@ Do not proceed with any recommendations until the user has validated your unders
 
 ### Risk Assessment and Mitigation
 
-[[LLM: Identify risks specific to working with existing codebase]]
+[[LLM: 
+If document-project output available:
+- Reference "Technical Debt and Known Issues" section
+- Include "Workarounds and Gotchas" that might impact enhancement
+- Note any identified constraints from "Critical Technical Debt"
 
-**Technical Risks**: [[LLM: Risks related to modifying existing code]]
-**Integration Risks**: [[LLM: Risks in integrating with existing systems]]
-**Deployment Risks**: [[LLM: Risks in deploying alongside existing features]]
-**Mitigation Strategies**: [[LLM: Specific strategies to address identified risks]]
+Build risk assessment incorporating existing known issues:
+]]
+
+**Technical Risks**: [[LLM: Include risks from document-project + new enhancement risks]]
+**Integration Risks**: [[LLM: Reference integration constraints from document-project]]
+**Deployment Risks**: [[LLM: Include deployment gotchas from document-project]]
+**Mitigation Strategies**: [[LLM: Address both existing and new risks]]
 
 ## Epic and Story Structure
 

bmad-core/templates/fullstack-architecture-tmpl.md

@@ -288,7 +288,7 @@ Use appropriate format for the chosen API style. If no API (e.g., static site),
 
 ^^CONDITION: has_rest_api^^
 
-```yml
+```yaml
 openapi: 3.0.0
 info:
   title:
@@ -644,8 +644,8 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 {{project-name}}/
 ├── .github/                    # CI/CD workflows
 │   └── workflows/
-│       ├── ci.yml
-│       └── deploy.yml
+│       ├── ci.yaml
+│       └── deploy.yaml
 ├── apps/                       # Application packages
 │   ├── web/                    # Frontend application
 │   │   ├── src/

bmad-core/utils/file-resolution-context.md

@@ -1,10 +0,0 @@
-# File Resolution Context
-
-Update the installer/upgrader so that when agents are added to a project (under Add these two lines to any agent's `activation-instructions` for ide installation:
-
-```yaml
-- IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
-- REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.
-```
-
-and add `root: .bmad-core` as the first root yml property.

bmad-core/utils/plan-management.md

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

bmad-core/utils/workflow-management.md

@@ -1,223 +0,0 @@
-# Workflow Management
-
-This utility enables the BMAD orchestrator to manage and execute team workflows.
-
-## Important: Dynamic Workflow Loading
-
-The BMAD orchestrator MUST read the available workflows from the current team configuration's `workflows` field. Do not use hardcoded workflow lists. Each team bundle defines its own set of supported workflows based on the agents it includes.
-
-**Critical Distinction**:
-
-- When asked "what workflows are available?", show ONLY the workflows defined in the current team bundle's configuration
-- Use `/agent-list` to show agents in the current bundle
-- Use `/workflows` to show workflows in the current bundle, NOT any creation tasks
-
-### Workflow Descriptions
-
-When displaying workflows, use these descriptions based on the workflow ID:
-
-- **greenfield-fullstack**: Build a new full-stack application from concept to development
-- **brownfield-fullstack**: Enhance an existing full-stack application with new features
-- **greenfield-service**: Build a new backend service or API from concept to development
-- **brownfield-service**: Enhance an existing backend service or API
-- **greenfield-ui**: Build a new frontend/UI application from concept to development
-- **brownfield-ui**: Enhance an existing frontend/UI application
-
-## Workflow Commands
-
-### /workflows
-
-Lists all available workflows for the current team. The available workflows are determined by the team configuration and may include workflows such as:
-
-- greenfield-fullstack
-- brownfield-fullstack
-- greenfield-service
-- brownfield-service
-- greenfield-ui
-- brownfield-ui
-
-The actual list depends on which team bundle is loaded. When responding to this command, display the workflows that are configured in the current team's `workflows` field.
-
-Example response format:
-
-```text
-Available workflows for [Team Name]:
-1. [workflow-id] - [Brief description based on workflow type]
-2. [workflow-id] - [Brief description based on workflow type]
-[... etc. ...]
-
-Use /workflow-start {number or id} to begin a workflow.
-```
-
-### /workflow-start {workflow-id}
-
-Starts a specific workflow and transitions to the first agent.
-
-Example: `/workflow-start greenfield-fullstack`
-
-### /workflow-status
-
-Shows current workflow progress, completed artifacts, and next steps.
-
-Example response:
-
-```text
-Current Workflow: Greenfield Full-Stack Development
-Stage: Product Planning (2 of 6)
-Completed:
-  ✓ Discovery & Requirements
-    - project-brief (completed by Mary)
-
-In Progress:
-  ⚡ Product Planning
-    - Create PRD (John) - awaiting input
-
-Next: Technical Architecture
-```
-
-### /workflow-resume
-
-Resumes a workflow from where it left off, useful when starting a new chat.
-
-User can provide completed artifacts:
-
-```text
-User: /workflow-resume greenfield-fullstack
-      I have completed: project-brief, PRD
-BMad: I see you've completed Discovery and part of Product Planning.
-      Based on the greenfield-fullstack workflow, the next step is:
-      - UX Strategy with Sally (ux-expert)
-
-      Would you like me to load Sally to continue?
-```
-
-### /workflow-next
-
-Shows the next recommended agent and action in the current workflow.
-
-## Workflow Execution Flow
-
-### 1. Starting a Workflow
-
-When a workflow is started:
-
-1. Load the workflow definition
-2. Identify the first stage and step
-3. Transition to the required agent
-4. Provide context about expected inputs/outputs
-5. Guide artifact creation
-
-### 2. Stage Transitions
-
-After each artifact is completed:
-
-1. Mark the step as complete
-2. Check transition conditions
-3. If stage is complete, move to next stage
-4. Load the appropriate agent
-5. Pass relevant artifacts as context
-
-### 3. Artifact Tracking
-
-Track all created artifacts:
-
-```yaml
-workflow_state:
-  current_workflow: greenfield-fullstack
-  current_stage: planning
-  current_step: 2
-  artifacts:
-    project-brief:
-      status: completed
-      created_by: analyst
-      timestamp: 2024-01-15T10:30:00.000Z
-    prd:
-      status: in-progress
-      created_by: pm
-      started: 2024-01-15T11:00:00.000Z
-```
-
-### 4. Workflow Interruption Handling
-
-When user returns after interruption:
-
-1. Ask if continuing previous workflow
-2. Request any completed artifacts
-3. Analyze provided artifacts
-4. Determine workflow position
-5. Suggest next appropriate step
-
-Example:
-
-```text
-User: I'm working on a new app. Here's my PRD and architecture doc.
-BMad: I see you have a PRD and architecture document. Based on these artifacts,
-      it looks like you're following the greenfield-fullstack workflow and have completed
-      stages 1-3. The next recommended step would be:
-
-      Stage 4: Validation & Refinement
-      - Load Sarah (Product Owner) to validate all artifacts
-
-      Would you like to continue with this workflow?
-```
-
-## Workflow Context Passing
-
-When transitioning between agents, pass:
-
-1. Previous artifacts created
-2. Current workflow stage
-3. Expected outputs
-4. Any decisions or constraints identified
-
-Example transition:
-
-```text
-BMad: Great! John has completed the PRD. According to the greenfield-fullstack workflow,
-      the next step is UX Strategy with Sally.
-
-      /ux-expert
-
-Sally: I see we're in the Product Planning stage of the greenfield-fullstack workflow.
-       I have access to:
-       - Project Brief from Mary
-       - PRD from John
-
-       Let's create the UX strategy and UI specifications. First, let me review
-       the PRD to understand the features we're designing for...
-```
-
-## Multi-Path Workflows
-
-Some workflows may have multiple paths:
-
-```yaml
-conditional_paths:
-  - condition: project_type == 'mobile'
-    next_stage: mobile-specific-design
-  - condition: project_type == 'web'
-    next_stage: web-architecture
-  - default: fullstack-architecture
-```
-
-Handle these by asking clarifying questions when needed.
-
-## Workflow Best Practices
-
-1. **Always show progress** - Users should know where they are
-2. **Explain transitions** - Why moving to next agent
-3. **Preserve context** - Pass relevant information forward
-4. **Allow flexibility** - Users can skip or modify steps
-5. **Track everything** - Maintain complete workflow state
-
-## Integration with Agents
-
-Each agent should be workflow-aware:
-
-- Know which workflow is active
-- Understand their role in the workflow
-- Access previous artifacts
-- Know expected outputs
-- Guide toward workflow goals
-
-This creates a seamless experience where the entire team works together toward the workflow's objectives.

bmad-core/workflows/brownfield-fullstack.yaml

@@ -0,0 +1,297 @@
+workflow:
+  id: brownfield-fullstack
+  name: Brownfield Full-Stack Enhancement
+  description: >-
+    Agent workflow for enhancing existing full-stack applications with new features,
+    modernization, or significant changes. Handles existing system analysis and safe integration.
+  type: brownfield
+  project_types:
+    - feature-addition
+    - refactoring
+    - modernization
+    - integration-enhancement
+
+  sequence:
+    - step: enhancement_classification
+      agent: analyst
+      action: classify enhancement scope
+      notes: |
+        Determine enhancement complexity to route to appropriate path:
+        - Single story (< 4 hours) → Use brownfield-create-story task
+        - Small feature (1-3 stories) → Use brownfield-create-epic task  
+        - Major enhancement (multiple epics) → Continue with full workflow
+        
+        Ask user: "Can you describe the enhancement scope? Is this a small fix, a feature addition, or a major enhancement requiring architectural changes?"
+
+    - step: routing_decision
+      condition: based_on_classification
+      routes:
+        single_story:
+          agent: pm
+          uses: brownfield-create-story
+          notes: "Create single story for immediate implementation. Exit workflow after story creation."
+        small_feature:
+          agent: pm
+          uses: brownfield-create-epic
+          notes: "Create focused epic with 1-3 stories. Exit workflow after epic creation."
+        major_enhancement:
+          continue: to_next_step
+          notes: "Continue with comprehensive planning workflow below."
+
+    - step: documentation_check
+      agent: analyst
+      action: check existing documentation
+      condition: major_enhancement_path
+      notes: |
+        Check if adequate project documentation exists:
+        - Look for existing architecture docs, API specs, coding standards
+        - Assess if documentation is current and comprehensive
+        - If adequate: Skip document-project, proceed to PRD
+        - If inadequate: Run document-project first
+
+    - step: project_analysis
+      agent: architect
+      action: analyze existing project and use task document-project
+      creates: brownfield-architecture.md (or multiple documents)
+      condition: documentation_inadequate
+      notes: "Run document-project to capture current system state, technical debt, and constraints. Pass findings to PRD creation."
+
+    - agent: pm
+      creates: prd.md
+      uses: brownfield-prd-tmpl
+      requires: existing_documentation_or_analysis
+      notes: |
+        Creates PRD for major enhancement. If document-project was run, reference its output to avoid re-analysis.
+        If skipped, use existing project documentation.
+        SAVE OUTPUT: Copy final prd.md to your project's docs/ folder.
+
+    - step: architecture_decision
+      agent: pm/architect
+      action: determine if architecture document needed
+      condition: after_prd_creation
+      notes: |
+        Review PRD to determine if architectural planning is needed:
+        - New architectural patterns → Create architecture doc
+        - New libraries/frameworks → Create architecture doc
+        - Platform/infrastructure changes → Create architecture doc
+        - Following existing patterns → Skip to story creation
+
+    - agent: architect
+      creates: architecture.md
+      uses: brownfield-architecture-tmpl
+      requires: prd.md
+      condition: architecture_changes_needed
+      notes: "Creates architecture ONLY for significant architectural changes. SAVE OUTPUT: Copy final architecture.md to your project's docs/ folder."
+
+    - agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      notes: "Validates all documents for integration safety and completeness. May require updates to any document."
+
+    - agent: various
+      updates: any_flagged_documents
+      condition: po_checklist_issues
+      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
+
+    - agent: po
+      action: shard_documents
+      creates: sharded_docs
+      requires: all_artifacts_in_project
+      notes: |
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - agent: sm
+      action: create_story
+      creates: story.md
+      requires: sharded_docs_or_brownfield_docs
+      repeats: for_each_epic_or_enhancement
+      notes: |
+        Story creation cycle:
+        - For sharded PRD: @sm → *create (uses create-next-story)
+        - For brownfield docs: @sm → use create-brownfield-story task
+        - Creates story from available documentation
+        - Story starts in "Draft" status
+        - May require additional context gathering for brownfield
+
+    - agent: analyst/pm
+      action: review_draft_story
+      updates: story.md
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - agent: dev
+      action: implement_story
+      creates: implementation_files
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - agent: qa
+      action: review_implementation
+      updates: implementation_files
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - repeat_development_cycle:
+      action: continue_for_all_stories
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - workflow_end:
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
+        
+        Reference: data#bmad-kb:IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Brownfield Enhancement] --> B[analyst: classify enhancement scope]
+        B --> C{Enhancement Size?}
+        
+        C -->|Single Story| D[pm: brownfield-create-story]
+        C -->|1-3 Stories| E[pm: brownfield-create-epic]
+        C -->|Major Enhancement| F[analyst: check documentation]
+        
+        D --> END1[To Dev Implementation]
+        E --> END2[To Story Creation]
+        
+        F --> G{Docs Adequate?}
+        G -->|No| H[architect: document-project]
+        G -->|Yes| I[pm: brownfield PRD]
+        H --> I
+        
+        I --> J{Architecture Needed?}
+        J -->|Yes| K[architect: architecture.md]
+        J -->|No| L[po: validate artifacts]
+        K --> L
+        
+        L --> M{PO finds issues?}
+        M -->|Yes| N[Fix issues]
+        M -->|No| O[po: shard documents]
+        N --> L
+        
+        O --> P[sm: create story]
+        P --> Q{Story Type?}
+        Q -->|Sharded PRD| R[create-next-story]
+        Q -->|Brownfield Docs| S[create-brownfield-story]
+        
+        R --> T{Review draft?}
+        S --> T
+        T -->|Yes| U[review & approve]
+        T -->|No| V[dev: implement]
+        U --> V
+        
+        V --> W{QA review?}
+        W -->|Yes| X[qa: review]
+        W -->|No| Y{More stories?}
+        X --> Z{Issues?}
+        Z -->|Yes| AA[dev: fix]
+        Z -->|No| Y
+        AA --> X
+        Y -->|Yes| P
+        Y -->|No| AB{Retrospective?}
+        AB -->|Yes| AC[po: retrospective]
+        AB -->|No| AD[Complete]
+        AC --> AD
+
+        style AD fill:#90EE90
+        style END1 fill:#90EE90
+        style END2 fill:#90EE90
+        style D fill:#87CEEB
+        style E fill:#87CEEB
+        style I fill:#FFE4B5
+        style K fill:#FFE4B5
+        style O fill:#ADD8E6
+        style P fill:#ADD8E6
+        style V fill:#ADD8E6
+        style U fill:#F0E68C
+        style X fill:#F0E68C
+        style AC fill:#F0E68C
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - Enhancement requires coordinated stories
+      - Architectural changes are needed
+      - Significant integration work required
+      - Risk assessment and mitigation planning necessary
+      - Multiple team members will work on related changes
+
+  handoff_prompts:
+    classification_complete: |
+      Enhancement classified as: {{enhancement_type}}
+      {{if single_story}}: Proceeding with brownfield-create-story task for immediate implementation.
+      {{if small_feature}}: Creating focused epic with brownfield-create-epic task.
+      {{if major_enhancement}}: Continuing with comprehensive planning workflow.
+    
+    documentation_assessment: |
+      Documentation assessment complete:
+      {{if adequate}}: Existing documentation is sufficient. Proceeding directly to PRD creation.
+      {{if inadequate}}: Running document-project to capture current system state before PRD.
+    
+    document_project_to_pm: |
+      Project analysis complete. Key findings documented in:
+      - {{document_list}}
+      Use these findings to inform PRD creation and avoid re-analyzing the same aspects.
+    
+    pm_to_architect_decision: |
+      PRD complete and saved as docs/prd.md. 
+      Architectural changes identified: {{yes/no}}
+      {{if yes}}: Proceeding to create architecture document for: {{specific_changes}}
+      {{if no}}: No architectural changes needed. Proceeding to validation.
+    
+    architect_to_po: "Architecture complete. Save it as docs/architecture.md. Please validate all artifacts for integration safety."
+    
+    po_to_sm: |
+      All artifacts validated. 
+      Documentation type available: {{sharded_prd / brownfield_docs}}
+      {{if sharded}}: Use standard create-next-story task.
+      {{if brownfield}}: Use create-brownfield-story task to handle varied documentation formats.
+    
+    sm_story_creation: |
+      Creating story from {{documentation_type}}.
+      {{if missing_context}}: May need to gather additional context from user during story creation.
+    
+    complete: "All planning artifacts validated and development can begin. Stories will be created based on available documentation format."

bmad-core/workflows/brownfield-fullstack.yml

@@ -1,112 +0,0 @@
-workflow:
-  id: brownfield-fullstack
-  name: Brownfield Full-Stack Enhancement
-  description: >-
-    Agent workflow for enhancing existing full-stack applications with new features,
-    modernization, or significant changes. Handles existing system analysis and safe integration.
-  type: brownfield
-  project_types:
-    - feature-addition
-    - refactoring
-    - modernization
-    - integration-enhancement
-
-  sequence:
-    - step: project_analysis
-      agent: architect
-      action: analyze existing project and use task document-project
-      creates: multiple documents per the document-project template
-      notes: "Review existing documentation, codebase structure, and identify integration points. Document current system understanding before proceeding."
-
-    - agent: pm
-      creates: brownfield-prd.md
-      uses: brownfield-prd-tmpl
-      requires: existing_project_analysis
-      notes: "Creates comprehensive brownfield PRD with existing system analysis and enhancement planning. SAVE OUTPUT: Copy final brownfield-prd.md to your project's docs/ folder."
-
-    - agent: architect
-      creates: brownfield-architecture.md
-      uses: brownfield-architecture-tmpl
-      requires: brownfield-prd.md
-      notes: "Creates brownfield architecture with integration strategy and existing system constraints. SAVE OUTPUT: Copy final brownfield-architecture.md to your project's docs/ folder."
-
-    - agent: po
-      validates: all_artifacts
-      uses: po-master-checklist
-      notes: "Validates all brownfield documents for integration safety and completeness. May require updates to any document."
-
-    - agent: various
-      updates: any_flagged_documents
-      condition: po_checklist_issues
-      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
-
-    - workflow_end:
-      action: move_to_ide
-      notes: |
-        Planning phase complete! Now transition to IDE Development:
-        
-        1. ENSURE DOCUMENTS ARE IN PROJECT:
-           - Copy final prd.md to project's docs/prd.md
-           - Copy final architecture.md to project's docs/architecture.md
-           - All documents must be in the project before proceeding
-        
-        2. SHARD DOCUMENTS (in IDE):
-           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
-           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
-           - This creates docs/prd/ and docs/architecture/ folders with sharded content
-        
-        3. START DEVELOPMENT CYCLE:
-           a. SM Agent (New Chat): @sm → *create
-              - Creates next story from sharded docs
-              - Review and approve story (Draft → Approved)
-           
-           b. Dev Agent (New Chat): @dev
-              - Implements approved story
-              - Updates File List with all changes
-              - Marks story as "Review" when complete
-           
-           c. QA Agent (New Chat): @qa → review-story
-              - Senior dev review with refactoring ability
-              - Fixes small issues directly
-              - Leaves checklist for remaining items
-              - Updates story status (Review → Done or stays Review)
-           
-           d. If QA left unchecked items:
-              - Dev Agent (New Chat): Address remaining items
-              - Return to QA for final approval
-        
-        4. REPEAT: Continue cycle for all epic stories
-        
-        Reference: data#bmad-kb:IDE Development Workflow
-
-  flow_diagram: |
-    ```mermaid
-    graph TD
-        A[Start: Brownfield Enhancement] --> B[analyst: analyze existing project]
-        B --> C[pm: brownfield-prd.md]
-        C --> D[architect: brownfield-architecture.md]
-        D --> E[po: validate with po-master-checklist]
-        E --> F{PO finds issues?}
-        F -->|Yes| G[Return to relevant agent for fixes]
-        F -->|No| H[Move to IDE Environment]
-        G --> E
-
-        style H fill:#90EE90
-        style C fill:#FFE4B5
-        style D fill:#FFE4B5
-    ```
-
-  decision_guidance:
-    when_to_use:
-      - Enhancement requires coordinated stories
-      - Architectural changes are needed
-      - Significant integration work required
-      - Risk assessment and mitigation planning necessary
-      - Multiple team members will work on related changes
-
-  handoff_prompts:
-    analyst_to_pm: "Existing project analysis complete. Create comprehensive brownfield PRD with integration strategy."
-    pm_to_architect: "Brownfield PRD ready. Save it as docs/brownfield-prd.md, then create the integration architecture."
-    architect_to_po: "Architecture complete. Save it as docs/brownfield-architecture.md. Please validate all artifacts for integration safety."
-    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
-    complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."

bmad-core/workflows/brownfield-service.yaml

@@ -0,0 +1,187 @@
+workflow:
+  id: brownfield-service
+  name: Brownfield Service/API Enhancement
+  description: >-
+    Agent workflow for enhancing existing backend services and APIs with new features,
+    modernization, or performance improvements. Handles existing system analysis and safe integration.
+  type: brownfield
+  project_types:
+    - service-modernization
+    - api-enhancement
+    - microservice-extraction
+    - performance-optimization
+    - integration-enhancement
+
+  sequence:
+    - step: service_analysis
+      agent: architect
+      action: analyze existing project and use task document-project
+      creates: multiple documents per the document-project template
+      notes: "Review existing service documentation, codebase, performance metrics, and identify integration dependencies."
+
+    - agent: pm
+      creates: prd.md
+      uses: brownfield-prd-tmpl
+      requires: existing_service_analysis
+      notes: "Creates comprehensive PRD focused on service enhancement with existing system analysis. SAVE OUTPUT: Copy final prd.md to your project's docs/ folder."
+
+    - agent: architect
+      creates: architecture.md
+      uses: brownfield-architecture-tmpl
+      requires: prd.md
+      notes: "Creates architecture with service integration strategy and API evolution planning. SAVE OUTPUT: Copy final architecture.md to your project's docs/ folder."
+
+    - agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      notes: "Validates all documents for service integration safety and API compatibility. May require updates to any document."
+
+    - agent: various
+      updates: any_flagged_documents
+      condition: po_checklist_issues
+      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
+
+    - agent: po
+      action: shard_documents
+      creates: sharded_docs
+      requires: all_artifacts_in_project
+      notes: |
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - agent: sm
+      action: create_story
+      creates: story.md
+      requires: sharded_docs
+      repeats: for_each_epic
+      notes: |
+        Story creation cycle:
+        - SM Agent (New Chat): @sm → *create
+        - Creates next story from sharded docs
+        - Story starts in "Draft" status
+
+    - agent: analyst/pm
+      action: review_draft_story
+      updates: story.md
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - agent: dev
+      action: implement_story
+      creates: implementation_files
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - agent: qa
+      action: review_implementation
+      updates: implementation_files
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - repeat_development_cycle:
+      action: continue_for_all_stories
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - workflow_end:
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
+        
+        Reference: data#bmad-kb:IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: Service Enhancement] --> B[analyst: analyze existing service]
+        B --> C[pm: prd.md]
+        C --> D[architect: architecture.md]
+        D --> E[po: validate with po-master-checklist]
+        E --> F{PO finds issues?}
+        F -->|Yes| G[Return to relevant agent for fixes]
+        F -->|No| H[po: shard documents]
+        G --> E
+        
+        H --> I[sm: create story]
+        I --> J{Review draft story?}
+        J -->|Yes| K[analyst/pm: review & approve story]
+        J -->|No| L[dev: implement story]
+        K --> L
+        L --> M{QA review?}
+        M -->|Yes| N[qa: review implementation]
+        M -->|No| O{More stories?}
+        N --> P{QA found issues?}
+        P -->|Yes| Q[dev: address QA feedback]
+        P -->|No| O
+        Q --> N
+        O -->|Yes| I
+        O -->|No| R{Epic retrospective?}
+        R -->|Yes| S[po: epic retrospective]
+        R -->|No| T[Project Complete]
+        S --> T
+
+        style T fill:#90EE90
+        style H fill:#ADD8E6
+        style I fill:#ADD8E6
+        style L fill:#ADD8E6
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
+        style K fill:#F0E68C
+        style N fill:#F0E68C
+        style S fill:#F0E68C
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - Service enhancement requires coordinated stories
+      - API versioning or breaking changes needed
+      - Database schema changes required
+      - Performance or scalability improvements needed
+      - Multiple integration points affected
+
+  handoff_prompts:
+    analyst_to_pm: "Service analysis complete. Create comprehensive PRD with service integration strategy."
+    pm_to_architect: "PRD ready. Save it as docs/prd.md, then create the service architecture."
+    architect_to_po: "Architecture complete. Save it as docs/architecture.md. Please validate all artifacts for service integration safety."
+    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."

bmad-core/workflows/brownfield-service.yml

@@ -1,113 +0,0 @@
-workflow:
-  id: brownfield-service
-  name: Brownfield Service/API Enhancement
-  description: >-
-    Agent workflow for enhancing existing backend services and APIs with new features,
-    modernization, or performance improvements. Handles existing system analysis and safe integration.
-  type: brownfield
-  project_types:
-    - service-modernization
-    - api-enhancement
-    - microservice-extraction
-    - performance-optimization
-    - integration-enhancement
-
-  sequence:
-    - step: service_analysis
-      agent: architect
-      action: analyze existing project and use task document-project
-      creates: multiple documents per the document-project template
-      notes: "Review existing service documentation, codebase, performance metrics, and identify integration dependencies."
-
-    - agent: pm
-      creates: brownfield-prd.md
-      uses: brownfield-prd-tmpl
-      requires: existing_service_analysis
-      notes: "Creates comprehensive brownfield PRD focused on service enhancement with existing system analysis. SAVE OUTPUT: Copy final brownfield-prd.md to your project's docs/ folder."
-
-    - agent: architect
-      creates: brownfield-architecture.md
-      uses: brownfield-architecture-tmpl
-      requires: brownfield-prd.md
-      notes: "Creates brownfield architecture with service integration strategy and API evolution planning. SAVE OUTPUT: Copy final brownfield-architecture.md to your project's docs/ folder."
-
-    - agent: po
-      validates: all_artifacts
-      uses: po-master-checklist
-      notes: "Validates all brownfield documents for service integration safety and API compatibility. May require updates to any document."
-
-    - agent: various
-      updates: any_flagged_documents
-      condition: po_checklist_issues
-      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
-
-    - workflow_end:
-      action: move_to_ide
-      notes: |
-        Planning phase complete! Now transition to IDE Development:
-        
-        1. ENSURE DOCUMENTS ARE IN PROJECT:
-           - Copy final prd.md to project's docs/prd.md
-           - Copy final architecture.md to project's docs/architecture.md
-           - All documents must be in the project before proceeding
-        
-        2. SHARD DOCUMENTS (in IDE):
-           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
-           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
-           - This creates docs/prd/ and docs/architecture/ folders with sharded content
-        
-        3. START DEVELOPMENT CYCLE:
-           a. SM Agent (New Chat): @sm → *create
-              - Creates next story from sharded docs
-              - Review and approve story (Draft → Approved)
-           
-           b. Dev Agent (New Chat): @dev
-              - Implements approved story
-              - Updates File List with all changes
-              - Marks story as "Review" when complete
-           
-           c. QA Agent (New Chat): @qa → review-story
-              - Senior dev review with refactoring ability
-              - Fixes small issues directly
-              - Leaves checklist for remaining items
-              - Updates story status (Review → Done or stays Review)
-           
-           d. If QA left unchecked items:
-              - Dev Agent (New Chat): Address remaining items
-              - Return to QA for final approval
-        
-        4. REPEAT: Continue cycle for all epic stories
-        
-        Reference: data#bmad-kb:IDE Development Workflow
-
-  flow_diagram: |
-    ```mermaid
-    graph TD
-        A[Start: Service Enhancement] --> B[analyst: analyze existing service]
-        B --> C[pm: brownfield-prd.md]
-        C --> D[architect: brownfield-architecture.md]
-        D --> E[po: validate with po-master-checklist]
-        E --> F{PO finds issues?}
-        F -->|Yes| G[Return to relevant agent for fixes]
-        F -->|No| H[Move to IDE Environment]
-        G --> E
-
-        style H fill:#90EE90
-        style C fill:#FFE4B5
-        style D fill:#FFE4B5
-    ```
-
-  decision_guidance:
-    when_to_use:
-      - Service enhancement requires coordinated stories
-      - API versioning or breaking changes needed
-      - Database schema changes required
-      - Performance or scalability improvements needed
-      - Multiple integration points affected
-
-  handoff_prompts:
-    analyst_to_pm: "Service analysis complete. Create comprehensive brownfield PRD with service integration strategy."
-    pm_to_architect: "Brownfield PRD ready. Save it as docs/brownfield-prd.md, then create the service architecture."
-    architect_to_po: "Architecture complete. Save it as docs/brownfield-architecture.md. Please validate all artifacts for service integration safety."
-    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
-    complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."

bmad-core/workflows/brownfield-ui.yaml

@@ -0,0 +1,197 @@
+workflow:
+  id: brownfield-ui
+  name: Brownfield UI/Frontend Enhancement
+  description: >-
+    Agent workflow for enhancing existing frontend applications with new features,
+    modernization, or design improvements. Handles existing UI analysis and safe integration.
+  type: brownfield
+  project_types:
+    - ui-modernization
+    - framework-migration
+    - design-refresh
+    - frontend-enhancement
+
+  sequence:
+    - step: ui_analysis
+      agent: architect
+      action: analyze existing project and use task document-project
+      creates: multiple documents per the document-project template
+      notes: "Review existing frontend application, user feedback, analytics data, and identify improvement areas."
+
+    - agent: pm
+      creates: prd.md
+      uses: brownfield-prd-tmpl
+      requires: existing_ui_analysis
+      notes: "Creates comprehensive PRD focused on UI enhancement with existing system analysis. SAVE OUTPUT: Copy final prd.md to your project's docs/ folder."
+
+    - agent: ux-expert
+      creates: front-end-spec.md
+      uses: front-end-spec-tmpl
+      requires: prd.md
+      notes: "Creates UI/UX specification that integrates with existing design patterns. SAVE OUTPUT: Copy final front-end-spec.md to your project's docs/ folder."
+
+    - agent: architect
+      creates: architecture.md
+      uses: brownfield-architecture-tmpl
+      requires:
+        - prd.md
+        - front-end-spec.md
+      notes: "Creates frontend architecture with component integration strategy and migration planning. SAVE OUTPUT: Copy final architecture.md to your project's docs/ folder."
+
+    - agent: po
+      validates: all_artifacts
+      uses: po-master-checklist
+      notes: "Validates all documents for UI integration safety and design consistency. May require updates to any document."
+
+    - agent: various
+      updates: any_flagged_documents
+      condition: po_checklist_issues
+      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
+
+    - agent: po
+      action: shard_documents
+      creates: sharded_docs
+      requires: all_artifacts_in_project
+      notes: |
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - agent: sm
+      action: create_story
+      creates: story.md
+      requires: sharded_docs
+      repeats: for_each_epic
+      notes: |
+        Story creation cycle:
+        - SM Agent (New Chat): @sm → *create
+        - Creates next story from sharded docs
+        - Story starts in "Draft" status
+
+    - agent: analyst/pm
+      action: review_draft_story
+      updates: story.md
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - agent: dev
+      action: implement_story
+      creates: implementation_files
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - agent: qa
+      action: review_implementation
+      updates: implementation_files
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - repeat_development_cycle:
+      action: continue_for_all_stories
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - workflow_end:
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
+        
+        Reference: data#bmad-kb:IDE Development Workflow
+
+  flow_diagram: |
+    ```mermaid
+    graph TD
+        A[Start: UI Enhancement] --> B[analyst: analyze existing UI]
+        B --> C[pm: prd.md]
+        C --> D[ux-expert: front-end-spec.md]
+        D --> E[architect: architecture.md]
+        E --> F[po: validate with po-master-checklist]
+        F --> G{PO finds issues?}
+        G -->|Yes| H[Return to relevant agent for fixes]
+        G -->|No| I[po: shard documents]
+        H --> F
+        
+        I --> J[sm: create story]
+        J --> K{Review draft story?}
+        K -->|Yes| L[analyst/pm: review & approve story]
+        K -->|No| M[dev: implement story]
+        L --> M
+        M --> N{QA review?}
+        N -->|Yes| O[qa: review implementation]
+        N -->|No| P{More stories?}
+        O --> Q{QA found issues?}
+        Q -->|Yes| R[dev: address QA feedback]
+        Q -->|No| P
+        R --> O
+        P -->|Yes| J
+        P -->|No| S{Epic retrospective?}
+        S -->|Yes| T[po: epic retrospective]
+        S -->|No| U[Project Complete]
+        T --> U
+
+        style U fill:#90EE90
+        style I fill:#ADD8E6
+        style J fill:#ADD8E6
+        style M fill:#ADD8E6
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
+        style E fill:#FFE4B5
+        style L fill:#F0E68C
+        style O fill:#F0E68C
+        style T fill:#F0E68C
+    ```
+
+  decision_guidance:
+    when_to_use:
+      - UI enhancement requires coordinated stories
+      - Design system changes needed
+      - New component patterns required
+      - User research and testing needed
+      - Multiple team members will work on related changes
+
+  handoff_prompts:
+    analyst_to_pm: "UI analysis complete. Create comprehensive PRD with UI integration strategy."
+    pm_to_ux: "PRD ready. Save it as docs/prd.md, then create the UI/UX specification."
+    ux_to_architect: "UI/UX spec complete. Save it as docs/front-end-spec.md, then create the frontend architecture."
+    architect_to_po: "Architecture complete. Save it as docs/architecture.md. Please validate all artifacts for UI integration safety."
+    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."

bmad-core/workflows/brownfield-ui.yml

@@ -1,123 +0,0 @@
-workflow:
-  id: brownfield-ui
-  name: Brownfield UI/Frontend Enhancement
-  description: >-
-    Agent workflow for enhancing existing frontend applications with new features,
-    modernization, or design improvements. Handles existing UI analysis and safe integration.
-  type: brownfield
-  project_types:
-    - ui-modernization
-    - framework-migration
-    - design-refresh
-    - frontend-enhancement
-
-  sequence:
-    - step: ui_analysis
-      agent: architect
-      action: analyze existing project and use task document-project
-      creates: multiple documents per the document-project template
-      notes: "Review existing frontend application, user feedback, analytics data, and identify improvement areas."
-
-    - agent: pm
-      creates: brownfield-prd.md
-      uses: brownfield-prd-tmpl
-      requires: existing_ui_analysis
-      notes: "Creates comprehensive brownfield PRD focused on UI enhancement with existing system analysis. SAVE OUTPUT: Copy final brownfield-prd.md to your project's docs/ folder."
-
-    - agent: ux-expert
-      creates: front-end-spec.md
-      uses: front-end-spec-tmpl
-      requires: brownfield-prd.md
-      notes: "Creates UI/UX specification for brownfield enhancement that integrates with existing design patterns. SAVE OUTPUT: Copy final front-end-spec.md to your project's docs/ folder."
-
-    - agent: architect
-      creates: brownfield-architecture.md
-      uses: brownfield-architecture-tmpl
-      requires:
-        - brownfield-prd.md
-        - front-end-spec.md
-      notes: "Creates brownfield frontend architecture with component integration strategy and migration planning. SAVE OUTPUT: Copy final brownfield-architecture.md to your project's docs/ folder."
-
-    - agent: po
-      validates: all_artifacts
-      uses: po-master-checklist
-      notes: "Validates all brownfield documents for UI integration safety and design consistency. May require updates to any document."
-
-    - agent: various
-      updates: any_flagged_documents
-      condition: po_checklist_issues
-      notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
-
-    - workflow_end:
-      action: move_to_ide
-      notes: |
-        Planning phase complete! Now transition to IDE Development:
-        
-        1. ENSURE DOCUMENTS ARE IN PROJECT:
-           - Copy final prd.md to project's docs/prd.md
-           - Copy final architecture.md to project's docs/architecture.md
-           - All documents must be in the project before proceeding
-        
-        2. SHARD DOCUMENTS (in IDE):
-           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
-           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
-           - This creates docs/prd/ and docs/architecture/ folders with sharded content
-        
-        3. START DEVELOPMENT CYCLE:
-           a. SM Agent (New Chat): @sm → *create
-              - Creates next story from sharded docs
-              - Review and approve story (Draft → Approved)
-           
-           b. Dev Agent (New Chat): @dev
-              - Implements approved story
-              - Updates File List with all changes
-              - Marks story as "Review" when complete
-           
-           c. QA Agent (New Chat): @qa → review-story
-              - Senior dev review with refactoring ability
-              - Fixes small issues directly
-              - Leaves checklist for remaining items
-              - Updates story status (Review → Done or stays Review)
-           
-           d. If QA left unchecked items:
-              - Dev Agent (New Chat): Address remaining items
-              - Return to QA for final approval
-        
-        4. REPEAT: Continue cycle for all epic stories
-        
-        Reference: data#bmad-kb:IDE Development Workflow
-
-  flow_diagram: |
-    ```mermaid
-    graph TD
-        A[Start: UI Enhancement] --> B[analyst: analyze existing UI]
-        B --> C[pm: brownfield-prd.md]
-        C --> D[ux-expert: front-end-spec.md]
-        D --> E[architect: brownfield-architecture.md]
-        E --> F[po: validate with po-master-checklist]
-        F --> G{PO finds issues?}
-        G -->|Yes| H[Return to relevant agent for fixes]
-        G -->|No| I[Move to IDE Environment]
-        H --> F
-
-        style I fill:#90EE90
-        style C fill:#FFE4B5
-        style D fill:#FFE4B5
-        style E fill:#FFE4B5
-    ```
-
-  decision_guidance:
-    when_to_use:
-      - UI enhancement requires coordinated stories
-      - Design system changes needed
-      - New component patterns required
-      - User research and testing needed
-      - Multiple team members will work on related changes
-
-  handoff_prompts:
-    analyst_to_pm: "UI analysis complete. Create comprehensive brownfield PRD with UI integration strategy."
-    pm_to_ux: "Brownfield PRD ready. Save it as docs/brownfield-prd.md, then create the UI/UX specification."
-    ux_to_architect: "UI/UX spec complete. Save it as docs/front-end-spec.md, then create the frontend architecture."
-    architect_to_po: "Architecture complete. Save it as docs/brownfield-architecture.md. Please validate all artifacts for UI integration safety."
-    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
-    complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."

bmad-core/workflows/greenfield-fullstack.yaml

@@ -73,42 +73,92 @@ workflow:
       action: guide_development_sequence
       notes: "Based on PRD stories: If stories are frontend-heavy, start with frontend project/directory first. If backend-heavy or API-first, start with backend. For tightly coupled features, follow story sequence in monorepo setup. Reference sharded PRD epics for development order."
 
-    - workflow_end:
-      action: move_to_ide
+    - agent: po
+      action: shard_documents
+      creates: sharded_docs
+      requires: all_artifacts_in_project
       notes: |
-        Planning phase complete! Now transition to IDE Development:
-        
-        1. ENSURE DOCUMENTS ARE IN PROJECT:
-           - Copy final prd.md to project's docs/prd.md
-           - Copy final architecture.md to project's docs/architecture.md
-           - All documents must be in the project before proceeding
-        
-        2. SHARD DOCUMENTS (in IDE):
-           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
-           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
-           - This creates docs/prd/ and docs/architecture/ folders with sharded content
-        
-        3. START DEVELOPMENT CYCLE:
-           a. SM Agent (New Chat): @sm → *create
-              - Creates next story from sharded docs
-              - Review and approve story (Draft → Approved)
-           
-           b. Dev Agent (New Chat): @dev
-              - Implements approved story
-              - Updates File List with all changes
-              - Marks story as "Review" when complete
-           
-           c. QA Agent (New Chat): @qa → review-story
-              - Senior dev review with refactoring ability
-              - Fixes small issues directly
-              - Leaves checklist for remaining items
-              - Updates story status (Review → Done or stays Review)
-           
-           d. If QA left unchecked items:
-              - Dev Agent (New Chat): Address remaining items
-              - Return to QA for final approval
-        
-        4. REPEAT: Continue cycle for all epic stories
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - agent: sm
+      action: create_story
+      creates: story.md
+      requires: sharded_docs
+      repeats: for_each_epic
+      notes: |
+        Story creation cycle:
+        - SM Agent (New Chat): @sm → *create
+        - Creates next story from sharded docs
+        - Story starts in "Draft" status
+
+    - agent: analyst/pm
+      action: review_draft_story
+      updates: story.md
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - agent: dev
+      action: implement_story
+      creates: implementation_files
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - agent: qa
+      action: review_implementation
+      updates: implementation_files
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - repeat_development_cycle:
+      action: continue_for_all_stories
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - workflow_end:
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
         
         Reference: data#bmad-kb:IDE Development Workflow
 
@@ -129,21 +179,45 @@ workflow:
         G --> H
         H --> I{PO finds issues?}
         I -->|Yes| J[Return to relevant agent for fixes]
-        I -->|No| K[Move to IDE Environment]
+        I -->|No| K[po: shard documents]
         J --> H
+        
+        K --> L[sm: create story]
+        L --> M{Review draft story?}
+        M -->|Yes| N[analyst/pm: review & approve story]
+        M -->|No| O[dev: implement story]
+        N --> O
+        O --> P{QA review?}
+        P -->|Yes| Q[qa: review implementation]
+        P -->|No| R{More stories?}
+        Q --> S{QA found issues?}
+        S -->|Yes| T[dev: address QA feedback]
+        S -->|No| R
+        T --> Q
+        R -->|Yes| L
+        R -->|No| U{Epic retrospective?}
+        U -->|Yes| V[po: epic retrospective]
+        U -->|No| W[Project Complete]
+        V --> W
 
         B -.-> B1[Optional: brainstorming]
         B -.-> B2[Optional: market research]
         D -.-> D1[Optional: user research]
         E -.-> E1[Optional: technical research]
 
-        style K fill:#90EE90
+        style W fill:#90EE90
+        style K fill:#ADD8E6
+        style L fill:#ADD8E6
+        style O fill:#ADD8E6
         style D3 fill:#E6E6FA
         style D4 fill:#E6E6FA
         style B fill:#FFE4B5
         style C fill:#FFE4B5
         style D fill:#FFE4B5
         style E fill:#FFE4B5
+        style N fill:#F0E68C
+        style Q fill:#F0E68C
+        style V fill:#F0E68C
     ```
 
   decision_guidance:

bmad-core/workflows/greenfield-service.yaml

@@ -49,42 +49,92 @@ workflow:
       condition: po_checklist_issues
       notes: "If PO finds issues, return to relevant agent to fix and re-export updated documents to docs/ folder."
 
-    - workflow_end:
-      action: move_to_ide
+    - agent: po
+      action: shard_documents
+      creates: sharded_docs
+      requires: all_artifacts_in_project
       notes: |
-        Planning phase complete! Now transition to IDE Development:
-        
-        1. ENSURE DOCUMENTS ARE IN PROJECT:
-           - Copy final prd.md to project's docs/prd.md
-           - Copy final architecture.md to project's docs/architecture.md
-           - All documents must be in the project before proceeding
-        
-        2. SHARD DOCUMENTS (in IDE):
-           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
-           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
-           - This creates docs/prd/ and docs/architecture/ folders with sharded content
-        
-        3. START DEVELOPMENT CYCLE:
-           a. SM Agent (New Chat): @sm → *create
-              - Creates next story from sharded docs
-              - Review and approve story (Draft → Approved)
-           
-           b. Dev Agent (New Chat): @dev
-              - Implements approved story
-              - Updates File List with all changes
-              - Marks story as "Review" when complete
-           
-           c. QA Agent (New Chat): @qa → review-story
-              - Senior dev review with refactoring ability
-              - Fixes small issues directly
-              - Leaves checklist for remaining items
-              - Updates story status (Review → Done or stays Review)
-           
-           d. If QA left unchecked items:
-              - Dev Agent (New Chat): Address remaining items
-              - Return to QA for final approval
-        
-        4. REPEAT: Continue cycle for all epic stories
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - agent: sm
+      action: create_story
+      creates: story.md
+      requires: sharded_docs
+      repeats: for_each_epic
+      notes: |
+        Story creation cycle:
+        - SM Agent (New Chat): @sm → *create
+        - Creates next story from sharded docs
+        - Story starts in "Draft" status
+
+    - agent: analyst/pm
+      action: review_draft_story
+      updates: story.md
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - agent: dev
+      action: implement_story
+      creates: implementation_files
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - agent: qa
+      action: review_implementation
+      updates: implementation_files
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - repeat_development_cycle:
+      action: continue_for_all_stories
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - workflow_end:
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Service development phase complete.
         
         Reference: data#bmad-kb:IDE Development Workflow
 
@@ -100,17 +150,41 @@ workflow:
         F --> G
         G --> H{PO finds issues?}
         H -->|Yes| I[Return to relevant agent for fixes]
-        H -->|No| J[Move to IDE Environment]
+        H -->|No| J[po: shard documents]
         I --> G
+        
+        J --> K[sm: create story]
+        K --> L{Review draft story?}
+        L -->|Yes| M[analyst/pm: review & approve story]
+        L -->|No| N[dev: implement story]
+        M --> N
+        N --> O{QA review?}
+        O -->|Yes| P[qa: review implementation]
+        O -->|No| Q{More stories?}
+        P --> R{QA found issues?}
+        R -->|Yes| S[dev: address QA feedback]
+        R -->|No| Q
+        S --> P
+        Q -->|Yes| K
+        Q -->|No| T{Epic retrospective?}
+        T -->|Yes| U[po: epic retrospective]
+        T -->|No| V[Project Complete]
+        U --> V
 
         B -.-> B1[Optional: brainstorming]
         B -.-> B2[Optional: market research]
         D -.-> D1[Optional: technical research]
 
-        style J fill:#90EE90
+        style V fill:#90EE90
+        style J fill:#ADD8E6
+        style K fill:#ADD8E6
+        style N fill:#ADD8E6
         style B fill:#FFE4B5
         style C fill:#FFE4B5
         style D fill:#FFE4B5
+        style M fill:#F0E68C
+        style P fill:#F0E68C
+        style U fill:#F0E68C
     ```
 
   decision_guidance:

bmad-core/workflows/greenfield-ui.yaml

@@ -68,42 +68,92 @@ workflow:
       condition: user_has_generated_ui
       notes: "If user generated UI with v0/Lovable: For polyrepo setup, place downloaded project in separate frontend repo. For monorepo, place in apps/web or frontend/ directory. Review architecture document for specific guidance."
 
-    - workflow_end:
-      action: move_to_ide
+    - agent: po
+      action: shard_documents
+      creates: sharded_docs
+      requires: all_artifacts_in_project
       notes: |
-        Planning phase complete! Now transition to IDE Development:
-        
-        1. ENSURE DOCUMENTS ARE IN PROJECT:
-           - Copy final prd.md to project's docs/prd.md
-           - Copy final architecture.md to project's docs/architecture.md
-           - All documents must be in the project before proceeding
-        
-        2. SHARD DOCUMENTS (in IDE):
-           - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
-           - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
-           - This creates docs/prd/ and docs/architecture/ folders with sharded content
-        
-        3. START DEVELOPMENT CYCLE:
-           a. SM Agent (New Chat): @sm → *create
-              - Creates next story from sharded docs
-              - Review and approve story (Draft → Approved)
-           
-           b. Dev Agent (New Chat): @dev
-              - Implements approved story
-              - Updates File List with all changes
-              - Marks story as "Review" when complete
-           
-           c. QA Agent (New Chat): @qa → review-story
-              - Senior dev review with refactoring ability
-              - Fixes small issues directly
-              - Leaves checklist for remaining items
-              - Updates story status (Review → Done or stays Review)
-           
-           d. If QA left unchecked items:
-              - Dev Agent (New Chat): Address remaining items
-              - Return to QA for final approval
-        
-        4. REPEAT: Continue cycle for all epic stories
+        Shard documents for IDE development:
+        - Option A: Use PO agent to shard: @po then ask to shard docs/prd.md
+        - Option B: Manual: Drag shard-doc task + docs/prd.md into chat
+        - Creates docs/prd/ and docs/architecture/ folders with sharded content
+
+    - agent: sm
+      action: create_story
+      creates: story.md
+      requires: sharded_docs
+      repeats: for_each_epic
+      notes: |
+        Story creation cycle:
+        - SM Agent (New Chat): @sm → *create
+        - Creates next story from sharded docs
+        - Story starts in "Draft" status
+
+    - agent: analyst/pm
+      action: review_draft_story
+      updates: story.md
+      requires: story.md
+      optional: true
+      condition: user_wants_story_review
+      notes: |
+        OPTIONAL: Review and approve draft story
+        - NOTE: story-review task coming soon
+        - Review story completeness and alignment
+        - Update story status: Draft → Approved
+
+    - agent: dev
+      action: implement_story
+      creates: implementation_files
+      requires: story.md
+      notes: |
+        Dev Agent (New Chat): @dev
+        - Implements approved story
+        - Updates File List with all changes
+        - Marks story as "Review" when complete
+
+    - agent: qa
+      action: review_implementation
+      updates: implementation_files
+      requires: implementation_files
+      optional: true
+      notes: |
+        OPTIONAL: QA Agent (New Chat): @qa → review-story
+        - Senior dev review with refactoring ability
+        - Fixes small issues directly
+        - Leaves checklist for remaining items
+        - Updates story status (Review → Done or stays Review)
+
+    - agent: dev
+      action: address_qa_feedback
+      updates: implementation_files
+      condition: qa_left_unchecked_items
+      notes: |
+        If QA left unchecked items:
+        - Dev Agent (New Chat): Address remaining items
+        - Return to QA for final approval
+
+    - repeat_development_cycle:
+      action: continue_for_all_stories
+      notes: |
+        Repeat story cycle (SM → Dev → QA) for all epic stories
+        Continue until all stories in PRD are complete
+
+    - agent: po
+      action: epic_retrospective
+      creates: epic-retrospective.md
+      condition: epic_complete
+      optional: true
+      notes: |
+        OPTIONAL: After epic completion
+        - NOTE: epic-retrospective task coming soon
+        - Validate epic was completed correctly
+        - Document learnings and improvements
+
+    - workflow_end:
+      action: project_complete
+      notes: |
+        All stories implemented and reviewed!
+        Project development phase complete.
         
         Reference: data#bmad-kb:IDE Development Workflow
 
@@ -124,21 +174,45 @@ workflow:
         G --> H
         H --> I{PO finds issues?}
         I -->|Yes| J[Return to relevant agent for fixes]
-        I -->|No| K[Move to IDE Environment]
+        I -->|No| K[po: shard documents]
         J --> H
+        
+        K --> L[sm: create story]
+        L --> M{Review draft story?}
+        M -->|Yes| N[analyst/pm: review & approve story]
+        M -->|No| O[dev: implement story]
+        N --> O
+        O --> P{QA review?}
+        P -->|Yes| Q[qa: review implementation]
+        P -->|No| R{More stories?}
+        Q --> S{QA found issues?}
+        S -->|Yes| T[dev: address QA feedback]
+        S -->|No| R
+        T --> Q
+        R -->|Yes| L
+        R -->|No| U{Epic retrospective?}
+        U -->|Yes| V[po: epic retrospective]
+        U -->|No| W[Project Complete]
+        V --> W
 
         B -.-> B1[Optional: brainstorming]
         B -.-> B2[Optional: market research]
         D -.-> D1[Optional: user research]
         E -.-> E1[Optional: technical research]
 
-        style K fill:#90EE90
+        style W fill:#90EE90
+        style K fill:#ADD8E6
+        style L fill:#ADD8E6
+        style O fill:#ADD8E6
         style D3 fill:#E6E6FA
         style D4 fill:#E6E6FA
         style B fill:#FFE4B5
         style C fill:#FFE4B5
         style D fill:#FFE4B5
         style E fill:#FFE4B5
+        style N fill:#F0E68C
+        style Q fill:#F0E68C
+        style V fill:#F0E68C
     ```
 
   decision_guidance:

common/tasks/create-doc.md

@@ -0,0 +1,91 @@
+# Create Document from Template Task
+
+## Purpose
+
+Generate documents from templates by EXECUTING (not just reading) embedded instructions from the perspective of the selected agent persona.
+
+## CRITICAL RULES
+
+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
+
+## Execution Flow
+
+### 0. Check Workflow Plan (if configured)
+
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
+
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
+
+### 1. Identify Template
+
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
+
+### 2. Ask Interaction Mode
+
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
+
+### 3. Execute Template
+
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
+- Use @{examples} for guidance but never output them
+
+### 4. Key Execution Patterns
+
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
+
+- Draft the content
+- Present it to user
+- IMMEDIATELY execute the task
+- Wait for completion before continuing
+
+**When you see:** `[[LLM: After section completion, apply tasks#Y]]`
+
+- Finish the section
+- STOP and execute the task
+- Wait for user input
+
+### 5. Validation & Final Presentation
+
+- Run any specified checklists
+- Present clean, formatted content only
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
+
+### 6. Update Workflow Plan (if applicable)
+
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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.

common/tasks/execute-checklist.md

@@ -2,13 +2,9 @@
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -17,7 +13,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder

common/utils/template-format.md

@@ -1,6 +1,6 @@
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

common/utils/workflow-management.md

@@ -0,0 +1,69 @@
+# Workflow Management
+
+Enables BMad orchestrator to manage and execute team workflows.
+
+## Dynamic Workflow Loading
+
+Read available workflows from current team configuration's `workflows` field. Each team bundle defines its own supported workflows.
+
+**Key Commands**:
+
+- `/workflows` - List workflows in current bundle or workflows folder
+- `/agent-list` - Show agents in current bundle
+
+## Workflow Commands
+
+### /workflows
+
+Lists available workflows with titles and descriptions.
+
+### /workflow-start {workflow-id}
+
+Starts workflow and transitions to first agent.
+
+### /workflow-status
+
+Shows current progress, completed artifacts, and next steps.
+
+### /workflow-resume
+
+Resumes workflow from last position. User can provide completed artifacts.
+
+### /workflow-next
+
+Shows next recommended agent and action.
+
+## Execution Flow
+
+1. **Starting**: Load definition → Identify first stage → Transition to agent → Guide artifact creation
+
+2. **Stage Transitions**: Mark complete → Check conditions → Load next agent → Pass artifacts
+
+3. **Artifact Tracking**: Track status, creator, timestamps in workflow_state
+
+4. **Interruption Handling**: Analyze provided artifacts → Determine position → Suggest next step
+
+## Context Passing
+
+When transitioning, pass:
+
+- Previous artifacts
+- Current workflow stage
+- Expected outputs
+- Decisions/constraints
+
+## Multi-Path Workflows
+
+Handle conditional paths by asking clarifying questions when needed.
+
+## Best Practices
+
+1. Show progress
+2. Explain transitions
+3. Preserve context
+4. Allow flexibility
+5. Track state
+
+## Agent Integration
+
+Agents should be workflow-aware: know active workflow, their role, access artifacts, understand expected outputs.

dist/agents/analyst.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#analyst ====================
 # analyst
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -652,76 +652,93 @@ 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:
+### 0. Check Workflow Plan (if configured)
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **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)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
 - 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
-- **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
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-### 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
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-## Important Notes
+### 6. Update Workflow Plan (if applicable)
 
-- Template markup is for AI processing only - never expose to users
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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 ====================
@@ -1933,11 +1950,11 @@ These replace the standard elicitation options when working on competitive analy
 ==================== END: templates#competitor-analysis-tmpl ====================
 
 ==================== START: data#bmad-kb ====================
-# BMAD Knowledge Base
+# BMad Knowledge Base
 
 ## Overview
 
-BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework that combines AI agents with Agile development methodologies. The v4 system introduces a modular architecture with improved dependency management, bundle optimization, and support for both web and IDE environments.
+BMad-Method (Breakthrough Method of Agile AI-driven Development) is a framework that combines AI agents with Agile development methodologies. The v4 system introduces a modular architecture with improved dependency management, bundle optimization, and support for both web and IDE environments.
 
 ### Key Features
 
@@ -1947,7 +1964,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
 - **Reusable Resources**: Portable templates, tasks, and checklists
 - **Slash Command Integration**: Quick agent switching and control
 
-### When to Use BMAD
+### When to Use BMad
 
 - **New Projects (Greenfield)**: Complete end-to-end development
 - **Existing Projects (Brownfield)**: Feature additions and enhancements
@@ -1955,11 +1972,11 @@ BMAD-METHOD (Breakthrough Method of Agile AI-driven Development) is a framework
 - **Quality Assurance**: Structured testing and validation
 - **Documentation**: Professional PRDs, architecture docs, user stories
 
-## How BMAD Works
+## How BMad Works
 
 ### The Core Method
 
-BMAD transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
+BMad transforms you into a "Vibe CEO" - directing a team of specialized AI agents through structured workflows. Here's how:
 
 1. **You Direct, AI Executes**: You provide vision and decisions; agents handle implementation details
 2. **Specialized Agents**: Each agent masters one role (PM, Developer, Architect, etc.)
@@ -2013,7 +2030,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, Github Copilot users
 
 ```bash
 # Interactive installation (recommended)
@@ -2028,15 +2045,16 @@ npx bmad-method install
   - **Windsurf**: Built-in AI capabilities
   - **Cline**: VS Code extension with AI features
   - **Roo Code**: Web-based IDE with agent support
+  - **Github 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.
+**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.
 
 **Verify Installation**:
 - `.bmad-core/` folder created with all agents
 - IDE-specific integration files created
 - All agent commands/rules/modes available
 
-**Remember**: At its core, BMAD-METHOD is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMAD - the framework provides the structured prompts and workflows that make AI development effective
+**Remember**: At its core, BMad-Method is about mastering and harnessing prompt engineering. Any IDE with AI agent support can use BMad - the framework provides the structured prompts and workflows that make AI development effective
 
 ### Environment Selection Guide
 
@@ -2095,13 +2113,13 @@ npx bmad-method install
 5. **MUST switch to Dev agent** for implementation
 6. Keep planning and coding in separate chat sessions
 
-## Core Configuration (core-config.yml)
+## Core Configuration (core-config.yaml)
 
-**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+**New in V4**: The `bmad-core/core-config.yaml` file is a critical innovation that enables BMad to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
 
-### What is core-config.yml?
+### What is core-config.yaml?
 
-This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+This configuration file acts as a map for BMad agents, telling them exactly where to find your project documents and how they're structured. It enables:
 
 - **Version Flexibility**: Work with V3, V4, or custom document structures
 - **Custom Locations**: Define where your documents and shards live
@@ -2130,7 +2148,7 @@ This configuration file acts as a map for BMAD agents, telling them exactly wher
 
 1. **No Forced Migrations**: Keep your existing document structure
 2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
-3. **Custom Workflows**: Configure BMAD to match your team's process
+3. **Custom Workflows**: Configure BMad to match your team's process
 4. **Intelligent Agents**: Agents automatically adapt to your configuration
 
 ### Common Configurations
@@ -2213,6 +2231,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`)
+- **Github 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
@@ -2258,7 +2277,7 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 
 ### System Overview
 
-The BMAD-Method is built around a modular architecture centered on the `bmad-core` directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).
+The BMad-Method is built around a modular architecture centered on the `bmad-core` directory, which serves as the brain of the entire system. This design enables the framework to operate effectively in both IDE environments (like Cursor, VS Code) and web-based AI interfaces (like ChatGPT, Gemini).
 
 ### Key Architectural Components
 
@@ -2270,7 +2289,7 @@ The BMAD-Method is built around a modular architecture centered on the `bmad-cor
 
 #### 2. Agent Teams (`bmad-core/agent-teams/`)
 - **Purpose**: Define collections of agents bundled together for specific purposes
-- **Examples**: `team-all.yml` (comprehensive bundle), `team-fullstack.yml` (full-stack development)
+- **Examples**: `team-all.yaml` (comprehensive bundle), `team-fullstack.yaml` (full-stack development)
 - **Usage**: Creates pre-packaged contexts for web UI environments
 
 #### 3. Workflows (`bmad-core/workflows/`)
@@ -2302,7 +2321,7 @@ The BMAD-Method is built around a modular architecture centered on the `bmad-cor
 
 ### Template Processing System
 
-BMAD employs a sophisticated template system with three key components:
+BMad employs a sophisticated template system with three key components:
 
 1. **Template Format** (`utils/template-format.md`): Defines markup language for variable substitution and AI processing directives
 2. **Document Creation** (`tasks/create-doc.md`): Orchestrates template selection and user interaction
@@ -2331,7 +2350,7 @@ The `web-builder.js` tool creates web-ready bundles by:
 3. Concatenating content into single text files with clear separators
 4. Outputting ready-to-upload bundles for web AI interfaces
 
-This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMAD powerful.
+This architecture enables seamless operation across environments while maintaining the rich, interconnected agent ecosystem that makes BMad powerful.
 
 ## Complete Development Workflow
 
@@ -2592,7 +2611,7 @@ Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sh
 - **Keep conversations focused** - One agent, one task per conversation
 - **Review everything** - Always review and approve before marking complete
 
-## Contributing to BMAD-METHOD
+## Contributing to BMad-Method
 
 ### Quick Contribution Guidelines
 
@@ -2621,7 +2640,7 @@ For full details, see `CONTRIBUTING.md`. Key points:
 
 ### What Are Expansion Packs?
 
-Expansion packs extend BMAD-METHOD beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
+Expansion packs extend BMad-Method beyond traditional software development into ANY domain. They provide specialized agent teams, templates, and workflows while keeping the core framework lean and focused on development.
 
 ### Why Use Expansion Packs?
 
@@ -2654,7 +2673,7 @@ Expansion packs extend BMAD-METHOD beyond traditional software development into
 ### Using Expansion Packs
 
 1. **Browse Available Packs**: Check `expansion-packs/` directory
-2. **Get Inspiration**: See `docs/expansion-pack-ideas.md` for detailed examples
+2. **Get Inspiration**: See `docs/expansion-packs.md` for detailed examples and ideas
 3. **Install via CLI**: 
    ```bash
    npx bmad-method install
@@ -2685,7 +2704,7 @@ Use the **expansion-creator** pack to build your own:
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

dist/agents/architect.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#architect ====================
 # architect
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -107,76 +107,93 @@ 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:
+### 0. Check Workflow Plan (if configured)
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **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)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
 - 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
-- **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
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-### 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
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-## Important Notes
+### 6. Update Workflow Plan (if applicable)
 
-- Template markup is for AI processing only - never expose to users
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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 ====================
@@ -808,13 +825,9 @@ Apply the advanced elicitation task after major sections to refine based on user
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -823,7 +836,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder
@@ -1302,7 +1315,7 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 {{project-root}}/
 ├── .github/                    # CI/CD workflows
 │   └── workflows/
-│       └── main.yml
+│       └── main.yaml
 ├── .vscode/                    # VSCode settings (optional)
 │   └── settings.json
 ├── build/                      # Compiled output (git-ignored)
@@ -2151,7 +2164,7 @@ Use appropriate format for the chosen API style. If no API (e.g., static site),
 
 ^^CONDITION: has_rest_api^^
 
-```yml
+```yaml
 openapi: 3.0.0
 info:
   title:
@@ -2507,8 +2520,8 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 {{project-name}}/
 ├── .github/                    # CI/CD workflows
 │   └── workflows/
-│       ├── ci.yml
-│       └── deploy.yml
+│       ├── ci.yaml
+│       └── deploy.yaml
 ├── apps/                       # Application packages
 │   ├── web/                    # Frontend application
 │   │   ├── src/
@@ -3883,7 +3896,7 @@ None Listed
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

dist/agents/dev.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#dev ====================
 # dev
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 agent:
@@ -53,7 +53,7 @@ agent:
   customization: null
 startup:
   - Announce: Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Load .bmad-core/core-config.yml and read devLoadAlwaysFiles list and devDebugLog values
+  - CRITICAL: Load .bmad-core/core-config.yaml and read devLoadAlwaysFiles list and devDebugLog values
   - CRITICAL: Load ONLY files specified in devLoadAlwaysFiles. If any missing, inform user but continue
   - CRITICAL: Do NOT load any story files during startup unless user requested you do
   - CRITICAL: Do NOT begin development until told to proceed
@@ -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
@@ -102,13 +102,9 @@ dependencies:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -117,7 +113,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder

dist/agents/pm.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#pm ====================
 # pm
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -104,76 +104,93 @@ 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:
+### 0. Check Workflow Plan (if configured)
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **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)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
 - 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
-- **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
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-### 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
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-## Important Notes
+### 6. Update Workflow Plan (if applicable)
 
-- Template markup is for AI processing only - never expose to users
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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 ====================
@@ -874,13 +891,9 @@ The story creation is successful when:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -889,7 +902,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder
@@ -980,20 +993,20 @@ The LLM will:
 
 ## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
 
 If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
 
 If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
 
 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in bmad-core/core-config.yml
+2. Or set markdownExploder to false in bmad-core/core-config.yaml
 
 **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
 
 If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
 
-1. Set markdownExploder to true in bmad-core/core-config.yml
+1. Set markdownExploder to true in bmad-core/core-config.yaml
 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
 
 I will now proceed with the manual sharding process."
@@ -1393,34 +1406,45 @@ Do not proceed with any recommendations until the user has validated your unders
 
 ### Existing Project Overview
 
-[[LLM: If working in IDE with project loaded, analyze the project structure and existing documentation. If working in web interface, request project upload or detailed project information from user.]]
+[[LLM: Check if document-project analysis was already performed. If yes, reference that output instead of re-analyzing.]]
 
-**Project Location**: [[LLM: Note if this is IDE-based analysis or user-provided information]]
+**Analysis Source**: [[LLM: Indicate one of the following:
+- Document-project output available at: {{path}}
+- IDE-based fresh analysis
+- User-provided information
+]]
 
-**Current Project State**: [[LLM: Brief description of what the project currently does and its primary purpose]]
+**Current Project State**: [[LLM: 
+- If document-project output exists: Extract summary from "High Level Architecture" and "Technical Summary" sections
+- Otherwise: Brief description of what the project currently does and its primary purpose
+]]
 
 ### Available Documentation Analysis
 
-[[LLM: Check for existing documentation in docs folder or provided by user. List what documentation is available and assess its completeness. Required documents include:
+[[LLM: 
+If document-project was run:
+- Note: "Document-project analysis available - using existing technical documentation"
+- List key documents created by document-project
+- Skip the missing documentation check below
 
-- Tech stack documentation
-- Source tree/architecture overview
-- Coding standards
-- API documentation or OpenAPI specs
-- External API integrations
-- UX/UI guidelines or existing patterns]]
+Otherwise, check for existing documentation:
+]]
 
 **Available Documentation**:
 
-- [ ] Tech Stack Documentation
-- [ ] Source Tree/Architecture
-- [ ] Coding Standards
-- [ ] API Documentation
-- [ ] External API Documentation
-- [ ] UX/UI Guidelines
+- [ ] Tech Stack Documentation [[LLM: If from document-project, check ✓]]
+- [ ] Source Tree/Architecture [[LLM: If from document-project, check ✓]]
+- [ ] Coding Standards [[LLM: If from document-project, may be partial]]
+- [ ] API Documentation [[LLM: If from document-project, check ✓]]
+- [ ] External API Documentation [[LLM: If from document-project, check ✓]]
+- [ ] UX/UI Guidelines [[LLM: May not be in document-project]]
+- [ ] Technical Debt Documentation [[LLM: If from document-project, check ✓]]
 - [ ] Other: \***\*\_\_\_\*\***
 
-[[LLM: If critical documentation is missing, STOP and recommend: "I recommend running the document-project task first to generate baseline documentation including tech-stack, source-tree, coding-standards, APIs, external-APIs, and UX/UI information. This will provide the foundation needed for a comprehensive brownfield PRD."]]
+[[LLM: 
+- If document-project was already run: "Using existing project analysis from document-project output."
+- If critical documentation is missing and no document-project: "I recommend running the document-project task first..."
+]]
 
 ### Enhancement Scope Definition
 
@@ -1510,13 +1534,19 @@ Do not proceed with any recommendations until the user has validated your unders
 
 ### Existing Technology Stack
 
-[[LLM: Document the current technology stack that must be maintained or integrated with]]
+[[LLM: 
+If document-project output available:
+- Extract from "Actual Tech Stack" table in High Level Architecture section
+- Include version numbers and any noted constraints
 
-**Languages**: [[LLM: Current programming languages in use]]
-**Frameworks**: [[LLM: Current frameworks and their versions]]
-**Database**: [[LLM: Current database technology and schema considerations]]
-**Infrastructure**: [[LLM: Current deployment and hosting infrastructure]]
-**External Dependencies**: [[LLM: Current third-party services and APIs]]
+Otherwise, document the current technology stack:
+]]
+
+**Languages**: [[LLM: From document-project or fresh analysis]]
+**Frameworks**: [[LLM: From document-project or fresh analysis]]
+**Database**: [[LLM: From document-project or fresh analysis]]
+**Infrastructure**: [[LLM: From document-project or fresh analysis]]
+**External Dependencies**: [[LLM: From document-project "External Services" section or fresh analysis]]
 
 ### Integration Approach
 
@@ -1547,12 +1577,19 @@ Do not proceed with any recommendations until the user has validated your unders
 
 ### Risk Assessment and Mitigation
 
-[[LLM: Identify risks specific to working with existing codebase]]
+[[LLM: 
+If document-project output available:
+- Reference "Technical Debt and Known Issues" section
+- Include "Workarounds and Gotchas" that might impact enhancement
+- Note any identified constraints from "Critical Technical Debt"
 
-**Technical Risks**: [[LLM: Risks related to modifying existing code]]
-**Integration Risks**: [[LLM: Risks in integrating with existing systems]]
-**Deployment Risks**: [[LLM: Risks in deploying alongside existing features]]
-**Mitigation Strategies**: [[LLM: Specific strategies to address identified risks]]
+Build risk assessment incorporating existing known issues:
+]]
+
+**Technical Risks**: [[LLM: Include risks from document-project + new enhancement risks]]
+**Integration Risks**: [[LLM: Reference integration constraints from document-project]]
+**Deployment Risks**: [[LLM: Include deployment gotchas from document-project]]
+**Mitigation Strategies**: [[LLM: Address both existing and new risks]]
 
 ## Epic and Story Structure
 
@@ -1994,7 +2031,7 @@ After presenting the report, ask if the user wants:
 ==================== START: checklists#change-checklist ====================
 # Change Navigation Checklist
 
-**Purpose:** To systematically guide the selected Agent and user through the analysis and planning required when a significant change (pivot, tech issue, missing requirement, failed story) is identified during the BMAD workflow.
+**Purpose:** To systematically guide the selected Agent and user through the analysis and planning required when a significant change (pivot, tech issue, missing requirement, failed story) is identified during the BMad workflow.
 
 **Instructions:** Review each item with the user. Mark `[x]` for completed/confirmed, `[N/A]` if not applicable, or add notes for discussion points.
 
@@ -2069,7 +2106,7 @@ Think about both immediate and downstream effects.]]
 
 ## 3. Artifact Conflict & Impact Analysis
 
-[[LLM: Documentation drives development in BMAD. Check each artifact:
+[[LLM: Documentation drives development in BMad. Check each artifact:
 
 1. Does this change invalidate documented decisions?
 2. Are architectural assumptions still valid?
@@ -2185,7 +2222,7 @@ None Listed
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

dist/agents/po.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#po ====================
 # po
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -106,13 +106,9 @@ dependencies:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -121,7 +117,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder
@@ -212,20 +208,20 @@ The LLM will:
 
 ## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
 
 If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
 
 If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
 
 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
-2. Or set markdownExploder to false in bmad-core/core-config.yml
+2. Or set markdownExploder to false in bmad-core/core-config.yaml
 
 **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
 
 If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
 
-1. Set markdownExploder to true in bmad-core/core-config.yml
+1. Set markdownExploder to true in bmad-core/core-config.yaml
 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
 
 I will now proceed with the manual sharding process."
@@ -1303,7 +1299,7 @@ After presenting the report, ask if the user wants:
 ==================== START: checklists#change-checklist ====================
 # Change Navigation Checklist
 
-**Purpose:** To systematically guide the selected Agent and user through the analysis and planning required when a significant change (pivot, tech issue, missing requirement, failed story) is identified during the BMAD workflow.
+**Purpose:** To systematically guide the selected Agent and user through the analysis and planning required when a significant change (pivot, tech issue, missing requirement, failed story) is identified during the BMad workflow.
 
 **Instructions:** Review each item with the user. Mark `[x]` for completed/confirmed, `[N/A]` if not applicable, or add notes for discussion points.
 
@@ -1378,7 +1374,7 @@ Think about both immediate and downstream effects.]]
 
 ## 3. Artifact Conflict & Impact Analysis
 
-[[LLM: Documentation drives development in BMAD. Check each artifact:
+[[LLM: Documentation drives development in BMad. Check each artifact:
 
 1. Does this change invalidate documented decisions?
 2. Are architectural assumptions still valid?
@@ -1488,7 +1484,7 @@ Keep it action-oriented and forward-looking.]]
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

dist/agents/qa.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#qa ====================
 # qa
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -235,7 +235,7 @@ None Listed
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

dist/agents/sm.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#sm ====================
 # sm
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -79,7 +79,7 @@ dependencies:
   tasks:
     - create-next-story
     - execute-checklist
-    - course-correct
+    - correct-course
   templates:
     - story-tmpl
   checklists:
@@ -102,12 +102,12 @@ To identify the next logical story based on project progress and epic definition
 
 [[LLM: CRITICAL - This MUST be your first step]]
 
-- Load `.bmad-core/core-config.yml` from the project root
+- Load `.bmad-core/core-config.yaml` from the project root
 - If the file does not exist:
-  - HALT and inform the user: "core-config.yml not found. This file is required for story creation. You can:
-    1. Copy it from GITHUB BMAD-METHOD/bmad-core/core-config.yml and configure it for your project
-    2. Run the BMAD installer against your project to upgrade and add the file automatically
-    Please add and configure core-config.yml before proceeding."
+  - HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can:
+    1. Copy it from GITHUB BMad-Method/bmad-core/core-config.yaml and configure it for your project
+    2. Run the BMad installer against your project to upgrade and add the file automatically
+    Please add and configure core-config.yaml before proceeding."
 - Extract the following key configurations:
   - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
@@ -118,6 +118,22 @@ To identify the next logical story based on project progress and epic definition
   - `architecture.architectureSharded`: Whether architecture is sharded
   - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
+  - `workflow.trackProgress`: Whether workflow plan tracking is enabled
+  - `workflow.planFile`: Location of workflow plan (if tracking enabled)
+
+### 0.5 Check Workflow Plan (if configured)
+
+[[LLM: Check if workflow plan tracking is enabled]]
+
+- If `workflow.trackProgress: true`, check for active plan at `workflow.planFile`
+- If plan exists:
+  - Parse plan to check if story creation is the expected next step
+  - If out of sequence and `workflow.enforceSequence: true`:
+    - Show warning: "The workflow plan indicates you should complete {expected_step} before creating stories."
+    - Block execution unless user explicitly overrides
+  - If out of sequence and `workflow.enforceSequence: false`:
+    - Show warning but allow continuation with confirmation
+- Continue with story identification after plan check
 
 ### 1. Identify Next Story for Preparation
 
@@ -341,6 +357,15 @@ Provide a summary to the user including:
 - Recommendations for story review before approval
 - Next steps: Story should be reviewed by PO for approval before dev work begins
 
+### 10. Update Workflow Plan (if applicable)
+
+[[LLM: After successful story creation]]
+
+- If `workflow.trackProgress: true` and `workflow.updateOnCompletion: true`:
+  - Call update-workflow-plan task to mark story creation step complete
+  - Parameters: task: create-next-story, step_id: {from plan}, status: complete
+  - If plan shows next step, mention it in completion message
+
 [[LLM: Remember - The success of this task depends on extracting real, specific technical details from the architecture shards. The dev agent should have everything they need in the story file without having to search through multiple documents.]]
 ==================== END: tasks#create-next-story ====================
 
@@ -349,13 +374,9 @@ Provide a summary to the user including:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -364,7 +385,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder
@@ -444,6 +465,82 @@ The LLM will:
 - Offer to provide detailed analysis of any section, especially those with warnings or failures
 ==================== END: tasks#execute-checklist ====================
 
+==================== START: tasks#correct-course ====================
+# Correct Course Task
+
+## Purpose
+
+- Guide a structured response to a change trigger using the `change-checklist`.
+- Analyze the impacts of the change on epics, project artifacts, and the MVP, guided by the checklist's structure.
+- Explore potential solutions (e.g., adjust scope, rollback elements, rescope features) as prompted by the checklist.
+- Draft specific, actionable proposed updates to any affected project artifacts (e.g., epics, user stories, PRD sections, architecture document sections) based on the analysis.
+- Produce a consolidated "Sprint Change Proposal" document that contains the impact analysis and the clearly drafted proposed edits for user review and approval.
+- Ensure a clear handoff path if the nature of the changes necessitates fundamental replanning by other core agents (like PM or Architect).
+
+## Instructions
+
+### 1. Initial Setup & Mode Selection
+
+- **Acknowledge Task & Inputs:**
+  - Confirm with the user that the "Correct Course Task" (Change Navigation & Integration) is being initiated.
+  - Verify the change trigger and ensure you have the user's initial explanation of the issue and its perceived impact.
+  - Confirm access to all relevant project artifacts (e.g., PRD, Epics/Stories, Architecture Documents, UI/UX Specifications) and, critically, the `change-checklist` (e.g., `change-checklist`).
+- **Establish Interaction Mode:**
+  - Ask the user their preferred interaction mode for this task:
+    - **"Incrementally (Default & Recommended):** Shall we work through the `change-checklist` section by section, discussing findings and collaboratively drafting proposed changes for each relevant part before moving to the next? This allows for detailed, step-by-step refinement."
+    - **"YOLO Mode (Batch Processing):** Or, would you prefer I conduct a more batched analysis based on the checklist and then present a consolidated set of findings and proposed changes for a broader review? This can be quicker for initial assessment but might require more extensive review of the combined proposals."
+  - Request the user to select their preferred mode.
+  - Once the user chooses, confirm the selected mode (e.g., "Okay, we will proceed in Incremental mode."). This chosen mode will govern how subsequent steps in this task are executed.
+- **Explain Process:** Briefly inform the user: "We will now use the `change-checklist` to analyze the change and draft proposed updates. I will guide you through the checklist items based on our chosen interaction mode."
+  <rule>When asking multiple questions or presenting multiple points for user input at once, number them clearly (e.g., 1., 2a., 2b.) to make it easier for the user to provide specific responses.</rule>
+
+### 2. Execute Checklist Analysis (Iteratively or Batched, per Interaction Mode)
+
+- Systematically work through Sections 1-4 of the `change-checklist` (typically covering Change Context, Epic/Story Impact Analysis, Artifact Conflict Resolution, and Path Evaluation/Recommendation).
+- For each checklist item or logical group of items (depending on interaction mode):
+  - Present the relevant prompt(s) or considerations from the checklist to the user.
+  - Request necessary information and actively analyze the relevant project artifacts (PRD, epics, architecture documents, story history, etc.) to assess the impact.
+  - Discuss your findings for each item with the user.
+  - Record the status of each checklist item (e.g., `[x] Addressed`, `[N/A]`, `[!] Further Action Needed`) and any pertinent notes or decisions.
+  - Collaboratively agree on the "Recommended Path Forward" as prompted by Section 4 of the checklist.
+
+### 3. Draft Proposed Changes (Iteratively or Batched)
+
+- Based on the completed checklist analysis (Sections 1-4) and the agreed "Recommended Path Forward" (excluding scenarios requiring fundamental replans that would necessitate immediate handoff to PM/Architect):
+  - Identify the specific project artifacts that require updates (e.g., specific epics, user stories, PRD sections, architecture document components, diagrams).
+  - **Draft the proposed changes directly and explicitly for each identified artifact.** Examples include:
+    - Revising user story text, acceptance criteria, or priority.
+    - Adding, removing, reordering, or splitting user stories within epics.
+    - Proposing modified architecture diagram snippets (e.g., providing an updated Mermaid diagram block or a clear textual description of the change to an existing diagram).
+    - Updating technology lists, configuration details, or specific sections within the PRD or architecture documents.
+    - Drafting new, small supporting artifacts if necessary (e.g., a brief addendum for a specific decision).
+  - If in "Incremental Mode," discuss and refine these proposed edits for each artifact or small group of related artifacts with the user as they are drafted.
+  - If in "YOLO Mode," compile all drafted edits for presentation in the next step.
+
+### 4. Generate "Sprint Change Proposal" with Edits
+
+- Synthesize the complete `change-checklist` analysis (covering findings from Sections 1-4) and all the agreed-upon proposed edits (from Instruction 3) into a single document titled "Sprint Change Proposal." This proposal should align with the structure suggested by Section 5 of the `change-checklist` (Proposal Components).
+- The proposal must clearly present:
+  - **Analysis Summary:** A concise overview of the original issue, its analyzed impact (on epics, artifacts, MVP scope), and the rationale for the chosen path forward.
+  - **Specific Proposed Edits:** For each affected artifact, clearly show or describe the exact changes (e.g., "Change Story X.Y from: [old text] To: [new text]", "Add new Acceptance Criterion to Story A.B: [new AC]", "Update Section 3.2 of Architecture Document as follows: [new/modified text or diagram description]").
+- Present the complete draft of the "Sprint Change Proposal" to the user for final review and feedback. Incorporate any final adjustments requested by the user.
+
+### 5. Finalize & Determine Next Steps
+
+- Obtain explicit user approval for the "Sprint Change Proposal," including all the specific edits documented within it.
+- Provide the finalized "Sprint Change Proposal" document to the user.
+- **Based on the nature of the approved changes:**
+  - **If the approved edits sufficiently address the change and can be implemented directly or organized by a PO/SM:** State that the "Correct Course Task" is complete regarding analysis and change proposal, and the user can now proceed with implementing or logging these changes (e.g., updating actual project documents, backlog items). Suggest handoff to a PO/SM agent for backlog organization if appropriate.
+  - **If the analysis and proposed path (as per checklist Section 4 and potentially Section 6) indicate that the change requires a more fundamental replan (e.g., significant scope change, major architectural rework):** Clearly state this conclusion. Advise the user that the next step involves engaging the primary PM or Architect agents, using the "Sprint Change Proposal" as critical input and context for that deeper replanning effort.
+
+## Output Deliverables
+
+- **Primary:** A "Sprint Change Proposal" document (in markdown format). This document will contain:
+  - A summary of the `change-checklist` analysis (issue, impact, rationale for the chosen path).
+  - Specific, clearly drafted proposed edits for all affected project artifacts.
+- **Implicit:** An annotated `change-checklist` (or the record of its completion) reflecting the discussions, findings, and decisions made during the process.
+==================== END: tasks#correct-course ====================
+
 ==================== START: templates#story-tmpl ====================
 # Story {{EpicNum}}.{{StoryNum}}: {{Short Title Copied from Epic File specific story}}
 
@@ -678,7 +775,7 @@ Be pragmatic - perfect documentation doesn't exist. Focus on whether a competent
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

dist/agents/ux-expert.txt

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#ux-expert ====================
 # ux-expert
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -464,76 +464,93 @@ 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:
+### 0. Check Workflow Plan (if configured)
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **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)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
 - 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
-- **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
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-### 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
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-## Important Notes
+### 6. Update Workflow Plan (if applicable)
 
-- Template markup is for AI processing only - never expose to users
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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 ====================
@@ -541,13 +558,9 @@ If template specifies a checklist:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -556,7 +569,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder
@@ -1061,7 +1074,7 @@ None Listed
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

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

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#game-designer ====================
 # game-designer
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -104,76 +104,93 @@ 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:
+### 0. Check Workflow Plan (if configured)
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **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)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
 - 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
-- **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
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-### 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
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-## Important Notes
+### 6. Update Workflow Plan (if applicable)
 
-- Template markup is for AI processing only - never expose to users
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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 ====================
@@ -181,13 +198,9 @@ If template specifies a checklist:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -196,7 +209,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder

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

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#game-developer ====================
 # game-developer
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -112,13 +112,9 @@ dependencies:
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -127,7 +123,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder

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

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#game-sm ====================
 # game-sm
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -316,13 +316,9 @@ This task ensures game development stories are immediately actionable and enable
 
 This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
 
-## Context
-
-The BMAD Method uses various checklists to ensure quality and completeness of different artifacts. Each checklist contains embedded prompts and instructions to guide the LLM through thorough validation and advanced elicitation. The checklists automatically identify their required artifacts and guide the validation process.
-
 ## Available Checklists
 
-If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the bmad-core/checklists folder to select the appropriate one to run.
+If the user asks or does not specify a specific checklist, list the checklists available to the agent persona. If the task is being run not with a specific agent, tell the user to check the {root}/checklists folder to select the appropriate one to run.
 
 ## Instructions
 
@@ -331,7 +327,7 @@ If the user asks or does not specify a specific checklist, list the checklists a
    - If user or the task being run provides a checklist name:
      - Try fuzzy matching (e.g. "architecture checklist" -> "architect-checklist")
      - If multiple matches found, ask user to clarify
-     - Load the appropriate checklist from bmad-core/checklists/
+     - Load the appropriate checklist from {root}/checklists/
    - If no checklist specified:
      - Ask the user which checklist they want to use
      - Present the available options from the files in the checklists folder

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

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#bmad-the-creator ====================
 # bmad-the-creator
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -52,27 +52,27 @@ activation-instructions:
 agent:
   name: The Creator
   id: bmad-the-creator
-  title: BMAD Framework Extension Specialist
+  title: BMad Framework Extension Specialist
   icon: 🏗️
-  whenToUse: Use for creating new agents, expansion packs, and extending the BMAD framework
+  whenToUse: Use for creating new agents, expansion packs, and extending the BMad framework
   customization: null
 persona:
-  role: Expert BMAD Framework Architect & Creator
+  role: Expert BMad Framework Architect & Creator
   style: Methodical, creative, framework-aware, systematic
-  identity: Master builder who extends BMAD capabilities through thoughtful design and deep framework understanding
-  focus: Creating well-structured agents, expansion packs, and framework extensions that follow BMAD patterns and conventions
+  identity: Master builder who extends BMad capabilities through thoughtful design and deep framework understanding
+  focus: Creating well-structured agents, expansion packs, and framework extensions that follow BMad patterns and conventions
 core_principles:
-  - Framework Consistency - All creations follow established BMAD patterns
+  - Framework Consistency - All creations follow established BMad patterns
   - Modular Design - Create reusable, composable components
   - Clear Documentation - Every creation includes proper documentation
-  - Convention Over Configuration - Follow BMAD naming and structure patterns
+  - Convention Over Configuration - Follow BMad naming and structure patterns
   - Extensibility First - Design for future expansion and customization
   - Numbered Options Protocol - Always use numbered lists for user selections
 startup:
   - Greet the user with your name and role, and inform of the *help command
   - CRITICAL: Do NOT automatically create documents or execute tasks during startup
   - CRITICAL: Do NOT create or modify any files during startup
-  - Offer to help with BMAD framework extensions but wait for explicit user confirmation
+  - Offer to help with BMad framework extensions but wait for explicit user confirmation
   - Only execute tasks when user explicitly requests them
 commands:
   - '*help" - Show numbered list of available commands for selection'
@@ -97,7 +97,7 @@ dependencies:
 ==================== START: tasks#create-agent ====================
 # Create Agent Task
 
-This task guides you through creating a new BMAD agent following the standard template.
+This task guides you through creating a new BMad agent following the standard template.
 
 ## Prerequisites
 
@@ -300,11 +300,11 @@ dependencies:
 ==================== START: tasks#generate-expansion-pack ====================
 # Create Expansion Pack Task
 
-This task helps you create a sophisticated BMAD expansion pack with advanced agent orchestration, template systems, and quality assurance patterns based on proven best practices.
+This task helps you create a sophisticated BMad expansion pack with advanced agent orchestration, template systems, and quality assurance patterns based on proven best practices.
 
 ## Understanding Expansion Packs
 
-Expansion packs extend BMAD with domain-specific capabilities using sophisticated AI agent orchestration patterns. They are self-contained packages that leverage:
+Expansion packs extend BMad with domain-specific capabilities using sophisticated AI agent orchestration patterns. They are self-contained packages that leverage:
 
 - **Advanced Agent Architecture**: YAML-in-Markdown with embedded personas and character consistency
 - **Template Systems**: LLM instruction embedding with conditional content and dynamic variables
@@ -312,7 +312,7 @@ Expansion packs extend BMAD with domain-specific capabilities using sophisticate
 - **Quality Assurance**: Multi-level validation with star ratings and comprehensive checklists
 - **Knowledge Integration**: Domain-specific data organization and best practices embedding
 
-Every expansion pack MUST include a custom BMAD orchestrator agent with sophisticated command systems and numbered options protocols.
+Every expansion pack MUST include a custom BMad orchestrator agent with sophisticated command systems and numbered options protocols.
 
 ## CRITICAL REQUIREMENTS
 
@@ -383,7 +383,7 @@ Create `expansion-packs/{pack-name}/plan.md` with:
 
 ### Agents (with Character Personas)
 
-- [ ] {pack-name}-orchestrator (REQUIRED: Custom BMAD orchestrator)
+- [ ] {pack-name}-orchestrator (REQUIRED: Custom BMad orchestrator)
   - Character Name: {human-name}
   - Communication Style: {style}
   - Key Commands: {command-list}
@@ -457,7 +457,7 @@ Important: Wait for user approval before proceeding to Phase 2
 
 #### 2.1 Create Orchestrator Agent with Domain-Themed Character
 
-**FIRST PRIORITY**: Design the custom BMAD orchestrator with domain-appropriate theme:
+**FIRST PRIORITY**: Design the custom BMad orchestrator with domain-appropriate theme:
 
 **Themed Character Design:**
 
@@ -483,7 +483,7 @@ Important: Wait for user approval before proceeding to Phase 2
 - **Activation Instructions**: Embedded YAML with behavior directives
 - **Startup Procedures**: Initialize without auto-execution
 - **Dependencies**: Clear references to tasks, templates, and data files
-- **Integration Points**: How it coordinates with core BMAD agents
+- **Integration Points**: How it coordinates with core BMad agents
 
 #### 2.2 Design Specialist Agents with Character Personas
 
@@ -586,7 +586,7 @@ IMPORTANT: Only proceed after plan.md is approved
 expansion-packs/
 └── {pack-name}/
 ├── plan.md (ALREADY CREATED)
-├── manifest.yml
+├── manifest.yaml
 ├── README.md
 ├── agents/
 │ ├── {pack-name}-orchestrator.md (REQUIRED - Custom themed orchestrator)
@@ -609,13 +609,13 @@ expansion-packs/
 ├── workflows/
 │ └── {domain}-workflow.md (REQUIRED if multiple agents)
 └── agent-teams/
-└── {domain}-team.yml (REQUIRED if multiple agents)
+└── {domain}-team.yaml (REQUIRED if multiple agents)
 
 ```
 
 #### 3.2 Create Manifest
 
-Create `manifest.yml`:
+Create `manifest.yaml`:
 
 ```yaml
 name: {pack-name}
@@ -658,7 +658,7 @@ files:
     - {domain}-workflow.md        # REQUIRED if multiple agents - decision trees
 
   agent-teams:
-    - {domain}-team.yml           # REQUIRED if multiple agents - team config
+    - {domain}-team.yaml          # REQUIRED if multiple agents - team config
 
 # Data files users must provide (in their bmad-core/data/ directory)
 required_user_data:
@@ -674,7 +674,7 @@ embedded_knowledge:
   - {domain}-terminology.md
   - {domain}-standards.md
 
-# Dependencies on core BMAD components
+# Dependencies on core BMad components
 core_dependencies:
   agents:
     - architect        # For system design
@@ -736,17 +736,17 @@ IMPORTANT: Work through plan.md checklist systematically!
 
 **Step 2: Copy Core Utilities**
 
-Before proceeding, copy these essential files from bmad-core:
+Before proceeding, copy these essential files from common:
 
 ```bash
 # Copy core task utilities
-cp bmad-core/tasks/create-doc.md expansion-packs/{pack-name}/tasks/
-cp bmad-core/tasks/execute-checklist.md expansion-packs/{pack-name}/tasks/
+cp common/tasks/create-doc.md expansion-packs/{pack-name}/tasks/
+cp common/tasks/execute-checklist.md expansion-packs/{pack-name}/tasks/
 
 # Copy core utility files
 mkdir -p expansion-packs/{pack-name}/utils
-cp bmad-core/utils/template-format.md expansion-packs/{pack-name}/utils/
-cp bmad-core/utils/workflow-management.md expansion-packs/{pack-name}/utils/
+cp common/utils/template-format.md expansion-packs/{pack-name}/utils/
+cp common/utils/workflow-management.md expansion-packs/{pack-name}/utils/
 ```
 
 **Step 3: Technical Implementation**
@@ -794,7 +794,7 @@ cp bmad-core/utils/workflow-management.md expansion-packs/{pack-name}/utils/
 1. Design decision trees for workflow branching
 2. Create handoff protocols to specialist agents
 3. Implement validation loops and quality checkpoints
-4. **If multiple agents**: Create team configuration in `agent-teams/{domain}-team.yml`
+4. **If multiple agents**: Create team configuration in `agent-teams/{domain}-team.yaml`
 5. **If multiple agents**: Create workflow in `workflows/{domain}-workflow.md`
 6. Ensure orchestrator references workflow-management utility
 7. Verify ALL referenced tasks exist (including core utilities)
@@ -965,7 +965,7 @@ Before declaring complete:
 
 1. [ ] Decision trees and workflow orchestration complete
 2. [ ] Knowledge base files embedded (best practices, terminology, standards)
-3. [ ] Manifest.yml reflects all components and dependencies
+3. [ ] Manifest.yaml reflects all components and dependencies
 4. [ ] All items in plan.md marked complete
 5. [ ] No orphaned tasks or templates
 
@@ -1072,7 +1072,7 @@ These files are automatically available to all agents and don't require user set
 ```text
 healthcare/
 ├── plan.md (Created first for approval)
-├── manifest.yml (with dependency mapping and character descriptions)
+├── manifest.yaml (with dependency mapping and character descriptions)
 ├── README.md (featuring character introductions and numbered options)
 ├── agents/
 │   ├── healthcare-orchestrator.md (Dr. Sarah Chen - YAML-in-Markdown)
@@ -1098,7 +1098,7 @@ healthcare/
 │   ├── clinical-trial-workflow.md (decision trees with Mermaid diagrams)
 │   └── compliance-audit-workflow.md (handoff protocols and quality gates)
 └── agent-teams/
-    └── healthcare-team.yml (coordinated team configurations)
+    └── healthcare-team.yaml (coordinated team configurations)
 
 Required user data files (bmad-core/data/):
 - medical-terminology.md (institution-specific terms and abbreviations)
@@ -1163,7 +1163,7 @@ Embedded knowledge (automatic):
 7. "Where in the workflow should users choose between different paths?"
 8. "How should the orchestrator hand off to specialist agents?"
 9. "What quality gates should be built into the workflow?"
-10. "How should it integrate with core BMAD agents?"
+10. "How should it integrate with core BMad agents?"
 
 ### Agent Planning
 
@@ -1213,7 +1213,7 @@ Embedded knowledge (automatic):
 **Quality and Validation:**
 
 - **Plan First**: ALWAYS create and get approval for plan.md before implementing
-- **Orchestrator Required**: Every pack MUST have a custom BMAD orchestrator with sophisticated command system
+- **Orchestrator Required**: Every pack MUST have a custom BMad orchestrator with sophisticated command system
 - **Verify References**: ALL referenced tasks/templates MUST exist and be tested
 - **Multi-Level Validation**: Quality systems must provide basic, comprehensive, and expert-level assessment
 - **Domain Expertise**: Ensure accuracy in specialized fields with embedded best practices
@@ -1309,7 +1309,7 @@ Embedded knowledge (automatic):
 - [ ] All agent references verified (tasks, templates, data, checklists)
 - [ ] Data requirements documented with validation criteria and examples
 - [ ] README includes character introductions and numbered options explanation
-- [ ] manifest.yml reflects actual files with dependency mapping and character descriptions
+- [ ] manifest.yaml reflects actual files with dependency mapping and character descriptions
 
 **Advanced Quality Gates:**
 
@@ -1730,9 +1730,9 @@ Present these numbered options to the user:
 4. Character personas should be consistent and domain-appropriate
 5. Follow the numbered options protocol for all user interactions]]
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
-```yml
+```yaml
 activation-instructions:
     - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
     - Only read the files/tasks listed here when user selects them for execution to minimize context usage
@@ -1938,7 +1938,7 @@ Users must add these files to `bmad-core/data/`:
 
 ## Integration Points
 
-- Depends on core agents: {list any core BMAD agents used}
+- Depends on core agents: {list any core BMad agents used}
 - Extends teams: {which teams to update}
 
 ## Success Criteria

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

@@ -1,6 +1,6 @@
 # Web Agent Bundle Instructions
 
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
+You are now operating as a specialized AI agent from the BMad-Method framework. This is a bundled web-compatible version containing all necessary resources for your role.
 
 ## Important Instructions
 
@@ -34,14 +34,14 @@ These references map directly to bundle sections:
 
 3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
 
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMad-Method framework.
 
 ---
 
 ==================== START: agents#infra-devops-platform ====================
 # infra-devops-platform
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions:
@@ -105,76 +105,93 @@ 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:
+### 0. Check Workflow Plan (if configured)
 
-    @{example}
-    dependencies:
-    templates: - prd-tmpl - architecture-tmpl
-    @{/example}
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
 
-    You would offer to create "PRD" and "Architecture" documents when the user asks what you can help with.
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
 
-- Gather all relevant inputs, or ask for them, or else rely on user providing necessary details to complete the document
-- Understand the document purpose and target audience
+### 1. Identify Template
 
-### 2. Determine Interaction Mode
+- Load from `templates#*` or `{root}/templates directory`
+- Agent-specific templates are listed in agent's dependencies
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
-Confirm with the user their preferred interaction style:
+### 2. Ask Interaction Mode
 
-- **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)
+> 1. **Incremental** - Section by section with reviews
+> 2. **YOLO Mode** - Complete draft then review (user can type `/yolo` anytime to switch)
 
 ### 3. Execute Template
 
-- Load specified template from `templates#*` or the /templates directory
-- Follow ALL embedded LLM instructions within the template
-- Process template markup according to `utils#template-format` conventions
-
-### 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
+- Replace {{placeholders}} with real content
+- Execute [[LLM:]] instructions as you encounter them
+- Process <<REPEAT>> loops and ^^CONDITIONS^^
 - 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
-- **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
+**When you see:** `[[LLM: Draft X and immediately execute tasks#advanced-elicitation]]`
 
-### 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
-- Document completion status for each item
-- Address any deficiencies found
-- Present validation summary to user
+- Finish the section
+- STOP and execute the task
+- Wait for user input
 
-### 7. Final Presentation
+### 5. Validation & Final Presentation
 
+- Run any specified checklists
 - Present clean, formatted content only
-- Ensure all sections are complete
-- DO NOT truncate or summarize content
-- Begin directly with document content (no preamble)
-- Include any handoff prompts specified in template
+- No truncation or summarization
+- Begin directly with content (no preamble)
+- Include any handoff prompts from template
 
-## Important Notes
+### 6. Update Workflow Plan (if applicable)
 
-- Template markup is for AI processing only - never expose to users
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
+## Common Mistakes to Avoid
+
+❌ 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 ====================
@@ -235,13 +252,13 @@ To conduct a thorough review of existing infrastructure to identify improvement
 - Create an improvement roadmap with suggested timelines
 - Highlight cost optimization opportunities
 
-### 5. BMAD Integration Assessment
+### 5. BMad Integration Assessment
 
-- Evaluate how current infrastructure supports other BMAD agents:
+- Evaluate how current infrastructure supports other BMad agents:
   - **Development Support:** Assess how infrastructure enables Frontend Dev (Mira), Backend Dev (Enrique), and Full Stack Dev workflows
   - **Product Alignment:** Verify infrastructure supports PRD requirements from Product Owner (Oli)
   - **Architecture Compliance:** Check if implementation follows Architect (Alphonse) decisions
-  - Document any gaps in BMAD integration
+  - Document any gaps in BMad integration
 
 ### 6. Architectural Escalation Assessment
 
@@ -313,7 +330,7 @@ A comprehensive infrastructure review report that includes:
 2. **Prioritized findings** with severity ratings
 3. **Detailed recommendations** with effort/impact estimates
 4. **Cost optimization opportunities**
-5. **BMAD integration assessment**
+5. **BMad integration assessment**
 6. **Architectural escalation assessment** with clear escalation recommendations
 7. **Action plan** for critical improvements and architectural work
 8. **Escalation documentation** for Architect Agent collaboration (if applicable)
@@ -345,7 +362,7 @@ REPEAT by Asking the user if they would like to perform another Reflective, Elic
 
 ## Purpose
 
-To comprehensively validate platform infrastructure changes against security, reliability, operational, and compliance requirements before deployment. This task ensures all platform infrastructure meets organizational standards, follows best practices, and properly integrates with the broader BMAD ecosystem.
+To comprehensively validate platform infrastructure changes against security, reliability, operational, and compliance requirements before deployment. This task ensures all platform infrastructure meets organizational standards, follows best practices, and properly integrates with the broader BMad ecosystem.
 
 ## Inputs
 
@@ -425,9 +442,9 @@ To comprehensively validate platform infrastructure changes against security, re
 - Provide validation signoff recommendation based on complete platform assessment
 - Document platform component integration validation results
 
-### 6. BMAD Integration Assessment
+### 6. BMad Integration Assessment
 
-- Review how platform infrastructure changes support other BMAD agents:
+- Review how platform infrastructure changes support other BMad agents:
   - **Development Agent Alignment:** Verify platform infrastructure supports Frontend Dev, Backend Dev, and Full Stack Dev requirements including:
     - Container platform development environment provisioning
     - GitOps workflows for application deployment
@@ -471,7 +488,7 @@ A comprehensive platform validation report documenting:
 3. **Detailed findings for each non-compliant item** across foundation and platform components
 4. **Platform integration validation results** documenting component interoperability
 5. **Remediation recommendations with priority levels** based on platform impact
-6. **BMAD integration assessment results** for complete platform stack
+6. **BMad integration assessment results** for complete platform stack
 7. **Clear signoff recommendation** for platform deployment readiness or architectural revision requirements
 8. **Next steps for implementation or remediation** prioritized by platform dependencies
 
@@ -764,9 +781,9 @@ Create pipeline diagram showing:
 - Cost Monitoring & Reporting
 - Optimization Recommendations
 
-## BMAD Integration Architecture
+## BMad Integration Architecture
 
-[[LLM: Design infrastructure to specifically support other BMAD agents and their workflows. This ensures the infrastructure enables the entire BMAD methodology.]]
+[[LLM: Design infrastructure to specifically support other BMad agents and their workflows. This ensures the infrastructure enables the entire BMad methodology.]]
 
 ### Development Agent Support
 
@@ -1283,7 +1300,7 @@ kind: ConfigMap
 metadata:
   name: prometheus-config
 data:
-  prometheus.yml: |
+  prometheus.yaml: |
     global:
       scrape_interval: {{scrape_interval}}
     scrape_configs:
@@ -1806,7 +1823,7 @@ This checklist serves as a comprehensive framework for validating infrastructure
 - [ ] Business stakeholders informed of changes
 - [ ] Feedback loops established for continuous improvement
 
-## 11. BMAD WORKFLOW INTEGRATION
+## 11. BMad WORKFLOW INTEGRATION
 
 ### 11.1 Development Agent Alignment
 
@@ -2029,7 +2046,7 @@ None Listed
 ==================== START: utils#template-format ====================
 # Template Format Conventions
 
-Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+Templates in the BMad method use standardized markup for AI processing. These conventions ensure consistent document generation.
 
 ## Template Markup Elements
 

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

@@ -0,0 +1,19 @@
+# BMad Method Guide for Claude Code
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Claude Code** as your IDE. This creates:
+
+- `.bmad-core/` folder with all agents
+- `.claude/commands/` folder with agent command files (`.md`)
+
+## Using BMad Agents in Claude Code
+
+Type `/agent-name` in your chat to activate an agent.
+
+## Tips for Claude Code Users
+
+- Commands are auto-suggested as you type `/`
+- More coming soon...

docs/agentic-tools/cline-guide.md

@@ -0,0 +1,16 @@
+# BMad Method Guide for Cline (VS Code)
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Cline** as your IDE. This creates:
+
+- `.clinerules/` directory with numbered agent rule files (`.md`)
+- Agents ordered by priority (bmad-master first)
+
+## Using BMad Agents in Cline
+
+1. **Open Cline panel** in VS Code
+2. **Type `@agent-name`** in the chat (e.g., `@dev`, `@sm`, `@architect`)
+3. The agent adopts that persona for the conversation

docs/agentic-tools/cursor-guide.md

@@ -0,0 +1,14 @@
+# BMad Method Guide for Cursor
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Cursor** as your IDE. This creates:
+
+- `.bmad-core/` folder with all agents
+- `.cursor/rules/` folder with agent rule files (`.mdc`)
+
+## Using BMad Agents in Cursor
+
+Type `@agent-name` in chat (Ctrl+L / Cmd+L) to activate an agent. Make sure you select the icon that looks like a small ruler if presented with multiple options in the popup window.

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

@@ -0,0 +1,32 @@
+# BMad Method Guide for Gemini CLI
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Gemini CLI** as your IDE. This creates:
+
+- `.gemini/agents/` directory with all agent context files
+- `.gemini/settings.json` configured to load all agents automatically
+
+## Using BMad Agents with Gemini CLI
+
+Simply mention the agent in your prompt:
+
+- "As @dev, implement the login feature"
+- "Acting as @architect, review this system design"
+- "@sm, create the next story for our project"
+
+The Gemini CLI automatically loads the appropriate agent context.
+
+## Gemini CLI-Specific Features
+
+- **Context files**: All agents loaded as context in `.gemini/agents/`
+- **Automatic loading**: Settings.json ensures agents are always available
+- **Natural language**: No special syntax needed, just mention the agent
+
+## Tips for Gemini CLI Users
+
+- Be explicit about which agent you're addressing
+- You can switch agents mid-conversation by mentioning a different one
+- The CLI maintains context across your session

docs/agentic-tools/github-copilot-guide.md

@@ -0,0 +1,22 @@
+# BMad Method Guide for Github Copilot
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Github Copilot** as your IDE. This command will perform the following actions:
+
+- Create the `.bmad-core/` directory with all the agent rule files.
+- Create the `.vscode/` directory and add a `settings.json` file if it does not already exist, and add the basic configuration to enable GitHub Copilot's agent mode.
+- Create a chatmodes file under your .github folder for each specific agent being added
+
+## Using BMad Agents in VS Code
+
+1. In the GitHub Copilot Chat window, select **Agent** from the chat mode dropdown list.
+
+## VS Code Specific Features
+
+- **Dynamic Configuration**: When you first invoke an agent (e.g., `@dev`), VS Code will automatically update `.vscode/settings.json` by adding the configuration for that chat mode.
+- **Activation**: Use the `@` prefix in the GitHub Copilot Chat for instant switching between agents.
+- **Collaboration**: Fully compatible with **Live Share**, allowing you, your team, and BMad agents to work together in real-time.
+- **Project Context**: Agents have full access to your workspace, including open files and the selected code.

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

@@ -0,0 +1,15 @@
+# BMad Method Guide for Roo Code
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Roo Code** as your IDE. This creates:
+
+- `.bmad-core/` folder with all agents
+- `.roomodes` file in project root with custom modes
+
+## Roo Code-Specific Features
+
+- **Mode file**: `.roomodes` in project root
+- **Mode switching**: Use mode selecto

docs/agentic-tools/windsurf-guide.md

@@ -0,0 +1,14 @@
+# BMad Method Guide for Windsurf
+
+For the complete workflow, see the [BMad Workflow Guide](../bmad-workflow-guide.md).
+
+## Installation
+
+When running `npx bmad-method install`, select **Windsurf** as your IDE. This creates:
+
+- `.bmad-core/` folder with all agents
+- `.windsurf/rules/` folder with agent rule files (`.md`)
+
+## Using BMad Agents in Windsurf
+
+Type `@agent-name` in chat to activate an agent.

docs/bmad-workflow-guide.md

@@ -1,12 +1,12 @@
-# BMAD Method Universal Workflow Guide
+# BMad Method Universal Workflow Guide
 
-This guide outlines the core BMAD workflow that applies regardless of which AI-powered IDE you're using.
+This guide outlines the core BMad workflow that applies regardless of which AI-powered IDE you're using.
 
 ## Overview
 
-The BMAD Method follows a structured approach to AI-assisted software development:
+The BMad Method follows a structured approach to AI-assisted software development:
 
-1. **Install BMAD** in your project
+1. **Install BMad** in your project
 2. **Plan with Gemini** using team-fullstack
 3. **Organize with bmad-master** (document sharding)
 4. **Develop iteratively** with SM → Dev cycles
@@ -15,14 +15,14 @@ The BMAD Method follows a structured approach to AI-assisted software developmen
 
 ### Phase 1: Project Setup
 
-1. **Install BMAD in your project**:
+1. **Install BMad in your project**:
 
    ```bash
    npx bmad-method install
    ```
 
    - Choose "Complete installation"
-   - Select your IDE (Cursor, Claude Code, Windsurf, or Roo Code)
+   - Select your IDE (Cursor, Claude Code, Windsurf, Roo Code, or Github Copilot)
 
 2. **Verify installation**:
    - `.bmad-core/` folder created with all agents
@@ -35,7 +35,7 @@ Use Google's Gemini for collaborative planning with the full team:
 
 1. **Open [Google Gems](https://gemini.google.com/gems/view)**
 2. **Create a new Gem**:
-   - Give it a title and description (e.g., "BMAD Team Fullstack")
+   - Give it a title and description (e.g., "BMad Team Fullstack")
 3. **Load team-fullstack**:
    - Copy contents of: `dist/teams/team-fullstack.txt` from your project
    - Paste this content into the Gem setup to configure the team
@@ -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`)
+- **Github 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/claude-code-guide.md

@@ -1,121 +0,0 @@
-# BMAD Method Guide for Claude Code
-
-This guide walks you through the complete BMAD workflow using Claude Code as your AI-powered IDE.
-
-## Step 1: Install BMAD in Your Project
-
-1. Navigate to your project directory
-2. Run the BMAD installer:
-
-   ```bash
-   npx bmad-method install
-   ```
-
-3. When prompted:
-   - **Installation Type**: Choose "Complete installation (recommended)"
-   - **IDE**: Select "Claude Code"
-
-This creates a `.bmad-core` folder with all agents and a `.claude/commands` folder with agent commands.
-
-## Step 2: Set Up Team Fullstack in Gemini
-
-For ideation and planning, use Google's Gemini Custom Gem with the team-fullstack configuration:
-
-1. Open [Google gems](https://gemini.google.com/gems/view)
-2. Create a new Gem - give it a title and description
-3. Copy the contents of `.<install location>/<web-bundles>/teams/team-fullstack.txt` (location can vary if you chose a non default installation location for the bundles) - or just use the bundle premade from the repo dist folder.
-4. Paste this content into Gemini to set up the team
-
-### Gemini Planning Phase
-
-In Gemini, ask the BMAD team to help you:
-
-- **Ideate** your project concept
-- **Brainstorm** features and requirements
-- **Create a PRD** (Product Requirements Document)
-- **Design the architecture**
-
-Ask questions like:
-
-- "Help me brainstorm a [type of application] that does [core functionality]"
-- "Create a comprehensive PRD for this concept"
-- "Design the technical architecture for this system"
-
-Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
-
-- `docs/prd.md`
-- `docs/architecture.md`
-
-## Step 3: Back to Claude Code - Document Sharding
-
-Once you have your PRD and architecture documents in the `docs/` folder:
-
-1. **Start a new chat in Claude Code**
-2. **Load the bmad-master agent**: Type `/bmad-master`
-3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
-4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
-
-This creates organized folders:
-
-- `docs/prd/` - Contains broken down PRD sections
-- `docs/architecture/` - Contains broken down architecture sections
-
-## Step 4: Story Development Cycle
-
-Now begin the iterative development cycle:
-
-### Create Stories (Scrum Master)
-
-1. **Start a new chat**
-2. **Load SM agent**: Type `/sm`
-3. **Create story**: Type `*create` (this runs the create-next-story task)
-4. **Review the generated story**
-5. **If approved**: Set story status to "Approved" in the story file
-
-### Implement Stories (Developer)
-
-1. **Start a new chat**
-2. **Load Dev agent**: Type `/dev`
-3. **The agent will ask which story to implement**
-4. **Follow the development tasks** the agent provides
-5. **When story is complete**: Mark status as "Done"
-
-### Repeat the Cycle
-
-1. **Start a new chat with SM agent** (`/sm`)
-2. **Create next story**: Type `*create`
-3. **Review and approve**
-4. **Start new chat with Dev agent** (`/dev`)
-5. **Implement the story**
-6. **Repeat until project complete**
-
-## Available Commands in Claude Code
-
-All BMAD agents are available as Claude Code commands:
-
-- `/bmad-master` - Universal task executor
-- `/sm` - Scrum Master for story creation
-- `/dev` - Full-stack developer for implementation
-- `/architect` - Solution architect for design
-- `/pm` - Product manager for planning
-- `/analyst` - Business analyst for requirements
-- `/qa` - QA specialist for testing
-- `/po` - Product owner for prioritization
-- `/ux-expert` - UX specialist for design
-
-## Key Workflow Principles
-
-1. **Always start new chats** when switching agents to avoid context confusion
-2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
-3. **Use bmad-master for document management** (sharding, templates, etc.)
-4. **Follow the SM → Dev cycle** for consistent story development
-5. **Review and approve stories** before implementation begins
-
-## Tips for Success
-
-- **Keep chats focused**: Each chat should have one agent and one primary task
-- **Use \*help command**: Every agent supports `*help` to see available commands
-- **Review generated content**: Always review and approve stories before marking them ready
-- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
-
-This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

docs/core-architecture.md

@@ -1,24 +1,22 @@
-# BMAD Method: Core Architecture
-
-This document serves as the definitive source of truth for the BMAD-Method's architecture. It is designed to be understood by both human developers and the AI agents that operate within the framework.
+# BMad Method: Core Architecture
 
 ## 1. Overview
 
-The BMAD-Method is an AI-Powered Agile Development Framework designed to transform software development by providing specialized AI agents for every role in a complete Agile team. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex software development tasks in a predictable, high-quality manner.
+The BMad Method is designed to provide agentic modes, tasks and templates to allow repeatable helpful workflows be it for agile agentic development, or expansion into vastly different domains. The core purpose of the project is to provide a structured yet flexible set of prompts, templates, and workflows that users can employ to guide AI agents (like Gemini, Claude, or ChatGPT) to perform complex tasks, guided discussions, or other meaningful domain specific flows in a predictable, high-quality manner.
 
-The system facilitates a full development lifecycle:
+The systems core module facilitates a full development lifecycle tailored to the challenges of current modern AI Agentic tooling:
 
 1. **Ideation & Planning**: Brainstorming, market research, and creating project briefs.
 2. **Architecture & Design**: Defining system architecture and UI/UX specifications.
-3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
+3. **Development Execution**: A cyclical workflow where a Scrum Master (SM) agent drafts stories with extremely specific context and a Developer (Dev) agent implements them one at a time. This process works for both new (Greenfield) and existing (Brownfield) projects.
 
 ## 2. System Architecture Diagram
 
-The entire BMAD-Method ecosystem is designed around the `.bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
+The entire BMad-Method ecosystem is designed around the installed `bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
 
 ```mermaid
 graph TD
-    subgraph BMAD Method Project
+    subgraph BMad Method Project
         subgraph Core Framework
             A["bmad-core"]
             A --> B["agents"]
@@ -63,9 +61,9 @@ graph TD
 
 ## 3. Core Components
 
-The `.bmad-core` directory contains all the definitions and resources that give the agents their capabilities.
+The `bmad-core` directory contains all the definitions and resources that give the agents their capabilities.
 
-### 3.1. Agents (`.bmad-core/agents/`)
+### 3.1. Agents (`bmad-core/agents/`)
 
 - **Purpose**: These are the foundational building blocks of the system. Each markdown file (e.g., `bmad-master.md`, `pm.md`, `dev.md`) defines the persona, capabilities, and dependencies of a single AI agent.
 - **Structure**: An agent file contains a YAML header that specifies its role, persona, dependencies, and startup instructions. These dependencies are lists of tasks, templates, checklists, and data files that the agent is allowed to use.
@@ -73,14 +71,14 @@ The `.bmad-core` directory contains all the definitions and resources that give
 - **Document Integration**: Agents can reference and load documents from the project's `docs/` folder as part of tasks, workflows, or startup sequences. Users can also drag documents directly into chat interfaces to provide additional context.
 - **Example**: The `bmad-master` agent lists its dependencies, which tells the build tool which files to include in a web bundle and informs the agent of its own capabilities.
 
-### 3.2. Agent Teams (`.bmad-core/agent-teams/`)
+### 3.2. Agent Teams (`bmad-core/agent-teams/`)
 
-- **Purpose**: Team files (e.g., `team-all.yml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
+- **Purpose**: Team files (e.g., `team-all.yaml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
 - **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
 
-### 3.3. Workflows (`.bmad-core/workflows/`)
+### 3.3. Workflows (`bmad-core/workflows/`)
 
-- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
+- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yaml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
 - **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
 
 ### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
@@ -93,21 +91,21 @@ The `.bmad-core` directory contains all the definitions and resources that give
 
 #### 3.4.1. Template Processing System
 
-A key architectural principle of BMAD is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
+A key architectural principle of BMad is that templates are self-contained and interactive - they embed both the desired document output and the LLM instructions needed to work with users. This means that in many cases, no separate task is needed for document creation, as the template itself contains all the processing logic.
 
-The BMAD framework employs a sophisticated template processing system orchestrated by three key components:
+The BMad framework employs a sophisticated template processing system orchestrated by three key components:
 
-- **`template-format.md`** (`.bmad-core/utils/`): Defines the foundational markup language used throughout all BMAD templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
+- **`template-format.md`** (`bmad-core/utils/`): Defines the foundational markup language used throughout all BMad templates. This specification establishes syntax rules for variable substitution (`{{placeholders}}`), AI-only processing directives (`[[LLM: instructions]]`), and conditional logic blocks. Templates follow this format to ensure consistent processing across the system.
 
-- **`create-doc.md`** (`.bmad-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
+- **`create-doc.md`** (`bmad-core/tasks/`): Acts as the orchestration engine that manages the entire document generation workflow. This task coordinates template selection, manages user interaction modes (incremental vs. rapid generation), enforces template-format processing rules, and handles validation. It serves as the primary interface between users and the template system.
 
-- **`advanced-elicitation.md`** (`.bmad-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
+- **`advanced-elicitation.md`** (`bmad-core/tasks/`): Provides an interactive refinement layer that can be embedded within templates through `[[LLM: instructions]]` blocks. This component offers 10 structured brainstorming actions, section-by-section review capabilities, and iterative improvement workflows to enhance content quality.
 
 The system maintains a clean separation of concerns: template markup is processed internally by AI agents but never exposed to users, while providing sophisticated AI processing capabilities through embedded intelligence within the templates themselves.
 
 #### 3.4.2. Technical Preferences System
 
-BMAD includes a personalization layer through the `technical-preferences.md` file in `.bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
+BMad includes a personalization layer through the `technical-preferences.md` file in `bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
 
 **Purpose and Benefits:**
 
@@ -144,14 +142,14 @@ The framework is designed for two primary environments: local IDEs and web-based
 
 ### 4.2. Environment-Specific Usage
 
-- **For IDEs**: Users interact with the agents directly via their markdown files in `.bmad-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
+- **For IDEs**: Users interact with the agents directly via their markdown files in `bmad-core/agents/`. The IDE integration (for Cursor, Claude Code, etc.) knows how to call these agents.
 - **For Web UIs**: Users upload a pre-built bundle from `dist`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
 
-## 5. BMAD Workflows
+## 5. BMad Workflows
 
 ### 5.1. The Planning Workflow
 
-Before development begins, BMAD follows a structured planning workflow that establishes the foundation for successful project execution:
+Before development begins, BMad follows a structured planning workflow that establishes the foundation for successful project execution:
 
 ```mermaid
 graph TD
@@ -204,12 +202,18 @@ graph TD
     F -->|Approved| G["Dev: Implement Story"]
     F -->|Needs Changes| E
     G --> H["Dev: Complete story Tasks"]
-    H --> I{"User Verification"}
-    I -->|Verified Complete| J["Mark Story as Done"]
-    I -->|Needs Fixes| G
-    J --> E
+    H --> I["Dev: Mark Ready for Review"]
+    I --> J{"User Verification"}
+    J -->|Request QA Review| K["QA: Run review-story task"]
+    J -->|Approve Without QA| M["Mark Story as Done"]
+    K --> L{"QA Review Results"}
+    L -->|Needs Work| G
+    L -->|Approved| M["Mark Story as Done"]
+    J -->|Needs Fixes| G
+    M --> E
 
-    style J fill:#34a853,color:#fff
+    style M fill:#34a853,color:#fff
+    style K fill:#f9ab00,color:#fff
 ```
 
-This cycle continues, with the Scrum Master and Developer agents working in tandem, until all stories in the epic are completed.
+This cycle continues, with the Scrum Master, Developer, and optionally QA agents working together. The QA agent provides senior developer review capabilities through the `review-story` task, offering code refactoring, quality improvements, and knowledge transfer. This ensures high code quality while maintaining development velocity.

docs/cursor-guide.md

@@ -1,131 +0,0 @@
-# BMAD Method Guide for Cursor
-
-This guide walks you through the complete BMAD workflow using Cursor as your AI-powered IDE.
-
-## Step 1: Install BMAD in Your Project
-
-1. Navigate to your project directory
-2. Run the BMAD installer:
-
-   ```bash
-   npx bmad-method install
-   ```
-
-3. When prompted:
-   - **Installation Type**: Choose "Complete installation (recommended)"
-   - **IDE**: Select "Cursor"
-
-This creates a `.bmad-core` folder with all agents and a `.cursor/rules` folder with agent rules.
-
-## Step 2: Set Up Team Fullstack in Gemini
-
-For ideation and planning, use Google's Gemini Custom Gem with the team-fullstack configuration:
-
-1. Open [Google gems](https://gemini.google.com/gems/view)
-2. Create a new Gem - give it a title and description
-3. Copy the contents of `.<install location>/<web-bundles>/teams/team-fullstack.txt` (location can vary if you chose a non default installation location for the bundles) - or just use the bundle premade from the repo dist folder.
-4. Paste this content into Gemini to set up the team
-
-### Gemini Planning Phase
-
-In Gemini, ask the BMAD team to help you:
-
-- **Ideate** your project concept
-- **Brainstorm** features and requirements
-- **Create a PRD** (Product Requirements Document)
-- **Design the architecture**
-
-Ask questions like:
-
-- "Help me brainstorm a [type of application] that does [core functionality]"
-- "Create a comprehensive PRD for this concept"
-- "Design the technical architecture for this system"
-
-Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
-
-- `docs/prd.md`
-- `docs/architecture.md`
-
-## Step 3: Back to Cursor - Document Sharding
-
-Once you have your PRD and architecture documents in the `docs/` folder:
-
-1. **Start a new chat in Cursor**
-2. **Load the bmad-master agent**: Type `@bmad-master`
-3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
-4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
-
-This creates organized folders:
-
-- `docs/prd/` - Contains broken down PRD sections
-- `docs/architecture/` - Contains broken down architecture sections
-
-## Step 4: Story Development Cycle
-
-Now begin the iterative development cycle:
-
-### Create Stories (Scrum Master)
-
-1. **Start a new chat**
-2. **Load SM agent**: Type `@sm`
-3. **Create story**: Type `*create` (this runs the create-next-story task)
-4. **Review the generated story**
-5. **If approved**: Set story status to "Approved" in the story file
-
-### Implement Stories (Developer)
-
-1. **Start a new chat**
-2. **Load Dev agent**: Type `@dev`
-3. **The agent will ask which story to implement**
-4. **Follow the development tasks** the agent provides
-5. **When story is complete**: Mark status as "Done"
-
-### Repeat the Cycle
-
-1. **Start a new chat with SM agent** (`@sm`)
-2. **Create next story**: Type `*create`
-3. **Review and approve**
-4. **Start new chat with Dev agent** (`@dev`)
-5. **Implement the story**
-6. **Repeat until project complete**
-
-## Available Agent Rules in Cursor
-
-All BMAD agents are available as Cursor rules (use `@` prefix):
-
-- `@bmad-master` - Universal task executor
-- `@sm` - Scrum Master for story creation
-- `@dev` - Full-stack developer for implementation
-- `@architect` - Solution architect for design
-- `@pm` - Product manager for planning
-- `@analyst` - Business analyst for requirements
-- `@qa` - QA specialist for testing
-- `@po` - Product owner for prioritization
-- `@ux-expert` - UX specialist for design
-
-Alternatively, and more performance - you can copy the contents of an agent file into a custom mode - see the cursor docs on how to use custom agents.
-
-## Cursor-Specific Features
-
-- **Agent rules are stored in**: `.cursor/rules/` as `.mdc` files
-- **Auto-completion**: Cursor will suggest `@agent-name` as you type
-- **Rule activation**: Rules activate automatically when you mention `@agent-name`
-- **Context awareness**: Agents have access to your current file context
-
-## Key Workflow Principles
-
-1. **Always start new chats** when switching agents to avoid context confusion
-2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
-3. **Use bmad-master for document management** (sharding, templates, etc.)
-4. **Follow the SM → Dev cycle** for consistent story development
-5. **Review and approve stories** before implementation begins
-
-## Tips for Success
-
-- **Keep chats focused**: Each chat should have one agent and one primary task
-- **Use \*help command**: Every agent supports `*help` to see available commands
-- **Review generated content**: Always review and approve stories before marking them ready
-- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
-- **Leverage Cursor's context**: Agents can see your current file selection for better assistance
-
-This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

docs/expansion-pack-ideas.md

@@ -1,121 +0,0 @@
-# Expansion Pack Ideas
-
-The BMAD Method's natural language framework can be applied to any domain. Here are ideas to inspire your own expansion packs:
-
-## Health & Wellness Pack
-
-### Agents
-
-- **Fitness Coach** - Creates personalized workout plans
-- **Nutrition Advisor** - Designs meal plans and tracks nutrition
-- **Meditation Guide** - Leads mindfulness sessions
-- **Sleep Optimizer** - Improves sleep habits
-
-### Tasks
-
-- `create-workout-plan` - Generates weekly exercise routines
-- `analyze-nutrition` - Reviews dietary habits
-- `design-meditation` - Creates guided meditation scripts
-
-### Templates
-
-- `workout-plan-tmpl` - Structured exercise program
-- `meal-plan-tmpl` - Weekly nutrition guide
-- `wellness-journal-tmpl` - Progress tracking
-
-## Creative Writing Pack
-
-### Agents
-
-- **Story Architect** - Plots narratives and story structures
-- **Character Developer** - Creates deep, complex characters
-- **World Builder** - Designs fictional universes
-- **Dialog Master** - Crafts authentic conversations
-
-### Tasks
-
-- `develop-plot` - Creates story outlines
-- `build-character` - Develops character profiles
-- `create-world` - Designs settings and cultures
-
-### Templates
-
-- `story-outline-tmpl` - Three-act structure
-- `character-sheet-tmpl` - Detailed character profile
-- `world-bible-tmpl` - Universe documentation
-
-## Business Strategy Pack
-
-### Agents
-
-- **Strategy Consultant** - Develops business strategies
-- **Market Analyst** - Researches market opportunities
-- **Financial Advisor** - Creates financial projections
-- **Operations Expert** - Optimizes business processes
-
-### Tasks
-
-- `swot-analysis` - Conducts SWOT analysis
-- `market-research` - Analyzes market conditions
-- `financial-forecast` - Projects revenue/costs
-
-### Templates
-
-- `business-plan-tmpl` - Complete business plan
-- `market-analysis-tmpl` - Market research report
-- `pitch-deck-tmpl` - Investor presentation
-
-## Education Pack
-
-### Agents
-
-- **Curriculum Designer** - Creates learning pathways
-- **Lesson Planner** - Develops engaging lessons
-- **Assessment Creator** - Designs fair evaluations
-- **Learning Coach** - Provides personalized guidance
-
-### Tasks
-
-- `design-curriculum` - Creates course structure
-- `plan-lesson` - Develops lesson content
-- `create-assessment` - Builds tests/quizzes
-
-### Templates
-
-- `course-outline-tmpl` - Semester plan
-- `lesson-plan-tmpl` - Daily lesson structure
-- `rubric-tmpl` - Assessment criteria
-
-## Personal Development Pack
-
-### Agents
-
-- **Life Coach** - Guides personal growth
-- **Goal Strategist** - Helps achieve objectives
-- **Habit Builder** - Creates lasting habits
-- **Mindset Mentor** - Develops positive thinking
-
-### Tasks
-
-- `goal-setting` - Defines SMART goals
-- `habit-tracking` - Monitors habit formation
-- `reflection-exercise` - Facilitates self-reflection
-
-### Templates
-
-- `goal-plan-tmpl` - Goal achievement roadmap
-- `habit-tracker-tmpl` - Daily habit log
-- `journal-prompts-tmpl` - Reflection questions
-
-## Creating Your Own
-
-To create an expansion pack:
-
-1. **Identify the domain** - What area of expertise?
-2. **Define agent roles** - Who are the experts?
-3. **Create tasks** - What procedures do they follow?
-4. **Design templates** - What outputs do they produce?
-5. **Test with users** - Does it provide value?
-6. **Share with community** - Help others benefit!
-
-Remember: The BMAD Method works anywhere natural language instructions can guide AI assistance!

docs/expansion-packs.md

@@ -1,14 +1,14 @@
-# The Power of BMAD Expansion Packs
+# The Power of BMad Expansion Packs
 
 ## Overview
 
-BMAD Method's expansion packs unlock the framework's true potential by extending its natural language AI orchestration to ANY domain. While the core framework focuses on software development, expansion packs transform BMAD into a universal AI agent system.
+BMad Method's expansion packs unlock the framework's true potential by extending its natural language AI orchestration to ANY domain. While the core framework focuses on software development, expansion packs transform BMad into a universal AI agent system.
 
 ## Why Expansion Packs?
 
 ### Keep Core Lean
 
-The core BMAD framework maintains its focus on software development, ensuring dev agents have maximum context for coding. Expansion packs handle everything else.
+The core BMad framework maintains its focus on software development, ensuring dev agents have maximum context for coding. Expansion packs handle everything else.
 
 ### Domain Expertise
 
@@ -132,6 +132,21 @@ Property investment and management:
 - **Flip Strategist**: Renovation ROI, project planning
 - **Agent Assistant**: Listing optimization, showing prep
 
+### Personal Development Pack
+
+Complete personal growth system:
+
+- **Life Coach**: Guides personal growth and transformation
+- **Goal Strategist**: Helps achieve objectives with SMART goals
+- **Habit Builder**: Creates lasting habits with accountability
+- **Mindset Mentor**: Develops positive thinking patterns
+
+Key tasks include:
+
+- `goal-setting`: Defines SMART goals with action plans
+- `habit-tracking`: Monitors habit formation progress
+- `reflection-exercise`: Facilitates deep self-reflection
+
 ## Unique & Innovative Packs
 
 ### Role-Playing Game Master Pack
@@ -260,6 +275,6 @@ Every expansion pack:
 
 ## Remember
 
-The BMAD Method is more than a development framework - it's a platform for structuring human expertise into AI-accessible formats. Every expansion pack you create makes specialized knowledge more accessible to everyone.
+The BMad Method is more than a development framework - it's a platform for structuring human expertise into AI-accessible formats. Every expansion pack you create makes specialized knowledge more accessible to everyone.
 
 **What expertise will you share with the world?**

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

@@ -8,13 +8,21 @@ 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
 
 ### 1. Fork the Repository
 
-1. Go to the [BMAD-METHOD repository](https://github.com/bmadcode/bmad-method)
+1. Go to the [BMad-Method repository](https://github.com/bmadcode/bmad-method)
 2. Click the "Fork" button in the top-right corner
 3. This creates your own copy of the project
 
@@ -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:
-   - **Title**: Clear, descriptive title
-   - **Description**: Explain what you changed and why
+3. Select the correct target branch:
+   - **`next` branch** for most contributions (features, docs, enhancements)
+   - **`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
-- 💬 Ask questions in [Discussions](https://github.com/bmadcode/bmad-method/discussions)
-- 🐛 Report bugs in [Issues](https://github.com/bmadcode/bmad-method/issues)
+- 💬 Join our [Discord Community](https://discord.gg/g6ypHytrCB) for real-time help:
+  - **#general-dev** - Technical questions and feature discussions
+  - **#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

docs/roo-code-guide.md

@@ -1,142 +0,0 @@
-# BMAD Method Guide for Roo Code
-
-This guide walks you through the complete BMAD workflow using Roo Code as your AI-powered IDE.
-
-## Step 1: Install BMAD in Your Project
-
-1. Navigate to your project directory
-2. Run the BMAD installer:
-
-   ```bash
-   npx bmad-method install
-   ```
-
-3. When prompted:
-   - **Installation Type**: Choose "Complete installation (recommended)"
-   - **IDE**: Select "Roo Code"
-
-This creates a `.bmad-core` folder with all agents and a `.roomodes` file (in the project root) with custom modes.
-
-## Step 2: Set Up Team Fullstack in Gemini
-
-For ideation and planning, use Google's Gemini Custom Gem with the team-fullstack configuration:
-
-1. Open [Google gems](https://gemini.google.com/gems/view)
-2. Create a new Gem - give it a title and description
-3. Copy the contents of `.<install location>/<web-bundles>/teams/team-fullstack.txt` (location can vary if you chose a non default installation location for the bundles) - or just use the bundle premade from the repo dist folder.
-4. Paste this content into Gemini to set up the team
-
-### Gemini Planning Phase
-
-In Gemini, ask the BMAD team to help you:
-
-- **Ideate** your project concept
-- **Brainstorm** features and requirements
-- **Create a PRD** (Product Requirements Document)
-- **Design the architecture**
-
-Ask questions like:
-
-- "Help me brainstorm a [type of application] that does [core functionality]"
-- "Create a comprehensive PRD for this concept"
-- "Design the technical architecture for this system"
-
-Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
-
-- `docs/prd.md`
-- `docs/architecture.md`
-
-## Step 3: Back to Roo Code - Document Sharding
-
-Once you have your PRD and architecture documents in the `docs/` folder:
-
-1. **Open your project in Roo Code**
-2. **Select the bmad-master mode** from the mode selector (usually in status bar)
-3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
-4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
-
-This creates organized folders:
-
-- `docs/prd/` - Contains broken down PRD sections
-- `docs/architecture/` - Contains broken down architecture sections
-
-## Step 4: Story Development Cycle
-
-Now begin the iterative development cycle:
-
-### Create Stories (Scrum Master)
-
-1. **Start a new chat or conversation**
-2. **Switch to SM mode**: Select `bmad-sm` from the mode selector
-3. **Create story**: Type `*create` (this runs the create-next-story task)
-4. **Review the generated story**
-5. **If approved**: Set story status to "Approved" in the story file
-
-### Implement Stories (Developer)
-
-1. **Start a new conversation**
-2. **Switch to Dev mode**: Select `bmad-dev` from the mode selector
-3. **The agent will ask which story to implement**
-4. **Follow the development tasks** the agent provides
-5. **When story is complete**: Mark status as "Done"
-
-### Repeat the Cycle
-
-1. **Switch to SM mode** (`bmad-sm`)
-2. **Create next story**: Type `*create`
-3. **Review and approve**
-4. **Switch to Dev mode** (`bmad-dev`)
-5. **Implement the story**
-6. **Repeat until project complete**
-
-## Available Custom Modes in Roo Code
-
-All BMAD agents are available as custom modes:
-
-- `bmad-bmad-master` - 🧙 Universal task executor
-- `bmad-sm` - 🏃 Scrum Master for story creation
-- `bmad-dev` - 💻 Full-stack developer for implementation
-- `bmad-architect` - 🏗️ Solution architect for design
-- `bmad-pm` - 📋 Product manager for planning
-- `bmad-analyst` - 📊 Business analyst for requirements
-- `bmad-qa` - 🧪 QA specialist for testing
-- `bmad-po` - 🎯 Product owner for prioritization
-- `bmad-ux-expert` - 🎨 UX specialist for design
-
-## Roo Code-Specific Features
-
-- **Custom modes are stored in**: `.roomodes` file (in the project root)
-- **Mode switching**: Use the mode selector in Roo Code's interface
-- **File permissions**: Each agent has specific file access permissions
-  - **Documentation agents** (SM, PM, PO, Analyst): Limited to `.md` and `.txt` files
-  - **Technical agents** (Dev, Architect, Master): Full file access
-  - **QA agents**: Access to test files and documentation
-  - **UX agents**: Access to design-related files
-- **Context preservation**: Modes maintain context within conversations
-
-## Key Workflow Principles
-
-1. **Switch modes instead of starting new chats** - Roo Code handles context better with mode switching
-2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
-3. **Use bmad-master mode for document management** (sharding, templates, etc.)
-4. **Follow the SM → Dev mode cycle** for consistent story development
-5. **Review and approve stories** before implementation begins
-
-## Tips for Success
-
-- **Use mode selector effectively**: Switch modes as needed for different tasks
-- **Respect file permissions**: Agents can only edit files they have permission for
-- **Use \*help command**: Every mode supports `*help` to see available commands
-- **Review generated content**: Always review and approve stories before marking them ready
-- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
-- **Leverage Roo's context**: Modes can maintain context across the conversation
-
-## File Permission Summary
-
-- **bmad-analyst, bmad-pm, bmad-po, bmad-sm**: `.md`, `.txt` files only
-- **bmad-architect**: `.md`, `.txt`, `.yml`, `.yaml`, `.json` files
-- **bmad-qa**: Test files (`.test.js`, `.spec.ts`, etc.) and `.md` files
-- **bmad-ux-expert**: `.md`, `.css`, `.scss`, `.html`, `.jsx`, `.tsx` files
-- **bmad-dev, bmad-bmad-master, bmad-orchestrator**: Full file access
-
-This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

docs/user-guide.md

@@ -1,26 +1,23 @@
-# BMAD-METHOD User Guide
+# BMad-Method Agentic Agile Driven Development User Guide
 
-This comprehensive guide will help you understand and effectively use the BMAD-METHOD framework for AI-assisted software development.
+This comprehensive guide will help you understand and effectively use the BMad Method framework for AI-assisted software development along with many expansion purposes.
 
 ## Table of Contents
 
-1. [Understanding BMAD](#understanding-bmad)
+1. [Understanding BMad](#understanding-bmad)
 2. [Getting Started](#getting-started)
 3. [Agent System](#agent-system)
 4. [Templates and Document Creation](#templates-and-document-creation)
 5. [Development Workflow](#development-workflow)
-6. [Team Configurations](#team-configurations)
-7. [IDE Integration](#ide-integration)
-8. [Web UI Usage](#web-ui-usage)
-9. [Advanced Features](#advanced-features)
-10. [Troubleshooting](#troubleshooting)
-11. [Best Practices](#best-practices)
+6. [IDE Integration](#ide-integration)
+7. [Web UI Usage](#web-ui-usage)
+8. [Advanced Features](#advanced-features)
 
-## Understanding BMAD
+## Understanding BMad
 
-### What is BMAD-METHOD?
+### What is BMad-Method?
 
-BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) is an AI agent orchestration framework that provides specialized AI agents for every role in a complete Agile development team. Unlike generic AI assistants, each BMAD agent has deep expertise in their specific domain and can collaborate to deliver complete software projects.
+BMad-Method (Breakthrough Method of Agile AI-Driven Development) is an AI agent orchestration framework that provides specialized AI agents for every role in a complete Agile development team. Unlike generic AI assistants, each BMad agent has deep expertise in their specific domain and can collaborate with you using advanced elicitation techniques, and guided workflows
 
 ### Core Principles
 
@@ -28,9 +25,9 @@ BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) is an AI agent
 2. **True Agile Workflow**: Follows real Agile methodologies with proper story management
 3. **Self-Contained Templates**: Documents embed both output and processing instructions
 4. **Dynamic Dependencies**: Agents only load resources they need
-5. **Platform Agnostic**: Works with any AI platform or IDE
+5. **Platform Agnostic**: Works with any Project Type or Agentic IDE
 
-### When to Use BMAD
+### When to Use BMad
 
 - **New Projects (Greenfield)**: Complete end-to-end development
 - **Existing Projects (Brownfield)**: Feature additions and enhancements
@@ -44,7 +41,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) is an AI agent
 
 #### Option 1: Web UI (Fastest - 2 minutes)
 
-Best for: ChatGPT, Claude, Gemini users
+If you want to do the planning int he Web:
 
 1. Navigate to `dist/teams/`
 2. Copy `team-fullstack.txt` content
@@ -54,34 +51,38 @@ Best for: ChatGPT, Claude, Gemini users
 
 #### Option 2: IDE Integration (5 minutes)
 
-Best for: Cursor, Claude Code, Windsurf, VS Code users
-
 ```bash
 # Interactive installation (recommended)
 npx bmad-method install
 ```
 
-### First Steps
+### CLI Commands
 
-1. **Choose Your Environment**: Web UI or IDE
-2. **Select Agent/Team**: Individual agent or full team
-3. **Initialize Project**: Run `/help` or `*help` to see capabilities
-4. **Start Development**: Begin with planning or jump into coding
+```bash
+# List all available agents
+npx bmad-method list
+
+# Install or update (automatically detects existing installations)
+npx bmad-method install
+
+# Check installation status
+npx bmad-method status
+```
 
 ## Agent System
 
 ### Core Development Team
 
-| Agent       | Role               | Primary Functions                       | When to Use                            |
-| ----------- | ------------------ | --------------------------------------- | -------------------------------------- |
-| `analyst`   | Business Analyst   | Market research, requirements gathering | Project planning, competitive analysis |
-| `pm`        | Product Manager    | PRD creation, feature prioritization    | Strategic planning, roadmaps           |
-| `architect` | Solution Architect | System design, technical architecture   | Complex systems, scalability planning  |
-| `dev`       | Developer          | Code implementation, debugging          | All development tasks                  |
-| `qa`        | QA Specialist      | Test planning, quality assurance        | Testing strategies, bug validation     |
-| `ux-expert` | UX Designer        | UI/UX design, prototypes                | User experience, interface design      |
-| `po`        | Product Owner      | Backlog management, story validation    | Story refinement, acceptance criteria  |
-| `sm`        | Scrum Master       | Sprint planning, story creation         | Project management, workflow           |
+| Agent       | Role               | Primary Functions                              | When to Use                                       |
+| ----------- | ------------------ | ---------------------------------------------- | ------------------------------------------------- |
+| `analyst`   | Business Analyst   | Market research, requirements gathering        | Project planning, competitive analysis            |
+| `pm`        | Product Manager    | PRD creation, feature prioritization           | Strategic planning, roadmaps                      |
+| `architect` | Solution Architect | System design, technical architecture          | Complex systems, scalability planning             |
+| `dev`       | Developer          | Sequential task execution, testing, validation | Story implementation with test-driven development |
+| `qa`        | QA Specialist      | Code review, refactoring, test validation      | Senior developer review via `review-story` task   |
+| `ux-expert` | UX Designer        | UI/UX design, prototypes                       | User experience, interface design                 |
+| `po`        | Product Owner      | Backlog management, story validation           | Story refinement, acceptance criteria             |
+| `sm`        | Scrum Master       | Sprint planning, story creation                | Project management, workflow                      |
 
 ### Meta Agents
 
@@ -141,7 +142,7 @@ dependencies:
 
 ### Understanding Templates
 
-BMAD templates are **self-contained and interactive** - they embed both the desired document output and the LLM instructions needed to work with users. This means no separate task is needed for most document creation.
+BMad templates are **self-contained and interactive** - they embed both the desired document output and the LLM instructions needed to work with users. This means no separate task is needed for most document creation.
 
 #### Template Structure
 
@@ -193,8 +194,8 @@ Templates follow the `template-format.md` specification:
 For cost efficiency, especially with Gemini:
 
 1. **Create Large Documents in Web UI**: Use web bundles for PRD and architecture creation
-2. **Copy to Project**: Save the final markdown output to your project's `docs/` folder
-3. **Standard Naming**: Use `prd.md` and `architecture.md` for consistency
+2. **Copy to Project**: Save the final markdown output to your project's `docs/` folder (use the ... menu)
+3. **Standard Naming**: Use `prd.md` and `architecture.md` for consistent file name
 4. **Continue in IDE**: Use IDE agents for development tasks and smaller documents
 
 #### File Naming Conventions
@@ -243,7 +244,7 @@ This provides 10 structured brainstorming actions:
 
 ### The Planning Workflow (Web UI)
 
-Before development begins, BMAD follows a structured planning workflow that's ideally done in web UI for cost efficiency:
+Before development begins, BMad follows a structured planning workflow that's ideally done in web UI for cost efficiency:
 
 ```mermaid
 graph TD
@@ -280,24 +281,33 @@ graph TD
 
 ### The Core Development Cycle (IDE)
 
-Once planning is complete and documents are sharded, BMAD follows a structured development workflow:
+Once planning is complete and documents are sharded, BMad follows a structured development workflow:
 
 ```mermaid
 graph TD
-    A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
-    B --> C["PO: Shard Arch"]
-    C --> D["Development Phase"]
-    D --> E["Scrum Master: Drafts next story from sharded epic"]
-    E --> F{"User Approval"}
-    F -->|Approved| G["Dev: Implement Story"]
-    F -->|Needs Changes| E
-    G --> H["Dev: Complete story Tasks"]
-    H --> I{"User Verification"}
-    I -->|Verified Complete| J["Mark Story as Done"]
-    I -->|Needs Fixes| G
-    J --> E
+    A["Development Phase Start"] --> B["SM: Reviews Previous Story Dev/QA Notes"]
+    B --> B2["SM: Drafts Next Story from Sharded Epic + Architecture"]
+    B2 --> C{"User Approval"}
+    C -->|Approved| D["Dev: Sequential Task Execution"]
+    C -->|Needs Changes| B2
+    D --> E["Dev: Implement Tasks + Tests"]
+    E --> F["Dev: Run All Validations"]
+    F --> G["Dev: Mark Ready for Review + Add Notes"]
+    G --> H{"User Verification"}
+    H -->|Request QA Review| I["QA: Senior Dev Review + Active Refactoring"]
+    H -->|Approve Without QA| K["Mark Story as Done"]
+    I --> J["QA: Review, Refactor Code, Add Tests, Document Notes"]
+    J --> L{"QA Decision"}
+    L -->|Needs Dev Work| D
+    L -->|Approved| K
+    H -->|Needs Fixes| D
+    K --> B
 
-    style J fill:#34a853,color:#fff
+    style K fill:#34a853,color:#fff
+    style I fill:#f9ab00,color:#fff
+    style J fill:#ffd54f,color:#000
+    style E fill:#e3f2fd,color:#000
+    style B fill:#e8f5e9,color:#000
 ```
 
 ### Workflow Phases
@@ -319,15 +329,142 @@ graph TD
 
 - **SM**: Draft next story from sharded epic
 - **User**: Review and approve story
-- **Dev**: Implement all story tasks
+- **Dev**: Sequential task execution:
+  - Reads each task in the story
+  - Implements code for the task
+  - Writes tests alongside implementation
+  - Runs validations (linting, tests)
+  - Updates task checkbox [x] only if all validations pass
+  - Maintains Debug Log for temporary changes
+  - Updates File List with all created/modified files
+- **Dev**: After all tasks complete:
+  - Runs integration tests (if specified)
+  - Runs E2E tests (if specified)
+  - Validates Definition of Done checklist
+  - Marks story as "Ready for Review"
 - **User**: Verify implementation
+- **Optional QA Review**: User can request QA to run `review-story` task
 - **Repeat**: Until all stories complete
 
-#### 4. Quality Assurance
+#### Dev Agent Workflow Details
 
-- **QA**: Test planning and execution
-- **Dev**: Bug fixes and refinements
-- **PO**: Acceptance criteria validation
+The Dev agent follows a strict test-driven sequential workflow:
+
+**Key Behaviors:**
+
+- **Story-Centric**: Works only from the story file, never loads PRD/architecture unless specified in dev notes
+- **Sequential Execution**: Completes tasks one by one, marking [x] only after validations pass
+- **Test-Driven**: Writes tests alongside code for every task
+- **Quality Gates**: Never marks tasks complete if validations fail
+- **Debug Logging**: Tracks temporary changes in the story's Debug Log table
+- **File Tracking**: Maintains complete File List of all created/modified files
+
+**Blocking Conditions:**
+The Dev agent will stop and request help if:
+
+- Story is not approved
+- Requirements are ambiguous after checking the story
+- Validations fail 3 times for the same task
+- Critical configuration files are missing
+- Automated tests or linting fails
+
+#### 4. Quality Assurance Integration
+
+The QA agent plays a crucial role after development:
+
+- **When Dev marks "Ready for Review"**: Story is ready for user verification
+- **User Options**:
+  - **Direct Approval**: If satisfied, mark story as "Done"
+  - **Request Changes**: Send back to Dev with specific feedback
+  - **Request QA Review**: Ask QA to run the `review-story` task for senior developer review
+- **QA Review Process** (`/qa run review-story`):
+
+  - Reviews code as a senior developer with authority to refactor
+  - **Active Refactoring**: Makes improvements directly in the code
+  - **Comprehensive Review Focus**:
+    - Code architecture and design patterns
+    - Refactoring opportunities and code duplication
+    - Performance optimizations and security concerns
+    - Best practices and patterns
+  - **Standards Compliance**: Verifies adherence to:
+    - `docs/coding-standards.md`
+    - `docs/unified-project-structure.md`
+    - `docs/testing-strategy.md`
+  - **Test Coverage Review**: Can add missing tests if critical coverage is lacking
+  - **Documentation**: Adds comments for complex logic if missing
+  - **Results Documentation** in story's QA Results section:
+    - Code quality assessment
+    - Refactoring performed with WHY and HOW explanations
+    - Compliance check results
+    - Improvements checklist (completed vs. pending items)
+    - Security and performance findings
+    - Final approval status
+
+### Understanding the SM/Dev/QA Story Workflow
+
+The story file is the central artifact that enables seamless collaboration between the Scrum Master (SM), Developer (Dev), and Quality Assurance (QA) agents. Here's how they work together:
+
+#### Why We Have the Scrum Master
+
+The SM agent serves as a critical bridge between high-level planning and technical implementation:
+
+1. **Document Synthesis**: Reads sharded PRD epics and architecture documents to extract relevant technical details
+2. **Story Enrichment**: Creates self-contained stories with all technical context needed for implementation
+3. **Continuous Learning**: Uses notes from previous stories to improve future story preparation
+4. **Developer Efficiency**: Ensures developers have everything needed without searching multiple documents
+
+#### The Story Creation Process
+
+When the SM agent executes the `create-next-story` task:
+
+1. **Loads Configuration**: Reads `core-config.yaml` to understand project structure
+2. **Identifies Next Story**: Sequentially processes stories from epics (1.1, 1.2, 2.1, etc.)
+3. **Gathers Architecture Context**: Reads relevant sharded architecture documents based on story type:
+
+   - Backend stories: data models, API specs, database schemas
+   - Frontend stories: component specs, UI patterns, workflows
+   - Full-stack: both backend and frontend documents
+
+4. **Reviews Previous Story**: Extracts Dev and QA notes to learn from past implementation
+
+#### The Story Template Structure
+
+The story template contains embedded LLM instructions for the SM Dev and QA Agent.
+
+#### How Agents Pass Information
+
+##### SM → Dev Flow
+
+The SM prepares the story with:
+
+- **Dev Notes**: Specific technical guidance extracted from architecture
+- **Testing Requirements**: Unit, integration, and E2E test specifications
+- **Tasks/Subtasks**: Detailed implementation steps with AC mappings
+
+##### Dev → SM Flow
+
+The Dev agent provides feedback through:
+
+- **Completion Notes**: Deviations or discoveries that impact future stories
+- **Debug Log References**: Technical challenges and solutions
+- **File List**: Complete inventory of created/modified files
+- **Change Log**: Any requirement modifications during development
+
+##### QA → SM Flow
+
+The QA agent contributes:
+
+- **Code Quality Assessment**: Senior developer perspective on implementation quality
+- **Refactoring Performed**: Direct code improvements with:
+  - What was changed
+  - Why the change was made
+  - How it improves the code
+- **Compliance Results**: Verification against coding standards, project structure, and testing strategy
+- **Test Coverage**: Added tests for critical missing coverage
+- **Security Review**: Any security concerns found and whether addressed
+- **Performance Considerations**: Performance issues found and optimizations made
+- **Improvements Checklist**: Items completed (marked [x]) vs. items for Dev to address (marked [ ])
+- **Learning Opportunities**: Explanations for junior/mid-level developer growth
 
 ### Workflow Types
 
@@ -351,85 +488,11 @@ For existing projects:
 4. Incremental development
 5. Integration testing
 
-## Team Configurations
-
-### Pre-Built Teams
-
-#### Team All
-
-- **Includes**: All 10 agents + orchestrator
-- **Use Case**: Complete projects requiring all roles
-- **Bundle**: `team-all.txt`
-
-#### Team Fullstack
-
-- **Includes**: PM, Architect, Developer, QA, UX Expert
-- **Use Case**: End-to-end web/mobile development
-- **Bundle**: `team-fullstack.txt`
-
-#### Team No-UI
-
-- **Includes**: PM, Architect, Developer, QA (no UX Expert)
-- **Use Case**: Backend services, APIs, system development
-- **Bundle**: `team-no-ui.txt`
-
-### Custom Team Configuration
-
-Create custom teams by modifying `.bmad-core/agent-teams/`:
-
-```yaml
-name: Custom Development Team
-description: Specialized team for specific needs
-agents:
-  - pm
-  - architect
-  - dev
-  - qa
-workflows:
-  - greenfield-fullstack
-```
-
 ## IDE Integration
 
-### Supported IDEs
-
-#### Cursor IDE
-
-- **Commands**: `@agent-name task` (manual rules)
-- **Example**: `@pm Create a PRD for user management`
-- **Features**: Inline suggestions, context awareness
-- **Integration**: Agents loaded as manual rules
-
-#### Claude Code
-
-- **Commands**: `/agent-name task` (command files)
-- **Example**: `/architect Design microservices architecture`
-- **Features**: File integration, project context
-- **Integration**: Agents installed as files in commands folder
-
-#### Windsurf
-
-- **Commands**: `@agent-name task` (manual rules)
-- **Example**: `@dev Implement authentication`
-- **Features**: Multi-file editing, project awareness
-- **Integration**: Agents loaded as manual rules
-
-#### VS Code (Generic)
-
-- **Setup**: Manual installation
-- **Usage**: Copy agent content to chat
-- **Features**: Basic integration
-
-### IDE Setup Process
-
-1. **Install CLI**: `npx bmad-method install`
-2. **Select IDE**: Choose during installation
-3. **Configure Integration**: Automatic setup for supported IDEs
-4. **Verify Installation**: Test with `@agent-name help`
-
 ### IDE Best Practices
 
-- **Context Management**: Keep relevant files open
+- **Context Management**: Keep relevant files only in context, keep files as lean and focused as necessary
 - **Agent Selection**: Use appropriate agent for task
 - **Iterative Development**: Work in small, focused tasks
 - **File Organization**: Maintain clean project structure
@@ -438,97 +501,19 @@ workflows:
 
 **Important**: Web UI is primarily designed for planning and documentation phases, not development. Use IDE integration for coding tasks.
 
-### Platform Setup
-
-#### ChatGPT Custom GPT
-
-1. Create new Custom GPT
-2. Upload team bundle as knowledge
-3. Set instructions: "Your critical operating instructions are attached, do not break character as directed"
-4. Configure capabilities as needed
-
-#### Claude Projects
-
-1. Create new project
-2. Add team bundle to project knowledge
-3. Set project instructions with agent behavior
-4. Start conversation with `/help`
-
-#### Gemini Gems
-
-1. Create new Gem
-2. Upload bundle as instruction file
-3. Set system instructions for agent behavior
-4. Initialize with `/help` command
-
 ### Web UI Commands
 
-#### Universal Commands
-
-- `/help` - Show available commands
-- `/status` - Current agent status
-- `/switch agent-name` - Change active agent (if orchestrator available)
-
-#### Document Commands
-
-- `/create-doc type` - Create document of specified type
-- `/review-doc` - Review current document
-- `/refine-doc` - Improve document quality
-
-#### Planning Commands
-
-- `/pm create-doc prd` - Create Product Requirements Document
-- `/architect create-doc architecture` - Create system architecture
-- `/analyst create-doc project-brief` - Create project brief
-- `/po run-checklist` - Validate document alignment
+type #help when in the Gem or Custom GPT with one of the teams, and the BMad-Orchestrator will give you an up to date list of commands.
 
 ### Web UI Agent Interaction
 
 Web UI agents focus on planning and documentation. Here's how to interact with each:
 
-#### Agent Switching and Conversation
-
-- **Switch Agents**: Use `/pm`, `/architect`, `/analyst`, `/po` to switch between roles
-- **Agent Consultation**: Each agent offers their specialized options and capabilities
-- **Natural Conversation**: Agents guide you through their processes with questions and suggestions
-
-#### Planning Phase Agents
-
-- **Analyst**: `/analyst` - Brainstorming, market research, competitive analysis
-- **PM**: `/pm` - Product requirements, feature definition, roadmaps
-- **Architect**: `/architect` - System design, technical architecture
-- **PO**: `/po` - Document validation, epic management, story alignment
-
-### Web UI Best Practices
-
-- **Clear Instructions**: Be specific about requirements
-- **Context Sharing**: Provide relevant background
-- **Iterative Refinement**: Use built-in elicitation features
-- **Document Management**: Keep generated docs organized
-- **Stay in Planning**: Use web UI for documentation, switch to IDE for development
-
-#### Cost-Effective Document Creation
-
-**Recommended Workflow for Large Documents:**
-
-1. **Use Web UI for PRD and Architecture**: These are token-heavy documents, especially in Gemini
-2. **Copy Final Output**: Save complete markdown to your project
-3. **Standard File Names**:
-   - Save PRD as `docs/prd.md`
-   - Save Architecture as `docs/architecture.md`
-4. **IDE for Development**: Switch to IDE agents for implementation tasks
-
-**Why This Saves Money:**
-
-- Web UI pricing is typically more cost-effective for large context windows
-- PRD and architecture creation involves extensive back-and-forth refinement
-- IDE token costs can accumulate quickly with large document generation
-
 ## Advanced Features
 
 ### Dynamic Resource Loading
 
-BMAD's dependency system ensures agents only load necessary resources:
+BMad's dependency system ensures agents only load necessary resources:
 
 - **Templates**: Only relevant document templates
 - **Tasks**: Only required automation tasks
@@ -537,7 +522,7 @@ BMAD's dependency system ensures agents only load necessary resources:
 
 ### Custom Templates
 
-Create custom templates following `template-format.md`:
+Create custom templates following `utils/template-format.md`:
 
 ```markdown
 ---
@@ -595,7 +580,7 @@ phases:
 
 Templates are self-contained documents that embed both output structure and processing instructions. Follow these patterns from existing templates:
 
-#### Template Structure
+#### Template Structure Example
 
 ```markdown
 # {{Project Name}} Document Title
@@ -792,7 +777,7 @@ Agents can reference and load documents from the `docs/` folder:
 
 ### Technical Preferences System
 
-BMAD includes a powerful personalization system through the `technical-preferences.md` file located in `.bmad-core/data/`.
+BMad includes a powerful personalization system through the `technical-preferences.md` file located in `.bmad-core/data/`.
 
 #### What is technical-preferences.md?
 
@@ -884,13 +869,13 @@ This file allows you to define your preferred technologies, patterns, and standa
 
 When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation.
 
-### Core Configuration (core-config.yml)
+### Core Configuration
 
-The `bmad-core/core-config.yml` file is a critical V4 innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+The `bmad-core/core-config.yaml` file is a critical V4 innovation that enables BMad to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
 
-#### Understanding core-config.yml
+#### Understanding core-config.yaml
 
-This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It's what makes V4 agents intelligent enough to work with V3 projects, custom layouts, or any document organization you prefer.
+This configuration file acts as a map for BMad agents, telling them exactly where to find your project documents and how they're structured. It's what makes V4 agents intelligent enough to work with V3 projects, custom layouts, or any document organization you prefer.
 
 #### Configuration Structure
 
@@ -1100,10 +1085,10 @@ customTechnicalDocuments:
 
 #### Best Practices
 
-1. **Always Configure for Your Structure**: Don't force your project to match BMAD defaults
+1. **Always Configure for Your Structure**: Don't force your project to match BMad defaults
 2. **Keep devLoadAlwaysFiles Focused**: Only include files needed for every dev task
 3. **Use Debug Log**: Enable when troubleshooting story implementation issues
-4. **Version Control core-config.yml**: Track changes to understand project evolution
+4. **Version Control core-config.yaml**: Track changes to understand project evolution
 5. **Document Custom Patterns**: If using custom epicFilePattern, document it
 
 #### Troubleshooting
@@ -1135,137 +1120,18 @@ Add specialized capabilities:
 - **Data Pack**: Analytics, ML integration
 - **Security Pack**: Security analysis, compliance
 
-## Troubleshooting
+## Troubleshooting Guide
 
-### Common Issues
+## Getting Help
 
-#### Agent Not Responding
-
-- **Cause**: Incorrect agent name or command
-- **Solution**: Check available agents with `/help`
-- **Prevention**: Use tab completion in supported IDEs
-
-#### Template Errors
-
-- **Cause**: Malformed template syntax
-- **Solution**: Validate against `template-format.md`
-- **Prevention**: Use provided templates as starting point
-
-#### Context Overload
-
-- **Cause**: Too many dependencies loaded
-- **Solution**: Use specific agents instead of `bmad-master`
-- **Prevention**: Choose appropriate team size
-
-#### Installation Issues
-
-- **Cause**: Node.js version, permissions
-- **Solution**: Update Node.js, check permissions
-- **Prevention**: Use recommended Node.js version (14+)
-
-### Debugging Steps
-
-1. **Check Installation**: `npx bmad-method status`
-2. **Verify Agent**: Test with simple command
-3. **Review Dependencies**: Ensure required files exist
-4. **Clear Cache**: Restart IDE/browser
-5. **Reinstall**: `npx bmad-method install --force`
-
-### Getting Help
-
-- **Discord Community**: [Join Discord](https://discord.gg/g6ypHytrCB)
+- **Discord Community**: [Join Discord](https://discord.gg/gk8jAdXWmj)
 - **GitHub Issues**: [Report bugs](https://github.com/bmadcode/bmad-method/issues)
 - **Documentation**: [Browse docs](https://github.com/bmadcode/bmad-method/tree/main/docs)
 - **YouTube**: [BMadCode Channel](https://www.youtube.com/@BMadCode)
 
-## Best Practices
-
-### Project Organization
-
-#### Folder Structure
-
-```text
-project/
-├── .bmad-core/          # BMAD agents and resources
-├── docs/                # Generated documentation
-│   ├── prd.md
-│   ├── architecture.md
-│   └── stories/
-├── src/                 # Source code
-└── tests/               # Test files
-```
-
-#### Document Management
-
-- Keep generated docs in `docs/` folder
-- Version control all BMAD-generated content
-- Regular backups of `.bmad-core/` customizations
-
-### Development Workflow
-
-#### Planning Phase
-
-1. **Start with Analysis**: Use analyst for market research
-2. **Create PRD**: PM agent for comprehensive requirements
-3. **Design Architecture**: Architect for technical foundation
-4. **Plan UX**: UX Expert for user experience
-
-#### Development Phase
-
-1. **Shard Work**: PO to break down epics
-2. **Story Development**: SM for manageable tasks
-3. **Implementation**: Dev for coding
-4. **Quality Assurance**: QA for testing
-
-#### Review Process
-
-1. **Code Review**: Dev agent for code quality
-2. **Functional Testing**: QA for feature validation
-3. **User Acceptance**: PO for business requirements
-4. **Documentation**: Update docs as needed
-
-### Quality Assurance
-
-#### Code Quality
-
-- Use dev agent for code reviews
-- Implement suggested improvements
-- Follow established coding standards
-- Regular refactoring sessions
-
-#### Documentation Standards
-
-- Keep docs updated with changes
-- Use templates for consistency
-- Regular doc reviews with PO
-- Clear, actionable user stories
-
-#### Process Quality
-
-- Follow Agile ceremonies
-- Regular retrospectives
-- Continuous improvement
-- Stakeholder feedback integration
-
-### Performance Optimization
-
-#### Context Management
-
-- Use specific agents vs. bmad-master
-- Minimal team configurations
-- Regular dependency cleanup
-- Archive completed projects
-
-#### Resource Efficiency
-
-- Appropriate bundle sizes
-- Selective agent usage
-- Efficient template design
-- Regular cache clearing
-
 ## Conclusion
 
-BMAD-METHOD provides a comprehensive framework for AI-assisted software development. By following this guide, you'll be able to:
+BMad-Method provides a comprehensive framework for AI-assisted software development. By following this guide, you'll be able to:
 
 - Effectively use specialized AI agents
 - Create professional documentation
@@ -1273,8 +1139,4 @@ BMAD-METHOD provides a comprehensive framework for AI-assisted software developm
 - Integrate with your preferred tools
 - Maintain high quality standards
 
-Remember: BMAD is designed to enhance your development process, not replace your expertise. Use it as a powerful tool to accelerate your projects while maintaining control over design decisions and implementation details.
-
----
-
-For additional support, join our [Discord community](https://discord.gg/g6ypHytrCB) or check out the [YouTube channel](https://www.youtube.com/@BMadCode) for video tutorials and walkthroughs.
+Remember: BMad is designed to enhance your development process, not replace your expertise. Use it as a powerful tool to accelerate your projects while maintaining control over design decisions and implementation details.

docs/versioning-and-releases.md

@@ -2,7 +2,7 @@
 
 ## Automated Releases (Recommended)
 
-The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push - everything else happens automatically!
+The easiest way to release new versions is through **automatic semantic releases**. Just commit with the right message format and push and everything else happens automatically.
 
 ### Commit Message Format
 
@@ -58,7 +58,7 @@ npm run release:test    # Safe to run locally - tests the config
 
 ## Manual Release Methods (Exceptions Only)
 
-**⚠️ Only use these methods if you need to bypass the automatic system**
+⚠️ Only use these methods if you need to bypass the automatic system
 
 ### Quick Manual Version Bump
 
@@ -75,11 +75,3 @@ git push && git push --tags
 ### Manual GitHub Actions Trigger
 
 You can also trigger releases manually through GitHub Actions workflow dispatch if needed.
-
----
-
-## Summary
-
-**For 99% of releases**: Just use `fix:` or `feat:` commit messages and push. Everything else is automatic!
-
-**Manual methods**: Only needed for special cases or if you want to bypass the automated system.

docs/versions.md

@@ -2,9 +2,9 @@
 
 ## Previous Versions
 
-- [Version 3](https://github.com/bmadcode/BMAD-METHOD/tree/V3)
-- [Version 2](https://github.com/bmadcode/BMAD-METHOD/tree/V2)
-- [Version 1](https://github.com/bmadcode/BMAD-METHOD/tree/V1)
+- [Version 3](https://github.com/bmadcode/BMad-Method/tree/V3)
+- [Version 2](https://github.com/bmadcode/BMad-Method/tree/V2)
+- [Version 1](https://github.com/bmadcode/BMad-Method/tree/V1)
 
 ## Current Version: V4 - Alpha
 
@@ -16,7 +16,6 @@ Guiding Principles of V4:
 - Helpers for installers and web builders that will work with any OS and IDE easily
 - Align all agents to be the same for IDE and Web, without losing the power of the web versions, or the leanness of the files in the IDE to reduce context
 - Further improvements to the two most important agents - the SM and DEV
-- Expansion Packs - Coming soon...
 
 ## V3
 
@@ -26,7 +25,7 @@ V3 didn't fix the disconnect, but it did make it easier to maintain them all in
 
 V3's biggest impact was a full explosion of customizability. Tasks, Personas, Agent Configurations, Doc Templates, data payloads.
 
-BUT - the BIGGEST change was the realization that we were barely scratching the surface of what could be loaded into Gemini Gems and still have very long chats. The BMAD AGENT arose, and with a single V3 release - the future of the BMad Method was changed forever.
+BUT - the BIGGEST change was the realization that we were barely scratching the surface of what could be loaded into Gemini Gems and still have very long chats. The BMad AGENT arose, and with a single V3 release - the future of the BMad Method was changed forever.
 
 Now, instead of configuring 4+ web agents, all needing many files uploaded to create them, a single Agent called BMad, with a whole team, and the ability to switch and maintain personas evolved. Now you could in the same chat thread, talk to the whole team, or anyone on the team. No more exporting and reimporting docs to different chats - all of the sudden, you could finish the PRD, and ask Josh to pass it off to the Architect, and that was it, the architect just had it and we moved on! And all of that with just 7 total files to upload, delivering all power.
 

docs/windsurf-guide.md

@@ -1,129 +0,0 @@
-# BMAD Method Guide for Windsurf
-
-This guide walks you through the complete BMAD workflow using Windsurf as your AI-powered IDE.
-
-## Step 1: Install BMAD in Your Project
-
-1. Navigate to your project directory
-2. Run the BMAD installer:
-
-   ```bash
-   npx bmad-method install
-   ```
-
-3. When prompted:
-   - **Installation Type**: Choose "Complete installation (recommended)"
-   - **IDE**: Select "Windsurf"
-
-This creates a `.bmad-core` folder with all agents and a `.windsurf/rules` folder with agent rules.
-
-## Step 2: Set Up Team Fullstack in Gemini
-
-For ideation and planning, use Google's Gemini Custom Gem with the team-fullstack configuration:
-
-1. Open [Google gems](https://gemini.google.com/gems/view)
-2. Create a new Gem - give it a title and description
-3. Copy the contents of `.<install location>/<web-bundles>/teams/team-fullstack.txt` (location can vary if you chose a non default installation location for the bundles) - or just use the bundle premade from the repo dist folder.
-4. Paste this content into Gemini to set up the team
-
-### Gemini Planning Phase
-
-In Gemini, ask the BMAD team to help you:
-
-- **Ideate** your project concept
-- **Brainstorm** features and requirements
-- **Create a PRD** (Product Requirements Document)
-- **Design the architecture**
-
-Ask questions like:
-
-- "Help me brainstorm a [type of application] that does [core functionality]"
-- "Create a comprehensive PRD for this concept"
-- "Design the technical architecture for this system"
-
-Copy the PRD and architecture documents that Gemini creates into your project's `docs/` folder:
-
-- `docs/prd.md`
-- `docs/architecture.md`
-
-## Step 3: Back to Windsurf - Document Sharding
-
-Once you have your PRD and architecture documents in the `docs/` folder:
-
-1. **Start a new chat in Windsurf**
-2. **Load the bmad-master agent**: Type `@bmad-master`
-3. **Shard the PRD**: Type `*shard-doc docs/prd.md prd`
-4. **Shard the architecture**: Type `*shard-doc docs/architecture.md architecture`
-
-This creates organized folders:
-
-- `docs/prd/` - Contains broken down PRD sections
-- `docs/architecture/` - Contains broken down architecture sections
-
-## Step 4: Story Development Cycle
-
-Now begin the iterative development cycle:
-
-### Create Stories (Scrum Master)
-
-1. **Start a new chat**
-2. **Load SM agent**: Type `@sm`
-3. **Create story**: Type `*create` (this runs the create-next-story task)
-4. **Review the generated story**
-5. **If approved**: Set story status to "Approved" in the story file
-
-### Implement Stories (Developer)
-
-1. **Start a new chat**
-2. **Load Dev agent**: Type `@dev`
-3. **The agent will ask which story to implement**
-4. **Follow the development tasks** the agent provides
-5. **When story is complete**: Mark status as "Done"
-
-### Repeat the Cycle
-
-1. **Start a new chat with SM agent** (`@sm`)
-2. **Create next story**: Type `*create`
-3. **Review and approve**
-4. **Start new chat with Dev agent** (`@dev`)
-5. **Implement the story**
-6. **Repeat until project complete**
-
-## Available Agent Rules in Windsurf
-
-All BMAD agents are available as Windsurf rules (use `@` prefix):
-
-- `@bmad-master` - Universal task executor
-- `@sm` - Scrum Master for story creation
-- `@dev` - Full-stack developer for implementation
-- `@architect` - Solution architect for design
-- `@pm` - Product manager for planning
-- `@analyst` - Business analyst for requirements
-- `@qa` - QA specialist for testing
-- `@po` - Product owner for prioritization
-- `@ux-expert` - UX specialist for design
-
-## Windsurf-Specific Features
-
-- **Agent rules are stored in**: `.windsurf/rules/` as `.md` files
-- **Rule activation**: Rules activate when you mention `@agent-name` in chat
-- **Collaborative workflow**: Windsurf's collaborative features work well with BMAD's agent-switching pattern
-- **Context awareness**: Agents have access to your project context
-
-## Key Workflow Principles
-
-1. **Always start new chats** when switching agents to avoid context confusion
-2. **Use Gemini for initial planning** and ideation with the team-fullstack bundle
-3. **Use bmad-master for document management** (sharding, templates, etc.)
-4. **Follow the SM → Dev cycle** for consistent story development
-5. **Review and approve stories** before implementation begins
-
-## Tips for Success
-
-- **Keep chats focused**: Each chat should have one agent and one primary task
-- **Use \*help command**: Every agent supports `*help` to see available commands
-- **Review generated content**: Always review and approve stories before marking them ready
-- **Maintain status updates**: Keep story statuses current (Draft → Approved → InProgress → Done)
-- **Leverage Windsurf's collaboration**: Use the collaborative features for team reviews
-
-This workflow ensures systematic, AI-assisted development following agile principles with clear handoffs between planning, story creation, and implementation phases.

docs/working-in-the-brownfield.md

@@ -1,22 +1,17 @@
 # Working in the Brownfield: A Complete Guide
 
-> 🚀 **HIGHLY RECOMMENDED: Use Gemini Web for Brownfield Documentation!**
+> **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation Generation!**
 >
-> Gemini Web's 1M+ token context window can analyze your ENTIRE codebase at once:
+> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase or critical sections of it all at once (obviously within reason):
 >
-> - Upload via GitHub URL
-> - Upload up to 1000 files
-> - Upload zipped project
->
-> This is MUCH more cost-effective than IDE analysis which reads files one by one!
+> - Upload via GitHub URL or use gemini cli in the project folder
+> - If in the web: Upload up to 1000 files or the zipped project or just give it the github url
 
 ## What is Brownfield Development?
 
 Brownfield development refers to adding features, fixing bugs, or modernizing existing software projects. Unlike greenfield (new) projects, brownfield work requires understanding existing code, respecting constraints, and ensuring new changes integrate seamlessly without breaking existing functionality.
 
-## When to Use BMAD for Brownfield
-
-BMAD-METHOD excels at brownfield development when you need to:
+## When to Use BMad for Brownfield
 
 - Add significant new features to existing applications
 - Modernize legacy codebases
@@ -25,11 +20,15 @@ BMAD-METHOD excels at brownfield development when you need to:
 - Fix bugs that require architectural understanding
 - Document undocumented systems
 
+## When NOT to use a Brownfield Flow
+
+If you have just completed an MVP with BMad, and you want to continue with post-MVP, its easier to just talk to the PM and ask him to work with you to create a new epic to add into the PRD, shard out the epic, update any architecture documents with the architect, and just go from there.
+
 ## The Complete Brownfield Workflow
 
 ### Choose Your Approach
 
-#### Approach A: PRD-First (Recommended for Large Codebases/Monorepos)
+#### Approach A: PRD-First (Recommended if adding very large and complex new features, single or multiple epics or massive changes)
 
 **Best for**: Large codebases, monorepos, or when you know exactly what you want to build
 
@@ -116,7 +115,7 @@ The analyst will generate comprehensive documentation of everything.
 
 #### Option A: Full Brownfield Workflow (Recommended for Major Changes)
 
-**1. Create Brownfield PRD**
+**1. Create Brownfield PRD**:
 
 ```bash
 @pm
@@ -143,7 +142,7 @@ The PM agent will:
 - "What are the critical constraints we must respect?"
 - "What is your timeline and team size?"
 
-**2. Create Brownfield Architecture**
+**2. Create Brownfield Architecture**:
 
 ```bash
 @architect
@@ -357,6 +356,6 @@ Is this a major enhancement affecting multiple systems?
 
 ## Conclusion
 
-Brownfield development with BMAD-METHOD provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
+Brownfield development with BMad-Method provides structure and safety when modifying existing systems. The key is providing comprehensive context through documentation, using specialized templates that consider integration requirements, and following workflows that respect existing constraints while enabling progress.
 
 Remember: **Document First, Plan Carefully, Integrate Safely**

expansion-packs/README.md

@@ -1,3 +1,3 @@
-# BMAD Method Expansion Packs
+# BMad Method Expansion Packs
 
-Expansion packs extend BMAD-METHOD beyond traditional software development, providing specialized agent teams, templates, and workflows for specific domains and industries. Each pack is a self-contained ecosystem designed to bring the power of AI-assisted workflows to any field. Coming soon.
+Expansion packs extend BMad-Method beyond traditional software development, providing specialized agent teams, templates, and workflows for specific domains and industries. Each pack is a self-contained ecosystem designed to bring the power of AI-assisted workflows to any field. Coming soon.

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

@@ -1,6 +1,6 @@
 # game-designer
 
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
 
 ```yaml
 activation-instructions: