bmad-method-test-architecture-enterprise 1.2.5 → 1.3.0

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/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/how-to/customization/configure-browser-automation.md#related) for contract testing workflows. See the [pact-mcp knowledge fragment](../../src/testarch/knowledge/pact-mcp.md) 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:** `false`
+
+**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:** `"none"`
+
+**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'
 ```
 
 ---

package/docs/reference/knowledge-base.md

@@ -1,11 +1,11 @@
 ---
 title: 'TEA Knowledge Base Index'
-description: Complete index of TEA's 35 knowledge fragments for context engineering
+description: Complete index of TEA's 40 knowledge fragments for context engineering
 ---
 
 # TEA Knowledge Base Index
 
-TEA uses 35 specialized knowledge fragments for context engineering. These fragments are loaded dynamically based on workflow needs via the `tea-index.csv` manifest.
+TEA uses 40 specialized knowledge fragments for context engineering. These fragments are loaded dynamically based on workflow needs via the `tea-index.csv` manifest.
 
 ## What is Context Engineering?
 
@@ -158,20 +158,36 @@ Selector resilience, race condition debugging, and visual debugging.
 
 ---
 
-### Feature Flags & Testing Patterns
+### Feature Flags & API Patterns
 
-Feature flag testing, contract testing, and API testing patterns.
+Feature flag testing and pure API testing patterns.
 
 | Fragment                                                                                                                                                   | Description                                             | Key Topics                   |
 | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | ---------------------------- |
 | [feature-flags](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/feature-flags.md)               | Enum management, targeting helpers, cleanup, checklists | Feature flags, toggles       |
-| [contract-testing](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/contract-testing.md)         | Pact publishing, provider verification, resilience      | Contract testing, Pact       |
 | [api-testing-patterns](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/api-testing-patterns.md) | Pure API patterns without browser                       | API testing, backend testing |
 
 **Used in:** `test-design`, `atdd`, `automate`
 
 ---
 
+### Pact & Contract Testing Integration
+
+Contract testing fundamentals plus Pact.js Utils and Pact MCP integrations.
+
+| Fragment                                                                                                                                                                       | Description                                                                      | Key Topics                                     |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | ---------------------------------------------- |
+| [contract-testing](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/contract-testing.md)                             | Raw Pact patterns, publishing, verification, resilience                          | Contract testing, Pact fundamentals            |
+| [pactjs-utils-overview](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-overview.md)                   | Installation, flow decision tree, utility map                                    | pactjs-utils, CDCT/BDCT, integration strategy  |
+| [pactjs-utils-consumer-helpers](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-consumer-helpers.md)   | `createProviderState`, `toJsonMap` for consumer-side provider states             | pactjs-utils, consumer testing, provider state |
+| [pactjs-utils-provider-verifier](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-provider-verifier.md) | `buildVerifierOptions`, `buildMessageVerifierOptions`, broker selectors, tagging | pactjs-utils, provider verification, CI        |
+| [pactjs-utils-request-filter](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pactjs-utils-request-filter.md)       | `createRequestFilter`, `noOpRequestFilter` auth/header patterns                  | pactjs-utils, request filter, auth injection   |
+| [pact-mcp](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/testarch/knowledge/pact-mcp.md)                                             | SmartBear MCP tools for provider states, review, can-i-deploy, matrix            | pact-mcp, broker interaction, pactflow         |
+
+**Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci` (conditioned by `tea_use_pactjs_utils` and `tea_pact_mcp`)
+
+---
+
 ### Browser Automation
 
 CLI and MCP integration for AI-driven browser automation during test generation.
@@ -239,7 +255,7 @@ Fragments are loaded based on workflow needs and tier priority:
 - **Extended tier**: Loaded when the workflow context requires them (e.g., `auth-session.md` when tests involve authentication)
 - **Specialized tier**: Only loaded when the specific use case matches (e.g., contract-testing for microservices, email-auth for email flows)
 
-**Fragment Location:** `src/testarch/knowledge/` (all 35 fragments in single directory)
+**Fragment Location:** `src/testarch/knowledge/` (all 40 fragments in a single directory)
 
 **Manifest:** `src/testarch/tea-index.csv`
 

package/docs/reference/troubleshooting.md

@@ -289,14 +289,14 @@ If the BMAD installer can run but cannot fetch the Test Architect module from Gi
 
    ```bash
    cat _bmad/tea/testarch/tea-index.csv | wc -l
-   # Should show 36 lines (header + 35 fragments)
+   # Should show 41 lines (header + 40 fragments)
    ```
 
 2. Check knowledge fragment files:
 
    ```bash
    ls -la _bmad/tea/testarch/knowledge/ | wc -l
-   # Should show 35+ files
+   # Should show 40+ files
    ```
 
 3. Validate CSV format:
@@ -543,6 +543,8 @@ If the BMAD installer can run but cannot fetch the Test Architect module from Gi
    }
    ```
 
+   See [Configure Browser Automation — MCP Setup](/docs/how-to/customization/configure-browser-automation.md#for-mcp-mcp-or-auto-mode) for the exact config file path for your tool (Claude Code, Codex, Gemini CLI, Cursor, Windsurf).
+
 3. Check variable setting:
 
    ```bash
@@ -591,7 +593,7 @@ If the BMAD installer can run but cannot fetch the Test Architect module from Gi
 
 **Causes**:
 
-- All 35 fragments loading at once
+- All 40 fragments loading at once
 - Large fragment file sizes
 - Disk I/O bottleneck
 
@@ -669,7 +671,7 @@ Check these first:
 - [ ] TEA is installed: `ls -la _bmad/tea/`
 - [ ] Using correct command namespace: `/bmad:tea:*` not `/bmad:bmm:tea:*`
 - [ ] Module.yaml exists and is valid
-- [ ] Knowledge base files present (35 fragments)
+- [ ] Knowledge base files present (40 fragments)
 - [ ] Output directory exists and is writable
 - [ ] No disk space issues: `df -h`
 - [ ] Node version >=20.0.0: `node --version`
@@ -733,11 +735,11 @@ done
 
 # Check knowledge base
 fragment_count=$(ls _bmad/tea/testarch/knowledge/*.md 2>/dev/null | wc -l)
-echo "Knowledge fragments: $fragment_count (expected: 35)"
+echo "Knowledge fragments: $fragment_count (expected: 40)"
 
 # Check tea-index.csv
 csv_lines=$(wc -l < _bmad/tea/testarch/tea-index.csv 2>/dev/null || echo "0")
-echo "TEA index lines: $csv_lines (expected: 36)"
+echo "TEA index lines: $csv_lines (expected: 41)"
 
 echo "Validation complete!"
 ```

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.2.5",
+  "version": "1.3.0",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",

package/release_notes.md

@@ -1,14 +1,10 @@
-## 🚀 What's New in v1.2.5
+## 🚀 What's New in v1.3.0
 
 ### ✨ New Features
-- feat: add gemini support
-
-### 🐛 Bug Fixes
-- fix: addressed PR comment
-- fix: addressed PR comment 2
+- feat: pactjs utils support
 
 ### 📦 Other Changes
-- Merge pull request #39 from bmad-code-org/feat/gemini-support
+- Merge pull request #41 from bmad-code-org/feat/pactjs-utils-support
 
 
 ## 📦 Installation
@@ -18,4 +14,4 @@ npx bmad-method install
 # Select "Test Architect" from module menu
 ```
 
-**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.2.4...v1.2.5
+**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.2.6...v1.3.0