bmad-method 5.1.3 → 6.0.0-alpha.1

package/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/ux-design-template.md

@@ -0,0 +1,145 @@
+# {{project_name}} UX Design Specification
+
+_Created on {{date}} by {{user_name}}_
+_Generated using BMad Method - Create UX Design Workflow v1.0_
+
+---
+
+## Executive Summary
+
+{{project_vision}}
+
+---
+
+## 1. Design System Foundation
+
+### 1.1 Design System Choice
+
+{{design_system_decision}}
+
+---
+
+## 2. Core User Experience
+
+### 2.1 Defining Experience
+
+{{core_experience}}
+
+### 2.2 Novel UX Patterns
+
+{{novel_ux_patterns}}
+
+---
+
+## 3. Visual Foundation
+
+### 3.1 Color System
+
+{{visual_foundation}}
+
+**Interactive Visualizations:**
+
+- Color Theme Explorer: [ux-color-themes.html](./ux-color-themes.html)
+
+---
+
+## 4. Design Direction
+
+### 4.1 Chosen Design Approach
+
+{{design_direction_decision}}
+
+**Interactive Mockups:**
+
+- Design Direction Showcase: [ux-design-directions.html](./ux-design-directions.html)
+
+---
+
+## 5. User Journey Flows
+
+### 5.1 Critical User Paths
+
+{{user_journey_flows}}
+
+---
+
+## 6. Component Library
+
+### 6.1 Component Strategy
+
+{{component_library_strategy}}
+
+---
+
+## 7. UX Pattern Decisions
+
+### 7.1 Consistency Rules
+
+{{ux_pattern_decisions}}
+
+---
+
+## 8. Responsive Design & Accessibility
+
+### 8.1 Responsive Strategy
+
+{{responsive_accessibility_strategy}}
+
+---
+
+## 9. Implementation Guidance
+
+### 9.1 Completion Summary
+
+{{completion_summary}}
+
+---
+
+## Appendix
+
+### Related Documents
+
+- Product Requirements: `{{prd_file}}`
+- Product Brief: `{{brief_file}}`
+- Brainstorming: `{{brainstorm_file}}`
+
+### Core Interactive Deliverables
+
+This UX Design Specification was created through visual collaboration:
+
+- **Color Theme Visualizer**: {{color_themes_html}}
+  - Interactive HTML showing all color theme options explored
+  - Live UI component examples in each theme
+  - Side-by-side comparison and semantic color usage
+
+- **Design Direction Mockups**: {{design_directions_html}}
+  - Interactive HTML with 6-8 complete design approaches
+  - Full-screen mockups of key screens
+  - Design philosophy and rationale for each direction
+
+### Optional Enhancement Deliverables
+
+_This section will be populated if additional UX artifacts are generated through follow-up workflows._
+
+<!-- Additional deliverables added here by other workflows -->
+
+### Next Steps & Follow-Up Workflows
+
+This UX Design Specification can serve as input to:
+
+- **Wireframe Generation Workflow** - Create detailed wireframes from user flows
+- **Figma Design Workflow** - Generate Figma files via MCP integration
+- **Interactive Prototype Workflow** - Build clickable HTML prototypes
+- **Component Showcase Workflow** - Create interactive component library
+- **AI Frontend Prompt Workflow** - Generate prompts for v0, Lovable, Bolt, etc.
+- **Solution Architecture Workflow** - Define technical architecture with UX context
+
+### Version History
+
+| Date     | Version | Changes                         | Author        |
+| -------- | ------- | ------------------------------- | ------------- |
+| {{date}} | 1.0     | Initial UX Design Specification | {{user_name}} |
+
+---
+
+_This UX Design Specification was created through collaborative design facilitation, not template generation. All decisions were made with user input and are documented with rationale._

package/src/modules/bmm/workflows/2-plan-workflows/create-ux-design/workflow.yaml

@@ -0,0 +1,42 @@
+# Create UX Design Workflow Configuration
+name: create-ux-design
+description: "Collaborative UX design facilitation workflow that creates exceptional user experiences through visual exploration and informed decision-making. Unlike template-driven approaches, this workflow facilitates discovery, generates visual options, and collaboratively designs the UX with the user at every step."
+author: "BMad"
+
+# Critical variables from config
+config_source: "{project-root}/bmad/bmm/config.yaml"
+output_folder: "{config_source}:output_folder"
+user_name: "{config_source}:user_name"
+communication_language: "{config_source}:communication_language"
+document_output_language: "{config_source}:document_output_language"
+user_skill_level: "{config_source}:user_skill_level"
+date: system-generated
+
+# Input requirements - We work from PRD, Brief, or Brainstorming docs
+recommended_inputs:
+  - prd: "Product Requirements Document with features and user journeys"
+  - product_brief: "Product brief with vision and target users"
+  - brainstorming: "Brainstorming documents with ideas and concepts"
+
+# Input file references (fuzzy matched from output folder)
+prd_file: "{output_folder}/bmm-PRD.md or PRD.md or product-requirements.md"
+brief_file: "{output_folder}/product-brief.md or brief.md or project-brief.md"
+brainstorm_file: "{output_folder}/brainstorming.md or brainstorm.md or ideation.md"
+
+# Module path and component files
+installed_path: "{project-root}/bmad/bmm/workflows/2-plan-workflows/create-ux-design"
+instructions: "{installed_path}/instructions.md"
+validation: "{installed_path}/checklist.md"
+template: "{installed_path}/ux-design-template.md"
+
+# Knowledge bases for intelligent UX decisions
+ux_pattern_catalog: "{installed_path}/ux-pattern-catalog.yaml"
+color_psychology: "{installed_path}/color-psychology.yaml"
+layout_patterns: "{installed_path}/layout-patterns.yaml"
+
+# Output configuration - Progressive saves throughout workflow
+default_output_file: "{output_folder}/ux-design-specification.md"
+color_themes_html: "{output_folder}/ux-color-themes.html"
+design_directions_html: "{output_folder}/ux-design-directions.html"
+
+standalone: true

package/src/modules/bmm/workflows/2-plan-workflows/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 and Context
+- Core Gameplay
+- Win/Loss Conditions
+- Progression and Balance
+- Level Design Framework
+- Art and 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 and Unlocks
+
+**rpg.md**:
+
+- Character System (stats, classes, leveling)
+- Inventory and Equipment
+- Quest System
+- World and Exploration
+- NPC and Dialogue
+- Combat System
+
+**puzzle.md**:
+
+- Core Puzzle Mechanics
+- Puzzle Progression
+- Level Structure
+- Player Assistance
+- Replayability
+
+**roguelike.md**:
+
+- Run Structure
+- Procedural Generation
+- Permadeath and Progression
+- Item and 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 and target audience
+   - Goals and context
+   - Core gameplay (pillars, loop, win/loss)
+   - Mechanics and controls
+   - Progression and balance
+   - Level design
+   - Art and audio
+   - Technical specs
+   - Epics and 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 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-workflows/gdd/checklist.md

@@ -0,0 +1,148 @@
+# GDD Workflow Validation Checklist
+
+**Purpose**: Validate GDD workflow outputs are complete, playable, and ready for solutioning.
+
+**Scope**: All game project levels (0-4)
+
+**Expected Outputs**: GDD.md, epics.md
+
+---
+
+## 1. Output Files Exist
+
+- [ ] GDD.md created in output folder
+- [ ] epics.md created in output folder (separate file)
+- [ ] bmm-workflow-status.md updated
+- [ ] No unfilled {{template_variables}}
+
+---
+
+## 2. Core Gameplay Definition (CRITICAL)
+
+### Game Pillars
+
+- [ ] **2-4 game pillars defined** (fundamental gameplay elements)
+- [ ] Each pillar is game-defining (not superficial)
+- [ ] Pillars are distinct (don't overlap)
+
+### Core Gameplay Loop
+
+- [ ] **Complete cycle documented** (what player does repeatedly)
+- [ ] Loop shows: player action → outcome → reward → motivation to repeat
+- [ ] Loop sounds compelling and repeatable
+
+### Win/Loss Conditions
+
+- [ ] Victory conditions clearly defined
+- [ ] Failure conditions defined (or N/A for sandbox games)
+- [ ] Conditions are testable
+
+---
+
+## 3. Game Mechanics and Systems
+
+### Mechanics
+
+- [ ] Primary mechanics described in detail
+- [ ] Mechanics support the game pillars
+- [ ] Player interaction with mechanics is clear
+
+### Progression
+
+- [ ] Player progression system defined (skill/power/unlock/narrative)
+- [ ] Difficulty curve explained
+- [ ] Progression feels rewarding
+
+### Platform and Controls
+
+- [ ] Target platforms specified
+- [ ] Control scheme appropriate for platforms
+- [ ] Input method clear (keyboard/gamepad/touch/etc.)
+
+---
+
+## 4. Story Quality (If epics.md exists)
+
+### Epic Structure
+
+- [ ] Epics represent deliverable game features
+- [ ] Epic sequence makes sense for game development
+- [ ] Stories show implementation path
+
+### Story Sequencing (If stories present)
+
+- [ ] **Vertical slices**: Each story delivers playable functionality
+- [ ] **Sequential ordering**: Stories build progressively
+- [ ] **No forward dependencies**: Each story builds on previous work only
+- [ ] Stories result in testable game features
+
+---
+
+## 5. Technical Specifications
+
+### Performance and Platform
+
+- [ ] Performance requirements specified (frame rate, resolution, etc.)
+- [ ] Platform-specific considerations noted
+- [ ] Asset requirements estimated
+
+### Production Scope
+
+- [ ] Art requirements realistic for project scale
+- [ ] Audio requirements documented
+- [ ] Scope matches project level and resources
+
+---
+
+## 6. Narrative Integration (If Applicable)
+
+**If narrative-design.md was generated:**
+
+- [ ] Narrative aligns with GDD game design
+- [ ] Story supports gameplay (not fighting it)
+- [ ] Tone consistent across GDD and narrative docs
+
+---
+
+## 7. Consistency
+
+- [ ] Epic titles match between GDD.md and epics.md
+- [ ] Game type identified and appropriate
+- [ ] Terminology consistent throughout
+- [ ] No contradictions between sections
+
+---
+
+## 8. Readiness for Solutioning
+
+- [ ] Sufficient detail for engine/platform selection
+- [ ] Game systems defined enough for technical architecture
+- [ ] Clear what needs to be built
+- [ ] Playable vision (reader can envision playing the game)
+
+---
+
+## 9. Critical Failures (Auto-Fail)
+
+- [ ] ❌ **No core gameplay loop** (can't be a game without this)
+- [ ] ❌ **No game pillars** (game-defining elements missing)
+- [ ] ❌ **No mechanics** (what does player actually DO?)
+- [ ] ❌ **No epics.md file** (implementation roadmap required)
+- [ ] ❌ **Engine/tech in GDD** (should defer to solutioning workflow)
+
+---
+
+## Validation Notes
+
+**Document any findings:**
+
+- Game concept strength: [Compelling / Interesting / Unclear / Weak]
+- Strengths:
+- Issues to address:
+- Recommended actions:
+
+**Ready for solutioning?** [Yes / No - explain]
+
+---
+
+_Adapt based on game type and narrative complexity. Core gameplay must always be solid._

package/src/modules/bmm/workflows/2-plan-workflows/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 and Unlocks
+
+{{player_abilities}}
+
+**Ability progression:**
+
+- Starting abilities
+- Unlockable abilities
+- Ability synergies
+- Upgrade paths

package/src/modules/bmm/workflows/2-plan-workflows/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 and 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