chore(release): 4.21.1 [skip ci]

## [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](9371a5784f))
fix: readme clarifies that the installer handles installs upgrades and expansion installation
2025-06-30 02:09:46 +00:00 · 2025-06-29 21:09:13 -05:00 · 2025-06-30 01:53:38 +00:00 · 2025-06-29 20:53:09 -05:00 · 2025-06-29 20:52:23 -05:00 · 2025-06-29 11:30:15 -05:00
149 changed files with 24226 additions and 14690 deletions
--- a/.github/FUNDING.yml
+++ b/.github/FUNDING.yml
@@ -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']
--- a/.github/ISSUE_TEMPLATE/bug_report.md
+++ b/.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
--- a/.github/ISSUE_TEMPLATE/feature_request.md
+++ b/.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.
--- a/.gitignore
+++ b/.gitignore
@@ -20,3 +20,8 @@ CLAUDE.md
 .ai/*
 test-project-install/*
 sample-project/*
+.claude
+.bmad-core
+.bmad-creator-tools
+.gemini
+.bmad*/
--- a/.prettierignore
+++ b/.prettierignore
@@ -4,7 +4,6 @@ package-lock.json

 # Build outputs
 dist/
-web-bundles/

 # Generated files
 *.log
--- a/.vscode/extensions.json
+++ b/.vscode/extensions.json
@@ -1,6 +0,0 @@
-{
-	"recommendations": [
-		"davidanson.vscode-markdownlint",
-		"streetsidesoftware.code-spell-checker"
-	]
-}
--- a/.vscode/settings.json
+++ b/.vscode/settings.json
@@ -1,76 +1,7 @@
 {
    "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",
-		"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"]
-		}
-	}
+        "Agentic",
+        "elicitations",
+        "Shardable"
+    ]
 }
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,237 @@
+## [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)
+
+
+### Features
+
+* Add Gemini CLI Integration ([#271](https://github.com/bmadcode/BMAD-METHOD/issues/271)) ([44b9d7b](https://github.com/bmadcode/BMAD-METHOD/commit/44b9d7bcb5cbb6de5a15d8f2ec7918d186ac9576))
+
+## [4.14.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.14.0...v4.14.1) (2025-06-26)
+
+
+### Bug Fixes
+
+* add updated web builds ([6dabbcb](https://github.com/bmadcode/BMAD-METHOD/commit/6dabbcb670ef22708db6c01dac82069547ca79d6))
+
+# [4.14.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.13.0...v4.14.0) (2025-06-25)
+
+
+### Features
+
+* enhance QA agent as senior developer with code review capabilities and major brownfield improvements ([3af3d33](https://github.com/bmadcode/BMAD-METHOD/commit/3af3d33d4a40586479a382620687fa99a9f6a5f7))
+
+# [4.13.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.12.0...v4.13.0) (2025-06-24)
+
+
+### Features
+
+* **ide-setup:** add support for Cline IDE and configuration rules ([#262](https://github.com/bmadcode/BMAD-METHOD/issues/262)) ([913dbec](https://github.com/bmadcode/BMAD-METHOD/commit/913dbeced60ad65086df6233086d83a51ead81a9))
+
+# [4.12.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.11.0...v4.12.0) (2025-06-23)
+
+
+### Features
+
+* **dev-agent:** add quality gates to prevent task completion with failing validations ([#261](https://github.com/bmadcode/BMAD-METHOD/issues/261)) ([45110ff](https://github.com/bmadcode/BMAD-METHOD/commit/45110ffffe6d29cc08e227e22a901892185dfbd2))
+
+# [4.11.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.3...v4.11.0) (2025-06-21)
+
+
+### Bug Fixes
+
+* resolve web bundles directory path when using relative paths in NPX installer ([5c8485d](https://github.com/bmadcode/BMAD-METHOD/commit/5c8485d09ffec60ad4965ced62f4595890cb7535))
+
+
+### Features
+
+* add markdown-tree integration for document sharding ([540578b](https://github.com/bmadcode/BMAD-METHOD/commit/540578b39d1815e41e11f0e87545de3f09ee54e1))
+
+## [4.10.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.2...v4.10.3) (2025-06-20)
+
+
+### Bug Fixes
+
+* bundle update ([2cf3ba1](https://github.com/bmadcode/BMAD-METHOD/commit/2cf3ba1ab8dd7e52584bef16a96e65e7d2513c4f))
+
+## [4.10.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.1...v4.10.2) (2025-06-20)
+
+
+### Bug Fixes
+
+* file formatting ([c78a35f](https://github.com/bmadcode/BMAD-METHOD/commit/c78a35f547459b07a15d94c827ec05921cd21571))
+
+## [4.10.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.0...v4.10.1) (2025-06-20)
+
+
+### Bug Fixes
+
+* SM sometimes would skip the rest of the epic stories, fixed ([1148b32](https://github.com/bmadcode/BMAD-METHOD/commit/1148b32fa97586d2f86d07a70ffbf9bb8c327261))
+
+# [4.10.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.9.2...v4.10.0) (2025-06-19)
+
+
+### Features
+
+* Core Config and doc sharding is now optional in v4 ([ff6112d](https://github.com/bmadcode/BMAD-METHOD/commit/ff6112d6c2f822ed22c75046f5a14f05e36041c2))
+
+## [4.9.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.9.1...v4.9.2) (2025-06-19)
+
+
+### Bug Fixes
+
+* bad brownfield yml ([09d2ad6](https://github.com/bmadcode/BMAD-METHOD/commit/09d2ad6aea187996d0a2e1dff27d9bf7e3e6dc06))
+
+## [4.9.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.9.0...v4.9.1) (2025-06-19)
+
+
+### Bug Fixes
+
+* dist bundles updated ([d9a989d](https://github.com/bmadcode/BMAD-METHOD/commit/d9a989dbe50da62cf598afa07a8588229c56b69c))
+
+# [4.9.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.8.0...v4.9.0) (2025-06-19)
+
+
+### Features
+
+* dev can use debug log configured in core-config.yml ([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)
+
+
+### Bug Fixes
+
+* installer has fast v4 update option now to keep the bmad method up to date with changes easily without breaking any customizations from the user. The SM and DEV are much more configurable to find epics stories and architectureal information when the prd and architecture are deviant from v4 templates and/or have not been sharded. so a config will give the user the option to configure the SM to use the full large documents or the sharded versions! ([aea7f3c](https://github.com/bmadcode/BMAD-METHOD/commit/aea7f3cc86e749d25ed18bed761dc2839023b3b3))
+* prevent double installation when updating v4 ([af0e767](https://github.com/bmadcode/BMAD-METHOD/commit/af0e767ecf1b91d41f114e1a5d7bf5da08de57d6))
+* resolve undefined config properties in performUpdate ([0185e01](https://github.com/bmadcode/BMAD-METHOD/commit/0185e012bb579948a4de1ea3950db4e399761619))
+* update file-manager to properly handle YAML manifest files ([724cdd0](https://github.com/bmadcode/BMAD-METHOD/commit/724cdd07a199cb12b82236ad34ca1a0c61eb43e2))
+
+
+### Features
+
+* add early v4 detection for improved update flow ([29e7bbf](https://github.com/bmadcode/BMAD-METHOD/commit/29e7bbf4c5aa7e17854061a5ee695f44324f307a))
+* add file resolution context for IDE agents ([74d9bb4](https://github.com/bmadcode/BMAD-METHOD/commit/74d9bb4b2b70a341673849a1df704f6eac70c3de))
+* update web builder to remove IDE-specific properties from agent bundles ([2f2a1e7](https://github.com/bmadcode/BMAD-METHOD/commit/2f2a1e72d6a70f8127db6ba58a563d0f289621c3))
+
+# [4.7.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.6.3...v4.7.0) (2025-06-19)
+
+
+### Features
+
+* extensive bmad-kb for web orchestrator to be much more helpful ([e663a11](https://github.com/bmadcode/BMAD-METHOD/commit/e663a1146b89e7b5078d9726649a51ae5624da46))
+
+## [4.6.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.6.2...v4.6.3) (2025-06-19)
+
+
+### Bug Fixes
+
+* SM fixed file resolution issue in v4 ([61ab116](https://github.com/bmadcode/BMAD-METHOD/commit/61ab1161e59a92d657ab663082abcaf26729fa6b))
+
+## [4.6.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.6.1...v4.6.2) (2025-06-19)
+
+
+### Bug Fixes
+
+* installer upgrade path fixed ([bd6a558](https://github.com/bmadcode/BMAD-METHOD/commit/bd6a55892906077a700f488bde175b57e846729d))
+
+## [4.6.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.6.0...v4.6.1) (2025-06-19)
+
+
+### Bug Fixes
+
+* expansion pack builder now includes proper dependencies from core as needed, and default template file name save added to template llm instructions ([9dded00](https://github.com/bmadcode/BMAD-METHOD/commit/9dded003565879901246885d60787695e0d0b7bd))
+
+# [4.6.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.5.1...v4.6.0) (2025-06-18)
+
+
+### Bug Fixes
+
+* orchestractor yml ([3727cc7](https://github.com/bmadcode/BMAD-METHOD/commit/3727cc764a7c7295932ff872e2e5be8b4c4e6859))
+
+
+### Features
+
+* removed some templates that are not ready for use ([b03aece](https://github.com/bmadcode/BMAD-METHOD/commit/b03aece79e52cfe9585225de5aff7659293d9295))
+
 ## [4.5.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.5.0...v4.5.1) (2025-06-18)


--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,8 +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.
+
 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.
@@ -14,18 +21,96 @@ 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:
+
+- Keep dev agents lean - they need context for coding, not documentation
+- Web/planning agents can be larger with more complex tasks
+- Everything is natural language (markdown) - no code in core framework
+- Use expansion packs for domain-specific features
+
+#### Which Branch for Your PR?
+
+**Submit to `next` branch** (most contributions):
+
+- ✨ New features or agents
+- 🎨 Enhancements to existing features
+- 📚 Documentation updates
+- ♻️ Code refactoring
+- ⚡ Performance improvements
+- 🧪 New tests
+- 🎁 New expansion packs
+
+**Submit to `main` branch** (critical only):
+
+- 🚨 Critical bug fixes that break basic functionality
+- 🔒 Security patches
+- 📚 Fixing dangerously incorrect documentation
+- 🐛 Bugs preventing installation or basic usage
+
+**When in doubt, submit to `next`**. We'd rather test changes thoroughly before they hit stable.
+
+#### PR Size Guidelines
+
+- **Ideal PR size**: 200-400 lines of code changes
+- **Maximum PR size**: 800 lines (excluding generated files)
+- **One feature/fix per PR**: Each PR should address a single issue or add one feature
+- **If your change is larger**: Break it into multiple smaller PRs that can be reviewed independently
+- **Related changes**: Even related changes should be separate PRs if they deliver independent value
+
+#### Breaking Down Large PRs
+
+If your change exceeds 800 lines, use this checklist to split it:
+
+- [ ] Can I separate the refactoring from the feature implementation?
+- [ ] Can I introduce the new API/interface in one PR and implementation in another?
+- [ ] Can I split by file or module?
+- [ ] Can I create a base PR with shared utilities first?
+- [ ] Can I separate test additions from implementation?
+- [ ] Even if changes are related, can they deliver value independently?
+- [ ] Can these changes be merged in any order without breaking things?
+
+Example breakdown:
+
+1. PR #1: Add utility functions and types (100 lines)
+2. PR #2: Refactor existing code to use utilities (200 lines)
+3. PR #3: Implement new feature using refactored code (300 lines)
+4. PR #4: Add comprehensive tests (200 lines)
+
+**Note**: PRs #1 and #4 could be submitted simultaneously since they deliver independent value and don't depend on each other's merge order.
+
+#### Pull Request Steps
+
 1. Fork the repository
 2. Create a new branch (`git checkout -b feature/your-feature-name`)
 3. Make your changes
@@ -34,9 +119,85 @@ Please only propose small granular commits! If its large or significant, please
 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:
+
+### PR Description Template
+
+Keep your PR description concise and focused. Use this template:
+
+```markdown
+## What
+
+[1-2 sentences describing WHAT changed]
+
+## Why
+
+[1-2 sentences explaining WHY this change is needed]
+Fixes #[issue number] (if applicable)
+
+## How
+
+[2-3 bullets listing HOW you implemented it]
+
+-
+-
+-
+
+## Testing
+
+[1-2 sentences on how you tested this]
+```
+
+**Maximum PR description length: 200 words** (excluding code examples if needed)
+
+### Good vs Bad PR Descriptions
+
+❌ **Bad Example:**
+
+> This revolutionary PR introduces a paradigm-shifting enhancement to the system's architecture by implementing a state-of-the-art solution that leverages cutting-edge methodologies to optimize performance metrics and deliver unprecedented value to stakeholders through innovative approaches...
+
+✅ **Good Example:**
+
+> **What:** Added validation for agent dependency resolution
+> **Why:** Build was failing silently when agents had circular dependencies
+> **How:**
+>
+> - Added cycle detection in dependency-resolver.js
+> - Throws clear error with dependency chain
+>   **Testing:** Tested with circular deps between 3 agents
+
 ## Commit Message Convention

-PRs with a wall of AI Generated marketing hype that is unclear in what is being proposed will be closed and rejected. Your best change to contribute is with a small clear PR description explaining, what is the issue being solved or gap in the system being filled. Also explain how it leads to the core guiding principles of the project.
+Use conventional commits format:
+
+- `feat:` New feature
+- `fix:` Bug fix
+- `docs:` Documentation only
+- `refactor:` Code change that neither fixes a bug nor adds a feature
+- `test:` Adding missing tests
+- `chore:` Changes to build process or auxiliary tools
+
+Keep commit messages under 72 characters.
+
+### Atomic Commits
+
+Each commit should represent one logical change:
+
+- **Do:** One bug fix per commit
+- **Do:** One feature addition per commit
+- **Don't:** Mix refactoring with bug fixes
+- **Don't:** Combine unrelated changes

 ## Code Style

--- a/GUIDING-PRINCIPLES.md
+++ b/GUIDING-PRINCIPLES.md
@@ -0,0 +1,85 @@
+# 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.
+
+## Core Principles
+
+### 1. Dev Agents Must Be Lean
+
+- **Minimize dev agent dependencies**: Development agents that work in IDEs must have minimal context overhead
+- **Save context for code**: Every line counts - dev agents should focus on coding, not documentation
+- **Web agents can be larger**: Planning agents (PRD Writer, Architect) used in web UI can have more complex tasks and dependencies
+- **Small files, loaded on demand**: Multiple small, focused files are better than large files with many branches
+
+### 2. Natural Language First
+
+- **Everything is markdown**: Agents, tasks, templates - all written in plain English
+- **No code in core**: The framework itself contains no programming code, only natural language instructions
+- **Self-contained templates**: Templates include their own generation instructions using `[[LLM: ...]]` markup
+
+### 3. Agent and Task Design
+
+- **Agents define roles**: Each agent is a persona with specific expertise (e.g., Frontend Developer, API Developer)
+- **Tasks are procedures**: Step-by-step instructions an agent follows to complete work
+- **Templates are outputs**: Structured documents with embedded instructions for generation
+- **Dependencies matter**: Explicitly declare only what's needed
+
+## Practical Guidelines
+
+### When to Add to Core
+
+- Universal software development needs only
+- Doesn't bloat dev agent contexts
+- Follows existing agent/task/template patterns
+
+### When to Create Expansion Packs
+
+- Domain-specific needs beyond software development
+- Non-technical domains (business, wellness, education, creative)
+- Specialized technical domains (games, infrastructure, mobile)
+- Heavy documentation or knowledge bases
+- Anything that would bloat core agents
+
+See [Expansion Packs Guide](../docs/expansion-packs.md) for detailed examples and ideas.
+
+### Agent Design Rules
+
+1. **Web/Planning Agents**: Can have richer context, multiple tasks, extensive templates
+2. **Dev Agents**: Minimal dependencies, focused on code generation, lean task sets
+3. **All Agents**: Clear persona, specific expertise, well-defined capabilities
+
+### Task Writing Rules
+
+1. Write clear step-by-step procedures
+2. Use markdown formatting for readability
+3. Keep dev agent tasks focused and concise
+4. Planning tasks can be more elaborate
+5. **Prefer multiple small tasks over one large branching task**
+   - Instead of one task with many conditional paths
+   - Create multiple focused tasks the agent can choose from
+   - This keeps context overhead minimal
+6. **Reuse common tasks** - Don't create new document creation tasks
+   - Use the existing `create-doc` task
+   - Pass the appropriate template with embedded LLM instructions
+   - This maintains consistency and reduces duplication
+
+### Template Rules
+
+1. Include generation instructions with `[[LLM: ...]]` markup
+2. Provide clear structure for output
+3. Make templates reusable across agents
+4. Use standardized markup elements:
+   - `{{placeholders}}` for variables to be replaced
+   - `[[LLM: instructions]]` for AI-only processing (never shown to users)
+   - `REPEAT` sections for repeatable content blocks
+   - `^^CONDITION^^` blocks for conditional content
+   - `@{examples}` for guidance examples (never output to users)
+5. NEVER display template markup or LLM instructions to users
+6. Focus on clean output - all processing instructions stay internal
+
+## Remember
+
+- The power is in natural language orchestration, not code
+- Dev agents code, planning agents plan
+- Keep dev agents lean for maximum coding efficiency
+- Expansion packs handle specialized domains
--- a/2
+++ b/2
@@ -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
--- a/README.md
+++ b/README.md
@@ -1,59 +1,139 @@
-# 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!
+
+⭐ **If you find this project helpful or useful, please give it a star in the upper right hand corner!** It helps others discover BMad-METHOD and you will be notified of updates!
+
+## 🧭 Quick Navigation - Find Your Path
+
+### 🚨 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: Keeping 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
+npm run install:bmad
+```
+
+This will:
+
+- ✅ Automatically detect your existing v4 installation
+- ✅ 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! 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

-### 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:
+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 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 tool, the BMad Methods agile flow does so much more. With most systems, you give your idea in a few sentences at most, 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 techniques and techniques also based in psychology to produce beyond the average slop LLMs and Task generators will on their own. This truly is a system of Human in the Loop produces 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:

@@ -64,49 +144,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.
+- `windsurf` - Windsurf with @agent commands

 ## 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               |
+| ----------- | ------------------ | -------------------------------------------------------------------------------------------- |
+| `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                                  |
+| ------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `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
@@ -119,92 +223,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
-2. Use `@bmad-master` agent to run the `doc-migration-task` to align your documents with V4 templates
-3. If you have separate front-end and backend architecture docs, the migration task will help merge them into a unified `full-stack-architecture.md`
-
-**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/`.
-
-## 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-coreconfigyml)** - 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/     # Pre-built bundles (deprecated - use dist/ instead)
+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/     # Optional add-ons (DevOps, Mobile, etc.)
-
-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)

@@ -226,55 +267,61 @@ 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
-
-### 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...
-
-### 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!
-
-## Contributing
-
-We welcome contributions!
-
- 🆕 **New to GitHub?** Start with our [Pull Request Guide](docs/how-to-contribute-with-pull-requests.md)
- See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines
-
-### 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
- 🎯 [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
+- 🏗️ [Working in the Brownfield Guide](docs/working-in-the-brownfield.md) - Complete guide for enhancing existing projects
+
+### IDE-Specific Guides
+
+- 🎯 [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
+
+## 🌟 Beyond Software Development - Expansion Packs
+
+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.
+
+### Available Expansion Packs
+
+#### Technical Domains
+
+- 🎮 **[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 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, content creators, research assistants
+
+### Creating Your Own Expansion Pack
+
+Transform your expertise into AI agents:
+
+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)** - Detailed examples, inspiration, and technical details

 ## Support

@@ -301,7 +348,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)

--- a/bmad-core/agents/analyst.md
+++ b/bmad-core/agents/analyst.md
@@ -3,6 +3,9 @@
 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:

 ```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.
 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
@@ -13,7 +16,7 @@ agent:
  id: analyst
  title: Business Analyst
  icon: 📊
-  whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, and initial project discovery
+  whenToUse: Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)
  customization: null
 persona:
  role: Insightful Analyst & Strategic Ideation Partner
@@ -34,20 +37,22 @@ persona:
    - Numbered Options Protocol - Always use numbered lists for selections
 startup:
  - Greet the user with your name and role, and inform of the *help command.
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) Strategic analysis consultation with advanced-elicitation'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*brainstorm {topic}" - Facilitate structured brainstorming session'
-  - '*research {topic}" - Generate deep research prompt for investigation'
-  - '*elicit" - Run advanced elicitation to clarify requirements'
-  - '*exit" - Say goodbye as the Business Analyst, and then abandon inhabiting this persona'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) Strategic analysis consultation with advanced-elicitation
+  - create-doc {template}: Create doc (no template = show available templates)
+  - brainstorm {topic}: Facilitate structured brainstorming session
+  - research {topic}: Generate deep research prompt for investigation
+  - elicit: Run advanced elicitation to clarify requirements
+  - document-project: Analyze and document existing project structure comprehensively
+  - exit: Say goodbye as the Business Analyst, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - brainstorming-techniques
    - create-deep-research-prompt
    - create-doc
    - advanced-elicitation
+    - document-project
  templates:
    - project-brief-tmpl
    - market-research-tmpl
--- a/bmad-core/agents/architect.md
+++ b/bmad-core/agents/architect.md
@@ -3,6 +3,9 @@
 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:

 ```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.
 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
@@ -34,13 +37,13 @@ persona:
 startup:
  - Greet the user with your name and role, and inform of the *help command.
  - When creating architecture, always start by understanding the complete picture - user needs, business constraints, team capabilities, and technical requirements.
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) Architect consultation with advanced-elicitation for complex system design'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*execute-checklist {checklist}" - Run architectural validation checklist'
-  - '*research {topic}" - Generate deep research prompt for architectural decisions'
-  - '*exit" - Say goodbye as the Architect, and then abandon inhabiting this persona'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) Architect consultation with advanced-elicitation for complex system design
+  - create-doc {template}: Create doc (no template = show available templates)
+  - execute-checklist {checklist}: Run architectural validation checklist
+  - research {topic}: Generate deep research prompt for architectural decisions
+  - exit: Say goodbye as the Architect, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - create-doc
--- a/bmad-core/agents/bmad-master.md
+++ b/bmad-core/agents/bmad-master.md
@@ -3,6 +3,9 @@
 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:

 ```yml
+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
@@ -22,21 +25,21 @@ persona:
    - Use numbered lists for choices
    - Process (*) commands immediately
 startup:
-  - Announce: I'm BMad Master, your BMAD task executor. I can run any task, template, util, checklist, workflow, or schema. Type *help or tell me what you need.
+  - Greet the user with your name and role, and inform of the *help command.
  - 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
  - Match request to resources, offer numbered options if unclear
  - Load resources only when explicitly requested
-commands:
-  - '*help" - Show commands'
-  - '*chat" - Advanced elicitation + KB mode'
-  - '*status" - Current context'
-  - '*task/template/util/checklist/workflow {name}" - Execute (list if no name)'
-  - '*list {type}" - List resources by type'
-  - '*exit" - Exit (confirm)'
-  - '*yolo" - Skip confirmations'
-  - '*doc-out" - Output full document'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show commands
+  - chat: Advanced elicitation + KB mode
+  - status: Current context
+  - task {template|util|checklist|workflow}: Execute
+  - list {task|template|util|checklist|workflow}: List resources by type
+  - 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
@@ -74,7 +77,6 @@ dependencies:
    - prd-tmpl
    - project-brief-tmpl
    - story-tmpl
-    - web-agent-startup-instructions-template
  data:
    - bmad-kb
    - technical-preferences
--- a/bmad-core/agents/bmad-orchestrator.md
+++ b/bmad-core/agents/bmad-orchestrator.md
@@ -3,6 +3,9 @@
 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:

 ```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 Orchestrator
  id: bmad-orchestrator
@@ -22,72 +25,68 @@ persona:
    - When embodied, specialized persona's principles take precedence
    - Be explicit about active persona and current task
    - Always use numbered lists for choices
-    - Process (*) commands immediately
+    - Process commands starting with * immediately
+    - Always remind users that commands require * prefix
 startup:
-  - Announce: Hey! I'm BMad, your BMAD-METHOD orchestrator. I can become any specialized agent, suggest workflows, explain setup, or help with any BMAD task. Type *help for options.
+  - 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
  - Assess user goal against available agents and workflows in this bundle
-  - If clear match to an agent's expertise, suggest transformation
-  - If project-oriented, explore available workflows and guide selection
-  - Load resources only when needed
-commands:
-  - '*help" - Show commands/workflows/agents'
-  - '*chat-mode" - Conversational mode with advanced-elicitation'
-  - '*kb-mode" - Load knowledge base for full BMAD help'
-  - '*status" - Show current context/agent/progress'
-  - '*agent {name}" - Transform into agent (list if unspecified)'
-  - '*exit" - Return to BMad or exit (confirm if exiting BMad)'
-  - '*task {name}" - Run task (list if unspecified)'
-  - '*workflow {type}" - Start/list workflows'
-  - '*workflow-guidance" - Get help selecting the right workflow for your project'
-  - '*checklist {name}" - Execute checklist (list if unspecified)'
-  - '*yolo" - Toggle skip confirmations'
-  - '*party-mode" - Group chat with all agents'
-  - '*doc-out" - Output full document'
-help-format:
-  - When *help is called, focus on agent capabilities and what each can do
-  - List actual agent names with their specializations and deliverables
-  - List actual workflow names with descriptions
-  - DO NOT list individual tasks/checklists (these belong to specific agents)
-  - Emphasize that users should switch to an agent to access its specific capabilities
-  - Format examples:
-    - "*agent game-designer: Game Design Specialist"
-    - "  Specializes in: Game concepts, mechanics, level design"
-    - "  Can create: Game design documents, level designs, game briefs"
+  - If clear match to an agent's expertise, suggest transformation with *agent command
+  - If project-oriented, suggest *workflow-guidance to explore options
+  - Load resources only when needed - never pre-load
+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
+  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
+  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 - Your Gateway to Specialized Agents
+  === BMAD Orchestrator Commands ===
+  All commands must start with * (asterisk)
  
-  I coordinate specialized agents for different tasks. Tell me what you need, and I'll connect you with the right expert!
+  Core Commands:
+  *help ............... Show this guide
+  *chat-mode .......... Start conversational mode for detailed assistance
+  *kb-mode ............ Load full BMAD knowledge base
+  *status ............. Show current context, active agent, and progress
+  *exit ............... Return to BMad or exit session
  
-  Orchestrator Commands:
-  *help: Show this guide
-  *chat-mode: Start conversational mode for detailed assistance
-  *kb-mode: Load full BMAD knowledge base
-  *status: Show current context, active agent, and progress
-  *yolo: Toggle skip confirmations mode
-  *party-mode: Group chat with all agents
-  *doc-out: Output full document
-  *exit: Return to BMad or exit session
-  
-  Agent Management:
-  *agent {name}: Transform into a specialized agent
-  *task {name}: Run a specific task (when in an agent)
-  *checklist {name}: Execute a checklist (when in an agent)
+  Agent & Task Management:
+  *agent [name] ....... Transform into specialized agent (list if no name)
+  *task [name] ........ Run specific task (list if no name, requires agent)
+  *checklist [name] ... Execute checklist (list if no name, requires agent)
  
  Workflow Commands:
-  *workflow {name}: Start a specific workflow directly
-  *workflow-guidance: Get personalized help selecting the right workflow for your project
+  *workflow [name] .... Start specific workflow (list if no name)
+  *workflow-guidance .. Get personalized help selecting the right workflow
  
-  Available Specialist Agents:
-  [For each agent in bundle, show:
-  *agent {name}: {role/title}
-    Specializes in: {key capabilities from agent's whenToUse}
-    Can create: {list of documents/deliverables this agent produces}]
+  Other Commands:
+  *yolo ............... Toggle skip confirmations mode
+  *party-mode ......... Group chat with all agents
+  *doc-out ............ Output full document
  
-  Available Workflows:
-  [For each workflow in bundle, show:
-  *workflow {name}: {workflow description}]
+  === Available Specialist Agents ===
+  [Dynamically list each agent in bundle with format:
+  *agent {id}: {title}
+    When to use: {whenToUse}
+    Key deliverables: {main outputs/documents}]
+  
+  === Available Workflows ===
+  [Dynamically list each workflow in bundle with format:
+  *workflow {id}: {name}
+    Purpose: {description}]
+  
+  💡 Tip: Each agent has unique tasks, templates, and checklists. Switch to an agent to access their capabilities!

-  💡 Tip: Each agent has their own tasks, templates, and checklists. Switch to an agent to see what they can do!
 fuzzy-matching:
  - 85% confidence threshold
  - Show numbered list if unsure
@@ -98,28 +97,27 @@ transformation:
 loading:
  - KB: Only for *kb-mode or BMAD questions
  - Agents: Only when transforming
-  - 'Templates/Tasks: Only when executing'
+  - Templates/Tasks: Only when executing
  - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
  - Discover available workflows in the bundle at runtime
  - 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 workflows with divergent paths (e.g., simple vs complex), help users choose the right path
+  - 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
-workflow-guidance-command:
-  - When *workflow-guidance is called, start an interactive session
-  - First, list all available workflows with brief descriptions
-  - Ask about the user's project goals and constraints
-  - Based on answers, recommend the most suitable workflow
-  - If a workflow has multiple paths, help choose between them (e.g., complex vs simple project flow)
-  - Explain what documents will be created and which agents will be involved
-  - Offer to start the recommended workflow immediately
+  - When *workflow-guidance is called, start an interactive session and list all available workflows with brief descriptions
 dependencies:
  tasks:
    - advanced-elicitation
    - create-doc
+    - kb-mode-interaction
  data:
    - bmad-kb
  utils:
--- a/bmad-core/agents/dev.md
+++ b/bmad-core/agents/dev.md
@@ -3,6 +3,9 @@
 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:

 ```yml
+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: James
  id: dev
@@ -11,6 +14,13 @@ agent:
  whenToUse: "Use for code implementation, debugging, refactoring, and development best practices"
  customization:

+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 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
+
 persona:
  role: Expert Senior Software Engineer & Implementation Specialist
  style: Extremely concise, pragmatic, detail-oriented, solution-focused
@@ -19,48 +29,33 @@ persona:

 core_principles:
  - CRITICAL: Story-Centric - Story has ALL info. NEVER load PRD/architecture/other docs files unless explicitly directed in dev notes
-  - CRITICAL: Load Standards - MUST load docs/architecture/coding-standards.md into core memory at startup
-  - CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
-  - Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
+  - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
  - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
-  - Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
+  - Quality Gate Discipline - NEVER complete tasks with failing automated validations
+  - Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix.
  - Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
-  - Code Excellence - Clean, secure, maintainable code per coding-standards.md
+  - Code Excellence - Clean, secure, maintainable code per loaded standards
  - Numbered Options - Always use numbered lists when presenting choices

-startup:
-  - Announce: Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Do NOT load any story files or coding-standards.md during startup
-  - CRITICAL: Do NOT scan docs/stories/ directory automatically
-  - CRITICAL: Do NOT begin any tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load files and begin work when explicitly requested by user
-
-commands:
-  - "*help" - Show commands
-  - "*chat-mode" - Conversational mode
-  - "*run-tests" - Execute linting+tests
-  - "*lint" - Run linting only
-  - "*dod-check" - Run story-dod-checklist
-  - "*status" - Show task progress
-  - "*debug-log" - Show debug entries
-  - "*complete-story" - Finalize to "Review"
-  - "*exit" - Leave developer mode
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - run-tests: Execute linting and tests
+  - debug-log: Show debug entries
+  - complete-story: Finalize to "Review"
+  - exit: Say goodbye as the Developer, and then abandon inhabiting this persona

 task-execution:
-  flow: "Read task→Implement→Write tests→Pass tests→Update [x]→Next task"
-
+  flow: "Read task→Implement→Write tests→Execute validations→Only if ALL pass→Update [x]→Next task"
  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"
-
-  blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config"
-
-  done: "Code matches reqs + Tests pass + Follows standards + No lint errors"
-
-  completion: "All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT"
+    - "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"
+  done: "Code matches reqs + All validations pass + Follows standards + File List complete"
+  completion: "All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Update File List→Mark Ready for Review→HALT"

 dependencies:
  tasks:
--- a/bmad-core/agents/pm.md
+++ b/bmad-core/agents/pm.md
@@ -3,6 +3,9 @@
 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:

 ```yml
+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.
 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
@@ -31,11 +34,11 @@ persona:
    - Strategic thinking & outcome-oriented
 startup:
  - Greet the user with your name and role, and inform of the *help command.
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) Deep conversation with advanced-elicitation'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*exit" - Say goodbye as the PM, and then abandon inhabiting this persona'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) Deep conversation with advanced-elicitation
+  - create-doc {template}: Create doc (no template = show available templates)
+  - exit: Say goodbye as the PM, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - create-doc
@@ -48,7 +51,6 @@ dependencies:
  templates:
    - prd-tmpl
    - brownfield-prd-tmpl
-    - simple-project-prd-tmpl
  checklists:
    - pm-checklist
    - change-checklist
--- a/bmad-core/agents/po.md
+++ b/bmad-core/agents/po.md
@@ -3,6 +3,9 @@
 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:

 ```yml
+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.
 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
@@ -33,16 +36,16 @@ persona:
    - Documentation Ecosystem Integrity - Maintain consistency across all documents
 startup:
  - Greet the user with your name and role, and inform of the *help command.
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) Product Owner consultation with advanced-elicitation'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*execute-checklist {checklist}" - Run validation checklist (default->po-master-checklist)'
-  - '*shard-doc {document}" - Break down document into actionable parts'
-  - '*correct-course" - Analyze and suggest project course corrections'
-  - '*create-epic" - Create epic for brownfield projects (task brownfield-create-epic)'
-  - '*create-story" - Create user story from requirements (task brownfield-create-story)'
-  - '*exit" - Say Goodbye, You are no longer this Agent'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) Product Owner consultation with advanced-elicitation
+  - create-doc {template}: Create doc (no template = show available templates)
+  - execute-checklist {checklist}: Run validation checklist (default->po-master-checklist)
+  - shard-doc {document}: Break down document into actionable parts
+  - correct-course: Analyze and suggest project course corrections
+  - create-epic: Create epic for brownfield projects (task brownfield-create-epic)
+  - create-story: Create user story from requirements (task brownfield-create-story)
+  - exit: Say goodbye as the Product Owner, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - execute-checklist
--- a/bmad-core/agents/qa.md
+++ b/bmad-core/agents/qa.md
@@ -3,6 +3,9 @@
 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:

 ```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.
 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
@@ -11,34 +14,35 @@ activation-instructions:
 agent:
  name: Quinn
  id: qa
-  title: Quality Assurance Test Architect
+  title: Senior Developer & QA Architect
  icon: 🧪
-  whenToUse: Use for test planning, test case creation, quality assurance, bug reporting, and testing strategy
+  whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
  customization: null
 persona:
-  role: Test Architect & Automation Expert
-  style: Methodical, detail-oriented, quality-focused, strategic
-  identity: Senior quality advocate with expertise in test architecture and automation
-  focus: Comprehensive testing strategies, automation frameworks, quality assurance at every phase
+  role: Senior Developer & Test Architect
+  style: Methodical, detail-oriented, quality-focused, mentoring, strategic
+  identity: Senior developer with deep expertise in code quality, architecture, and test automation
+  focus: Code excellence through review, refactoring, and comprehensive testing strategies
  core_principles:
+    - Senior Developer Mindset - Review and improve code as a senior mentoring juniors
+    - Active Refactoring - Don't just identify issues, fix them with clear explanations
    - Test Strategy & Architecture - Design holistic testing strategies across all levels
-    - Automation Excellence - Build maintainable and efficient test automation frameworks
+    - Code Quality Excellence - Enforce best practices, patterns, and clean code principles
    - Shift-Left Testing - Integrate testing early in development lifecycle
+    - Performance & Security - Proactively identify and fix performance/security issues
+    - Mentorship Through Action - Explain WHY and HOW when making improvements
    - Risk-Based Testing - Prioritize testing based on risk and critical areas
-    - Performance & Load Testing - Ensure systems meet performance requirements
-    - Security Testing Integration - Incorporate security testing into QA process
-    - Test Data Management - Design strategies for realistic and compliant test data
-    - Continuous Testing & CI/CD - Integrate tests seamlessly into pipelines
-    - Quality Metrics & Reporting - Track meaningful metrics and provide insights
-    - Cross-Browser & Cross-Platform Testing - Ensure comprehensive compatibility
+    - Continuous Improvement - Balance perfection with pragmatism
+    - Architecture & Design Patterns - Ensure proper patterns and maintainable code structure
 startup:
  - Greet the user with your name and role, and inform of the *help command.
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) QA consultation with advanced-elicitation for test strategy'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*exit" - Say goodbye as the QA Test Architect, and then abandon inhabiting this persona'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) QA consultation with advanced-elicitation for test strategy
+  - exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
 dependencies:
+  tasks:
+    - review-story
  data:
    - technical-preferences
  utils:
--- a/bmad-core/agents/sm.md
+++ b/bmad-core/agents/sm.md
@@ -3,9 +3,11 @@
 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:

 ```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.
 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
  - The customization field ALWAYS takes precedence over any conflicting instructions
  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
 agent:
@@ -21,31 +23,25 @@ persona:
  identity: Story creation expert who prepares detailed, actionable stories for AI developers
  focus: Creating crystal-clear stories that dumb AI agents can implement without confusion
  core_principles:
-    - Task Adherence - Rigorously follow create-next-story procedures
-    - Checklist-Driven Validation - Apply story-draft-checklist meticulously
-    - Clarity for Developer Handoff - Stories must be immediately actionable
-    - Focus on One Story at a Time - Complete one before starting next
-    - Numbered Options Protocol - Always use numbered lists for selections
+    - Rigorously follow `create-next-story` procedure to generate the detailed user story
+    - Will ensure all information comes from the PRD and Architecture to guide the dumb dev agent
+    - You are NOT allowed to implement stories or modify code EVER!
 startup:
-  - Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Do NOT automatically execute create-next-story tasks during startup
-  - CRITICAL: Do NOT create or modify any files during startup
+  - Greet the user with your name and role, and inform of the *help command and then HALT to await instruction if not given already.
  - Offer to help with story preparation but wait for explicit user confirmation
  - Only execute tasks when user explicitly requests them
-  - 'CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Dev Agent'
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - Conversational mode with advanced-elicitation for advice'
-  - '*create" - Execute all steps in Create Next Story Task document'
-  - '*pivot" - Run correct-course task (ensure no story already created first)'
-  - '*checklist {checklist}" - Show numbered list of checklists, execute selection'
-  - '*doc-shard {PRD|Architecture|Other}" - Execute shard-doc task'
-  - '*index-docs" - Update documentation index in /docs/index.md'
-  - '*exit" - Say goodbye as the Scrum Master, and then abandon inhabiting this persona'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: Conversational mode with advanced-elicitation for advice
+  - create|draft: Execute create-next-story
+  - pivot: Execute `correct-course` task
+  - checklist {checklist}: Show numbered list of checklists, execute selection
+  - exit: Say goodbye as the Scrum Master, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - create-next-story
    - execute-checklist
+    - course-correct
  templates:
    - story-tmpl
  checklists:
--- a/bmad-core/agents/ux-expert.md
+++ b/bmad-core/agents/ux-expert.md
@@ -3,6 +3,9 @@
 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:

 ```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.
 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
@@ -37,14 +40,14 @@ persona:
 startup:
  - Greet the user with your name and role, and inform of the *help command.
  - Always start by understanding the user's context, goals, and constraints before proposing solutions.
-commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) UX consultation with advanced-elicitation for design decisions'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*generate-ui-prompt" - Create AI frontend generation prompt'
-  - '*research {topic}" - Generate deep research prompt for UX investigation'
-  - '*execute-checklist {checklist}" - Run design validation checklist'
-  - '*exit" - Say goodbye as the UX Expert, and then abandon inhabiting this persona'
+commands:  # All commands require * prefix when used (e.g., *help)
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) UX consultation with advanced-elicitation for design decisions
+  - create-doc {template}: Create doc (no template = show available templates)
+  - generate-ui-prompt: Create AI frontend generation prompt
+  - research {topic}: Generate deep research prompt for UX investigation
+  - execute-checklist {checklist}: Run design validation checklist
+  - exit: Say goodbye as the UX Expert, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - generate-ai-frontend-prompt
--- a/bmad-core/core-config.yml
+++ b/bmad-core/core-config.yml
@@ -0,0 +1,20 @@
+version: 4.20.1
+markdownExploder: true
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v4
+  prdSharded: true
+  prdShardedLocation: docs/prd
+  epicFilePattern: epic-{n}*.md
+architecture:
+  architectureFile: docs/architecture.md
+  architectureVersion: v4
+  architectureSharded: true
+  architectureShardedLocation: docs/architecture
+customTechnicalDocuments: null
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/source-tree.md
+devDebugLog: .ai/debug-log.md
+devStoryLocation: docs/stories
--- a/bmad-core/data/bmad-kb.md
+++ b/bmad-core/data/bmad-kb.md
@@ -12,6 +12,212 @@ 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
+
+- **New Projects (Greenfield)**: Complete end-to-end development
+- **Existing Projects (Brownfield)**: Feature additions and enhancements
+- **Team Collaboration**: Multiple roles working together
+- **Quality Assurance**: Structured testing and validation
+- **Documentation**: Professional PRDs, architecture docs, user stories
+
+## 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:
+
+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.)
+3. **Structured Workflows**: Proven patterns guide you from idea to deployed code
+4. **Clean Handoffs**: Fresh context windows ensure agents stay focused and effective
+
+### The Two-Phase Approach
+
+**Phase 1: Planning (Web UI - Cost Effective)**
+- Use large context windows (Gemini's 1M tokens)
+- Generate comprehensive documents (PRD, Architecture)
+- Leverage multiple agents for brainstorming
+- Create once, use throughout development
+
+**Phase 2: Development (IDE - Implementation)**
+- Shard documents into manageable pieces
+- Execute focused SM → Dev cycles
+- One story at a time, sequential progress
+- Real-time file operations and testing
+
+### The Development Loop
+
+```text
+1. SM Agent (New Chat) → Creates next story from sharded docs
+2. You → Review and approve story
+3. Dev Agent (New Chat) → Implements approved story
+4. QA Agent (New Chat) → Reviews and refactors code
+5. You → Verify completion
+6. Repeat until epic complete
+```
+
+### Why This Works
+
+- **Context Optimization**: Clean chats = better AI performance
+- **Role Clarity**: Agents don't context-switch = higher quality
+- **Incremental Progress**: Small stories = manageable complexity
+- **Human Oversight**: You validate each step = quality control
+- **Document-Driven**: Specs guide everything = consistency
+
+## Getting Started
+
+### Quick Start Options
+
+#### Option 1: Web UI
+**Best for**: ChatGPT, Claude, Gemini users who want to start immediately
+
+1. Navigate to `dist/teams/`
+2. Copy `team-fullstack.txt` content
+3. Create new Gemini Gem or CustomGPT
+4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
+5. Type `/help` to see available commands
+
+#### Option 2: IDE Integration
+**Best for**: Cursor, Claude Code, Windsurf, Cline, Roo Code users
+
+```bash
+# Interactive installation (recommended)
+npx bmad-method install
+```
+
+**Installation Steps**:
+- Choose "Complete installation"
+- Select your IDE from supported options:
+  - **Cursor**: Native AI integration
+  - **Claude Code**: Anthropic's official IDE
+  - **Windsurf**: Built-in AI capabilities
+  - **Cline**: VS Code extension with AI features
+  - **Roo Code**: Web-based IDE with agent support
+
+**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
+
+### Environment Selection Guide
+
+**Use Web UI for**:
+- Initial planning and documentation (PRD, architecture)
+- Cost-effective document creation (especially with Gemini)
+- Brainstorming and analysis phases
+- Multi-agent consultation and planning
+
+**Use IDE for**:
+- Active development and coding
+- File operations and project integration
+- Document sharding and story management
+- Implementation workflow (SM/Dev cycles)
+
+**Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
+
+### IDE-Only Workflow Considerations
+
+**Can you do everything in IDE?** Yes, but understand the tradeoffs:
+
+**Pros of IDE-Only**:
+- Single environment workflow
+- Direct file operations from start
+- No copy/paste between environments
+- Immediate project integration
+
+**Cons of IDE-Only**:
+- Higher token costs for large document creation
+- Smaller context windows (varies by IDE/model)
+- May hit limits during planning phases
+- Less cost-effective for brainstorming
+
+**Using Web Agents in IDE**:
+- **NOT RECOMMENDED**: Web agents (PM, Architect) have rich dependencies designed for large contexts
+- **Why it matters**: Dev agents are kept lean to maximize coding context
+- **The principle**: "Dev agents code, planning agents plan" - mixing breaks this optimization
+
+**About bmad-master and bmad-orchestrator**:
+- **bmad-master**: CAN do any task without switching agents, BUT...
+- **Still use specialized agents for planning**: PM, Architect, and UX Expert have tuned personas that produce better results
+- **Why specialization matters**: Each agent's personality and focus creates higher quality outputs
+- **If using bmad-master/orchestrator**: Fine for planning phases, but...
+
+**CRITICAL RULE for Development**:
+- **ALWAYS use SM agent for story creation** - Never use bmad-master/orchestrator
+- **ALWAYS use Dev agent for implementation** - Never use bmad-master/orchestrator
+- **Why this matters**: SM and Dev agents are specifically optimized for the development workflow
+- **No exceptions**: Even if using bmad-master for everything else, switch to SM → Dev for implementation
+
+**Best Practice for IDE-Only**:
+1. Use PM/Architect/UX agents for planning (better than bmad-master)
+2. Create documents directly in project
+3. Shard immediately after creation
+4. **MUST switch to SM agent** for story creation
+5. **MUST switch to Dev agent** for implementation
+6. Keep planning and coding in separate chat sessions
+
+## Core Configuration (core-config.yml)
+
+**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.
+
+### What is core-config.yml?
+
+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
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+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
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy

 ### Vibe CEO'ing
@@ -33,15 +239,509 @@ You are the "Vibe CEO" - thinking like a CEO with unlimited resources and a sing
 7. **START_SMALL_SCALE_FAST**: Test concepts, then expand.
 8. **EMBRACE_THE_CHAOS**: Adapt and overcome challenges.

-## IDE Development Workflow
+### Key Workflow Principles

-1. Shard the PRD (And Architecture documents if they exist also based on workflow type) using the Doc Shard task. The BMad-Master agent can help you do this. You will select the task, provide the doc to shard and the output folder. for example: `BMad Master, please Shard the docs/prd.md to the doc/prd/ folder` - this should ask you to use the md-tree-parser which is recommended, but either way shoudl result in multiple documents being created in the folder docs/prd.
-2. If you have fullstack, front end and or back end architecture documents you will want to follow the same thing, but shard all of these to an architecture folder instead of a prd folder.
-3. Ensure that you have at least one epic-n.md file in your prd folder, with the stories in order to develop.
-4. The docs or architecture folder or prd folder should have a source tree document and coding standards at a minimum. These are used by the dev agent, and the many other sharded docs are used by the SM agent.
-5. Use a new chat window to allow the SM agent to `draft the next story`.
-6. If you agree the story is correct, mark it as approved in the status field, and then start a new chat window with the dev agent.
-7. Ask the dev agent to implement the next story. If you draft the story file into the chat it will save time for the dev to have to find what the next one is. The dev should follow the tasks and subtasks marking them off as they are completed. The dev agent will also leave notes potentially for the SM to know about any deviations that might have occured to help draft the next story.
-8. Once complete and you have verified, mark it done, and start a new chat. Ask the SM to draft the next story - repeating the cycle.
+1. **Agent Specialization**: Each agent has specific expertise and responsibilities
+2. **Clean Handoffs**: Always start fresh when switching between agents
+3. **Status Tracking**: Maintain story statuses (Draft → Approved → InProgress → Done)
+4. **Iterative Development**: Complete one story before starting the next
+5. **Documentation First**: Always start with solid PRD and architecture

-With this work flow, there is only 1 story in progress at a time, worked sequentially.
+## 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           |
+
+### Meta Agents
+
+| Agent               | Role             | Primary Functions                     | When to Use                       |
+| ------------------- | ---------------- | ------------------------------------- | --------------------------------- |
+| `bmad-orchestrator` | Team Coordinator | Multi-agent workflows, role switching | Complex multi-role tasks          |
+| `bmad-master`       | Universal Expert | All capabilities without switching    | Single-session comprehensive work |
+
+### Agent Interaction Commands
+
+#### IDE-Specific Syntax
+
+**Agent Loading by IDE**:
+- **Claude Code**: `/agent-name` (e.g., `/bmad-master`)
+- **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`)
+
+**Chat Management Guidelines**:
+- **Claude Code, Cursor, Windsurf**: Start new chats when switching agents
+- **Roo Code**: Switch modes within the same conversation
+
+**Common Task Commands**:
+- `*help` - Show available commands
+- `*status` - Show current context/progress
+- `*exit` - Exit the agent mode
+- `*shard-doc docs/prd.md prd` - Shard PRD into manageable pieces
+- `*shard-doc docs/architecture.md architecture` - Shard architecture document
+- `*create` - Run create-next-story task (SM agent)
+
+**In Web UI**:
+```text
+/pm create-doc prd
+/architect review system design
+/dev implement story 1.2
+/help - Show available commands
+/switch agent-name - Change active agent (if orchestrator available)
+```
+
+## 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`
+
+## Core Architecture
+
+### 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).
+
+### Key Architectural Components
+
+#### 1. Agents (`bmad-core/agents/`)
+- **Purpose**: Each markdown file defines a specialized AI agent for a specific Agile role (PM, Dev, Architect, etc.)
+- **Structure**: Contains YAML headers specifying the agent's persona, capabilities, and dependencies
+- **Dependencies**: Lists of tasks, templates, checklists, and data files the agent can use
+- **Startup Instructions**: Can load project-specific documentation for immediate context
+
+#### 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)
+- **Usage**: Creates pre-packaged contexts for web UI environments
+
+#### 3. Workflows (`bmad-core/workflows/`)
+- **Purpose**: YAML files defining prescribed sequences of steps for specific project types
+- **Types**: Greenfield (new projects) and Brownfield (existing projects) for UI, service, and fullstack development
+- **Structure**: Defines agent interactions, artifacts created, and transition conditions
+
+#### 4. Reusable Resources
+- **Templates** (`bmad-core/templates/`): Markdown templates for PRDs, architecture specs, user stories
+- **Tasks** (`bmad-core/tasks/`): Instructions for specific repeatable actions like "shard-doc" or "create-next-story"
+- **Checklists** (`bmad-core/checklists/`): Quality assurance checklists for validation and review
+- **Data** (`bmad-core/data/`): Core knowledge base and technical preferences
+
+### Dual Environment Architecture
+
+#### IDE Environment
+
+- Users interact directly with agent markdown files
+- Agents can access all dependencies dynamically
+- Supports real-time file operations and project integration
+- Optimized for development workflow execution
+
+#### Web UI Environment
+
+- Uses pre-built bundles from `dist/teams` for stand alone 1 upload files for all agents and their assest with an orchestrating agent
+- Single text files containing all agent dependencies are in `dist/agents/` - these are unnecessary unless you want to create a web agent that is only a single agent and not a team
+- Created by the web-builder tool for upload to web interfaces
+- Provides complete context in one package
+
+### Template Processing System
+
+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
+3. **Advanced Elicitation** (`tasks/advanced-elicitation.md`): Provides interactive refinement through structured brainstorming
+
+**Template Features**:
+
+- **Self-contained**: Templates embed both output structure and processing instructions
+- **Variable Substitution**: `{{placeholders}}` for dynamic content
+- **AI Processing Directives**: `[[LLM: instructions]]` for AI-only processing
+- **Interactive Refinement**: Built-in elicitation processes for quality improvement
+
+### Technical Preferences Integration
+
+The `technical-preferences.md` file serves as a persistent technical profile that:
+- Ensures consistency across all agents and projects
+- Eliminates repetitive technology specification
+- Provides personalized recommendations aligned with user preferences
+- Evolves over time with lessons learned
+
+### Build and Delivery Process
+
+The `web-builder.js` tool creates web-ready bundles by:
+1. Reading agent or team definition files
+2. Recursively resolving all dependencies
+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.
+
+## Complete Development Workflow
+
+### Planning Phase (Web UI Recommended - Especially Gemini!)
+
+**Ideal for cost efficiency with Gemini's massive context:**
+
+**For Brownfield Projects - Start Here!**:
+1. **Upload entire project to Gemini Web** (GitHub URL, files, or zip)
+2. **Document existing system**: `/analyst` → `*document-project`
+3. **Creates comprehensive docs** from entire codebase analysis
+
+**For All Projects**:
+1. **Optional Analysis**: `/analyst` - Market research, competitive analysis
+2. **Project Brief**: Create foundation document (Analyst or user)
+3. **PRD Creation**: `/pm create-doc prd` - Comprehensive product requirements
+4. **Architecture Design**: `/architect create-doc architecture` - Technical foundation
+5. **Validation & Alignment**: `/po` run master checklist to ensure document consistency
+6. **Document Preparation**: Copy final documents to project as `docs/prd.md` and `docs/architecture.md`
+
+#### Example Planning Prompts
+
+**For PRD Creation**:
+```text
+"I want to build a [type] application that [core purpose].
+Help me brainstorm features and create a comprehensive PRD."
+```
+
+**For Architecture Design**:
+```text
+"Based on this PRD, design a scalable technical architecture
+that can handle [specific requirements]."
+```
+
+### Critical Transition: Web UI to IDE
+
+**Once planning is complete, you MUST switch to IDE for development:**
+
+- **Why**: Development workflow requires file operations, real-time project integration, and document sharding
+- **Cost Benefit**: Web UI is more cost-effective for large document creation; IDE is optimized for development tasks
+- **Required Files**: Ensure `docs/prd.md` and `docs/architecture.md` exist in your project
+
+### IDE Development Workflow
+
+**Prerequisites**: Planning documents must exist in `docs/` folder
+
+1. **Document Sharding** (CRITICAL STEP): 
+   - Documents created by PM/Architect (in Web or IDE) MUST be sharded for development
+   - Two methods to shard:
+     a) **Manual**: Drag `shard-doc` task + document file into chat
+     b) **Agent**: Ask `@bmad-master` or `@po` to shard documents
+   - Shards `docs/prd.md` → `docs/prd/` folder
+   - Shards `docs/architecture.md` → `docs/architecture/` folder
+   - **WARNING**: Do NOT shard in Web UI - copying many small files is painful!
+
+2. **Verify Sharded Content**:
+   - At least one `epic-n.md` file in `docs/prd/` with stories in development order
+   - Source tree document and coding standards for dev agent reference
+   - Sharded docs for SM agent story creation
+
+**Resulting Folder Structure**:
+- `docs/prd/` - Broken down PRD sections
+- `docs/architecture/` - Broken down architecture sections
+- `docs/stories/` - Generated user stories
+
+3. **Development Cycle** (Sequential, one story at a time):
+
+   **CRITICAL CONTEXT MANAGEMENT**:
+   - **Context windows matter!** Always use fresh, clean context windows
+   - **Model selection matters!** Use most powerful thinking model for SM story creation
+   - **ALWAYS start new chat between SM, Dev, and QA work**
+
+   **Step 1 - Story Creation**: 
+   - **NEW CLEAN CHAT** → Select powerful model → `@sm` → `*create`
+   - SM executes create-next-story task
+   - Review generated story in `docs/stories/`
+   - Update status from "Draft" to "Approved"
+   
+   **Step 2 - Story Implementation**: 
+   - **NEW CLEAN CHAT** → `@dev`
+   - Agent asks which story to implement
+   - Include story file content to save dev agent lookup time
+   - Dev follows tasks/subtasks, marking completion
+   - Dev maintains File List of all changes
+   - Dev marks story as "Review" when complete with all tests passing
+   
+   **Step 3 - Senior QA Review**:
+   - **NEW CLEAN CHAT** → `@qa` → execute review-story task
+   - QA performs senior developer code review
+   - QA can refactor and improve code directly
+   - QA appends results to story's QA Results section
+   - If approved: Status → "Done"
+   - If changes needed: Status stays "Review" with unchecked items for dev
+   
+   **Step 4 - Repeat**: Continue SM → Dev → QA cycle until all epic stories complete
+
+**Important**: Only 1 story in progress at a time, worked sequentially until all epic stories complete.
+
+### Status Tracking Workflow
+
+Stories progress through defined statuses:
+- **Draft** → **Approved** → **InProgress** → **Done**
+
+Each status change requires user verification and approval before proceeding.
+
+### Workflow Types
+
+#### Greenfield Development
+- Business analysis and market research
+- Product requirements and feature definition  
+- System architecture and design
+- Development execution
+- Testing and deployment
+
+#### Brownfield Enhancement (Existing Projects)
+
+**Key Concept**: Brownfield development requires comprehensive documentation of your existing project for AI agents to understand context, patterns, and constraints.
+
+**Complete Brownfield Workflow Options**:
+
+**Option 1: PRD-First (Recommended for Large Codebases/Monorepos)**:
+1. **Upload project to Gemini Web** (GitHub URL, files, or zip)
+2. **Create PRD first**: `@pm` → `*create-doc brownfield-prd`
+3. **Focused documentation**: `@analyst` → `*document-project`
+   - Analyst asks for focus if no PRD provided
+   - Choose "single document" format for Web UI
+   - Uses PRD to document ONLY relevant areas
+   - Creates one comprehensive markdown file
+   - Avoids bloating docs with unused code
+
+**Option 2: Document-First (Good for Smaller Projects)**:
+1. **Upload project to Gemini Web**
+2. **Document everything**: `@analyst` → `*document-project`
+3. **Then create PRD**: `@pm` → `*create-doc brownfield-prd`
+   - More thorough but can create excessive documentation
+
+2. **Requirements Gathering**:
+   - **Brownfield PRD**: Use PM agent with `brownfield-prd-tmpl`
+   - **Analyzes**: Existing system, constraints, integration points
+   - **Defines**: Enhancement scope, compatibility requirements, risk assessment
+   - **Creates**: Epic and story structure for changes
+
+3. **Architecture Planning**:
+   - **Brownfield Architecture**: Use Architect agent with `brownfield-architecture-tmpl`
+   - **Integration Strategy**: How new features integrate with existing system
+   - **Migration Planning**: Gradual rollout and backwards compatibility
+   - **Risk Mitigation**: Addressing potential breaking changes
+
+**Brownfield-Specific Resources**:
+
+**Templates**:
+- `brownfield-prd-tmpl.md`: Comprehensive enhancement planning with existing system analysis
+- `brownfield-architecture-tmpl.md`: Integration-focused architecture for existing systems
+
+**Tasks**:
+- `document-project`: Generates comprehensive documentation from existing codebase
+- `brownfield-create-epic`: Creates single epic for focused enhancements (when full PRD is overkill)
+- `brownfield-create-story`: Creates individual story for small, isolated changes
+
+**When to Use Each Approach**:
+
+**Full Brownfield Workflow** (Recommended for):
+- Major feature additions
+- System modernization
+- Complex integrations
+- Multiple related changes
+
+**Quick Epic/Story Creation** (Use when):
+- Single, focused enhancement
+- Isolated bug fixes
+- Small feature additions
+- Well-documented existing system
+
+**Critical Success Factors**:
+1. **Documentation First**: Always run `document-project` if docs are outdated/missing
+2. **Context Matters**: Provide agents access to relevant code sections
+3. **Integration Focus**: Emphasize compatibility and non-breaking changes
+4. **Incremental Approach**: Plan for gradual rollout and testing
+
+**For detailed guide**: See `docs/working-in-the-brownfield.md`
+
+## Document Creation Best Practices
+
+### Required File Naming for Framework Integration
+
+- `docs/prd.md` - Product Requirements Document
+- `docs/architecture.md` - System Architecture Document
+
+**Why These Names Matter**:
+- Agents automatically reference these files during development
+- Sharding tasks expect these specific filenames
+- Workflow automation depends on standard naming
+
+### Cost-Effective Document Creation Workflow
+
+**Recommended for Large Documents (PRD, Architecture):**
+
+1. **Use Web UI**: Create documents in web interface for cost efficiency
+2. **Copy Final Output**: Save complete markdown to your project
+3. **Standard Names**: Save as `docs/prd.md` and `docs/architecture.md`
+4. **Switch to IDE**: Use IDE agents for development and smaller documents
+
+### Document Sharding
+
+Templates with Level 2 headings (`##`) can be automatically sharded:
+
+**Original PRD**:
+```markdown
+## Goals and Background Context
+## Requirements  
+## User Interface Design Goals
+## Success Metrics
+```
+
+**After Sharding**:
+- `docs/prd/goals-and-background-context.md`
+- `docs/prd/requirements.md`
+- `docs/prd/user-interface-design-goals.md`
+- `docs/prd/success-metrics.md`
+
+Use the `shard-doc` task or `@kayvan/markdown-tree-parser` tool for automatic sharding.
+
+## Usage Patterns and Best Practices
+
+### Environment-Specific Usage
+
+**Web UI Best For**:
+- Initial planning and documentation phases
+- Cost-effective large document creation
+- Agent consultation and brainstorming
+- Multi-agent workflows with orchestrator
+
+**IDE Best For**:
+- Active development and implementation
+- File operations and project integration
+- Story management and development cycles
+- Code review and debugging
+
+### Quality Assurance
+
+- Use appropriate agents for specialized tasks
+- Follow Agile ceremonies and review processes
+- Maintain document consistency with PO agent
+- Regular validation with checklists and templates
+
+### Performance Optimization
+
+- Use specific agents vs. `bmad-master` for focused tasks
+- Choose appropriate team size for project needs
+- Leverage technical preferences for consistency
+- Regular context management and cache clearing
+
+## Success Tips
+
+- **Use Gemini for big picture planning** - The team-fullstack bundle provides collaborative expertise
+- **Use bmad-master for document organization** - Sharding creates manageable chunks
+- **Follow the SM → Dev cycle religiously** - This ensures systematic progress
+- **Keep conversations focused** - One agent, one task per conversation
+- **Review everything** - Always review and approve before marking complete
+
+## Contributing to BMAD-METHOD
+
+### Quick Contribution Guidelines
+
+For full details, see `CONTRIBUTING.md`. Key points:
+
+**Fork Workflow**:
+1. Fork the repository
+2. Create feature branches
+3. Submit PRs to `next` branch (default) or `main` for critical fixes only
+4. Keep PRs small: 200-400 lines ideal, 800 lines maximum
+5. One feature/fix per PR
+
+**PR Requirements**:
+- Clear descriptions (max 200 words) with What/Why/How/Testing
+- Use conventional commits (feat:, fix:, docs:)
+- Atomic commits - one logical change per commit
+- Must align with guiding principles
+
+**Core Principles** (from GUIDING-PRINCIPLES.md):
+- **Dev Agents Must Be Lean**: Minimize dependencies, save context for code
+- **Natural Language First**: Everything in markdown, no code in core
+- **Core vs Expansion Packs**: Core for universal needs, packs for specialized domains
+- **Design Philosophy**: "Dev agents code, planning agents plan"
+
+## Expansion Packs
+
+### 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.
+
+### Why Use Expansion Packs?
+
+1. **Keep Core Lean**: Dev agents maintain maximum context for coding
+2. **Domain Expertise**: Deep, specialized knowledge without bloating core
+3. **Community Innovation**: Anyone can create and share packs
+4. **Modular Design**: Install only what you need
+
+### Available Expansion Packs
+
+**Technical Packs**:
+- **Infrastructure/DevOps**: Cloud architects, SRE experts, security specialists
+- **Game Development**: Game designers, level designers, narrative writers
+- **Mobile Development**: iOS/Android specialists, mobile UX experts
+- **Data Science**: ML engineers, data scientists, visualization experts
+
+**Non-Technical Packs**:
+- **Business Strategy**: Consultants, financial analysts, marketing strategists
+- **Creative Writing**: Plot architects, character developers, world builders
+- **Health & Wellness**: Fitness trainers, nutritionists, habit engineers
+- **Education**: Curriculum designers, assessment specialists
+- **Legal Support**: Contract analysts, compliance checkers
+
+**Specialty Packs**:
+- **Expansion Creator**: Tools to build your own expansion packs
+- **RPG Game Master**: Tabletop gaming assistance
+- **Life Event Planning**: Wedding planners, event coordinators
+- **Scientific Research**: Literature reviewers, methodology designers
+
+### Using Expansion Packs
+
+1. **Browse Available Packs**: Check `expansion-packs/` directory
+2. **Get Inspiration**: See `docs/expansion-packs.md` for detailed examples and ideas
+3. **Install via CLI**: 
+   ```bash
+   npx bmad-method install
+   # Select "Install expansion pack" option
+   ```
+4. **Use in Your Workflow**: Installed packs integrate seamlessly with existing agents
+
+### Creating Custom Expansion Packs
+
+Use the **expansion-creator** pack to build your own:
+
+1. **Define Domain**: What expertise are you capturing?
+2. **Design Agents**: Create specialized roles with clear boundaries
+3. **Build Resources**: Tasks, templates, checklists for your domain
+4. **Test & Share**: Validate with real use cases, share with community
+
+**Key Principle**: Expansion packs democratize expertise by making specialized knowledge accessible through AI agents.
+
+## Getting Help
+
+- **Commands**: Use `/help` in any environment to see available commands
+- **Agent Switching**: Use `/switch agent-name` with orchestrator for role changes
+- **Documentation**: Check `docs/` folder for project-specific context
+- **Community**: Discord and GitHub resources available for support
+- **Contributing**: See `CONTRIBUTING.md` for full guidelines
--- a/bmad-core/tasks/core-dump.md
+++ b/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
--- a/bmad-core/tasks/create-doc.md
+++ b/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
--- a/bmad-core/tasks/create-next-story.md
+++ b/bmad-core/tasks/create-next-story.md
@@ -4,45 +4,42 @@

 To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Story Template`. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research.

-## Inputs for this Task
-
- Access to the project's documentation repository, specifically:
-  - `docs/index.md` (hereafter "Index Doc")
-  - All Epic files - located in one of these locations:
-    - Primary: `docs/prd/epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
-    - Secondary: `docs/epics/epic-{n}-{description}.md`
-    - User-specified location if not found in above paths
-  - Existing story files in `docs/stories/`
-  - Main PRD (hereafter "PRD Doc")
-  - Main Architecture Document (hereafter "Main Arch Doc")
-  - Frontend Architecture Document (hereafter "Frontend Arch Doc," if relevant)
-  - Project Structure Guide (`docs/project-structure.md`)
-  - Operational Guidelines Document (`docs/operational-guidelines.md`)
-  - Technology Stack Document (`docs/tech-stack.md`)
-  - Data Models Document (as referenced in Index Doc)
-  - API Reference Document (as referenced in Index Doc)
-  - UI/UX Specifications, Style Guides, Component Guides (if relevant, as referenced in Index Doc)
- The `bmad-core/templates/story-tmpl.md` (hereafter "Story Template")
- The `bmad-core/checklists/story-draft-checklist.md` (hereafter "Story Draft Checklist")
- User confirmation to proceed with story identification and, if needed, to override warnings about incomplete prerequisite stories.
-
 ## Task Execution Instructions

+### 0. Load Core Configuration
+
+[[LLM: CRITICAL - This MUST be your first step]]
+
+- Load `.bmad-core/core-config.yml` 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."
+- Extract the following key configurations:
+  - `devStoryLocation`: Where to save story files
+  - `prd.prdSharded`: Whether PRD is sharded or monolithic
+  - `prd.prdFile`: Location of monolithic PRD (if not sharded)
+  - `prd.prdShardedLocation`: Location of sharded epic files
+  - `prd.epicFilePattern`: Pattern for epic files (e.g., `epic-{n}*.md`)
+  - `architecture.architectureVersion`: Architecture document version
+  - `architecture.architectureSharded`: Whether architecture is sharded
+  - `architecture.architectureFile`: Location of monolithic architecture
+  - `architecture.architectureShardedLocation`: Location of sharded architecture files
+
 ### 1. Identify Next Story for Preparation

 #### 1.1 Locate Epic Files

- First, determine where epic files are located:
-  - Check `docs/prd/` for files matching pattern `epic-{n}-*.md`
-  - If not found, check `docs/epics/` for files matching pattern `epic-{n}-*.md`
-  - If still not found, ask user: "Unable to locate epic files. Please specify the path where epic files are stored."
- Note: Epic files follow naming convention `epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
+- Based on `prdSharded` from config:
+  - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
+  - **If `prdSharded: false`**: Load the full PRD from `prdFile` and extract epics from section headings (## Epic N or ### Epic N)

 #### 1.2 Review Existing Stories

- Review `docs/stories/` to find the highest-numbered story file.
+- Check `devStoryLocation` from config (e.g., `docs/stories/`) for existing story files
+- If the directory exists and has at least 1 file, find the highest-numbered story file.
 - **If a highest story file exists (`{lastEpicNum}.{lastStoryNum}.story.md`):**
-
  - Verify its `Status` is 'Done' (or equivalent).
  - If not 'Done', present an alert to the user:

@@ -60,17 +57,45 @@ To identify the next logical story based on project progress and epic definition
    ```

  - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}-*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}-*.md`, then `epic-{lastEpicNum + 2}-*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.

 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".

-### 2. Gather Core Story Requirements (from Epic File)
+### 2. Gather Core Story Requirements (from Epic)

- For the identified story, open its parent Epic File (e.g., `epic-{epicNum}-*.md` from the location identified in step 1.1).
+- For the identified story, review its parent Epic (e.g., `epic-{epicNum}*.md` from the location identified in step 1.1).
 - Extract: Exact Title, full Goal/User Story statement, initial list of Requirements, all Acceptance Criteria (ACs), and any predefined high-level Tasks.
 - Keep a record of this original epic-defined scope for later deviation analysis.

@@ -79,7 +104,7 @@ To identify the next logical story based on project progress and epic definition
 [[LLM: This step is CRITICAL for continuity and learning from implementation experience]]

 - If this is not the first story (i.e., previous story exists):
-  - Read the previous story file: `docs/stories/{prevEpicNum}.{prevStoryNum}.story.md`
+  - Read the previous sequential story from `docs/stories`
  - Pay special attention to:
    - Dev Agent Record sections (especially Completion Notes and Debug Log References)
    - Any deviations from planned implementation
@@ -88,18 +113,30 @@ To identify the next logical story based on project progress and epic definition
    - Any "lessons learned" or notes for future stories
  - Extract relevant insights that might inform the current story's preparation

-### 4. Gather & Synthesize Architecture Context from Sharded Docs
+### 4. Gather & Synthesize Architecture Context

-[[LLM: CRITICAL - You MUST gather technical details from the sharded architecture documents. NEVER make up technical details not found in these documents.]]
+[[LLM: CRITICAL - You MUST gather technical details from the architecture documents. NEVER make up technical details not found in these documents.]]

-#### 4.1 Start with Architecture Index
+#### 4.1 Determine Architecture Document Strategy

- Read `docs/architecture/index.md` to understand the full scope of available documentation
- Identify which sharded documents are most relevant to the current story
+Based on configuration loaded in Step 0:

-#### 4.2 Recommended Reading Order Based on Story Type
+- **If `architectureVersion: v4` and `architectureSharded: true`**:
+  - Read `{architectureShardedLocation}/index.md` to understand available documentation
+  - Follow the structured reading order in section 4.2 below
  
-[[LLM: Read documents in this order, but ALWAYS verify relevance to the specific story. Skip irrelevant sections but NEVER skip documents that contain information needed for the story.]]
+- **If `architectureVersion: v4` and `architectureSharded: false`**:
+  - Load the monolithic architecture from `architectureFile`
+  - Extract relevant sections based on v4 structure (tech stack, project structure, etc.)
+  
+- **If `architectureVersion` is NOT v4**:
+  - Inform user: "Architecture document is not v4 format. Will use best judgment to find relevant information."
+  - If `architectureSharded: true`: Search sharded files by filename relevance
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
+
+#### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
+
+[[LLM: Use this structured approach ONLY for v4 sharded architecture. For other versions, use best judgment based on file names and content.]]

 **For ALL Stories:**

@@ -108,9 +145,18 @@ To identify the next logical story based on project progress and epic definition
 3. `docs/architecture/coding-standards.md` - Ensure dev follows project conventions
 4. `docs/architecture/testing-strategy.md` - Include testing requirements in tasks

-**For Backend/API Stories, additionally read:** 5. `docs/architecture/data-models.md` - Data structures and validation rules 6. `docs/architecture/database-schema.md` - Database design and relationships 7. `docs/architecture/backend-architecture.md` - Service patterns and structure 8. `docs/architecture/rest-api-spec.md` - API endpoint specifications 9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)
+**For Backend/API Stories, additionally read:**
+5. `docs/architecture/data-models.md` - Data structures and validation rules
+6. `docs/architecture/database-schema.md` - Database design and relationships
+7. `docs/architecture/backend-architecture.md` - Service patterns and structure
+8. `docs/architecture/rest-api-spec.md` - API endpoint specifications
+9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)

-**For Frontend/UI Stories, additionally read:** 5. `docs/architecture/frontend-architecture.md` - Component structure and patterns 6. `docs/architecture/components.md` - Specific component designs 7. `docs/architecture/core-workflows.md` - User interaction flows 8. `docs/architecture/data-models.md` - Frontend data handling
+**For Frontend/UI Stories, additionally read:**
+5. `docs/architecture/frontend-architecture.md` - Component structure and patterns
+6. `docs/architecture/components.md` - Specific component designs
+7. `docs/architecture/core-workflows.md` - User interaction flows
+8. `docs/architecture/data-models.md` - Frontend data handling

 **For Full-Stack Stories:**

@@ -143,7 +189,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`

 ### 6. Populate Story Template with Full Context

- Create a new story file: `docs/stories/{epicNum}.{storyNum}.story.md`.
+- Create a new story file: `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config).
 - Use the Story Template to structure the file.
 - Fill in:
  - Story `{EpicNum}.{StoryNum}: {Short Title Copied from Epic File}`
@@ -190,7 +236,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
- Save the story file to `docs/stories/{epicNum}.{storyNum}.story.md`
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)

 ### 9. Report Completion

--- a/bmad-core/tasks/doc-migration-task.md
+++ b/bmad-core/tasks/doc-migration-task.md
@@ -68,7 +68,7 @@ The epic numbering starts at 1 and increments for each epic found.

 ### Before (PRD):

-`````markdown
+```markdown
 # Product Requirements Document

 ## 1. Executive Summary
@@ -91,9 +91,10 @@ Epic content...

 Content here...

-````text
+```

 ### After (PRD):
+
 ```markdown
 # Product Requirements Document

@@ -113,9 +114,11 @@ Epic content...

 ## Success Metrics
 Content here...
-```text
+
+```

 ### Before (Non-PRD):
+
 ```markdown
 # Architecture Document

@@ -124,9 +127,10 @@ Content...

 ## 2.1 Technical Stack & Tools
 Content...
-```text
+```

 ### After (Non-PRD):
+
 ```markdown
 # Architecture Document

@@ -135,9 +139,5 @@ Content...

 ## Technical Stack Tools
 Content...
-````
-`````
-
-```text

 ```
--- a/bmad-core/tasks/document-project.md
+++ b/bmad-core/tasks/document-project.md
@@ -8,7 +8,39 @@ Generate comprehensive documentation for existing projects optimized for AI deve

 ### 1. Initial Project Analysis

-[[LLM: Begin by conducting a comprehensive analysis of the existing project. Use available tools to:
+[[LLM: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
+
+**IF PRD EXISTS**: 
+
+- Review the PRD to understand what enhancement/feature is planned
+- Identify which modules, services, or areas will be affected
+- Focus documentation ONLY on these relevant areas
+- Skip unrelated parts of the codebase to keep docs lean
+
+**IF NO PRD EXISTS**:
+Ask the user:
+
+"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
+
+1. **Create a PRD first** - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
+
+2. **Provide existing requirements** - Do you have a requirements document, epic, or feature description you can share?
+
+3. **Describe the focus** - Can you briefly describe what enhancement or feature you're planning? For example:
+   - 'Adding payment processing to the user service'
+   - 'Refactoring the authentication module'
+   - 'Integrating with a new third-party API'
+
+4. **Document everything** - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
+
+Please let me know your preference, or I can proceed with full documentation if you prefer."
+
+Based on their response:
+
+- If they choose option 1-3: Use that context to focus documentation
+- If they choose option 4 or decline: Proceed with comprehensive analysis below
+
+Begin by conducting analysis of the existing project. Use available tools to:

 1. **Project Structure Discovery**: Examine the root directory structure, identify main folders, and understand the overall organization
 2. **Technology Stack Identification**: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
@@ -23,367 +55,263 @@ Ask the user these elicitation questions to better understand their needs:
 - What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
 - Are there any existing documentation standards or formats you prefer?
 - What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
+- Is there a specific feature or enhancement you're planning? (This helps focus documentation)
  ]]

-### 2. Core Documentation Generation
+### 2. Deep Codebase Analysis

-[[LLM: Based on your analysis, generate the following core documentation files. Adapt the content and structure to match the specific project type and context you discovered:
+[[LLM: Before generating documentation, conduct extensive analysis of the existing codebase:

-**Core Documents (always generate):**
+1. **Explore Key Areas**:
+   - Entry points (main files, index files, app initializers)
+   - Configuration files and environment setup
+   - Package dependencies and versions
+   - Build and deployment configurations
+   - Test suites and coverage

-1. **docs/index.md** - Master documentation index
-2. **docs/architecture/index.md** - Architecture documentation index
-3. **docs/architecture/coding-standards.md** - Coding conventions and style guidelines
-4. **docs/architecture/tech-stack.md** - Technology stack and version constraints
-5. **docs/architecture/unified-project-structure.md** - Project structure and organization
-6. **docs/architecture/testing-strategy.md** - Testing approaches and requirements
+2. **Ask Clarifying Questions**:
+   - "I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
+   - "What are the most critical/complex parts of this system that developers struggle with?"
+   - "Are there any undocumented 'tribal knowledge' areas I should capture?"
+   - "What technical debt or known issues should I document?"
+   - "Which parts of the codebase change most frequently?"

-**Backend Documents (generate for backend/full-stack projects):**
+3. **Map the Reality**:
+   - Identify ACTUAL patterns used (not theoretical best practices)
+   - Find where key business logic lives
+   - Locate integration points and external dependencies
+   - Document workarounds and technical debt
+   - Note areas that differ from standard patterns

-7. **docs/architecture/backend-architecture.md** - Backend service patterns and structure
-8. **docs/architecture/rest-api-spec.md** - API endpoint specifications
-9. **docs/architecture/data-models.md** - Data structures and validation rules
-10. **docs/architecture/database-schema.md** - Database design and relationships
-11. **docs/architecture/external-apis.md** - Third-party integrations
+**IF PRD PROVIDED**: Also analyze what would need to change for the enhancement]]

-**Frontend Documents (generate for frontend/full-stack projects):**
+### 3. Core Documentation Generation

-12. **docs/architecture/frontend-architecture.md** - Frontend patterns and structure
-13. **docs/architecture/components.md** - UI component specifications
-14. **docs/architecture/core-workflows.md** - User interaction flows
-15. **docs/architecture/ui-ux-spec.md** - UI/UX specifications and guidelines
+[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.

-**Additional Documents (generate if applicable):**
+**CRITICAL**: This is NOT an aspirational architecture document. Document what EXISTS, including:
+- Technical debt and workarounds
+- Inconsistent patterns between different parts
+- Legacy code that can't be changed
+- Integration constraints
+- Performance bottlenecks

-16. **docs/prd.md** - Product requirements document (if not exists)
-17. **docs/architecture/deployment-guide.md** - Deployment and operations info
-18. **docs/architecture/security-considerations.md** - Security patterns and requirements
-19. **docs/architecture/performance-guidelines.md** - Performance optimization patterns
+**Document Structure**:

-**Optional Enhancement Documents:**
+# [Project Name] Brownfield Architecture Document

-20. **docs/architecture/troubleshooting-guide.md** - Common issues and solutions
-21. **docs/architecture/changelog-conventions.md** - Change management practices
-22. **docs/architecture/code-review-checklist.md** - Review standards and practices
+## Introduction
+This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.

-Present each document section by section, using the advanced elicitation task after each major section.]]
+### Document Scope
+[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
+[If no PRD: "Comprehensive documentation of entire system"]

-### 3. Document Structure Template
+### Change Log
+| Date | Version | Description | Author |
+|------|---------|-------------|--------|
+| [Date] | 1.0 | Initial brownfield analysis | [Analyst] |

-[[LLM: Use this standardized structure for each documentation file, adapting content as needed:
+## Quick Reference - Key Files and Entry Points

-```markdown
-# {{Document Title}}
+### Critical Files for Understanding the System
+- **Main Entry**: `src/index.js` (or actual entry point)
+- **Configuration**: `config/app.config.js`, `.env.example`
+- **Core Business Logic**: `src/services/`, `src/domain/`
+- **API Definitions**: `src/routes/` or link to OpenAPI spec
+- **Database Models**: `src/models/` or link to schema files
+- **Key Algorithms**: [List specific files with complex logic]

-## Overview
+### If PRD Provided - Enhancement Impact Areas
+[Highlight which files/modules will be affected by the planned enhancement]

-{{Brief description of what this document covers and why it's important for AI agents}}
+## High Level Architecture

-## Quick Reference
+### Technical Summary
+[Real assessment of architecture - mention if it's well-structured or has issues]

-{{Key points, commands, or patterns that agents need most frequently}}
+### Actual Tech Stack (from package.json/requirements.txt)
+| Category | Technology | Version | Notes |
+|----------|------------|---------|--------|
+| Runtime | Node.js | 16.x | [Any constraints] |
+| Framework | Express | 4.18.2 | [Custom middleware?] |
+| Database | PostgreSQL | 13 | [Connection pooling setup] |
+| [etc...] |

-## Detailed Information
+### Repository Structure Reality Check
+- Type: [Monorepo/Polyrepo/Hybrid]
+- Package Manager: [npm/yarn/pnpm]
+- Notable: [Any unusual structure decisions]

-{{Comprehensive information organized into logical sections}}
+## Source Tree and Module Organization

-## Examples
-
-{{Concrete examples showing proper usage or implementation}}
-
-## Common Patterns
-
-{{Recurring patterns agents should recognize and follow}}
-
-## Things to Avoid
-
-{{Anti-patterns, deprecated approaches, or common mistakes}}
-
-## Related Resources
-
-{{Links to other relevant documentation or external resources}}
+### Project Structure (Actual)
+```
+project-root/
+├── src/
+│   ├── controllers/     # HTTP request handlers
+│   ├── services/        # Business logic (NOTE: inconsistent patterns between user and payment services)
+│   ├── models/          # Database models (Sequelize)
+│   ├── utils/           # Mixed bag - needs refactoring
+│   └── legacy/          # DO NOT MODIFY - old payment system still in use
+├── tests/               # Jest tests (60% coverage)
+├── scripts/             # Build and deployment scripts
+└── config/              # Environment configs
 ```

-Each document should be:
-
- **Concrete and actionable** - Focus on what agents need to do, not just concepts
- **Pattern-focused** - Highlight recurring patterns agents can recognize and replicate
- **Example-rich** - Include specific code examples and real file references
- **Context-aware** - Reference actual project files, folders, and conventions
- **Assumption-free** - Don't assume agents know project history or implicit knowledge
-  ]]
-
-### 4. Content Guidelines for Each Document Type
-
-#### Core Architecture Documents
-
-##### docs/architecture/index.md
-
-[[LLM: Create a comprehensive index of all architecture documentation:
-
- List all architecture documents with brief descriptions
- Group documents by category (backend, frontend, shared)
- Include quick links to key sections
- Provide reading order recommendations for different use cases]]
-
-##### docs/architecture/unified-project-structure.md
-
-[[LLM: Document the complete project structure:
-
- Root-level directory structure with explanations
- Where each type of code belongs (backend, frontend, tests, etc.)
- File naming conventions and patterns
- Module/package organization
- Generated vs. source file locations
- Build output locations]]
-
-##### docs/architecture/coding-standards.md
-
-[[LLM: Capture project-wide coding conventions:
-
- Language-specific style guidelines
- Naming conventions (variables, functions, classes, files)
- Code organization within files
- Import/export patterns
- Comment and documentation standards
- Linting and formatting tool configurations
- Git commit message conventions]]
-
-##### docs/architecture/tech-stack.md
-
-[[LLM: Document all technologies and versions:
-
- Primary languages and versions
- Frameworks and major libraries with versions
- Development tools and their versions
- Database systems and versions
- External services and APIs used
- Browser/runtime requirements]]
-
-##### docs/architecture/testing-strategy.md
-
-[[LLM: Define testing approaches and requirements:
-
- Test file locations and naming conventions
- Unit testing patterns and frameworks
- Integration testing approaches
- E2E testing setup (if applicable)
- Test coverage requirements
- Mocking strategies
- Test data management]]
-
-#### Backend Architecture Documents
-
-##### docs/architecture/backend-architecture.md
-
-[[LLM: Document backend service structure:
-
- Service layer organization
- Controller/route patterns
- Middleware architecture
- Authentication/authorization patterns
- Request/response flow
- Background job processing
- Service communication patterns]]
-
-##### docs/architecture/rest-api-spec.md
-
-[[LLM: Specify all API endpoints:
-
- Base URL and versioning strategy
- Authentication methods
- Common headers and parameters
- Each endpoint with:
-  - HTTP method and path
-  - Request parameters/body
-  - Response format and status codes
-  - Error responses
- Rate limiting and quotas]]
-
-##### docs/architecture/data-models.md
-
-[[LLM: Define data structures and validation:
-
- Core business entities
- Data validation rules
- Relationships between entities
- Computed fields and derivations
- Data transformation patterns
- Serialization formats]]
-
-##### docs/architecture/database-schema.md
-
-[[LLM: Document database design:
-
- Database type and version
- Table/collection structures
- Indexes and constraints
- Relationships and foreign keys
- Migration patterns
- Seed data requirements
- Backup and recovery procedures]]
-
-##### docs/architecture/external-apis.md
-
-[[LLM: Document third-party integrations:
-
- List of external services used
- Authentication methods for each
- API endpoints and usage patterns
- Rate limits and quotas
- Error handling strategies
- Webhook configurations
- Data synchronization patterns]]
-
-#### Frontend Architecture Documents
-
-##### docs/architecture/frontend-architecture.md
-
-[[LLM: Document frontend application structure:
-
- Component hierarchy and organization
- State management patterns
- Routing architecture
- Data fetching patterns
- Authentication flow
- Error boundary strategies
- Performance optimization patterns]]
-
-##### docs/architecture/components.md
-
-[[LLM: Specify UI components:
-
- Component library/design system used
- Custom component specifications
- Props and state for each component
- Component composition patterns
- Styling approaches
- Accessibility requirements
- Component testing patterns]]
-
-##### docs/architecture/core-workflows.md
-
-[[LLM: Document user interaction flows:
-
- Major user journeys
- Screen flow diagrams
- Form handling patterns
- Navigation patterns
- Data flow through workflows
- Error states and recovery
- Loading and transition states]]
-
-##### docs/architecture/ui-ux-spec.md
-
-[[LLM: Define UI/UX guidelines:
-
- Design system specifications
- Color palette and typography
- Spacing and layout grids
- Responsive breakpoints
- Animation and transition guidelines
- Accessibility standards
- Browser compatibility requirements]]
-
-### 5. Adaptive Content Strategy
-
-[[LLM: Adapt your documentation approach based on project characteristics:
-
-**For Web Applications:**
-
- Focus on component patterns, routing, state management
- Include build processes, asset handling, and deployment
- Cover API integration patterns and data fetching
-
-**For Backend Services:**
-
- Emphasize service architecture, data models, and API design
- Include database interaction patterns and migration strategies
- Cover authentication, authorization, and security patterns
-
-**For CLI Tools:**
-
- Focus on command structure, argument parsing, and output formatting
- Include plugin/extension patterns if applicable
- Cover configuration file handling and user interaction patterns
-
-**For Libraries/Frameworks:**
-
- Emphasize public API design and usage patterns
- Include extension points and customization approaches
- Cover versioning, compatibility, and migration strategies
-
-**For Mobile Applications:**
-
- Focus on platform-specific patterns and navigation
- Include state management and data persistence approaches
- Cover platform integration and native feature usage
-
-**For Data Science/ML Projects:**
-
- Emphasize data pipeline patterns and model organization
- Include experiment tracking and reproducibility approaches
- Cover data validation and model deployment patterns
-  ]]
-
-### 6. Quality Assurance
-
-[[LLM: Before completing each document:
-
-1. **Accuracy Check**: Verify all file paths, commands, and code examples work
-2. **Completeness Review**: Ensure the document covers the most important patterns an agent would encounter
-3. **Clarity Assessment**: Check that explanations are clear and actionable
-4. **Consistency Verification**: Ensure terminology and patterns align across all documents
-5. **Agent Perspective**: Review from the viewpoint of an AI agent that needs to contribute to this project
-
-Ask the user to review each completed document and use the advanced elicitation task to refine based on their feedback.]]
-
-### 7. Final Integration
-
-[[LLM: After all documents are completed:
-
-1. Ensure all documents are created in the proper BMAD-expected locations:
-
-   - Core docs in `docs/` (index.md, prd.md)
-   - Architecture shards in `docs/architecture/` subdirectory
-   - Create the `docs/architecture/` directory if it doesn't exist
-
-2. Create/update the master index documents:
-
-   - Update `docs/index.md` to reference all documentation
-   - Create `docs/architecture/index.md` listing all architecture shards
-
-3. Verify document cross-references:
-
-   - Ensure all documents link to related documentation
-   - Check that file paths match the actual project structure
-   - Validate that examples reference real files in the project
-
-4. Provide maintenance guidance:
-
-   - Document update triggers (when to update each doc)
-   - Create a simple checklist for keeping docs current
-   - Suggest automated validation approaches
-
-5. Summary report including:
-   - List of all documents created with their paths
-   - Any gaps or areas needing human review
-   - Recommendations for project-specific additions
-   - Next steps for maintaining documentation accuracy
-
-Present a summary of what was created and ask if any additional documentation would be helpful for AI agents working on this specific project.]]
+### Key Modules and Their Purpose
+- **User Management**: `src/services/userService.js` - Handles all user operations
+- **Authentication**: `src/middleware/auth.js` - JWT-based, custom implementation
+- **Payment Processing**: `src/legacy/payment.js` - CRITICAL: Do not refactor, tightly coupled
+- **[List other key modules with their actual files]**
+
+## Data Models and APIs
+
+### Data Models
+Instead of duplicating, reference actual model files:
+- **User Model**: See `src/models/User.js`
+- **Order Model**: See `src/models/Order.js`
+- **Related Types**: TypeScript definitions in `src/types/`
+
+### API Specifications
+- **OpenAPI Spec**: `docs/api/openapi.yaml` (if exists)
+- **Postman Collection**: `docs/api/postman-collection.json`
+- **Manual Endpoints**: [List any undocumented endpoints discovered]
+
+## Technical Debt and Known Issues
+
+### Critical Technical Debt
+1. **Payment Service**: Legacy code in `src/legacy/payment.js` - tightly coupled, no tests
+2. **User Service**: Different pattern than other services, uses callbacks instead of promises
+3. **Database Migrations**: Manually tracked, no proper migration tool
+4. **[Other significant debt]**
+
+### Workarounds and Gotchas
+- **Environment Variables**: Must set `NODE_ENV=production` even for staging (historical reason)
+- **Database Connections**: Connection pool hardcoded to 10, changing breaks payment service
+- **[Other workarounds developers need to know]**
+
+## Integration Points and External Dependencies
+
+### External Services
+| Service | Purpose | Integration Type | Key Files |
+|---------|---------|------------------|-----------|
+| Stripe | Payments | REST API | `src/integrations/stripe/` |
+| SendGrid | Emails | SDK | `src/services/emailService.js` |
+| [etc...] |
+
+### Internal Integration Points
+- **Frontend Communication**: REST API on port 3000, expects specific headers
+- **Background Jobs**: Redis queue, see `src/workers/`
+- **[Other integrations]**
+
+## Development and Deployment
+
+### Local Development Setup
+1. Actual steps that work (not ideal steps)
+2. Known issues with setup
+3. Required environment variables (see `.env.example`)
+
+### Build and Deployment Process
+- **Build Command**: `npm run build` (webpack config in `webpack.config.js`)
+- **Deployment**: Manual deployment via `scripts/deploy.sh`
+- **Environments**: Dev, Staging, Prod (see `config/environments/`)
+
+## Testing Reality
+
+### Current Test Coverage
+- Unit Tests: 60% coverage (Jest)
+- Integration Tests: Minimal, in `tests/integration/`
+- E2E Tests: None
+- Manual Testing: Primary QA method
+
+### Running Tests
+```bash
+npm test           # Runs unit tests
+npm run test:integration  # Runs integration tests (requires local DB)
+```
+
+## If Enhancement PRD Provided - Impact Analysis
+
+### Files That Will Need Modification
+Based on the enhancement requirements, these files will be affected:
+- `src/services/userService.js` - Add new user fields
+- `src/models/User.js` - Update schema
+- `src/routes/userRoutes.js` - New endpoints
+- [etc...]
+
+### New Files/Modules Needed
+- `src/services/newFeatureService.js` - New business logic
+- `src/models/NewFeature.js` - New data model
+- [etc...]
+
+### Integration Considerations
+- Will need to integrate with existing auth middleware
+- Must follow existing response format in `src/utils/responseFormatter.js`
+- [Other integration points]
+
+## Appendix - Useful Commands and Scripts
+
+### Frequently Used Commands
+```bash
+npm run dev         # Start development server
+npm run build       # Production build
+npm run migrate     # Run database migrations
+npm run seed        # Seed test data
+```
+
+### Debugging and Troubleshooting
+- **Logs**: Check `logs/app.log` for application logs
+- **Debug Mode**: Set `DEBUG=app:*` for verbose logging
+- **Common Issues**: See `docs/troubleshooting.md`]]
+
+### 4. Document Delivery
+
+[[LLM: After generating the complete architecture document:
+
+1. **In Web UI (Gemini, ChatGPT, Claude)**:
+   - Present the entire document in one response (or multiple if too long)
+   - Tell user to copy and save as `docs/brownfield-architecture.md` or `docs/project-architecture.md`
+   - Mention it can be sharded later in IDE if needed
+
+2. **In IDE Environment**:
+   - Create the document as `docs/brownfield-architecture.md`
+   - Inform user this single document contains all architectural information
+   - Can be sharded later using PO agent if desired
+
+The document should be comprehensive enough that future agents can understand:
+- The actual state of the system (not idealized)
+- Where to find key files and logic
+- What technical debt exists
+- What constraints must be respected
+- If PRD provided: What needs to change for the enhancement]]
+
+### 5. Quality Assurance
+
+[[LLM: Before finalizing the document:
+
+1. **Accuracy Check**: Verify all technical details match the actual codebase
+2. **Completeness Review**: Ensure all major system components are documented
+3. **Focus Validation**: If user provided scope, verify relevant areas are emphasized
+4. **Clarity Assessment**: Check that explanations are clear for AI agents
+5. **Navigation**: Ensure document has clear section structure for easy reference
+
+Apply the advanced elicitation task after major sections to refine based on user feedback.]]

 ## Success Criteria

- Documentation enables AI agents to understand project context without additional explanation
- All major architectural patterns and coding conventions are captured
- Examples reference actual project files and demonstrate real usage
- Documentation is structured consistently and easy to navigate
- Content is actionable and focuses on what agents need to do, not just understand
+- Single comprehensive brownfield architecture document created
+- Document reflects REALITY including technical debt and workarounds
+- Key files and modules are referenced with actual paths
+- Models/APIs reference source files rather than duplicating content
+- If PRD provided: Clear impact analysis showing what needs to change
+- Document enables AI agents to navigate and understand the actual codebase
+- Technical constraints and "gotchas" are clearly documented

 ## Notes

- This task is designed to work with any project type, language, or framework
- The documentation should reflect the project as it actually is, not as it should be
- Focus on patterns that agents can recognize and replicate consistently
- Include both positive examples (what to do) and negative examples (what to avoid)
+- This task creates ONE document that captures the TRUE state of the system
+- References actual files rather than duplicating content when possible
+- Documents technical debt, workarounds, and constraints honestly
+- For brownfield projects with PRD: Provides clear enhancement impact analysis
+- The goal is PRACTICAL documentation for AI agents doing real work
--- a/bmad-core/tasks/execute-checklist.md
+++ b/bmad-core/tasks/execute-checklist.md
@@ -1,97 +0,0 @@
-# Checklist Validation Task
-
-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.
-
-## Instructions
-
-1. **Initial Assessment**
-
-   - 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/
-   - If no checklist specified:
-     - Ask the user which checklist they want to use
-     - Present the available options from the files in the checklists folder
-   - Confirm if they want to work through the checklist:
-     - Section by section (interactive mode - very time consuming)
-     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
-
-2. **Document and Artifact Gathering**
-
-   - Each checklist will specify its required documents/artifacts at the beginning
-   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
-
-3. **Checklist Processing**
-
-   If in interactive mode:
-
-   - Work through each section of the checklist one at a time
-   - For each section:
-     - Review all items in the section following instructions for that section embedded in the checklist
-     - Check each item against the relevant documentation or artifacts as appropriate
-     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
-     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
-
-   If in YOLO mode:
-
-   - Process all sections at once
-   - Create a comprehensive report of all findings
-   - Present the complete analysis to the user
-
-4. **Validation Approach**
-
-   For each checklist item:
-
-   - Read and understand the requirement
-   - Look for evidence in the documentation that satisfies the requirement
-   - Consider both explicit mentions and implicit coverage
-   - Aside from this, follow all checklist llm instructions
-   - Mark items as:
-     - ✅ PASS: Requirement clearly met
-     - ❌ FAIL: Requirement not met or insufficient coverage
-     - ⚠️ PARTIAL: Some aspects covered but needs improvement
-     - N/A: Not applicable to this case
-
-5. **Section Analysis**
-
-   For each section:
-
-   - think step by step to calculate pass rate
-   - Identify common themes in failed items
-   - Provide specific recommendations for improvement
-   - In interactive mode, discuss findings with user
-   - Document any user decisions or explanations
-
-6. **Final Report**
-
-   Prepare a summary that includes:
-
-   - Overall checklist completion status
-   - Pass rates by section
-   - List of failed items with context
-   - Specific recommendations for improvement
-   - Any sections or items marked as N/A with justification
-
-## Checklist Execution Methodology
-
-Each checklist now contains embedded LLM prompts and instructions that will:
-
-1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
-2. **Request specific artifacts** - Clear instructions on what documents/access is needed
-3. **Provide contextual guidance** - Section-specific prompts for better validation
-4. **Generate comprehensive reports** - Final summary with detailed findings
-
-The LLM will:
-
- Execute the complete checklist validation
- Present a final report with pass/fail rates and key findings
- Offer to provide detailed analysis of any section, especially those with warnings or failures
--- a/bmad-core/tasks/index-docs.md
+++ b/bmad-core/tasks/index-docs.md
@@ -56,7 +56,7 @@ You are now operating as a Documentation Indexer. Your goal is to ensure all doc

 The index should be organized as follows:

-`````markdown
+```markdown
 # Documentation Index

 ## Root Documents
@@ -89,7 +89,7 @@ Documents within the `another-folder/` directory:

 Description of nested document.

-````text
+```

 ### Index Entry Format

@@ -99,10 +99,7 @@ Each entry should follow this format:
 ### [Document Title](relative/path/to/file.md)

 Brief description of the document's purpose and contents.
-````
-`````
-
-````
+```

 ### Rules of Operation

@@ -180,4 +177,3 @@ Please provide:
 5. Whether to include hidden files/folders (starting with `.`)

 Would you like to proceed with documentation indexing? Please provide the required input above.
-````
--- a/bmad-core/tasks/kb-mode-interaction.md
+++ b/bmad-core/tasks/kb-mode-interaction.md
@@ -0,0 +1,70 @@
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+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."
+
+### 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
+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
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**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.
+
+**What would you like to know more about?**
+
+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
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
--- a/bmad-core/tasks/review-story.md
+++ b/bmad-core/tasks/review-story.md
@@ -0,0 +1,135 @@
+# review-story
+
+When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
+
+[[LLM: QA Agent executing review-story task as Senior Developer]]
+
+## Prerequisites
+
+- Story status must be "Review"
+- Developer has completed all tasks and updated the File List
+- All automated tests are passing
+
+## Review Process
+
+1. **Read the Complete Story**
+   - Review all acceptance criteria
+   - Understand the dev notes and requirements
+   - Note any completion notes from the developer
+
+2. **Focus on the File List**
+   - Verify all files listed were actually created/modified
+   - Check for any missing files that should have been updated
+
+3. **Senior Developer Code Review**
+   - Review code with the eye of a senior developer
+   - If changes form a cohesive whole, review them together
+   - If changes are independent, review incrementally file by file
+   - Focus on:
+     - Code architecture and design patterns
+     - Refactoring opportunities
+     - Code duplication or inefficiencies
+     - Performance optimizations
+     - Security concerns
+     - Best practices and patterns
+
+4. **Active Refactoring**
+   - As a senior developer, you CAN and SHOULD refactor code where improvements are needed
+   - When refactoring:
+     - Make the changes directly in the files
+     - Explain WHY you're making the change
+     - Describe HOW the change improves the code
+     - Ensure all tests still pass after refactoring
+     - Update the File List if you modify additional files
+
+5. **Standards Compliance Check**
+   - Verify adherence to `docs/coding-standards.md`
+   - Check compliance with `docs/unified-project-structure.md`
+   - Validate testing approach against `docs/testing-strategy.md`
+   - Ensure all guidelines mentioned in the story are followed
+
+6. **Acceptance Criteria Validation**
+   - Verify each AC is fully implemented
+   - Check for any missing functionality
+   - Validate edge cases are handled
+
+7. **Test Coverage Review**
+   - Ensure unit tests cover edge cases
+   - Add missing tests if critical coverage is lacking
+   - Verify integration tests (if required) are comprehensive
+   - Check that test assertions are meaningful
+   - Look for missing test scenarios
+
+8. **Documentation and Comments**
+   - Verify code is self-documenting where possible
+   - Add comments for complex logic if missing
+   - Ensure any API changes are documented
+
+## Append Results to Story File
+
+After review and any refactoring, append your results to the story file in the QA Results section:
+
+```markdown
+## QA Results
+
+### Review Date: [Date]
+### Reviewed By: Quinn (Senior Developer QA)
+
+### Code Quality Assessment
+[Overall assessment of implementation quality]
+
+### Refactoring Performed
+[List any refactoring you performed with explanations]
+- **File**: [filename]
+  - **Change**: [what was changed]
+  - **Why**: [reason for change]
+  - **How**: [how it improves the code]
+
+### Compliance Check
+- Coding Standards: [✓/✗] [notes if any]
+- Project Structure: [✓/✗] [notes if any]
+- Testing Strategy: [✓/✗] [notes if any]
+- All ACs Met: [✓/✗] [notes if any]
+
+### Improvements Checklist
+[Check off items you handled yourself, leave unchecked for dev to address]
+
+- [x] Refactored user service for better error handling (services/user.service.ts)
+- [x] Added missing edge case tests (services/user.service.test.ts)
+- [ ] Consider extracting validation logic to separate validator class
+- [ ] Add integration test for error scenarios
+- [ ] Update API documentation for new error codes
+
+### Security Review
+[Any security concerns found and whether addressed]
+
+### Performance Considerations
+[Any performance issues found and whether addressed]
+
+### Final Status
+[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
+```
+
+## Key Principles
+
+- You are a SENIOR developer reviewing junior/mid-level work
+- You have the authority and responsibility to improve code directly
+- Always explain your changes for learning purposes
+- Balance between perfection and pragmatism
+- Focus on significant improvements, not nitpicks
+
+## Blocking Conditions
+
+Stop the review and request clarification if:
+- Story file is incomplete or missing critical sections
+- File List is empty or clearly incomplete
+- No tests exist when they were required
+- Code changes don't align with story requirements
+- Critical architectural issues that require discussion
+
+## Completion
+
+After review:
+1. If all items are checked and approved: Update story status to "Done"
+2. If unchecked items remain: Keep status as "Review" for dev to address
+3. Always provide constructive feedback and explanations for learning
--- a/bmad-core/tasks/shard-doc.md
+++ b/bmad-core/tasks/shard-doc.md
@@ -6,9 +6,27 @@
 - Create a folder structure to organize the sharded documents
 - Maintain all content integrity including code blocks, diagrams, and markdown formatting

-## Recommended Method: @kayvan/markdown-tree-parser
+## Primary Method: Automatic with markdown-tree

-[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
+[[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}`.
+
+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
+
+**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
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]

 ### Installation and Usage

@@ -41,19 +59,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu

 ---

-## Manual Method (if @kayvan/markdown-tree-parser is not available)
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)

 [[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]

 ### Task Instructions

-### 1. Identify Document and Target Location
+1. Identify Document and Target Location

 - Determine which document to shard (user-provided path)
 - Create a new folder under `docs/` with the same name as the document (without extension)
 - Example: `docs/prd.md` → create folder `docs/prd/`

-### 2. Parse and Extract Sections
+2. Parse and Extract Sections

 [[LLM: When sharding the document:

@@ -63,7 +81,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
   - Extract the section heading and ALL content until the next level 2 section
   - Include all subsections, code blocks, diagrams, lists, tables, etc.
   - Be extremely careful with:
-     - Fenced code blocks (```) - ensure you capture the full block including closing backticks
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
     - Mermaid diagrams - preserve the complete diagram syntax
     - Nested markdown elements
     - Multi-line content that might contain ## inside code blocks
@@ -82,7 +100,7 @@ For each extracted section:

 2. **Adjust heading levels**:

-   - The level 2 heading becomes level 1 (# instead of ##)
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
   - All subsection levels decrease by 1:

   ```txt
@@ -112,7 +130,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
  ...
-```text
+```

 ### 5. Preserve Special Content

--- a/bmad-core/templates/architecture-tmpl.md
+++ b/bmad-core/templates/architecture-tmpl.md
@@ -2,6 +2,8 @@

 [[LLM: If available, review any provided relevant documents to gather all relevant context before beginning. If at a minimum you cannot local `docs/prd.md` ask the user what docs will provide the basis for the architecture.]]

+[[LLM: The default path and filename unless specified is docs/architecture.md]]
+
 ## Introduction

 [[LLM: This section establishes the document's purpose and scope. Keep the content below but ensure project name is properly substituted.
@@ -355,7 +357,7 @@ servers:
      '[object Object]': null
    description:
      '[object Object]': null
-```text
+```

 ^^/CONDITION: has_rest_api^^

@@ -418,7 +420,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text

@{example: monorepo-structure}
 project-root/
@@ -430,6 +431,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
@{/example}
+```

 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]

--- a/bmad-core/templates/brownfield-architecture-tmpl.md
+++ b/bmad-core/templates/brownfield-architecture-tmpl.md
@@ -1,5 +1,7 @@
 # {{Project Name}} Brownfield Enhancement Architecture

+[[LLM: The default path and filename unless specified is docs/architecture.md]]
+
 [[LLM: IMPORTANT - SCOPE AND ASSESSMENT REQUIRED:

 This architecture document is for SIGNIFICANT enhancements to existing projects that require comprehensive architectural planning. Before proceeding:
@@ -224,7 +226,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]

 ```mermaid
 {{component_interaction_diagram}}
-```text
+```

 ## API Design and Integration

@@ -264,7 +266,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]

 ```json
 {{response_schema}}
-```text
+```

 <</REPEAT>>

--- a/bmad-core/templates/brownfield-prd-tmpl.md
+++ b/bmad-core/templates/brownfield-prd-tmpl.md
@@ -1,5 +1,7 @@
 # {{Project Name}} Brownfield Enhancement PRD

+[[LLM: The default path and filename unless specified is docs/prd.md]]
+
 [[LLM: IMPORTANT - SCOPE ASSESSMENT REQUIRED:

 This PRD is for SIGNIFICANT enhancements to existing projects that require comprehensive planning and multiple stories. Before proceeding:
--- a/bmad-core/templates/competitor-analysis-tmpl.md
+++ b/bmad-core/templates/competitor-analysis-tmpl.md
@@ -1,5 +1,7 @@
 # Competitive Analysis Report: {{Project/Product Name}}

+[[LLM: The default path and filename unless specified is docs/competitor-analysis.md]]
+
 [[LLM: This template guides comprehensive competitor analysis. Start by understanding the user's competitive intelligence needs and strategic objectives. Help them identify and prioritize competitors before diving into detailed analysis.]]

 ## Executive Summary
--- a/bmad-core/templates/front-end-architecture-tmpl.md
+++ b/bmad-core/templates/front-end-architecture-tmpl.md
@@ -1,5 +1,7 @@
 # {{Project Name}} Frontend Architecture Document

+[[LLM: The default path and filename unless specified is docs/ui-architecture.md]]
+
 [[LLM: Review provided documents including PRD, UX-UI Specification, and main Architecture Document. Focus on extracting technical implementation details needed for AI frontend tools and developer agents. Ask the user for any of these documents if you are unable to locate and were not provided.]]

 ## Template and Framework Selection
--- a/bmad-core/templates/front-end-spec-tmpl.md
+++ b/bmad-core/templates/front-end-spec-tmpl.md
@@ -1,5 +1,7 @@
 # {{Project Name}} UI/UX Specification

+[[LLM: The default path and filename unless specified is docs/front-end-spec.md]]
+
 [[LLM: Review provided documents including Project Brief, PRD, and any user research to gather context. Focus on understanding user needs, pain points, and desired outcomes before beginning the specification.]]

 ## Introduction
@@ -76,7 +78,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ```mermaid
 {{sitemap_diagram}}
-```text
+```

@{example: sitemap}

@@ -131,7 +133,7 @@ Create subsections for each major flow. After presenting all flows, apply `tasks

 ```mermaid
 {{flow_diagram}}
-```text
+```

 **Edge Cases & Error Handling:**

--- a/bmad-core/templates/fullstack-architecture-tmpl.md
+++ b/bmad-core/templates/fullstack-architecture-tmpl.md
@@ -1,5 +1,7 @@
 # {{Project Name}} Fullstack Architecture Document

+[[LLM: The default path and filename unless specified is docs/architecture.md]]
+
 [[LLM: If available, review any provided relevant documents to gather all relevant context before beginning. At minimum, you should have access to docs/prd.md and docs/front-end-spec.md. Ask the user for any documents you need but cannot locate. This template creates a unified architecture that covers both backend and frontend concerns to guide AI-driven fullstack development.]]

 ## Introduction
@@ -84,7 +86,7 @@ Document the choice and key services that will be used.]]

 ### Repository Structure

-[[LLM: Define the repository approach based on PRD requirements and platform choice:
+[[LLM: Define the repository approach based on PRD requirements and platform choice, explain your rationale or ask quetsions to the user if unsure:

 1. For modern fullstack apps, monorepo is often preferred
 2. Consider tooling (Nx, Turborepo, Lerna, npm workspaces)
@@ -109,9 +111,9 @@ Document the choice and key services that will be used.]]

 Use appropriate diagram type for clarity.]]

-````mermaid
+```mermaid
 {{architecture_diagram}}
-```text
+```

 ### Architectural Patterns

@@ -222,7 +224,7 @@ After presenting all data models, apply `tasks#advanced-elicitation` protocol]]
    model_interface;
  }
 }
-````
+```

 **Relationships:**

@@ -246,7 +248,7 @@ After presenting all data models, apply `tasks#advanced-elicitation` protocol]]

 **TypeScript Interface:**

-````typescript
+```typescript
 interface User {
  id: string;
  email: string;
@@ -262,7 +264,7 @@ interface UserProfile {
  bio?: string;
  preferences: Record<string, any>;
 }
-```text
+```

 **Relationships:**

@@ -300,16 +302,16 @@ servers:
      '[object Object]': null
    description:
      '[object Object]': null
-````
+```

 ^^/CONDITION: has_rest_api^^

 ^^CONDITION: has_graphql_api^^

-````graphql
+```graphql
 # GraphQL Schema
 {{graphql_schema}}
-```text
+```

 ^^/CONDITION: has_graphql_api^^

@@ -322,7 +324,7 @@ servers:
    trpc_routers;
  }
 }
-````
+```

 ^^/CONDITION: has_trpc_api^^

@@ -467,19 +469,19 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 **Component Organization:**

-`````text
-{{component_structure}}
 ```text
+{{component_structure}}
+```

 **Component Template:**

-````typescript
+```typescript
 {
  {
    component_template;
  }
 }
-```text
+```

 ### State Management Architecture

@@ -493,7 +495,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
    state_structure;
  }
 }
-`````
+```

 **State Management Patterns:**

@@ -508,17 +510,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ```text
 {{route_structure}}
-```text
+```

 **Protected Route Pattern:**

-````typescript
+```typescript
 {
  {
    protected_route_example;
  }
 }
-```text
+```

 ### Frontend Services Layer

@@ -532,17 +534,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
    api_client_setup;
  }
 }
-````
+```

 **Service Example:**

-````typescript
+```typescript
 {
  {
    service_example;
  }
 }
-```text
+```

 ## Backend Architecture

@@ -557,11 +559,11 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 ^^CONDITION: serverless^^
 **Function Organization:**

-````
+```text

 {{function_structure}}

-````text
+```

 **Function Template:**

@@ -571,26 +573,26 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
    function_template;
  }
 }
-````
+```

 ^^/CONDITION: serverless^^

 ^^CONDITION: traditional_server^^
 **Controller/Route Organization:**

-`````text
-{{controller_structure}}
 ```text
+{{controller_structure}}
+```

 **Controller Template:**

-````typescript
+```typescript
 {
  {
    controller_template;
  }
 }
-```text
+```

 ^^/CONDITION: traditional_server^^

@@ -602,17 +604,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ```sql
 {{database_schema}}
-`````
+```

 **Data Access Layer:**

-````typescript
+```typescript
 {
  {
    repository_pattern;
  }
 }
-```text
+```

 ### Authentication and Authorization

@@ -622,17 +624,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ```mermaid
 {{auth_flow_diagram}}
-````
+```

 **Middleware/Guards:**

-````typescript
+```typescript
 {
  {
    auth_middleware;
  }
 }
-```text
+```

 ## Unified Project Structure

@@ -692,7 +694,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 ├── package.json                # Root package.json
 ├── {{monorepo_config}}         # Monorepo configuration
 └── README.md
-````
+```

@{example: vercel_structure}
 apps/
@@ -714,19 +716,19 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 **Prerequisites:**

-````bash
+```bash
 {{prerequisites_commands}}
-```text
+```

 **Initial Setup:**

 ```bash
 {{setup_commands}}
-````
+```

 **Development Commands:**

-````bash
+```bash
 # Start all services
 {{start_all_command}}

@@ -738,7 +740,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 # Run tests
 {{test_commands}}
-```text
+```

 ### Environment Configuration

@@ -753,7 +755,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 # Shared
 {{shared_env_vars}}
-````
+```

 ## Deployment Architecture

@@ -776,9 +778,9 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ### CI/CD Pipeline

-````yaml
+```yaml
 '[object Object]': null
-```text
+```

 ### Environments

@@ -836,7 +838,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ### Testing Pyramid

-````
+```text

        E2E Tests
       /          \
@@ -845,17 +847,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 / \
 Frontend Unit Backend Unit

-```text
+```

 ### Test Organization

 **Frontend Tests:**

-```
+```text

 {{frontend_test_structure}}

-````text
+```

 **Backend Tests:**

@@ -863,15 +865,15 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 {{backend_test_structure}}

-```text
+```

 **E2E Tests:**

-````
+```text

 {{e2e_test_structure}}

-````text
+```

 ### Test Examples

@@ -883,17 +885,17 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
    frontend_test_example;
  }
 }
-````
+```

 **Backend API Test:**

-````typescript
+```typescript
 {
  {
    backend_test_example;
  }
 }
-```text
+```

 **E2E Test:**

@@ -903,7 +905,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
    e2e_test_example;
  }
 }
-````
+```

 ## Coding Standards

@@ -944,9 +946,9 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ### Error Flow

-````mermaid
+```mermaid
 {{error_flow_diagram}}
-```text
+```

 ### Error Response Format

@@ -960,17 +962,17 @@ interface ApiError {
    requestId: string;
  };
 }
-````
+```

 ### Frontend Error Handling

-````typescript
+```typescript
 {
  {
    frontend_error_handler;
  }
 }
-```text
+```

 ### Backend Error Handling

@@ -980,7 +982,7 @@ interface ApiError {
    backend_error_handler;
  }
 }
-````
+```

 ## Monitoring and Observability

--- a/bmad-core/templates/market-research-tmpl.md
+++ b/bmad-core/templates/market-research-tmpl.md
@@ -1,5 +1,7 @@
 # Market Research Report: {{Project/Product Name}}

+[[LLM: The default path and filename unless specified is docs/market-research.md]]
+
 [[LLM: This template guides the creation of a comprehensive market research report. Begin by understanding what market insights the user needs and why. Work through each section systematically, using the appropriate analytical frameworks based on the research objectives.]]

 ## Executive Summary
--- a/bmad-core/templates/prd-tmpl.md
+++ b/bmad-core/templates/prd-tmpl.md
@@ -1,5 +1,7 @@
 # {{Project Name}} Product Requirements Document (PRD)

+[[LLM: The default path and filename unless specified is docs/prd.md]]
+
 [[LLM: If available, review any provided document or ask if any are optionally available: Project Brief]]

 ## Goals and Background Context
@@ -116,7 +118,7 @@
 CRITICAL: Epics MUST be logically sequential following agile best practices:

 - Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality
- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page
+- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page - remember this when we produce the stories for the first epic!
 - Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed
 - Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic.
 - Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things.
@@ -148,7 +150,7 @@ CRITICAL: Epics MUST be logically sequential following agile best practices:
 [[LLM: CRITICAL STORY SEQUENCING REQUIREMENTS:

 - Stories within each epic MUST be logically sequential
- Each story should be a "vertical slice" delivering complete functionality
+- Each story should be a "vertical slice" delivering complete functionality aside from early enabler stories for project foundation
 - No story should depend on work from a later story or epic
 - Identify and note any direct prerequisite stories
 - Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story.
--- a/bmad-core/templates/project-brief-tmpl.md
+++ b/bmad-core/templates/project-brief-tmpl.md
@@ -1,5 +1,7 @@
 # Project Brief: {{Project Name}}

+[[LLM: The default path and filename unless specified is docs/brief.md]]
+
 [[LLM: This template guides creation of a comprehensive Project Brief that serves as the foundational input for product development.

 Start by asking the user which mode they prefer:
--- a/bmad-core/templates/simple-project-prd-tmpl.md
+++ b/bmad-core/templates/simple-project-prd-tmpl.md
@@ -1,461 +0,0 @@
-# {{Project Name}} Product Requirements Document (PRD)
-
-[[LLM: If available, review any provided document or ask if any are optionally available: Project Brief]]
-
-## Goals and Background Context
-
-[[LLM: Populate the 2 child sections based on what we have received from user description or the provided brief. Allow user to review the 2 sections and offer changes before proceeding]]
-
-### Goals
-
-[[LLM: Bullet list of 1 line desired outcomes the PRD will deliver if successful - user and project desires]]
-
-### Background Context
-
-[[LLM: 1-2 short paragraphs summarizing the background context, such as what we learned in the brief without being redundant with the goals, what and why this solves a problem, what the current landscape or need is etc...]]
-
-### Change Log
-
-[[LLM: Track document versions and changes]]
-
-| Date | Version | Description | Author |
-| :--- | :------ | :---------- | :----- |
-
-## Requirements
-
-[[LLM: Draft the list of functional and non functional requirements under the two child sections, and immediately execute tasks#advanced-elicitation display]]
-
-### Functional
-
-[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with FR`.]]
-@{example: - FR6: The Todo List uses AI to detect and warn against adding potentially duplicate todo items that are worded differently.}
-
-### Non Functional
-
-[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with NFR`.]]
-@{example: - NFR1: AWS service usage **must** aim to stay within free-tier limits where feasible.}
-
-^^CONDITION: has_ui^^
-
-## User Interface Design Goals
-
-[[LLM: Capture high-level UI/UX vision to inform story creation and also generate a prompt for Lovable or V0 if the user would like either. Steps:
-
-1. Pre-fill all subsections with educated guesses based on project context
-2. Present the complete rendered section to user
-3. Clearly let the user know where assumptions were made
-4. Ask targeted questions for unclear/missing elements or areas needing more specification
-5. This is NOT detailed UI spec - focus on product vision and user goals
-6. After section completion, immediately apply `tasks#advanced-elicitation` protocol]]
-
-### Overall UX Vision
-
-### Key Interaction Paradigms
-
-### Core Screens and Views
-
-[[LLM: From a product perspective, what are the most critical screens or views necessary to deliver the the PRD values and goals? This is meant to be Conceptual High Level to Drive Rough Epic or User Stories]]
-
-@{example}
-
- Login Screen
- Main Dashboard
- Item Detail Page
- Settings Page
-  @{/example}
-
-### Accessibility: { None, WCAG, etc }
-
-### Branding
-
-[[LLM: Any known branding elements or style guides that must be incorporated?]]
-
-@{example}
-
- Replicate the look and feel of early 1900s black and white cinema, including animated effects replicating film damage or projector glitches during page or state transitions.
- Attached is the full color pallet and tokens for our corporate branding.
-  @{/example}
-
-### Target Device and Platforms
-
-@{example}
-"Web Responsive, and all mobile platforms", "IPhone Only", "ASCII Windows Desktop"
-@{/example}
-
-^^/CONDITION: has_ui^^
-
-## Technical Assumptions
-
-[[LLM: Gather technical decisions that will be used for this simple technical PRD that includes architecture decisions. Steps:
-
-1. Check if `data#technical-preferences` or an attached `technical-preferences` file exists - use it to pre-populate choices
-2. Ask user about: languages, frameworks, starter templates, libraries, APIs, deployment targets
-3. For unknowns, offer guidance based on project goals and MVP scope
-4. Document ALL technical choices with rationale (why this choice fits the project)
-5. These become constraints for the Architect - be specific and complete
-6. After section completion, apply `tasks#advanced-elicitation` protocol.]]
-
-### Repository Structure: { Monorepo, Polyrepo, etc...}
-
-### Service Architecture
-
-[[LLM: CRITICAL DECISION - Document the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo).]]
-
-## Testing requirements
-
-[[LLM: CRITICAL DECISION - Document the testing requirements, unit only, integration, e2e, manual, need for manual testing convenience methods).]]
-
-### Additional Technical Assumptions and Requests
-
-[[LLM: Throughout the entire process of drafting this document, if any other technical assumptions are raised or discovered appropriate for the architect, add them here as additional bulleted items]]
-
-## Data Models
-
-[[LLM: Define the core data models/entities that will be used in the front end (if there is one), core application or back end, and if both, shared between frontend and backend:
-
-1. Review PRD requirements and identify key business entities
-2. For each model, explain its purpose and relationships
-3. Include key attributes and data types
-4. Show relationships between models
-5. Create TypeScript interfaces that can be shared
-6. Discuss design decisions with user
-
-Create a clear conceptual model before moving to database schema.
-
-After presenting all data models, apply `tasks#advanced-elicitation` protocol]]
-
-<<REPEAT: data_model>>
-
-### {{model_name}}
-
-**Purpose:** {{model_purpose}}
-
-**Key Attributes:**
-
- {{attribute_1}}: {{type_1}} - {{description_1}}
- {{attribute_2}}: {{type_2}} - {{description_2}}
-
-**TypeScript Interface:**
-
-````typescript
-{
-  {
-    model_interface;
-  }
-}
-```text
-
-**Relationships:**
-
- {{relationship_1}}
- {{relationship_2}}
-  <</REPEAT>>
-
-@{example: data_model}
-
-### User
-
-**Purpose:** Represents authenticated users in the system
-
-**Key Attributes:**
-
- id: string - Unique identifier
- email: string - User's email address
- name: string - Display name
- role: enum - User permission level
- timestamps: Date - Created and updated times
-
-**TypeScript Interface:**
-
-```typescript
-interface User {
-  id: string;
-  email: string;
-  name: string;
-  role: "admin" | "user" | "guest";
-  createdAt: Date;
-  updatedAt: Date;
-  profile?: UserProfile;
-}
-
-interface UserProfile {
-  avatarUrl?: string;
-  bio?: string;
-  preferences: Record<string, any>;
-}
-````
-
-**Relationships:**
-
- Has many Posts (1:n)
- Has one Profile (1:1)
-  @{/example}
-
-## REST API Spec
-
-[[LLM: Based on the chosen API style from Tech Stack:
-
-1. If REST API, create an OpenAPI 3.0 specification
-2. If GraphQL, provide the GraphQL schema
-3. If tRPC, show router definitions
-4. Include all endpoints from epics/stories
-5. Define request/response schemas based on data models
-6. Document authentication requirements
-7. Include example requests/responses
-
-Use appropriate format for the chosen API style. If no API (e.g., static site), skip this section.]]
-
-^^CONDITION: has_rest_api^^
-
-````yml
-openapi: 3.0.0
-info:
-  title:
-    '[object Object]': null
-  version:
-    '[object Object]': null
-  description:
-    '[object Object]': null
-servers:
-  - url:
-      '[object Object]': null
-    description:
-      '[object Object]': null
-```text
-
-^^/CONDITION: has_rest_api^^
-
-^^CONDITION: has_graphql_api^^
-
-```graphql
-# GraphQL Schema
-{{graphql_schema}}
-````
-
-^^/CONDITION: has_graphql_api^^
-
-^^CONDITION: has_trpc_api^^
-
-```typescript
-// tRPC Router Definitions
-{
-  {
-    trpc_routers;
-  }
-}
-```
-
-^^/CONDITION: has_trpc_api^^
-
-[[LLM: After presenting the API spec (or noting its absence if not applicable), apply `tasks#advanced-elicitation` protocol]]
-
-## Components
-
-[[LLM: Based on the architectural patterns, tech stack, and data models from above:
-
-1. Identify major logical components/services across the fullstack
-2. Consider both frontend and backend components
-3. Define clear boundaries and interfaces between components
-4. For each component, specify:
-
- Primary responsibility
- Key interfaces/APIs exposed
- Dependencies on other components
- Technology specifics based on tech stack choices
-
-5. Create component diagrams where helpful
-6. After presenting all components, apply `tasks#advanced-elicitation` protocol]]
-
-<<REPEAT: component>>
-
-### {{component_name}}
-
-**Responsibility:** {{component_description}}
-
-**Key Interfaces:**
-
- {{interface_1}}
- {{interface_2}}
-
-**Dependencies:** {{dependencies}}
-
-**Technology Stack:** {{component_tech_details}}
-<</REPEAT>>
-
-### Component Diagrams
-
-[[LLM: Create Mermaid diagrams to visualize component relationships. Options:
-
- C4 Container diagram for high-level view
- Component diagram for detailed internal structure
- Sequence diagrams for complex interactions
-  Choose the most appropriate for clarity
-
-After presenting the diagrams, apply `tasks#advanced-elicitation` protocol]]
-
-## External APIs
-
-[[LLM: For each external service integration:
-
-1. Identify APIs needed based on PRD requirements and component design
-2. If documentation URLs are unknown, ask user for specifics
-3. Document authentication methods and security considerations
-4. List specific endpoints that will be used
-5. Note any rate limits or usage constraints
-
-If no external APIs are needed, state this explicitly and skip to next section.]]
-
-^^CONDITION: has_external_apis^^
-
-<<REPEAT: external_api>>
-
-### {{api_name}} API
-
- **Purpose:** {{api_purpose}}
- **Documentation:** {{api_docs_url}}
- **Base URL(s):** {{api_base_url}}
- **Authentication:** {{auth_method}}
- **Rate Limits:** {{rate_limits}}
-
-**Key Endpoints Used:**
-<<REPEAT: endpoint>>
-
- `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}
-  <</REPEAT>>
-
-**Integration Notes:** {{integration_considerations}}
-<</REPEAT>>
-
-@{example: external_api}
-
-### Stripe API
-
- **Purpose:** Payment processing and subscription management
- **Documentation:** https://stripe.com/docs/api
- **Base URL(s):** `https://api.stripe.com/v1`
- **Authentication:** Bearer token with secret key
- **Rate Limits:** 100 requests per second
-
-**Key Endpoints Used:**
-
- `POST /customers` - Create customer profiles
- `POST /payment_intents` - Process payments
- `POST /subscriptions` - Manage subscriptions
-  @{/example}
-
-^^/CONDITION: has_external_apis^^
-
-[[LLM: After presenting external APIs (or noting their absence), apply `tasks#advanced-elicitation` protocol]]
-
-## Coding Standards
-
-[[LLM: Define MINIMAL but CRITICAL standards for AI agents. Focus only on project-specific rules that prevent common mistakes. These will be used by dev agents.
-
-After presenting this section, apply `tasks#advanced-elicitation` protocol]]
-
-### Critical Fullstack Rules
-
-<<REPEAT: critical_rule>>
-
- **{{rule_name}}:** {{rule_description}}
-  <</REPEAT>>
-
-@{example: critical_rules}
-
- **Type Sharing:** Always define types in packages/shared and import from there
- **API Calls:** Never make direct HTTP calls - use the service layer
- **Environment Variables:** Access only through config objects, never process.env directly
- **Error Handling:** All API routes must use the standard error handler
- **State Updates:** Never mutate state directly - use proper state management patterns
-  @{/example}
-
-### Naming Conventions
-
-| Element         | Frontend             | Backend    | Example             |
-| :-------------- | :------------------- | :--------- | :------------------ |
-| Components      | PascalCase           | -          | `UserProfile.tsx`   |
-| Hooks           | camelCase with 'use' | -          | `useAuth.ts`        |
-| API Routes      | -                    | kebab-case | `/api/user-profile` |
-| Database Tables | -                    | snake_case | `user_profiles`     |
-
-## Epics
-
-[[LLM: First, present a high-level list of all epics for user approval, the epic_list and immediately execute tasks#advanced-elicitation display. Each epic should have a title and a short (1 sentence) goal statement. This allows the user to review the overall structure before diving into details.
-
-CRITICAL: Epics MUST be logically sequential following agile best practices:
-
- Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality
- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page
- Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed
- Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic.
- Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things.
- Cross Cutting Concerns should flow through epics and stories and not be final stories. For example, adding a logging framework as a last story of an epic, or at the end of a project as a final epic or story would be terrible as we would not have logging from the beginning.]]
-
-<<REPEAT: epic_list>>
-
- Epic{{epic_number}} {{epic_title}}: {{short_goal}}
-
-<</REPEAT>>
-
-@{example: epic_list}
-
-1. Foundation & Core Infrastructure: Establish project setup, authentication, and basic user management
-2. Core Business Entities: Create and manage primary domain objects with CRUD operations
-3. User Workflows & Interactions: Enable key user journeys and business processes
-4. Reporting & Analytics: Provide insights and data visualization for users
-
-@{/example}
-
-[[LLM: After the epic list is approved, present each `epic_details` with all its stories and acceptance criteria as a complete review unit and immediately execute tasks#advanced-elicitation display, before moving on to the next epic.]]
-
-<<REPEAT: epic_details>>
-
-## Epic {{epic_number}} {{epic_title}}
-
-{{epic_goal}} [[LLM: Expanded goal - 2-3 sentences describing the objective and value all the stories will achieve]]
-
-[[LLM: CRITICAL STORY SEQUENCING REQUIREMENTS:
-
- Stories within each epic MUST be logically sequential
- Each story should be a "vertical slice" delivering complete functionality
- No story should depend on work from a later story or epic
- Identify and note any direct prerequisite stories
- Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story.
- Ensure each story delivers clear user or business value, try to avoid enablers and build them into stories that deliver value.
- Size stories for AI agent execution: Each story must be completable by a single AI agent in one focused session without context overflow
- Think "junior developer working for 2-4 hours" - stories must be small, focused, and self-contained
- If a story seems complex, break it down further as long as it can deliver a vertical slice
- Each story should result in working, testable code before the agent's context window fills]]
-
-<<REPEAT: story>>
-
-### Story {{epic_number}}.{{story_number}} {{story_title}}
-
-As a {{user_type}},
-I want {{action}},
-so that {{benefit}}.
-
-#### Acceptance Criteria
-
-[[LLM: Define clear, comprehensive, and testable acceptance criteria that:
-
- Precisely define what "done" means from a functional perspective
- Are unambiguous and serve as basis for verification
- Include any critical non-functional requirements from the PRD
- Consider local testability for backend/data components
- Specify UI/UX requirements and framework adherence where applicable
- Avoid cross-cutting concerns that should be in other stories or PRD sections]]
-
-<<REPEAT: criteria>>
-
- {{criterion number}}: {{criteria}}
-
-<</REPEAT>>
-<</REPEAT>>
-<</REPEAT>>
-
-## Next Steps
-
-### Design Architect Prompt
-
-[[LLM: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.]]
--- a/bmad-core/templates/story-tmpl.md
+++ b/bmad-core/templates/story-tmpl.md
@@ -52,6 +52,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
 [[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
 [[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]

+### File List
+
+[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
+
 ### Change Log

 [[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
@@ -59,3 +63,7 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the

 | Date | Version | Description | Author |
 | :--- | :------ | :---------- | :----- |
+
+## QA Results
+
+[[LLM: QA Agent Results]]
--- a/bmad-core/utils/workflow-management.md
+++ b/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.
-```text
-
-### /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
-```text
-
-### /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?
-```text
-
-### /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?
-```text
-
-## 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...
-```text
-
-## 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.
--- a/bmad-core/workflows/brownfield-fullstack.yml
+++ b/bmad-core/workflows/brownfield-fullstack.yml
@@ -11,34 +11,29 @@ workflow:
    - modernization
    - integration-enhancement

-  # For Complex Enhancements (Multiple Stories, Architectural Changes)
-  complex_enhancement_sequence:
-    - step: scope_assessment
-      agent: any
-      action: assess complexity
-      notes: "First, assess if this is a simple change (use simple_enhancement_sequence) or complex enhancement requiring full planning."
-
+  sequence:
    - step: project_analysis
-      agent: analyst
-      action: analyze existing project
+      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
+      creates: 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."
+      notes: "Creates comprehensive PRD with existing system analysis and enhancement planning. SAVE OUTPUT: Copy final prd.md to your project's docs/ folder."

    - agent: architect
-      creates: brownfield-architecture.md
+      creates: 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."
+      requires: prd.md
+      notes: "Creates architecture with integration strategy and existing system constraints. SAVE OUTPUT: Copy final 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."
+      notes: "Validates all documents for integration safety and completeness. May require updates to any document."

    - agent: various
      updates: any_flagged_documents
@@ -47,70 +42,71 @@ workflow:

    - workflow_end:
      action: move_to_ide
-      notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
        
-  # For Simple Enhancements (1-3 Stories, Following Existing Patterns)
-  simple_enhancement_sequence:
-    - step: enhancement_type
-      action: choose approach
-      notes: "Choose between creating single story (very small change) or epic (1-3 related stories)."
+        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
        
-    - agent: pm|po|sm
-      creates: brownfield_epic OR brownfield_story
-      uses: brownfield-create-epic OR brownfield-create-story
-      notes: "Create focused enhancement with existing system integration. Choose agent based on team preference and context."
+        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
        
-    - workflow_end:
-      action: move_to_ide
-      notes: "Enhancement defined. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+        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{Enhancement Complexity?}
-        B -->|Complex/Significant| C[analyst: analyze existing project]
-        B -->|Simple| D{1 Story or 2-3 Stories?}
+        A[Start: Brownfield Enhancement] --> B[analyst: analyze existing project]
+        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[Move to IDE Environment]
+        G --> E

-        C --> E[pm: brownfield-prd.md]
-        E --> F[architect: brownfield-architecture.md]
-        F --> G[po: validate with po-master-checklist]
-        G --> H{PO finds issues?}
-        H -->|Yes| I[Return to relevant agent for fixes]
-        H -->|No| J[Move to IDE Environment]
-        I --> G
-
-        D -->|1 Story| K[pm/po/sm: brownfield-create-story]
-        D -->|2-3 Stories| L[pm/po/sm: brownfield-create-epic]
-        K --> M[Move to IDE Environment]
-        L --> M
-
-        style J fill:#90EE90
-        style M fill:#90EE90
-        style E fill:#FFE4B5
-        style F fill:#FFE4B5
-        style K fill:#FFB6C1
-        style L fill:#FFB6C1
+        style H fill:#90EE90
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
    ```

  decision_guidance:
-    use_complex_sequence_when:
-      - Enhancement requires multiple coordinated stories (4+)
+    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

-    use_simple_sequence_when:
-      - Enhancement can be completed in 1-3 stories
-      - Follows existing project patterns
-      - Integration complexity is minimal
-      - Risk to existing system is low
-      - Change is isolated with clear boundaries
-
  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."
+    analyst_to_pm: "Existing project analysis complete. Create comprehensive PRD with integration strategy."
+    pm_to_architect: "PRD ready. Save it as docs/prd.md, then create the integration architecture."
+    architect_to_po: "Architecture complete. Save it as docs/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."
-    simple_to_ide: "Enhancement defined with existing system integration. Move to IDE environment to begin development."
-    complex_complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
--- a/bmad-core/workflows/brownfield-service.yml
+++ b/bmad-core/workflows/brownfield-service.yml
@@ -12,34 +12,29 @@ workflow:
    - performance-optimization
    - integration-enhancement

-  # For Complex Service Enhancements (Multiple Stories, Architectural Changes)
-  complex_enhancement_sequence:
-    - step: scope_assessment
-      agent: any
-      action: assess complexity
-      notes: "First, assess if this is a simple service change (use simple_enhancement_sequence) or complex enhancement requiring full planning."
-
+  sequence:
    - step: service_analysis
-      agent: analyst
-      action: analyze existing service
+      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
+      creates: 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."
+      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: brownfield-architecture.md
+      creates: 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."
+      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 brownfield documents for service integration safety and API compatibility. May require updates to any document."
+      notes: "Validates all documents for service integration safety and API compatibility. May require updates to any document."

    - agent: various
      updates: any_flagged_documents
@@ -48,70 +43,71 @@ workflow:

    - workflow_end:
      action: move_to_ide
-      notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
        
-  # For Simple Service Enhancements (1-3 Stories, Following Existing Patterns)
-  simple_enhancement_sequence:
-    - step: enhancement_type
-      action: choose approach
-      notes: "Choose between creating single story (simple API endpoint) or epic (1-3 related service changes)."
+        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
        
-    - agent: pm|po|sm
-      creates: brownfield_epic OR brownfield_story
-      uses: brownfield-create-epic OR brownfield-create-story
-      notes: "Create focused service enhancement with existing API integration. Choose agent based on team preference and context."
+        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
        
-    - workflow_end:
-      action: move_to_ide
-      notes: "Service enhancement defined. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+        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{Enhancement Complexity?}
-        B -->|Complex/Significant| C[analyst: analyze existing service]
-        B -->|Simple| D{1 Story or 2-3 Stories?}
+        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[Move to IDE Environment]
+        G --> E

-        C --> E[pm: brownfield-prd.md]
-        E --> F[architect: brownfield-architecture.md]
-        F --> G[po: validate with po-master-checklist]
-        G --> H{PO finds issues?}
-        H -->|Yes| I[Return to relevant agent for fixes]
-        H -->|No| J[Move to IDE Environment]
-        I --> G
-
-        D -->|1 Story| K[pm/po/sm: brownfield-create-story]
-        D -->|2-3 Stories| L[pm/po/sm: brownfield-create-epic]
-        K --> M[Move to IDE Environment]
-        L --> M
-
-        style J fill:#90EE90
-        style M fill:#90EE90
-        style E fill:#FFE4B5
-        style F fill:#FFE4B5
-        style K fill:#FFB6C1
-        style L fill:#FFB6C1
+        style H fill:#90EE90
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
    ```

  decision_guidance:
-    use_complex_sequence_when:
-      - Service enhancement requires multiple coordinated stories (4+)
+    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

-    use_simple_sequence_when:
-      - Adding simple endpoints or modifying existing ones
-      - Enhancement follows existing service patterns
-      - API compatibility maintained
-      - Risk to existing service is low
-      - Change is isolated with clear boundaries
-
  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."
+    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."
-    simple_to_ide: "Service enhancement defined with existing API integration. Move to IDE environment to begin development."
-    complex_complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
--- a/bmad-core/workflows/brownfield-ui.yml
+++ b/bmad-core/workflows/brownfield-ui.yml
@@ -11,42 +11,37 @@ workflow:
    - design-refresh
    - frontend-enhancement

-  # For Complex UI Enhancements (Multiple Stories, Design Changes)
-  complex_enhancement_sequence:
-    - step: scope_assessment
-      agent: any
-      action: assess complexity
-      notes: "First, assess if this is a simple UI change (use simple_enhancement_sequence) or complex enhancement requiring full planning."
-
+  sequence:
    - step: ui_analysis
-      agent: analyst
-      action: analyze existing UI
+      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
+      creates: 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."
+      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: 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."
+      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: brownfield-architecture.md
+      creates: architecture.md
      uses: brownfield-architecture-tmpl
      requires:
-        - brownfield-prd.md
+        - 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."
+      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 brownfield documents for UI integration safety and design consistency. May require updates to any document."
+      notes: "Validates all documents for UI integration safety and design consistency. May require updates to any document."

    - agent: various
      updates: any_flagged_documents
@@ -55,73 +50,74 @@ workflow:

    - workflow_end:
      action: move_to_ide
-      notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
        
-  # For Simple UI Enhancements (1-3 Stories, Following Existing Design)
-  simple_enhancement_sequence:
-    - step: enhancement_type
-      action: choose approach
-      notes: "Choose between creating single story (simple component change) or epic (1-3 related UI changes)."
+        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
        
-    - agent: pm|po|sm
-      creates: brownfield_epic OR brownfield_story
-      uses: brownfield-create-epic OR brownfield-create-story
-      notes: "Create focused UI enhancement with existing design system integration. Choose agent based on team preference and context."
+        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
        
-    - workflow_end:
-      action: move_to_ide
-      notes: "UI enhancement defined. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+        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{Enhancement Complexity?}
-        B -->|Complex/Significant| C[analyst: analyze existing UI]
-        B -->|Simple| D{1 Story or 2-3 Stories?}
+        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[Move to IDE Environment]
+        H --> F

-        C --> E[pm: brownfield-prd.md]
-        E --> F[ux-expert: front-end-spec.md]
-        F --> G[architect: brownfield-architecture.md]
-        G --> H[po: validate with po-master-checklist]
-        H --> I{PO finds issues?}
-        I -->|Yes| J[Return to relevant agent for fixes]
-        I -->|No| K[Move to IDE Environment]
-        J --> H
-
-        D -->|1 Story| L[pm/po/sm: brownfield-create-story]
-        D -->|2-3 Stories| M[pm/po/sm: brownfield-create-epic]
-        L --> N[Move to IDE Environment]
-        M --> N
-
-        style K fill:#90EE90
-        style N fill:#90EE90
+        style I fill:#90EE90
+        style C fill:#FFE4B5
+        style D fill:#FFE4B5
        style E fill:#FFE4B5
-        style F fill:#FFE4B5
-        style G fill:#FFE4B5
-        style L fill:#FFB6C1
-        style M fill:#FFB6C1
    ```

  decision_guidance:
-    use_complex_sequence_when:
-      - UI enhancement requires multiple coordinated stories (4+)
+    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

-    use_simple_sequence_when:
-      - Enhancement can be completed in 1-3 stories
-      - Follows existing design patterns exactly
-      - Component changes are isolated
-      - Risk to existing UI is low
-      - Change maintains current user experience
-
  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."
+    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/brownfield-architecture.md. Please validate all artifacts for UI integration safety."
+    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."
-    simple_to_ide: "UI enhancement defined with existing design integration. Move to IDE environment to begin development."
-    complex_complete: "All brownfield planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
--- a/bmad-core/workflows/greenfield-fullstack.yml
+++ b/bmad-core/workflows/greenfield-fullstack.yml
@@ -12,8 +12,7 @@ workflow:
    - prototype
    - mvp

-  # For Complex Projects (Production-Ready, Multiple Features)
-  complex_project_sequence:
+  sequence:
    - agent: analyst
      creates: project-brief.md
      optional_steps:
@@ -76,93 +75,87 @@ workflow:

    - workflow_end:
      action: move_to_ide
-      notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
        
-  # For Simple Projects (Prototypes, MVPs, Quick Experiments)
-  simple_project_sequence:
-    - step: project_scope
-      action: assess complexity
-      notes: "First, assess if this needs full planning (use complex_project_sequence) or can be a simple prototype/MVP."
+        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
        
-    - agent: analyst
-      creates: project-brief.md
-      optional_steps:
-        - brainstorming_session
-      notes: "Creates focused project brief for simple project. SAVE OUTPUT: Copy final project-brief.md to your project's docs/ folder."
+        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
        
-    - agent: pm
-      creates: simple-project-prd.md
-      uses: create doc simple-project-prd OR create-epic OR create-story
-      requires: project-brief.md
-      notes: "Create simple prd, simple epic or story instead of full PRD for rapid development. Choose based on scope."
+        3. START DEVELOPMENT CYCLE:
+           a. SM Agent (New Chat): @sm → *create
+              - Creates next story from sharded docs
+              - Review and approve story (Draft → Approved)
           
-    - workflow_end:
-      action: move_to_ide
-      notes: "Simple project defined. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+           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: Greenfield Project] --> B{Project Complexity?}
-        B -->|Complex/Production| C[analyst: project-brief.md]
-        B -->|Simple/Prototype| D[analyst: focused project-brief.md]
+        A[Start: Greenfield Project] --> B[analyst: project-brief.md]
+        B --> C[pm: prd.md]
+        C --> D[ux-expert: front-end-spec.md]
+        D --> D2{Generate v0 prompt?}
+        D2 -->|Yes| D3[ux-expert: create v0 prompt]
+        D2 -->|No| E[architect: fullstack-architecture.md]
+        D3 --> D4[User: generate UI in v0/Lovable]
+        D4 --> E
+        E --> F{Architecture suggests PRD changes?}
+        F -->|Yes| G[pm: update prd.md]
+        F -->|No| H[po: validate all artifacts]
+        G --> H
+        H --> I{PO finds issues?}
+        I -->|Yes| J[Return to relevant agent for fixes]
+        I -->|No| K[Move to IDE Environment]
+        J --> H

-        C --> E[pm: prd.md]
-        E --> F[ux-expert: front-end-spec.md]
-        F --> F2{Generate v0 prompt?}
-        F2 -->|Yes| F3[ux-expert: create v0 prompt]
-        F2 -->|No| G[architect: fullstack-architecture.md]
-        F3 --> F4[User: generate UI in v0/Lovable]
-        F4 --> G
-        G --> H{Architecture suggests PRD changes?}
-        H -->|Yes| I[pm: update prd.md]
-        H -->|No| J[po: validate all artifacts]
-        I --> J
-        J --> K{PO finds issues?}
-        K -->|Yes| L[Return to relevant agent for fixes]
-        K -->|No| M[Move to IDE Environment]
-        L --> J
+        B -.-> B1[Optional: brainstorming]
+        B -.-> B2[Optional: market research]
+        D -.-> D1[Optional: user research]
+        E -.-> E1[Optional: technical research]

-        D --> N[pm: simple epic or story]
-        N --> O[Move to IDE Environment]
-
-        C -.-> C1[Optional: brainstorming]
-        C -.-> C2[Optional: market research]
-        F -.-> F1[Optional: user research]
-        G -.-> G1[Optional: technical research]
-        D -.-> D1[Optional: brainstorming]
-
-        style M fill:#90EE90
-        style O fill:#90EE90
-        style F3 fill:#E6E6FA
-        style F4 fill:#E6E6FA
+        style K fill:#90EE90
+        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 F fill:#FFE4B5
-        style G fill:#FFE4B5
-        style D fill:#FFB6C1
-        style N fill:#FFB6C1
    ```

  decision_guidance:
-    use_complex_sequence_when:
+    when_to_use:
      - Building production-ready applications
      - Multiple team members will be involved
-      - Complex feature requirements (4+ stories)
+      - Complex feature requirements
      - Need comprehensive documentation
      - Long-term maintenance expected
      - Enterprise or customer-facing applications

-    use_simple_sequence_when:
-      - Building prototypes or MVPs
-      - Solo developer or small team
-      - Simple requirements (1-3 stories)
-      - Quick experiments or proof-of-concepts
-      - Short-term or throwaway projects
-      - Learning or educational projects
-
  handoff_prompts:
-    # Complex sequence prompts
    analyst_to_pm: "Project brief is complete. Save it as docs/project-brief.md in your project, then create the PRD."
    pm_to_ux: "PRD is ready. Save it as docs/prd.md in your project, then create the UI/UX specification."
    ux_to_architect: "UI/UX spec complete. Save it as docs/front-end-spec.md in your project, then create the fullstack architecture."
@@ -170,8 +163,4 @@ workflow:
    architect_to_pm: "Please update the PRD with the suggested story changes, then re-export the complete prd.md to docs/."
    updated_to_po: "All documents ready in docs/ folder. Please validate all artifacts for consistency."
    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
-    complex_complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
-
-    # Simple sequence prompts
-    simple_analyst_to_pm: "Focused project brief complete. Save it as docs/project-brief.md, then create simple epic or story for rapid development."
-    simple_complete: "Simple project defined. Move to IDE environment to begin development."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
--- a/bmad-core/workflows/greenfield-service.yml
+++ b/bmad-core/workflows/greenfield-service.yml
@@ -13,8 +13,7 @@ workflow:
    - api-prototype
    - simple-service

-  # For Complex Services (Production APIs, Multiple Endpoints)
-  complex_service_sequence:
+  sequence:
    - agent: analyst
      creates: project-brief.md
      optional_steps:
@@ -52,67 +51,70 @@ workflow:

    - workflow_end:
      action: move_to_ide
-      notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
        
-  # For Simple Services (Simple APIs, Single Purpose Services)
-  simple_service_sequence:
-    - step: service_scope
-      action: assess complexity
-      notes: "First, assess if this needs full planning (use complex_service_sequence) or can be a simple API/service."
+        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
        
-    - agent: analyst
-      creates: project-brief.md
-      optional_steps:
-        - brainstorming_session
-      notes: "Creates focused project brief for simple service. SAVE OUTPUT: Copy final project-brief.md to your project's docs/ folder."
+        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
        
-    - agent: pm
-      creates: simple_epic OR single_story
-      uses: create-epic OR create-story
-      requires: project-brief.md
-      notes: "Create simple epic or story for API endpoints instead of full PRD for rapid development."
+        3. START DEVELOPMENT CYCLE:
+           a. SM Agent (New Chat): @sm → *create
+              - Creates next story from sharded docs
+              - Review and approve story (Draft → Approved)
           
-    - workflow_end:
-      action: move_to_ide
-      notes: "Simple service defined. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+           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 Development] --> B{Service Complexity?}
-        B -->|Complex/Production| C[analyst: project-brief.md]
-        B -->|Simple/Prototype| D[analyst: focused project-brief.md]
+        A[Start: Service Development] --> B[analyst: project-brief.md]
+        B --> C[pm: prd.md]
+        C --> D[architect: architecture.md]
+        D --> E{Architecture suggests PRD changes?}
+        E -->|Yes| F[pm: update prd.md]
+        E -->|No| G[po: validate all artifacts]
+        F --> G
+        G --> H{PO finds issues?}
+        H -->|Yes| I[Return to relevant agent for fixes]
+        H -->|No| J[Move to IDE Environment]
+        I --> G

-        C --> E[pm: prd.md]
-        E --> F[architect: architecture.md]
-        F --> G{Architecture suggests PRD changes?}
-        G -->|Yes| H[pm: update prd.md]
-        G -->|No| I[po: validate all artifacts]
-        H --> I
-        I --> J{PO finds issues?}
-        J -->|Yes| K[Return to relevant agent for fixes]
-        J -->|No| L[Move to IDE Environment]
-        K --> I
+        B -.-> B1[Optional: brainstorming]
+        B -.-> B2[Optional: market research]
+        D -.-> D1[Optional: technical research]

-        D --> M[pm: simple epic or story]
-        M --> N[Move to IDE Environment]
-
-        C -.-> C1[Optional: brainstorming]
-        C -.-> C2[Optional: market research]
-        F -.-> F1[Optional: technical research]
-        D -.-> D1[Optional: brainstorming]
-
-        style L fill:#90EE90
-        style N fill:#90EE90
+        style J fill:#90EE90
+        style B fill:#FFE4B5
        style C fill:#FFE4B5
-        style E fill:#FFE4B5
-        style F fill:#FFE4B5
-        style D fill:#FFB6C1
-        style M fill:#FFB6C1
+        style D fill:#FFE4B5
    ```

  decision_guidance:
-    use_complex_sequence_when:
+    when_to_use:
      - Building production APIs or microservices
      - Multiple endpoints and complex business logic
      - Need comprehensive documentation and testing
@@ -120,24 +122,11 @@ workflow:
      - Long-term maintenance expected
      - Enterprise or external-facing APIs

-    use_simple_sequence_when:
-      - Building simple APIs or single-purpose services
-      - Few endpoints with straightforward logic
-      - Prototyping or proof-of-concept APIs
-      - Solo developer or small team
-      - Internal tools or utilities
-      - Learning or experimental projects
-
  handoff_prompts:
-    # Complex sequence prompts
    analyst_to_pm: "Project brief is complete. Save it as docs/project-brief.md in your project, then create the PRD."
    pm_to_architect: "PRD is ready. Save it as docs/prd.md in your project, then create the service architecture."
    architect_review: "Architecture complete. Save it as docs/architecture.md. Do you suggest any changes to the PRD stories or need new stories added?"
    architect_to_pm: "Please update the PRD with the suggested story changes, then re-export the complete prd.md to docs/."
    updated_to_po: "All documents ready in docs/ folder. Please validate all artifacts for consistency."
    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
-    complex_complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
-
-    # Simple sequence prompts
-    simple_analyst_to_pm: "Focused project brief complete. Save it as docs/project-brief.md, then create simple epic or story for API development."
-    simple_complete: "Simple service defined. Move to IDE environment to begin development."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
--- a/bmad-core/workflows/greenfield-ui.yml
+++ b/bmad-core/workflows/greenfield-ui.yml
@@ -13,8 +13,7 @@ workflow:
    - ui-prototype
    - simple-interface

-  # For Complex UIs (Production Apps, Multiple Views)
-  complex_ui_sequence:
+  sequence:
    - agent: analyst
      creates: project-brief.md
      optional_steps:
@@ -71,76 +70,79 @@ workflow:

    - workflow_end:
      action: move_to_ide
-      notes: "All planning artifacts complete. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+      notes: |
+        Planning phase complete! Now transition to IDE Development:
        
-  # For Simple UIs (Simple Interfaces, Few Components)
-  simple_ui_sequence:
-    - step: ui_scope
-      action: assess complexity
-      notes: "First, assess if this needs full planning (use complex_ui_sequence) or can be a simple interface."
+        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
        
-    - agent: analyst
-      creates: project-brief.md
-      optional_steps:
-        - brainstorming_session
-      notes: "Creates focused project brief for simple UI. SAVE OUTPUT: Copy final project-brief.md to your project's docs/ folder."
+        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
        
-    - agent: ux-expert
-      creates: simple_wireframes OR quick_spec
-      uses: create-epic OR create-story
-      requires: project-brief.md
-      notes: "Create simple wireframes and component list instead of full UI/UX spec for rapid development."
+        3. START DEVELOPMENT CYCLE:
+           a. SM Agent (New Chat): @sm → *create
+              - Creates next story from sharded docs
+              - Review and approve story (Draft → Approved)
           
-    - workflow_end:
-      action: move_to_ide
-      notes: "Simple UI defined. Move to IDE environment to begin development. Explain to the user the IDE Development Workflow next steps: data#bmad-kb:IDE Development Workflow"
+           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 Development] --> B{UI Complexity?}
-        B -->|Complex/Production| C[analyst: project-brief.md]
-        B -->|Simple/Prototype| D[analyst: focused project-brief.md]
+        A[Start: UI Development] --> B[analyst: project-brief.md]
+        B --> C[pm: prd.md]
+        C --> D[ux-expert: front-end-spec.md]
+        D --> D2{Generate v0 prompt?}
+        D2 -->|Yes| D3[ux-expert: create v0 prompt]
+        D2 -->|No| E[architect: front-end-architecture.md]
+        D3 --> D4[User: generate UI in v0/Lovable]
+        D4 --> E
+        E --> F{Architecture suggests PRD changes?}
+        F -->|Yes| G[pm: update prd.md]
+        F -->|No| H[po: validate all artifacts]
+        G --> H
+        H --> I{PO finds issues?}
+        I -->|Yes| J[Return to relevant agent for fixes]
+        I -->|No| K[Move to IDE Environment]
+        J --> H

-        C --> E[pm: prd.md]
-        E --> F[ux-expert: front-end-spec.md]
-        F --> F2{Generate v0 prompt?}
-        F2 -->|Yes| F3[ux-expert: create v0 prompt]
-        F2 -->|No| G[architect: front-end-architecture.md]
-        F3 --> F4[User: generate UI in v0/Lovable]
-        F4 --> G
-        G --> H{Architecture suggests PRD changes?}
-        H -->|Yes| I[pm: update prd.md]
-        H -->|No| J[po: validate all artifacts]
-        I --> J
-        J --> K{PO finds issues?}
-        K -->|Yes| L[Return to relevant agent for fixes]
-        K -->|No| M[Move to IDE Environment]
-        L --> J
+        B -.-> B1[Optional: brainstorming]
+        B -.-> B2[Optional: market research]
+        D -.-> D1[Optional: user research]
+        E -.-> E1[Optional: technical research]

-        D --> N[ux-expert: simple wireframes]
-        N --> O[Move to IDE Environment]
-
-        C -.-> C1[Optional: brainstorming]
-        C -.-> C2[Optional: market research]
-        F -.-> F1[Optional: user research]
-        G -.-> G1[Optional: technical research]
-        D -.-> D1[Optional: brainstorming]
-
-        style M fill:#90EE90
-        style O fill:#90EE90
-        style F3 fill:#E6E6FA
-        style F4 fill:#E6E6FA
+        style K fill:#90EE90
+        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 F fill:#FFE4B5
-        style G fill:#FFE4B5
-        style D fill:#FFB6C1
-        style N fill:#FFB6C1
    ```

  decision_guidance:
-    use_complex_sequence_when:
+    when_to_use:
      - Building production frontend applications
      - Multiple views/pages with complex interactions
      - Need comprehensive UI/UX design and testing
@@ -148,16 +150,7 @@ workflow:
      - Long-term maintenance expected
      - Customer-facing applications

-    use_simple_sequence_when:
-      - Building simple interfaces or prototypes
-      - Few views with straightforward interactions
-      - Internal tools or admin interfaces
-      - Solo developer or small team
-      - Quick experiments or proof-of-concepts
-      - Learning or educational projects
-
  handoff_prompts:
-    # Complex sequence prompts
    analyst_to_pm: "Project brief is complete. Save it as docs/project-brief.md in your project, then create the PRD."
    pm_to_ux: "PRD is ready. Save it as docs/prd.md in your project, then create the UI/UX specification."
    ux_to_architect: "UI/UX spec complete. Save it as docs/front-end-spec.md in your project, then create the frontend architecture."
@@ -165,8 +158,4 @@ workflow:
    architect_to_pm: "Please update the PRD with the suggested story changes, then re-export the complete prd.md to docs/."
    updated_to_po: "All documents ready in docs/ folder. Please validate all artifacts for consistency."
    po_issues: "PO found issues with [document]. Please return to [agent] to fix and re-save the updated document."
-    complex_complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
-
-    # Simple sequence prompts
-    simple_analyst_to_ux: "Focused project brief complete. Save it as docs/project-brief.md, then create simple wireframes for rapid development."
-    simple_complete: "Simple UI defined. Move to IDE environment to begin development."
+    complete: "All planning artifacts validated and saved in docs/ folder. Move to IDE environment to begin development."
--- a/expansion-packs/bmad-infrastructure-devops/tasks/create-doc.md
+++ b/expansion-packs/bmad-infrastructure-devops/tasks/create-doc.md
@@ -31,9 +31,9 @@ Confirm with the user their preferred interaction style:

 ### 3. Execute Template

- Load specified template from `templates#*` or the /templates directory
+- Load specified template from `templates#*` or the `{root}/templates directory`
 - Follow ALL embedded LLM instructions within the template
- Process template markup according to `utils#template-format` conventions
+- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions

 ### 4. Template Processing Rules

--- a/expansion-packs/expansion-creator/common-tasks/execute-checklist.md
+++ b/expansion-packs/expansion-creator/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
--- a/bmad-core/utils/template-format.md
+++ b/bmad-core/utils/template-format.md
--- a/common/utils/workflow-management.md
+++ b/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.
--- a/dist/agents/analyst.txt
+++ b/dist/agents/analyst.txt
--- a/dist/agents/architect.txt
+++ b/dist/agents/architect.txt
--- a/dist/agents/bmad-master.txt
+++ b/dist/agents/bmad-master.txt
--- a/dist/agents/bmad-orchestrator.txt
+++ b/dist/agents/bmad-orchestrator.txt
--- a/dist/agents/dev.txt
+++ b/dist/agents/dev.txt
@@ -43,66 +43,52 @@ These references map directly to bundle sections:

 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:

-```yml
+```yaml
 agent:
  name: James
  id: dev
  title: Full Stack Developer
  icon: 💻
-  whenToUse: "Use for code implementation, debugging, refactoring, and development best practices"
-  customization:
-
+  whenToUse: Use for code implementation, debugging, refactoring, and development best practices
+  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 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
 persona:
  role: Expert Senior Software Engineer & Implementation Specialist
  style: Extremely concise, pragmatic, detail-oriented, solution-focused
  identity: Expert who implements stories by reading requirements and executing tasks sequentially with comprehensive testing
  focus: Executing story tasks with precision, updating Dev Agent Record sections only, maintaining minimal context overhead
-
 core_principles:
  - CRITICAL: Story-Centric - Story has ALL info. NEVER load PRD/architecture/other docs files unless explicitly directed in dev notes
-  - CRITICAL: Load Standards - MUST load docs/architecture/coding-standards.md into core memory at startup
-  - CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
-  - Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
+  - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
  - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
-  - Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
+  - Quality Gate Discipline - NEVER complete tasks with failing automated validations
+  - Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix.
  - Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
-  - Code Excellence - Clean, secure, maintainable code per coding-standards.md
+  - Code Excellence - Clean, secure, maintainable code per loaded standards
  - Numbered Options - Always use numbered lists when presenting choices
-
-startup:
-  - Announce: Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Do NOT load any story files or coding-standards.md during startup
-  - CRITICAL: Do NOT scan docs/stories/ directory automatically
-  - CRITICAL: Do NOT begin any tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load files and begin work when explicitly requested by user
-
 commands:
-  - "*help" - Show commands
-  - "*chat-mode" - Conversational mode
-  - "*run-tests" - Execute linting+tests
-  - "*lint" - Run linting only
-  - "*dod-check" - Run story-dod-checklist
-  - "*status" - Show task progress
-  - "*debug-log" - Show debug entries
-  - "*complete-story" - Finalize to "Review"
-  - "*exit" - Leave developer mode
-
+  - help: Show numbered list of the following commands to allow selection
+  - run-tests: Execute linting and tests
+  - debug-log: Show debug entries
+  - complete-story: Finalize to "Review"
+  - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 task-execution:
-  flow: "Read task→Implement→Write tests→Pass tests→Update [x]→Next task"
-
+  flow: Read task→Implement→Write tests→Execute validations→Only if ALL pass→Update [x]→Next task
  updates-ONLY:
-    - "Checkboxes: [ ] not started | [-] in progress | [x] complete"
-    - "Debug Log: | Task | File | Change | Reverted? |"
-    - "Completion Notes: Deviations only, <50 words"
-    - "Change Log: Requirement changes only"
-
-  blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config"
-
-  done: "Code matches reqs + Tests pass + Follows standards + No lint errors"
-
-  completion: "All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT"
-
+    - 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
+    - 'Debug Log: | Task | File | Change | Reverted? |'
+    - '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
+  done: Code matches reqs + All validations pass + Follows standards + File List complete
+  completion: All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Update File List→Mark Ready for Review→HALT
 dependencies:
  tasks:
    - execute-checklist
@@ -116,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

@@ -131,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
--- a/dist/agents/pm.txt
+++ b/dist/agents/pm.txt
@@ -43,7 +43,7 @@ These references map directly to bundle sections:

 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:

-```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
@@ -73,10 +73,10 @@ persona:
 startup:
  - Greet the user with your name and role, and inform of the *help command.
 commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) Deep conversation with advanced-elicitation'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*exit" - Say goodbye as the PM, and then abandon inhabiting this persona'
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) Deep conversation with advanced-elicitation
+  - create-doc {template}: Create doc (no template = show available templates)
+  - exit: Say goodbye as the PM, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - create-doc
@@ -89,7 +89,6 @@ dependencies:
  templates:
    - prd-tmpl
    - brownfield-prd-tmpl
-    - simple-project-prd-tmpl
  checklists:
    - pm-checklist
    - change-checklist
@@ -134,9 +133,9 @@ Confirm with the user their preferred interaction style:

 ### 3. Execute Template

- Load specified template from `templates#*` or the /templates directory
+- Load specified template from `templates#*` or the `{root}/templates directory`
 - Follow ALL embedded LLM instructions within the template
- Process template markup according to `utils#template-format` conventions
+- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions

 ### 4. Template Processing Rules

@@ -875,13 +874,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

@@ -890,7 +885,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
@@ -979,9 +974,27 @@ The LLM will:
 - Create a folder structure to organize the sharded documents
 - Maintain all content integrity including code blocks, diagrams, and markdown formatting

-## Recommended Method: @kayvan/markdown-tree-parser
+## Primary Method: Automatic with markdown-tree

-[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
+[[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}`.
+
+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
+
+**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
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]

 ### Installation and Usage

@@ -1014,19 +1027,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu

 ---

-## Manual Method (if @kayvan/markdown-tree-parser is not available)
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)

 [[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]

 ### Task Instructions

-### 1. Identify Document and Target Location
+1. Identify Document and Target Location

 - Determine which document to shard (user-provided path)
 - Create a new folder under `docs/` with the same name as the document (without extension)
 - Example: `docs/prd.md` → create folder `docs/prd/`

-### 2. Parse and Extract Sections
+2. Parse and Extract Sections

 [[LLM: When sharding the document:

@@ -1036,7 +1049,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
   - Extract the section heading and ALL content until the next level 2 section
   - Include all subsections, code blocks, diagrams, lists, tables, etc.
   - Be extremely careful with:
-     - Fenced code blocks (```) - ensure you capture the full block including closing backticks
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
     - Mermaid diagrams - preserve the complete diagram syntax
     - Nested markdown elements
     - Multi-line content that might contain ## inside code blocks
@@ -1055,7 +1068,7 @@ For each extracted section:

 2. **Adjust heading levels**:

-   - The level 2 heading becomes level 1 (# instead of ##)
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
   - All subsection levels decrease by 1:

   ```txt
@@ -1085,7 +1098,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
  ...
-```text
+```

 ### 5. Preserve Special Content

@@ -1149,6 +1162,8 @@ Document sharded successfully:
 ==================== START: templates#prd-tmpl ====================
 # {{Project Name}} Product Requirements Document (PRD)

+[[LLM: The default path and filename unless specified is docs/prd.md]]
+
 [[LLM: If available, review any provided document or ask if any are optionally available: Project Brief]]

 ## Goals and Background Context
@@ -1265,7 +1280,7 @@ Document sharded successfully:
 CRITICAL: Epics MUST be logically sequential following agile best practices:

 - Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality
- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page
+- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page - remember this when we produce the stories for the first epic!
 - Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed
 - Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic.
 - Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things.
@@ -1297,7 +1312,7 @@ CRITICAL: Epics MUST be logically sequential following agile best practices:
 [[LLM: CRITICAL STORY SEQUENCING REQUIREMENTS:

 - Stories within each epic MUST be logically sequential
- Each story should be a "vertical slice" delivering complete functionality
+- Each story should be a "vertical slice" delivering complete functionality aside from early enabler stories for project foundation
 - No story should depend on work from a later story or epic
 - Identify and note any direct prerequisite stories
 - Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story.
@@ -1352,6 +1367,8 @@ so that {{benefit}}.
 ==================== START: templates#brownfield-prd-tmpl ====================
 # {{Project Name}} Brownfield Enhancement PRD

+[[LLM: The default path and filename unless specified is docs/prd.md]]
+
 [[LLM: IMPORTANT - SCOPE ASSESSMENT REQUIRED:

 This PRD is for SIGNIFICANT enhancements to existing projects that require comprehensive planning and multiple stories. Before proceeding:
@@ -1592,470 +1609,6 @@ so that {{benefit}}.
 <</REPEAT>>
 ==================== END: templates#brownfield-prd-tmpl ====================

-==================== START: templates#simple-project-prd-tmpl ====================
-# {{Project Name}} Product Requirements Document (PRD)
-
-[[LLM: If available, review any provided document or ask if any are optionally available: Project Brief]]
-
-## Goals and Background Context
-
-[[LLM: Populate the 2 child sections based on what we have received from user description or the provided brief. Allow user to review the 2 sections and offer changes before proceeding]]
-
-### Goals
-
-[[LLM: Bullet list of 1 line desired outcomes the PRD will deliver if successful - user and project desires]]
-
-### Background Context
-
-[[LLM: 1-2 short paragraphs summarizing the background context, such as what we learned in the brief without being redundant with the goals, what and why this solves a problem, what the current landscape or need is etc...]]
-
-### Change Log
-
-[[LLM: Track document versions and changes]]
-
-| Date | Version | Description | Author |
-| :--- | :------ | :---------- | :----- |
-
-## Requirements
-
-[[LLM: Draft the list of functional and non functional requirements under the two child sections, and immediately execute tasks#advanced-elicitation display]]
-
-### Functional
-
-[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with FR`.]]
-@{example: - FR6: The Todo List uses AI to detect and warn against adding potentially duplicate todo items that are worded differently.}
-
-### Non Functional
-
-[[LLM: Each Requirement will be a bullet markdown and an identifier sequence starting with NFR`.]]
-@{example: - NFR1: AWS service usage **must** aim to stay within free-tier limits where feasible.}
-
-^^CONDITION: has_ui^^
-
-## User Interface Design Goals
-
-[[LLM: Capture high-level UI/UX vision to inform story creation and also generate a prompt for Lovable or V0 if the user would like either. Steps:
-
-1. Pre-fill all subsections with educated guesses based on project context
-2. Present the complete rendered section to user
-3. Clearly let the user know where assumptions were made
-4. Ask targeted questions for unclear/missing elements or areas needing more specification
-5. This is NOT detailed UI spec - focus on product vision and user goals
-6. After section completion, immediately apply `tasks#advanced-elicitation` protocol]]
-
-### Overall UX Vision
-
-### Key Interaction Paradigms
-
-### Core Screens and Views
-
-[[LLM: From a product perspective, what are the most critical screens or views necessary to deliver the the PRD values and goals? This is meant to be Conceptual High Level to Drive Rough Epic or User Stories]]
-
-@{example}
-
- Login Screen
- Main Dashboard
- Item Detail Page
- Settings Page
-  @{/example}
-
-### Accessibility: { None, WCAG, etc }
-
-### Branding
-
-[[LLM: Any known branding elements or style guides that must be incorporated?]]
-
-@{example}
-
- Replicate the look and feel of early 1900s black and white cinema, including animated effects replicating film damage or projector glitches during page or state transitions.
- Attached is the full color pallet and tokens for our corporate branding.
-  @{/example}
-
-### Target Device and Platforms
-
-@{example}
-"Web Responsive, and all mobile platforms", "IPhone Only", "ASCII Windows Desktop"
-@{/example}
-
-^^/CONDITION: has_ui^^
-
-## Technical Assumptions
-
-[[LLM: Gather technical decisions that will be used for this simple technical PRD that includes architecture decisions. Steps:
-
-1. Check if `data#technical-preferences` or an attached `technical-preferences` file exists - use it to pre-populate choices
-2. Ask user about: languages, frameworks, starter templates, libraries, APIs, deployment targets
-3. For unknowns, offer guidance based on project goals and MVP scope
-4. Document ALL technical choices with rationale (why this choice fits the project)
-5. These become constraints for the Architect - be specific and complete
-6. After section completion, apply `tasks#advanced-elicitation` protocol.]]
-
-### Repository Structure: { Monorepo, Polyrepo, etc...}
-
-### Service Architecture
-
-[[LLM: CRITICAL DECISION - Document the high-level service architecture (e.g., Monolith, Microservices, Serverless functions within a Monorepo).]]
-
-## Testing requirements
-
-[[LLM: CRITICAL DECISION - Document the testing requirements, unit only, integration, e2e, manual, need for manual testing convenience methods).]]
-
-### Additional Technical Assumptions and Requests
-
-[[LLM: Throughout the entire process of drafting this document, if any other technical assumptions are raised or discovered appropriate for the architect, add them here as additional bulleted items]]
-
-## Data Models
-
-[[LLM: Define the core data models/entities that will be used in the front end (if there is one), core application or back end, and if both, shared between frontend and backend:
-
-1. Review PRD requirements and identify key business entities
-2. For each model, explain its purpose and relationships
-3. Include key attributes and data types
-4. Show relationships between models
-5. Create TypeScript interfaces that can be shared
-6. Discuss design decisions with user
-
-Create a clear conceptual model before moving to database schema.
-
-After presenting all data models, apply `tasks#advanced-elicitation` protocol]]
-
-<<REPEAT: data_model>>
-
-### {{model_name}}
-
-**Purpose:** {{model_purpose}}
-
-**Key Attributes:**
-
- {{attribute_1}}: {{type_1}} - {{description_1}}
- {{attribute_2}}: {{type_2}} - {{description_2}}
-
-**TypeScript Interface:**
-
-````typescript
-{
-  {
-    model_interface;
-  }
-}
-```text
-
-**Relationships:**
-
- {{relationship_1}}
- {{relationship_2}}
-  <</REPEAT>>
-
-@{example: data_model}
-
-### User
-
-**Purpose:** Represents authenticated users in the system
-
-**Key Attributes:**
-
- id: string - Unique identifier
- email: string - User's email address
- name: string - Display name
- role: enum - User permission level
- timestamps: Date - Created and updated times
-
-**TypeScript Interface:**
-
-```typescript
-interface User {
-  id: string;
-  email: string;
-  name: string;
-  role: "admin" | "user" | "guest";
-  createdAt: Date;
-  updatedAt: Date;
-  profile?: UserProfile;
-}
-
-interface UserProfile {
-  avatarUrl?: string;
-  bio?: string;
-  preferences: Record<string, any>;
-}
-````
-
-**Relationships:**
-
- Has many Posts (1:n)
- Has one Profile (1:1)
-  @{/example}
-
-## REST API Spec
-
-[[LLM: Based on the chosen API style from Tech Stack:
-
-1. If REST API, create an OpenAPI 3.0 specification
-2. If GraphQL, provide the GraphQL schema
-3. If tRPC, show router definitions
-4. Include all endpoints from epics/stories
-5. Define request/response schemas based on data models
-6. Document authentication requirements
-7. Include example requests/responses
-
-Use appropriate format for the chosen API style. If no API (e.g., static site), skip this section.]]
-
-^^CONDITION: has_rest_api^^
-
-````yml
-openapi: 3.0.0
-info:
-  title:
-    '[object Object]': null
-  version:
-    '[object Object]': null
-  description:
-    '[object Object]': null
-servers:
-  - url:
-      '[object Object]': null
-    description:
-      '[object Object]': null
-```text
-
-^^/CONDITION: has_rest_api^^
-
-^^CONDITION: has_graphql_api^^
-
-```graphql
-# GraphQL Schema
-{{graphql_schema}}
-````
-
-^^/CONDITION: has_graphql_api^^
-
-^^CONDITION: has_trpc_api^^
-
-```typescript
-// tRPC Router Definitions
-{
-  {
-    trpc_routers;
-  }
-}
-```
-
-^^/CONDITION: has_trpc_api^^
-
-[[LLM: After presenting the API spec (or noting its absence if not applicable), apply `tasks#advanced-elicitation` protocol]]
-
-## Components
-
-[[LLM: Based on the architectural patterns, tech stack, and data models from above:
-
-1. Identify major logical components/services across the fullstack
-2. Consider both frontend and backend components
-3. Define clear boundaries and interfaces between components
-4. For each component, specify:
-
- Primary responsibility
- Key interfaces/APIs exposed
- Dependencies on other components
- Technology specifics based on tech stack choices
-
-5. Create component diagrams where helpful
-6. After presenting all components, apply `tasks#advanced-elicitation` protocol]]
-
-<<REPEAT: component>>
-
-### {{component_name}}
-
-**Responsibility:** {{component_description}}
-
-**Key Interfaces:**
-
- {{interface_1}}
- {{interface_2}}
-
-**Dependencies:** {{dependencies}}
-
-**Technology Stack:** {{component_tech_details}}
-<</REPEAT>>
-
-### Component Diagrams
-
-[[LLM: Create Mermaid diagrams to visualize component relationships. Options:
-
- C4 Container diagram for high-level view
- Component diagram for detailed internal structure
- Sequence diagrams for complex interactions
-  Choose the most appropriate for clarity
-
-After presenting the diagrams, apply `tasks#advanced-elicitation` protocol]]
-
-## External APIs
-
-[[LLM: For each external service integration:
-
-1. Identify APIs needed based on PRD requirements and component design
-2. If documentation URLs are unknown, ask user for specifics
-3. Document authentication methods and security considerations
-4. List specific endpoints that will be used
-5. Note any rate limits or usage constraints
-
-If no external APIs are needed, state this explicitly and skip to next section.]]
-
-^^CONDITION: has_external_apis^^
-
-<<REPEAT: external_api>>
-
-### {{api_name}} API
-
- **Purpose:** {{api_purpose}}
- **Documentation:** {{api_docs_url}}
- **Base URL(s):** {{api_base_url}}
- **Authentication:** {{auth_method}}
- **Rate Limits:** {{rate_limits}}
-
-**Key Endpoints Used:**
-<<REPEAT: endpoint>>
-
- `{{method}} {{endpoint_path}}` - {{endpoint_purpose}}
-  <</REPEAT>>
-
-**Integration Notes:** {{integration_considerations}}
-<</REPEAT>>
-
-@{example: external_api}
-
-### Stripe API
-
- **Purpose:** Payment processing and subscription management
- **Documentation:** https://stripe.com/docs/api
- **Base URL(s):** `https://api.stripe.com/v1`
- **Authentication:** Bearer token with secret key
- **Rate Limits:** 100 requests per second
-
-**Key Endpoints Used:**
-
- `POST /customers` - Create customer profiles
- `POST /payment_intents` - Process payments
- `POST /subscriptions` - Manage subscriptions
-  @{/example}
-
-^^/CONDITION: has_external_apis^^
-
-[[LLM: After presenting external APIs (or noting their absence), apply `tasks#advanced-elicitation` protocol]]
-
-## Coding Standards
-
-[[LLM: Define MINIMAL but CRITICAL standards for AI agents. Focus only on project-specific rules that prevent common mistakes. These will be used by dev agents.
-
-After presenting this section, apply `tasks#advanced-elicitation` protocol]]
-
-### Critical Fullstack Rules
-
-<<REPEAT: critical_rule>>
-
- **{{rule_name}}:** {{rule_description}}
-  <</REPEAT>>
-
-@{example: critical_rules}
-
- **Type Sharing:** Always define types in packages/shared and import from there
- **API Calls:** Never make direct HTTP calls - use the service layer
- **Environment Variables:** Access only through config objects, never process.env directly
- **Error Handling:** All API routes must use the standard error handler
- **State Updates:** Never mutate state directly - use proper state management patterns
-  @{/example}
-
-### Naming Conventions
-
-| Element         | Frontend             | Backend    | Example             |
-| :-------------- | :------------------- | :--------- | :------------------ |
-| Components      | PascalCase           | -          | `UserProfile.tsx`   |
-| Hooks           | camelCase with 'use' | -          | `useAuth.ts`        |
-| API Routes      | -                    | kebab-case | `/api/user-profile` |
-| Database Tables | -                    | snake_case | `user_profiles`     |
-
-## Epics
-
-[[LLM: First, present a high-level list of all epics for user approval, the epic_list and immediately execute tasks#advanced-elicitation display. Each epic should have a title and a short (1 sentence) goal statement. This allows the user to review the overall structure before diving into details.
-
-CRITICAL: Epics MUST be logically sequential following agile best practices:
-
- Each epic should deliver a significant, end-to-end, fully deployable increment of testable functionality
- Epic 1 must establish foundational project infrastructure (app setup, Git, CI/CD, core services) unless we are adding new functionality to an existing app, while also delivering an initial piece of functionality, even as simple as a health-check route or display of a simple canary page
- Each subsequent epic builds upon previous epics' functionality delivering major blocks of functionality that provide tangible value to users or business when deployed
- Not every project needs multiple epics, an epic needs to deliver value. For example, an API completed can deliver value even if a UI is not complete and planned for a separate epic.
- Err on the side of less epics, but let the user know your rationale and offer options for splitting them if it seems some are too large or focused on disparate things.
- Cross Cutting Concerns should flow through epics and stories and not be final stories. For example, adding a logging framework as a last story of an epic, or at the end of a project as a final epic or story would be terrible as we would not have logging from the beginning.]]
-
-<<REPEAT: epic_list>>
-
- Epic{{epic_number}} {{epic_title}}: {{short_goal}}
-
-<</REPEAT>>
-
-@{example: epic_list}
-
-1. Foundation & Core Infrastructure: Establish project setup, authentication, and basic user management
-2. Core Business Entities: Create and manage primary domain objects with CRUD operations
-3. User Workflows & Interactions: Enable key user journeys and business processes
-4. Reporting & Analytics: Provide insights and data visualization for users
-
-@{/example}
-
-[[LLM: After the epic list is approved, present each `epic_details` with all its stories and acceptance criteria as a complete review unit and immediately execute tasks#advanced-elicitation display, before moving on to the next epic.]]
-
-<<REPEAT: epic_details>>
-
-## Epic {{epic_number}} {{epic_title}}
-
-{{epic_goal}} [[LLM: Expanded goal - 2-3 sentences describing the objective and value all the stories will achieve]]
-
-[[LLM: CRITICAL STORY SEQUENCING REQUIREMENTS:
-
- Stories within each epic MUST be logically sequential
- Each story should be a "vertical slice" delivering complete functionality
- No story should depend on work from a later story or epic
- Identify and note any direct prerequisite stories
- Focus on "what" and "why" not "how" (leave technical implementation to Architect) yet be precise enough to support a logical sequential order of operations from story to story.
- Ensure each story delivers clear user or business value, try to avoid enablers and build them into stories that deliver value.
- Size stories for AI agent execution: Each story must be completable by a single AI agent in one focused session without context overflow
- Think "junior developer working for 2-4 hours" - stories must be small, focused, and self-contained
- If a story seems complex, break it down further as long as it can deliver a vertical slice
- Each story should result in working, testable code before the agent's context window fills]]
-
-<<REPEAT: story>>
-
-### Story {{epic_number}}.{{story_number}} {{story_title}}
-
-As a {{user_type}},
-I want {{action}},
-so that {{benefit}}.
-
-#### Acceptance Criteria
-
-[[LLM: Define clear, comprehensive, and testable acceptance criteria that:
-
- Precisely define what "done" means from a functional perspective
- Are unambiguous and serve as basis for verification
- Include any critical non-functional requirements from the PRD
- Consider local testability for backend/data components
- Specify UI/UX requirements and framework adherence where applicable
- Avoid cross-cutting concerns that should be in other stories or PRD sections]]
-
-<<REPEAT: criteria>>
-
- {{criterion number}}: {{criteria}}
-
-<</REPEAT>>
-<</REPEAT>>
-<</REPEAT>>
-
-## Next Steps
-
-### Design Architect Prompt
-
-[[LLM: This section will contain the prompt for the Design Architect, keep it short and to the point to initiate create architecture mode using this document as input.]]
-==================== END: templates#simple-project-prd-tmpl ====================
-
 ==================== START: checklists#pm-checklist ====================
 # Product Manager (PM) Requirements Checklist

--- a/dist/agents/po.txt
+++ b/dist/agents/po.txt
@@ -43,7 +43,7 @@ These references map directly to bundle sections:

 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:

-```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
@@ -75,15 +75,15 @@ persona:
 startup:
  - Greet the user with your name and role, and inform of the *help command.
 commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) Product Owner consultation with advanced-elicitation'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*execute-checklist {checklist}" - Run validation checklist (default->po-master-checklist)'
-  - '*shard-doc {document}" - Break down document into actionable parts'
-  - '*correct-course" - Analyze and suggest project course corrections'
-  - '*create-epic" - Create epic for brownfield projects (task brownfield-create-epic)'
-  - '*create-story" - Create user story from requirements (task brownfield-create-story)'
-  - '*exit" - Say Goodbye, You are no longer this Agent'
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) Product Owner consultation with advanced-elicitation
+  - create-doc {template}: Create doc (no template = show available templates)
+  - execute-checklist {checklist}: Run validation checklist (default->po-master-checklist)
+  - shard-doc {document}: Break down document into actionable parts
+  - correct-course: Analyze and suggest project course corrections
+  - create-epic: Create epic for brownfield projects (task brownfield-create-epic)
+  - create-story: Create user story from requirements (task brownfield-create-story)
+  - exit: Say goodbye as the Product Owner, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - execute-checklist
@@ -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
@@ -210,9 +206,27 @@ The LLM will:
 - Create a folder structure to organize the sharded documents
 - Maintain all content integrity including code blocks, diagrams, and markdown formatting

-## Recommended Method: @kayvan/markdown-tree-parser
+## Primary Method: Automatic with markdown-tree

-[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
+[[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}`.
+
+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
+
+**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
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]

 ### Installation and Usage

@@ -245,19 +259,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu

 ---

-## Manual Method (if @kayvan/markdown-tree-parser is not available)
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)

 [[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]

 ### Task Instructions

-### 1. Identify Document and Target Location
+1. Identify Document and Target Location

 - Determine which document to shard (user-provided path)
 - Create a new folder under `docs/` with the same name as the document (without extension)
 - Example: `docs/prd.md` → create folder `docs/prd/`

-### 2. Parse and Extract Sections
+2. Parse and Extract Sections

 [[LLM: When sharding the document:

@@ -267,7 +281,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
   - Extract the section heading and ALL content until the next level 2 section
   - Include all subsections, code blocks, diagrams, lists, tables, etc.
   - Be extremely careful with:
-     - Fenced code blocks (```) - ensure you capture the full block including closing backticks
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
     - Mermaid diagrams - preserve the complete diagram syntax
     - Nested markdown elements
     - Multi-line content that might contain ## inside code blocks
@@ -286,7 +300,7 @@ For each extracted section:

 2. **Adjust heading levels**:

-   - The level 2 heading becomes level 1 (# instead of ##)
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
   - All subsection levels decrease by 1:

   ```txt
@@ -316,7 +330,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
  ...
-```text
+```

 ### 5. Preserve Special Content

@@ -821,6 +835,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
 [[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
 [[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]

+### File List
+
+[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
+
 ### Change Log

 [[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
@@ -828,6 +846,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the

 | Date | Version | Description | Author |
 | :--- | :------ | :---------- | :----- |
+
+## QA Results
+
+[[LLM: QA Agent Results]]
 ==================== END: templates#story-tmpl ====================

 ==================== START: checklists#po-master-checklist ====================
--- a/dist/agents/qa.txt
+++ b/dist/agents/qa.txt
@@ -52,34 +52,35 @@ activation-instructions:
 agent:
  name: Quinn
  id: qa
-  title: Quality Assurance Test Architect
+  title: Senior Developer & QA Architect
  icon: 🧪
-  whenToUse: Use for test planning, test case creation, quality assurance, bug reporting, and testing strategy
+  whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
  customization: null
 persona:
-  role: Test Architect & Automation Expert
-  style: Methodical, detail-oriented, quality-focused, strategic
-  identity: Senior quality advocate with expertise in test architecture and automation
-  focus: Comprehensive testing strategies, automation frameworks, quality assurance at every phase
+  role: Senior Developer & Test Architect
+  style: Methodical, detail-oriented, quality-focused, mentoring, strategic
+  identity: Senior developer with deep expertise in code quality, architecture, and test automation
+  focus: Code excellence through review, refactoring, and comprehensive testing strategies
  core_principles:
+    - Senior Developer Mindset - Review and improve code as a senior mentoring juniors
+    - Active Refactoring - Don't just identify issues, fix them with clear explanations
    - Test Strategy & Architecture - Design holistic testing strategies across all levels
-    - Automation Excellence - Build maintainable and efficient test automation frameworks
+    - Code Quality Excellence - Enforce best practices, patterns, and clean code principles
    - Shift-Left Testing - Integrate testing early in development lifecycle
+    - Performance & Security - Proactively identify and fix performance/security issues
+    - Mentorship Through Action - Explain WHY and HOW when making improvements
    - Risk-Based Testing - Prioritize testing based on risk and critical areas
-    - Performance & Load Testing - Ensure systems meet performance requirements
-    - Security Testing Integration - Incorporate security testing into QA process
-    - Test Data Management - Design strategies for realistic and compliant test data
-    - Continuous Testing & CI/CD - Integrate tests seamlessly into pipelines
-    - Quality Metrics & Reporting - Track meaningful metrics and provide insights
-    - Cross-Browser & Cross-Platform Testing - Ensure comprehensive compatibility
+    - Continuous Improvement - Balance perfection with pragmatism
+    - Architecture & Design Patterns - Ensure proper patterns and maintainable code structure
 startup:
  - Greet the user with your name and role, and inform of the *help command.
 commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) QA consultation with advanced-elicitation for test strategy'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*exit" - Say goodbye as the QA Test Architect, and then abandon inhabiting this persona'
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) QA consultation with advanced-elicitation for test strategy
+  - exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
 dependencies:
+  tasks:
+    - review-story
  data:
    - technical-preferences
  utils:
@@ -87,6 +88,144 @@ dependencies:
 ```
 ==================== END: agents#qa ====================

+==================== START: tasks#review-story ====================
+# review-story
+
+When a developer marks a story as "Ready for Review", perform a comprehensive senior developer code review with the ability to refactor and improve code directly.
+
+[[LLM: QA Agent executing review-story task as Senior Developer]]
+
+## Prerequisites
+
+- Story status must be "Review"
+- Developer has completed all tasks and updated the File List
+- All automated tests are passing
+
+## Review Process
+
+1. **Read the Complete Story**
+   - Review all acceptance criteria
+   - Understand the dev notes and requirements
+   - Note any completion notes from the developer
+
+2. **Focus on the File List**
+   - Verify all files listed were actually created/modified
+   - Check for any missing files that should have been updated
+
+3. **Senior Developer Code Review**
+   - Review code with the eye of a senior developer
+   - If changes form a cohesive whole, review them together
+   - If changes are independent, review incrementally file by file
+   - Focus on:
+     - Code architecture and design patterns
+     - Refactoring opportunities
+     - Code duplication or inefficiencies
+     - Performance optimizations
+     - Security concerns
+     - Best practices and patterns
+
+4. **Active Refactoring**
+   - As a senior developer, you CAN and SHOULD refactor code where improvements are needed
+   - When refactoring:
+     - Make the changes directly in the files
+     - Explain WHY you're making the change
+     - Describe HOW the change improves the code
+     - Ensure all tests still pass after refactoring
+     - Update the File List if you modify additional files
+
+5. **Standards Compliance Check**
+   - Verify adherence to `docs/coding-standards.md`
+   - Check compliance with `docs/unified-project-structure.md`
+   - Validate testing approach against `docs/testing-strategy.md`
+   - Ensure all guidelines mentioned in the story are followed
+
+6. **Acceptance Criteria Validation**
+   - Verify each AC is fully implemented
+   - Check for any missing functionality
+   - Validate edge cases are handled
+
+7. **Test Coverage Review**
+   - Ensure unit tests cover edge cases
+   - Add missing tests if critical coverage is lacking
+   - Verify integration tests (if required) are comprehensive
+   - Check that test assertions are meaningful
+   - Look for missing test scenarios
+
+8. **Documentation and Comments**
+   - Verify code is self-documenting where possible
+   - Add comments for complex logic if missing
+   - Ensure any API changes are documented
+
+## Append Results to Story File
+
+After review and any refactoring, append your results to the story file in the QA Results section:
+
+```markdown
+## QA Results
+
+### Review Date: [Date]
+### Reviewed By: Quinn (Senior Developer QA)
+
+### Code Quality Assessment
+[Overall assessment of implementation quality]
+
+### Refactoring Performed
+[List any refactoring you performed with explanations]
+- **File**: [filename]
+  - **Change**: [what was changed]
+  - **Why**: [reason for change]
+  - **How**: [how it improves the code]
+
+### Compliance Check
+- Coding Standards: [✓/✗] [notes if any]
+- Project Structure: [✓/✗] [notes if any]
+- Testing Strategy: [✓/✗] [notes if any]
+- All ACs Met: [✓/✗] [notes if any]
+
+### Improvements Checklist
+[Check off items you handled yourself, leave unchecked for dev to address]
+
+- [x] Refactored user service for better error handling (services/user.service.ts)
+- [x] Added missing edge case tests (services/user.service.test.ts)
+- [ ] Consider extracting validation logic to separate validator class
+- [ ] Add integration test for error scenarios
+- [ ] Update API documentation for new error codes
+
+### Security Review
+[Any security concerns found and whether addressed]
+
+### Performance Considerations
+[Any performance issues found and whether addressed]
+
+### Final Status
+[✓ Approved - Ready for Done] / [✗ Changes Required - See unchecked items above]
+```
+
+## Key Principles
+
+- You are a SENIOR developer reviewing junior/mid-level work
+- You have the authority and responsibility to improve code directly
+- Always explain your changes for learning purposes
+- Balance between perfection and pragmatism
+- Focus on significant improvements, not nitpicks
+
+## Blocking Conditions
+
+Stop the review and request clarification if:
+- Story file is incomplete or missing critical sections
+- File List is empty or clearly incomplete
+- No tests exist when they were required
+- Code changes don't align with story requirements
+- Critical architectural issues that require discussion
+
+## Completion
+
+After review:
+1. If all items are checked and approved: Update story status to "Done"
+2. If unchecked items remain: Keep status as "Review" for dev to address
+3. Always provide constructive feedback and explanations for learning
+==================== END: tasks#review-story ====================
+
 ==================== START: data#technical-preferences ====================
 # User-Defined Preferred Patterns and Preferences

--- a/dist/agents/sm.txt
+++ b/dist/agents/sm.txt
@@ -46,7 +46,6 @@ CRITICAL: Read the full YML, start activation to alter your state of being, foll
 ```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
  - The customization field ALWAYS takes precedence over any conflicting instructions
  - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
 agent:
@@ -62,31 +61,25 @@ persona:
  identity: Story creation expert who prepares detailed, actionable stories for AI developers
  focus: Creating crystal-clear stories that dumb AI agents can implement without confusion
  core_principles:
-    - Task Adherence - Rigorously follow create-next-story procedures
-    - Checklist-Driven Validation - Apply story-draft-checklist meticulously
-    - Clarity for Developer Handoff - Stories must be immediately actionable
-    - Focus on One Story at a Time - Complete one before starting next
-    - Numbered Options Protocol - Always use numbered lists for selections
+    - Rigorously follow `create-next-story` procedure to generate the detailed user story
+    - Will ensure all information comes from the PRD and Architecture to guide the dumb dev agent
+    - You are NOT allowed to implement stories or modify code EVER!
 startup:
-  - Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Do NOT automatically execute create-next-story tasks during startup
-  - CRITICAL: Do NOT create or modify any files during startup
+  - Greet the user with your name and role, and inform of the *help command and then HALT to await instruction if not given already.
  - Offer to help with story preparation but wait for explicit user confirmation
  - Only execute tasks when user explicitly requests them
-  - 'CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Dev Agent'
 commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - Conversational mode with advanced-elicitation for advice'
-  - '*create" - Execute all steps in Create Next Story Task document'
-  - '*pivot" - Run correct-course task (ensure no story already created first)'
-  - '*checklist {checklist}" - Show numbered list of checklists, execute selection'
-  - '*doc-shard {PRD|Architecture|Other}" - Execute shard-doc task'
-  - '*index-docs" - Update documentation index in /docs/index.md'
-  - '*exit" - Say goodbye as the Scrum Master, and then abandon inhabiting this persona'
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: Conversational mode with advanced-elicitation for advice
+  - create|draft: Execute create-next-story
+  - pivot: Execute `correct-course` task
+  - checklist {checklist}: Show numbered list of checklists, execute selection
+  - exit: Say goodbye as the Scrum Master, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - create-next-story
    - execute-checklist
+    - course-correct
  templates:
    - story-tmpl
  checklists:
@@ -103,45 +96,42 @@ dependencies:

 To identify the next logical story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Story Template`. This task ensures the story is enriched with all necessary technical context, requirements, and acceptance criteria, making it ready for efficient implementation by a Developer Agent with minimal need for additional research.

-## Inputs for this Task
-
- Access to the project's documentation repository, specifically:
-  - `docs/index.md` (hereafter "Index Doc")
-  - All Epic files - located in one of these locations:
-    - Primary: `docs/prd/epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
-    - Secondary: `docs/epics/epic-{n}-{description}.md`
-    - User-specified location if not found in above paths
-  - Existing story files in `docs/stories/`
-  - Main PRD (hereafter "PRD Doc")
-  - Main Architecture Document (hereafter "Main Arch Doc")
-  - Frontend Architecture Document (hereafter "Frontend Arch Doc," if relevant)
-  - Project Structure Guide (`docs/project-structure.md`)
-  - Operational Guidelines Document (`docs/operational-guidelines.md`)
-  - Technology Stack Document (`docs/tech-stack.md`)
-  - Data Models Document (as referenced in Index Doc)
-  - API Reference Document (as referenced in Index Doc)
-  - UI/UX Specifications, Style Guides, Component Guides (if relevant, as referenced in Index Doc)
- The `bmad-core/templates/story-tmpl.md` (hereafter "Story Template")
- The `bmad-core/checklists/story-draft-checklist.md` (hereafter "Story Draft Checklist")
- User confirmation to proceed with story identification and, if needed, to override warnings about incomplete prerequisite stories.
-
 ## Task Execution Instructions

+### 0. Load Core Configuration
+
+[[LLM: CRITICAL - This MUST be your first step]]
+
+- Load `.bmad-core/core-config.yml` 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."
+- Extract the following key configurations:
+  - `devStoryLocation`: Where to save story files
+  - `prd.prdSharded`: Whether PRD is sharded or monolithic
+  - `prd.prdFile`: Location of monolithic PRD (if not sharded)
+  - `prd.prdShardedLocation`: Location of sharded epic files
+  - `prd.epicFilePattern`: Pattern for epic files (e.g., `epic-{n}*.md`)
+  - `architecture.architectureVersion`: Architecture document version
+  - `architecture.architectureSharded`: Whether architecture is sharded
+  - `architecture.architectureFile`: Location of monolithic architecture
+  - `architecture.architectureShardedLocation`: Location of sharded architecture files
+
 ### 1. Identify Next Story for Preparation

 #### 1.1 Locate Epic Files

- First, determine where epic files are located:
-  - Check `docs/prd/` for files matching pattern `epic-{n}-*.md`
-  - If not found, check `docs/epics/` for files matching pattern `epic-{n}-*.md`
-  - If still not found, ask user: "Unable to locate epic files. Please specify the path where epic files are stored."
- Note: Epic files follow naming convention `epic-{n}-{description}.md` (e.g., `epic-1-foundation-core-infrastructure.md`)
+- Based on `prdSharded` from config:
+  - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
+  - **If `prdSharded: false`**: Load the full PRD from `prdFile` and extract epics from section headings (## Epic N or ### Epic N)

 #### 1.2 Review Existing Stories

- Review `docs/stories/` to find the highest-numbered story file.
+- Check `devStoryLocation` from config (e.g., `docs/stories/`) for existing story files
+- If the directory exists and has at least 1 file, find the highest-numbered story file.
 - **If a highest story file exists (`{lastEpicNum}.{lastStoryNum}.story.md`):**
-
  - Verify its `Status` is 'Done' (or equivalent).
  - If not 'Done', present an alert to the user:

@@ -159,17 +149,45 @@ To identify the next logical story based on project progress and epic definition
    ```

  - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}-*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}-*.md`, then `epic-{lastEpicNum + 2}-*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.

 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".

-### 2. Gather Core Story Requirements (from Epic File)
+### 2. Gather Core Story Requirements (from Epic)

- For the identified story, open its parent Epic File (e.g., `epic-{epicNum}-*.md` from the location identified in step 1.1).
+- For the identified story, review its parent Epic (e.g., `epic-{epicNum}*.md` from the location identified in step 1.1).
 - Extract: Exact Title, full Goal/User Story statement, initial list of Requirements, all Acceptance Criteria (ACs), and any predefined high-level Tasks.
 - Keep a record of this original epic-defined scope for later deviation analysis.

@@ -178,7 +196,7 @@ To identify the next logical story based on project progress and epic definition
 [[LLM: This step is CRITICAL for continuity and learning from implementation experience]]

 - If this is not the first story (i.e., previous story exists):
-  - Read the previous story file: `docs/stories/{prevEpicNum}.{prevStoryNum}.story.md`
+  - Read the previous sequential story from `docs/stories`
  - Pay special attention to:
    - Dev Agent Record sections (especially Completion Notes and Debug Log References)
    - Any deviations from planned implementation
@@ -187,18 +205,30 @@ To identify the next logical story based on project progress and epic definition
    - Any "lessons learned" or notes for future stories
  - Extract relevant insights that might inform the current story's preparation

-### 4. Gather & Synthesize Architecture Context from Sharded Docs
+### 4. Gather & Synthesize Architecture Context

-[[LLM: CRITICAL - You MUST gather technical details from the sharded architecture documents. NEVER make up technical details not found in these documents.]]
+[[LLM: CRITICAL - You MUST gather technical details from the architecture documents. NEVER make up technical details not found in these documents.]]

-#### 4.1 Start with Architecture Index
+#### 4.1 Determine Architecture Document Strategy

- Read `docs/architecture/index.md` to understand the full scope of available documentation
- Identify which sharded documents are most relevant to the current story
+Based on configuration loaded in Step 0:

-#### 4.2 Recommended Reading Order Based on Story Type
+- **If `architectureVersion: v4` and `architectureSharded: true`**:
+  - Read `{architectureShardedLocation}/index.md` to understand available documentation
+  - Follow the structured reading order in section 4.2 below
  
-[[LLM: Read documents in this order, but ALWAYS verify relevance to the specific story. Skip irrelevant sections but NEVER skip documents that contain information needed for the story.]]
+- **If `architectureVersion: v4` and `architectureSharded: false`**:
+  - Load the monolithic architecture from `architectureFile`
+  - Extract relevant sections based on v4 structure (tech stack, project structure, etc.)
+  
+- **If `architectureVersion` is NOT v4**:
+  - Inform user: "Architecture document is not v4 format. Will use best judgment to find relevant information."
+  - If `architectureSharded: true`: Search sharded files by filename relevance
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
+
+#### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
+
+[[LLM: Use this structured approach ONLY for v4 sharded architecture. For other versions, use best judgment based on file names and content.]]

 **For ALL Stories:**

@@ -207,9 +237,18 @@ To identify the next logical story based on project progress and epic definition
 3. `docs/architecture/coding-standards.md` - Ensure dev follows project conventions
 4. `docs/architecture/testing-strategy.md` - Include testing requirements in tasks

-**For Backend/API Stories, additionally read:** 5. `docs/architecture/data-models.md` - Data structures and validation rules 6. `docs/architecture/database-schema.md` - Database design and relationships 7. `docs/architecture/backend-architecture.md` - Service patterns and structure 8. `docs/architecture/rest-api-spec.md` - API endpoint specifications 9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)
+**For Backend/API Stories, additionally read:**
+5. `docs/architecture/data-models.md` - Data structures and validation rules
+6. `docs/architecture/database-schema.md` - Database design and relationships
+7. `docs/architecture/backend-architecture.md` - Service patterns and structure
+8. `docs/architecture/rest-api-spec.md` - API endpoint specifications
+9. `docs/architecture/external-apis.md` - Third-party integrations (if relevant)

-**For Frontend/UI Stories, additionally read:** 5. `docs/architecture/frontend-architecture.md` - Component structure and patterns 6. `docs/architecture/components.md` - Specific component designs 7. `docs/architecture/core-workflows.md` - User interaction flows 8. `docs/architecture/data-models.md` - Frontend data handling
+**For Frontend/UI Stories, additionally read:**
+5. `docs/architecture/frontend-architecture.md` - Component structure and patterns
+6. `docs/architecture/components.md` - Specific component designs
+7. `docs/architecture/core-workflows.md` - User interaction flows
+8. `docs/architecture/data-models.md` - Frontend data handling

 **For Full-Stack Stories:**

@@ -242,7 +281,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`

 ### 6. Populate Story Template with Full Context

- Create a new story file: `docs/stories/{epicNum}.{storyNum}.story.md`.
+- Create a new story file: `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config).
 - Use the Story Template to structure the file.
 - Fill in:
  - Story `{EpicNum}.{StoryNum}: {Short Title Copied from Epic File}`
@@ -289,7 +328,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
- Save the story file to `docs/stories/{epicNum}.{storyNum}.story.md`
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)

 ### 9. Report Completion

@@ -310,13 +349,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

@@ -325,7 +360,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
@@ -460,6 +495,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the
 [[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update - remove this line to the SM]]
 [[LLM: (Dev Agent) Anything the SM needs to know that deviated from the story that might impact drafting the next story.]]

+### File List
+
+[[LLM: (Dev Agent) List every new file created, or existing file modified in a bullet list.]]
+
 ### Change Log

 [[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update- remove this line to the SM]]
@@ -467,6 +506,10 @@ Manual Test Steps: [[LLM: Include how if possible the user can manually test the

 | Date | Version | Description | Author |
 | :--- | :------ | :---------- | :----- |
+
+## QA Results
+
+[[LLM: QA Agent Results]]
 ==================== END: templates#story-tmpl ====================

 ==================== START: checklists#story-draft-checklist ====================
--- a/dist/agents/ux-expert.txt
+++ b/dist/agents/ux-expert.txt
@@ -79,13 +79,13 @@ startup:
  - Greet the user with your name and role, and inform of the *help command.
  - Always start by understanding the user's context, goals, and constraints before proposing solutions.
 commands:
-  - '*help" - Show: numbered list of the following commands to allow selection'
-  - '*chat-mode" - (Default) UX consultation with advanced-elicitation for design decisions'
-  - '*create-doc {template}" - Create doc (no template = show available templates)'
-  - '*generate-ui-prompt" - Create AI frontend generation prompt'
-  - '*research {topic}" - Generate deep research prompt for UX investigation'
-  - '*execute-checklist {checklist}" - Run design validation checklist'
-  - '*exit" - Say goodbye as the UX Expert, and then abandon inhabiting this persona'
+  - help: Show numbered list of the following commands to allow selection
+  - chat-mode: (Default) UX consultation with advanced-elicitation for design decisions
+  - create-doc {template}: Create doc (no template = show available templates)
+  - generate-ui-prompt: Create AI frontend generation prompt
+  - research {topic}: Generate deep research prompt for UX investigation
+  - execute-checklist {checklist}: Run design validation checklist
+  - exit: Say goodbye as the UX Expert, and then abandon inhabiting this persona
 dependencies:
  tasks:
    - generate-ai-frontend-prompt
@@ -493,9 +493,9 @@ Confirm with the user their preferred interaction style:

 ### 3. Execute Template

- Load specified template from `templates#*` or the /templates directory
+- Load specified template from `templates#*` or the `{root}/templates directory`
 - Follow ALL embedded LLM instructions within the template
- Process template markup according to `utils#template-format` conventions
+- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions

 ### 4. Template Processing Rules

@@ -541,13 +541,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 +552,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
@@ -639,6 +635,8 @@ The LLM will:
 ==================== START: templates#front-end-spec-tmpl ====================
 # {{Project Name}} UI/UX Specification

+[[LLM: The default path and filename unless specified is docs/front-end-spec.md]]
+
 [[LLM: Review provided documents including Project Brief, PRD, and any user research to gather context. Focus on understanding user needs, pain points, and desired outcomes before beginning the specification.]]

 ## Introduction
@@ -715,7 +713,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]

 ```mermaid
 {{sitemap_diagram}}
-```text
+```

@{example: sitemap}

@@ -770,7 +768,7 @@ Create subsections for each major flow. After presenting all flows, apply `tasks

 ```mermaid
 {{flow_diagram}}
-```text
+```

 **Edge Cases & Error Handling:**

--- a/dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.txt
+++ b/dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.txt
--- a/dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.txt
+++ b/dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.txt
@@ -107,6 +107,102 @@ dependencies:
 ```
 ==================== END: agents#game-developer ====================

+==================== START: tasks#execute-checklist ====================
+# Checklist Validation Task
+
+This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
+
+## 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 {root}/checklists folder to select the appropriate one to run.
+
+## Instructions
+
+1. **Initial Assessment**
+
+   - 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 {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
+   - Confirm if they want to work through the checklist:
+     - Section by section (interactive mode - very time consuming)
+     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
+
+2. **Document and Artifact Gathering**
+
+   - Each checklist will specify its required documents/artifacts at the beginning
+   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
+
+3. **Checklist Processing**
+
+   If in interactive mode:
+
+   - Work through each section of the checklist one at a time
+   - For each section:
+     - Review all items in the section following instructions for that section embedded in the checklist
+     - Check each item against the relevant documentation or artifacts as appropriate
+     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
+     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
+
+   If in YOLO mode:
+
+   - Process all sections at once
+   - Create a comprehensive report of all findings
+   - Present the complete analysis to the user
+
+4. **Validation Approach**
+
+   For each checklist item:
+
+   - Read and understand the requirement
+   - Look for evidence in the documentation that satisfies the requirement
+   - Consider both explicit mentions and implicit coverage
+   - Aside from this, follow all checklist llm instructions
+   - Mark items as:
+     - ✅ PASS: Requirement clearly met
+     - ❌ FAIL: Requirement not met or insufficient coverage
+     - ⚠️ PARTIAL: Some aspects covered but needs improvement
+     - N/A: Not applicable to this case
+
+5. **Section Analysis**
+
+   For each section:
+
+   - think step by step to calculate pass rate
+   - Identify common themes in failed items
+   - Provide specific recommendations for improvement
+   - In interactive mode, discuss findings with user
+   - Document any user decisions or explanations
+
+6. **Final Report**
+
+   Prepare a summary that includes:
+
+   - Overall checklist completion status
+   - Pass rates by section
+   - List of failed items with context
+   - Specific recommendations for improvement
+   - Any sections or items marked as N/A with justification
+
+## Checklist Execution Methodology
+
+Each checklist now contains embedded LLM prompts and instructions that will:
+
+1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
+2. **Request specific artifacts** - Clear instructions on what documents/access is needed
+3. **Provide contextual guidance** - Section-specific prompts for better validation
+4. **Generate comprehensive reports** - Final summary with detailed findings
+
+The LLM will:
+
+- Execute the complete checklist validation
+- Present a final report with pass/fail rates and key findings
+- Offer to provide detailed analysis of any section, especially those with warnings or failures
+==================== END: tasks#execute-checklist ====================
+
 ==================== START: templates#game-architecture-tmpl ====================
 # {{Game Title}} Game Architecture Document

@@ -190,7 +286,7 @@ This architecture is designed to support the gameplay mechanics defined in the G
 │   ├── stories/         # Development stories
 │   └── architecture/    # Technical docs
 └── dist/                # Built game files
-```text
+```

 ### Module Organization

@@ -475,7 +571,7 @@ const gameConfig: Phaser.Types.Core.GameConfig = {
    },
    // Additional configuration...
 };
-```text
+```

 ### Game Balance Configuration

@@ -676,6 +772,7 @@ export const GameBalance = {
 ## Story Completeness

 ### Basic Story Elements
+
 - [ ] **Story Title** - Clear, descriptive title that identifies the feature
 - [ ] **Epic Assignment** - Story is properly assigned to relevant epic
 - [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -683,6 +780,7 @@ export const GameBalance = {
 - [ ] **Description** - Clear, concise description of what needs to be implemented

 ### Game Design Alignment
+
 - [ ] **GDD Reference** - Specific Game Design Document section referenced
 - [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
 - [ ] **Player Experience Goal** - Describes the intended player experience
@@ -692,6 +790,7 @@ export const GameBalance = {
 ## Technical Specifications

 ### Architecture Compliance
+
 - [ ] **File Organization** - Follows game architecture document structure
 - [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
 - [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -699,6 +798,7 @@ export const GameBalance = {
 - [ ] **Dependencies** - All system dependencies clearly identified

 ### Phaser 3 Requirements
+
 - [ ] **Scene Integration** - Specifies which scenes are affected and how
 - [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
 - [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -706,6 +806,7 @@ export const GameBalance = {
 - [ ] **Performance Considerations** - 60 FPS target and optimization requirements

 ### Code Quality Standards
+
 - [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
 - [ ] **Error Handling** - Error scenarios and handling requirements specified
 - [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -715,6 +816,7 @@ export const GameBalance = {
 ## Implementation Readiness

 ### Acceptance Criteria
+
 - [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
 - [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
 - [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -722,6 +824,7 @@ export const GameBalance = {
 - [ ] **Completeness** - No acceptance criteria are vague or unmeasurable

 ### Implementation Tasks
+
 - [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
 - [ ] **Task Scope** - Each task is completable in 1-4 hours
 - [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -729,6 +832,7 @@ export const GameBalance = {
 - [ ] **Development Flow** - Tasks follow logical implementation order

 ### Dependencies
+
 - [ ] **Story Dependencies** - All prerequisite stories identified with IDs
 - [ ] **Technical Dependencies** - Required systems and files identified
 - [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -738,6 +842,7 @@ export const GameBalance = {
 ## Testing Requirements

 ### Test Coverage
+
 - [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
 - [ ] **Integration Test Cases** - Integration testing with other game systems specified
 - [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -745,6 +850,7 @@ export const GameBalance = {
 - [ ] **Edge Case Testing** - Edge cases and error conditions covered

 ### Test Implementation
+
 - [ ] **Test File Paths** - Exact test file locations specified
 - [ ] **Test Scenarios** - All test scenarios are complete and executable
 - [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -754,6 +860,7 @@ export const GameBalance = {
 ## Game-Specific Quality

 ### Gameplay Implementation
+
 - [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
 - [ ] **Player Controls** - Input handling requirements are complete
 - [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -761,6 +868,7 @@ export const GameBalance = {
 - [ ] **State Management** - Game state changes and persistence requirements defined

 ### User Experience
+
 - [ ] **UI Requirements** - User interface elements and behaviors specified
 - [ ] **Audio Integration** - Sound effect and music requirements defined
 - [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -768,6 +876,7 @@ export const GameBalance = {
 - [ ] **Error Recovery** - User-facing error handling and recovery specified

 ### Performance Optimization
+
 - [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
 - [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
 - [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -777,6 +886,7 @@ export const GameBalance = {
 ## Documentation and Communication

 ### Story Documentation
+
 - [ ] **Implementation Notes** - Additional context and implementation guidance provided
 - [ ] **Design Decisions** - Key design choices documented with rationale
 - [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -784,6 +894,7 @@ export const GameBalance = {
 - [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs

 ### Developer Handoff
+
 - [ ] **Immediate Actionability** - Developer can start implementation without additional questions
 - [ ] **Complete Context** - All necessary context provided within the story
 - [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -793,6 +904,7 @@ export const GameBalance = {
 ## Final Validation

 ### Story Readiness
+
 - [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
 - [ ] **Technical Completeness** - All technical requirements are specified and actionable
 - [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -800,6 +912,7 @@ export const GameBalance = {
 - [ ] **Review Completion** - Story has been reviewed for completeness and accuracy

 ### Implementation Preparedness
+
 - [ ] **Environment Ready** - Development environment requirements specified
 - [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
 - [ ] **Testing Prepared** - Testing environment and data requirements specified
@@ -828,6 +941,7 @@ This document establishes coding standards, architectural patterns, and developm
 ### Strict Mode Configuration

 **Required tsconfig.json settings:**
+
 ```json
 {
  "compilerOptions": {
@@ -841,11 +955,12 @@ This document establishes coding standards, architectural patterns, and developm
    "exactOptionalPropertyTypes": true
  }
 }
-```text
+```

 ### Type Definitions

 **Game Object Interfaces:**
+
 ```typescript
 // Core game entity interface
 interface GameEntity {
@@ -869,9 +984,10 @@ interface GameSystem {
  update(delta: number): void;
  shutdown(): void;
 }
-```text
+```

 **Scene Data Interfaces:**
+
 ```typescript
 // Scene transition data
 interface SceneData {
@@ -889,28 +1005,32 @@ interface GameState {
 interface GameSettings {
  musicVolume: number;
  sfxVolume: number;
-  difficulty: 'easy' | 'normal' | 'hard';
+  difficulty: "easy" | "normal" | "hard";
  controls: ControlScheme;
 }
-```text
+```

 ### Naming Conventions

 **Classes and Interfaces:**
+
 - PascalCase for classes: `PlayerSprite`, `GameManager`, `AudioSystem`
 - PascalCase with 'I' prefix for interfaces: `IGameEntity`, `IPlayerController`
 - Descriptive names that indicate purpose: `CollisionManager` not `CM`

 **Methods and Variables:**
+
 - camelCase for methods and variables: `updatePosition()`, `playerSpeed`
 - Descriptive names: `calculateDamage()` not `calcDmg()`
 - Boolean variables with is/has/can prefix: `isActive`, `hasCollision`, `canMove`

 **Constants:**
+
 - UPPER_SNAKE_CASE for constants: `MAX_PLAYER_SPEED`, `DEFAULT_VOLUME`
 - Group related constants in enums or const objects

 **Files and Directories:**
+
 - kebab-case for file names: `player-controller.ts`, `audio-manager.ts`
 - PascalCase for scene files: `MenuScene.ts`, `GameScene.ts`

@@ -919,18 +1039,19 @@ interface GameSettings {
 ### Scene Organization

 **Scene Lifecycle Management:**
+
 ```typescript
 class GameScene extends Phaser.Scene {
  private gameManager!: GameManager;
  private inputManager!: InputManager;

  constructor() {
-    super({ key: 'GameScene' });
+    super({ key: "GameScene" });
  }

  preload(): void {
    // Load only scene-specific assets
-    this.load.image('player', 'assets/player.png');
+    this.load.image("player", "assets/player.png");
  }

  create(data: SceneData): void {
@@ -955,27 +1076,29 @@ class GameScene extends Phaser.Scene {
    this.inputManager.destroy();

    // Remove event listeners
-    this.events.off('*');
+    this.events.off("*");
  }
 }
 ```

 **Scene Transitions:**
+
 ```typescript
 // Proper scene transitions with data
-this.scene.start('NextScene', {
+this.scene.start("NextScene", {
  playerScore: this.playerScore,
-  currentLevel: this.currentLevel + 1
+  currentLevel: this.currentLevel + 1,
 });

 // Scene overlays for UI
-this.scene.launch('PauseMenuScene');
+this.scene.launch("PauseMenuScene");
 this.scene.pause();
-```text
+```

 ### Game Object Patterns

 **Component-Based Architecture:**
+
 ```typescript
 // Base game entity
 abstract class GameEntity extends Phaser.GameObjects.Sprite {
@@ -996,11 +1119,11 @@ abstract class GameEntity extends Phaser.GameObjects.Sprite {
  }

  update(delta: number): void {
-    this.components.forEach(component => component.update(delta));
+    this.components.forEach((component) => component.update(delta));
  }

  destroy(): void {
-    this.components.forEach(component => component.destroy());
+    this.components.forEach((component) => component.destroy());
    this.components.clear();
    super.destroy();
  }
@@ -1012,17 +1135,18 @@ class Player extends GameEntity {
  private health!: HealthComponent;

  constructor(scene: Phaser.Scene, x: number, y: number) {
-    super(scene, x, y, 'player');
+    super(scene, x, y, "player");

    this.movement = this.addComponent(new MovementComponent(this));
    this.health = this.addComponent(new HealthComponent(this, 100));
  }
 }
-```text
+```

 ### System Management

 **Singleton Managers:**
+
 ```typescript
 class GameManager {
  private static instance: GameManager;
@@ -1031,7 +1155,7 @@ class GameManager {

  constructor(scene: Phaser.Scene) {
    if (GameManager.instance) {
-      throw new Error('GameManager already exists!');
+      throw new Error("GameManager already exists!");
    }

    this.scene = scene;
@@ -1041,7 +1165,7 @@ class GameManager {

  static getInstance(): GameManager {
    if (!GameManager.instance) {
-      throw new Error('GameManager not initialized!');
+      throw new Error("GameManager not initialized!");
    }
    return GameManager.instance;
  }
@@ -1054,13 +1178,14 @@ class GameManager {
    GameManager.instance = null!;
  }
 }
-```text
+```

 ## Performance Optimization

 ### Object Pooling

 **Required for High-Frequency Objects:**
+
 ```typescript
 class BulletPool {
  private pool: Bullet[] = [];
@@ -1079,7 +1204,7 @@ class BulletPool {
  }

  getBullet(): Bullet | null {
-    const bullet = this.pool.find(b => !b.active);
+    const bullet = this.pool.find((b) => !b.active);
    if (bullet) {
      bullet.setActive(true);
      bullet.setVisible(true);
@@ -1087,7 +1212,7 @@ class BulletPool {
    }

    // Pool exhausted - create new bullet
-    console.warn('Bullet pool exhausted, creating new bullet');
+    console.warn("Bullet pool exhausted, creating new bullet");
    return new Bullet(this.scene, 0, 0);
  }

@@ -1102,6 +1227,7 @@ class BulletPool {
 ### Frame Rate Optimization

 **Performance Monitoring:**
+
 ```typescript
 class PerformanceMonitor {
  private frameCount: number = 0;
@@ -1127,9 +1253,10 @@ class PerformanceMonitor {
    // Reduce particle counts, disable effects, etc.
  }
 }
-```text
+```

 **Update Loop Optimization:**
+
 ```typescript
 // Avoid expensive operations in update loops
 class GameScene extends Phaser.Scene {
@@ -1150,13 +1277,14 @@ class GameScene extends Phaser.Scene {
    }
  }
 }
-```text
+```

 ## Input Handling

 ### Cross-Platform Input

 **Input Abstraction:**
+
 ```typescript
 interface InputState {
  moveLeft: boolean;
@@ -1172,7 +1300,7 @@ class InputManager {
    moveRight: false,
    jump: false,
    action: false,
-    pause: false
+    pause: false,
  };

  private keys!: { [key: string]: Phaser.Input.Keyboard.Key };
@@ -1184,12 +1312,12 @@ class InputManager {
  }

  private setupKeyboard(): void {
-    this.keys = this.scene.input.keyboard.addKeys('W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT');
+    this.keys = this.scene.input.keyboard.addKeys("W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT");
  }

  private setupTouch(): void {
-    this.scene.input.on('pointerdown', this.handlePointerDown, this);
-    this.scene.input.on('pointerup', this.handlePointerUp, this);
+    this.scene.input.on("pointerdown", this.handlePointerDown, this);
+    this.scene.input.on("pointerup", this.handlePointerUp, this);
  }

  update(): void {
@@ -1204,20 +1332,21 @@ class InputManager {
    return { ...this.inputState };
  }
 }
-```text
+```

 ## Error Handling

 ### Graceful Degradation

 **Asset Loading Error Handling:**
+
 ```typescript
 class AssetManager {
  loadAssets(): Promise<void> {
    return new Promise((resolve, reject) => {
-      this.scene.load.on('filecomplete', this.handleFileComplete, this);
-      this.scene.load.on('loaderror', this.handleLoadError, this);
-      this.scene.load.on('complete', () => resolve());
+      this.scene.load.on("filecomplete", this.handleFileComplete, this);
+      this.scene.load.on("loaderror", this.handleLoadError, this);
+      this.scene.load.on("complete", () => resolve());

      this.scene.load.start();
    });
@@ -1233,8 +1362,8 @@ class AssetManager {
  private loadFallbackAsset(key: string): void {
    // Load placeholder or default assets
    switch (key) {
-      case 'player':
-        this.scene.load.image('player', 'assets/defaults/default-player.png');
+      case "player":
+        this.scene.load.image("player", "assets/defaults/default-player.png");
        break;
      default:
        console.warn(`No fallback for asset: ${key}`);
@@ -1246,6 +1375,7 @@ class AssetManager {
 ### Runtime Error Recovery

 **System Error Handling:**
+
 ```typescript
 class GameSystem {
  protected handleError(error: Error, context: string): void {
@@ -1260,11 +1390,11 @@ class GameSystem {

  private attemptRecovery(context: string): void {
    switch (context) {
-      case 'update':
+      case "update":
        // Reset system state
        this.reset();
        break;
-      case 'render':
+      case "render":
        // Disable visual effects
        this.disableEffects();
        break;
@@ -1274,16 +1404,17 @@ class GameSystem {
    }
  }
 }
-```text
+```

 ## Testing Standards

 ### Unit Testing

 **Game Logic Testing:**
+
 ```typescript
 // Example test for game mechanics
-describe('HealthComponent', () => {
+describe("HealthComponent", () => {
  let healthComponent: HealthComponent;

  beforeEach(() => {
@@ -1291,30 +1422,31 @@ describe('HealthComponent', () => {
    healthComponent = new HealthComponent(mockEntity, 100);
  });

-  test('should initialize with correct health', () => {
+  test("should initialize with correct health", () => {
    expect(healthComponent.currentHealth).toBe(100);
    expect(healthComponent.maxHealth).toBe(100);
  });

-  test('should handle damage correctly', () => {
+  test("should handle damage correctly", () => {
    healthComponent.takeDamage(25);
    expect(healthComponent.currentHealth).toBe(75);
    expect(healthComponent.isAlive()).toBe(true);
  });

-  test('should handle death correctly', () => {
+  test("should handle death correctly", () => {
    healthComponent.takeDamage(150);
    expect(healthComponent.currentHealth).toBe(0);
    expect(healthComponent.isAlive()).toBe(false);
  });
 });
-```text
+```

 ### Integration Testing

 **Scene Testing:**
+
 ```typescript
-describe('GameScene Integration', () => {
+describe("GameScene Integration", () => {
  let scene: GameScene;
  let mockGame: Phaser.Game;

@@ -1324,14 +1456,14 @@ describe('GameScene Integration', () => {
    scene = new GameScene();
  });

-  test('should initialize all systems', () => {
+  test("should initialize all systems", () => {
    scene.create({});

    expect(scene.gameManager).toBeDefined();
    expect(scene.inputManager).toBeDefined();
  });
 });
-```text
+```

 ## File Organization

@@ -1385,21 +1517,25 @@ src/
 ### Story Implementation Process

 1. **Read Story Requirements:**
+
   - Understand acceptance criteria
   - Identify technical requirements
   - Review performance constraints

 2. **Plan Implementation:**
+
   - Identify files to create/modify
   - Consider component architecture
   - Plan testing approach

 3. **Implement Feature:**
+
   - Follow TypeScript strict mode
   - Use established patterns
   - Maintain 60 FPS performance

 4. **Test Implementation:**
+
   - Write unit tests for game logic
   - Test cross-platform functionality
   - Validate performance targets
@@ -1412,6 +1548,7 @@ src/
 ### Code Review Checklist

 **Before Committing:**
+
 - [ ] TypeScript compiles without errors
 - [ ] All tests pass
 - [ ] Performance targets met (60 FPS)
@@ -1425,17 +1562,20 @@ src/
 ## Performance Targets

 ### Frame Rate Requirements
+
 - **Desktop**: Maintain 60 FPS at 1080p
 - **Mobile**: Maintain 60 FPS on mid-range devices, minimum 30 FPS on low-end
 - **Optimization**: Implement dynamic quality scaling when performance drops

 ### Memory Management
+
 - **Total Memory**: Under 100MB for full game
 - **Per Scene**: Under 50MB per gameplay scene
 - **Asset Loading**: Progressive loading to stay under limits
 - **Garbage Collection**: Minimize object creation in update loops

 ### Loading Performance
+
 - **Initial Load**: Under 5 seconds for game start
 - **Scene Transitions**: Under 2 seconds between scenes
 - **Asset Streaming**: Background loading for upcoming content
--- a/dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.txt
+++ b/dist/expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.txt
@@ -109,6 +109,7 @@ Create detailed, actionable game development stories that enable AI developers t
 ## Prerequisites

 Before creating stories, ensure you have:
+
 - Completed Game Design Document (GDD)
 - Game Architecture Document
 - Epic definition this story belongs to
@@ -119,12 +120,14 @@ Before creating stories, ensure you have:
 ### 1. Story Identification

 **Review Epic Context:**
+
 - Understand the epic's overall goal
 - Identify specific features that need implementation
 - Review any existing stories in the epic
 - Ensure no duplicate work

 **Feature Analysis:**
+
 - Reference specific GDD sections
 - Understand player experience goals
 - Identify technical complexity
@@ -133,12 +136,14 @@ Before creating stories, ensure you have:
 ### 2. Story Scoping

 **Single Responsibility:**
+
 - Focus on one specific game feature
 - Ensure story is completable in 1-3 days
 - Break down complex features into multiple stories
 - Maintain clear boundaries with other stories

 **Implementation Clarity:**
+
 - Define exactly what needs to be built
 - Specify all technical requirements
 - Include all necessary integration points
@@ -150,6 +155,7 @@ Before creating stories, ensure you have:
 Use `templates#game-story-tmpl` following all embedded LLM instructions

 **Key Focus Areas:**
+
 - Clear, actionable description
 - Specific acceptance criteria
 - Detailed technical specifications
@@ -159,18 +165,21 @@ Use `templates#game-story-tmpl` following all embedded LLM instructions
 ### 4. Story Validation

 **Technical Review:**
+
 - Verify all technical specifications are complete
 - Ensure integration points are clearly defined
 - Confirm file paths match architecture
 - Validate TypeScript interfaces and classes

 **Game Design Alignment:**
+
 - Confirm story implements GDD requirements
 - Verify player experience goals are met
 - Check balance parameters are included
 - Ensure game mechanics are correctly interpreted

 **Implementation Readiness:**
+
 - All dependencies identified
 - Assets requirements specified
 - Testing criteria defined
@@ -182,6 +191,7 @@ Use `templates#game-story-tmpl` following all embedded LLM instructions
 Execute `checklists#game-story-dod-checklist` against completed story

 **Story Criteria:**
+
 - Story is immediately actionable
 - No design decisions left to developer
 - Technical requirements are complete
@@ -191,12 +201,14 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ### 6. Story Refinement

 **Developer Perspective:**
+
 - Can a developer start implementation immediately?
 - Are all technical questions answered?
 - Is the scope appropriate for the estimated points?
 - Are all dependencies clearly identified?

 **Iterative Improvement:**
+
 - Address any gaps or ambiguities
 - Clarify complex technical requirements
 - Ensure story fits within epic scope
@@ -205,6 +217,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Story Elements Checklist

 ### Required Sections
+
 - [ ] Clear, specific description
 - [ ] Complete acceptance criteria (functional, technical, game design)
 - [ ] Detailed technical specifications
@@ -218,6 +231,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Definition of Done checklist

 ### Game-Specific Requirements
+
 - [ ] GDD section references
 - [ ] Game mechanic implementation details
 - [ ] Player experience goals
@@ -227,6 +241,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Cross-platform considerations

 ### Technical Quality
+
 - [ ] TypeScript strict mode compliance
 - [ ] Architecture document alignment
 - [ ] Code organization follows standards
@@ -237,18 +252,21 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Common Pitfalls

 **Scope Issues:**
+
 - Story too large (break into multiple stories)
 - Story too vague (add specific requirements)
 - Missing dependencies (identify all prerequisites)
 - Unclear boundaries (define what's in/out of scope)

 **Technical Issues:**
+
 - Missing integration details
 - Incomplete technical specifications
 - Undefined interfaces or classes
 - Missing performance requirements

 **Game Design Issues:**
+
 - Not referencing GDD properly
 - Missing player experience context
 - Unclear game mechanic implementation
@@ -257,6 +275,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Success Criteria

 **Story Readiness:**
+
 - [ ] Developer can start implementation immediately
 - [ ] No additional design decisions required
 - [ ] All technical questions answered
@@ -265,6 +284,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Story fits within epic scope

 **Quality Validation:**
+
 - [ ] Game story DOD checklist passes
 - [ ] Architecture alignment confirmed
 - [ ] GDD requirements covered
@@ -274,6 +294,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Handoff Protocol

 **To Game Developer:**
+
 1. Provide story document
 2. Confirm GDD and architecture access
 3. Verify all dependencies are met
@@ -281,6 +302,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 5. Establish check-in schedule

 **Story Status Updates:**
+
 - Draft → Ready for Development
 - In Development → Code Review
 - Code Review → Testing
@@ -289,6 +311,102 @@ Execute `checklists#game-story-dod-checklist` against completed story
 This task ensures game development stories are immediately actionable and enable efficient AI-driven development of game features.
 ==================== END: tasks#create-game-story ====================

+==================== START: tasks#execute-checklist ====================
+# Checklist Validation Task
+
+This task provides instructions for validating documentation against checklists. The agent MUST follow these instructions to ensure thorough and systematic validation of documents.
+
+## 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 {root}/checklists folder to select the appropriate one to run.
+
+## Instructions
+
+1. **Initial Assessment**
+
+   - 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 {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
+   - Confirm if they want to work through the checklist:
+     - Section by section (interactive mode - very time consuming)
+     - All at once (YOLO mode - recommended for checklists, there will be a summary of sections at the end to discuss)
+
+2. **Document and Artifact Gathering**
+
+   - Each checklist will specify its required documents/artifacts at the beginning
+   - Follow the checklist's specific instructions for what to gather, generally a file can be resolved in the docs folder, if not or unsure, halt and ask or confirm with the user.
+
+3. **Checklist Processing**
+
+   If in interactive mode:
+
+   - Work through each section of the checklist one at a time
+   - For each section:
+     - Review all items in the section following instructions for that section embedded in the checklist
+     - Check each item against the relevant documentation or artifacts as appropriate
+     - Present summary of findings for that section, highlighting warnings, errors and non applicable items (rationale for non-applicability).
+     - Get user confirmation before proceeding to next section or if any thing major do we need to halt and take corrective action
+
+   If in YOLO mode:
+
+   - Process all sections at once
+   - Create a comprehensive report of all findings
+   - Present the complete analysis to the user
+
+4. **Validation Approach**
+
+   For each checklist item:
+
+   - Read and understand the requirement
+   - Look for evidence in the documentation that satisfies the requirement
+   - Consider both explicit mentions and implicit coverage
+   - Aside from this, follow all checklist llm instructions
+   - Mark items as:
+     - ✅ PASS: Requirement clearly met
+     - ❌ FAIL: Requirement not met or insufficient coverage
+     - ⚠️ PARTIAL: Some aspects covered but needs improvement
+     - N/A: Not applicable to this case
+
+5. **Section Analysis**
+
+   For each section:
+
+   - think step by step to calculate pass rate
+   - Identify common themes in failed items
+   - Provide specific recommendations for improvement
+   - In interactive mode, discuss findings with user
+   - Document any user decisions or explanations
+
+6. **Final Report**
+
+   Prepare a summary that includes:
+
+   - Overall checklist completion status
+   - Pass rates by section
+   - List of failed items with context
+   - Specific recommendations for improvement
+   - Any sections or items marked as N/A with justification
+
+## Checklist Execution Methodology
+
+Each checklist now contains embedded LLM prompts and instructions that will:
+
+1. **Guide thorough thinking** - Prompts ensure deep analysis of each section
+2. **Request specific artifacts** - Clear instructions on what documents/access is needed
+3. **Provide contextual guidance** - Section-specific prompts for better validation
+4. **Generate comprehensive reports** - Final summary with detailed findings
+
+The LLM will:
+
+- Execute the complete checklist validation
+- Present a final report with pass/fail rates and key findings
+- Offer to provide detailed analysis of any section, especially those with warnings or failures
+==================== END: tasks#execute-checklist ====================
+
 ==================== START: templates#game-story-tmpl ====================
 # Story: {{Story Title}}

@@ -533,6 +651,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Story Completeness

 ### Basic Story Elements
+
 - [ ] **Story Title** - Clear, descriptive title that identifies the feature
 - [ ] **Epic Assignment** - Story is properly assigned to relevant epic
 - [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -540,6 +659,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Description** - Clear, concise description of what needs to be implemented

 ### Game Design Alignment
+
 - [ ] **GDD Reference** - Specific Game Design Document section referenced
 - [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
 - [ ] **Player Experience Goal** - Describes the intended player experience
@@ -549,6 +669,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Technical Specifications

 ### Architecture Compliance
+
 - [ ] **File Organization** - Follows game architecture document structure
 - [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
 - [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -556,6 +677,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Dependencies** - All system dependencies clearly identified

 ### Phaser 3 Requirements
+
 - [ ] **Scene Integration** - Specifies which scenes are affected and how
 - [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
 - [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -563,6 +685,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Performance Considerations** - 60 FPS target and optimization requirements

 ### Code Quality Standards
+
 - [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
 - [ ] **Error Handling** - Error scenarios and handling requirements specified
 - [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -572,6 +695,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Implementation Readiness

 ### Acceptance Criteria
+
 - [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
 - [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
 - [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -579,6 +703,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Completeness** - No acceptance criteria are vague or unmeasurable

 ### Implementation Tasks
+
 - [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
 - [ ] **Task Scope** - Each task is completable in 1-4 hours
 - [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -586,6 +711,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Development Flow** - Tasks follow logical implementation order

 ### Dependencies
+
 - [ ] **Story Dependencies** - All prerequisite stories identified with IDs
 - [ ] **Technical Dependencies** - Required systems and files identified
 - [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -595,6 +721,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Testing Requirements

 ### Test Coverage
+
 - [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
 - [ ] **Integration Test Cases** - Integration testing with other game systems specified
 - [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -602,6 +729,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Edge Case Testing** - Edge cases and error conditions covered

 ### Test Implementation
+
 - [ ] **Test File Paths** - Exact test file locations specified
 - [ ] **Test Scenarios** - All test scenarios are complete and executable
 - [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -611,6 +739,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Game-Specific Quality

 ### Gameplay Implementation
+
 - [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
 - [ ] **Player Controls** - Input handling requirements are complete
 - [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -618,6 +747,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **State Management** - Game state changes and persistence requirements defined

 ### User Experience
+
 - [ ] **UI Requirements** - User interface elements and behaviors specified
 - [ ] **Audio Integration** - Sound effect and music requirements defined
 - [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -625,6 +755,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Error Recovery** - User-facing error handling and recovery specified

 ### Performance Optimization
+
 - [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
 - [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
 - [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -634,6 +765,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Documentation and Communication

 ### Story Documentation
+
 - [ ] **Implementation Notes** - Additional context and implementation guidance provided
 - [ ] **Design Decisions** - Key design choices documented with rationale
 - [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -641,6 +773,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs

 ### Developer Handoff
+
 - [ ] **Immediate Actionability** - Developer can start implementation without additional questions
 - [ ] **Complete Context** - All necessary context provided within the story
 - [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -650,6 +783,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Final Validation

 ### Story Readiness
+
 - [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
 - [ ] **Technical Completeness** - All technical requirements are specified and actionable
 - [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -657,6 +791,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Review Completion** - Story has been reviewed for completeness and accuracy

 ### Implementation Preparedness
+
 - [ ] **Environment Ready** - Development environment requirements specified
 - [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
 - [ ] **Testing Prepared** - Testing environment and data requirements specified
--- a/dist/expansion-packs/bmad-2d-phaser-game-dev/teams/phaser-2d-nodejs-game-team.txt
+++ b/dist/expansion-packs/bmad-2d-phaser-game-dev/teams/phaser-2d-nodejs-game-team.txt
--- a/dist/expansion-packs/bmad-creator-tools/agents/bmad-the-creator.txt
+++ b/dist/expansion-packs/bmad-creator-tools/agents/bmad-the-creator.txt
@@ -101,7 +101,7 @@ This task guides you through creating a new BMAD agent following the standard te

 ## Prerequisites

- Agent template: `.bmad-core/templates/agent-tmpl.md`
+- Agent template: `../templates/agent-tmpl.md`
 - Target directory: `.bmad-core/agents/`

 ## Steps
@@ -160,7 +160,7 @@ Created during agent setup:
 - Templates:
  - [ ] template-name-1.md
  - [ ] template-name-2.md
-```text
+```

 ### 4. Create Agent File

@@ -218,7 +218,7 @@ Present to the user:
   1. Review and customize the created tasks/templates
   2. Run npm run build:agents
   3. Test the agent thoroughly
-```text
+```

 ## Template Reference

@@ -247,7 +247,7 @@ persona:
    - Data integrity and accuracy above all
    - Clear communication of complex findings
    - Actionable insights over raw numbers
-```text
+```

 ## Creating Missing Dependencies

@@ -280,12 +280,12 @@ When a required task or template doesn't exist:
 ```yaml
 dependencies:
  tasks:
-    - 'create-doc # Required if agent creates any documents'
-    - 'analyze-requirements # Custom task for this agent'
-    - 'generate-report # Another custom task'
+    - create-doc
+    - analyze-requirements
+    - generate-report
  templates:
-    - 'requirements-doc # Template for requirements documents'
-    - 'analysis-report # Template for analysis reports'
+    - requirements-doc
+    - analysis-report
 ```

 ## Notes
@@ -318,7 +318,7 @@ Every expansion pack MUST include a custom BMAD orchestrator agent with sophisti

 1. **Create Planning Document First**: Before any implementation, create a comprehensive plan for user approval
 2. **Agent Architecture Standards**: Use YAML-in-Markdown structure with activation instructions, personas, and command systems
-3. **Character Consistency**: Every agent must have a persistent persona with name, communication style, and numbered options protocol
+3. **Character Consistency**: Every agent must have a persistent persona with name, communication style, and numbered options protocol similar to `expansion-packs/bmad-2d-phaser-game-dev/agents/game-designer.md`
 4. **Custom Themed Orchestrator**: The orchestrator should embody the domain theme (e.g., Office Manager for medical, Project Lead for tech) for better user experience
 5. **Core Utilities Required**: ALWAYS include these core files in every expansion pack:
   - `tasks/create-doc.md` - Document creation from templates
@@ -326,8 +326,8 @@ Every expansion pack MUST include a custom BMAD orchestrator agent with sophisti
   - `utils/template-format.md` - Template markup conventions
   - `utils/workflow-management.md` - Workflow orchestration
 6. **Team and Workflow Requirements**: If pack has >1 agent, MUST include:
-   - At least one team configuration in `agent-teams/`
-   - At least one workflow in `workflows/`
+   - At least one team configuration in `expansion-packs/{new-expansion}/agent-teams/`
+   - At least one workflow in `expansion-packs/{new-expansion}workflows/`
 7. **Template Sophistication**: Implement LLM instruction embedding with `[[LLM: guidance]]`, conditional content, and variable systems
 8. **Workflow Orchestration**: Include decision trees, handoff protocols, and validation loops
 9. **Quality Assurance Integration**: Multi-level checklists with star ratings and ready/not-ready frameworks
@@ -449,7 +449,7 @@ Create `expansion-packs/{pack-name}/plan.md` with:
 ## Approval

 User approval received: [ ] Yes
-```text
+```

 Important: Wait for user approval before proceeding to Phase 2

@@ -582,6 +582,7 @@ IMPORTANT: Only proceed after plan.md is approved
 #### 3.1 Create Directory Structure

 ```
+
 expansion-packs/
 └── {pack-name}/
 ├── plan.md (ALREADY CREATED)
@@ -609,7 +610,8 @@ expansion-packs/
 │ └── {domain}-workflow.md (REQUIRED if multiple agents)
 └── agent-teams/
 └── {domain}-team.yml (REQUIRED if multiple agents)
-```text
+
+```

 #### 3.2 Create Manifest

@@ -734,18 +736,18 @@ 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/
-```text
+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**

@@ -971,7 +973,7 @@ Before declaring complete:

 **README Structure with Character Introduction:**

-````markdown
+```markdown
 # {Pack Name} Expansion Pack

 ## Meet Your {Domain} Team
@@ -995,10 +997,8 @@ _{Professional background and expertise}_
   - `{file2}.{ext}` - {description}

 2. **Launch Orchestrator**:
-   ```bash
+
   npm run agent {pack-name}-orchestrator
-   ```
-````

 3. **Follow Numbered Options**: {Character Name} will present numbered choices for each decision

@@ -1028,14 +1028,12 @@ _{Professional background and expertise}_
 ### Knowledge Base

 [Embedded domain expertise]
-
-````
+```

 #### 6.3 Advanced Data File Documentation with Validation

 For each required data file, provide comprehensive guidance:

-```markdown
 ## Required User Data Files

 ### {filename}.{ext}
@@ -1045,7 +1043,6 @@ For each required data file, provide comprehensive guidance:
 - **Location**: Place in `bmad-core/data/`
 - **Validation**: {how agents will verify the file is correct}
 - **Example Structure**:
-````

 {sample content showing exact format}

@@ -1323,6 +1320,405 @@ Embedded knowledge (automatic):
 - [ ] Character interactions tested for consistency and professional authenticity
 ==================== END: tasks#generate-expansion-pack ====================

+==================== START: tasks#advanced-elicitation ====================
+# Advanced Elicitation Task
+
+## Purpose
+
+- Provide optional reflective and brainstorming actions to enhance content quality
+- Enable deeper exploration of ideas through structured elicitation techniques
+- Support iterative refinement through multiple analytical perspectives
+
+## Task Instructions
+
+### 1. Section Context and Review
+
+[[LLM: When invoked after outputting a section:
+
+1. First, provide a brief 1-2 sentence summary of what the user should look for in the section just presented (e.g., "Please review the technology choices for completeness and alignment with your project needs. Pay special attention to version numbers and any missing categories.")
+
+2. If the section contains Mermaid diagrams, explain each diagram briefly before offering elicitation options (e.g., "The component diagram shows the main system modules and their interactions. Notice how the API Gateway routes requests to different services.")
+
+3. If the section contains multiple distinct items (like multiple components, multiple patterns, etc.), inform the user they can apply elicitation actions to:
+
+   - The entire section as a whole
+   - Individual items within the section (specify which item when selecting an action)
+
+4. Then present the action list as specified below.]]
+
+### 2. Ask for Review and Present Action List
+
+[[LLM: Ask the user to review the drafted section. In the SAME message, inform them that they can suggest additions, removals, or modifications, OR they can select an action by number from the 'Advanced Reflective, Elicitation & Brainstorming Actions'. If there are multiple items in the section, mention they can specify which item(s) to apply the action to. Then, present ONLY the numbered list (0-9) of these actions. Conclude by stating that selecting 9 will proceed to the next section. Await user selection. If an elicitation action (0-8) is chosen, execute it and then re-offer this combined review/elicitation choice. If option 9 is chosen, or if the user provides direct feedback, proceed accordingly.]]
+
+**Present the numbered list (0-9) with this exact format:**
+
+```text
+**Advanced Reflective, Elicitation & Brainstorming Actions**
+Choose an action (0-9 - 9 to bypass - HELP for explanation of these options):
+
+0. Expand or Contract for Audience
+1. Explain Reasoning (CoT Step-by-Step)
+2. Critique and Refine
+3. Analyze Logical Flow and Dependencies
+4. Assess Alignment with Overall Goals
+5. Identify Potential Risks and Unforeseen Issues
+6. Challenge from Critical Perspective (Self or Other Persona)
+7. Explore Diverse Alternatives (ToT-Inspired)
+8. Hindsight is 20/20: The 'If Only...' Reflection
+9. Proceed / No Further Actions
+```
+
+### 2. Processing Guidelines
+
+**Do NOT show:**
+
+- The full protocol text with `[[LLM: ...]]` instructions
+- Detailed explanations of each option unless executing or the user asks, when giving the definition you can modify to tie its relevance
+- Any internal template markup
+
+**After user selection from the list:**
+
+- Execute the chosen action according to the protocol instructions below
+- Ask if they want to select another action or proceed with option 9 once complete
+- Continue until user selects option 9 or indicates completion
+
+## Action Definitions
+
+0. Expand or Contract for Audience
+   [[LLM: Ask the user whether they want to 'expand' on the content (add more detail, elaborate) or 'contract' it (simplify, clarify, make more concise). Also, ask if there's a specific target audience they have in mind. Once clarified, perform the expansion or contraction from your current role's perspective, tailored to the specified audience if provided.]]
+
+1. Explain Reasoning (CoT Step-by-Step)
+   [[LLM: Explain the step-by-step thinking process, characteristic of your role, that you used to arrive at the current proposal for this content.]]
+
+2. Critique and Refine
+   [[LLM: From your current role's perspective, review your last output or the current section for flaws, inconsistencies, or areas for improvement, and then suggest a refined version reflecting your expertise.]]
+
+3. Analyze Logical Flow and Dependencies
+   [[LLM: From your role's standpoint, examine the content's structure for logical progression, internal consistency, and any relevant dependencies. Confirm if elements are presented in an effective order.]]
+
+4. Assess Alignment with Overall Goals
+   [[LLM: Evaluate how well the current content contributes to the stated overall goals of the document, interpreting this from your specific role's perspective and identifying any misalignments you perceive.]]
+
+5. Identify Potential Risks and Unforeseen Issues
+   [[LLM: Based on your role's expertise, brainstorm potential risks, overlooked edge cases, or unintended consequences related to the current content or proposal.]]
+
+6. Challenge from Critical Perspective (Self or Other Persona)
+   [[LLM: Adopt a critical perspective on the current content. If the user specifies another role or persona (e.g., 'as a customer', 'as [Another Persona Name]'), critique the content or play devil's advocate from that specified viewpoint. If no other role is specified, play devil's advocate from your own current persona's viewpoint, arguing against the proposal or current content and highlighting weaknesses or counterarguments specific to your concerns. This can also randomly include YAGNI when appropriate, such as when trimming the scope of an MVP, the perspective might challenge the need for something to cut MVP scope.]]
+
+7. Explore Diverse Alternatives (ToT-Inspired)
+   [[LLM: From your role's perspective, first broadly brainstorm a range of diverse approaches or solutions to the current topic. Then, from this wider exploration, select and present 2 distinct alternatives, detailing the pros, cons, and potential implications you foresee for each.]]
+
+8. Hindsight is 20/20: The 'If Only...' Reflection
+   [[LLM: In your current persona, imagine it's a retrospective for a project based on the current content. What's the one 'if only we had known/done X...' that your role would humorously or dramatically highlight, along with the imagined consequences?]]
+
+9. Proceed / No Further Actions
+   [[LLM: Acknowledge the user's choice to finalize the current work, accept the AI's last output as is, or move on to the next step without selecting another action from this list. Prepare to proceed accordingly.]]
+==================== END: tasks#advanced-elicitation ====================
+
+==================== START: tasks#create-deep-research-prompt ====================
+# Create Deep Research Prompt Task
+
+This task helps create comprehensive research prompts for various types of deep analysis. It can process inputs from brainstorming sessions, project briefs, market research, or specific research questions to generate targeted prompts for deeper investigation.
+
+## Purpose
+
+Generate well-structured research prompts that:
+
+- Define clear research objectives and scope
+- Specify appropriate research methodologies
+- Outline expected deliverables and formats
+- Guide systematic investigation of complex topics
+- Ensure actionable insights are captured
+
+## Research Type Selection
+
+[[LLM: First, help the user select the most appropriate research focus based on their needs and any input documents they've provided.]]
+
+### 1. Research Focus Options
+
+Present these numbered options to the user:
+
+1. **Product Validation Research**
+
+   - Validate product hypotheses and market fit
+   - Test assumptions about user needs and solutions
+   - Assess technical and business feasibility
+   - Identify risks and mitigation strategies
+
+2. **Market Opportunity Research**
+
+   - Analyze market size and growth potential
+   - Identify market segments and dynamics
+   - Assess market entry strategies
+   - Evaluate timing and market readiness
+
+3. **User & Customer Research**
+
+   - Deep dive into user personas and behaviors
+   - Understand jobs-to-be-done and pain points
+   - Map customer journeys and touchpoints
+   - Analyze willingness to pay and value perception
+
+4. **Competitive Intelligence Research**
+
+   - Detailed competitor analysis and positioning
+   - Feature and capability comparisons
+   - Business model and strategy analysis
+   - Identify competitive advantages and gaps
+
+5. **Technology & Innovation Research**
+
+   - Assess technology trends and possibilities
+   - Evaluate technical approaches and architectures
+   - Identify emerging technologies and disruptions
+   - Analyze build vs. buy vs. partner options
+
+6. **Industry & Ecosystem Research**
+
+   - Map industry value chains and dynamics
+   - Identify key players and relationships
+   - Analyze regulatory and compliance factors
+   - Understand partnership opportunities
+
+7. **Strategic Options Research**
+
+   - Evaluate different strategic directions
+   - Assess business model alternatives
+   - Analyze go-to-market strategies
+   - Consider expansion and scaling paths
+
+8. **Risk & Feasibility Research**
+
+   - Identify and assess various risk factors
+   - Evaluate implementation challenges
+   - Analyze resource requirements
+   - Consider regulatory and legal implications
+
+9. **Custom Research Focus**
+   [[LLM: Allow user to define their own specific research focus.]]
+   - User-defined research objectives
+   - Specialized domain investigation
+   - Cross-functional research needs
+
+### 2. Input Processing
+
+[[LLM: Based on the selected research type and any provided inputs (project brief, brainstorming results, etc.), extract relevant context and constraints.]]
+
+**If Project Brief provided:**
+
+- Extract key product concepts and goals
+- Identify target users and use cases
+- Note technical constraints and preferences
+- Highlight uncertainties and assumptions
+
+**If Brainstorming Results provided:**
+
+- Synthesize main ideas and themes
+- Identify areas needing validation
+- Extract hypotheses to test
+- Note creative directions to explore
+
+**If Market Research provided:**
+
+- Build on identified opportunities
+- Deepen specific market insights
+- Validate initial findings
+- Explore adjacent possibilities
+
+**If Starting Fresh:**
+
+- Gather essential context through questions
+- Define the problem space
+- Clarify research objectives
+- Establish success criteria
+
+## Process
+
+### 3. Research Prompt Structure
+
+[[LLM: Based on the selected research type and context, collaboratively develop a comprehensive research prompt with these components.]]
+
+#### A. Research Objectives
+
+[[LLM: Work with the user to articulate clear, specific objectives for the research.]]
+
+- Primary research goal and purpose
+- Key decisions the research will inform
+- Success criteria for the research
+- Constraints and boundaries
+
+#### B. Research Questions
+
+[[LLM: Develop specific, actionable research questions organized by theme.]]
+
+**Core Questions:**
+
+- Central questions that must be answered
+- Priority ranking of questions
+- Dependencies between questions
+
+**Supporting Questions:**
+
+- Additional context-building questions
+- Nice-to-have insights
+- Future-looking considerations
+
+#### C. Research Methodology
+
+[[LLM: Specify appropriate research methods based on the type and objectives.]]
+
+**Data Collection Methods:**
+
+- Secondary research sources
+- Primary research approaches (if applicable)
+- Data quality requirements
+- Source credibility criteria
+
+**Analysis Frameworks:**
+
+- Specific frameworks to apply
+- Comparison criteria
+- Evaluation methodologies
+- Synthesis approaches
+
+#### D. Output Requirements
+
+[[LLM: Define how research findings should be structured and presented.]]
+
+**Format Specifications:**
+
+- Executive summary requirements
+- Detailed findings structure
+- Visual/tabular presentations
+- Supporting documentation
+
+**Key Deliverables:**
+
+- Must-have sections and insights
+- Decision-support elements
+- Action-oriented recommendations
+- Risk and uncertainty documentation
+
+### 4. Prompt Generation
+
+[[LLM: Synthesize all elements into a comprehensive, ready-to-use research prompt.]]
+
+**Research Prompt Template:**
+
+```markdown
+## Research Objective
+
+[Clear statement of what this research aims to achieve]
+
+## Background Context
+
+[Relevant information from project brief, brainstorming, or other inputs]
+
+## Research Questions
+
+### Primary Questions (Must Answer)
+
+1. [Specific, actionable question]
+2. [Specific, actionable question]
+   ...
+
+### Secondary Questions (Nice to Have)
+
+1. [Supporting question]
+2. [Supporting question]
+   ...
+
+## Research Methodology
+
+### Information Sources
+
+- [Specific source types and priorities]
+
+### Analysis Frameworks
+
+- [Specific frameworks to apply]
+
+### Data Requirements
+
+- [Quality, recency, credibility needs]
+
+## Expected Deliverables
+
+### Executive Summary
+
+- Key findings and insights
+- Critical implications
+- Recommended actions
+
+### Detailed Analysis
+
+[Specific sections needed based on research type]
+
+### Supporting Materials
+
+- Data tables
+- Comparison matrices
+- Source documentation
+
+## Success Criteria
+
+[How to evaluate if research achieved its objectives]
+
+## Timeline and Priority
+
+[If applicable, any time constraints or phasing]
+```
+
+### 5. Review and Refinement
+
+[[LLM: Present the draft research prompt for user review and refinement.]]
+
+1. **Present Complete Prompt**
+
+   - Show the full research prompt
+   - Explain key elements and rationale
+   - Highlight any assumptions made
+
+2. **Gather Feedback**
+
+   - Are the objectives clear and correct?
+   - Do the questions address all concerns?
+   - Is the scope appropriate?
+   - Are output requirements sufficient?
+
+3. **Refine as Needed**
+   - Incorporate user feedback
+   - Adjust scope or focus
+   - Add missing elements
+   - Clarify ambiguities
+
+### 6. Next Steps Guidance
+
+[[LLM: Provide clear guidance on how to use the research prompt.]]
+
+**Execution Options:**
+
+1. **Use with AI Research Assistant**: Provide this prompt to an AI model with research capabilities
+2. **Guide Human Research**: Use as a framework for manual research efforts
+3. **Hybrid Approach**: Combine AI and human research using this structure
+
+**Integration Points:**
+
+- How findings will feed into next phases
+- Which team members should review results
+- How to validate findings
+- When to revisit or expand research
+
+## Important Notes
+
+- The quality of the research prompt directly impacts the quality of insights gathered
+- Be specific rather than general in research questions
+- Consider both current state and future implications
+- Balance comprehensiveness with focus
+- Document assumptions and limitations clearly
+- Plan for iterative refinement based on initial findings
+==================== END: tasks#create-deep-research-prompt ====================
+
 ==================== START: templates#agent-tmpl ====================
 # [AGENT_ID]

@@ -1342,6 +1738,7 @@ activation-instructions:
    - Only read the files/tasks listed here when user selects them for execution to minimize context usage
    - The customization field ALWAYS takes precedence over any conflicting instructions
    - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
+    - Command

 agent:
  name: [AGENT_NAME]
@@ -1362,7 +1759,9 @@ persona:
    # Add more principles as needed

 startup:
-  - [STARTUP_INSTRUCTIONS]
+  - Greet the user with your name and role, and inform of the *help command.
+  - [STARTUP_INSTRUCTION]
+  - [STARTUP_INSTRUCTION]...

 commands:
  - "*help" - Show: numbered list of the following commands to allow selection
@@ -1393,7 +1792,7 @@ dependencies:
    - [TEMPLATE_1]  # Template with LLM instructions for guided creation
    - [TEMPLATE_2]  # Another template for different document type
    [[LLM: Example: blueprint-tmpl, contract-tmpl, report-tmpl
-    Each template should include [[LLM: guidance]] and other conventions from `template-formmat.md` sections for user interaction]]
+    Each template should include [[LLM: guidance]] and other conventions from `template-format.md` sections for user interaction]]

  checklists:
    - [CHECKLIST_1]  # Quality validation for template outputs
@@ -1409,7 +1808,7 @@ dependencies:
    - template-format  # Required if using templates
    - [UTIL_1]        # Other utilities as needed
    [[LLM: Include workflow-management if agent participates in workflows]]
-```text
+```

@{example: Construction Contractor Agent}

@@ -1448,21 +1847,21 @@ commands:
  - '*exit" - Say goodbye as Marcus and exit'
 dependencies:
  tasks:
-    - 'create-doc          # For document creation'
-    - 'validate-plans      # Custom validation task'
-    - 'safety-assessment   # Custom safety review task'
+    - create-doc
+    - validate-plans
+    - safety-assessment
  templates:
-    - 'blueprint-tmpl      # Architectural blueprint template'
-    - 'estimate-tmpl       # Cost estimation template'
-    - 'schedule-tmpl       # Project timeline template'
+    - blueprint-tmpl
+    - estimate-tmpl
+    - schedule-tmpl
  checklists:
-    - 'blueprint-checklist # Validates blueprint completeness'
-    - 'safety-checklist    # Safety compliance validation'
+    - blueprint-checklist
+    - safety-checklist
  data:
-    - 'building-codes.md   # Local building code reference'
-    - 'materials-guide.md  # Construction materials specs'
+    - building-codes.md
+    - materials-guide.md
  utils:
-    - 'template-format     # For template processing'
+    - template-format
 ```
 ==================== END: templates#agent-tmpl ====================

--- a/dist/expansion-packs/bmad-infrastructure-devops/agents/infra-devops-platform.txt
+++ b/dist/expansion-packs/bmad-infrastructure-devops/agents/infra-devops-platform.txt
@@ -134,9 +134,9 @@ Confirm with the user their preferred interaction style:

 ### 3. Execute Template

- Load specified template from `templates#*` or the /templates directory
+- Load specified template from `templates#*` or the `{root}/templates directory`
 - Follow ALL embedded LLM instructions within the template
- Process template markup according to `utils#template-format` conventions
+- Process template markup according to `utils#template-format` or `{root}/utils/template-format` conventions

 ### 4. Template Processing Rules

@@ -1006,7 +1006,7 @@ module "vpc" {
  public_subnets = {{public_subnets}}
  private_subnets = {{private_subnets}}
 }
-```text
+```

 ### Security Foundation

@@ -1053,7 +1053,7 @@ eksctl create cluster \
  --nodegroup-name {{nodegroup_name}} \
  --node-type {{instance_type}} \
  --nodes {{node_count}}
-```text
+```

 ^^/CONDITION: uses_eks^^

@@ -1067,7 +1067,7 @@ az aks create \
  --node-count {{node_count}} \
  --node-vm-size {{vm_size}} \
  --network-plugin azure
-```text
+```

 ^^/CONDITION: uses_aks^^

@@ -1111,11 +1111,11 @@ metadata:
 spec:
  source:
    repoURL:
-      '[object Object]': null
+      "[object Object]": null
    targetRevision:
-      '[object Object]': null
+      "[object Object]": null
    path:
-      '[object Object]': null
+      "[object Object]": null
 ```

 ^^/CONDITION: uses_argocd^^
@@ -1132,10 +1132,10 @@ spec:
  interval: 1m
  ref:
    branch:
-      '[object Object]': null
+      "[object Object]": null
  url:
-    '[object Object]': null
-```text
+    "[object Object]": null
+```

 ^^/CONDITION: uses_flux^^

@@ -1153,7 +1153,7 @@ platform-gitops/
 applications/
     base/
     overlays/
-```text
+```

 ### Deployment Workflows

@@ -1197,7 +1197,7 @@ istioctl install --set profile={{istio_profile}} \
 # Linkerd Installation
 linkerd install --cluster-name={{cluster_name}} | kubectl apply -f -
 linkerd viz install | kubectl apply -f -
-```text
+```

 - Control plane setup
 - Proxy injection
@@ -1248,7 +1248,7 @@ spec:
    - name: deploy
      taskRef:
        name: gitops-deploy
-```text
+```

 ### Development Tools

@@ -1290,7 +1290,7 @@ data:
      - job_name: 'kubernetes-pods'
        kubernetes_sd_configs:
          - role: pod
-```text
+```

 ### Platform Observability

@@ -1380,7 +1380,7 @@ stages:
  - develop
  - test
  - deploy
-```text
+```

 ## Platform Validation & Testing

@@ -1409,8 +1409,8 @@ stages:

 ### Load Testing

-```yaml
-# K6 Load Test Example
+```typescript
+// K6 Load Test Example
 import http from 'k6/http';
 import { check } from 'k6';

@@ -2019,3 +2019,38 @@ This checklist serves as a comprehensive framework for validating infrastructure
 - [ ] Platform component integration validated
 - [ ] Cross-platform functionality tested and verified
 ==================== END: checklists#infrastructure-checklist ====================
+
+==================== START: data#technical-preferences ====================
+# User-Defined Preferred Patterns and Preferences
+
+None Listed
+==================== END: data#technical-preferences ====================
+
+==================== START: utils#template-format ====================
+# Template Format Conventions
+
+Templates in the BMAD method use standardized markup for AI processing. These conventions ensure consistent document generation.
+
+## Template Markup Elements
+
+- **{{placeholders}}**: Variables to be replaced with actual content
+- **[[LLM: instructions]]**: Internal processing instructions for AI agents (never shown to users)
+- **REPEAT** sections: Content blocks that may be repeated as needed
+- **^^CONDITION^^** blocks: Conditional content included only if criteria are met
+- **@{examples}**: Example content for guidance (never output to users)
+
+## Processing Rules
+
+- Replace all {{placeholders}} with project-specific content
+- Execute all [[LLM: instructions]] internally without showing users
+- Process conditional and repeat blocks as specified
+- Use examples for guidance but never include them in final output
+- Present only clean, formatted content to users
+
+## Critical Guidelines
+
+- **NEVER display template markup, LLM instructions, or examples to users**
+- Template elements are for AI processing only
+- Focus on faithful template execution and clean output
+- All template-specific instructions are embedded within templates
+==================== END: utils#template-format ====================
--- a/dist/teams/team-all.txt
+++ b/dist/teams/team-all.txt
--- a/dist/teams/team-fullstack.txt
+++ b/dist/teams/team-fullstack.txt
--- a/dist/teams/team-ide-minimal.txt
+++ b/dist/teams/team-ide-minimal.txt
--- a/dist/teams/team-no-ui.txt
+++ b/dist/teams/team-no-ui.txt
--- a/docs/agentic-tools/claude-code-guide.md
+++ b/docs/agentic-tools/claude-code-guide.md
@@ -0,0 +1,36 @@
+# BMAD Method Guide for Claude Code
+
+This guide covers Claude Code-specific setup and usage with BMAD Method. 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:
+
+- `/bmad-master` - Universal task executor
+- `/sm` - Scrum Master
+- `/dev` - Full-stack developer
+- `/architect` - Solution architect
+- `/pm` - Product manager
+- `/analyst` - Business analyst
+- `/qa` - QA specialist
+- `/po` - Product owner
+- `/ux-expert` - UX specialist
+
+## Claude Code-Specific Features
+
+- **Command files**: Stored in `.claude/commands/` as `.md` files
+- **Activation**: Use forward slash `/` prefix for all agents
+- **Chat management**: Start new chats when switching agents for clean context
+
+## Tips for Claude Code Users
+
+- Commands are auto-suggested as you type `/`
+- Each agent supports `*help` to see available commands
+- Claude Code maintains excellent context within each chat
--- a/docs/agentic-tools/cline-guide.md
+++ b/docs/agentic-tools/cline-guide.md
@@ -0,0 +1,42 @@
+# BMAD Method Guide for Cline (VS Code)
+
+This guide covers Cline-specific setup and usage with BMAD Method. 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
+
+## Available Agents
+
+All agents use `@` prefix:
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master
+- `@dev` - Full-stack developer
+- `@architect` - Solution architect
+- `@pm` - Product manager
+- `@analyst` - Business analyst
+- `@qa` - QA specialist
+- `@po` - Product owner
+- `@ux-expert` - UX specialist
+
+## Cline-Specific Features
+
+- **Rule files**: Stored as numbered files in `.clinerules/` (e.g., `01-bmad-master.md`)
+- **Agent ordering**: Prioritized list with core agents first
+- **VS Code integration**: Works within VS Code's Cline extension panel
+
+## Tips for Cline Users
+
+- Cline maintains conversation context well
+- Use `@agent-name` at the start of your message for best results
+- Agent rules are loaded automatically when mentioned
--- a/docs/agentic-tools/cursor-guide.md
+++ b/docs/agentic-tools/cursor-guide.md
@@ -0,0 +1,37 @@
+# BMAD Method Guide for Cursor
+
+This guide covers Cursor-specific setup and usage with BMAD Method. 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:
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master
+- `@dev` - Full-stack developer
+- `@architect` - Solution architect
+- `@pm` - Product manager
+- `@analyst` - Business analyst
+- `@qa` - QA specialist
+- `@po` - Product owner
+- `@ux-expert` - UX specialist
+
+## Cursor-Specific Features
+
+- **Rule files**: Stored in `.cursor/rules/` as `.mdc` files
+- **Auto-completion**: Cursor suggests agents as you type `@`
+- **Context awareness**: Agents can see your current file selection
+- **Custom agents**: For better performance, copy agent content into Cursor's custom modes
+
+## Tips for Cursor Users
+
+- Start new chats when switching agents
+- Each agent supports `*help` to see available commands
+- Leverage Cursor's file context for more accurate assistance
--- a/docs/agentic-tools/gemini-cli-guide.md
+++ b/docs/agentic-tools/gemini-cli-guide.md
@@ -0,0 +1,46 @@
+# BMAD Method Guide for Gemini CLI
+
+This guide covers Gemini CLI-specific setup and usage with BMAD Method. 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.
+
+## Available Agents
+
+All agents are referenced with `@` in prompts:
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master
+- `@dev` - Full-stack developer
+- `@architect` - Solution architect
+- `@pm` - Product manager
+- `@analyst` - Business analyst
+- `@qa` - QA specialist
+- `@po` - Product owner
+- `@ux-expert` - UX specialist
+
+## 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
--- a/docs/agentic-tools/roo-code-guide.md
+++ b/docs/agentic-tools/roo-code-guide.md
@@ -0,0 +1,46 @@
+# BMAD Method Guide for Roo Code
+
+This guide covers Roo Code-specific setup and usage with BMAD Method. 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
+
+## Using BMAD Agents in Roo Code
+
+Select mode from the mode selector (usually in status bar):
+
+- `bmad-bmad-master` - 🧙 Universal task executor
+- `bmad-sm` - 🏃 Scrum Master
+- `bmad-dev` - 💻 Full-stack developer
+- `bmad-architect` - 🏗️ Solution architect
+- `bmad-pm` - 📋 Product manager
+- `bmad-analyst` - 📊 Business analyst
+- `bmad-qa` - 🧪 QA specialist
+- `bmad-po` - 🎯 Product owner
+- `bmad-ux-expert` - 🎨 UX specialist
+
+## Roo Code-Specific Features
+
+- **Mode file**: `.roomodes` in project root
+- **Mode switching**: Use mode selector instead of starting new chats
+- **Context preservation**: Maintains context across mode switches
+- **File permissions**: Each agent has specific file access:
+
+### File Permission Summary
+
+- **Documentation agents** (analyst, pm, po, sm): `.md`, `.txt` only
+- **bmad-architect**: `.md`, `.txt`, `.yml`, `.yaml`, `.json`
+- **bmad-qa**: Test files (`.test.*`, `.spec.*`) and `.md`
+- **bmad-ux-expert**: `.md`, `.css`, `.scss`, `.html`, `.jsx`, `.tsx`
+- **Full access**: `bmad-dev`, `bmad-bmad-master`, `bmad-orchestrator`
+
+## Tips for Roo Code Users
+
+- Switch modes instead of starting new chats
+- Each mode supports `*help` to see available commands
+- Agents respect file permission boundaries
+- Context persists across mode switches
--- a/docs/agentic-tools/windsurf-guide.md
+++ b/docs/agentic-tools/windsurf-guide.md
@@ -0,0 +1,37 @@
+# BMAD Method Guide for Windsurf
+
+This guide covers Windsurf-specific setup and usage with BMAD Method. 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:
+
+- `@bmad-master` - Universal task executor
+- `@sm` - Scrum Master
+- `@dev` - Full-stack developer
+- `@architect` - Solution architect
+- `@pm` - Product manager
+- `@analyst` - Business analyst
+- `@qa` - QA specialist
+- `@po` - Product owner
+- `@ux-expert` - UX specialist
+
+## Windsurf-Specific Features
+
+- **Rule files**: Stored in `.windsurf/rules/` as `.md` files
+- **Activation**: Use `@` prefix to mention agents
+- **Collaborative features**: Works well with BMAD's agent-switching pattern
+- **Project context**: Agents have access to your full project context
+
+## Tips for Windsurf Users
+
+- Start new chats when switching agents
+- Each agent supports `*help` to see available commands
+- Leverage Windsurf's collaboration features for team reviews
--- a/docs/bmad-workflow-guide.md
+++ b/docs/bmad-workflow-guide.md
@@ -33,11 +33,13 @@ The BMAD Method follows a structured approach to AI-assisted software developmen

 Use Google's Gemini for collaborative planning with the full team:

-1. **Open [Google AI Studio](https://aistudio.google.com/)**
-2. **Load team-fullstack**:
-   - Copy contents of: `/Users/brianmadison/dev/BMAD-METHOD/.bmad-core/web-bundles/teams/team-fullstack.txt`
-   - Paste into new Gemini chat
-3. **Collaborate with the 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")
+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
+4. **Collaborate with the team**:
   - Business Analyst: Requirements gathering
   - Product Manager: Feature prioritization
   - Solution Architect: Technical design
@@ -53,9 +55,9 @@ Help me brainstorm features and create a comprehensive PRD."
 that can handle [specific requirements]."
 ```

-4. **Export planning documents**:
-   - Save PRD as `docs/prd.md`
-   - Save architecture as `docs/architecture.md`
+5. **Export planning documents**:
+   - Copy the PRD output and save as `docs/prd.md` in your project
+   - Copy the architecture output and save as `docs/architecture.md` in your project

 ### Phase 3: Document Organization (IDE)

--- a/docs/claude-code-guide.md
+++ b/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`
-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.
--- a/docs/core-architecture.md
+++ b/docs/core-architecture.md
@@ -35,7 +35,7 @@ graph TD
        end

        subgraph Outputs
-            J[".bmad-core/web-bundles"]
+            J["dist"]
        end

        B -- defines dependencies for --> E
@@ -59,7 +59,7 @@ graph TD
    style A fill:#1a73e8,color:#fff
    style I fill:#f9ab00,color:#fff
    style J fill:#34a853,color:#fff
-```text
+```

 ## 3. Core Components

@@ -110,6 +110,7 @@ The system maintains a clean separation of concerns: template markup is processe
 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:**
+
 - **Consistency**: Ensures all agents reference the same technical preferences
 - **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
 - **Personalization**: Agents provide recommendations aligned with user preferences
@@ -119,6 +120,7 @@ BMAD includes a personalization layer through the `technical-preferences.md` fil
 The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.

 **Integration Points:**
+
 - Templates can reference technical preferences during document generation
 - Agents suggest preferred technologies when appropriate for project requirements
 - When preferences don't fit project needs, agents explain alternatives
@@ -133,17 +135,17 @@ The framework is designed for two primary environments: local IDEs and web-based

 ### 4.1. Web Builder (`tools/builders/web-builder.js`)

- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `.bmad-core/web-bundles/`.
+- **Purpose**: This Node.js script is responsible for creating the `.txt` bundles found in `dist`.
 - **Process**:
  1. **Resolves Dependencies**: For a given agent or team, the script reads its definition file.
  2. It recursively finds all dependent resources (tasks, templates, etc.) that the agent/team needs.
  3. **Bundles Content**: It reads the content of all these files and concatenates them into a single, large text file, with clear separators indicating the original file path of each section.
-  4. **Outputs Bundle**: The final `.txt` file is saved in the `web-bundles` directory, ready to be uploaded to a web UI.
+  4. **Outputs Bundle**: The final `.txt` file is saved in the `dist` directory, ready to be uploaded to a web UI.

 ### 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 Web UIs**: Users upload a pre-built bundle from `.bmad-core/web-bundles/`. This single file provides the AI with the context of the entire team and all their required tools and knowledge.
+- **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

@@ -202,12 +204,180 @@ 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.
+
+## 8. Complete Source Tree
+
+The BMAD-METHOD project structure is designed for clarity, modularity, and extensibility. Here's the complete source tree with explanations:
+
+```plaintext
+bmad-method/
+├── .bmad-core/                    # Core framework (installed in user projects)
+│   ├── agents/                    # Individual agent definitions
+│   │   ├── analyst.md            # Business analyst agent
+│   │   ├── architect.md          # Solution architect agent
+│   │   ├── bmad-master.md        # Universal expert agent
+│   │   ├── bmad-orchestrator.md  # Multi-agent coordinator
+│   │   ├── dev.md                # Full-stack developer agent
+│   │   ├── pm.md                 # Product manager agent
+│   │   ├── po.md                 # Product owner agent
+│   │   ├── qa.md                 # QA specialist agent
+│   │   ├── sm.md                 # Scrum master agent
+│   │   └── ux-expert.md          # UX designer agent
+│   ├── agent-teams/              # Pre-configured agent teams
+│   │   ├── team-all.yml          # All agents bundle
+│   │   ├── team-fullstack.yml    # Full-stack development team
+│   │   ├── team-ide-minimal.yml  # Minimal IDE-focused team
+│   │   └── team-no-ui.yml        # Backend-only team
+│   ├── checklists/               # Quality assurance checklists
+│   │   ├── architect-checklist.md
+│   │   ├── po-master-checklist.md
+│   │   └── story-dod-checklist.md
+│   ├── data/                     # Knowledge base and preferences
+│   │   ├── bmad-kb.md            # Core knowledge base
+│   │   └── technical-preferences.md  # User tech preferences
+│   ├── tasks/                    # Reusable task definitions
+│   │   ├── advanced-elicitation.md   # Deep diving techniques
+│   │   ├── create-doc.md         # Document creation task
+│   │   ├── create-next-story.md  # Story generation task
+│   │   ├── doc-migration-task.md # V3 to V4 migration
+│   │   ├── execute-checklist.md  # Checklist runner
+│   │   └── shard-doc.md          # Document sharding task
+│   ├── templates/                # Document templates
+│   │   ├── full-stack-architecture-tmpl.md
+│   │   ├── prd-tmpl.md
+│   │   ├── project-brief-tmpl.md
+│   │   ├── story-tmpl.md
+│   │   └── [other templates...]
+│   ├── utils/                    # Utility components
+│   │   ├── agent-switcher.web    # Web UI agent switching
+│   │   ├── template-format.md    # Template markup spec
+│   │   └── workflow-management.md # Workflow helpers
+│   ├── workflows/                # Development workflows
+│   │   ├── brownfield-enhancement.yml
+│   │   ├── greenfield-fullstack.yml
+│   │   ├── greenfield-service.yml
+│   │   └── greenfield-simple.yml
+│   └── core-config.yml           # V4 configuration system
+│
+├── dist/                         # Pre-built bundles (generated)
+│   ├── agents/                   # Individual agent bundles
+│   │   ├── analyst.txt
+│   │   ├── architect.txt
+│   │   └── [other agents...]
+│   ├── teams/                    # Team bundles for web UI
+│   │   ├── team-all.txt
+│   │   ├── team-fullstack.txt
+│   │   └── [other teams...]
+│   └── expansion-packs/          # Expansion pack bundles
+│
+├── docs/                         # Documentation
+│   ├── agentic-tools/           # IDE-specific guides
+│   │   ├── claude-code-guide.md
+│   │   ├── cursor-guide.md
+│   │   ├── cline-guide.md
+│   │   ├── gemini-cli-guide.md
+│   │   ├── roo-code-guide.md
+│   │   └── windsurf-guide.md
+│   ├── bmad-workflow-guide.md    # Universal workflow guide
+│   ├── core-architecture.md      # This document
+│   ├── expansion-packs.md        # Expansion pack guide
+│   ├── user-guide.md            # Comprehensive user guide
+│   └── [other docs...]
+│
+├── expansion-packs/              # Domain-specific extensions
+│   ├── bmad-2d-phaser-game-dev/ # Game development pack
+│   ├── bmad-creator-tools/      # Agent creation tools
+│   ├── bmad-infrastructure-devops/ # DevOps pack
+│   └── README.md
+│
+├── tools/                        # Build and installation tools
+│   ├── builders/                 # Build system
+│   │   └── web-builder.js       # Bundle generator
+│   ├── cli.js                   # Main CLI tool
+│   ├── installer/               # NPX installer
+│   │   ├── index.js             # Installer entry point
+│   │   ├── config/              # Installation configs
+│   │   ├── lib/                 # Installer utilities
+│   │   └── templates/           # IDE template files
+│   └── lib/                     # Shared libraries
+│       ├── bundle-utils.js
+│       ├── dependency-resolver.js
+│       └── file-processor.js
+│
+├── .github/                     # GitHub configuration
+│   ├── workflows/               # GitHub Actions
+│   └── ISSUE_TEMPLATE/         # Issue templates
+│
+├── common/                      # Shared resources
+│   ├── tasks/                   # Common tasks
+│   └── utils/                   # Common utilities
+│
+├── bmad-core/                   # Source for .bmad-core
+│   └── [mirrors .bmad-core structure]
+│
+├── package.json                 # Node.js configuration
+├── README.md                    # Project readme
+├── CONTRIBUTING.md              # Contribution guidelines
+├── GUIDING-PRINCIPLES.md        # Core principles
+└── LICENSE                      # MIT license
+```
+
+### Directory Purposes
+
+#### Core Framework (.bmad-core/)
+
+- **agents/**: Individual AI agent personalities and capabilities
+- **agent-teams/**: Bundles of agents for specific workflows
+- **checklists/**: Quality assurance and validation steps
+- **data/**: Knowledge base and user preferences
+- **tasks/**: Reusable procedures agents can execute
+- **templates/**: Document templates with embedded AI instructions
+- **utils/**: Helper components for agents
+- **workflows/**: Structured development processes
+
+#### Generated Bundles (dist/)
+
+- Pre-built text files ready for web UI upload
+- Automatically generated by the build system
+- Includes resolved dependencies for each agent/team
+
+#### Tools (tools/)
+
+- **cli.js**: Main build tool for creating bundles
+- **installer/**: NPX-based installer for projects
+- **builders/**: Bundle generation logic
+- **lib/**: Shared utilities for build system
+
+#### Expansion Packs (expansion-packs/)
+
+- Domain-specific agent collections
+- Extend BMAD beyond software development
+- Each pack is self-contained with its own agents, tasks, and templates
+
+#### Documentation (docs/)
+
+- Comprehensive guides for users
+- Technical architecture documentation
+- IDE-specific setup instructions
+
+### Key Files
+
+- **core-config.yml**: V4's flexible configuration system
+- **bmad-kb.md**: Central knowledge base loaded by most agents
+- **template-format.md**: Specification for BMAD's template markup
+- **dependency-resolver.js**: Manages agent resource loading
--- a/docs/cursor-guide.md
+++ b/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`
-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.
--- a/docs/expansion-packs.md
+++ b/docs/expansion-packs.md
@@ -0,0 +1,280 @@
+# 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.
+
+## 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.
+
+### Domain Expertise
+
+Each expansion pack provides deep, specialized knowledge without bloating the core system. Install only what you need.
+
+### Community Innovation
+
+Anyone can create and share expansion packs, fostering a ecosystem of AI-powered solutions across all industries and interests.
+
+## Technical Expansion Packs
+
+### Game Development Pack
+
+Transform your AI into a complete game development studio:
+
+- **Game Designer**: Mechanics, balance, progression systems
+- **Level Designer**: Map layouts, puzzle design, difficulty curves
+- **Narrative Designer**: Story arcs, dialog trees, lore creation
+- **Art Director**: Visual style guides, asset specifications
+- **Sound Designer**: Audio direction, music themes, SFX planning
+
+### Mobile Development Pack
+
+Specialized agents for mobile app creation:
+
+- **iOS Specialist**: Swift/SwiftUI patterns, Apple guidelines
+- **Android Expert**: Kotlin best practices, Material Design
+- **Mobile UX Designer**: Touch interfaces, gesture patterns
+- **App Store Optimizer**: ASO strategies, listing optimization
+- **Performance Tuner**: Battery optimization, network efficiency
+
+### DevOps/Infrastructure Pack
+
+Complete infrastructure automation team:
+
+- **Cloud Architect**: AWS/Azure/GCP design patterns
+- **Security Specialist**: Zero-trust implementation, compliance
+- **SRE Expert**: Monitoring, alerting, incident response
+- **Container Orchestrator**: Kubernetes, Docker optimization
+- **Cost Optimizer**: Cloud spend analysis, resource right-sizing
+
+### Data Science Pack
+
+AI-powered data analysis team:
+
+- **Data Scientist**: Statistical analysis, ML model selection
+- **Data Engineer**: Pipeline design, ETL processes
+- **ML Engineer**: Model deployment, A/B testing
+- **Visualization Expert**: Dashboard design, insight communication
+- **Ethics Advisor**: Bias detection, fairness assessment
+
+## Non-Technical Expansion Packs
+
+### Business Strategy Pack
+
+Complete business advisory team:
+
+- **Strategy Consultant**: Market positioning, competitive analysis
+- **Financial Analyst**: Projections, unit economics, funding strategies
+- **Operations Manager**: Process optimization, efficiency improvements
+- **Marketing Strategist**: Go-to-market plans, growth hacking
+- **HR Advisor**: Talent strategies, culture building
+
+### Creative Writing Pack
+
+Your personal writing team:
+
+- **Plot Architect**: Three-act structure, story beats, pacing
+- **Character Psychologist**: Deep motivations, authentic dialog
+- **World Builder**: Consistent universes, cultural systems
+- **Editor**: Style consistency, grammar, flow
+- **Beta Reader**: Feedback simulation, plot hole detection
+
+### Health & Wellness Pack
+
+Personal wellness coaching system:
+
+- **Fitness Trainer**: Progressive overload, form correction
+- **Nutritionist**: Macro planning, supplement guidance
+- **Sleep Coach**: Circadian optimization, sleep hygiene
+- **Stress Manager**: Coping strategies, work-life balance
+- **Habit Engineer**: Behavior change, accountability systems
+
+### Education Pack
+
+Complete learning design system:
+
+- **Curriculum Architect**: Learning objectives, scope & sequence
+- **Instructional Designer**: Engagement strategies, multimedia learning
+- **Assessment Specialist**: Rubrics, formative/summative evaluation
+- **Differentiation Expert**: Adaptive learning, special needs
+- **EdTech Integrator**: Tool selection, digital pedagogy
+
+### Mental Health Support Pack
+
+Therapeutic support system:
+
+- **CBT Guide**: Cognitive restructuring, thought challenging
+- **Mindfulness Teacher**: Meditation scripts, awareness exercises
+- **Journal Therapist**: Reflective prompts, emotional processing
+- **Crisis Support**: Coping strategies, safety planning
+- **Habit Tracker**: Mood monitoring, trigger identification
+
+### Legal Assistant Pack
+
+Legal document and research support:
+
+- **Contract Analyst**: Term review, risk assessment
+- **Legal Researcher**: Case law, precedent analysis
+- **Document Drafter**: Template customization, clause libraries
+- **Compliance Checker**: Regulatory alignment, audit prep
+- **IP Advisor**: Patent strategies, trademark guidance
+
+### Real Estate Pack
+
+Property investment and management:
+
+- **Market Analyst**: Comparable analysis, trend prediction
+- **Investment Calculator**: ROI modeling, cash flow analysis
+- **Property Manager**: Tenant screening, maintenance scheduling
+- **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
+
+AI-powered tabletop RPG assistance:
+
+- **World Master**: Dynamic world generation, NPC creation
+- **Combat Referee**: Initiative tracking, rule clarification
+- **Story Weaver**: Plot hooks, side quests, consequences
+- **Character Builder**: Backstory generation, stat optimization
+- **Loot Master**: Treasure generation, magic item creation
+
+### Life Event Planning Pack
+
+Major life event coordination:
+
+- **Wedding Planner**: Vendor coordination, timeline creation
+- **Event Designer**: Theme development, decoration plans
+- **Budget Manager**: Cost tracking, vendor negotiation
+- **Guest Coordinator**: RSVP tracking, seating arrangements
+- **Timeline Keeper**: Day-of scheduling, contingency planning
+
+### Hobby Mastery Pack
+
+Deep dive into specific hobbies:
+
+- **Garden Designer**: Plant selection, seasonal planning
+- **Brew Master**: Recipe formulation, process optimization
+- **Maker Assistant**: 3D printing, woodworking, crafts
+- **Collection Curator**: Organization, valuation, trading
+- **Photography Coach**: Composition, lighting, post-processing
+
+### Scientific Research Pack
+
+Research acceleration tools:
+
+- **Literature Reviewer**: Paper summarization, gap analysis
+- **Hypothesis Generator**: Research question formulation
+- **Methodology Designer**: Experiment planning, control design
+- **Statistical Advisor**: Test selection, power analysis
+- **Grant Writer**: Proposal structure, impact statements
+
+## Creating Your Own Expansion Pack
+
+### Step 1: Define Your Domain
+
+What expertise are you capturing? What problems will it solve?
+
+### Step 2: Design Your Agents
+
+Each agent should have:
+
+- Clear expertise area
+- Specific personality traits
+- Defined capabilities
+- Knowledge boundaries
+
+### Step 3: Create Tasks
+
+Tasks should be:
+
+- Step-by-step procedures
+- Reusable across scenarios
+- Clear and actionable
+- Domain-specific
+
+### Step 4: Build Templates
+
+Templates need:
+
+- Structured output format
+- Embedded LLM instructions
+- Placeholders for customization
+- Professional formatting
+
+### Step 5: Test & Iterate
+
+- Use with real scenarios
+- Gather user feedback
+- Refine agent responses
+- Improve task clarity
+
+### Step 6: Package & Share
+
+- Create clear documentation
+- Include usage examples
+- Add to expansion-packs directory
+- Share with community
+
+## The Future of Expansion Packs
+
+### Marketplace Potential
+
+Imagine a future where:
+
+- Professional expansion packs are sold
+- Certified packs for regulated industries
+- Community ratings and reviews
+- Automatic updates and improvements
+
+### AI Agent Ecosystems
+
+Expansion packs could enable:
+
+- Cross-pack agent collaboration
+- Industry-standard agent protocols
+- Interoperable AI workflows
+- Universal agent languages
+
+### Democratizing Expertise
+
+Every expansion pack:
+
+- Makes expert knowledge accessible
+- Reduces barriers to entry
+- Enables solo entrepreneurs
+- Empowers small teams
+
+## Getting Started
+
+1. **Browse existing packs**: Check `expansion-packs/` directory
+2. **Install what you need**: Use the installer's expansion pack option
+3. **Create your own**: Use the expansion-creator pack
+4. **Share with others**: Submit PRs with new packs
+5. **Build the future**: Help shape AI-assisted work
+
+## 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.
+
+**What expertise will you share with the world?**
--- a/docs/how-to-contribute-with-pull-requests.md
+++ b/docs/how-to-contribute-with-pull-requests.md
@@ -8,7 +8,15 @@ A pull request (PR) is how you propose changes to a project on GitHub. Think of

 ## Before You Start

-⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change. If you're planning something big, please [open an issue](https://github.com/bmadcode/bmad-method/issues) or start a [discussion](https://github.com/bmadcode/bmad-method/discussions) first.
+⚠️ **Important**: Please keep your contributions small and focused! We prefer many small, clear changes rather than one massive change.
+
+**Required before submitting PRs:**
+
+- **For bug fixes**: Create an issue using the [bug report template](https://github.com/bmadcode/bmad-method/issues/new?template=bug_report.md)
+- **For new features**:
+  1. Discuss in Discord [#general-dev channel](https://discord.gg/g6ypHytrCB)
+  2. Create an issue using the [feature request template](https://github.com/bmadcode/bmad-method/issues/new?template=feature_request.md)
+- **For large changes**: Always open an issue first to discuss alignment

 ## Step-by-Step Guide

@@ -24,7 +32,7 @@ A pull request (PR) is how you propose changes to a project on GitHub. Think of
 # Replace YOUR-USERNAME with your actual GitHub username
 git clone https://github.com/YOUR-USERNAME/bmad-method.git
 cd bmad-method
-```text
+```

 ### 3. Create a New Branch

@@ -57,7 +65,7 @@ git add .

 # Commit with a clear message
 git commit -m "Fix typo in README.md"
-```text
+```

 **Good commit messages:**

@@ -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
--- a/docs/roo-code-guide.md
+++ b/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`
-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.
--- a/docs/user-guide.md
+++ b/docs/user-guide.md
@@ -1,6 +1,6 @@
-# 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.

 ## Table of Contents

@@ -46,7 +46,7 @@ BMAD-METHOD (Breakthrough Method of Agile AI-Driven Development) is an AI agent

 Best for: ChatGPT, Claude, Gemini users

-1. Navigate to `.bmad-core/web-bundles/teams/`
+1. Navigate to `dist/teams/`
 2. Copy `team-fullstack.txt` content
 3. Create new Gemini Gem or CustomGPT
 4. Upload file with instructions: "Your critical operating instructions are attached, do not break character as directed"
@@ -59,10 +59,20 @@ Best for: Cursor, Claude Code, Windsurf, VS Code users
 ```bash
 # Interactive installation (recommended)
 npx bmad-method install
+```

-# Command line installation
-npx bmad-method install --full --directory ./my-project --ide cursor
-```text
+### CLI Commands
+
+```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
+```

 ### First Steps

@@ -71,17 +81,44 @@ npx bmad-method install --full --directory ./my-project --ide cursor
 3. **Initialize Project**: Run `/help` or `*help` to see capabilities
 4. **Start Development**: Begin with planning or jump into coding

+### 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 by 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-coreconfigyml)
+
+**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/` - you can remove the backup folder versions.
+
 ## 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     |
+| `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                      |
@@ -130,7 +167,7 @@ dependencies:
 # Claude Code (files in commands folder - loaded with /)
 /pm Create user stories
 /dev Fix the login bug
-```text
+```

 **In Web UI:**

@@ -203,10 +240,12 @@ For cost efficiency, especially with Gemini:
 #### File Naming Conventions

 **Required Names for Framework Integration:**
+
 - `docs/prd.md` - Product Requirements Document
 - `docs/architecture.md` - System Architecture Document

 **Why These Names Matter:**
+
 - Agents automatically reference these files during development
 - Sharding tasks expect these specific filenames
 - Workflow automation depends on standard naming
@@ -214,6 +253,7 @@ For cost efficiency, especially with Gemini:
 #### IDE Document Creation

 When working directly in IDEs:
+
 - Agents should create documents in `docs/` folder automatically
 - If agents name files differently (e.g., `product-requirements.md`), rename to `prd.md`
 - Verify document location matches `docs/prd.md` and `docs/architecture.md`
@@ -226,7 +266,7 @@ Templates can include `advanced-elicitation.md` for enhanced interaction:

 ```markdown
 [[LLM: Use advanced-elicitation actions 0-3 to refine requirements]]
-```text
+```

 This provides 10 structured brainstorming actions:

@@ -284,21 +324,30 @@ Once planning is complete and documents are sharded, BMAD follows a structured d

 ```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
-```text
+    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 +368,213 @@ 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.yml` 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 different agents:
+
+**SM Agent Instructions**:
+
+- Populate Dev Notes with specific technical details from architecture
+- Include source references for all technical guidance
+- Create detailed tasks based on architecture constraints
+- Add testing requirements from testing strategy
+
+**Dev Agent Instructions**:
+
+- Update Debug Log References during implementation
+- Document any deviations in Completion Notes
+- Maintain comprehensive File List of all changes
+- Track requirement changes in Change Log
+
+**QA Agent Instructions**:
+
+- Append review results in QA Results section
+- Document refactoring performed with explanations
+- Note security and performance considerations
+
+#### 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
+
+#### Example: How Notes Flow Between Stories
+
+**Story 1.1 Completion**:
+
+```markdown
+### Completion Notes List
+
+- Discovered that user authentication requires additional session management not specified in architecture
+- Created new SessionManager service in services/auth/session-manager.ts
+- Recommend updating architecture to include session management patterns
+```
+
+**Story 1.2 Creation** (SM uses the above notes):
+
+```markdown
+## Dev Notes
+
+### Previous Story Insights
+
+- Story 1.1 created SessionManager service for auth (services/auth/session-manager.ts)
+- Consider using SessionManager for this story's user profile feature
+- Architecture update pending for session management patterns
+```
+
+This continuous feedback loop ensures each story benefits from lessons learned in previous implementations.
+
+#### QA Agent Key Principles
+
+When the QA agent performs the review-story task:
+
+- **Senior Developer Authority**: Reviews as a senior developer with authority to refactor directly
+- **Active Improvement**: Makes code improvements rather than just identifying issues
+- **Teaching Focus**: Explains all changes for developer learning and growth
+- **Pragmatic Balance**: Focuses on significant improvements, not nitpicks
+- **Quality Gates**: Can block story completion if critical issues exist
+
+**QA Blocking Conditions**:
+The QA will stop and request clarification if:
+
+- Story file is incomplete or missing critical sections
+- File List is empty or clearly incomplete
+- No tests exist when they were required
+- Code changes don't align with story requirements
+- Critical architectural issues require discussion
+
+- **Benefits of QA Review**:
+  - Code quality improvements and refactoring
+  - Knowledge transfer through documented explanations
+  - Catching edge cases and security issues
+  - Ensuring architectural consistency

 ### Workflow Types

@@ -487,11 +734,13 @@ workflows:
 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
@@ -517,6 +766,7 @@ Web UI agents focus on planning and documentation. Here's how to interact with e
 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
@@ -525,7 +775,7 @@ Web UI agents focus on planning and documentation. Here's how to interact with e

 ### 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
@@ -557,7 +807,7 @@ dependencies:
 ## Section 2

 {{section_2_content}}
-```text
+```

 ### Workflow Customization

@@ -592,7 +842,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
@@ -611,27 +861,34 @@ Templates are self-contained documents that embed both output structure and proc
@{example: Example content for AI guidance}

 ^^CONDITION: condition_name^^
+
 ## Conditional Section
+
 [[LLM: Only include if condition is met]]
 ^^/CONDITION^^
-```text
+```

 #### Key Template Patterns

 **Variable Substitution:**
+
 - `{{Project Name}}` - Dynamic project name
 - `{{document_title}}` - Document-specific title
 - `{{section_content}}` - Placeholder for generated content

 **AI Processing Instructions:**
+
 - `[[LLM: Instructions for AI behavior]]` - AI-only processing directives
 - `@{example: Sample content}` - Guidance examples (not output)
 - `tasks#advanced-elicitation` - Reference to embedded tasks

 **Conditional Content:**
+
 ```markdown
 ^^CONDITION: has_ui^^
+
 ## User Interface Section
+
 [[LLM: Only include for UI projects]]
 ^^/CONDITION^^
 ```
@@ -641,14 +898,19 @@ Templates are self-contained documents that embed both output structure and proc
 Level 2 headings (`##`) in templates can be automatically sharded into separate documents:

 **Original PRD:**
+
 ```markdown
 ## Goals and Background Context
+
 ## Requirements
+
 ## User Interface Design Goals
+
 ## Success Metrics
-```text
+```

 **After Sharding:**
+
 - `docs/prd/goals-and-background-context.md`
 - `docs/prd/requirements.md`
 - `docs/prd/user-interface-design-goals.md`
@@ -673,10 +935,12 @@ Tasks are reusable automation instructions that agents can execute. They follow
 ## Instructions

 ### 1. Step One
+
 - Detailed instructions for the agent
 - Specific behaviors and outputs expected

 ### 2. Step Two
+
 - Additional processing steps
 - Integration with other resources

@@ -688,20 +952,23 @@ Tasks are reusable automation instructions that agents can execute. They follow
 #### Task Patterns

 **Resource Integration:**
+
 ```markdown
 [[LLM: Check if docs/coding-standards.md exists and reference it]]
 [[LLM: Load docs/openapi-spec.yaml for API context]]
-```text
+```

 **Advanced Elicitation:**
+
 ```markdown
 [[LLM: Apply tasks#advanced-elicitation protocol after completion]]
 ```

 **Conditional Logic:**
+
 ```markdown
 [[LLM: If project has UI components, also check frontend standards]]
-```text
+```

 ### Creating Custom Agents

@@ -747,7 +1014,7 @@ startup:
  - Review docs/project-structure.md for context
  - Check for docs/third-party-apis/ folder
  - Announce specialized capabilities
-```text
+```

 #### Loading Project Documents

@@ -763,6 +1030,7 @@ Agents can reference and load documents from the `docs/` folder:

 ```markdown
 [[LLM: Before beginning, check for and load relevant context:
+
 - docs/coding-standards.md for development standards
 - docs/brand-guidelines.md for design consistency
 - docs/third-party-apis/ for integration requirements
@@ -780,50 +1048,60 @@ This file allows you to define your preferred technologies, patterns, and standa
 #### What to Include

 **Technology Stack Preferences:**
+
 ```markdown
 ## Preferred Technologies

 ### Frontend
+
 - React with TypeScript
 - Tailwind CSS for styling
 - Next.js for full-stack applications

 ### Backend
+
 - Node.js with Express
 - PostgreSQL for relational data
 - Redis for caching

 ### Deployment
+
 - Vercel for frontend
 - Railway for backend services
-```text
+```

 **Design Patterns & Standards:**
+
 ```markdown
 ## Code Standards
+
 - Use functional programming patterns where possible
 - Prefer composition over inheritance
 - Always include comprehensive error handling
 - Write tests for all business logic

 ## Architecture Preferences
+
 - Microservices for complex applications
 - RESTful APIs with OpenAPI documentation
 - Event-driven architecture for real-time features
 ```

 **External Services & APIs:**
+
 ```markdown
 ## Preferred External Services
+
 - Auth0 for authentication
 - Stripe for payments
 - SendGrid for email
 - Cloudinary for image processing

 ## APIs to Avoid
+
 - Legacy SOAP services
 - Services without proper documentation
-```text
+```

 #### How Agents Use This File

@@ -837,22 +1115,264 @@ This file allows you to define your preferred technologies, patterns, and standa

 **Learning and Evolution**: As you work on projects, add discoveries to your preferences file:

-```markdown
 ## Lessons Learned
+
 - Avoid using Library X for large datasets (performance issues)
 - Pattern Y works well for real-time features
 - Service Z has excellent documentation and support

 ## Future Exploration
+
 - Want to try Framework A on next appropriate project
 - Interested in Pattern B for microservices
 - Consider Service C for better performance
-```

-#### Using with Web Bundles
+### Using with Web Bundles

 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)
+
+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.
+
+#### Understanding core-config.yml
+
+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
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: docs/stories # Where completed stories are saved
+
+  prd:
+    prdFile: docs/prd.md
+    prdVersion: v4 # v3 or v4
+    prdSharded: true # false if epics are embedded in PRD
+    prdShardedLocation: docs/prd # Where sharded epics live
+    epicFilePattern: epic-{n}*.md # Pattern for epic files
+
+  architecture:
+    architectureFile: docs/architecture.md
+    architectureVersion: v4 # v3 or v4
+    architectureSharded: true # false if monolithic
+    architectureShardedLocation: docs/architecture
+
+  customTechnicalDocuments: null # Additional docs for SM
+
+  devLoadAlwaysFiles: # Files dev agent always loads
+    - docs/architecture/coding-standards.md
+    - docs/architecture/tech-stack.md
+    - docs/architecture/project-structure.md
+
+  devDebugLog: .ai/debug-log.md # Dev agent debug tracking
+  agentCoreDump: .ai/core-dump{n}.md # Export chat contents
+```
+
+#### Key Configuration Options
+
+##### PRD Configuration
+
+The Scrum Master agent uses these settings to locate epics:
+
+**V4 Sharded Structure:**
+
+```yaml
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v4
+  prdSharded: true
+  prdShardedLocation: docs/prd
+  epicFilePattern: epic-{n}*.md
+```
+
+**V3 Embedded Epics:**
+
+```yaml
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v3
+  prdSharded: false # Epics are inside PRD
+```
+
+**Custom Sharded Location:**
+
+```yaml
+prd:
+  prdFile: docs/product-requirements.md
+  prdVersion: v4
+  prdSharded: true
+  prdShardedLocation: docs # Epics in docs/ not docs/prd/
+  epicFilePattern: epic-*.md
+```
+
+##### Architecture Configuration
+
+Similar flexibility for architecture documents:
+
+**V4 Sharded Architecture:**
+
+```yaml
+architecture:
+  architectureFile: docs/architecture.md
+  architectureVersion: v4
+  architectureSharded: true
+  architectureShardedLocation: docs/architecture
+```
+
+**V3 Monolithic Architecture:**
+
+```yaml
+architecture:
+  architectureFile: docs/technical-architecture.md
+  architectureVersion: v3
+  architectureSharded: false # All in one file
+```
+
+##### Developer Context Files
+
+Define which files the dev agent should always load:
+
+```yaml
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/project-structure.md
+  - docs/api-contracts.yaml
+  - docs/database-schema.md
+  - .env.example
+```
+
+This ensures the dev agent always has critical context without needing to search for it.
+
+##### Debug and Export Options
+
+**Debug Log:**
+
+```yaml
+devDebugLog: .ai/debug-log.md
+```
+
+When the dev agent encounters repeated failures implementing a story, it logs issues here to avoid repeating the same mistakes.
+
+**Core Dump:**
+
+```yaml
+agentCoreDump: .ai/core-dump{n}.md
+```
+
+Export entire chat conversations for preservation or analysis. The `{n}` is replaced with a number.
+
+#### Common Configurations
+
+##### Legacy V3 Project
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: docs/stories
+  prd:
+    prdFile: docs/prd.md
+    prdVersion: v3
+    prdSharded: false
+  architecture:
+    architectureFile: docs/architecture.md
+    architectureVersion: v3
+    architectureSharded: false
+  devLoadAlwaysFiles: []
+```
+
+##### Hybrid Project (V3 PRD, V4 Architecture)
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: .ai/stories
+  prd:
+    prdFile: docs/product-requirements.md
+    prdVersion: v3
+    prdSharded: false
+  architecture:
+    architectureFile: docs/architecture.md
+    architectureVersion: v4
+    architectureSharded: true
+    architectureShardedLocation: docs/architecture
+  devLoadAlwaysFiles:
+    - docs/architecture/tech-stack.md
+```
+
+##### Custom Organization
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: development/completed-stories
+  prd:
+    prdFile: planning/requirements.md
+    prdVersion: v4
+    prdSharded: true
+    prdShardedLocation: planning/epics
+    epicFilePattern: requirement-{n}.md
+  architecture:
+    architectureFile: technical/system-design.md
+    architectureVersion: v4
+    architectureSharded: true
+    architectureShardedLocation: technical/components
+  customTechnicalDocuments:
+    - technical/api-guide.md
+    - technical/deployment.md
+  devLoadAlwaysFiles:
+    - technical/coding-guidelines.md
+    - technical/git-workflow.md
+```
+
+#### Migration Strategies
+
+##### Gradual V3 to V4 Migration
+
+Start with V3 documents and gradually adopt V4 patterns:
+
+1. **Initial State**: Set `prdVersion: v3` and `prdSharded: false`
+2. **Shard PRD**: Use PO agent to shard, then update to `prdSharded: true`
+3. **Update Version**: Change to `prdVersion: v4` after using V4 templates
+4. **Repeat for Architecture**: Same process for architecture documents
+
+##### Working with Mixed Teams
+
+If some team members use V3 and others use V4:
+
+```yaml
+# Support both patterns
+customTechnicalDocuments:
+  - docs/legacy-requirements.md # V3 format
+  - docs/prd.md # V4 format
+```
+
+#### Best Practices
+
+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
+5. **Document Custom Patterns**: If using custom epicFilePattern, document it
+
+#### Troubleshooting
+
+**Scrum Master Can't Find Epics:**
+
+- Check `prdSharded` matches your structure
+- Verify `prdShardedLocation` path exists
+- Confirm `epicFilePattern` matches your files
+
+**Dev Agent Missing Context:**
+
+- Add critical files to `devLoadAlwaysFiles`
+- Ensure file paths are correct
+- Check files exist and are readable
+
+**Architecture Not Loading:**
+
+- Verify `architectureFile` path
+- Check `architectureVersion` setting
+- Confirm sharding configuration matches reality
+
 ### Extension Packs

 Add specialized capabilities:
@@ -862,7 +1382,7 @@ Add specialized capabilities:
 - **Data Pack**: Analytics, ML integration
 - **Security Pack**: Security analysis, compliance

-## Troubleshooting
+## Troubleshooting Guide

 ### Common Issues

@@ -905,7 +1425,7 @@ Add specialized capabilities:
 - **Documentation**: [Browse docs](https://github.com/bmadcode/bmad-method/tree/main/docs)
 - **YouTube**: [BMadCode Channel](https://www.youtube.com/@BMadCode)

-## Best Practices
+## Best Practices and Tips

 ### Project Organization

@@ -928,7 +1448,7 @@ project/
 - Version control all BMAD-generated content
 - Regular backups of `.bmad-core/` customizations

-### Development Workflow
+### Recommended Development Flow

 #### Planning Phase

--- a/docs/versioning-and-releases.md
+++ b/docs/versioning-and-releases.md
@@ -2,17 +2,17 @@

 ## 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

 Use these prefixes to control what type of release happens:

-````bash
+```bash
 fix: resolve CLI argument parsing bug      # → patch release (4.1.0 → 4.1.1)
 feat: add new agent orchestration mode     # → minor release (4.1.0 → 4.2.0)
 feat!: redesign CLI interface              # → major release (4.1.0 → 5.0.0)
-```text
+```

 ### What Happens Automatically

@@ -35,30 +35,30 @@ git push

 # That's it! Release happens automatically 🎉
 # Users can now run: npx bmad-method (and get the new version)
-````
+```

 ### Commits That DON'T Trigger Releases

 These commit types won't create releases (use them for maintenance):

-````bash
+```bash
 chore: update dependencies     # No release
 docs: fix typo in readme      # No release
 style: format code            # No release
 test: add unit tests          # No release
-```text
+```

 ### Test Your Setup

 ```bash
 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.
--- a/docs/versions.md
+++ b/docs/versions.md
@@ -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

--- a/docs/windsurf-guide.md
+++ b/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`
-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.
--- a/docs/working-in-the-brownfield.md
+++ b/docs/working-in-the-brownfield.md
@@ -0,0 +1,358 @@
+# Working in the Brownfield: A Complete Guide
+
+> 🚀 **HIGHLY RECOMMENDED: Use Gemini Web or Gemini CLI for Brownfield Documentation!**
+>
+> Gemini Web's 1M+ token context window or Gemini CLI (when its working) can analyze your ENTIRE codebase at once:
+>
+> - Upload via GitHub URL
+> - Upload up to 1000 files
+> - Upload zipped project
+
+## 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
+
+- Add significant new features to existing applications
+- Modernize legacy codebases
+- Integrate new technologies or services
+- Refactor complex systems
+- Fix bugs that require architectural understanding
+- Document undocumented systems
+
+## The Complete Brownfield Workflow
+
+### Choose Your Approach
+
+#### 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
+
+1. **Create PRD First** to define requirements
+2. **Document only relevant areas** based on PRD needs
+3. **More efficient** - avoids documenting unused code
+
+#### Approach B: Document-First (Good for Smaller Projects)
+
+**Best for**: Smaller codebases, unknown systems, or exploratory changes
+
+1. **Document entire system** first
+2. **Create PRD** with full context
+3. **More thorough** - captures everything
+
+### Approach A: PRD-First Workflow (Recommended)
+
+#### Phase 1: Define Requirements First
+
+**In Gemini Web (with your codebase uploaded):**
+
+```bash
+@pm
+*create-doc brownfield-prd
+```
+
+The PM will:
+
+- **Ask about your enhancement** requirements
+- **Explore the codebase** to understand current state
+- **Identify affected areas** that need documentation
+- **Create focused PRD** with clear scope
+
+**Key Advantage**: The PRD identifies which parts of your monorepo/large codebase actually need documentation!
+
+#### Phase 2: Focused Documentation
+
+**Still in Gemini Web, now with PRD context:**
+
+```bash
+@analyst
+*document-project
+```
+
+The analyst will:
+
+- **Ask about your focus** if no PRD was provided
+- **Offer options**: Create PRD, provide requirements, or describe the enhancement
+- **Reference the PRD/description** to understand scope
+- **Focus on relevant modules** identified in PRD or your description
+- **Skip unrelated areas** to keep docs lean
+- **Generate ONE architecture document** for all environments
+
+The analyst creates:
+
+- **One comprehensive architecture document** following fullstack-architecture template
+- **Covers all system aspects** in a single file
+- **Easy to copy and save** as `docs/project-architecture.md`
+- **Can be sharded later** in IDE if desired
+
+For example, if you say "Add payment processing to user service":
+
+- Documents only: user service, API endpoints, database schemas, payment integrations
+- Creates focused source tree showing only payment-related code paths
+- Skips: admin panels, reporting modules, unrelated microservices
+
+### Approach B: Document-First Workflow
+
+#### Phase 1: Document the Existing System
+
+**Best Approach - Gemini Web with 1M+ Context**:
+
+1. **Go to Gemini Web** (gemini.google.com)
+2. **Upload your project**:
+   - **Option A**: Paste your GitHub repository URL directly
+   - **Option B**: Upload up to 1000 files from your src/project folder
+   - **Option C**: Zip your project and upload the archive
+3. **Load the analyst agent**: Upload `dist/agents/analyst.txt`
+4. **Run documentation**: Type `*document-project`
+
+The analyst will generate comprehensive documentation of everything.
+
+#### Phase 2: Plan Your Enhancement
+
+#### Option A: Full Brownfield Workflow (Recommended for Major Changes)
+
+**1. Create Brownfield PRD**:
+
+```bash
+@pm
+*create-doc brownfield-prd
+```
+
+The PM agent will:
+
+- **Analyze existing documentation** from Phase 1
+- **Request specific enhancement details** from you
+- **Assess complexity** and recommend approach
+- **Create epic/story structure** for the enhancement
+- **Identify risks and integration points**
+
+**How PM Agent Gets Project Context**:
+
+- In Gemini Web: Already has full project context from Phase 1 documentation
+- In IDE: Will ask "Please provide the path to your existing project documentation"
+
+**Key Prompts You'll Encounter**:
+
+- "What specific enhancement or feature do you want to add?"
+- "Are there any existing systems or APIs this needs to integrate with?"
+- "What are the critical constraints we must respect?"
+- "What is your timeline and team size?"
+
+**2. Create Brownfield Architecture**:
+
+```bash
+@architect
+*create-doc brownfield-architecture
+```
+
+The architect will:
+
+- **Review the brownfield PRD**
+- **Design integration strategy**
+- **Plan migration approach** if needed
+- **Identify technical risks**
+- **Define compatibility requirements**
+
+#### Option B: Quick Enhancement (For Focused Changes)
+
+**For Single Epic Without Full PRD**:
+
+```bash
+@pm
+*brownfield-create-epic
+```
+
+Use when:
+
+- Enhancement is well-defined and isolated
+- Existing documentation is comprehensive
+- Changes don't impact multiple systems
+- You need quick turnaround
+
+**For Single Story**:
+
+```bash
+@pm
+*brownfield-create-story
+```
+
+Use when:
+
+- Bug fix or tiny feature
+- Very isolated change
+- No architectural impact
+- Clear implementation path
+
+### Phase 3: Validate Planning Artifacts
+
+```bash
+@po
+*execute-checklist po-master-checklist
+```
+
+The PO ensures:
+
+- Compatibility with existing system
+- No breaking changes planned
+- Risk mitigation strategies in place
+- Clear integration approach
+
+### Phase 4: Transition to Development
+
+Follow the enhanced IDE Development Workflow:
+
+1. **Ensure documents are in project**:
+
+   - Copy `docs/prd.md` (or brownfield-prd.md)
+   - Copy `docs/architecture.md` (or brownfield-architecture.md)
+
+2. **Shard documents**:
+
+   ```bash
+   @po
+   # Ask to shard docs/prd.md
+   ```
+
+3. **Development cycle**:
+   - **SM** creates stories with integration awareness
+   - **Dev** implements with existing code respect
+   - **QA** reviews for compatibility and improvements
+
+## Brownfield Best Practices
+
+### 1. Always Document First
+
+Even if you think you know the codebase:
+
+- Run `document-project` to capture current state
+- AI agents need this context
+- Discovers undocumented patterns
+
+### 2. Respect Existing Patterns
+
+The brownfield templates specifically look for:
+
+- Current coding conventions
+- Existing architectural patterns
+- Technology constraints
+- Team preferences
+
+### 3. Plan for Gradual Rollout
+
+Brownfield changes should:
+
+- Support feature flags
+- Plan rollback strategies
+- Include migration scripts
+- Maintain backwards compatibility
+
+### 4. Test Integration Thoroughly
+
+Focus testing on:
+
+- Integration points
+- Existing functionality (regression)
+- Performance impact
+- Data migrations
+
+### 5. Communicate Changes
+
+Document:
+
+- What changed and why
+- Migration instructions
+- New patterns introduced
+- Deprecation notices
+
+## Common Brownfield Scenarios
+
+### Scenario 1: Adding a New Feature
+
+1. Document existing system
+2. Create brownfield PRD focusing on integration
+3. Architecture emphasizes compatibility
+4. Stories include integration tasks
+
+### Scenario 2: Modernizing Legacy Code
+
+1. Extensive documentation phase
+2. PRD includes migration strategy
+3. Architecture plans gradual transition
+4. Stories follow strangler fig pattern
+
+### Scenario 3: Bug Fix in Complex System
+
+1. Document relevant subsystems
+2. Use `brownfield-create-story` for focused fix
+3. Include regression test requirements
+4. QA validates no side effects
+
+### Scenario 4: API Integration
+
+1. Document existing API patterns
+2. PRD defines integration requirements
+3. Architecture ensures consistent patterns
+4. Stories include API documentation updates
+
+## Troubleshooting
+
+### "The AI doesn't understand my codebase"
+
+**Solution**: Re-run `document-project` with more specific paths to critical files
+
+### "Generated plans don't fit our patterns"
+
+**Solution**: Update generated documentation with your specific conventions before planning phase
+
+### "Too much boilerplate for small changes"
+
+**Solution**: Use `brownfield-create-story` instead of full workflow
+
+### "Integration points unclear"
+
+**Solution**: Provide more context during PRD creation, specifically highlighting integration systems
+
+## Quick Reference
+
+### Brownfield-Specific Commands
+
+```bash
+# Document existing project
+@analyst → *document-project
+
+# Create enhancement PRD
+@pm → *create-doc brownfield-prd
+
+# Create architecture with integration focus
+@architect → *create-doc brownfield-architecture
+
+# Quick epic creation
+@pm → *brownfield-create-epic
+
+# Single story creation
+@pm → *brownfield-create-story
+```
+
+### Decision Tree
+
+```text
+Do you have a large codebase or monorepo?
+├─ Yes → PRD-First Approach
+│   └─ Create PRD → Document only affected areas
+└─ No → Is the codebase well-known to you?
+    ├─ Yes → PRD-First Approach
+    └─ No → Document-First Approach
+
+Is this a major enhancement affecting multiple systems?
+├─ Yes → Full Brownfield Workflow
+└─ No → Is this more than a simple bug fix?
+    ├─ Yes → brownfield-create-epic
+    └─ No → brownfield-create-story
+```
+
+## 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.
+
+Remember: **Document First, Plan Carefully, Integrate Safely**
--- a/expansion-packs/bmad-2d-phaser-game-dev/agent-teams/phaser-2d-nodejs-game-team.yml
+++ b/expansion-packs/bmad-2d-phaser-game-dev/agent-teams/phaser-2d-nodejs-game-team.yml
@@ -3,6 +3,7 @@ bundle:
  icon: 🎮
  description: Game Development team specialized in 2D games using Phaser 3 and TypeScript.
 agents:
+  - analyst
  - bmad-orchestrator
  - game-designer
  - game-developer
--- a/expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.md
+++ b/expansion-packs/bmad-2d-phaser-game-dev/agents/game-developer.md
@@ -48,10 +48,10 @@ commands:
 task-execution:
  flow: Read story → Implement game feature → Write tests → Pass tests → Update [x] → Next task
  updates-ONLY:
-    - 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
-    - 'Debug Log: | Task | File | Change | Reverted? |'
-    - 'Completion Notes: Deviations only, <50 words'
-    - 'Change Log: Requirement changes only'
+    - "Checkboxes: [ ] not started | [-] in progress | [x] complete"
+    - "Debug Log: | Task | File | Change | Reverted? |"
+    - "Completion Notes: Deviations only, <50 words"
+    - "Change Log: Requirement changes only"
  blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing game config
  done: Game feature works + Tests pass + 60 FPS + No lint errors + Follows Phaser 3 best practices
 dependencies:
--- a/expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.md
+++ b/expansion-packs/bmad-2d-phaser-game-dev/agents/game-sm.md
@@ -33,7 +33,7 @@ startup:
  - CRITICAL: Do NOT create or modify any files during startup
  - Offer to help with game story preparation but wait for explicit user confirmation
  - Only execute tasks when user explicitly requests them
-  - 'CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Game Developer Agent'
+  - "CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Game Developer Agent"
 commands:
  - '*help" - Show numbered list of available commands for selection'
  - '*chat-mode" - Conversational mode with advanced-elicitation for game dev advice'
--- a/expansion-packs/bmad-2d-phaser-game-dev/checklists/game-design-checklist.md
+++ b/expansion-packs/bmad-2d-phaser-game-dev/checklists/game-design-checklist.md
@@ -3,6 +3,7 @@
 ## Document Completeness

 ### Executive Summary
+
 - [ ] **Core Concept** - Game concept is clearly explained in 2-3 sentences
 - [ ] **Target Audience** - Primary and secondary audiences defined with demographics
 - [ ] **Platform Requirements** - Technical platforms and requirements specified
@@ -10,6 +11,7 @@
 - [ ] **Technical Foundation** - Phaser 3 + TypeScript requirements confirmed

 ### Game Design Foundation
+
 - [ ] **Game Pillars** - 3-5 core design pillars defined and actionable
 - [ ] **Core Gameplay Loop** - 30-60 second loop documented with specific timings
 - [ ] **Win/Loss Conditions** - Clear victory and failure states defined
@@ -19,6 +21,7 @@
 ## Gameplay Mechanics

 ### Core Mechanics Documentation
+
 - [ ] **Primary Mechanics** - 3-5 core mechanics detailed with implementation notes
 - [ ] **Mechanic Integration** - How mechanics work together is clear
 - [ ] **Player Input** - All input methods specified for each platform
@@ -26,6 +29,7 @@
 - [ ] **Performance Impact** - Performance considerations for each mechanic noted

 ### Controls and Interaction
+
 - [ ] **Multi-Platform Controls** - Desktop, mobile, and gamepad controls defined
 - [ ] **Input Responsiveness** - Requirements for responsive game feel specified
 - [ ] **Accessibility Options** - Control customization and accessibility considered
@@ -35,6 +39,7 @@
 ## Progression and Balance

 ### Player Progression
+
 - [ ] **Progression Type** - Linear, branching, or metroidvania approach defined
 - [ ] **Key Milestones** - Major progression points documented
 - [ ] **Unlock System** - What players unlock and when is specified
@@ -42,6 +47,7 @@
 - [ ] **Player Agency** - Meaningful player choices and consequences defined

 ### Game Balance
+
 - [ ] **Balance Parameters** - Numeric values for key game systems provided
 - [ ] **Difficulty Curve** - Appropriate challenge progression designed
 - [ ] **Economy Design** - Resource systems balanced for engagement
@@ -51,6 +57,7 @@
 ## Level Design Framework

 ### Level Structure
+
 - [ ] **Level Types** - Different level categories defined with purposes
 - [ ] **Level Progression** - How players move through levels specified
 - [ ] **Duration Targets** - Expected play time for each level type
@@ -58,6 +65,7 @@
 - [ ] **Replay Value** - Elements that encourage repeated play designed

 ### Content Guidelines
+
 - [ ] **Level Creation Rules** - Clear guidelines for level designers
 - [ ] **Mechanic Introduction** - How new mechanics are taught in levels
 - [ ] **Pacing Variety** - Mix of action, puzzle, and rest moments planned
@@ -67,6 +75,7 @@
 ## Technical Implementation Readiness

 ### Performance Requirements
+
 - [ ] **Frame Rate Targets** - 60 FPS target with minimum acceptable rates
 - [ ] **Memory Budgets** - Maximum memory usage limits defined
 - [ ] **Load Time Goals** - Acceptable loading times for different content
@@ -74,6 +83,7 @@
 - [ ] **Scalability Plan** - How performance scales across different devices

 ### Platform Specifications
+
 - [ ] **Desktop Requirements** - Minimum and recommended PC/Mac specs
 - [ ] **Mobile Optimization** - iOS and Android specific requirements
 - [ ] **Browser Compatibility** - Supported browsers and versions listed
@@ -81,6 +91,7 @@
 - [ ] **Update Strategy** - Plan for post-launch updates and patches

 ### Asset Requirements
+
 - [ ] **Art Style Definition** - Clear visual style with reference materials
 - [ ] **Asset Specifications** - Technical requirements for all asset types
 - [ ] **Audio Requirements** - Music and sound effect specifications
@@ -90,6 +101,7 @@
 ## Development Planning

 ### Implementation Phases
+
 - [ ] **Phase Breakdown** - Development divided into logical phases
 - [ ] **Epic Definitions** - Major development epics identified
 - [ ] **Dependency Mapping** - Prerequisites between features documented
@@ -97,6 +109,7 @@
 - [ ] **Milestone Planning** - Key deliverables and deadlines established

 ### Team Requirements
+
 - [ ] **Role Definitions** - Required team roles and responsibilities
 - [ ] **Skill Requirements** - Technical skills needed for implementation
 - [ ] **Resource Allocation** - Time and effort estimates for major features
@@ -106,6 +119,7 @@
 ## Quality Assurance

 ### Success Metrics
+
 - [ ] **Technical Metrics** - Measurable technical performance goals
 - [ ] **Gameplay Metrics** - Player engagement and retention targets
 - [ ] **Quality Benchmarks** - Standards for bug rates and polish level
@@ -113,6 +127,7 @@
 - [ ] **Business Objectives** - Commercial or project success criteria

 ### Testing Strategy
+
 - [ ] **Playtesting Plan** - How and when player feedback will be gathered
 - [ ] **Technical Testing** - Performance and compatibility testing approach
 - [ ] **Balance Validation** - Methods for confirming game balance
@@ -122,6 +137,7 @@
 ## Documentation Quality

 ### Clarity and Completeness
+
 - [ ] **Clear Writing** - All sections are well-written and understandable
 - [ ] **Complete Coverage** - No major game systems left undefined
 - [ ] **Actionable Detail** - Enough detail for developers to create implementation stories
@@ -129,6 +145,7 @@
 - [ ] **Reference Materials** - Links to inspiration, research, and additional resources

 ### Maintainability
+
 - [ ] **Version Control** - Change log established for tracking revisions
 - [ ] **Update Process** - Plan for maintaining document during development
 - [ ] **Team Access** - All team members can access and reference the document
@@ -138,6 +155,7 @@
 ## Stakeholder Alignment

 ### Team Understanding
+
 - [ ] **Shared Vision** - All team members understand and agree with the game vision
 - [ ] **Role Clarity** - Each team member understands their contribution
 - [ ] **Decision Framework** - Process for making design decisions during development
@@ -145,6 +163,7 @@
 - [ ] **Communication Channels** - Regular meetings and feedback sessions planned

 ### External Validation
+
 - [ ] **Market Validation** - Competitive analysis and market fit assessment
 - [ ] **Technical Validation** - Feasibility confirmed with technical team
 - [ ] **Resource Validation** - Required resources available and committed
@@ -154,6 +173,7 @@
 ## Final Readiness Assessment

 ### Implementation Preparedness
+
 - [ ] **Story Creation Ready** - Document provides sufficient detail for story creation
 - [ ] **Architecture Alignment** - Game design aligns with technical capabilities
 - [ ] **Asset Production** - Asset requirements enable art and audio production
@@ -161,6 +181,7 @@
 - [ ] **Quality Assurance** - Testing and validation processes established

 ### Document Approval
+
 - [ ] **Design Review Complete** - Document reviewed by all relevant stakeholders
 - [ ] **Technical Review Complete** - Technical feasibility confirmed
 - [ ] **Business Review Complete** - Project scope and goals approved
--- a/expansion-packs/bmad-2d-phaser-game-dev/checklists/game-story-dod-checklist.md
+++ b/expansion-packs/bmad-2d-phaser-game-dev/checklists/game-story-dod-checklist.md
@@ -3,6 +3,7 @@
 ## Story Completeness

 ### Basic Story Elements
+
 - [ ] **Story Title** - Clear, descriptive title that identifies the feature
 - [ ] **Epic Assignment** - Story is properly assigned to relevant epic
 - [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -10,6 +11,7 @@
 - [ ] **Description** - Clear, concise description of what needs to be implemented

 ### Game Design Alignment
+
 - [ ] **GDD Reference** - Specific Game Design Document section referenced
 - [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
 - [ ] **Player Experience Goal** - Describes the intended player experience
@@ -19,6 +21,7 @@
 ## Technical Specifications

 ### Architecture Compliance
+
 - [ ] **File Organization** - Follows game architecture document structure
 - [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
 - [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -26,6 +29,7 @@
 - [ ] **Dependencies** - All system dependencies clearly identified

 ### Phaser 3 Requirements
+
 - [ ] **Scene Integration** - Specifies which scenes are affected and how
 - [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
 - [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -33,6 +37,7 @@
 - [ ] **Performance Considerations** - 60 FPS target and optimization requirements

 ### Code Quality Standards
+
 - [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
 - [ ] **Error Handling** - Error scenarios and handling requirements specified
 - [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -42,6 +47,7 @@
 ## Implementation Readiness

 ### Acceptance Criteria
+
 - [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
 - [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
 - [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -49,6 +55,7 @@
 - [ ] **Completeness** - No acceptance criteria are vague or unmeasurable

 ### Implementation Tasks
+
 - [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
 - [ ] **Task Scope** - Each task is completable in 1-4 hours
 - [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -56,6 +63,7 @@
 - [ ] **Development Flow** - Tasks follow logical implementation order

 ### Dependencies
+
 - [ ] **Story Dependencies** - All prerequisite stories identified with IDs
 - [ ] **Technical Dependencies** - Required systems and files identified
 - [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -65,6 +73,7 @@
 ## Testing Requirements

 ### Test Coverage
+
 - [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
 - [ ] **Integration Test Cases** - Integration testing with other game systems specified
 - [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -72,6 +81,7 @@
 - [ ] **Edge Case Testing** - Edge cases and error conditions covered

 ### Test Implementation
+
 - [ ] **Test File Paths** - Exact test file locations specified
 - [ ] **Test Scenarios** - All test scenarios are complete and executable
 - [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -81,6 +91,7 @@
 ## Game-Specific Quality

 ### Gameplay Implementation
+
 - [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
 - [ ] **Player Controls** - Input handling requirements are complete
 - [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -88,6 +99,7 @@
 - [ ] **State Management** - Game state changes and persistence requirements defined

 ### User Experience
+
 - [ ] **UI Requirements** - User interface elements and behaviors specified
 - [ ] **Audio Integration** - Sound effect and music requirements defined
 - [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -95,6 +107,7 @@
 - [ ] **Error Recovery** - User-facing error handling and recovery specified

 ### Performance Optimization
+
 - [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
 - [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
 - [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -104,6 +117,7 @@
 ## Documentation and Communication

 ### Story Documentation
+
 - [ ] **Implementation Notes** - Additional context and implementation guidance provided
 - [ ] **Design Decisions** - Key design choices documented with rationale
 - [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -111,6 +125,7 @@
 - [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs

 ### Developer Handoff
+
 - [ ] **Immediate Actionability** - Developer can start implementation without additional questions
 - [ ] **Complete Context** - All necessary context provided within the story
 - [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -120,6 +135,7 @@
 ## Final Validation

 ### Story Readiness
+
 - [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
 - [ ] **Technical Completeness** - All technical requirements are specified and actionable
 - [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -127,6 +143,7 @@
 - [ ] **Review Completion** - Story has been reviewed for completeness and accuracy

 ### Implementation Preparedness
+
 - [ ] **Environment Ready** - Development environment requirements specified
 - [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
 - [ ] **Testing Prepared** - Testing environment and data requirements specified
--- a/Show More
+++ b/Show More