ma-agents 2.19.2 → 2.20.1

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-automate/steps-c/step-01-preflight-and-context.md

@@ -0,0 +1,237 @@
+---
+name: 'step-01-preflight-and-context'
+description: 'Determine mode, verify framework, and load context and knowledge'
+outputFile: '{test_artifacts}/automation-summary.md'
+nextStepFile: './step-02-identify-targets.md'
+knowledgeIndex: '{project-root}/_bmad/tea/testarch/tea-index.csv'
+---
+
+# Step 1: Preflight & Context Loading
+
+## STEP GOAL
+
+Determine execution mode, verify framework readiness, and load the necessary artifacts and knowledge fragments.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- 🚫 Halt if framework scaffolding is missing
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, loaded artifacts, and knowledge fragments
+- Focus: this step's goal only
+- Limits: do not execute future steps
+- Dependencies: prior steps' outputs (if any)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+## 1. Stack Detection & Verify Framework
+
+**Read `config.test_stack_type`** from `{config_source}`.
+
+**Auto-Detection Algorithm** (when `test_stack_type` is `"auto"` or not configured):
+
+- Scan `{project-root}` for project manifests:
+  - **Frontend indicators**: `package.json` with react/vue/angular/next dependencies, `playwright.config.*`, `vite.config.*`, `webpack.config.*`
+  - **Backend indicators**: `pyproject.toml`, `pom.xml`/`build.gradle`, `go.mod`, `*.csproj`/`*.sln`, `Gemfile`, `Cargo.toml`
+  - **Both present** = `fullstack`; only frontend = `frontend`; only backend = `backend`
+- Explicit `test_stack_type` config value overrides auto-detection
+- **Backward compatibility**: if `test_stack_type` is not in config, treat as `"auto"` (preserves current frontend behavior for existing installs)
+
+Store result as `{detected_stack}` = `frontend` | `backend` | `fullstack`
+
+**Verify framework exists:**
+
+**If {detected_stack} is `frontend` or `fullstack`:**
+
+- `playwright.config.ts` or `cypress.config.ts`
+- `package.json` includes test dependencies
+
+**If {detected_stack} is `backend` or `fullstack`:**
+
+- Relevant test config exists (e.g., `conftest.py`, `src/test/`, `*_test.go`, `.rspec`, test project `*.csproj`)
+
+If missing: **HALT** with message "Run `framework` workflow first."
+
+---
+
+## 2. Determine Execution Mode
+
+- **BMad-Integrated** if story/tech-spec/test-design artifacts are provided or found
+- **Standalone** if only source code is available
+- If unclear, ask the user which mode to use
+
+---
+
+## 3. Load Context
+
+### BMad-Integrated (if available)
+
+- Story with acceptance criteria
+- PRD and/or tech spec
+- Test-design document (if exists)
+
+### Standalone
+
+- Skip artifacts; proceed to codebase analysis
+
+### Always Load
+
+- Test framework config
+- Existing test structure in `{test_dir}`
+- Existing tests (for coverage gaps)
+
+### Read TEA Config Flags
+
+- From `{config_source}` read `tea_use_playwright_utils`
+- From `{config_source}` read `tea_use_pactjs_utils`
+- From `{config_source}` read `tea_pact_mcp`
+- From `{config_source}` read `tea_browser_automation`
+- From `{config_source}` read `test_stack_type`
+
+---
+
+### Tiered Knowledge Loading
+
+Load fragments based on their `tier` classification in `tea-index.csv`:
+
+1. **Core tier** (always load): Foundational fragments required for this workflow
+2. **Extended tier** (load on-demand): Load when deeper analysis is needed or when the user's context requires it
+3. **Specialized tier** (load only when relevant): Load only when the specific use case matches (e.g., contract-testing only for microservices, email-auth only for email flows)
+
+> **Context Efficiency**: Loading only core fragments reduces context usage by 40-50% compared to loading all fragments.
+
+### Playwright Utils Loading Profiles
+
+**If `tea_use_playwright_utils` is enabled**, select the appropriate loading profile:
+
+- **API-only profile** (when `{detected_stack}` is `backend` or no `page.goto`/`page.locator` found in test files):
+  Load: `overview`, `api-request`, `auth-session`, `recurse` (~1,800 lines)
+
+- **Full UI+API profile** (when `{detected_stack}` is `frontend`/`fullstack` or browser tests detected):
+  Load: all Playwright Utils core fragments (~4,500 lines)
+
+**Detection**: Scan `{test_dir}` for files containing `page.goto` or `page.locator`. If none found, use API-only profile.
+
+### Pact.js Utils Loading
+
+**If `tea_use_pactjs_utils` is enabled** (and `{detected_stack}` is `backend` or `fullstack`, or microservices indicators detected):
+
+Load: `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md` (~800 lines)
+
+**If `tea_use_pactjs_utils` is disabled** but contract testing is relevant (microservices architecture detected, existing Pact config found):
+
+Load: `contract-testing.md` (~960 lines)
+
+**Detection**: Scan `{project-root}` for Pact indicators: `pact/` directory, `@pact-foundation/pact` in `package.json`, `pactUrls` in test files, `PACT_BROKER` in env files.
+
+### Pact MCP Loading
+
+**If `tea_pact_mcp` is `"mcp"`:**
+
+Load: `pact-mcp.md` (~150 lines) — enables agent to use SmartBear MCP tools for fetching provider states and generating pact tests during automation.
+
+## 4. Load Knowledge Base Fragments
+
+Use `{knowledgeIndex}` and load only what is required.
+
+**Core (always load):**
+
+- `test-levels-framework.md`
+- `test-priorities-matrix.md`
+- `data-factories.md`
+- `selective-testing.md`
+- `ci-burn-in.md`
+- `test-quality.md`
+
+**Playwright Utils (if enabled):**
+
+- `overview.md`, `api-request.md`, `network-recorder.md`, `auth-session.md`, `intercept-network-call.md`, `recurse.md`, `log.md`, `file-utils.md`, `burn-in.md`, `network-error-monitor.md`, `fixtures-composition.md`
+
+**Traditional Patterns (if Playwright Utils disabled):**
+
+- `fixture-architecture.md`
+- `network-first.md`
+
+**Pact.js Utils (if enabled):**
+
+- `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md`
+
+**Contract Testing (if pactjs-utils disabled but relevant):**
+
+- `contract-testing.md`
+
+**Pact MCP (if tea_pact_mcp is "mcp"):**
+
+- `pact-mcp.md`
+
+**Healing (if auto-heal enabled):**
+
+- `test-healing-patterns.md`
+- `selector-resilience.md`
+- `timing-debugging.md`
+
+**Playwright CLI (if tea_browser_automation is "cli" or "auto"):**
+
+- `playwright-cli.md`
+
+**MCP Patterns (if tea_browser_automation is "mcp" or "auto"):**
+
+- (existing MCP-related fragments, if any are added in future)
+
+---
+
+## 5. Confirm Inputs
+
+Summarize loaded artifacts, framework, and knowledge fragments, then proceed.
+
+---
+
+## 6. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-01-preflight-and-context']
+  lastStep: 'step-01-preflight-and-context'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-01-preflight-and-context'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-01-preflight-and-context'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section.
+
+**Update `inputDocuments`**: Set `inputDocuments` in the output template frontmatter to the list of artifact paths loaded in this step (e.g., knowledge fragments, test design documents, configuration files).
+
+Load next step: `{nextStepFile}`
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Step completed in full with required outputs
+
+### ❌ SYSTEM FAILURE:
+
+- Skipped sequence steps or missing outputs
+  **Master Rule:** Skipping steps is FORBIDDEN.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-automate/steps-c/step-01b-resume.md

@@ -0,0 +1,94 @@
+---
+name: 'step-01b-resume'
+description: 'Resume interrupted workflow from last completed step'
+outputFile: '{test_artifacts}/automation-summary.md'
+---
+
+# Step 1b: Resume Workflow
+
+## STEP GOAL
+
+Resume an interrupted workflow by loading the existing output document, displaying progress, and routing to the next incomplete step.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Output document with progress frontmatter
+- Focus: Load progress and route to next step
+- Limits: Do not re-execute completed steps
+- Dependencies: Output document must exist from a previous run
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Load Output Document
+
+Read `{outputFile}` and parse YAML frontmatter for:
+
+- `stepsCompleted` — array of completed step names
+- `lastStep` — last completed step name
+- `lastSaved` — timestamp of last save
+
+**If `{outputFile}` does not exist**, display:
+
+"⚠️ **No previous progress found.** There is no output document to resume from. Please use **[C] Create** to start a fresh workflow run."
+
+**THEN:** Halt. Do not proceed.
+
+---
+
+### 2. Display Progress Dashboard
+
+Display progress with ✅/⬜ indicators:
+
+1. ✅/⬜ Preflight & Context (step-01-preflight-and-context)
+2. ✅/⬜ Identify Targets (step-02-identify-targets)
+3. ✅/⬜ Generate Tests + Aggregate (step-03c-aggregate)
+4. ✅/⬜ Validate & Summarize (step-04-validate-and-summarize)
+
+---
+
+### 3. Route to Next Step
+
+Based on `lastStep`, load the next incomplete step:
+
+- `'step-01-preflight-and-context'` → load `./step-02-identify-targets.md`
+- `'step-02-identify-targets'` → load `./step-03-generate-tests.md`
+- `'step-03c-aggregate'` → load `./step-04-validate-and-summarize.md`
+- `'step-04-validate-and-summarize'` → **Workflow already complete.** Display: "✅ **All steps completed.** Use **[V] Validate** to review outputs or **[E] Edit** to make revisions." Then halt.
+
+**If `lastStep` does not match any value above**, display: "⚠️ **Unknown progress state** (`lastStep`: {lastStep}). Please use **[C] Create** to start fresh." Then halt.
+
+**Otherwise**, load the identified step file, read completely, and execute.
+
+The existing content in `{outputFile}` provides context from previously completed steps.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Output document loaded and parsed correctly
+- Progress dashboard displayed accurately
+- Routed to correct next step
+
+### ❌ SYSTEM FAILURE:
+
+- Not loading output document
+- Incorrect progress display
+- Routing to wrong step
+
+**Master Rule:** Resume MUST route to the exact next incomplete step. Never re-execute completed steps.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-automate/steps-c/step-02-identify-targets.md

@@ -0,0 +1,169 @@
+---
+name: 'step-02-identify-targets'
+description: 'Identify automation targets and create coverage plan'
+outputFile: '{test_artifacts}/automation-summary.md'
+nextStepFile: './step-03-generate-tests.md'
+---
+
+# Step 2: Identify Automation Targets
+
+## STEP GOAL
+
+Determine what needs to be tested and select appropriate test levels and priorities.
+
+## MANDATORY EXECUTION RULES
+
+- 📖 Read the entire step file before acting
+- ✅ Speak in `{communication_language}`
+- 🚫 Avoid duplicate coverage across test levels
+
+---
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow the MANDATORY SEQUENCE exactly
+- 💾 Record outputs before proceeding
+- 📖 Load the next step only when instructed
+
+## CONTEXT BOUNDARIES:
+
+- Available context: config, loaded artifacts, and knowledge fragments
+- Focus: this step's goal only
+- Limits: do not execute future steps
+- Dependencies: prior steps' outputs (if any)
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
+
+## 1. Determine Targets
+
+**BMad-Integrated:**
+
+- Map acceptance criteria to test scenarios
+- Check for existing ATDD outputs to avoid duplication
+- Expand coverage with edge cases and negative paths
+
+**Standalone:**
+
+- If specific target feature/files are provided, focus there
+- Otherwise auto-discover features in `{source_dir}`
+- Prioritize critical paths, integrations, and untested logic
+
+**If {detected_stack} is `frontend` or `fullstack`:**
+
+**Browser Exploration (if `tea_browser_automation` is `cli` or `auto`):**
+
+> **Fallback:** If CLI is not installed, fall back to MCP (if available) or skip browser exploration and rely on code/doc analysis.
+
+Use CLI to explore the application and identify testable pages/flows:
+
+1. `playwright-cli -s=tea-automate open <target_url>`
+2. `playwright-cli -s=tea-automate snapshot` → capture page structure and element refs
+3. Analyze snapshot output to identify testable elements and flows
+4. `playwright-cli -s=tea-automate close`
+
+> **Session Hygiene:** Always close sessions using `playwright-cli -s=tea-automate close`. Do NOT use `close-all` — it kills every session on the machine and breaks parallel execution.
+
+**If {detected_stack} is `backend` or `fullstack`:**
+
+**Source & API Analysis (no browser exploration):**
+
+- Scan source code for route handlers, controllers, service classes, and public APIs
+- Read OpenAPI/Swagger specs (`openapi.yaml`, `swagger.json`) if available
+- Identify database models, migrations, and data access patterns
+- Map service-to-service integrations and message queue consumers/producers
+- Check for existing contract tests (Pact, etc.)
+
+---
+
+**If `use_pactjs_utils` is enabled — Provider Endpoint Mapping (all stacks):**
+
+When consumer-driven contract tests will be generated, build a Provider Endpoint Map during target identification. This applies to all `{detected_stack}` values — frontend, backend, and fullstack consumers all need provider scrutiny.
+
+1. **Locate provider source and/or OpenAPI spec**: Scan workspace for provider project (from config, monorepo structure, or adjacent repositories). Also check for OpenAPI/Swagger spec files (`openapi.yaml`, `openapi.json`, `swagger.json`) — these document the provider's contract explicitly and can supplement or replace handler code analysis.
+2. **Map each consumer endpoint** to its provider counterpart:
+   - Provider file path (route handler)
+   - Route pattern (METHOD + path)
+   - Validation schema location (Joi, Zod, class-validator) or OpenAPI request schema
+   - Response type/DTO definition location or OpenAPI response schema
+   - OpenAPI spec path (if available, e.g., `server/openapi.yaml`)
+3. **Output as "Provider Endpoint Map" table** in the coverage plan:
+
+```markdown
+| Consumer Endpoint     | Provider File                     | Route                     | Validation Schema                   | Response Type   | OpenAPI Spec                                      |
+| --------------------- | --------------------------------- | ------------------------- | ----------------------------------- | --------------- | ------------------------------------------------- |
+| GET /api/v2/users/:id | server/src/routes/userHandlers.ts | GET /api/v2/users/:userId | server/src/validation/user.ts       | UserResponseDto | server/openapi.yaml#/paths/~1api~1v2~1users~1{id} |
+| POST /api/v2/users    | server/src/routes/userHandlers.ts | POST /api/v2/users        | server/src/validation/createUser.ts | UserResponseDto | server/openapi.yaml#/paths/~1api~1v2~1users       |
+```
+
+4. **If provider source not accessible**: Mark entries with `TODO — provider source not accessible` and note in coverage plan that provider scrutiny will use graceful degradation (see `contract-testing.md` Provider Scrutiny Protocol)
+
+---
+
+## 2. Choose Test Levels
+
+Use `test-levels-framework.md` to select:
+
+- **E2E** for critical user journeys
+- **API** for business logic and service contracts
+- **Component** for UI behavior
+- **Unit** for pure logic and edge cases
+
+---
+
+## 3. Assign Priorities
+
+Use `test-priorities-matrix.md`:
+
+- P0: Critical path + high risk
+- P1: Important flows + medium/high risk
+- P2: Secondary + edge cases
+- P3: Optional/rare scenarios
+
+---
+
+## 4. Coverage Plan
+
+Produce a concise coverage plan:
+
+- Targets by test level
+- Priority assignments
+- Justification for coverage scope (critical-paths/comprehensive/selective)
+
+---
+
+## 5. Save Progress
+
+**Save this step's accumulated work to `{outputFile}`.**
+
+- **If `{outputFile}` does not exist** (first save), create it with YAML frontmatter:
+
+  ```yaml
+  ---
+  stepsCompleted: ['step-02-identify-targets']
+  lastStep: 'step-02-identify-targets'
+  lastSaved: '{date}'
+  ---
+  ```
+
+  Then write this step's output below the frontmatter.
+
+- **If `{outputFile}` already exists**, update:
+  - Add `'step-02-identify-targets'` to `stepsCompleted` array (only if not already present)
+  - Set `lastStep: 'step-02-identify-targets'`
+  - Set `lastSaved: '{date}'`
+  - Append this step's output to the appropriate section.
+
+Load next step: `{nextStepFile}`
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
+
+### ✅ SUCCESS:
+
+- Step completed in full with required outputs
+
+### ❌ SYSTEM FAILURE:
+
+- Skipped sequence steps or missing outputs
+  **Master Rule:** Skipping steps is FORBIDDEN.