bmad-method 4.31.0 → 4.33.0

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

@@ -531,25 +531,21 @@ Assets/
 ### 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 Unity's component-based architecture
    - Plan testing approach
 
 3. **Implement Feature:**
-
    - Write clean C# code following all guidelines
    - Use established patterns
    - Maintain stable FPS performance
 
 4. **Test Implementation:**
-
    - Write edit mode tests for game logic
    - Write play mode tests for integration testing
    - Test cross-platform functionality

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

@@ -18,7 +18,6 @@
 2. If the section contains game flow diagrams, level layouts, or system diagrams, explain each diagram briefly with game development context before offering elicitation options (e.g., "The gameplay loop diagram shows how player actions lead to rewards and progression. Notice how each step maintains player engagement and creates opportunities for skill development.")
 
 3. If the section contains multiple game elements (like multiple mechanics, multiple levels, multiple systems, etc.), inform the user they can apply elicitation actions to:
-
    - The entire section as a whole
    - Individual game elements within the section (specify which element when selecting an action)
 

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

@@ -0,0 +1,141 @@
+# 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.