@cregis-dev/cckit 0.3.0 → 0.4.1

package/templates/bmad/tea/workflows/testarch/atdd/steps-c/step-04-generate-tests.md

@@ -1,39 +1,40 @@
 ---
 name: 'step-04-generate-tests'
-description: 'Orchestrate parallel FAILING test generation (TDD red phase)'
+description: 'Orchestrate adaptive FAILING test generation (TDD red phase)'
 nextStepFile: './step-04c-aggregate.md'
 ---
 
-# Step 4: Orchestrate Parallel FAILING Test Generation
+# Step 4: Orchestrate Adaptive FAILING Test Generation
 
 ## STEP GOAL
 
-Launch parallel subprocesses to generate FAILING API and E2E tests simultaneously (TDD RED PHASE) for maximum performance.
+Select execution mode deterministically, then generate FAILING API and E2E tests (TDD RED PHASE) with consistent output contracts across agent-team, subagent, or sequential execution.
 
 ## MANDATORY EXECUTION RULES
 
 - 📖 Read the entire step file before acting
 - ✅ Speak in `{communication_language}`
-- ✅ Launch TWO subprocesses in PARALLEL
+- ✅ Resolve execution mode from config (`tea_execution_mode`, `tea_capability_probe`)
+- ✅ Apply fallback rules deterministically when requested mode is unsupported
 - ✅ Generate FAILING tests only (TDD red phase)
-- ✅ Wait for BOTH subprocesses to complete
-- ❌ Do NOT generate sequential tests (use subprocesses)
+- ✅ Wait for required worker steps to complete
+- ❌ Do NOT skip capability checks when probing is enabled
 - ❌ Do NOT generate passing tests (this is red phase)
-- ❌ Do NOT proceed until both subprocesses finish
+- ❌ Do NOT proceed until required worker steps finish
 
 ---
 
 ## EXECUTION PROTOCOLS:
 
 - 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Wait for subprocess outputs
+- 💾 Wait for subagent outputs
 - 📖 Load the next step only when instructed
 
 ## CONTEXT BOUNDARIES:
 
 - Available context: config, acceptance criteria from Step 1, test strategy from Step 3
-- Focus: subprocess orchestration only
-- Limits: do not generate tests directly (delegate to subprocesses)
+- Focus: orchestration only (mode selection + worker dispatch)
+- Limits: do not generate tests directly (delegate to worker steps)
 - Dependencies: Steps 1-3 outputs
 
 ---
@@ -42,7 +43,7 @@ Launch parallel subprocesses to generate FAILING API and E2E tests simultaneousl
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
-### 1. Prepare Subprocess Inputs
+### 1. Prepare Execution Context
 
 **Generate unique timestamp** for temp file naming:
 
@@ -50,17 +51,29 @@ Launch parallel subprocesses to generate FAILING API and E2E tests simultaneousl
 const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
 ```
 
-**Prepare input context for both subprocesses:**
+**Prepare input context for both subagents:**
 
 ```javascript
-const subprocessContext = {
+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 = {
   story_acceptance_criteria: /* from Step 1 */,
   test_strategy: /* from Step 3 */,
   knowledge_fragments_loaded: /* list of fragments */,
   config: {
     test_framework: config.test_framework,
     use_playwright_utils: config.tea_use_playwright_utils,
-    browser_automation: config.tea_browser_automation
+    browser_automation: config.tea_browser_automation,
+    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
   },
   timestamp: timestamp
 };
@@ -68,63 +81,153 @@ const subprocessContext = {
 
 ---
 
-### 2. Launch Subprocess A: Failing API Test Generation
+### 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: runtime.canLaunchSubagents?.() === true,
+  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,
+};
+
+if (!probeEnabled && (requestedMode === 'agent-team' || requestedMode === 'subagent')) {
+  const unsupportedRequestedMode =
+    (requestedMode === 'agent-team' && !supports.agentTeam) || (requestedMode === 'subagent' && !supports.subagent);
+
+  if (unsupportedRequestedMode) {
+    subagentContext.execution.error = `Requested execution mode "${requestedMode}" is unavailable because capability probing is disabled.`;
+    throw new Error(subagentContext.execution.error);
+  }
+}
+```
+
+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.
+
+---
+
+### 3. Dispatch Worker A: Failing API Test Generation
 
-**Launch subprocess in parallel:**
+**Dispatch worker:**
 
-- **Subprocess File:** `./step-04a-subprocess-api-failing.md`
+- **Subagent File:** `./step-04a-subagent-api-failing.md`
 - **Output File:** `/tmp/tea-atdd-api-tests-${timestamp}.json`
-- **Context:** Pass `subprocessContext`
-- **Execution:** PARALLEL (non-blocking)
+- **Context:** Pass `subagentContext`
+- **Execution:**
+  - `agent-team` or `subagent`: launch non-blocking
+  - `sequential`: run blocking and wait before next dispatch
 - **TDD Phase:** RED (failing tests)
 
 **System Action:**
 
 ```
-🚀 Launching Subprocess A: FAILING API Test Generation (RED PHASE)
+🚀 Launching Subagent A: FAILING API Test Generation (RED PHASE)
 📝 Output: /tmp/tea-atdd-api-tests-${timestamp}.json
+⚙️ Mode: ${resolvedMode}
 🔴 TDD Phase: RED (tests will fail until feature implemented)
-⏳ Status: Running in parallel...
+⏳ Status: Running...
 ```
 
 ---
 
-### 3. Launch Subprocess B: Failing E2E Test Generation
+### 4. Dispatch Worker B: Failing E2E Test Generation
 
-**Launch subprocess in parallel:**
+**Dispatch worker:**
 
-- **Subprocess File:** `./step-04b-subprocess-e2e-failing.md`
+- **Subagent File:** `./step-04b-subagent-e2e-failing.md`
 - **Output File:** `/tmp/tea-atdd-e2e-tests-${timestamp}.json`
-- **Context:** Pass `subprocessContext`
-- **Execution:** PARALLEL (non-blocking)
+- **Context:** Pass `subagentContext`
+- **Execution:**
+  - `agent-team` or `subagent`: launch non-blocking
+  - `sequential`: run blocking and wait before next dispatch
 - **TDD Phase:** RED (failing tests)
 
 **System Action:**
 
 ```
-🚀 Launching Subprocess B: FAILING E2E Test Generation (RED PHASE)
+🚀 Launching Subagent B: FAILING E2E Test Generation (RED PHASE)
 📝 Output: /tmp/tea-atdd-e2e-tests-${timestamp}.json
+⚙️ Mode: ${resolvedMode}
 🔴 TDD Phase: RED (tests will fail until feature implemented)
-⏳ Status: Running in parallel...
+⏳ Status: Running...
 ```
 
 ---
 
-### 4. Wait for Both Subprocesses to Complete
+### 5. Wait for Required Worker Completion
 
-**Monitor subprocess execution:**
+**If `resolvedMode` is `agent-team` or `subagent`:**
 
 ```
-⏳ Waiting for subprocesses to complete...
-  ├── Subprocess A (API RED): Running... ⟳
-  └── Subprocess B (E2E RED): Running... ⟳
+⏳ Waiting for subagents to complete...
+  ├── Subagent A (API RED): Running... ⟳
+  └── Subagent B (E2E RED): Running... ⟳
 
 [... time passes ...]
 
-  ├── Subprocess A (API RED): Complete ✅
-  └── Subprocess B (E2E RED): Complete ✅
+  ├── Subagent A (API RED): Complete ✅
+  └── Subagent B (E2E RED): Complete ✅
 
-✅ All subprocesses completed successfully!
+✅ All subagents completed successfully!
+```
+
+**If `resolvedMode` is `sequential`:**
+
+```
+✅ Sequential mode: each worker already completed during dispatch.
 ```
 
 **Verify both outputs exist:**
@@ -134,20 +237,20 @@ const apiOutputExists = fs.existsSync(`/tmp/tea-atdd-api-tests-${timestamp}.json
 const e2eOutputExists = fs.existsSync(`/tmp/tea-atdd-e2e-tests-${timestamp}.json`);
 
 if (!apiOutputExists || !e2eOutputExists) {
-  throw new Error('One or both subprocess outputs missing!');
+  throw new Error('One or both subagent outputs missing!');
 }
 ```
 
 ---
 
-### 5. TDD Red Phase Report
+### 6. TDD Red Phase Report
 
 **Display TDD status:**
 
 ```
 🔴 TDD RED PHASE: Failing Tests Generated
 
-✅ Both subprocesses completed:
+✅ Both subagents completed:
 - API Tests: Generated with test.skip()
 - E2E Tests: Generated with test.skip()
 
@@ -160,30 +263,29 @@ Next: Aggregation will verify TDD compliance
 
 ---
 
-### 6. Performance Report
+### 7. Execution Report
 
 **Display performance metrics:**
 
 ```
 🚀 Performance Report:
-- Execution Mode: PARALLEL (2 subprocesses)
+- Execution Mode: {resolvedMode}
 - API Test Generation: ~X minutes
 - E2E Test Generation: ~Y minutes
-- Total Elapsed: ~max(X, Y) minutes
-- Sequential Would Take: ~(X + Y) minutes
-- Performance Gain: ~50% faster!
+- Total Elapsed: ~mode-dependent
+- Parallel Gain: ~50% faster when mode is subagent/agent-team
 ```
 
 ---
 
-### 7. Proceed to Aggregation
+### 8. Proceed to Aggregation
 
 **Load aggregation step:**
 Load next step: `{nextStepFile}`
 
 The aggregation step (4C) will:
 
-- Read both subprocess outputs
+- Read both subagent outputs
 - Verify TDD red phase compliance (all tests have test.skip())
 - Write all test files to disk
 - Generate ATDD checklist
@@ -195,16 +297,16 @@ The aggregation step (4C) will:
 
 Proceed to Step 4C (Aggregation) when:
 
-- ✅ Subprocess A (API failing tests) completed successfully
-- ✅ Subprocess B (E2E failing tests) completed successfully
+- ✅ Subagent A (API failing tests) completed successfully
+- ✅ Subagent B (E2E failing tests) completed successfully
 - ✅ Both output files exist and are valid JSON
 - ✅ TDD red phase status reported
 
 **Do NOT proceed if:**
 
-- ❌ One or both subprocesses failed
+- ❌ One or both subagents failed
 - ❌ Output files missing or corrupted
-- ❌ Subprocess generated passing tests (wrong - must be failing)
+- ❌ Subagent generated passing tests (wrong - must be failing)
 
 ---
 
@@ -212,18 +314,18 @@ Proceed to Step 4C (Aggregation) when:
 
 ### ✅ SUCCESS:
 
-- Both subprocesses launched successfully
-- Both subprocesses completed without errors
+- Both subagents launched successfully
+- Both worker steps completed without errors
 - Output files generated and valid
 - Tests generated with test.skip() (TDD red phase)
-- Parallel execution achieved ~50% performance gain
+- Fallback behavior respected configuration and capability probe rules
 
 ### ❌ SYSTEM FAILURE:
 
-- Failed to launch subprocesses
-- One or both subprocesses failed
+- Failed to launch subagents
+- One or both subagents failed
 - Output files missing or invalid
 - Tests generated without test.skip() (wrong phase)
-- Attempted sequential generation instead of parallel
+- Unsupported requested mode with probing disabled
 
-**Master Rule:** TDD RED PHASE requires FAILING tests (with test.skip()). Parallel subprocess execution is MANDATORY for performance.
+**Master Rule:** TDD RED PHASE requires FAILING tests (with test.skip()). Mode selection changes orchestration, never red-phase requirements.

package/templates/bmad/tea/workflows/testarch/atdd/steps-c/step-04a-subagent-api-failing.md

@@ -0,0 +1,215 @@
+---
+name: 'step-04a-subagent-api-failing'
+description: 'Subagent: Generate FAILING API tests (TDD red phase)'
+subagent: true
+outputFile: '/tmp/tea-atdd-api-tests-{{timestamp}}.json'
+---
+
+# Subagent 4A: Generate Failing API Tests (TDD Red Phase)
+
+## SUBAGENT CONTEXT
+
+This is an **isolated subagent** running in parallel with E2E failing test generation.
+
+**What you have from parent workflow:**
+
+- Story acceptance criteria from Step 1
+- Test strategy and scenarios from Step 3
+- Knowledge fragments loaded: api-request, data-factories, api-testing-patterns
+- Config: test framework, Playwright Utils enabled/disabled
+
+**Your task:** Generate API tests that will FAIL because the feature is not implemented yet (TDD RED PHASE).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subagent file before acting
+- ✅ Generate FAILING API tests ONLY
+- ✅ Tests MUST fail when run (feature not implemented yet)
+- ✅ Output structured JSON to temp file
+- ✅ Follow knowledge fragment patterns
+- ❌ Do NOT generate E2E tests (that's subagent 4B)
+- ❌ Do NOT generate passing tests (this is TDD red phase)
+- ❌ Do NOT run tests (that's step 5)
+
+---
+
+## SUBAGENT TASK
+
+### 1. Identify API Endpoints from Acceptance Criteria
+
+From the story acceptance criteria (Step 1 output), identify:
+
+- Which API endpoints will be created for this story
+- Expected request/response contracts
+- Authentication requirements
+- Expected status codes and error scenarios
+
+**Example Acceptance Criteria:**
+
+```
+Story: User Registration
+- As a user, I can POST to /api/users/register with email and password
+- System returns 201 Created with user object
+- System returns 400 Bad Request if email already exists
+- System returns 422 Unprocessable Entity if validation fails
+```
+
+### 2. Generate FAILING API Test Files
+
+For each API endpoint, create test file in `tests/api/[feature].spec.ts`:
+
+**Test Structure (ATDD - Red Phase):**
+
+```typescript
+import { test, expect } from '@playwright/test';
+// If Playwright Utils enabled:
+// import { apiRequest } from '@playwright-utils/api';
+
+test.describe('[Story Name] API Tests (ATDD)', () => {
+  test.skip('[P0] should register new user successfully', async ({ request }) => {
+    // THIS TEST WILL FAIL - Endpoint not implemented yet
+    const response = await request.post('/api/users/register', {
+      data: {
+        email: 'newuser@example.com',
+        password: 'SecurePass123!',
+      },
+    });
+
+    // Expect 201 but will get 404 (endpoint doesn't exist)
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user).toMatchObject({
+      id: expect.any(Number),
+      email: 'newuser@example.com',
+    });
+  });
+
+  test.skip('[P1] should return 400 if email exists', async ({ request }) => {
+    // THIS TEST WILL FAIL - Endpoint not implemented yet
+    const response = await request.post('/api/users/register', {
+      data: {
+        email: 'existing@example.com',
+        password: 'SecurePass123!',
+      },
+    });
+
+    expect(response.status()).toBe(400);
+    const error = await response.json();
+    expect(error.message).toContain('Email already exists');
+  });
+});
+```
+
+**CRITICAL ATDD Requirements:**
+
+- ✅ Use `test.skip()` to mark tests as intentionally failing (red phase)
+- ✅ Write assertions for EXPECTED behavior (even though not implemented)
+- ✅ Use realistic test data (not placeholder data)
+- ✅ Test both happy path and error scenarios from acceptance criteria
+- ✅ Use `apiRequest()` helper if Playwright Utils enabled
+- ✅ Use data factories for test data (from data-factories fragment)
+- ✅ Include priority tags [P0], [P1], [P2], [P3]
+
+**Why test.skip():**
+
+- Tests are written correctly for EXPECTED behavior
+- But we know they'll fail because feature isn't implemented
+- `test.skip()` documents this is intentional (TDD red phase)
+- Once feature is implemented, remove `test.skip()` to verify green phase
+
+### 3. Track Fixture Needs
+
+Identify fixtures needed for API tests:
+
+- Authentication fixtures (if endpoints require auth)
+- Data factories (user 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-atdd-api-tests-{{timestamp}}.json`
+
+```json
+{
+  "success": true,
+  "subagent": "atdd-api-tests",
+  "tests": [
+    {
+      "file": "tests/api/user-registration.spec.ts",
+      "content": "[full TypeScript test file content with test.skip()]",
+      "description": "ATDD API tests for user registration (RED PHASE)",
+      "expected_to_fail": true,
+      "acceptance_criteria_covered": [
+        "User can register with email/password",
+        "System returns 201 on success",
+        "System returns 400 if email exists"
+      ],
+      "priority_coverage": {
+        "P0": 1,
+        "P1": 2,
+        "P2": 0,
+        "P3": 0
+      }
+    }
+  ],
+  "fixture_needs": ["userDataFactory"],
+  "knowledge_fragments_used": ["api-request", "data-factories", "api-testing-patterns"],
+  "test_count": 3,
+  "tdd_phase": "RED",
+  "summary": "Generated 3 FAILING API tests for user registration story"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "success": false,
+  "subagent": "atdd-api-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subagent completes when:
+
+- ✅ All API endpoints from acceptance criteria have test files
+- ✅ All tests use `test.skip()` (documented failing tests)
+- ✅ All tests assert EXPECTED behavior (not placeholder assertions)
+- ✅ JSON output written to temp file
+- ✅ Fixture needs to be tracked
+
+**Subagent terminates here.** Parent workflow will read output and proceed to aggregation.
+
+---
+
+## 🚨 SUBAGENT SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- All API tests generated with test.skip()
+- Tests assert expected behavior (not placeholders)
+- JSON output valid and complete
+- No E2E/component/unit tests included (out of scope)
+- Tests follow knowledge fragment patterns
+
+### ❌ FAILURE:
+
+- Generated passing tests (wrong - this is RED phase)
+- Tests without test.skip() (will break CI)
+- Placeholder assertions (expect(true).toBe(true))
+- Did not follow knowledge fragment patterns
+- Invalid or missing JSON output