chore(release): 4.12.0 [skip ci]

# [4.12.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.11.0...v4.12.0) (2025-06-23)

### Features

* **dev-agent:** add quality gates to prevent task completion with failing validations ([#261](https://github.com/bmadcode/BMAD-METHOD/issues/261)) ([45110ff](45110ffffe))

.vscode/settings.json

@@ -24,6 +24,7 @@
 		"Immer",
 		"implementability",
 		"Inclusivity",
+		"kayvan",
 		"Luxon",
 		"MERN",
 		"mgmt",

CHANGELOG.md

@@ -1,3 +1,71 @@
+# [4.12.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.11.0...v4.12.0) (2025-06-23)
+
+
+### Features
+
+* **dev-agent:** add quality gates to prevent task completion with failing validations ([#261](https://github.com/bmadcode/BMAD-METHOD/issues/261)) ([45110ff](https://github.com/bmadcode/BMAD-METHOD/commit/45110ffffe6d29cc08e227e22a901892185dfbd2))
+
+# [4.11.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.3...v4.11.0) (2025-06-21)
+
+
+### Bug Fixes
+
+* resolve web bundles directory path when using relative paths in NPX installer ([5c8485d](https://github.com/bmadcode/BMAD-METHOD/commit/5c8485d09ffec60ad4965ced62f4595890cb7535))
+
+
+### Features
+
+* add markdown-tree integration for document sharding ([540578b](https://github.com/bmadcode/BMAD-METHOD/commit/540578b39d1815e41e11f0e87545de3f09ee54e1))
+
+## [4.10.3](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.2...v4.10.3) (2025-06-20)
+
+
+### Bug Fixes
+
+* bundle update ([2cf3ba1](https://github.com/bmadcode/BMAD-METHOD/commit/2cf3ba1ab8dd7e52584bef16a96e65e7d2513c4f))
+
+## [4.10.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.1...v4.10.2) (2025-06-20)
+
+
+### Bug Fixes
+
+* file formatting ([c78a35f](https://github.com/bmadcode/BMAD-METHOD/commit/c78a35f547459b07a15d94c827ec05921cd21571))
+
+## [4.10.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.10.0...v4.10.1) (2025-06-20)
+
+
+### Bug Fixes
+
+* SM sometimes would skip the rest of the epic stories, fixed ([1148b32](https://github.com/bmadcode/BMAD-METHOD/commit/1148b32fa97586d2f86d07a70ffbf9bb8c327261))
+
+# [4.10.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.9.2...v4.10.0) (2025-06-19)
+
+
+### Features
+
+* Core Config and doc sharding is now optional in v4 ([ff6112d](https://github.com/bmadcode/BMAD-METHOD/commit/ff6112d6c2f822ed22c75046f5a14f05e36041c2))
+
+## [4.9.2](https://github.com/bmadcode/BMAD-METHOD/compare/v4.9.1...v4.9.2) (2025-06-19)
+
+
+### Bug Fixes
+
+* bad brownfield yml ([09d2ad6](https://github.com/bmadcode/BMAD-METHOD/commit/09d2ad6aea187996d0a2e1dff27d9bf7e3e6dc06))
+
+## [4.9.1](https://github.com/bmadcode/BMAD-METHOD/compare/v4.9.0...v4.9.1) (2025-06-19)
+
+
+### Bug Fixes
+
+* dist bundles updated ([d9a989d](https://github.com/bmadcode/BMAD-METHOD/commit/d9a989dbe50da62cf598afa07a8588229c56b69c))
+
+# [4.9.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.8.0...v4.9.0) (2025-06-19)
+
+
+### Features
+
+* dev can use debug log configured in core-config.yml ([0e5aaf0](https://github.com/bmadcode/BMAD-METHOD/commit/0e5aaf07bbc6fd9f2706ea26e35f5f38fd72147a))
+
 # [4.8.0](https://github.com/bmadcode/BMAD-METHOD/compare/v4.7.0...v4.8.0) (2025-06-19)
 
 

README.md

@@ -172,11 +172,37 @@ The upgrade process will:
 
 After upgrading:
 
-1. Review your documents in the `docs/` folder
-2. Use `@bmad-master` agent to run the `doc-migration-task` to align your documents with V4 templates
-3. If you have separate front-end and backend architecture docs, the migration task will help merge them into a unified `full-stack-architecture.md`
+1. Review your documents in the `docs/` folder - if you had a PRD or architecture in your old project, copy it from the backup to the docs folder if they are not there.
+2. Optionally run the `doc-migration-task` to align your documents with V4 templates - you can do this with your agent my saying something like: 'run {drag in task} against {drag prd or arch file from docs} to align with {drag the template from .bmad-core/templates/full-stack-architecture.md}
+3. If you have separate front-end and backend architecture docs you can modify step 2 to merge both into a single full stack architecture or separate Front and Back end.
 
-**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/`.
+The reason #2 and 3 are optional is because now BMad V4 makes sharding optional for the SM. See [Core Configuration](#-core-configuration-new-in-v4)
+
+**Note**: The agents in `.bmad-core/` fully replace the items in `bmad-agent/` - you can remove the backup folder versions.
+
+### 🔧 Core Configuration (NEW in V4)
+
+**Critical**: V4 introduces `bmad-core/core-config.yml` - a powerful configuration file that enables BMAD to work seamlessly with any project structure, whether it's V4-optimized or legacy. You can even now use non-standard PRDs and architectures!
+
+#### What is core-config.yml?
+
+This configuration file tells BMAD agents exactly where to find your project documents and how they're structured. It's the key to V4's flexibility and backwards compatibility.
+
+#### Key Features:
+
+- **Version Awareness**: Agents understand if your PRD/Architecture follows V4 conventions or earlier versions
+- **Flexible Document Locations**: Works whether your epics are embedded in PRD or properly sharded
+- **Developer Context**: Define which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting story implementation
+
+#### Why It Matters:
+
+- **Use BMAD with ANY project structure** - V3, V4, or custom layouts
+- **No forced migrations** - Keep your existing document organization
+- **Customize developer workflow** - Specify exactly which files provide context
+- **Seamless upgrades** - Start with V3 docs and gradually adopt V4 patterns
+
+See the [detailed core-config.yml guide](docs/user-guide.md#core-configuration-coreconfigyml) for configuration examples and best practices.
 
 ## Teams & Workflows
 

bmad-core/agents/bmad-orchestrator.md

@@ -99,6 +99,11 @@ loading:
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
   - Discover available workflows in the bundle at runtime
   - Understand each workflow's purpose, options, and decision points
@@ -112,6 +117,7 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - kb-mode-interaction
   data:
     - bmad-kb
   utils:

bmad-core/agents/dev.md

@@ -14,6 +14,13 @@ agent:
   whenToUse: "Use for code implementation, debugging, refactoring, and development best practices"
   customization:
 
+startup:
+  - Announce: Greet the user with your name and role, and inform of the *help command.
+  - CRITICAL: Load .bmad-core/core-config.yml and read devLoadAlwaysFiles list and devDebugLog values
+  - CRITICAL: Load ONLY files specified in devLoadAlwaysFiles. If any missing, inform user but continue
+  - CRITICAL: Do NOT load any story files during startup unless user requested you do
+  - CRITICAL: Do NOT begin development until told to proceed
+
 persona:
   role: Expert Senior Software Engineer & Implementation Specialist
   style: Extremely concise, pragmatic, detail-oriented, solution-focused
@@ -22,50 +29,32 @@ persona:
 
 core_principles:
   - CRITICAL: Story-Centric - Story has ALL info. NEVER load PRD/architecture/other docs files unless explicitly directed in dev notes
-  - CRITICAL: Config-Based Loading - MUST load .bmad-core/core-config.yml at startup, then load ONLY files listed in devLoadAlwaysFiles. Inform user of missing files but continue
-  - CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
-  - Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
+  - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
   - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
-  - Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
+  - Quality Gate Discipline - NEVER complete tasks with failing automated validations
+  - Debug Log Discipline - Log temp changes to md table in devDebugLog. Revert after fix.
   - Block Only When Critical - HALT for: missing approval/ambiguous reqs/3 failures/missing config
   - Code Excellence - Clean, secure, maintainable code per loaded standards
   - Numbered Options - Always use numbered lists when presenting choices
 
-startup:
-  - Announce: Greet the user with your name and role, and inform of the *help command.
-  - CRITICAL: Load .bmad-core/core-config.yml and read devLoadAlwaysFiles list
-  - 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 scan docs/stories/ directory automatically
-  - CRITICAL: Do NOT begin any tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load story files and begin work when explicitly requested by user
-
 commands:  # All commands require * prefix when used (e.g., *help)
   - help: Show numbered list of the following commands to allow selection
-  - chat-mode: Conversational mode for development discussions
   - run-tests: Execute linting and tests
-  - lint: Run linting only
-  - dod-check: Run story-dod-checklist
-  - status: Show task progress
   - debug-log: Show debug entries
   - complete-story: Finalize to "Review"
   - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
 
 task-execution:
-  flow: "Read task→Implement→Write tests→Pass tests→Update [x]→Next task"
-
+  flow: "Read task→Implement→Write tests→Execute validations→Only if ALL pass→Update [x]→Next task"
   updates-ONLY:
     - "Checkboxes: [ ] not started | [-] in progress | [x] complete"
     - "Debug Log: | Task | File | Change | Reverted? |"
     - "Completion Notes: Deviations only, <50 words"
     - "Change Log: Requirement changes only"
-
-  blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config"
-
-  done: "Code matches reqs + Tests pass + Follows standards + No lint errors"
-
-  completion: "All [x]→Lint→Tests(100%)→Integration(if noted)→Coverage(80%+)→E2E(if noted)→DoD→Summary→HALT"
+  blocking: "Unapproved deps | Ambiguous after story check | 3 failures | Missing config | Failing validations"
+  done: "Code matches reqs + All validations pass + Follows standards"
+  completion: "All [x]→Validations pass→Integration(if noted)→E2E(if noted)→DoD→Summary→HALT"
 
 dependencies:
   tasks:

bmad-core/core-config.yml

@@ -1,24 +1,20 @@
-core-project-information:
-  dev-story-location: docs/stories # alternate could be .ai/stories if preferred for example
-  prd:
-    prd-file: docs/prd.md
-    prdVersion: v4
-    prdSharded: true
-    prdShardedLocation: docs/prd
-    epicFilePattern: epic-{n}*.md
-  architecture:
-    architecture-file: docs/architecture.md
-    architectureVersion: v4
-    architectureSharded: true
-    architectureShardedLocation: docs/architecture
-  # if you have a front-end architecture document, uncomment the following and validate the file path
-  # front-end-architecture:
-  #   front-end-architecture-file: docs/front-end-architecture.md
-  #   architectureVersion: v4
-  #   architectureSharded: true
-  #   architectureShardedLocation: docs/architecture
-  customTechnicalDocuments: null # list other documents only if you want the SM to read them when creating stories
-  devLoadAlwaysFiles:
-    - docs/architecture/coding-standards.md
-    - docs/architecture/tech-stack.md
-    - docs/architecture/project-structure.md
+markdownExploder: true
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v4
+  prdSharded: true
+  prdShardedLocation: docs/prd
+  epicFilePattern: epic-{n}*.md
+architecture:
+  architectureFile: docs/architecture.md
+  architectureVersion: v4
+  architectureSharded: true
+  architectureShardedLocation: docs/architecture
+customTechnicalDocuments: null
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/source-tree.md
+devDebugLog: .ai/debug-log.md
+devStoryLocation: docs/stories
+agentCoreDump: .ai/core-dump{n}.md

bmad-core/data/bmad-kb.md

@@ -66,6 +66,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing

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

@@ -17,14 +17,14 @@ To identify the next logical story based on project progress and epic definition
     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:
-  - `dev-story-location`: Where to save story files
+  - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
-  - `prd.prd-file`: Location of monolithic PRD (if not sharded)
+  - `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.architecture-file`: Location of monolithic architecture
+  - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
 
 ### 1. Identify Next Story for Preparation
@@ -33,11 +33,11 @@ To identify the next logical story based on project progress and epic definition
 
 - Based on `prdSharded` from config:
   - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
-  - **If `prdSharded: false`**: Load the full PRD from `prd-file` and extract epics from section headings (## Epic N or ### Epic N)
+  - **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 `dev-story-location` from config (e.g., `docs/stories/`) for existing story files
+- 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).
@@ -57,12 +57,40 @@ To identify the next logical story based on project progress and epic definition
     ```
 
   - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}*.md`, then `epic-{lastEpicNum + 2}*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.
 
 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
-- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
 
 ### 2. Gather Core Story Requirements (from Epic)
@@ -98,13 +126,13 @@ Based on configuration loaded in Step 0:
   - Follow the structured reading order in section 4.2 below
   
 - **If `architectureVersion: v4` and `architectureSharded: false`**:
-  - Load the monolithic architecture from `architecture-file`
+  - 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 `architecture-file` for relevant sections
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
 
 #### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
 
@@ -161,7 +189,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 
 ### 6. Populate Story Template with Full Context
 
-- Create a new story file: `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config).
+- 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}`
@@ -208,7 +236,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
-- Save the story file to `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config)
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)
 
 ### 9. Report Completion
 

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

@@ -0,0 +1,70 @@
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+Announce entering KB mode with a brief, friendly introduction:
+
+"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+
+### 2. Present Topic Areas
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: *kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]

bmad-core/tasks/shard-doc.md

@@ -6,9 +6,27 @@
 - Create a folder structure to organize the sharded documents
 - Maintain all content integrity including code blocks, diagrams, and markdown formatting
 
-## Recommended Method: @kayvan/markdown-tree-parser
+## Primary Method: Automatic with markdown-tree
 
-[[LLM: First, suggest the user install and use the @kayvan/markdown-tree-parser tool if the md-tree command is unavailable so we can have the best performance and reliable document sharding. Let the user know this will save cost of having the LLM to the expensive sharding operation. Give instructions for MPV NPX and PNPM global installs.]]
+[[LLM: First, check if markdownExploder is set to true in bmad-core/core-config.yml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+
+If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
+
+If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
+
+1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+2. Or set markdownExploder to false in bmad-core/core-config.yml
+
+**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
+
+If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
+
+1. Set markdownExploder to true in bmad-core/core-config.yml
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]
 
 ### Installation and Usage
 
@@ -41,19 +59,19 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
 
 ---
 
-## Manual Method (if @kayvan/markdown-tree-parser is not available)
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
 
 [[LLM: Only proceed with the manual instructions below if the user cannot or does not want to use @kayvan/markdown-tree-parser.]]
 
 ### Task Instructions
 
-### 1. Identify Document and Target Location
+1. Identify Document and Target Location
 
 - Determine which document to shard (user-provided path)
 - Create a new folder under `docs/` with the same name as the document (without extension)
 - Example: `docs/prd.md` → create folder `docs/prd/`
 
-### 2. Parse and Extract Sections
+2. Parse and Extract Sections
 
 [[LLM: When sharding the document:
 
@@ -63,7 +81,7 @@ If the user has @kayvan/markdown-tree-parser installed, use it and skip the manu
    - Extract the section heading and ALL content until the next level 2 section
    - Include all subsections, code blocks, diagrams, lists, tables, etc.
    - Be extremely careful with:
-     - Fenced code blocks (```) - ensure you capture the full block including closing backticks
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
      - Mermaid diagrams - preserve the complete diagram syntax
      - Nested markdown elements
      - Multi-line content that might contain ## inside code blocks
@@ -82,7 +100,7 @@ For each extracted section:
 
 2. **Adjust heading levels**:
 
-   - The level 2 heading becomes level 1 (# instead of ##)
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
    - All subsection levels decrease by 1:
 
    ```txt
@@ -112,7 +130,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 

bmad-core/templates/architecture-tmpl.md

@@ -357,7 +357,7 @@ servers:
       '[object Object]': null
     description:
       '[object Object]': null
-```text
+```
 
 ^^/CONDITION: has_rest_api^^
 
@@ -420,7 +420,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text
 
 @{example: monorepo-structure}
 project-root/
@@ -432,6 +431,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
 @{/example}
+```
 
 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]
 

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

@@ -226,7 +226,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{component_interaction_diagram}}
-```text
+```
 
 ## API Design and Integration
 
@@ -266,7 +266,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]
 
 ```json
 {{response_schema}}
-```text
+```
 
 <</REPEAT>>
 

bmad-core/templates/front-end-spec-tmpl.md

@@ -78,7 +78,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{sitemap_diagram}}
-```text
+```
 
 @{example: sitemap}
 

bmad-core/utils/workflow-management.md

@@ -47,7 +47,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -73,7 +73,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -89,7 +89,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -159,7 +159,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -185,7 +185,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 

bmad-core/workflows/brownfield-service.yml

@@ -14,7 +14,7 @@ workflow:
 
   sequence:
     - step: service_analysis
-     agent: architect
+      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."

dist/agents/analyst.txt

@@ -1679,6 +1679,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing

dist/agents/architect.txt

@@ -1335,7 +1335,7 @@ servers:
       '[object Object]': null
     description:
       '[object Object]': null
-```text
+```
 
 ^^/CONDITION: has_rest_api^^
 
@@ -1398,7 +1398,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text
 
 @{example: monorepo-structure}
 project-root/
@@ -1410,6 +1409,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
 @{/example}
+```
 
 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]
 
@@ -3182,7 +3182,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{component_interaction_diagram}}
-```text
+```
 
 ## API Design and Integration
 
@@ -3222,7 +3222,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]
 
 ```json
 {{response_schema}}
-```text
+```
 
 <</REPEAT>>
 

dist/agents/bmad-master.txt

@@ -1734,14 +1734,14 @@ To identify the next logical story based on project progress and epic definition
     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:
-  - `dev-story-location`: Where to save story files
+  - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
-  - `prd.prd-file`: Location of monolithic PRD (if not sharded)
+  - `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.architecture-file`: Location of monolithic architecture
+  - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
 
 ### 1. Identify Next Story for Preparation
@@ -1750,11 +1750,11 @@ To identify the next logical story based on project progress and epic definition
 
 - Based on `prdSharded` from config:
   - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
-  - **If `prdSharded: false`**: Load the full PRD from `prd-file` and extract epics from section headings (## Epic N or ### Epic N)
+  - **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 `dev-story-location` from config (e.g., `docs/stories/`) for existing story files
+- 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).
@@ -1774,12 +1774,40 @@ To identify the next logical story based on project progress and epic definition
     ```
 
   - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}*.md`, then `epic-{lastEpicNum + 2}*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.
 
 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
-- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
 
 ### 2. Gather Core Story Requirements (from Epic)
@@ -1815,13 +1843,13 @@ Based on configuration loaded in Step 0:
   - Follow the structured reading order in section 4.2 below
   
 - **If `architectureVersion: v4` and `architectureSharded: false`**:
-  - Load the monolithic architecture from `architecture-file`
+  - 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 `architecture-file` for relevant sections
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
 
 #### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
 
@@ -1878,7 +1906,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 
 ### 6. Populate Story Template with Full Context
 
-- Create a new story file: `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config).
+- 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}`
@@ -1925,7 +1953,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
-- Save the story file to `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config)
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)
 
 ### 9. Report Completion
 
@@ -2392,7 +2420,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 
@@ -2813,7 +2841,7 @@ servers:
       '[object Object]': null
     description:
       '[object Object]': null
-```text
+```
 
 ^^/CONDITION: has_rest_api^^
 
@@ -2876,7 +2904,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text
 
 @{example: monorepo-structure}
 project-root/
@@ -2888,6 +2915,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
 @{/example}
+```
 
 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]
 
@@ -3461,7 +3489,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{component_interaction_diagram}}
-```text
+```
 
 ## API Design and Integration
 
@@ -3501,7 +3529,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]
 
 ```json
 {{response_schema}}
-```text
+```
 
 <</REPEAT>>
 
@@ -4577,7 +4605,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{sitemap_diagram}}
-```text
+```
 
 @{example: sitemap}
 
@@ -8486,6 +8514,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -8933,7 +9019,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -8959,7 +9045,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -8975,7 +9061,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -9045,7 +9131,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -9071,7 +9157,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 

dist/agents/bmad-orchestrator.txt

@@ -136,6 +136,11 @@ loading:
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
   - Discover available workflows in the bundle at runtime
   - Understand each workflow's purpose, options, and decision points
@@ -149,6 +154,7 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - kb-mode-interaction
   data:
     - bmad-kb
   utils:
@@ -329,6 +335,79 @@ If template specifies a checklist:
 - Template markup is for AI processing only - never expose to users
 ==================== END: tasks#create-doc ====================
 
+==================== START: tasks#kb-mode-interaction ====================
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+Announce entering KB mode with a brief, friendly introduction:
+
+"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+
+### 2. Present Topic Areas
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: *kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
+==================== END: tasks#kb-mode-interaction ====================
+
 ==================== START: data#bmad-kb ====================
 # BMAD Knowledge Base
 
@@ -398,6 +477,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -810,7 +947,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -836,7 +973,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -852,7 +989,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -922,7 +1059,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -948,7 +1085,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 

dist/agents/dev.txt

@@ -51,6 +51,12 @@ agent:
   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
@@ -58,30 +64,16 @@ persona:
   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: Config-Based Loading - MUST load .bmad-core/core-config.yml at startup, then load ONLY files listed in devLoadAlwaysFiles. Inform user of missing files but continue
-  - CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
-  - Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
+  - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
   - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
-  - Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
+  - 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
-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
-  - 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 scan docs/stories/ directory automatically
-  - CRITICAL: Do NOT begin any tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load story files and begin work when explicitly requested by user
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - chat-mode: Conversational mode for development discussions
   - run-tests: Execute linting and tests
-  - lint: Run linting only
-  - dod-check: Run story-dod-checklist
-  - status: Show task progress
   - debug-log: Show debug entries
   - complete-story: Finalize to "Review"
   - exit: Say goodbye as the Developer, and then abandon inhabiting this persona

dist/agents/pm.txt

@@ -1084,7 +1084,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 

dist/agents/po.txt

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

dist/agents/sm.txt

@@ -109,14 +109,14 @@ To identify the next logical story based on project progress and epic definition
     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:
-  - `dev-story-location`: Where to save story files
+  - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
-  - `prd.prd-file`: Location of monolithic PRD (if not sharded)
+  - `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.architecture-file`: Location of monolithic architecture
+  - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
 
 ### 1. Identify Next Story for Preparation
@@ -125,11 +125,11 @@ To identify the next logical story based on project progress and epic definition
 
 - Based on `prdSharded` from config:
   - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
-  - **If `prdSharded: false`**: Load the full PRD from `prd-file` and extract epics from section headings (## Epic N or ### Epic N)
+  - **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 `dev-story-location` from config (e.g., `docs/stories/`) for existing story files
+- 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).
@@ -149,12 +149,40 @@ To identify the next logical story based on project progress and epic definition
     ```
 
   - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}*.md`, then `epic-{lastEpicNum + 2}*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.
 
 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
-- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
 
 ### 2. Gather Core Story Requirements (from Epic)
@@ -190,13 +218,13 @@ Based on configuration loaded in Step 0:
   - Follow the structured reading order in section 4.2 below
   
 - **If `architectureVersion: v4` and `architectureSharded: false`**:
-  - Load the monolithic architecture from `architecture-file`
+  - 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 `architecture-file` for relevant sections
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
 
 #### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
 
@@ -253,7 +281,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 
 ### 6. Populate Story Template with Full Context
 
-- Create a new story file: `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config).
+- 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}`
@@ -300,7 +328,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
-- Save the story file to `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config)
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)
 
 ### 9. Report Completion
 

dist/agents/ux-expert.txt

@@ -717,7 +717,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{sitemap_diagram}}
-```text
+```
 
 @{example: sitemap}
 

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

@@ -288,6 +288,7 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Begin by understanding the game design context and goals. Ask clarifying questions if needed to determine the best approach for game-specific ideation.]]
 
 1. **Establish Game Context**
+
    - Understand the game genre or opportunity area
    - Identify target audience and platform constraints
    - Determine session goals (concept exploration vs. mechanic refinement)
@@ -443,26 +444,31 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Help user select appropriate techniques based on their specific game design needs.]]
 
 **For Initial Game Concepts:**
+
 - What If Game Scenarios
 - Cross-Genre Fusion
 - Emotion-First Design
 
 **For Stuck/Blocked Creativity:**
+
 - Player Motivation Reversal
 - Constraint-Based Creativity
 - Genre Expectation Subversion
 
 **For Mechanic Development:**
+
 - SCAMPER for Game Mechanics
 - Core Loop Deconstruction
 - Player Agency Spectrum
 
 **For Player Experience:**
+
 - Player Archetype Brainstorming
 - Emotion-First Design
 - Accessibility-First Innovation
 
 **For World Building:**
+
 - Environmental Storytelling
 - Player-Generated Narrative
 - Platform-Specific Design
@@ -472,16 +478,19 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Guide the brainstorming session with appropriate pacing for game design exploration.]]
 
 1. **Inspiration Phase** (10-15 min)
+
    - Reference existing games and mechanics
    - Explore player experiences and emotions
    - Gather visual and thematic inspiration
 
 2. **Divergent Exploration** (25-35 min)
+
    - Generate many game concepts or mechanics
    - Use expansion and fusion techniques
    - Encourage wild and impossible ideas
 
 3. **Player-Centered Filtering** (15-20 min)
+
    - Consider target audience reactions
    - Evaluate emotional impact and engagement
    - Group ideas by player experience goals
@@ -496,6 +505,7 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Present brainstorming results in a format useful for game development.]]
 
 **Session Summary:**
+
 - Techniques used and focus areas
 - Total concepts/mechanics generated
 - Key themes and patterns identified
@@ -511,21 +521,25 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 **Development Readiness:**
 
 **Prototype-Ready Ideas:**
+
 - Ideas that can be tested immediately
 - Minimum viable implementations
 - Quick validation approaches
 
 **Research-Required Ideas:**
+
 - Concepts needing technical investigation
 - Player testing and market research needs
 - Competitive analysis requirements
 
 **Future Innovation Pipeline:**
+
 - Ideas requiring significant development
 - Technology-dependent concepts
 - Market timing considerations
 
 **Next Steps:**
+
 - Which concepts to prototype first
 - Recommended research areas
 - Suggested playtesting approaches
@@ -534,24 +548,28 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 ## Game Design Specific Considerations
 
 ### Platform and Audience Awareness
+
 - Always consider target platform limitations and advantages
 - Keep target audience preferences and expectations in mind
 - Balance innovation with familiar game design patterns
 - Consider monetization and business model implications
 
 ### Rapid Prototyping Mindset
+
 - Focus on ideas that can be quickly tested
 - Emphasize core mechanics over complex features
 - Design for iteration and player feedback
 - Consider digital and paper prototyping approaches
 
 ### Player Psychology Integration
+
 - Understand motivation and engagement drivers
 - Consider learning curves and skill development
 - Design for different play session lengths
 - Balance challenge and reward appropriately
 
 ### Technical Feasibility
+
 - Keep development resources and timeline in mind
 - Consider art and audio asset requirements
 - Think about performance and optimization needs
@@ -979,6 +997,7 @@ This elicitation task is specifically designed for game development and should b
 - **Platform Considerations**: When adapting designs for different devices and input methods
 
 The questions and perspectives offered should always consider:
+
 - Player psychology and motivation
 - Technical feasibility with Phaser 3 and TypeScript
 - Performance implications for 60 FPS targets
@@ -1042,6 +1061,7 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Define the 30-60 second loop that players will repeat. Be specific about timing and player actions.]]
 
 **Primary Loop ({{duration}} seconds):**
+
 1. {{action_1}} ({{time_1}}s)
 2. {{action_2}} ({{time_2}}s)
 3. {{action_3}} ({{time_3}}s)
@@ -1052,10 +1072,12 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Clearly define success and failure states]]
 
 **Victory Conditions:**
+
 - {{win_condition_1}}
 - {{win_condition_2}}
 
 **Failure States:**
+
 - {{loss_condition_1}}
 - {{loss_condition_2}}
 
@@ -1076,6 +1098,7 @@ If available, review any provided documents or ask if any are optionally availab
 **System Response:** {{game_response}}
 
 **Implementation Notes:**
+
 - {{tech_requirement_1}}
 - {{tech_requirement_2}}
 - {{performance_consideration}}
@@ -1088,8 +1111,8 @@ If available, review any provided documents or ask if any are optionally availab
 
 [[LLM: Define all input methods for different platforms]]
 
-| Action | Desktop | Mobile | Gamepad |
-|--------|---------|--------|---------|
+| Action       | Desktop | Mobile      | Gamepad    |
+| ------------ | ------- | ----------- | ---------- |
 | {{action_1}} | {{key}} | {{gesture}} | {{button}} |
 | {{action_2}} | {{key}} | {{gesture}} | {{button}} |
 
@@ -1102,6 +1125,7 @@ If available, review any provided documents or ask if any are optionally availab
 **Progression Type:** {{linear|branching|metroidvania}}
 
 **Key Milestones:**
+
 1. **{{milestone_1}}** - {{unlock_description}}
 2. **{{milestone_2}}** - {{unlock_description}}
 3. **{{milestone_3}}** - {{unlock_description}}
@@ -1121,9 +1145,9 @@ If available, review any provided documents or ask if any are optionally availab
 
 [[LLM: Define any in-game currencies, resources, or collectibles]]
 
-| Resource | Earn Rate | Spend Rate | Purpose | Cap |
-|----------|-----------|------------|---------|-----|
-| {{resource_1}} | {{rate}} | {{rate}} | {{use}} | {{max}} |
+| Resource       | Earn Rate | Spend Rate | Purpose | Cap     |
+| -------------- | --------- | ---------- | ------- | ------- |
+| {{resource_1}} | {{rate}}  | {{rate}}   | {{use}} | {{max}} |
 
 ^^/CONDITION: has_economy^^
 
@@ -1143,6 +1167,7 @@ If available, review any provided documents or ask if any are optionally availab
 **Difficulty:** {{relative_difficulty}}
 
 **Structure Template:**
+
 - Introduction: {{intro_description}}
 - Challenge: {{main_challenge}}
 - Resolution: {{completion_requirement}}
@@ -1169,11 +1194,13 @@ If available, review any provided documents or ask if any are optionally availab
 ### Platform Specific
 
 **Desktop:**
+
 - Resolution: {{min_resolution}} - {{max_resolution}}
 - Input: Keyboard, Mouse, Gamepad
 - Browser: Chrome 80+, Firefox 75+, Safari 13+
 
 **Mobile:**
+
 - Resolution: {{mobile_min}} - {{mobile_max}}
 - Input: Touch, Tilt (optional)
 - OS: iOS 13+, Android 8+
@@ -1183,12 +1210,14 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Define asset specifications for the art and audio teams]]
 
 **Visual Assets:**
+
 - Art Style: {{style_description}}
 - Color Palette: {{color_specification}}
 - Animation: {{animation_requirements}}
 - UI Resolution: {{ui_specs}}
 
 **Audio Assets:**
+
 - Music Style: {{music_genre}}
 - Sound Effects: {{sfx_requirements}}
 - Voice Acting: {{voice_needs}}
@@ -1200,6 +1229,7 @@ If available, review any provided documents or ask if any are optionally availab
 ### Engine Configuration
 
 **Phaser 3 Setup:**
+
 - TypeScript: Strict mode enabled
 - Physics: {{physics_system}} (Arcade/Matter)
 - Renderer: WebGL with Canvas fallback
@@ -1208,6 +1238,7 @@ If available, review any provided documents or ask if any are optionally availab
 ### Code Architecture
 
 **Required Systems:**
+
 - Scene Management
 - State Management
 - Asset Loading
@@ -1219,6 +1250,7 @@ If available, review any provided documents or ask if any are optionally availab
 ### Data Management
 
 **Save Data:**
+
 - Progress tracking
 - Settings persistence
 - Statistics collection
@@ -1231,12 +1263,14 @@ If available, review any provided documents or ask if any are optionally availab
 ### Phase 1: Core Systems ({{duration}})
 
 **Epic: Foundation**
+
 - Engine setup and configuration
 - Basic scene management
 - Core input handling
 - Asset loading pipeline
 
 **Epic: Core Mechanics**
+
 - {{primary_mechanic}} implementation
 - Basic physics and collision
 - Player controller
@@ -1244,11 +1278,13 @@ If available, review any provided documents or ask if any are optionally availab
 ### Phase 2: Gameplay Features ({{duration}})
 
 **Epic: Game Systems**
+
 - {{mechanic_2}} implementation
 - {{mechanic_3}} implementation
 - Game state management
 
 **Epic: Content Creation**
+
 - Level loading system
 - First playable levels
 - Basic UI implementation
@@ -1256,11 +1292,13 @@ If available, review any provided documents or ask if any are optionally availab
 ### Phase 3: Polish & Optimization ({{duration}})
 
 **Epic: Performance**
+
 - Optimization and profiling
 - Mobile platform testing
 - Memory management
 
 **Epic: User Experience**
+
 - Audio implementation
 - Visual effects and polish
 - Final UI/UX refinement
@@ -1270,12 +1308,14 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Define measurable goals for the game]]
 
 **Technical Metrics:**
+
 - Frame rate: {{fps_target}}
 - Load time: {{load_target}}
 - Crash rate: <{{crash_threshold}}%
 - Memory usage: <{{memory_target}}MB
 
 **Gameplay Metrics:**
+
 - Tutorial completion: {{completion_rate}}%
 - Average session: {{session_length}} minutes
 - Level completion: {{level_completion}}%
@@ -1366,19 +1406,23 @@ This framework ensures consistency across all levels while providing flexibility
 **Difficulty Range:** {{difficulty_scale}}
 
 **Key Mechanics Featured:**
+
 - {{mechanic_1}} - {{usage_description}}
 - {{mechanic_2}} - {{usage_description}}
 
 **Player Objectives:**
+
 - Primary: {{primary_objective}}
 - Secondary: {{secondary_objective}}
 - Hidden: {{secret_objective}}
 
 **Success Criteria:**
+
 - {{completion_requirement_1}}
 - {{completion_requirement_2}}
 
 **Technical Requirements:**
+
 - Maximum entities: {{entity_limit}}
 - Performance target: {{fps_target}} FPS
 - Memory budget: {{memory_limit}}MB
@@ -1399,6 +1443,7 @@ This framework ensures consistency across all levels while providing flexibility
 **Total Level Count:** {{number}}
 
 **World Breakdown:**
+
 - World 1: {{level_count}} levels - {{theme}} - {{difficulty_range}}
 - World 2: {{level_count}} levels - {{theme}} - {{difficulty_range}}
 - World 3: {{level_count}} levels - {{theme}} - {{difficulty_range}}
@@ -1408,7 +1453,8 @@ This framework ensures consistency across all levels while providing flexibility
 [[LLM: Define how challenge increases across the game]]
 
 **Progression Curve:**
-```text
+
+````text
 Difficulty
     ^     ___/```
     |    /
@@ -1418,9 +1464,10 @@ Difficulty
     |/     /
     +-----------> Level Number
    Tutorial  Early  Mid  Late
-```text
+````
 
 **Scaling Parameters:**
+
 - Enemy count: {{start_count}} → {{end_count}}
 - Enemy difficulty: {{start_diff}} → {{end_diff}}
 - Level complexity: {{start_complex}} → {{end_complex}}
@@ -1431,6 +1478,7 @@ Difficulty
 [[LLM: Define how players access new levels]]
 
 **Progression Gates:**
+
 - Linear progression: Complete previous level
 - Star requirements: {{star_count}} stars to unlock
 - Skill gates: Demonstrate {{skill_requirement}}
@@ -1445,14 +1493,17 @@ Difficulty
 [[LLM: Define all environmental components that can be used in levels]]
 
 **Terrain Types:**
+
 - {{terrain_1}}: {{properties_and_usage}}
 - {{terrain_2}}: {{properties_and_usage}}
 
 **Interactive Objects:**
+
 - {{object_1}}: {{behavior_and_purpose}}
 - {{object_2}}: {{behavior_and_purpose}}
 
 **Hazards and Obstacles:**
+
 - {{hazard_1}}: {{damage_and_behavior}}
 - {{hazard_2}}: {{damage_and_behavior}}
 
@@ -1461,15 +1512,18 @@ Difficulty
 [[LLM: Define all collectible items and their placement rules]]
 
 **Collectible Types:**
+
 - {{collectible_1}}: {{value_and_purpose}}
 - {{collectible_2}}: {{value_and_purpose}}
 
 **Placement Guidelines:**
+
 - Mandatory collectibles: {{placement_rules}}
 - Optional collectibles: {{placement_rules}}
 - Secret collectibles: {{placement_rules}}
 
 **Reward Distribution:**
+
 - Easy to find: {{percentage}}%
 - Moderate challenge: {{percentage}}%
 - High skill required: {{percentage}}%
@@ -1479,15 +1533,18 @@ Difficulty
 [[LLM: Define how enemies should be placed and balanced in levels]]
 
 **Enemy Categories:**
+
 - {{enemy_type_1}}: {{behavior_and_usage}}
 - {{enemy_type_2}}: {{behavior_and_usage}}
 
 **Placement Principles:**
+
 - Introduction encounters: {{guideline}}
 - Standard encounters: {{guideline}}
 - Challenge encounters: {{guideline}}
 
 **Difficulty Scaling:**
+
 - Enemy count progression: {{scaling_rule}}
 - Enemy type introduction: {{pacing_rule}}
 - Encounter complexity: {{complexity_rule}}
@@ -1499,12 +1556,14 @@ Difficulty
 ### Level Layout Principles
 
 **Spatial Design:**
+
 - Grid size: {{grid_dimensions}}
 - Minimum path width: {{width_units}}
 - Maximum vertical distance: {{height_units}}
 - Safe zones placement: {{safety_guidelines}}
 
 **Navigation Design:**
+
 - Clear path indication: {{visual_cues}}
 - Landmark placement: {{landmark_rules}}
 - Dead end avoidance: {{dead_end_policy}}
@@ -1515,11 +1574,13 @@ Difficulty
 [[LLM: Define how to control the rhythm and pace of gameplay within levels]]
 
 **Action Sequences:**
+
 - High intensity duration: {{max_duration}}
 - Rest period requirement: {{min_rest_time}}
 - Intensity variation: {{pacing_pattern}}
 
 **Learning Sequences:**
+
 - New mechanic introduction: {{teaching_method}}
 - Practice opportunity: {{practice_duration}}
 - Skill application: {{application_context}}
@@ -1529,12 +1590,14 @@ Difficulty
 [[LLM: Define how to create appropriate challenges for each level type]]
 
 **Challenge Types:**
+
 - Execution challenges: {{skill_requirements}}
 - Puzzle challenges: {{complexity_guidelines}}
 - Time challenges: {{time_pressure_rules}}
 - Resource challenges: {{resource_management}}
 
 **Difficulty Calibration:**
+
 - Skill check frequency: {{frequency_guidelines}}
 - Failure recovery: {{retry_mechanics}}
 - Hint system integration: {{help_system}}
@@ -1548,11 +1611,13 @@ Difficulty
 [[LLM: Define how level data should be structured for implementation]]
 
 **Level File Format:**
+
 - Data format: {{json|yaml|custom}}
 - File naming: `level_{{world}}_{{number}}.{{extension}}`
 - Data organization: {{structure_description}}
 
 **Required Data Fields:**
+
 ```json
 {
   "levelId": "{{unique_identifier}}",
@@ -1584,12 +1649,14 @@ Difficulty
 [[LLM: Define how level assets are organized and loaded]]
 
 **Tilemap Requirements:**
+
 - Tile size: {{tile_dimensions}}px
 - Tileset organization: {{tileset_structure}}
 - Layer organization: {{layer_system}}
 - Collision data: {{collision_format}}
 
 **Audio Integration:**
+
 - Background music: {{music_requirements}}
 - Ambient sounds: {{ambient_system}}
 - Dynamic audio: {{dynamic_audio_rules}}
@@ -1599,16 +1666,19 @@ Difficulty
 [[LLM: Define performance requirements for level systems]]
 
 **Entity Limits:**
+
 - Maximum active entities: {{entity_limit}}
 - Maximum particles: {{particle_limit}}
 - Maximum audio sources: {{audio_limit}}
 
 **Memory Management:**
+
 - Texture memory budget: {{texture_memory}}MB
 - Audio memory budget: {{audio_memory}}MB
 - Level loading time: <{{load_time}}s
 
 **Culling and LOD:**
+
 - Off-screen culling: {{culling_distance}}
 - Level-of-detail rules: {{lod_system}}
 - Asset streaming: {{streaming_requirements}}
@@ -1620,11 +1690,13 @@ Difficulty
 ### Automated Testing
 
 **Performance Testing:**
+
 - Frame rate validation: Maintain {{fps_target}} FPS
 - Memory usage monitoring: Stay under {{memory_limit}}MB
 - Loading time verification: Complete in <{{load_time}}s
 
 **Gameplay Testing:**
+
 - Completion path validation: All objectives achievable
 - Collectible accessibility: All items reachable
 - Softlock prevention: No unwinnable states
@@ -1632,6 +1704,7 @@ Difficulty
 ### Manual Testing Protocol
 
 **Playtesting Checklist:**
+
 - [ ] Level completes within target time range
 - [ ] All mechanics function correctly
 - [ ] Difficulty feels appropriate for level category
@@ -1639,6 +1712,7 @@ Difficulty
 - [ ] No exploits or sequence breaks (unless intended)
 
 **Player Experience Testing:**
+
 - [ ] Tutorial levels teach effectively
 - [ ] Challenge feels fair and rewarding
 - [ ] Flow and pacing maintain engagement
@@ -1647,12 +1721,14 @@ Difficulty
 ### Balance Validation
 
 **Metrics Collection:**
+
 - Completion rate: Target {{completion_percentage}}%
 - Average completion time: {{target_time}} ± {{variance}}
 - Death count per level: <{{max_deaths}}
 - Collectible discovery rate: {{discovery_percentage}}%
 
 **Iteration Guidelines:**
+
 - Adjustment criteria: {{criteria_for_changes}}
 - Testing sample size: {{minimum_testers}}
 - Validation period: {{testing_duration}}
@@ -1664,12 +1740,14 @@ Difficulty
 ### Design Phase
 
 **Concept Development:**
+
 1. Define level purpose and goals
 2. Create rough layout sketch
 3. Identify key mechanics and challenges
 4. Estimate difficulty and duration
 
 **Documentation Requirements:**
+
 - Level design brief
 - Layout diagrams
 - Mechanic integration notes
@@ -1678,6 +1756,7 @@ Difficulty
 ### Implementation Phase
 
 **Technical Implementation:**
+
 1. Create level data file
 2. Build tilemap and layout
 3. Place entities and objects
@@ -1685,6 +1764,7 @@ Difficulty
 5. Integrate audio and visual effects
 
 **Quality Assurance:**
+
 1. Automated testing execution
 2. Internal playtesting
 3. Performance validation
@@ -1693,12 +1773,14 @@ Difficulty
 ### Integration Phase
 
 **Game Integration:**
+
 1. Level progression integration
 2. Save system compatibility
 3. Analytics integration
 4. Achievement system integration
 
 **Final Validation:**
+
 1. Full game context testing
 2. Performance regression testing
 3. Platform compatibility verification
@@ -1709,18 +1791,21 @@ Difficulty
 [[LLM: Define how to measure level design success]]
 
 **Player Engagement:**
+
 - Level completion rate: {{target_rate}}%
 - Replay rate: {{replay_target}}%
 - Time spent per level: {{engagement_time}}
 - Player satisfaction scores: {{satisfaction_target}}/10
 
 **Technical Performance:**
+
 - Frame rate consistency: {{fps_consistency}}%
 - Loading time compliance: {{load_compliance}}%
 - Memory usage efficiency: {{memory_efficiency}}%
 - Crash rate: <{{crash_threshold}}%
 
 **Design Quality:**
+
 - Difficulty curve adherence: {{curve_accuracy}}
 - Mechanic integration effectiveness: {{integration_score}}
 - Player guidance clarity: {{guidance_score}}
@@ -1790,11 +1875,13 @@ This brief is typically created early in the ideation process, often after brain
 [[LLM: List the 3-5 most important gameplay mechanics that define the player experience]]
 
 **Core Mechanic 1: {{mechanic_name}}**
+
 - **Description:** {{how_it_works}}
 - **Player Value:** {{why_its_fun}}
 - **Implementation Scope:** {{complexity_estimate}}
 
 **Core Mechanic 2: {{mechanic_name}}**
+
 - **Description:** {{how_it_works}}
 - **Player Value:** {{why_its_fun}}
 - **Implementation Scope:** {{complexity_estimate}}
@@ -1821,10 +1908,12 @@ This brief is typically created early in the ideation process, often after brain
 ### Technical Constraints
 
 **Platform Requirements:**
+
 - Primary: {{platform_1}} - {{requirements}}
 - Secondary: {{platform_2}} - {{requirements}}
 
 **Technical Specifications:**
+
 - Engine: Phaser 3 + TypeScript
 - Performance Target: {{fps_target}} FPS on {{target_device}}
 - Memory Budget: <{{memory_limit}}MB
@@ -1855,6 +1944,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Inspiration Games
 
 **Primary References:**
+
 1. **{{reference_game_1}}** - {{what_we_learn_from_it}}
 2. **{{reference_game_2}}** - {{what_we_learn_from_it}}
 3. **{{reference_game_3}}** - {{what_we_learn_from_it}}
@@ -1862,6 +1952,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Competitive Analysis
 
 **Direct Competitors:**
+
 - {{competitor_1}}: {{strengths_and_weaknesses}}
 - {{competitor_2}}: {{strengths_and_weaknesses}}
 
@@ -1887,13 +1978,16 @@ This brief is typically created early in the ideation process, often after brain
 ### Content Categories
 
 **Core Content:**
+
 - {{content_type_1}}: {{quantity_and_description}}
 - {{content_type_2}}: {{quantity_and_description}}
 
 **Optional Content:**
+
 - {{optional_content_type}}: {{quantity_and_description}}
 
 **Replay Elements:**
+
 - {{replayability_features}}
 
 ### Difficulty and Accessibility
@@ -1931,23 +2025,23 @@ This brief is typically created early in the ideation process, often after brain
 
 ### Technical Risks
 
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|-------------|--------|-------------------|
-| {{technical_risk_1}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
-| {{technical_risk_2}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
+| Risk                 | Probability | Impact | Mitigation Strategy |
+| -------------------- | ----------- | ------ | ------------------- | ------ | --- | ----- | ----------------------- |
+| {{technical_risk_1}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
+| {{technical_risk_2}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
 
 ### Design Risks
 
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|-------------|--------|-------------------|
-| {{design_risk_1}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
-| {{design_risk_2}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
+| Risk              | Probability | Impact | Mitigation Strategy |
+| ----------------- | ----------- | ------ | ------------------- | ------ | --- | ----- | ----------------------- |
+| {{design_risk_1}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
+| {{design_risk_2}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
 
 ### Market Risks
 
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|-------------|--------|-------------------|
-| {{market_risk_1}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
+| Risk              | Probability | Impact | Mitigation Strategy |
+| ----------------- | ----------- | ------ | ------------------- | ------ | --- | ----- | ----------------------- |
+| {{market_risk_1}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
 
 ## Success Criteria
 
@@ -1956,11 +2050,13 @@ This brief is typically created early in the ideation process, often after brain
 ### Player Experience Metrics
 
 **Engagement Goals:**
+
 - Tutorial completion rate: >{{percentage}}%
 - Average session length: {{duration}} minutes
 - Player retention: D1 {{d1}}%, D7 {{d7}}%, D30 {{d30}}%
 
 **Quality Benchmarks:**
+
 - Player satisfaction: >{{rating}}/10
 - Completion rate: >{{percentage}}%
 - Technical performance: {{fps_target}} FPS consistent
@@ -1968,11 +2064,13 @@ This brief is typically created early in the ideation process, often after brain
 ### Development Metrics
 
 **Technical Targets:**
+
 - Zero critical bugs at launch
 - Performance targets met on all platforms
 - Load times under {{seconds}}s
 
 **Process Goals:**
+
 - Development timeline adherence
 - Feature scope completion
 - Quality assurance standards
@@ -1982,6 +2080,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Business Metrics
 
 **Commercial Goals:**
+
 - {{revenue_target}} in first {{time_period}}
 - {{user_acquisition_target}} players in first {{time_period}}
 - {{retention_target}} monthly active users
@@ -2001,16 +2100,19 @@ This brief is typically created early in the ideation process, often after brain
 ### Development Roadmap
 
 **Phase 1: Pre-Production** ({{duration}})
+
 - Detailed Game Design Document creation
 - Technical architecture planning
 - Art style exploration and pipeline setup
 
 **Phase 2: Prototype** ({{duration}})
+
 - Core mechanic implementation
 - Technical proof of concept
 - Initial playtesting and iteration
 
 **Phase 3: Production** ({{duration}})
+
 - Full feature development
 - Content creation and integration
 - Comprehensive testing and optimization
@@ -2018,6 +2120,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Documentation Pipeline
 
 **Required Documents:**
+
 1. Game Design Document (GDD) - {{target_completion}}
 2. Technical Architecture Document - {{target_completion}}
 3. Art Style Guide - {{target_completion}}
@@ -2026,10 +2129,12 @@ This brief is typically created early in the ideation process, often after brain
 ### Validation Plan
 
 **Concept Testing:**
+
 - {{validation_method_1}} - {{timeline}}
 - {{validation_method_2}} - {{timeline}}
 
 **Prototype Testing:**
+
 - {{testing_approach}} - {{timeline}}
 - {{feedback_collection_method}} - {{timeline}}
 
@@ -2061,6 +2166,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Document Completeness
 
 ### Executive Summary
+
 - [ ] **Core Concept** - Game concept is clearly explained in 2-3 sentences
 - [ ] **Target Audience** - Primary and secondary audiences defined with demographics
 - [ ] **Platform Requirements** - Technical platforms and requirements specified
@@ -2068,6 +2174,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Technical Foundation** - Phaser 3 + TypeScript requirements confirmed
 
 ### Game Design Foundation
+
 - [ ] **Game Pillars** - 3-5 core design pillars defined and actionable
 - [ ] **Core Gameplay Loop** - 30-60 second loop documented with specific timings
 - [ ] **Win/Loss Conditions** - Clear victory and failure states defined
@@ -2077,6 +2184,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Gameplay Mechanics
 
 ### Core Mechanics Documentation
+
 - [ ] **Primary Mechanics** - 3-5 core mechanics detailed with implementation notes
 - [ ] **Mechanic Integration** - How mechanics work together is clear
 - [ ] **Player Input** - All input methods specified for each platform
@@ -2084,6 +2192,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Performance Impact** - Performance considerations for each mechanic noted
 
 ### Controls and Interaction
+
 - [ ] **Multi-Platform Controls** - Desktop, mobile, and gamepad controls defined
 - [ ] **Input Responsiveness** - Requirements for responsive game feel specified
 - [ ] **Accessibility Options** - Control customization and accessibility considered
@@ -2093,6 +2202,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Progression and Balance
 
 ### Player Progression
+
 - [ ] **Progression Type** - Linear, branching, or metroidvania approach defined
 - [ ] **Key Milestones** - Major progression points documented
 - [ ] **Unlock System** - What players unlock and when is specified
@@ -2100,6 +2210,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Player Agency** - Meaningful player choices and consequences defined
 
 ### Game Balance
+
 - [ ] **Balance Parameters** - Numeric values for key game systems provided
 - [ ] **Difficulty Curve** - Appropriate challenge progression designed
 - [ ] **Economy Design** - Resource systems balanced for engagement
@@ -2109,6 +2220,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Level Design Framework
 
 ### Level Structure
+
 - [ ] **Level Types** - Different level categories defined with purposes
 - [ ] **Level Progression** - How players move through levels specified
 - [ ] **Duration Targets** - Expected play time for each level type
@@ -2116,6 +2228,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Replay Value** - Elements that encourage repeated play designed
 
 ### Content Guidelines
+
 - [ ] **Level Creation Rules** - Clear guidelines for level designers
 - [ ] **Mechanic Introduction** - How new mechanics are taught in levels
 - [ ] **Pacing Variety** - Mix of action, puzzle, and rest moments planned
@@ -2125,6 +2238,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Technical Implementation Readiness
 
 ### Performance Requirements
+
 - [ ] **Frame Rate Targets** - 60 FPS target with minimum acceptable rates
 - [ ] **Memory Budgets** - Maximum memory usage limits defined
 - [ ] **Load Time Goals** - Acceptable loading times for different content
@@ -2132,6 +2246,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Scalability Plan** - How performance scales across different devices
 
 ### Platform Specifications
+
 - [ ] **Desktop Requirements** - Minimum and recommended PC/Mac specs
 - [ ] **Mobile Optimization** - iOS and Android specific requirements
 - [ ] **Browser Compatibility** - Supported browsers and versions listed
@@ -2139,6 +2254,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Update Strategy** - Plan for post-launch updates and patches
 
 ### Asset Requirements
+
 - [ ] **Art Style Definition** - Clear visual style with reference materials
 - [ ] **Asset Specifications** - Technical requirements for all asset types
 - [ ] **Audio Requirements** - Music and sound effect specifications
@@ -2148,6 +2264,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Development Planning
 
 ### Implementation Phases
+
 - [ ] **Phase Breakdown** - Development divided into logical phases
 - [ ] **Epic Definitions** - Major development epics identified
 - [ ] **Dependency Mapping** - Prerequisites between features documented
@@ -2155,6 +2272,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Milestone Planning** - Key deliverables and deadlines established
 
 ### Team Requirements
+
 - [ ] **Role Definitions** - Required team roles and responsibilities
 - [ ] **Skill Requirements** - Technical skills needed for implementation
 - [ ] **Resource Allocation** - Time and effort estimates for major features
@@ -2164,6 +2282,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Quality Assurance
 
 ### Success Metrics
+
 - [ ] **Technical Metrics** - Measurable technical performance goals
 - [ ] **Gameplay Metrics** - Player engagement and retention targets
 - [ ] **Quality Benchmarks** - Standards for bug rates and polish level
@@ -2171,6 +2290,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Business Objectives** - Commercial or project success criteria
 
 ### Testing Strategy
+
 - [ ] **Playtesting Plan** - How and when player feedback will be gathered
 - [ ] **Technical Testing** - Performance and compatibility testing approach
 - [ ] **Balance Validation** - Methods for confirming game balance
@@ -2180,6 +2300,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Documentation Quality
 
 ### Clarity and Completeness
+
 - [ ] **Clear Writing** - All sections are well-written and understandable
 - [ ] **Complete Coverage** - No major game systems left undefined
 - [ ] **Actionable Detail** - Enough detail for developers to create implementation stories
@@ -2187,6 +2308,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Reference Materials** - Links to inspiration, research, and additional resources
 
 ### Maintainability
+
 - [ ] **Version Control** - Change log established for tracking revisions
 - [ ] **Update Process** - Plan for maintaining document during development
 - [ ] **Team Access** - All team members can access and reference the document
@@ -2196,6 +2318,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Stakeholder Alignment
 
 ### Team Understanding
+
 - [ ] **Shared Vision** - All team members understand and agree with the game vision
 - [ ] **Role Clarity** - Each team member understands their contribution
 - [ ] **Decision Framework** - Process for making design decisions during development
@@ -2203,6 +2326,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Communication Channels** - Regular meetings and feedback sessions planned
 
 ### External Validation
+
 - [ ] **Market Validation** - Competitive analysis and market fit assessment
 - [ ] **Technical Validation** - Feasibility confirmed with technical team
 - [ ] **Resource Validation** - Required resources available and committed
@@ -2212,6 +2336,7 @@ This brief is typically created early in the ideation process, often after brain
 ## Final Readiness Assessment
 
 ### Implementation Preparedness
+
 - [ ] **Story Creation Ready** - Document provides sufficient detail for story creation
 - [ ] **Architecture Alignment** - Game design aligns with technical capabilities
 - [ ] **Asset Production** - Asset requirements enable art and audio production
@@ -2219,6 +2344,7 @@ This brief is typically created early in the ideation process, often after brain
 - [ ] **Quality Assurance** - Testing and validation processes established
 
 ### Document Approval
+
 - [ ] **Design Review Complete** - Document reviewed by all relevant stakeholders
 - [ ] **Technical Review Complete** - Technical feasibility confirmed
 - [ ] **Business Review Complete** - Project scope and goals approved

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

@@ -290,7 +290,7 @@ This architecture is designed to support the gameplay mechanics defined in the G
 │   ├── stories/         # Development stories
 │   └── architecture/    # Technical docs
 └── dist/                # Built game files
-```text
+```
 
 ### Module Organization
 
@@ -575,7 +575,7 @@ const gameConfig: Phaser.Types.Core.GameConfig = {
     },
     // Additional configuration...
 };
-```text
+```
 
 ### Game Balance Configuration
 
@@ -776,6 +776,7 @@ export const GameBalance = {
 ## Story Completeness
 
 ### Basic Story Elements
+
 - [ ] **Story Title** - Clear, descriptive title that identifies the feature
 - [ ] **Epic Assignment** - Story is properly assigned to relevant epic
 - [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -783,6 +784,7 @@ export const GameBalance = {
 - [ ] **Description** - Clear, concise description of what needs to be implemented
 
 ### Game Design Alignment
+
 - [ ] **GDD Reference** - Specific Game Design Document section referenced
 - [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
 - [ ] **Player Experience Goal** - Describes the intended player experience
@@ -792,6 +794,7 @@ export const GameBalance = {
 ## Technical Specifications
 
 ### Architecture Compliance
+
 - [ ] **File Organization** - Follows game architecture document structure
 - [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
 - [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -799,6 +802,7 @@ export const GameBalance = {
 - [ ] **Dependencies** - All system dependencies clearly identified
 
 ### Phaser 3 Requirements
+
 - [ ] **Scene Integration** - Specifies which scenes are affected and how
 - [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
 - [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -806,6 +810,7 @@ export const GameBalance = {
 - [ ] **Performance Considerations** - 60 FPS target and optimization requirements
 
 ### Code Quality Standards
+
 - [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
 - [ ] **Error Handling** - Error scenarios and handling requirements specified
 - [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -815,6 +820,7 @@ export const GameBalance = {
 ## Implementation Readiness
 
 ### Acceptance Criteria
+
 - [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
 - [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
 - [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -822,6 +828,7 @@ export const GameBalance = {
 - [ ] **Completeness** - No acceptance criteria are vague or unmeasurable
 
 ### Implementation Tasks
+
 - [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
 - [ ] **Task Scope** - Each task is completable in 1-4 hours
 - [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -829,6 +836,7 @@ export const GameBalance = {
 - [ ] **Development Flow** - Tasks follow logical implementation order
 
 ### Dependencies
+
 - [ ] **Story Dependencies** - All prerequisite stories identified with IDs
 - [ ] **Technical Dependencies** - Required systems and files identified
 - [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -838,6 +846,7 @@ export const GameBalance = {
 ## Testing Requirements
 
 ### Test Coverage
+
 - [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
 - [ ] **Integration Test Cases** - Integration testing with other game systems specified
 - [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -845,6 +854,7 @@ export const GameBalance = {
 - [ ] **Edge Case Testing** - Edge cases and error conditions covered
 
 ### Test Implementation
+
 - [ ] **Test File Paths** - Exact test file locations specified
 - [ ] **Test Scenarios** - All test scenarios are complete and executable
 - [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -854,6 +864,7 @@ export const GameBalance = {
 ## Game-Specific Quality
 
 ### Gameplay Implementation
+
 - [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
 - [ ] **Player Controls** - Input handling requirements are complete
 - [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -861,6 +872,7 @@ export const GameBalance = {
 - [ ] **State Management** - Game state changes and persistence requirements defined
 
 ### User Experience
+
 - [ ] **UI Requirements** - User interface elements and behaviors specified
 - [ ] **Audio Integration** - Sound effect and music requirements defined
 - [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -868,6 +880,7 @@ export const GameBalance = {
 - [ ] **Error Recovery** - User-facing error handling and recovery specified
 
 ### Performance Optimization
+
 - [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
 - [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
 - [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -877,6 +890,7 @@ export const GameBalance = {
 ## Documentation and Communication
 
 ### Story Documentation
+
 - [ ] **Implementation Notes** - Additional context and implementation guidance provided
 - [ ] **Design Decisions** - Key design choices documented with rationale
 - [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -884,6 +898,7 @@ export const GameBalance = {
 - [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs
 
 ### Developer Handoff
+
 - [ ] **Immediate Actionability** - Developer can start implementation without additional questions
 - [ ] **Complete Context** - All necessary context provided within the story
 - [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -893,6 +908,7 @@ export const GameBalance = {
 ## Final Validation
 
 ### Story Readiness
+
 - [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
 - [ ] **Technical Completeness** - All technical requirements are specified and actionable
 - [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -900,6 +916,7 @@ export const GameBalance = {
 - [ ] **Review Completion** - Story has been reviewed for completeness and accuracy
 
 ### Implementation Preparedness
+
 - [ ] **Environment Ready** - Development environment requirements specified
 - [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
 - [ ] **Testing Prepared** - Testing environment and data requirements specified
@@ -928,6 +945,7 @@ This document establishes coding standards, architectural patterns, and developm
 ### Strict Mode Configuration
 
 **Required tsconfig.json settings:**
+
 ```json
 {
   "compilerOptions": {
@@ -941,11 +959,12 @@ This document establishes coding standards, architectural patterns, and developm
     "exactOptionalPropertyTypes": true
   }
 }
-```text
+```
 
 ### Type Definitions
 
 **Game Object Interfaces:**
+
 ```typescript
 // Core game entity interface
 interface GameEntity {
@@ -969,9 +988,10 @@ interface GameSystem {
   update(delta: number): void;
   shutdown(): void;
 }
-```text
+```
 
 **Scene Data Interfaces:**
+
 ```typescript
 // Scene transition data
 interface SceneData {
@@ -989,28 +1009,32 @@ interface GameState {
 interface GameSettings {
   musicVolume: number;
   sfxVolume: number;
-  difficulty: 'easy' | 'normal' | 'hard';
+  difficulty: "easy" | "normal" | "hard";
   controls: ControlScheme;
 }
-```text
+```
 
 ### Naming Conventions
 
 **Classes and Interfaces:**
+
 - PascalCase for classes: `PlayerSprite`, `GameManager`, `AudioSystem`
 - PascalCase with 'I' prefix for interfaces: `IGameEntity`, `IPlayerController`
 - Descriptive names that indicate purpose: `CollisionManager` not `CM`
 
 **Methods and Variables:**
+
 - camelCase for methods and variables: `updatePosition()`, `playerSpeed`
 - Descriptive names: `calculateDamage()` not `calcDmg()`
 - Boolean variables with is/has/can prefix: `isActive`, `hasCollision`, `canMove`
 
 **Constants:**
+
 - UPPER_SNAKE_CASE for constants: `MAX_PLAYER_SPEED`, `DEFAULT_VOLUME`
 - Group related constants in enums or const objects
 
 **Files and Directories:**
+
 - kebab-case for file names: `player-controller.ts`, `audio-manager.ts`
 - PascalCase for scene files: `MenuScene.ts`, `GameScene.ts`
 
@@ -1019,88 +1043,91 @@ interface GameSettings {
 ### Scene Organization
 
 **Scene Lifecycle Management:**
+
 ```typescript
 class GameScene extends Phaser.Scene {
   private gameManager!: GameManager;
   private inputManager!: InputManager;
-  
+
   constructor() {
-    super({ key: 'GameScene' });
+    super({ key: "GameScene" });
   }
-  
+
   preload(): void {
     // Load only scene-specific assets
-    this.load.image('player', 'assets/player.png');
+    this.load.image("player", "assets/player.png");
   }
-  
+
   create(data: SceneData): void {
     // Initialize game systems
     this.gameManager = new GameManager(this);
     this.inputManager = new InputManager(this);
-    
+
     // Set up scene-specific logic
     this.setupGameObjects();
     this.setupEventListeners();
   }
-  
+
   update(time: number, delta: number): void {
     // Update all game systems
     this.gameManager.update(delta);
     this.inputManager.update(delta);
   }
-  
+
   shutdown(): void {
     // Clean up resources
     this.gameManager.destroy();
     this.inputManager.destroy();
-    
+
     // Remove event listeners
-    this.events.off('*');
+    this.events.off("*");
   }
 }
 ```
 
 **Scene Transitions:**
+
 ```typescript
 // Proper scene transitions with data
-this.scene.start('NextScene', {
+this.scene.start("NextScene", {
   playerScore: this.playerScore,
-  currentLevel: this.currentLevel + 1
+  currentLevel: this.currentLevel + 1,
 });
 
 // Scene overlays for UI
-this.scene.launch('PauseMenuScene');
+this.scene.launch("PauseMenuScene");
 this.scene.pause();
-```text
+```
 
 ### Game Object Patterns
 
 **Component-Based Architecture:**
+
 ```typescript
 // Base game entity
 abstract class GameEntity extends Phaser.GameObjects.Sprite {
   protected components: Map<string, GameComponent> = new Map();
-  
+
   constructor(scene: Phaser.Scene, x: number, y: number, texture: string) {
     super(scene, x, y, texture);
     scene.add.existing(this);
   }
-  
+
   addComponent<T extends GameComponent>(component: T): T {
     this.components.set(component.name, component);
     return component;
   }
-  
+
   getComponent<T extends GameComponent>(name: string): T | undefined {
     return this.components.get(name) as T;
   }
-  
+
   update(delta: number): void {
-    this.components.forEach(component => component.update(delta));
+    this.components.forEach((component) => component.update(delta));
   }
-  
+
   destroy(): void {
-    this.components.forEach(component => component.destroy());
+    this.components.forEach((component) => component.destroy());
     this.components.clear();
     super.destroy();
   }
@@ -1110,65 +1137,67 @@ abstract class GameEntity extends Phaser.GameObjects.Sprite {
 class Player extends GameEntity {
   private movement!: MovementComponent;
   private health!: HealthComponent;
-  
+
   constructor(scene: Phaser.Scene, x: number, y: number) {
-    super(scene, x, y, 'player');
-    
+    super(scene, x, y, "player");
+
     this.movement = this.addComponent(new MovementComponent(this));
     this.health = this.addComponent(new HealthComponent(this, 100));
   }
 }
-```text
+```
 
 ### System Management
 
 **Singleton Managers:**
+
 ```typescript
 class GameManager {
   private static instance: GameManager;
   private scene: Phaser.Scene;
   private gameState: GameState;
-  
+
   constructor(scene: Phaser.Scene) {
     if (GameManager.instance) {
-      throw new Error('GameManager already exists!');
+      throw new Error("GameManager already exists!");
     }
-    
+
     this.scene = scene;
     this.gameState = this.loadGameState();
     GameManager.instance = this;
   }
-  
+
   static getInstance(): GameManager {
     if (!GameManager.instance) {
-      throw new Error('GameManager not initialized!');
+      throw new Error("GameManager not initialized!");
     }
     return GameManager.instance;
   }
-  
+
   update(delta: number): void {
     // Update game logic
   }
-  
+
   destroy(): void {
     GameManager.instance = null!;
   }
 }
-```text
+```
 
 ## Performance Optimization
 
 ### Object Pooling
 
 **Required for High-Frequency Objects:**
+
 ```typescript
 class BulletPool {
   private pool: Bullet[] = [];
   private scene: Phaser.Scene;
-  
+
   constructor(scene: Phaser.Scene, initialSize: number = 50) {
     this.scene = scene;
-    
+
     // Pre-create bullets
     for (let i = 0; i < initialSize; i++) {
       const bullet = new Bullet(scene, 0, 0);
@@ -1177,20 +1206,20 @@ class BulletPool {
       this.pool.push(bullet);
     }
   }
-  
+
   getBullet(): Bullet | null {
-    const bullet = this.pool.find(b => !b.active);
+    const bullet = this.pool.find((b) => !b.active);
     if (bullet) {
       bullet.setActive(true);
       bullet.setVisible(true);
       return bullet;
     }
-    
+
     // Pool exhausted - create new bullet
-    console.warn('Bullet pool exhausted, creating new bullet');
+    console.warn("Bullet pool exhausted, creating new bullet");
     return new Bullet(this.scene, 0, 0);
   }
-  
+
   releaseBullet(bullet: Bullet): void {
     bullet.setActive(false);
     bullet.setVisible(false);
@@ -1202,45 +1231,47 @@ class BulletPool {
 ### Frame Rate Optimization
 
 **Performance Monitoring:**
+
 ```typescript
 class PerformanceMonitor {
   private frameCount: number = 0;
   private lastTime: number = 0;
   private frameRate: number = 60;
-  
+
   update(time: number): void {
     this.frameCount++;
-    
+
     if (time - this.lastTime >= 1000) {
       this.frameRate = this.frameCount;
       this.frameCount = 0;
       this.lastTime = time;
-      
+
       if (this.frameRate < 55) {
         console.warn(`Low frame rate detected: ${this.frameRate} FPS`);
         this.optimizePerformance();
       }
     }
   }
-  
+
   private optimizePerformance(): void {
     // Reduce particle counts, disable effects, etc.
   }
 }
-```text
+```
 
 **Update Loop Optimization:**
+
 ```typescript
 // Avoid expensive operations in update loops
 class GameScene extends Phaser.Scene {
   private updateTimer: number = 0;
   private readonly UPDATE_INTERVAL = 100; // ms
-  
+
   update(time: number, delta: number): void {
     // High-frequency updates (every frame)
     this.updatePlayer(delta);
     this.updatePhysics(delta);
-    
+
     // Low-frequency updates (10 times per second)
     this.updateTimer += delta;
     if (this.updateTimer >= this.UPDATE_INTERVAL) {
@@ -1250,13 +1281,14 @@ class GameScene extends Phaser.Scene {
     }
   }
 }
-```text
+```
 
 ## Input Handling
 
 ### Cross-Platform Input
 
 **Input Abstraction:**
+
 ```typescript
 interface InputState {
   moveLeft: boolean;
@@ -1272,26 +1304,26 @@ class InputManager {
     moveRight: false,
     jump: false,
     action: false,
-    pause: false
+    pause: false,
   };
-  
+
   private keys!: { [key: string]: Phaser.Input.Keyboard.Key };
   private pointer!: Phaser.Input.Pointer;
-  
+
   constructor(private scene: Phaser.Scene) {
     this.setupKeyboard();
     this.setupTouch();
   }
-  
+
   private setupKeyboard(): void {
-    this.keys = this.scene.input.keyboard.addKeys('W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT');
+    this.keys = this.scene.input.keyboard.addKeys("W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT");
   }
-  
+
   private setupTouch(): void {
-    this.scene.input.on('pointerdown', this.handlePointerDown, this);
-    this.scene.input.on('pointerup', this.handlePointerUp, this);
+    this.scene.input.on("pointerdown", this.handlePointerDown, this);
+    this.scene.input.on("pointerup", this.handlePointerUp, this);
   }
-  
+
   update(): void {
     // Update input state from multiple sources
     this.inputState.moveLeft = this.keys.A.isDown || this.keys.LEFT.isDown;
@@ -1299,42 +1331,43 @@ class InputManager {
     this.inputState.jump = Phaser.Input.Keyboard.JustDown(this.keys.SPACE);
     // ... handle touch input
   }
-  
+
   getInputState(): InputState {
     return { ...this.inputState };
   }
 }
-```text
+```
 
 ## Error Handling
 
 ### Graceful Degradation
 
 **Asset Loading Error Handling:**
+
 ```typescript
 class AssetManager {
   loadAssets(): Promise<void> {
     return new Promise((resolve, reject) => {
-      this.scene.load.on('filecomplete', this.handleFileComplete, this);
-      this.scene.load.on('loaderror', this.handleLoadError, this);
-      this.scene.load.on('complete', () => resolve());
-      
+      this.scene.load.on("filecomplete", this.handleFileComplete, this);
+      this.scene.load.on("loaderror", this.handleLoadError, this);
+      this.scene.load.on("complete", () => resolve());
+
       this.scene.load.start();
     });
   }
-  
+
   private handleLoadError(file: Phaser.Loader.File): void {
     console.error(`Failed to load asset: ${file.key}`);
-    
+
     // Use fallback assets
     this.loadFallbackAsset(file.key);
   }
-  
+
   private loadFallbackAsset(key: string): void {
     // Load placeholder or default assets
     switch (key) {
-      case 'player':
-        this.scene.load.image('player', 'assets/defaults/default-player.png');
+      case "player":
+        this.scene.load.image("player", "assets/defaults/default-player.png");
         break;
       default:
         console.warn(`No fallback for asset: ${key}`);
@@ -1346,25 +1379,26 @@ class AssetManager {
 ### Runtime Error Recovery
 
 **System Error Handling:**
+
 ```typescript
 class GameSystem {
   protected handleError(error: Error, context: string): void {
     console.error(`Error in ${context}:`, error);
-    
+
     // Report to analytics/logging service
     this.reportError(error, context);
-    
+
     // Attempt recovery
     this.attemptRecovery(context);
   }
-  
+
   private attemptRecovery(context: string): void {
     switch (context) {
-      case 'update':
+      case "update":
         // Reset system state
         this.reset();
         break;
-      case 'render':
+      case "render":
         // Disable visual effects
         this.disableEffects();
         break;
@@ -1374,64 +1408,66 @@ class GameSystem {
     }
   }
 }
-```text
+```
 
 ## Testing Standards
 
 ### Unit Testing
 
 **Game Logic Testing:**
+
 ```typescript
 // Example test for game mechanics
-describe('HealthComponent', () => {
+describe("HealthComponent", () => {
   let healthComponent: HealthComponent;
-  
+
   beforeEach(() => {
     const mockEntity = {} as GameEntity;
     healthComponent = new HealthComponent(mockEntity, 100);
   });
-  
-  test('should initialize with correct health', () => {
+
+  test("should initialize with correct health", () => {
     expect(healthComponent.currentHealth).toBe(100);
     expect(healthComponent.maxHealth).toBe(100);
   });
-  
-  test('should handle damage correctly', () => {
+
+  test("should handle damage correctly", () => {
     healthComponent.takeDamage(25);
     expect(healthComponent.currentHealth).toBe(75);
     expect(healthComponent.isAlive()).toBe(true);
   });
-  
-  test('should handle death correctly', () => {
+
+  test("should handle death correctly", () => {
     healthComponent.takeDamage(150);
     expect(healthComponent.currentHealth).toBe(0);
     expect(healthComponent.isAlive()).toBe(false);
   });
 });
-```text
+```
 
 ### Integration Testing
 
 **Scene Testing:**
+
 ```typescript
-describe('GameScene Integration', () => {
+describe("GameScene Integration", () => {
   let scene: GameScene;
   let mockGame: Phaser.Game;
-  
+
   beforeEach(() => {
     // Mock Phaser game instance
     mockGame = createMockGame();
     scene = new GameScene();
   });
-  
-  test('should initialize all systems', () => {
+
+  test("should initialize all systems", () => {
     scene.create({});
-    
+
     expect(scene.gameManager).toBeDefined();
     expect(scene.inputManager).toBeDefined();
   });
 });
-```text
+```
 
 ## File Organization
 
@@ -1485,21 +1521,25 @@ src/
 ### Story Implementation Process
 
 1. **Read Story Requirements:**
+
    - Understand acceptance criteria
    - Identify technical requirements
    - Review performance constraints
 
 2. **Plan Implementation:**
+
    - Identify files to create/modify
    - Consider component architecture
    - Plan testing approach
 
 3. **Implement Feature:**
+
    - Follow TypeScript strict mode
    - Use established patterns
    - Maintain 60 FPS performance
 
 4. **Test Implementation:**
+
    - Write unit tests for game logic
    - Test cross-platform functionality
    - Validate performance targets
@@ -1512,6 +1552,7 @@ src/
 ### Code Review Checklist
 
 **Before Committing:**
+
 - [ ] TypeScript compiles without errors
 - [ ] All tests pass
 - [ ] Performance targets met (60 FPS)
@@ -1525,17 +1566,20 @@ src/
 ## Performance Targets
 
 ### Frame Rate Requirements
+
 - **Desktop**: Maintain 60 FPS at 1080p
 - **Mobile**: Maintain 60 FPS on mid-range devices, minimum 30 FPS on low-end
 - **Optimization**: Implement dynamic quality scaling when performance drops
 
 ### Memory Management
+
 - **Total Memory**: Under 100MB for full game
 - **Per Scene**: Under 50MB per gameplay scene
 - **Asset Loading**: Progressive loading to stay under limits
 - **Garbage Collection**: Minimize object creation in update loops
 
 ### Loading Performance
+
 - **Initial Load**: Under 5 seconds for game start
 - **Scene Transitions**: Under 2 seconds between scenes
 - **Asset Streaming**: Background loading for upcoming content

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

@@ -109,6 +109,7 @@ Create detailed, actionable game development stories that enable AI developers t
 ## Prerequisites
 
 Before creating stories, ensure you have:
+
 - Completed Game Design Document (GDD)
 - Game Architecture Document
 - Epic definition this story belongs to
@@ -119,12 +120,14 @@ Before creating stories, ensure you have:
 ### 1. Story Identification
 
 **Review Epic Context:**
+
 - Understand the epic's overall goal
 - Identify specific features that need implementation
 - Review any existing stories in the epic
 - Ensure no duplicate work
 
 **Feature Analysis:**
+
 - Reference specific GDD sections
 - Understand player experience goals
 - Identify technical complexity
@@ -133,12 +136,14 @@ Before creating stories, ensure you have:
 ### 2. Story Scoping
 
 **Single Responsibility:**
+
 - Focus on one specific game feature
 - Ensure story is completable in 1-3 days
 - Break down complex features into multiple stories
 - Maintain clear boundaries with other stories
 
 **Implementation Clarity:**
+
 - Define exactly what needs to be built
 - Specify all technical requirements
 - Include all necessary integration points
@@ -150,6 +155,7 @@ Before creating stories, ensure you have:
 Use `templates#game-story-tmpl` following all embedded LLM instructions
 
 **Key Focus Areas:**
+
 - Clear, actionable description
 - Specific acceptance criteria
 - Detailed technical specifications
@@ -159,18 +165,21 @@ Use `templates#game-story-tmpl` following all embedded LLM instructions
 ### 4. Story Validation
 
 **Technical Review:**
+
 - Verify all technical specifications are complete
 - Ensure integration points are clearly defined
 - Confirm file paths match architecture
 - Validate TypeScript interfaces and classes
 
 **Game Design Alignment:**
+
 - Confirm story implements GDD requirements
 - Verify player experience goals are met
 - Check balance parameters are included
 - Ensure game mechanics are correctly interpreted
 
 **Implementation Readiness:**
+
 - All dependencies identified
 - Assets requirements specified
 - Testing criteria defined
@@ -182,6 +191,7 @@ Use `templates#game-story-tmpl` following all embedded LLM instructions
 Execute `checklists#game-story-dod-checklist` against completed story
 
 **Story Criteria:**
+
 - Story is immediately actionable
 - No design decisions left to developer
 - Technical requirements are complete
@@ -191,12 +201,14 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ### 6. Story Refinement
 
 **Developer Perspective:**
+
 - Can a developer start implementation immediately?
 - Are all technical questions answered?
 - Is the scope appropriate for the estimated points?
 - Are all dependencies clearly identified?
 
 **Iterative Improvement:**
+
 - Address any gaps or ambiguities
 - Clarify complex technical requirements
 - Ensure story fits within epic scope
@@ -205,6 +217,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Story Elements Checklist
 
 ### Required Sections
+
 - [ ] Clear, specific description
 - [ ] Complete acceptance criteria (functional, technical, game design)
 - [ ] Detailed technical specifications
@@ -218,6 +231,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Definition of Done checklist
 
 ### Game-Specific Requirements
+
 - [ ] GDD section references
 - [ ] Game mechanic implementation details
 - [ ] Player experience goals
@@ -227,6 +241,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Cross-platform considerations
 
 ### Technical Quality
+
 - [ ] TypeScript strict mode compliance
 - [ ] Architecture document alignment
 - [ ] Code organization follows standards
@@ -237,18 +252,21 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Common Pitfalls
 
 **Scope Issues:**
+
 - Story too large (break into multiple stories)
 - Story too vague (add specific requirements)
 - Missing dependencies (identify all prerequisites)
 - Unclear boundaries (define what's in/out of scope)
 
 **Technical Issues:**
+
 - Missing integration details
 - Incomplete technical specifications
 - Undefined interfaces or classes
 - Missing performance requirements
 
 **Game Design Issues:**
+
 - Not referencing GDD properly
 - Missing player experience context
 - Unclear game mechanic implementation
@@ -257,6 +275,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Success Criteria
 
 **Story Readiness:**
+
 - [ ] Developer can start implementation immediately
 - [ ] No additional design decisions required
 - [ ] All technical questions answered
@@ -265,6 +284,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Story fits within epic scope
 
 **Quality Validation:**
+
 - [ ] Game story DOD checklist passes
 - [ ] Architecture alignment confirmed
 - [ ] GDD requirements covered
@@ -274,6 +294,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Handoff Protocol
 
 **To Game Developer:**
+
 1. Provide story document
 2. Confirm GDD and architecture access
 3. Verify all dependencies are met
@@ -281,6 +302,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 5. Establish check-in schedule
 
 **Story Status Updates:**
+
 - Draft → Ready for Development
 - In Development → Code Review
 - Code Review → Testing
@@ -633,6 +655,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Story Completeness
 
 ### Basic Story Elements
+
 - [ ] **Story Title** - Clear, descriptive title that identifies the feature
 - [ ] **Epic Assignment** - Story is properly assigned to relevant epic
 - [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -640,6 +663,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Description** - Clear, concise description of what needs to be implemented
 
 ### Game Design Alignment
+
 - [ ] **GDD Reference** - Specific Game Design Document section referenced
 - [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
 - [ ] **Player Experience Goal** - Describes the intended player experience
@@ -649,6 +673,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Technical Specifications
 
 ### Architecture Compliance
+
 - [ ] **File Organization** - Follows game architecture document structure
 - [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
 - [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -656,6 +681,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Dependencies** - All system dependencies clearly identified
 
 ### Phaser 3 Requirements
+
 - [ ] **Scene Integration** - Specifies which scenes are affected and how
 - [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
 - [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -663,6 +689,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Performance Considerations** - 60 FPS target and optimization requirements
 
 ### Code Quality Standards
+
 - [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
 - [ ] **Error Handling** - Error scenarios and handling requirements specified
 - [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -672,6 +699,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Implementation Readiness
 
 ### Acceptance Criteria
+
 - [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
 - [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
 - [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -679,6 +707,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Completeness** - No acceptance criteria are vague or unmeasurable
 
 ### Implementation Tasks
+
 - [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
 - [ ] **Task Scope** - Each task is completable in 1-4 hours
 - [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -686,6 +715,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Development Flow** - Tasks follow logical implementation order
 
 ### Dependencies
+
 - [ ] **Story Dependencies** - All prerequisite stories identified with IDs
 - [ ] **Technical Dependencies** - Required systems and files identified
 - [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -695,6 +725,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Testing Requirements
 
 ### Test Coverage
+
 - [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
 - [ ] **Integration Test Cases** - Integration testing with other game systems specified
 - [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -702,6 +733,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Edge Case Testing** - Edge cases and error conditions covered
 
 ### Test Implementation
+
 - [ ] **Test File Paths** - Exact test file locations specified
 - [ ] **Test Scenarios** - All test scenarios are complete and executable
 - [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -711,6 +743,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Game-Specific Quality
 
 ### Gameplay Implementation
+
 - [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
 - [ ] **Player Controls** - Input handling requirements are complete
 - [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -718,6 +751,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **State Management** - Game state changes and persistence requirements defined
 
 ### User Experience
+
 - [ ] **UI Requirements** - User interface elements and behaviors specified
 - [ ] **Audio Integration** - Sound effect and music requirements defined
 - [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -725,6 +759,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Error Recovery** - User-facing error handling and recovery specified
 
 ### Performance Optimization
+
 - [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
 - [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
 - [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -734,6 +769,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Documentation and Communication
 
 ### Story Documentation
+
 - [ ] **Implementation Notes** - Additional context and implementation guidance provided
 - [ ] **Design Decisions** - Key design choices documented with rationale
 - [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -741,6 +777,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs
 
 ### Developer Handoff
+
 - [ ] **Immediate Actionability** - Developer can start implementation without additional questions
 - [ ] **Complete Context** - All necessary context provided within the story
 - [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -750,6 +787,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 ## Final Validation
 
 ### Story Readiness
+
 - [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
 - [ ] **Technical Completeness** - All technical requirements are specified and actionable
 - [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -757,6 +795,7 @@ class {{ClassName}} extends {{PhaseClass}} {
 - [ ] **Review Completion** - Story has been reviewed for completeness and accuracy
 
 ### Implementation Preparedness
+
 - [ ] **Environment Ready** - Development environment requirements specified
 - [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
 - [ ] **Testing Prepared** - Testing environment and data requirements specified

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

@@ -1006,7 +1006,7 @@ module "vpc" {
   public_subnets = {{public_subnets}}
   private_subnets = {{private_subnets}}
 }
-```text
+```
 
 ### Security Foundation
 
@@ -1053,7 +1053,7 @@ eksctl create cluster \
   --nodegroup-name {{nodegroup_name}} \
   --node-type {{instance_type}} \
   --nodes {{node_count}}
-```text
+```
 
 ^^/CONDITION: uses_eks^^
 
@@ -1067,7 +1067,7 @@ az aks create \
   --node-count {{node_count}} \
   --node-vm-size {{vm_size}} \
   --network-plugin azure
-```text
+```
 
 ^^/CONDITION: uses_aks^^
 
@@ -1111,11 +1111,11 @@ metadata:
 spec:
   source:
     repoURL:
-      '[object Object]': null
+      "[object Object]": null
     targetRevision:
-      '[object Object]': null
+      "[object Object]": null
     path:
-      '[object Object]': null
+      "[object Object]": null
 ```
 
 ^^/CONDITION: uses_argocd^^
@@ -1132,10 +1132,10 @@ spec:
   interval: 1m
   ref:
     branch:
-      '[object Object]': null
+      "[object Object]": null
   url:
-    '[object Object]': null
-```text
+    "[object Object]": null
+```
 
 ^^/CONDITION: uses_flux^^
 
@@ -1153,7 +1153,7 @@ platform-gitops/
  applications/
      base/
      overlays/
-```text
+```
 
 ### Deployment Workflows
 
@@ -1197,7 +1197,7 @@ istioctl install --set profile={{istio_profile}} \
 # Linkerd Installation
 linkerd install --cluster-name={{cluster_name}} | kubectl apply -f -
 linkerd viz install | kubectl apply -f -
-```text
+```
 
 - Control plane setup
 - Proxy injection
@@ -1248,7 +1248,7 @@ spec:
     - name: deploy
       taskRef:
         name: gitops-deploy
-```text
+```
 
 ### Development Tools
 
@@ -1290,7 +1290,7 @@ data:
       - job_name: 'kubernetes-pods'
         kubernetes_sd_configs:
           - role: pod
-```text
+```
 
 ### Platform Observability
 
@@ -1380,7 +1380,7 @@ stages:
   - develop
   - test
   - deploy
-```text
+```
 
 ## Platform Validation & Testing
 
@@ -1409,8 +1409,8 @@ stages:
 
 ### Load Testing
 
-```yaml
-# K6 Load Test Example
+```typescript
+// K6 Load Test Example
 import http from 'k6/http';
 import { check } from 'k6';
 

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

@@ -160,7 +160,7 @@ Created during agent setup:
 - Templates:
   - [ ] template-name-1.md
   - [ ] template-name-2.md
-```text
+```
 
 ### 4. Create Agent File
 
@@ -218,7 +218,7 @@ Present to the user:
    1. Review and customize the created tasks/templates
    2. Run npm run build:agents
    3. Test the agent thoroughly
-```text
+```
 
 ## Template Reference
 
@@ -247,7 +247,7 @@ persona:
     - Data integrity and accuracy above all
     - Clear communication of complex findings
     - Actionable insights over raw numbers
-```text
+```
 
 ## Creating Missing Dependencies
 
@@ -280,12 +280,12 @@ When a required task or template doesn't exist:
 ```yaml
 dependencies:
   tasks:
-    - 'create-doc # Required if agent creates any documents'
-    - 'analyze-requirements # Custom task for this agent'
-    - 'generate-report # Another custom task'
+    - create-doc
+    - analyze-requirements
+    - generate-report
   templates:
-    - 'requirements-doc # Template for requirements documents'
-    - 'analysis-report # Template for analysis reports'
+    - requirements-doc
+    - analysis-report
 ```
 
 ## Notes
@@ -973,7 +973,7 @@ Before declaring complete:
 
 **README Structure with Character Introduction:**
 
-````markdown
+```markdown
 # {Pack Name} Expansion Pack
 
 ## Meet Your {Domain} Team
@@ -998,9 +998,7 @@ _{Professional background and expertise}_
 
 2. **Launch Orchestrator**:
 
-   ```bash
    npm run agent {pack-name}-orchestrator
-   ```
 
 3. **Follow Numbered Options**: {Character Name} will present numbered choices for each decision
 
@@ -1030,7 +1028,7 @@ _{Professional background and expertise}_
 ### Knowledge Base
 
 [Embedded domain expertise]
-````
+```
 
 #### 6.3 Advanced Data File Documentation with Validation
 
@@ -1742,7 +1740,7 @@ Present these numbered options to the user:
 
 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
+```yml
 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
@@ -1802,7 +1800,7 @@ dependencies:
     - [TEMPLATE_1]  # Template with LLM instructions for guided creation
     - [TEMPLATE_2]  # Another template for different document type
     [[LLM: Example: blueprint-tmpl, contract-tmpl, report-tmpl
-    Each template should include [[LLM: guidance]] and other conventions from `template-formmat.md` sections for user interaction]]
+    Each template should include [[LLM: guidance]] and other conventions from `template-format.md` sections for user interaction]]
 
   checklists:
     - [CHECKLIST_1]  # Quality validation for template outputs
@@ -1818,7 +1816,7 @@ dependencies:
     - template-format  # Required if using templates
     - [UTIL_1]        # Other utilities as needed
     [[LLM: Include workflow-management if agent participates in workflows]]
-```text
+```
 
 @{example: Construction Contractor Agent}
 
@@ -1857,22 +1855,22 @@ commands:
   - '*exit" - Say goodbye as Marcus and exit'
 dependencies:
   tasks:
-    - 'create-doc          # For document creation'
-    - 'validate-plans      # Custom validation task'
-    - 'safety-assessment   # Custom safety review task'
+    - create-doc
+    - validate-plans
+    - safety-assessment
   templates:
-    - 'blueprint-tmpl      # Architectural blueprint template'
-    - 'estimate-tmpl       # Cost estimation template'
-    - 'schedule-tmpl       # Project timeline template'
+    - blueprint-tmpl
+    - estimate-tmpl
+    - schedule-tmpl
   checklists:
-    - 'blueprint-checklist # Validates blueprint completeness'
-    - 'safety-checklist    # Safety compliance validation'
+    - blueprint-checklist
+    - safety-checklist
   data:
-    - 'building-codes.md   # Local building code reference'
-    - 'materials-guide.md  # Construction materials specs'
+    - building-codes.md
+    - materials-guide.md
   utils:
-    - 'template-format     # For template processing'
-````
+    - template-format
+```
 ==================== END: templates#agent-tmpl ====================
 
 ==================== START: templates#expansion-pack-plan-tmpl ====================

dist/teams/team-all.txt

@@ -153,6 +153,11 @@ loading:
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
   - Discover available workflows in the bundle at runtime
   - Understand each workflow's purpose, options, and decision points
@@ -166,6 +171,7 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - kb-mode-interaction
   data:
     - bmad-kb
   utils:
@@ -313,6 +319,12 @@ agent:
   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
@@ -320,30 +332,16 @@ persona:
   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: Config-Based Loading - MUST load .bmad-core/core-config.yml at startup, then load ONLY files listed in devLoadAlwaysFiles. Inform user of missing files but continue
-  - CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
-  - Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
+  - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
   - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
-  - Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
+  - 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
-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
-  - 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 scan docs/stories/ directory automatically
-  - CRITICAL: Do NOT begin any tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load story files and begin work when explicitly requested by user
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - chat-mode: Conversational mode for development discussions
   - run-tests: Execute linting and tests
-  - lint: Run linting only
-  - dod-check: Run story-dod-checklist
-  - status: Show task progress
   - debug-log: Show debug entries
   - complete-story: Finalize to "Review"
   - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
@@ -824,6 +822,79 @@ If template specifies a checklist:
 - Template markup is for AI processing only - never expose to users
 ==================== END: tasks#create-doc ====================
 
+==================== START: tasks#kb-mode-interaction ====================
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+Announce entering KB mode with a brief, friendly introduction:
+
+"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+
+### 2. Present Topic Areas
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: *kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
+==================== END: tasks#kb-mode-interaction ====================
+
 ==================== START: data#bmad-kb ====================
 # BMAD Knowledge Base
 
@@ -893,6 +964,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -1305,7 +1434,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -1331,7 +1460,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -1347,7 +1476,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -1417,7 +1546,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -1443,7 +1572,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 
@@ -3700,7 +3829,7 @@ servers:
       '[object Object]': null
     description:
       '[object Object]': null
-```text
+```
 
 ^^/CONDITION: has_rest_api^^
 
@@ -3763,7 +3892,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text
 
 @{example: monorepo-structure}
 project-root/
@@ -3775,6 +3903,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
 @{/example}
+```
 
 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]
 
@@ -5547,7 +5676,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{component_interaction_diagram}}
-```text
+```
 
 ## API Design and Integration
 
@@ -5587,7 +5716,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]
 
 ```json
 {{response_schema}}
-```text
+```
 
 <</REPEAT>>
 
@@ -6925,7 +7054,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 
@@ -8527,14 +8656,14 @@ To identify the next logical story based on project progress and epic definition
     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:
-  - `dev-story-location`: Where to save story files
+  - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
-  - `prd.prd-file`: Location of monolithic PRD (if not sharded)
+  - `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.architecture-file`: Location of monolithic architecture
+  - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
 
 ### 1. Identify Next Story for Preparation
@@ -8543,11 +8672,11 @@ To identify the next logical story based on project progress and epic definition
 
 - Based on `prdSharded` from config:
   - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
-  - **If `prdSharded: false`**: Load the full PRD from `prd-file` and extract epics from section headings (## Epic N or ### Epic N)
+  - **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 `dev-story-location` from config (e.g., `docs/stories/`) for existing story files
+- 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).
@@ -8567,12 +8696,40 @@ To identify the next logical story based on project progress and epic definition
     ```
 
   - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}*.md`, then `epic-{lastEpicNum + 2}*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.
 
 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
-- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
 
 ### 2. Gather Core Story Requirements (from Epic)
@@ -8608,13 +8765,13 @@ Based on configuration loaded in Step 0:
   - Follow the structured reading order in section 4.2 below
   
 - **If `architectureVersion: v4` and `architectureSharded: false`**:
-  - Load the monolithic architecture from `architecture-file`
+  - 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 `architecture-file` for relevant sections
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
 
 #### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
 
@@ -8671,7 +8828,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 
 ### 6. Populate Story Template with Full Context
 
-- Create a new story file: `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config).
+- 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}`
@@ -8718,7 +8875,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
-- Save the story file to `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config)
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)
 
 ### 9. Report Completion
 
@@ -9028,7 +9185,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{sitemap_diagram}}
-```text
+```
 
 @{example: sitemap}
 
@@ -9460,7 +9617,7 @@ workflow:
 
   sequence:
     - step: service_analysis
-     agent: architect
+      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."

dist/teams/team-fullstack.txt

@@ -157,6 +157,11 @@ loading:
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
   - Discover available workflows in the bundle at runtime
   - Understand each workflow's purpose, options, and decision points
@@ -170,6 +175,7 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - kb-mode-interaction
   data:
     - bmad-kb
   utils:
@@ -663,6 +669,79 @@ If template specifies a checklist:
 - Template markup is for AI processing only - never expose to users
 ==================== END: tasks#create-doc ====================
 
+==================== START: tasks#kb-mode-interaction ====================
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+Announce entering KB mode with a brief, friendly introduction:
+
+"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+
+### 2. Present Topic Areas
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: *kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
+==================== END: tasks#kb-mode-interaction ====================
+
 ==================== START: data#bmad-kb ====================
 # BMAD Knowledge Base
 
@@ -732,6 +811,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -1144,7 +1281,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -1170,7 +1307,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -1186,7 +1323,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -1256,7 +1393,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -1282,7 +1419,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 
@@ -3291,7 +3428,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 
@@ -4506,7 +4643,7 @@ After presenting this section, apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{sitemap_diagram}}
-```text
+```
 
 @{example: sitemap}
 
@@ -5593,7 +5730,7 @@ servers:
       '[object Object]': null
     description:
       '[object Object]': null
-```text
+```
 
 ^^/CONDITION: has_rest_api^^
 
@@ -5656,7 +5793,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text
 
 @{example: monorepo-structure}
 project-root/
@@ -5668,6 +5804,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
 @{/example}
+```
 
 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]
 
@@ -7440,7 +7577,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{component_interaction_diagram}}
-```text
+```
 
 ## API Design and Integration
 
@@ -7480,7 +7617,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]
 
 ```json
 {{response_schema}}
-```text
+```
 
 <</REPEAT>>
 
@@ -8809,7 +8946,7 @@ workflow:
 
   sequence:
     - step: service_analysis
-     agent: architect
+      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."

dist/teams/team-ide-minimal.txt

@@ -149,6 +149,11 @@ loading:
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
   - Discover available workflows in the bundle at runtime
   - Understand each workflow's purpose, options, and decision points
@@ -162,6 +167,7 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - kb-mode-interaction
   data:
     - bmad-kb
   utils:
@@ -297,6 +303,12 @@ agent:
   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
@@ -304,30 +316,16 @@ persona:
   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: Config-Based Loading - MUST load .bmad-core/core-config.yml at startup, then load ONLY files listed in devLoadAlwaysFiles. Inform user of missing files but continue
-  - CRITICAL: Dev Record Only - ONLY update Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
-  - Sequential Execution - Complete tasks 1-by-1 in order. Mark [x] before next. No skipping
+  - CRITICAL: Dev Record Only - ONLY update story file Dev Agent Record sections (checkboxes/Debug Log/Completion Notes/Change Log)
+  - Strive for Sequential Task Execution - Complete tasks 1-by-1 and mark [x] as completed
   - Test-Driven Quality - Write tests alongside code. Task incomplete without passing tests
-  - Debug Log Discipline - Log temp changes to table. Revert after fix. Keep story lean
+  - 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
-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
-  - 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 scan docs/stories/ directory automatically
-  - CRITICAL: Do NOT begin any tasks automatically
-  - Wait for user to specify story or ask for story selection
-  - Only load story files and begin work when explicitly requested by user
 commands:
   - help: Show numbered list of the following commands to allow selection
-  - chat-mode: Conversational mode for development discussions
   - run-tests: Execute linting and tests
-  - lint: Run linting only
-  - dod-check: Run story-dod-checklist
-  - status: Show task progress
   - debug-log: Show debug entries
   - complete-story: Finalize to "Review"
   - exit: Say goodbye as the Developer, and then abandon inhabiting this persona
@@ -570,6 +568,79 @@ If template specifies a checklist:
 - Template markup is for AI processing only - never expose to users
 ==================== END: tasks#create-doc ====================
 
+==================== START: tasks#kb-mode-interaction ====================
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+Announce entering KB mode with a brief, friendly introduction:
+
+"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+
+### 2. Present Topic Areas
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: *kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
+==================== END: tasks#kb-mode-interaction ====================
+
 ==================== START: data#bmad-kb ====================
 # BMAD Knowledge Base
 
@@ -639,6 +710,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -1051,7 +1180,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -1077,7 +1206,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -1093,7 +1222,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -1163,7 +1292,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -1189,7 +1318,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 
@@ -1471,7 +1600,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 
@@ -2634,14 +2763,14 @@ To identify the next logical story based on project progress and epic definition
     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:
-  - `dev-story-location`: Where to save story files
+  - `devStoryLocation`: Where to save story files
   - `prd.prdSharded`: Whether PRD is sharded or monolithic
-  - `prd.prd-file`: Location of monolithic PRD (if not sharded)
+  - `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.architecture-file`: Location of monolithic architecture
+  - `architecture.architectureFile`: Location of monolithic architecture
   - `architecture.architectureShardedLocation`: Location of sharded architecture files
 
 ### 1. Identify Next Story for Preparation
@@ -2650,11 +2779,11 @@ To identify the next logical story based on project progress and epic definition
 
 - Based on `prdSharded` from config:
   - **If `prdSharded: true`**: Look for epic files in `prdShardedLocation` using `epicFilePattern`
-  - **If `prdSharded: false`**: Load the full PRD from `prd-file` and extract epics from section headings (## Epic N or ### Epic N)
+  - **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 `dev-story-location` from config (e.g., `docs/stories/`) for existing story files
+- 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).
@@ -2674,12 +2803,40 @@ To identify the next logical story based on project progress and epic definition
     ```
 
   - Proceed only if user selects option 3 (Override) or if the last story was 'Done'.
-  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and check for a story numbered `{lastStoryNum + 1}`. If it exists and its prerequisites (per Epic File) are met, this is the next story.
-  - Else (story not found or prerequisites not met): The next story is the first story in the next Epic File (e.g., look for `epic-{lastEpicNum + 1}*.md`, then `epic-{lastEpicNum + 2}*.md`, etc.) whose prerequisites are met.
+  - If proceeding: Look for the Epic File for `{lastEpicNum}` (e.g., `epic-{lastEpicNum}*.md`) and parse it to find ALL stories in that epic. **ALWAYS select the next sequential story** (e.g., if last was 2.2, next MUST be 2.3).
+  - If the next sequential story has unmet prerequisites, present this to the user:
+
+    ```plaintext
+    ALERT: Next story has unmet prerequisites:
+    Story: {epicNum}.{storyNum} - {Story Title}
+    Prerequisites not met: [list specific prerequisites]
+    
+    Would you like to:
+    1. Create the story anyway (mark prerequisites as pending)
+    2. Skip to a different story (requires your specific instruction)
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - If there are no more stories in the current epic (e.g., 2.9 was done and there is no 2.10):
+
+    ```plaintext
+    Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed.
+    
+    Would you like to:
+    1. Begin Epic {epicNum + 1} with story {epicNum + 1}.1
+    2. Select a specific story to work on
+    3. Cancel story creation
+    
+    Please choose an option (1/2/3):
+    ```
+
+  - **CRITICAL**: NEVER automatically skip to another epic or non-sequential story. The user MUST explicitly instruct which story to create if skipping the sequential order.
 
 - **If no story files exist in `docs/stories/`:**
-  - The next story is the first story in the first epic file (look for `epic-1-*.md`, then `epic-2-*.md`, etc.) whose prerequisites are met.
-- If no suitable story with met prerequisites is found, report to the user that story creation is blocked, specifying what prerequisites are pending. HALT task.
+  - The next story is ALWAYS 1.1 (the first story of the first epic).
+  - If story 1.1 has unmet prerequisites, follow the same alert process as above.
 - Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}".
 
 ### 2. Gather Core Story Requirements (from Epic)
@@ -2715,13 +2872,13 @@ Based on configuration loaded in Step 0:
   - Follow the structured reading order in section 4.2 below
   
 - **If `architectureVersion: v4` and `architectureSharded: false`**:
-  - Load the monolithic architecture from `architecture-file`
+  - 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 `architecture-file` for relevant sections
+  - If `architectureSharded: false`: Search within monolithic `architectureFile` for relevant sections
 
 #### 4.2 Recommended Reading Order Based on Story Type (v4 Sharded Only)
 
@@ -2778,7 +2935,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 
 ### 6. Populate Story Template with Full Context
 
-- Create a new story file: `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config).
+- 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}`
@@ -2825,7 +2982,7 @@ Format references as: `[Source: architecture/{filename}.md#{section}]`
 - Verify all source references are included for technical details
 - Ensure tasks align with both epic requirements and architecture constraints
 - Update status to "Draft"
-- Save the story file to `{dev-story-location}/{epicNum}.{storyNum}.story.md` (using location from config)
+- Save the story file to `{devStoryLocation}/{epicNum}.{storyNum}.story.md` (using location from config)
 
 ### 9. Report Completion
 

dist/teams/team-no-ui.txt

@@ -152,6 +152,11 @@ loading:
   - Agents: Only when transforming
   - Templates/Tasks: Only when executing
   - Always indicate loading
+kb-mode-behavior:
+  - When *kb-mode is invoked, use kb-mode-interaction task
+  - Don't dump all KB content immediately
+  - Present topic areas and wait for user selection
+  - Provide focused, contextual responses
 workflow-guidance:
   - Discover available workflows in the bundle at runtime
   - Understand each workflow's purpose, options, and decision points
@@ -165,6 +170,7 @@ dependencies:
   tasks:
     - advanced-elicitation
     - create-doc
+    - kb-mode-interaction
   data:
     - bmad-kb
   utils:
@@ -595,6 +601,79 @@ If template specifies a checklist:
 - Template markup is for AI processing only - never expose to users
 ==================== END: tasks#create-doc ====================
 
+==================== START: tasks#kb-mode-interaction ====================
+# KB Mode Interaction Task
+
+## Purpose
+Provide a user-friendly interface to the BMAD knowledge base without overwhelming users with information upfront.
+
+## Instructions
+
+When entering KB mode (*kb-mode), follow these steps:
+
+### 1. Welcome and Guide
+Announce entering KB mode with a brief, friendly introduction:
+
+"I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD."
+
+### 2. Present Topic Areas
+Offer a concise list of main topic areas the user might want to explore:
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+### 3. Respond Contextually
+- Wait for user's specific question or topic selection
+- Provide focused, relevant information from the knowledge base
+- Offer to dive deeper or explore related topics
+- Keep responses concise unless user asks for detailed explanations
+
+### 4. Interactive Exploration
+- After answering, suggest related topics they might find helpful
+- Maintain conversational flow rather than data dumping
+- Use examples when appropriate
+- Reference specific documentation sections when relevant
+
+### 5. Exit Gracefully
+When user is done or wants to exit KB mode:
+- Summarize key points discussed if helpful
+- Remind them they can return to KB mode anytime with *kb-mode
+- Suggest next steps based on what was discussed
+
+## Example Interaction
+
+**User**: *kb-mode
+
+**Assistant**: I've entered KB mode and have access to the full BMAD knowledge base. I can help you with detailed information about any aspect of BMAD-METHOD.
+
+**What would you like to know more about?**
+
+1. **Setup & Installation** - Getting started with BMAD
+2. **Workflows** - Choosing the right workflow for your project
+3. **Web vs IDE** - When to use each environment
+4. **Agents** - Understanding specialized agents and their roles
+5. **Documents** - PRDs, Architecture, Stories, and more
+6. **Agile Process** - How BMAD implements Agile methodologies
+7. **Configuration** - Customizing BMAD for your needs
+8. **Best Practices** - Tips for effective BMAD usage
+
+Or ask me about anything else related to BMAD-METHOD!
+
+**User**: Tell me about workflows
+
+**Assistant**: [Provides focused information about workflows from the KB, then offers to explore specific workflow types or related topics]
+==================== END: tasks#kb-mode-interaction ====================
+
 ==================== START: data#bmad-kb ====================
 # BMAD Knowledge Base
 
@@ -664,6 +743,64 @@ npx bmad-method install
 
 **Cost-Saving Tip**: Create large documents (PRDs, architecture) in web UI, then copy to `docs/prd.md` and `docs/architecture.md` in your project before switching to IDE for development.
 
+## Core Configuration (core-config.yml)
+
+**New in V4**: The `bmad-core/core-config.yml` file is a critical innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+### What is core-config.yml?
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It enables:
+
+- **Version Flexibility**: Work with V3, V4, or custom document structures
+- **Custom Locations**: Define where your documents and shards live
+- **Developer Context**: Specify which files the dev agent should always load
+- **Debug Support**: Built-in logging for troubleshooting
+
+### Key Configuration Areas
+
+#### PRD Configuration
+- **prdVersion**: Tells agents if PRD follows v3 or v4 conventions
+- **prdSharded**: Whether epics are embedded (false) or in separate files (true)
+- **prdShardedLocation**: Where to find sharded epic files
+- **epicFilePattern**: Pattern for epic filenames (e.g., `epic-{n}*.md`)
+
+#### Architecture Configuration
+- **architectureVersion**: v3 (monolithic) or v4 (sharded)
+- **architectureSharded**: Whether architecture is split into components
+- **architectureShardedLocation**: Where sharded architecture files live
+
+#### Developer Files
+- **devLoadAlwaysFiles**: List of files the dev agent loads for every task
+- **devDebugLog**: Where dev agent logs repeated failures
+- **agentCoreDump**: Export location for chat conversations
+
+### Why It Matters
+
+1. **No Forced Migrations**: Keep your existing document structure
+2. **Gradual Adoption**: Start with V3 and migrate to V4 at your pace
+3. **Custom Workflows**: Configure BMAD to match your team's process
+4. **Intelligent Agents**: Agents automatically adapt to your configuration
+
+### Common Configurations
+
+**Legacy V3 Project**:
+```yaml
+prdVersion: v3
+prdSharded: false
+architectureVersion: v3
+architectureSharded: false
+```
+
+**V4 Optimized Project**:
+```yaml
+prdVersion: v4
+prdSharded: true
+prdShardedLocation: docs/prd
+architectureVersion: v4
+architectureSharded: true
+architectureShardedLocation: docs/architecture
+```
+
 ## Core Philosophy
 
 ### Vibe CEO'ing
@@ -1076,7 +1213,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -1102,7 +1239,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -1118,7 +1255,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -1188,7 +1325,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -1214,7 +1351,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 
@@ -3223,7 +3360,7 @@ Create an `index.md` file in the sharded folder that:
 - [Section Name 2](./section-name-2.md)
 - [Section Name 3](./section-name-3.md)
   ...
-```text
+```
 
 ### 5. Preserve Special Content
 
@@ -5055,7 +5192,7 @@ servers:
       '[object Object]': null
     description:
       '[object Object]': null
-```text
+```
 
 ^^/CONDITION: has_rest_api^^
 
@@ -5118,7 +5255,6 @@ After presenting the structure, apply `tasks#advanced-elicitation` protocol to r
 ├── {{package-manifest}}        # Dependencies manifest
 ├── {{config-files}}            # Language/framework configs
 └── README.md                   # Project documentation
-```text
 
 @{example: monorepo-structure}
 project-root/
@@ -5130,6 +5266,7 @@ project-root/
 ├── scripts/ # Monorepo management scripts
 └── package.json # Root package.json with workspaces
 @{/example}
+```
 
 [[LLM: After presenting the source tree structure, apply `tasks#advanced-elicitation` protocol]]
 
@@ -6902,7 +7039,7 @@ Present component architecture and apply `tasks#advanced-elicitation` protocol]]
 
 ```mermaid
 {{component_interaction_diagram}}
-```text
+```
 
 ## API Design and Integration
 
@@ -6942,7 +7079,7 @@ Present API design and apply `tasks#advanced-elicitation` protocol]]
 
 ```json
 {{response_schema}}
-```text
+```
 
 <</REPEAT>>
 
@@ -8291,7 +8428,7 @@ workflow:
 
   sequence:
     - step: service_analysis
-     agent: architect
+      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."

docs/core-architecture.md

@@ -16,7 +16,7 @@ The system facilitates a full development lifecycle:
 
 The entire BMAD-Method ecosystem is designed around the `.bmad-core` directory, which acts as the brain of the operation. The `tools` directory provides the means to process and package this brain for different environments.
 
-````mermaid
+```mermaid
 graph TD
     subgraph BMAD Method Project
         subgraph Core Framework
@@ -59,7 +59,7 @@ graph TD
     style A fill:#1a73e8,color:#fff
     style I fill:#f9ab00,color:#fff
     style J fill:#34a853,color:#fff
-```text
+```
 
 ## 3. Core Components
 
@@ -110,6 +110,7 @@ The system maintains a clean separation of concerns: template markup is processe
 BMAD includes a personalization layer through the `technical-preferences.md` file in `.bmad-core/data/`. This file serves as a persistent technical profile that influences agent behavior across all projects.
 
 **Purpose and Benefits:**
+
 - **Consistency**: Ensures all agents reference the same technical preferences
 - **Efficiency**: Eliminates the need to repeatedly specify preferred technologies
 - **Personalization**: Agents provide recommendations aligned with user preferences
@@ -119,6 +120,7 @@ BMAD includes a personalization layer through the `technical-preferences.md` fil
 The file typically includes preferred technology stacks, design patterns, external services, coding standards, and anti-patterns to avoid. Agents automatically reference this file during planning and development to provide contextually appropriate suggestions.
 
 **Integration Points:**
+
 - Templates can reference technical preferences during document generation
 - Agents suggest preferred technologies when appropriate for project requirements
 - When preferences don't fit project needs, agents explain alternatives
@@ -173,7 +175,7 @@ graph TD
     style G fill:#f9ab00,color:#fff
     style L fill:#1a73e8,color:#fff
     style N fill:#34a853,color:#fff
-````
+```
 
 **Key Planning Phases:**
 

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

@@ -24,7 +24,7 @@ A pull request (PR) is how you propose changes to a project on GitHub. Think of
 # Replace YOUR-USERNAME with your actual GitHub username
 git clone https://github.com/YOUR-USERNAME/bmad-method.git
 cd bmad-method
-```text
+```
 
 ### 3. Create a New Branch
 
@@ -57,7 +57,7 @@ git add .
 
 # Commit with a clear message
 git commit -m "Fix typo in README.md"
-```text
+```
 
 **Good commit messages:**
 

docs/user-guide.md

@@ -56,10 +56,10 @@ Best for: ChatGPT, Claude, Gemini users
 
 Best for: Cursor, Claude Code, Windsurf, VS Code users
 
-````bash
+```bash
 # Interactive installation (recommended)
 npx bmad-method install
-```text
+```
 
 ### First Steps
 
@@ -106,7 +106,7 @@ dependencies:
     - shard-doc.md
   data:
     - bmad-kb.md
-````
+```
 
 **Key Points:**
 
@@ -118,7 +118,7 @@ dependencies:
 
 **In IDE:**
 
-````bash
+```bash
 # Cursor or Windsurf (manual rules - loaded with @)
 @pm Create a PRD for a task management app
 @architect Design the system architecture
@@ -127,7 +127,7 @@ dependencies:
 # Claude Code (files in commands folder - loaded with /)
 /pm Create user stories
 /dev Fix the login bug
-```text
+```
 
 **In Web UI:**
 
@@ -135,7 +135,7 @@ dependencies:
 /pm create-doc prd
 /architect review system design
 /dev implement story 1.2
-````
+```
 
 ## Templates and Document Creation
 
@@ -224,10 +224,9 @@ When working directly in IDEs:
 
 Templates can include `advanced-elicitation.md` for enhanced interaction:
 
-`````markdown
+```markdown
 [[LLM: Use advanced-elicitation actions 0-3 to refine requirements]]
-
-````text
+```
 
 This provides 10 structured brainstorming actions:
 
@@ -268,10 +267,7 @@ graph TD
     style G fill:#f9ab00,color:#fff
     style L fill:#1a73e8,color:#fff
     style N fill:#34a853,color:#fff
-````
-`````
-
-`````
+```
 
 #### Web UI to IDE Transition
 
@@ -286,7 +282,7 @@ graph TD
 
 Once planning is complete and documents are sharded, BMAD follows a structured development workflow:
 
-````mermaid
+```mermaid
 graph TD
     A["Start: Planning Artifacts Complete"] --> B["PO: Shard Epics"]
     B --> C["PO: Shard Arch"]
@@ -302,7 +298,7 @@ graph TD
     J --> E
 
     style J fill:#34a853,color:#fff
-```text
+```
 
 ### Workflow Phases
 
@@ -391,7 +387,7 @@ agents:
   - qa
 workflows:
   - greenfield-fullstack
-`````
+```
 
 ## IDE Integration
 
@@ -543,7 +539,7 @@ BMAD's dependency system ensures agents only load necessary resources:
 
 Create custom templates following `template-format.md`:
 
-`````markdown
+```markdown
 ---
 title: Custom Template
 description: Your custom document type
@@ -564,8 +560,7 @@ dependencies:
 ## Section 2
 
 {{section_2_content}}
-
-````text
+```
 
 ### Workflow Customization
 
@@ -594,10 +589,7 @@ phases:
     deliverables:
       - implementation
       - tests
-````
-`````
-
-`````
+```
 
 ### Creating Custom Templates
 
@@ -605,7 +597,7 @@ Templates are self-contained documents that embed both output structure and proc
 
 #### Template Structure
 
-````markdown
+```markdown
 # {{Project Name}} Document Title
 
 [[LLM: Opening instruction for AI processing]]
@@ -627,30 +619,32 @@ Templates are self-contained documents that embed both output structure and proc
 
 [[LLM: Only include if condition is met]]
 ^^/CONDITION^^
-
-````text
+```
 
 #### Key Template Patterns
 
 **Variable Substitution:**
+
 - `{{Project Name}}` - Dynamic project name
 - `{{document_title}}` - Document-specific title
 - `{{section_content}}` - Placeholder for generated content
 
 **AI Processing Instructions:**
+
 - `[[LLM: Instructions for AI behavior]]` - AI-only processing directives
 - `@{example: Sample content}` - Guidance examples (not output)
 - `tasks#advanced-elicitation` - Reference to embedded tasks
 
 **Conditional Content:**
+
 ```markdown
 ^^CONDITION: has_ui^^
+
 ## User Interface Section
+
 [[LLM: Only include for UI projects]]
 ^^/CONDITION^^
-`````
-
-`````
+```
 
 #### Document Sharding
 
@@ -658,7 +652,7 @@ Level 2 headings (`##`) in templates can be automatically sharded into separate
 
 **Original PRD:**
 
-````markdown
+```markdown
 ## Goals and Background Context
 
 ## Requirements
@@ -666,10 +660,10 @@ Level 2 headings (`##`) in templates can be automatically sharded into separate
 ## User Interface Design Goals
 
 ## Success Metrics
-
-````text
+```
 
 **After Sharding:**
+
 - `docs/prd/goals-and-background-context.md`
 - `docs/prd/requirements.md`
 - `docs/prd/user-interface-design-goals.md`
@@ -694,43 +688,40 @@ Tasks are reusable automation instructions that agents can execute. They follow
 ## Instructions
 
 ### 1. Step One
+
 - Detailed instructions for the agent
 - Specific behaviors and outputs expected
 
 ### 2. Step Two
+
 - Additional processing steps
 - Integration with other resources
 
 ## Examples
 
 @{example: Concrete usage examples}
-`````
-
-`````
+```
 
 #### Task Patterns
 
 **Resource Integration:**
 
-````markdown
+```markdown
 [[LLM: Check if docs/coding-standards.md exists and reference it]]
 [[LLM: Load docs/openapi-spec.yaml for API context]]
-
-````text
+```
 
 **Advanced Elicitation:**
+
 ```markdown
 [[LLM: Apply tasks#advanced-elicitation protocol after completion]]
-`````
-
-`````
+```
 
 **Conditional Logic:**
 
-````markdown
+```markdown
 [[LLM: If project has UI components, also check frontend standards]]
-
-````text
+```
 
 ### Creating Custom Agents
 
@@ -764,21 +755,19 @@ dependencies:
     - custom-task.md
   data:
     - domain-knowledge.md
-`````
-
-`````
+```
 
 #### Agent Startup Instructions
 
 Agents can load project-specific documents and provide custom context:
 
-````yaml
+```yaml
 startup:
   - Load docs/coding-standards.md if available
   - Review docs/project-structure.md for context
   - Check for docs/third-party-apis/ folder
   - Announce specialized capabilities
-```text
+```
 
 #### Loading Project Documents
 
@@ -794,11 +783,12 @@ Agents can reference and load documents from the `docs/` folder:
 
 ```markdown
 [[LLM: Before beginning, check for and load relevant context:
+
 - docs/coding-standards.md for development standards
 - docs/brand-guidelines.md for design consistency
 - docs/third-party-apis/ for integration requirements
 - Any project-specific documentation in docs/ folder]]
-`````
+```
 
 ### Technical Preferences System
 
@@ -812,7 +802,7 @@ This file allows you to define your preferred technologies, patterns, and standa
 
 **Technology Stack Preferences:**
 
-`````markdown
+```markdown
 ## Preferred Technologies
 
 ### Frontend
@@ -831,29 +821,28 @@ This file allows you to define your preferred technologies, patterns, and standa
 
 - Vercel for frontend
 - Railway for backend services
-
-````text
+```
 
 **Design Patterns & Standards:**
+
 ```markdown
 ## Code Standards
+
 - Use functional programming patterns where possible
 - Prefer composition over inheritance
 - Always include comprehensive error handling
 - Write tests for all business logic
 
 ## Architecture Preferences
+
 - Microservices for complex applications
 - RESTful APIs with OpenAPI documentation
 - Event-driven architecture for real-time features
-````
-`````
-
-`````
+```
 
 **External Services & APIs:**
 
-````markdown
+```markdown
 ## Preferred External Services
 
 - Auth0 for authentication
@@ -865,8 +854,7 @@ This file allows you to define your preferred technologies, patterns, and standa
 
 - Legacy SOAP services
 - Services without proper documentation
-
-````text
+```
 
 #### How Agents Use This File
 
@@ -880,24 +868,264 @@ This file allows you to define your preferred technologies, patterns, and standa
 
 **Learning and Evolution**: As you work on projects, add discoveries to your preferences file:
 
-```markdown
 ## Lessons Learned
+
 - Avoid using Library X for large datasets (performance issues)
 - Pattern Y works well for real-time features
 - Service Z has excellent documentation and support
 
 ## Future Exploration
+
 - Want to try Framework A on next appropriate project
 - Interested in Pattern B for microservices
 - Consider Service C for better performance
-`````
 
-````
-
-#### Using with Web Bundles
+### Using with Web Bundles
 
 When creating custom web bundles or uploading to AI platforms, include your `technical-preferences.md` content to ensure agents have your preferences from the start of any conversation.
 
+### Core Configuration (core-config.yml)
+
+The `bmad-core/core-config.yml` file is a critical V4 innovation that enables BMAD to work seamlessly with any project structure, providing maximum flexibility and backwards compatibility.
+
+#### Understanding core-config.yml
+
+This configuration file acts as a map for BMAD agents, telling them exactly where to find your project documents and how they're structured. It's what makes V4 agents intelligent enough to work with V3 projects, custom layouts, or any document organization you prefer.
+
+#### Configuration Structure
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: docs/stories # Where completed stories are saved
+
+  prd:
+    prdFile: docs/prd.md
+    prdVersion: v4 # v3 or v4
+    prdSharded: true # false if epics are embedded in PRD
+    prdShardedLocation: docs/prd # Where sharded epics live
+    epicFilePattern: epic-{n}*.md # Pattern for epic files
+
+  architecture:
+    architectureFile: docs/architecture.md
+    architectureVersion: v4 # v3 or v4
+    architectureSharded: true # false if monolithic
+    architectureShardedLocation: docs/architecture
+
+  customTechnicalDocuments: null # Additional docs for SM
+
+  devLoadAlwaysFiles: # Files dev agent always loads
+    - docs/architecture/coding-standards.md
+    - docs/architecture/tech-stack.md
+    - docs/architecture/project-structure.md
+
+  devDebugLog: .ai/debug-log.md # Dev agent debug tracking
+  agentCoreDump: .ai/core-dump{n}.md # Export chat contents
+```
+
+#### Key Configuration Options
+
+##### PRD Configuration
+
+The Scrum Master agent uses these settings to locate epics:
+
+**V4 Sharded Structure:**
+
+```yaml
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v4
+  prdSharded: true
+  prdShardedLocation: docs/prd
+  epicFilePattern: epic-{n}*.md
+```
+
+**V3 Embedded Epics:**
+
+```yaml
+prd:
+  prdFile: docs/prd.md
+  prdVersion: v3
+  prdSharded: false # Epics are inside PRD
+```
+
+**Custom Sharded Location:**
+
+```yaml
+prd:
+  prdFile: docs/product-requirements.md
+  prdVersion: v4
+  prdSharded: true
+  prdShardedLocation: docs # Epics in docs/ not docs/prd/
+  epicFilePattern: epic-*.md
+```
+
+##### Architecture Configuration
+
+Similar flexibility for architecture documents:
+
+**V4 Sharded Architecture:**
+
+```yaml
+architecture:
+  architectureFile: docs/architecture.md
+  architectureVersion: v4
+  architectureSharded: true
+  architectureShardedLocation: docs/architecture
+```
+
+**V3 Monolithic Architecture:**
+
+```yaml
+architecture:
+  architectureFile: docs/technical-architecture.md
+  architectureVersion: v3
+  architectureSharded: false # All in one file
+```
+
+##### Developer Context Files
+
+Define which files the dev agent should always load:
+
+```yaml
+devLoadAlwaysFiles:
+  - docs/architecture/coding-standards.md
+  - docs/architecture/tech-stack.md
+  - docs/architecture/project-structure.md
+  - docs/api-contracts.yaml
+  - docs/database-schema.md
+  - .env.example
+```
+
+This ensures the dev agent always has critical context without needing to search for it.
+
+##### Debug and Export Options
+
+**Debug Log:**
+
+```yaml
+devDebugLog: .ai/debug-log.md
+```
+
+When the dev agent encounters repeated failures implementing a story, it logs issues here to avoid repeating the same mistakes.
+
+**Core Dump:**
+
+```yaml
+agentCoreDump: .ai/core-dump{n}.md
+```
+
+Export entire chat conversations for preservation or analysis. The `{n}` is replaced with a number.
+
+#### Common Configurations
+
+##### Legacy V3 Project
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: docs/stories
+  prd:
+    prdFile: docs/prd.md
+    prdVersion: v3
+    prdSharded: false
+  architecture:
+    architectureFile: docs/architecture.md
+    architectureVersion: v3
+    architectureSharded: false
+  devLoadAlwaysFiles: []
+```
+
+##### Hybrid Project (V3 PRD, V4 Architecture)
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: .ai/stories
+  prd:
+    prdFile: docs/product-requirements.md
+    prdVersion: v3
+    prdSharded: false
+  architecture:
+    architectureFile: docs/architecture.md
+    architectureVersion: v4
+    architectureSharded: true
+    architectureShardedLocation: docs/architecture
+  devLoadAlwaysFiles:
+    - docs/architecture/tech-stack.md
+```
+
+##### Custom Organization
+
+```yaml
+coreProjectLocation:
+  devStoryLocation: development/completed-stories
+  prd:
+    prdFile: planning/requirements.md
+    prdVersion: v4
+    prdSharded: true
+    prdShardedLocation: planning/epics
+    epicFilePattern: requirement-{n}.md
+  architecture:
+    architectureFile: technical/system-design.md
+    architectureVersion: v4
+    architectureSharded: true
+    architectureShardedLocation: technical/components
+  customTechnicalDocuments:
+    - technical/api-guide.md
+    - technical/deployment.md
+  devLoadAlwaysFiles:
+    - technical/coding-guidelines.md
+    - technical/git-workflow.md
+```
+
+#### Migration Strategies
+
+##### Gradual V3 to V4 Migration
+
+Start with V3 documents and gradually adopt V4 patterns:
+
+1. **Initial State**: Set `prdVersion: v3` and `prdSharded: false`
+2. **Shard PRD**: Use PO agent to shard, then update to `prdSharded: true`
+3. **Update Version**: Change to `prdVersion: v4` after using V4 templates
+4. **Repeat for Architecture**: Same process for architecture documents
+
+##### Working with Mixed Teams
+
+If some team members use V3 and others use V4:
+
+```yaml
+# Support both patterns
+customTechnicalDocuments:
+  - docs/legacy-requirements.md # V3 format
+  - docs/prd.md # V4 format
+```
+
+#### Best Practices
+
+1. **Always Configure for Your Structure**: Don't force your project to match BMAD defaults
+2. **Keep devLoadAlwaysFiles Focused**: Only include files needed for every dev task
+3. **Use Debug Log**: Enable when troubleshooting story implementation issues
+4. **Version Control core-config.yml**: Track changes to understand project evolution
+5. **Document Custom Patterns**: If using custom epicFilePattern, document it
+
+#### Troubleshooting
+
+**Scrum Master Can't Find Epics:**
+
+- Check `prdSharded` matches your structure
+- Verify `prdShardedLocation` path exists
+- Confirm `epicFilePattern` matches your files
+
+**Dev Agent Missing Context:**
+
+- Add critical files to `devLoadAlwaysFiles`
+- Ensure file paths are correct
+- Check files exist and are readable
+
+**Architecture Not Loading:**
+
+- Verify `architectureFile` path
+- Check `architectureVersion` setting
+- Confirm sharding configuration matches reality
+
 ### Extension Packs
 
 Add specialized capabilities:
@@ -1050,4 +1278,3 @@ Remember: BMAD is designed to enhance your development process, not replace your
 ---
 
 For additional support, join our [Discord community](https://discord.gg/g6ypHytrCB) or check out the [YouTube channel](https://www.youtube.com/@BMadCode) for video tutorials and walkthroughs.
-````

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

@@ -55,4 +55,4 @@ dependencies:
     - game-brief-tmpl
   checklists:
     - game-design-checklist
-```
+```

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

@@ -48,10 +48,10 @@ commands:
 task-execution:
   flow: Read story → Implement game feature → Write tests → Pass tests → Update [x] → Next task
   updates-ONLY:
-    - 'Checkboxes: [ ] not started | [-] in progress | [x] complete'
-    - 'Debug Log: | Task | File | Change | Reverted? |'
-    - 'Completion Notes: Deviations only, <50 words'
-    - 'Change Log: Requirement changes only'
+    - "Checkboxes: [ ] not started | [-] in progress | [x] complete"
+    - "Debug Log: | Task | File | Change | Reverted? |"
+    - "Completion Notes: Deviations only, <50 words"
+    - "Change Log: Requirement changes only"
   blocking: Unapproved deps | Ambiguous after story check | 3 failures | Missing game config
   done: Game feature works + Tests pass + 60 FPS + No lint errors + Follows Phaser 3 best practices
 dependencies:
@@ -63,4 +63,4 @@ dependencies:
     - game-story-dod-checklist
   data:
     - development-guidelines
-```
+```

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

@@ -33,7 +33,7 @@ startup:
   - CRITICAL: Do NOT create or modify any files during startup
   - Offer to help with game story preparation but wait for explicit user confirmation
   - Only execute tasks when user explicitly requests them
-  - 'CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Game Developer Agent'
+  - "CRITICAL RULE: You are ONLY allowed to create/modify story files - NEVER implement! If asked to implement, tell user they MUST switch to Game Developer Agent"
 commands:
   - '*help" - Show numbered list of available commands for selection'
   - '*chat-mode" - Conversational mode with advanced-elicitation for game dev advice'
@@ -48,4 +48,4 @@ dependencies:
     - game-story-tmpl
   checklists:
     - game-story-dod-checklist
-```
+```

expansion-packs/bmad-2d-phaser-game-dev/checklists/game-design-checklist.md

@@ -3,6 +3,7 @@
 ## Document Completeness
 
 ### Executive Summary
+
 - [ ] **Core Concept** - Game concept is clearly explained in 2-3 sentences
 - [ ] **Target Audience** - Primary and secondary audiences defined with demographics
 - [ ] **Platform Requirements** - Technical platforms and requirements specified
@@ -10,6 +11,7 @@
 - [ ] **Technical Foundation** - Phaser 3 + TypeScript requirements confirmed
 
 ### Game Design Foundation
+
 - [ ] **Game Pillars** - 3-5 core design pillars defined and actionable
 - [ ] **Core Gameplay Loop** - 30-60 second loop documented with specific timings
 - [ ] **Win/Loss Conditions** - Clear victory and failure states defined
@@ -19,6 +21,7 @@
 ## Gameplay Mechanics
 
 ### Core Mechanics Documentation
+
 - [ ] **Primary Mechanics** - 3-5 core mechanics detailed with implementation notes
 - [ ] **Mechanic Integration** - How mechanics work together is clear
 - [ ] **Player Input** - All input methods specified for each platform
@@ -26,6 +29,7 @@
 - [ ] **Performance Impact** - Performance considerations for each mechanic noted
 
 ### Controls and Interaction
+
 - [ ] **Multi-Platform Controls** - Desktop, mobile, and gamepad controls defined
 - [ ] **Input Responsiveness** - Requirements for responsive game feel specified
 - [ ] **Accessibility Options** - Control customization and accessibility considered
@@ -35,6 +39,7 @@
 ## Progression and Balance
 
 ### Player Progression
+
 - [ ] **Progression Type** - Linear, branching, or metroidvania approach defined
 - [ ] **Key Milestones** - Major progression points documented
 - [ ] **Unlock System** - What players unlock and when is specified
@@ -42,6 +47,7 @@
 - [ ] **Player Agency** - Meaningful player choices and consequences defined
 
 ### Game Balance
+
 - [ ] **Balance Parameters** - Numeric values for key game systems provided
 - [ ] **Difficulty Curve** - Appropriate challenge progression designed
 - [ ] **Economy Design** - Resource systems balanced for engagement
@@ -51,6 +57,7 @@
 ## Level Design Framework
 
 ### Level Structure
+
 - [ ] **Level Types** - Different level categories defined with purposes
 - [ ] **Level Progression** - How players move through levels specified
 - [ ] **Duration Targets** - Expected play time for each level type
@@ -58,6 +65,7 @@
 - [ ] **Replay Value** - Elements that encourage repeated play designed
 
 ### Content Guidelines
+
 - [ ] **Level Creation Rules** - Clear guidelines for level designers
 - [ ] **Mechanic Introduction** - How new mechanics are taught in levels
 - [ ] **Pacing Variety** - Mix of action, puzzle, and rest moments planned
@@ -67,6 +75,7 @@
 ## Technical Implementation Readiness
 
 ### Performance Requirements
+
 - [ ] **Frame Rate Targets** - 60 FPS target with minimum acceptable rates
 - [ ] **Memory Budgets** - Maximum memory usage limits defined
 - [ ] **Load Time Goals** - Acceptable loading times for different content
@@ -74,6 +83,7 @@
 - [ ] **Scalability Plan** - How performance scales across different devices
 
 ### Platform Specifications
+
 - [ ] **Desktop Requirements** - Minimum and recommended PC/Mac specs
 - [ ] **Mobile Optimization** - iOS and Android specific requirements
 - [ ] **Browser Compatibility** - Supported browsers and versions listed
@@ -81,6 +91,7 @@
 - [ ] **Update Strategy** - Plan for post-launch updates and patches
 
 ### Asset Requirements
+
 - [ ] **Art Style Definition** - Clear visual style with reference materials
 - [ ] **Asset Specifications** - Technical requirements for all asset types
 - [ ] **Audio Requirements** - Music and sound effect specifications
@@ -90,6 +101,7 @@
 ## Development Planning
 
 ### Implementation Phases
+
 - [ ] **Phase Breakdown** - Development divided into logical phases
 - [ ] **Epic Definitions** - Major development epics identified
 - [ ] **Dependency Mapping** - Prerequisites between features documented
@@ -97,6 +109,7 @@
 - [ ] **Milestone Planning** - Key deliverables and deadlines established
 
 ### Team Requirements
+
 - [ ] **Role Definitions** - Required team roles and responsibilities
 - [ ] **Skill Requirements** - Technical skills needed for implementation
 - [ ] **Resource Allocation** - Time and effort estimates for major features
@@ -106,6 +119,7 @@
 ## Quality Assurance
 
 ### Success Metrics
+
 - [ ] **Technical Metrics** - Measurable technical performance goals
 - [ ] **Gameplay Metrics** - Player engagement and retention targets
 - [ ] **Quality Benchmarks** - Standards for bug rates and polish level
@@ -113,6 +127,7 @@
 - [ ] **Business Objectives** - Commercial or project success criteria
 
 ### Testing Strategy
+
 - [ ] **Playtesting Plan** - How and when player feedback will be gathered
 - [ ] **Technical Testing** - Performance and compatibility testing approach
 - [ ] **Balance Validation** - Methods for confirming game balance
@@ -122,6 +137,7 @@
 ## Documentation Quality
 
 ### Clarity and Completeness
+
 - [ ] **Clear Writing** - All sections are well-written and understandable
 - [ ] **Complete Coverage** - No major game systems left undefined
 - [ ] **Actionable Detail** - Enough detail for developers to create implementation stories
@@ -129,6 +145,7 @@
 - [ ] **Reference Materials** - Links to inspiration, research, and additional resources
 
 ### Maintainability
+
 - [ ] **Version Control** - Change log established for tracking revisions
 - [ ] **Update Process** - Plan for maintaining document during development
 - [ ] **Team Access** - All team members can access and reference the document
@@ -138,6 +155,7 @@
 ## Stakeholder Alignment
 
 ### Team Understanding
+
 - [ ] **Shared Vision** - All team members understand and agree with the game vision
 - [ ] **Role Clarity** - Each team member understands their contribution
 - [ ] **Decision Framework** - Process for making design decisions during development
@@ -145,6 +163,7 @@
 - [ ] **Communication Channels** - Regular meetings and feedback sessions planned
 
 ### External Validation
+
 - [ ] **Market Validation** - Competitive analysis and market fit assessment
 - [ ] **Technical Validation** - Feasibility confirmed with technical team
 - [ ] **Resource Validation** - Required resources available and committed
@@ -154,6 +173,7 @@
 ## Final Readiness Assessment
 
 ### Implementation Preparedness
+
 - [ ] **Story Creation Ready** - Document provides sufficient detail for story creation
 - [ ] **Architecture Alignment** - Game design aligns with technical capabilities
 - [ ] **Asset Production** - Asset requirements enable art and audio production
@@ -161,6 +181,7 @@
 - [ ] **Quality Assurance** - Testing and validation processes established
 
 ### Document Approval
+
 - [ ] **Design Review Complete** - Document reviewed by all relevant stakeholders
 - [ ] **Technical Review Complete** - Technical feasibility confirmed
 - [ ] **Business Review Complete** - Project scope and goals approved
@@ -177,4 +198,4 @@
 _List any critical items that need attention before moving to implementation phase._
 
 **Next Steps:**
-_Outline immediate next actions for the team based on this assessment._
+_Outline immediate next actions for the team based on this assessment._

expansion-packs/bmad-2d-phaser-game-dev/checklists/game-story-dod-checklist.md

@@ -3,6 +3,7 @@
 ## Story Completeness
 
 ### Basic Story Elements
+
 - [ ] **Story Title** - Clear, descriptive title that identifies the feature
 - [ ] **Epic Assignment** - Story is properly assigned to relevant epic
 - [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
@@ -10,6 +11,7 @@
 - [ ] **Description** - Clear, concise description of what needs to be implemented
 
 ### Game Design Alignment
+
 - [ ] **GDD Reference** - Specific Game Design Document section referenced
 - [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
 - [ ] **Player Experience Goal** - Describes the intended player experience
@@ -19,6 +21,7 @@
 ## Technical Specifications
 
 ### Architecture Compliance
+
 - [ ] **File Organization** - Follows game architecture document structure
 - [ ] **Class Definitions** - TypeScript interfaces and classes are properly defined
 - [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
@@ -26,6 +29,7 @@
 - [ ] **Dependencies** - All system dependencies clearly identified
 
 ### Phaser 3 Requirements
+
 - [ ] **Scene Integration** - Specifies which scenes are affected and how
 - [ ] **Game Object Usage** - Proper use of Phaser 3 game objects and components
 - [ ] **Physics Integration** - Physics requirements specified if applicable
@@ -33,6 +37,7 @@
 - [ ] **Performance Considerations** - 60 FPS target and optimization requirements
 
 ### Code Quality Standards
+
 - [ ] **TypeScript Strict Mode** - All code must comply with strict TypeScript
 - [ ] **Error Handling** - Error scenarios and handling requirements specified
 - [ ] **Memory Management** - Object pooling and cleanup requirements where needed
@@ -42,6 +47,7 @@
 ## Implementation Readiness
 
 ### Acceptance Criteria
+
 - [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
 - [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
 - [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
@@ -49,6 +55,7 @@
 - [ ] **Completeness** - No acceptance criteria are vague or unmeasurable
 
 ### Implementation Tasks
+
 - [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
 - [ ] **Task Scope** - Each task is completable in 1-4 hours
 - [ ] **Task Clarity** - Each task has clear, actionable instructions
@@ -56,6 +63,7 @@
 - [ ] **Development Flow** - Tasks follow logical implementation order
 
 ### Dependencies
+
 - [ ] **Story Dependencies** - All prerequisite stories identified with IDs
 - [ ] **Technical Dependencies** - Required systems and files identified
 - [ ] **Asset Dependencies** - All needed assets specified with locations
@@ -65,6 +73,7 @@
 ## Testing Requirements
 
 ### Test Coverage
+
 - [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined
 - [ ] **Integration Test Cases** - Integration testing with other game systems specified
 - [ ] **Manual Test Cases** - Game-specific manual testing procedures defined
@@ -72,6 +81,7 @@
 - [ ] **Edge Case Testing** - Edge cases and error conditions covered
 
 ### Test Implementation
+
 - [ ] **Test File Paths** - Exact test file locations specified
 - [ ] **Test Scenarios** - All test scenarios are complete and executable
 - [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
@@ -81,6 +91,7 @@
 ## Game-Specific Quality
 
 ### Gameplay Implementation
+
 - [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
 - [ ] **Player Controls** - Input handling requirements are complete
 - [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
@@ -88,6 +99,7 @@
 - [ ] **State Management** - Game state changes and persistence requirements defined
 
 ### User Experience
+
 - [ ] **UI Requirements** - User interface elements and behaviors specified
 - [ ] **Audio Integration** - Sound effect and music requirements defined
 - [ ] **Visual Feedback** - Animation and visual effect requirements specified
@@ -95,6 +107,7 @@
 - [ ] **Error Recovery** - User-facing error handling and recovery specified
 
 ### Performance Optimization
+
 - [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
 - [ ] **Memory Usage** - Memory consumption limits and monitoring requirements
 - [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
@@ -104,6 +117,7 @@
 ## Documentation and Communication
 
 ### Story Documentation
+
 - [ ] **Implementation Notes** - Additional context and implementation guidance provided
 - [ ] **Design Decisions** - Key design choices documented with rationale
 - [ ] **Future Considerations** - Potential future enhancements or modifications noted
@@ -111,6 +125,7 @@
 - [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs
 
 ### Developer Handoff
+
 - [ ] **Immediate Actionability** - Developer can start implementation without additional questions
 - [ ] **Complete Context** - All necessary context provided within the story
 - [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
@@ -120,6 +135,7 @@
 ## Final Validation
 
 ### Story Readiness
+
 - [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
 - [ ] **Technical Completeness** - All technical requirements are specified and actionable
 - [ ] **Scope Appropriateness** - Story scope matches assigned story points
@@ -127,6 +143,7 @@
 - [ ] **Review Completion** - Story has been reviewed for completeness and accuracy
 
 ### Implementation Preparedness
+
 - [ ] **Environment Ready** - Development environment requirements specified
 - [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
 - [ ] **Testing Prepared** - Testing environment and data requirements specified
@@ -140,4 +157,4 @@
 **Ready for Development:** [ ] Yes [ ] No
 
 **Additional Notes:**
-_Any specific concerns, recommendations, or clarifications needed before development begins._
+_Any specific concerns, recommendations, or clarifications needed before development begins._

expansion-packs/bmad-2d-phaser-game-dev/data/development-guidelines.md

@@ -9,6 +9,7 @@ This document establishes coding standards, architectural patterns, and developm
 ### Strict Mode Configuration
 
 **Required tsconfig.json settings:**
+
 ```json
 {
   "compilerOptions": {
@@ -22,11 +23,12 @@ This document establishes coding standards, architectural patterns, and developm
     "exactOptionalPropertyTypes": true
   }
 }
-```text
+```
 
 ### Type Definitions
 
 **Game Object Interfaces:**
+
 ```typescript
 // Core game entity interface
 interface GameEntity {
@@ -50,9 +52,10 @@ interface GameSystem {
   update(delta: number): void;
   shutdown(): void;
 }
-```text
+```
 
 **Scene Data Interfaces:**
+
 ```typescript
 // Scene transition data
 interface SceneData {
@@ -70,28 +73,32 @@ interface GameState {
 interface GameSettings {
   musicVolume: number;
   sfxVolume: number;
-  difficulty: 'easy' | 'normal' | 'hard';
+  difficulty: "easy" | "normal" | "hard";
   controls: ControlScheme;
 }
-```text
+```
 
 ### Naming Conventions
 
 **Classes and Interfaces:**
+
 - PascalCase for classes: `PlayerSprite`, `GameManager`, `AudioSystem`
 - PascalCase with 'I' prefix for interfaces: `IGameEntity`, `IPlayerController`
 - Descriptive names that indicate purpose: `CollisionManager` not `CM`
 
 **Methods and Variables:**
+
 - camelCase for methods and variables: `updatePosition()`, `playerSpeed`
 - Descriptive names: `calculateDamage()` not `calcDmg()`
 - Boolean variables with is/has/can prefix: `isActive`, `hasCollision`, `canMove`
 
 **Constants:**
+
 - UPPER_SNAKE_CASE for constants: `MAX_PLAYER_SPEED`, `DEFAULT_VOLUME`
 - Group related constants in enums or const objects
 
 **Files and Directories:**
+
 - kebab-case for file names: `player-controller.ts`, `audio-manager.ts`
 - PascalCase for scene files: `MenuScene.ts`, `GameScene.ts`
 
@@ -100,88 +107,91 @@ interface GameSettings {
 ### Scene Organization
 
 **Scene Lifecycle Management:**
+
 ```typescript
 class GameScene extends Phaser.Scene {
   private gameManager!: GameManager;
   private inputManager!: InputManager;
-  
+
   constructor() {
-    super({ key: 'GameScene' });
+    super({ key: "GameScene" });
   }
-  
+
   preload(): void {
     // Load only scene-specific assets
-    this.load.image('player', 'assets/player.png');
+    this.load.image("player", "assets/player.png");
   }
-  
+
   create(data: SceneData): void {
     // Initialize game systems
     this.gameManager = new GameManager(this);
     this.inputManager = new InputManager(this);
-    
+
     // Set up scene-specific logic
     this.setupGameObjects();
     this.setupEventListeners();
   }
-  
+
   update(time: number, delta: number): void {
     // Update all game systems
     this.gameManager.update(delta);
     this.inputManager.update(delta);
   }
-  
+
   shutdown(): void {
     // Clean up resources
     this.gameManager.destroy();
     this.inputManager.destroy();
-    
+
     // Remove event listeners
-    this.events.off('*');
+    this.events.off("*");
   }
 }
 ```
 
 **Scene Transitions:**
+
 ```typescript
 // Proper scene transitions with data
-this.scene.start('NextScene', {
+this.scene.start("NextScene", {
   playerScore: this.playerScore,
-  currentLevel: this.currentLevel + 1
+  currentLevel: this.currentLevel + 1,
 });
 
 // Scene overlays for UI
-this.scene.launch('PauseMenuScene');
+this.scene.launch("PauseMenuScene");
 this.scene.pause();
-```text
+```
 
 ### Game Object Patterns
 
 **Component-Based Architecture:**
+
 ```typescript
 // Base game entity
 abstract class GameEntity extends Phaser.GameObjects.Sprite {
   protected components: Map<string, GameComponent> = new Map();
-  
+
   constructor(scene: Phaser.Scene, x: number, y: number, texture: string) {
     super(scene, x, y, texture);
     scene.add.existing(this);
   }
-  
+
   addComponent<T extends GameComponent>(component: T): T {
     this.components.set(component.name, component);
     return component;
   }
-  
+
   getComponent<T extends GameComponent>(name: string): T | undefined {
     return this.components.get(name) as T;
   }
-  
+
   update(delta: number): void {
-    this.components.forEach(component => component.update(delta));
+    this.components.forEach((component) => component.update(delta));
   }
-  
+
   destroy(): void {
-    this.components.forEach(component => component.destroy());
+    this.components.forEach((component) => component.destroy());
     this.components.clear();
     super.destroy();
   }
@@ -191,65 +201,67 @@ abstract class GameEntity extends Phaser.GameObjects.Sprite {
 class Player extends GameEntity {
   private movement!: MovementComponent;
   private health!: HealthComponent;
-  
+
   constructor(scene: Phaser.Scene, x: number, y: number) {
-    super(scene, x, y, 'player');
-    
+    super(scene, x, y, "player");
+
     this.movement = this.addComponent(new MovementComponent(this));
     this.health = this.addComponent(new HealthComponent(this, 100));
   }
 }
-```text
+```
 
 ### System Management
 
 **Singleton Managers:**
+
 ```typescript
 class GameManager {
   private static instance: GameManager;
   private scene: Phaser.Scene;
   private gameState: GameState;
-  
+
   constructor(scene: Phaser.Scene) {
     if (GameManager.instance) {
-      throw new Error('GameManager already exists!');
+      throw new Error("GameManager already exists!");
     }
-    
+
     this.scene = scene;
     this.gameState = this.loadGameState();
     GameManager.instance = this;
   }
-  
+
   static getInstance(): GameManager {
     if (!GameManager.instance) {
-      throw new Error('GameManager not initialized!');
+      throw new Error("GameManager not initialized!");
     }
     return GameManager.instance;
   }
-  
+
   update(delta: number): void {
     // Update game logic
   }
-  
+
   destroy(): void {
     GameManager.instance = null!;
   }
 }
-```text
+```
 
 ## Performance Optimization
 
 ### Object Pooling
 
 **Required for High-Frequency Objects:**
+
 ```typescript
 class BulletPool {
   private pool: Bullet[] = [];
   private scene: Phaser.Scene;
-  
+
   constructor(scene: Phaser.Scene, initialSize: number = 50) {
     this.scene = scene;
-    
+
     // Pre-create bullets
     for (let i = 0; i < initialSize; i++) {
       const bullet = new Bullet(scene, 0, 0);
@@ -258,20 +270,20 @@ class BulletPool {
       this.pool.push(bullet);
     }
   }
-  
+
   getBullet(): Bullet | null {
-    const bullet = this.pool.find(b => !b.active);
+    const bullet = this.pool.find((b) => !b.active);
     if (bullet) {
       bullet.setActive(true);
       bullet.setVisible(true);
       return bullet;
     }
-    
+
     // Pool exhausted - create new bullet
-    console.warn('Bullet pool exhausted, creating new bullet');
+    console.warn("Bullet pool exhausted, creating new bullet");
     return new Bullet(this.scene, 0, 0);
   }
-  
+
   releaseBullet(bullet: Bullet): void {
     bullet.setActive(false);
     bullet.setVisible(false);
@@ -283,45 +295,47 @@ class BulletPool {
 ### Frame Rate Optimization
 
 **Performance Monitoring:**
+
 ```typescript
 class PerformanceMonitor {
   private frameCount: number = 0;
   private lastTime: number = 0;
   private frameRate: number = 60;
-  
+
   update(time: number): void {
     this.frameCount++;
-    
+
     if (time - this.lastTime >= 1000) {
       this.frameRate = this.frameCount;
       this.frameCount = 0;
       this.lastTime = time;
-      
+
       if (this.frameRate < 55) {
         console.warn(`Low frame rate detected: ${this.frameRate} FPS`);
         this.optimizePerformance();
       }
     }
   }
-  
+
   private optimizePerformance(): void {
     // Reduce particle counts, disable effects, etc.
   }
 }
-```text
+```
 
 **Update Loop Optimization:**
+
 ```typescript
 // Avoid expensive operations in update loops
 class GameScene extends Phaser.Scene {
   private updateTimer: number = 0;
   private readonly UPDATE_INTERVAL = 100; // ms
-  
+
   update(time: number, delta: number): void {
     // High-frequency updates (every frame)
     this.updatePlayer(delta);
     this.updatePhysics(delta);
-    
+
     // Low-frequency updates (10 times per second)
     this.updateTimer += delta;
     if (this.updateTimer >= this.UPDATE_INTERVAL) {
@@ -331,13 +345,14 @@ class GameScene extends Phaser.Scene {
     }
   }
 }
-```text
+```
 
 ## Input Handling
 
 ### Cross-Platform Input
 
 **Input Abstraction:**
+
 ```typescript
 interface InputState {
   moveLeft: boolean;
@@ -353,26 +368,26 @@ class InputManager {
     moveRight: false,
     jump: false,
     action: false,
-    pause: false
+    pause: false,
   };
-  
+
   private keys!: { [key: string]: Phaser.Input.Keyboard.Key };
   private pointer!: Phaser.Input.Pointer;
-  
+
   constructor(private scene: Phaser.Scene) {
     this.setupKeyboard();
     this.setupTouch();
   }
-  
+
   private setupKeyboard(): void {
-    this.keys = this.scene.input.keyboard.addKeys('W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT');
+    this.keys = this.scene.input.keyboard.addKeys("W,A,S,D,SPACE,ESC,UP,DOWN,LEFT,RIGHT");
   }
-  
+
   private setupTouch(): void {
-    this.scene.input.on('pointerdown', this.handlePointerDown, this);
-    this.scene.input.on('pointerup', this.handlePointerUp, this);
+    this.scene.input.on("pointerdown", this.handlePointerDown, this);
+    this.scene.input.on("pointerup", this.handlePointerUp, this);
   }
-  
+
   update(): void {
     // Update input state from multiple sources
     this.inputState.moveLeft = this.keys.A.isDown || this.keys.LEFT.isDown;
@@ -380,42 +395,43 @@ class InputManager {
     this.inputState.jump = Phaser.Input.Keyboard.JustDown(this.keys.SPACE);
     // ... handle touch input
   }
-  
+
   getInputState(): InputState {
     return { ...this.inputState };
   }
 }
-```text
+```
 
 ## Error Handling
 
 ### Graceful Degradation
 
 **Asset Loading Error Handling:**
+
 ```typescript
 class AssetManager {
   loadAssets(): Promise<void> {
     return new Promise((resolve, reject) => {
-      this.scene.load.on('filecomplete', this.handleFileComplete, this);
-      this.scene.load.on('loaderror', this.handleLoadError, this);
-      this.scene.load.on('complete', () => resolve());
-      
+      this.scene.load.on("filecomplete", this.handleFileComplete, this);
+      this.scene.load.on("loaderror", this.handleLoadError, this);
+      this.scene.load.on("complete", () => resolve());
+
       this.scene.load.start();
     });
   }
-  
+
   private handleLoadError(file: Phaser.Loader.File): void {
     console.error(`Failed to load asset: ${file.key}`);
-    
+
     // Use fallback assets
     this.loadFallbackAsset(file.key);
   }
-  
+
   private loadFallbackAsset(key: string): void {
     // Load placeholder or default assets
     switch (key) {
-      case 'player':
-        this.scene.load.image('player', 'assets/defaults/default-player.png');
+      case "player":
+        this.scene.load.image("player", "assets/defaults/default-player.png");
         break;
       default:
         console.warn(`No fallback for asset: ${key}`);
@@ -427,25 +443,26 @@ class AssetManager {
 ### Runtime Error Recovery
 
 **System Error Handling:**
+
 ```typescript
 class GameSystem {
   protected handleError(error: Error, context: string): void {
     console.error(`Error in ${context}:`, error);
-    
+
     // Report to analytics/logging service
     this.reportError(error, context);
-    
+
     // Attempt recovery
     this.attemptRecovery(context);
   }
-  
+
   private attemptRecovery(context: string): void {
     switch (context) {
-      case 'update':
+      case "update":
         // Reset system state
         this.reset();
         break;
-      case 'render':
+      case "render":
         // Disable visual effects
         this.disableEffects();
         break;
@@ -455,64 +472,66 @@ class GameSystem {
     }
   }
 }
-```text
+```
 
 ## Testing Standards
 
 ### Unit Testing
 
 **Game Logic Testing:**
+
 ```typescript
 // Example test for game mechanics
-describe('HealthComponent', () => {
+describe("HealthComponent", () => {
   let healthComponent: HealthComponent;
-  
+
   beforeEach(() => {
     const mockEntity = {} as GameEntity;
     healthComponent = new HealthComponent(mockEntity, 100);
   });
-  
-  test('should initialize with correct health', () => {
+
+  test("should initialize with correct health", () => {
     expect(healthComponent.currentHealth).toBe(100);
     expect(healthComponent.maxHealth).toBe(100);
   });
-  
-  test('should handle damage correctly', () => {
+
+  test("should handle damage correctly", () => {
     healthComponent.takeDamage(25);
     expect(healthComponent.currentHealth).toBe(75);
     expect(healthComponent.isAlive()).toBe(true);
   });
-  
-  test('should handle death correctly', () => {
+
+  test("should handle death correctly", () => {
     healthComponent.takeDamage(150);
     expect(healthComponent.currentHealth).toBe(0);
     expect(healthComponent.isAlive()).toBe(false);
   });
 });
-```text
+```
 
 ### Integration Testing
 
 **Scene Testing:**
+
 ```typescript
-describe('GameScene Integration', () => {
+describe("GameScene Integration", () => {
   let scene: GameScene;
   let mockGame: Phaser.Game;
-  
+
   beforeEach(() => {
     // Mock Phaser game instance
     mockGame = createMockGame();
     scene = new GameScene();
   });
-  
-  test('should initialize all systems', () => {
+
+  test("should initialize all systems", () => {
     scene.create({});
-    
+
     expect(scene.gameManager).toBeDefined();
     expect(scene.inputManager).toBeDefined();
   });
 });
-```text
+```
 
 ## File Organization
 
@@ -566,21 +585,25 @@ src/
 ### Story Implementation Process
 
 1. **Read Story Requirements:**
+
    - Understand acceptance criteria
    - Identify technical requirements
    - Review performance constraints
 
 2. **Plan Implementation:**
+
    - Identify files to create/modify
    - Consider component architecture
    - Plan testing approach
 
 3. **Implement Feature:**
+
    - Follow TypeScript strict mode
    - Use established patterns
    - Maintain 60 FPS performance
 
 4. **Test Implementation:**
+
    - Write unit tests for game logic
    - Test cross-platform functionality
    - Validate performance targets
@@ -593,6 +616,7 @@ src/
 ### Code Review Checklist
 
 **Before Committing:**
+
 - [ ] TypeScript compiles without errors
 - [ ] All tests pass
 - [ ] Performance targets met (60 FPS)
@@ -606,19 +630,22 @@ src/
 ## Performance Targets
 
 ### Frame Rate Requirements
+
 - **Desktop**: Maintain 60 FPS at 1080p
 - **Mobile**: Maintain 60 FPS on mid-range devices, minimum 30 FPS on low-end
 - **Optimization**: Implement dynamic quality scaling when performance drops
 
 ### Memory Management
+
 - **Total Memory**: Under 100MB for full game
 - **Per Scene**: Under 50MB per gameplay scene
 - **Asset Loading**: Progressive loading to stay under limits
 - **Garbage Collection**: Minimize object creation in update loops
 
 ### Loading Performance
+
 - **Initial Load**: Under 5 seconds for game start
 - **Scene Transitions**: Under 2 seconds between scenes
 - **Asset Streaming**: Background loading for upcoming content
 
-These guidelines ensure consistent, high-quality game development that meets performance targets and maintains code quality across all implementation stories.
+These guidelines ensure consistent, high-quality game development that meets performance targets and maintains code quality across all implementation stories.

expansion-packs/bmad-2d-phaser-game-dev/tasks/advanced-elicitation.md

@@ -103,8 +103,9 @@ This elicitation task is specifically designed for game development and should b
 - **Platform Considerations**: When adapting designs for different devices and input methods
 
 The questions and perspectives offered should always consider:
+
 - Player psychology and motivation
 - Technical feasibility with Phaser 3 and TypeScript
 - Performance implications for 60 FPS targets
 - Cross-platform compatibility (desktop and mobile)
-- Game development best practices and common pitfalls
+- Game development best practices and common pitfalls

expansion-packs/bmad-2d-phaser-game-dev/tasks/create-game-story.md

@@ -14,6 +14,7 @@ Create detailed, actionable game development stories that enable AI developers t
 ## Prerequisites
 
 Before creating stories, ensure you have:
+
 - Completed Game Design Document (GDD)
 - Game Architecture Document
 - Epic definition this story belongs to
@@ -24,12 +25,14 @@ Before creating stories, ensure you have:
 ### 1. Story Identification
 
 **Review Epic Context:**
+
 - Understand the epic's overall goal
 - Identify specific features that need implementation
 - Review any existing stories in the epic
 - Ensure no duplicate work
 
 **Feature Analysis:**
+
 - Reference specific GDD sections
 - Understand player experience goals
 - Identify technical complexity
@@ -38,12 +41,14 @@ Before creating stories, ensure you have:
 ### 2. Story Scoping
 
 **Single Responsibility:**
+
 - Focus on one specific game feature
 - Ensure story is completable in 1-3 days
 - Break down complex features into multiple stories
 - Maintain clear boundaries with other stories
 
 **Implementation Clarity:**
+
 - Define exactly what needs to be built
 - Specify all technical requirements
 - Include all necessary integration points
@@ -55,6 +60,7 @@ Before creating stories, ensure you have:
 Use `templates#game-story-tmpl` following all embedded LLM instructions
 
 **Key Focus Areas:**
+
 - Clear, actionable description
 - Specific acceptance criteria
 - Detailed technical specifications
@@ -64,18 +70,21 @@ Use `templates#game-story-tmpl` following all embedded LLM instructions
 ### 4. Story Validation
 
 **Technical Review:**
+
 - Verify all technical specifications are complete
 - Ensure integration points are clearly defined
 - Confirm file paths match architecture
 - Validate TypeScript interfaces and classes
 
 **Game Design Alignment:**
+
 - Confirm story implements GDD requirements
 - Verify player experience goals are met
 - Check balance parameters are included
 - Ensure game mechanics are correctly interpreted
 
 **Implementation Readiness:**
+
 - All dependencies identified
 - Assets requirements specified
 - Testing criteria defined
@@ -87,6 +96,7 @@ Use `templates#game-story-tmpl` following all embedded LLM instructions
 Execute `checklists#game-story-dod-checklist` against completed story
 
 **Story Criteria:**
+
 - Story is immediately actionable
 - No design decisions left to developer
 - Technical requirements are complete
@@ -96,12 +106,14 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ### 6. Story Refinement
 
 **Developer Perspective:**
+
 - Can a developer start implementation immediately?
 - Are all technical questions answered?
 - Is the scope appropriate for the estimated points?
 - Are all dependencies clearly identified?
 
 **Iterative Improvement:**
+
 - Address any gaps or ambiguities
 - Clarify complex technical requirements
 - Ensure story fits within epic scope
@@ -110,6 +122,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Story Elements Checklist
 
 ### Required Sections
+
 - [ ] Clear, specific description
 - [ ] Complete acceptance criteria (functional, technical, game design)
 - [ ] Detailed technical specifications
@@ -123,6 +136,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Definition of Done checklist
 
 ### Game-Specific Requirements
+
 - [ ] GDD section references
 - [ ] Game mechanic implementation details
 - [ ] Player experience goals
@@ -132,6 +146,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Cross-platform considerations
 
 ### Technical Quality
+
 - [ ] TypeScript strict mode compliance
 - [ ] Architecture document alignment
 - [ ] Code organization follows standards
@@ -142,18 +157,21 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Common Pitfalls
 
 **Scope Issues:**
+
 - Story too large (break into multiple stories)
 - Story too vague (add specific requirements)
 - Missing dependencies (identify all prerequisites)
 - Unclear boundaries (define what's in/out of scope)
 
 **Technical Issues:**
+
 - Missing integration details
 - Incomplete technical specifications
 - Undefined interfaces or classes
 - Missing performance requirements
 
 **Game Design Issues:**
+
 - Not referencing GDD properly
 - Missing player experience context
 - Unclear game mechanic implementation
@@ -162,6 +180,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Success Criteria
 
 **Story Readiness:**
+
 - [ ] Developer can start implementation immediately
 - [ ] No additional design decisions required
 - [ ] All technical questions answered
@@ -170,6 +189,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 - [ ] Story fits within epic scope
 
 **Quality Validation:**
+
 - [ ] Game story DOD checklist passes
 - [ ] Architecture alignment confirmed
 - [ ] GDD requirements covered
@@ -179,6 +199,7 @@ Execute `checklists#game-story-dod-checklist` against completed story
 ## Handoff Protocol
 
 **To Game Developer:**
+
 1. Provide story document
 2. Confirm GDD and architecture access
 3. Verify all dependencies are met
@@ -186,9 +207,10 @@ Execute `checklists#game-story-dod-checklist` against completed story
 5. Establish check-in schedule
 
 **Story Status Updates:**
+
 - Draft → Ready for Development
 - In Development → Code Review
 - Code Review → Testing
 - Testing → Done
 
-This task ensures game development stories are immediately actionable and enable efficient AI-driven development of game features.
+This task ensures game development stories are immediately actionable and enable efficient AI-driven development of game features.

expansion-packs/bmad-2d-phaser-game-dev/tasks/game-design-brainstorming.md

@@ -9,6 +9,7 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Begin by understanding the game design context and goals. Ask clarifying questions if needed to determine the best approach for game-specific ideation.]]
 
 1. **Establish Game Context**
+
    - Understand the game genre or opportunity area
    - Identify target audience and platform constraints
    - Determine session goals (concept exploration vs. mechanic refinement)
@@ -164,26 +165,31 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Help user select appropriate techniques based on their specific game design needs.]]
 
 **For Initial Game Concepts:**
+
 - What If Game Scenarios
 - Cross-Genre Fusion
 - Emotion-First Design
 
 **For Stuck/Blocked Creativity:**
+
 - Player Motivation Reversal
 - Constraint-Based Creativity
 - Genre Expectation Subversion
 
 **For Mechanic Development:**
+
 - SCAMPER for Game Mechanics
 - Core Loop Deconstruction
 - Player Agency Spectrum
 
 **For Player Experience:**
+
 - Player Archetype Brainstorming
 - Emotion-First Design
 - Accessibility-First Innovation
 
 **For World Building:**
+
 - Environmental Storytelling
 - Player-Generated Narrative
 - Platform-Specific Design
@@ -193,16 +199,19 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Guide the brainstorming session with appropriate pacing for game design exploration.]]
 
 1. **Inspiration Phase** (10-15 min)
+
    - Reference existing games and mechanics
    - Explore player experiences and emotions
    - Gather visual and thematic inspiration
 
 2. **Divergent Exploration** (25-35 min)
+
    - Generate many game concepts or mechanics
    - Use expansion and fusion techniques
    - Encourage wild and impossible ideas
 
 3. **Player-Centered Filtering** (15-20 min)
+
    - Consider target audience reactions
    - Evaluate emotional impact and engagement
    - Group ideas by player experience goals
@@ -217,6 +226,7 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 [[LLM: Present brainstorming results in a format useful for game development.]]
 
 **Session Summary:**
+
 - Techniques used and focus areas
 - Total concepts/mechanics generated
 - Key themes and patterns identified
@@ -232,21 +242,25 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 **Development Readiness:**
 
 **Prototype-Ready Ideas:**
+
 - Ideas that can be tested immediately
 - Minimum viable implementations
 - Quick validation approaches
 
 **Research-Required Ideas:**
+
 - Concepts needing technical investigation
 - Player testing and market research needs
 - Competitive analysis requirements
 
 **Future Innovation Pipeline:**
+
 - Ideas requiring significant development
 - Technology-dependent concepts
 - Market timing considerations
 
 **Next Steps:**
+
 - Which concepts to prototype first
 - Recommended research areas
 - Suggested playtesting approaches
@@ -255,24 +269,28 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 ## Game Design Specific Considerations
 
 ### Platform and Audience Awareness
+
 - Always consider target platform limitations and advantages
 - Keep target audience preferences and expectations in mind
 - Balance innovation with familiar game design patterns
 - Consider monetization and business model implications
 
 ### Rapid Prototyping Mindset
+
 - Focus on ideas that can be quickly tested
 - Emphasize core mechanics over complex features
 - Design for iteration and player feedback
 - Consider digital and paper prototyping approaches
 
 ### Player Psychology Integration
+
 - Understand motivation and engagement drivers
 - Consider learning curves and skill development
 - Design for different play session lengths
 - Balance challenge and reward appropriately
 
 ### Technical Feasibility
+
 - Keep development resources and timeline in mind
 - Consider art and audio asset requirements
 - Think about performance and optimization needs
@@ -287,4 +305,4 @@ This task provides a comprehensive toolkit of creative brainstorming techniques
 - Think about community and social aspects of gameplay
 - Consider accessibility and inclusivity from the start
 - Balance innovation with market viability
-- Plan for iteration based on player feedback
+- Plan for iteration based on player feedback

expansion-packs/bmad-2d-phaser-game-dev/templates/game-architecture-tmpl.md

@@ -80,7 +80,7 @@ This architecture is designed to support the gameplay mechanics defined in the G
 │   ├── stories/         # Development stories
 │   └── architecture/    # Technical docs
 └── dist/                # Built game files
-```text
+```
 
 ### Module Organization
 
@@ -365,7 +365,7 @@ const gameConfig: Phaser.Types.Core.GameConfig = {
     },
     // Additional configuration...
 };
-```text
+```
 
 ### Game Balance Configuration
 

expansion-packs/bmad-2d-phaser-game-dev/templates/game-brief-tmpl.md

@@ -60,11 +60,13 @@ This brief is typically created early in the ideation process, often after brain
 [[LLM: List the 3-5 most important gameplay mechanics that define the player experience]]
 
 **Core Mechanic 1: {{mechanic_name}}**
+
 - **Description:** {{how_it_works}}
 - **Player Value:** {{why_its_fun}}
 - **Implementation Scope:** {{complexity_estimate}}
 
 **Core Mechanic 2: {{mechanic_name}}**
+
 - **Description:** {{how_it_works}}
 - **Player Value:** {{why_its_fun}}
 - **Implementation Scope:** {{complexity_estimate}}
@@ -91,10 +93,12 @@ This brief is typically created early in the ideation process, often after brain
 ### Technical Constraints
 
 **Platform Requirements:**
+
 - Primary: {{platform_1}} - {{requirements}}
 - Secondary: {{platform_2}} - {{requirements}}
 
 **Technical Specifications:**
+
 - Engine: Phaser 3 + TypeScript
 - Performance Target: {{fps_target}} FPS on {{target_device}}
 - Memory Budget: <{{memory_limit}}MB
@@ -125,6 +129,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Inspiration Games
 
 **Primary References:**
+
 1. **{{reference_game_1}}** - {{what_we_learn_from_it}}
 2. **{{reference_game_2}}** - {{what_we_learn_from_it}}
 3. **{{reference_game_3}}** - {{what_we_learn_from_it}}
@@ -132,6 +137,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Competitive Analysis
 
 **Direct Competitors:**
+
 - {{competitor_1}}: {{strengths_and_weaknesses}}
 - {{competitor_2}}: {{strengths_and_weaknesses}}
 
@@ -157,13 +163,16 @@ This brief is typically created early in the ideation process, often after brain
 ### Content Categories
 
 **Core Content:**
+
 - {{content_type_1}}: {{quantity_and_description}}
 - {{content_type_2}}: {{quantity_and_description}}
 
 **Optional Content:**
+
 - {{optional_content_type}}: {{quantity_and_description}}
 
 **Replay Elements:**
+
 - {{replayability_features}}
 
 ### Difficulty and Accessibility
@@ -201,23 +210,23 @@ This brief is typically created early in the ideation process, often after brain
 
 ### Technical Risks
 
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|-------------|--------|-------------------|
-| {{technical_risk_1}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
-| {{technical_risk_2}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
+| Risk                 | Probability | Impact | Mitigation Strategy |
+| -------------------- | ----------- | ------ | ------------------- | ------ | --- | ----- | ----------------------- |
+| {{technical_risk_1}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
+| {{technical_risk_2}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
 
 ### Design Risks
 
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|-------------|--------|-------------------|
-| {{design_risk_1}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
-| {{design_risk_2}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
+| Risk              | Probability | Impact | Mitigation Strategy |
+| ----------------- | ----------- | ------ | ------------------- | ------ | --- | ----- | ----------------------- |
+| {{design_risk_1}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
+| {{design_risk_2}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
 
 ### Market Risks
 
-| Risk | Probability | Impact | Mitigation Strategy |
-|------|-------------|--------|-------------------|
-| {{market_risk_1}} | {{high|med|low}} | {{high|med|low}} | {{mitigation_approach}} |
+| Risk              | Probability | Impact | Mitigation Strategy |
+| ----------------- | ----------- | ------ | ------------------- | ------ | --- | ----- | ----------------------- |
+| {{market_risk_1}} | {{high      | med    | low}}               | {{high | med | low}} | {{mitigation_approach}} |
 
 ## Success Criteria
 
@@ -226,11 +235,13 @@ This brief is typically created early in the ideation process, often after brain
 ### Player Experience Metrics
 
 **Engagement Goals:**
+
 - Tutorial completion rate: >{{percentage}}%
 - Average session length: {{duration}} minutes
 - Player retention: D1 {{d1}}%, D7 {{d7}}%, D30 {{d30}}%
 
 **Quality Benchmarks:**
+
 - Player satisfaction: >{{rating}}/10
 - Completion rate: >{{percentage}}%
 - Technical performance: {{fps_target}} FPS consistent
@@ -238,11 +249,13 @@ This brief is typically created early in the ideation process, often after brain
 ### Development Metrics
 
 **Technical Targets:**
+
 - Zero critical bugs at launch
 - Performance targets met on all platforms
 - Load times under {{seconds}}s
 
 **Process Goals:**
+
 - Development timeline adherence
 - Feature scope completion
 - Quality assurance standards
@@ -252,6 +265,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Business Metrics
 
 **Commercial Goals:**
+
 - {{revenue_target}} in first {{time_period}}
 - {{user_acquisition_target}} players in first {{time_period}}
 - {{retention_target}} monthly active users
@@ -271,16 +285,19 @@ This brief is typically created early in the ideation process, often after brain
 ### Development Roadmap
 
 **Phase 1: Pre-Production** ({{duration}})
+
 - Detailed Game Design Document creation
 - Technical architecture planning
 - Art style exploration and pipeline setup
 
 **Phase 2: Prototype** ({{duration}})
+
 - Core mechanic implementation
 - Technical proof of concept
 - Initial playtesting and iteration
 
 **Phase 3: Production** ({{duration}})
+
 - Full feature development
 - Content creation and integration
 - Comprehensive testing and optimization
@@ -288,6 +305,7 @@ This brief is typically created early in the ideation process, often after brain
 ### Documentation Pipeline
 
 **Required Documents:**
+
 1. Game Design Document (GDD) - {{target_completion}}
 2. Technical Architecture Document - {{target_completion}}
 3. Art Style Guide - {{target_completion}}
@@ -296,10 +314,12 @@ This brief is typically created early in the ideation process, often after brain
 ### Validation Plan
 
 **Concept Testing:**
+
 - {{validation_method_1}} - {{timeline}}
 - {{validation_method_2}} - {{timeline}}
 
 **Prototype Testing:**
+
 - {{testing_approach}} - {{timeline}}
 - {{feedback_collection_method}} - {{timeline}}
 
@@ -322,4 +342,4 @@ This brief is typically created early in the ideation process, often after brain
 [[LLM: Track document versions and changes]]
 
 | Date | Version | Description | Author |
-| :--- | :------ | :---------- | :----- |
+| :--- | :------ | :---------- | :----- |

expansion-packs/bmad-2d-phaser-game-dev/templates/game-design-doc-tmpl.md

@@ -53,6 +53,7 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Define the 30-60 second loop that players will repeat. Be specific about timing and player actions.]]
 
 **Primary Loop ({{duration}} seconds):**
+
 1. {{action_1}} ({{time_1}}s)
 2. {{action_2}} ({{time_2}}s)
 3. {{action_3}} ({{time_3}}s)
@@ -63,10 +64,12 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Clearly define success and failure states]]
 
 **Victory Conditions:**
+
 - {{win_condition_1}}
 - {{win_condition_2}}
 
 **Failure States:**
+
 - {{loss_condition_1}}
 - {{loss_condition_2}}
 
@@ -87,6 +90,7 @@ If available, review any provided documents or ask if any are optionally availab
 **System Response:** {{game_response}}
 
 **Implementation Notes:**
+
 - {{tech_requirement_1}}
 - {{tech_requirement_2}}
 - {{performance_consideration}}
@@ -99,8 +103,8 @@ If available, review any provided documents or ask if any are optionally availab
 
 [[LLM: Define all input methods for different platforms]]
 
-| Action | Desktop | Mobile | Gamepad |
-|--------|---------|--------|---------|
+| Action       | Desktop | Mobile      | Gamepad    |
+| ------------ | ------- | ----------- | ---------- |
 | {{action_1}} | {{key}} | {{gesture}} | {{button}} |
 | {{action_2}} | {{key}} | {{gesture}} | {{button}} |
 
@@ -113,6 +117,7 @@ If available, review any provided documents or ask if any are optionally availab
 **Progression Type:** {{linear|branching|metroidvania}}
 
 **Key Milestones:**
+
 1. **{{milestone_1}}** - {{unlock_description}}
 2. **{{milestone_2}}** - {{unlock_description}}
 3. **{{milestone_3}}** - {{unlock_description}}
@@ -132,9 +137,9 @@ If available, review any provided documents or ask if any are optionally availab
 
 [[LLM: Define any in-game currencies, resources, or collectibles]]
 
-| Resource | Earn Rate | Spend Rate | Purpose | Cap |
-|----------|-----------|------------|---------|-----|
-| {{resource_1}} | {{rate}} | {{rate}} | {{use}} | {{max}} |
+| Resource       | Earn Rate | Spend Rate | Purpose | Cap     |
+| -------------- | --------- | ---------- | ------- | ------- |
+| {{resource_1}} | {{rate}}  | {{rate}}   | {{use}} | {{max}} |
 
 ^^/CONDITION: has_economy^^
 
@@ -154,6 +159,7 @@ If available, review any provided documents or ask if any are optionally availab
 **Difficulty:** {{relative_difficulty}}
 
 **Structure Template:**
+
 - Introduction: {{intro_description}}
 - Challenge: {{main_challenge}}
 - Resolution: {{completion_requirement}}
@@ -180,11 +186,13 @@ If available, review any provided documents or ask if any are optionally availab
 ### Platform Specific
 
 **Desktop:**
+
 - Resolution: {{min_resolution}} - {{max_resolution}}
 - Input: Keyboard, Mouse, Gamepad
 - Browser: Chrome 80+, Firefox 75+, Safari 13+
 
 **Mobile:**
+
 - Resolution: {{mobile_min}} - {{mobile_max}}
 - Input: Touch, Tilt (optional)
 - OS: iOS 13+, Android 8+
@@ -194,12 +202,14 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Define asset specifications for the art and audio teams]]
 
 **Visual Assets:**
+
 - Art Style: {{style_description}}
 - Color Palette: {{color_specification}}
 - Animation: {{animation_requirements}}
 - UI Resolution: {{ui_specs}}
 
 **Audio Assets:**
+
 - Music Style: {{music_genre}}
 - Sound Effects: {{sfx_requirements}}
 - Voice Acting: {{voice_needs}}
@@ -211,6 +221,7 @@ If available, review any provided documents or ask if any are optionally availab
 ### Engine Configuration
 
 **Phaser 3 Setup:**
+
 - TypeScript: Strict mode enabled
 - Physics: {{physics_system}} (Arcade/Matter)
 - Renderer: WebGL with Canvas fallback
@@ -219,6 +230,7 @@ If available, review any provided documents or ask if any are optionally availab
 ### Code Architecture
 
 **Required Systems:**
+
 - Scene Management
 - State Management
 - Asset Loading
@@ -230,6 +242,7 @@ If available, review any provided documents or ask if any are optionally availab
 ### Data Management
 
 **Save Data:**
+
 - Progress tracking
 - Settings persistence
 - Statistics collection
@@ -242,12 +255,14 @@ If available, review any provided documents or ask if any are optionally availab
 ### Phase 1: Core Systems ({{duration}})
 
 **Epic: Foundation**
+
 - Engine setup and configuration
 - Basic scene management
 - Core input handling
 - Asset loading pipeline
 
 **Epic: Core Mechanics**
+
 - {{primary_mechanic}} implementation
 - Basic physics and collision
 - Player controller
@@ -255,11 +270,13 @@ If available, review any provided documents or ask if any are optionally availab
 ### Phase 2: Gameplay Features ({{duration}})
 
 **Epic: Game Systems**
+
 - {{mechanic_2}} implementation
 - {{mechanic_3}} implementation
 - Game state management
 
 **Epic: Content Creation**
+
 - Level loading system
 - First playable levels
 - Basic UI implementation
@@ -267,11 +284,13 @@ If available, review any provided documents or ask if any are optionally availab
 ### Phase 3: Polish & Optimization ({{duration}})
 
 **Epic: Performance**
+
 - Optimization and profiling
 - Mobile platform testing
 - Memory management
 
 **Epic: User Experience**
+
 - Audio implementation
 - Visual effects and polish
 - Final UI/UX refinement
@@ -281,12 +300,14 @@ If available, review any provided documents or ask if any are optionally availab
 [[LLM: Define measurable goals for the game]]
 
 **Technical Metrics:**
+
 - Frame rate: {{fps_target}}
 - Load time: {{load_target}}
 - Crash rate: <{{crash_threshold}}%
 - Memory usage: <{{memory_target}}MB
 
 **Gameplay Metrics:**
+
 - Tutorial completion: {{completion_rate}}%
 - Average session: {{session_length}} minutes
 - Level completion: {{level_completion}}%
@@ -307,4 +328,4 @@ If available, review any provided documents or ask if any are optionally availab
 
 - {{reference_1}}
 - {{reference_2}}
-- {{reference_3}}
+- {{reference_3}}

expansion-packs/bmad-2d-phaser-game-dev/templates/level-design-doc-tmpl.md

@@ -64,19 +64,23 @@ This framework ensures consistency across all levels while providing flexibility
 **Difficulty Range:** {{difficulty_scale}}
 
 **Key Mechanics Featured:**
+
 - {{mechanic_1}} - {{usage_description}}
 - {{mechanic_2}} - {{usage_description}}
 
 **Player Objectives:**
+
 - Primary: {{primary_objective}}
 - Secondary: {{secondary_objective}}
 - Hidden: {{secret_objective}}
 
 **Success Criteria:**
+
 - {{completion_requirement_1}}
 - {{completion_requirement_2}}
 
 **Technical Requirements:**
+
 - Maximum entities: {{entity_limit}}
 - Performance target: {{fps_target}} FPS
 - Memory budget: {{memory_limit}}MB
@@ -97,6 +101,7 @@ This framework ensures consistency across all levels while providing flexibility
 **Total Level Count:** {{number}}
 
 **World Breakdown:**
+
 - World 1: {{level_count}} levels - {{theme}} - {{difficulty_range}}
 - World 2: {{level_count}} levels - {{theme}} - {{difficulty_range}}
 - World 3: {{level_count}} levels - {{theme}} - {{difficulty_range}}
@@ -106,7 +111,8 @@ This framework ensures consistency across all levels while providing flexibility
 [[LLM: Define how challenge increases across the game]]
 
 **Progression Curve:**
-```text
+
+````text
 Difficulty
     ^     ___/```
     |    /
@@ -116,9 +122,10 @@ Difficulty
     |/     /
     +-----------> Level Number
    Tutorial  Early  Mid  Late
-```text
+````
 
 **Scaling Parameters:**
+
 - Enemy count: {{start_count}} → {{end_count}}
 - Enemy difficulty: {{start_diff}} → {{end_diff}}
 - Level complexity: {{start_complex}} → {{end_complex}}
@@ -129,6 +136,7 @@ Difficulty
 [[LLM: Define how players access new levels]]
 
 **Progression Gates:**
+
 - Linear progression: Complete previous level
 - Star requirements: {{star_count}} stars to unlock
 - Skill gates: Demonstrate {{skill_requirement}}
@@ -143,14 +151,17 @@ Difficulty
 [[LLM: Define all environmental components that can be used in levels]]
 
 **Terrain Types:**
+
 - {{terrain_1}}: {{properties_and_usage}}
 - {{terrain_2}}: {{properties_and_usage}}
 
 **Interactive Objects:**
+
 - {{object_1}}: {{behavior_and_purpose}}
 - {{object_2}}: {{behavior_and_purpose}}
 
 **Hazards and Obstacles:**
+
 - {{hazard_1}}: {{damage_and_behavior}}
 - {{hazard_2}}: {{damage_and_behavior}}
 
@@ -159,15 +170,18 @@ Difficulty
 [[LLM: Define all collectible items and their placement rules]]
 
 **Collectible Types:**
+
 - {{collectible_1}}: {{value_and_purpose}}
 - {{collectible_2}}: {{value_and_purpose}}
 
 **Placement Guidelines:**
+
 - Mandatory collectibles: {{placement_rules}}
 - Optional collectibles: {{placement_rules}}
 - Secret collectibles: {{placement_rules}}
 
 **Reward Distribution:**
+
 - Easy to find: {{percentage}}%
 - Moderate challenge: {{percentage}}%
 - High skill required: {{percentage}}%
@@ -177,15 +191,18 @@ Difficulty
 [[LLM: Define how enemies should be placed and balanced in levels]]
 
 **Enemy Categories:**
+
 - {{enemy_type_1}}: {{behavior_and_usage}}
 - {{enemy_type_2}}: {{behavior_and_usage}}
 
 **Placement Principles:**
+
 - Introduction encounters: {{guideline}}
 - Standard encounters: {{guideline}}
 - Challenge encounters: {{guideline}}
 
 **Difficulty Scaling:**
+
 - Enemy count progression: {{scaling_rule}}
 - Enemy type introduction: {{pacing_rule}}
 - Encounter complexity: {{complexity_rule}}
@@ -197,12 +214,14 @@ Difficulty
 ### Level Layout Principles
 
 **Spatial Design:**
+
 - Grid size: {{grid_dimensions}}
 - Minimum path width: {{width_units}}
 - Maximum vertical distance: {{height_units}}
 - Safe zones placement: {{safety_guidelines}}
 
 **Navigation Design:**
+
 - Clear path indication: {{visual_cues}}
 - Landmark placement: {{landmark_rules}}
 - Dead end avoidance: {{dead_end_policy}}
@@ -213,11 +232,13 @@ Difficulty
 [[LLM: Define how to control the rhythm and pace of gameplay within levels]]
 
 **Action Sequences:**
+
 - High intensity duration: {{max_duration}}
 - Rest period requirement: {{min_rest_time}}
 - Intensity variation: {{pacing_pattern}}
 
 **Learning Sequences:**
+
 - New mechanic introduction: {{teaching_method}}
 - Practice opportunity: {{practice_duration}}
 - Skill application: {{application_context}}
@@ -227,12 +248,14 @@ Difficulty
 [[LLM: Define how to create appropriate challenges for each level type]]
 
 **Challenge Types:**
+
 - Execution challenges: {{skill_requirements}}
 - Puzzle challenges: {{complexity_guidelines}}
 - Time challenges: {{time_pressure_rules}}
 - Resource challenges: {{resource_management}}
 
 **Difficulty Calibration:**
+
 - Skill check frequency: {{frequency_guidelines}}
 - Failure recovery: {{retry_mechanics}}
 - Hint system integration: {{help_system}}
@@ -246,11 +269,13 @@ Difficulty
 [[LLM: Define how level data should be structured for implementation]]
 
 **Level File Format:**
+
 - Data format: {{json|yaml|custom}}
 - File naming: `level_{{world}}_{{number}}.{{extension}}`
 - Data organization: {{structure_description}}
 
 **Required Data Fields:**
+
 ```json
 {
   "levelId": "{{unique_identifier}}",
@@ -282,12 +307,14 @@ Difficulty
 [[LLM: Define how level assets are organized and loaded]]
 
 **Tilemap Requirements:**
+
 - Tile size: {{tile_dimensions}}px
 - Tileset organization: {{tileset_structure}}
 - Layer organization: {{layer_system}}
 - Collision data: {{collision_format}}
 
 **Audio Integration:**
+
 - Background music: {{music_requirements}}
 - Ambient sounds: {{ambient_system}}
 - Dynamic audio: {{dynamic_audio_rules}}
@@ -297,16 +324,19 @@ Difficulty
 [[LLM: Define performance requirements for level systems]]
 
 **Entity Limits:**
+
 - Maximum active entities: {{entity_limit}}
 - Maximum particles: {{particle_limit}}
 - Maximum audio sources: {{audio_limit}}
 
 **Memory Management:**
+
 - Texture memory budget: {{texture_memory}}MB
 - Audio memory budget: {{audio_memory}}MB
 - Level loading time: <{{load_time}}s
 
 **Culling and LOD:**
+
 - Off-screen culling: {{culling_distance}}
 - Level-of-detail rules: {{lod_system}}
 - Asset streaming: {{streaming_requirements}}
@@ -318,11 +348,13 @@ Difficulty
 ### Automated Testing
 
 **Performance Testing:**
+
 - Frame rate validation: Maintain {{fps_target}} FPS
 - Memory usage monitoring: Stay under {{memory_limit}}MB
 - Loading time verification: Complete in <{{load_time}}s
 
 **Gameplay Testing:**
+
 - Completion path validation: All objectives achievable
 - Collectible accessibility: All items reachable
 - Softlock prevention: No unwinnable states
@@ -330,6 +362,7 @@ Difficulty
 ### Manual Testing Protocol
 
 **Playtesting Checklist:**
+
 - [ ] Level completes within target time range
 - [ ] All mechanics function correctly
 - [ ] Difficulty feels appropriate for level category
@@ -337,6 +370,7 @@ Difficulty
 - [ ] No exploits or sequence breaks (unless intended)
 
 **Player Experience Testing:**
+
 - [ ] Tutorial levels teach effectively
 - [ ] Challenge feels fair and rewarding
 - [ ] Flow and pacing maintain engagement
@@ -345,12 +379,14 @@ Difficulty
 ### Balance Validation
 
 **Metrics Collection:**
+
 - Completion rate: Target {{completion_percentage}}%
 - Average completion time: {{target_time}} ± {{variance}}
 - Death count per level: <{{max_deaths}}
 - Collectible discovery rate: {{discovery_percentage}}%
 
 **Iteration Guidelines:**
+
 - Adjustment criteria: {{criteria_for_changes}}
 - Testing sample size: {{minimum_testers}}
 - Validation period: {{testing_duration}}
@@ -362,12 +398,14 @@ Difficulty
 ### Design Phase
 
 **Concept Development:**
+
 1. Define level purpose and goals
 2. Create rough layout sketch
 3. Identify key mechanics and challenges
 4. Estimate difficulty and duration
 
 **Documentation Requirements:**
+
 - Level design brief
 - Layout diagrams
 - Mechanic integration notes
@@ -376,6 +414,7 @@ Difficulty
 ### Implementation Phase
 
 **Technical Implementation:**
+
 1. Create level data file
 2. Build tilemap and layout
 3. Place entities and objects
@@ -383,6 +422,7 @@ Difficulty
 5. Integrate audio and visual effects
 
 **Quality Assurance:**
+
 1. Automated testing execution
 2. Internal playtesting
 3. Performance validation
@@ -391,12 +431,14 @@ Difficulty
 ### Integration Phase
 
 **Game Integration:**
+
 1. Level progression integration
 2. Save system compatibility
 3. Analytics integration
 4. Achievement system integration
 
 **Final Validation:**
+
 1. Full game context testing
 2. Performance regression testing
 3. Platform compatibility verification
@@ -407,19 +449,22 @@ Difficulty
 [[LLM: Define how to measure level design success]]
 
 **Player Engagement:**
+
 - Level completion rate: {{target_rate}}%
 - Replay rate: {{replay_target}}%
 - Time spent per level: {{engagement_time}}
 - Player satisfaction scores: {{satisfaction_target}}/10
 
 **Technical Performance:**
+
 - Frame rate consistency: {{fps_consistency}}%
 - Loading time compliance: {{load_compliance}}%
 - Memory usage efficiency: {{memory_efficiency}}%
 - Crash rate: <{{crash_threshold}}%
 
 **Design Quality:**
+
 - Difficulty curve adherence: {{curve_accuracy}}
 - Mechanic integration effectiveness: {{integration_score}}
 - Player guidance clarity: {{guidance_score}}
-- Content accessibility: {{accessibility_rate}}%
+- Content accessibility: {{accessibility_rate}}%

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

@@ -66,13 +66,13 @@ To install this expansion pack, run:
 
 ```bash
 npm run install:expansion infrastructure
-```text
+```
 
 Or manually:
 
 ```bash
 node tools/install-expansion-pack.js infrastructure
-```text
+```
 
 This will:
 
@@ -92,7 +92,7 @@ After the main architecture is complete:
 
 # Or directly with DevOps agent
 npm run agent devops
-```text
+```
 
 ### 2. Platform Implementation
 

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

@@ -31,8 +31,8 @@ persona:
     - Collaborative Operations - Work closely with development teams fostering shared responsibility for system reliability
 startup:
   - Announce: Hey! I'm Alex, your DevOps Infrastructure Specialist. I love when things run secure, stable, reliable and performant. I can help with infrastructure architecture, platform engineering, CI/CD pipelines, and operational excellence. What infrastructure challenge can I help you with today?
-  - 'List available tasks: review-infrastructure, validate-infrastructure, create infrastructure documentation'
-  - 'List available templates: infrastructure-architecture, infrastructure-platform-from-arch'
+  - "List available tasks: review-infrastructure, validate-infrastructure, create infrastructure documentation"
+  - "List available templates: infrastructure-architecture, infrastructure-platform-from-arch"
   - Execute selected task or stay in persona to help guided by Core DevOps Principles
 commands:
   - '*help" - Show: numbered list of the following commands to allow selection'

expansion-packs/expansion-creator/README.md

@@ -5,4 +5,4 @@ Tools for creating and extending BMAD framework components.
 ## Tasks
 
 - **create-agent**: Create new AI agent definitions
-- **generate-expansion-pack**: Generate new expansion pack templates
+- **generate-expansion-pack**: Generate new expansion pack templates

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

@@ -50,4 +50,4 @@ dependencies:
   templates:
     - agent-tmpl
     - expansion-pack-plan-tmpl
-```
+```

expansion-packs/expansion-creator/tasks/create-agent.md

@@ -63,7 +63,7 @@ Created during agent setup:
 - Templates:
   - [ ] template-name-1.md
   - [ ] template-name-2.md
-```text
+```
 
 ### 4. Create Agent File
 
@@ -121,7 +121,7 @@ Present to the user:
    1. Review and customize the created tasks/templates
    2. Run npm run build:agents
    3. Test the agent thoroughly
-```text
+```
 
 ## Template Reference
 
@@ -150,7 +150,7 @@ persona:
     - Data integrity and accuracy above all
     - Clear communication of complex findings
     - Actionable insights over raw numbers
-```text
+```
 
 ## Creating Missing Dependencies
 
@@ -183,12 +183,12 @@ When a required task or template doesn't exist:
 ```yaml
 dependencies:
   tasks:
-    - 'create-doc # Required if agent creates any documents'
-    - 'analyze-requirements # Custom task for this agent'
-    - 'generate-report # Another custom task'
+    - create-doc
+    - analyze-requirements
+    - generate-report
   templates:
-    - 'requirements-doc # Template for requirements documents'
-    - 'analysis-report # Template for analysis reports'
+    - requirements-doc
+    - analysis-report
 ```
 
 ## Notes

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

@@ -673,7 +673,7 @@ Before declaring complete:
 
 **README Structure with Character Introduction:**
 
-````markdown
+```markdown
 # {Pack Name} Expansion Pack
 
 ## Meet Your {Domain} Team
@@ -698,9 +698,7 @@ _{Professional background and expertise}_
 
 2. **Launch Orchestrator**:
 
-   ```bash
    npm run agent {pack-name}-orchestrator
-   ```
 
 3. **Follow Numbered Options**: {Character Name} will present numbered choices for each decision
 
@@ -730,7 +728,7 @@ _{Professional background and expertise}_
 ### Knowledge Base
 
 [Embedded domain expertise]
-````
+```
 
 #### 6.3 Advanced Data File Documentation with Validation
 

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

@@ -83,7 +83,7 @@ workflows:
   - {{workflow-name}}  # {{workflow-description}}
   <</REPEAT>>
   ^^/CONDITION: domain-workflows^^
-```text
+```
 
 @{example-1: Standard fullstack team}
 
@@ -127,7 +127,7 @@ workflows:
   - healthcare-patient-portal
   - healthcare-compliance-audit
   - clinical-trial-management
-```text
+```
 
 @{example-3: Minimal IDE team}
 

expansion-packs/expansion-creator/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
+```yml
 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
@@ -70,7 +70,7 @@ dependencies:
     - [TEMPLATE_1]  # Template with LLM instructions for guided creation
     - [TEMPLATE_2]  # Another template for different document type
     [[LLM: Example: blueprint-tmpl, contract-tmpl, report-tmpl
-    Each template should include [[LLM: guidance]] and other conventions from `template-formmat.md` sections for user interaction]]
+    Each template should include [[LLM: guidance]] and other conventions from `template-format.md` sections for user interaction]]
 
   checklists:
     - [CHECKLIST_1]  # Quality validation for template outputs
@@ -86,7 +86,7 @@ dependencies:
     - template-format  # Required if using templates
     - [UTIL_1]        # Other utilities as needed
     [[LLM: Include workflow-management if agent participates in workflows]]
-```text
+```
 
 @{example: Construction Contractor Agent}
 
@@ -125,19 +125,19 @@ commands:
   - '*exit" - Say goodbye as Marcus and exit'
 dependencies:
   tasks:
-    - 'create-doc          # For document creation'
-    - 'validate-plans      # Custom validation task'
-    - 'safety-assessment   # Custom safety review task'
+    - create-doc
+    - validate-plans
+    - safety-assessment
   templates:
-    - 'blueprint-tmpl      # Architectural blueprint template'
-    - 'estimate-tmpl       # Cost estimation template'
-    - 'schedule-tmpl       # Project timeline template'
+    - blueprint-tmpl
+    - estimate-tmpl
+    - schedule-tmpl
   checklists:
-    - 'blueprint-checklist # Validates blueprint completeness'
-    - 'safety-checklist    # Safety compliance validation'
+    - blueprint-checklist
+    - safety-checklist
   data:
-    - 'building-codes.md   # Local building code reference'
-    - 'materials-guide.md  # Construction materials specs'
+    - building-codes.md
+    - materials-guide.md
   utils:
-    - 'template-format     # For template processing'
-````
+    - template-format
+```

expansion-packs/expansion-creator/utils/workflow-management.md

@@ -47,7 +47,7 @@ Available workflows for [Team Name]:
 [... etc. ...]
 
 Use /workflow-start {number or id} to begin a workflow.
-```text
+```
 
 ### /workflow-start {workflow-id}
 
@@ -73,7 +73,7 @@ In Progress:
     - Create PRD (John) - awaiting input
 
 Next: Technical Architecture
-```text
+```
 
 ### /workflow-resume
 
@@ -89,7 +89,7 @@ BMad: I see you've completed Discovery and part of Product Planning.
       - UX Strategy with Sally (ux-expert)
 
       Would you like me to load Sally to continue?
-```text
+```
 
 ### /workflow-next
 
@@ -135,7 +135,7 @@ workflow_state:
       status: in-progress
       created_by: pm
       started: 2024-01-15T11:00:00.000Z
-```text
+```
 
 ### 4. Workflow Interruption Handling
 
@@ -159,7 +159,7 @@ BMad: I see you have a PRD and architecture document. Based on these artifacts,
       - Load Sarah (Product Owner) to validate all artifacts
 
       Would you like to continue with this workflow?
-```text
+```
 
 ## Workflow Context Passing
 
@@ -185,7 +185,7 @@ Sally: I see we're in the Product Planning stage of the greenfield-fullstack wor
 
        Let's create the UX strategy and UI specifications. First, let me review
        the PRD to understand the features we're designing for...
-```text
+```
 
 ## Multi-Path Workflows
 

package-lock.json

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

package.json

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

tools/installer/README.md

@@ -33,7 +33,7 @@ installer/
 
 ## Usage
 
-````bash
+```bash
 # Interactive installation
 npx bmad-method install
 
@@ -42,7 +42,7 @@ npx bmad-method install --profile=minimal
 
 # Update existing installation
 npx bmad-method update
-```text
+```
 
 ## Development
 
@@ -55,4 +55,4 @@ npm test
 
 # Lint code
 npm run lint
-````
+```

tools/installer/lib/installer.js

@@ -350,7 +350,12 @@ class Installer {
     // Install web bundles if requested
     if (config.includeWebBundles && config.webBundlesDirectory) {
       spinner.text = "Installing web bundles...";
-      await this.installWebBundles(config.webBundlesDirectory, config, spinner);
+      // Resolve web bundles directory using the same logic as the main installation directory
+      const originalCwd = process.env.INIT_CWD || process.env.PWD || process.cwd();
+      let resolvedWebBundlesDir = path.isAbsolute(config.webBundlesDirectory) 
+        ? config.webBundlesDirectory 
+        : path.resolve(originalCwd, config.webBundlesDirectory);
+      await this.installWebBundles(resolvedWebBundlesDir, config, spinner);
     }
 
     // Set up IDE integration if requested
@@ -608,7 +613,12 @@ class Installer {
     
     if (config.includeWebBundles && config.webBundlesDirectory) {
       const bundleInfo = this.getWebBundleInfo(config);
-      console.log(chalk.green(`✓ Web bundles (${bundleInfo}) installed to: ${config.webBundlesDirectory}`));
+      // Resolve the web bundles directory for display
+      const originalCwd = process.env.INIT_CWD || process.env.PWD || process.cwd();
+      const resolvedWebBundlesDir = path.isAbsolute(config.webBundlesDirectory) 
+        ? config.webBundlesDirectory 
+        : path.resolve(originalCwd, config.webBundlesDirectory);
+      console.log(chalk.green(`✓ Web bundles (${bundleInfo}) installed to: ${resolvedWebBundlesDir}`));
     }
     
     if (ides.length > 0) {

tools/installer/package.json

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