qaa-agent 1.5.0 → 1.6.0

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

@@ -31,7 +31,90 @@ Generate production-ready test files with POM pattern for a specific feature or
    - `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. Invoke executor agent to generate test files:
+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="
@@ -39,6 +122,8 @@ Task(
     <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)
@@ -48,11 +133,12 @@ Task(
     user_input: $ARGUMENTS
     mode: feature-test
     codebase_map_dir: .qa-output/codebase
+    locator_registry: .qa-output/locators/LOCATOR_REGISTRY.md
     </parameters>
   "
 )
 
-5. If E2E test files were generated AND `--skip-run` was NOT passed, invoke the E2E runner to execute tests against the live app:
+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="
@@ -70,7 +156,7 @@ Task(
   "
 )
 
-6. Present results:
+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

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/settings.json

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

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/agents/qaa-executor.md

@@ -34,6 +34,17 @@ Read ALL of the following files BEFORE producing any output. The executor's code
 
 - **~/.claude/qaa/MY_PREFERENCES.md** (optional -- read if exists). User's personal QA preferences saved by the qa-learner skill. If a preference conflicts with CLAUDE.md, the preference wins (it is a user override). Check for rules about: framework choices, locator strategy, assertion style, naming conventions, language preferences.
 
+- **Locator Registry** (optional -- read if it exists):
+  - **`.qa-output/locators/LOCATOR_REGISTRY.md`** -- Central index of all locators extracted from the live app across all features. Contains locators per page with element name, locator type, value, and tier.
+  - **`.qa-output/locators/{feature}.locators.md`** -- Per-feature locator files with detailed page-by-page locator tables.
+
+  When locator registry files exist:
+  - Use the exact `data-testid` values, ARIA roles, and labels from the registry in POM locator properties
+  - Do NOT propose or guess locator values -- use what was captured from the rendered page
+  - If an element appears in the registry, its locator is authoritative (Tier 1)
+  - If an element needed by a test case is NOT in the registry, fall back to CLAUDE.md locator tier hierarchy as usual
+  - Check the feature-specific file first (`{feature}.locators.md`), then fall back to `LOCATOR_REGISTRY.md`
+
 - **Codebase map documents** (optional -- read if they exist in `{codebase_map_dir}/` or `.qa-output/codebase/`):
   - **CODE_PATTERNS.md** -- Naming conventions, import patterns, code style used in the project. Use to generate tests that feel native to the codebase (matching variable naming, import style, file organization).
   - **API_CONTRACTS.md** -- Exact request/response shapes, auth patterns, error response formats. Use for API test assertions with real payload shapes and correct auth headers.
@@ -84,7 +95,15 @@ Read all input artifacts and build the execution context.
    - Extract expected outcome rules
    - These patterns guide the code generation in step 4
 
-6. **Read codebase map documents** (if they exist -- check `{codebase_map_dir}/` or `.qa-output/codebase/`):
+6. **Read Locator Registry** (if it exists):
+   - Check for `.qa-output/locators/LOCATOR_REGISTRY.md` (central index)
+   - Check for `.qa-output/locators/{feature}.locators.md` (feature-specific, more detailed)
+   - Extract all locators per page: element name, locator type, locator value, tier
+   - Index by page name for quick lookup during POM generation
+   - When generating POM locator properties, use the exact values from the registry instead of proposing values
+   - If no locator registry exists, proceed normally -- propose locators based on CLAUDE.md conventions and source code analysis
+
+7. **Read codebase map documents** (if they exist -- check `{codebase_map_dir}/` or `.qa-output/codebase/`):
    - **CODE_PATTERNS.md** -- Extract naming conventions (variable casing, import style, file organization). Match generated test code to the project's native style.
    - **API_CONTRACTS.md** -- Extract exact request/response shapes with field types, auth header patterns, error response formats. Use for concrete API test payloads and response assertions.
    - **TEST_SURFACE.md** -- Extract function signatures with parameter types and return types. Use to write accurate import statements, mock setup, and assertion values.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.5.0",
+  "version": "1.6.0",
   "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
   "bin": {
     "qaa-agent": "./bin/install.cjs"
@@ -21,6 +21,9 @@
   },
   "author": "Backhaus7997",
   "license": "MIT",
+  "dependencies": {
+    "@playwright/mcp": "latest"
+  },
   "files": [
     "bin/",
     "agents/",
@@ -30,7 +33,9 @@
     ".claude/commands/",
     ".claude/skills/",
     ".claude/settings.json",
+    ".mcp.json",
     "CLAUDE.md",
+    "CHANGELOG.md",
     "README.md"
   ]
 }

package/workflows/qa-from-ticket.md

@@ -215,8 +215,69 @@ Generating test cases based on ticket content only (no source-level analysis).
 ```
 </step>
 
+<step name="extract_locators_from_app">
+## Step 5: Check Locator Registry and Extract from Live App (Optional)
+
+Check the locator registry for existing locators, and if needed, use Playwright MCP to extract new ones from the live app.
+
+**Step 5a: Check existing registry**
+
+Read `.qa-output/locators/LOCATOR_REGISTRY.md` if it exists. Check if locators for pages related to this ticket's feature already exist. If they do and no `--app-url` was provided, reuse them and skip browser extraction.
+
+**Step 5b: When to extract from browser**
+- Locators for this feature's pages are NOT in the registry, OR
+- An `--app-url` argument was explicitly provided (forces re-extraction)
+
+**When to skip entirely:**
+- No app URL available, no dev server detected, AND no registry exists
+- The ticket describes only backend/API functionality with no UI
+
+**Extraction process:**
+
+1. Identify relevant pages from the ticket's acceptance criteria and affected components (from Step 3 and Step 4).
+
+2. For each relevant page, navigate and capture:
+   ```
+   mcp__playwright__browser_navigate({ url: "{app_url}/{page_path}" })
+   mcp__playwright__browser_snapshot()
+   ```
+
+3. If the ticket describes a user flow (e.g., "user fills form and submits"), walk through the flow:
+   ```
+   mcp__playwright__browser_fill_form({ ... })
+   mcp__playwright__browser_click({ element: "Submit button" })
+   mcp__playwright__browser_snapshot()  // capture resulting page
+   ```
+
+4. From each snapshot, extract:
+   - All `data-testid` attributes
+   - ARIA roles with accessible names
+   - Form labels and placeholders
+   - Page structure and navigation elements
+
+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 |
+   |---------|-------------|---------------|------|
+   | ... | data-testid | ... | 1 |
+   | ... | role + name | ... | 1 |
+   | ... | label | ... | 2 |
+   ```
+
+6. Update the registry `.qa-output/locators/LOCATOR_REGISTRY.md` -- merge new locators into the central index without overwriting locators from other features.
+
+If this step is skipped entirely, the executor will propose locators based on source code analysis and CLAUDE.md conventions.
+</step>
+
 <step name="generate_test_cases">
-## Step 5: Generate Test Cases with Traceability Matrix
+## Step 6: Generate Test Cases with Traceability Matrix
 
 Map each acceptance criterion to one or more test cases, following CLAUDE.md test spec rules.
 
@@ -312,7 +373,7 @@ Write to `{OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md`.
 </step>
 
 <step name="generate_test_files">
-## Step 6: Spawn Executor Agent
+## Step 7: Spawn Executor Agent
 
 Build a synthetic generation plan from the test cases and spawn the executor to write test files.
 
@@ -361,6 +422,7 @@ Task(
     <files_to_read>
     - {OUTPUT_DIR}/GENERATION_PLAN_TICKET.md
     - {OUTPUT_DIR}/TEST_CASES_FROM_TICKET.md
+    - {OUTPUT_DIR}/locators/LOCATOR_REGISTRY.md (if exists -- accumulated real locators)
     - CLAUDE.md
     </files_to_read>
     <parameters>
@@ -376,7 +438,7 @@ Extract: `files_created`, `total_files`, `commit_count`, `test_case_count`.
 </step>
 
 <step name="validate_generated_tests">
-## Step 7: Spawn Validator Agent
+## Step 8: Spawn Validator Agent
 
 Validate the generated test files against CLAUDE.md standards.
 
@@ -402,7 +464,7 @@ Extract: `overall_status`, `confidence`, `issues_found`, `issues_fixed`, `unreso
 </step>
 
 <step name="print_summary">
-## Step 8: Print Summary
+## Step 9: Print Summary
 
 Print a comprehensive summary showing traceability from ticket to tests.
 

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

@@ -1,19 +0,0 @@
-# QA Repository Analysis (Deprecated)
-
-This command has been merged into `/qa-map`, which runs codebase mapping + analysis in one step.
-
-## Usage
-
-Use `/qa-map` instead:
-
-```
-/qa-map [--dev-repo <path>] [--qa-repo <path>]
-```
-
-## Instructions
-
-Tell the user: "/qa-analyze is now part of /qa-map. Running /qa-map for you."
-
-Then execute `/qa-map` with the same arguments the user provided.
-
-$ARGUMENTS

package/README.md

@@ -1,431 +0,0 @@
-# QAA -- QA Automation Agent
-
-Multi-agent QA automation system for Claude Code. Point it at any repository -- it analyzes the codebase, generates a standards-compliant test suite, validates everything, and delivers the result as a draft PR. Runs locally via Claude Code.
-
-No manual test writing. No guessing what to cover. One command, full pipeline.
-
-## Quick Start
-
-Prerequisites: Node.js 18+, Claude Code (Pro or Max plan), gh CLI (authenticated), Git.
-
-```bash
-# 1. Clone this repo alongside your project
-git clone <this-repo-url> qa-agent
-
-# 2. Open Claude Code in the qa-agent directory
-
-# 3. Run the full pipeline against your dev repo
-/qa-start --dev-repo /path/to/your-project
-
-# 4. Wait for the pipeline to complete, then review the draft PR
-```
-
-For an existing QA repository:
-
-```bash
-/qa-start --dev-repo /path/to/dev-repo --qa-repo /path/to/qa-repo
-```
-
-For fully unattended execution (auto-approve safe checkpoints):
-
-```bash
-/qa-start --dev-repo /path/to/your-project --auto
-```
-
-## Prerequisites
-
-Every tool below must be installed and working before running the pipeline.
-
-- **Node.js 18+** -- Runtime for CLI tooling. The pipeline uses Node for configuration management and artifact validation.
-- **Claude Code** (Anthropic) -- The AI coding assistant that executes the agents. You must have a **Pro or Max plan** for access to the Opus model, which all agents require.
-- **gh CLI** -- GitHub's official command-line tool for creating pull requests. Install from https://cli.github.com and authenticate before first use.
-- **Git** -- Version control. The target repository must have a remote origin configured for PR delivery.
-
-### Verifying Prerequisites
-
-Run each command and confirm the expected output:
-
-```bash
-node --version          # Must show v18.x.x or higher
-claude --version        # Must show Claude Code version
-gh auth status          # Must show "Logged in to github.com"
-git --version           # Must show git version 2.x+
-```
-
-If any command fails, install the missing tool before proceeding.
-
-## Installation
-
-1. Clone or copy this repository into a local directory:
-   ```bash
-   git clone <this-repo-url> qa-agent
-   cd qa-agent
-   ```
-
-2. Verify the setup is healthy:
-   ```bash
-   node bin/qaa-tools.cjs validate health
-   ```
-
-3. Open Claude Code in this directory. The `.claude/commands/` directory provides all slash commands automatically -- no additional setup needed.
-
-## Configuration
-
-The pipeline behavior is controlled by `.planning/config.json`. Default values work for most projects.
-
-| Setting | Options | Default | Description |
-|---------|---------|---------|-------------|
-| `mode` | `quality`, `balanced`, `budget` | `quality` | Controls which AI models agents use |
-| `granularity` | `coarse`, `standard`, `fine` | `standard` | Detail level of analysis and generation |
-| `parallelization` | `true`, `false` | `true` | Enable wave-based parallel agent execution |
-| `workflow.auto_advance` | `true`, `false` | `false` | Auto-approve safe checkpoints without pausing |
-
-Set values via CLI:
-
-```bash
-node bin/qaa-tools.cjs config set mode balanced
-node bin/qaa-tools.cjs config set workflow.auto_advance true
-```
-
-Or edit `.planning/config.json` directly.
-
-## Commands
-
-All commands are available as slash commands in Claude Code. They are organized into three tiers by frequency of use.
-
-### /qa-start -- Full Pipeline (Tier 1: Daily Use)
-
-The primary command. Runs the entire QA automation pipeline from scan to PR delivery.
-
-```
-/qa-start [--dev-repo <path>] [--qa-repo <path>] [--auto]
-```
-
-**Arguments:**
-- No arguments: uses current directory as the dev repo (Option 1: dev-only)
-- `--dev-repo`: explicit path to the developer repository
-- `--qa-repo`: path to an existing QA repository (triggers Option 2 or 3 based on maturity score)
-- `--auto`: enable auto-advance mode (skips safe checkpoint pauses)
-
-**What happens:**
-1. Scans the repository -- detects framework, language, testable surfaces
-2. Analyzes architecture -- produces risk assessment, test inventory, blueprint
-3. Injects test IDs (if frontend components detected)
-4. Plans test generation -- groups test cases by feature domain
-5. Generates test files -- unit, API, integration, E2E with Page Object Models
-6. Validates generated tests -- 4-layer validation with auto-fix (up to 3 loops)
-7. Classifies any remaining failures (if present)
-8. Delivers everything as a draft PR on a `qa/auto-{project}-{date}` branch
-
-**What it produces:**
-- SCAN_MANIFEST.md, QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md
-- Generated test files, POMs, fixtures, and config files
-- VALIDATION_REPORT.md with confidence level (HIGH/MEDIUM/LOW)
-- A draft pull request with full analysis summary
-
-### Analysis Commands (Tier 2: Common Use)
-
-#### /qa-analyze -- Repository Analysis
-
-Scan and analyze a repository without generating tests. Produces assessment documents only.
-
-```
-/qa-analyze [--dev-repo <path>] [--qa-repo <path>]
-```
-
-Produces: SCAN_MANIFEST.md, QA_ANALYSIS.md, TEST_INVENTORY.md, and either QA_REPO_BLUEPRINT.md (no QA repo) or GAP_ANALYSIS.md (QA repo provided).
-
-#### /qa-validate -- Test Validation
-
-Validate existing test files against QA standards. Runs 4-layer checks (syntax, structure, dependencies, logic) and classifies failures.
-
-```
-/qa-validate <path-to-tests> [--framework <name>]
-```
-
-Produces: VALIDATION_REPORT.md. If failures are found, also produces FAILURE_CLASSIFICATION_REPORT.md.
-
-#### /qa-testid -- Test ID Injection
-
-Scan frontend source code, audit missing `data-testid` attributes, and inject them using the project naming convention. Creates a separate branch for changes.
-
-```
-/qa-testid <path-to-frontend-source>
-```
-
-Produces: TESTID_AUDIT_REPORT.md and modified source files with `data-testid` attributes.
-
-### Specialized Commands (Tier 3)
-
-| Command | Purpose | Usage |
-|---------|---------|-------|
-| `/qa-fix` | Diagnose and fix broken test files | `/qa-fix <path-to-tests> [error output]` |
-| `/qa-pom` | Generate Page Object Model files | `/qa-pom <path-to-pages> [--framework <name>]` |
-| `/qa-audit` | Full 6-dimension quality audit of a test suite | `/qa-audit <path-to-tests> [--dev-repo <path>]` |
-| `/qa-gap` | Gap analysis between dev and QA repos | `/qa-gap --dev-repo <path> --qa-repo <path>` |
-| `/qa-blueprint` | Generate QA repository structure blueprint | `/qa-blueprint [--dev-repo <path>]` |
-| `/qa-report` | Generate QA status report (team/management/client) | `/qa-report <path-to-tests> [--audience <level>]` |
-| `/qa-pyramid` | Analyze test distribution vs. ideal pyramid | `/qa-pyramid <path-to-tests> [--dev-repo <path>]` |
-| `/create-test` | Generate tests for a specific feature | `/create-test <feature-name> [--dev-repo <path>] [--app-url <url>]` |
-| `/update-test` | Improve existing tests without rewriting them | `/update-test <path-to-tests> [--scope <type>]` |
-| `/qa-map` | Deep-scan codebase for testability, risk, patterns | `/qa-map [--focus <area>]` |
-| `/qa-research` | Research best testing stack and practices | `/qa-research [--focus <area>]` |
-| `/qa-from-ticket` | Generate tests from a Jira/Linear/GitHub ticket | `/qa-from-ticket <source>` |
-| `/qa-pr` | Create draft PR from QA artifacts | `/qa-pr [--ticket <id>] [--title <desc>]` |
-
-## Workflow Options
-
-The pipeline automatically selects the right workflow based on the repositories you provide.
-
-### Option 1: Dev-Only Repository
-
-**When to use:** The project has no existing QA repository. You are starting QA from scratch.
-
-**Trigger:** Run `/qa-start --dev-repo <path>` with no `--qa-repo` argument.
-
-**What happens:** Full pipeline -- scan, analyze, plan, generate, validate, deliver. Produces a complete test suite with POMs, fixtures, config files, and a QA repository blueprint. The draft PR contains everything needed to bootstrap a QA repo.
-
-### Option 2: Dev + Immature QA Repository
-
-**When to use:** A QA repo exists but has low coverage, inconsistent patterns, or broken tests. Maturity score below 70%.
-
-**Trigger:** Run `/qa-start --dev-repo <path> --qa-repo <path>` where the QA repo scores below the maturity threshold.
-
-**What happens:** Scans both repos, runs gap analysis, fixes broken tests, adds missing coverage, standardizes existing tests to match CLAUDE.md conventions. Produces a PR that improves the existing test suite rather than replacing it.
-
-### Option 3: Dev + Mature QA Repository
-
-**When to use:** A solid QA repo already exists with good coverage and patterns. Maturity score 70% or above.
-
-**Trigger:** Run `/qa-start --dev-repo <path> --qa-repo <path>` where the QA repo scores at or above the maturity threshold.
-
-**What happens:** Scans both repos, identifies only thin coverage areas, adds surgical test additions without touching existing working tests. Produces a minimal PR with targeted additions.
-
-## Example Output
-
-The following shows a typical `/qa-start` run against a Next.js e-commerce project:
-
-```
-> /qa-start --dev-repo ./shopflow --auto
-
-+------------------------------------------+
-|  QA Automation Pipeline                  |
-|  Option: 1 (Dev-only)                   |
-|  Target: shopflow                        |
-+------------------------------------------+
-
-+------------------------------------------+
-|  STAGE 1: Scan                           |
-|  Status: Running...                      |
-+------------------------------------------+
-Scanner complete. 847 files scanned, 32 testable surfaces identified.
-Output: .qa-output/SCAN_MANIFEST.md
-
-+------------------------------------------+
-|  STAGE 2: Analyze                        |
-|  Status: Running...                      |
-+------------------------------------------+
-Architecture: Next.js 14, TypeScript, Prisma ORM, REST API
-Risk areas: authentication (HIGH), payment processing (HIGH), cart logic (MEDIUM)
-Output: .qa-output/QA_ANALYSIS.md, .qa-output/TEST_INVENTORY.md, .qa-output/QA_REPO_BLUEPRINT.md
-
-+------------------------------------------+
-|  STAGE 3: Test ID Injection              |
-|  Status: Running...                      |
-+------------------------------------------+
-Frontend detected. Auditing data-testid coverage...
-Coverage: 12% (18 of 147 interactive elements have data-testid)
-Injected 94 data-testid attributes across 23 components.
-Output: .qa-output/TESTID_AUDIT_REPORT.md
-
-+------------------------------------------+
-|  STAGE 4: Plan                           |
-|  Status: Running...                      |
-+------------------------------------------+
-Grouped 42 test cases into 6 feature domains: auth, products, cart, checkout, orders, admin.
-
-+------------------------------------------+
-|  STAGE 5: Generate                       |
-|  Status: Running...                      |
-+------------------------------------------+
-Generated 38 test files: 24 unit, 8 API, 4 integration, 2 E2E
-Created 6 Page Object Models, 4 fixture files, 2 config files.
-
-+------------------------------------------+
-|  STAGE 6: Validate                       |
-|  Status: Running...                      |
-+------------------------------------------+
-Validation loop 1: 3 issues found, 3 auto-fixed.
-Validation loop 2: all files PASS.
-Confidence: HIGH
-
-+------------------------------------------+
-|  STAGE 7: Deliver                        |
-|  Status: Running...                      |
-+------------------------------------------+
-Branch created: qa/auto-shopflow-2026-03-19
-PR created: https://github.com/client/shopflow/pull/42
-
-+------------------------------------------+
-|  PIPELINE COMPLETE                       |
-|  Tests: 24 unit, 8 API, 4 integration,  |
-|         2 E2E (38 total)                 |
-|  Validation: PASS (HIGH confidence)      |
-|  PR: https://github.com/client/shopflow  |
-|      /pull/42                            |
-+------------------------------------------+
-```
-
-## Troubleshooting
-
-### "gh: not authenticated"
-
-The gh CLI needs to be authenticated before the pipeline can create PRs. Run:
-
-```bash
-gh auth login
-```
-
-Select GitHub.com, HTTPS protocol, and authenticate via browser. After login, verify with `gh auth status`.
-
-### "No git remote found"
-
-The target repository must have a remote origin configured for the deliver stage to push and create a PR. Add one:
-
-```bash
-cd /path/to/target-repo
-git remote add origin https://github.com/org/repo.git
-```
-
-If you only want local output without a PR, the pipeline will fall back gracefully -- all artifacts are still written to `.qa-output/`.
-
-### "A branch named 'qa/auto-...' already exists"
-
-A pipeline was previously run on the same day against the same project. The system automatically appends a numeric suffix (`-2`, `-3`, etc.) to avoid collisions. If you want to clean up old branches:
-
-```bash
-git branch -D qa/auto-shopflow-2026-03-19
-```
-
-### Pipeline stalls at a checkpoint
-
-Some pipeline stages have verification checkpoints that pause for your input. Type your response in the Claude Code terminal to continue. To skip safe checkpoints automatically, use the `--auto` flag:
-
-```
-/qa-start --dev-repo <path> --auto
-```
-
-Or enable auto-advance globally:
-
-```bash
-node bin/qaa-tools.cjs config set workflow.auto_advance true
-```
-
-### Tests fail validation after 3 fix loops
-
-The validator attempted 3 automatic fix cycles but could not resolve all issues. Review the details in `.qa-output/VALIDATION_REPORT.md` to understand what failed and why. Fix the remaining issues manually, then re-validate:
-
-```
-/qa-validate <path-to-test-files>
-```
-
-### Claude Code says "model not available"
-
-You need a Pro or Max plan for Opus model access. Check your plan at https://console.anthropic.com. The pipeline requires Opus for all agent operations.
-
-## Project Structure
-
-```
-qa-agent-gsd/
-  agents/                          -- Agent workflow definitions
-    qa-pipeline-orchestrator.md    --   Main pipeline controller (3 options)
-    qaa-scanner.md                 --   Repository scanner agent
-    qaa-codebase-mapper.md         --   Codebase deep-scan agent (4 parallel focus areas)
-    qaa-analyzer.md                --   Architecture analyzer agent
-    qaa-planner.md                 --   Test generation planner agent
-    qaa-executor.md                --   Test file generator agent
-    qaa-validator.md               --   Test validation agent
-    qaa-e2e-runner.md              --   E2E test execution agent (Playwright browser)
-    qaa-testid-injector.md         --   Test ID injection agent
-    qaa-bug-detective.md           --   Failure classification agent
-    qaa-project-researcher.md      --   Testing stack research agent
-  bin/                             -- CLI tooling
-    qaa-tools.cjs                  --   Main CLI entry point
-    lib/                           --   CLI module library
-  templates/                       -- Output artifact templates (9 templates + PR template)
-    scan-manifest.md               --   Scan output template
-    qa-analysis.md                 --   Analysis output template
-    test-inventory.md              --   Test inventory template
-    qa-repo-blueprint.md           --   Repository blueprint template
-    gap-analysis.md                --   Gap analysis template
-    validation-report.md           --   Validation report template
-    failure-classification.md      --   Failure classification template
-    testid-audit-report.md         --   Test ID audit template
-    qa-audit-report.md             --   Quality audit template
-    pr-template.md                 --   Pull request body template
-  .claude/commands/                -- Slash commands (17 commands, auto-detected by Claude Code)
-    qa-start.md                    --   Tier 1: full pipeline
-    qa-analyze.md                  --   Tier 2: analysis only
-    qa-validate.md                 --   Tier 2: test validation
-    qa-testid.md                   --   Tier 2: test ID injection
-    qa-fix.md                      --   Tier 3: fix broken tests
-    qa-pom.md                      --   Tier 3: generate POMs
-    qa-audit.md                    --   Tier 3: quality audit
-    qa-gap.md                      --   Tier 3: gap analysis
-    qa-blueprint.md                --   Tier 3: repo blueprint
-    qa-report.md                   --   Tier 3: status report
-    qa-pyramid.md                  --   Tier 3: pyramid analysis
-    create-test.md                 --   Tier 3: create tests for a feature
-    update-test.md                 --   Tier 3: improve existing tests
-    qa-map.md                      --   Tier 3: deep-scan codebase
-    qa-research.md                 --   Tier 3: research testing stack
-    qa-from-ticket.md              --   Tier 3: tests from ticket
-    qa-pr.md                       --   Tier 3: create draft PR
-  CLAUDE.md                        -- QA standards, agent coordination, quality gates
-  .planning/                       -- Planning artifacts and project state
-    config.json                    --   Pipeline configuration
-  .qa-output/                      -- Generated artifacts (created during pipeline run)
-```
-
-## Pipeline Stages
-
-The full pipeline follows this sequence:
-
-```
-scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
-```
-
-| Stage | Agent | Input | Output |
-|-------|-------|-------|--------|
-| Scan | qa-scanner | Repository source files | SCAN_MANIFEST.md |
-| Codebase Map | qa-codebase-mapper (x4 parallel) | SCAN_MANIFEST.md, source files | 8 codebase documents (testability, risk, patterns, existing tests) |
-| Analyze | qa-analyzer | SCAN_MANIFEST.md, codebase map | QA_ANALYSIS.md, TEST_INVENTORY.md, blueprint or gap analysis |
-| Test ID Inject | qa-testid-injector | Frontend source files | TESTID_AUDIT_REPORT.md, modified source files |
-| Plan | qa-planner | TEST_INVENTORY.md, QA_ANALYSIS.md, codebase map | Generation plan (internal) |
-| Generate | qa-executor | Generation plan, codebase map | Test files, POMs, fixtures, configs |
-| Validate | qa-validator | Generated test files | VALIDATION_REPORT.md |
-| E2E Runner | qa-e2e-runner | E2E test files, live app | E2E_RUN_REPORT.md, fixed locators |
-| Bug Detective | qa-bug-detective | Test execution results | FAILURE_CLASSIFICATION_REPORT.md |
-| Deliver | orchestrator | All artifacts | Git branch + draft PR |
-
-Each stage produces artifacts consumed by the next. The pipeline will not advance to the next stage until the current stage's artifacts pass verification.
-
-## Output Artifacts
-
-All artifacts are written to the `.qa-output/` directory during a pipeline run:
-
-| Artifact | Description |
-|----------|-------------|
-| SCAN_MANIFEST.md | File tree, framework detection, testable surfaces, file priority |
-| 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 | Recommended QA repo structure, configs, CI/CD, definition of done |
-| GAP_ANALYSIS.md | Coverage gaps between dev and QA repos (Option 2/3 only) |
-| VALIDATION_REPORT.md | 4-layer validation results per file, confidence level, fix loop log |
-| FAILURE_CLASSIFICATION_REPORT.md | Failure classification: APP BUG, TEST ERROR, ENV ISSUE, INCONCLUSIVE |
-| TESTID_AUDIT_REPORT.md | data-testid coverage score, proposed values, decision gate |
-| QA_AUDIT_REPORT.md | 6-dimension quality score with weighted calculation |
-
----
-
-Powered by Claude Code.