@cregis-dev/cckit 0.4.0 → 0.5.0

package/templates/bmad/tea/workflows/testarch/atdd/checklist.md

@@ -1,374 +0,0 @@
-# ATDD Workflow Validation Checklist
-
-Use this checklist to validate that the ATDD workflow has been executed correctly and all deliverables meet quality standards.
-
-## Prerequisites
-
-Before starting this workflow, verify:
-
-- [ ] Story approved with clear acceptance criteria (AC must be testable)
-- [ ] Development sandbox/environment ready
-- [ ] Framework scaffolding exists (run `framework` workflow if missing)
-- [ ] Test framework configuration available (playwright.config.ts or cypress.config.ts)
-- [ ] Package.json has test dependencies installed (Playwright or Cypress)
-
-**Halt if missing:** Framework scaffolding or story acceptance criteria
-
----
-
-## Step 1: Story Context and Requirements
-
-- [ ] Story markdown file loaded and parsed successfully
-- [ ] All acceptance criteria identified and extracted
-- [ ] Affected systems and components identified
-- [ ] Technical constraints documented
-- [ ] Framework configuration loaded (playwright.config.ts or cypress.config.ts)
-- [ ] Test directory structure identified from config
-- [ ] Existing fixture patterns reviewed for consistency
-- [ ] Similar test patterns searched and found in `{test_dir}`
-- [ ] Knowledge base fragments loaded:
-  - [ ] `fixture-architecture.md`
-  - [ ] `data-factories.md`
-  - [ ] `component-tdd.md`
-  - [ ] `network-first.md`
-  - [ ] `test-quality.md`
-
----
-
-## Step 2: Test Level Selection and Strategy
-
-- [ ] Each acceptance criterion analyzed for appropriate test level
-- [ ] Test level selection framework applied (E2E vs API vs Component vs Unit)
-- [ ] E2E tests: Critical user journeys and multi-system integration identified
-- [ ] API tests: Business logic and service contracts identified
-- [ ] Component tests: UI component behavior and interactions identified
-- [ ] Unit tests: Pure logic and edge cases identified (if applicable)
-- [ ] Duplicate coverage avoided (same behavior not tested at multiple levels unnecessarily)
-- [ ] Tests prioritized using P0-P3 framework (if test-design document exists)
-- [ ] Primary test level set in `primary_level` variable (typically E2E or API)
-- [ ] Test levels documented in ATDD checklist
-
----
-
-## Step 3: Failing Tests Generated
-
-### Test File Structure Created
-
-- [ ] Test files organized in appropriate directories:
-  - [ ] `tests/e2e/` for end-to-end tests
-  - [ ] `tests/api/` for API tests
-  - [ ] `tests/component/` for component tests
-  - [ ] `tests/support/` for infrastructure (fixtures, factories, helpers)
-
-### E2E Tests (If Applicable)
-
-- [ ] E2E test files created in `tests/e2e/`
-- [ ] All tests follow Given-When-Then format
-- [ ] Tests use `data-testid` selectors (not CSS classes or fragile selectors)
-- [ ] One assertion per test (atomic test design)
-- [ ] No hard waits or sleeps (explicit waits only)
-- [ ] Network-first pattern applied (route interception BEFORE navigation)
-- [ ] Tests fail initially (RED phase verified by local test run)
-- [ ] Failure messages are clear and actionable
-
-### API Tests (If Applicable)
-
-- [ ] API test files created in `tests/api/`
-- [ ] Tests follow Given-When-Then format
-- [ ] API contracts validated (request/response structure)
-- [ ] HTTP status codes verified
-- [ ] Response body validation includes all required fields
-- [ ] Error cases tested (400, 401, 403, 404, 500)
-- [ ] Tests fail initially (RED phase verified)
-
-### Component Tests (If Applicable)
-
-- [ ] Component test files created in `tests/component/`
-- [ ] Tests follow Given-When-Then format
-- [ ] Component mounting works correctly
-- [ ] Interaction testing covers user actions (click, hover, keyboard)
-- [ ] State management within component validated
-- [ ] Props and events tested
-- [ ] Tests fail initially (RED phase verified)
-
-### Test Quality Validation
-
-- [ ] All tests use Given-When-Then structure with clear comments
-- [ ] All tests have descriptive names explaining what they test
-- [ ] No duplicate tests (same behavior tested multiple times)
-- [ ] No flaky patterns (race conditions, timing issues)
-- [ ] No test interdependencies (tests can run in any order)
-- [ ] Tests are deterministic (same input always produces same result)
-
----
-
-## Step 4: Data Infrastructure Built
-
-### Data Factories Created
-
-- [ ] Factory files created in `tests/support/factories/`
-- [ ] All factories use `@faker-js/faker` for random data generation (no hardcoded values)
-- [ ] Factories support overrides for specific test scenarios
-- [ ] Factories generate complete valid objects matching API contracts
-- [ ] Helper functions for bulk creation provided (e.g., `createUsers(count)`)
-- [ ] Factory exports are properly typed (TypeScript)
-
-### Test Fixtures Created
-
-- [ ] Fixture files created in `tests/support/fixtures/`
-- [ ] All fixtures use Playwright's `test.extend()` pattern
-- [ ] Fixtures have setup phase (arrange test preconditions)
-- [ ] Fixtures provide data to tests via `await use(data)`
-- [ ] Fixtures have teardown phase with auto-cleanup (delete created data)
-- [ ] Fixtures are composable (can use other fixtures if needed)
-- [ ] Fixtures are isolated (each test gets fresh data)
-- [ ] Fixtures are type-safe (TypeScript types defined)
-
-### Mock Requirements Documented
-
-- [ ] External service mocking requirements identified
-- [ ] Mock endpoints documented with URLs and methods
-- [ ] Success response examples provided
-- [ ] Failure response examples provided
-- [ ] Mock requirements documented in ATDD checklist for DEV team
-
-### data-testid Requirements Listed
-
-- [ ] All required data-testid attributes identified from E2E tests
-- [ ] data-testid list organized by page or component
-- [ ] Each data-testid has clear description of element it targets
-- [ ] data-testid list included in ATDD checklist for DEV team
-
----
-
-## Step 5: Implementation Checklist Created
-
-- [ ] Implementation checklist created with clear structure
-- [ ] Each failing test mapped to concrete implementation tasks
-- [ ] Tasks include:
-  - [ ] Route/component creation
-  - [ ] Business logic implementation
-  - [ ] API integration
-  - [ ] data-testid attribute additions
-  - [ ] Error handling
-  - [ ] Test execution command
-  - [ ] Completion checkbox
-- [ ] Red-Green-Refactor workflow documented in checklist
-- [ ] RED phase marked as complete (TEA responsibility)
-- [ ] GREEN phase tasks listed for DEV team
-- [ ] REFACTOR phase guidance provided
-- [ ] Execution commands provided:
-  - [ ] Run all tests: `npm run test:e2e`
-  - [ ] Run specific test file
-  - [ ] Run in headed mode
-  - [ ] Debug specific test
-- [ ] Estimated effort included (hours or story points)
-
----
-
-## Step 6: Deliverables Generated
-
-### ATDD Checklist Document Created
-
-- [ ] Output file created at `{test_artifacts}/atdd-checklist-{story_id}.md`
-- [ ] Document follows template structure from `atdd-checklist-template.md`
-- [ ] Document includes all required sections:
-  - [ ] Story summary
-  - [ ] Acceptance criteria breakdown
-  - [ ] Failing tests created (paths and line counts)
-  - [ ] Data factories created
-  - [ ] Fixtures created
-  - [ ] Mock requirements
-  - [ ] Required data-testid attributes
-  - [ ] Implementation checklist
-  - [ ] Red-green-refactor workflow
-  - [ ] Execution commands
-  - [ ] Next steps for DEV team
-- [ ] Output shared with DEV workflow (manual handoff; not auto-consumed)
-
-### All Tests Verified to Fail (RED Phase)
-
-- [ ] Full test suite run locally before finalizing
-- [ ] All tests fail as expected (RED phase confirmed)
-- [ ] No tests passing before implementation (if passing, test is invalid)
-- [ ] Failure messages documented in ATDD checklist
-- [ ] Failures are due to missing implementation, not test bugs
-- [ ] Test run output captured for reference
-
-### Summary Provided
-
-- [ ] Summary includes:
-  - [ ] Story ID
-  - [ ] Primary test level
-  - [ ] Test counts (E2E, API, Component)
-  - [ ] Test file paths
-  - [ ] Factory count
-  - [ ] Fixture count
-  - [ ] Mock requirements count
-  - [ ] data-testid count
-  - [ ] Implementation task count
-  - [ ] Estimated effort
-  - [ ] Next steps for DEV team
-  - [ ] Output file path
-  - [ ] Knowledge base references applied
-
----
-
-## Quality Checks
-
-### Test Design Quality
-
-- [ ] Tests are readable (clear Given-When-Then structure)
-- [ ] Tests are maintainable (use factories and fixtures, not hardcoded data)
-- [ ] Tests are isolated (no shared state between tests)
-- [ ] Tests are deterministic (no race conditions or flaky patterns)
-- [ ] Tests are atomic (one assertion per test)
-- [ ] Tests are fast (no unnecessary waits or delays)
-
-### Knowledge Base Integration
-
-- [ ] fixture-architecture.md patterns applied to all fixtures
-- [ ] data-factories.md patterns applied to all factories
-- [ ] network-first.md patterns applied to E2E tests with network requests
-- [ ] component-tdd.md patterns applied to component tests
-- [ ] test-quality.md principles applied to all test design
-
-### Code Quality
-
-- [ ] All TypeScript types are correct and complete
-- [ ] No linting errors in generated test files
-- [ ] Consistent naming conventions followed
-- [ ] Imports are organized and correct
-- [ ] Code follows project style guide
-
----
-
-## Integration Points
-
-### With DEV Agent
-
-- [ ] ATDD checklist provides clear implementation guidance
-- [ ] Implementation tasks are granular and actionable
-- [ ] data-testid requirements are complete and clear
-- [ ] Mock requirements include all necessary details
-- [ ] Execution commands work correctly
-
-### With Story Workflow
-
-- [ ] Story ID correctly referenced in output files
-- [ ] Acceptance criteria from story accurately reflected in tests
-- [ ] Technical constraints from story considered in test design
-
-### With Framework Workflow
-
-- [ ] Test framework configuration correctly detected and used
-- [ ] Directory structure matches framework setup
-- [ ] Fixtures and helpers follow established patterns
-- [ ] Naming conventions consistent with framework standards
-
-### With test-design Workflow (If Available)
-
-- [ ] P0 scenarios from test-design prioritized in ATDD
-- [ ] Risk assessment from test-design considered in test coverage
-- [ ] Coverage strategy from test-design aligned with ATDD tests
-
----
-
-## Completion Criteria
-
-All of the following must be true before marking this workflow as complete:
-
-- [ ] **Story acceptance criteria analyzed** and mapped to appropriate test levels
-- [ ] **Failing tests created** at all appropriate levels (E2E, API, Component)
-- [ ] **Given-When-Then format** used consistently across all tests
-- [ ] **RED phase verified** by local test run (all tests failing as expected)
-- [ ] **Network-first pattern** applied to E2E tests with network requests
-- [ ] **Data factories created** using faker (no hardcoded test data)
-- [ ] **Fixtures created** with auto-cleanup in teardown
-- [ ] **Mock requirements documented** for external services
-- [ ] **data-testid attributes listed** for DEV team
-- [ ] **Implementation checklist created** mapping tests to code tasks
-- [ ] **Red-green-refactor workflow documented** in ATDD checklist
-- [ ] **Execution commands provided** and verified to work
-- [ ] **ATDD checklist document created** and saved to correct location
-- [ ] **Output file formatted correctly** using template structure
-- [ ] **Knowledge base references applied** and documented in summary
-- [ ] **No test quality issues** (flaky patterns, race conditions, hardcoded data)
-
----
-
-## Common Issues and Resolutions
-
-### Issue: Tests pass before implementation
-
-**Problem:** A test passes even though no implementation code exists yet.
-
-**Resolution:**
-
-- Review test to ensure it's testing actual behavior, not mocked/stubbed behavior
-- Check if test is accidentally using existing functionality
-- Verify test assertions are correct and meaningful
-- Rewrite test to fail until implementation is complete
-
-### Issue: Network-first pattern not applied
-
-**Problem:** Route interception happens after navigation, causing race conditions.
-
-**Resolution:**
-
-- Move `await page.route()` calls BEFORE `await page.goto()`
-- Review `network-first.md` knowledge fragment
-- Update all E2E tests to follow network-first pattern
-
-### Issue: Hardcoded test data in tests
-
-**Problem:** Tests use hardcoded strings/numbers instead of factories.
-
-**Resolution:**
-
-- Replace all hardcoded data with factory function calls
-- Use `faker` for all random data generation
-- Update data-factories to support all required test scenarios
-
-### Issue: Fixtures missing auto-cleanup
-
-**Problem:** Fixtures create data but don't clean it up in teardown.
-
-**Resolution:**
-
-- Add cleanup logic after `await use(data)` in fixture
-- Call deletion/cleanup functions in teardown
-- Verify cleanup works by checking database/storage after test run
-
-### Issue: Tests have multiple assertions
-
-**Problem:** Tests verify multiple behaviors in single test (not atomic).
-
-**Resolution:**
-
-- Split into separate tests (one assertion per test)
-- Each test should verify exactly one behavior
-- Use descriptive test names to clarify what each test verifies
-
-### Issue: Tests depend on execution order
-
-**Problem:** Tests fail when run in isolation or different order.
-
-**Resolution:**
-
-- Remove shared state between tests
-- Each test should create its own test data
-- Use fixtures for consistent setup across tests
-- Verify tests can run with `.only` flag
-
----
-
-## Notes for TEA Agent
-
-- **Preflight halt is critical:** Do not proceed if story has no acceptance criteria or framework is missing
-- **RED phase verification is mandatory:** Tests must fail before sharing with DEV team
-- **Network-first pattern:** Route interception BEFORE navigation prevents race conditions
-- **One assertion per test:** Atomic tests provide clear failure diagnosis
-- **Auto-cleanup is non-negotiable:** Every fixture must clean up data in teardown
-- **Use knowledge base:** Load relevant fragments (fixture-architecture, data-factories, network-first, component-tdd, test-quality) for guidance
-- **Share with DEV agent:** ATDD checklist provides implementation roadmap from red to green

package/templates/bmad/tea/workflows/testarch/atdd/instructions.md

@@ -1,45 +0,0 @@
-<!-- Powered by BMAD-CORE™ -->
-
-# Acceptance Test-Driven Development (ATDD)
-
-**Workflow ID**: `_bmad/tea/testarch/atdd`
-**Version**: 5.0 (Step-File Architecture)
-
----
-
-## Overview
-
-Generates **failing acceptance tests** before implementation (TDD red phase), plus an implementation checklist. Produces tests at appropriate levels (E2E/API/Component) with supporting fixtures and helpers.
-
----
-
-## WORKFLOW ARCHITECTURE
-
-This workflow uses **step-file architecture**:
-
-- **Micro-file Design**: Each step is self-contained
-- **JIT Loading**: Only the current step file is in memory
-- **Sequential Enforcement**: Execute steps in order without skipping
-
----
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-From `workflow.yaml`, resolve:
-
-- `config_source`, `test_artifacts`, `user_name`, `communication_language`, `document_output_language`, `date`
-- `test_dir`
-
-### 2. First Step
-
-Load, read completely, and execute:
-`{project-root}/_bmad/tea/workflows/testarch/atdd/steps-c/step-01-preflight-and-context.md`
-
-### 3. Resume Support
-
-If the user selects **Resume** mode, load, read completely, and execute:
-`{project-root}/_bmad/tea/workflows/testarch/atdd/steps-c/step-01b-resume.md`
-
-This checks the output document for progress tracking frontmatter and routes to the next incomplete step.

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

@@ -1,226 +0,0 @@
----
-name: 'step-01-preflight-and-context'
-description: 'Verify prerequisites and load story, framework, and knowledge base'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
-nextStepFile: './step-02-generation-mode.md'
-knowledgeIndex: '{project-root}/_bmad/tea/testarch/tea-index.csv'
----
-
-# Step 1: Preflight & Context Loading
-
-## STEP GOAL
-
-Verify prerequisites and load all required inputs before generating failing tests.
-
-## MANDATORY EXECUTION RULES
-
-- 📖 Read the entire step file before acting
-- ✅ Speak in `{communication_language}`
-- 🚫 Halt if requirements are missing
-
----
-
-## 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. Stack Detection
-
-**Read `config.test_stack_type`** from `{config_source}`.
-
-**Auto-Detection Algorithm** (when `test_stack_type` is `"auto"` or not configured):
-
-- Scan `{project-root}` for project manifests:
-  - **Frontend indicators**: `package.json` with react/vue/angular/next dependencies, `playwright.config.*`, `vite.config.*`, `webpack.config.*`
-  - **Backend indicators**: `pyproject.toml`, `pom.xml`/`build.gradle`, `go.mod`, `*.csproj`/`*.sln`, `Gemfile`, `Cargo.toml`
-  - **Both present** = `fullstack`; only frontend = `frontend`; only backend = `backend`
-- Explicit `test_stack_type` config value overrides auto-detection
-- **Backward compatibility**: if `test_stack_type` is not in config, treat as `"auto"` (preserves current frontend behavior for existing installs)
-
-Store result as `{detected_stack}` = `frontend` | `backend` | `fullstack`
-
----
-
-## 2. Prerequisites (Hard Requirements)
-
-- Story approved with **clear acceptance criteria**
-- Test framework configured:
-  - **If {detected_stack} is `frontend` or `fullstack`:** `playwright.config.ts` or `cypress.config.ts`
-  - **If {detected_stack} is `backend`:** relevant test config exists (e.g., `conftest.py`, `src/test/`, `*_test.go`, `.rspec`)
-- Development environment available
-
-If any are missing: **HALT** and notify the user.
-
----
-
-## 3. Load Story Context
-
-- Read story markdown from `{story_file}` (or ask user if not provided)
-- Extract acceptance criteria and constraints
-- Identify affected components and integrations
-
----
-
-## 4. Load Framework & Existing Patterns
-
-- Read framework config
-- Inspect `{test_dir}` for existing test patterns, fixtures, helpers
-
-## 4.5 Read TEA Config Flags
-
-From `{config_source}`:
-
-- `tea_use_playwright_utils`
-- `tea_use_pactjs_utils`
-- `tea_pact_mcp`
-- `tea_browser_automation`
-- `test_stack_type`
-
----
-
-### Tiered Knowledge Loading
-
-Load fragments based on their `tier` classification in `tea-index.csv`:
-
-1. **Core tier** (always load): Foundational fragments required for this workflow
-2. **Extended tier** (load on-demand): Load when deeper analysis is needed or when the user's context requires it
-3. **Specialized tier** (load only when relevant): Load only when the specific use case matches (e.g., contract-testing only for microservices, email-auth only for email flows)
-
-> **Context Efficiency**: Loading only core fragments reduces context usage by 40-50% compared to loading all fragments.
-
-### Playwright Utils Loading Profiles
-
-**If `tea_use_playwright_utils` is enabled**, select the appropriate loading profile:
-
-- **API-only profile** (when `{detected_stack}` is `backend` or no `page.goto`/`page.locator` found in test files):
-  Load: `overview`, `api-request`, `auth-session`, `recurse` (~1,800 lines)
-
-- **Full UI+API profile** (when `{detected_stack}` is `frontend`/`fullstack` or browser tests detected):
-  Load: all Playwright Utils core fragments (~4,500 lines)
-
-**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`
-
-**If `tea_use_pactjs_utils` is disabled** but contract testing is relevant:
-
-Load: `contract-testing.md`
-
-### Pact MCP Loading
-
-**If `tea_pact_mcp` is `"mcp"`:**
-
-Load: `pact-mcp.md`
-
-## 5. Load Knowledge Base Fragments
-
-Use `{knowledgeIndex}` to load:
-
-**Core (always):**
-
-- `data-factories.md`
-- `component-tdd.md`
-- `test-quality.md`
-- `test-healing-patterns.md`
-
-**If {detected_stack} is `frontend` or `fullstack`:**
-
-- `selector-resilience.md`
-- `timing-debugging.md`
-
-**Playwright Utils (if enabled and {detected_stack} is `frontend` or `fullstack`):**
-
-- `overview.md`, `api-request.md`, `network-recorder.md`, `auth-session.md`, `intercept-network-call.md`, `recurse.md`, `log.md`, `file-utils.md`, `network-error-monitor.md`, `fixtures-composition.md`
-
-**Playwright CLI (if tea_browser_automation is "cli" or "auto" and {detected_stack} is `frontend` or `fullstack`):**
-
-- `playwright-cli.md`
-
-**MCP Patterns (if tea_browser_automation is "mcp" or "auto" and {detected_stack} is `frontend` or `fullstack`):**
-
-- (existing MCP-related fragments, if any are added in future)
-
-**Traditional Patterns (if utils disabled and {detected_stack} is `frontend` or `fullstack`):**
-
-- `fixture-architecture.md`
-- `network-first.md`
-
-**Backend Patterns (if {detected_stack} is `backend` or `fullstack`):**
-
-- `test-levels-framework.md`
-- `test-priorities-matrix.md`
-- `ci-burn-in.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`
-
----
-
-## 6. Confirm Inputs
-
-Summarize loaded inputs and confirm with the user. Then proceed.
-
----
-
-## 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-01-preflight-and-context']
-  lastStep: 'step-01-preflight-and-context'
-  lastSaved: '{date}'
-  ---
-  ```
-
-  Then write this step's output below the frontmatter.
-
-- **If `{outputFile}` already exists**, update:
-  - Add `'step-01-preflight-and-context'` to `stepsCompleted` array (only if not already present)
-  - Set `lastStep: 'step-01-preflight-and-context'`
-  - Set `lastSaved: '{date}'`
-  - Append this step's output to the appropriate section.
-
-**Update `inputDocuments`**: Set `inputDocuments` in the output template frontmatter to the list of artifact paths loaded in this step (e.g., knowledge fragments, test design documents, configuration files).
-
-Load next step: `{nextStepFile}`
-
-## 🚨 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.