@cregis-dev/cckit 0.3.0 → 0.4.0

package/templates/bmad/core/tasks/review-edge-case-hunter.xml

@@ -0,0 +1,63 @@
+<!-- if possible, run this in a separate subagent or process with read access to the project,
+  but no context except the content to review -->
+
+<task id="_bmad/core/tasks/review-edge-case-hunter.xml" name="Edge Case Hunter Review"
+  description="Walk every branching path and boundary condition in content, report only unhandled edge cases. Orthogonal to adversarial review - method-driven not attitude-driven.">
+  <objective>You are a pure path tracer. Never comment on whether code is good or bad; only list missing handling.
+When a diff is provided, scan only the diff hunks and list boundaries that are directly reachable from the changed lines and lack an explicit guard in the diff.
+When no diff is provided (full file or function), treat the entire provided content as the scope.
+Ignore the rest of the codebase unless the provided content explicitly references external functions.</objective>
+
+  <inputs>
+    <input name="content" desc="Content to review - diff, full file, or function" />
+    <input name="also_consider" required="false"
+      desc="Optional areas to keep in mind during review alongside normal edge-case analysis" />
+  </inputs>
+
+  <output-format>Return ONLY a valid JSON array of objects. Each object must contain exactly these four fields and nothing else:
+{
+  "location": "file:line",
+  "trigger_condition": "one-line description (max 15 words)",
+  "guard_snippet": "minimal code sketch that closes the gap",
+  "potential_consequence": "what could actually go wrong (max 15 words)"
+}
+No extra text, no explanations, no markdown wrapping.</output-format>
+
+  <llm critical="true">
+    <i>MANDATORY: Execute ALL steps in the flow section IN EXACT ORDER</i>
+    <i>DO NOT skip steps or change the sequence</i>
+    <i>HALT immediately when halt-conditions are met</i>
+    <i>Each action xml tag within step xml tag is a REQUIRED action to complete that step</i>
+
+    <i>Your method is exhaustive path enumeration — mechanically walk every branch, not hunt by intuition</i>
+    <i>Trace each branching path: conditionals, switches, early returns, guard clauses, loops, error handlers</i>
+    <i>Trace each boundary condition: null, undefined, empty, zero, negative, overflow, max-length, type coercion, concurrency, timing</i>
+    <i>Report ONLY paths and conditions that lack handling — discard handled ones silently</i>
+    <i>Do NOT editorialize or add filler — findings only</i>
+  </llm>
+
+  <flow>
+    <step n="1" title="Receive Content">
+      <action>Load the content to review from provided input or context</action>
+      <action>If content to review is empty, ask for clarification and abort task</action>
+      <action>Identify content type (diff, full file, or function) to determine scope rules</action>
+    </step>
+
+    <step n="2" title="Exhaustive Path Analysis" critical="true">
+      <mandate>Walk every branching path and boundary condition within scope - report only unhandled ones</mandate>
+      <action>If also_consider input was provided, incorporate those areas into the analysis</action>
+      <action>Enumerate all branching paths and boundary conditions within scope: conditionals, switches, early returns, guard clauses, loops, error handlers, null/empty states, overflow, type edges, concurrency, timing</action>
+      <action>For each path: determine whether the content handles it</action>
+      <action>Collect only the unhandled paths as findings - discard handled ones silently</action>
+    </step>
+
+    <step n="3" title="Present Findings">
+      <action>Output findings as a JSON array following the output-format specification exactly</action>
+    </step>
+  </flow>
+
+  <halt-conditions>
+    <condition>HALT if content is empty or unreadable</condition>
+  </halt-conditions>
+
+</task>

package/templates/bmad/core/tasks/shard-doc.xml

@@ -1,5 +1,5 @@
 <task id="_bmad/core/tasks/shard-doc" name="Shard Document"
-  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says 'Shard Document [document]'">
+  description="Splits large markdown documents into smaller, organized files based on level 2 (default) sections. Use if the user says perform shard document">
   <objective>Split large markdown documents into smaller, organized files based on level 2 sections using @kayvan/markdown-tree-parser tool</objective>
 
   <llm critical="true">

package/templates/bmad/core/workflows/advanced-elicitation/workflow.xml

@@ -1,5 +1,5 @@
 <task id="_bmad/core/workflows/advanced-elicitation/workflow.xml" name="Advanced Elicitation"
-  description="Push the LLM to reconsider refine and improve its recent output. Use when the user asks for 'advanced elicitation'"
+  description="Push the LLM to reconsider refine and improve its recent output. Use when the user asks for advanced elicitation"
   methods="{project-root}/_bmad/core/workflows/advanced-elicitation/methods.csv"
   agent-party="{project-root}/_bmad/_config/agent-manifest.csv">
   <llm critical="true">

package/templates/bmad/core/workflows/brainstorming/steps/step-01-session-setup.md

@@ -29,23 +29,30 @@ Initialize the brainstorming workflow by detecting continuation state and settin
 
 ## INITIALIZATION SEQUENCE:
 
-### 1. Check for Existing Workflow
+### 1. Check for Existing Sessions
 
-First, check if the output document already exists:
+First, check the brainstorming sessions folder for existing sessions:
 
-- Look for file at `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`
-- If exists, read the complete file including frontmatter
-- If not exists, this is a fresh workflow
+- List all files in `{output_folder}/brainstorming/`
+- **DO NOT read any file contents** - only list filenames
+- If files exist, identify the most recent by date/time in the filename
+- If no files exist, this is a fresh workflow
 
-### 2. Handle Continuation (If Document Exists)
+### 2. Handle Existing Sessions (If Files Found)
 
-If the document exists and has frontmatter with `stepsCompleted`:
+If existing session files are found:
 
-- **STOP here** and load `./step-01b-continue.md` immediately
-- Do not proceed with any initialization tasks
-- Let step-01b handle the continuation logic
+- Display the most recent session filename (do NOT read its content)
+- Ask the user: "Found existing session: `[filename]`. Would you like to:
+  **[1]** Continue this session
+  **[2]** Start a new session
+  **[3]** See all existing sessions"
 
-### 3. Fresh Workflow Setup (If No Document)
+- If user selects **[1]** (continue): Set `{brainstorming_session_output_file}` to that file path and load `./step-01b-continue.md`
+- If user selects **[2]** (new): Generate new filename with current date/time and proceed to step 3
+- If user selects **[3]** (see all): List all session filenames and ask which to continue or if new
+
+### 3. Fresh Workflow Setup (If No Files or User Chooses New)
 
 If no document exists or no `stepsCompleted` in frontmatter:
 
@@ -55,10 +62,10 @@ Create the brainstorming session document:
 
 ```bash
 # Create directory if needed
-mkdir -p "$(dirname "{output_folder}/brainstorming/brainstorming-session-{{date}}.md")"
+mkdir -p "$(dirname "{brainstorming_session_output_file}")"
 
 # Initialize from template
-cp "{template_path}" "{output_folder}/brainstorming/brainstorming-session-{{date}}.md"
+cp "{template_path}" "{brainstorming_session_output_file}"
 ```
 
 #### B. Context File Check and Loading
@@ -134,7 +141,7 @@ _[Content based on conversation about session parameters and facilitator approac
 
 ## APPEND TO DOCUMENT:
 
-When user selects approach, append the session overview content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from above.
+When user selects approach, append the session overview content directly to `{brainstorming_session_output_file}` using the structure from above.
 
 ### E. Continue to Technique Selection
 
@@ -152,7 +159,7 @@ Which approach appeals to you most? (Enter 1-4)"
 
 #### When user selects approach number:
 
-- **Append initial session overview to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`**
+- **Append initial session overview to `{brainstorming_session_output_file}`**
 - **Update frontmatter:** `stepsCompleted: [1]`, `selected_approach: '[selected approach]'`
 - **Load the appropriate step-02 file** based on selection
 
@@ -167,7 +174,9 @@ After user selects approach number:
 
 ## SUCCESS METRICS:
 
-✅ Existing workflow detected and continuation handled properly
+✅ Existing sessions detected without reading file contents
+✅ User prompted to continue existing session or start new
+✅ Correct session file selected for continuation
 ✅ Fresh workflow initialized with correct document structure
 ✅ Session context gathered and understood clearly
 ✅ User's approach selection captured and routed correctly
@@ -176,7 +185,9 @@ After user selects approach number:
 
 ## FAILURE MODES:
 
-❌ Not checking for existing document before creating new one
+❌ Reading file contents during session detection (wastes context)
+❌ Not asking user before continuing existing session
+❌ Not properly routing user's continue/new session selection
 ❌ Missing continuation detection leading to duplicate work
 ❌ Insufficient session context gathering
 ❌ Not properly routing user's approach selection
@@ -184,7 +195,9 @@ After user selects approach number:
 
 ## SESSION SETUP PROTOCOLS:
 
-- Always verify document existence before initialization
+- Always list sessions folder WITHOUT reading file contents
+- Ask user before continuing any existing session
+- Only load continue step after user confirms
 - Load brain techniques CSV only when needed for technique presentation
 - Use collaborative facilitation language throughout
 - Maintain psychological safety for creative exploration

package/templates/bmad/core/workflows/brainstorming/steps/step-01b-continue.md

@@ -35,7 +35,7 @@ Load existing document and analyze current state:
 
 **Document Analysis:**
 
-- Read existing `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`
+- Read existing `{brainstorming_session_output_file}`
 - Examine frontmatter for `stepsCompleted`, `session_topic`, `session_goals`
 - Review content to understand session progress and outcomes
 - Identify current stage and next logical steps

package/templates/bmad/core/workflows/brainstorming/steps/step-03-technique-execution.md

@@ -296,7 +296,7 @@ After final technique element:
 
 #### If 'C' (Move to organization):
 
-- **Append the technique execution content to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`**
+- **Append the technique execution content to `{brainstorming_session_output_file}`**
 - **Update frontmatter:** `stepsCompleted: [1, 2, 3]`
 - **Load:** `./step-04-idea-organization.md`
 
@@ -356,7 +356,7 @@ _[Short narrative describing the user and AI collaboration journey - what made t
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from above.
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from above.
 
 ## SUCCESS METRICS:
 

package/templates/bmad/core/workflows/brainstorming/steps/step-04-idea-organization.md

@@ -253,14 +253,14 @@ Provide final session wrap-up and forward guidance:
 
 #### If [C] Complete:
 
-- **Append the final session content to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`**
+- **Append the final session content to `{brainstorming_session_output_file}`**
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
 - Set `session_active: false` and `workflow_completed: true`
 - Complete workflow with positive closure message
 
 ## APPEND TO DOCUMENT:
 
-When user selects 'C', append the content directly to `{output_folder}/brainstorming/brainstorming-session-{{date}}.md` using the structure from step 7.
+When user selects 'C', append the content directly to `{brainstorming_session_output_file}` using the structure from step 7.
 
 ## SUCCESS METRICS:
 

package/templates/bmad/core/workflows/brainstorming/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: brainstorming
-description: "Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says 'help me brainstorm' or 'help me ideate'."
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
 context_file: '' # Optional context file path for project-specific guidance
 ---
 
@@ -45,7 +45,9 @@ Load config from `{project-root}/_bmad/core/config.yaml` and resolve:
 - `installed_path` = `{project-root}/_bmad/core/workflows/brainstorming`
 - `template_path` = `{installed_path}/template.md`
 - `brain_techniques_path` = `{installed_path}/brain-methods.csv`
-- `default_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}.md`
+- `brainstorming_session_output_file` = `{output_folder}/brainstorming/brainstorming-session-{{date}}-{{time}}.md` (evaluated once at workflow start)
+
+All steps MUST reference `{brainstorming_session_output_file}` instead of the full path pattern.
 - `context_file` = Optional context file path from workflow invocation for project-specific guidance
 - `advancedElicitationTask` = `{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml`
 

package/templates/bmad/core/workflows/party-mode/workflow.md

@@ -1,6 +1,6 @@
 ---
 name: party-mode
-description: "Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests 'party mode' only."
+description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.'
 ---
 
 # Party Mode Workflow

package/templates/bmad/tea/config.yaml

@@ -1,11 +1,15 @@
 # TEA Module Configuration
 # Generated by BMAD installer
-# Version: 6.0.2
+# Version: 6.0.4
 # Date: {install_date}
 
 test_artifacts: "{project-root}/{output_folder}/test-artifacts"
 tea_use_playwright_utils: true
+tea_use_pactjs_utils: true
+tea_pact_mcp: mcp
 tea_browser_automation: auto
+tea_execution_mode: auto
+tea_capability_probe: true
 test_stack_type: auto
 ci_platform: auto
 test_framework: auto

package/templates/bmad/tea/testarch/knowledge/contract-testing.md

@@ -4,10 +4,14 @@
 
 Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
 
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
 ## Rationale
 
 Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
 
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
 ## Pattern Examples
 
 ### Example 1: Pact Consumer Test (Frontend → Backend API)
@@ -164,7 +168,7 @@ describe('User API Contract', () => {
 {
   "scripts": {
     "test:contract": "jest tests/contract --testTimeout=30000",
-    "pact:publish": "pact-broker publish ./pacts --consumer-app-version=$GIT_SHA --broker-base-url=$PACT_BROKER_URL --broker-token=$PACT_BROKER_TOKEN"
+    "pact:publish": "pact-broker publish ./pacts --consumer-app-version=$GITHUB_SHA --broker-base-url=$PACT_BROKER_BASE_URL --broker-token=$PACT_BROKER_TOKEN"
   }
 }
 ```
@@ -954,4 +958,22 @@ Before implementing contract testing, verify:
 - Related fragments: `test-levels-framework.md`, `ci-burn-in.md`
 - Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
 
-_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation_
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                     | Pact.js Utils Equivalent                                                          | Benefit                                                |
+| ------------------------------------------------ | --------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Manual `JsonMap` casting for `.given()` params   | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects |
+| 30+ lines of `VerifierOptions` assembly          | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection         |
+| Manual broker URL + selector logic from env vars | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors |
+| DIY Express middleware for auth injection        | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs     |
+| Manual CI branch/tag extraction                  | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)             |
+| Message verifier config assembly                 | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts        |
+| Inline no-op filter `(req, res, next) => next()` | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers           |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_

package/templates/bmad/tea/testarch/knowledge/pact-mcp.md

@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = global)
+claude mcp add-json -s user smartbear \
+  '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "<your-api-token>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_