bmad-studio 0.1.0

package/_bmad/tea/workflows/testarch/bmad-testarch-automate/steps-c/step-03-generate-tests.md

@@ -0,0 +1,394 @@
+---
+name: 'step-03-generate-tests'
+description: 'Orchestrate adaptive test generation (agent-team, subagent, or sequential)'
+nextStepFile: './step-03c-aggregate.md'
+---
+
+# Step 3: Orchestrate Adaptive Test Generation
+
+## STEP GOAL
+
+Select execution mode deterministically, then generate tests using agent-team, subagent, or sequential execution while preserving the same output contract. Worker selection depends on `{detected_stack}`.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Resolve execution mode from config (`tea_execution_mode`, `tea_capability_probe`)
+- ✅ Apply fallback rules deterministically when requested mode is unsupported
+- ✅ Preserve output schema and temp file naming across all modes
+- ❌ Do NOT skip capability checks when probing is enabled
+- ❌ Do NOT change output paths or JSON schema by mode
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Wait for subagent outputs
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, coverage plan from Step 2, knowledge fragments
+- Focus: orchestration only (mode selection + worker dispatch)
+- Limits: do not generate tests directly (delegate to worker steps)
+- Dependencies: Step 2 outputs (coverage plan, target features)
+
+---
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Prepare Execution Context
+
+**Generate unique timestamp** for temp file naming:
+
+```javascript
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+```
+
+**Prepare input context for subagents:**
+
+```javascript
+const parseBooleanFlag = (value, defaultValue = true) => {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['false', '0', 'off', 'no'].includes(normalized)) return false;
+    if (['true', '1', 'on', 'yes'].includes(normalized)) return true;
+  }
+  if (value === undefined || value === null) return defaultValue;
+  return Boolean(value);
+};
+
+const subagentContext = {
+  features: /* from Step 2 coverage plan */,
+  knowledge_fragments_loaded: /* list of fragments */,
+  config: {
+    test_framework: config.test_framework,
+    use_playwright_utils: config.tea_use_playwright_utils,
+    use_pactjs_utils: config.tea_use_pactjs_utils,
+    pact_mcp: config.tea_pact_mcp,  // "mcp" | "none"
+    browser_automation: config.tea_browser_automation,  // "auto" | "cli" | "mcp" | "none"
+    detected_stack: '{detected_stack}',  // "frontend" | "backend" | "fullstack"
+    execution_mode: config.tea_execution_mode || 'auto',  // "auto" | "subagent" | "agent-team" | "sequential"
+    capability_probe: parseBooleanFlag(config.tea_capability_probe, true),  // supports booleans and "false"/"true" strings
+    provider_endpoint_map: /* from Step 2 coverage plan, if use_pactjs_utils enabled */,
+  },
+  timestamp: timestamp
+};
+```
+
+---
+
+### 2. Resolve Execution Mode with Capability Probe
+
+```javascript
+const normalizeUserExecutionMode = (mode) => {
+  if (typeof mode !== 'string') return null;
+  const normalized = mode.trim().toLowerCase().replace(/[-_]/g, ' ').replace(/\s+/g, ' ');
+
+  if (normalized === 'auto') return 'auto';
+  if (normalized === 'sequential') return 'sequential';
+  if (normalized === 'subagent' || normalized === 'sub agent' || normalized === 'subagents' || normalized === 'sub agents') {
+    return 'subagent';
+  }
+  if (normalized === 'agent team' || normalized === 'agent teams' || normalized === 'agentteam') {
+    return 'agent-team';
+  }
+
+  return null;
+};
+
+const normalizeConfigExecutionMode = (mode) => {
+  if (mode === 'subagent') return 'subagent';
+  if (mode === 'auto' || mode === 'sequential' || mode === 'subagent' || mode === 'agent-team') {
+    return mode;
+  }
+  return null;
+};
+
+// Explicit user instruction in the active run takes priority over config.
+const explicitModeFromUser = normalizeUserExecutionMode(runtime.getExplicitExecutionModeHint?.() || null);
+
+const requestedMode = explicitModeFromUser || normalizeConfigExecutionMode(subagentContext.config.execution_mode) || 'auto';
+const probeEnabled = subagentContext.config.capability_probe;
+
+const supports = {
+  subagent: false,
+  agentTeam: false,
+};
+
+if (probeEnabled) {
+  // Probe using runtime-native capability checks or a no-op launch test.
+  supports.subagent = runtime.canLaunchSubagents?.() === true;
+  supports.agentTeam = runtime.canLaunchAgentTeams?.() === true;
+}
+
+let resolvedMode = requestedMode;
+
+if (requestedMode === 'auto') {
+  if (supports.agentTeam) resolvedMode = 'agent-team';
+  else if (supports.subagent) resolvedMode = 'subagent';
+  else resolvedMode = 'sequential';
+} else if (probeEnabled && requestedMode === 'agent-team' && !supports.agentTeam) {
+  resolvedMode = supports.subagent ? 'subagent' : 'sequential';
+} else if (probeEnabled && requestedMode === 'subagent' && !supports.subagent) {
+  resolvedMode = 'sequential';
+}
+
+subagentContext.execution = {
+  requestedMode,
+  resolvedMode,
+  probeEnabled,
+  supports,
+};
+```
+
+Resolution precedence:
+
+1. Explicit user request in this run (`agent team` => `agent-team`; `subagent` => `subagent`; `sequential`; `auto`)
+2. `tea_execution_mode` from config
+3. Runtime capability fallback (when probing enabled)
+
+If probing is disabled, honor the requested mode strictly. If that mode cannot be executed at runtime, fail with explicit error instead of silent fallback.
+
+Report selected mode before dispatch:
+
+```
+⚙️ Execution Mode Resolution:
+- Requested: {requestedMode}
+- Probe Enabled: {probeEnabled}
+- Supports agent-team: {supports.agentTeam}
+- Supports subagent: {supports.subagent}
+- Resolved: {resolvedMode}
+```
+
+---
+
+### 3. Subagent Dispatch Matrix
+
+**Select subagents based on `{detected_stack}`:**
+
+| `{detected_stack}` | Subagent A (API) | Subagent B (E2E) | Subagent B-backend |
+| ------------------ | ---------------- | ---------------- | ------------------ |
+| `frontend`         | Launch           | Launch           | Skip               |
+| `backend`          | Launch           | Skip             | Launch             |
+| `fullstack`        | Launch           | Launch           | Launch             |
+
+### 3A. Runtime-Managed Parallelism
+
+When `resolvedMode` is `agent-team` or `subagent`, let the runtime decide concurrency and scheduling. TEA does not impose an additional worker ceiling.
+
+---
+
+### Contract Test Generation Note
+
+When `use_pactjs_utils` is enabled, the API test generation subagent (step-03a) also generates:
+
+- **Consumer contract tests**: Using `createProviderState` for type-safe provider states
+- **Provider verification tests**: Using `buildVerifierOptions` for one-call verifier setup
+- **Message contract tests**: Using `buildMessageVerifierOptions` if async/Kafka patterns detected
+- **Helper files**: Request filter setup with `createRequestFilter`, shared state constants
+- **Provider scrutiny**: Subagent reads provider route handlers, types, and validation schemas before generating each interaction (see `contract-testing.md` Provider Scrutiny Protocol)
+
+When `pact_mcp` is `"mcp"`, the subagent can use SmartBear MCP tools to fetch existing provider states and generate tests informed by broker data.
+
+---
+
+### 4. Dispatch Worker A: API Test Generation (always)
+
+**Dispatch worker:**
+
+- **Subagent File:** `./step-03a-subagent-api.md`
+- **Output File:** `/tmp/tea-automate-api-tests-${timestamp}.json`
+- **Context:** Pass `subagentContext`
+- **Execution:**
+  - `agent-team` or `subagent`: launch non-blocking
+  - `sequential`: run blocking and wait before next dispatch
+
+**System Action:**
+
+```
+🚀 Launching Subagent A: API Test Generation
+📝 Output: /tmp/tea-automate-api-tests-${timestamp}.json
+⚙️ Mode: ${resolvedMode}
+⏳ Status: Running...
+```
+
+---
+
+### 5. Dispatch Worker B: E2E Test Generation (frontend/fullstack only)
+
+**If {detected_stack} is `frontend` or `fullstack`:**
+
+**Dispatch worker:**
+
+- **Subagent File:** `./step-03b-subagent-e2e.md`
+- **Output File:** `/tmp/tea-automate-e2e-tests-${timestamp}.json`
+- **Context:** Pass `subagentContext`
+- **Execution:**
+  - `agent-team` or `subagent`: launch non-blocking
+  - `sequential`: run blocking and wait before next dispatch
+
+**System Action:**
+
+```
+🚀 Launching Subagent B: E2E Test Generation
+📝 Output: /tmp/tea-automate-e2e-tests-${timestamp}.json
+⚙️ Mode: ${resolvedMode}
+⏳ Status: Running...
+```
+
+**If {detected_stack} is `backend`:** Skip this subagent.
+
+---
+
+### 6. Dispatch Worker B-backend: Backend Test Generation (backend/fullstack only)
+
+**If {detected_stack} is `backend` or `fullstack`:**
+
+**Dispatch worker:**
+
+- **Subagent File:** `./step-03b-subagent-backend.md`
+- **Output File:** `/tmp/tea-automate-backend-tests-${timestamp}.json`
+- **Context:** Pass `subagentContext`
+- **Execution:**
+  - `agent-team` or `subagent`: launch non-blocking
+  - `sequential`: run blocking and wait before next dispatch
+
+**System Action:**
+
+```
+🚀 Launching Subagent B-backend: Backend Test Generation
+📝 Output: /tmp/tea-automate-backend-tests-${timestamp}.json
+⚙️ Mode: ${resolvedMode}
+⏳ Status: Running...
+```
+
+**If {detected_stack} is `frontend`:** Skip this subagent.
+
+---
+
+### 7. Wait for Expected Worker Completion
+
+**If `resolvedMode` is `agent-team` or `subagent`:**
+
+```
+⏳ Waiting for subagents to complete...
+  ├── Subagent A (API): Running... ⟳
+  ├── Subagent B (E2E): Running... ⟳       [if frontend/fullstack]
+  └── Subagent B-backend: Running... ⟳     [if backend/fullstack]
+
+[... time passes ...]
+
+  ├── Subagent A (API): Complete ✅
+  ├── Subagent B (E2E): Complete ✅         [if frontend/fullstack]
+  └── Subagent B-backend: Complete ✅       [if backend/fullstack]
+
+✅ All subagents completed successfully!
+```
+
+**If `resolvedMode` is `sequential`:**
+
+```
+✅ Sequential mode: each worker already completed during dispatch.
+```
+
+**Verify outputs exist (based on `{detected_stack}`):**
+
+```javascript
+const apiOutputExists = fs.existsSync(`/tmp/tea-automate-api-tests-${timestamp}.json`);
+
+// Check based on detected_stack
+if (detected_stack === 'frontend' || detected_stack === 'fullstack') {
+  const e2eOutputExists = fs.existsSync(`/tmp/tea-automate-e2e-tests-${timestamp}.json`);
+  if (!e2eOutputExists) throw new Error('E2E subagent output missing!');
+}
+if (detected_stack === 'backend' || detected_stack === 'fullstack') {
+  const backendOutputExists = fs.existsSync(`/tmp/tea-automate-backend-tests-${timestamp}.json`);
+  if (!backendOutputExists) throw new Error('Backend subagent output missing!');
+}
+if (!apiOutputExists) throw new Error('API subagent output missing!');
+```
+
+---
+
+### Subagent Output Schema Contract
+
+The aggregate step expects both outputs to include `success`, but the payload shapes are intentionally different:
+
+- `step-03b-subagent-e2e.md` output includes `success`, `subagent`, `tests`, `fixture_needs`, `knowledge_fragments_used`, `test_count`, and `summary`.
+- `step-03b-subagent-backend.md` output includes `success`, `subagent`, `subagentType`, `testsGenerated`, `coverageSummary` (with `fixtureNeeds`), `status`, `knowledge_fragments_used`, and `summary`.
+
+The aggregate step reads whichever output file(s) exist based on `{detected_stack}` and must use the matching schema per subagent type.
+
+---
+
+### 8. Execution Report
+
+**Display performance metrics:**
+
+```
+🚀 Performance Report:
+- Execution Mode: {resolvedMode}
+- Stack Type: {detected_stack}
+- API Test Generation: ~X minutes
+- E2E Test Generation: ~Y minutes       [if frontend/fullstack]
+- Backend Test Generation: ~Z minutes    [if backend/fullstack]
+- Total Elapsed: ~mode-dependent
+- Parallel Gain: ~40-70% faster when mode is subagent/agent-team
+```
+
+---
+
+### 9. Proceed to Aggregation
+
+**Load aggregation step:**
+Load next step: `{nextStepFile}`
+
+The aggregation step (3C) will:
+
+- Read all subagent outputs (based on `{detected_stack}`)
+- Write all test files to disk
+- Generate shared fixtures and helpers
+- Calculate summary statistics
+
+---
+
+## EXIT CONDITION
+
+Proceed to Step 3C (Aggregation) when:
+
+- ✅ Subagent A (API tests) completed successfully
+- ✅ Subagent B (E2E tests) completed successfully [if frontend/fullstack]
+- ✅ Subagent B-backend (Backend tests) completed successfully [if backend/fullstack]
+- ✅ All expected output files exist and are valid JSON
+- ✅ Execution metrics displayed
+
+**Do NOT proceed if:**
+
+- ❌ Any launched subagent failed
+- ❌ Output files missing or corrupted
+- ❌ Timeout occurred (parallel mode only)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- All required subagents launched successfully (based on `{detected_stack}`)
+- All required worker steps completed without errors
+- Output files generated and valid
+- Fallback behavior respected configuration and capability probe rules
+
+### ❌ SYSTEM FAILURE:
+
+- Failed to launch subagents
+- One or more subagents failed
+- Output files missing or invalid
+- Unsupported requested mode with probing disabled
+
+**Master Rule:** Deterministic mode selection + stable output contract. Use the best supported mode, then aggregate normally.

package/_bmad/tea/workflows/testarch/bmad-testarch-automate/steps-c/step-03a-subagent-api.md

@@ -0,0 +1,263 @@
+---
+name: 'step-03a-subagent-api'
+description: 'Subagent: Generate API tests only'
+subagent: true
+outputFile: '/tmp/tea-automate-api-tests-{{timestamp}}.json'
+---
+
+# Subagent 3A: Generate API Tests
+
+## SUBAGENT CONTEXT
+
+This is an **isolated subagent** running in parallel with E2E test generation.
+
+**What you have from parent workflow:**
+
+- Target features/components identified in Step 2
+- Knowledge fragments loaded: api-request, data-factories, api-testing-patterns
+- Config: test framework, Playwright Utils enabled/disabled, Pact.js Utils enabled/disabled, Pact MCP mode
+- Coverage plan: which API endpoints need testing
+
+**Your task:** Generate API tests ONLY (not E2E, not fixtures, not other test types).
+
+**If `use_pactjs_utils` is enabled:** Also generate consumer contract tests and provider verification tests alongside API tests. Use the loaded pactjs-utils fragments (`pactjs-utils-overview`, `pactjs-utils-consumer-helpers`, `pactjs-utils-provider-verifier`, `pactjs-utils-request-filter`) for patterns. If `pact_mcp` is `"mcp"`, use SmartBear MCP tools (Fetch Provider States, Generate Pact Tests) to inform test generation.
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subagent file before acting
+- ✅ Generate API tests ONLY
+- ✅ Output structured JSON to temp file
+- ✅ Follow knowledge fragment patterns
+- ❌ Do NOT generate E2E tests (that's subagent 3B)
+- ❌ Do NOT run tests (that's step 4)
+- ❌ Do NOT generate fixtures yet (that's step 3C aggregation)
+
+---
+
+## SUBAGENT TASK
+
+### 1. Identify API Endpoints
+
+From the coverage plan (Step 2 output), identify:
+
+- Which API endpoints need test coverage
+- Expected request/response formats
+- Authentication requirements
+- Error scenarios to test
+
+### 2. Generate API Test Files
+
+For each API endpoint, create test file in `tests/api/[feature].spec.ts`:
+
+**Test Structure:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+// If Playwright Utils enabled:
+// import { apiRequest } from '@playwright-utils/api';
+
+test.describe('[Feature] API Tests', () => {
+  test('[P0] should handle successful [operation]', async ({ request }) => {
+    // Use apiRequest helper if Playwright Utils enabled
+    // Otherwise use standard request fixture
+    const response = await request.post('/api/endpoint', {
+      data: {
+        /* test data */
+      },
+    });
+
+    expect(response.status()).toBe(200);
+    expect(await response.json()).toMatchObject({
+      /* expected */
+    });
+  });
+
+  test('[P1] should handle [error scenario]', async ({ request }) => {
+    // Test error handling
+  });
+});
+```
+
+**Requirements:**
+
+- ✅ Use `apiRequest()` helper if Playwright Utils enabled (from api-request fragment)
+- ✅ Use data factories for test data (from data-factories fragment)
+- ✅ Follow API testing patterns (from api-testing-patterns fragment)
+- ✅ Include priority tags [P0], [P1], [P2], [P3]
+- ✅ Test both happy path and error scenarios
+- ✅ Use proper TypeScript types
+- ✅ Deterministic assertions (no timing dependencies)
+
+**If Pact.js Utils enabled (from `subagentContext.config.use_pactjs_utils`):**
+
+- ✅ Generate consumer contract tests in `pact/http/consumer/` using `createProviderState({ name, params })` pattern
+- ✅ Generate provider verification tests in `pact/http/provider/` using `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` pattern
+- ✅ Generate request filter helpers in `pact/http/helpers/` using `createRequestFilter({ tokenGenerator: () => string })`
+- ✅ Generate shared state constants in `pact/http/helpers/states.ts`
+- ✅ If async/message patterns detected, generate message consumer tests in `pact/message/` using `buildMessageVerifierOptions`
+- ✅ **Provider endpoint comment MANDATORY** on every Pact interaction: `// Provider endpoint: <path> -> <METHOD> <route>`
+- ⚠️ **Postel's Law for matchers**: Use `like()`, `eachLike()`, `string()`, `integer()` matchers ONLY in `willRespondWith` (responses). Request bodies in `withRequest` MUST use exact values — never wrap request bodies in `like()`. The consumer controls what it sends, so contracts should be strict about request shape.
+
+### 1.5 Provider Source Scrutiny (CDC Only)
+
+**CRITICAL**: Before generating ANY Pact consumer interaction, perform provider source scrutiny per the **Seven-Point Scrutiny Checklist** defined in `contract-testing.md`. Do NOT generate response matchers from consumer-side types alone — this is the #1 cause of contract verification failures.
+
+The seven points to verify for each interaction:
+
+1. Response shape
+2. Status codes
+3. Field names
+4. Enum values
+5. Required fields
+6. Data types
+7. Nested structures
+
+**Source priority**: Provider source code is most authoritative. When an OpenAPI/Swagger spec exists (`openapi.yaml`, `openapi.json`, `swagger.json`), use it as a complementary or alternative source — it documents the provider's contract explicitly and can be faster to parse than tracing through handler code. When both exist, cross-reference them; if they disagree, the source code wins. Document the discrepancy in the scrutiny evidence block (e.g., `OpenAPI shows 200 but handler returns 201; using handler behavior`) and flag it in the output JSON `summary` so it is discoverable by downstream consumers or audits.
+
+**Scrutiny Sequence** (for each endpoint in the coverage plan):
+
+1. **READ provider route handler and/or OpenAPI spec**: Find the handler file from `subagentContext.config.provider_endpoint_map` or by scanning the provider codebase. Also check for OpenAPI/Swagger spec files. Extract:
+   - Exact status codes returned (`res.status(201)` / OpenAPI `responses` keys)
+   - Response construction (`res.json({ data: ... })` / OpenAPI `schema`)
+   - Error handling paths (what status codes for what conditions)
+
+2. **READ provider type/model/DTO definitions**: Find the response type referenced by the handler or OpenAPI `$ref` schemas. Extract:
+   - Exact field names (`transaction_id` not `transactionId`)
+   - Field types (`string` ID vs `number` ID / OpenAPI `type` + `format`)
+   - Optional vs required fields (OpenAPI `required` array)
+   - Nested object structures (OpenAPI `$ref`, `allOf`, `oneOf`)
+
+3. **READ provider validation schemas**: Find Joi/Zod/class-validator schemas or OpenAPI request body `schema.required`. Extract:
+   - Required request fields and headers
+   - Enum/union type allowed values (`"active" | "inactive"` / OpenAPI `enum`)
+   - Request body constraints
+
+4. **Cross-reference findings** against consumer expectations:
+   - Does the consumer expect the same field names the provider sends?
+   - Does the consumer expect the same status codes the provider returns?
+   - Does the consumer expect the same nesting the provider produces?
+
+5. **Document scrutiny evidence** as a block comment in the generated test:
+
+```typescript
+/*
+ * Provider Scrutiny Evidence:
+ * - Handler: server/src/routes/userHandlers.ts:45
+ * - OpenAPI: server/openapi.yaml paths./api/v2/users/{userId}.get (if available)
+ * - Response type: UserResponseDto (server/src/types/user.ts:12)
+ * - Status: 201 for creation (line 52), 400 for validation error (line 48)
+ * - Fields: { id: number, name: string, email: string, role: "user" | "admin" }
+ * - Required request headers: Authorization (Bearer token)
+ */
+```
+
+6. **Graceful degradation** when provider source is not accessible (follows the canonical four-step protocol from `contract-testing.md`):
+   1. **OpenAPI/Swagger spec available**: Use the spec as the source of truth for response shapes, status codes, and field names
+   2. **Pact Broker available** (when `pact_mcp` is `"mcp"` in `subagentContext.config`): Use SmartBear MCP tools to fetch existing provider states and verified interactions as reference
+   3. **Neither available**: Generate from consumer types but use the TODO form of the mandatory comment: `// Provider endpoint: TODO — provider source not accessible, verify manually`. Set `provider_scrutiny: "pending"` in output JSON
+   4. **Never silently guess**: Document all assumptions in the scrutiny evidence block
+
+> ⚠️ **Anti-pattern**: Generating response matchers from consumer-side types alone. This produces contracts that reflect what the consumer _wishes_ the provider returns, not what it _actually_ returns. Always read provider source or OpenAPI spec first.
+
+### 3. Track Fixture Needs
+
+Identify fixtures needed for API tests:
+
+- Authentication fixtures (auth tokens, API keys)
+- Data factories (user data, product data, etc.)
+- API client configurations
+
+**Do NOT create fixtures yet** - just track what's needed for aggregation step.
+
+---
+
+## OUTPUT FORMAT
+
+Write JSON to temp file: `/tmp/tea-automate-api-tests-{{timestamp}}.json`
+
+```json
+{
+  "success": true,
+  "subagent": "api-tests",
+  "tests": [
+    {
+      "file": "tests/api/auth.spec.ts",
+      "content": "[full TypeScript test file content]",
+      "description": "API tests for authentication endpoints",
+      "priority_coverage": {
+        "P0": 3,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    },
+    {
+      "file": "tests/api/checkout.spec.ts",
+      "content": "[full TypeScript test file content]",
+      "description": "API tests for checkout endpoints",
+      "priority_coverage": {
+        "P0": 2,
+        "P1": 3,
+        "P2": 1,
+        "P3": 0
+      }
+    }
+  ],
+  "fixture_needs": ["authToken", "userDataFactory", "productDataFactory"],
+  "knowledge_fragments_used": ["api-request", "data-factories", "api-testing-patterns"],
+  "provider_scrutiny": "completed",
+  "provider_files_read": ["server/src/routes/authHandlers.ts", "server/src/routes/checkoutHandlers.ts", "server/src/types/auth.ts"],
+  "test_count": 12,
+  "summary": "Generated 12 API test cases covering 3 features"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "success": false,
+  "subagent": "api-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subagent completes when:
+
+- ✅ All API endpoints have test files generated
+- ✅ All tests follow knowledge fragment patterns
+- ✅ JSON output written to temp file
+- ✅ Fixture needs tracked
+
+**Subagent terminates here.** Parent workflow will read output and proceed to aggregation.
+
+---
+
+## 🚨 SUBAGENT SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- All API tests generated following patterns
+- JSON output valid and complete
+- No E2E/component/unit tests included (out of scope)
+- Every Pact interaction has `// Provider endpoint:` comment (if CDC enabled)
+- Provider source scrutiny completed or gracefully degraded with TODO markers (if CDC enabled)
+- Scrutiny evidence documented as block comments in test files (if CDC enabled)
+
+### ❌ FAILURE:
+
+- Generated tests other than API tests
+- Did not follow knowledge fragment patterns
+- Invalid or missing JSON output
+- Ran tests (not subagent responsibility)
+- Pact interactions missing provider endpoint comments (if CDC enabled)
+- Response matchers generated from consumer-side types without provider scrutiny (if CDC enabled)