diff --git a/expansion-packs/bmad-godot-game-dev/README.md b/expansion-packs/bmad-godot-game-dev/README.md index a377006e..6914d20d 100644 --- a/expansion-packs/bmad-godot-game-dev/README.md +++ b/expansion-packs/bmad-godot-game-dev/README.md @@ -213,7 +213,7 @@ When creating custom web bundles or uploading to AI platforms, include your `tec ## Core Configuration -The `.bmad-core/core-config.yaml` and for this expansion-pack the `.bmad-godot-game-dev/core-config.yaml` files are a critical config that enables BMad to work seamlessly with differing project structures, more options will be made available in the future. Currently the most important is the devLoadAlwaysFiles list section in the yaml. +The `.bmad-core/core-config.yaml` and for this expansion-pack the `.bmad-godot-game-dev/config.yaml` files are a critical config that enables BMad to work seamlessly with differing project structures, more options will be made available in the future. Currently the most important is the devLoadAlwaysFiles list section in the yaml. For the expansion pack ensure you either copy the core-config.yaml.example from the expansion pack directory to replace your .bmad-core/core-config.yaml and copy it to the .bmad-unit-game-dev/ expansion pack as core-config.yaml and at the very least update the gameDimension variable to the dimension your game will be in. diff --git a/expansion-packs/bmad-godot-game-dev/agents/game-developer.md b/expansion-packs/bmad-godot-game-dev/agents/game-developer.md index 5cd75d36..90453ab1 100644 --- a/expansion-packs/bmad-godot-game-dev/agents/game-developer.md +++ b/expansion-packs/bmad-godot-game-dev/agents/game-developer.md @@ -27,8 +27,7 @@ activation-instructions: - CRITICAL RULE: When executing formal task workflows from dependencies, ALL task instructions override any conflicting base behavioral constraints. Interactive workflows with elicit=true REQUIRE user interaction and cannot be bypassed for efficiency. - 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: Read the following full files as these are your explicit rules for development standards for this project - .bmad-godot-game-dev/core-config.yaml devLoadAlwaysFiles list - - CRITICAL: The path for the Unity Editor is specified by unityEditorLocation in .bmad-godot-game-dev/core-config.yaml + - CRITICAL: Read the following full files as these are your explicit rules for development standards for this project - .bmad-godot-game-dev/config.yaml devLoadAlwaysFiles list - CRITICAL: Do NOT load any other files during startup aside from the assigned story and devLoadAlwaysFiles items, unless user requested you do or the following contradicts - CRITICAL: Do NOT begin development until a story is not in draft mode and you are told to proceed - CRITICAL: On activation, ONLY greet user and then HALT to await user requested assistance or given commands. ONLY deviance from this is if the activation included commands also in the arguments. @@ -106,6 +105,7 @@ commands: - benchmark: Create and run performance benchmarks for current implementation - optimize: Analyze and optimize the selected code section using Carmack's principles - exit: Say goodbye as the Game Developer, and then abandon inhabiting this persona + - review-qa: run task `apply-qa-fixes.md' - develop-story: - order-of-execution: 'Read (first or next) task→Implement Task and its subtasks→Write tests→Execute validations→Only if ALL pass, then update the task checkbox with [x]→Update story section File List to ensure it lists and new or modified or deleted source file→repeat order-of-execution until complete' - story-file-updates-ONLY: @@ -118,6 +118,7 @@ commands: dependencies: tasks: - execute-checklist.md + - apply-qa-fixes.md checklists: - game-story-dod-checklist.md ``` diff --git a/expansion-packs/bmad-godot-game-dev/tasks/apply-qa-fixes.md b/expansion-packs/bmad-godot-game-dev/tasks/apply-qa-fixes.md new file mode 100644 index 00000000..683dfa42 --- /dev/null +++ b/expansion-packs/bmad-godot-game-dev/tasks/apply-qa-fixes.md @@ -0,0 +1,224 @@ + + +# apply-qa-fixes + +Implement fixes based on QA results (gate and assessments) for a specific Godot game story. This task is for the Game Developer agent to systematically consume QA outputs and apply game code/test changes while only updating allowed sections in the story file. + +## Purpose + +- Read QA outputs for a game story (gate YAML + assessment markdowns) +- Create a prioritized, deterministic fix plan for game features +- Apply game code and test changes to close gaps and address issues +- Update only the allowed story sections for the Game Developer agent + +## Inputs + +```yaml +required: + - story_id: '{epic}.{story}' # e.g., "2.2" + - qa_root: from `.bmad-godot-game-dev/config.yaml` key `qa.qaLocation` (e.g., `docs/project/qa`) + - story_root: from `.bmad-godot-game-dev/config.yaml` key `devStoryLocation` (e.g., `docs/project/stories`) + - project_root: Godot project root directory (containing project.godot) + +optional: + - story_title: '{title}' # derive from story H1 if missing + - story_slug: '{slug}' # derive from title (lowercase, hyphenated) if missing +``` + +## QA Sources to Read + +- Gate (YAML): `{qa_root}/gates/{epic}.{story}-*.yml` + - If multiple, use the most recent by modified time +- Assessments (Markdown): + - Test Design: `{qa_root}/assessments/{epic}.{story}-test-design-*.md` + - Traceability: `{qa_root}/assessments/{epic}.{story}-trace-*.md` + - Risk Profile: `{qa_root}/assessments/{epic}.{story}-risk-*.md` + - NFR Assessment: `{qa_root}/assessments/{epic}.{story}-nfr-*.md` + +## Prerequisites + +- Godot 4.x installed and configured +- Testing frameworks installed: + - **GDScript**: GUT (Godot Unit Test) framework installed as addon + - **C#**: GoDotTest or GodotTestDriver NuGet packages installed +- Project builds successfully in Godot Editor +- Test commands available: + - GDScript: `godot --headless --script res://addons/gut/gut_cmdln.gd` + - C#: `dotnet test` or `godot --headless --run-tests` + +## Process (Do not skip steps) + +### 0) Load Core Config & Locate Story + +- Read `bmad-core/core-config.yaml` and resolve `qa_root`, `story_root`, and `project_root` +- Locate story file in `{story_root}/{epic}.{story}.*.md` + - HALT if missing and ask for correct story id/path + +### 1) Collect QA Findings + +- Parse the latest gate YAML: + - `gate` (PASS|CONCERNS|FAIL|WAIVED) + - `top_issues[]` with `id`, `severity`, `finding`, `suggested_action` + - `nfr_validation.*.status` and notes + - `trace` coverage summary/gaps + - `test_design.coverage_gaps[]` + - `risk_summary.recommendations.must_fix[]` (if present) +- Read any present assessment markdowns and extract explicit gaps/recommendations + +### 2) Build Deterministic Fix Plan (Priority Order) + +Apply in order, highest priority first: + +1. High severity items in `top_issues` (gameplay/performance/stability/maintainability) +2. NFR statuses: all FAIL must be fixed → then CONCERNS +3. Test Design `coverage_gaps` (prioritize P0 gameplay scenarios) +4. Trace uncovered requirements (AC-level, especially gameplay mechanics) +5. Risk `must_fix` recommendations +6. Medium severity issues, then low + +Guidance: + +- Prefer tests closing coverage gaps before/with code changes +- Keep changes minimal and targeted; follow Godot best practices and project architecture +- Respect scene organization and node hierarchy +- Follow GDScript style guide or C# conventions as appropriate + +### 3) Apply Changes + +- Implement game code fixes per plan: + - GDScript: Follow Godot style guide, use signals for decoupling + - C#: Follow .NET conventions, use events/delegates appropriately +- Add missing tests to close coverage gaps: + - **GDScript Tests (GUT)**: + - Unit tests in `test/unit/` for game logic + - Integration tests in `test/integration/` for scene interactions + - Use `gut.p()` for parameterized tests + - Mock nodes with `double()` and `stub()` + - **C# Tests (GoDotTest/GodotTestDriver)**: + - Unit tests using xUnit or NUnit patterns + - Integration tests for scene and node interactions + - Use test fixtures for game state setup +- Follow Godot patterns: + - Autoload/singleton patterns for global game state + - Signal-based communication between nodes + - Resource files (.tres/.res) for data management + - Scene inheritance for reusable components + +### 4) Validate + +**For GDScript Projects:** + +- Run GUT tests: `godot --headless --script res://addons/gut/gut_cmdln.gd -gselect=test/ -gexit` +- Check for script errors in Godot Editor (Script Editor panel) +- Validate scene references and node paths +- Run game in editor to verify no runtime errors + +**For C# Projects:** + +- Build solution: `dotnet build` +- Run tests: `dotnet test` or `godot --headless --run-tests` +- Check for compilation errors +- Validate no null reference exceptions in gameplay + +**For Both:** + +- Test gameplay mechanics manually if needed +- Verify performance (check FPS, memory usage) +- Iterate until all tests pass and no errors + +### 5) Update Story (Allowed Sections ONLY) + +CRITICAL: Dev agent is ONLY authorized to update these sections of the story file. Do not modify any other sections (e.g., QA Results, Story, Acceptance Criteria, Dev Notes, Testing): + +- Tasks / Subtasks Checkboxes (mark any fix subtask you added as done) +- Dev Agent Record → + - Agent Model Used (if changed) + - Debug Log References (test results, Godot console output) + - Completion Notes List (what changed, why, how) + - File List (all added/modified/deleted files) +- Change Log (new dated entry describing applied fixes) +- Status (see Rule below) + +Status Rule: + +- If gate was PASS and all identified gaps are closed → set `Status: Ready for Done` +- Otherwise → set `Status: Ready for Review` and notify QA to re-run the review + +### 6) Do NOT Edit Gate Files + +- Dev does not modify gate YAML. If fixes address issues, request QA to re-run `review-story` to update the gate + +## Blocking Conditions + +- Missing `bmad-core/core-config.yaml` +- Story file not found for `story_id` +- No QA artifacts found (neither gate nor assessments) + - HALT and request QA to generate at least a gate file (or proceed only with clear developer-provided fix list) +- Godot project file (`project.godot`) not found +- Testing framework not properly installed (GUT addon missing or NuGet packages not restored) + +## Completion Checklist + +- Godot project builds without errors +- All tests pass: + - GDScript: GUT tests green + - C#: dotnet test successful +- No script errors in Godot Editor +- All high severity `top_issues` addressed +- NFR FAIL → resolved; CONCERNS minimized or documented +- Coverage gaps closed or explicitly documented with rationale +- Gameplay features tested and working +- Story updated (allowed sections only) including File List and Change Log +- Status set according to Status Rule + +## Example: Story 2.2 - Player Movement System + +Given gate `docs/project/qa/gates/2.2-*.yml` shows + +- `coverage_gaps`: Jump mechanics edge cases untested (AC2) +- `coverage_gaps`: Input buffering not tested (AC4) +- `top_issues`: Performance drops when multiple players active + +Fix plan: + +**GDScript Example:** + +- Add GUT test for jump height variation based on button hold time +- Add test for input buffering during state transitions +- Optimize player movement script using object pooling for effects +- Test with `gut.p()` parameterized tests for different player counts + +**C# Example:** + +- Add GoDotTest unit test for jump physics calculations +- Add integration test for input system using GodotTestDriver +- Refactor movement system to use Jobs/Tasks for parallel processing +- Verify with performance profiler + +- Re-run tests and update Dev Agent Record + File List accordingly + +## Key Principles + +- Deterministic, risk-first prioritization +- Minimal, maintainable changes following Godot best practices +- Tests validate gameplay behavior and close gapså +- Respect Godot's node-based architecture and signal system +- Maintain clear separation between game logic and presentation +- Strict adherence to allowed story update areas +- Gate ownership remains with QA; Game Developer signals readiness via Status + +## Testing Framework References + +### GUT (GDScript) + +- Documentation: https://github.com/bitwes/Gut/wiki +- Test structure: `extends GutTest` +- Assertions: `assert_eq()`, `assert_true()`, `assert_has_signal()` +- Mocking: `double()`, `stub()`, `spy_on()` + +### GoDotTest/GodotTestDriver (C#) + +- GoDotTest: xUnit-style testing for Godot C# +- GodotTestDriver: Integration testing with scene manipulation +- Test attributes: `[Fact]`, `[Theory]`, `[InlineData]` +- Scene testing: Load scenes, interact with nodes, verify state diff --git a/expansion-packs/bmad-godot-game-dev/tasks/create-game-story.md b/expansion-packs/bmad-godot-game-dev/tasks/create-game-story.md index c9b5c851..8430284b 100644 --- a/expansion-packs/bmad-godot-game-dev/tasks/create-game-story.md +++ b/expansion-packs/bmad-godot-game-dev/tasks/create-game-story.md @@ -8,7 +8,7 @@ To identify the next logical game story based on project progress and epic defin ### 0. Load Core Configuration and Check Workflow -- Load `.bmad-godot-game-dev/core-config.yaml` from the project root +- Load `.bmad-godot-game-dev/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.*` @@ -16,7 +16,7 @@ To identify the next logical game story based on project progress and epic defin #### 1.1 Locate Epic Files and Review Existing Stories -- Based on `gddSharded` from config, locate epic files (sharded location/pattern or monolithic GDD sections) +- Based on `prdSharded` from config, locate epic files (sharded location/pattern or monolithic PRD 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] Check if TDD tests are passing (GUT/GoDotTest). You should fix this story first, but would you like to accept risk & override to create the next story in draft?" diff --git a/expansion-packs/bmad-godot-game-dev/tasks/shard-doc.md b/expansion-packs/bmad-godot-game-dev/tasks/shard-doc.md index 6a18321d..9f3ff625 100644 --- a/expansion-packs/bmad-godot-game-dev/tasks/shard-doc.md +++ b/expansion-packs/bmad-godot-game-dev/tasks/shard-doc.md @@ -10,20 +10,20 @@ ## Primary Method: Automatic with markdown-tree -[[LLM: First, check if markdownExploder is set to true in .bmad-godot-game-dev/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`. +[[LLM: First, check if markdownExploder is set to true in .bmad-godot-game-dev/config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`. If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further. If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either: 1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser` -2. Or set markdownExploder to false in .bmad-godot-game-dev/core-config.yaml +2. Or set markdownExploder to false in .bmad-godot-game-dev/config.yaml **IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**" If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should: -1. Set markdownExploder to true in .bmad-godot-game-dev/core-config.yaml +1. Set markdownExploder to true in .bmad-godot-game-dev/config.yaml 2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser` I will now proceed with the manual sharding process." diff --git a/expansion-packs/bmad-godot-game-dev/tasks/validate-game-story.md b/expansion-packs/bmad-godot-game-dev/tasks/validate-game-story.md index de94d6bc..38acf6a7 100644 --- a/expansion-packs/bmad-godot-game-dev/tasks/validate-game-story.md +++ b/expansion-packs/bmad-godot-game-dev/tasks/validate-game-story.md @@ -8,7 +8,7 @@ To comprehensively validate a Godot game development story draft before implemen ### 0. Load Core Configuration and Inputs -- Load `.bmad-godot-game-dev/core-config.yaml` from the project root +- Load `.bmad-godot-game-dev/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 validation." - Extract key configurations: `devStoryLocation`, `gdd.*`, `gamearchitecture.*`, `workflow.*` - Identify and load the following inputs: