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

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

@@ -1,8 +1,14 @@
 ---
-last-redoc-date: 2025-11-05
+title: "Test Architect (TEA) Overview"
+description: Understanding the Test Architect (TEA) agent and its role in BMad Method
 ---
 
-# Test Architect (TEA) Agent Guide
+
+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
 
@@ -10,6 +16,42 @@ last-redoc-date: 2025-11-05
 - **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):
@@ -20,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
 
@@ -27,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
@@ -108,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)
 
@@ -155,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
 
@@ -259,17 +281,17 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
 - 🔄 Phase 4: `*test-design` - Focus on regression hotspots and brownfield risks
 - 🔄 Phase 4: Story Review - May include `*nfr-assess` if not done earlier
 
-| Workflow Stage                     | Test Architect                                                               | Dev / Team                                                                          | Outputs                                                                |
-| ---------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| **Documentation**: Prerequisite ➕ | -                                                                            | Analyst `*document-project` (if undocumented)                                       | Comprehensive project documentation                                    |
-| **Phase 1**: Discovery             | -                                                                            | Analyst/PM/Architect rerun planning workflows                                       | Updated planning artifacts in `{output_folder}`                        |
-| **Phase 2**: Planning              | Run ➕ `*trace` (baseline coverage)                                          | PM `*prd` (creates PRD with FRs/NFRs)                                               | PRD with FRs/NFRs, ➕ coverage baseline                                |
-| **Phase 3**: Solutioning           | Run `*framework`, `*ci` AFTER architecture and epic creation                 | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline               |
-| **Phase 4**: Sprint Start          | -                                                                            | SM `*sprint-planning`                                                               | Sprint status file with all epics and stories                          |
-| **Phase 4**: Epic Planning         | Run `*test-design` for THIS epic 🔄 (regression hotspots)                    | Review epic scope and brownfield risks                                              | `test-design-epic-N.md` with brownfield risk assessment and mitigation |
-| **Phase 4**: Story Dev             | (Optional) `*atdd` before dev, then `*automate` after                        | SM `*create-story`, DEV implements                                                  | Tests, story implementation                                            |
-| **Phase 4**: Story Review          | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests                                                     | Quality report, refreshed coverage matrix, NFR report                  |
-| **Phase 4**: Release Gate          | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2)            | Capture sign-offs, share release notes                                              | Quality audit, Gate YAML + release summary                             |
+| Workflow Stage                    | Test Architect                                                              | Dev / Team                                                                          | Outputs                                                                |
+| --------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Documentation**: Prerequisite ➕ | -                                                                           | Analyst `*document-project` (if undocumented)                                       | Comprehensive project documentation                                    |
+| **Phase 1**: Discovery            | -                                                                           | Analyst/PM/Architect rerun planning workflows                                       | Updated planning artifacts in `{output_folder}`                        |
+| **Phase 2**: Planning             | Run ➕ `*trace` (baseline coverage)                                          | PM `*prd` (creates PRD with FRs/NFRs)                                               | PRD with FRs/NFRs, ➕ coverage baseline                                 |
+| **Phase 3**: Solutioning          | Run `*framework`, `*ci` AFTER architecture and epic creation                | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline               |
+| **Phase 4**: Sprint Start         | -                                                                           | SM `*sprint-planning`                                                               | Sprint status file with all epics and stories                          |
+| **Phase 4**: Epic Planning        | Run `*test-design` for THIS epic 🔄 (regression hotspots)                    | Review epic scope and brownfield risks                                              | `test-design-epic-N.md` with brownfield risk assessment and mitigation |
+| **Phase 4**: Story Dev            | (Optional) `*atdd` before dev, then `*automate` after                       | SM `*create-story`, DEV implements                                                  | Tests, story implementation                                            |
+| **Phase 4**: Story Review         | Apply `*test-review` (optional), re-run `*trace`, ➕ `*nfr-assess` if needed | Resolve gaps, update docs/tests                                                     | Quality report, refreshed coverage matrix, NFR report                  |
+| **Phase 4**: Release Gate         | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2)           | Capture sign-offs, share release notes                                              | Quality audit, Gate YAML + release summary                             |
 
 <details>
 <summary>Execution Notes</summary>
@@ -309,15 +331,15 @@ These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks*
 - 🔄 Phase 4: `*test-design` - Enterprise focus (compliance, security architecture alignment)
 - 📦 Release Gate - Archive artifacts and compliance evidence for audits
 
-| Workflow Stage             | Test Architect                                                           | Dev / Team                                                                          | Outputs                                                            |
-| -------------------------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
-| **Phase 1**: Discovery     | -                                                                        | Analyst ➕ `*research`, `*product-brief`                                            | Domain research, compliance analysis, product brief                |
-| **Phase 2**: Planning      | Run ➕ `*nfr-assess`                                                     | PM `*prd` (creates PRD with FRs/NFRs), UX `*create-ux-design`                       | Enterprise PRD with FRs/NFRs, UX design, ➕ NFR documentation      |
-| **Phase 3**: Solutioning   | Run `*framework`, `*ci` AFTER architecture and epic creation             | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline           |
-| **Phase 4**: Sprint Start  | -                                                                        | SM `*sprint-planning`                                                               | Sprint plan with all epics                                         |
+| Workflow Stage             | Test Architect                                                          | Dev / Team                                                                          | Outputs                                                            |
+| -------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| **Phase 1**: Discovery     | -                                                                       | Analyst ➕ `*research`, `*product-brief`                                             | Domain research, compliance analysis, product brief                |
+| **Phase 2**: Planning      | Run ➕ `*nfr-assess`                                                     | PM `*prd` (creates PRD with FRs/NFRs), UX `*create-ux-design`                       | Enterprise PRD with FRs/NFRs, UX design, ➕ NFR documentation       |
+| **Phase 3**: Solutioning   | Run `*framework`, `*ci` AFTER architecture and epic creation            | Architect `*architecture`, `*create-epics-and-stories`, `*implementation-readiness` | Architecture, epics/stories, test framework, CI pipeline           |
+| **Phase 4**: Sprint Start  | -                                                                       | SM `*sprint-planning`                                                               | Sprint plan with all epics                                         |
 | **Phase 4**: Epic Planning | Run `*test-design` for THIS epic 🔄 (compliance focus)                   | Review epic scope and compliance requirements                                       | `test-design-epic-N.md` with security/performance/compliance focus |
-| **Phase 4**: Story Dev     | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story      | SM `*create-story`, DEV implements                                                  | Tests, fixtures, quality reports, coverage matrices                |
-| **Phase 4**: Release Gate  | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence                                           | Quality audit, updated assessments, gate YAML, 📦 audit trail      |
+| **Phase 4**: Story Dev     | (Optional) `*atdd`, `*automate`, `*test-review`, `*trace` per story     | SM `*create-story`, DEV implements                                                  | Tests, fixtures, quality reports, coverage matrices                |
+| **Phase 4**: Release Gate  | Final `*test-review` audit, Run `*trace` (Phase 2), 📦 archive artifacts | Capture sign-offs, 📦 compliance evidence                                            | Quality audit, updated assessments, gate YAML, 📦 audit trail       |
 
 <details>
 <summary>Execution Notes</summary>
@@ -344,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**:
 
@@ -398,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)
+<summary><strong>How MCP Enhances TEA Workflows</strong></summary>
 
-   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)
-
-   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/explanation/features/web-bundles.md

@@ -0,0 +1,35 @@
+---
+title: "Web Bundles"
+---
+
+
+Use BMad agents in Gemini Gems and Custom GPTs.
+
+## Status
+
+> **Note:** The Web Bundling Feature is being rebuilt from the ground up. Current v6 bundles may be incomplete or missing functionality.
+
+## What Are Web Bundles?
+
+Web bundles package BMad agents as self-contained files that work in Gemini Gems and Custom GPTs. Everything the agent needs - instructions, workflows, dependencies - is bundled into a single file for easy upload.
+
+### What's Included
+
+- Complete agent persona and instructions
+- All workflows and dependencies
+- Interactive menu system
+- Party mode for multi-agent collaboration
+- No external files required
+
+### Use Cases
+
+**Perfect for:**
+- Uploading a single file to a Gemini GEM or Custom GPT
+- Using BMad Method from the Web
+- Cost savings (generally lower cost than local usage)
+- Quick sharing of agent configurations
+
+**Trade-offs:**
+- Some quality reduction vs local usage
+- Less convenient than full local installation
+- Limited to agent capabilities (no workflow file access)

package/{src/modules/bmgd/docs/agents-guide.md → docs/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/{src/modules/bmgd/docs/game-types-guide.md → docs/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