bmad-method-test-architecture-enterprise 1.2.6 → 1.3.1

package/README.md

@@ -21,26 +21,79 @@ TEA plugs into BMad the same way a specialist plugs into a team. It uses the sam
 
 ## Architecture & Flow
 
-BMad is a small **agent + workflow engine**:
-
-- **Agent** = expert persona (e.g., Test Architect).
-- **Workflow** = a guided sequence of step files.
-- **Step file** = one focused instruction set; outputs are written only in the steps that produce them.
-- **Knowledge base** = reusable standards and patterns loaded only when needed.
-- **Modes** = `steps-c/` (Create), `steps-e/` (Edit), `steps-v/` (Validate).
-  - This keeps the create flow separate from editing and validation, and matches BMad Builder conventions.
+BMad is a small **agent + workflow engine**. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.
+
+### Building Blocks
+
+Each workflow directory contains these files, and each has a specific job:
+
+| File              | What it does                                                                                                        | When it loads                                                             |
+| ----------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `tea.agent.yaml`  | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                                                 |
+| `workflow.yaml`   | Machine-readable metadata — config variables, required tools, tags                                                  | Second — resolves `{project-root}`, `{config_source}`, `{test_artifacts}` |
+| `workflow.md`     | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step                          | Second — presents mode choice                                             |
+| `instructions.md` | Workflow-specific rules and context (optional, supplements workflow.md)                                             | On demand                                                                 |
+| `steps-c/*.md`    | **Create** steps — primary execution, 5-9 sequential files                                                          | One at a time (just-in-time)                                              |
+| `steps-e/*.md`    | **Edit** steps — always 2 files: assess target, apply edit                                                          | One at a time                                                             |
+| `steps-v/*.md`    | **Validate** steps — always 1 file: evaluate against checklist                                                      | On demand                                                                 |
+| `checklist.md`    | Validation criteria — what "done" looks like for this workflow                                                      | Read by steps-v                                                           |
+| `*-template.md`   | Output skeleton with `{PLACEHOLDER}` vars — steps fill these in to produce the final artifact                       | Read by steps-c when generating output                                    |
+| `tea-index.csv`   | Knowledge fragment index — id, name, tags, tier (core/extended/specialized), file path                              | Read by step-01 to decide which fragments to load                         |
+| `knowledge/*.md`  | 40 reusable fragments — standards, patterns, API references (e.g., `data-factories.md`, `pactjs-utils-overview.md`) | Selectively read into context based on tier + config flags                |
 
 ```mermaid
 flowchart LR
   U[User] --> A[Agent Persona]
   A --> W[Workflow Entry: workflow.md]
   W --> S[Step Files: steps-c / steps-e / steps-v]
-  S --> K[Knowledge Fragments<br/>optional]
-  S --> T[Templates & Checklists<br/>optional]
+  S --> K[Knowledge Fragments<br/>tea-index.csv → knowledge/*.md]
+  S --> T[Templates & Checklists<br/>*-template.md, checklist.md]
   S --> O[Outputs: docs/tests/reports<br/>when a step writes output]
   O --> V[Validation: checklist + report]
 ```
 
+### How It Works at Runtime
+
+1. **Trigger** — User types `/bmad:tea:automate` (or shorthand `TA`). The agent menu in `tea.agent.yaml` maps the trigger to `automate/workflow.yaml`.
+2. **Agent loads** — `tea.agent.yaml` injects the persona (identity, principles, critical actions) into the context window.
+3. **Workflow loads** — `workflow.yaml` resolves config variables and `workflow.md` presents the mode menu (Create / Edit / Validate), then routes to the first step file.
+4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one (`nextStepFile: './step-02-...'`). The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
+5. **Knowledge injection** — Step-01 reads `tea-index.csv` and selectively loads fragments by **tier** (core = always, extended = on-demand, specialized = only when relevant) and **config flags** (e.g., `tea_use_pactjs_utils`). This is deliberate context engineering: a backend project loads ~1,800 lines of fragments; a fullstack project loads ~4,500 lines. Conditional loading cuts context usage by 40-50%.
+6. **Templates** — When a step produces output (e.g., a traceability matrix or test review report), it reads the `*-template.md` file and fills in the `{PLACEHOLDER}` values with computed results. The template provides consistent structure; the step provides the content.
+7. **Subprocess isolation** — Heavy workflows (e.g., `automate`) spawn parallel subprocesses that each run in an isolated context. Subprocesses write structured JSON to temp files. An aggregation step reads the JSON outputs — only the results enter the main context, not the full subprocess history.
+8. **Progress tracking** — Each step appends to an output file with YAML frontmatter (`stepsCompleted`, `lastStep`, `lastSaved`). Resume mode reads this frontmatter and routes to the next incomplete step.
+9. **Validation** — The `steps-v/` mode reads `checklist.md` and evaluates the workflow's output against its criteria, producing a pass/fail validation report.
+
+### Workflows vs Skills
+
+BMad workflows and Claude Code Skills solve different problems at different scales:
+
+| Capability        | Claude Code Skills          | BMad Workflows                                                               |
+| ----------------- | --------------------------- | ---------------------------------------------------------------------------- |
+| **Execution**     | Single prompt, one shot     | 5-9 sequential steps with explicit handoffs                                  |
+| **State**         | Stateless                   | YAML frontmatter tracking (`stepsCompleted`, `lastStep`) with resume         |
+| **Knowledge**     | Whatever fits in one prompt | Tiered index (40 fragments), conditional loading by config + stack detection |
+| **Context mgmt**  | Everything in one shot      | Just-in-time step loading, subprocess isolation (separate contexts)          |
+| **Output**        | Freeform                    | Templates with `{PLACEHOLDER}` vars filled by specific steps                 |
+| **Validation**    | None                        | Dedicated mode (`steps-v/`) evaluating against checklists                    |
+| **Configuration** | None                        | `module.yaml` with prompted config flags driving conditional behavior        |
+| **Modes**         | None                        | Create / Edit / Validate — three separate step chains per workflow           |
+
+The key insight is that there is **no external runtime engine** — the LLM _is_ the engine. BMad workflows are structured markdown that the LLM follows as instructions: "read this file, execute it completely, save your output, load the next file." Skills are a single tool in a toolbox; BMad workflows are a workshop with a process manual.
+
+**How workflows become commands.** When you run `npx bmad-method install`, the installer converts every workflow and agent into a Claude Code command in `.claude/commands/`. For example, `bmad-tea-testarch-automate.md` tells the LLM: "load the core workflow engine (`workflow.xml`), pass it this workflow config (`automate/workflow.yaml`), follow the instructions exactly." That single command file is the bridge — it triggers the workflow entry point; the multi-step engine takes over from there.
+
+```
+.claude/commands/                         # Generated by installer
+├── bmad-agent-tea-tea.md                 # /tea → loads agent persona + menu
+├── bmad-tea-testarch-automate.md         # /automate → loads workflow.xml + workflow.yaml
+├── bmad-tea-testarch-test-design.md      # /test-design → ...
+├── bmad-bmm-create-prd.md               # /create-prd → BMM workflow
+└── ... (61 commands total across all installed modules)
+```
+
+The BMAD-METHOD source repo also has standalone `.claude/skills/` (e.g., `bmad-os-release-module`, `bmad-os-gh-triage`) for its own maintenance workflows. External tools can register skills too (e.g., `playwright-cli install --skills`). The installer supports 10+ platforms: Claude Code, Cursor, GitHub Copilot, Codex, Gemini, Windsurf, Cline, and more.
+
 ## Install
 
 ```bash
@@ -86,6 +139,8 @@ TEA variables are defined in `src/module.yaml` and prompted during install:
 
 - `test_artifacts` — base output folder for test artifacts
 - `tea_use_playwright_utils` — enable Playwright Utils integration (boolean)
+- `tea_use_pactjs_utils` — enable Pact.js Utils integration for contract testing (boolean)
+- `tea_pact_mcp` — SmartBear MCP for PactFlow/Broker interaction: mcp, none (string)
 - `tea_browser_automation` — browser automation mode: auto, cli, mcp, none (string)
 - `test_framework` — detected or configured test framework (Playwright, Cypress, Jest, Vitest, pytest, JUnit, Go test, dotnet test, RSpec)
 - `test_stack_type` — detected or configured stack type (frontend, backend, fullstack)

package/docs/explanation/tea-overview.md

@@ -338,6 +338,16 @@ Production-ready fixtures and utilities that enhance TEA workflows.
 - Impacts: `framework`, `atdd`, `automate`, `test-review`, `ci`
 - Utilities include: api-request, auth-session, network-recorder, intercept-network-call, recurse, log, file-utils, burn-in, network-error-monitor, fixtures-composition
 
+### Pact.js Utils (`@seontechnologies/pactjs-utils`)
+
+Production-ready contract testing utilities that reduce raw Pact.js boilerplate and standardize provider verification patterns.
+
+- Install: `npm install -D @seontechnologies/pactjs-utils @pact-foundation/pact`
+- Config: `tea_use_pactjs_utils: true` (default is `true`)
+- Impacts: `framework`, `atdd`, `automate`, `test-design`, `test-review`, `ci`
+- Utilities include: createProviderState, toJsonMap, buildVerifierOptions, buildMessageVerifierOptions, createRequestFilter, noOpRequestFilter, handlePactBrokerUrlAndSelectors, getProviderVersionTags
+- Supports local monorepo flow (`pactUrls`) and remote broker flow (`PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`)
+
 ### Browser Automation (Playwright CLI + MCP)
 
 **CLI and MCP are complementary tools, not competitors.** Auto mode uses each where it shines — CLI for token-efficient stateless snapshots, MCP for rich stateful automation — while giving users full control to override when they know better.
@@ -370,6 +380,34 @@ Production-ready fixtures and utilities that enhance TEA workflows.
 
 **To disable**: set `tea_browser_automation: "none"` in config or skip both CLI and MCP installation.
 
+### Pact MCP (SmartBear MCP for PactFlow/Pact Broker)
+
+Optional MCP integration for design-time broker interaction in contract testing workflows.
+
+**Configuration** (`_bmad/tea/config.yaml`):
+
+    tea_pact_mcp: "mcp"  # mcp | none
+
+| Mode   | What happens                                                                                                        |
+| ------ | ------------------------------------------------------------------------------------------------------------------- |
+| `mcp`  | TEA can use SmartBear MCP tools for provider-state discovery, test review support, can-i-deploy, and matrix checks. |
+| `none` | TEA uses CLI/script guidance only for broker interactions.                                                          |
+
+**Setup:**
+
+- Install: `npm install -g @smartbear/mcp` (or use `npx -y @smartbear/mcp@latest`)
+- Claude Code example: `claude mcp add --transport stdio smartbear -- npx -y @smartbear/mcp@latest`
+- Required broker env vars: `PACT_BROKER_BASE_URL` and token/basic-auth credentials
+
+**Which workflows benefit:**
+
+- `test-design` — Fetch provider states and broker landscape
+- `automate` — Assist pact test generation with broker context
+- `test-review` — Review pact tests against broker-informed best practices
+- `ci` — Reference can-i-deploy and matrix checks
+
+**Note:** Pact MCP complements `pactjs-utils`. MCP helps at planning/review time; `pactjs-utils` is used in runtime test code.
+
 ---
 
 ## Complete TEA Documentation Navigation
@@ -400,6 +438,7 @@ Production-ready fixtures and utilities that enhance TEA workflows.
 
 - [Integrate Playwright Utils](/docs/how-to/customization/integrate-playwright-utils.md) - Production-ready fixtures and 9 utilities
 - [Configure Browser Automation](/docs/how-to/customization/configure-browser-automation.md) - Playwright CLI + MCP setup, auto mode
+- [TEA Configuration Reference (Pact.js Utils + Pact MCP)](/docs/reference/configuration.md#tea_use_pactjs_utils) - Contract-testing integrations and setup
 
 ### Use-Case Guides
 
@@ -416,7 +455,7 @@ Production-ready fixtures and utilities that enhance TEA workflows.
 - [Test Quality Standards](/docs/explanation/test-quality-standards.md) - Definition of Done, determinism, isolation, explicit assertions
 - [Fixture Architecture](/docs/explanation/fixture-architecture.md) - Pure function → fixture → composition pattern
 - [Network-First Patterns](/docs/explanation/network-first-patterns.md) - Intercept-before-navigate, eliminating flakiness
-- [Knowledge Base System](/docs/explanation/knowledge-base-system.md) - Context engineering with tea-index.csv, 35 fragments
+- [Knowledge Base System](/docs/explanation/knowledge-base-system.md) - Context engineering with tea-index.csv, 40 fragments
 - [Engagement Models](/docs/explanation/engagement-models.md) - TEA Lite, TEA Solo, TEA Integrated (5 models explained)
 
 ### Philosophy & Design
@@ -431,5 +470,5 @@ Production-ready fixtures and utilities that enhance TEA workflows.
 
 - [TEA Command Reference](/docs/reference/commands.md) - All 9 workflows: inputs, outputs, phases, frequency
 - [TEA Configuration Reference](/docs/reference/configuration.md) - Config options, file locations, setup examples
-- [Knowledge Base Index](/docs/reference/knowledge-base.md) - 35 fragments categorized and explained
+- [Knowledge Base Index](/docs/reference/knowledge-base.md) - 40 fragments categorized and explained
 - [Glossary - TEA Section](/docs/glossary/index.md#test-architect-tea-concepts) - 20 TEA-specific terms defined

package/docs/explanation/testing-as-engineering.md

@@ -1,9 +1,9 @@
 ---
 title: 'AI-Generated Testing: Why Most Approaches Fail'
-description: How Playwright-Utils, TEA workflows, and Playwright MCPs solve AI test quality problems
+description: How Playwright-Utils, pactjs-utils, TEA workflows, Playwright CLI, and MCPs solve AI test quality problems
 ---
 
-AI-generated tests frequently fail in production because they lack systematic quality standards. This document explains the problem and presents a solution combining three components: Playwright-Utils, TEA (Test Engineering Architect), and Playwright MCPs.
+AI-generated tests frequently fail in production because they lack systematic quality standards. This document explains the problem and presents a solution combining utility standards, TEA workflows, and automation interfaces across both UI, API and contract testing.
 
 :::note[Source]
 This article is adapted from [The Testing Meta Most Teams Have Not Caught Up To Yet](https://dev.to/muratkeremozcan/the-testing-meta-most-teams-have-not-caught-up-to-yet-5765) by Murat K Ozcan.
@@ -30,25 +30,22 @@ AI excels at generating code quickly, but testing requires precision and consist
 
 The solution combines three components that work together to enforce quality:
 
-### Playwright-Utils
+### 1. Utilities: Playwright-Utils + Pact.js Utils
 
-Bridges the gap between Cypress ergonomics and Playwright's capabilities by standardizing commonly reinvented primitives through utility functions.
+`@seontechnologies/playwright-utils` standardizes commonly reinvented testing primitives across UI, API, web, and non-web flows. `@seontechnologies/pactjs-utils` standardizes Pact.js contract-testing primitives for provider state setup, request filtering, and provider/message verifier configuration.
 
-| Utility                | Purpose                           |
-| ---------------------- | --------------------------------- |
-| api-request            | API calls with schema validation  |
-| auth-session           | Authentication handling           |
-| intercept-network-call | Network mocking and interception  |
-| recurse                | Retry logic and polling           |
-| log                    | Structured logging                |
-| network-recorder       | Record and replay network traffic |
-| burn-in                | Smart test selection for CI       |
-| network-error-monitor  | HTTP error detection              |
-| file-utils             | CSV/PDF handling                  |
+| Track              | Utility Layer                        | Purpose                                                  |
+| ------------------ | ------------------------------------ | -------------------------------------------------------- |
+| UI/API/Web/Non-web | `@seontechnologies/playwright-utils` | Reusable testing primitives and fixtures                 |
+| Contract           | `@seontechnologies/pactjs-utils`     | Reusable Pact consumer/provider helpers and verification |
 
-These utilities eliminate the need to reinvent authentication, API calls, retries, and logging for every project.
+**Playwright-Utils examples:** `api-request`, `auth-session`, `intercept-network-call`, `recurse`, `log`, `network-recorder`, `burn-in`, `network-error-monitor`, `file-utils`.
 
-### TEA (Test Architect Agent)
+**pactjs-utils examples:** `createProviderState`, `toJsonMap`, `createRequestFilter`, `noOpRequestFilter`, `buildVerifierOptions`, `buildMessageVerifierOptions`.
+
+Together, these utility libraries eliminate the need to reinvent core testing primitives across UI, API, web, non-web, and contract testing.
+
+### 2. Process: TEA (Test Architect Agent)
 
 A quality operating model packaged as eight executable workflows spanning test design, CI/CD gates, and release readiness. TEA encodes test architecture expertise into repeatable processes.
 
@@ -67,28 +64,35 @@ A quality operating model packaged as eight executable workflows spanning test d
 TEA doesn't just generate tests—it provides a complete quality operating model with workflows for planning, execution, and release gates.
 :::
 
-### Playwright MCPs
+### 3. Automation Interfaces: Playwright CLI + MCPs
+
+Automation interfaces enable real-time verification during test generation and review across browser and contract tracks:
+
+- **Playwright CLI**: token-efficient browser automation for stateless execution and fast checks in workflows.
+- **Playwright MCP**: stateful browser automation with richer context for interactive exploration and DOM validation.
+- **Pact MCP**: broker-aware contract automation for verification matrix queries, provider-state discovery, compatibility analysis, and `can-i-deploy` deployment decisions.
 
-Model Context Protocols enable real-time verification during test generation. Instead of inferring selectors and behavior from documentation, MCPs allow agents to:
+Instead of inferring behavior from documentation alone, these interfaces allow agents to:
 
-- Run flows and confirm the DOM against the accessibility tree
-- Validate network responses in real-time
-- Discover actual functionality through interactive exploration
-- Verify generated tests against live applications
+- Run browser flows and confirm the DOM against the accessibility tree
+- Validate UI/API network behavior in real-time
+- Query Pact verification matrix results across consumer/provider versions
+- Check provider states and contract compatibility before release
+- Execute `can-i-deploy` checks against target environments
 
 ## How They Work Together
 
 The three components form a quality pipeline:
 
-| Stage        | Component        | Action                                              |
-| ------------ | ---------------- | --------------------------------------------------- |
-| Standards    | Playwright-Utils | Provides production-ready patterns and utilities    |
-| Process      | TEA Workflows    | Enforces systematic test planning and review        |
-| Verification | Playwright MCPs  | Validates generated tests against live applications |
+| Stage        | Component                                  | Action                                                       |
+| ------------ | ------------------------------------------ | ------------------------------------------------------------ |
+| Standards    | Playwright-Utils + pactjs-utils            | Provides production-ready patterns for UI and contract tests |
+| Process      | TEA Workflows                              | Enforces systematic test planning and review                 |
+| Verification | Playwright CLI + Playwright MCP + Pact MCP | Validates tests and contracts against live systems           |
 
 **Before (AI-only):** 20 tests with redundant coverage, incorrect assertions, and flaky behavior.
 
-**After (Full Stack):** Risk-based selection, verified selectors, validated behavior, reviewable code.
+**After (Full Stack):** Risk-based selection, verified selectors, validated behavior, contract compatibility checks, reviewable code.
 
 ## Why This Matters
 
@@ -101,11 +105,11 @@ Traditional AI testing approaches fail because they:
 
 The three-part stack addresses each gap:
 
-| Gap             | Solution                                            |
-| --------------- | --------------------------------------------------- |
-| No standards    | Playwright-Utils provides production-ready patterns |
-| No planning     | TEA `test-design` creates risk-based test plans     |
-| No verification | Playwright MCPs validate against live applications  |
-| No review       | TEA `test-review` audits quality with scoring       |
+| Gap             | Solution                                                                 |
+| --------------- | ------------------------------------------------------------------------ |
+| No standards    | Playwright-Utils + pactjs-utils provide production-ready patterns        |
+| No planning     | TEA `test-design` creates risk-based test plans                          |
+| No verification | Playwright CLI + Playwright MCP + Pact MCP validate against live systems |
+| No review       | TEA `test-review` audits quality with scoring                            |
 
 This approach is sometimes called _context engineering_—loading domain-specific standards into AI context automatically rather than relying on prompts alone. TEA's `tea-index.csv` manifest loads relevant knowledge fragments so the AI doesn't relearn testing patterns each session.

package/docs/how-to/customization/configure-browser-automation.md

@@ -37,7 +37,7 @@ The global npm install is one-time. The skills install (`playwright-cli install
 
 ### For MCP (`mcp` or `auto` mode)
 
-Configure MCP servers in your IDE:
+Add these MCP server entries to your tool's configuration file:
 
 ```json
 {
@@ -49,12 +49,77 @@ Configure MCP servers in your IDE:
     "playwright-test": {
       "command": "npx",
       "args": ["playwright", "run-test-mcp-server"]
+    },
+    "smartbear": {
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "<your-api-token>"
+      }
     }
   }
 }
 ```
 
-See your IDE documentation for MCP server configuration.
+The `smartbear` server is optional — only needed if you use the [Pact MCP integration](/docs/reference/configuration.md#tea_pact_mcp) for contract testing workflows. See the [pact-mcp knowledge fragment](/docs/reference/knowledge-base.md#pact-contract-testing-integration) for details.
+
+#### Where to put the config
+
+| Tool        | 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`)    |
+
+#### CLI shortcuts
+
+Claude Code and Codex support adding MCP servers from the command line:
+
+```bash
+# Claude Code — Playwright
+claude mcp add playwright -- npx @playwright/mcp@latest
+claude mcp add playwright-test -- npx playwright run-test-mcp-server
+
+# Claude Code — SmartBear (Pact)
+claude mcp add smartbear --scope user \
+  -e PACT_BROKER_BASE_URL=https://{tenant}.pactflow.io \
+  -e PACT_BROKER_TOKEN=<your-token> \
+  -- npx -y @smartbear/mcp@latest
+
+# Codex — Playwright
+codex mcp add playwright -- npx @playwright/mcp@latest
+codex mcp add playwright-test -- npx playwright run-test-mcp-server
+
+# Codex — SmartBear (Pact)
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+#### Codex TOML format
+
+Codex uses TOML instead of JSON. If editing the config file manually:
+
+```toml
+[mcp_servers.playwright]
+command = "npx"
+args = ["@playwright/mcp@latest"]
+
+[mcp_servers.playwright-test]
+command = "npx"
+args = ["playwright", "run-test-mcp-server"]
+
+[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`.
 
 ## How Auto Mode Works
 

package/docs/reference/configuration.md

@@ -30,6 +30,8 @@ user_skill_level: intermediate
 output_folder: _bmad-output
 test_artifacts: _bmad-output/test-artifacts
 tea_use_playwright_utils: true
+tea_use_pactjs_utils: true
+tea_pact_mcp: 'mcp'
 tea_browser_automation: 'auto'
 ```
 
@@ -75,19 +77,18 @@ test_artifacts: docs/testing-artifacts
 
 Enable Playwright Utils integration for production-ready fixtures and utilities.
 
-**Schema Location:** `src/bmm/module.yaml:52-56`
+**Schema Location:** `src/module.yaml` (TEA module config)
 
 **User Config:** `_bmad/tea/config.yaml`
 
 **Type:** `boolean`
 
-**Default:** `false` (set via installer prompt during installation)
+**Default:** `true`
 
 **Installer Prompt:**
 
 ```
-Are you using playwright-utils (@seontechnologies/playwright-utils) in your project?
-You must install packages yourself, or use test architect's `framework` command.
+Enable Playwright Utils integration?
 ```
 
 **Purpose:** Enables TEA to:
@@ -130,6 +131,130 @@ npm install -D @seontechnologies/playwright-utils
 
 ---
 
+### tea_use_pactjs_utils
+
+Enable Pact.js Utils integration for production-ready contract testing utilities.
+
+**Schema Location:** `src/module.yaml` (TEA module config)
+
+**User Config:** `_bmad/tea/config.yaml`
+
+**Type:** `boolean`
+
+**Default:** `true`
+
+**Installer Prompt:**
+
+```
+Enable Pact.js Utils integration for contract testing?
+```
+
+**Purpose:** Enables TEA to:
+
+- Load Pact.js Utils knowledge fragments during context loading
+- Scaffold contract test structure and examples in `framework`
+- Generate contract testing guidance in `atdd` and `automate`
+- Review provider verification patterns in `test-review`
+- Add contract pipeline stage and gates in `ci`
+
+**Affects Workflows:**
+
+- `framework` - Creates pact test folders and pactjs-utils sample patterns
+- `atdd` - Loads pactjs-utils fragments for contract-aware generation context
+- `automate` - Loads pactjs-utils fragments and passes pact config to subprocesses
+- `test-design` - Loads pactjs-utils fragments for system/epic planning
+- `test-review` - Uses pactjs-utils provider/review patterns
+- `ci` - Adds contract-test stage and quality gates
+
+**Example (Enable):**
+
+```yaml
+tea_use_pactjs_utils: true
+```
+
+**Example (Disable):**
+
+```yaml
+tea_use_pactjs_utils: false
+```
+
+**Prerequisites:**
+
+```bash
+npm install -D @seontechnologies/pactjs-utils @pact-foundation/pact
+```
+
+**Related:**
+
+- [Pact.js Utils docs](https://seontechnologies.github.io/pactjs-utils/)
+- [TEA Overview - Optional Integrations](/docs/explanation/tea-overview.md#optional-integrations)
+
+---
+
+### tea_pact_mcp
+
+Pact MCP strategy for broker interaction during contract testing workflows.
+
+**Schema Location:** `src/module.yaml` (TEA module config)
+
+**User Config:** `_bmad/tea/config.yaml`
+
+**Type:** `string`
+
+**Default:** `"mcp"`
+
+**Options:** `"mcp"` | `"none"`
+
+**Installer Prompt:**
+
+```
+Enable SmartBear MCP for PactFlow/Pact Broker interaction?
+```
+
+**Purpose:** Controls whether TEA can use SmartBear MCP tools for:
+
+- Provider-state discovery in design/generation workflows
+- Pact test review assistance
+- Can-i-deploy and matrix guidance in CI workflows
+
+**Affects Workflows:**
+
+- `test-design` - Broker-aware contract context loading
+- `automate` - Broker-assisted pact generation context
+- `test-review` - MCP-assisted pact review context
+- `ci` - MCP can-i-deploy/matrix guidance references
+
+**Prerequisites:**
+
+```bash
+npm install -g @smartbear/mcp
+# or: npx -y @smartbear/mcp@latest
+```
+
+**Required broker env vars (for Pact features):**
+
+- `PACT_BROKER_BASE_URL`
+- `PACT_BROKER_TOKEN` (or username/password for basic auth)
+
+**Example (Enable MCP):**
+
+```yaml
+tea_pact_mcp: 'mcp'
+```
+
+**Example (Disable MCP):**
+
+```yaml
+tea_pact_mcp: 'none'
+```
+
+**Related:**
+
+- [Configure Browser Automation Guide](/docs/how-to/customization/configure-browser-automation.md)
+- [SmartBear MCP docs](https://developer.smartbear.com/smartbear-mcp/docs/getting-started)
+
+---
+
 ### tea_browser_automation
 
 Browser automation strategy for TEA workflows. Controls how TEA interacts with live browsers during test generation.
@@ -711,12 +836,15 @@ project_name: my-project
 user_skill_level: beginner # or intermediate/expert
 output_folder: _bmad-output
 tea_use_playwright_utils: true # Recommended
+tea_use_pactjs_utils: true # Recommended - production-ready contract testing utilities
+tea_pact_mcp: 'mcp' # Recommended - SmartBear MCP for PactFlow/Broker interaction
 tea_browser_automation: 'auto' # Recommended
 ```
 
 **Why recommended:**
 
 - Playwright Utils: Production-ready fixtures and utilities
+- Pact.js Utils: Optional contract-testing acceleration for backend/fullstack services
 - Browser automation (auto): Smart CLI/MCP selection with fallback
 - Together: The three-part stack (see [Testing as Engineering](/docs/explanation/testing-as-engineering.md))
 
@@ -724,6 +852,9 @@ tea_browser_automation: 'auto' # Recommended
 
 ```bash
 npm install -D @seontechnologies/playwright-utils
+# Optional contract-testing stack:
+# npm install -D @seontechnologies/pactjs-utils @pact-foundation/pact
+# npm install -g @smartbear/mcp
 npm install -g @playwright/cli@latest  # For CLI mode
 # Configure MCP servers in IDE (see Configure Browser Automation guide)
 ```
@@ -739,6 +870,8 @@ npm install -g @playwright/cli@latest  # For CLI mode
 project_name: my-project
 output_folder: _bmad-output
 tea_use_playwright_utils: false
+tea_use_pactjs_utils: false
+tea_pact_mcp: 'none'
 tea_browser_automation: 'none'
 ```
 
@@ -761,6 +894,8 @@ tea_browser_automation: 'none'
 project_name: monorepo
 output_folder: _bmad-output
 tea_use_playwright_utils: true
+tea_use_pactjs_utils: true
+tea_pact_mcp: 'mcp'
 ```
 
 **Package configs:**
@@ -774,6 +909,8 @@ output_folder: ../../_bmad-output/web
 project_name: api-service
 output_folder: ../../_bmad-output/api
 tea_use_playwright_utils: false  # Using vanilla Playwright only
+tea_use_pactjs_utils: true       # API service uses contract testing utilities
+tea_pact_mcp: 'mcp'              # Optional broker interaction via MCP
 ```
 
 ---
@@ -796,6 +933,8 @@ project_knowledge: docs
 
 # TEA Configuration (Recommended: Enable both for full stack)
 tea_use_playwright_utils: true # Recommended - production-ready utilities
+tea_use_pactjs_utils: true # Recommended - production-ready contract testing utilities
+tea_pact_mcp: 'mcp' # Recommended - SmartBear MCP for broker integration
 tea_browser_automation: 'auto' # Recommended - smart CLI/MCP selection
 
 # Languages
@@ -817,6 +956,12 @@ document_output_language: english
 5. (Optional) Enable playwright-utils:
    npm install -D @seontechnologies/playwright-utils
    Set tea_use_playwright_utils: true
+6. (Optional) Enable pactjs-utils:
+   npm install -D @seontechnologies/pactjs-utils @pact-foundation/pact
+   Set tea_use_pactjs_utils: true
+7. (Optional) Enable Pact MCP:
+   npm install -g @smartbear/mcp
+   Set tea_pact_mcp: 'mcp'
 ```
 
 ---