bmad-method 4.31.0 → 4.32.0

package/expansion-packs/bmad-2d-unity-game-dev/tasks/correct-course-game.md

@@ -0,0 +1,151 @@
+# Correct Course Task - Game Development
+
+## Purpose
+
+- Guide a structured response to game development change triggers using the `{root}/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 `{root}/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

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

@@ -1,217 +1,184 @@
-# 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 `{root}/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 `{root}/tasks/execute-checklist` `{root}/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.