@cregis-dev/cckit 0.3.0 → 0.4.1

package/templates/bmad/tea/workflows/testarch/ci/steps-c/step-02-generate-pipeline.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-02-generate-pipeline'
-description: 'Generate CI pipeline configuration'
+description: 'Generate CI pipeline configuration with adaptive orchestration (agent-team, subagent, or sequential)'
 nextStepFile: './step-03-configure-quality-gates.md'
 outputFile: '{test_artifacts}/ci-pipeline-progress.md'
 ---
@@ -15,6 +15,8 @@ Create platform-specific CI configuration with test execution, sharding, burn-in
 
 - 📖 Read the entire step file before acting
 - ✅ Speak in `{communication_language}`
+- ✅ Resolve execution mode from explicit user request first, then config
+- ✅ Apply fallback rules deterministically when requested mode is unsupported
 
 ---
 
@@ -35,6 +37,71 @@ Create platform-specific CI configuration with test execution, sharding, burn-in
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
+## 0. Resolve Execution Mode (User Override First)
+
+```javascript
+const orchestrationContext = {
+  config: {
+    execution_mode: config.tea_execution_mode || 'auto', // "auto" | "subagent" | "agent-team" | "sequential"
+    capability_probe: config.tea_capability_probe !== false, // true by default
+  },
+  timestamp: new Date().toISOString().replace(/[:.]/g, '-'),
+};
+
+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(orchestrationContext.config.execution_mode) || 'auto';
+const probeEnabled = orchestrationContext.config.capability_probe;
+
+const supports = { subagent: false, agentTeam: false };
+if (probeEnabled) {
+  supports.subagent = runtime.canLaunchSubagents?.() === true;
+  supports.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';
+}
+```
+
+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)
+
 ## 1. Resolve Output Path and Select Template
 
 Determine the pipeline output file path based on the detected `ci_platform`:
@@ -58,6 +125,7 @@ Include stages:
 
 - lint
 - test (parallel shards)
+- contract-test (if `tea_use_pactjs_utils` enabled)
 - burn-in (flaky detection)
 - report (aggregate + publish)
 
@@ -80,6 +148,51 @@ Write the selected pipeline configuration to the resolved output path from step
 - **Backend (C#/.NET)**: Use `dotnet test` with coverage, restore NuGet packages
 - **Backend (Ruby)**: Use `bundle exec rspec` with coverage, cache `vendor/bundle`
 
+### Contract Testing Pipeline (if `tea_use_pactjs_utils` enabled)
+
+When `tea_use_pactjs_utils` is enabled, add a `contract-test` stage after `test`:
+
+**Required env block** (add to the generated pipeline):
+
+```yaml
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }} # auto-set by GitHub Actions
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }} # NOT auto-set — must be defined explicitly
+```
+
+> **Note:** `GITHUB_SHA` is auto-set by GitHub Actions, but `GITHUB_BRANCH` is **not** — it must be derived from `github.head_ref` (for PRs) or `github.ref_name` (for pushes). The pactjs-utils library reads both from `process.env`.
+
+1. **Consumer test + publish**: Run consumer contract tests, then publish pacts to broker
+   - `npm run test:contract:consumer`
+   - `npx pact-broker publish ./pacts --consumer-app-version=$GITHUB_SHA --branch=$GITHUB_BRANCH`
+   - Only publish on PR and main branch pushes
+
+2. **Provider verification**: Run provider verification against published pacts
+   - `npm run test:contract:provider`
+   - `buildVerifierOptions` auto-reads `PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`, `GITHUB_SHA`, `GITHUB_BRANCH`
+   - Verification results published to broker when `CI=true`
+
+3. **Can-I-Deploy gate**: Block deployment if contracts are incompatible
+   - `npx pact-broker can-i-deploy --pacticipant=<ServiceName> --version=$GITHUB_SHA --to-environment=production`
+   - Add `--retry-while-unknown 6 --retry-interval 10` for async verification
+
+4. **Webhook job**: Add `repository_dispatch` trigger for `pact_changed` event
+   - Provider verification runs when consumers publish new pacts
+   - Ensures compatibility is checked on both consumer and provider changes
+
+5. **Breaking change handling**: When `PACT_BREAKING_CHANGE=true` env var is set:
+   - Provider test passes `includeMainAndDeployed: false` to `buildVerifierOptions` — verifies only matching branch
+   - Coordinate with consumer team before removing the flag
+
+6. **Record deployment**: After successful deployment, record version in broker
+   - `npx pact-broker record-deployment --pacticipant=<ServiceName> --version=$GITHUB_SHA --environment=production`
+
+Required CI secrets: `PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`
+
+**If `tea_pact_mcp` is `"mcp"`:** Reference the SmartBear MCP `Can I Deploy` and `Matrix` tools for pipeline guidance in `pact-mcp.md`.
+
 ---
 
 ### 4. Save Progress
@@ -104,6 +217,16 @@ Write the selected pipeline configuration to the resolved output path from step
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
+### 5. Orchestration Notes for This Step
+
+For this step, treat these work units as parallelizable when `resolvedMode` is `agent-team` or `subagent`:
+
+- Worker A: resolve platform path/template and produce base pipeline skeleton (section 1)
+- Worker B: construct stage definitions and test execution blocks (sections 2-3)
+- Worker C: contract-testing block (only when `tea_use_pactjs_utils` is true)
+
+If `resolvedMode` is `sequential`, execute sections 1→4 in order.
+
 Load next step: `{nextStepFile}`
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS:

package/templates/bmad/tea/workflows/testarch/ci/steps-c/step-03-configure-quality-gates.md

@@ -58,6 +58,13 @@ Define:
 - Fail CI on critical test failures
 - Optional: require traceability or nfr-assess output before release
 
+**Contract testing gate** (if `tea_use_pactjs_utils` is enabled):
+
+- **can-i-deploy must pass** before any deployment to staging or production
+- Block the deployment pipeline if contract verification fails
+- Treat consumer pact publishing failures as CI failures (contracts must stay up-to-date)
+- Provider verification must pass for all consumer pacts before merge
+
 ---
 
 ## 3. Notifications

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

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

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

@@ -1,7 +1,7 @@
 ---
 validationDate: 2026-01-27
 workflowName: testarch-ci
-workflowPath: /Users/murat.ozcan/opensource/bmad-method-test-architecture-enterprise/src/workflows/testarch/ci
+workflowPath: {project-root}/src/workflows/testarch/ci
 validationStatus: COMPLETE
 completionDate: 2026-01-27 10:24:01
 ---
@@ -85,9 +85,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/ci/workflow.yaml

@@ -1,6 +1,7 @@
 # Test Architect workflow: ci
 name: testarch-ci
-description: "Scaffold CI/CD quality pipeline with test execution. Use when the user says 'lets setup CI pipeline' or 'I want to create quality gates'"
+# prettier-ignore
+description: 'Scaffold CI/CD quality pipeline with test execution. Use when the user says "lets setup CI pipeline" or "I want to create quality gates"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/tea/config.yaml"
@@ -45,4 +46,3 @@ execution_hints:
   interactive: false # Minimize prompts, auto-detect when possible
   autonomous: true # Proceed without user input unless blocked
   iterative: true
-

package/templates/bmad/tea/workflows/testarch/framework/steps-c/step-03-scaffold-framework.md

@@ -1,6 +1,6 @@
 ---
 name: 'step-03-scaffold-framework'
-description: 'Create directory structure, config, fixtures, factories, and sample tests'
+description: 'Create framework scaffold with adaptive orchestration (agent-team, subagent, or sequential)'
 nextStepFile: './step-04-docs-and-scripts.md'
 knowledgeIndex: '{project-root}/_bmad/tea/testarch/tea-index.csv'
 outputFile: '{test_artifacts}/framework-setup-progress.md'
@@ -10,13 +10,15 @@ outputFile: '{test_artifacts}/framework-setup-progress.md'
 
 ## STEP GOAL
 
-Generate the test directory structure, configuration files, fixtures, factories, helpers, and sample tests.
+Generate the test directory structure, configuration files, fixtures, factories, helpers, and sample tests using deterministic mode selection with runtime fallback.
 
 ## MANDATORY EXECUTION RULES
 
 - 📖 Read the entire step file before acting
 - ✅ Speak in `{communication_language}`
 - ✅ Apply knowledge base patterns where required
+- ✅ Resolve execution mode from explicit user request first, then config
+- ✅ Apply fallback rules deterministically when requested mode is unsupported
 
 ---
 
@@ -37,6 +39,81 @@ Generate the test directory structure, configuration files, fixtures, factories,
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
+## 0. Resolve Execution Mode (User Override First)
+
+```javascript
+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 orchestrationContext = {
+  config: {
+    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: new Date().toISOString().replace(/[:.]/g, '-'),
+};
+
+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(orchestrationContext.config.execution_mode) || 'auto';
+const probeEnabled = orchestrationContext.config.capability_probe;
+
+const supports = { subagent: false, agentTeam: false };
+if (probeEnabled) {
+  supports.subagent = runtime.canLaunchSubagents?.() === true;
+  supports.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';
+}
+```
+
+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)
+
 ## 1. Create Directory Structure
 
 Use `{detected_stack}` from Step 1 to determine directory layout.
@@ -59,6 +136,15 @@ Create the idiomatic test directory for the detected language:
 - **Ruby (RSpec)**: `spec/` with `spec/unit/`, `spec/integration/`, `spec/api/`, `spec/support/`
 - **Rust**: `tests/` for integration tests, inline `#[cfg(test)]` modules for unit tests
 
+**If `config.tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`):
+
+Create contract testing directory structure:
+
+- `pact/http/consumer/` — consumer contract tests
+- `pact/http/provider/` — provider verification tests and state handlers
+- `pact/http/helpers/` — shared helpers (request filter, state constants)
+- `pact/message/` — message/Kafka contract tests (if async patterns detected)
+
 ---
 
 ## 2. Generate Framework Config
@@ -122,6 +208,19 @@ Read `{config_source}` and use `{knowledgeIndex}` to load fragments based on `co
 
 - `fixture-architecture.md`, `data-factories.md`, `network-first.md`, `playwright-config.md`, `test-quality.md`
 
+**If Pact.js Utils enabled** (`config.tea_use_pactjs_utils`):
+
+- `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md`, `contract-testing.md`
+- Recommend installing `@seontechnologies/pactjs-utils` and `@pact-foundation/pact`
+
+**If Pact.js Utils disabled but contract testing relevant:**
+
+- `contract-testing.md`
+
+**If Pact MCP enabled** (`config.tea_pact_mcp` is `"mcp"`):
+
+- `pact-mcp.md`
+
 Implement:
 
 - Fixture index with `mergeTests`
@@ -158,9 +257,33 @@ Create helpers for:
 - Auth helpers
 - Test data factories (language-idiomatic patterns)
 
+**If `config.tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`):
+
+Create contract test samples in `pact/` directory:
+
+- **Consumer test**: Example using `PactV3` + `createProviderState` for type-safe provider states
+- **Provider verification test**: Example using `buildVerifierOptions` + `createRequestFilter`
+- **Helpers**: Request filter setup (`pact/http/helpers/request-filter.ts`), shared state constants (`pact/http/helpers/states.ts`)
+- **Vitest configs** (if vitest detected): `vitest.consumer.config.mts` and `vitest.provider.config.mts` for separated test execution
+- **package.json scripts**: `test:contract:consumer`, `test:contract:provider`, `pact:publish`, `pact:can-deploy`
+
 ---
 
-### 6. Save Progress
+### 6. Orchestration Notes for This Step
+
+For this step, treat these work units as parallelizable when `resolvedMode` is `agent-team` or `subagent`:
+
+- Worker A: directory + framework config + env setup (sections 1-3)
+- Worker B: fixtures + factories (section 4)
+- Worker C: sample tests + helpers (section 5)
+
+In parallel-capable modes, runtime decides worker scheduling and concurrency.
+
+If `resolvedMode` is `sequential`, execute sections 1→5 in order.
+
+Regardless of mode, outputs must be identical in structure and quality.
+
+### 7. Save Progress
 
 **Save this step's accumulated work to `{outputFile}`.**
 

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

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

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

@@ -1,7 +1,7 @@
 ---
 validationDate: 2026-01-27
 workflowName: testarch-framework
-workflowPath: /Users/murat.ozcan/opensource/bmad-method-test-architecture-enterprise/src/workflows/testarch/framework
+workflowPath: {project-root}/src/workflows/testarch/framework
 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/framework/workflow.yaml

@@ -1,6 +1,7 @@
 # Test Architect workflow: framework
 name: testarch-framework
-description: "Initialize test framework with Playwright or Cypress. Use when the user says 'lets setup test framework' or 'I want to initialize testing framework'"
+# prettier-ignore
+description: 'Initialize test framework with Playwright or Cypress. Use when the user says "lets setup test framework" or "I want to initialize testing framework"'
 
 # Critical variables from config
 config_source: "{project-root}/_bmad/tea/config.yaml"
@@ -45,4 +46,3 @@ execution_hints:
   interactive: false # Minimize prompts; auto-detect when possible
   autonomous: true # Proceed without user input unless blocked
   iterative: true
-