bmad-method-test-architecture-enterprise 1.4.0 → 1.4.1

package/docs/explanation/subagent-architecture.md

@@ -1,580 +1,189 @@
 ---
 title: Subagent Architecture
-description: Parallel execution pattern for TEA workflows
+description: How TEA uses subagents and agent teams across workflows
 ---
 
-# Subagent Architecture for TEA Workflows
+# Subagents and Agent Teams in TEA
 
-**Version**: 1.0
-**Date**: 2026-01-27
-**Status**: Implementation Guide
+This guide explains how TEA orchestrates work when a workflow can split into
+worker steps (independent workers or dependency-ordered work units).
 
----
-
-## Overview
-
-TEA workflows use **subagent patterns** to parallelize independent tasks, improving performance and maintaining clean separation of concerns. Five workflows benefit from this architecture:
-
-1. **automate** - Parallel test generation (API + E2E)
-2. **atdd** - Parallel failing test generation (API + E2E)
-3. **test-review** - Parallel quality dimension checks
-4. **nfr-assess** - Parallel NFR domain assessments
-5. **trace** - Two-phase workflow separation
-
----
-
-## Core Subagent Pattern
-
-### Architecture
-
-```
-Main Workflow (Orchestrator)
-├── Step 1: Setup & Context Loading
-├── Step 2: Launch Subagents
-│   ├── Subagent A → temp-file-a.json
-│   ├── Subagent B → temp-file-b.json
-│   ├── Subagent C → temp-file-c.json
-│   └── (All run in parallel, isolated 200k containers)
-└── Step 3: Aggregate Results
-    ├── Read all temp files
-    ├── Merge/synthesize outputs
-    └── Generate final artifact
-```
-
-### Key Principles
-
-1. **Independence**: Each subagent is completely independent (no shared state)
-2. **Isolation**: Each subagent runs in separate 200k context container
-3. **Output Format**: All subagents output structured JSON to temp files
-4. **Aggregation**: Main workflow reads temp files and synthesizes final output
-5. **Error Handling**: Each subagent reports success/failure in JSON output
-
----
-
-## Workflow-Specific Designs
-
-### 1. automate - Parallel Test Generation
-
-**Goal**: Generate API and E2E tests in parallel
-
-#### Architecture
+## Scope
 
-```
-automate workflow
-├── Step 1: Analyze codebase & identify features
-├── Step 2: Load relevant knowledge fragments
-├── Step 3: Launch parallel test generation
-│   ├── Subagent A: Generate API tests → /tmp/api-tests-{timestamp}.json
-│   └── Subagent B: Generate E2E tests → /tmp/e2e-tests-{timestamp}.json
-├── Step 4: Aggregate tests
-│   ├── Read API tests JSON
-│   ├── Read E2E tests JSON
-│   └── Generate fixtures (if needed)
-├── Step 5: Verify all tests pass
-└── Step 6: Generate DoD summary
-```
-
-#### Subagent A: API Tests
-
-**Input** (passed via temp file):
-
-```json
-{
-  "features": ["feature1", "feature2"],
-  "knowledge_fragments": ["api-request", "data-factories"],
-  "config": {
-    "use_playwright_utils": true,
-    "framework": "playwright"
-  }
-}
-```
-
-**Output** (`/tmp/api-tests-{timestamp}.json`):
-
-```json
-{
-  "success": true,
-  "tests": [
-    {
-      "file": "tests/api/feature1.spec.ts",
-      "content": "import { test, expect } from '@playwright/test';\n...",
-      "description": "API tests for feature1"
-    }
-  ],
-  "fixtures": [],
-  "summary": "Generated 5 API test cases"
-}
-```
+This applies to these workflows:
 
-#### Subagent B: E2E Tests
+- `automate`
+- `atdd`
+- `test-review`
+- `nfr-assess`
+- `framework`
+- `ci`
+- `test-design`
+- `trace`
 
-**Input** (passed via temp file):
-
-```json
-{
-  "features": ["feature1", "feature2"],
-  "knowledge_fragments": ["fixture-architecture", "network-first"],
-  "config": {
-    "use_playwright_utils": true,
-    "framework": "playwright"
-  }
-}
-```
-
-**Output** (`/tmp/e2e-tests-{timestamp}.json`):
-
-```json
-{
-  "success": true,
-  "tests": [
-    {
-      "file": "tests/e2e/feature1.spec.ts",
-      "content": "import { test, expect } from '@playwright/test';\n...",
-      "description": "E2E tests for feature1 user journey"
-    }
-  ],
-  "fixtures": ["authFixture", "dataFixture"],
-  "summary": "Generated 8 E2E test cases"
-}
-```
-
-#### Step 4: Aggregation Logic
-
-```javascript
-// Read both subagent outputs
-const apiTests = JSON.parse(fs.readFileSync('/tmp/api-tests-{timestamp}.json', 'utf8'));
-const e2eTests = JSON.parse(fs.readFileSync('/tmp/e2e-tests-{timestamp}.json', 'utf8'));
-
-// Merge test suites
-const allTests = [...apiTests.tests, ...e2eTests.tests];
-
-// Collect unique fixtures
-const allFixtures = [...new Set([...apiTests.fixtures, ...e2eTests.fixtures])];
-
-// Generate combined DoD summary
-const summary = {
-  total_tests: allTests.length,
-  api_tests: apiTests.tests.length,
-  e2e_tests: e2eTests.tests.length,
-  fixtures: allFixtures,
-  status: apiTests.success && e2eTests.success ? 'PASS' : 'FAIL',
-};
-```
+It does not apply to `teach-me-testing`.
 
 ---
 
-### 2. atdd - Parallel Failing Test Generation
-
-**Goal**: Generate failing API and E2E tests in parallel (TDD red phase)
+## Core Model
 
-#### Architecture
+TEA orchestration has three parts:
 
-```
-atdd workflow
-├── Step 1: Load story acceptance criteria
-├── Step 2: Load relevant knowledge fragments
-├── Step 3: Launch parallel test generation
-│   ├── Subagent A: Generate failing API tests → /tmp/atdd-api-{timestamp}.json
-│   └── Subagent B: Generate failing E2E tests → /tmp/atdd-e2e-{timestamp}.json
-├── Step 4: Aggregate tests
-├── Step 5: Verify tests fail (red phase)
-└── Step 6: Output ATDD checklist
-```
-
-**Key Difference from automate**: Tests must be written to **fail** before implementation exists.
-
-#### Subagent Outputs
-
-Same JSON structure as automate, but:
+1. Resolve execution mode (`tea_execution_mode` + optional runtime probe)
+2. Dispatch worker steps (independent or dependency-ordered, depending on workflow)
+3. Aggregate worker outputs into one deterministic final artifact
 
-- Tests include failing assertions (e.g., `expect(response.status).toBe(200)` when endpoint doesn't exist yet)
-- Summary includes: `"expected_to_fail": true`
+Workers are isolated and exchange data through structured outputs that the
+aggregation step validates.
 
 ---
 
-### 3. test-review - Parallel Quality Dimension Checks
+## Execution Modes
 
-**Goal**: Run independent quality checks in parallel, aggregate into 0-100 score
+TEA supports four modes:
 
-#### Architecture
+- `auto`
+- `agent-team`
+- `subagent`
+- `sequential`
 
-```
-test-review workflow
-├── Step 1: Load test files & context
-├── Step 2: Launch parallel quality checks
-│   ├── Subagent A: Determinism check → /tmp/determinism-{timestamp}.json
-│   ├── Subagent B: Isolation check → /tmp/isolation-{timestamp}.json
-│   ├── Subagent C: Maintainability check → /tmp/maintainability-{timestamp}.json
-│   ├── Subagent D: Coverage check → /tmp/coverage-{timestamp}.json
-│   └── Subagent E: Performance check → /tmp/performance-{timestamp}.json
-└── Step 3: Aggregate findings
-    ├── Calculate weighted score (0-100)
-    ├── Synthesize violations
-    └── Generate review report with suggestions
-```
+### What Each Mode Means
 
-#### Subagent Output Format
-
-Each quality dimension subagent outputs:
-
-```json
-{
-  "dimension": "determinism",
-  "score": 85,
-  "max_score": 100,
-  "violations": [
-    {
-      "file": "tests/api/user.spec.ts",
-      "line": 42,
-      "severity": "HIGH",
-      "description": "Test uses Math.random() - non-deterministic",
-      "suggestion": "Use faker with fixed seed"
-    }
-  ],
-  "passed_checks": 12,
-  "failed_checks": 3,
-  "summary": "Tests are mostly deterministic with 3 violations"
-}
-```
+- `auto`: Choose the best supported mode at runtime.
+- `agent-team`: Prefer team/delegation orchestration when runtime supports it.
+- `subagent`: Prefer isolated worker orchestration when runtime supports it.
+- `sequential`: Run worker steps one-by-one.
 
-#### Step 3: Aggregation Logic
-
-```javascript
-// Read all dimension outputs
-const dimensions = ['determinism', 'isolation', 'maintainability', 'coverage', 'performance'];
-const results = dimensions.map((d) => JSON.parse(fs.readFileSync(`/tmp/${d}-{timestamp}.json`, 'utf8')));
-
-// Calculate weighted score
-const weights = { determinism: 0.25, isolation: 0.25, maintainability: 0.2, coverage: 0.15, performance: 0.15 };
-const totalScore = results.reduce((sum, r) => sum + r.score * weights[r.dimension], 0);
-
-// Aggregate violations by severity
-const allViolations = results.flatMap((r) => r.violations);
-const highSeverity = allViolations.filter((v) => v.severity === 'HIGH');
-const mediumSeverity = allViolations.filter((v) => v.severity === 'MEDIUM');
-const lowSeverity = allViolations.filter((v) => v.severity === 'LOW');
-
-// Generate final report
-const report = {
-  overall_score: Math.round(totalScore),
-  grade: getGrade(totalScore), // A/B/C/D/F
-  dimensions: results,
-  violations_summary: {
-    high: highSeverity.length,
-    medium: mediumSeverity.length,
-    low: lowSeverity.length,
-    total: allViolations.length,
-  },
-  top_suggestions: prioritizeSuggestions(allViolations),
-};
-```
+### Fallback Behavior
 
----
+When `tea_capability_probe: true`, TEA can fallback safely:
 
-### 4. nfr-assess - Parallel NFR Domain Assessments
+- `auto` falls back in order: `agent-team` -> `subagent` -> `sequential`
+- explicit `agent-team` or `subagent` falls back to next supported mode
+- `sequential` always stays sequential
 
-**Goal**: Assess independent NFR domains in parallel
+When `tea_capability_probe: false`, TEA honors the requested mode strictly and
+fails if runtime cannot execute it.
 
-#### Architecture
+### Runtime Scheduling
 
-```
-nfr-assess workflow
-├── Step 1: Load system context
-├── Step 2: Launch parallel NFR assessments
-│   ├── Subagent A: Security assessment → /tmp/nfr-security-{timestamp}.json
-│   ├── Subagent B: Performance assessment → /tmp/nfr-performance-{timestamp}.json
-│   ├── Subagent C: Reliability assessment → /tmp/nfr-reliability-{timestamp}.json
-│   └── Subagent D: Scalability assessment → /tmp/nfr-scalability-{timestamp}.json
-└── Step 3: Aggregate NFR report
-    ├── Synthesize domain assessments
-    ├── Identify cross-domain risks
-    └── Generate compliance documentation
-```
-
-#### Subagent Output Format
-
-Each NFR domain subagent outputs:
-
-```json
-{
-  "domain": "security",
-  "risk_level": "MEDIUM",
-  "findings": [
-    {
-      "category": "Authentication",
-      "status": "PASS",
-      "description": "OAuth2 with JWT tokens implemented",
-      "recommendations": []
-    },
-    {
-      "category": "Data Encryption",
-      "status": "CONCERN",
-      "description": "Database encryption at rest not enabled",
-      "recommendations": ["Enable database encryption", "Use AWS KMS for key management"]
-    }
-  ],
-  "compliance": {
-    "SOC2": "PARTIAL",
-    "GDPR": "PASS",
-    "HIPAA": "N/A"
-  },
-  "priority_actions": ["Enable database encryption within 30 days"]
-}
-```
-
-#### Step 3: Aggregation Logic
-
-```javascript
-// Read all NFR domain outputs
-const domains = ['security', 'performance', 'reliability', 'scalability'];
-const assessments = domains.map((d) => JSON.parse(fs.readFileSync(`/tmp/nfr-${d}-{timestamp}.json`, 'utf8')));
-
-// Calculate overall risk
-const riskLevels = { HIGH: 3, MEDIUM: 2, LOW: 1, NONE: 0 };
-const maxRiskLevel = Math.max(...assessments.map((a) => riskLevels[a.risk_level]));
-const overallRisk = Object.keys(riskLevels).find((k) => riskLevels[k] === maxRiskLevel);
-
-// Aggregate compliance status
-const allCompliance = assessments.flatMap((a) => Object.entries(a.compliance));
-const complianceSummary = {};
-allCompliance.forEach(([std, status]) => {
-  if (!complianceSummary[std]) complianceSummary[std] = [];
-  complianceSummary[std].push(status);
-});
-
-// Synthesize cross-domain risks
-const crossDomainRisks = identifyCrossDomainRisks(assessments); // e.g., "Performance + scalability concern"
-
-// Generate final report
-const report = {
-  overall_risk: overallRisk,
-  domains: assessments,
-  compliance_summary: complianceSummary,
-  cross_domain_risks: crossDomainRisks,
-  priority_actions: assessments.flatMap((a) => a.priority_actions),
-  executive_summary: generateExecutiveSummary(assessments),
-};
-```
+In `agent-team` and `subagent` modes, runtime decides concurrency and timing.
+TEA does not impose its own parallel worker limit.
 
 ---
 
-### 5. trace - Two-Phase Workflow Separation
+## Verbal Override Rules
 
-**Goal**: Clean separation of coverage matrix generation and gate decision
+During a run, explicit user phrasing can override config for that run only.
 
-#### Architecture
+Supported normalized terms:
 
-```
-trace workflow
-├── Phase 1: Coverage Matrix
-│   ├── Step 1: Load requirements
-│   ├── Step 2: Analyze test suite
-│   └── Step 3: Generate traceability matrix → /tmp/trace-matrix-{timestamp}.json
-└── Phase 2: Gate Decision (depends on Phase 1 output)
-    ├── Step 4: Read coverage matrix
-    ├── Step 5: Apply decision tree logic
-    ├── Step 6: Calculate coverage percentages
-    └── Step 7: Generate gate decision (PASS/CONCERNS/FAIL/WAIVED)
-```
+- `agent team` or `agent teams` -> `agent-team`
+- `agentteam` -> `agent-team`
+- `subagent`, `subagents`, `sub agent`, or `sub agents` -> `subagent`
+- `sequential` -> `sequential`
+- `auto` -> `auto`
 
-**Note**: This isn't parallel subagents, but subagent-like **phase separation** where Phase 2 depends on Phase 1 output.
-
-#### Phase 1 Output Format
-
-```json
-{
-  "requirements": [
-    {
-      "id": "REQ-001",
-      "description": "User can login with email/password",
-      "priority": "P0",
-      "tests": ["tests/auth/login.spec.ts::should login with valid credentials"],
-      "coverage": "FULL"
-    },
-    {
-      "id": "REQ-002",
-      "description": "User can reset password",
-      "priority": "P1",
-      "tests": [],
-      "coverage": "NONE"
-    }
-  ],
-  "total_requirements": 50,
-  "covered_requirements": 42,
-  "coverage_percentage": 84
-}
-```
+Resolution precedence:
 
-#### Phase 2: Gate Decision Logic
-
-```javascript
-// Read Phase 1 output
-const matrix = JSON.parse(fs.readFileSync('/tmp/trace-matrix-{timestamp}.json', 'utf8'));
-
-// Apply decision tree
-const p0Coverage = matrix.requirements.filter((r) => r.priority === 'P0' && r.coverage === 'FULL').length;
-const totalP0 = matrix.requirements.filter((r) => r.priority === 'P0').length;
-
-let gateDecision;
-if (p0Coverage === totalP0 && matrix.coverage_percentage >= 90) {
-  gateDecision = 'PASS';
-} else if (p0Coverage === totalP0 && matrix.coverage_percentage >= 75) {
-  gateDecision = 'CONCERNS';
-} else if (p0Coverage < totalP0) {
-  gateDecision = 'FAIL';
-} else {
-  gateDecision = 'WAIVED'; // Manual review required
-}
-
-// Generate gate report
-const report = {
-  decision: gateDecision,
-  coverage_matrix: matrix,
-  p0_coverage: `${p0Coverage}/${totalP0}`,
-  overall_coverage: `${matrix.coverage_percentage}%`,
-  recommendations: generateRecommendations(matrix, gateDecision),
-  uncovered_requirements: matrix.requirements.filter((r) => r.coverage === 'NONE'),
-};
-```
+1. Explicit run-level request (if present)
+2. `tea_execution_mode` in config
+3. Runtime fallback (when probing is enabled)
 
 ---
 
-## Implementation Guidelines
+## Workflow Coverage Map
 
-### Temp File Management
+### `automate`
 
-**Naming Convention**:
+- Worker split: API + E2E/backend test generation workers
+- Aggregation: merges generated tests, fixtures, and summary stats
+- Mode effect: changes orchestration style only, not output contract
 
-```
-/tmp/{workflow}-{subagent-name}-{timestamp}.json
-```
+### `atdd`
 
-**Examples**:
+- Worker split: failing API + failing E2E test generation workers
+- Aggregation: validates red-phase output and merges artifacts
+- Mode effect: changes orchestration style only, not red-phase requirements
 
-- `/tmp/automate-api-tests-20260127-143022.json`
-- `/tmp/test-review-determinism-20260127-143022.json`
-- `/tmp/nfr-security-20260127-143022.json`
+### `test-review`
 
-**Cleanup**:
+- Worker split: quality-dimension evaluations (determinism, isolation,
+  maintainability, performance)
+- Aggregation: computes combined quality score/report
+- Mode effect: changes orchestration style only, not scoring schema
 
-- Temp files should be cleaned up after successful aggregation
-- Keep temp files on error for debugging
-- Implement retry logic for temp file reads (race conditions)
+### `nfr-assess`
 
-### Error Handling
+- Worker split: security, performance, reliability, scalability assessments
+- Aggregation: computes overall risk, compliance summary, priority actions
+- Mode effect: changes orchestration style only, not report schema
 
-Each subagent JSON output must include:
-
-```json
-{
-  "success": true|false,
-  "error": "Error message if failed",
-  "data": { ... }
-}
-```
+### `framework`
 
-Main workflow aggregation step must:
+- Worker split: scaffold work units (structure/config, fixtures, samples)
+- Aggregation: consolidates generated framework setup outputs
+- Mode effect: changes orchestration style only
 
-1. Check `success` field for each subagent
-2. If any subagent failed, aggregate error messages
-3. Decide whether to continue (partial success) or fail (critical subagent failed)
+### `ci`
 
-### Performance Considerations
+- Worker split: orchestration-capable mode resolution for pipeline generation
+- Aggregation: deterministic single pipeline artifact
+- Mode effect: mostly impacts orchestration policy; final pipeline contract is
+  unchanged
 
-**Subagent Isolation**:
+### `test-design`
 
-- Each subagent runs in separate 200k context container
-- No shared memory or state
-- Communication only via JSON files
+- Worker split: orchestration-capable mode resolution for output generation
+- Aggregation: deterministic design artifact output
+- Mode effect: orchestration policy only; output schema unchanged
 
-**Parallelization**:
+### `trace`
 
-- Resolve execution mode via config (`tea_execution_mode`, `tea_capability_probe`)
-- Probe runtime support for agent-team and subagent launch before dispatch
-- Fallback order in `auto` mode: `agent-team` → `subagent` → `sequential`
-- Ensure temp file paths are unique (timestamp-based)
-- Implement proper synchronization (wait for all subagents to complete)
+- Worker split: phase/work-unit separation with dependency ordering
+- Aggregation: merges gap analysis + coverage/gate data
+- Mode effect: orchestration policy only; final decision/report contract
+  unchanged
 
 ---
 
-## Testing Subagent Workflows
-
-### Test Checklist
-
-For each workflow with subagents:
-
-- [ ] **Unit Test**: Test each subagent in isolation
-  - Provide mock input JSON
-  - Verify output JSON structure
-  - Test error scenarios
-
-- [ ] **Integration Test**: Test full workflow
-  - Launch all subagents
-  - Verify parallel execution
-  - Verify aggregation logic
-  - Test with real project data
-
-- [ ] **Performance Test**: Measure speedup
-  - Benchmark sequential vs parallel
-  - Measure subagent overhead
-  - Verify memory usage acceptable
+## Design Guarantees
 
-- [ ] **Error Handling Test**: Test failure scenarios
-  - One subagent fails
-  - Multiple subagents fail
-  - Temp file read/write errors
-  - Timeout scenarios
+TEA maintains these guarantees across all modes:
 
-### Expected Performance Gains
+- Same output schema for a given workflow
+- Same validation and aggregation rules
+- Same deterministic fallback semantics
+- Same failure behavior for missing/invalid worker outputs
 
-**automate**:
-
-- Sequential: ~5-10 minutes (API then E2E)
-- Parallel: ~3-6 minutes (both at once)
-- **Speedup: ~40-50%**
-
-**test-review**:
-
-- Sequential: ~3-5 minutes (5 quality checks)
-- Parallel: ~1-2 minutes (all checks at once)
-- **Speedup: ~60-70%**
-
-**nfr-assess**:
-
-- Sequential: ~8-12 minutes (4 NFR domains)
-- Parallel: ~3-5 minutes (all domains at once)
-- **Speedup: ~60-70%**
+Mode selection changes orchestration behavior, not artifact contracts.
 
 ---
 
-## Documentation for Users
+## Practical Guidance
 
-Users don't need to know about subagent implementation details, but they should know:
+Recommended defaults:
 
-1. **Performance**: Certain workflows are optimized for parallel execution
-2. **Temp Files**: Workflows create temporary files during execution (cleaned up automatically)
-3. **Progress**: When running workflows, they may see multiple "subagent" indicators
-4. **Debugging**: If workflow fails, temp files may be preserved for troubleshooting
-
----
+```yaml
+tea_execution_mode: 'auto'
+tea_capability_probe: true
+```
 
-## Future Enhancements
+Use `sequential` when you need strict single-threaded execution or debugging
+clarity.
 
-1. **Subagent Pooling**: Reuse subagent containers for multiple operations
-2. **Adaptive Parallelization**: Dynamically decide whether to parallelize based on workload
-3. **Progress Reporting**: Real-time progress updates from each subagent
-4. **Caching**: Cache subagent outputs for identical inputs (idempotent operations)
-5. **Distributed Execution**: Run subagents on different machines for massive parallelization
+Use explicit `agent-team` or `subagent` only when you intentionally want that
+mode and understand runtime support in your environment.
 
 ---
 
-## References
+## Troubleshooting Signals
 
-- BMad Builder subagent examples: `_bmad/bmb/workflows/*/subagent-*.md`
-- Runtime-specific agent/subagent documentation (Codex, Claude Code, etc.)
-- TEA Workflow validation reports (proof of 100% compliance)
+Common causes of orchestration confusion:
 
----
+- Explicit run-level override text was provided and took precedence over config
+- Runtime did not support requested mode and fallback changed final mode
+- Probe disabled (`tea_capability_probe: false`) with unsupported explicit mode
 
-**Status**: Ready for implementation across 5 workflows
-**Next Steps**: Implement subagent patterns in workflow step files, test, document
+Check resolved mode logs in the workflow execution report to confirm what mode
+actually ran.

package/docs/reference/configuration.md

@@ -338,7 +338,7 @@ tea_browser_automation: 'none'
 
 ### tea_execution_mode
 
-Execution strategy for multi-worker orchestration steps in TEA workflows.
+Execution strategy for orchestration-capable TEA workflows.
 
 **Schema Location:** `src/module.yaml` (TEA module config)
 
@@ -356,47 +356,60 @@ Execution strategy for multi-worker orchestration steps in TEA workflows.
 How should TEA orchestrate multi-step generation and evaluation?
 ```
 
-**Purpose:** Controls orchestration behavior in workflows that can launch worker steps (currently `automate`, `atdd`, `test-review`, `nfr-assess`, `framework`, `ci`, `test-design`, and `trace`).
-
-| Mode         | Behavior                                                                                                         |
-| ------------ | ---------------------------------------------------------------------------------------------------------------- |
-| `auto`       | Probes runtime support and selects best mode. Order: `agent-team` → `subagent` → `sequential`. **Recommended**   |
-| `subagent`   | Uses isolated subagent-style workers (parallel where applicable). Verbal request term: `subagent` / `subagents`. |
-| `agent-team` | Uses runtime delegation/team workers when available. Verbal request terms: `agent team` / `agent teams`.         |
-| `sequential` | Runs worker steps one by one. Most deterministic, slowest.                                                       |
-
-**Runtime terminology note:** Claude terminology is `subagents` and `agent teams`. TEA uses `subagent` and `agent-team` as user-facing terms.
-
-**Resolution Order:**
-
-1. Normalize explicit run-level override text (if present):
-   - `agent team` / `agent teams` → `agent-team`
-   - `subagent` / `subagents` → `subagent`
-   - `sequential` → `sequential`
-   - `auto` → `auto`
-2. If no explicit run-level override is present, read `tea_execution_mode` from `_bmad/tea/config.yaml`.
+**Purpose:** Defines how TEA orchestrates worker-style steps in these workflows:
+
+- `automate`
+- `atdd`
+- `test-review`
+- `nfr-assess`
+- `framework`
+- `ci`
+- `test-design`
+- `trace`
+
+`teach-me-testing` does not use this setting.
+
+**Mode behavior:**
+
+| Mode         | Behavior                                                                                         |
+| ------------ | ------------------------------------------------------------------------------------------------ |
+| `auto`       | Recommended. TEA picks best supported mode using runtime capability checks (if probing enabled). |
+| `agent-team` | Prefer runtime team/delegation orchestration.                                                    |
+| `subagent`   | Prefer isolated subagent-style orchestration.                                                    |
+| `sequential` | Force one-by-one execution. Most deterministic, typically slowest.                               |
+
+**Important:** In `agent-team` and `subagent` modes, runtime decides scheduling and concurrency. TEA does not enforce a separate parallel-worker cap.
+
+**Per-workflow effect:**
+
+| Workflow      | Orchestrated unit                              | What mode changes    |
+| ------------- | ---------------------------------------------- | -------------------- |
+| `automate`    | API + E2E/backend generation workers           | Dispatch style only  |
+| `atdd`        | failing API + failing E2E workers              | Dispatch style only  |
+| `test-review` | quality-dimension workers                      | Dispatch style only  |
+| `nfr-assess`  | domain assessment workers                      | Dispatch style only  |
+| `framework`   | scaffold work units                            | Dispatch style only  |
+| `ci`          | orchestration-capable pipeline generation step | Orchestration policy |
+| `test-design` | orchestration-capable output generation step   | Orchestration policy |
+| `trace`       | phase/work-unit separation with dependencies   | Orchestration policy |
+
+Output contracts remain the same across modes for a given workflow.
+
+**Resolution order:**
+
+1. Normalize explicit run-level wording (if present):
+   - `agent team` / `agent teams` / `agentteam` -> `agent-team`
+   - `subagent` / `subagents` / `sub agent` / `sub agents` -> `subagent`
+   - `sequential` -> `sequential`
+   - `auto` -> `auto`
+2. If no explicit override exists, use `tea_execution_mode` from `_bmad/tea/config.yaml`.
 3. If `tea_capability_probe: true`, detect runtime support for `agent-team` and `subagent`.
-4. Resolve final mode:
-   - `auto` → `agent-team` → `subagent` → `sequential`
-   - `agent-team`/`subagent` → fallback to next supported mode when probing is enabled
-   - `sequential` → always sequential
-5. Execute the same workflow output contract in the resolved mode.
-
-**Verbal Request vs Config:**
-
-During workflow execution, explicit user text can override config for that run.
-
-Resolution precedence:
-
-1. Explicit user request in the active run (normalized):
-   - `agent team` / `agent teams` => `agent-team`
-   - `subagent` / `subagents` => `subagent`
-   - `sequential` => `sequential`
-   - `auto` => `auto`
-2. `tea_execution_mode` from `_bmad/tea/config.yaml`
-3. Runtime capability fallback when `tea_capability_probe: true`
+4. Resolve mode:
+   - `auto` -> `agent-team` -> `subagent` -> `sequential`
+   - explicit `agent-team`/`subagent` -> fallback only when probing is enabled
+   - `sequential` -> always sequential
 
-Default behavior when user says nothing is `auto` (or the configured value if explicitly set).
+Default when no explicit run request is given: configured value (typically `auto`).
 
 **Example (Recommended):**
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",

package/release_notes.md

@@ -1,13 +1,9 @@
-## 🚀 What's New in v1.4.0
-
-### ✨ New Features
-- feat: subprocess agent team config
-- feat: subprocess agent team config 2
+## 🚀 What's New in v1.4.1
 
 ### 📦 Other Changes
-- addressed review comments
-- do not set agent number
-- Merge pull request #47 from bmad-code-org/feat/subprocess-agent-team-config
+- docs: clarified how sub agents and agent teams work
+- addressed pr comments
+- Merge pull request #48 from bmad-code-org/docs/workers-subagents-agent-teams
 
 
 ## 📦 Installation
@@ -17,4 +13,4 @@ npx bmad-method install
 # Select "Test Architect" from module menu
 ```
 
-**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.3.2...v1.4.0
+**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.4.0...v1.4.1

package/website/astro.config.mjs

@@ -139,7 +139,6 @@ export default defineConfig({
             { label: 'Fixture Architecture', slug: 'explanation/fixture-architecture' },
             { label: 'Step-File Architecture', slug: 'explanation/step-file-architecture' },
             { label: 'Subagent Architecture', slug: 'explanation/subagent-architecture' },
-            { label: 'Subagent Implementation Status', slug: 'explanation/subagent-implementation-status' },
           ],
         },
         {

package/docs/explanation/subagent-implementation-status.md

@@ -1,327 +0,0 @@
----
-title: Subagent Implementation Status
-description: Status of subagent implementation across workflows
----
-
-# Subagent Pattern Implementation Status
-
-**Date**: 2026-01-27
-**Status**: Phase 5 - Subagent Patterns
-
----
-
-## ✅ Completed Implementations
-
-### 1. automate Workflow - COMPLETE ✅
-
-**Pattern**: Parallel API + E2E test generation
-
-**Files Created**:
-
-- `src/workflows/testarch/automate/steps-c/step-03a-*.md` (API subagent step)
-- `src/workflows/testarch/automate/steps-c/step-03b-*.md` (E2E subagent step)
-- `src/workflows/testarch/automate/steps-c/step-03c-aggregate.md`
-- Updated: `src/workflows/testarch/automate/steps-c/step-03-generate-tests.md`
-
-**Subagents**:
-
-- Subagent A: API test generation → `/tmp/tea-automate-api-tests-{{timestamp}}.json`
-- Subagent B: E2E test generation → `/tmp/tea-automate-e2e-tests-{{timestamp}}.json`
-- Aggregation: Reads both outputs, writes tests to disk, generates fixtures
-
-**Performance**: ~50% faster (parallel vs sequential)
-
----
-
-### 2. atdd Workflow - COMPLETE ✅
-
-**Pattern**: Parallel FAILING API + E2E test generation (TDD RED PHASE)
-
-**Files Created**:
-
-- `src/workflows/testarch/atdd/steps-c/step-04a-*.md` (API subagent step)
-- `src/workflows/testarch/atdd/steps-c/step-04b-*.md` (E2E subagent step)
-- `src/workflows/testarch/atdd/steps-c/step-04c-aggregate.md`
-- Updated: `src/workflows/testarch/atdd/steps-c/step-04-generate-tests.md`
-
-**Subagents**:
-
-- Subagent A: API failing tests (with test.skip()) → `/tmp/tea-atdd-api-tests-{{timestamp}}.json`
-- Subagent B: E2E failing tests (with test.skip()) → `/tmp/tea-atdd-e2e-tests-{{timestamp}}.json`
-- Aggregation: TDD red phase validation, writes tests, generates ATDD checklist
-
-**Performance**: ~50% faster (parallel vs sequential)
-
-**Special Features**: TDD compliance validation (all tests have test.skip())
-
----
-
-## 🟨 Implementation Guide for Remaining Workflows
-
-### 3. test-review Workflow - TO IMPLEMENT
-
-**Pattern**: 5 parallel quality dimension checks
-
-**Subagent Architecture**:
-
-```
-test-review/
-├── step-XX-orchestrate.md (updated to launch subagents)
-├── step-XXa-determinism.md
-├── step-XXb-isolation.md
-├── step-XXc-maintainability.md
-├── step-XXd-coverage.md
-├── step-XXe-performance.md
-└── step-XXz-aggregate-scores.md
-```
-
-**Subagent Outputs**:
-Each subagent outputs JSON with:
-
-```json
-{
-  "dimension": "determinism",
-  "score": 85,
-  "max_score": 100,
-  "violations": [
-    {
-      "file": "tests/api/user.spec.ts",
-      "line": 42,
-      "severity": "HIGH",
-      "description": "Test uses Math.random() - non-deterministic",
-      "suggestion": "Use faker with fixed seed"
-    }
-  ],
-  "passed_checks": 12,
-  "failed_checks": 3
-}
-```
-
-**Aggregation Logic**:
-
-- Read all 5 dimension outputs
-- Calculate weighted score (0-100)
-- Aggregate violations by severity
-- Generate review report with actionable suggestions
-
-**Performance**: ~60% faster (5 checks in parallel vs sequential)
-
-**Implementation Steps**:
-
-1. Create 5 subagent step files (one per quality dimension)
-2. Each subagent analyzes test files for its specific dimension
-3. Create aggregation step to calculate overall score
-4. Update orchestration step to launch all 5 subagents in parallel
-
----
-
-### 4. nfr-assess Workflow - TO IMPLEMENT
-
-**Pattern**: 4 parallel NFR domain assessments
-
-**Subagent Architecture**:
-
-```
-nfr-assess/
-├── step-XX-orchestrate.md (updated to launch subagents)
-├── step-XXa-security.md
-├── step-XXb-performance.md
-├── step-XXc-reliability.md
-├── step-XXd-scalability.md
-└── step-XXz-aggregate-report.md
-```
-
-**Subagent Outputs**:
-Each subagent outputs JSON with:
-
-```json
-{
-  "domain": "security",
-  "risk_level": "MEDIUM",
-  "findings": [
-    {
-      "category": "Authentication",
-      "status": "PASS",
-      "description": "OAuth2 with JWT tokens implemented",
-      "recommendations": []
-    },
-    {
-      "category": "Data Encryption",
-      "status": "CONCERN",
-      "description": "Database encryption at rest not enabled",
-      "recommendations": ["Enable database encryption", "Use AWS KMS"]
-    }
-  ],
-  "compliance": {
-    "SOC2": "PARTIAL",
-    "GDPR": "PASS",
-    "HIPAA": "N/A"
-  },
-  "priority_actions": ["Enable database encryption within 30 days"]
-}
-```
-
-**Aggregation Logic**:
-
-- Read all 4 NFR domain outputs
-- Calculate overall risk (max of all domain risks)
-- Aggregate compliance status
-- Identify cross-domain risks
-- Generate executive summary with priority actions
-
-**Performance**: ~67% faster (4 domains in parallel vs sequential)
-
-**Implementation Steps**:
-
-1. Create 4 subagent step files (one per NFR domain)
-2. Each subagent assesses system for its specific domain
-3. Create aggregation step to synthesize findings
-4. Update orchestration step to launch all 4 subagents in parallel
-
----
-
-### 5. trace Workflow - TO IMPLEMENT
-
-**Pattern**: Two-phase workflow separation (not parallel, but clean separation)
-
-**Subagent Architecture**:
-
-```
-trace/
-├── step-XX-phase-1-coverage-matrix.md (generates matrix → temp file)
-├── step-XX-phase-2-gate-decision.md (reads matrix → applies decision tree)
-```
-
-**Phase 1 Output**:
-
-```json
-{
-  "requirements": [
-    {
-      "id": "REQ-001",
-      "description": "User can login",
-      "priority": "P0",
-      "tests": ["tests/auth/login.spec.ts::should login"],
-      "coverage": "FULL"
-    },
-    {
-      "id": "REQ-002",
-      "description": "User can reset password",
-      "priority": "P1",
-      "tests": [],
-      "coverage": "NONE"
-    }
-  ],
-  "total_requirements": 50,
-  "covered_requirements": 42,
-  "coverage_percentage": 84
-}
-```
-
-**Phase 2 Logic**:
-
-- Read Phase 1 coverage matrix
-- Apply decision tree:
-  - P0 coverage == 100% AND overall >= 90% → PASS
-  - P0 coverage == 100% AND overall >= 75% → CONCERNS
-  - P0 coverage < 100% → FAIL
-  - Otherwise → WAIVED (manual review)
-- Generate gate report with recommendations
-
-**Performance**: Not about parallelization, but clean phase separation
-
-**Implementation Steps**:
-
-1. Split current trace workflow into 2 phases
-2. Phase 1: Generate coverage matrix to temp file
-3. Phase 2: Read matrix, apply gate logic, generate report
-4. Subagent-like isolation without actual parallel execution
-
----
-
-## 📊 Implementation Summary
-
-| Workflow        | Status          | Subagents              | Performance Gain | Complexity |
-| --------------- | --------------- | ---------------------- | ---------------- | ---------- |
-| **automate**    | ✅ Complete     | 2 (API, E2E)           | ~50%             | Medium     |
-| **atdd**        | ✅ Complete     | 2 (API RED, E2E RED)   | ~50%             | Medium     |
-| **test-review** | 🟨 To Implement | 5 (quality dimensions) | ~60%             | High       |
-| **nfr-assess**  | 🟨 To Implement | 4 (NFR domains)        | ~67%             | High       |
-| **trace**       | 🟨 To Implement | 2 phases (sequential)  | N/A              | Medium     |
-
----
-
-## 🎯 Implementation Priority
-
-**Priority 1 (Highest Impact - Already Done)**:
-
-- ✅ automate - Most frequently used
-- ✅ atdd - Frequently used, TDD workflow
-
-**Priority 2 (Next to Implement)**:
-
-- test-review - Complex validation, clear parallelization benefit
-- nfr-assess - Independent domains, high parallelization benefit
-
-**Priority 3 (Good Separation)**:
-
-- trace - Two-phase separation, clean design
-
----
-
-## 🚀 Next Steps
-
-### For test-review Implementation:
-
-1. Identify which step currently does quality checks
-2. Create 5 subagent step files (determinism, isolation, maintainability, coverage, performance)
-3. Each subagent analyzes test files for specific quality dimension
-4. Create aggregation step to calculate 0-100 score
-5. Update orchestration step to launch all 5 in parallel
-
-### For nfr-assess Implementation:
-
-1. Identify which step currently does NFR assessment
-2. Create 4 subagent step files (security, performance, reliability, scalability)
-3. Each subagent assesses system for specific NFR domain
-4. Create aggregation step to synthesize findings
-5. Update orchestration step to launch all 4 in parallel
-
-### For trace Implementation:
-
-1. Identify current trace workflow structure
-2. Split into Phase 1 (coverage matrix) and Phase 2 (gate decision)
-3. Phase 1 outputs to temp file
-4. Phase 2 reads temp file and applies decision logic
-5. Update workflow.yaml to point to new phase structure
-
----
-
-## 📝 Testing Checklist
-
-After implementing each workflow:
-
-- [ ] Create subagent step files
-- [ ] Update orchestration step
-- [ ] Test with real project data
-- [ ] Verify subagent outputs are valid JSON
-- [ ] Verify aggregation logic works correctly
-- [ ] Measure performance improvement
-- [ ] Run BMad Builder validation (should score 100%)
-- [ ] Document in subagent-architecture.md
-
----
-
-## 🔗 References
-
-- **Subagent Architecture**: `docs/explanation/subagent-architecture.md`
-- **Step-File Architecture**: `docs/explanation/step-file-architecture.md`
-- **Completed Examples**:
-  - `src/workflows/testarch/automate/steps-c/step-03*`
-  - `src/workflows/testarch/atdd/steps-c/step-04*`
-
----
-
-**Status**: 2 of 5 workflows complete, 3 remaining (implementation guide provided)
-**Next Action**: Implement test-review, nfr-assess, trace following established patterns
-**Expected Total Performance Gain**: 40-67% across all applicable workflows