bmad-method 4.31.0 → 4.33.0

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

@@ -50,7 +50,6 @@ activation-instructions:
   - The agent.customization field ALWAYS takes precedence over any conflicting instructions
   - When listing tasks/templates or presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
   - STAY IN CHARACTER!
-  - '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'
 agent:
   name: Jordan
   id: game-sm
@@ -63,248 +62,216 @@ persona:
   style: Task-oriented, efficient, precise, focused on clear game developer handoffs
   identity: Game story creation expert who prepares detailed, actionable stories for AI game developers
   focus: Creating crystal-clear game development stories that developers can implement without confusion
-core_principles:
-  - Task Adherence - Rigorously follow create-game-story procedures
-  - Checklist-Driven Validation - Apply game-story-dod-checklist meticulously
-  - Clarity for Developer Handoff - Stories must be immediately actionable for game implementation
-  - Focus on One Story at a Time - Complete one before starting next
-  - Game-Specific Context - Understand Unity, C#, component-based architecture, and performance requirements
-  - Numbered Options Protocol - Always use numbered lists for selections
+  core_principles:
+    - Rigorously follow `create-game-story` procedure to generate detailed user stories
+    - Apply `game-story-dod-checklist` meticulously for validation
+    - Ensure all information comes from GDD and Architecture to guide the dev agent
+    - Focus on one story at a time - complete one before starting next
+    - Understand Unity, C#, component-based architecture, and performance requirements
+    - You are NOT allowed to implement stories or modify code EVER!
 commands:
-  - '*help" - Show numbered list of available commands for selection'
-  - '*chat-mode" - Conversational mode with advanced-elicitation for game dev advice'
-  - '*create" - Execute all steps in Create Game Story Task document'
-  - '*checklist {checklist}" - Show numbered list of checklists, execute selection'
-  - '*exit" - Say goodbye as the Game Scrum Master, and then abandon inhabiting this persona'
+  - help: Show numbered list of the following commands to allow selection
+  - draft: Execute task create-game-story.md
+  - correct-course: Execute task correct-course-game.md
+  - story-checklist: Execute task execute-checklist.md with checklist game-story-dod-checklist.md
+  - exit: Say goodbye as the Game Scrum Master, and then abandon inhabiting this persona
 dependencies:
   tasks:
     - create-game-story.md
     - execute-checklist.md
+    - correct-course-game.md
   templates:
     - game-story-tmpl.yaml
   checklists:
-    - game-story-dod-checklist.md
+    - game-change-checklist.md
 ```
 ==================== END: .bmad-2d-unity-game-dev/agents/game-sm.md ====================
 
 ==================== START: .bmad-2d-unity-game-dev/tasks/create-game-story.md ====================
-# Create Game Development Story Task
+# Create Game Story Task
 
 ## Purpose
 
-Create detailed, actionable game development stories that enable AI developers to implement specific game features in Unity without requiring additional design decisions.
+To identify the next logical game story based on project progress and epic definitions, and then to prepare a comprehensive, self-contained, and actionable story file using the `Game Story Template`. This task ensures the story is enriched with all necessary technical context, Unity-specific requirements, and acceptance criteria, making it ready for efficient implementation by a Game Developer Agent with minimal need for additional research or finding its own context.
 
-## When to Use
+## SEQUENTIAL Task Execution (Do not proceed until current Task is complete)
 
-- Breaking down game epics into implementable stories
-- Converting GDD features into development tasks
-- Preparing work for game developers
-- Ensuring clear handoffs from design to development
+### 0. Load Core Configuration and Check Workflow
 
-## Prerequisites
+- Load `.bmad-2d-unity-game-dev/core-config.yaml` from the project root
+- If the file does not exist, HALT and inform the user: "core-config.yaml not found. This file is required for story creation. You can either: 1) Copy core-config.yaml from GITHUB bmad-core/ and configure it for your game project OR 2) Run the BMad installer against your project to upgrade and add the file automatically. Please add and configure before proceeding."
+- Extract key configurations: `devStoryLocation`, `gdd.*`, `gamearchitecture.*`, `workflow.*`
 
-Before creating stories, ensure you have:
+### 1. Identify Next Story for Preparation
 
-- Completed Game Design Document (GDD)
-- Game Architecture Document
-- Epic definition this story belongs to
-- Clear understanding of the specific game feature
+#### 1.1 Locate Epic Files and Review Existing Stories
 
-## Process
+- Based on `gddSharded` from config, locate epic files (sharded location/pattern or monolithic GDD sections)
+- If `devStoryLocation` has story files, load the highest `{epicNum}.{storyNum}.story.md` file
+- **If highest story exists:**
+  - Verify status is 'Done'. If not, alert user: "ALERT: Found incomplete story! File: {lastEpicNum}.{lastStoryNum}.story.md Status: [current status] You should fix this story first, but would you like to accept risk & override to create the next story in draft?"
+  - If proceeding, select next sequential story in the current epic
+  - If epic is complete, prompt user: "Epic {epicNum} Complete: All stories in Epic {epicNum} have been completed. Would you like to: 1) Begin Epic {epicNum + 1} with story 1 2) Select a specific story to work on 3) Cancel story creation"
+  - **CRITICAL**: NEVER automatically skip to another epic. User MUST explicitly instruct which story to create.
+- **If no story files exist:** The next story is ALWAYS 1.1 (first story of first epic)
+- Announce the identified story to the user: "Identified next story for preparation: {epicNum}.{storyNum} - {Story Title}"
 
-### 1. Story Identification
+### 2. Gather Story Requirements and Previous Story Context
 
-**Review Epic Context:**
+- Extract story requirements from the identified epic file or GDD section
+- If previous story exists, review Dev Agent Record sections for:
+  - Completion Notes and Debug Log References
+  - Implementation deviations and technical decisions
+  - Unity-specific challenges (prefab issues, scene management, performance)
+  - Asset pipeline decisions and optimizations
+- Extract relevant insights that inform the current story's preparation
 
-- Understand the epic's overall goal
-- Identify specific features that need implementation
-- Review any existing stories in the epic
-- Ensure no duplicate work
+### 3. Gather Architecture Context
 
-**Feature Analysis:**
+#### 3.1 Determine Architecture Reading Strategy
 
-- Reference specific GDD sections
-- Understand player experience goals
-- Identify technical complexity
-- Estimate implementation scope
+- **If `gamearchitectureVersion: >= v3` and `gamearchitectureSharded: true`**: Read `{gamearchitectureShardedLocation}/index.md` then follow structured reading order below
+- **Else**: Use monolithic `gamearchitectureFile` for similar sections
 
-### 2. Story Scoping
+#### 3.2 Read Architecture Documents Based on Story Type
 
-**Single Responsibility:**
+**For ALL Game Stories:** tech-stack.md, unity-project-structure.md, coding-standards.md, testing-resilience-architecture.md
 
-- 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
+**For Gameplay/Mechanics Stories, additionally:** gameplay-systems-architecture.md, component-architecture-details.md, physics-config.md, input-system.md, state-machines.md, game-data-models.md
 
-**Implementation Clarity:**
+**For UI/UX Stories, additionally:** ui-architecture.md, ui-components.md, ui-state-management.md, scene-management.md
 
-- Define exactly what needs to be built
-- Specify all technical requirements
-- Include all necessary integration points
-- Provide clear success criteria
-
-### 3. Template Execution
-
-**Load Template:**
-Use `templates#game-story-tmpl` following all embedded LLM instructions
-
-**Key Focus Areas:**
-
-- Clear, actionable description
-- Specific acceptance criteria
-- Detailed technical specifications
-- Complete implementation task list
-- Comprehensive testing requirements
-
-### 4. Story Validation
-
-**Technical Review:**
-
-- Verify all technical specifications are complete
-- Ensure integration points are clearly defined
-- Confirm file paths match architecture
-- Validate C# interfaces and classes
-- Check for proper use of prefabs and scenes
-
-**Game Design Alignment:**
-
-- Confirm story implements GDD requirements
-- Verify player experience goals are met
-- Check balance parameters are included
-- Ensure game mechanics are correctly interpreted
-
-**Implementation Readiness:**
-
-- All dependencies identified
-- Assets requirements specified
-- Testing criteria defined
-- Definition of Done complete
-
-### 5. Quality Assurance
-
-**Apply Checklist:**
-Execute `checklists#game-story-dod-checklist` against completed story
-
-**Story Criteria:**
-
-- Story is immediately actionable
-- No design decisions left to developer
-- Technical requirements are complete
-- Testing requirements are comprehensive
-- Performance requirements are specified
-
-### 6. Story Refinement
-
-**Developer Perspective:**
-
-- Can a developer start implementation immediately?
-- Are all technical questions answered?
-- Is the scope appropriate for the estimated points?
-- Are all dependencies clearly identified?
-
-**Iterative Improvement:**
-
-- Address any gaps or ambiguities
-- Clarify complex technical requirements
-- Ensure story fits within epic scope
-- Verify story points estimation
-
-## Story Elements Checklist
-
-### Required Sections
-
-- [ ] Clear, specific description
-- [ ] Complete acceptance criteria (functional, technical, game design)
-- [ ] Detailed technical specifications
-- [ ] File creation/modification list
-- [ ] C# interfaces and classes
-- [ ] Integration point specifications
-- [ ] Ordered implementation tasks
-- [ ] Comprehensive testing requirements
-- [ ] Performance criteria
-- [ ] Dependencies clearly identified
-- [ ] Definition of Done checklist
-
-### Game-Specific Requirements
-
-- [ ] GDD section references
-- [ ] Game mechanic implementation details
-- [ ] Player experience goals
-- [ ] Balance parameters
-- [ ] Unity-specific requirements (components, prefabs, scenes)
-- [ ] Performance targets (stable frame rate)
-- [ ] Cross-platform considerations
-
-### Technical Quality
-
-- [ ] C# best practices compliance
-- [ ] Architecture document alignment
-- [ ] Code organization follows standards
-- [ ] Error handling requirements
-- [ ] Memory management considerations
-- [ ] Testing strategy defined
-
-## Common Pitfalls
-
-**Scope Issues:**
-
-- Story too large (break into multiple stories)
-- Story too vague (add specific requirements)
-- Missing dependencies (identify all prerequisites)
-- Unclear boundaries (define what's in/out of scope)
-
-**Technical Issues:**
-
-- Missing integration details
-- Incomplete technical specifications
-- Undefined interfaces or classes
-- Missing performance requirements
-
-**Game Design Issues:**
-
-- Not referencing GDD properly
-- Missing player experience context
-- Unclear game mechanic implementation
-- Missing balance parameters
-
-## Success Criteria
-
-**Story Readiness:**
-
-- [ ] Developer can start implementation immediately
-- [ ] No additional design decisions required
-- [ ] All technical questions answered
-- [ ] Testing strategy is complete
-- [ ] Performance requirements are clear
-- [ ] Story fits within epic scope
-
-**Quality Validation:**
-
-- [ ] Game story DOD checklist passes
-- [ ] Architecture alignment confirmed
-- [ ] GDD requirements covered
-- [ ] Implementation tasks are ordered and specific
-- [ ] Dependencies are complete and accurate
-
-## Handoff Protocol
-
-**To Game Developer:**
-
-1. Provide story document
-2. Confirm GDD and architecture access
-3. Verify all dependencies are met
-4. Answer any clarification questions
-5. Establish check-in schedule
-
-**Story Status Updates:**
-
-- Draft → Ready for Development
-- In Development → Code Review
-- Code Review → Testing
-- Testing → Done
-
-This task ensures game development stories are immediately actionable and enable efficient AI-driven development of game features in Unity.
+**For Backend/Services Stories, additionally:** game-data-models.md, data-persistence.md, save-system.md, analytics-integration.md, multiplayer-architecture.md
+
+**For Graphics/Rendering Stories, additionally:** rendering-pipeline.md, shader-guidelines.md, sprite-management.md, particle-systems.md
+
+**For Audio Stories, additionally:** audio-architecture.md, audio-mixing.md, sound-banks.md
+
+#### 3.3 Extract Story-Specific Technical Details
+
+Extract ONLY information directly relevant to implementing the current story. Do NOT invent new patterns, systems, or standards not in the source documents.
+
+Extract:
+
+- Specific Unity components and MonoBehaviours the story will use
+- Unity Package Manager dependencies and their APIs (e.g., Cinemachine, Input System, URP)
+- Package-specific configurations and setup requirements
+- Prefab structures and scene organization requirements
+- Input system bindings and configurations
+- Physics settings and collision layers
+- UI canvas and layout specifications
+- Asset naming conventions and folder structures
+- Performance budgets (target FPS, memory limits, draw calls)
+- Platform-specific considerations (mobile vs desktop)
+- Testing requirements specific to Unity features
+
+ALWAYS cite source documents: `[Source: gamearchitecture/{filename}.md#{section}]`
+
+### 4. Unity-Specific Technical Analysis
+
+#### 4.1 Package Dependencies Analysis
+
+- Identify Unity Package Manager packages required for the story
+- Document package versions from manifest.json
+- Note any package-specific APIs or components being used
+- List package configuration requirements (e.g., Input System settings, URP asset config)
+- Identify any third-party Asset Store packages and their integration points
+
+#### 4.2 Scene and Prefab Planning
+
+- Identify which scenes will be modified or created
+- List prefabs that need to be created or updated
+- Document prefab variant requirements
+- Specify scene loading/unloading requirements
+
+#### 4.3 Component Architecture
+
+- Define MonoBehaviour scripts needed
+- Specify ScriptableObject assets required
+- Document component dependencies and execution order
+- Identify required Unity Events and UnityActions
+- Note any package-specific components (e.g., Cinemachine VirtualCamera, InputActionAsset)
+
+#### 4.4 Asset Requirements
+
+- List sprite/texture requirements with resolution specs
+- Define animation clips and animator controllers needed
+- Specify audio clips and their import settings
+- Document any shader or material requirements
+- Note any package-specific assets (e.g., URP materials, Input Action maps)
+
+### 5. Populate Story Template with Full Context
+
+- Create new story file: `{devStoryLocation}/{epicNum}.{storyNum}.story.md` using Game Story Template
+- Fill in basic story information: Title, Status (Draft), Story statement, Acceptance Criteria from Epic/GDD
+- **`Dev Notes` section (CRITICAL):**
+  - CRITICAL: This section MUST contain ONLY information extracted from gamearchitecture documents and GDD. NEVER invent or assume technical details.
+  - Include ALL relevant technical details from Steps 2-4, organized by category:
+    - **Previous Story Insights**: Key learnings from previous story implementation
+    - **Package Dependencies**: Unity packages required, versions, configurations [with source references]
+    - **Unity Components**: Specific MonoBehaviours, ScriptableObjects, systems [with source references]
+    - **Scene & Prefab Specs**: Scene modifications, prefab structures, variants [with source references]
+    - **Input Configuration**: Input actions, bindings, control schemes [with source references]
+    - **UI Implementation**: Canvas setup, layout groups, UI events [with source references]
+    - **Asset Pipeline**: Asset requirements, import settings, optimization notes
+    - **Performance Targets**: FPS targets, memory budgets, profiler metrics
+    - **Platform Considerations**: Mobile vs desktop differences, input variations
+    - **Testing Requirements**: PlayMode tests, Unity Test Framework specifics
+  - Every technical detail MUST include its source reference: `[Source: gamearchitecture/{filename}.md#{section}]`
+  - If information for a category is not found in the gamearchitecture docs, explicitly state: "No specific guidance found in gamearchitecture docs"
+- **`Tasks / Subtasks` section:**
+  - Generate detailed, sequential list of technical tasks based ONLY on: Epic/GDD Requirements, Story AC, Reviewed GameArchitecture Information
+  - Include Unity-specific tasks:
+    - Scene setup and configuration
+    - Prefab creation and testing
+    - Component implementation with proper lifecycle methods
+    - Input system integration
+    - Physics configuration
+    - UI implementation with proper anchoring
+    - Performance profiling checkpoints
+  - Each task must reference relevant gamearchitecture documentation
+  - Include PlayMode testing as explicit subtasks
+  - Link tasks to ACs where applicable (e.g., `Task 1 (AC: 1, 3)`)
+- Add notes on Unity project structure alignment or discrepancies found in Step 4
+
+### 6. Story Draft Completion and Review
+
+- Review all sections for completeness and accuracy
+- Verify all source references are included for technical details
+- Ensure Unity-specific requirements are comprehensive:
+  - All scenes and prefabs documented
+  - Component dependencies clear
+  - Asset requirements specified
+  - Performance targets defined
+- Update status to "Draft" and save the story file
+- Execute `.bmad-2d-unity-game-dev/tasks/execute-checklist` `.bmad-2d-unity-game-dev/checklists/game-story-dod-checklist`
+- Provide summary to user including:
+  - Story created: `{devStoryLocation}/{epicNum}.{storyNum}.story.md`
+  - Status: Draft
+  - Key Unity components and systems included
+  - Scene/prefab modifications required
+  - Asset requirements identified
+  - Any deviations or conflicts noted between GDD and gamearchitecture
+  - Checklist Results
+  - Next steps: For complex Unity features, suggest the user review the story draft and optionally test critical assumptions in Unity Editor
+
+### 7. Unity-Specific Validation
+
+Before finalizing, ensure:
+
+- [ ] All required Unity packages are documented with versions
+- [ ] Package-specific APIs and configurations are included
+- [ ] All MonoBehaviour lifecycle methods are considered
+- [ ] Prefab workflows are clearly defined
+- [ ] Scene management approach is specified
+- [ ] Input system integration is complete (legacy or new Input System)
+- [ ] UI canvas setup follows Unity best practices
+- [ ] Performance profiling points are identified
+- [ ] Asset import settings are documented
+- [ ] Platform-specific code paths are noted
+- [ ] Package compatibility is verified (e.g., URP vs Built-in pipeline)
+
+This task ensures game development stories are immediately actionable and enable efficient AI-driven development of Unity 2D game features.
 ==================== END: .bmad-2d-unity-game-dev/tasks/create-game-story.md ====================
 
 ==================== START: .bmad-2d-unity-game-dev/tasks/execute-checklist.md ====================
@@ -403,11 +370,165 @@ The LLM will:
 - Offer to provide detailed analysis of any section, especially those with warnings or failures
 ==================== END: .bmad-2d-unity-game-dev/tasks/execute-checklist.md ====================
 
+==================== START: .bmad-2d-unity-game-dev/tasks/correct-course-game.md ====================
+# Correct Course Task - Game Development
+
+## Purpose
+
+- Guide a structured response to game development change triggers using the `.bmad-2d-unity-game-dev/checklists/game-change-checklist`.
+- Analyze the impacts of changes on game features, technical systems, and milestone deliverables.
+- Explore game-specific solutions (e.g., performance optimizations, feature scaling, platform adjustments).
+- Draft specific, actionable proposed updates to affected game artifacts (e.g., GDD sections, technical specs, Unity configurations).
+- Produce a consolidated "Game Development Change Proposal" document for review and approval.
+- Ensure clear handoff path for changes requiring fundamental redesign or technical architecture updates.
+
+## Instructions
+
+### 1. Initial Setup & Mode Selection
+
+- **Acknowledge Task & Inputs:**
+
+  - Confirm with the user that the "Game Development Correct Course Task" is being initiated.
+  - Verify the change trigger (e.g., performance issue, platform constraint, gameplay feedback, technical blocker).
+  - Confirm access to relevant game artifacts:
+    - Game Design Document (GDD)
+    - Technical Design Documents
+    - Unity Architecture specifications
+    - Performance budgets and platform requirements
+    - Current sprint's game stories and epics
+    - Asset specifications and pipelines
+  - Confirm access to `.bmad-2d-unity-game-dev/checklists/game-change-checklist`.
+
+- **Establish Interaction Mode:**
+  - Ask the user their preferred interaction mode:
+    - **"Incrementally (Default & Recommended):** Work through the game-change-checklist section by section, discussing findings and drafting changes collaboratively. Best for complex technical or gameplay changes."
+    - **"YOLO Mode (Batch Processing):** Conduct batched analysis and present consolidated findings. Suitable for straightforward performance optimizations or minor adjustments."
+  - Confirm the selected mode and inform: "We will now use the game-change-checklist to analyze the change and draft proposed updates specific to our Unity game development context."
+
+### 2. Execute Game Development Checklist Analysis
+
+- Systematically work through the game-change-checklist sections:
+
+  1. **Change Context & Game Impact**
+  2. **Feature/System Impact Analysis**
+  3. **Technical Artifact Conflict Resolution**
+  4. **Performance & Platform Evaluation**
+  5. **Path Forward Recommendation**
+
+- For each checklist section:
+  - Present game-specific prompts and considerations
+  - Analyze impacts on:
+    - Unity scenes and prefabs
+    - Component dependencies
+    - Performance metrics (FPS, memory, build size)
+    - Platform-specific code paths
+    - Asset loading and management
+    - Third-party plugins/SDKs
+  - Discuss findings with clear technical context
+  - Record status: `[x] Addressed`, `[N/A]`, `[!] Further Action Needed`
+  - Document Unity-specific decisions and constraints
+
+### 3. Draft Game-Specific Proposed Changes
+
+Based on the analysis and agreed path forward:
+
+- **Identify affected game artifacts requiring updates:**
+
+  - GDD sections (mechanics, systems, progression)
+  - Technical specifications (architecture, performance targets)
+  - Unity-specific configurations (build settings, quality settings)
+  - Game story modifications (scope, acceptance criteria)
+  - Asset pipeline adjustments
+  - Platform-specific adaptations
+
+- **Draft explicit changes for each artifact:**
+
+  - **Game Stories:** Revise story text, Unity-specific acceptance criteria, technical constraints
+  - **Technical Specs:** Update architecture diagrams, component hierarchies, performance budgets
+  - **Unity Configurations:** Propose settings changes, optimization strategies, platform variants
+  - **GDD Updates:** Modify feature descriptions, balance parameters, progression systems
+  - **Asset Specifications:** Adjust texture sizes, model complexity, audio compression
+  - **Performance Targets:** Update FPS goals, memory limits, load time requirements
+
+- **Include Unity-specific details:**
+  - Prefab structure changes
+  - Scene organization updates
+  - Component refactoring needs
+  - Shader/material optimizations
+  - Build pipeline modifications
+
+### 4. Generate "Game Development Change Proposal"
+
+- Create a comprehensive proposal document containing:
+
+  **A. Change Summary:**
+
+  - Original issue (performance, gameplay, technical constraint)
+  - Game systems affected
+  - Platform/performance implications
+  - Chosen solution approach
+
+  **B. Technical Impact Analysis:**
+
+  - Unity architecture changes needed
+  - Performance implications (with metrics)
+  - Platform compatibility effects
+  - Asset pipeline modifications
+  - Third-party dependency impacts
+
+  **C. Specific Proposed Edits:**
+
+  - For each game story: "Change Story GS-X.Y from: [old] To: [new]"
+  - For technical specs: "Update Unity Architecture Section X: [changes]"
+  - For GDD: "Modify [Feature] in Section Y: [updates]"
+  - For configurations: "Change [Setting] from [old_value] to [new_value]"
+
+  **D. Implementation Considerations:**
+
+  - Required Unity version updates
+  - Asset reimport needs
+  - Shader recompilation requirements
+  - Platform-specific testing needs
+
+### 5. Finalize & Determine Next Steps
+
+- Obtain explicit approval for the "Game Development Change Proposal"
+- Provide the finalized document to the user
+
+- **Based on change scope:**
+
+  - **Minor adjustments (can be handled in current sprint):**
+    - Confirm task completion
+    - Suggest handoff to game-dev agent for implementation
+    - Note any required playtesting validation
+  - **Major changes (require replanning):**
+    - Clearly state need for deeper technical review
+    - Recommend engaging Game Architect or Technical Lead
+    - Provide proposal as input for architecture revision
+    - Flag any milestone/deadline impacts
+
+## Output Deliverables
+
+- **Primary:** "Game Development Change Proposal" document containing:
+
+  - Game-specific change analysis
+  - Technical impact assessment with Unity context
+  - Platform and performance considerations
+  - Clearly drafted updates for all affected game artifacts
+  - Implementation guidance and constraints
+
+- **Secondary:** Annotated game-change-checklist showing:
+  - Technical decisions made
+  - Performance trade-offs considered
+  - Platform-specific accommodations
+  - Unity-specific implementation notes
+==================== END: .bmad-2d-unity-game-dev/tasks/correct-course-game.md ====================
+
 ==================== START: .bmad-2d-unity-game-dev/templates/game-story-tmpl.yaml ====================
 template:
-  id: game-story-template-v2
+  id: game-story-template-v3
   name: Game Development Story
-  version: 2.0
+  version: 3.0
   output:
     format: markdown
     filename: "stories/{{epic_name}}/{{story_id}}-{{story_name}}.md"
@@ -455,9 +576,9 @@ sections:
         title: Technical Requirements
         type: checklist
         items:
-          - "Code follows C# best practices"
-          - "Maintains stable frame rate on target devices"
-          - "No memory leaks or performance degradation"
+          - Code follows C# best practices
+          - Maintains stable frame rate on target devices
+          - No memory leaks or performance degradation
           - "{{specific_technical_requirement}}"
       - id: game-design-requirements
         title: Game Design Requirements
@@ -633,13 +754,13 @@ sections:
     instruction: Checklist that must be completed before the story is considered finished
     type: checklist
     items:
-      - "All acceptance criteria met"
-      - "Code reviewed and approved"
-      - "Unit tests written and passing"
-      - "Integration tests passing"
-      - "Performance targets met"
-      - "No C# compiler errors or warnings"
-      - "Documentation updated"
+      - All acceptance criteria met
+      - Code reviewed and approved
+      - Unit tests written and passing
+      - Integration tests passing
+      - Performance targets met
+      - No C# compiler errors or warnings
+      - Documentation updated
       - "{{game_specific_dod_item}}"
 
   - id: notes
@@ -662,165 +783,208 @@ sections:
       - {{future_optimization_1}}
 ==================== END: .bmad-2d-unity-game-dev/templates/game-story-tmpl.yaml ====================
 
-==================== START: .bmad-2d-unity-game-dev/checklists/game-story-dod-checklist.md ====================
-# Game Development Story Definition of Done Checklist
-
-## Story Completeness
-
-### Basic Story Elements
-
-- [ ] **Story Title** - Clear, descriptive title that identifies the feature
-- [ ] **Epic Assignment** - Story is properly assigned to relevant epic
-- [ ] **Priority Level** - Appropriate priority assigned (High/Medium/Low)
-- [ ] **Story Points** - Realistic estimation for implementation complexity
-- [ ] **Description** - Clear, concise description of what needs to be implemented
-
-### Game Design Alignment
-
-- [ ] **GDD Reference** - Specific Game Design Document section referenced
-- [ ] **Game Mechanic Context** - Clear connection to game mechanics defined in GDD
-- [ ] **Player Experience Goal** - Describes the intended player experience
-- [ ] **Balance Parameters** - Includes any relevant game balance values
-- [ ] **Design Intent** - Purpose and rationale for the feature is clear
-
-## Technical Specifications
-
-### Architecture Compliance
-
-- [ ] **File Organization** - Follows game architecture document structure (e.g., scripts, prefabs, scenes)
-- [ ] **Class Definitions** - C# classes and interfaces are properly defined
-- [ ] **Integration Points** - Clear specification of how feature integrates with existing systems
-- [ ] **Event Communication** - UnityEvents or C# events usage specified
-- [ ] **Dependencies** - All system dependencies clearly identified
-
-### Unity Requirements
-
-- [ ] **Scene Integration** - Specifies which scenes are affected and how
-- [ ] **Prefab Usage** - Proper use of prefabs for reusable GameObjects
-- [ ] **Component Design** - Logic is encapsulated in well-defined MonoBehaviour components
-- [ ] **Asset Requirements** - All needed assets (sprites, audio, materials) identified
-- [ ] **Performance Considerations** - Stable frame rate target and optimization requirements
-
-### Code Quality Standards
-
-- [ ] **C# Best Practices** - All code must comply with modern C# standards
-- [ ] **Error Handling** - Error scenarios and handling requirements specified
-- [ ] **Memory Management** - Coroutine and object lifecycle management requirements where needed
-- [ ] **Cross-Platform Support** - Desktop and mobile considerations addressed
-- [ ] **Code Organization** - Follows established Unity project structure
+==================== START: .bmad-2d-unity-game-dev/checklists/game-change-checklist.md ====================
+# Game Development Change Navigation Checklist
 
-## Implementation Readiness
+**Purpose:** To systematically guide the Game SM agent and user through analysis and planning when a significant change (performance issue, platform constraint, technical blocker, gameplay feedback) is identified during Unity game development.
 
-### Acceptance Criteria
+**Instructions:** Review each item with the user. Mark `[x]` for completed/confirmed, `[N/A]` if not applicable, or add notes for discussion points.
 
-- [ ] **Functional Requirements** - All functional acceptance criteria are specific and testable
-- [ ] **Technical Requirements** - Technical acceptance criteria are complete and verifiable
-- [ ] **Game Design Requirements** - Game-specific requirements match GDD specifications
-- [ ] **Performance Requirements** - Frame rate and memory usage criteria specified
-- [ ] **Completeness** - No acceptance criteria are vague or unmeasurable
+[[LLM: INITIALIZATION INSTRUCTIONS - GAME CHANGE NAVIGATION
 
-### Implementation Tasks
+Changes during game development are common - performance issues, platform constraints, gameplay feedback, and technical limitations are part of the process.
 
-- [ ] **Task Breakdown** - Story broken into specific, ordered implementation tasks
-- [ ] **Task Scope** - Each task is completable in 1-4 hours
-- [ ] **Task Clarity** - Each task has clear, actionable instructions
-- [ ] **File Specifications** - Exact file paths and purposes specified (e.g., `Scripts/Player/PlayerMovement.cs`)
-- [ ] **Development Flow** - Tasks follow logical implementation order
+Before proceeding, understand:
 
-### Dependencies
+1. This checklist is for SIGNIFICANT changes affecting game architecture or features
+2. Minor tweaks (shader adjustments, UI positioning) don't require this process
+3. The goal is to maintain playability while adapting to technical realities
+4. Performance and player experience are paramount
 
-- [ ] **Story Dependencies** - All prerequisite stories identified with IDs
-- [ ] **Technical Dependencies** - Required systems and files identified
-- [ ] **Asset Dependencies** - All needed assets specified with locations
-- [ ] **External Dependencies** - Any third-party or external requirements noted (e.g., Asset Store packages)
-- [ ] **Dependency Validation** - All dependencies are actually available
+Required context:
 
-## Testing Requirements
+- The triggering issue (performance metrics, crash logs, feedback)
+- Current development state (implemented features, current sprint)
+- Access to GDD, technical specs, and performance budgets
+- Understanding of remaining features and milestones
 
-### Test Coverage
+APPROACH:
+This is an interactive process. Discuss performance implications, platform constraints, and player impact. The user makes final decisions, but provide expert Unity/game dev guidance.
 
-- [ ] **Unit Test Requirements** - Specific unit test files and scenarios defined for NUnit
-- [ ] **Integration Test Cases** - Integration testing with other game systems specified
-- [ ] **Manual Test Cases** - Game-specific manual testing procedures defined in the Unity Editor
-- [ ] **Performance Tests** - Frame rate and memory testing requirements specified
-- [ ] **Edge Case Testing** - Edge cases and error conditions covered
+REMEMBER: Game development is iterative. Changes often lead to better gameplay and performance.]]
 
-### Test Implementation
-
-- [ ] **Test File Paths** - Exact test file locations specified (e.g., `Assets/Tests/EditMode`)
-- [ ] **Test Scenarios** - All test scenarios are complete and executable
-- [ ] **Expected Behaviors** - Clear expected outcomes for all tests defined
-- [ ] **Performance Metrics** - Specific performance targets for testing
-- [ ] **Test Data** - Any required test data or mock objects specified
-
-## Game-Specific Quality
-
-### Gameplay Implementation
-
-- [ ] **Mechanic Accuracy** - Implementation matches GDD mechanic specifications
-- [ ] **Player Controls** - Input handling requirements are complete (e.g., Input System package)
-- [ ] **Game Feel** - Requirements for juice, feedback, and responsiveness specified
-- [ ] **Balance Implementation** - Numeric values and parameters from GDD included
-- [ ] **State Management** - Game state changes and persistence requirements defined
-
-### User Experience
-
-- [ ] **UI Requirements** - User interface elements and behaviors specified (e.g., UI Toolkit or UGUI)
-- [ ] **Audio Integration** - Sound effect and music requirements defined
-- [ ] **Visual Feedback** - Animation and visual effect requirements specified (e.g., Animator, Particle System)
-- [ ] **Accessibility** - Mobile touch and responsive design considerations
-- [ ] **Error Recovery** - User-facing error handling and recovery specified
-
-### Performance Optimization
-
-- [ ] **Frame Rate Targets** - Specific FPS requirements for different platforms
-- [ ] **Memory Usage** - Memory consumption limits and monitoring requirements (e.g., Profiler)
-- [ ] **Asset Optimization** - Texture, audio, and data optimization requirements
-- [ ] **Mobile Considerations** - Touch controls and mobile performance requirements
-- [ ] **Loading Performance** - Asset loading and scene transition requirements
-
-## Documentation and Communication
-
-### Story Documentation
-
-- [ ] **Implementation Notes** - Additional context and implementation guidance provided
-- [ ] **Design Decisions** - Key design choices documented with rationale
-- [ ] **Future Considerations** - Potential future enhancements or modifications noted
-- [ ] **Change Tracking** - Process for tracking any requirement changes during development
-- [ ] **Reference Materials** - Links to relevant GDD sections and architecture docs
-
-### Developer Handoff
-
-- [ ] **Immediate Actionability** - Developer can start implementation without additional questions
-- [ ] **Complete Context** - All necessary context provided within the story
-- [ ] **Clear Boundaries** - What is and isn't included in the story scope is clear
-- [ ] **Success Criteria** - Objective measures for story completion defined
-- [ ] **Communication Plan** - Process for developer questions and updates established
-
-## Final Validation
-
-### Story Readiness
-
-- [ ] **No Ambiguity** - No sections require interpretation or additional design decisions
-- [ ] **Technical Completeness** - All technical requirements are specified and actionable
-- [ ] **Scope Appropriateness** - Story scope matches assigned story points
-- [ ] **Quality Standards** - Story meets all game development quality standards
-- [ ] **Review Completion** - Story has been reviewed for completeness and accuracy
-
-### Implementation Preparedness
-
-- [ ] **Environment Ready** - Development environment requirements specified (e.g., Unity version)
-- [ ] **Resources Available** - All required resources (assets, docs, dependencies) accessible
-- [ ] **Testing Prepared** - Testing environment and data requirements specified
-- [ ] **Definition of Done** - Clear, objective completion criteria established
-- [ ] **Handoff Complete** - Story is ready for developer assignment and implementation
-
-## Checklist Completion
-
-**Overall Story Quality:** ⭐⭐⭐⭐⭐
+---
 
-**Ready for Development:** [ ] Yes [ ] No
+## 1. Understand the Trigger & Context
+
+[[LLM: Start by understanding the game-specific issue. Ask technical questions:
+
+- What performance metrics triggered this? (FPS, memory, load times)
+- Is this platform-specific or universal?
+- Can we reproduce it consistently?
+- What Unity profiler data do we have?
+- Is this a gameplay issue or technical constraint?
+
+Focus on measurable impacts and technical specifics.]]
+
+- [ ] **Identify Triggering Element:** Clearly identify the game feature/system revealing the issue.
+- [ ] **Define the Issue:** Articulate the core problem precisely.
+  - [ ] Performance bottleneck (CPU/GPU/Memory)?
+  - [ ] Platform-specific limitation?
+  - [ ] Unity engine constraint?
+  - [ ] Gameplay/balance issue from playtesting?
+  - [ ] Asset pipeline or build size problem?
+  - [ ] Third-party SDK/plugin conflict?
+- [ ] **Assess Performance Impact:** Document specific metrics (current FPS, target FPS, memory usage, build size).
+- [ ] **Gather Technical Evidence:** Note profiler data, crash logs, platform test results, player feedback.
+
+## 2. Game Feature Impact Assessment
+
+[[LLM: Game features are interconnected. Evaluate systematically:
+
+1. Can we optimize the current feature without changing gameplay?
+2. Do dependent features need adjustment?
+3. Are there platform-specific workarounds?
+4. Does this affect our performance budget allocation?
+
+Consider both technical and gameplay impacts.]]
+
+- [ ] **Analyze Current Sprint Features:**
+  - [ ] Can the current feature be optimized (LOD, pooling, batching)?
+  - [ ] Does it need gameplay simplification?
+  - [ ] Should it be platform-specific (high-end only)?
+- [ ] **Analyze Dependent Systems:**
+  - [ ] Review all game systems interacting with the affected feature.
+  - [ ] Do physics systems need adjustment?
+  - [ ] Are UI/HUD systems impacted?
+  - [ ] Do save/load systems require changes?
+  - [ ] Are multiplayer systems affected?
+- [ ] **Summarize Feature Impact:** Document effects on gameplay systems and technical architecture.
+
+## 3. Game Artifact Conflict & Impact Analysis
+
+[[LLM: Game documentation drives development. Check each artifact:
+
+1. Does this invalidate GDD mechanics?
+2. Are technical architecture assumptions still valid?
+3. Do performance budgets need reallocation?
+4. Are platform requirements still achievable?
+
+Missing conflicts cause performance issues later.]]
+
+- [ ] **Review GDD:**
+  - [ ] Does the issue conflict with core gameplay mechanics?
+  - [ ] Do game features need scaling for performance?
+  - [ ] Are progression systems affected?
+  - [ ] Do balance parameters need adjustment?
+- [ ] **Review Technical Architecture:**
+  - [ ] Does the issue conflict with Unity architecture (scene structure, prefab hierarchy)?
+  - [ ] Are component systems impacted?
+  - [ ] Do shader/rendering approaches need revision?
+  - [ ] Are data structures optimal for the scale?
+- [ ] **Review Performance Specifications:**
+  - [ ] Are target framerates still achievable?
+  - [ ] Do memory budgets need reallocation?
+  - [ ] Are load time targets realistic?
+  - [ ] Do we need platform-specific targets?
+- [ ] **Review Asset Specifications:**
+  - [ ] Do texture resolutions need adjustment?
+  - [ ] Are model poly counts appropriate?
+  - [ ] Do audio compression settings need changes?
+  - [ ] Is the animation budget sustainable?
+- [ ] **Summarize Artifact Impact:** List all game documents requiring updates.
+
+## 4. Path Forward Evaluation
+
+[[LLM: Present game-specific solutions with technical trade-offs:
+
+1. What's the performance gain?
+2. How much rework is required?
+3. What's the player experience impact?
+4. Are there platform-specific solutions?
+5. Is this maintainable across updates?
+
+Be specific about Unity implementation details.]]
+
+- [ ] **Option 1: Optimization Within Current Design:**
+  - [ ] Can performance be improved through Unity optimizations?
+    - [ ] Object pooling implementation?
+    - [ ] LOD system addition?
+    - [ ] Texture atlasing?
+    - [ ] Draw call batching?
+    - [ ] Shader optimization?
+  - [ ] Define specific optimization techniques.
+  - [ ] Estimate performance improvement potential.
+- [ ] **Option 2: Feature Scaling/Simplification:**
+  - [ ] Can the feature be simplified while maintaining fun?
+  - [ ] Identify specific elements to scale down.
+  - [ ] Define platform-specific variations.
+  - [ ] Assess player experience impact.
+- [ ] **Option 3: Architecture Refactor:**
+  - [ ] Would restructuring improve performance significantly?
+  - [ ] Identify Unity-specific refactoring needs:
+    - [ ] Scene organization changes?
+    - [ ] Prefab structure optimization?
+    - [ ] Component system redesign?
+    - [ ] State machine optimization?
+  - [ ] Estimate development effort.
+- [ ] **Option 4: Scope Adjustment:**
+  - [ ] Can we defer features to post-launch?
+  - [ ] Should certain features be platform-exclusive?
+  - [ ] Do we need to adjust milestone deliverables?
+- [ ] **Select Recommended Path:** Choose based on performance gain vs. effort.
+
+## 5. Game Development Change Proposal Components
+
+[[LLM: The proposal must include technical specifics:
+
+1. Performance metrics (before/after projections)
+2. Unity implementation details
+3. Platform-specific considerations
+4. Testing requirements
+5. Risk mitigation strategies
+
+Make it actionable for game developers.]]
+
+(Ensure all points from previous sections are captured)
+
+- [ ] **Technical Issue Summary:** Performance/technical problem with metrics.
+- [ ] **Feature Impact Summary:** Affected game systems and dependencies.
+- [ ] **Performance Projections:** Expected improvements from chosen solution.
+- [ ] **Implementation Plan:** Unity-specific technical approach.
+- [ ] **Platform Considerations:** Any platform-specific implementations.
+- [ ] **Testing Strategy:** Performance benchmarks and validation approach.
+- [ ] **Risk Assessment:** Technical risks and mitigation plans.
+- [ ] **Updated Game Stories:** Revised stories with technical constraints.
+
+## 6. Final Review & Handoff
+
+[[LLM: Game changes require technical validation. Before concluding:
+
+1. Are performance targets clearly defined?
+2. Is the Unity implementation approach clear?
+3. Do we have rollback strategies?
+4. Are test scenarios defined?
+5. Is platform testing covered?
+
+Get explicit approval on technical approach.
+
+FINAL REPORT:
+Provide a technical summary:
+
+- Performance issue and root cause
+- Chosen solution with expected gains
+- Implementation approach in Unity
+- Testing and validation plan
+- Timeline and milestone impacts
+
+Keep it technically precise and actionable.]]
+
+- [ ] **Review Checklist:** Confirm all technical aspects discussed.
+- [ ] **Review Change Proposal:** Ensure Unity implementation details are clear.
+- [ ] **Performance Validation:** Define how we'll measure success.
+- [ ] **User Approval:** Obtain approval for technical approach.
+- [ ] **Developer Handoff:** Ensure game-dev agent has all technical details needed.
 
-**Additional Notes:**
-_Any specific concerns, recommendations, or clarifications needed before development begins._
-==================== END: .bmad-2d-unity-game-dev/checklists/game-story-dod-checklist.md ====================
+---
+==================== END: .bmad-2d-unity-game-dev/checklists/game-change-checklist.md ====================