@cregis-dev/cckit 0.2.0

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

@@ -0,0 +1,278 @@
+---
+name: 'step-03-generate-tests'
+description: 'Orchestrate parallel test generation via subprocesses'
+nextStepFile: './step-03c-aggregate.md'
+---
+
+# Step 3: Orchestrate Parallel Test Generation
+
+## STEP GOAL
+
+Launch parallel subprocesses to generate tests simultaneously for maximum performance. Subprocess selection depends on `{detected_stack}`.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Launch subprocesses in PARALLEL based on `{detected_stack}`
+- ✅ Wait for ALL launched subprocesses to complete
+- ❌ Do NOT generate tests sequentially (use subprocesses)
+- ❌ Do NOT proceed until all subprocesses finish
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Wait for subprocess outputs
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, coverage plan from Step 2, knowledge fragments
+- Focus: subprocess orchestration only
+- Limits: do not generate tests directly (delegate to subprocesses)
+- Dependencies: Step 2 outputs (coverage plan, target features)
+
+---
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Prepare Subprocess Inputs
+
+**Generate unique timestamp** for temp file naming:
+
+```javascript
+const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+```
+
+**Prepare input context for subprocesses:**
+
+```javascript
+const subprocessContext = {
+  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,
+    browser_automation: config.tea_browser_automation,  // "auto" | "cli" | "mcp" | "none"
+    detected_stack: '{detected_stack}'  // "frontend" | "backend" | "fullstack"
+  },
+  timestamp: timestamp
+};
+```
+
+---
+
+### 2. Subprocess Dispatch Matrix
+
+**Select subprocesses based on `{detected_stack}`:**
+
+| `{detected_stack}` | Subprocess A (API) | Subprocess B (E2E) | Subprocess B-backend |
+| ------------------ | ------------------ | ------------------ | -------------------- |
+| `frontend`         | Launch             | Launch             | Skip                 |
+| `backend`          | Launch             | Skip               | Launch               |
+| `fullstack`        | Launch             | Launch             | Launch               |
+
+---
+
+### 3. Launch Subprocess A: API Test Generation (always)
+
+**Launch subprocess in parallel:**
+
+- **Subprocess File:** `./step-03a-subprocess-api.md`
+- **Output File:** `/tmp/tea-automate-api-tests-${timestamp}.json`
+- **Context:** Pass `subprocessContext`
+- **Execution:** PARALLEL (non-blocking)
+
+**System Action:**
+
+```
+🚀 Launching Subprocess A: API Test Generation
+📝 Output: /tmp/tea-automate-api-tests-${timestamp}.json
+⏳ Status: Running in parallel...
+```
+
+---
+
+### 4. Launch Subprocess B: E2E Test Generation (frontend/fullstack only)
+
+**If {detected_stack} is `frontend` or `fullstack`:**
+
+**Launch subprocess in parallel:**
+
+- **Subprocess File:** `./step-03b-subprocess-e2e.md`
+- **Output File:** `/tmp/tea-automate-e2e-tests-${timestamp}.json`
+- **Context:** Pass `subprocessContext`
+- **Execution:** PARALLEL (non-blocking)
+
+**System Action:**
+
+```
+🚀 Launching Subprocess B: E2E Test Generation
+📝 Output: /tmp/tea-automate-e2e-tests-${timestamp}.json
+⏳ Status: Running in parallel...
+```
+
+**If {detected_stack} is `backend`:** Skip this subprocess.
+
+---
+
+### 5. Launch Subprocess B-backend: Backend Test Generation (backend/fullstack only)
+
+**If {detected_stack} is `backend` or `fullstack`:**
+
+**Launch subprocess in parallel:**
+
+- **Subprocess File:** `./step-03b-subprocess-backend.md`
+- **Output File:** `/tmp/tea-automate-backend-tests-${timestamp}.json`
+- **Context:** Pass `subprocessContext`
+- **Execution:** PARALLEL (non-blocking)
+
+**System Action:**
+
+```
+🚀 Launching Subprocess B-backend: Backend Test Generation
+📝 Output: /tmp/tea-automate-backend-tests-${timestamp}.json
+⏳ Status: Running in parallel...
+```
+
+**If {detected_stack} is `frontend`:** Skip this subprocess.
+
+---
+
+### 6. Wait for All Subprocesses to Complete
+
+**Monitor subprocess execution based on `{detected_stack}`:**
+
+```
+⏳ Waiting for subprocesses to complete...
+  ├── Subprocess A (API): Running... ⟳
+  ├── Subprocess B (E2E): Running... ⟳       [if frontend/fullstack]
+  └── Subprocess B-backend: Running... ⟳     [if backend/fullstack]
+
+[... time passes ...]
+
+  ├── Subprocess A (API): Complete ✅
+  ├── Subprocess B (E2E): Complete ✅         [if frontend/fullstack]
+  └── Subprocess B-backend: Complete ✅       [if backend/fullstack]
+
+✅ All subprocesses completed successfully!
+```
+
+**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 subprocess 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 subprocess output missing!');
+}
+if (!apiOutputExists) throw new Error('API subprocess output missing!');
+```
+
+---
+
+### Subprocess Output Schema Contract
+
+Both `step-03b-subprocess-e2e.md` and `step-03b-subprocess-backend.md` MUST write JSON to their output file with identical schema:
+
+```json
+{
+  "subprocessType": "e2e | backend",
+  "testsGenerated": [
+    {
+      "file": "path/to/test-file",
+      "content": "[full test file content]",
+      "description": "Test description",
+      "priority_coverage": { "P0": 0, "P1": 0, "P2": 0, "P3": 0 }
+    }
+  ],
+  "coverageSummary": {
+    "totalTests": 0,
+    "testLevels": ["unit", "integration", "api", "e2e"],
+    "fixtureNeeds": []
+  },
+  "status": "complete | partial"
+}
+```
+
+The aggregate step reads whichever output file(s) exist based on `{detected_stack}`.
+
+---
+
+### 7. Performance Report
+
+**Display performance metrics:**
+
+```
+🚀 Performance Report:
+- Execution Mode: PARALLEL (subprocesses based on {detected_stack})
+- 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: ~max(X, Y, Z) minutes
+- Sequential Would Take: ~(X + Y + Z) minutes
+- Performance Gain: ~40-70% faster!
+```
+
+---
+
+### 8. Proceed to Aggregation
+
+**Load aggregation step:**
+Load next step: `{nextStepFile}`
+
+The aggregation step (3C) will:
+
+- Read all subprocess 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:
+
+- ✅ Subprocess A (API tests) completed successfully
+- ✅ Subprocess B (E2E tests) completed successfully [if frontend/fullstack]
+- ✅ Subprocess B-backend (Backend tests) completed successfully [if backend/fullstack]
+- ✅ All expected output files exist and are valid JSON
+- ✅ Performance metrics displayed
+
+**Do NOT proceed if:**
+
+- ❌ Any launched subprocess failed
+- ❌ Output files missing or corrupted
+- ❌ Timeout occurred (subprocesses took too long)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- All required subprocesses launched successfully (based on `{detected_stack}`)
+- All subprocesses completed without errors
+- Output files generated and valid
+- Parallel execution achieved ~40-70% performance gain
+
+### ❌ SYSTEM FAILURE:
+
+- Failed to launch subprocesses
+- One or more subprocesses failed
+- Output files missing or invalid
+- Attempted sequential generation instead of parallel
+
+**Master Rule:** Parallel subprocess execution is MANDATORY for performance.

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

@@ -0,0 +1,183 @@
+---
+name: 'step-03a-subprocess-api'
+description: 'Subprocess: Generate API tests only'
+subprocess: true
+outputFile: '/tmp/tea-automate-api-tests-{{timestamp}}.json'
+---
+
+# Subprocess 3A: Generate API Tests
+
+## SUBPROCESS CONTEXT
+
+This is an **isolated subprocess** 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
+- Coverage plan: which API endpoints need testing
+
+**Your task:** Generate API tests ONLY (not E2E, not fixtures, not other test types).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subprocess file before acting
+- ✅ Generate API tests ONLY
+- ✅ Output structured JSON to temp file
+- ✅ Follow knowledge fragment patterns
+- ❌ Do NOT generate E2E tests (that's subprocess 3B)
+- ❌ Do NOT run tests (that's step 4)
+- ❌ Do NOT generate fixtures yet (that's step 3C aggregation)
+
+---
+
+## SUBPROCESS 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)
+
+### 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,
+  "subprocess": "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"],
+  "test_count": 12,
+  "summary": "Generated 12 API test cases covering 3 features"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "success": false,
+  "subprocess": "api-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subprocess completes when:
+
+- ✅ All API endpoints have test files generated
+- ✅ All tests follow knowledge fragment patterns
+- ✅ JSON output written to temp file
+- ✅ Fixture needs tracked
+
+**Subprocess terminates here.** Parent workflow will read output and proceed to aggregation.
+
+---
+
+## 🚨 SUBPROCESS SUCCESS METRICS
+
+### ✅ SUCCESS:
+
+- All API tests generated following patterns
+- JSON output valid and complete
+- No E2E/component/unit tests included (out of scope)
+
+### ❌ FAILURE:
+
+- Generated tests other than API tests
+- Did not follow knowledge fragment patterns
+- Invalid or missing JSON output
+- Ran tests (not subprocess responsibility)

package/templates/bmad/tea/workflows/testarch/automate/steps-c/step-03b-subprocess-backend.md

@@ -0,0 +1,246 @@
+---
+name: 'step-03b-subprocess-backend'
+description: 'Subprocess: Generate backend tests only (unit, integration, contract)'
+subprocess: true
+outputFile: '/tmp/tea-automate-backend-tests-{{timestamp}}.json'
+---
+
+# Subprocess 3B-backend: Generate Backend Tests
+
+## SUBPROCESS CONTEXT
+
+This is an **isolated subprocess** running in parallel with API test generation (and optionally E2E test generation for fullstack projects).
+
+**What you have from parent workflow:**
+
+- Target features/services identified in Step 2
+- Knowledge fragments loaded: test-levels-framework, test-priorities-matrix, data-factories
+- Config: test framework, detected stack type
+- Coverage plan: which services/modules need backend testing
+
+**Your task:** Generate backend tests ONLY (unit, integration, contract - not API endpoint tests, not E2E).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- Read this entire subprocess file before acting
+- Generate backend tests ONLY (unit, integration, contract)
+- Output structured JSON to temp file using the subprocess output schema contract
+- Follow knowledge fragment patterns
+- Do NOT generate API endpoint tests (that's subprocess 3A)
+- Do NOT generate E2E tests (that's subprocess 3B)
+- Do NOT run tests (that's step 4)
+- Do NOT generate fixtures yet (that's step 3C aggregation)
+
+---
+
+## SUBPROCESS TASK
+
+### 1. Identify Test Targets
+
+From the coverage plan (Step 2 output), identify:
+
+- Which services/modules need unit test coverage
+- Which integrations need integration test coverage (database, message queues, external services)
+- Which service contracts need contract test coverage (Pact, schema validation)
+- Business logic functions requiring edge case coverage
+
+### 2. Detect Framework & Language
+
+From `config.test_framework` and project manifests, determine:
+
+- **Python (pytest)**: Use `pytest` conventions, `conftest.py` fixtures, `@pytest.mark` decorators
+- **Java/Kotlin (JUnit)**: Use JUnit 5 annotations (`@Test`, `@BeforeEach`, `@Nested`), Mockito for mocking
+- **Go (go test)**: Use `*_test.go` files, `testing.T`, table-driven tests, `testify` assertions
+- **C#/.NET (xUnit)**: Use `[Fact]`, `[Theory]`, `[InlineData]`, `Moq` for mocking
+- **Ruby (RSpec)**: Use `describe`/`context`/`it` blocks, `let`/`before` helpers, `FactoryBot`
+
+### 3. Generate Unit Tests
+
+For each module/service, create test files following language-idiomatic patterns:
+
+**Python (pytest) example:**
+
+```python
+import pytest
+from unittest.mock import MagicMock, patch
+from myapp.services.user_service import UserService
+
+class TestUserService:
+    """[P0] Unit tests for UserService"""
+
+    def test_create_user_with_valid_data(self, user_factory):
+        """Should create user when data is valid"""
+        user_data = user_factory.build()
+        result = UserService.create(user_data)
+        assert result.email == user_data["email"]
+
+    def test_create_user_rejects_duplicate_email(self, user_factory):
+        """[P1] Should reject duplicate email"""
+        user_data = user_factory.build(email="existing@test.com")
+        with pytest.raises(DuplicateEmailError):
+            UserService.create(user_data)
+```
+
+**Go (go test) example:**
+
+```go
+func TestUserService_Create(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   CreateUserInput
+        wantErr bool
+    }{
+        {"valid user", validInput(), false},
+        {"duplicate email", duplicateInput(), true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            svc := NewUserService(mockRepo)
+            _, err := svc.Create(tt.input)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("Create() error = %v, wantErr %v", err, tt.wantErr)
+            }
+        })
+    }
+}
+```
+
+**Requirements:**
+
+- Follow the detected framework's idiomatic test patterns
+- Include priority tags [P0], [P1], [P2], [P3] in test descriptions
+- Use proper mocking for external dependencies (database, APIs, message queues)
+- Test both happy path and error cases
+- Use proper typing/type hints where applicable
+- No hard-coded test data; use factories or builders
+
+### 4. Generate Integration Tests
+
+For service integrations, create integration test files:
+
+- Database integration tests (with test database or in-memory alternatives)
+- Message queue consumer/producer tests
+- Cache integration tests
+- External service integration tests (with mocked HTTP clients)
+
+### 5. Generate Contract Tests (if applicable)
+
+If the project uses microservices or has defined API contracts:
+
+- Pact consumer/provider tests
+- Schema validation tests (JSON Schema, Protobuf)
+- OpenAPI spec compliance tests
+
+### 6. Track Fixture Needs
+
+Identify fixtures/helpers needed for backend tests:
+
+- Database fixtures (seed data, cleanup)
+- Factory functions (test data builders)
+- Mock services (HTTP mocks, message queue mocks)
+- Configuration fixtures (test environment config)
+
+**Do NOT create fixtures yet** - just track what's needed for aggregation step.
+
+---
+
+## OUTPUT FORMAT
+
+Write JSON to temp file: `/tmp/tea-automate-backend-tests-{{timestamp}}.json`
+
+```json
+{
+  "subprocessType": "backend",
+  "testsGenerated": [
+    {
+      "file": "tests/unit/test_user_service.py",
+      "content": "[full test file content]",
+      "description": "Unit tests for UserService",
+      "priority_coverage": {
+        "P0": 3,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    },
+    {
+      "file": "tests/integration/test_user_repository.py",
+      "content": "[full test file content]",
+      "description": "Integration tests for user database operations",
+      "priority_coverage": {
+        "P0": 1,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    }
+  ],
+  "coverageSummary": {
+    "totalTests": 15,
+    "testLevels": ["unit", "integration", "contract"],
+    "fixtureNeeds": ["databaseFixture", "userFactory", "mockHttpClient"]
+  },
+  "status": "complete",
+  "success": true,
+  "subprocess": "backend-tests",
+  "knowledge_fragments_used": ["test-levels-framework", "test-priorities-matrix", "data-factories"],
+  "summary": "Generated 15 backend test cases (10 unit, 4 integration, 1 contract)"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "subprocessType": "backend",
+  "testsGenerated": [],
+  "coverageSummary": {
+    "totalTests": 0,
+    "testLevels": [],
+    "fixtureNeeds": []
+  },
+  "status": "partial",
+  "success": false,
+  "subprocess": "backend-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subprocess completes when:
+
+- All identified modules have backend test files generated
+- All tests follow language-idiomatic patterns
+- JSON output written to temp file using the subprocess output schema contract
+- Fixture needs tracked
+
+**Subprocess terminates here.** Parent workflow will read output and proceed to aggregation.
+
+---
+
+## SUBPROCESS SUCCESS METRICS
+
+### SUCCESS:
+
+- All backend tests generated following idiomatic patterns
+- JSON output valid and complete, matches subprocess output schema contract
+- No E2E or browser tests included (out of scope)
+- Proper mocking used for external dependencies
+- Priority tags assigned to all test cases
+
+### FAILURE:
+
+- Generated tests other than backend tests (unit/integration/contract)
+- Did not follow language-idiomatic patterns
+- Invalid or missing JSON output
+- Output schema does not match the contract
+- Ran tests (not subprocess responsibility)
+- Used real external services instead of mocks