qaa-agent 1.4.0 → 1.6.0

package/.claude/commands/create-test.md

@@ -1,19 +1,22 @@
 # Create Automated Tests
 
-Generate production-ready test files with POM pattern for a specific feature or module. Reads existing QA_ANALYSIS.md and TEST_INVENTORY.md if available.
+Generate production-ready test files with POM pattern for a specific feature or module. Reads codebase map, existing analysis artifacts, and CLAUDE.md standards to produce tests that match the project's actual code patterns. If E2E tests are generated and an app URL is available, runs them against the live app and fixes locators until they pass.
 
 ## Usage
 
-/create-test <feature-name> [--dev-repo <path>]
+/create-test <feature-name> [--dev-repo <path>] [--app-url <url>] [--skip-run]
 
 - feature-name: which feature to test (e.g., "login", "checkout", "user API")
 - --dev-repo: path to developer repository (default: current directory)
+- --app-url: URL of running application for E2E test execution (auto-detects if not provided)
+- --skip-run: skip E2E execution, only generate and statically validate
 
 ## What It Produces
 
 - Test spec files (unit, API, E2E as appropriate for the feature)
 - Page Object Model files (for E2E tests)
 - Fixture files (test data)
+- E2E_RUN_REPORT.md (if E2E tests were run against live app)
 
 ## Instructions
 
@@ -21,20 +24,141 @@ Generate production-ready test files with POM pattern for a specific feature or
 2. Read existing analysis artifacts if available:
    - `.qa-output/QA_ANALYSIS.md` -- architecture context
    - `.qa-output/TEST_INVENTORY.md` -- pre-defined test cases for this feature
-3. Invoke executor agent:
+3. Read codebase map if available (check `.qa-output/codebase/`):
+   - `CODE_PATTERNS.md` -- naming conventions, import style, code patterns to match
+   - `API_CONTRACTS.md` -- request/response shapes for API tests
+   - `TEST_SURFACE.md` -- function signatures and testable entry points
+   - `TESTABILITY.md` -- pure functions vs stateful code, mock boundaries
+   If codebase map does not exist, run `/qa-map` first for best results, or proceed without it.
+
+4. **Check existing locator registry and extract new locators from live app:**
+
+   a. **Check the locator registry first.** Read `.qa-output/locators/LOCATOR_REGISTRY.md` if it exists. This is the accumulated registry of all locators previously extracted from the live app. Check if locators for this feature's pages already exist.
+
+   b. **If locators for this feature's pages are already in the registry AND no `--app-url` was provided:** Skip browser extraction -- reuse existing locators. Print: `"Reusing cached locators for {feature} from registry."`
+
+   c. **If locators are missing or `--app-url` was provided:** Use the Playwright MCP to navigate the app and extract real locators BEFORE generating tests.
+
+   **Browser extraction process:**
+
+   1. Navigate to the feature's relevant pages:
+      ```
+      mcp__playwright__browser_navigate({ url: "{app_url}/{feature_path}" })
+      ```
+
+   2. Take an accessibility snapshot of each page to discover all interactive elements:
+      ```
+      mcp__playwright__browser_snapshot()
+      ```
+
+   3. Extract real locators from the snapshot -- collect:
+      - All `data-testid` attributes present on the page
+      - ARIA roles with accessible names (buttons, inputs, links, etc.)
+      - Form labels and placeholders
+      - Navigation structure and page layout
+
+   4. If the feature has multiple pages/views (e.g., login -> dashboard), navigate through the flow:
+      ```
+      mcp__playwright__browser_fill_form({ ... })
+      mcp__playwright__browser_click({ element: "..." })
+      mcp__playwright__browser_snapshot()  // capture next page
+      ```
+
+   5. Write per-feature locator file to `.qa-output/locators/{feature}.locators.md`:
+      ```markdown
+      # Locators -- {feature}
+
+      Extracted: {date}
+      App URL: {app_url}
+
+      ## Page: {page_name} ({url})
+
+      | Element | Locator Type | Locator Value | Tier |
+      |---------|-------------|---------------|------|
+      | Email input | data-testid | login-email-input | 1 |
+      | Password input | data-testid | login-password-input | 1 |
+      | Submit button | role + name | button "Log in" | 1 |
+      | Remember me | label | "Remember me" | 2 |
+
+      ## Page: {next_page} ({url})
+      ...
+      ```
+
+   6. Update the registry `.qa-output/locators/LOCATOR_REGISTRY.md` -- merge new locators into the central index:
+      ```markdown
+      # Locator Registry
+
+      Last updated: {date}
+      Total pages: {N}
+      Total locators: {N}
+
+      ## Index
+
+      | Feature | File | Pages | Locators | Extracted |
+      |---------|------|-------|----------|-----------|
+      | login | login.locators.md | 2 | 14 | 2026-03-25 |
+      | checkout | checkout.locators.md | 3 | 22 | 2026-03-25 |
+      | dashboard | dashboard.locators.md | 1 | 8 | 2026-03-25 |
+
+      ## All Locators by Page
+
+      ### /login
+      | Element | Locator Type | Locator Value | Tier | Source |
+      |---------|-------------|---------------|------|--------|
+      | Email input | data-testid | login-email-input | 1 | login.locators.md |
+      | ... | ... | ... | ... | ... |
+
+      ### /dashboard
+      ...
+      ```
+
+   If no app URL is available and no locators exist in the registry for this feature, skip this step -- the executor will propose locators based on source code analysis and CLAUDE.md conventions.
+
+5. Invoke executor agent to generate test files:
 
 Task(
   prompt="
-    <objective>Generate test files for the specified feature following CLAUDE.md standards</objective>
+    <objective>Generate test files for the specified feature following CLAUDE.md standards, using codebase map for context</objective>
     <execution_context>@agents/qaa-executor.md</execution_context>
     <files_to_read>
     - CLAUDE.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists -- accumulated real locators)
+    - .qa-output/locators/{feature}.locators.md (if exists -- feature-specific locators)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
+    - .qa-output/codebase/API_CONTRACTS.md (if exists)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists)
+    - .qa-output/codebase/TESTABILITY.md (if exists)
     </files_to_read>
     <parameters>
     user_input: $ARGUMENTS
     mode: feature-test
+    codebase_map_dir: .qa-output/codebase
+    locator_registry: .qa-output/locators/LOCATOR_REGISTRY.md
     </parameters>
   "
 )
 
+6. If E2E test files were generated AND `--skip-run` was NOT passed, invoke the E2E runner to execute tests against the live app:
+
+Task(
+  prompt="
+    <objective>Run generated E2E tests against live application, capture real locators, fix mismatches, loop until pass</objective>
+    <execution_context>@agents/qaa-e2e-runner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - {generated E2E test files from executor return}
+    - {generated POM files from executor return}
+    </files_to_read>
+    <parameters>
+    app_url: {from --app-url flag or auto-detect}
+    output_dir: .qa-output
+    </parameters>
+  "
+)
+
+7. Present results:
+   - List generated files with type counts (unit, API, E2E, POM, fixture)
+   - If E2E runner executed: show pass/fail counts, locator fixes applied, app bugs found
+   - Suggest `/qa-pr` to package as a pull request
+
 $ARGUMENTS

package/.claude/commands/qa-from-ticket.md

@@ -1,16 +1,17 @@
 # Create Tests from Ticket
 
-Generate test cases and executable test files from a ticket (Jira, Linear, GitHub Issue, or plain text user story). Combines the ticket's acceptance criteria with actual source code analysis to produce targeted, concrete tests.
+Generate test cases and executable test files from a ticket (Jira, Linear, GitHub Issue, or plain text user story). Combines the ticket's acceptance criteria with actual source code analysis to produce targeted, concrete tests. If an app URL is available, navigates the live app with Playwright MCP to extract real locators before generating tests.
 
 ## Usage
 
-/qa-from-ticket <ticket-source> [--dev-repo <path>]
+/qa-from-ticket <ticket-source> [--dev-repo <path>] [--app-url <url>]
 
 - ticket-source: one of:
   - URL to GitHub/Jira/Linear issue
   - Plain text user story or acceptance criteria
   - File path to a .md or .txt with ticket details
 - --dev-repo: path to developer repository (default: current directory)
+- --app-url: URL of running application for browser-based locator extraction (auto-detects if not provided)
 
 ## Instructions
 

package/.claude/commands/qa-map.md

@@ -1,21 +1,30 @@
-# QA Codebase Map
+# QA Codebase Map & Analysis
 
-Deep-scan a codebase for QA-relevant information. Spawns 4 parallel mapper agents that analyze testability, risk areas, code patterns, and existing tests. Produces structured documents consumed by the QA pipeline.
+Deep-scan a codebase for QA-relevant information and produce a complete analysis. Runs codebase mapping (4 parallel agents) followed by repository analysis. One command to fully understand a codebase before writing tests.
 
 ## Usage
 
-/qa-map [--focus <area>]
+/qa-map [--focus <area>] [--dev-repo <path>] [--qa-repo <path>]
 
-- No arguments: runs all 4 focus areas in parallel
-- --focus: run a single area (testability, risk, patterns, existing-tests)
+- No arguments: runs full map + analysis on current directory
+- --focus: run a single map area only, skip analysis (testability, risk, patterns, existing-tests)
+- --dev-repo: explicit path to developer repository
+- --qa-repo: path to existing QA repository (produces gap analysis instead of blueprint)
 
 ## What It Produces
 
+### Stage 1: Codebase Map (4 parallel agents)
 - TESTABILITY.md + TEST_SURFACE.md — what's testable, entry points, mocking needs
 - RISK_MAP.md + CRITICAL_PATHS.md — business-critical paths, error handling gaps
 - CODE_PATTERNS.md + API_CONTRACTS.md — naming conventions, API shapes, auth patterns
 - TEST_ASSESSMENT.md + COVERAGE_GAPS.md — existing test quality, what's missing
 
+### Stage 2: Repository Analysis
+- SCAN_MANIFEST.md — file tree, framework detection, testable surfaces
+- QA_ANALYSIS.md — architecture overview, risk assessment, top 10 unit targets, testing pyramid
+- TEST_INVENTORY.md — every test case with ID, target, inputs, expected outcome, priority
+- QA_REPO_BLUEPRINT.md (no QA repo) or GAP_ANALYSIS.md (QA repo provided)
+
 ## Instructions
 
 1. Read `CLAUDE.md` — QA standards.
@@ -30,7 +39,9 @@ Agent(
   execution_context="@agents/qaa-codebase-mapper.md"
 )
 
-4. If --focus flag, spawn only that one area.
-5. When all complete, print summary of documents produced.
+4. If --focus flag, spawn only that one area and stop (skip analysis stage).
+5. When all map agents complete, print summary of codebase documents produced.
+6. Run the analysis stage — execute the workflow defined in `@workflows/qa-analyze.md` end-to-end. Pass --dev-repo and --qa-repo arguments if provided. Preserve all workflow gates (scan verification, artifact checks).
+7. Print final summary: all documents produced across both stages.
 
 $ARGUMENTS

package/.claude/commands/qa-pr.md

@@ -0,0 +1,23 @@
+# Create QA Pull Request
+
+Create a draft PR from QA artifacts already on disk. Auto-detects git platform (GitHub, Azure DevOps, GitLab), applies your team's branch naming convention, and creates a draft PR with a summary. Asks for your branch pattern the first time and remembers it.
+
+## Usage
+
+/qa-pr [--ticket <id>] [--title <description>] [--scope <type>] [--files <glob>] [--base <branch>]
+
+- --ticket: ticket/issue ID for branch name (e.g., PROJ-123)
+- --title: short description for branch and PR title (e.g., "login tests")
+- --scope: limit to file type: unit, api, e2e, all (default: all)
+- --files: explicit file glob to include (e.g., "tests/unit/auth*")
+- --base: target branch for PR (default: auto-detect)
+
+## Instructions
+
+1. Read `CLAUDE.md` -- git workflow, commit conventions.
+2. Execute the workflow:
+
+Follow the workflow defined in `@workflows/qa-pr.md` end-to-end.
+Preserve all workflow gates (platform detection, user confirmation before push, branch convention save).
+
+$ARGUMENTS

package/.claude/commands/qa-validate.md

@@ -1,20 +1,42 @@
 # QA Test Validation
 
-Validate existing test files against CLAUDE.md standards. Runs 4-layer validation (syntax, structure, dependencies, logic) and classifies any failures found.
+Validate existing test files against CLAUDE.md standards. Runs 4-layer static validation (syntax, structure, dependencies, logic) and optionally executes E2E tests against a live app to verify locators and assertions with real page data.
 
 ## Usage
 
-/qa-validate [<test-directory>] [--classify]
+/qa-validate [<test-directory>] [--classify] [--run --app-url <url>]
 
 - test-directory: path to test files (auto-detects if omitted)
 - --classify: also run bug-detective to classify failures
+- --run: execute E2E tests against a live application after static validation
+- --app-url: URL of running application (auto-detects if not provided)
 
 ## Instructions
 
 1. Read `CLAUDE.md` -- quality gates, locator tiers, assertion rules.
-2. Execute the workflow:
+2. Execute the static validation workflow:
 
 Follow the workflow defined in `@workflows/qa-validate.md` end-to-end.
 Preserve all workflow gates (fix loops, classification).
 
+3. If `--run` flag is present and E2E test files exist in the validated directory, invoke the E2E runner:
+
+Task(
+  prompt="
+    <objective>Run E2E tests against live application, capture real locators, fix mismatches, loop until pass</objective>
+    <execution_context>@agents/qaa-e2e-runner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - {E2E test files from validated directory}
+    - {POM files from validated directory}
+    </files_to_read>
+    <parameters>
+    app_url: {from --app-url flag or auto-detect}
+    output_dir: .qa-output
+    </parameters>
+  "
+)
+
+4. Present combined results: static validation + E2E execution (if ran).
+
 $ARGUMENTS

package/.claude/settings.json

@@ -10,7 +10,8 @@
       "Agent",
       "WebFetch",
       "WebSearch",
-      "NotebookEdit"
+      "NotebookEdit",
+      "mcp__playwright__*"
     ]
   },
   "env": {

package/.claude/skills/qa-learner/SKILL.md

@@ -132,6 +132,14 @@ The preference file is the user's personal override layer on top of the project'
 **Extract:** Naming rule — test ID at start of name
 **Save:** `## Naming\n- Test ID must appear at the beginning of the test name (e.g., "UT-AUTH-001: should validate email format") — (added 2026-03-24, context: "user wants ID at start of test name")`
 
+**User says:** "Las branches tienen que ser feature/{ticket}-{description}"
+**Extract:** Workflow rule — branch naming convention
+**Save:** `## Workflow\n- Branch naming convention: feature/{ticket}-{description} — (added 2026-03-24, context: "user configured branch pattern for /qa-pr")`
+
+**User says:** "Nuestras ramas siempre empiezan con test/ y el ticket de Jira"
+**Extract:** Workflow rule — branch naming convention
+**Save:** `## Workflow\n- Branch naming convention: test/{ticket}-{description} — (added 2026-03-24, context: "user specified branch pattern with Jira ticket prefix")`
+
 ## Important Rules
 
 1. **NEVER push MY_PREFERENCES.md to any repo** — it's personal

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+
+# Changelog
+
+All notable changes to QAA (QA Automation Agent) are documented here.
+
+## [1.6.0] - 2026-03-25
+
+### Added
+- Playwright MCP server bundled in agent package (`.mcp.json`) -- starts automatically when opening project in Claude Code
+- Persistent locator registry at `.qa-output/locators/` -- accumulates real locators across features over time
+  - Per-feature files: `{feature}.locators.md` -- extracted locators for each feature tested
+  - Central index: `LOCATOR_REGISTRY.md` -- all locators by page, searchable by any command
+- Browser-based locator extraction step in `/create-test` and `/qa-from-ticket` -- navigates live app with Playwright MCP and captures real data-testid, ARIA roles, and labels before generating tests
+- Registry cache: if locators for a feature already exist in the registry, browser extraction is skipped (reuses cached locators)
+- `--app-url` flag added to `/qa-from-ticket`
+- CHANGELOG.md
+
+### Changed
+- `qaa-executor` now reads locator registry (when available) to use real locators in POMs instead of proposing them
+- `/create-test` flow: checks registry first, then extracts via browser if needed, BEFORE test generation
+- `/qa-from-ticket` workflow: locator extraction step added after source scan, before test case generation
+
+### Removed
+- `/qa-analyze` command (deprecated since v1.4.0, fully replaced by `/qa-map`)
+
+## [1.5.0] - 2026-03-24
+
+### Added
+- Stable release
+
+## [1.4.0]
+
+### Changed
+- Merged `/qa-analyze` into `/qa-map` -- single command for codebase scanning and analysis
+- Consolidated pipeline flow
+
+### Deprecated
+- `/qa-analyze` command (use `/qa-map` instead)
+
+## [1.3.0]
+
+### Added
+- `qa-learner` skill -- persistent preferences from user corrections
+- Preferences saved to `~/.claude/qaa/MY_PREFERENCES.md`
+- Trigger detection for English and Spanish frustration signals
+
+## [1.2.0]
+
+### Added
+- `qaa-codebase-mapper` agent -- 4 parallel focus areas (testability, risk, patterns, existing tests)
+- `qaa-project-researcher` agent -- researches best testing stack and practices
+- 8 codebase map documents produced by mapper
+
+## [1.1.0]
+
+### Added
+- Workflow definitions for all pipeline stages
+- Interactive installer (`npx qaa-agent`)
+- `qaa init` command for per-project initialization
+- npm package distribution
+
+## [1.0.0]
+
+### Added
+- Full QA automation pipeline -- 11 agents, 17 commands, 10 templates, 7 workflows
+- 3 workflow options (dev-only, immature QA, mature QA)
+- 4-layer test validation (syntax, structure, dependencies, logic)
+- Page Object Model generation with CLAUDE.md standards
+- Test ID injection for frontend components
+- Bug detective failure classification
+- Draft PR delivery with branch naming convention

package/CLAUDE.md

@@ -197,7 +197,7 @@ The QA automation system runs agents in a defined pipeline. Each stage produces
 ### Pipeline Stages
 
 ```
-scan -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> deliver
+scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
 ```
 
 ### Workflow Options
@@ -205,9 +205,9 @@ scan -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -
 **Option 1: Dev-Only Repo (no existing QA repo)**
 Full pipeline from scratch:
 ```
-scan -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> deliver
+scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
 ```
-Produces: SCAN_MANIFEST.md -> QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md -> [TESTID_AUDIT_REPORT.md] -> generation plan -> test files + POMs + fixtures + configs -> VALIDATION_REPORT.md -> branch + PR
+Produces: SCAN_MANIFEST.md -> 8 codebase map documents -> QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md -> [TESTID_AUDIT_REPORT.md] -> generation plan -> test files + POMs + fixtures + configs -> VALIDATION_REPORT.md -> [E2E_RUN_REPORT.md] -> branch + PR
 
 **Option 2: Dev + Immature QA Repo (existing QA repo with low coverage or quality)**
 Gap-fill and standardize:
@@ -227,13 +227,18 @@ Produces: SCAN_MANIFEST.md (both repos) -> GAP_ANALYSIS.md (thin areas only) ->
 
 | From | To | Condition |
 |------|----|-----------|
-| scan | analyze | SCAN_MANIFEST.md exists with > 0 testable surfaces |
+| scan | codebase-map | SCAN_MANIFEST.md exists with > 0 testable surfaces |
+| codebase-map | analyze | At least 4 of 8 codebase map documents exist |
 | analyze | testid-inject | QA_ANALYSIS.md exists AND frontend components detected |
 | analyze | plan | QA_ANALYSIS.md + TEST_INVENTORY.md exist (skip testid-inject if no frontend) |
 | testid-inject | plan | TESTID_AUDIT_REPORT.md exists with coverage score calculated |
 | plan | generate | Generation plan approved (or auto-approved in auto-advance mode) |
 | generate | validate | All planned test files exist on disk |
-| validate | deliver | VALIDATION_REPORT.md shows PASS or max fix loops (3) exhausted |
+| validate | e2e-runner | VALIDATION_REPORT.md shows PASS AND E2E test files were generated AND live app available |
+| validate | deliver | VALIDATION_REPORT.md shows PASS and no E2E files or --skip-run |
+| e2e-runner | bug-detective | E2E_RUN_REPORT.md exists AND failures need classification |
+| e2e-runner | deliver | E2E_RUN_REPORT.md exists AND all tests pass or failures classified |
+| bug-detective | deliver | FAILURE_CLASSIFICATION_REPORT.md exists |
 
 ---
 
@@ -244,12 +249,15 @@ Each agent owns specific artifacts. No agent may produce artifacts assigned to a
 | Agent | Reads | Produces | Template |
 |-------|-------|----------|----------|
 | qa-scanner | repo source files, package.json, file tree | SCAN_MANIFEST.md | templates/scan-manifest.md |
-| qa-analyzer | SCAN_MANIFEST.md, CLAUDE.md | QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md (Option 1) or GAP_ANALYSIS.md (Option 2/3) | templates/qa-analysis.md, templates/test-inventory.md, templates/qa-repo-blueprint.md, templates/gap-analysis.md |
-| qa-planner | TEST_INVENTORY.md, QA_ANALYSIS.md | Generation plan (internal) | -- |
-| qa-executor | TEST_INVENTORY.md, CLAUDE.md | test files, POMs, fixtures, configs | qa-template-engine patterns |
+| qa-codebase-mapper | SCAN_MANIFEST.md, repo source files, CLAUDE.md | TESTABILITY.md, TEST_SURFACE.md, RISK_MAP.md, CRITICAL_PATHS.md, CODE_PATTERNS.md, API_CONTRACTS.md, TEST_ASSESSMENT.md, COVERAGE_GAPS.md | -- |
+| qa-analyzer | SCAN_MANIFEST.md, codebase map documents, CLAUDE.md | QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md (Option 1) or GAP_ANALYSIS.md (Option 2/3) | templates/qa-analysis.md, templates/test-inventory.md, templates/qa-repo-blueprint.md, templates/gap-analysis.md |
+| qa-planner | TEST_INVENTORY.md, QA_ANALYSIS.md, codebase map documents | Generation plan (internal) | -- |
+| qa-executor | TEST_INVENTORY.md, codebase map documents, CLAUDE.md | test files, POMs, fixtures, configs | qa-template-engine patterns |
 | qa-validator | generated test files, CLAUDE.md | VALIDATION_REPORT.md (validation mode) or QA_AUDIT_REPORT.md (audit mode) | templates/validation-report.md, templates/qa-audit-report.md |
+| qa-e2e-runner | generated E2E test files, POM files, CLAUDE.md, live application | E2E_RUN_REPORT.md, fixed test/POM files with real locators | -- |
 | qa-testid-injector | repo source files, SCAN_MANIFEST.md, CLAUDE.md | TESTID_AUDIT_REPORT.md, modified source files with data-testid attributes | templates/scan-manifest.md, templates/testid-audit-report.md |
 | qa-bug-detective | test execution results, test source files, CLAUDE.md | FAILURE_CLASSIFICATION_REPORT.md | templates/failure-classification.md |
+| qa-project-researcher | SCAN_MANIFEST.md, repo source files | TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md | -- |
 
 **Rule:** An agent MUST NOT produce artifacts assigned to another agent.
 
@@ -390,11 +398,13 @@ Each agent operates on the same branch. No worktree splits are needed for this s
 
 Respect stage transitions from the Agent Pipeline section:
 1. qa-scanner runs first (no dependencies)
-2. qa-analyzer and qa-testid-injector run after scanner (both depend on SCAN_MANIFEST.md)
-3. qa-planner runs after analyzer (depends on QA_ANALYSIS.md + TEST_INVENTORY.md)
-4. qa-executor runs after planner (depends on generation plan)
-5. qa-validator runs after executor (depends on generated test files)
-6. qa-bug-detective runs after test execution (depends on test results)
+2. qa-codebase-mapper runs after scanner (depends on SCAN_MANIFEST.md, spawns 4 parallel focus agents)
+3. qa-analyzer and qa-testid-injector run after codebase-map (both depend on SCAN_MANIFEST.md + codebase map documents)
+4. qa-planner runs after analyzer (depends on QA_ANALYSIS.md + TEST_INVENTORY.md + codebase map documents)
+5. qa-executor runs after planner (depends on generation plan + codebase map documents)
+6. qa-validator runs after executor (depends on generated test files)
+7. qa-e2e-runner runs after validator (depends on E2E test files + live application)
+8. qa-bug-detective runs after e2e-runner or validator if failures (depends on test results)
 
 ### Auto-Advance Mode