mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-01-30 04:32:02 +00:00
gitignore ide installs settings and removed gamedev doc reference
This commit is contained in:
Brian Madison
@@ -1,219 +0,0 @@
|
||||
---
|
||||
title: "BMGD Troubleshooting"
|
||||
---
|
||||
|
||||
Use this guide to resolve common issues when using BMGD workflows.
|
||||
|
||||
## Installation Issues
|
||||
|
||||
### BMGD module not appearing
|
||||
|
||||
**Symptom:** BMGD agents and workflows are not available after installation.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Verify BMGD was selected during installation
|
||||
2. Check `_bmad/bmgd/` folder exists in your project
|
||||
3. Re-run installer with `--add-module bmgd`
|
||||
|
||||
### Config file missing
|
||||
|
||||
**Symptom:** Workflows fail with "config not found" errors.
|
||||
|
||||
**Solution:**
|
||||
Check for `_bmad/bmgd/config.yaml` in your project. If missing, create it:
|
||||
|
||||
```yaml
|
||||
output_folder: '{project-root}/docs/game-design'
|
||||
user_name: 'Your Name'
|
||||
communication_language: 'English'
|
||||
document_output_language: 'English'
|
||||
game_dev_experience: 'intermediate'
|
||||
```
|
||||
|
||||
## Workflow Issues
|
||||
|
||||
### "GDD not found" in Narrative workflow
|
||||
|
||||
**Symptom:** Narrative workflow can't find the GDD.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Ensure GDD exists in `{output_folder}`
|
||||
2. Check GDD filename contains "gdd" (e.g., `game-gdd.md`, `my-gdd.md`)
|
||||
3. If using sharded GDD, verify `{output_folder}/gdd/index.md` exists
|
||||
|
||||
### Workflow state not persisting
|
||||
|
||||
**Symptom:** Returning to a workflow starts from the beginning.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Check the output document's frontmatter for `stepsCompleted` array
|
||||
2. Ensure document was saved before ending session
|
||||
3. Use "Continue existing" option when re-entering workflow
|
||||
|
||||
### Wrong game type sections in GDD
|
||||
|
||||
**Symptom:** GDD includes irrelevant sections for your game type.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Review game type selection at Step 7 of GDD workflow
|
||||
2. You can select multiple types for hybrid games
|
||||
3. Irrelevant sections can be marked N/A or removed
|
||||
|
||||
## Agent Issues
|
||||
|
||||
### Agent not recognizing commands
|
||||
|
||||
**Symptom:** Typing a command like `create-gdd` doesn't trigger the workflow.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Ensure you're chatting with the correct agent (Game Designer for GDD)
|
||||
2. Check exact command spelling (case-sensitive)
|
||||
3. Try `workflow-status` to verify agent is loaded correctly
|
||||
|
||||
### Agent using wrong persona
|
||||
|
||||
**Symptom:** Agent responses don't match expected personality.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Verify correct agent file is loaded
|
||||
2. Check `_bmad/bmgd/agents/` for agent definitions
|
||||
3. Start a fresh chat session with the correct agent
|
||||
|
||||
## Document Issues
|
||||
|
||||
### Document too large for context
|
||||
|
||||
**Symptom:** AI can't process the entire GDD or narrative document.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Use sharded document structure (index.md + section files)
|
||||
2. Request specific sections rather than full document
|
||||
3. GDD workflow supports automatic sharding for large documents
|
||||
|
||||
### Template placeholders not replaced
|
||||
|
||||
**Symptom:** Output contains `{{placeholder}}` text.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Workflow may have been interrupted before completion
|
||||
2. Re-run the specific step that generates that section
|
||||
3. Manually edit the document to fill in missing values
|
||||
|
||||
### Frontmatter parsing errors
|
||||
|
||||
**Symptom:** YAML errors when loading documents.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Validate YAML syntax (proper indentation, quotes around special characters)
|
||||
2. Check for tabs vs spaces (YAML requires spaces)
|
||||
3. Ensure frontmatter is bounded by `---` markers
|
||||
|
||||
## Phase 4 (Production) Issues
|
||||
|
||||
### Sprint status not updating
|
||||
|
||||
**Symptom:** Story status changes don't reflect in sprint-status.yaml.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Run `sprint-planning` to refresh status
|
||||
2. Check file permissions on sprint-status.yaml
|
||||
3. Verify workflow-install files exist in `_bmad/bmgd/workflows/4-production/`
|
||||
|
||||
### Story context missing code references
|
||||
|
||||
**Symptom:** Generated story context doesn't include relevant code.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Ensure project-context.md exists and is current
|
||||
2. Check that architecture document references correct file paths
|
||||
3. Story may need more specific file references in acceptance criteria
|
||||
|
||||
### Code review not finding issues
|
||||
|
||||
**Symptom:** Code review passes but bugs exist.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Code review is AI-assisted, not comprehensive testing
|
||||
2. Always run actual tests before marking story done
|
||||
3. Consider manual review for critical code paths
|
||||
|
||||
## Performance Issues
|
||||
|
||||
### Workflows running slowly
|
||||
|
||||
**Symptom:** Long wait times between workflow steps.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Use IDE-based workflows (faster than web)
|
||||
2. Keep documents concise (avoid unnecessary detail)
|
||||
3. Use sharded documents for large projects
|
||||
|
||||
### Context limit reached mid-workflow
|
||||
|
||||
**Symptom:** Workflow stops or loses context partway through.
|
||||
|
||||
**Solutions:**
|
||||
|
||||
1. Save progress frequently (workflows auto-save on Continue)
|
||||
2. Break complex sections into multiple sessions
|
||||
3. Use step-file architecture (workflows resume from last step)
|
||||
|
||||
## Common Error Messages
|
||||
|
||||
### "Input file not found"
|
||||
|
||||
**Cause:** Workflow requires a document that doesn't exist.
|
||||
|
||||
**Fix:** Complete prerequisite workflow first (e.g., Game Brief before GDD).
|
||||
|
||||
### "Invalid game type"
|
||||
|
||||
**Cause:** Selected game type not in supported list.
|
||||
|
||||
**Fix:** Check `game-types.csv` for valid type IDs.
|
||||
|
||||
### "Validation failed"
|
||||
|
||||
**Cause:** Document doesn't meet checklist requirements.
|
||||
|
||||
**Fix:** Review the validation output and address flagged items.
|
||||
|
||||
## Getting Help
|
||||
|
||||
### Community Support
|
||||
|
||||
- **[Discord Community](https://discord.gg/gk8jAdXWmj)** - Real-time help from the community
|
||||
- **[GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)** - Report bugs or request features
|
||||
|
||||
### Self-Help
|
||||
|
||||
1. Check `workflow-status` to understand current state
|
||||
2. Review workflow markdown files for expected behavior
|
||||
3. Look at completed example documents in the module
|
||||
|
||||
### Reporting Issues
|
||||
|
||||
When reporting issues, include:
|
||||
|
||||
1. Which workflow and step
|
||||
2. Error message (if any)
|
||||
3. Relevant document frontmatter
|
||||
4. Steps to reproduce
|
||||
|
||||
## Next Steps
|
||||
|
||||
- **[Workflows Guide](/docs/reference/workflows/index.md)** - Workflow reference
|
||||
- **[Glossary](/docs/reference/glossary/index.md)** - Terminology
|
||||
@@ -1,368 +0,0 @@
|
||||
---
|
||||
title: "BMGD Workflows Guide"
|
||||
---
|
||||
|
||||
Complete reference for all BMGD workflows organized by development phase.
|
||||
|
||||
## Overview
|
||||
|
||||
BMGD workflows are organized into four phases:
|
||||
|
||||
|
||||
|
||||
## Phase 1: Preproduction
|
||||
|
||||
### Brainstorm Game
|
||||
|
||||
**Command:** `brainstorm-game`
|
||||
**Agent:** Game Designer
|
||||
**Input:** None required
|
||||
**Output:** Ideas and concepts (optionally saved)
|
||||
|
||||
Guided ideation session using game-specific brainstorming techniques:
|
||||
|
||||
- **MDA Framework** — Mechanics → Dynamics → Aesthetics analysis
|
||||
- **Core Loop Workshop** — Define the fundamental gameplay loop
|
||||
- **Player Fantasy Mining** — Explore what players want to feel
|
||||
- **Genre Mashup** — Combine genres for unique concepts
|
||||
|
||||
**Steps:**
|
||||
1. Initialize brainstorm session
|
||||
2. Load game-specific techniques
|
||||
3. Execute ideation with selected techniques
|
||||
4. Summarize and (optionally) hand off to Game Brief
|
||||
|
||||
### Game Brief
|
||||
|
||||
**Command:** `create-game-brief`
|
||||
**Agent:** Game Designer
|
||||
**Input:** Ideas from brainstorming (optional)
|
||||
**Output:** `{output_folder}/game-brief.md`
|
||||
|
||||
Captures your game's core vision and fundamentals. Foundation for all subsequent design work.
|
||||
|
||||
**Sections covered:**
|
||||
- Game concept and vision
|
||||
- Design pillars (3-5 core principles)
|
||||
- Target audience and market
|
||||
- Platform considerations
|
||||
- Core gameplay loop
|
||||
- Initial scope definition
|
||||
|
||||
## Phase 2: Design
|
||||
|
||||
### GDD (Game Design Document)
|
||||
|
||||
**Command:** `create-gdd`
|
||||
**Agent:** Game Designer
|
||||
**Input:** Game Brief
|
||||
**Output:** `{output_folder}/gdd.md` (or sharded into `{output_folder}/gdd/`)
|
||||
|
||||
Comprehensive game design document with genre-specific sections based on 24 supported game types.
|
||||
|
||||
**Core sections:**
|
||||
1. Executive Summary
|
||||
2. Gameplay Systems
|
||||
3. Core Mechanics
|
||||
4. Progression Systems
|
||||
5. UI/UX Design
|
||||
6. Audio Design
|
||||
7. Art Direction
|
||||
8. Technical Requirements
|
||||
9. Game-Type-Specific Sections
|
||||
10. Epic Generation (for sprint planning)
|
||||
|
||||
**Features:**
|
||||
- Game type selection with specialized sections
|
||||
- Hybrid game type support
|
||||
- Automatic epic generation
|
||||
- Scale-adaptive complexity
|
||||
|
||||
### Narrative Design
|
||||
|
||||
**Command:** `narrative`
|
||||
**Agent:** Game Designer
|
||||
**Input:** GDD (required), Game Brief (optional)
|
||||
**Output:** `{output_folder}/narrative-design.md`
|
||||
|
||||
For story-driven games. Creates comprehensive narrative documentation.
|
||||
|
||||
**Sections covered:**
|
||||
1. Story Foundation (premise, themes, tone)
|
||||
2. Story Structure (acts, beats, pacing)
|
||||
3. Characters (protagonists, antagonists, supporting, arcs)
|
||||
4. World Building (setting, history, factions, locations)
|
||||
5. Dialogue Framework (style, branching)
|
||||
6. Environmental Storytelling
|
||||
7. Narrative Delivery Methods
|
||||
8. Gameplay-Narrative Integration
|
||||
9. Production Planning (scope, localization, voice acting)
|
||||
10. Appendices (relationship map, timeline)
|
||||
|
||||
**Narrative Complexity Levels:**
|
||||
- **Critical** — Story IS the game (visual novels, adventure games)
|
||||
- **Heavy** — Deep narrative with gameplay (RPGs, story-driven action)
|
||||
- **Moderate** — Meaningful story supporting gameplay
|
||||
- **Light** — Minimal story, gameplay-focused
|
||||
|
||||
## Phase 3: Technical
|
||||
|
||||
### Game Architecture
|
||||
|
||||
**Command:** `create-architecture`
|
||||
**Agent:** Game Architect
|
||||
**Input:** GDD, Narrative Design (optional)
|
||||
**Output:** `{output_folder}/game-architecture.md`
|
||||
|
||||
Technical architecture document covering engine selection, system design, and implementation approach.
|
||||
|
||||
**Sections covered:**
|
||||
1. Executive Summary
|
||||
2. Engine/Framework Selection
|
||||
3. Core Systems Architecture
|
||||
4. Data Architecture
|
||||
5. Performance Requirements
|
||||
6. Platform-Specific Considerations
|
||||
7. Development Environment
|
||||
8. Testing Strategy
|
||||
9. Build and Deployment
|
||||
10. Technical Risks and Mitigations
|
||||
|
||||
## Phase 4: Production
|
||||
|
||||
Production workflows inherit from BMM and add game-specific overrides.
|
||||
|
||||
### Sprint Planning
|
||||
|
||||
**Command:** `sprint-planning`
|
||||
**Agent:** Game Scrum Master
|
||||
**Input:** GDD with epics
|
||||
**Output:** `{implementation_artifacts}/sprint-status.yaml`
|
||||
|
||||
Generates or updates sprint tracking from epic files. Sets up the sprint backlog and tracking.
|
||||
|
||||
### Sprint Status
|
||||
|
||||
**Command:** `sprint-status`
|
||||
**Agent:** Game Scrum Master
|
||||
**Input:** `sprint-status.yaml`
|
||||
**Output:** Sprint summary, risks, next action recommendation
|
||||
|
||||
Summarizes sprint progress, surfaces risks (stale file, orphaned stories, stories in review), and recommends the next workflow to run.
|
||||
|
||||
**Modes:**
|
||||
- **interactive** (default) — Displays summary with menu options
|
||||
- **validate** — Checks sprint-status.yaml structure
|
||||
- **data** — Returns raw data for other workflows
|
||||
|
||||
### Create Story
|
||||
|
||||
**Command:** `create-story`
|
||||
**Agent:** Game Scrum Master
|
||||
**Input:** GDD, Architecture, Epic context
|
||||
**Output:** `{output_folder}/epics/{epic-name}/stories/{story-name}.md`
|
||||
|
||||
Creates implementable story drafts with acceptance criteria, tasks, and technical notes. Stories are marked ready-for-dev directly when created.
|
||||
|
||||
**Validation:** `validate-create-story`
|
||||
|
||||
### Dev Story
|
||||
|
||||
**Command:** `dev-story`
|
||||
**Agent:** Game Developer
|
||||
**Input:** Story (ready for dev)
|
||||
**Output:** Implemented code
|
||||
|
||||
Implements story tasks following acceptance criteria. Uses TDD approach (red-green-refactor). Updates sprint-status.yaml automatically on completion.
|
||||
|
||||
### Code Review
|
||||
|
||||
**Command:** `code-review`
|
||||
**Agent:** Game Developer
|
||||
**Input:** Story (ready for review)
|
||||
**Output:** Review feedback, approved/needs changes
|
||||
|
||||
Thorough QA code review with game-specific considerations (performance, 60fps, etc.).
|
||||
|
||||
### Retrospective
|
||||
|
||||
**Command:** `epic-retrospective`
|
||||
**Agent:** Game Scrum Master
|
||||
**Input:** Completed epic
|
||||
**Output:** Retrospective document
|
||||
|
||||
Facilitates team retrospective after epic completion. Captures learnings and improvements.
|
||||
|
||||
### Correct Course
|
||||
|
||||
**Command:** `correct-course`
|
||||
**Agent:** Game Scrum Master or Game Architect
|
||||
**Input:** Current project state
|
||||
**Output:** Correction plan
|
||||
|
||||
Navigates significant changes when implementation is off-track. Analyzes impact and recommends adjustments.
|
||||
|
||||
## Workflow Status
|
||||
|
||||
**Command:** `workflow-status`
|
||||
**Agent:** All agents
|
||||
|
||||
Checks current project status across all phases. Shows completed documents, current phase, and next steps.
|
||||
|
||||
## Quick-Flow Workflows
|
||||
|
||||
Fast-track workflows that skip full planning phases. See [Quick-Flow Guide](/docs/how-to/workflows/bmgd-quick-flow.md) for detailed usage.
|
||||
|
||||
### Quick-Prototype
|
||||
|
||||
**Command:** `quick-prototype`
|
||||
**Agent:** Game Designer, Game Developer
|
||||
**Input:** Idea or concept to test
|
||||
**Output:** Working prototype, playtest results
|
||||
|
||||
Rapid prototyping workflow for testing game mechanics and ideas quickly. Focuses on "feel" over polish.
|
||||
|
||||
**Use when:**
|
||||
- Testing if a mechanic is fun
|
||||
- Proving a concept before committing to design
|
||||
- Experimenting with gameplay ideas
|
||||
|
||||
### Quick-Dev
|
||||
|
||||
**Command:** `quick-dev`
|
||||
**Agent:** Game Developer
|
||||
**Input:** Tech-spec, prototype, or direct instructions
|
||||
**Output:** Implemented feature
|
||||
|
||||
Flexible development workflow with game-specific considerations (performance, feel, integration).
|
||||
|
||||
**Use when:**
|
||||
- Implementing features from tech-specs
|
||||
- Building on successful prototypes
|
||||
- Making changes that don't need full story workflow
|
||||
|
||||
## Quality Assurance Workflows
|
||||
|
||||
Game testing workflows for automated testing, playtesting, and quality assurance across Unity, Unreal, and Godot.
|
||||
|
||||
### Test Framework
|
||||
|
||||
**Command:** `test-framework`
|
||||
**Agent:** Game QA
|
||||
**Input:** Game project
|
||||
**Output:** Configured test framework
|
||||
|
||||
Initialize a production-ready test framework for your game engine:
|
||||
|
||||
- **Unity** — Unity Test Framework with Edit Mode and Play Mode tests
|
||||
- **Unreal** — Unreal Automation system with functional tests
|
||||
- **Godot** — GUT (Godot Unit Test) framework
|
||||
|
||||
**Creates:**
|
||||
- Test directory structure
|
||||
- Framework configuration
|
||||
- Sample unit and integration tests
|
||||
- Test documentation
|
||||
|
||||
### Test Design
|
||||
|
||||
**Command:** `test-design`
|
||||
**Agent:** Game QA
|
||||
**Input:** GDD, Architecture
|
||||
**Output:** `{output_folder}/game-test-design.md`
|
||||
|
||||
Creates comprehensive test scenarios covering:
|
||||
|
||||
- Core gameplay mechanics
|
||||
- Progression and save systems
|
||||
- Multiplayer (if applicable)
|
||||
- Platform certification requirements
|
||||
|
||||
Uses GIVEN/WHEN/THEN format with priority levels (P0-P3).
|
||||
|
||||
### Automate
|
||||
|
||||
**Command:** `automate`
|
||||
**Agent:** Game QA
|
||||
**Input:** Test design, game code
|
||||
**Output:** Automated test files
|
||||
|
||||
Generates engine-appropriate automated tests:
|
||||
|
||||
- Unit tests for pure logic
|
||||
- Integration tests for system interactions
|
||||
- Smoke tests for critical path validation
|
||||
|
||||
### Playtest Plan
|
||||
|
||||
**Command:** `playtest-plan`
|
||||
**Agent:** Game QA
|
||||
**Input:** Build, test objectives
|
||||
**Output:** `{output_folder}/playtest-plan.md`
|
||||
|
||||
Creates structured playtesting sessions:
|
||||
|
||||
- Session structure (pre/during/post)
|
||||
- Observation guides
|
||||
- Interview questions
|
||||
- Analysis templates
|
||||
|
||||
**Playtest Types:**
|
||||
- **Internal** — Team validation
|
||||
- **External** — Unbiased feedback
|
||||
- **Focused** — Specific feature testing
|
||||
|
||||
### Performance Test
|
||||
|
||||
**Command:** `performance-test`
|
||||
**Agent:** Game QA
|
||||
**Input:** Platform targets
|
||||
**Output:** `{output_folder}/performance-test-plan.md`
|
||||
|
||||
Designs performance testing strategy:
|
||||
|
||||
- Frame rate targets per platform
|
||||
- Memory budgets
|
||||
- Loading time requirements
|
||||
- Benchmark scenarios
|
||||
- Profiling methodology
|
||||
|
||||
### Test Review
|
||||
|
||||
**Command:** `test-review`
|
||||
**Agent:** Game QA
|
||||
**Input:** Existing test suite
|
||||
**Output:** `{output_folder}/test-review-report.md`
|
||||
|
||||
Reviews test quality and coverage:
|
||||
|
||||
- Test suite metrics
|
||||
- Quality assessment
|
||||
- Coverage gaps
|
||||
- Recommendations
|
||||
|
||||
## Utility Workflows
|
||||
|
||||
### Party Mode
|
||||
|
||||
**Command:** `party-mode`
|
||||
**Agent:** All agents
|
||||
|
||||
Brings multiple agents together for collaborative discussion on complex decisions.
|
||||
|
||||
### Advanced Elicitation
|
||||
|
||||
**Command:** `advanced-elicitation`
|
||||
**Agent:** All agents (web only)
|
||||
|
||||
Deep exploration techniques to challenge assumptions and surface hidden requirements.
|
||||
|
||||
## Standalone BMGD Workflows
|
||||
|
||||
:::note[Implementation Detail]
|
||||
BMGD Phase 4 workflows are standalone implementations tailored for game development. They are self-contained with game-specific logic, templates, and checklists — no dependency on BMM workflow files.
|
||||
:::
|
||||
|
||||
```yaml
|
||||
workflow: '{project-root}/_bmad/bmgd/workflows/4-production/dev-story/workflow.yaml'
|
||||
```
|
||||
@@ -10,6 +10,3 @@ Reference documentation for all BMad Method workflows.
|
||||
- [Core Workflows](/docs/reference/workflows/core-workflows.md) — Domain-agnostic workflows available to all modules
|
||||
- [Document Project](/docs/reference/workflows/document-project.md) — Brownfield project documentation
|
||||
|
||||
## Module-Specific Workflows
|
||||
|
||||
- [BMGD Workflows](/docs/reference/workflows/bmgd-workflows.md) — Game development workflows
|
||||
|
||||
Reference in New Issue
Block a user