bmad-method 6.0.0-alpha.22 → 6.0.0-alpha.23

package/docs/{modules/bmm-bmad-method/test-architecture.md → explanation/features/tea-overview.md}

@@ -1,4 +1,14 @@
-# Test Architect (TEA) Agent Guide
+---
+title: "Test Architect (TEA) Overview"
+description: Understanding the Test Architect (TEA) agent and its role in BMad Method
+---
+
+
+The Test Architect (TEA) is a specialized agent focused on quality strategy, test automation, and release gates in BMad Method projects.
+
+:::tip[Design Philosophy]
+TEA was built to solve AI-generated tests that rot in review. For the problem statement and design principles, see [Testing as Engineering](/docs/explanation/philosophy/testing-as-engineering.md). For setup, see [Setup Test Framework](/docs/how-to/workflows/setup-test-framework.md).
+:::
 
 ## Overview
 
@@ -6,6 +16,42 @@
 - **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project complexity and compliance demands.
 - **Use When:** BMad Method or Enterprise track projects, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required. (Quick Flow projects typically don't require TEA)
 
+---
+
+## Choose Your TEA Engagement Model
+
+BMad does not mandate TEA. There are five valid ways to use it (or skip it). Pick one intentionally.
+
+1. **No TEA**
+   - Skip all TEA workflows. Use your existing team testing approach.
+
+2. **TEA-only (Standalone)**
+   - Use TEA on a non-BMad project. Bring your own requirements, acceptance criteria, and environments.
+   - Typical sequence: `*test-design` (system or epic) -> `*atdd` and/or `*automate` -> optional `*test-review` -> `*trace` for coverage and gate decisions.
+   - Run `*framework` or `*ci` only if you want TEA to scaffold the harness or pipeline.
+
+3. **Integrated: Greenfield - BMad Method (Simple/Standard Work)**
+   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
+   - Phase 4: per-epic `*test-design`, optional `*atdd`, then `*automate` and optional `*test-review`.
+   - Gate (Phase 2): `*trace`.
+
+4. **Integrated: Brownfield - BMad Method or Enterprise (Simple or Complex)**
+   - Phase 2: baseline `*trace`.
+   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
+   - Phase 4: per-epic `*test-design` focused on regression and integration risks.
+   - Gate (Phase 2): `*trace`; `*nfr-assess` (if not done earlier).
+   - For brownfield BMad Method, follow the same flow with `*nfr-assess` optional.
+
+5. **Integrated: Greenfield - Enterprise Method (Enterprise/Compliance Work)**
+   - Phase 2: `*nfr-assess`.
+   - Phase 3: system-level `*test-design`, then `*framework` and `*ci`.
+   - Phase 4: per-epic `*test-design`, plus `*atdd`/`*automate`/`*test-review`.
+   - Gate (Phase 2): `*trace`; archive artifacts as needed.
+
+If you are unsure, default to the integrated path for your track and adjust later.
+
+---
+
 ## TEA Workflow Lifecycle
 
 TEA integrates into the BMad development lifecycle during Solutioning (Phase 3) and Implementation (Phase 4):
@@ -16,6 +62,9 @@ graph TB
     subgraph Phase2["<b>Phase 2: PLANNING</b>"]
         PM["<b>PM: *prd (creates PRD with FRs/NFRs)</b>"]
         PlanNote["<b>Business requirements phase</b>"]
+        NFR2["<b>TEA: *nfr-assess (optional, enterprise)</b>"]
+        PM -.-> NFR2
+        NFR2 -.-> PlanNote
         PM -.-> PlanNote
     end
 
@@ -23,8 +72,8 @@ graph TB
         Architecture["<b>Architect: *architecture</b>"]
         EpicsStories["<b>PM/Architect: *create-epics-and-stories</b>"]
         TestDesignSys["<b>TEA: *test-design (system-level)</b>"]
-        Framework["<b>TEA: *framework</b>"]
-        CI["<b>TEA: *ci</b>"]
+        Framework["<b>TEA: *framework (optional if needed)</b>"]
+        CI["<b>TEA: *ci (optional if needed)</b>"]
         GateCheck["<b>Architect: *implementation-readiness</b>"]
         Architecture --> EpicsStories
         Architecture --> TestDesignSys
@@ -104,12 +153,11 @@ Quick Flow track skips Phases 1 and 3.
 BMad Method and Enterprise use all phases based on project needs.
 When an ADR or architecture draft is produced, run `*test-design` in **system-level** mode before the implementation-readiness gate. This ensures the ADR has an attached testability review and ADR → test mapping. Keep the test-design updated if ADRs change.
 
-### Why TEA is Different from Other BMM Agents
+---
 
-TEA is the only BMM agent that operates in **multiple phases** (Phase 3 and Phase 4) and has its own **knowledge base architecture**.
+## Why TEA is Different from Other BMM Agents
 
-<details>
-<summary><strong>Cross-Phase Operation & Unique Architecture</strong></summary>
+TEA is the only BMM agent that operates in **multiple phases** (Phase 3 and Phase 4) and has its own **knowledge base architecture**.
 
 ### Phase-Specific Agents (Standard Pattern)
 
@@ -151,40 +199,18 @@ Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
 
 **Note**: `*trace` is a two-phase workflow: Phase 1 (traceability) + Phase 2 (gate decision). This reduces cognitive load while maintaining natural workflow.
 
-### Why TEA Gets Special Treatment
+### Why TEA Requires Its Own Knowledge Base
 
 TEA uniquely requires:
 
-- **Extensive domain knowledge**: 32 fragments covering test patterns, CI/CD, fixtures, quality practices, healing strategies, and optional playwright-utils integration
-- **Centralized reference system**: `tea-index.csv` for on-demand fragment loading during workflow execution
-- **Cross-cutting concerns**: Domain-specific testing patterns (vs project-specific artifacts like PRDs/stories)
-- **Optional integrations**: MCP capabilities (healing, exploratory, verification) and playwright-utils support
+- **Extensive domain knowledge**: 30+ fragments covering test patterns, CI/CD, fixtures, quality practices, and optional playwright-utils integration
+- **Cross-cutting concerns**: Domain-specific testing patterns that apply across all BMad projects (vs project-specific artifacts like PRDs/stories)
+- **Optional integrations**: MCP capabilities (exploratory, verification) and playwright-utils support
 
 This architecture enables TEA to maintain consistent, production-ready testing patterns across all BMad projects while operating across multiple development phases.
 
-### Playwright Utils Integration
+---
 
-TEA optionally integrates with `@seontechnologies/playwright-utils`, an open-source library providing fixture-based utilities for Playwright tests.
-
-**Installation:**
-
-```bash
-npm install -D @seontechnologies/playwright-utils
-```
-
-**Enable during BMAD installation** by answering "Yes" when prompted.
-
-**Supported utilities (11 total):**
-
-- api-request, network-recorder, auth-session, intercept-network-call, recurse
-- log, file-utils, burn-in, network-error-monitor
-- fixtures-composition (integration patterns)
-
-**Workflows adapt:** automate, framework, test-review, ci, atdd (+ light mention in test-design).
-
-**Knowledge base:** 32 total fragments (21 core patterns + 11 playwright-utils)
-
-</details>
 
 ## High-Level Cheat Sheets
 
@@ -340,37 +366,84 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
 
 </details>
 
-## Command Catalog
+---
+
+## TEA Command Catalog
+
+| Command        | Primary Outputs                                                                               | Notes                                                | With Playwright MCP Enhancements                                                                             |
+| -------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `*framework`   | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs                           | Use when no production-ready harness exists          | -                                                                                                            |
+| `*ci`          | CI workflow, selective test scripts, secrets checklist                                        | Platform-aware (GitHub Actions default)              | -                                                                                                            |
+| `*test-design` | Combined risk assessment, mitigation plan, and coverage strategy                              | Risk scoring + optional exploratory mode             | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality)           |
+| `*atdd`        | Failing acceptance tests + implementation checklist                                           | TDD red phase + optional recording mode              | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM)                 |
+| `*automate`    | Prioritized specs, fixtures, README/script updates, DoD summary                               | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser |
+| `*test-review` | Test quality review report with 0-100 score, violations, fixes                                | Reviews tests against knowledge base patterns        | -                                                                                                            |
+| `*nfr-assess`  | NFR assessment report with actions                                                            | Focus on security/performance/reliability            | -                                                                                                            |
+| `*trace`       | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision     | -                                                                                                            |
+
+---
+
+## Playwright Utils Integration
+
+TEA optionally integrates with `@seontechnologies/playwright-utils`, an open-source library providing fixture-based utilities for Playwright tests. This integration enhances TEA's test generation and review workflows with production-ready patterns.
 
 <details>
-<summary><strong>Optional Playwright MCP Enhancements</strong></summary>
+<summary><strong>Installation & Configuration</strong></summary>
 
-**Two Playwright MCP servers** (actively maintained, continuously updated):
+**Package**: `@seontechnologies/playwright-utils` ([npm](https://www.npmjs.com/package/@seontechnologies/playwright-utils) | [GitHub](https://github.com/seontechnologies/playwright-utils))
 
-- `playwright` - Browser automation (`npx @playwright/mcp@latest`)
-- `playwright-test` - Test runner with failure analysis (`npx playwright run-test-mcp-server`)
+**Install**: `npm install -D @seontechnologies/playwright-utils`
 
-**How MCP Enhances TEA Workflows**:
+**Enable during BMAD installation** by answering "Yes" when prompted, or manually set `tea_use_playwright_utils: true` in `_bmad/bmm/config.yaml`.
 
-MCP provides additional capabilities on top of TEA's default AI-based approach:
+**To disable**: Set `tea_use_playwright_utils: false` in `_bmad/bmm/config.yaml`.
 
-1. `*test-design`:
-   - Default: Analysis + documentation
-   - **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
+</details>
 
-   Benefit: Discover actual functionality, edge cases, undocumented features
+<details>
+<summary><strong>How Playwright Utils Enhances TEA Workflows</strong></summary>
 
-2. `*atdd`, `*automate`:
-   - Default: Infers selectors and interactions from requirements and knowledge fragments
-   - **+ MCP**: Generates tests **then** verifies with `generator_setup_page`, `browser_*` tools, validates against live app
+1. `*framework`:
+   - Default: Basic Playwright scaffold
+   - **+ playwright-utils**: Scaffold with api-request, network-recorder, auth-session, burn-in, network-error-monitor fixtures pre-configured
 
-   Benefit: Accurate selectors from real DOM, verified behavior, refined test code
+   Benefit: Production-ready patterns from day one
 
-3. `*automate`:
-   - Default: Pattern-based fixes from error messages + knowledge fragments
-   - **+ MCP**: Pattern fixes **enhanced with** `browser_snapshot`, `browser_console_messages`, `browser_network_requests`, `browser_generate_locator`
+2. `*automate`, `*atdd`:
+   - Default: Standard test patterns
+   - **+ playwright-utils**: Tests using api-request (schema validation), intercept-network-call (mocking), recurse (polling), log (structured logging), file-utils (CSV/PDF)
 
-   Benefit: Visual failure context, live DOM inspection, root cause discovery
+   Benefit: Advanced patterns without boilerplate
+
+3. `*test-review`:
+   - Default: Reviews against core knowledge base (22 fragments)
+   - **+ playwright-utils**: Reviews against expanded knowledge base (33 fragments: 22 core + 11 playwright-utils)
+
+   Benefit: Reviews include fixture composition, auth patterns, network recording best practices
+
+4. `*ci`:
+   - Default: Standard CI workflow
+   - **+ playwright-utils**: CI workflow with burn-in script (smart test selection) and network-error-monitor integration
+
+   Benefit: Faster CI feedback, HTTP error detection
+
+**Utilities available** (10 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
+
+</details>
+
+---
+
+## Playwright MCP Enhancements
+
+TEA can leverage Playwright MCP servers to enhance test generation with live browser verification. MCP provides interactive capabilities on top of TEA's default AI-based approach.
+
+<details>
+<summary><strong>MCP Server Configuration</strong></summary>
+
+**Two Playwright MCP servers** (actively maintained, continuously updated):
+
+- `playwright` - Browser automation (`npx @playwright/mcp@latest`)
+- `playwright-test` - Test runner with failure analysis (`npx playwright run-test-mcp-server`)
 
 **Config example**:
 
@@ -394,58 +467,31 @@ MCP provides additional capabilities on top of TEA's default AI-based approach:
 </details>
 
 <details>
-<summary><strong>Optional Playwright Utils Integration</strong></summary>
-
-**Open-source Playwright utilities** from SEON Technologies (production-tested, npm published):
-
-- **Package**: `@seontechnologies/playwright-utils` ([npm](https://www.npmjs.com/package/@seontechnologies/playwright-utils) | [GitHub](https://github.com/seontechnologies/playwright-utils))
-- **Install**: `npm install -D @seontechnologies/playwright-utils`
-
-**How Playwright Utils Enhances TEA Workflows**:
-
-Provides fixture-based utilities that integrate into TEA's test generation and review workflows:
-
-1. `*framework`:
-   - Default: Basic Playwright scaffold
-   - **+ playwright-utils**: Scaffold with api-request, network-recorder, auth-session, burn-in, network-error-monitor fixtures pre-configured
-
-   Benefit: Production-ready patterns from day one
-
-2. `*automate`, `*atdd`:
-   - Default: Standard test patterns
-   - **+ playwright-utils**: Tests using api-request (schema validation), intercept-network-call (mocking), recurse (polling), log (structured logging), file-utils (CSV/PDF)
-
-   Benefit: Advanced patterns without boilerplate
-
-3. `*test-review`:
-   - Default: Reviews against core knowledge base (21 fragments)
-   - **+ playwright-utils**: Reviews against expanded knowledge base (32 fragments: 21 core + 11 playwright-utils)
+<summary><strong>How MCP Enhances TEA Workflows</strong></summary>
 
-   Benefit: Reviews include fixture composition, auth patterns, network recording best practices
+1. `*test-design`:
+   - Default: Analysis + documentation
+   - **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
 
-4. `*ci`:
-   - Default: Standard CI workflow
-   - **+ playwright-utils**: CI workflow with burn-in script (smart test selection) and network-error-monitor integration
+   Benefit: Discover actual functionality, edge cases, undocumented features
 
-   Benefit: Faster CI feedback, HTTP error detection
+2. `*atdd`, `*automate`:
+   - Default: Infers selectors and interactions from requirements and knowledge fragments
+   - **+ MCP**: Generates tests **then** verifies with `generator_setup_page`, `browser_*` tools, validates against live app
 
-**Utilities available** (11 total): api-request, network-recorder, auth-session, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
+   Benefit: Accurate selectors from real DOM, verified behavior, refined test code
 
-**Enable during BMAD installation** by answering "Yes" when prompted, or manually set `tea_use_playwright_utils: true` in `_bmad/bmm/config.yaml`.
+3. `*automate` (healing mode):
+   - Default: Pattern-based fixes from error messages + knowledge fragments
+   - **+ MCP**: Pattern fixes **enhanced with** `browser_snapshot`, `browser_console_messages`, `browser_network_requests`, `browser_generate_locator`
 
-**To disable**: Set `tea_use_playwright_utils: false` in `_bmad/bmm/config.yaml`.
+   Benefit: Visual failure context, live DOM inspection, root cause discovery
 
 </details>
 
-<br></br>
+---
 
-| Command        | Primary Outputs                                                                               | Notes                                                | With Playwright MCP Enhancements                                                                             |
-| -------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| `*framework`   | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs                           | Use when no production-ready harness exists          | -                                                                                                            |
-| `*ci`          | CI workflow, selective test scripts, secrets checklist                                        | Platform-aware (GitHub Actions default)              | -                                                                                                            |
-| `*test-design` | Combined risk assessment, mitigation plan, and coverage strategy                              | Risk scoring + optional exploratory mode             | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality)           |
-| `*atdd`        | Failing acceptance tests + implementation checklist                                           | TDD red phase + optional recording mode              | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM)                 |
-| `*automate`    | Prioritized specs, fixtures, README/script updates, DoD summary                               | Optional healing/recording, avoid duplicate coverage | **+ Healing**: Pattern fixes enhanced with visual debugging + **+ Recording**: AI verified with live browser |
-| `*test-review` | Test quality review report with 0-100 score, violations, fixes                                | Reviews tests against knowledge base patterns        | -                                                                                                            |
-| `*nfr-assess`  | NFR assessment report with actions                                                            | Focus on security/performance/reliability            | -                                                                                                            |
-| `*trace`       | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision     | -                                                                                                            |
+## Related Documentation
+
+- [Setup Test Framework](/docs/how-to/workflows/setup-test-framework.md) - How to set up testing infrastructure
+- [Run Test Design](/docs/how-to/workflows/run-test-design.md) - Creating test plans

package/docs/{bmad-core-concepts/web-bundles/index.md → explanation/features/web-bundles.md}

@@ -1,6 +1,9 @@
-# Web Bundles
+---
+title: "Web Bundles"
+---
 
-Use BMAD agents in Gemini Gems and Custom GPTs.
+
+Use BMad agents in Gemini Gems and Custom GPTs.
 
 ## Status
 
@@ -22,7 +25,7 @@ Web bundles package BMad agents as self-contained files that work in Gemini Gems
 
 **Perfect for:**
 - Uploading a single file to a Gemini GEM or Custom GPT
-- Using BMAD Method from the Web
+- Using BMad Method from the Web
 - Cost savings (generally lower cost than local usage)
 - Quick sharing of agent configurations
 
@@ -30,5 +33,3 @@ Web bundles package BMad agents as self-contained files that work in Gemini Gems
 - Some quality reduction vs local usage
 - Less convenient than full local installation
 - Limited to agent capabilities (no workflow file access)
-
-[← Back to Core Concepts](../index.md)

package/docs/{modules/bmgd-bmad-game-dev/agents-guide.md → explanation/game-dev/agents.md}

@@ -1,4 +1,7 @@
-# BMGD Agents Guide
+---
+title: "BMGD Agents Guide"
+---
+
 
 Complete reference for BMGD's six specialized game development agents.
 
@@ -300,7 +303,7 @@ Direct, confident, and gameplay-focused. Uses dev slang, thinks in game feel and
 | ------------------ | ------------------------------------------------------ |
 | `quick-prototype`  | Rapid prototype to test if a mechanic is fun           |
 | `quick-dev`        | Implement features end-to-end with game considerations |
-| `create-tech-spec` | Create implementation-ready technical spec             |
+| `quick-spec`       | Create implementation-ready technical spec             |
 | `code-review`      | Review code quality                                    |
 | `test-framework`   | Set up automated testing                               |
 | `party-mode`       | Bring in specialists when needed                       |
@@ -402,6 +405,6 @@ The `project-context.md` file (if present) serves as the authoritative source fo
 
 ## Next Steps
 
-- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
-- **[Workflows Guide](./workflows-guide.md)** - Detailed workflow reference
-- **[Game Types Guide](./game-types-guide.md)** - Game type templates
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD
+- **[Workflows Guide](/docs/reference/workflows/index.md)** - Detailed workflow reference
+- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Game type templates

package/docs/explanation/game-dev/bmgd-vs-bmm.md

@@ -0,0 +1,150 @@
+---
+title: "BMGD vs BMM"
+description: Understanding the differences between BMGD and BMM
+---
+
+
+BMGD (BMad Game Development) extends BMM (BMad Method) with game-specific capabilities. This page explains the key differences.
+
+---
+
+## Quick Comparison
+
+| Aspect         | BMM                                   | BMGD                                                                     |
+| -------------- | ------------------------------------- | ------------------------------------------------------------------------ |
+| **Focus**      | General software                      | Game development                                                         |
+| **Agents**     | PM, Architect, Dev, SM, TEA, Solo Dev | Game Designer, Game Dev, Game Architect, Game SM, Game QA, Game Solo Dev |
+| **Planning**   | PRD, Tech Spec                        | Game Brief, GDD                                                          |
+| **Types**      | N/A                                   | 24 game type templates                                                   |
+| **Narrative**  | N/A                                   | Full narrative workflow                                                  |
+| **Testing**    | Web-focused                           | Engine-specific (Unity, Unreal, Godot)                                   |
+| **Production** | BMM workflows                         | BMM workflows with game overrides                                        |
+
+---
+
+## Agent Differences
+
+### BMM Agents
+- PM (Product Manager)
+- Architect
+- DEV (Developer)
+- SM (Scrum Master)
+- TEA (Test Architect)
+- Quick Flow Solo Dev
+
+### BMGD Agents
+- Game Designer
+- Game Developer
+- Game Architect
+- Game Scrum Master
+- Game QA
+- Game Solo Dev
+
+BMGD agents understand game-specific concepts like:
+- Game mechanics and balance
+- Player psychology
+- Engine-specific patterns
+- Playtesting and QA
+
+---
+
+## Planning Documents
+
+### BMM Planning
+- **Product Brief** → **PRD** → **Architecture**
+- Focus: Software requirements, user stories, system design
+
+### BMGD Planning
+- **Game Brief** → **GDD** → **Architecture**
+- Focus: Game vision, mechanics, narrative, player experience
+
+The GDD (Game Design Document) includes:
+- Core gameplay loop
+- Mechanics and systems
+- Progression and balance
+- Art and audio direction
+- Genre-specific sections
+
+---
+
+## Game Type Templates
+
+BMGD includes 24 game type templates that auto-configure GDD sections:
+
+- Action, Adventure, Puzzle
+- RPG, Strategy, Simulation
+- Sports, Racing, Fighting
+- Horror, Platformer, Shooter
+- And more...
+
+Each template provides:
+- Genre-specific GDD sections
+- Relevant mechanics patterns
+- Testing considerations
+- Common pitfalls to avoid
+
+---
+
+## Narrative Support
+
+BMGD includes full narrative workflow for story-driven games:
+
+- **Narrative Design** workflow
+- Story structure templates
+- Character development
+- World-building guidelines
+- Dialogue systems
+
+BMM has no equivalent for narrative design.
+
+---
+
+## Testing Differences
+
+### BMM Testing (TEA)
+- Web-focused (Playwright, Cypress)
+- API testing
+- E2E for web applications
+
+### BMGD Testing (Game QA)
+- Engine-specific frameworks (Unity, Unreal, Godot)
+- Gameplay testing
+- Performance profiling
+- Playtest planning
+- Balance validation
+
+---
+
+## Production Workflow
+
+BMGD production workflows **inherit from BMM** and add game-specific:
+- Checklists
+- Templates
+- Quality gates
+- Engine-specific considerations
+
+This means you get all of BMM's implementation structure plus game-specific enhancements.
+
+---
+
+## When to Use Each
+
+### Use BMM when:
+- Building web applications
+- Creating APIs and services
+- Developing mobile apps (non-game)
+- Any general software project
+
+### Use BMGD when:
+- Building video games
+- Creating interactive experiences
+- Game prototyping
+- Game jams
+
+---
+
+## Related
+
+- [BMGD Overview](/docs/explanation/game-dev/index.md) - Getting started with BMGD
+- [Game Types Guide](/docs/explanation/game-dev/game-types.md) - Understanding game templates
+- [Quick Start BMGD](/docs/tutorials/getting-started/quick-start-bmgd.md) - Tutorial

package/docs/{modules/bmgd-bmad-game-dev/game-types-guide.md → explanation/game-dev/game-types.md}

@@ -1,4 +1,7 @@
-# BMGD Game Types Guide
+---
+title: "BMGD Game Types Guide"
+---
+
 
 Reference for selecting and using BMGD's 24 supported game type templates.
 
@@ -498,6 +501,6 @@ When you select a game type, BMGD adds these GDD sections:
 
 ## Next Steps
 
-- **[Quick Start Guide](./quick-start.md)** - Get started with BMGD
-- **[Workflows Guide](./workflows-guide.md)** - GDD workflow details
-- **[Glossary](./glossary.md)** - Game development terminology
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started with BMGD
+- **[Workflows Guide](/docs/reference/workflows/bmgd-workflows.md)** - GDD workflow details
+- **[Glossary](/docs/reference/glossary/index.md)** - Game development terminology

package/docs/explanation/game-dev/index.md

@@ -0,0 +1,85 @@
+---
+title: "BMGD - Game Development Module"
+description: AI-powered workflows for game design and development with BMGD
+---
+
+
+Complete guides for the BMad Game Development Module (BMGD) - AI-powered workflows for game design and development that adapt to your project's needs.
+
+---
+
+## Getting Started
+
+**New to BMGD?** Start here:
+
+- **[Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)** - Get started building your first game
+  - Installation and setup
+  - Understanding the game development phases
+  - Running your first workflows
+  - Agent-based development flow
+
+**Quick Path:** Install BMGD module → Game Brief → GDD → Architecture → Build
+
+---
+
+## Core Documentation
+
+- **[Game Types Guide](/docs/explanation/game-dev/game-types.md)** - Selecting and using game type templates (24 supported types)
+- **[BMGD vs BMM](/docs/explanation/game-dev/bmgd-vs-bmm.md)** - Understanding the differences
+
+---
+
+## Game Development Phases
+
+BMGD follows four phases aligned with game development:
+
+### Phase 1: Preproduction
+- **Brainstorm Game** - Ideation with game-specific techniques
+- **Game Brief** - Capture vision, market, and fundamentals
+
+### Phase 2: Design
+- **GDD (Game Design Document)** - Comprehensive game design
+- **Narrative Design** - Story, characters, world (for story-driven games)
+
+### Phase 3: Technical
+- **Game Architecture** - Engine, systems, patterns, structure
+
+### Phase 4: Production
+- **Sprint Planning** - Epic and story management
+- **Story Development** - Implementation workflow
+- **Code Review** - Quality assurance
+- **Testing** - Automated tests, playtesting, performance
+- **Retrospective** - Continuous improvement
+
+---
+
+## Choose Your Path
+
+### I need to...
+
+**Start a new game project**
+→ Start with [Quick Start Guide](/docs/tutorials/getting-started/quick-start-bmgd.md)
+→ Run `brainstorm-game` for ideation
+→ Create a Game Brief with `create-brief`
+
+**Design my game**
+→ Create a GDD with `create-gdd`
+→ If story-heavy, add Narrative Design with `create-narrative`
+
+**Plan the technical architecture**
+→ Run `create-architecture` with the Game Architect
+
+**Build my game**
+→ Use Phase 4 production workflows
+→ Follow the sprint-based development cycle
+
+**Quickly test an idea**
+→ Use [Quick-Flow](/docs/how-to/workflows/bmgd-quick-flow.md) for rapid prototyping
+
+---
+
+## Related
+
+- [Game Types Guide](/docs/explanation/game-dev/game-types.md) - Understanding game type templates
+- [BMGD vs BMM](/docs/explanation/game-dev/bmgd-vs-bmm.md) - Comparison with core method
+- [Glossary](/docs/reference/glossary/index.md) - Terminology reference