bmad-method-test-architecture-enterprise 1.2.2 → 1.2.3

package/src/workflows/testarch/test-design/steps-c/step-05-generate-output.md

@@ -79,7 +79,34 @@ If any checklist criteria are missing, fix before completion.
 
 ---
 
-## 4. Completion Report
+## 4. Generate BMAD Handoff Document (System-Level Mode Only)
+
+**If this is a system-level test design** (not component/feature level):
+
+1. Copy `test-design-handoff-template.md` to `{test_artifacts}/test-design/{project_name}-handoff.md`
+2. Populate all sections from the test design output:
+   - Fill TEA Artifacts Inventory with actual paths
+   - Extract P0/P1 risks into Epic-Level guidance
+   - Map critical test scenarios to Story-Level guidance
+   - Build risk-to-story mapping table from risk register
+3. Save alongside the test design document
+
+> **Note**: The handoff document is designed for consumption by BMAD's `create-epics-and-stories` workflow. It is only generated for system-level test designs where epic/story decomposition is relevant.
+
+---
+
+## 5. Polish Output
+
+Before finalizing, review the complete output document for quality:
+
+1. **Remove duplication**: Progressive-append workflow may have created repeated sections — consolidate
+2. **Verify consistency**: Ensure terminology, risk scores, and references are consistent throughout
+3. **Check completeness**: All template sections should be populated or explicitly marked N/A
+4. **Format cleanup**: Ensure markdown formatting is clean (tables aligned, headers consistent, no orphaned references)
+
+---
+
+## 6. Completion Report
 
 Summarize:
 
@@ -90,7 +117,7 @@ Summarize:
 
 ---
 
-### 5. Save Progress
+### 7. Save Progress
 
 **Save this step's accumulated work to `{progressFile}`.**
 

package/src/workflows/testarch/test-design/test-design-architecture-template.md

@@ -2,6 +2,8 @@
 stepsCompleted: []
 lastStep: ''
 lastSaved: ''
+workflowType: 'testarch-test-design'
+inputDocuments: []
 ---
 
 # Test Design for Architecture: {Feature Name}
@@ -49,21 +51,21 @@ lastSaved: ''
 
 ### 🚨 BLOCKERS - Team Must Decide (Can't Proceed Without)
 
-**Sprint 0 Critical Path** - These MUST be completed before QA can write integration tests:
+**Pre-Implementation Critical Path** - These MUST be completed before QA can write integration tests:
 
 1. **{Blocker ID}: {Blocker Title}** - {What architecture must provide} (recommended owner: {Team/Role})
 2. **{Blocker ID}: {Blocker Title}** - {What architecture must provide} (recommended owner: {Team/Role})
 3. **{Blocker ID}: {Blocker Title}** - {What architecture must provide} (recommended owner: {Team/Role})
 
-**What we need from team:** Complete these {N} items in Sprint 0 or test development is blocked.
+**What we need from team:** Complete these {N} items pre-implementation or test development is blocked.
 
 ---
 
 ### ⚠️ HIGH PRIORITY - Team Should Validate (We Provide Recommendation, You Approve)
 
-1. **{Risk ID}: {Title}** - {Recommendation + who should approve} (Sprint {N})
-2. **{Risk ID}: {Title}** - {Recommendation + who should approve} (Sprint {N})
-3. **{Risk ID}: {Title}** - {Recommendation + who should approve} (Sprint {N})
+1. **{Risk ID}: {Title}** - {Recommendation + who should approve} (implementation phase)
+2. **{Risk ID}: {Title}** - {Recommendation + who should approve} (implementation phase)
+3. **{Risk ID}: {Title}** - {Recommendation + who should approve} (implementation phase)
 
 **What we need from team:** Review recommendations and approve (or suggest changes).
 
@@ -124,13 +126,13 @@ lastSaved: ''
 
 #### 1. Blockers to Fast Feedback (WHAT WE NEED FROM ARCHITECTURE)
 
-| Concern            | Impact              | What Architecture Must Provide         | Owner  | Timeline |
-| ------------------ | ------------------- | -------------------------------------- | ------ | -------- |
-| **{Concern name}** | {Impact on testing} | {Specific architectural change needed} | {Team} | {Sprint} |
+| Concern            | Impact              | What Architecture Must Provide         | Owner  | Timeline    |
+| ------------------ | ------------------- | -------------------------------------- | ------ | ----------- |
+| **{Concern name}** | {Impact on testing} | {Specific architectural change needed} | {Team} | {Milestone} |
 
 **Example:**
 
-- **No API for test data seeding** → Cannot parallelize tests → Provide POST /test/seed endpoint (Backend, Sprint 0)
+- **No API for test data seeding** → Cannot parallelize tests → Provide POST /test/seed endpoint (Backend, pre-implementation)
 
 #### 2. Architectural Improvements Needed (WHAT SHOULD BE CHANGED)
 
@@ -141,7 +143,7 @@ lastSaved: ''
    - **Required change**: {What architecture must do}
    - **Impact if not fixed**: {Consequences}
    - **Owner**: {Team}
-   - **Timeline**: {Sprint}
+   - **Timeline**: {Milestone}
 
 ---
 
@@ -181,7 +183,7 @@ For {Feature} Phase 1, the following trade-offs are acceptable:
 3. {Step 3}
 
 **Owner:** {Owner}
-**Timeline:** {Sprint or date}
+**Timeline:** {Milestone or date}
 **Status:** Planned / In Progress / Complete
 **Verification:** {How to verify mitigation is effective}
 
@@ -201,8 +203,8 @@ For {Feature} Phase 1, the following trade-offs are acceptable:
 
 #### Dependencies
 
-1. {Dependency} - Required by {date/sprint}
-2. {Dependency} - Required by {date/sprint}
+1. {Dependency} - Required by {date/milestone}
+2. {Dependency} - Required by {date/milestone}
 
 #### Risks to Plan
 
@@ -223,6 +225,6 @@ For {Feature} Phase 1, the following trade-offs are acceptable:
 
 **Next Steps for QA Team:**
 
-1. Wait for Sprint 0 blockers to be resolved
+1. Wait for pre-implementation blockers to be resolved
 2. Refer to companion QA doc (test-design-qa.md) for test scenarios
 3. Begin test infrastructure setup (factories, fixtures, environments)

package/src/workflows/testarch/test-design/test-design-handoff-template.md

@@ -0,0 +1,70 @@
+---
+title: 'TEA Test Design → BMAD Handoff Document'
+version: '1.0'
+workflowType: 'testarch-test-design-handoff'
+inputDocuments: []
+sourceWorkflow: 'testarch-test-design'
+generatedBy: 'TEA Master Test Architect'
+generatedAt: '{timestamp}'
+projectName: '{project_name}'
+---
+
+# TEA → BMAD Integration Handoff
+
+## Purpose
+
+This document bridges TEA's test design outputs with BMAD's epic/story decomposition workflow (`create-epics-and-stories`). It provides structured integration guidance so that quality requirements, risk assessments, and test strategies flow into implementation planning.
+
+## TEA Artifacts Inventory
+
+| Artifact             | Path                      | BMAD Integration Point                               |
+| -------------------- | ------------------------- | ---------------------------------------------------- |
+| Test Design Document | `{test_design_path}`      | Epic quality requirements, story acceptance criteria |
+| Risk Assessment      | (embedded in test design) | Epic risk classification, story priority             |
+| Coverage Strategy    | (embedded in test design) | Story test requirements                              |
+
+## Epic-Level Integration Guidance
+
+### Risk References
+
+<!-- TEA will populate: P0/P1 risks that should appear as epic-level quality gates -->
+
+### Quality Gates
+
+<!-- TEA will populate: recommended quality gates per epic based on risk assessment -->
+
+## Story-Level Integration Guidance
+
+### P0/P1 Test Scenarios → Story Acceptance Criteria
+
+<!-- TEA will populate: critical test scenarios that MUST be acceptance criteria -->
+
+### Data-TestId Requirements
+
+<!-- TEA will populate: recommended data-testid attributes for testability -->
+
+## Risk-to-Story Mapping
+
+| Risk ID | Category | P×I | Recommended Story/Epic | Test Level |
+| ------- | -------- | --- | ---------------------- | ---------- |
+
+<!-- TEA will populate from risk assessment -->
+
+## Recommended BMAD → TEA Workflow Sequence
+
+1. **TEA Test Design** (`TD`) → produces this handoff document
+2. **BMAD Create Epics & Stories** → consumes this handoff, embeds quality requirements
+3. **TEA ATDD** (`AT`) → generates acceptance tests per story
+4. **BMAD Implementation** → developers implement with test-first guidance
+5. **TEA Automate** (`TA`) → generates full test suite
+6. **TEA Trace** (`TR`) → validates coverage completeness
+
+## Phase Transition Quality Gates
+
+| From Phase          | To Phase            | Gate Criteria                                          |
+| ------------------- | ------------------- | ------------------------------------------------------ |
+| Test Design         | Epic/Story Creation | All P0 risks have mitigation strategy                  |
+| Epic/Story Creation | ATDD                | Stories have acceptance criteria from test design      |
+| ATDD                | Implementation      | Failing acceptance tests exist for all P0/P1 scenarios |
+| Implementation      | Test Automation     | All acceptance tests pass                              |
+| Test Automation     | Release             | Trace matrix shows ≥80% coverage of P0/P1 requirements |

package/src/workflows/testarch/test-design/test-design-qa-template.md

@@ -2,6 +2,8 @@
 stepsCompleted: []
 lastStep: ''
 lastSaved: ''
+workflowType: 'testarch-test-design'
+inputDocuments: []
 ---
 
 # Test Design for QA: {Feature Name}
@@ -52,7 +54,7 @@ lastSaved: ''
 
 **CRITICAL:** QA cannot proceed without these items from other teams.
 
-### Backend/Architecture Dependencies (Sprint 0)
+### Backend/Architecture Dependencies (Pre-Implementation)
 
 **Source:** See Architecture doc "Quick Guide" for detailed mitigation plans
 
@@ -64,7 +66,7 @@ lastSaved: ''
    - {What QA needs}
    - {Why it blocks testing}
 
-### QA Infrastructure Setup (Sprint 0)
+### QA Infrastructure Setup (Pre-Implementation)
 
 1. **Test Data Factories** - QA
    - {Entity} factory with faker-based randomization
@@ -125,7 +127,7 @@ test('example test @p0', async ({ apiRequest }) => {
 - [ ] All requirements and assumptions agreed upon by QA, Dev, PM
 - [ ] Test environments provisioned and accessible
 - [ ] Test data factories ready or seed data available
-- [ ] Sprint 0 blockers resolved (see Dependencies section)
+- [ ] Pre-implementation blockers resolved (see Dependencies section)
 - [ ] Feature deployed to test environment
 - [ ] {Additional project-specific entry criteria}
 
@@ -276,16 +278,16 @@ test('example test @p0', async ({ apiRequest }) => {
 
 ---
 
-## Sprint Planning Handoff (Optional)
+## Implementation Planning Handoff (Optional)
 
 **Include only if this test design produces implementation tasks that must be scheduled.**
 
-**Use this to inform sprint planning; if no dedicated QA, assign to Dev owners.**
+**Use this to inform implementation planning; if no dedicated QA, assign to Dev owners.**
 
-| Work Item   | Owner        | Target Sprint (Optional) | Dependencies/Notes |
-| ----------- | ------------ | ------------------------ | ------------------ |
-| {Work item} | {QA/Dev/etc} | {Sprint or date}         | {Notes}            |
-| {Work item} | {QA/Dev/etc} | {Sprint or date}         | {Notes}            |
+| Work Item   | Owner        | Target Milestone (Optional) | Dependencies/Notes |
+| ----------- | ------------ | --------------------------- | ------------------ |
+| {Work item} | {QA/Dev/etc} | {Milestone or date}         | {Notes}            |
+| {Work item} | {QA/Dev/etc} | {Milestone or date}         | {Notes}            |
 
 ---
 

package/src/workflows/testarch/test-design/workflow.yaml

@@ -25,6 +25,7 @@ template: "{installed_path}/test-design-template.md"
 variables:
   design_level: "full" # full, targeted, minimal - scope of design effort
   mode: "auto-detect" # auto-detect (default), system-level, epic-level
+  test_stack_type: "auto" # auto, frontend, backend, fullstack - from config or auto-detected
 
 # Output configuration
 # Note: Actual output file determined dynamically based on mode detection
@@ -38,11 +39,17 @@ outputs:
     audience: architecture
 
   - id: test-design-qa
-    description: "System-level test design: Test execution recipe, coverage plan, Sprint 0 setup for QA team"
+    description: "System-level test design: Test execution recipe, coverage plan, pre-implementation setup for QA team"
     path: "{test_artifacts}/test-design-qa.md"
     mode: system-level
     audience: qa
 
+  - id: test-design-handoff
+    description: "TEA → BMAD handoff document: Bridges test design outputs with epic/story decomposition"
+    path: "{test_artifacts}/test-design/{project_name}-handoff.md"
+    mode: system-level
+    audience: bmad-integration
+
   # Epic-Level Mode (Phase 4) - ONE document (unchanged)
   - id: epic-level
     description: "Epic-level test plan (Phase 4)"

package/src/workflows/testarch/test-review/steps-c/step-01-load-context.md

@@ -36,7 +36,7 @@ Determine review scope, load required knowledge fragments, and gather related ar
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
-## 1. Determine Scope
+## 1. Determine Scope and Stack
 
 Use `review_scope`:
 
@@ -46,8 +46,39 @@ Use `review_scope`:
 
 If unclear, ask the user.
 
+**Stack Detection** (for context-aware loading):
+
+Read `test_stack_type` from `{config_source}`. If `"auto"` or not configured, infer `{detected_stack}` by scanning `{project-root}`:
+
+- **Frontend indicators**: `playwright.config.*`, `cypress.config.*`, `package.json` with react/vue/angular
+- **Backend indicators**: `pyproject.toml`, `pom.xml`/`build.gradle`, `go.mod`, `*.csproj`, `Gemfile`, `Cargo.toml`
+- **Both present** → `fullstack`; only frontend → `frontend`; only backend → `backend`
+- Explicit `test_stack_type` overrides auto-detection
+
 ---
 
+### Tiered Knowledge Loading
+
+Load fragments based on their `tier` classification in `tea-index.csv`:
+
+1. **Core tier** (always load): Foundational fragments required for this workflow
+2. **Extended tier** (load on-demand): Load when deeper analysis is needed or when the user's context requires it
+3. **Specialized tier** (load only when relevant): Load only when the specific use case matches (e.g., contract-testing only for microservices, email-auth only for email flows)
+
+> **Context Efficiency**: Loading only core fragments reduces context usage by 40-50% compared to loading all fragments.
+
+### Playwright Utils Loading Profiles
+
+**If `tea_use_playwright_utils` is enabled**, select the appropriate loading profile:
+
+- **API-only profile** (when `{detected_stack}` is `backend` or no `page.goto`/`page.locator` found in test files):
+  Load: `overview`, `api-request`, `auth-session`, `recurse` (~1,800 lines)
+
+- **Full UI+API profile** (when `{detected_stack}` is `frontend`/`fullstack` or browser tests detected):
+  Load: all Playwright Utils core fragments (~4,500 lines)
+
+**Detection**: Scan `{test_dir}` for files containing `page.goto` or `page.locator`. If none found, use API-only profile.
+
 ## 2. Load Knowledge Base
 
 From `{knowledgeIndex}` load:
@@ -122,6 +153,8 @@ Coverage mapping and coverage gates are out of scope in `test-review`. Route tho
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
+**Update `inputDocuments`**: Set `inputDocuments` in the output template frontmatter to the list of artifact paths loaded in this step (e.g., knowledge fragments, test design documents, configuration files).
+
 Load next step: `{nextStepFile}`
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS:

package/src/workflows/testarch/test-review/steps-c/step-04-generate-report.md

@@ -46,7 +46,18 @@ Use `test-review-template.md` to produce `{outputFile}` including:
 
 ---
 
-## 2. Validation
+## 2. Polish Output
+
+Before finalizing, review the complete output document for quality:
+
+1. **Remove duplication**: Progressive-append workflow may have created repeated sections — consolidate
+2. **Verify consistency**: Ensure terminology, risk scores, and references are consistent throughout
+3. **Check completeness**: All template sections should be populated or explicitly marked N/A
+4. **Format cleanup**: Ensure markdown formatting is clean (tables aligned, headers consistent, no orphaned references)
+
+---
+
+## 3. Validation
 
 Validate against `checklist.md` and fix any gaps.
 
@@ -55,7 +66,7 @@ Validate against `checklist.md` and fix any gaps.
 
 ---
 
-## 3. Save Progress
+## 4. Save Progress
 
 **Save this step's accumulated work to `{outputFile}`.**
 
@@ -79,7 +90,7 @@ Validate against `checklist.md` and fix any gaps.
 
 ---
 
-## 4. Completion Summary
+## 5. Completion Summary
 
 Report:
 

package/src/workflows/testarch/test-review/test-review-template.md

@@ -2,6 +2,8 @@
 stepsCompleted: []
 lastStep: ''
 lastSaved: ''
+workflowType: 'testarch-test-review'
+inputDocuments: []
 ---
 
 # Test Quality Review: {test_filename}
@@ -289,11 +291,11 @@ See [tea-index.csv](../../../testarch/tea-index.csv) for complete knowledge base
 
 1. **{action_1}** - {description}
    - Priority: {P2 | P3}
-   - Target: {next_sprint | backlog}
+   - Target: {next_milestone | backlog}
 
 2. **{action_2}** - {description}
    - Priority: {P2 | P3}
-   - Target: {next_sprint | backlog}
+   - Target: {next_milestone | backlog}
 
 ### Re-Review Needed?
 

package/src/workflows/testarch/test-review/workflow.yaml

@@ -22,6 +22,7 @@ template: "{installed_path}/test-review-template.md"
 variables:
   test_dir: "{project-root}/tests" # Root test directory
   review_scope: "single" # single (one file), directory (folder), suite (all tests)
+  test_stack_type: "auto" # auto, frontend, backend, fullstack - from config or auto-detected
 
 # Output configuration
 default_output_file: "{test_artifacts}/test-review.md"

package/src/workflows/testarch/trace/trace-template.md

@@ -2,6 +2,8 @@
 stepsCompleted: []
 lastStep: ''
 lastSaved: ''
+workflowType: 'testarch-trace'
+inputDocuments: []
 ---
 
 # Traceability Matrix & Gate Decision - Story {STORY_ID}
@@ -230,7 +232,7 @@ Note: This workflow does not generate tests. If gaps exist, run `*atdd` or `*aut
 1. **{ACTION_1}** - {DESCRIPTION}
 2. **{ACTION_2}** - {DESCRIPTION}
 
-#### Short-term Actions (This Sprint)
+#### Short-term Actions (This Milestone)
 
 1. **{ACTION_1}** - {DESCRIPTION}
 2. **{ACTION_2}** - {DESCRIPTION}
@@ -248,7 +250,7 @@ Note: This workflow does not generate tests. If gaps exist, run `*atdd` or `*aut
 1. **Add P1 Password Reset Tests** - Implement `1.3-API-001` for email service integration and `1.3-E2E-004` for error path validation. P1 coverage currently at 80%, target is 90%.
 2. **Optimize Slow E2E Test** - Refactor `1.3-E2E-001` to use faster fixture setup. Currently 145s, target is <90s.
 
-**Short-term Actions (This Sprint)**
+**Short-term Actions (This Milestone)**
 
 1. **Enhance P2 Coverage** - Add E2E validation for session timeout (`1.3-E2E-005`). Currently UNIT-ONLY coverage.
 2. **Split Large Test File** - Break `1.3-UNIT-005` (320 lines) into multiple focused test files (<300 lines each).
@@ -439,7 +441,7 @@ List unresolved P1/P2 issues that don't block release but should be tracked:
    - **Impact**: Low | Medium | High
    - **Risk Score**: {probability × impact}
    - **Mitigation**: {workaround or monitoring plan}
-   - **Remediation**: {fix in next sprint/release}
+   - **Remediation**: {fix in next milestone/release}
 
 **Overall Residual Risk**: {LOW | MEDIUM | HIGH}
 
@@ -526,7 +528,7 @@ Top blockers requiring immediate attention:
 2. **Create Remediation Backlog**
    - Create story: "{fix_title_1}" (Priority: {priority})
    - Create story: "{fix_title_2}" (Priority: {priority})
-   - Target sprint: {next_sprint}
+   - Target milestone: {next_milestone}
 
 3. **Post-Deployment Actions**
    - Monitor {specific_areas} closely for {time_period}
@@ -583,7 +585,7 @@ Top blockers requiring immediate attention:
 2. {action_2}
 3. {action_3}
 
-**Follow-up Actions** (next sprint/release):
+**Follow-up Actions** (next milestone/release):
 
 1. {action_1}
 2. {action_2}

package/test/test-installation-components.js

@@ -127,7 +127,7 @@ async function runTests() {
       const lines = csvContent.trim().split('\n');
 
       assert(lines.length === 36, 'tea-index.csv has 36 lines (header + 35 fragments)', `Found ${lines.length} lines`);
-      assert(lines[0].includes('id,name,description,tags,fragment_file'), 'tea-index.csv has correct header format');
+      assert(lines[0].includes('id,name,description,tags,tier,fragment_file'), 'tea-index.csv has correct header format');
 
       // Verify no BMM references in CSV
       assert(!csvContent.includes('bmm'), 'tea-index.csv has no BMM references');

package/test/test-knowledge-base.js

@@ -90,9 +90,18 @@ function runTests() {
 
     assert(records.length === 35, 'tea-index.csv has 35 fragment records', `Found ${records.length}`);
 
-    const requiredFields = ['id', 'name', 'description', 'tags', 'fragment_file'];
+    const requiredFields = ['id', 'name', 'description', 'tags', 'tier', 'fragment_file'];
     const missingFields = requiredFields.filter((field) => !Object.prototype.hasOwnProperty.call(records[0] || {}, field));
     assert(missingFields.length === 0, 'tea-index.csv has required columns', missingFields.join(', '));
+
+    // Validate tier values
+    const validTiers = new Set(['core', 'extended', 'specialized']);
+    const invalidTiers = records.filter((r) => !validTiers.has(r.tier));
+    assert(
+      invalidTiers.length === 0,
+      'All fragments have valid tier values (core/extended/specialized)',
+      invalidTiers.map((r) => `${r.id}: "${r.tier}"`).join(', '),
+    );
   } catch (error) {
     assert(false, 'tea-index.csv parsed successfully', error.message);
   }