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

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -22,7 +22,7 @@ Please check all that apply:
 
 - [ ] Workflows (test-design, automate, atdd, test-review, trace, nfr-assess, ci, framework)
 - [ ] Knowledge Base (new testing patterns or fragments)
-- [ ] Subprocess Architecture (parallel execution)
+- [ ] Subagent Architecture (parallel execution)
 - [ ] Configuration (module variables or settings)
 - [ ] Documentation (guides, tutorials, or references)
 - [ ] Integrations (Playwright Utils, MCP, or other tools)

package/CHANGELOG.md

@@ -31,8 +31,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - `true` -> `"auto"` (recommended), `false` -> `"none"`
 - All workflow preflight steps updated to read `tea_browser_automation`
 - All browser-touching workflow steps updated with CLI/MCP/auto branching
-- Subprocess context passes `browser_automation` instead of `use_mcp_enhancements`
+- Subagent context passes `browser_automation` instead of `use_mcp_enhancements`
 - Module subheader updated to reference Playwright CLI
+- **Breaking**: Orchestration terminology standardized to `subagent` / `agent-team` (removed `subprocess` wording)
+  - Renamed worker step files from `*-subprocess-*` to `*-subagent-*` in `automate`, `atdd`, `nfr-assess`, and `test-review`
+  - Updated orchestration mode resolution examples to use `subagent` only
+  - Renamed architecture docs: `subprocess-architecture.md` -> `subagent-architecture.md`, `subprocess-implementation-status.md` -> `subagent-implementation-status.md`
+  - Updated docs navigation, troubleshooting references, and workflow/resource indexes to new names
+  - Updated workflow contract labels/examples from `subprocess` to `subagent` (for example `subagent_execution`, `subagentType`)
 
 ### Deprecated
 
@@ -83,17 +89,17 @@ All workflows implement the **trivariate step pattern** (Create/Edit/Validate):
 
 4. **ATDD (`AT` / `/bmad:tea:atdd`)**
    - Generate failing acceptance tests (TDD red phase)
-   - **Subprocess Architecture**: Parallel API + E2E test generation
+   - **Subagent Architecture**: Parallel API + E2E test generation
    - Acceptance criteria validation checklist
 
 5. **Test Automation (`TA` / `/bmad:tea:automate`)**
    - Expand automation coverage systematically
-   - **Subprocess Architecture**: Parallel API + E2E test generation
+   - **Subagent Architecture**: Parallel API + E2E test generation
    - Coverage gap analysis and prioritization
 
 6. **Test Review (`RV` / `/bmad:tea:test-review`)**
    - Comprehensive test quality audit (0-100 scoring)
-   - **Subprocess Architecture**: Parallel evaluation across 5 quality dimensions
+   - **Subagent Architecture**: Parallel evaluation across 5 quality dimensions
      - Determinism
      - Isolation
      - Maintainability
@@ -108,24 +114,24 @@ All workflows implement the **trivariate step pattern** (Create/Edit/Validate):
 
 8. **NFR Assessment (`NR` / `/bmad:tea:nfr-assess`)**
    - Non-functional requirements evaluation
-   - **Subprocess Architecture**: Parallel assessment across 4 NFR domains
+   - **Subagent Architecture**: Parallel assessment across 4 NFR domains
      - Security
      - Performance
      - Reliability
      - Scalability
    - Evidence-based scoring with recommendations
 
-#### Subprocess Architecture (Phase 5)
+#### Subagent Architecture (Phase 5)
 
-- **19 Subprocess Step Files** for parallel execution:
-  - `automate`: 3 subprocess files (2 parallel + aggregate)
-  - `atdd`: 3 subprocess files (2 parallel + aggregate)
-  - `test-review`: 6 subprocess files (5 parallel + aggregate)
-  - `nfr-assess`: 5 subprocess files (4 parallel + aggregate)
+- **19 Subagent Step Files** for parallel execution:
+  - `automate`: 3 subagent files (2 parallel + aggregate)
+  - `atdd`: 3 subagent files (2 parallel + aggregate)
+  - `test-review`: 6 subagent files (5 parallel + aggregate)
+  - `nfr-assess`: 5 subagent files (4 parallel + aggregate)
   - `trace`: Two-phase separation (coverage → gate decision)
-- **Temp File Outputs**: Each subprocess writes to `/tmp/bmad-tea-*` files
-- **Aggregation Step**: Consolidates subprocess results into final output
-- **Documentation**: Complete subprocess architecture documentation in `docs/explanation/`
+- **Temp File Outputs**: Each subagent writes to `/tmp/bmad-tea-*` files
+- **Aggregation Step**: Consolidates subagent results into final output
+- **Documentation**: Complete subagent architecture documentation in `docs/explanation/`
 
 #### Knowledge Base System
 
@@ -197,7 +203,7 @@ All workflows implement the **trivariate step pattern** (Create/Edit/Validate):
   - `steps-v/` (Validate mode) - 1 step per workflow
 - **Validation Reports**: Comprehensive validation with checklist scoring
 - **Documentation Links**: All internal links validated and fixed (309 → 0 broken links)
-- **Subprocess Optimization**: Parallel execution for faster workflow completion
+- **Subagent Optimization**: Parallel execution for faster workflow completion
 
 ### Fixed
 
@@ -238,7 +244,7 @@ For users migrating from BMM-embedded TEA, see [`docs/MIGRATION.md`](docs/MIGRAT
 
 - **1.0.0** (2026-01-XX) - TEA Module Independence Release
   - Standalone module extraction from BMAD Method
-  - 9 workflows with subprocess architecture
+  - 9 workflows with subagent architecture
   - 34 knowledge base fragments
   - Complete documentation suite
 

package/README.md

@@ -60,7 +60,7 @@ flowchart LR
 4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one (`nextStepFile: './step-02-...'`). The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
 5. **Knowledge injection** — Step-01 reads `tea-index.csv` and selectively loads fragments by **tier** (core = always, extended = on-demand, specialized = only when relevant) and **config flags** (e.g., `tea_use_pactjs_utils`). This is deliberate context engineering: a backend project loads ~1,800 lines of fragments; a fullstack project loads ~4,500 lines. Conditional loading cuts context usage by 40-50%.
 6. **Templates** — When a step produces output (e.g., a traceability matrix or test review report), it reads the `*-template.md` file and fills in the `{PLACEHOLDER}` values with computed results. The template provides consistent structure; the step provides the content.
-7. **Subprocess isolation** — Heavy workflows (e.g., `automate`) spawn parallel subprocesses that each run in an isolated context. Subprocesses write structured JSON to temp files. An aggregation step reads the JSON outputs — only the results enter the main context, not the full subprocess history.
+7. **Subagent isolation** — Heavy workflows (e.g., `automate`) spawn parallel subagents that each run in an isolated context. Subagents write structured JSON to temp files. An aggregation step reads the JSON outputs — only the results enter the main context, not the full subagent history.
 8. **Progress tracking** — Each step appends to an output file with YAML frontmatter (`stepsCompleted`, `lastStep`, `lastSaved`). Resume mode reads this frontmatter and routes to the next incomplete step.
 9. **Validation** — The `steps-v/` mode reads `checklist.md` and evaluates the workflow's output against its criteria, producing a pass/fail validation report.
 
@@ -73,7 +73,7 @@ BMad workflows and Claude Code Skills solve different problems at different scal
 | **Execution**     | Single prompt, one shot     | 5-9 sequential steps with explicit handoffs                                  |
 | **State**         | Stateless                   | YAML frontmatter tracking (`stepsCompleted`, `lastStep`) with resume         |
 | **Knowledge**     | Whatever fits in one prompt | Tiered index (40 fragments), conditional loading by config + stack detection |
-| **Context mgmt**  | Everything in one shot      | Just-in-time step loading, subprocess isolation (separate contexts)          |
+| **Context mgmt**  | Everything in one shot      | Just-in-time step loading, subagent isolation (separate contexts)            |
 | **Output**        | Freeform                    | Templates with `{PLACEHOLDER}` vars filled by specific steps                 |
 | **Validation**    | None                        | Dedicated mode (`steps-v/`) evaluating against checklists                    |
 | **Configuration** | None                        | `module.yaml` with prompted config flags driving conditional behavior        |

package/docs/explanation/step-file-architecture.md

@@ -72,7 +72,7 @@ workflow/
 - Granular instructions → LLM focuses on one task
 - Clear exit conditions → LLM knows when to stop
 - Repeated context → LLM has all necessary info
-- Subprocess support → Parallel execution possible
+- Subagent support → Parallel execution possible
 
 ---
 
@@ -153,19 +153,19 @@ Example:
 - ❌ Do NOT add features not requested
 ```
 
-### 5. Subprocess Support
+### 5. Subagent Support
 
-**Independent steps can run in parallel subprocesses** - massive performance gain.
+**Independent steps can run in parallel subagents** - massive performance gain.
 
 Example (automate workflow):
 
 ```
 Step 1-2: Sequential (setup)
-Step 3: Subprocess A (API tests) + Subprocess B (E2E tests) - PARALLEL
+Step 3: Subagent A (API tests) + Subagent B (E2E tests) - PARALLEL
 Step 4: Sequential (aggregate)
 ```
 
-See [subprocess-architecture.md](./subprocess-architecture.md) for details.
+See [subagent-architecture.md](./subagent-architecture.md) for details.
 
 ---
 
@@ -193,8 +193,8 @@ Step 1: Setup → Step 2: Configure → Step 3: Generate → Step 4: Validate
 Step 1: Setup
 Step 2: Load knowledge
 Step 3: PARALLEL
-  ├── Subprocess A: Generate API tests
-  └── Subprocess B: Generate E2E tests
+  ├── Subagent A: Generate API tests
+  └── Subagent B: Generate E2E tests
 Step 4: Aggregate + validate
 ```
 
@@ -211,9 +211,9 @@ Step 4: Aggregate + validate
 ```
 Step 1: Load context
 Step 2: PARALLEL
-  ├── Subprocess A: Check dimension 1
-  ├── Subprocess B: Check dimension 2
-  ├── Subprocess C: Check dimension 3
+  ├── Subagent A: Check dimension 1
+  ├── Subagent B: Check dimension 2
+  ├── Subagent C: Check dimension 3
   └── (etc.)
 Step 3: Aggregate scores
 ```
@@ -237,7 +237,7 @@ Phase 2: Read matrix → Apply decision tree → Generate gate decision
 
 - Phase 2 depends on Phase 1 output
 - Not parallel, but clean separation of concerns
-- Subprocess-like phase isolation
+- Subagent-like phase isolation
 
 ### Pattern 5: Risk-Based Planning (Design Workflows)
 
@@ -354,7 +354,7 @@ Load `steps/step-[N+1]-[action].md` and execute.
 ### Example: Step File for API Test Generation
 
 ````markdown
-# Step 3A: Generate API Tests (Subprocess)
+# Step 3A: Generate API Tests (Subagent)
 
 ## Context (from previous steps)
 
@@ -397,7 +397,7 @@ Generate API tests for the 3 features identified above.
 
 ## What You MUST NOT Do
 
-- ❌ Do NOT generate E2E tests (that's Step 3B - parallel subprocess)
+- ❌ Do NOT generate E2E tests (that's Step 3B - parallel subagent)
 - ❌ Do NOT generate fixtures yet (that's Step 4)
 - ❌ Do NOT run tests yet (that's Step 5)
 - ❌ Do NOT use custom fetch/axios (use apiRequest helper)
@@ -425,14 +425,14 @@ Output JSON to `/tmp/automate-api-tests-{timestamp}.json`:
 
 ## Exit Condition
 
-You may finish this subprocess when:
+You may finish this subagent when:
 
 - ✅ All 3 features have API test files
 - ✅ All tests use Playwright Utils helpers
 - ✅ All tests use data factories
 - ✅ JSON output file written to /tmp/
 
-Subprocess complete. Main workflow will read output and proceed.
+Subagent complete. Main workflow will read output and proceed.
 
 ````
 
@@ -450,7 +450,7 @@ All 9 TEA workflows score **100%** on BMad Builder validation. Validation report
 - ✅ Explicit exit conditions (LLM knows when to stop)
 - ✅ Context injection (each step self-contained)
 - ✅ Strict action boundaries (prevents improvisation)
-- ✅ Subprocess support (where applicable)
+- ✅ Subagent support (where applicable)
 
 ### Real-Project Testing
 
@@ -479,7 +479,7 @@ Update step files when:
 1. **Knowledge fragments change**: Update fragment loading instructions
 2. **New patterns emerge**: Add new requirements/patterns to steps
 3. **LLM improvises**: Add stricter boundaries to prevent improvisation
-4. **Performance issues**: Split steps further or add subprocesses
+4. **Performance issues**: Split steps further or add subagents
 5. **User feedback**: Clarify ambiguous instructions
 
 ### Best Practices
@@ -510,7 +510,7 @@ Update step files when:
 - test-review: ~5 minutes (5 quality checks sequentially)
 - nfr-assess: ~12 minutes (4 NFR domains sequentially)
 
-**After Step Files (Parallel Subprocesses)**:
+**After Step Files (Parallel Subagents)**:
 
 - automate: ~5 minutes (API + E2E in parallel) - **50% faster**
 - test-review: ~2 minutes (all checks in parallel) - **60% faster**
@@ -538,9 +538,9 @@ When running workflows, users see:
 ```
 ✓ Step 1: Setup complete
 ✓ Step 2: Knowledge fragments loaded
-⟳ Step 3: Generating tests (2 subprocesses running)
-  ├── Subprocess A: API tests... ✓
-  └── Subprocess B: E2E tests... ✓
+⟳ Step 3: Generating tests (2 subagents running)
+  ├── Subagent A: API tests... ✓
+  └── Subagent B: E2E tests... ✓
 ✓ Step 4: Aggregating results
 ✓ Step 5: Validation complete
 ```
@@ -556,7 +556,7 @@ When running workflows, users see:
 - **Diagnosis**: Step instructions too vague
 - **Fix**: Add more explicit requirements and forbidden actions
 
-**Issue**: Subprocess output not aggregating correctly
+**Issue**: Subagent output not aggregating correctly
 
 - **Diagnosis**: Temp file path mismatch or JSON parsing error
 - **Fix**: Check temp file naming convention, verify JSON format
@@ -566,16 +566,16 @@ When running workflows, users see:
 - **Diagnosis**: Fragment loading instructions unclear
 - **Fix**: Make fragment usage requirements more explicit
 
-**Issue**: Workflow too slow despite subprocesses
+**Issue**: Workflow too slow despite subagents
 
 - **Diagnosis**: Not enough parallelization
-- **Fix**: Identify more independent steps for subprocess pattern
+- **Fix**: Identify more independent steps for subagent pattern
 
 ---
 
 ## References
 
-- **Subprocess Architecture**: [subprocess-architecture.md](./subprocess-architecture.md)
+- **Subagent Architecture**: [subagent-architecture.md](./subagent-architecture.md)
 - **Knowledge Base System**: [knowledge-base-system.md](./knowledge-base-system.md)
 - **BMad Builder Validation Reports**: `src/workflows/testarch/*/validation-report-*.md`
 - **TEA Workflow Examples**: `src/workflows/testarch/*/steps/*.md`
@@ -595,5 +595,5 @@ When running workflows, users see:
 **Status**: Production-ready, 100% LLM compliance achieved
 **Validation**: All 9 workflows score 100% on BMad Builder validation
 **Testing**: All 9 workflows tested with real projects, zero improvisation issues
-**Next Steps**: Implement subprocess patterns (see subprocess-architecture.md)
+**Next Steps**: Implement subagent patterns (see subagent-architecture.md)
 ````

package/docs/explanation/subagent-architecture.md

@@ -0,0 +1,189 @@
+---
+title: Subagent Architecture
+description: How TEA uses subagents and agent teams across workflows
+---
+
+# Subagents and Agent Teams in TEA
+
+This guide explains how TEA orchestrates work when a workflow can split into
+worker steps (independent workers or dependency-ordered work units).
+
+## Scope
+
+This applies to these workflows:
+
+- `automate`
+- `atdd`
+- `test-review`
+- `nfr-assess`
+- `framework`
+- `ci`
+- `test-design`
+- `trace`
+
+It does not apply to `teach-me-testing`.
+
+---
+
+## Core Model
+
+TEA orchestration has three parts:
+
+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
+
+Workers are isolated and exchange data through structured outputs that the
+aggregation step validates.
+
+---
+
+## Execution Modes
+
+TEA supports four modes:
+
+- `auto`
+- `agent-team`
+- `subagent`
+- `sequential`
+
+### What Each Mode Means
+
+- `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.
+
+### Fallback Behavior
+
+When `tea_capability_probe: true`, TEA can fallback safely:
+
+- `auto` falls back in order: `agent-team` -> `subagent` -> `sequential`
+- explicit `agent-team` or `subagent` falls back to next supported mode
+- `sequential` always stays sequential
+
+When `tea_capability_probe: false`, TEA honors the requested mode strictly and
+fails if runtime cannot execute it.
+
+### Runtime Scheduling
+
+In `agent-team` and `subagent` modes, runtime decides concurrency and timing.
+TEA does not impose its own parallel worker limit.
+
+---
+
+## Verbal Override Rules
+
+During a run, explicit user phrasing can override config for that run only.
+
+Supported normalized terms:
+
+- `agent team` or `agent teams` -> `agent-team`
+- `agentteam` -> `agent-team`
+- `subagent`, `subagents`, `sub agent`, or `sub agents` -> `subagent`
+- `sequential` -> `sequential`
+- `auto` -> `auto`
+
+Resolution precedence:
+
+1. Explicit run-level request (if present)
+2. `tea_execution_mode` in config
+3. Runtime fallback (when probing is enabled)
+
+---
+
+## Workflow Coverage Map
+
+### `automate`
+
+- 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
+
+### `atdd`
+
+- 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
+
+### `test-review`
+
+- Worker split: quality-dimension evaluations (determinism, isolation,
+  maintainability, performance)
+- Aggregation: computes combined quality score/report
+- Mode effect: changes orchestration style only, not scoring schema
+
+### `nfr-assess`
+
+- Worker split: security, performance, reliability, scalability assessments
+- Aggregation: computes overall risk, compliance summary, priority actions
+- Mode effect: changes orchestration style only, not report schema
+
+### `framework`
+
+- Worker split: scaffold work units (structure/config, fixtures, samples)
+- Aggregation: consolidates generated framework setup outputs
+- Mode effect: changes orchestration style only
+
+### `ci`
+
+- 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
+
+### `test-design`
+
+- Worker split: orchestration-capable mode resolution for output generation
+- Aggregation: deterministic design artifact output
+- Mode effect: orchestration policy only; output schema unchanged
+
+### `trace`
+
+- 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
+
+---
+
+## Design Guarantees
+
+TEA maintains these guarantees across all modes:
+
+- Same output schema for a given workflow
+- Same validation and aggregation rules
+- Same deterministic fallback semantics
+- Same failure behavior for missing/invalid worker outputs
+
+Mode selection changes orchestration behavior, not artifact contracts.
+
+---
+
+## Practical Guidance
+
+Recommended defaults:
+
+```yaml
+tea_execution_mode: 'auto'
+tea_capability_probe: true
+```
+
+Use `sequential` when you need strict single-threaded execution or debugging
+clarity.
+
+Use explicit `agent-team` or `subagent` only when you intentionally want that
+mode and understand runtime support in your environment.
+
+---
+
+## Troubleshooting Signals
+
+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
+
+Check resolved mode logs in the workflow execution report to confirm what mode
+actually ran.