bmad-method 5.1.2 → 6.0.0-alpha.0

package/src/modules/bmm/workflows/2-plan/gdd/README.md

@@ -0,0 +1,222 @@
+# Game Design Document (GDD) Workflow
+
+This folder contains the GDD workflow for game projects, replacing the traditional PRD approach with game-specific documentation.
+
+## Overview
+
+The GDD workflow creates a comprehensive Game Design Document that captures:
+
+- Core gameplay mechanics and pillars
+- Game type-specific elements (RPG systems, platformer movement, puzzle mechanics, etc.)
+- Level design framework
+- Art and audio direction
+- Technical specifications (platform-agnostic)
+- Development epics
+
+## Architecture
+
+### Universal Template
+
+`gdd-template.md` contains sections common to ALL game types:
+
+- Executive Summary
+- Goals & Context
+- Core Gameplay
+- Win/Loss Conditions
+- Progression & Balance
+- Level Design Framework
+- Art & Audio Direction
+- Technical Specs
+- Development Epics
+- Success Metrics
+
+### Game-Type-Specific Injection
+
+The template includes a `{{GAME_TYPE_SPECIFIC_SECTIONS}}` placeholder that gets replaced with game-type-specific content.
+
+### Game Types Registry
+
+`game-types.csv` defines 24+ game types with:
+
+- **id**: Unique identifier (e.g., `action-platformer`, `rpg`, `roguelike`)
+- **name**: Human-readable name
+- **description**: Brief description of the game type
+- **genre_tags**: Searchable tags
+- **fragment_file**: Path to type-specific template fragment
+
+### Game-Type Fragments
+
+Located in `game-types/` folder, these markdown files contain sections specific to each game type:
+
+**action-platformer.md**:
+
+- Movement System (jump mechanics, air control, special moves)
+- Combat System (attack types, combos, enemy AI)
+- Level Design Patterns (platforming challenges, combat arenas)
+- Player Abilities & Unlocks
+
+**rpg.md**:
+
+- Character System (stats, classes, leveling)
+- Inventory & Equipment
+- Quest System
+- World & Exploration
+- NPC & Dialogue
+- Combat System
+
+**puzzle.md**:
+
+- Core Puzzle Mechanics
+- Puzzle Progression
+- Level Structure
+- Player Assistance
+- Replayability
+
+**roguelike.md**:
+
+- Run Structure
+- Procedural Generation
+- Permadeath & Progression
+- Item & Upgrade System
+- Character Selection
+- Difficulty Modifiers
+
+...and 20+ more game types!
+
+## Workflow Flow
+
+1. **Router Detection** (instructions-router.md):
+   - Step 3 asks for project type
+   - If "Game" selected → sets `workflow_type = "gdd"`
+   - Skips standard level classification
+   - Jumps to GDD-specific assessment
+
+2. **Game Type Selection** (instructions-gdd.md Step 1):
+   - Presents 9 common game types + "Other"
+   - Maps selection to `game-types.csv`
+   - Loads corresponding fragment file
+   - Stores `game_type` for injection
+
+3. **Universal GDD Sections** (Steps 2-5, 7-13):
+   - Platform & target audience
+   - Goals & context
+   - Core gameplay (pillars, loop, win/loss)
+   - Mechanics & controls
+   - Progression & balance
+   - Level design
+   - Art & audio
+   - Technical specs
+   - Epics & metrics
+
+4. **Game-Type Injection** (Step 6):
+   - Loads fragment from `game-types/{game_type}.md`
+   - For each `{{placeholder}}` in fragment, elicits details
+   - Injects completed sections into `{{GAME_TYPE_SPECIFIC_SECTIONS}}`
+
+5. **Solutioning Handoff** (Step 14):
+   - Routes to `3-solutioning` workflow
+   - Platform/engine specifics handled by solutioning registry
+   - Game-\* entries in solutioning `registry.csv` provide engine-specific guidance
+
+## Platform vs. Game Type Separation
+
+**GDD (this workflow)**: Game-type specifics
+
+- What makes an RPG an RPG (stats, quests, inventory)
+- What makes a platformer a platformer (jump mechanics, level design)
+- Genre-defining mechanics and systems
+
+**Solutioning (3-solutioning workflow)**: Platform/engine specifics
+
+- Unity vs. Godot vs. Phaser vs. Unreal
+- 2D vs. 3D rendering
+- Physics engines
+- Input systems
+- Platform constraints (mobile, web, console)
+
+This separation allows:
+
+- Single universal GDD regardless of platform
+- Platform decisions made during architecture phase
+- Easy platform pivots without rewriting GDD
+
+## Output
+
+**GDD.md**: Complete game design document with:
+
+- All universal sections filled
+- Game-type-specific sections injected
+- Ready for solutioning handoff
+
+## Example Game Types
+
+| ID                | Name              | Key Sections                                      |
+| ----------------- | ----------------- | ------------------------------------------------- |
+| action-platformer | Action Platformer | Movement, Combat, Level Patterns, Abilities       |
+| rpg               | RPG               | Character System, Inventory, Quests, World, NPCs  |
+| puzzle            | Puzzle            | Puzzle Mechanics, Progression, Level Structure    |
+| roguelike         | Roguelike         | Run Structure, Procgen, Permadeath, Items         |
+| shooter           | Shooter           | Weapon Systems, Enemy AI, Arena Design            |
+| strategy          | Strategy          | Resources, Units, AI, Victory Conditions          |
+| metroidvania      | Metroidvania      | Interconnected World, Ability Gating, Exploration |
+| visual-novel      | Visual Novel      | Branching Story, Dialogue Trees, Choices          |
+| tower-defense     | Tower Defense     | Waves, Tower Types, Placement, Economy            |
+| card-game         | Card Game         | Deck Building, Card Mechanics, Turn System        |
+
+...and 14+ more!
+
+## Adding New Game Types
+
+1. Add row to `game-types.csv`:
+
+   ```csv
+   new-type,New Type Name,"Description",tags,new-type.md
+   ```
+
+2. Create `game-types/new-type.md`:
+
+   ```markdown
+   ## New Type Specific Elements
+
+   ### System Name
+
+   {{system_placeholder}}
+
+   **Details:**
+
+   - Element 1
+   - Element 2
+   ```
+
+3. The workflow automatically uses it!
+
+## Integration with Solutioning
+
+When a game project completes the GDD and moves to solutioning:
+
+1. Solutioning workflow reads `project_type == "game"`
+2. Loads GDD.md instead of PRD.md
+3. Matches game platforms to solutioning `registry.csv` game-\* entries
+4. Provides engine-specific guidance (Unity, Godot, Phaser, etc.)
+5. Generates solution-architecture.md with platform decisions
+6. Creates per-epic tech specs
+
+Example solutioning registry entries:
+
+- `game-unity-2d`: Unity 2D games
+- `game-godot-3d`: Godot 3D games
+- `game-phaser`: Phaser web games
+- `game-unreal-3d`: Unreal Engine games
+- `game-custom-3d-rust`: Custom Rust game engines
+
+## Philosophy
+
+**Game projects are fundamentally different from software products**:
+
+- Gameplay feel > feature lists
+- Playtesting > user testing
+- Game pillars > product goals
+- Mechanics > requirements
+- Fun > utility
+
+The GDD workflow respects these differences while maintaining BMAD Method rigor.

package/src/modules/bmm/workflows/2-plan/gdd/game-types/action-platformer.md

@@ -0,0 +1,45 @@
+## Action Platformer Specific Elements
+
+### Movement System
+
+{{movement_mechanics}}
+
+**Core movement abilities:**
+
+- Jump mechanics (height, air control, coyote time)
+- Running/walking speed
+- Special movement (dash, wall-jump, double-jump, etc.)
+
+### Combat System
+
+{{combat_system}}
+
+**Combat mechanics:**
+
+- Attack types (melee, ranged, special)
+- Combo system
+- Enemy AI behavior patterns
+- Hit feedback and impact
+
+### Level Design Patterns
+
+{{level_design_patterns}}
+
+**Level structure:**
+
+- Platforming challenges
+- Combat arenas
+- Secret areas and collectibles
+- Checkpoint placement
+- Difficulty spikes and pacing
+
+### Player Abilities & Unlocks
+
+{{player_abilities}}
+
+**Ability progression:**
+
+- Starting abilities
+- Unlockable abilities
+- Ability synergies
+- Upgrade paths

package/src/modules/bmm/workflows/2-plan/gdd/game-types/adventure.md

@@ -0,0 +1,84 @@
+## Adventure Specific Elements
+
+<narrative-workflow-recommended>
+This game type is **narrative-heavy**. Consider running the Narrative Design workflow after completing the GDD to create:
+- Detailed story structure and beats
+- Character profiles and arcs
+- World lore and history
+- Dialogue framework
+- Environmental storytelling
+</narrative-workflow-recommended>
+
+### Exploration Mechanics
+
+{{exploration_mechanics}}
+
+**Exploration design:**
+
+- World structure (linear, open, hub-based, interconnected)
+- Movement and traversal
+- Observation and inspection mechanics
+- Discovery rewards (story reveals, items, secrets)
+- Pacing of exploration vs. story
+
+### Story Integration
+
+{{story_integration}}
+
+**Narrative gameplay:**
+
+- Story delivery methods (cutscenes, in-game, environmental)
+- Player agency in story (linear, branching, player-driven)
+- Story pacing (acts, beats, tension/release)
+- Character introduction and development
+- Climax and resolution structure
+
+**Note:** Detailed story elements (plot, characters, lore) belong in the Narrative Design Document.
+
+### Puzzle Systems
+
+{{puzzle_systems}}
+
+**Puzzle integration:**
+
+- Puzzle types (inventory, logic, environmental, dialogue)
+- Puzzle difficulty curve
+- Hint systems
+- Puzzle-story connection (narrative purpose)
+- Optional vs. required puzzles
+
+### Character Interaction
+
+{{character_interaction}}
+
+**NPC systems:**
+
+- Dialogue system (branching, linear, choice-based)
+- Character relationships
+- NPC schedules/behaviors
+- Companion mechanics (if applicable)
+- Memorable character moments
+
+### Inventory & Items
+
+{{inventory_items}}
+
+**Item systems:**
+
+- Inventory scope (key items, collectibles, consumables)
+- Item examination/description
+- Combination/crafting (if applicable)
+- Story-critical items vs. optional items
+- Item-based progression gates
+
+### Environmental Storytelling
+
+{{environmental_storytelling}}
+
+**World narrative:**
+
+- Visual storytelling techniques
+- Audio atmosphere
+- Readable documents (journals, notes, signs)
+- Environmental clues
+- Show vs. tell balance

package/src/modules/bmm/workflows/2-plan/gdd/game-types/card-game.md

@@ -0,0 +1,76 @@
+## Card Game Specific Elements
+
+### Card Types & Effects
+
+{{card_types}}
+
+**Card design:**
+
+- Card categories (creatures, spells, enchantments, etc.)
+- Card rarity tiers (common, rare, epic, legendary)
+- Card attributes (cost, power, health, etc.)
+- Effect types (damage, healing, draw, control, etc.)
+- Keywords and abilities
+- Card synergies
+
+### Deck Building
+
+{{deck_building}}
+
+**Deck construction:**
+
+- Deck size limits (minimum, maximum)
+- Card quantity limits (e.g., max 2 copies)
+- Class/faction restrictions
+- Deck archetypes (aggro, control, combo, midrange)
+- Sideboard mechanics (if applicable)
+- Pre-built vs. custom decks
+
+### Mana/Resource System
+
+{{mana_resources}}
+
+**Resource mechanics:**
+
+- Mana generation (per turn, from cards, etc.)
+- Mana curve design
+- Resource types (colored mana, energy, etc.)
+- Ramp mechanics
+- Resource denial strategies
+
+### Turn Structure
+
+{{turn_structure}}
+
+**Game flow:**
+
+- Turn phases (draw, main, combat, end)
+- Priority and response windows
+- Simultaneous vs. alternating turns
+- Time limits per turn
+- Match length targets
+
+### Card Collection & Progression
+
+{{collection_progression}}
+
+**Player progression:**
+
+- Card acquisition (packs, rewards, crafting)
+- Deck unlocks
+- Currency systems (gold, dust, wildcards)
+- Free-to-play balance
+- Collection completion incentives
+
+### Game Modes
+
+{{game_modes}}
+
+**Mode variety:**
+
+- Ranked ladder
+- Draft/Arena modes
+- Campaign/story mode
+- Casual/unranked
+- Special event modes
+- Tournament formats

package/src/modules/bmm/workflows/2-plan/gdd/game-types/fighting.md

@@ -0,0 +1,89 @@
+## Fighting Game Specific Elements
+
+### Character Roster
+
+{{character_roster}}
+
+**Fighter design:**
+
+- Roster size (launch + planned DLC)
+- Character archetypes (rushdown, zoner, grappler, all-rounder, etc.)
+- Move list diversity
+- Complexity tiers (beginner vs. expert characters)
+- Balance philosophy (everyone viable vs. tier system)
+
+### Move Lists & Frame Data
+
+{{moves_frame_data}}
+
+**Combat mechanics:**
+
+- Normal moves (light, medium, heavy)
+- Special moves (quarter-circle, charge, etc.)
+- Super/ultimate moves
+- Frame data (startup, active, recovery, advantage)
+- Hit/hurt boxes
+- Command inputs vs. simplified inputs
+
+### Combo System
+
+{{combo_system}}
+
+**Combo design:**
+
+- Combo structure (links, cancels, chains)
+- Juggle system
+- Wall/ground bounces
+- Combo scaling
+- Reset opportunities
+- Optimal vs. practical combos
+
+### Defensive Mechanics
+
+{{defensive_mechanics}}
+
+**Defense options:**
+
+- Blocking (high, low, crossup protection)
+- Dodging/rolling/backdashing
+- Parries/counters
+- Pushblock/advancing guard
+- Invincibility frames
+- Escape options (burst, breaker, etc.)
+
+### Stage Design
+
+{{stage_design}}
+
+**Arena design:**
+
+- Stage size and boundaries
+- Wall mechanics (wall combos, wall break)
+- Interactive elements
+- Ring-out mechanics (if applicable)
+- Visual clarity vs. aesthetics
+
+### Single Player Modes
+
+{{single_player}}
+
+**Offline content:**
+
+- Arcade/story mode
+- Training mode features
+- Mission/challenge mode
+- Boss fights
+- Unlockables
+
+### Competitive Features
+
+{{competitive_features}}
+
+**Tournament-ready:**
+
+- Ranked matchmaking
+- Lobby systems
+- Replay features
+- Frame delay/rollback netcode
+- Spectator mode
+- Tournament mode

package/src/modules/bmm/workflows/2-plan/gdd/game-types/horror.md

@@ -0,0 +1,86 @@
+## Horror Game Specific Elements
+
+<narrative-workflow-recommended>
+This game type is **narrative-important**. Consider running the Narrative Design workflow after completing the GDD to create:
+- Detailed story structure and scares
+- Character backstories and motivations
+- World lore and mythology
+- Environmental storytelling
+- Tension pacing and narrative beats
+</narrative-workflow-recommended>
+
+### Atmosphere & Tension Building
+
+{{atmosphere}}
+
+**Horror atmosphere:**
+
+- Visual design (lighting, shadows, color palette)
+- Audio design (soundscape, silence, music cues)
+- Environmental storytelling
+- Pacing of tension and release
+- Jump scares vs. psychological horror
+- Safe zones vs. danger zones
+
+### Fear Mechanics
+
+{{fear_mechanics}}
+
+**Core horror systems:**
+
+- Visibility/darkness mechanics
+- Limited resources (ammo, health, light)
+- Vulnerability (combat avoidance, hiding)
+- Sanity/fear meter (if applicable)
+- Pursuer/stalker mechanics
+- Detection systems (line of sight, sound)
+
+### Enemy/Threat Design
+
+{{enemy_threat}}
+
+**Threat systems:**
+
+- Enemy types (stalker, environmental, psychological)
+- Enemy behavior (patrol, hunt, ambush)
+- Telegraphing and tells
+- Invincible vs. killable enemies
+- Boss encounters
+- Encounter frequency and pacing
+
+### Resource Scarcity
+
+{{resource_scarcity}}
+
+**Limited resources:**
+
+- Ammo/weapon durability
+- Health items
+- Light sources (batteries, fuel)
+- Save points (if limited)
+- Inventory constraints
+- Risk vs. reward of exploration
+
+### Safe Zones & Respite
+
+{{safe_zones}}
+
+**Tension management:**
+
+- Safe room design
+- Save point placement
+- Temporary refuge mechanics
+- Calm before storm pacing
+- Item management areas
+
+### Puzzle Integration
+
+{{puzzles}}
+
+**Environmental puzzles:**
+
+- Puzzle types (locks, codes, environmental)
+- Difficulty balance (accessibility vs. challenge)
+- Hint systems
+- Puzzle-tension balance
+- Narrative purpose of puzzles

package/src/modules/bmm/workflows/2-plan/gdd/game-types/idle-incremental.md

@@ -0,0 +1,78 @@
+## Idle/Incremental Game Specific Elements
+
+### Core Click/Interaction
+
+{{core_interaction}}
+
+**Primary mechanic:**
+
+- Click action (what happens on click)
+- Click value progression
+- Auto-click mechanics
+- Combo/streak systems (if applicable)
+- Satisfaction and feedback (visual, audio)
+
+### Upgrade Trees
+
+{{upgrade_trees}}
+
+**Upgrade systems:**
+
+- Upgrade categories (click power, auto-generation, multipliers)
+- Upgrade costs and scaling
+- Unlock conditions
+- Synergies between upgrades
+- Upgrade branches and choices
+- Meta-upgrades (affect future runs)
+
+### Automation Systems
+
+{{automation}}
+
+**Passive mechanics:**
+
+- Auto-clicker unlocks
+- Manager/worker systems
+- Multiplier stacking
+- Offline progression
+- Automation tiers
+- Balance between active and idle play
+
+### Prestige & Reset Mechanics
+
+{{prestige_reset}}
+
+**Long-term progression:**
+
+- Prestige conditions (when to reset)
+- Persistent bonuses after reset
+- Prestige currency
+- Multiple prestige layers (if applicable)
+- Scaling between runs
+- Endgame infinite scaling
+
+### Number Balancing
+
+{{number_balancing}}
+
+**Economy design:**
+
+- Exponential growth curves
+- Notation systems (K, M, B, T or scientific)
+- Soft caps and plateaus
+- Time gates
+- Pacing of progression
+- Wall breaking mechanics
+
+### Meta-Progression
+
+{{meta_progression}}
+
+**Long-term engagement:**
+
+- Achievement system
+- Collectibles
+- Alternate game modes
+- Seasonal content
+- Challenge runs
+- Endgame goals