@cregis-dev/cckit 0.2.0

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

@@ -0,0 +1,213 @@
+---
+name: 'step-03b-subprocess-e2e'
+description: 'Subprocess: Generate E2E tests only'
+subprocess: true
+outputFile: '/tmp/tea-automate-e2e-tests-{{timestamp}}.json'
+---
+
+# Subprocess 3B: Generate E2E Tests
+
+## SUBPROCESS CONTEXT
+
+This is an **isolated subprocess** running in parallel with API test generation.
+
+**What you have from parent workflow:**
+
+- Target features/user journeys identified in Step 2
+- Knowledge fragments loaded: fixture-architecture, network-first, selector-resilience
+- Config: test framework, Playwright Utils enabled/disabled
+- Coverage plan: which user journeys need E2E testing
+
+**Your task:** Generate E2E tests ONLY (not API, not fixtures, not other test types).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subprocess file before acting
+- ✅ Generate E2E tests ONLY
+- ✅ Output structured JSON to temp file
+- ✅ Follow knowledge fragment patterns
+- ❌ Do NOT generate API tests (that's subprocess 3A)
+- ❌ Do NOT run tests (that's step 4)
+- ❌ Do NOT generate fixtures yet (that's step 3C aggregation)
+
+---
+
+## SUBPROCESS TASK
+
+### 1. Identify User Journeys
+
+From the coverage plan (Step 2 output), identify:
+
+- Which user journeys need E2E coverage
+- Critical user paths (authentication, checkout, profile, etc.)
+- UI interactions required
+- Expected visual states
+
+### 2. Browser Interaction (Selector Verification)
+
+**Automation mode:** `config.tea_browser_automation`
+
+If `auto` (fall back to MCP if CLI unavailable; if neither available, generate from best practices):
+
+- Open the target page first, then verify selectors with a snapshot:
+  `playwright-cli -s=tea-automate-{{timestamp}} open <target_url>`
+  `playwright-cli -s=tea-automate-{{timestamp}} snapshot` → map refs to Playwright locators
+  - ref `{role: "button", name: "Submit"}` → `page.getByRole('button', { name: 'Submit' })`
+  - ref `{role: "textbox", name: "Email"}` → `page.getByRole('textbox', { name: 'Email' })`
+- `playwright-cli -s=tea-automate-{{timestamp}} close` when done
+
+If `cli` (CLI only — do NOT fall back to MCP; generate from best practices if CLI unavailable):
+
+- Open the target page first, then verify selectors with a snapshot:
+  `playwright-cli -s=tea-automate-{{timestamp}} open <target_url>`
+  `playwright-cli -s=tea-automate-{{timestamp}} snapshot` → map refs to Playwright locators
+  - ref `{role: "button", name: "Submit"}` → `page.getByRole('button', { name: 'Submit' })`
+  - ref `{role: "textbox", name: "Email"}` → `page.getByRole('textbox', { name: 'Email' })`
+- `playwright-cli -s=tea-automate-{{timestamp}} close` when done
+
+> **Session Hygiene:** Always close sessions using `playwright-cli -s=tea-automate-{{timestamp}} close`. Do NOT use `close-all` — it kills every session on the machine and breaks parallel execution.
+
+If `mcp`:
+
+- Use MCP tools for selector verification (current behavior)
+
+If `none`:
+
+- Generate selectors from best practices without browser verification
+
+### 3. Generate E2E Test Files
+
+For each user journey, create test file in `tests/e2e/[feature].spec.ts`:
+
+**Test Structure:**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('[Feature] E2E User Journey', () => {
+  test('[P0] should complete [user journey]', async ({ page }) => {
+    // Navigate to starting point
+    await page.goto('/feature');
+
+    // Interact with UI
+    await page.getByRole('button', { name: 'Submit' }).click();
+
+    // Assert expected state
+    await expect(page.getByText('Success')).toBeVisible();
+  });
+
+  test('[P1] should handle [edge case]', async ({ page }) => {
+    // Test edge case scenario
+  });
+});
+```
+
+**Requirements:**
+
+- ✅ Follow fixture architecture patterns (from fixture-architecture fragment)
+- ✅ Use network-first patterns: intercept before navigate (from network-first fragment)
+- ✅ Use resilient selectors: getByRole, getByText, getByLabel (from selector-resilience fragment)
+- ✅ Include priority tags [P0], [P1], [P2], [P3]
+- ✅ Test complete user journeys (not isolated clicks)
+- ✅ Use proper TypeScript types
+- ✅ Deterministic waits (no hard sleeps, use expect().toBeVisible())
+
+### 4. Track Fixture Needs
+
+Identify fixtures needed for E2E tests:
+
+- Page object models (if complex)
+- Authentication fixtures (logged-in user state)
+- Network mocks/intercepts
+- Test data fixtures
+
+**Do NOT create fixtures yet** - just track what's needed for aggregation step.
+
+---
+
+## OUTPUT FORMAT
+
+Write JSON to temp file: `/tmp/tea-automate-e2e-tests-{{timestamp}}.json`
+
+```json
+{
+  "success": true,
+  "subprocess": "e2e-tests",
+  "tests": [
+    {
+      "file": "tests/e2e/authentication.spec.ts",
+      "content": "[full TypeScript test file content]",
+      "description": "E2E tests for user authentication journey",
+      "priority_coverage": {
+        "P0": 2,
+        "P1": 3,
+        "P2": 2,
+        "P3": 0
+      }
+    },
+    {
+      "file": "tests/e2e/checkout.spec.ts",
+      "content": "[full TypeScript test file content]",
+      "description": "E2E tests for checkout journey",
+      "priority_coverage": {
+        "P0": 3,
+        "P1": 2,
+        "P2": 1,
+        "P3": 0
+      }
+    }
+  ],
+  "fixture_needs": ["authenticatedUserFixture", "paymentMockFixture", "checkoutDataFixture"],
+  "knowledge_fragments_used": ["fixture-architecture", "network-first", "selector-resilience"],
+  "test_count": 15,
+  "summary": "Generated 15 E2E test cases covering 5 user journeys"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "success": false,
+  "subprocess": "e2e-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subprocess completes when:
+
+- ✅ All user journeys have E2E 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 E2E tests generated following patterns
+- JSON output valid and complete
+- No API/component/unit tests included (out of scope)
+- Resilient selectors used (getByRole, getByText)
+- Network-first patterns applied (intercept before navigate)
+
+### ❌ FAILURE:
+
+- Generated tests other than E2E tests
+- Did not follow knowledge fragment patterns
+- Invalid or missing JSON output
+- Ran tests (not subprocess responsibility)
+- Used brittle selectors (CSS classes, XPath)

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

@@ -0,0 +1,377 @@
+---
+name: 'step-03c-aggregate'
+description: 'Aggregate subprocess outputs and complete test infrastructure'
+outputFile: '{test_artifacts}/automation-summary.md'
+nextStepFile: './step-04-validate-and-summarize.md'
+---
+
+# Step 3C: Aggregate Test Generation Results
+
+## STEP GOAL
+
+Read outputs from parallel subprocesses (API + E2E and/or Backend test generation based on `{detected_stack}`), aggregate results, and create supporting infrastructure (fixtures, helpers).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Read subprocess outputs from temp files
+- ✅ Generate shared fixtures based on fixture needs from both subprocesses
+- ✅ Write all generated test files to disk
+- ❌ Do NOT regenerate tests (use subprocess outputs)
+- ❌ Do NOT run tests yet (that's step 4)
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, subprocess outputs from temp files
+- Focus: aggregation and fixture generation only
+- Limits: do not execute future steps
+- Dependencies: Step 3A and 3B subprocess outputs
+
+---
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+### 1. Read Subprocess Outputs
+
+**Read API test subprocess output (always):**
+
+```javascript
+const apiTestsPath = '/tmp/tea-automate-api-tests-{{timestamp}}.json';
+const apiTestsOutput = JSON.parse(fs.readFileSync(apiTestsPath, 'utf8'));
+```
+
+**Read E2E test subprocess output (if {detected_stack} is `frontend` or `fullstack`):**
+
+```javascript
+let e2eTestsOutput = null;
+if (detected_stack === 'frontend' || detected_stack === 'fullstack') {
+  const e2eTestsPath = '/tmp/tea-automate-e2e-tests-{{timestamp}}.json';
+  e2eTestsOutput = JSON.parse(fs.readFileSync(e2eTestsPath, 'utf8'));
+}
+```
+
+**Read Backend test subprocess output (if {detected_stack} is `backend` or `fullstack`):**
+
+```javascript
+let backendTestsOutput = null;
+if (detected_stack === 'backend' || detected_stack === 'fullstack') {
+  const backendTestsPath = '/tmp/tea-automate-backend-tests-{{timestamp}}.json';
+  backendTestsOutput = JSON.parse(fs.readFileSync(backendTestsPath, 'utf8'));
+}
+```
+
+**Verify all launched subprocesses succeeded:**
+
+- Check `apiTestsOutput.success === true`
+- If E2E was launched: check `e2eTestsOutput.success === true`
+- If Backend was launched: check `backendTestsOutput.success === true`
+- If any failed, report error and stop (don't proceed)
+
+---
+
+### 2. Write All Test Files to Disk
+
+**Write API test files:**
+
+```javascript
+apiTestsOutput.tests.forEach((test) => {
+  fs.writeFileSync(test.file, test.content, 'utf8');
+  console.log(`✅ Created: ${test.file}`);
+});
+```
+
+**Write E2E test files (if {detected_stack} is `frontend` or `fullstack`):**
+
+```javascript
+if (e2eTestsOutput) {
+  e2eTestsOutput.tests.forEach((test) => {
+    fs.writeFileSync(test.file, test.content, 'utf8');
+    console.log(`✅ Created: ${test.file}`);
+  });
+}
+```
+
+**Write Backend test files (if {detected_stack} is `backend` or `fullstack`):**
+
+```javascript
+if (backendTestsOutput) {
+  backendTestsOutput.testsGenerated.forEach((test) => {
+    fs.writeFileSync(test.file, test.content, 'utf8');
+    console.log(`✅ Created: ${test.file}`);
+  });
+}
+```
+
+---
+
+### 3. Aggregate Fixture Needs
+
+**Collect all fixture needs from all launched subprocesses:**
+
+```javascript
+const allFixtureNeeds = [
+  ...apiTestsOutput.fixture_needs,
+  ...(e2eTestsOutput ? e2eTestsOutput.fixture_needs : []),
+  ...(backendTestsOutput ? backendTestsOutput.coverageSummary?.fixtureNeeds || [] : []),
+];
+
+// Remove duplicates
+const uniqueFixtures = [...new Set(allFixtureNeeds)];
+```
+
+**Categorize fixtures:**
+
+- **Authentication fixtures:** authToken, authenticatedUserFixture, etc.
+- **Data factories:** userDataFactory, productDataFactory, etc.
+- **Network mocks:** paymentMockFixture, apiResponseMocks, etc.
+- **Test helpers:** wait/retry/assertion helpers
+
+---
+
+### 4. Generate Fixture Infrastructure
+
+**Create or update fixture files based on needs:**
+
+**A) Authentication Fixtures** (`tests/fixtures/auth.ts`):
+
+```typescript
+import { test as base } from '@playwright/test';
+
+export const test = base.extend({
+  authenticatedUser: async ({ page }, use) => {
+    // Login logic
+    await page.goto('/login');
+    await page.fill('[name="email"]', 'test@example.com');
+    await page.fill('[name="password"]', 'password');
+    await page.click('button[type="submit"]');
+    await page.waitForURL('/dashboard');
+
+    await use(page);
+  },
+
+  authToken: async ({ request }, use) => {
+    // Get auth token for API tests
+    const response = await request.post('/api/auth/login', {
+      data: { email: 'test@example.com', password: 'password' },
+    });
+    const { token } = await response.json();
+
+    await use(token);
+  },
+});
+```
+
+**B) Data Factories** (`tests/fixtures/data-factories.ts`):
+
+```typescript
+import { faker } from '@faker-js/faker';
+
+export const createUserData = (overrides = {}) => ({
+  name: faker.person.fullName(),
+  email: faker.internet.email(),
+  ...overrides,
+});
+
+export const createProductData = (overrides = {}) => ({
+  name: faker.commerce.productName(),
+  price: faker.number.int({ min: 10, max: 1000 }),
+  ...overrides,
+});
+```
+
+**C) Network Mocks** (`tests/fixtures/network-mocks.ts`):
+
+```typescript
+import { Page } from '@playwright/test';
+
+export const mockPaymentSuccess = async (page: Page) => {
+  await page.route('/api/payment/**', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ success: true, transactionId: '12345' }),
+    });
+  });
+};
+```
+
+**D) Helper Utilities** (`tests/fixtures/helpers.ts`):
+
+```typescript
+import { expect, Page } from '@playwright/test';
+
+export const waitForApiResponse = async (page: Page, urlPattern: string) => {
+  return page.waitForResponse((response) => response.url().includes(urlPattern) && response.ok());
+};
+```
+
+---
+
+### 5. Calculate Summary Statistics
+
+**Aggregate test counts (based on `{detected_stack}`):**
+
+```javascript
+const e2eCount = e2eTestsOutput ? e2eTestsOutput.test_count : 0;
+const backendCount = backendTestsOutput ? (backendTestsOutput.coverageSummary?.totalTests ?? 0) : 0;
+
+const summary = {
+  detected_stack: '{detected_stack}',
+  total_tests: apiTestsOutput.test_count + e2eCount + backendCount,
+  api_tests: apiTestsOutput.test_count,
+  e2e_tests: e2eCount,
+  backend_tests: backendCount,
+  fixtures_created: uniqueFixtures.length,
+  api_test_files: apiTestsOutput.tests.length,
+  e2e_test_files: e2eTestsOutput ? e2eTestsOutput.tests.length : 0,
+  backend_test_files: backendTestsOutput ? backendTestsOutput.testsGenerated.length : 0,
+  priority_coverage: {
+    P0:
+      (apiTestsOutput.priority_coverage?.P0 ?? 0) +
+      (e2eTestsOutput?.priority_coverage?.P0 ?? 0) +
+      (backendTestsOutput?.testsGenerated?.reduce((sum, t) => sum + (t.priority_coverage?.P0 ?? 0), 0) ?? 0),
+    P1:
+      (apiTestsOutput.priority_coverage?.P1 ?? 0) +
+      (e2eTestsOutput?.priority_coverage?.P1 ?? 0) +
+      (backendTestsOutput?.testsGenerated?.reduce((sum, t) => sum + (t.priority_coverage?.P1 ?? 0), 0) ?? 0),
+    P2:
+      (apiTestsOutput.priority_coverage?.P2 ?? 0) +
+      (e2eTestsOutput?.priority_coverage?.P2 ?? 0) +
+      (backendTestsOutput?.testsGenerated?.reduce((sum, t) => sum + (t.priority_coverage?.P2 ?? 0), 0) ?? 0),
+    P3:
+      (apiTestsOutput.priority_coverage?.P3 ?? 0) +
+      (e2eTestsOutput?.priority_coverage?.P3 ?? 0) +
+      (backendTestsOutput?.testsGenerated?.reduce((sum, t) => sum + (t.priority_coverage?.P3 ?? 0), 0) ?? 0),
+  },
+  knowledge_fragments_used: [
+    ...apiTestsOutput.knowledge_fragments_used,
+    ...(e2eTestsOutput ? e2eTestsOutput.knowledge_fragments_used : []),
+    ...(backendTestsOutput ? backendTestsOutput.knowledge_fragments_used || [] : []),
+  ],
+  subprocess_execution: `PARALLEL (based on ${detected_stack})`,
+  performance_gain: '~40-70% faster than sequential',
+};
+```
+
+**Store summary for Step 4:**
+Save summary to temp file for validation step:
+
+```javascript
+fs.writeFileSync('/tmp/tea-automate-summary-{{timestamp}}.json', JSON.stringify(summary, null, 2), 'utf8');
+```
+
+---
+
+### 6. Optional Cleanup
+
+**Clean up subprocess temp files** (optional - can keep for debugging):
+
+```javascript
+fs.unlinkSync(apiTestsPath);
+if (e2eTestsOutput) fs.unlinkSync('/tmp/tea-automate-e2e-tests-{{timestamp}}.json');
+if (backendTestsOutput) fs.unlinkSync('/tmp/tea-automate-backend-tests-{{timestamp}}.json');
+console.log('✅ Subprocess temp files cleaned up');
+```
+
+---
+
+## OUTPUT SUMMARY
+
+Display to user:
+
+```
+✅ Test Generation Complete (Parallel Execution)
+
+📊 Summary:
+- Stack Type: {detected_stack}
+- Total Tests: {total_tests}
+  - API Tests: {api_tests} ({api_test_files} files)
+  - E2E Tests: {e2e_tests} ({e2e_test_files} files)         [if frontend/fullstack]
+  - Backend Tests: {backend_tests} ({backend_test_files} files)  [if backend/fullstack]
+- Fixtures Created: {fixtures_created}
+- Priority Coverage:
+  - P0 (Critical): {P0} tests
+  - P1 (High): {P1} tests
+  - P2 (Medium): {P2} tests
+  - P3 (Low): {P3} tests
+
+🚀 Performance: Parallel execution ~40-70% faster than sequential
+
+📂 Generated Files:
+- tests/api/[feature].spec.ts                                [always]
+- tests/e2e/[feature].spec.ts                                [if frontend/fullstack]
+- tests/unit/[feature].test.*                                 [if backend/fullstack]
+- tests/integration/[feature].test.*                          [if backend/fullstack]
+- tests/fixtures/ or tests/support/                           [shared infrastructure]
+
+✅ Ready for validation (Step 4)
+```
+
+---
+
+## EXIT CONDITION
+
+Proceed to Step 4 when:
+
+- ✅ All test files written to disk (API + E2E and/or Backend, based on `{detected_stack}`)
+- ✅ All fixtures and helpers created
+- ✅ Summary statistics calculated and saved
+- ✅ Output displayed to user
+
+---
+
+### 7. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-03c-aggregate']
+  lastStep: 'step-03c-aggregate'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-03c-aggregate'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-03c-aggregate'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section.
+
+Load next step: `{nextStepFile}`
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- All launched subprocesses succeeded (based on `{detected_stack}`)
+- All test files written to disk
+- Fixtures generated based on subprocess needs
+- Summary complete and accurate
+
+### ❌ SYSTEM FAILURE:
+
+- One or more subprocesses failed
+- Test files not written to disk
+- Fixtures missing or incomplete
+- Summary missing or inaccurate
+
+**Master Rule:** Do NOT proceed to Step 4 if aggregation incomplete.

package/templates/bmad/tea/workflows/testarch/automate/steps-c/step-04-validate-and-summarize.md

@@ -0,0 +1,106 @@
+---
+name: 'step-04-validate-and-summarize'
+description: 'Validate outputs and produce automation summary'
+outputFile: '{test_artifacts}/automation-summary.md'
+---
+
+# Step 4: Validate & Summarize
+
+## STEP GOAL
+
+Validate generated outputs and produce a concise automation summary.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- ✅ Validate against the checklist before completion
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, loaded artifacts, and knowledge fragments
+- Focus: this step's goal only
+- Limits: do not execute future steps
+- Dependencies: prior steps' outputs (if any)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+## 1. Validate
+
+Use `checklist.md` to validate:
+
+- Framework readiness
+- Coverage mapping
+- Test quality and structure
+- Fixtures, factories, helpers
+- [ ] CLI sessions cleaned up (no orphaned browsers)
+- [ ] Temp artifacts stored in `{test_artifacts}/` not random locations
+
+Fix gaps before proceeding.
+
+---
+
+## 2. Polish Output
+
+Before finalizing, review the complete output document for quality:
+
+1. **Remove duplication**: Progressive-append workflow may have created repeated sections — consolidate
+2. **Verify consistency**: Ensure terminology, risk scores, and references are consistent throughout
+3. **Check completeness**: All template sections should be populated or explicitly marked N/A
+4. **Format cleanup**: Ensure markdown formatting is clean (tables aligned, headers consistent, no orphaned references)
+
+---
+
+## 3. Summary Output
+
+Write `{outputFile}` including:
+
+- Coverage plan by test level and priority
+- Files created/updated
+- Key assumptions and risks
+- Next recommended workflow (e.g., `test-review` or `trace`)
+
+---
+
+## 4. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-04-validate-and-summarize']
+  lastStep: 'step-04-validate-and-summarize'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-04-validate-and-summarize'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-04-validate-and-summarize'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section.
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Step completed in full with required outputs
+
+### ❌ SYSTEM FAILURE:
+
+- Skipped sequence steps or missing outputs
+  **Master Rule:** Skipping steps is FORBIDDEN.