@cregis-dev/cckit 0.3.0 → 0.4.1

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

@@ -0,0 +1,244 @@
+---
+name: 'step-04b-subagent-e2e-failing'
+description: 'Subagent: Generate FAILING E2E tests (TDD red phase)'
+subagent: true
+outputFile: '/tmp/tea-atdd-e2e-tests-{{timestamp}}.json'
+---
+
+# Subagent 4B: Generate Failing E2E Tests (TDD Red Phase)
+
+## SUBAGENT CONTEXT
+
+This is an **isolated subagent** running in parallel with API failing test generation.
+
+**What you have from parent workflow:**
+
+- Story acceptance criteria from Step 1
+- Test strategy and user journey scenarios from Step 3
+- Knowledge fragments loaded: fixture-architecture, network-first, selector-resilience
+- Config: test framework, Playwright Utils enabled/disabled
+
+**Your task:** Generate E2E tests that will FAIL because the feature UI is not implemented yet (TDD RED PHASE).
+
+---
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read this entire subagent file before acting
+- ✅ Generate FAILING E2E tests ONLY
+- ✅ Tests MUST fail when run (UI not implemented yet)
+- ✅ Output structured JSON to temp file
+- ✅ Follow knowledge fragment patterns
+- ❌ Do NOT generate API tests (that's subagent 4A)
+- ❌ Do NOT generate passing tests (this is TDD red phase)
+- ❌ Do NOT run tests (that's step 5)
+
+---
+
+## SUBAGENT TASK
+
+### 1. Identify User Journeys from Acceptance Criteria
+
+From the story acceptance criteria (Step 1 output), identify:
+
+- Which UI flows will be created for this story
+- User interactions required
+- Expected visual states
+- Success/error messages expected
+
+**Example Acceptance Criteria:**
+
+```
+Story: User Registration
+- As a user, I can navigate to /register page
+- I can fill in email and password fields
+- I can click "Register" button
+- System shows success message and redirects to dashboard
+- System shows error if email already exists
+```
+
+### 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-atdd-{{timestamp}} open <target_url>`
+  `playwright-cli -s=tea-atdd-{{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-atdd-{{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-atdd-{{timestamp}} open <target_url>`
+  `playwright-cli -s=tea-atdd-{{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-atdd-{{timestamp}} close` when done
+
+> **Session Hygiene:** Always close sessions using `playwright-cli -s=tea-atdd-{{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 FAILING E2E Test Files
+
+For each user journey, create test file in `tests/e2e/[feature].spec.ts`:
+
+**Test Structure (ATDD - Red Phase):**
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('[Story Name] E2E User Journey (ATDD)', () => {
+  test.skip('[P0] should complete user registration successfully', async ({ page }) => {
+    // THIS TEST WILL FAIL - UI not implemented yet
+    await page.goto('/register');
+
+    // Expect registration form but will get 404 or missing elements
+    await page.fill('[name="email"]', 'newuser@example.com');
+    await page.fill('[name="password"]', 'SecurePass123!');
+    await page.click('button:has-text("Register")');
+
+    // Expect success message and redirect
+    await expect(page.getByText('Registration successful!')).toBeVisible();
+    await page.waitForURL('/dashboard');
+  });
+
+  test.skip('[P1] should show error if email exists', async ({ page }) => {
+    // THIS TEST WILL FAIL - UI not implemented yet
+    await page.goto('/register');
+
+    await page.fill('[name="email"]', 'existing@example.com');
+    await page.fill('[name="password"]', 'SecurePass123!');
+    await page.click('button:has-text("Register")');
+
+    // Expect error message
+    await expect(page.getByText('Email already exists')).toBeVisible();
+  });
+});
+```
+
+**CRITICAL ATDD Requirements:**
+
+- ✅ Use `test.skip()` to mark tests as intentionally failing (red phase)
+- ✅ Write assertions for EXPECTED UI behavior (even though not implemented)
+- ✅ Use resilient selectors: getByRole, getByText, getByLabel (from selector-resilience)
+- ✅ Follow network-first patterns if API calls involved (from network-first)
+- ✅ Test complete user journeys from acceptance criteria
+- ✅ Include priority tags [P0], [P1], [P2], [P3]
+- ✅ Use proper TypeScript types
+- ✅ Deterministic waits (no hard sleeps)
+
+**Why test.skip():**
+
+- Tests are written correctly for EXPECTED UI behavior
+- But we know they'll fail because UI isn't implemented
+- `test.skip()` documents this is intentional (TDD red phase)
+- Once UI is implemented, remove `test.skip()` to verify green phase
+
+### 4. Track Fixture Needs
+
+Identify fixtures needed for E2E tests:
+
+- Authentication fixtures (if journey requires logged-in state)
+- Network mocks (if API calls involved)
+- 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-atdd-e2e-tests-{{timestamp}}.json`
+
+```json
+{
+  "success": true,
+  "subagent": "atdd-e2e-tests",
+  "tests": [
+    {
+      "file": "tests/e2e/user-registration.spec.ts",
+      "content": "[full TypeScript test file content with test.skip()]",
+      "description": "ATDD E2E tests for user registration journey (RED PHASE)",
+      "expected_to_fail": true,
+      "acceptance_criteria_covered": [
+        "User can navigate to /register",
+        "User can fill registration form",
+        "System shows success message on registration",
+        "System shows error if email exists"
+      ],
+      "priority_coverage": {
+        "P0": 1,
+        "P1": 1,
+        "P2": 0,
+        "P3": 0
+      }
+    }
+  ],
+  "fixture_needs": ["registrationPageMock"],
+  "knowledge_fragments_used": ["fixture-architecture", "network-first", "selector-resilience"],
+  "test_count": 2,
+  "tdd_phase": "RED",
+  "summary": "Generated 2 FAILING E2E tests for user registration story"
+}
+```
+
+**On Error:**
+
+```json
+{
+  "success": false,
+  "subagent": "atdd-e2e-tests",
+  "error": "Error message describing what went wrong",
+  "partial_output": {
+    /* any tests generated before error */
+  }
+}
+```
+
+---
+
+## EXIT CONDITION
+
+Subagent completes when:
+
+- ✅ All user journeys from acceptance criteria have test files
+- ✅ All tests use `test.skip()` (documented failing tests)
+- ✅ All tests assert EXPECTED UI behavior (not placeholder assertions)
+- ✅ Resilient selectors used (getByRole, getByText)
+- ✅ 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 E2E tests generated with test.skip()
+- Tests assert expected UI behavior (not placeholders)
+- Resilient selectors used (getByRole, getByText)
+- JSON output valid and complete
+- No API/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))
+- Brittle selectors used (CSS classes, XPath)
+- Did not follow knowledge fragment patterns
+- Invalid or missing JSON output

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

@@ -1,6 +1,6 @@
 ---
 name: 'step-04c-aggregate'
-description: 'Aggregate subprocess outputs and complete ATDD test infrastructure'
+description: 'Aggregate subagent outputs and complete ATDD test infrastructure'
 outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
 nextStepFile: './step-05-validate-and-complete.md'
 ---
@@ -9,7 +9,7 @@ nextStepFile: './step-05-validate-and-complete.md'
 
 ## STEP GOAL
 
-Read outputs from parallel subprocesses (API + E2E failing test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
+Read outputs from parallel subagents (API + E2E failing test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
 
 ---
 
@@ -17,7 +17,7 @@ Read outputs from parallel subprocesses (API + E2E failing test generation), agg
 
 - 📖 Read the entire step file before acting
 - ✅ Speak in `{communication_language}`
-- ✅ Read subprocess outputs from temp files
+- ✅ Read subagent outputs from temp files
 - ✅ Verify all tests are marked with test.skip() (TDD red phase)
 - ✅ Generate shared fixtures based on fixture needs
 - ✅ Write all generated test files to disk
@@ -34,10 +34,10 @@ Read outputs from parallel subprocesses (API + E2E failing test generation), agg
 
 ## CONTEXT BOUNDARIES:
 
-- Available context: config, subprocess outputs from temp files
+- Available context: config, subagent outputs from temp files
 - Focus: aggregation and TDD validation
 - Limits: do not execute future steps
-- Dependencies: Step 4A and 4B subprocess outputs
+- Dependencies: Step 4A and 4B subagent outputs
 
 ---
 
@@ -45,23 +45,23 @@ Read outputs from parallel subprocesses (API + E2E failing test generation), agg
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
-### 1. Read Subprocess Outputs
+### 1. Read Subagent Outputs
 
-**Read API test subprocess output:**
+**Read API test subagent output:**
 
 ```javascript
 const apiTestsPath = '/tmp/tea-atdd-api-tests-{{timestamp}}.json';
 const apiTestsOutput = JSON.parse(fs.readFileSync(apiTestsPath, 'utf8'));
 ```
 
-**Read E2E test subprocess output:**
+**Read E2E test subagent output:**
 
 ```javascript
 const e2eTestsPath = '/tmp/tea-atdd-e2e-tests-{{timestamp}}.json';
 const e2eTestsOutput = JSON.parse(fs.readFileSync(e2eTestsPath, 'utf8'));
 ```
 
-**Verify both subprocesses succeeded:**
+**Verify both subagents succeeded:**
 
 - Check `apiTestsOutput.success === true`
 - Check `e2eTestsOutput.success === true`
@@ -148,7 +148,7 @@ e2eTestsOutput.tests.forEach((test) => {
 
 ### 4. Aggregate Fixture Needs
 
-**Collect all fixture needs from both subprocesses:**
+**Collect all fixture needs from both subagents:**
 
 ```javascript
 const allFixtureNeeds = [...apiTestsOutput.fixture_needs, ...e2eTestsOutput.fixture_needs];
@@ -230,6 +230,22 @@ fs.writeFileSync(`{test_artifacts}/atdd-checklist-{story-id}.md`, checklistConte
 **Aggregate test counts:**
 
 ```javascript
+const resolvedMode = subagentContext?.execution?.resolvedMode; // Provided by Step 4's orchestration context
+const subagentExecutionLabel =
+  resolvedMode === 'sequential'
+    ? 'SEQUENTIAL (API → E2E)'
+    : resolvedMode === 'agent-team'
+      ? 'AGENT-TEAM (API + E2E)'
+      : resolvedMode === 'subagent'
+        ? 'SUBAGENT (API + E2E)'
+        : 'PARALLEL (API + E2E)';
+const performanceGainLabel =
+  resolvedMode === 'sequential'
+    ? 'baseline (no parallel speedup)'
+    : resolvedMode === 'agent-team' || resolvedMode === 'subagent'
+      ? '~50% faster than sequential'
+      : 'mode-dependent';
+
 const summary = {
   tdd_phase: 'RED',
   total_tests: apiTestsOutput.test_count + e2eTestsOutput.test_count,
@@ -243,8 +259,8 @@ const summary = {
     ...e2eTestsOutput.tests.flatMap((t) => t.acceptance_criteria_covered),
   ],
   knowledge_fragments_used: [...apiTestsOutput.knowledge_fragments_used, ...e2eTestsOutput.knowledge_fragments_used],
-  subprocess_execution: 'PARALLEL (API + E2E)',
-  performance_gain: '~50% faster than sequential',
+  subagent_execution: subagentExecutionLabel,
+  performance_gain: performanceGainLabel,
 };
 ```
 
@@ -275,7 +291,7 @@ Display to user:
 ✅ Acceptance Criteria Coverage:
 {list all covered criteria}
 
-🚀 Performance: Parallel execution ~50% faster than sequential
+🚀 Performance: {performance_gain}
 
 📂 Generated Files:
 - tests/api/[feature].spec.ts (with test.skip())
@@ -337,7 +353,7 @@ Load next step: `{nextStepFile}`
 
 ### ✅ SUCCESS:
 
-- Both subprocesses succeeded
+- Both subagents succeeded
 - All tests have test.skip() (TDD red phase compliant)
 - All tests assert expected behavior (not placeholders)
 - All test files written to disk
@@ -345,7 +361,7 @@ Load next step: `{nextStepFile}`
 
 ### ❌ SYSTEM FAILURE:
 
-- One or both subprocesses failed
+- One or both subagents failed
 - Tests missing test.skip() (would break CI)
 - Tests have placeholder assertions
 - Test files not written to disk

package/templates/bmad/tea/workflows/testarch/atdd/validation-report-20260127-095021.md

@@ -1,7 +1,7 @@
 ---
 validationDate: 2026-01-27
 workflowName: testarch-atdd
-workflowPath: /Users/murat.ozcan/opensource/bmad-method-test-architecture-enterprise/src/workflows/testarch/atdd
+workflowPath: {project-root}/src/workflows/testarch/atdd
 validationStatus: COMPLETE
 completionDate: 2026-01-27 10:03:10
 ---

package/templates/bmad/tea/workflows/testarch/atdd/validation-report-20260127-102401.md

@@ -1,7 +1,7 @@
 ---
 validationDate: 2026-01-27
 workflowName: testarch-atdd
-workflowPath: /Users/murat.ozcan/opensource/bmad-method-test-architecture-enterprise/src/workflows/testarch/atdd
+workflowPath: {project-root}/src/workflows/testarch/atdd
 validationStatus: COMPLETE
 completionDate: 2026-01-27 10:24:01
 ---
@@ -87,9 +87,9 @@ Standard BMAD config variables treated as valid exceptions: bmb_creations_output
 - Steps use progressive prompts and clear role reinforcement; no laundry-list interrogation detected
 - Flow progression is clear and aligned to workflow goals
 
-## Subprocess Optimization Opportunities
+## Subagent Optimization Opportunities
 
-- No high-priority subprocess optimizations identified; workflow already uses step-file architecture
+- No high-priority subagent optimizations identified; workflow already uses step-file architecture
 - Pattern 1 (grep/regex): N/A for most steps
 - Pattern 2 (per-file analysis): already aligned to validation structure
 - Pattern 3 (data ops): minimal data file loads

package/templates/bmad/tea/workflows/testarch/atdd/workflow.yaml

@@ -1,6 +1,7 @@
 # Test Architect workflow: atdd
 name: testarch-atdd
-description: "Generate failing acceptance tests using TDD cycle. Use when the user says 'lets write acceptance tests' or 'I want to do ATDD'"
+# prettier-ignore
+description: 'Generate failing acceptance tests using TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/tea/config.yaml"
@@ -43,4 +44,3 @@ execution_hints:
   interactive: false # Minimize prompts
   autonomous: true # Proceed without user input unless blocked
   iterative: true
-

package/templates/bmad/tea/workflows/testarch/automate/steps-c/step-01-preflight-and-context.md

@@ -96,6 +96,8 @@ If missing: **HALT** with message "Run `framework` workflow first."
 ### Read TEA Config Flags
 
 - From `{config_source}` read `tea_use_playwright_utils`
+- From `{config_source}` read `tea_use_pactjs_utils`
+- From `{config_source}` read `tea_pact_mcp`
 - From `{config_source}` read `tea_browser_automation`
 - From `{config_source}` read `test_stack_type`
 
@@ -123,6 +125,24 @@ Load fragments based on their `tier` classification in `tea-index.csv`:
 
 **Detection**: Scan `{test_dir}` for files containing `page.goto` or `page.locator`. If none found, use API-only profile.
 
+### Pact.js Utils Loading
+
+**If `tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`, or microservices indicators detected):
+
+Load: `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md` (~800 lines)
+
+**If `tea_use_pactjs_utils` is disabled** but contract testing is relevant (microservices architecture detected, existing Pact config found):
+
+Load: `contract-testing.md` (~960 lines)
+
+**Detection**: Scan `{project-root}` for Pact indicators: `pact/` directory, `@pact-foundation/pact` in `package.json`, `pactUrls` in test files, `PACT_BROKER` in env files.
+
+### Pact MCP Loading
+
+**If `tea_pact_mcp` is `"mcp"`:**
+
+Load: `pact-mcp.md` (~150 lines) — enables agent to use SmartBear MCP tools for fetching provider states and generating pact tests during automation.
+
 ## 4. Load Knowledge Base Fragments
 
 Use `{knowledgeIndex}` and load only what is required.
@@ -145,6 +165,18 @@ Use `{knowledgeIndex}` and load only what is required.
 - `fixture-architecture.md`
 - `network-first.md`
 
+**Pact.js Utils (if enabled):**
+
+- `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md`
+
+**Contract Testing (if pactjs-utils disabled but relevant):**
+
+- `contract-testing.md`
+
+**Pact MCP (if tea_pact_mcp is "mcp"):**
+
+- `pact-mcp.md`
+
 **Healing (if auto-heal enabled):**
 
 - `test-healing-patterns.md`