bmad-method 6.0.0-alpha.5 → 6.0.0-alpha.6

package/src/modules/bmm/docs/brownfield-guide.md

@@ -277,7 +277,7 @@ It's better to spend 10-30 minutes generating fresh, accurate docs than to waste
 
 **When to skip:** Bug fixes, well-understood features, time-sensitive changes
 
-See [Workflows Guide](../workflows/README.md) for details.
+See the [Workflows section in BMM README](../README.md) for details.
 
 ### Phase 2: Planning (Required)
 
@@ -736,11 +736,11 @@ flowchart TD
 - **[Glossary](./glossary.md)** - Key terminology
 - **[FAQ](./faq.md)** - Common questions
 - **[Troubleshooting](./troubleshooting.md)** - Problem resolution
-- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
+- **[Workflow Documentation](./README.md#-workflow-guides)** - Complete workflow reference
 
 ---
 
-## Support & Resources
+## Support and Resources
 
 **Community:**
 
@@ -750,9 +750,8 @@ flowchart TD
 
 **Documentation:**
 
-- [BMM Workflows Guide](../workflows/README.md)
-- [Test Architect Guide](../testarch/README.md)
-- [BMM Module README](../README.md)
+- [Test Architect Guide](./test-architecture.md) - Comprehensive testing strategy
+- [BMM Module README](../README.md) - Complete module and workflow reference
 
 ---
 

package/src/modules/bmm/docs/enterprise-agentic-development.md

@@ -9,7 +9,7 @@
 ## Table of Contents
 
 - [The Paradigm Shift](#the-paradigm-shift)
-- [The Evolving Role of Product Managers & UX Designers](#the-evolving-role-of-product-managers--ux-designers)
+- [The Evolving Role of Product Managers and UX Designers](#the-evolving-role-of-product-managers-and-ux-designers)
 - [How BMad Method Enables PM/UX Technical Evolution](#how-bmad-method-enables-pmux-technical-evolution)
 - [Team Collaboration Patterns](#team-collaboration-patterns)
 - [Work Distribution Strategies](#work-distribution-strategies)
@@ -59,7 +59,7 @@
 
 ---
 
-## The Evolving Role of Product Managers & UX Designers
+## The Evolving Role of Product Managers and UX Designers
 
 ### The Future is Now
 
@@ -672,7 +672,7 @@ PMs write BMad PRDs → Stories auto-fed to cloud AI agents → Parallel impleme
 - [FAQ](./faq.md) - Common questions
 - [Scale Adaptive System](./scale-adaptive-system.md) - Project levels explained
 - [Quick Start Guide](./quick-start.md) - Getting started
-- [Workflows Guide](../workflows/README.md) - Complete workflow reference
+- [Workflow Documentation](./README.md#-workflow-guides) - Complete workflow reference
 - [Agents Guide](./agents-guide.md) - Understanding BMad agents
 
 ---

package/src/modules/bmm/docs/faq.md

@@ -8,11 +8,11 @@ Quick answers to common questions about the BMad Method Module.
 
 - [Getting Started](#getting-started)
 - [Choosing the Right Level](#choosing-the-right-level)
-- [Workflows & Phases](#workflows--phases)
+- [Workflows and Phases](#workflows-and-phases)
 - [Planning Documents](#planning-documents)
 - [Implementation](#implementation)
 - [Brownfield Development](#brownfield-development)
-- [Tools & Technical](#tools--technical)
+- [Tools and Technical](#tools-and-technical)
 
 ---
 
@@ -26,7 +26,7 @@ Quick answers to common questions about the BMad Method Module.
 - Creates the tracking status file
 - Routes you to the correct starting workflow
 
-For experienced users: use the [Quick Reference](./quick-start.md#quick-reference-agent--document-mapping) to go directly to the right agent/workflow.
+For experienced users: use the [Quick Reference](./quick-start.md#quick-reference-agent-document-mapping) to go directly to the right agent/workflow.
 
 ### Q: Why do I need fresh chats for each workflow?
 
@@ -108,7 +108,7 @@ The overlap (5-10 stories) is intentional. Choose based on:
 
 ---
 
-## Workflows & Phases
+## Workflows and Phases
 
 ### Q: What's the difference between workflow-status and workflow-init?
 
@@ -339,7 +339,7 @@ BMM respects your choice - it won't force modernization, but it will offer it.
 
 ---
 
-## Tools & Technical
+## Tools and Technical
 
 ### Q: Why are my Mermaid diagrams not rendering?
 
@@ -399,7 +399,7 @@ Use them together for best results.
 
 **Why model quality matters:** BMM workflows require LLMs that can follow multi-step processes, maintain context across phases, and implement code that adheres to specifications. Tools with weaker models will struggle with workflow adherence and code quality.
 
-See [IDE Setup Guides](../../../docs/ide-info/) for configuration specifics.
+See [IDE Setup Guides](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for configuration specifics.
 
 ### Q: Can I customize agents?
 

package/src/modules/bmm/docs/glossary.md

@@ -7,11 +7,11 @@ Comprehensive terminology reference for the BMad Method Module.
 ## Navigation
 
 - [Core Concepts](#core-concepts)
-- [Scale & Complexity](#scale--complexity)
+- [Scale and Complexity](#scale-and-complexity)
 - [Planning Documents](#planning-documents)
-- [Workflow & Phases](#workflow--phases)
-- [Agents & Roles](#agents--roles)
-- [Status & Tracking](#status--tracking)
+- [Workflow and Phases](#workflow-and-phases)
+- [Agents and Roles](#agents-and-roles)
+- [Status and Tracking](#status-and-tracking)
 - [Project Types](#project-types)
 - [Implementation Terms](#implementation-terms)
 
@@ -41,7 +41,7 @@ A multi-step guided process that orchestrates AI agent activities to produce spe
 
 ---
 
-## Scale & Complexity
+## Scale and Complexity
 
 ### Quick Flow Track
 
@@ -99,7 +99,7 @@ Game development equivalent of PRD, created by Game Designer agent for game proj
 
 ---
 
-## Workflow & Phases
+## Workflow and Phases
 
 ### Phase 0: Documentation (Prerequisite)
 
@@ -135,7 +135,7 @@ Dynamic technical guidance generated for each story via epic-tech-context and st
 
 ---
 
-## Agents & Roles
+## Agents and Roles
 
 ### PM (Product Manager)
 
@@ -183,7 +183,7 @@ Multi-agent collaboration feature where all installed agents (19+ from BMM, CIS,
 
 ---
 
-## Status & Tracking
+## Status and Tracking
 
 ### bmm-workflow-status.yaml
 

package/src/modules/bmm/docs/quick-spec-flow.md

@@ -277,7 +277,7 @@ For user-facing changes, Quick Spec Flow captures:
 
 ---
 
-## Auto-Validation & Quality Assurance
+## Auto-Validation and Quality Assurance
 
 Quick Spec Flow **automatically validates** everything:
 
@@ -543,7 +543,7 @@ Quick Spec Flow is **fully standalone**:
 
 ---
 
-## Tips & Best Practices
+## Tips and Best Practices
 
 ### 1. **Be Specific in Discovery**
 
@@ -643,7 +643,7 @@ Quick Spec Flow is your **fast path from idea to implementation** for:
 ## Next Steps
 
 - **Try it now:** Load PM agent and describe a small change
-- **Learn more:** See `src/modules/bmm/workflows/README.md` for full BMM workflow guide
+- **Learn more:** See the [BMM Workflow Guides](./README.md#-workflow-guides) for comprehensive workflow documentation
 - **Need help deciding?** Run `workflow-init` to get a recommendation
 - **Have questions?** Join us on Discord: https://discord.gg/gk8jAdXWmj
 

package/src/modules/bmm/docs/quick-start.md

@@ -37,9 +37,9 @@ The interactive installer will guide you through setup and create a `bmad/` fold
 
 ### Step 1: Initialize Your Workflow
 
-1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](../docs/ide-info/) for how to activate agents:
-   - [Claude Code](../docs/ide-info/claude-code.md)
-   - [VS Code/Cursor/Windsurf](../docs/ide-info/) - Check your IDE folder
+1. **Load the Analyst agent** in your IDE - See your IDE-specific instructions in [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for how to activate agents:
+   - [Claude Code](https://github.com/bmad-code-org/BMAD-METHOD/blob/main/docs/ide-info/claude-code.md)
+   - [VS Code/Cursor/Windsurf](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) - Check your IDE folder
    - Other IDEs also supported
 2. **Wait for the agent's menu** to appear
 3. **Tell the agent**: "Run workflow-init" or type "\*workflow-init" or select the menu item number
@@ -107,7 +107,7 @@ The next TRULY REQUIRED step is:
 
 When an agent tells you to run a workflow (like `prd`):
 
-1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](../docs/ide-info/) for your IDE's specific instructions
+1. **Start a new chat** with the specified agent (e.g., PM) - See [docs/ide-info](https://github.com/bmad-code-org/BMAD-METHOD/tree/main/docs/ide-info) for your IDE's specific instructions
 2. **Wait for the menu** to appear
 3. **Tell the agent** to run it using any of these formats:
    - Type the shorthand: `*prd`
@@ -350,7 +350,7 @@ A: Yes, once you learn the flow. Use the Quick Reference in Step 2 to go directl
 
 - **During workflows**: Agents guide you with questions and explanations
 - **Community**: [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
-- **Complete guide**: [BMM Workflows README](../src/modules/bmm/workflows/README.md)
+- **Complete guide**: [BMM Workflow Documentation](./README.md#-workflow-guides)
 - **YouTube tutorials**: [BMad Code Channel](https://www.youtube.com/@BMadCode)
 
 ---

package/src/modules/bmm/docs/scale-adaptive-system.md

@@ -592,7 +592,7 @@ Run `workflow-init` on existing projects to migrate to new tracking system. It d
 - **[Brownfield Guide](./brownfield-guide.md)** - Existing codebase workflows
 - **[Glossary](./glossary.md)** - Complete terminology
 - **[FAQ](./faq.md)** - Common questions
-- **[Workflows Guide](../workflows/README.md)** - Complete workflow reference
+- **[Workflows Guide](./README.md#-workflow-guides)** - Complete workflow reference
 
 ---
 

package/src/modules/bmm/docs/test-architecture.md

@@ -0,0 +1,329 @@
+---
+last-redoc-date: 2025-10-14
+---
+
+# Test Architect (TEA) Agent Guide
+
+## Overview
+
+- **Persona:** Murat, Master Test Architect and Quality Advisor focused on risk-based testing, fixture architecture, ATDD, and CI/CD governance.
+- **Mission:** Deliver actionable quality strategies, automation coverage, and gate decisions that scale with project level and compliance demands.
+- **Use When:** Project level ≥2, integration risk is non-trivial, brownfield regression risk exists, or compliance/NFR evidence is required.
+
+## TEA Workflow Lifecycle
+
+TEA integrates across the entire BMad development lifecycle, providing quality assurance at every phase:
+
+```mermaid
+%%{init: {'theme':'base', 'themeVariables': { 'primaryColor':'#fff','primaryTextColor':'#000','primaryBorderColor':'#000','lineColor':'#000','secondaryColor':'#fff','tertiaryColor':'#fff','fontSize':'16px','fontFamily':'arial'}}}%%
+graph TB
+    subgraph Phase2["<b>Phase 2: PLANNING</b>"]
+        PM["<b>PM: *prd</b>"]
+        Framework["<b>TEA: *framework</b>"]
+        CI["<b>TEA: *ci</b>"]
+        TestDesign["<b>TEA: *test-design</b>"]
+        PM --> Framework
+        Framework --> CI
+        CI --> TestDesign
+        SetupNote["<b>Setup once per project</b>"]
+        TestDesign -.-> SetupNote
+    end
+
+    subgraph Phase4["<b>Phase 4: IMPLEMENTATION - Per Story Cycle</b>"]
+        CreateStory["<b>SM: *create-story</b>"]
+        ATDD["<b>TEA: *atdd (optional, before dev)</b>"]
+        DevImpl["<b>DEV: implements story</b>"]
+        Automate["<b>TEA: *automate</b>"]
+        TestReview1["<b>TEA: *test-review (optional)</b>"]
+        Trace1["<b>TEA: *trace (refresh coverage)</b>"]
+
+        CreateStory --> ATDD
+        ATDD --> DevImpl
+        DevImpl --> Automate
+        Automate --> TestReview1
+        TestReview1 --> Trace1
+        Trace1 -.->|next story| CreateStory
+    end
+
+    subgraph Gate["<b>EPIC/RELEASE GATE</b>"]
+        NFR["<b>TEA: *nfr-assess (if not done earlier)</b>"]
+        TestReview2["<b>TEA: *test-review (final audit, optional)</b>"]
+        TraceGate["<b>TEA: *trace - Phase 2: Gate</b>"]
+        GateDecision{"<b>Gate Decision</b>"}
+
+        NFR --> TestReview2
+        TestReview2 --> TraceGate
+        TraceGate --> GateDecision
+        GateDecision -->|PASS| Pass["<b>PASS ✅</b>"]
+        GateDecision -->|CONCERNS| Concerns["<b>CONCERNS ⚠️</b>"]
+        GateDecision -->|FAIL| Fail["<b>FAIL ❌</b>"]
+        GateDecision -->|WAIVED| Waived["<b>WAIVED ⏭️</b>"]
+    end
+
+    Phase2 --> Phase4
+    Phase4 --> Gate
+
+    style Phase2 fill:#bbdefb,stroke:#0d47a1,stroke-width:3px,color:#000
+    style Phase4 fill:#e1bee7,stroke:#4a148c,stroke-width:3px,color:#000
+    style Gate fill:#ffe082,stroke:#f57c00,stroke-width:3px,color:#000
+    style Pass fill:#4caf50,stroke:#1b5e20,stroke-width:3px,color:#000
+    style Concerns fill:#ffc107,stroke:#f57f17,stroke-width:3px,color:#000
+    style Fail fill:#f44336,stroke:#b71c1c,stroke-width:3px,color:#000
+    style Waived fill:#9c27b0,stroke:#4a148c,stroke-width:3px,color:#000
+```
+
+### TEA Integration with BMad v6 Workflow
+
+TEA operates **across all four BMad phases**, unlike other agents that are phase-specific:
+
+<details>
+<summary><strong>Cross-Phase Integration & Workflow Complexity</strong></summary>
+
+### Phase-Specific Agents (Standard Pattern)
+
+- **Phase 1 (Analysis)**: Analyst agent
+- **Phase 2 (Planning)**: PM agent
+- **Phase 3 (Solutioning)**: Architect agent
+- **Phase 4 (Implementation)**: SM, DEV agents
+
+### TEA: Cross-Phase Quality Agent (Unique Pattern)
+
+TEA is **the only agent that spans all phases**:
+
+```
+Phase 1 (Analysis) → [TEA not typically used]
+    ↓
+Phase 2 (Planning) → TEA: *framework, *ci, *test-design (setup)
+    ↓
+Phase 3 (Solutioning) → [TEA validates architecture testability]
+    ↓
+Phase 4 (Implementation) → TEA: *atdd, *automate, *test-review, *trace (per story)
+    ↓
+Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
+```
+
+### Why TEA Needs 8 Workflows
+
+**Standard agents**: 1-3 workflows per phase
+**TEA**: 8 workflows across 3+ phases
+
+| Phase       | TEA Workflows                          | Frequency        | Purpose                          |
+| ----------- | -------------------------------------- | ---------------- | -------------------------------- |
+| **Phase 2** | *framework, *ci, \*test-design         | Once per project | Establish quality infrastructure |
+| **Phase 4** | *atdd, *automate, *test-review, *trace | Per story/sprint | Continuous quality validation    |
+| **Release** | *nfr-assess, *trace (Phase 2: gate)    | Per epic/release | Go/no-go decision                |
+
+**Note**: `*trace` is a two-phase workflow: Phase 1 (traceability) + Phase 2 (gate decision). This reduces cognitive load while maintaining natural workflow.
+
+This complexity **requires specialized documentation** (this guide), **extensive knowledge base** (19+ fragments), and **unique architecture** (`testarch/` directory).
+
+</details>
+
+## Prerequisites and Setup
+
+1. Run the core planning workflows first:
+   - Analyst `*product-brief`
+   - Product Manager `*prd`
+   - Architect `*create-architecture`
+2. Confirm `bmad/bmm/config.yaml` defines `project_name`, `output_folder`, `dev_story_location`, and language settings.
+3. Ensure a test test framework setup exists; if not, use `*framework` command to create a test framework setup, prior to development.
+4. Skim supporting references (knowledge under `testarch/`, command workflows under `workflows/testarch/`).
+   - `tea-index.csv` + `knowledge/*.md`
+
+## High-Level Cheat Sheets
+
+### Greenfield Feature Launch (Level 2)
+
+| Phase              | Test Architect                                                            | Dev / Team                                                            | Outputs                                                                      |
+| ------------------ | ------------------------------------------------------------------------- | --------------------------------------------------------------------- | ---------------------------------------------------------------------------- |
+| Setup              | -                                                                         | Analyst `*product-brief`, PM `*prd`, Architect `*create-architecture` | `{output_folder}/product-brief*.md`, `PRD.md`, `epics.md`, `architecture.md` |
+| Pre-Implementation | Run `*framework` (if harness missing), `*ci`, and `*test-design`          | Review risk/design/CI guidance, align backlog                         | Test scaffold, CI pipeline, risk and coverage strategy                       |
+| Story Prep         | -                                                                         | Scrum Master `*create-story`, `*story-context`                        | Story markdown + context XML                                                 |
+| Implementation     | (Optional) Trigger `*atdd` before dev to supply failing tests + checklist | Implement story guided by ATDD checklist                              | Failing acceptance tests + implementation checklist                          |
+| Post-Dev           | Execute `*automate`, (Optional) `*test-review`, re-run `*trace`           | Address recommendations, update code/tests                            | Regression specs, quality report, refreshed coverage matrix                  |
+| Release            | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2)         | Confirm Definition of Done, share release notes                       | Quality audit, Gate YAML + release summary (owners, waivers)                 |
+
+<details>
+<summary>Execution Notes</summary>
+
+- Run `*framework` only once per repo or when modern harness support is missing.
+- `*framework` followed by `*ci` establishes install + pipeline; `*test-design` then handles risk scoring, mitigations, and scenario planning in one pass.
+- Use `*atdd` before coding when the team can adopt ATDD; share its checklist with the dev agent.
+- Post-implementation, keep `*trace` current, expand coverage with `*automate`, optionally review test quality with `*test-review`. For release gate, run `*trace` with Phase 2 enabled to get deployment decision.
+- Use `*test-review` after `*atdd` to validate generated tests, after `*automate` to ensure regression quality, or before gate for final audit.
+
+</details>
+
+<details>
+<summary>Worked Example – “Nova CRM” Greenfield Feature</summary>
+
+1. **Planning:** Analyst runs `*product-brief`; PM executes `*prd` to produce PRD and epics; Architect completes `*create-architecture` for the new module.
+2. **Setup:** TEA checks harness via `*framework`, configures `*ci`, and runs `*test-design` to capture risk/coverage plans.
+3. **Story Prep:** Scrum Master generates the story via `*create-story`; PO validates using `*solutioning-gate-check`.
+4. **Implementation:** TEA optionally runs `*atdd`; Dev implements with guidance from failing tests and the plan.
+5. **Post-Dev and Release:** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled to generate both traceability and gate decision.
+
+</details>
+
+### Brownfield Feature Enhancement (Level 3–4)
+
+| Phase             | Test Architect                                                                         | Dev / Team                                                   | Outputs                                                                 |
+| ----------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------------- |
+| Refresh Context   | -                                                                                      | Analyst/PM/Architect rerun planning workflows                | Updated planning artifacts in `{output_folder}`                         |
+| Baseline Coverage | Run `*trace` to inventory existing tests                                               | Review matrix, flag hotspots                                 | Coverage matrix + initial gate snippet                                  |
+| Risk Targeting    | Run `*test-design`                                                                     | Align remediation/backlog priorities                         | Brownfield risk memo + scenario matrix                                  |
+| Story Prep        | -                                                                                      | Scrum Master `*create-story`                                 | Updated story markdown                                                  |
+| Implementation    | (Optional) Run `*atdd` before dev                                                      | Implement story, referencing checklist/tests                 | Failing acceptance tests + implementation checklist                     |
+| Post-Dev          | Apply `*automate`, (Optional) `*test-review`, re-run `*trace`, `*nfr-assess` if needed | Resolve gaps, update docs/tests                              | Regression specs, quality report, refreshed coverage matrix, NFR report |
+| Release           | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2)                      | Product Owner `*solutioning-gate-check`, share release notes | Quality audit, Gate YAML + release summary                              |
+
+<details>
+<summary>Execution Notes</summary>
+
+- Lead with `*trace` so remediation plans target true coverage gaps. Ensure `*framework` and `*ci` are in place early in the engagement; if the brownfield lacks them, run those setup steps immediately after refreshing context.
+- `*test-design` should highlight regression hotspots, mitigations, and P0 scenarios.
+- Use `*atdd` when stories benefit from ATDD; otherwise proceed to implementation and rely on post-dev automation.
+- After development, expand coverage with `*automate`, optionally review test quality with `*test-review`, re-run `*trace` (Phase 2 for gate decision). Run `*nfr-assess` now if non-functional risks weren't addressed earlier.
+- Use `*test-review` to validate existing brownfield tests or audit new tests before gate.
+- Product Owner `*solutioning-gate-check` confirms the team has artifacts before handoff or release.
+
+</details>
+
+<details>
+<summary>Worked Example – “Atlas Payments” Brownfield Story</summary>
+
+1. **Context Refresh:** Analyst reruns `*product-brief`; PM executes `*prd` to update PRD, analysis, and `epics.md`; Architect triggers `*create-architecture` capturing legacy payment flows.
+2. **Baseline Coverage:** TEA executes `*trace` to record current coverage in `docs/qa/assessments/atlas-payment-trace.md`.
+3. **Risk and Design:** `*test-design` flags settlement edge cases, plans mitigations, and allocates new API/E2E scenarios with P0 priorities.
+4. **Story Prep:** Scrum Master generates `stories/story-1.1.md` via `*create-story`, automatically pulling updated context.
+5. **ATDD First:** TEA runs `*atdd`, producing failing Playwright specs under `tests/e2e/payments/` plus an implementation checklist.
+6. **Implementation:** Dev pairs with the checklist/tests to deliver the story.
+7. **Post-Implementation:** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` with Phase 2 enabled, performs `*nfr-assess` to validate SLAs. The `*trace` Phase 2 output marks PASS with follow-ups.
+
+</details>
+
+### Enterprise / Compliance Program (Level 4)
+
+| Phase               | Test Architect                                                    | Dev / Team                                     | Outputs                                                    |
+| ------------------- | ----------------------------------------------------------------- | ---------------------------------------------- | ---------------------------------------------------------- |
+| Strategic Planning  | -                                                                 | Analyst/PM/Architect standard workflows        | Enterprise-grade PRD, epics, architecture                  |
+| Quality Planning    | Run `*framework`, `*test-design`, `*nfr-assess`                   | Review guidance, align compliance requirements | Harness scaffold, risk + coverage plan, NFR documentation  |
+| Pipeline Enablement | Configure `*ci`                                                   | Coordinate secrets, pipeline approvals         | `.github/workflows/test.yml`, helper scripts               |
+| Execution           | Enforce `*atdd`, `*automate`, `*test-review`, `*trace` per story  | Implement stories, resolve TEA findings        | Tests, fixtures, quality reports, coverage matrices        |
+| Release             | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Capture sign-offs, archive artifacts           | Quality audit, updated assessments, gate YAML, audit trail |
+
+<details>
+<summary>Execution Notes</summary>
+
+- Use `*atdd` for every story when feasible so acceptance tests lead implementation in regulated environments.
+- `*ci` scaffolds selective testing scripts, burn-in jobs, caching, and notifications for long-running suites.
+- Enforce `*test-review` per story or sprint to maintain quality standards and ensure compliance with testing best practices.
+- Prior to release, rerun coverage (`*trace`, `*automate`), perform final quality audit with `*test-review`, and formalize the decision with `*trace` Phase 2 (gate decision); store everything for audits. Call `*nfr-assess` here if compliance/performance requirements weren't captured during planning.
+
+</details>
+
+<details>
+<summary>Worked Example – “Helios Ledger” Enterprise Release</summary>
+
+1. **Strategic Planning:** Analyst/PM/Architect complete PRD, epics, and architecture using the standard workflows.
+2. **Quality Planning:** TEA runs `*framework`, `*test-design`, and `*nfr-assess` to establish mitigations, coverage, and NFR targets.
+3. **Pipeline Setup:** TEA configures CI via `*ci` with selective execution scripts.
+4. **Execution:** For each story, TEA enforces `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings.
+5. **Release:** TEA re-checks coverage, performs final quality audit with `*test-review`, and logs the final gate decision via `*trace` Phase 2, archiving artifacts for compliance.
+
+</details>
+
+## Command Catalog
+
+<details>
+<summary><strong>Optional Playwright MCP Enhancements</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`)
+
+**How MCP Enhances TEA Workflows**:
+
+MCP provides additional capabilities on top of TEA's default AI-based approach:
+
+1. `*test-design`:
+   - Default: Analysis + documentation
+   - **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
+
+   Benefit:Discover actual functionality, edge cases, undocumented features
+
+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
+
+   Benefit: Accurate selectors from real DOM, verified behavior, refined test code
+
+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`
+
+   Benefit: Visual failure context, live DOM inspection, root cause discovery
+
+**Config example**:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    },
+    "playwright-test": {
+      "command": "npx",
+      "args": ["playwright", "run-test-mcp-server"]
+    }
+  }
+}
+```
+
+**To disable**: Set `tea_use_mcp_enhancements: false` in `bmad/bmm/config.yaml` OR remove MCPs from IDE config.
+
+</details>
+
+<br></br>
+
+| Command        | Workflow README                                   | Primary Outputs                                                                               | Notes                                                | With Playwright MCP Enhancements                                                                             |
+| -------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `*framework`   | [📖](../workflows/testarch/framework/README.md)   | Playwright/Cypress scaffold, `.env.example`, `.nvmrc`, sample specs                           | Use when no production-ready harness exists          | -                                                                                                            |
+| `*ci`          | [📖](../workflows/testarch/ci/README.md)          | CI workflow, selective test scripts, secrets checklist                                        | Platform-aware (GitHub Actions default)              | -                                                                                                            |
+| `*test-design` | [📖](../workflows/testarch/test-design/README.md) | Combined risk assessment, mitigation plan, and coverage strategy                              | Risk scoring + optional exploratory mode             | **+ Exploratory**: Interactive UI discovery with browser automation (uncover actual functionality)           |
+| `*atdd`        | [📖](../workflows/testarch/atdd/README.md)        | Failing acceptance tests + implementation checklist                                           | TDD red phase + optional recording mode              | **+ Recording**: AI generation verified with live browser (accurate selectors from real DOM)                 |
+| `*automate`    | [📖](../workflows/testarch/automate/README.md)    | 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` | [📖](../workflows/testarch/test-review/README.md) | Test quality review report with 0-100 score, violations, fixes                                | Reviews tests against knowledge base patterns        | -                                                                                                            |
+| `*nfr-assess`  | [📖](../workflows/testarch/nfr-assess/README.md)  | NFR assessment report with actions                                                            | Focus on security/performance/reliability            | -                                                                                                            |
+| `*trace`       | [📖](../workflows/testarch/trace/README.md)       | Phase 1: Coverage matrix, recommendations. Phase 2: Gate decision (PASS/CONCERNS/FAIL/WAIVED) | Two-phase workflow: traceability + gate decision     | -                                                                                                            |
+
+**📖** = Click to view detailed workflow documentation
+
+## Why TEA is Architecturally Different
+
+TEA is the only BMM agent with its own top-level module directory (`bmm/testarch/`). This intentional design pattern reflects TEA's unique requirements:
+
+<details>
+<summary><strong>Unique Architecture Pattern & Rationale</strong></summary>
+
+### Directory Structure
+
+```
+src/modules/bmm/
+├── agents/
+│   └── tea.agent.yaml          # Agent definition (standard location)
+├── workflows/
+│   └── testarch/               # TEA workflows (standard location)
+└── testarch/                   # Knowledge base (UNIQUE!)
+    ├── knowledge/              # 21 production-ready test pattern fragments
+    ├── tea-index.csv           # Centralized knowledge lookup (21 fragments indexed)
+    └── README.md               # This guide
+```
+
+### Why TEA Gets Special Treatment
+
+TEA uniquely requires **extensive domain knowledge** (21 fragments, 12,821 lines: test patterns, CI/CD, fixtures, quality practices, healing strategies), a **centralized reference system** (`tea-index.csv` for on-demand fragment loading), **cross-cutting concerns** (domain-specific patterns vs project-specific artifacts like PRDs/stories), and **optional MCP integration** (healing, exploratory, verification modes). Other BMM agents don't require this architecture.
+
+</details>

package/src/modules/bmm/docs/troubleshooting.md

@@ -30,18 +30,18 @@ flowchart TD
 
 ## Table of Contents
 
-- [Setup & Installation Issues](#setup--installation-issues)
+- [Setup and Installation Issues](#setup-and-installation-issues)
 - [Level Detection Problems](#level-detection-problems)
 - [Workflow Issues](#workflow-issues)
-- [Context & Documentation Issues](#context--documentation-issues)
+- [Context and Documentation Issues](#context-and-documentation-issues)
 - [Implementation Issues](#implementation-issues)
-- [File & Path Issues](#file--path-issues)
+- [File and Path Issues](#file-and-path-issues)
 - [Agent Behavior Issues](#agent-behavior-issues)
 - [Integration Issues (Brownfield)](#integration-issues-brownfield)
 
 ---
 
-## Setup & Installation Issues
+## Setup and Installation Issues
 
 ### Problem: BMM not found after installation
 
@@ -238,7 +238,7 @@ workflow-init asks: "Is this work in progress or previous effort?"
 
 ---
 
-## Context & Documentation Issues
+## Context and Documentation Issues
 
 ### Problem: AI agents lack codebase understanding (Brownfield)
 
@@ -393,7 +393,7 @@ For most brownfield projects, **Deep scan is sufficient**.
 
 ---
 
-## File & Path Issues
+## File and Path Issues
 
 ### Problem: Output files in wrong location