diff --git a/.github/workflows/claude-code-review.yaml b/.github/workflows/claude-code-review.yaml
new file mode 100644
index 00000000..da0b6b59
--- /dev/null
+++ b/.github/workflows/claude-code-review.yaml
@@ -0,0 +1,203 @@
+# Sample Claude Code Review Workflow
+#
+# This is a template workflow that demonstrates how to set up automated code reviews
+# using Claude via GitHub Actions. Customize the prompt and focus areas for your project.
+#
+# To use this workflow:
+# 1. Use Claude Code command in your terminal: /install-github-app , this holds your hand throughout the setup
+# 2. Copy this file over to your repository's .github/workflows/claude-code-review.yml , which gets auto-generated
+# 3. Add ANTHROPIC_API_KEY to your repository secrets
+# 4. Customize the prompt section for your project's specific needs
+# 5. Adjust the focus areas, tools, and model as needed
+
+name: Claude Code Review - BMAD Method
+
+on:
+ pull_request:
+ types: [opened, synchronize, ready_for_review, reopened]
+
+# if this branch is pushed back to back, cancel the older branch's workflow
+concurrency:
+ group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ claude-review:
+ runs-on: ubuntu-latest
+ permissions:
+ contents: read
+ pull-requests: write
+ issues: read
+ id-token: write
+
+ steps:
+ - name: Checkout repository
+ uses: actions/checkout@v4
+ with:
+ fetch-depth: 1
+
+ - name: Run Claude Code Review
+ id: claude-review
+ uses: anthropics/claude-code-action@v1
+ with:
+ # Using API key for per-token billing plan
+ anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+
+ # Track progress creates a comment showing review progress
+ track_progress: true
+
+ prompt: |
+ REPO: ${{ github.repository }}
+ PR NUMBER: ${{ github.event.pull_request.number }}
+
+ # BMAD-METHOD Repository - AI Agent Framework
+
+ IMPORTANT: Skip reviewing files in these directories:
+ - docs/ (user-facing documentation)
+ - bmad/ (compiled installation output, not source)
+ - test/fixtures/ (test data files)
+ - node_modules/ (dependencies)
+
+ **Context:** This is BMAD-CORE, a universal human-AI collaboration framework with YAML-based agent definitions and XML-tagged workflow instructions.
+
+ Perform comprehensive code review focusing on BMAD-specific patterns:
+
+ ## 1. Agent YAML Schema Compliance (CRITICAL)
+
+ **For files in `src/modules/*/agents/*.agent.yaml`:**
+ - ✅ Required fields: metadata (id, name, title, icon, module), persona (role, identity, communication_style, principles), menu items
+ - ✅ Menu triggers must reference valid workflow paths: `{project-root}/bmad/{module}/workflows/{path}/workflow.yaml`
+ - ✅ Critical actions syntax (if TEA agent): Must reference tea-index.csv and knowledge fragments
+ - ✅ Schema validation: Run `npm run validate:schemas` to verify compliance
+ - ❌ No hardcoded file paths outside {project-root} or {installed_path}
+ - ❌ No duplicate menu triggers within an agent
+
+ ## 2. Workflow Definition Integrity
+
+ **For files in `src/modules/*/workflows/**/workflow.yaml`:**
+ - ✅ Required fields: name, config_source, instructions, default_output_file (if template-based)
+ - ✅ Variable resolution: Use {config_source}, {project-root}, {installed_path}, {output_folder}
+ - ✅ Instructions path must exist: `{installed_path}/instructions.md`
+ - ✅ Template path (if template workflow): `{installed_path}/template.md`
+ - ❌ No absolute paths - use variable placeholders
+
+ **For `instructions.md` files:**
+ - ✅ XML tag syntax: ``, ``, `section`, ``
+ - ✅ Steps must have sequential numbering (1, 2, 3...)
+ - ✅ All XML tags must close properly (e.g., ``, ``)
+ - ✅ Template-output tags reference actual template sections
+ - ❌ No malformed XML that breaks workflow execution engine
+
+ ## 3. TEA Knowledge Base Integrity
+
+ **For changes in `src/modules/bmm/testarch/`:**
+ - ✅ tea-index.csv must match knowledge/ directory (21 fragments indexed)
+ - ✅ Fragment file names match csv entries exactly
+ - ✅ TEA agent critical_actions reference tea-index.csv correctly
+ - ✅ Knowledge fragments maintain consistent format
+ - ❌ Don't break the index-fragment relationship
+
+ ## 4. Documentation Consistency (Phase & Track Terminology)
+
+ **For changes in `src/modules/bmm/docs/`:**
+ - ✅ Use 3-track terminology: Quick Flow, BMad Method, Enterprise Method (not Level 0-4)
+ - ✅ Phase numbering: Phase 1 (Analysis), Phase 2 (Planning), Phase 3 (Solutioning), Phase 4 (Implementation)
+ - ✅ TEA operates in Phase 2 and Phase 4 only (not "all phases")
+ - ✅ `*test-design` is per-epic in Phase 4 (not per-project in Phase 2/3)
+ - ❌ Don't mix YAML phase numbers (0-indexed) with doc phase numbers (1-indexed) without context
+
+ **For changes in workflow-status YAML paths:**
+ - ✅ Only include phase-gate workflows (prd, architecture, sprint-planning)
+ - ❌ Don't include per-epic/per-story workflows (test-design, create-story, atdd, automate)
+ - Note: Per-epic/per-story workflows tracked in sprint-status.yaml, not workflow-status.yaml
+
+ ## 5. Cross-Module Dependencies
+
+ - ✅ Verify workflow invocations reference valid paths
+ - ✅ Module dependencies declared in installer-manifest.yaml
+ - ✅ Shared task references resolve correctly
+ - ❌ No circular dependencies between modules
+
+ ## 6. Compilation & Installation
+
+ **For changes affecting `tools/cli/`:**
+ - ✅ Agent compilation: YAML → Markdown/XML for both IDE and web bundle targets
+ - ✅ forWebBundle flag changes compilation behavior (inline vs file paths)
+ - ✅ Manifest generation creates agent-manifest.csv and workflow-manifest.csv
+ - ✅ Platform-specific hooks execute for IDE integrations
+
+ ## 7. Code Quality (Node.js/JavaScript)
+
+ - ✅ Modern JavaScript (ES6+, async/await, proper error handling)
+ - ✅ Schema validation with Zod where applicable
+ - ✅ Proper YAML parsing with js-yaml
+ - ✅ File operations use fs-extra for better error handling
+ - ❌ No synchronous file I/O in async contexts
+
+ ## Review Guidelines
+
+ - Reference CLAUDE.md for repository architecture
+ - Check CONTRIBUTING.md for contribution guidelines
+ - **Validation commands** (deterministic tests):
+ - `npm test` - Comprehensive quality checks (all validations + linting + formatting)
+ - `npm run test:schemas` - Agent schema validation tests (fixture-based)
+ - `npm run test:install` - Installation component tests (compilation)
+ - `npm run validate:schemas` - YAML schema validation
+ - `npm run validate:bundles` - Web bundle integrity
+ - `npm run lint` - ESLint compliance
+ - `npm run format:check` - Prettier formatting
+ - Prioritize issues: **Critical** (breaks workflows/compilation) > **High** (schema violations) > **Medium** (inconsistency) > **Low** (style)
+ - Be specific with file paths and line numbers
+
+ Use `gh pr comment` with your Bash tool to leave your review as a comment on the PR.
+
+ # Using Sonnet 4.5 for comprehensive reviews
+ # Available models: claude-opus-4-1-20250805, claude-sonnet-4-5-20250929, etc.
+ # Tools can be restricted based on what review actions you want to allow
+ claude_args: '--model claude-sonnet-4-5-20250929 --allowed-tools "mcp__github_inline_comment__create_inline_comment,Bash(gh issue view:*),Bash(gh search:*),Bash(gh issue list:*),Bash(gh pr comment:*),Bash(gh pr diff:*),Bash(gh pr view:*),Bash(gh pr list:*)"'
+
+ # SETUP INSTRUCTIONS
+# ==================
+#
+# 1. Repository Secrets Setup:
+# - Go to your repository � Settings � Secrets and variables � Actions
+# - Click "New repository secret"
+# - Name: ANTHROPIC_API_KEY
+# - Value: Your Anthropic API key (get one from https://console.anthropic.com/)
+#
+# 2. Permissions:
+# - The workflow needs 'pull-requests: write' to comment on PRs
+# - The workflow needs 'contents: read' to access repository code
+# - The workflow needs 'issues: read' for GitHub CLI operations
+#
+# 3. Customization:
+# - Update the prompt section to match your project's needs
+# - Add project-specific file/directory exclusions
+# - Customize the focus areas based on your tech stack
+# - Adjust the model (opus for more thorough reviews, sonnet for faster)
+# - Modify allowed tools based on what actions you want Claude to perform
+#
+# 4. Testing:
+# - Create a test PR to verify the workflow runs correctly
+# - Check that Claude can comment on the PR
+# - Ensure the review quality meets your standards
+#
+# 5. Advanced Customization:
+# - Add conditional logic based on file types or changes
+# - Integrate with other GitHub Actions (linting, testing, etc.)
+# - Set up different review levels based on PR size or author
+# - Add custom review templates for different types of changes
+#
+# TROUBLESHOOTING
+# ===============
+#
+# Common Issues:
+# - "Authentication failed" � Check ANTHROPIC_API_KEY secret
+# - "Permission denied" � Verify workflow permissions in job definition
+# - "No comments posted" � Check allowed tools and gh CLI permissions
+# - "Review too generic" � Customize prompt with project-specific guidance
+#
+# For more help:
+# - GitHub Actions documentation: https://docs.github.com/en/actions
+# - Claude Code Action: https://github.com/anthropics/claude-code-action
+# - Anthropic API documentation: https://docs.anthropic.com/
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
deleted file mode 100644
index 6d8fab2a..00000000
--- a/.github/workflows/lint.yaml
+++ /dev/null
@@ -1,61 +0,0 @@
-name: lint
-
-"on":
- pull_request:
- branches: ["**"]
- workflow_dispatch:
-
-jobs:
- prettier:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup Node
- uses: actions/setup-node@v4
- with:
- node-version-file: ".nvmrc"
- cache: "npm"
-
- - name: Install dependencies
- run: npm ci
-
- - name: Prettier format check
- run: npm run format:check
-
- eslint:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup Node
- uses: actions/setup-node@v4
- with:
- node-version-file: ".nvmrc"
- cache: "npm"
-
- - name: Install dependencies
- run: npm ci
-
- - name: ESLint
- run: npm run lint
-
- schema-validation:
- runs-on: ubuntu-latest
- steps:
- - name: Checkout
- uses: actions/checkout@v4
-
- - name: Setup Node
- uses: actions/setup-node@v4
- with:
- node-version-file: ".nvmrc"
- cache: "npm"
-
- - name: Install dependencies
- run: npm ci
-
- - name: Validate YAML schemas
- run: npm run validate:schemas
diff --git a/.github/workflows/quality.yaml b/.github/workflows/quality.yaml
new file mode 100644
index 00000000..7a32718b
--- /dev/null
+++ b/.github/workflows/quality.yaml
@@ -0,0 +1,123 @@
+name: Quality & Validation
+
+# Runs comprehensive quality checks on all PRs:
+# - Prettier (formatting)
+# - ESLint (linting)
+# - Schema validation (YAML structure)
+# - Agent schema tests (fixture-based validation)
+# - Installation component tests (compilation)
+# - Bundle validation (web bundle integrity)
+
+"on":
+ pull_request:
+ branches: ["**"]
+ workflow_dispatch:
+
+jobs:
+ prettier:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Prettier format check
+ run: npm run format:check
+
+ eslint:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: ESLint
+ run: npm run lint
+
+ schema-validation:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Validate YAML schemas
+ run: npm run validate:schemas
+
+ agent-schema-tests:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Run agent schema validation tests
+ run: npm run test:schemas
+
+ installation-components:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Test agent compilation components
+ run: npm run test:install
+
+ bundle-validation:
+ runs-on: ubuntu-latest
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v4
+
+ - name: Setup Node
+ uses: actions/setup-node@v4
+ with:
+ node-version-file: ".nvmrc"
+ cache: "npm"
+
+ - name: Install dependencies
+ run: npm ci
+
+ - name: Validate web bundles
+ run: npm run validate:bundles
diff --git a/.husky/pre-commit b/.husky/pre-commit
index 7e617c2c..1397d511 100755
--- a/.husky/pre-commit
+++ b/.husky/pre-commit
@@ -1,3 +1,7 @@
#!/usr/bin/env sh
+# Auto-fix changed files and stage them
npx --no-install lint-staged
+
+# Validate everything
+npm test
diff --git a/README.md b/README.md
index e9151d4e..d9e8c690 100644
--- a/README.md
+++ b/README.md
@@ -35,11 +35,15 @@ The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but yo
- [C.O.R.E. Philosophy](#core-philosophy)
- [Modules](#modules)
- [BMad Method (BMM) - AI-Driven Agile Development](#bmad-method-bmm---ai-driven-agile-development)
+ - [v6 Highlights](#v6-highlights)
+ - [🚀 Quick Start](#-quick-start)
- [BMad Builder (BMB) - Create Custom Solutions](#bmad-builder-bmb---create-custom-solutions)
- [Creative Intelligence Suite (CIS) - Innovation \& Creativity](#creative-intelligence-suite-cis---innovation--creativity)
- - [🚀 Quick Start](#-quick-start)
- [Installation](#installation)
- [🎯 Working with Agents \& Commands](#-working-with-agents--commands)
+ - [Method 1: Agent Menu (Recommended for Beginners)](#method-1-agent-menu-recommended-for-beginners)
+ - [Method 2: Direct Slash Commands](#method-2-direct-slash-commands)
+ - [Method 3: Party Mode Execution](#method-3-party-mode-execution)
- [Key Features](#key-features)
- [🎨 Update-Safe Customization](#-update-safe-customization)
- [🚀 Intelligent Installation](#-intelligent-installation)
@@ -47,6 +51,10 @@ The **BMad-CORE** powers the **BMad Method** (probably why you're here!), but yo
- [📄 Document Sharding (Advanced)](#-document-sharding-advanced)
- [Documentation](#documentation)
- [Community \& Support](#community--support)
+ - [Development \& Quality Checks](#development--quality-checks)
+ - [Testing \& Validation](#testing--validation)
+ - [Code Quality](#code-quality)
+ - [Build \& Development](#build--development)
- [Contributing](#contributing)
- [License](#license)
@@ -352,6 +360,56 @@ Optional optimization for large projects (BMad Method and Enterprise tracks):
---
+## Development & Quality Checks
+
+**For contributors working on the BMAD codebase:**
+
+**Requirements:** Node.js 22+ (see `.nvmrc`). Run `nvm use` to switch to the correct version.
+
+### Testing & Validation
+
+```bash
+# Run all quality checks (comprehensive - use before pushing)
+npm test
+
+# Individual test suites
+npm run test:schemas # Agent schema validation (fixture-based)
+npm run test:install # Installation component tests (compilation)
+npm run validate:schemas # YAML schema validation
+npm run validate:bundles # Web bundle integrity
+```
+
+### Code Quality
+
+```bash
+# Lint check
+npm run lint
+
+# Auto-fix linting issues
+npm run lint:fix
+
+# Format check
+npm run format:check
+
+# Auto-format all files
+npm run format:fix
+```
+
+### Build & Development
+
+```bash
+# Bundle for web deployment
+npm run bundle
+
+# Test local installation
+npm run install:bmad
+```
+
+**Pre-commit Hook:** Auto-fixes changed files (lint-staged) + validates everything (npm test)
+**CI:** GitHub Actions runs all quality checks in parallel on every PR
+
+---
+
## Contributing
We welcome contributions! See **[CONTRIBUTING.md](CONTRIBUTING.md)** for:
diff --git a/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml b/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml
index 7e4d0d73..a05527b1 100644
--- a/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml
+++ b/bmad/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml
@@ -77,26 +77,33 @@ phases:
output: "Integration architecture with enterprise considerations"
note: "Distills brownfield context + adds security/scalability/compliance design"
+ - id: "framework"
+ optional: true
+ agent: "tea"
+ command: "framework"
+ output: "Test framework scaffold (Playwright/Cypress)"
+ note: "Modernize test framework AFTER architecture defines integration approach"
+
+ - id: "ci"
+ optional: true
+ agent: "tea"
+ command: "ci"
+ output: "CI/CD test pipeline configuration"
+ note: "Configure CI pipeline AFTER architecture and framework decisions"
+
- id: "create-security-architecture"
- required: true
+ optional: true
agent: "architect"
command: "create-security-architecture"
output: "Security architecture for brownfield integration"
- note: "Future workflow - threat model, auth integration, audit requirements"
+ note: "Future workflow - optional extended enterprise workflow for threat model, auth integration, audit requirements"
- id: "create-devops-strategy"
- required: true
+ optional: true
agent: "architect"
command: "create-devops-strategy"
output: "DevOps strategy for brownfield deployment"
- note: "Future workflow - CI/CD integration, deployment strategy, monitoring"
-
- - id: "create-test-strategy"
- required: true
- agent: "tea"
- command: "create-test-strategy"
- output: "Test strategy including regression testing"
- note: "Future workflow - critical for brownfield to prevent breaking existing functionality"
+ note: "Future workflow - optional extended enterprise workflow for CI/CD integration, deployment strategy, monitoring"
- id: "validate-architecture"
optional: true
diff --git a/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml b/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml
index f5584d2c..bb743071 100644
--- a/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml
+++ b/bmad/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml
@@ -65,26 +65,33 @@ phases:
output: "Enterprise-grade system architecture"
note: "Includes scalability, multi-tenancy, integration architecture"
+ - id: "framework"
+ optional: true
+ agent: "tea"
+ command: "framework"
+ output: "Test framework scaffold (Playwright/Cypress)"
+ note: "Initialize test framework AFTER architecture defines technology stack"
+
+ - id: "ci"
+ optional: true
+ agent: "tea"
+ command: "ci"
+ output: "CI/CD test pipeline configuration"
+ note: "Configure CI pipeline AFTER architecture and framework choices are made"
+
- id: "create-security-architecture"
- required: true
+ optional: true
agent: "architect"
command: "create-security-architecture"
output: "Security architecture and threat model"
- note: "Future workflow - security design, auth, compliance"
+ note: "Future workflow - optional extended enterprise workflow for security design, auth, compliance"
- id: "create-devops-strategy"
- required: true
+ optional: true
agent: "architect"
command: "create-devops-strategy"
output: "DevOps pipeline and infrastructure plan"
- note: "Future workflow - CI/CD, deployment, monitoring"
-
- - id: "create-test-strategy"
- required: true
- agent: "tea"
- command: "create-test-strategy"
- output: "Comprehensive test strategy"
- note: "Future workflow - test approach, automation, quality gates"
+ note: "Future workflow - optional extended enterprise workflow for CI/CD, deployment, monitoring"
- id: "validate-architecture"
optional: true
diff --git a/package-lock.json b/package-lock.json
index 4de233c1..c7a06422 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "bmad-method",
- "version": "6.0.0-alpha.5",
+ "version": "6.0.0-alpha.6",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "bmad-method",
- "version": "6.0.0-alpha.5",
+ "version": "6.0.0-alpha.6",
"license": "MIT",
"dependencies": {
"@kayvan/markdown-tree-parser": "^1.6.1",
diff --git a/package.json b/package.json
index eb9a75c0..41f56180 100644
--- a/package.json
+++ b/package.json
@@ -39,8 +39,10 @@
"release:minor": "gh workflow run \"Manual Release\" -f version_bump=minor",
"release:patch": "gh workflow run \"Manual Release\" -f version_bump=patch",
"release:watch": "gh run watch",
- "test": "node test/test-agent-schema.js",
- "test:coverage": "c8 --reporter=text --reporter=html node test/test-agent-schema.js",
+ "test": "npm run test:schemas && npm run test:install && npm run validate:bundles && npm run validate:schemas && npm run lint && npm run format:check",
+ "test:coverage": "c8 --reporter=text --reporter=html npm run test:schemas",
+ "test:install": "node test/test-installation-components.js",
+ "test:schemas": "node test/test-agent-schema.js",
"validate:bundles": "node tools/validate-bundles.js",
"validate:schemas": "node tools/validate-agent-schema.js"
},
diff --git a/src/modules/bmm/docs/test-architecture.md b/src/modules/bmm/docs/test-architecture.md
index 1e9dcb59..57d3eca6 100644
--- a/src/modules/bmm/docs/test-architecture.md
+++ b/src/modules/bmm/docs/test-architecture.md
@@ -1,5 +1,5 @@
---
-last-redoc-date: 2025-10-14
+last-redoc-date: 2025-11-05
---
# Test Architect (TEA) Agent Guide
@@ -7,29 +7,37 @@ last-redoc-date: 2025-10-14
## 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.
+- **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)
## TEA Workflow Lifecycle
-TEA integrates across the entire BMad development lifecycle, providing quality assurance at every phase:
+TEA integrates into the BMad development lifecycle during Solutioning (Phase 3) and Implementation (Phase 4):
```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["Phase 2: PLANNING"]
- PM["PM: *prd"]
- Framework["TEA: *framework"]
- CI["TEA: *ci"]
- TestDesign["TEA: *test-design"]
- PM --> Framework
- Framework --> CI
- CI --> TestDesign
- SetupNote["Setup once per project"]
- TestDesign -.-> SetupNote
+ PM["PM: *prd (creates PRD + epics)"]
+ PlanNote["Business requirements phase"]
+ PM -.-> PlanNote
end
- subgraph Phase4["Phase 4: IMPLEMENTATION - Per Story Cycle"]
+ subgraph Phase3["Phase 3: SOLUTIONING"]
+ Architecture["Architect: *architecture"]
+ Framework["TEA: *framework"]
+ CI["TEA: *ci"]
+ GateCheck["Architect: *solutioning-gate-check"]
+ Architecture --> Framework
+ Framework --> CI
+ CI --> GateCheck
+ Phase3Note["Test infrastructure AFTER architecture
defines technology stack"]
+ Framework -.-> Phase3Note
+ end
+
+ subgraph Phase4["Phase 4: IMPLEMENTATION - Per Epic Cycle"]
+ SprintPlan["SM: *sprint-planning"]
+ TestDesign["TEA: *test-design (per epic)"]
CreateStory["SM: *create-story"]
ATDD["TEA: *atdd (optional, before dev)"]
DevImpl["DEV: implements story"]
@@ -37,12 +45,16 @@ graph TB
TestReview1["TEA: *test-review (optional)"]
Trace1["TEA: *trace (refresh coverage)"]
+ SprintPlan --> TestDesign
+ TestDesign --> CreateStory
CreateStory --> ATDD
ATDD --> DevImpl
DevImpl --> Automate
Automate --> TestReview1
TestReview1 --> Trace1
Trace1 -.->|next story| CreateStory
+ TestDesignNote["Test design: 'How do I test THIS epic?'
Creates test-design-epic-N.md per epic"]
+ TestDesign -.-> TestDesignNote
end
subgraph Gate["EPIC/RELEASE GATE"]
@@ -60,10 +72,12 @@ graph TB
GateDecision -->|WAIVED| Waived["WAIVED ⏭️"]
end
- Phase2 --> Phase4
+ Phase2 --> Phase3
+ Phase3 --> Phase4
Phase4 --> Gate
style Phase2 fill:#bbdefb,stroke:#0d47a1,stroke-width:3px,color:#000
+ style Phase3 fill:#c8e6c9,stroke:#2e7d32,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
@@ -72,82 +86,129 @@ graph TB
style Waived fill:#9c27b0,stroke:#4a148c,stroke-width:3px,color:#000
```
-### TEA Integration with BMad v6 Workflow
+**Phase Numbering Note:** BMad uses a 4-phase methodology with optional Phase 0/1:
-TEA operates **across all four BMad phases**, unlike other agents that are phase-specific:
+- **Phase 0** (Optional): Documentation (brownfield prerequisite - `*document-project`)
+- **Phase 1** (Optional): Discovery/Analysis (`*brainstorm`, `*research`, `*product-brief`)
+- **Phase 2** (Required): Planning (`*prd` creates PRD + epics)
+- **Phase 3** (Track-dependent): Solutioning (`*architecture` → TEA: `*framework`, `*ci` → `*solutioning-gate-check`)
+- **Phase 4** (Required): Implementation (`*sprint-planning` → per-epic: `*test-design` → per-story: dev workflows)
+
+**TEA workflows:** `*framework` and `*ci` run once in Phase 3 after architecture. `*test-design` runs per-epic in Phase 4. Output: `test-design-epic-N.md`.
+
+Quick Flow track skips Phases 0, 1, and 3. BMad Method and Enterprise use all phases based on project needs.
+
+### 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**.
-Cross-Phase Integration & Workflow Complexity
+Cross-Phase Operation & Unique Architecture
### Phase-Specific Agents (Standard Pattern)
+Most BMM agents work in a single phase:
+
- **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: Multi-Phase Quality Agent (Unique Pattern)
-TEA is **the only agent that spans all phases**:
+TEA is **the only agent that operates in multiple phases**:
```
Phase 1 (Analysis) → [TEA not typically used]
↓
-Phase 2 (Planning) → TEA: *framework, *ci, *test-design (setup)
+Phase 2 (Planning) → [PM defines requirements - TEA not active]
↓
-Phase 3 (Solutioning) → [TEA validates architecture testability]
+Phase 3 (Solutioning) → TEA: *framework, *ci (test infrastructure AFTER architecture)
↓
-Phase 4 (Implementation) → TEA: *atdd, *automate, *test-review, *trace (per story)
+Phase 4 (Implementation) → TEA: *test-design (per epic: "how do I test THIS feature?")
+ → TEA: *atdd, *automate, *test-review, *trace (per story)
↓
Epic/Release Gate → TEA: *nfr-assess, *trace Phase 2 (release decision)
```
-### Why TEA Needs 8 Workflows
+### TEA's 8 Workflows Across Phases
**Standard agents**: 1-3 workflows per phase
-**TEA**: 8 workflows across 3+ phases
+**TEA**: 8 workflows across Phase 3, Phase 4, and Release Gate
-| 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 |
+| Phase | TEA Workflows | Frequency | Purpose |
+| ----------- | ----------------------------------------------------- | ---------------- | ---------------------------------------------- |
+| **Phase 2** | (none) | - | Planning phase - PM defines requirements |
+| **Phase 3** | *framework, *ci | Once per project | Setup test infrastructure AFTER architecture |
+| **Phase 4** | *test-design, *atdd, *automate, *test-review, \*trace | Per epic/story | Test planning per epic, then per-story testing |
+| **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).
+### Unique Directory Architecture
+
+TEA is the only BMM agent with its own top-level module directory (`bmm/testarch/`):
+
+```
+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 covering test patterns, CI/CD, fixtures, quality practices, healing strategies
+- **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 MCP integration**: Healing, exploratory, and verification modes for enhanced testing capabilities
+
+This architecture enables TEA to maintain consistent, production-ready testing patterns across all BMad projects while operating across multiple development phases.
-## 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)
+These cheat sheets map TEA workflows to the **BMad Method and Enterprise tracks** across the **4-Phase Methodology** (Phase 1: Analysis, Phase 2: Planning, Phase 3: Solutioning, Phase 4: Implementation).
-| 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) |
+**Note:** Quick Flow projects typically don't require TEA (covered in Overview). These cheat sheets focus on BMad Method and Enterprise tracks where TEA adds value.
+
+**Legend for Track Deltas:**
+
+- ➕ = New workflow or phase added (doesn't exist in baseline)
+- 🔄 = Modified focus (same workflow, different emphasis or purpose)
+- 📦 = Additional output or archival requirement
+
+### Greenfield - BMad Method (Simple/Standard Work)
+
+**Planning Track:** BMad Method (PRD + Architecture)
+**Use Case:** New projects with standard complexity
+
+| Workflow Stage | Test Architect | Dev / Team | Outputs |
+| -------------------------- | ----------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------- |
+| **Phase 1**: Discovery | - | Analyst `*product-brief` (optional) | `product-brief.md` |
+| **Phase 2**: Planning | - | PM `*prd` (creates PRD + epics) | PRD, epics |
+| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture | Architect `*architecture`, `*solutioning-gate-check` | Architecture, test scaffold, 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 (per-epic test plan) | Review epic scope | `test-design-epic-N.md` with risk assessment and test plan |
+| **Phase 4**: Story Dev | (Optional) `*atdd` before dev, then `*automate` after | SM `*create-story`, DEV implements | Tests, story implementation |
+| **Phase 4**: Story Review | Execute `*test-review` (optional), re-run `*trace` | Address recommendations, update code/tests | Quality report, refreshed coverage matrix |
+| **Phase 4**: Release Gate | (Optional) `*test-review` for final audit, Run `*trace` (Phase 2) | Confirm Definition of Done, share release notes | Quality audit, Gate YAML + release summary |
Execution Notes
- 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.
+- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` to setup test infrastructure based on architectural decisions.
+- **Phase 4 starts**: After solutioning is complete, sprint planning loads all epics.
+- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to create a test plan for THAT specific epic/feature. Output: `test-design-epic-N.md`.
- 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.
@@ -157,79 +218,110 @@ This complexity **requires specialized documentation** (this guide), **extensive
Worked Example – “Nova CRM” Greenfield Feature
-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.
+1. **Planning (Phase 2):** Analyst runs `*product-brief`; PM executes `*prd` to produce PRD and epics.
+2. **Solutioning (Phase 3):** Architect completes `*architecture` for the new module; TEA sets up test infrastructure via `*framework` and `*ci` based on architectural decisions; gate check validates planning completeness.
+3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load all epics into sprint status.
+4. **Epic 1 Planning (Phase 4):** TEA runs `*test-design` to create test plan for Epic 1, producing `test-design-epic-1.md` with risk assessment.
+5. **Story Implementation (Phase 4):** For each story in Epic 1, SM generates story via `*create-story`; TEA optionally runs `*atdd`; Dev implements with guidance from failing tests.
+6. **Post-Dev (Phase 4):** TEA runs `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` to refresh coverage.
+7. **Release Gate:** TEA runs `*trace` with Phase 2 enabled to generate gate decision.
-### Brownfield Feature Enhancement (Level 3–4)
+### Brownfield - BMad Method or Enterprise (Simple or Complex)
-| 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 |
+**Planning Tracks:** BMad Method or Enterprise Method
+**Use Case:** Existing codebases - simple additions (BMad Method) or complex enterprise requirements (Enterprise Method)
+
+**🔄 Brownfield Deltas from Greenfield:**
+
+- ➕ Phase 0 (Documentation) - Document existing codebase if undocumented
+- ➕ Phase 2: `*trace` - Baseline existing test coverage before planning
+- 🔄 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 |
+| ----------------------------- | ---------------------------------------------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------- |
+| **Phase 0**: Documentation ➕ | - | 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 + epics) | PRD, epics, ➕ coverage baseline |
+| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture | Architect `*architecture`, `*solutioning-gate-check` | Architecture, 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 |
Execution Notes
-- 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.
+- Lead with `*trace` during Planning (Phase 2) to baseline existing test coverage before architecture work begins.
+- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` to modernize test infrastructure. For brownfield, framework may need to integrate with or replace existing test setup.
+- **Phase 4 starts**: After solutioning is complete and sprint planning loads all epics.
+- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to identify regression hotspots, integration risks, and mitigation strategies for THAT specific epic/feature. Output: `test-design-epic-N.md`.
- 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.
Worked Example – “Atlas Payments” Brownfield Story
-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.
+1. **Planning (Phase 2):** PM executes `*prd` to update PRD and `epics.md` (Epic 1: Payment Processing); TEA runs `*trace` to baseline existing coverage.
+2. **Solutioning (Phase 3):** Architect triggers `*architecture` capturing legacy payment flows and integration architecture; TEA sets up `*framework` and `*ci` based on architectural decisions; gate check validates planning.
+3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load Epic 1 into sprint status.
+4. **Epic 1 Planning (Phase 4):** TEA runs `*test-design` for Epic 1 (Payment Processing), producing `test-design-epic-1.md` that flags settlement edge cases, regression hotspots, and mitigation plans.
+5. **Story Implementation (Phase 4):** For each story in Epic 1, SM generates story via `*create-story`; TEA runs `*atdd` producing failing Playwright specs; Dev implements with guidance from tests and checklist.
+6. **Post-Dev (Phase 4):** TEA applies `*automate`, optionally `*test-review` to audit test quality, re-runs `*trace` to refresh coverage.
+7. **Release Gate:** TEA performs `*nfr-assess` to validate SLAs, runs `*trace` with Phase 2 enabled to generate gate decision (PASS/CONCERNS/FAIL).
-### Enterprise / Compliance Program (Level 4)
+### Greenfield - Enterprise Method (Enterprise/Compliance Work)
-| 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 |
+**Planning Track:** Enterprise Method (BMad Method + extended security/devops/test strategies)
+**Use Case:** New enterprise projects with compliance, security, or complex regulatory requirements
+
+**🏢 Enterprise Deltas from BMad Method:**
+
+- ➕ Phase 1: `*research` - Domain and compliance research (recommended)
+- ➕ Phase 2: `*nfr-assess` - Capture NFR requirements early (security/performance/reliability)
+- 🔄 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 + epics), UX `*create-design` | Enterprise PRD, epics, UX design, ➕ NFR documentation |
+| **Phase 3**: Solutioning | Run `*framework`, `*ci` AFTER architecture | Architect `*architecture`, `*solutioning-gate-check` | Architecture, 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 |
Execution Notes
-- 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.
+- `*nfr-assess` runs early in Planning (Phase 2) to capture compliance, security, and performance requirements upfront.
+- **Phase 3 (Solutioning)**: After architecture is complete, run `*framework` and `*ci` with enterprise-grade configurations (selective testing, burn-in jobs, caching, notifications).
+- **Phase 4 starts**: After solutioning is complete and sprint planning loads all epics.
+- **`*test-design` runs per-epic**: At the beginning of working on each epic, run `*test-design` to create an enterprise-focused test plan for THAT specific epic, ensuring alignment with security architecture, performance targets, and compliance requirements. Output: `test-design-epic-N.md`.
+- Use `*atdd` for stories when feasible so acceptance tests can lead implementation.
+- Use `*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); archive artifacts for compliance audits.
Worked Example – “Helios Ledger” Enterprise Release
-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.
+1. **Planning (Phase 2):** Analyst runs `*research` and `*product-brief`; PM completes `*prd` creating PRD and epics; TEA runs `*nfr-assess` to establish NFR targets.
+2. **Solutioning (Phase 3):** Architect completes `*architecture` with enterprise considerations; TEA sets up `*framework` and `*ci` with enterprise-grade configurations based on architectural decisions; gate check validates planning completeness.
+3. **Sprint Start (Phase 4):** Scrum Master runs `*sprint-planning` to load all epics into sprint status.
+4. **Per-Epic (Phase 4):** For each epic, TEA runs `*test-design` to create epic-specific test plan (e.g., `test-design-epic-1.md`, `test-design-epic-2.md`) with compliance-focused risk assessment.
+5. **Per-Story (Phase 4):** For each story, TEA uses `*atdd`, `*automate`, `*test-review`, and `*trace`; Dev teams iterate on the findings.
+6. **Release Gate:** 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.
@@ -251,7 +343,7 @@ MCP provides additional capabilities on top of TEA's default AI-based approach:
- Default: Analysis + documentation
- **+ MCP**: Interactive UI discovery with `browser_navigate`, `browser_click`, `browser_snapshot`, behavior observation
- Benefit:Discover actual functionality, edge cases, undocumented features
+ Benefit: Discover actual functionality, edge cases, undocumented features
2. `*atdd`, `*automate`:
- Default: Infers selectors and interactions from requirements and knowledge fragments
@@ -300,30 +392,3 @@ MCP provides additional capabilities on top of TEA's default AI-based approach:
| `*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:
-
-
-Unique Architecture Pattern & Rationale
-
-### 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.
-
-
diff --git a/src/modules/bmm/docs/workflows-solutioning.md b/src/modules/bmm/docs/workflows-solutioning.md
index 875301ff..f1a38e18 100644
--- a/src/modules/bmm/docs/workflows-solutioning.md
+++ b/src/modules/bmm/docs/workflows-solutioning.md
@@ -32,9 +32,8 @@ graph TB
subgraph Optional["ENTERPRISE ADDITIONS (Optional)"]
direction LR
- TestArch["TEA: test-architecture
(Future)"]
- SecArch["Architect: security-architecture"]
- DevOps["Architect: devops-strategy"]
+ SecArch["Architect: security-architecture
(Future)"]
+ DevOps["Architect: devops-strategy
(Future)"]
end
GateCheck["Architect: solutioning-gate-check
Validation before Phase 4"]
@@ -69,7 +68,6 @@ graph TB
style SkipArch fill:#aed581,stroke:#1b5e20,stroke-width:2px,color:#000
style Architecture fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
- style TestArch fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
style SecArch fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
style DevOps fill:#ef9a9a,stroke:#c62828,stroke-width:2px,color:#000
style GateCheck fill:#42a5f5,stroke:#0d47a1,stroke-width:2px,color:#000
@@ -352,13 +350,14 @@ Planning (prd by PM)
```
Planning (prd by PM - same as BMad Method)
→ architecture (Architect)
- → Optional: test-architecture (TEA, future)
- → Optional: security-architecture (Architect)
- → Optional: devops-strategy (Architect)
+ → Optional: security-architecture (Architect, future)
+ → Optional: devops-strategy (Architect, future)
→ solutioning-gate-check (Architect)
→ Phase 4 (Implementation)
```
+**Note on TEA (Test Architect):** TEA is fully operational with 8 workflows across all phases. TEA validates architecture testability during Phase 3 reviews but does not have a dedicated solutioning workflow. TEA's primary setup occurs in Phase 2 (`*framework`, `*ci`, `*test-design`) and testing execution in Phase 4 (`*atdd`, `*automate`, `*test-review`, `*trace`, `*nfr-assess`).
+
**Note:** Enterprise uses the same planning and architecture as BMad Method. The only difference is optional extended workflows added AFTER architecture but BEFORE gate check.
### Solutioning → Implementation Handoff
@@ -422,11 +421,13 @@ Architecture documents are living. Update them as you learn during implementatio
### Enterprise
- **Planning:** prd (PM) - same as BMad Method
-- **Solutioning:** architecture (Architect) → Optional extended workflows (test-architecture, security-architecture, devops-strategy) → solutioning-gate-check (Architect)
+- **Solutioning:** architecture (Architect) → Optional extended workflows (security-architecture, devops-strategy) → solutioning-gate-check (Architect)
- **Implementation:** sprint-planning → epic-tech-context → dev-story
**Key Difference:** Enterprise adds optional extended workflows AFTER architecture but BEFORE gate check. Everything else is identical to BMad Method.
+**Note:** TEA (Test Architect) operates across all phases and validates architecture testability but is not a Phase 3-specific workflow. See [Test Architecture Guide](./test-architecture.md) for TEA's full lifecycle integration.
+
---
## Common Anti-Patterns
diff --git a/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml
index 7e4d0d73..a1cedcac 100644
--- a/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml
+++ b/src/modules/bmm/workflows/workflow-status/paths/enterprise-brownfield.yaml
@@ -66,6 +66,20 @@ phases:
command: "create-design"
note: "Recommended - must integrate with existing UX patterns"
+ - id: "framework"
+ optional: true
+ agent: "tea"
+ command: "framework"
+ output: "Test framework scaffold (Playwright/Cypress)"
+ note: "Initialize or modernize test framework - critical if brownfield lacks proper test infrastructure"
+
+ - id: "ci"
+ optional: true
+ agent: "tea"
+ command: "ci"
+ output: "CI/CD test pipeline configuration"
+ note: "Establish or enhance CI pipeline with regression testing strategy"
+
- phase: 2
name: "Solutioning"
required: true
@@ -78,25 +92,18 @@ phases:
note: "Distills brownfield context + adds security/scalability/compliance design"
- id: "create-security-architecture"
- required: true
+ optional: true
agent: "architect"
command: "create-security-architecture"
output: "Security architecture for brownfield integration"
- note: "Future workflow - threat model, auth integration, audit requirements"
+ note: "Future workflow - optional extended enterprise workflow for threat model, auth integration, audit requirements"
- id: "create-devops-strategy"
- required: true
+ optional: true
agent: "architect"
command: "create-devops-strategy"
output: "DevOps strategy for brownfield deployment"
- note: "Future workflow - CI/CD integration, deployment strategy, monitoring"
-
- - id: "create-test-strategy"
- required: true
- agent: "tea"
- command: "create-test-strategy"
- output: "Test strategy including regression testing"
- note: "Future workflow - critical for brownfield to prevent breaking existing functionality"
+ note: "Future workflow - optional extended enterprise workflow for CI/CD integration, deployment strategy, monitoring"
- id: "validate-architecture"
optional: true
diff --git a/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml b/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml
index f5584d2c..47028ae9 100644
--- a/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml
+++ b/src/modules/bmm/workflows/workflow-status/paths/enterprise-greenfield.yaml
@@ -54,6 +54,20 @@ phases:
command: "create-design"
note: "Highly recommended for enterprise - design system and patterns"
+ - id: "framework"
+ optional: true
+ agent: "tea"
+ command: "framework"
+ output: "Test framework scaffold (Playwright/Cypress)"
+ note: "Initialize production-ready test framework - run once per project"
+
+ - id: "ci"
+ optional: true
+ agent: "tea"
+ command: "ci"
+ output: "CI/CD test pipeline configuration"
+ note: "Scaffold CI workflow with selective testing, burn-in, caching"
+
- phase: 2
name: "Solutioning"
required: true
@@ -66,25 +80,18 @@ phases:
note: "Includes scalability, multi-tenancy, integration architecture"
- id: "create-security-architecture"
- required: true
+ optional: true
agent: "architect"
command: "create-security-architecture"
output: "Security architecture and threat model"
- note: "Future workflow - security design, auth, compliance"
+ note: "Future workflow - optional extended enterprise workflow for security design, auth, compliance"
- id: "create-devops-strategy"
- required: true
+ optional: true
agent: "architect"
command: "create-devops-strategy"
output: "DevOps pipeline and infrastructure plan"
- note: "Future workflow - CI/CD, deployment, monitoring"
-
- - id: "create-test-strategy"
- required: true
- agent: "tea"
- command: "create-test-strategy"
- output: "Comprehensive test strategy"
- note: "Future workflow - test approach, automation, quality gates"
+ note: "Future workflow - optional extended enterprise workflow for CI/CD, deployment, monitoring"
- id: "validate-architecture"
optional: true
diff --git a/test/test-installation-components.js b/test/test-installation-components.js
new file mode 100644
index 00000000..464ca613
--- /dev/null
+++ b/test/test-installation-components.js
@@ -0,0 +1,214 @@
+/**
+ * Installation Component Tests
+ *
+ * Tests individual installation components in isolation:
+ * - Agent YAML → XML compilation
+ * - Manifest generation
+ * - Path resolution
+ * - Customization merging
+ *
+ * These are deterministic unit tests that don't require full installation.
+ * Usage: node test/test-installation-components.js
+ */
+
+const path = require('node:path');
+const fs = require('fs-extra');
+const { YamlXmlBuilder } = require('../tools/cli/lib/yaml-xml-builder');
+const { ManifestGenerator } = require('../tools/cli/installers/lib/core/manifest-generator');
+
+// ANSI colors
+const colors = {
+ reset: '\u001B[0m',
+ green: '\u001B[32m',
+ red: '\u001B[31m',
+ yellow: '\u001B[33m',
+ cyan: '\u001B[36m',
+ dim: '\u001B[2m',
+};
+
+let passed = 0;
+let failed = 0;
+
+/**
+ * Test helper: Assert condition
+ */
+function assert(condition, testName, errorMessage = '') {
+ if (condition) {
+ console.log(`${colors.green}✓${colors.reset} ${testName}`);
+ passed++;
+ } else {
+ console.log(`${colors.red}✗${colors.reset} ${testName}`);
+ if (errorMessage) {
+ console.log(` ${colors.dim}${errorMessage}${colors.reset}`);
+ }
+ failed++;
+ }
+}
+
+/**
+ * Test Suite
+ */
+async function runTests() {
+ console.log(`${colors.cyan}========================================`);
+ console.log('Installation Component Tests');
+ console.log(`========================================${colors.reset}\n`);
+
+ const projectRoot = path.join(__dirname, '..');
+
+ // ============================================================
+ // Test 1: YAML → XML Agent Compilation (In-Memory)
+ // ============================================================
+ console.log(`${colors.yellow}Test Suite 1: Agent Compilation${colors.reset}\n`);
+
+ try {
+ const builder = new YamlXmlBuilder();
+ const pmAgentPath = path.join(projectRoot, 'src/modules/bmm/agents/pm.agent.yaml');
+
+ // Create temp output path
+ const tempOutput = path.join(__dirname, 'temp-pm-agent.md');
+
+ try {
+ const result = await builder.buildAgent(pmAgentPath, null, tempOutput, { includeMetadata: true });
+
+ assert(result && result.outputPath === tempOutput, 'Agent compilation returns result object with outputPath');
+
+ // Read the output
+ const compiled = await fs.readFile(tempOutput, 'utf8');
+
+ assert(compiled.includes(' tag');
+
+ assert(compiled.includes(''), 'Compiled agent contains tag');
+
+ assert(compiled.includes('