sjennings ccb64623bc
feat(bmgd): comprehensive BMGD module upgrade (#1151)
* feat(bmgd): comprehensive BMGD module upgrade

## New Agents
- **Game QA (GLaDOS)**: Game QA Architect + Test Automation Specialist
  - Engine-specific testing (Unity, Unreal, Godot)
  - Knowledge base with 15+ testing topics
  - Workflows: test-framework, test-design, automate, playtest-plan, performance-test, test-review

- **Game Solo Dev (Indie)**: Elite Indie Game Developer + Quick Flow Specialist
  - Rapid prototyping and iteration focused
  - Quick-flow workflows for solo/small team development

## Production Workflow Alignment
Aligned BMGD 4-production workflows with BMM 4-implementation:

### Removed Obsolete Workflows
- story-done (merged into dev-story)
- story-ready (merged into create-story)
- story-context (merged into create-story)
- epic-tech-context (no longer separate workflow)

### Added Workflows
- sprint-status: View sprint progress, surface risks, recommend next action

### Updated Workflows (now standalone, copied from BMM)
- code-review: Adversarial review with instructions.xml
- correct-course: Sprint change management
- create-story: Direct ready-for-dev marking
- dev-story: TDD implementation with instructions.xml
- retrospective: Epic completion review
- sprint-planning: Sprint status generation

## Game Testing Architecture (gametest/)
New knowledge base for game-specific testing:
- qa-index.csv: Knowledge fragment index
- 15 knowledge files covering:
  - Engine-specific: Unity, Unreal, Godot testing
  - Game-specific: Playtesting, balance, save systems, multiplayer
  - Platform: Certification (TRC/XR), localization, input
  - General QA: Automation, performance, regression, smoke tests

## Quick-Flow Workflows (bmgd-quick-flow/)
- quick-prototype: Rapid mechanic testing
- quick-dev: Flexible feature implementation

## Documentation
Complete documentation suite in docs/:
- README.md: Documentation index
- quick-start.md: Getting started guide
- agents-guide.md: All 6 agents reference
- workflows-guide.md: Complete workflow reference
- quick-flow-guide.md: Rapid development guide
- game-types-guide.md: 24 game type templates
- glossary.md: Game dev terminology
- troubleshooting.md: Common issues

## Teams & Installer
- Updated team-gamedev.yaml with all 6 agents and workflows
- Updated default-party.csv with Game QA and Game Solo Dev
- Created _module-installer/ with:
  - installer.js: Creates directories, logs engine selection
  - platform-specifics/: Claude Code and Windsurf handlers

## Agent Updates
All agents now reference standalone BMGD workflows:
- game-architect: correct-course → BMGD
- game-dev: dev-story, code-review → BMGD
- game-scrum-master: All production workflows → BMGD
- game-solo-dev: code-review → BMGD

## Module Configuration
- Added sprint_artifacts alias for workflow compatibility
- All workflows use bmgd/config.yaml

* fix(bmgd): update sprint-status workflow to reference bmgd instead of bmm

Replace all /bmad:bmm:workflows references with /bmad:bmgd:workflows
in the sprint-status workflow instructions.

* feat(bmgd): add workflow-status and create-tech-spec workflows

Add BMGD-native workflow-status and create-tech-spec workflows,
replacing all BMM references with BMGD paths.

## New Workflows

### workflow-status
- Multi-mode status checker for game projects
- Game-specific project levels (Game Jam → AAA)
- Workflow paths: gamedev-greenfield, gamedev-brownfield,
  quickflow-greenfield, quickflow-brownfield
- Init workflow for new game project setup

### create-tech-spec
- Game-focused spec engineering workflow
- Engine-aware (Unity/Unreal/Godot)
- Performance and gameplay feel considerations

## Agent Updates
Updated all BMGD agents to reference BMGD workflows:
- game-architect, game-designer, game-dev, game-qa,
  game-scrum-master, game-solo-dev

All agents now use /bmad:bmgd:workflows instead of /bmad:bmm:workflows

* fix(bmgd): address PR review findings and enhance playtesting docs

## PR Review Fixes (F1-F20)

### Configuration & Naming
- F1: Changed user_skill_level to game_dev_experience in module.yaml
- F3: Renamed gametest/framework to gametest/test-framework

### Cleanup
- F2: Deleted 4 orphaned root-level template files
- F6: Removed duplicate code block in create-story/instructions.xml
- F9: Removed trailing empty line from qa-index.csv
- F20: Deleted orphaned docs/unnamed.jpg

### Installer Improvements
- F7: Simplified platform handler stubs (removed unused code)
- F8: Added return value checking for platform handlers
- F13: Added path traversal validation (isWithinProjectRoot)
- F18: Added type validation for config string values

### Agent Fixes
- F10: Added workflow-status and advanced-elicitation to game-solo-dev
- F12: Fixed "GOTO step 2a" → "GOTO step 2" references
- F14: Removed duplicate project-context.md from principles in 5 agents

### Workflow Updates
- F17: Added input_file_patterns to playtest-plan workflow

### Documentation
- F4-F5: Updated quick-start.md with 6 agents and fixed table
- Updated workflows-guide.md with test-framework reference

### Knowledge Base Updates (from earlier CodeRabbit comments)
- Updated unity-testing.md to Test Framework 1.6.0
- Fixed unreal-testing.md (MarkAsGarbage, UnrealEditor.exe)
- Added FVerifyPlayerMoved note to smoke-testing.md
- Fixed certification-testing.md table formatting

### Playtesting Documentation Enhancement
- Added "Playtesting by Game Type" section (7 genres)
- Added "Processing Feedback Effectively" section
- Expanded from ~138 to ~340 lines

* refactor(bmgd): use exec for step-file workflows and multi format

Update agent menu items to use correct notation for step-file workflows:

**game-designer.agent.yaml:**
- Convert 4 step-file workflows to multi format with shortcodes:
  - [BG] brainstorm-game
  - [GB] create-game-brief
  - [GDD] create-gdd
  - [ND] narrative
- Changed from workflow: .yaml to exec: .md

**game-architect.agent.yaml:**
- Changed create-architecture from workflow: to exec: with workflow.md

---------

Co-authored-by: Scott Jennings <scott.jennings+CIGINT@cloudimperiumgames.com>
2025-12-17 14:33:22 +08:00

5.8 KiB

name description workflow_path thisStepFile continueStepFile nextStepFile workflowFile outputFile templateFile
step-01-init Initialize narrative workflow, load GDD context, and assess narrative complexity {project-root}/_bmad/bmgd/workflows/2-design/narrative {workflow_path}/steps/step-01-init.md {workflow_path}/steps/step-01b-continue.md {workflow_path}/steps/step-02-foundation.md {workflow_path}/workflow.md {output_folder}/narrative-design.md {workflow_path}/templates/narrative-template.md

Step 1: Initialize Narrative Workflow

Progress: Step 1 of 11 - Next: Story Foundation

STEP GOAL:

Validate workflow readiness, check for existing narrative document, load GDD context, and assess the appropriate level of narrative complexity for this game.

MANDATORY EXECUTION RULES (READ FIRST):

Universal Rules:

  • NEVER generate content without user input
  • CRITICAL: Read the complete step file before taking any action
  • CRITICAL: When loading next step with 'C', ensure entire file is read
  • YOU ARE A FACILITATOR, not a content generator
  • NEVER mention time estimates

Role Reinforcement:

  • You are a narrative design facilitator
  • Help users craft THEIR story, not yours
  • Narrative complexity should match the game

Step-Specific Rules:

  • Check for existing narrative before starting fresh
  • Load GDD to understand game context
  • Let user confirm narrative complexity level

EXECUTION PROTOCOLS:

  • Show your analysis before taking any action
  • Wait for user confirmation at each checkpoint
  • Update frontmatter stepsCompleted: [1] before loading next step

Sequence of Instructions (Do not deviate, skip, or optimize)

1. Check Workflow Status

Search for workflow status file:

Check if {output_folder}/bmgd-workflow-status.yaml exists.

If status file found:

  • Load and parse workflow_status section
  • Check status of "narrative" workflow
  • Determine if this is the expected next workflow

Handle scenarios:

  • If already completed: Ask about overwriting
  • If out of sequence: Warn and confirm continuation
  • Set standalone_mode appropriately

2. Check for Existing Narrative

Search for existing narrative document:

Look for existing narrative files in {output_folder}:

  • *narrative*.md
  • *story*.md

If existing narrative found:

"I found an existing narrative document: {{existing_file}}

Options:

  1. Continue - Resume from where you left off
  2. Start Fresh - Begin a new narrative (will overwrite)
  3. Review - Let me review the existing document first

Which would you like to do?"

Handle selection:

  • If Continue: Load {continueStepFile}
  • If Start Fresh: Continue with step 3
  • If Review: Show document summary

3. Load GDD Context

Search for GDD:

Look for GDD files using patterns:

  • {output_folder}/*gdd*.md
  • {output_folder}/*game-design*.md

If GDD not found:

"Note: GDD Not Found

The Narrative workflow works best with a completed GDD.

Options:

  1. Continue without GDD (I'll ask more questions)
  2. Run GDD workflow first: create-gdd

Your choice:"

If GDD found:

Load and extract:

  • game_type
  • game_name
  • Any existing narrative mentions
  • Core mechanics and themes

4. Assess Narrative Complexity

"Narrative Complexity Assessment

Let's determine the right depth for your narrative design.

Narrative Complexity Levels:

Level Description Examples
Critical Story IS the game Visual Novel, Text Adventure
Heavy Story drives experience Story RPG, Narrative Adventure
Moderate Story enhances gameplay Metroidvania, Horror, Tactics
Light Story provides context Most action, puzzle, arcade

Based on {{game_type}}, I'd suggest: {{suggested_complexity}}

What level of narrative complexity does {{game_name}} have?"

5. Validate Complexity Choice

If user selects Light:

"Light narrative games usually don't need a full Narrative Design Document.

Your options:

  1. Proceed anyway - Create full narrative document
  2. Quick narrative - Just the essentials (premise, setting, key characters)
  3. Expand GDD - Add narrative sections to existing GDD instead

What would you like to do?"

Handle selection appropriately.

6. Initialize Output Document

If proceeding with full narrative:

Create {outputFile} with frontmatter:

---
title: 'Narrative Design Document'
project: '{{game_name}}'
date: '{{date}}'
author: '{{user_name}}'
version: '1.0'
stepsCompleted: [1]
status: 'in-progress'
narrativeComplexity: '{{selected_complexity}}'
gdd: '{{gdd_file}}'
---

# Narrative Design Document

## {{game_name}}

### Document Status

This narrative document is being created through the BMGD Narrative Workflow.

**Narrative Complexity:** {{selected_complexity}}
**Steps Completed:** 1 of 11 (Initialize)

---

_Content will be added as we progress through the workflow._

7. Proceed to Foundation Step

After initialization:

  • Update frontmatter: stepsCompleted: [1]
  • Load {nextStepFile}

SYSTEM SUCCESS/FAILURE METRICS

SUCCESS:

  • Workflow status checked appropriately
  • Existing narrative check performed
  • GDD loaded and analyzed (if available)
  • Narrative complexity assessed with user
  • Output document initialized with proper frontmatter
  • Frontmatter updated with stepsCompleted: [1]

SYSTEM FAILURE:

  • Starting without complexity assessment
  • Not checking for existing narrative
  • Proceeding without user confirmation
  • Missing frontmatter initialization

Master Rule: Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.