chore(release): 4.24.1 [skip ci]

## [4.24.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.0...v4.24.1) (2025-07-03)

### Bug Fixes

* centralized yamlExtraction function and all now fix character issues for windows ([e2985d6](e2985d6093))
* filtering extension stripping logic update ([405954a](405954ad92))
* standardize on file extension .yaml instead of a mix of yml and yaml ([a4c0b18](a4c0b1839d))

.vscode/settings.json

@@ -1,4 +1,10 @@
 {
+  "chat.agent.enabled": true,
+  "chat.agent.maxRequests": 15,
+  "github.copilot.chat.agent.runTasks": true,
+  "chat.mcp.discovery.enabled": true,
+  "github.copilot.chat.agent.autoFix": true,
+  "chat.tools.autoApprove": false,
   "cSpell.words": [
     "Agentic",
     "elicitations",

CHANGELOG.md

@@ -1,3 +1,24 @@
+## [4.24.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.24.0...v4.24.1) (2025-07-03)
+
+
+### Bug Fixes
+
+* centralized yamlExtraction function and all now fix character issues for windows ([e2985d6](https://github.com/bmadcode/BMAD-METHOD/commit/e2985d6093136575e8d8c91ce53c82abc4097de6))
+* filtering extension stripping logic update ([405954a](https://github.com/bmadcode/BMAD-METHOD/commit/405954ad924d8bd66f94c918643f6e9c091d4d09))
+* standardize on file extension .yaml instead of a mix of yml and yaml ([a4c0b18](https://github.com/bmadcode/BMAD-METHOD/commit/a4c0b1839d12d2ad21b7949aa30f4f7d82ec6c9c))
+
+# [4.24.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.23.0...v4.24.0) (2025-07-02)
+
+
+### Bug Fixes
+
+* corrected cursor agent update instructions ([84e394a](https://github.com/bmadcode/BMAD-METHOD/commit/84e394ac11136d9cf8164cefc9ca8e298e8ef0ec))
+
+
+### Features
+
+* workflow plans introduced, preliminary feature under review ([731589a](https://github.com/bmadcode/BMAD-METHOD/commit/731589aa287c31ea120e232b4dcc07e9790500ff))
+
 # [4.23.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.22.1...v4.23.0) (2025-07-01)
 
 
@@ -201,7 +222,7 @@
 
 ### Features
 
-* dev can use debug log configured in core-config.yml ([0e5aaf0](https://github.com/bmadcode/BMAD-METHOD/commit/0e5aaf07bbc6fd9f2706ea26e35f5f38fd72147a))
+* dev can use debug log configured in core-config.yaml ([0e5aaf0](https://github.com/bmadcode/BMAD-METHOD/commit/0e5aaf07bbc6fd9f2706ea26e35f5f38fd72147a))
 
 # [4.8.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.7.0...v4.8.0) (2025-06-19)
 

README.md

@@ -234,7 +234,7 @@ After uploading a bundle, type `/help` to see available commands.
 - **[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
+- **[Core Configuration](docs/user-guide.md#core-configuration)** - V4's flexible project structure support
 - **[Teams & Workflows](docs/user-guide.md#team-configurations)** - Pre-configured agent teams
 
 ## Project Structure
@@ -294,7 +294,7 @@ See the **[Core Architecture](docs/core-architecture.md)** for the complete sour
 
 ## 🌟 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.
+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
 

bmad-core/agents/bmad-master.md

@@ -2,7 +2,7 @@
 
 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
+```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.
@@ -26,6 +26,9 @@ persona:
     - Process (*) commands immediately
 startup:
   - Greet the user with your name and role, and inform of the *help command.
+  - Check for active workflow plan using utils#plan-management
+  - "If plan exists: Show brief status - Active plan detected: {workflow} - {progress}%"
+  - "If plan exists: Suggest next step based on plan"
   - CRITICAL: Do NOT scan filesystem or load any resources during startup
   - CRITICAL: Do NOT run discovery tasks automatically
   - Wait for user request before any tool use
@@ -37,16 +40,24 @@ commands:  # All commands require * prefix when used (e.g., *help)
   - status: Current context
   - task {template|util|checklist|workflow}: Execute
   - list {task|template|util|checklist|workflow}: List resources by type
+  - plan: Create workflow plan (for complex projects)
+  - plan-status: Show current workflow plan progress
+  - plan-update: Update workflow plan status
   - exit: Exit (confirm)
   - yolo: Toggle Yolo Mode off on - on will skip doc section confirmations
   - doc-out: Output full document
 fuzzy-matching:
   - 85% confidence threshold
   - Show numbered list if unsure
+workflow-guidance:
+  - When user asks about workflows, offer: "Would you like me to create a workflow plan first? (*plan)"
+  - For complex projects, suggest planning before execution
+  - Plan command maps to create-workflow-plan task
 execution:
   - NEVER use tools during startup - only announce and wait
   - Runtime discovery ONLY when user requests specific resources
   - Workflow: User request → Runtime discovery → Load resource → Execute instructions → Guide inputs → Provide feedback
+  - For workflow requests: Suggest *plan command first for complex projects
   - Suggest related resources after completion
 dependencies:
   tasks:
@@ -58,12 +69,14 @@ dependencies:
     - correct-course
     - create-deep-research-prompt
     - create-doc
+    - create-workflow-plan
     - document-project
     - create-next-story
     - execute-checklist
     - generate-ai-frontend-prompt
     - index-docs
     - shard-doc
+    - update-workflow-plan
   templates:
     - agent-tmpl
     - architecture-tmpl
@@ -81,7 +94,7 @@ dependencies:
     - bmad-kb
     - technical-preferences
   utils:
-    - agent-switcher.ide
+    - plan-management
     - template-format
     - workflow-management
   workflows:

bmad-core/agents/bmad-orchestrator.md

@@ -31,6 +31,9 @@ startup:
   - Announce: Introduce yourself as the BMAD Orchestrator, explain you can coordinate agents and workflows
   - IMPORTANT: Tell users that all commands start with * (e.g., *help, *agent, *workflow)
   - Mention *help shows all available commands and options
+  - Check for active workflow plan using utils#plan-management
+  - "If plan exists: Show 📋 Active plan: {workflow} ({progress}% complete). Use *plan-status for details."
+  - "If plan exists: Suggest next action based on plan progress"
   - Assess user goal against available agents and workflows in this bundle
   - If clear match to an agent's expertise, suggest transformation with *agent command
   - If project-oriented, suggest *workflow-guidance to explore options
@@ -45,6 +48,9 @@ commands:  # All commands require * prefix when used (e.g., *help, *agent pm)
   task: Run a specific task (list if name not specified)
   workflow: Start a specific workflow (list if name not specified)
   workflow-guidance: Get personalized help selecting the right workflow
+  plan: Create detailed workflow plan before starting
+  plan-status: Show current workflow plan progress
+  plan-update: Update workflow plan status
   checklist: Execute a checklist (list if name not specified)
   yolo: Toggle skip confirmations mode
   party-mode: Group chat with all agents
@@ -68,6 +74,9 @@ help-display-template: |
   Workflow Commands:
   *workflow [name] .... Start specific workflow (list if no name)
   *workflow-guidance .. Get personalized help selecting the right workflow
+  *plan ............... Create detailed workflow plan before starting
+  *plan-status ........ Show current workflow plan progress
+  *plan-update ........ Update workflow plan status
   
   Other Commands:
   *yolo ............... Toggle skip confirmations mode
@@ -109,6 +118,8 @@ workflow-guidance:
   - Understand each workflow's purpose, options, and decision points
   - Ask clarifying questions based on the workflow's structure
   - Guide users through workflow selection when multiple options exist
+  - For complex projects, offer to create a workflow plan using create-workflow-plan task
+  - When appropriate, suggest: "Would you like me to create a detailed workflow plan before starting?"
   - For workflows with divergent paths, help users choose the right path
   - Adapt questions to the specific domain (e.g., game dev vs infrastructure vs web dev)
   - Only recommend workflows that actually exist in the current bundle
@@ -117,10 +128,13 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - create-workflow-plan
     - kb-mode-interaction
+    - update-workflow-plan
   data:
     - bmad-kb
   utils:
+    - plan-management
     - workflow-management
     - template-format
 ```

bmad-core/agents/dev.md

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

bmad-core/agents/pm.md

@@ -2,7 +2,7 @@
 
 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
 root: .bmad-core
 IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.

bmad-core/agents/po.md

@@ -2,7 +2,7 @@
 
 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
 root: .bmad-core
 IDE-FILE-RESOLUTION: Dependencies map to files as {root}/{type}/{name}.md where root=".bmad-core", type=folder (tasks/templates/checklists/utils), name=dependency name.
 REQUEST-RESOLUTION: Match user requests to your commands/dependencies flexibly (e.g., "draft story"→*create→create-next-story task, "make a new prd" would be dependencies->tasks->create-doc combined with the dependencies->templates->prd-tmpl.md), or ask for clarification if ambiguous.

bmad-core/core-config.yaml

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

bmad-core/data/bmad-kb.md

@@ -161,11 +161,11 @@ npx bmad-method install
 5. **MUST switch to Dev agent** for implementation
 6. Keep planning and coding in separate chat sessions
 
-## Core Configuration (core-config.yml)
+## Core Configuration (core-config.yaml)
 
-**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+**New in V4**: The `bmad-core/core-config.yaml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
 
-### What is core-config.yml?
+### What is core-config.yaml?
 
 This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
 
@@ -337,7 +337,7 @@ The BMAD-Method is built around a modular architecture centered on the `bmad-cor
 
 #### 2. Agent Teams (`bmad-core/agent-teams/`)
 - **Purpose**: Define collections of agents bundled together for specific purposes
-- **Examples**: `team-all.yml` (comprehensive bundle), `team-fullstack.yml` (full-stack development)
+- **Examples**: `team-all.yaml` (comprehensive bundle), `team-fullstack.yaml` (full-stack development)
 - **Usage**: Creates pre-packaged contexts for web UI environments
 
 #### 3. Workflows (`bmad-core/workflows/`)

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

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

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

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

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

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

bmad-core/tasks/shard-doc.md

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

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

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

bmad-core/templates/architecture-tmpl.md

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

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

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

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

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

bmad-core/utils/plan-management.md

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

bmad-core/workflows/brownfield-fullstack.yaml

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

bmad-core/workflows/brownfield-fullstack.yml

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

bmad-core/workflows/brownfield-service.yaml

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

bmad-core/workflows/brownfield-service.yml

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

bmad-core/workflows/brownfield-ui.yaml

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

bmad-core/workflows/greenfield-fullstack.yaml

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

bmad-core/workflows/greenfield-service.yaml

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

bmad-core/workflows/greenfield-ui.yaml

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

common/tasks/create-doc.md

@@ -13,11 +13,22 @@ Generate documents from templates by EXECUTING (not just reading) embedded instr
 
 ## Execution Flow
 
+### 0. Check Workflow Plan (if configured)
+
+[[LLM: Check if plan tracking is enabled in core-config.yaml]]
+
+- If `workflow.trackProgress: true`, check for active plan using utils#plan-management
+- If plan exists and this document creation is part of the plan:
+  - Verify this is the expected next step
+  - If out of sequence and `enforceSequence: true`, warn user and halt without user override
+  - If out of sequence and `enforceSequence: false`, ask for confirmation
+- Continue with normal execution after plan check
+
 ### 1. Identify Template
 
 - Load from `templates#*` or `{root}/templates directory`
 - Agent-specific templates are listed in agent's dependencies
-- If agent has `templates: [prd-tmpl, architecture-tmpl]`, offer to create "PRD" and "Architecture" documents
+- If agent has `templates: [prd-tmpl, architecture-tmpl]` for example, then offer to create "PRD" and "Architecture" documents
 
 ### 2. Ask Interaction Mode
 
@@ -54,6 +65,15 @@ Generate documents from templates by EXECUTING (not just reading) embedded instr
 - Begin directly with content (no preamble)
 - Include any handoff prompts from template
 
+### 6. Update Workflow Plan (if applicable)
+
+[[LLM: After successful document creation]]
+
+- If plan tracking is enabled and document was part of plan:
+  - Call update-workflow-plan task to mark step complete
+  - Parameters: task: create-doc, step_id: {from plan}, status: complete
+  - Show next recommended step from plan
+
 ## Common Mistakes to Avoid
 
 ❌ Skipping elicitation tasks

dist/agents/dev.txt

@@ -1,298 +0,0 @@
-# Web Agent Bundle Instructions
-
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
-
-## Important Instructions
-
-1. **Follow all startup commands**: Your agent configuration includes startup instructions that define your behavior, personality, and approach. These MUST be followed exactly.
-
-2. **Resource Navigation**: This bundle contains all resources you need. Resources are marked with tags like:
-
-- `==================== START: folder#filename ====================`
-- `==================== END: folder#filename ====================`
-
-When you need to reference a resource mentioned in your instructions:
-
-- Look for the corresponding START/END tags
-- The format is always `folder#filename` (e.g., `personas#analyst`, `tasks#create-story`)
-- If a section is specified (e.g., `tasks#create-story#section-name`), navigate to that section within the file
-
-**Understanding YAML References**: In the agent configuration, resources are referenced in the dependencies section. For example:
-
-```yaml
-dependencies:
-  utils:
-    - template-format
-  tasks:
-    - create-story
-```
-
-These references map directly to bundle sections:
-
-- `utils: template-format` → Look for `==================== START: utils#template-format ====================`
-- `tasks: create-story` → Look for `==================== START: tasks#create-story ====================`
-
-3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
-
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
-
----
-
-==================== START: agents#dev ====================
-# dev
-
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```yaml
-agent:
-  name: James
-  id: dev
-  title: Full Stack Developer
-  icon: 💻
-  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: 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
-  - 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 loaded standards
-  - Numbered Options - Always use numbered lists when presenting choices
-commands:
-  - 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→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 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
-  checklists:
-    - story-dod-checklist
-```
-==================== END: agents#dev ====================
-
-==================== 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: checklists#story-dod-checklist ====================
-# Story Definition of Done (DoD) Checklist
-
-## Instructions for Developer Agent
-
-Before marking a story as 'Review', please go through each item in this checklist. Report the status of each item (e.g., [x] Done, [ ] Not Done, [N/A] Not Applicable) and provide brief comments if necessary.
-
-[[LLM: INITIALIZATION INSTRUCTIONS - STORY DOD VALIDATION
-
-This checklist is for DEVELOPER AGENTS to self-validate their work before marking a story complete.
-
-IMPORTANT: This is a self-assessment. Be honest about what's actually done vs what should be done. It's better to identify issues now than have them found in review.
-
-EXECUTION APPROACH:
-
-1. Go through each section systematically
-2. Mark items as [x] Done, [ ] Not Done, or [N/A] Not Applicable
-3. Add brief comments explaining any [ ] or [N/A] items
-4. Be specific about what was actually implemented
-5. Flag any concerns or technical debt created
-
-The goal is quality delivery, not just checking boxes.]]
-
-## Checklist Items
-
-1. **Requirements Met:**
-
-   [[LLM: Be specific - list each requirement and whether it's complete]]
-
-   - [ ] All functional requirements specified in the story are implemented.
-   - [ ] All acceptance criteria defined in the story are met.
-
-2. **Coding Standards & Project Structure:**
-
-   [[LLM: Code quality matters for maintainability. Check each item carefully]]
-
-   - [ ] All new/modified code strictly adheres to `Operational Guidelines`.
-   - [ ] All new/modified code aligns with `Project Structure` (file locations, naming, etc.).
-   - [ ] Adherence to `Tech Stack` for technologies/versions used (if story introduces or modifies tech usage).
-   - [ ] Adherence to `Api Reference` and `Data Models` (if story involves API or data model changes).
-   - [ ] Basic security best practices (e.g., input validation, proper error handling, no hardcoded secrets) applied for new/modified code.
-   - [ ] No new linter errors or warnings introduced.
-   - [ ] Code is well-commented where necessary (clarifying complex logic, not obvious statements).
-
-3. **Testing:**
-
-   [[LLM: Testing proves your code works. Be honest about test coverage]]
-
-   - [ ] All required unit tests as per the story and `Operational Guidelines` Testing Strategy are implemented.
-   - [ ] All required integration tests (if applicable) as per the story and `Operational Guidelines` Testing Strategy are implemented.
-   - [ ] All tests (unit, integration, E2E if applicable) pass successfully.
-   - [ ] Test coverage meets project standards (if defined).
-
-4. **Functionality & Verification:**
-
-   [[LLM: Did you actually run and test your code? Be specific about what you tested]]
-
-   - [ ] Functionality has been manually verified by the developer (e.g., running the app locally, checking UI, testing API endpoints).
-   - [ ] Edge cases and potential error conditions considered and handled gracefully.
-
-5. **Story Administration:**
-
-   [[LLM: Documentation helps the next developer. What should they know?]]
-
-   - [ ] All tasks within the story file are marked as complete.
-   - [ ] Any clarifications or decisions made during development are documented in the story file or linked appropriately.
-   - [ ] The story wrap up section has been completed with notes of changes or information relevant to the next story or overall project, the agent model that was primarily used during development, and the changelog of any changes is properly updated.
-
-6. **Dependencies, Build & Configuration:**
-
-   [[LLM: Build issues block everyone. Ensure everything compiles and runs cleanly]]
-
-   - [ ] Project builds successfully without errors.
-   - [ ] Project linting passes
-   - [ ] Any new dependencies added were either pre-approved in the story requirements OR explicitly approved by the user during development (approval documented in story file).
-   - [ ] If new dependencies were added, they are recorded in the appropriate project files (e.g., `package.json`, `requirements.txt`) with justification.
-   - [ ] No known security vulnerabilities introduced by newly added and approved dependencies.
-   - [ ] If new environment variables or configurations were introduced by the story, they are documented and handled securely.
-
-7. **Documentation (If Applicable):**
-
-   [[LLM: Good documentation prevents future confusion. What needs explaining?]]
-
-   - [ ] Relevant inline code documentation (e.g., JSDoc, TSDoc, Python docstrings) for new public APIs or complex logic is complete.
-   - [ ] User-facing documentation updated, if changes impact users.
-   - [ ] Technical documentation (e.g., READMEs, system diagrams) updated if significant architectural changes were made.
-
-## Final Confirmation
-
-[[LLM: FINAL DOD SUMMARY
-
-After completing the checklist:
-
-1. Summarize what was accomplished in this story
-2. List any items marked as [ ] Not Done with explanations
-3. Identify any technical debt or follow-up work needed
-4. Note any challenges or learnings for future stories
-5. Confirm whether the story is truly ready for review
-
-Be honest - it's better to flag issues now than have them discovered later.]]
-
-- [ ] I, the Developer Agent, confirm that all applicable items above have been addressed.
-==================== END: checklists#story-dod-checklist ====================

dist/agents/qa.txt

@@ -1,262 +0,0 @@
-# Web Agent Bundle Instructions
-
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
-
-## Important Instructions
-
-1. **Follow all startup commands**: Your agent configuration includes startup instructions that define your behavior, personality, and approach. These MUST be followed exactly.
-
-2. **Resource Navigation**: This bundle contains all resources you need. Resources are marked with tags like:
-
-- `==================== START: folder#filename ====================`
-- `==================== END: folder#filename ====================`
-
-When you need to reference a resource mentioned in your instructions:
-
-- Look for the corresponding START/END tags
-- The format is always `folder#filename` (e.g., `personas#analyst`, `tasks#create-story`)
-- If a section is specified (e.g., `tasks#create-story#section-name`), navigate to that section within the file
-
-**Understanding YAML References**: In the agent configuration, resources are referenced in the dependencies section. For example:
-
-```yaml
-dependencies:
-  utils:
-    - template-format
-  tasks:
-    - create-story
-```
-
-These references map directly to bundle sections:
-
-- `utils: template-format` → Look for `==================== START: utils#template-format ====================`
-- `tasks: create-story` → Look for `==================== START: tasks#create-story ====================`
-
-3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
-
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
-
----
-
-==================== START: agents#qa ====================
-# qa
-
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```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:
-  name: Quinn
-  id: qa
-  title: Senior Developer & QA Architect
-  icon: 🧪
-  whenToUse: Use for senior code review, refactoring, test planning, quality assurance, and mentoring through code improvements
-  customization: null
-persona:
-  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
-    - 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
-    - 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
-  - exit: Say goodbye as the QA Test Architect, and then abandon inhabiting this persona
-dependencies:
-  tasks:
-    - review-story
-  data:
-    - technical-preferences
-  utils:
-    - template-format
-```
-==================== 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
-
-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 ====================

dist/agents/sm.txt

@@ -1,701 +0,0 @@
-# Web Agent Bundle Instructions
-
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
-
-## Important Instructions
-
-1. **Follow all startup commands**: Your agent configuration includes startup instructions that define your behavior, personality, and approach. These MUST be followed exactly.
-
-2. **Resource Navigation**: This bundle contains all resources you need. Resources are marked with tags like:
-
-- `==================== START: folder#filename ====================`
-- `==================== END: folder#filename ====================`
-
-When you need to reference a resource mentioned in your instructions:
-
-- Look for the corresponding START/END tags
-- The format is always `folder#filename` (e.g., `personas#analyst`, `tasks#create-story`)
-- If a section is specified (e.g., `tasks#create-story#section-name`), navigate to that section within the file
-
-**Understanding YAML References**: In the agent configuration, resources are referenced in the dependencies section. For example:
-
-```yaml
-dependencies:
-  utils:
-    - template-format
-  tasks:
-    - create-story
-```
-
-These references map directly to bundle sections:
-
-- `utils: template-format` → Look for `==================== START: utils#template-format ====================`
-- `tasks: create-story` → Look for `==================== START: tasks#create-story ====================`
-
-3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
-
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
-
----
-
-==================== START: agents#sm ====================
-# sm
-
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```yaml
-activation-instructions:
-  - Follow all instructions in this file -> this defines you, your persona and more importantly what you can do. STAY IN CHARACTER!
-  - The customization field ALWAYS takes precedence over any conflicting instructions
-  - 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:
-  name: Bob
-  id: sm
-  title: Scrum Master
-  icon: 🏃
-  whenToUse: Use for story creation, epic management, retrospectives in party-mode, and agile process guidance
-  customization: null
-persona:
-  role: Technical Scrum Master - Story Preparation Specialist
-  style: Task-oriented, efficient, precise, focused on clear developer handoffs
-  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:
-    - 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 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
-commands:
-  - 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:
-    - story-draft-checklist
-  utils:
-    - template-format
-```
-==================== END: agents#sm ====================
-
-==================== START: tasks#create-next-story ====================
-# Create Next Story Task
-
-## Purpose
-
-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.
-
-## 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
-
-- 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
-
-- 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:
-
-    ```plaintext
-    ALERT: Found incomplete story:
-    File: {lastEpicNum}.{lastStoryNum}.story.md
-    Status: [current status]
-
-    Would you like to:
-    1. View the incomplete story details (instructs user to do so, agent does not display)
-    2. Cancel new story creation at this time
-    3. Accept risk & Override to create the next story in draft
-
-    Please choose an option (1/2/3):
-    ```
-
-  - 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 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 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)
-
-- 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.
-
-### 3. Review Previous Story and Extract Dev Notes
-
-[[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 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
-    - Technical decisions made during implementation
-    - Challenges encountered and solutions applied
-    - Any "lessons learned" or notes for future stories
-  - Extract relevant insights that might inform the current story's preparation
-
-### 4. Gather & Synthesize Architecture Context
-
-[[LLM: CRITICAL - You MUST gather technical details from the architecture documents. NEVER make up technical details not found in these documents.]]
-
-#### 4.1 Determine Architecture Document Strategy
-
-Based on configuration loaded in Step 0:
-
-- **If `architectureVersion: v4` and `architectureSharded: true`**:
-  - Read `{architectureShardedLocation}/index.md` to understand available documentation
-  - Follow the structured reading order in section 4.2 below
-  
-- **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:**
-
-1. `docs/architecture/tech-stack.md` - Understand technology constraints and versions
-2. `docs/architecture/unified-project-structure.md` - Know where code should be placed
-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 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:**
-
-- Read both Backend and Frontend sections above
-
-#### 4.3 Extract Story-Specific Technical Details
-
-[[LLM: As you read each document, extract ONLY the information directly relevant to implementing the current story. Do NOT include general information unless it directly impacts the story implementation.]]
-
-For each relevant document, extract:
-
-- Specific data models, schemas, or structures the story will use
-- API endpoints the story must implement or consume
-- Component specifications for UI elements in the story
-- File paths and naming conventions for new code
-- Testing requirements specific to the story's features
-- Security or performance considerations affecting the story
-
-#### 4.4 Document Source References
-
-[[LLM: ALWAYS cite the source document and section for each technical detail you include. This helps the dev agent verify information if needed.]]
-
-Format references as: `[Source: architecture/{filename}.md#{section}]`
-
-### 5. Verify Project Structure Alignment
-
-- Cross-reference the story's requirements and anticipated file manipulations with the Project Structure Guide from `docs/architecture/unified-project-structure.md`.
-- Ensure any file paths, component locations, or module names implied by the story align with defined structures.
-- Document any structural conflicts, necessary clarifications, or undefined components/paths in a "Project Structure Notes" section within the story draft.
-
-### 6. Populate Story Template with Full Context
-
-- 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}`
-  - `Status: Draft`
-  - `Story` (User Story statement from Epic)
-  - `Acceptance Criteria (ACs)` (from Epic, to be refined if needed based on context)
-- **`Dev Technical Guidance` section (CRITICAL):**
-
-  [[LLM: This section MUST contain ONLY information extracted from the architecture shards. NEVER invent or assume technical details.]]
-
-  - Include ALL relevant technical details gathered from Steps 3 and 4, organized by category:
-    - **Previous Story Insights**: Key learnings or considerations from the previous story
-    - **Data Models**: Specific schemas, validation rules, relationships [with source references]
-    - **API Specifications**: Endpoint details, request/response formats, auth requirements [with source references]
-    - **Component Specifications**: UI component details, props, state management [with source references]
-    - **File Locations**: Exact paths where new code should be created based on project structure
-    - **Testing Requirements**: Specific test cases or strategies from testing-strategy.md
-    - **Technical Constraints**: Version requirements, performance considerations, security rules
-  - Every technical detail MUST include its source reference: `[Source: architecture/{filename}.md#{section}]`
-  - If information for a category is not found in the architecture docs, explicitly state: "No specific guidance found in architecture docs"
-
-- **`Tasks / Subtasks` section:**
-  - Generate a detailed, sequential list of technical tasks based ONLY on:
-    - Requirements from the Epic
-    - Technical constraints from architecture shards
-    - Project structure from unified-project-structure.md
-    - Testing requirements from testing-strategy.md
-  - Each task must reference relevant architecture documentation
-  - Include unit testing as explicit subtasks based on testing-strategy.md
-  - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`)
-- Add notes on project structure alignment or discrepancies found in Step 5.
-- Prepare content for the "Deviation Analysis" based on any conflicts between epic requirements and architecture constraints.
-
-### 7. Run Story Draft Checklist
-
-- Execute the Story Draft Checklist against the prepared story
-- Document any issues or gaps identified
-- Make necessary adjustments to meet quality standards
-- Ensure all technical guidance is properly sourced from architecture docs
-
-### 8. Finalize Story File
-
-- Review all sections for completeness and accuracy
-- 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 `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)
-
-### 9. Report Completion
-
-Provide a summary to the user including:
-
-- Story created: `{epicNum}.{storyNum} - {Story Title}`
-- Status: Draft
-- Key technical components included from architecture docs
-- Any deviations or conflicts noted between epic and architecture
-- Recommendations for story review before approval
-- Next steps: Story should be reviewed by PO for approval before dev work begins
-
-[[LLM: Remember - The success of this task depends on extracting real, specific technical details from the architecture shards. The dev agent should have everything they need in the story file without having to search through multiple documents.]]
-==================== END: tasks#create-next-story ====================
-
-==================== 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#story-tmpl ====================
-# Story {{EpicNum}}.{{StoryNum}}: {{Short Title Copied from Epic File specific story}}
-
-## Status: {{ Draft | Approved | InProgress | Review | Done }}
-
-## Story
-
-- As a {{role}}
-- I want {{action}}
-- so that {{benefit}}
-
-## Acceptance Criteria (ACs)
-
-{{ Copy of Acceptance Criteria numbered list }}
-
-## Tasks / Subtasks
-
-- [ ] Task 1 (AC: # if applicable)
-  - [ ] Subtask1.1...
-- [ ] Task 2 (AC: # if applicable)
-  - [ ] Subtask 2.1...
-- [ ] Task 3 (AC: # if applicable)
-  - [ ] Subtask 3.1...
-
-## Dev Notes
-
-[[LLM: populates relevant information, only what was pulled from actual artifacts from docs folder, relevant to this story. Do not invent information. Critical: If known add Relevant Source Tree info that relates to this story. If there were important notes from previous story that are relevant to this one, also include them here if it will help the dev agent. You do NOT need to repeat anything from coding standards or test standards as the dev agent is already aware of those. The dev agent should NEVER need to read the PRD or architecture documents or child documents though to complete this self contained story, because your critical mission is to share the specific items needed here extremely concisely for the Dev Agent LLM to comprehend with the least about of context overhead token usage needed.]]
-
-### Testing
-
-[[LLM: Scrum Master use `test-strategy-and-standards.md` to leave instruction for developer agent in the following concise format, leave unchecked if no specific test requirement of that type]]
-Dev Note: Story Requires the following tests:
-
-- [ ] {{type f.e. Jest}} Unit Tests: (nextToFile: {{true|false}}), coverage requirement: {{from strategy or default 80%}}
-- [ ] {{type f.e. Jest with in memory db}} Integration Test (Test Location): location: {{Integration test location f.e. `/tests/story-name/foo.spec.cs` or `next to handler`}}
-- [ ] {{type f.e. Cypress}} E2E: location: {{f.e. `/e2e/{epic-name/bar.test.ts`}}
-
-Manual Test Steps: [[LLM: Include how if possible the user can manually test the functionality when story is Ready for Review, if any]]
-
-{{ f.e. `- dev will create a script with task 3 above that you can run with "npm run test-initiate-launch-sequence" and validate Armageddon is initiated`}}
-
-## Dev Agent Record
-
-### Agent Model Used: {{Agent Model Name/Version}}
-
-### Debug Log References
-
-[[LLM: (SM Agent) When Drafting Story, leave next prompt in place for dev agent to remove and update]]
-[[LLM: (Dev Agent) If the debug is logged to during the current story progress, create a table with the debug log and the specific task section in the debug log - do not repeat all the details in the story]]
-
-### Completion Notes List
-
-[[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]]
-[[LLM: (Dev Agent) Track document versions and changes during development that deviate from story dev start]]
-
-| Date | Version | Description | Author |
-| :--- | :------ | :---------- | :----- |
-
-## QA Results
-
-[[LLM: QA Agent Results]]
-==================== END: templates#story-tmpl ====================
-
-==================== START: checklists#story-draft-checklist ====================
-# Story Draft Checklist
-
-The Scrum Master should use this checklist to validate that each story contains sufficient context for a developer agent to implement it successfully, while assuming the dev agent has reasonable capabilities to figure things out.
-
-[[LLM: INITIALIZATION INSTRUCTIONS - STORY DRAFT VALIDATION
-
-Before proceeding with this checklist, ensure you have access to:
-
-1. The story document being validated (usually in docs/stories/ or provided directly)
-2. The parent epic context
-3. Any referenced architecture or design documents
-4. Previous related stories if this builds on prior work
-
-IMPORTANT: This checklist validates individual stories BEFORE implementation begins.
-
-VALIDATION PRINCIPLES:
-
-1. Clarity - A developer should understand WHAT to build
-2. Context - WHY this is being built and how it fits
-3. Guidance - Key technical decisions and patterns to follow
-4. Testability - How to verify the implementation works
-5. Self-Contained - Most info needed is in the story itself
-
-REMEMBER: We assume competent developer agents who can:
-
-- Research documentation and codebases
-- Make reasonable technical decisions
-- Follow established patterns
-- Ask for clarification when truly stuck
-
-We're checking for SUFFICIENT guidance, not exhaustive detail.]]
-
-## 1. GOAL & CONTEXT CLARITY
-
-[[LLM: Without clear goals, developers build the wrong thing. Verify:
-
-1. The story states WHAT functionality to implement
-2. The business value or user benefit is clear
-3. How this fits into the larger epic/product is explained
-4. Dependencies are explicit ("requires Story X to be complete")
-5. Success looks like something specific, not vague]]
-
-- [ ] Story goal/purpose is clearly stated
-- [ ] Relationship to epic goals is evident
-- [ ] How the story fits into overall system flow is explained
-- [ ] Dependencies on previous stories are identified (if applicable)
-- [ ] Business context and value are clear
-
-## 2. TECHNICAL IMPLEMENTATION GUIDANCE
-
-[[LLM: Developers need enough technical context to start coding. Check:
-
-1. Key files/components to create or modify are mentioned
-2. Technology choices are specified where non-obvious
-3. Integration points with existing code are identified
-4. Data models or API contracts are defined or referenced
-5. Non-standard patterns or exceptions are called out
-
-Note: We don't need every file listed - just the important ones.]]
-
-- [ ] Key files to create/modify are identified (not necessarily exhaustive)
-- [ ] Technologies specifically needed for this story are mentioned
-- [ ] Critical APIs or interfaces are sufficiently described
-- [ ] Necessary data models or structures are referenced
-- [ ] Required environment variables are listed (if applicable)
-- [ ] Any exceptions to standard coding patterns are noted
-
-## 3. REFERENCE EFFECTIVENESS
-
-[[LLM: References should help, not create a treasure hunt. Ensure:
-
-1. References point to specific sections, not whole documents
-2. The relevance of each reference is explained
-3. Critical information is summarized in the story
-4. References are accessible (not broken links)
-5. Previous story context is summarized if needed]]
-
-- [ ] References to external documents point to specific relevant sections
-- [ ] Critical information from previous stories is summarized (not just referenced)
-- [ ] Context is provided for why references are relevant
-- [ ] References use consistent format (e.g., `docs/filename.md#section`)
-
-## 4. SELF-CONTAINMENT ASSESSMENT
-
-[[LLM: Stories should be mostly self-contained to avoid context switching. Verify:
-
-1. Core requirements are in the story, not just in references
-2. Domain terms are explained or obvious from context
-3. Assumptions are stated explicitly
-4. Edge cases are mentioned (even if deferred)
-5. The story could be understood without reading 10 other documents]]
-
-- [ ] Core information needed is included (not overly reliant on external docs)
-- [ ] Implicit assumptions are made explicit
-- [ ] Domain-specific terms or concepts are explained
-- [ ] Edge cases or error scenarios are addressed
-
-## 5. TESTING GUIDANCE
-
-[[LLM: Testing ensures the implementation actually works. Check:
-
-1. Test approach is specified (unit, integration, e2e)
-2. Key test scenarios are listed
-3. Success criteria are measurable
-4. Special test considerations are noted
-5. Acceptance criteria in the story are testable]]
-
-- [ ] Required testing approach is outlined
-- [ ] Key test scenarios are identified
-- [ ] Success criteria are defined
-- [ ] Special testing considerations are noted (if applicable)
-
-## VALIDATION RESULT
-
-[[LLM: FINAL STORY VALIDATION REPORT
-
-Generate a concise validation report:
-
-1. Quick Summary
-
-   - Story readiness: READY / NEEDS REVISION / BLOCKED
-   - Clarity score (1-10)
-   - Major gaps identified
-
-2. Fill in the validation table with:
-
-   - PASS: Requirements clearly met
-   - PARTIAL: Some gaps but workable
-   - FAIL: Critical information missing
-
-3. Specific Issues (if any)
-
-   - List concrete problems to fix
-   - Suggest specific improvements
-   - Identify any blocking dependencies
-
-4. Developer Perspective
-   - Could YOU implement this story as written?
-   - What questions would you have?
-   - What might cause delays or rework?
-
-Be pragmatic - perfect documentation doesn't exist. Focus on whether a competent developer can succeed with this story.]]
-
-| Category                             | Status | Issues |
-| ------------------------------------ | ------ | ------ |
-| 1. Goal & Context Clarity            | _TBD_  |        |
-| 2. Technical Implementation Guidance | _TBD_  |        |
-| 3. Reference Effectiveness           | _TBD_  |        |
-| 4. Self-Containment Assessment       | _TBD_  |        |
-| 5. Testing Guidance                  | _TBD_  |        |
-
-**Final Assessment:**
-
-- READY: The story provides sufficient context for implementation
-- NEEDS REVISION: The story requires updates (see issues)
-- BLOCKED: External information required (specify what information)
-==================== END: checklists#story-draft-checklist ====================
-
-==================== 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 ====================

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

@@ -1,809 +0,0 @@
-# Web Agent Bundle Instructions
-
-You are now operating as a specialized AI agent from the BMAD-METHOD framework. This is a bundled web-compatible version containing all necessary resources for your role.
-
-## Important Instructions
-
-1. **Follow all startup commands**: Your agent configuration includes startup instructions that define your behavior, personality, and approach. These MUST be followed exactly.
-
-2. **Resource Navigation**: This bundle contains all resources you need. Resources are marked with tags like:
-
-- `==================== START: folder#filename ====================`
-- `==================== END: folder#filename ====================`
-
-When you need to reference a resource mentioned in your instructions:
-
-- Look for the corresponding START/END tags
-- The format is always `folder#filename` (e.g., `personas#analyst`, `tasks#create-story`)
-- If a section is specified (e.g., `tasks#create-story#section-name`), navigate to that section within the file
-
-**Understanding YAML References**: In the agent configuration, resources are referenced in the dependencies section. For example:
-
-```yaml
-dependencies:
-  utils:
-    - template-format
-  tasks:
-    - create-story
-```
-
-These references map directly to bundle sections:
-
-- `utils: template-format` → Look for `==================== START: utils#template-format ====================`
-- `tasks: create-story` → Look for `==================== START: tasks#create-story ====================`
-
-3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
-
-4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the BMAD-METHOD framework.
-
----
-
-==================== START: agents#game-sm ====================
-# game-sm
-
-CRITICAL: Read the full YML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
-
-```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:
-  name: Jordan
-  id: game-sm
-  title: Game Scrum Master
-  icon: 🏃‍♂️
-  whenToUse: Use for game story creation, epic management, game development planning, and agile process guidance
-  customization: null
-persona:
-  role: Technical Game Scrum Master - Game Story Preparation Specialist
-  style: Task-oriented, efficient, precise, focused on clear game developer handoffs
-  identity: Game story creation expert who prepares detailed, actionable stories for AI game developers
-  focus: Creating crystal-clear game development stories that developers can implement without confusion
-core_principles:
-  - Task Adherence - Rigorously follow create-game-story procedures
-  - Checklist-Driven Validation - Apply game-story-dod-checklist meticulously
-  - Clarity for Developer Handoff - Stories must be immediately actionable for game implementation
-  - Focus on One Story at a Time - Complete one before starting next
-  - Game-Specific Context - Understand Phaser 3, game mechanics, and performance requirements
-  - Numbered Options Protocol - Always use numbered lists for selections
-startup:
-  - Greet the user with your name and role, and inform of the *help command
-  - CRITICAL: Do NOT automatically execute create-game-story tasks during 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'
-commands:
-  - '*help" - Show numbered list of available commands for selection'
-  - '*chat-mode" - Conversational mode with advanced-elicitation for game dev advice'
-  - '*create" - Execute all steps in Create Game Story Task document'
-  - '*checklist {checklist}" - Show numbered list of checklists, execute selection'
-  - '*exit" - Say goodbye as the Game Scrum Master, and then abandon inhabiting this persona'
-dependencies:
-  tasks:
-    - create-game-story
-    - execute-checklist
-  templates:
-    - game-story-tmpl
-  checklists:
-    - game-story-dod-checklist
-```
-==================== END: agents#game-sm ====================
-
-==================== START: tasks#create-game-story ====================
-# Create Game Development Story Task
-
-## Purpose
-
-Create detailed, actionable game development stories that enable AI developers to implement specific game features without requiring additional design decisions.
-
-## When to Use
-
-- Breaking down game epics into implementable stories
-- Converting GDD features into development tasks
-- Preparing work for game developers
-- Ensuring clear handoffs from design to development
-
-## Prerequisites
-
-Before creating stories, ensure you have:
-
-- Completed Game Design Document (GDD)
-- Game Architecture Document
-- Epic definition this story belongs to
-- Clear understanding of the specific game feature
-
-## Process
-
-### 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
-- Estimate implementation scope
-
-### 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
-- Provide clear success criteria
-
-### 3. Template Execution
-
-**Load Template:**
-Use `templates#game-story-tmpl` following all embedded LLM instructions
-
-**Key Focus Areas:**
-
-- Clear, actionable description
-- Specific acceptance criteria
-- Detailed technical specifications
-- Complete implementation task list
-- Comprehensive testing requirements
-
-### 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
-- Definition of Done complete
-
-### 5. Quality Assurance
-
-**Apply Checklist:**
-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
-- Testing requirements are comprehensive
-- Performance requirements are specified
-
-### 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
-- Verify story points estimation
-
-## Story Elements Checklist
-
-### Required Sections
-
-- [ ] Clear, specific description
-- [ ] Complete acceptance criteria (functional, technical, game design)
-- [ ] Detailed technical specifications
-- [ ] File creation/modification list
-- [ ] TypeScript interfaces and classes
-- [ ] Integration point specifications
-- [ ] Ordered implementation tasks
-- [ ] Comprehensive testing requirements
-- [ ] Performance criteria
-- [ ] Dependencies clearly identified
-- [ ] Definition of Done checklist
-
-### Game-Specific Requirements
-
-- [ ] GDD section references
-- [ ] Game mechanic implementation details
-- [ ] Player experience goals
-- [ ] Balance parameters
-- [ ] Phaser 3 specific requirements
-- [ ] Performance targets (60 FPS)
-- [ ] Cross-platform considerations
-
-### Technical Quality
-
-- [ ] TypeScript strict mode compliance
-- [ ] Architecture document alignment
-- [ ] Code organization follows standards
-- [ ] Error handling requirements
-- [ ] Memory management considerations
-- [ ] Testing strategy defined
-
-## 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
-- Missing balance parameters
-
-## Success Criteria
-
-**Story Readiness:**
-
-- [ ] Developer can start implementation immediately
-- [ ] No additional design decisions required
-- [ ] All technical questions answered
-- [ ] Testing strategy is complete
-- [ ] Performance requirements are clear
-- [ ] Story fits within epic scope
-
-**Quality Validation:**
-
-- [ ] Game story DOD checklist passes
-- [ ] Architecture alignment confirmed
-- [ ] GDD requirements covered
-- [ ] Implementation tasks are ordered and specific
-- [ ] Dependencies are complete and accurate
-
-## Handoff Protocol
-
-**To Game Developer:**
-
-1. Provide story document
-2. Confirm GDD and architecture access
-3. Verify all dependencies are met
-4. Answer any clarification questions
-5. Establish check-in schedule
-
-**Story Status Updates:**
-
-- Draft → Ready for Development
-- In Development → Code Review
-- Code Review → Testing
-- Testing → Done
-
-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}}
-
-**Epic:** {{Epic Name}}  
-**Story ID:** {{ID}}  
-**Priority:** {{High|Medium|Low}}  
-**Points:** {{Story Points}}  
-**Status:** Draft
-
-[[LLM: This template creates detailed game development stories that are immediately actionable by game developers. Each story should focus on a single, implementable feature that contributes to the overall game functionality.
-
-Before starting, ensure you have access to:
-
-- Game Design Document (GDD)
-- Game Architecture Document
-- Any existing stories in this epic
-
-The story should be specific enough that a developer can implement it without requiring additional design decisions.]]
-
-## Description
-
-[[LLM: Provide a clear, concise description of what this story implements. Focus on the specific game feature or system being built. Reference the GDD section that defines this feature.]]
-
-{{clear_description_of_what_needs_to_be_implemented}}
-
-## Acceptance Criteria
-
-[[LLM: Define specific, testable conditions that must be met for the story to be considered complete. Each criterion should be verifiable and directly related to gameplay functionality.]]
-
-### Functional Requirements
-
-- [ ] {{specific_functional_requirement_1}}
-- [ ] {{specific_functional_requirement_2}}
-- [ ] {{specific_functional_requirement_3}}
-
-### Technical Requirements
-
-- [ ] Code follows TypeScript strict mode standards
-- [ ] Maintains 60 FPS on target devices
-- [ ] No memory leaks or performance degradation
-- [ ] {{specific_technical_requirement}}
-
-### Game Design Requirements
-
-- [ ] {{gameplay_requirement_from_gdd}}
-- [ ] {{balance_requirement_if_applicable}}
-- [ ] {{player_experience_requirement}}
-
-## Technical Specifications
-
-[[LLM: Provide specific technical details that guide implementation. Include class names, file locations, and integration points based on the game architecture.]]
-
-### Files to Create/Modify
-
-**New Files:**
-
-- `{{file_path_1}}` - {{purpose}}
-- `{{file_path_2}}` - {{purpose}}
-
-**Modified Files:**
-
-- `{{existing_file_1}}` - {{changes_needed}}
-- `{{existing_file_2}}` - {{changes_needed}}
-
-### Class/Interface Definitions
-
-[[LLM: Define specific TypeScript interfaces and class structures needed]]
-
-```typescript
-// {{interface_name}}
-interface {{InterfaceName}} {
-    {{property_1}}: {{type}};
-    {{property_2}}: {{type}};
-    {{method_1}}({{params}}): {{return_type}};
-}
-
-// {{class_name}}
-class {{ClassName}} extends {{PhaseClass}} {
-    private {{property}}: {{type}};
-
-    constructor({{params}}) {
-        // Implementation requirements
-    }
-
-    public {{method}}({{params}}): {{return_type}} {
-        // Method requirements
-    }
-}
-```
-
-### Integration Points
-
-[[LLM: Specify how this feature integrates with existing systems]]
-
-**Scene Integration:**
-
-- {{scene_name}}: {{integration_details}}
-
-**System Dependencies:**
-
-- {{system_name}}: {{dependency_description}}
-
-**Event Communication:**
-
-- Emits: `{{event_name}}` when {{condition}}
-- Listens: `{{event_name}}` to {{response}}
-
-## Implementation Tasks
-
-[[LLM: Break down the implementation into specific, ordered tasks. Each task should be completable in 1-4 hours.]]
-
-### Dev Agent Record
-
-**Tasks:**
-
-- [ ] {{task_1_description}}
-- [ ] {{task_2_description}}
-- [ ] {{task_3_description}}
-- [ ] {{task_4_description}}
-- [ ] Write unit tests for {{component}}
-- [ ] Integration testing with {{related_system}}
-- [ ] Performance testing and optimization
-
-**Debug Log:**
-| Task | File | Change | Reverted? |
-|------|------|--------|-----------|
-| | | | |
-
-**Completion Notes:**
-
-<!-- Only note deviations from requirements, keep under 50 words -->
-
-**Change Log:**
-
-<!-- Only requirement changes during implementation -->
-
-## Game Design Context
-
-[[LLM: Reference the specific sections of the GDD that this story implements]]
-
-**GDD Reference:** {{section_name}} ({{page_or_section_number}})
-
-**Game Mechanic:** {{mechanic_name}}
-
-**Player Experience Goal:** {{experience_description}}
-
-**Balance Parameters:**
-
-- {{parameter_1}}: {{value_or_range}}
-- {{parameter_2}}: {{value_or_range}}
-
-## Testing Requirements
-
-[[LLM: Define specific testing criteria for this game feature]]
-
-### Unit Tests
-
-**Test Files:**
-
-- `tests/{{component_name}}.test.ts`
-
-**Test Scenarios:**
-
-- {{test_scenario_1}}
-- {{test_scenario_2}}
-- {{edge_case_test}}
-
-### Game Testing
-
-**Manual Test Cases:**
-
-1. {{test_case_1_description}}
-
-   - Expected: {{expected_behavior}}
-   - Performance: {{performance_expectation}}
-
-2. {{test_case_2_description}}
-   - Expected: {{expected_behavior}}
-   - Edge Case: {{edge_case_handling}}
-
-### Performance Tests
-
-**Metrics to Verify:**
-
-- Frame rate maintains {{fps_target}} FPS
-- Memory usage stays under {{memory_limit}}MB
-- {{feature_specific_performance_metric}}
-
-## Dependencies
-
-[[LLM: List any dependencies that must be completed before this story can be implemented]]
-
-**Story Dependencies:**
-
-- {{story_id}}: {{dependency_description}}
-
-**Technical Dependencies:**
-
-- {{system_or_file}}: {{requirement}}
-
-**Asset Dependencies:**
-
-- {{asset_type}}: {{asset_description}}
-- Location: `{{asset_path}}`
-
-## Definition of Done
-
-[[LLM: Checklist that must be completed before the story is considered finished]]
-
-- [ ] All acceptance criteria met
-- [ ] Code reviewed and approved
-- [ ] Unit tests written and passing
-- [ ] Integration tests passing
-- [ ] Performance targets met
-- [ ] No linting errors
-- [ ] Documentation updated
-- [ ] {{game_specific_dod_item}}
-
-## Notes
-
-[[LLM: Any additional context, design decisions, or implementation notes]]
-
-**Implementation Notes:**
-
-- {{note_1}}
-- {{note_2}}
-
-**Design Decisions:**
-
-- {{decision_1}}: {{rationale}}
-- {{decision_2}}: {{rationale}}
-
-**Future Considerations:**
-
-- {{future_enhancement_1}}
-- {{future_optimization_1}}
-==================== END: templates#game-story-tmpl ====================
-
-==================== START: checklists#game-story-dod-checklist ====================
-# Game Development Story Definition of Done Checklist
-
-## 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)
-- [ ] **Story Points** - Realistic estimation for implementation complexity
-- [ ] **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
-- [ ] **Balance Parameters** - Includes any relevant game balance values
-- [ ] **Design Intent** - Purpose and rationale for the feature is clear
-
-## 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
-- [ ] **Event Communication** - Event emitting and listening requirements specified
-- [ ] **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
-- [ ] **Asset Requirements** - All needed assets (sprites, audio, data) identified
-- [ ] **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
-- [ ] **Cross-Platform Support** - Desktop and mobile considerations addressed
-- [ ] **Code Organization** - Follows established game project structure
-
-## 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
-- [ ] **Performance Requirements** - Frame rate and memory usage criteria specified
-- [ ] **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
-- [ ] **File Specifications** - Exact file paths and purposes specified
-- [ ] **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
-- [ ] **External Dependencies** - Any third-party or external requirements noted
-- [ ] **Dependency Validation** - All dependencies are actually available
-
-## 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
-- [ ] **Performance Tests** - Frame rate and memory testing requirements specified
-- [ ] **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
-- [ ] **Performance Metrics** - Specific performance targets for testing
-- [ ] **Test Data** - Any required test data or mock objects specified
-
-## 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
-- [ ] **Balance Implementation** - Numeric values and parameters from GDD included
-- [ ] **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
-- [ ] **Accessibility** - Mobile touch and responsive design considerations
-- [ ] **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
-- [ ] **Mobile Considerations** - Touch controls and mobile performance requirements
-- [ ] **Loading Performance** - Asset loading and scene transition requirements
-
-## 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
-- [ ] **Change Tracking** - Process for tracking any requirement changes during development
-- [ ] **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
-- [ ] **Success Criteria** - Objective measures for story completion defined
-- [ ] **Communication Plan** - Process for developer questions and updates established
-
-## 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
-- [ ] **Quality Standards** - Story meets all game development quality standards
-- [ ] **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
-- [ ] **Definition of Done** - Clear, objective completion criteria established
-- [ ] **Handoff Complete** - Story is ready for developer assignment and implementation
-
-## Checklist Completion
-
-**Overall Story Quality:** ⭐⭐⭐⭐⭐
-
-**Ready for Development:** [ ] Yes [ ] No
-
-**Additional Notes:**
-_Any specific concerns, recommendations, or clarifications needed before development begins._
-==================== END: checklists#game-story-dod-checklist ====================

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

@@ -33,7 +33,7 @@ Select mode from the mode selector (usually in status bar):
 ### File Permission Summary
 
 - **Documentation agents** (analyst, pm, po, sm): `.md`, `.txt` only
-- **bmad-architect**: `.md`, `.txt`, `.yml`, `.yaml`, `.json`
+- **bmad-architect**: `.md`, `.txt`, `.yaml`, `.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`

docs/core-architecture.md

@@ -75,12 +75,12 @@ The `.bmad-core` directory contains all the definitions and resources that give
 
 ### 3.2. Agent Teams (`.bmad-core/agent-teams/`)
 
-- **Purpose**: Team files (e.g., `team-all.yml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
+- **Purpose**: Team files (e.g., `team-all.yaml`) define collections of agents and workflows that are bundled together for a specific purpose, like "full-stack development" or "backend-only". This creates a larger, pre-packaged context for web UI environments.
 - **Structure**: A team file lists the agents to include. It can use wildcards, such as `"*"` to include all agents. This allows for the creation of comprehensive bundles like `team-all`.
 
 ### 3.3. Workflows (`.bmad-core/workflows/`)
 
-- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
+- **Purpose**: Workflows are YAML files (e.g., `greenfield-fullstack.yaml`) that define a prescribed sequence of steps and agent interactions for a specific project type. They act as a strategic guide for the user and the `bmad-orchestrator` agent.
 - **Structure**: A workflow defines sequences for both complex and simple projects, lists the agents involved at each step, the artifacts they create, and the conditions for moving from one step to the next. It often includes a Mermaid diagram for visualization.
 
 ### 3.4. Reusable Resources (`templates`, `tasks`, `checklists`, `data`)
@@ -239,10 +239,10 @@ bmad-method/
 │   │   ├── 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
+│   │   ├── team-all.yaml         # All agents bundle
+│   │   ├── team-fullstack.yaml   # Full-stack development team
+│   │   ├── team-ide-minimal.yaml # Minimal IDE-focused team
+│   │   └── team-no-ui.yaml       # Backend-only team
 │   ├── checklists/               # Quality assurance checklists
 │   │   ├── architect-checklist.md
 │   │   ├── po-master-checklist.md
@@ -268,11 +268,11 @@ bmad-method/
 │   │   ├── 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
+│   │   ├── brownfield-enhancement.yaml
+│   │   ├── greenfield-fullstack.yaml
+│   │   ├── greenfield-service.yaml
+│   │   └── greenfield-simple.yaml
+│   └── core-config.yaml          # V4 configuration system
 │
 ├── dist/                         # Pre-built bundles (generated)
 │   ├── agents/                   # Individual agent bundles
@@ -378,7 +378,7 @@ bmad-method/
 
 ### Key Files
 
-- **core-config.yml**: V4's flexible configuration system
+- **core-config.yaml**: 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

docs/user-guide.md

@@ -104,7 +104,7 @@ After upgrading:
 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)
+The reason #2 and #3 are optional is because now BMAD V4 makes sharding optional for the SM. See [Core Configuration](#core-configuration)
 
 **Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/` - you can remove the backup folder versions.
 
@@ -456,7 +456,7 @@ The SM agent serves as a critical bridge between high-level planning and technic
 
 When the SM agent executes the `create-next-story` task:
 
-1. **Loads Configuration**: Reads `core-config.yml` to understand project structure
+1. **Loads Configuration**: Reads `core-config.yaml` to understand project structure
 2. **Identifies Next Story**: Sequentially processes stories from epics (1.1, 1.2, 2.1, etc.)
 3. **Gathers Architecture Context**: Reads relevant sharded architecture documents based on story type:
 
@@ -1131,11 +1131,11 @@ This file allows you to define your preferred technologies, patterns, and standa
 
 When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation.
 
-### Core Configuration (core-config.yml)
+### Core Configuration
 
-The `bmad-core/core-config.yml` file is a critical V4 innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+The `bmad-core/core-config.yaml` file is a critical V4 innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
 
-#### Understanding core-config.yml
+#### Understanding core-config.yaml
 
 This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It's what makes V4 agents intelligent enough to work with V3 projects, custom layouts, or any document organization you prefer.
 
@@ -1350,7 +1350,7 @@ customTechnicalDocuments:
 1. **Always Configure for Your Structure**: Don't force your project to match BMAD defaults
 2. **Keep devLoadAlwaysFiles Focused**: Only include files needed for every dev task
 3. **Use Debug Log**: Enable when troubleshooting story implementation issues
-4. **Version Control core-config.yml**: Track changes to understand project evolution
+4. **Version Control core-config.yaml**: Track changes to understand project evolution
 5. **Document Custom Patterns**: If using custom epicFilePattern, document it
 
 #### Troubleshooting

expansion-packs/bmad-creator-tools/tasks/generate-expansion-pack.md

@@ -286,7 +286,7 @@ IMPORTANT: Only proceed after plan.md is approved
 expansion-packs/
 └── {pack-name}/
 ├── plan.md (ALREADY CREATED)
-├── manifest.yml
+├── manifest.yaml
 ├── README.md
 ├── agents/
 │ ├── {pack-name}-orchestrator.md (REQUIRED - Custom themed orchestrator)
@@ -309,13 +309,13 @@ expansion-packs/
 ├── workflows/
 │ └── {domain}-workflow.md (REQUIRED if multiple agents)
 └── agent-teams/
-└── {domain}-team.yml (REQUIRED if multiple agents)
+└── {domain}-team.yaml (REQUIRED if multiple agents)
 
 ```
 
 #### 3.2 Create Manifest
 
-Create `manifest.yml`:
+Create `manifest.yaml`:
 
 ```yaml
 name: {pack-name}
@@ -358,7 +358,7 @@ files:
     - {domain}-workflow.md        # REQUIRED if multiple agents - decision trees
 
   agent-teams:
-    - {domain}-team.yml           # REQUIRED if multiple agents - team config
+    - {domain}-team.yaml          # REQUIRED if multiple agents - team config
 
 # Data files users must provide (in their bmad-core/data/ directory)
 required_user_data:
@@ -494,7 +494,7 @@ cp common/utils/workflow-management.md expansion-packs/{pack-name}/utils/
 1. Design decision trees for workflow branching
 2. Create handoff protocols to specialist agents
 3. Implement validation loops and quality checkpoints
-4. **If multiple agents**: Create team configuration in `agent-teams/{domain}-team.yml`
+4. **If multiple agents**: Create team configuration in `agent-teams/{domain}-team.yaml`
 5. **If multiple agents**: Create workflow in `workflows/{domain}-workflow.md`
 6. Ensure orchestrator references workflow-management utility
 7. Verify ALL referenced tasks exist (including core utilities)
@@ -665,7 +665,7 @@ Before declaring complete:
 
 1. [ ] Decision trees and workflow orchestration complete
 2. [ ] Knowledge base files embedded (best practices, terminology, standards)
-3. [ ] Manifest.yml reflects all components and dependencies
+3. [ ] Manifest.yaml reflects all components and dependencies
 4. [ ] All items in plan.md marked complete
 5. [ ] No orphaned tasks or templates
 
@@ -772,7 +772,7 @@ These files are automatically available to all agents and don't require user set
 ```text
 healthcare/
 ├── plan.md (Created first for approval)
-├── manifest.yml (with dependency mapping and character descriptions)
+├── manifest.yaml (with dependency mapping and character descriptions)
 ├── README.md (featuring character introductions and numbered options)
 ├── agents/
 │   ├── healthcare-orchestrator.md (Dr. Sarah Chen - YAML-in-Markdown)
@@ -798,7 +798,7 @@ healthcare/
 │   ├── clinical-trial-workflow.md (decision trees with Mermaid diagrams)
 │   └── compliance-audit-workflow.md (handoff protocols and quality gates)
 └── agent-teams/
-    └── healthcare-team.yml (coordinated team configurations)
+    └── healthcare-team.yaml (coordinated team configurations)
 
 Required user data files (bmad-core/data/):
 - medical-terminology.md (institution-specific terms and abbreviations)
@@ -1009,7 +1009,7 @@ Embedded knowledge (automatic):
 - [ ] All agent references verified (tasks, templates, data, checklists)
 - [ ] Data requirements documented with validation criteria and examples
 - [ ] README includes character introductions and numbered options explanation
-- [ ] manifest.yml reflects actual files with dependency mapping and character descriptions
+- [ ] manifest.yaml reflects actual files with dependency mapping and character descriptions
 
 **Advanced Quality Gates:**
 

expansion-packs/bmad-creator-tools/templates/agent-teams-tmpl.md

@@ -150,5 +150,5 @@ workflows: null
 3. Replace all placeholders with actual values
 4. Ensure agent names match available agents in the system
 5. Verify workflow names match available workflows
-6. Save as team-[descriptor].yml or [domain]-team.yml
+6. Save as team-[descriptor].yaml or [domain]-team.yaml
 7. Place in the agent-teams directory of the appropriate location]]

expansion-packs/bmad-creator-tools/templates/agent-tmpl.md

@@ -10,7 +10,7 @@
 
 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

expansion-packs/bmad-infrastructure-devops/README.md

@@ -28,7 +28,7 @@ Install this expansion pack when your project requires:
 
 ### Agents
 
-- `devops.yml` - DevOps and Platform Engineering agent configuration
+- `devops.yaml` - DevOps and Platform Engineering agent configuration
 
 ### Personas
 
@@ -116,8 +116,8 @@ Before deployment:
 
 The DevOps agent can be added to team configurations:
 
-- `team-technical.yml` - For technical implementation teams
-- `team-full-org.yml` - For complete organizational teams
+- `team-technical.yaml` - For technical implementation teams
+- `team-full-org.yaml` - For complete organizational teams
 
 ## Dependencies
 

package-lock.json

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

package.json

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

tools/builders/web-builder.js

@@ -1,6 +1,7 @@
 const fs = require("node:fs").promises;
 const path = require("node:path");
 const DependencyResolver = require("../lib/dependency-resolver");
+const yamlUtils = require("../lib/yaml-utils");
 
 class WebBuilder {
   constructor(options = {}) {
@@ -111,10 +112,12 @@ class WebBuilder {
 
   processAgentContent(content) {
     // First, replace content before YAML with the template
+    const yamlContent = yamlUtils.extractYamlFromAgent(content);
+    if (!yamlContent) return content;
+
     const yamlMatch = content.match(/```ya?ml\n([\s\S]*?)\n```/);
     if (!yamlMatch) return content;
     
-    const yamlContent = yamlMatch[1];
     const yamlStartIndex = content.indexOf(yamlMatch[0]);
     const yamlEndIndex = yamlStartIndex + yamlMatch[0].length;
 
@@ -259,7 +262,7 @@ class WebBuilder {
     const agentTeamsDir = path.join(packDir, "agent-teams");
     try {
       const teamFiles = await fs.readdir(agentTeamsDir);
-      const teamFile = teamFiles.find((f) => f.endsWith(".yml"));
+      const teamFile = teamFiles.find((f) => f.endsWith(".yaml"));
 
       if (teamFile) {
         console.log(`    Building team bundle for ${packName}`);
@@ -272,7 +275,7 @@ class WebBuilder {
         for (const outputDir of outputDirs) {
           const teamsOutputDir = path.join(outputDir, "teams");
           await fs.mkdir(teamsOutputDir, { recursive: true });
-          const outputFile = path.join(teamsOutputDir, teamFile.replace(".yml", ".txt"));
+          const outputFile = path.join(teamsOutputDir, teamFile.replace(".yaml", ".txt"));
           await fs.writeFile(outputFile, bundle, "utf8");
           console.log(`    ✓ Created bundle: ${path.relative(this.rootDir, outputFile)}`);
         }
@@ -294,11 +297,11 @@ class WebBuilder {
     sections.push(this.formatSection(`agents#${agentName}`, agentContent));
 
     // Resolve and add agent dependencies
-    const agentYaml = agentContent.match(/```yaml\n([\s\S]*?)\n```/);
-    if (agentYaml) {
+    const yamlContent = yamlUtils.extractYamlFromAgent(agentContent);
+    if (yamlContent) {
       try {
         const yaml = require("js-yaml");
-        const agentConfig = yaml.load(agentYaml[1]);
+        const agentConfig = yaml.load(yamlContent);
 
         if (agentConfig.dependencies) {
           // Add resources, first try expansion pack, then core
@@ -306,7 +309,7 @@ class WebBuilder {
             if (Array.isArray(resources)) {
               for (const resourceName of resources) {
                 let found = false;
-                const extensions = [".md", ".yml", ".yaml"];
+                const extensions = [".md", ".yaml"];
 
                 // Try expansion pack first
                 for (const ext of extensions) {
@@ -391,7 +394,7 @@ class WebBuilder {
 
     // Add team configuration and parse to get agent list
     const teamContent = await fs.readFile(teamConfigPath, "utf8");
-    const teamFileName = path.basename(teamConfigPath, ".yml");
+    const teamFileName = path.basename(teamConfigPath, ".yaml");
     const teamConfig = this.parseYaml(teamContent);
     sections.push(this.formatSection(`agent-teams#${teamFileName}`, teamContent));
 
@@ -416,9 +419,9 @@ class WebBuilder {
       try {
         const resourceFiles = await fs.readdir(resourcePath);
         for (const resourceFile of resourceFiles.filter(
-          (f) => f.endsWith(".md") || f.endsWith(".yml")
+          (f) => f.endsWith(".md") || f.endsWith(".yaml")
         )) {
-          const fileName = resourceFile.replace(/\.(md|yml)$/, "");
+          const fileName = resourceFile.replace(/\.(md|yaml)$/, "");
           expansionResources.set(`${resourceDir}#${fileName}`, true);
         }
       } catch (error) {
@@ -474,13 +477,9 @@ class WebBuilder {
           sections.push(this.formatSection(`agents#${agentId}`, coreAgentContent));
 
           // Parse and collect dependencies from core agent
-          const agentYaml = coreAgentContent.match(/```yaml\n([\s\S]*?)\n```/);
-          if (agentYaml) {
+          const yamlContent = yamlUtils.extractYamlFromAgent(coreAgentContent, true);
+          if (yamlContent) {
             try {
-              // Clean up the YAML to handle command descriptions after dashes
-              let yamlContent = agentYaml[1];
-              yamlContent = yamlContent.replace(/^(\s*-)(\s*"[^"]+")(\s*-\s*.*)$/gm, "$1$2");
-
               const agentConfig = this.parseYaml(yamlContent);
               if (agentConfig.dependencies) {
                 for (const [resourceType, resources] of Object.entries(agentConfig.dependencies)) {
@@ -508,7 +507,7 @@ class WebBuilder {
     // Always prefer expansion pack versions if they exist
     for (const [key, dep] of allDependencies) {
       let found = false;
-      const extensions = [".md", ".yml", ".yaml"];
+      const extensions = [".md", ".yaml"];
 
       // Always check expansion pack first, even if the dependency came from a core agent
       if (expansionResources.has(key)) {
@@ -568,11 +567,11 @@ class WebBuilder {
       try {
         const resourceFiles = await fs.readdir(resourcePath);
         for (const resourceFile of resourceFiles.filter(
-          (f) => f.endsWith(".md") || f.endsWith(".yml")
+          (f) => f.endsWith(".md") || f.endsWith(".yaml")
         )) {
           const filePath = path.join(resourcePath, resourceFile);
           const fileContent = await fs.readFile(filePath, "utf8");
-          const fileName = resourceFile.replace(/\.(md|yml)$/, "");
+          const fileName = resourceFile.replace(/\.(md|yaml)$/, "");
 
           // Only add if not already included as a dependency
           const resourceKey = `${resourceDir}#${fileName}`;

tools/bump-all-versions.js

@@ -32,7 +32,7 @@ async function bumpAllVersions() {
   const updatedItems = [];
   
   // First, bump the core version
-  const coreConfigPath = path.join(__dirname, '..', 'bmad-core', 'core-config.yml');
+  const coreConfigPath = path.join(__dirname, '..', 'bmad-core', 'core-config.yaml');
   try {
     const coreConfigContent = fs.readFileSync(coreConfigPath, 'utf8');
     const coreConfig = yaml.load(coreConfigContent);
@@ -59,7 +59,7 @@ async function bumpAllVersions() {
     for (const entry of entries) {
       if (entry.isDirectory() && !entry.name.startsWith('.') && entry.name !== 'README.md') {
         const packId = entry.name;
-        const configPath = path.join(expansionPacksDir, packId, 'config.yml');
+        const configPath = path.join(expansionPacksDir, packId, 'config.yaml');
         
         if (fs.existsSync(configPath)) {
           try {

tools/bump-core-version.js

@@ -30,7 +30,7 @@ function bumpVersion(currentVersion, type) {
 
 async function bumpCoreVersion() {
   try {
-    const coreConfigPath = path.join(__dirname, '..', 'bmad-core', 'core-config.yml');
+    const coreConfigPath = path.join(__dirname, '..', 'bmad-core', 'core-config.yaml');
     
     const coreConfigContent = fs.readFileSync(coreConfigPath, 'utf8');
     const coreConfig = yaml.load(coreConfigContent);

tools/bump-expansion-version.js

@@ -38,7 +38,7 @@ function bumpVersion(currentVersion, type) {
 
 async function updateVersion() {
   try {
-    const configPath = path.join(__dirname, '..', 'expansion-packs', packId, 'config.yml');
+    const configPath = path.join(__dirname, '..', 'expansion-packs', packId, 'config.yaml');
     
     if (!fs.existsSync(configPath)) {
       console.error(`Error: Expansion pack '${packId}' not found`);

tools/installer/README.md

@@ -16,7 +16,7 @@ installer/
 │   ├── ide-setup.js     # IDE-specific setup
 │   └── prompts.js       # Interactive CLI prompts
 ├── config/          # Configuration files
-│   └── install.config.yml # Installation profiles
+│   └── install.config.yaml # Installation profiles
 ├── templates/       # IDE template files
 │   ├── cursor-rules.md     # Cursor template
 │   ├── claude-commands.md  # Claude Code template

tools/installer/bin/bmad.js

@@ -158,7 +158,7 @@ async function promptInstallation() {
   const choices = [];
   
   // Load core config to get short-title
-  const coreConfigPath = path.join(__dirname, '..', '..', '..', 'bmad-core', 'core-config.yml');
+  const coreConfigPath = path.join(__dirname, '..', '..', '..', 'bmad-core', 'core-config.yaml');
   const coreConfig = yaml.load(await fs.readFile(coreConfigPath, 'utf8'));
   const coreShortTitle = coreConfig['short-title'] || 'BMad Agile Core System';
   
@@ -166,7 +166,7 @@ async function promptInstallation() {
   let bmadOptionText;
   if (state.type === 'v4_existing') {
     const currentVersion = state.manifest?.version || 'unknown';
-    const newVersion = coreConfig.version || 'unknown'; // Use version from core-config.yml
+    const newVersion = coreConfig.version || 'unknown'; // Use version from core-config.yaml
     const versionInfo = currentVersion === newVersion 
       ? `(v${currentVersion} - reinstall)`
       : `(v${currentVersion} → v${newVersion})`;

tools/installer/lib/config-loader.js

@@ -1,10 +1,11 @@
 const fs = require('fs-extra');
 const path = require('path');
 const yaml = require('js-yaml');
+const { extractYamlFromAgent } = require('../../lib/yaml-utils');
 
 class ConfigLoader {
   constructor() {
-    this.configPath = path.join(__dirname, '..', 'config', 'install.config.yml');
+    this.configPath = path.join(__dirname, '..', 'config', 'install.config.yaml');
     this.config = null;
   }
 
@@ -41,9 +42,9 @@ class ConfigLoader {
             const agentContent = await fs.readFile(agentPath, 'utf8');
             
             // Extract YAML block from agent file
-            const yamlMatch = agentContent.match(/```yml\n([\s\S]*?)\n```/);
-            if (yamlMatch) {
-              const yamlContent = yaml.load(yamlMatch[1]);
+            const yamlContentText = extractYamlFromAgent(agentContent);
+            if (yamlContentText) {
+              const yamlContent = yaml.load(yamlContentText);
               const agentConfig = yamlContent.agent || {};
               
               agents.push({
@@ -79,10 +80,10 @@ class ConfigLoader {
       for (const entry of entries) {
         if (entry.isDirectory() && !entry.name.startsWith('.')) {
           const packPath = path.join(expansionPacksDir, entry.name);
-          const configPath = path.join(packPath, 'config.yml');
+          const configPath = path.join(packPath, 'config.yaml');
           
           try {
-            // Read config.yml
+            // Read config.yaml
             const configContent = await fs.readFile(configPath, 'utf8');
             const config = yaml.load(configContent);
             
@@ -97,7 +98,7 @@ class ConfigLoader {
               dependencies: config.dependencies?.agents || []
             });
           } catch (error) {
-            // Fallback if config.yml doesn't exist or can't be read
+            // Fallback if config.yaml doesn't exist or can't be read
             console.warn(`Failed to read config for expansion pack ${entry.name}: ${error.message}`);
             
             // Try to derive info from directory name as fallback
@@ -180,7 +181,7 @@ class ConfigLoader {
       const teams = [];
       
       for (const entry of entries) {
-        if (entry.isFile() && entry.name.endsWith('.yml')) {
+        if (entry.isFile() && entry.name.endsWith('.yaml')) {
           const teamPath = path.join(teamsDir, entry.name);
           
           try {
@@ -189,7 +190,7 @@ class ConfigLoader {
             
             if (teamConfig.bundle) {
               teams.push({
-                id: path.basename(entry.name, '.yml'),
+                id: path.basename(entry.name, '.yaml'),
                 name: teamConfig.bundle.name || entry.name,
                 description: teamConfig.bundle.description || 'Team configuration',
                 icon: teamConfig.bundle.icon || '📋'
@@ -209,7 +210,7 @@ class ConfigLoader {
   }
 
   getTeamPath(teamId) {
-    return path.join(this.getBmadCorePath(), 'agent-teams', `${teamId}.yml`);
+    return path.join(this.getBmadCorePath(), 'agent-teams', `${teamId}.yaml`);
   }
 
   async getTeamDependencies(teamId) {
@@ -224,7 +225,7 @@ class ConfigLoader {
       const depPaths = [];
       
       // Add team config file
-      depPaths.push(`.bmad-core/agent-teams/${teamId}.yml`);
+      depPaths.push(`.bmad-core/agent-teams/${teamId}.yaml`);
       
       // Add all agents
       for (const agent of teamDeps.agents) {
@@ -236,7 +237,7 @@ class ConfigLoader {
       
       // Add all resolved resources
       for (const resource of teamDeps.resources) {
-        const filePath = `.bmad-core/${resource.type}/${resource.id}.${resource.type === 'workflows' ? 'yml' : 'md'}`;
+        const filePath = `.bmad-core/${resource.type}/${resource.id}.${resource.type === 'workflows' ? 'yaml' : 'md'}`;
         if (!depPaths.includes(filePath)) {
           depPaths.push(filePath);
         }

tools/installer/lib/file-manager.js

@@ -17,7 +17,7 @@ async function initializeModules() {
 class FileManager {
   constructor() {
     this.manifestDir = ".bmad-core";
-    this.manifestFile = "install-manifest.yml";
+    this.manifestFile = "install-manifest.yaml";
   }
 
   async copyFile(source, destination) {
@@ -83,15 +83,15 @@ class FileManager {
       this.manifestFile
     );
 
-    // Read version from core-config.yml
-    const coreConfigPath = path.join(__dirname, "../../../bmad-core/core-config.yml");
+    // Read version from core-config.yaml
+    const coreConfigPath = path.join(__dirname, "../../../bmad-core/core-config.yaml");
     let coreVersion = "unknown";
     try {
       const coreConfigContent = await fs.readFile(coreConfigPath, "utf8");
       const coreConfig = yaml.load(coreConfigContent);
       coreVersion = coreConfig.version || "unknown";
     } catch (error) {
-      console.warn("Could not read version from core-config.yml, using 'unknown'");
+      console.warn("Could not read version from core-config.yaml, using 'unknown'");
     }
 
     const manifest = {
@@ -178,7 +178,7 @@ class FileManager {
       const filePath = path.join(installDir, file.path);
       
       // Skip checking the manifest file itself - it will always be different due to timestamps
-      if (file.path.endsWith('install-manifest.yml')) {
+      if (file.path.endsWith('install-manifest.yaml')) {
         continue;
       }
       

tools/installer/lib/ide-setup.js

@@ -3,6 +3,7 @@ const fs = require("fs-extra");
 const yaml = require("js-yaml");
 const fileManager = require("./file-manager");
 const configLoader = require("./config-loader");
+const { extractYamlFromAgent } = require("../../lib/yaml-utils");
 
 // Dynamic import for ES module
 let chalk;
@@ -27,7 +28,7 @@ class IdeSetup {
     if (this.ideAgentConfig) return this.ideAgentConfig;
     
     try {
-      const configPath = path.join(__dirname, '..', 'config', 'ide-agent-config.yml');
+      const configPath = path.join(__dirname, '..', 'config', 'ide-agent-config.yaml');
       const configContent = await fs.readFile(configPath, 'utf8');
       this.ideAgentConfig = yaml.load(configContent);
       return this.ideAgentConfig;
@@ -98,11 +99,11 @@ class IdeSetup {
         mdcContent += "## Agent Activation\n\n";
         mdcContent +=
           "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:\n\n";
-        mdcContent += "```yml\n";
+        mdcContent += "```yaml\n";
         // Extract just the YAML content from the agent file
-        const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)```/);
-        if (yamlMatch) {
-          mdcContent += yamlMatch[1].trim();
+        const yamlContent = extractYamlFromAgent(agentContent);
+        if (yamlContent) {
+          mdcContent += yamlContent;
         } else {
           // If no YAML found, include the whole content minus the header
           mdcContent += agentContent.replace(/^#.*$/m, "").trim();
@@ -180,11 +181,11 @@ class IdeSetup {
         mdContent += "## Agent Activation\n\n";
         mdContent +=
           "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:\n\n";
-        mdContent += "```yml\n";
+        mdContent += "```yaml\n";
         // Extract just the YAML content from the agent file
-        const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)```/);
-        if (yamlMatch) {
-          mdContent += yamlMatch[1].trim();
+        const yamlContent = extractYamlFromAgent(agentContent);
+        if (yamlContent) {
+          mdContent += yamlContent;
         } else {
           // If no YAML found, include the whole content minus the header
           mdContent += agentContent.replace(/^#.*$/m, "").trim();
@@ -428,11 +429,11 @@ class IdeSetup {
         mdContent += "## Role Definition\n\n";
         mdContent +=
           "When the user types `@" + agentId + "`, adopt this persona and follow these guidelines:\n\n";
-        mdContent += "```yml\n";
+        mdContent += "```yaml\n";
         // Extract just the YAML content from the agent file
-        const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)```/);
-        if (yamlMatch) {
-          mdContent += yamlMatch[1].trim();
+        const yamlContent = extractYamlFromAgent(agentContent);
+        if (yamlContent) {
+          mdContent += yamlContent;
         } else {
           // If no YAML found, include the whole content minus the header
           mdContent += agentContent.replace(/^#.*$/m, "").trim();

tools/installer/lib/installer.js

@@ -2,6 +2,7 @@ const path = require("node:path");
 const fileManager = require("./file-manager");
 const configLoader = require("./config-loader");
 const ideSetup = require("./ide-setup");
+const { extractYamlFromAgent } = require("../../lib/yaml-utils");
 
 // Dynamic imports for ES modules
 let chalk, ora, inquirer;
@@ -19,13 +20,13 @@ class Installer {
   async getCoreVersion() {
     const yaml = require("js-yaml");
     const fs = require("fs-extra");
-    const coreConfigPath = path.join(__dirname, "../../../bmad-core/core-config.yml");
+    const coreConfigPath = path.join(__dirname, "../../../bmad-core/core-config.yaml");
     try {
       const coreConfigContent = await fs.readFile(coreConfigPath, "utf8");
       const coreConfig = yaml.load(coreConfigContent);
       return coreConfig.version || "unknown";
     } catch (error) {
-      console.warn("Could not read version from core-config.yml, using 'unknown'");
+      console.warn("Could not read version from core-config.yaml, using 'unknown'");
       return "unknown";
     }
   }
@@ -185,7 +186,7 @@ class Installer {
 
     // Check for V4 installation (has .bmad-core with manifest)
     const bmadCorePath = path.join(installDir, ".bmad-core");
-    const manifestPath = path.join(bmadCorePath, "install-manifest.yml");
+    const manifestPath = path.join(bmadCorePath, "install-manifest.yaml");
 
     if (await fileManager.pathExists(manifestPath)) {
       state.type = "v4_existing";
@@ -713,7 +714,7 @@ class Installer {
       
       for (const file of filesToRestore) {
         // Skip the manifest file itself
-        if (file.endsWith('install-manifest.yml')) continue;
+        if (file.endsWith('install-manifest.yaml')) continue;
         
         const relativePath = file.replace('.bmad-core/', '');
         const destPath = path.join(installDir, file);
@@ -757,12 +758,7 @@ class Installer {
       const ides = manifest.ides_setup || [];
       if (ides.includes('cursor')) {
         console.log(chalk.yellow.bold("\n⚠️  IMPORTANT: Cursor Custom Modes Update Required"));
-        console.log(chalk.yellow("Since agent files have been repaired, you need to manually update your Cursor custom modes:"));
-        console.log(chalk.yellow("1. Open Cursor Settings (Cmd/Ctrl + ,)"));
-        console.log(chalk.yellow("2. Go to: Features > Cursor Tab > Custom Modes"));
-        console.log(chalk.yellow("3. Update each custom mode with the latest agent templates from:"));
-        console.log(chalk.yellow(`   ${path.join(installDir, '.bmad-core', 'agents')}`));
-        console.log(chalk.yellow("4. Copy the full content of each agent file into the corresponding custom mode"));
+        console.log(chalk.yellow("Since agent files have been repaired, you need to update any custom agent modes configured in the Cursor custom agent GUI per the Cursor docs."));
       }
       
     } catch (error) {
@@ -861,12 +857,7 @@ class Installer {
     // Warning for Cursor custom modes if agents were updated
     if (options.isUpdate && ides.includes('cursor')) {
       console.log(chalk.yellow.bold("\n⚠️  IMPORTANT: Cursor Custom Modes Update Required"));
-      console.log(chalk.yellow("Since agents have been updated, you need to manually update your Cursor custom modes:"));
-      console.log(chalk.yellow("1. Open Cursor Settings (Cmd/Ctrl + ,)"));
-      console.log(chalk.yellow("2. Go to: Features > Cursor Tab > Custom Modes"));
-      console.log(chalk.yellow("3. Update each custom mode with the latest agent templates from:"));
-      console.log(chalk.yellow(`   ${path.join(installDir, '.bmad-core', 'agents')}`));
-      console.log(chalk.yellow("4. Copy the full content of each agent file into the corresponding custom mode"));
+      console.log(chalk.yellow("Since agents have been updated, you need to update any custom agent modes configured in the Cursor custom agent GUI per the Cursor docs."));
     }
   }
 
@@ -1019,7 +1010,7 @@ class Installer {
         
         // Check if expansion pack already exists
         let expansionDotFolder = path.join(installDir, `.${packId}`);
-        const existingManifestPath = path.join(expansionDotFolder, 'install-manifest.yml');
+        const existingManifestPath = path.join(expansionDotFolder, 'install-manifest.yaml');
         
         if (await fileManager.pathExists(existingManifestPath)) {
           spinner.stop();
@@ -1161,12 +1152,12 @@ class Installer {
           }
         }
 
-        // Copy config.yml
-        const configPath = path.join(expansionPackDir, 'config.yml');
+        // Copy config.yaml
+        const configPath = path.join(expansionPackDir, 'config.yaml');
         if (await fileManager.pathExists(configPath)) {
-          const configDestPath = path.join(expansionDotFolder, 'config.yml');
+          const configDestPath = path.join(expansionDotFolder, 'config.yaml');
           if (await fileManager.copyFile(configPath, configDestPath)) {
-            installedFiles.push(path.join(`.${packId}`, 'config.yml'));
+            installedFiles.push(path.join(`.${packId}`, 'config.yaml'));
           }
         }
         
@@ -1232,10 +1223,10 @@ class Installer {
       const agentContent = await fs.readFile(agentPath, 'utf8');
       
       // Extract YAML frontmatter to check dependencies
-      const yamlMatch = agentContent.match(/```yaml\n([\s\S]*?)```/);
-      if (yamlMatch) {
+      const yamlContent = extractYamlFromAgent(agentContent);
+      if (yamlContent) {
         try {
-          const agentConfig = yaml.parse(yamlMatch[1]);
+          const agentConfig = yaml.parse(yamlContent);
           const dependencies = agentConfig.dependencies || {};
           
           // Check for core dependencies (those that don't exist in the expansion pack)
@@ -1278,7 +1269,7 @@ class Installer {
     const fs = require('fs').promises;
     
     // Find all team files in the expansion pack
-    const teamFiles = glob.sync('agent-teams/*.yml', {
+    const teamFiles = glob.sync('agent-teams/*.yaml', {
       cwd: expansionDotFolder
     });
 
@@ -1324,13 +1315,10 @@ class Installer {
               
               // Now resolve this agent's dependencies too
               const agentContent = await fs.readFile(coreAgentPath, 'utf8');
-              const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)```/);
+              const yamlContent = extractYamlFromAgent(agentContent, true);
               
-              if (yamlMatch) {
+              if (yamlContent) {
                 try {
-                  // Clean up the YAML to handle command descriptions
-                  let yamlContent = yamlMatch[1];
-                  yamlContent = yamlContent.replace(/^(\s*-)(\s*"[^"]+")(\s*-\s*.*)$/gm, '$1$2');
                   
                   const agentConfig = yaml.parse(yamlContent);
                   const dependencies = agentConfig.dependencies || {};
@@ -1340,7 +1328,7 @@ class Installer {
                     const deps = dependencies[depType] || [];
                     
                     for (const dep of deps) {
-                      const depFileName = dep.endsWith('.md') || dep.endsWith('.yml') ? dep : `${dep}.md`;
+                      const depFileName = dep.endsWith('.md') || dep.endsWith('.yaml') ? dep : `${dep}.md`;
                       const expansionDepPath = path.join(expansionDotFolder, depType, depFileName);
                       
                       // Check if dependency exists in expansion pack
@@ -1370,7 +1358,7 @@ class Installer {
                 }
               }
             } else {
-              console.warn(chalk.yellow(`  Warning: Core agent ${agentId} not found for team ${path.basename(teamFile, '.yml')}`));
+              console.warn(chalk.yellow(`  Warning: Core agent ${agentId} not found for team ${path.basename(teamFile, '.yaml')}`));
             }
           }
         }
@@ -1538,7 +1526,7 @@ class Installer {
       
       if (stats) {
         // Check if it has a manifest
-        const manifestPath = path.join(folderPath, "install-manifest.yml");
+        const manifestPath = path.join(folderPath, "install-manifest.yaml");
         if (await fileManager.pathExists(manifestPath)) {
           const manifest = await fileManager.readExpansionPackManifest(installDir, folder.substring(1));
           if (manifest) {
@@ -1549,8 +1537,8 @@ class Installer {
             };
           }
         } else {
-          // Check if it has a config.yml (expansion pack without manifest)
-          const configPath = path.join(folderPath, "config.yml");
+          // Check if it has a config.yaml (expansion pack without manifest)
+          const configPath = path.join(folderPath, "config.yaml");
           if (await fileManager.pathExists(configPath)) {
             expansionPacks[folder.substring(1)] = {
               path: folderPath,
@@ -1589,7 +1577,7 @@ class Installer {
       
       for (const file of filesToRestore) {
         // Skip the manifest file itself
-        if (file.endsWith('install-manifest.yml')) continue;
+        if (file.endsWith('install-manifest.yaml')) continue;
         
         const relativePath = file.replace(`.${packId}/`, '');
         const sourcePath = path.join(pack.packPath, relativePath);
@@ -1655,7 +1643,7 @@ class Installer {
 
     while (currentDir !== path.dirname(currentDir)) {
       const bmadDir = path.join(currentDir, ".bmad-core");
-      const manifestPath = path.join(bmadDir, "install-manifest.yml");
+      const manifestPath = path.join(bmadDir, "install-manifest.yaml");
 
       if (await fileManager.pathExists(manifestPath)) {
         return bmadDir;
@@ -1666,7 +1654,7 @@ class Installer {
 
     // Also check if we're inside a .bmad-core directory
     if (path.basename(process.cwd()) === ".bmad-core") {
-      const manifestPath = path.join(process.cwd(), "install-manifest.yml");
+      const manifestPath = path.join(process.cwd(), "install-manifest.yaml");
       if (await fileManager.pathExists(manifestPath)) {
         return process.cwd();
       }

tools/installer/package.json

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

tools/lib/dependency-resolver.js

@@ -1,6 +1,7 @@
 const fs = require('fs').promises;
 const path = require('path');
 const yaml = require('js-yaml');
+const { extractYamlFromAgent } = require('./yaml-utils');
 
 class DependencyResolver {
   constructor(rootDir) {
@@ -14,17 +15,12 @@ class DependencyResolver {
     const agentPath = path.join(this.bmadCore, 'agents', `${agentId}.md`);
     const agentContent = await fs.readFile(agentPath, 'utf8');
     
-    // Extract YAML from markdown content
-    const yamlMatch = agentContent.match(/```ya?ml\n([\s\S]*?)\n```/);
-    if (!yamlMatch) {
+    // Extract YAML from markdown content with command cleaning
+    const yamlContent = extractYamlFromAgent(agentContent, true);
+    if (!yamlContent) {
       throw new Error(`No YAML configuration found in agent ${agentId}`);
     }
     
-    // Clean up the YAML to handle command descriptions after dashes
-    let yamlContent = yamlMatch[1];
-    // Fix commands section: convert "- command - description" to just "- command"
-    yamlContent = yamlContent.replace(/^(\s*-)(\s*"[^"]+")(\s*-\s*.*)$/gm, '$1$2');
-    
     const agentConfig = yaml.load(yamlContent);
     
     const dependencies = {
@@ -53,7 +49,7 @@ class DependencyResolver {
   }
 
   async resolveTeamDependencies(teamId) {
-    const teamPath = path.join(this.bmadCore, 'agent-teams', `${teamId}.yml`);
+    const teamPath = path.join(this.bmadCore, 'agent-teams', `${teamId}.yaml`);
     const teamContent = await fs.readFile(teamPath, 'utf8');
     const teamConfig = yaml.load(teamContent);
     
@@ -120,7 +116,7 @@ class DependencyResolver {
     }
 
     try {
-      const extensions = ['.md', '.yml', '.yaml'];
+      const extensions = ['.md', '.yaml'];
       let content = null;
       let filePath = null;
 
@@ -183,8 +179,8 @@ class DependencyResolver {
     try {
       const files = await fs.readdir(path.join(this.bmadCore, 'agent-teams'));
       return files
-        .filter(f => f.endsWith('.yml'))
-        .map(f => f.replace('.yml', ''));
+        .filter(f => f.endsWith('.yaml'))
+        .map(f => f.replace('.yaml', ''));
     } catch (error) {
       return [];
     }

tools/lib/yaml-utils.js

@@ -0,0 +1,29 @@
+/**
+ * Utility functions for YAML extraction from agent files
+ */
+
+/**
+ * Extract YAML content from agent markdown files
+ * @param {string} agentContent - The full content of the agent file
+ * @param {boolean} cleanCommands - Whether to clean command descriptions (default: false)
+ * @returns {string|null} - The extracted YAML content or null if not found
+ */
+function extractYamlFromAgent(agentContent, cleanCommands = false) {
+  // Remove carriage returns and match YAML block
+  const yamlMatch = agentContent.replace(/\r/g, "").match(/```ya?ml\n([\s\S]*?)\n```/);
+  if (!yamlMatch) return null;
+  
+  let yamlContent = yamlMatch[1].trim();
+  
+  // Clean up command descriptions if requested
+  // Converts "- command - description" to just "- command"
+  if (cleanCommands) {
+    yamlContent = yamlContent.replace(/^(\s*-)(\s*"[^"]+")(\s*-\s*.*)$/gm, '$1$2');
+  }
+  
+  return yamlContent;
+}
+
+module.exports = {
+  extractYamlFromAgent
+};

tools/update-expansion-version.js

@@ -22,8 +22,8 @@ if (!/^\d+\.\d+\.\d+$/.test(newVersion)) {
 
 async function updateVersion() {
   try {
-    // Update in config.yml
-    const configPath = path.join(__dirname, '..', 'expansion-packs', packId, 'config.yml');
+    // Update in config.yaml
+    const configPath = path.join(__dirname, '..', 'expansion-packs', packId, 'config.yaml');
     
     if (!fs.existsSync(configPath)) {
       console.error(`Error: Expansion pack '${packId}' not found`);
@@ -39,7 +39,7 @@ async function updateVersion() {
     const updatedYaml = yaml.dump(config, { indent: 2 });
     fs.writeFileSync(configPath, updatedYaml);
     
-    console.log(`✓ Updated ${packId}/config.yml: ${oldVersion} → ${newVersion}`);
+    console.log(`✓ Updated ${packId}/config.yaml: ${oldVersion} → ${newVersion}`);
     console.log(`\n✓ Successfully updated ${packId} to version ${newVersion}`);
     console.log('\nNext steps:');
     console.log('1. Test the changes');

tools/yaml-format.js

@@ -197,7 +197,7 @@ async function main() {
       let changed = false;
       if (ext === '.md') {
         changed = await processMarkdownFile(filePath);
-      } else if (ext === '.yml' || ext === '.yaml' || basename.includes('roomodes') || basename.includes('.yml') || basename.includes('.yaml')) {
+      } else if (ext === '.yaml' || ext === '.yml' || basename.includes('roomodes') || basename.includes('.yaml') || basename.includes('.yml')) {
         // Handle YAML files and special cases like .roomodes
         changed = await processYamlFile(filePath);