qaa-agent 1.6.2 → 1.7.0

package/commands/qa-audit.md

@@ -0,0 +1,119 @@
+# QA Audit & Report
+
+Comprehensive quality audit of a test suite with 6-dimension scoring, testing pyramid analysis, and status reporting. Supports three output modes: full audit, pyramid analysis only, or status report adapted to audience.
+
+## Usage
+
+```
+/qa-audit <path-to-tests> [options]
+```
+
+### Options
+
+- `<path-to-tests>` — directory containing test files to audit
+- `--dev-repo <path>` — path to developer repository (for coverage cross-reference)
+- `--app-url <url>` — URL of running application for locator verification via Playwright MCP
+- `--pyramid` — pyramid analysis only: compare actual vs target distribution with action plan
+- `--report [team|management|client]` — generate status report adapted to audience (default: team)
+
+### Mode Detection
+
+```
+if --pyramid:
+  MODE = "pyramid"      → PYRAMID_ANALYSIS.md
+elif --report:
+  MODE = "report"       → QA_STATUS_REPORT.md (adapted to audience)
+else:
+  MODE = "audit"        → QA_AUDIT_REPORT.md (full 6-dimension audit, default)
+```
+
+## What It Produces
+
+| Mode | Artifact | Description |
+|------|----------|-------------|
+| audit | QA_AUDIT_REPORT.md | 6-dimension scoring, critical issues, recommendations with effort estimates |
+| pyramid | PYRAMID_ANALYSIS.md | Current vs target distribution, gap table, prioritized action plan |
+| report | QA_STATUS_REPORT.md | Metrics, pyramid distribution, risk areas, adapted to audience level |
+
+## Instructions
+
+### AUDIT MODE (default)
+
+Scores across 6 dimensions: Locator Quality (20%), Assertion Specificity (20%), POM Compliance (15%), Test Coverage (20%), Naming Convention (15%), Test Data Management (10%).
+
+1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules, POM rules, naming conventions.
+2. Invoke validator agent in audit mode:
+
+Task(
+  prompt="
+    <objective>Audit test suite quality and produce QA_AUDIT_REPORT.md with 6-dimension scoring. If Playwright MCP is connected and an app URL is available, verify E2E test locators against the live DOM via browser_navigate + browser_snapshot. Flag stale locators (Tier 4 CSS/XPath that could be upgraded to Tier 1 data-testid) and locators that no longer match any DOM element.</objective>
+    <execution_context>@agents/qaa-validator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: audit
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+3. Present results with overall score and prioritized recommendations.
+
+---
+
+### PYRAMID MODE (`--pyramid`)
+
+Analyze test distribution against the ideal testing pyramid from CLAUDE.md (Unit 60-70%, Integration 10-15%, API 20-25%, E2E 3-5%). Compares actual percentages to targets and produces an action plan.
+
+1. Read `CLAUDE.md` — testing pyramid target percentages.
+2. Invoke analyzer agent for pyramid analysis:
+
+Task(
+  prompt="
+    <objective>Produce PYRAMID_ANALYSIS.md comparing actual test distribution to target pyramid. Count tests by type (unit, integration, API, E2E), calculate percentages, compare to CLAUDE.md targets, identify gaps, and produce a prioritized action plan to reach the recommended distribution. Adjust target percentages based on the actual app architecture.</objective>
+    <execution_context>@agents/qaa-analyzer.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: pyramid-analysis
+    </parameters>
+  "
+)
+
+3. Present analysis with gap table and action plan.
+
+---
+
+### REPORT MODE (`--report`)
+
+Generate a summary report of current QA status. Adapts detail level to audience.
+
+**Audience levels:**
+- `team` (default) — file-level details, specific locator/assertion issues, technical recommendations
+- `management` — high-level metrics, risk areas, coverage percentages, trend indicators
+- `client` — coverage summary, confidence level, test pass rates, risk mitigation status
+
+1. Read `CLAUDE.md` — testing pyramid targets, quality gates.
+2. Invoke analyzer agent for status reporting:
+
+Task(
+  prompt="
+    <objective>Produce QA_STATUS_REPORT.md with current test suite metrics and coverage. Adapt detail level to the specified audience: team (file-level technical details), management (high-level metrics and risks), or client (coverage summary and confidence). Include testing pyramid distribution, pass/fail rates, risk areas, and actionable recommendations appropriate for the audience.</objective>
+    <execution_context>@agents/qaa-analyzer.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: status-report
+    </parameters>
+  "
+)
+
+3. Present report to user.
+
+$ARGUMENTS

package/commands/qa-create-test.md

@@ -0,0 +1,288 @@
+# QA Create Test
+
+Create, update, or generate tests from tickets — all in one command. Supports three modes: generate tests from code analysis, generate tests from a ticket (Jira/Linear/GitHub), or update/improve existing tests. Uses Playwright MCP to extract real locators from the live app when available.
+
+## Usage
+
+```
+/qa-create-test <feature-or-source> [options]
+```
+
+### Modes (auto-detected from arguments)
+
+| Mode | Trigger | Example |
+|------|---------|---------|
+| **From code** | Feature name (no URL, no path to tests) | `/qa-create-test login` |
+| **From ticket** | URL, shorthand (#123), or `--ticket` flag | `/qa-create-test https://github.com/org/repo/issues/42` |
+| **Update existing** | Path to existing test files or `--update` flag | `/qa-create-test --update tests/e2e/` |
+| **POM only** | `--pom-only` flag | `/qa-create-test --pom-only src/pages/` |
+
+### Options
+
+- `--dev-repo <path>` — path to developer repository (default: current directory)
+- `--app-url <url>` — URL of running application for E2E execution and locator extraction (auto-detects if not provided)
+- `--skip-run` — skip E2E execution, only generate and statically validate
+- `--ticket <source>` — force ticket mode with: URL, shorthand (#123, org/repo#123), file path, or plain text
+- `--update <path>` — force update mode: audit and improve existing tests at path
+- `--scope fix|improve|add|full` — for update mode only (default: full)
+- `--pom-only [path]` — generate only Page Object Model files (BasePage + feature POMs), no test specs
+- `--framework <name>` — override framework auto-detection (playwright, cypress, selenium) — used with --pom-only
+
+### Mode Detection Logic
+
+```
+if --pom-only:
+  MODE = "pom-only"
+elif argument matches URL pattern ...
+if argument matches URL pattern (github.com, atlassian.net, linear.app) OR contains "#" + digits OR --ticket flag:
+  MODE = "from-ticket"
+elif --update flag OR argument is path to existing test directory/files:
+  MODE = "update"
+else:
+  MODE = "from-code"
+```
+
+## What It Produces
+
+### From Code Mode
+- Test spec files (unit, API, E2E as appropriate)
+- Page Object Model files (for E2E tests)
+- Fixture files (test data)
+- Locator registry entries (`.qa-output/locators/`)
+- E2E_RUN_REPORT.md (if E2E tests ran against live app)
+
+### From Ticket Mode
+- TEST_CASES_FROM_TICKET.md — traceability matrix (AC → test case)
+- GENERATION_PLAN_TICKET.md — synthetic generation plan
+- Test spec files with `traces_to` fields linking back to ticket ACs
+- VALIDATION_REPORT.md
+
+### Update Mode
+- QA_AUDIT_REPORT.md — current quality assessment
+- Improved test files (after user approval)
+
+## Instructions
+
+### Step 1: Detect Mode
+
+Parse `$ARGUMENTS` to determine mode using the detection logic above.
+
+Print mode banner:
+```
+=== QA Create Test ===
+Mode: {from-code | from-ticket | update}
+Target: {feature name | ticket URL | test path}
+App URL: {url or "auto-detect"}
+===========================
+```
+
+---
+
+### FROM CODE MODE
+
+1. Read `CLAUDE.md` — POM rules, locator tiers, assertion rules, naming conventions, quality gates.
+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. **Check for codebase map** (`.qa-output/codebase/`):
+   - Look for: `CODE_PATTERNS.md`, `API_CONTRACTS.md`, `TEST_SURFACE.md`, `TESTABILITY.md`
+   - If at least 2 of these files exist: read them all for project context (naming conventions, API shapes, testable surfaces).
+   - **If NONE of these files exist: STOP and tell the user:**
+     ```
+     ⚠ No codebase map found (.qa-output/codebase/ is empty or missing).
+
+     The codebase map provides critical context: naming conventions, API contracts,
+     testable surfaces, and project structure. Without it, generated tests will lack
+     project-specific context and may not follow your repo's conventions.
+
+     Run /qa-map first to generate the codebase map, then re-run /qa-create-test.
+
+     To skip this check and proceed without context: re-run with --skip-map
+     ```
+     Only proceed without codebase map if the user explicitly passes `--skip-map`.
+
+4. **Check existing locator registry and extract new locators from live app:**
+
+   a. Read `.qa-output/locators/LOCATOR_REGISTRY.md` if it exists.
+
+   b. If locators for this feature already exist in the registry AND no `--app-url` was provided: reuse cached locators.
+
+   c. If locators are missing or `--app-url` was provided: Use Playwright MCP to navigate the app and extract real locators:
+      ```
+      mcp__playwright__browser_navigate({ url: "{app_url}/{feature_path}" })
+      mcp__playwright__browser_snapshot()
+      ```
+      Extract all data-testid, ARIA roles, labels, placeholders.
+      Navigate through multi-page flows if needed.
+      Write per-feature locator file to `.qa-output/locators/{feature}.locators.md`.
+      Update the registry `.qa-output/locators/LOCATOR_REGISTRY.md`.
+
+   If no app URL available and no locators in registry, skip — executor proposes locators from source code.
+
+5. Invoke executor agent to generate test files:
+
+Task(
+  prompt="
+    <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)
+    - .qa-output/locators/{feature}.locators.md (if exists)
+    - .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 E2E runner:
+
+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 with file counts and suggest `/qa-pr`.
+
+---
+
+### FROM TICKET MODE
+
+1. Read `CLAUDE.md` — all QA standards.
+2. Execute the ticket workflow end-to-end:
+
+Follow the workflow defined in `@workflows/qa-from-ticket.md` end-to-end.
+Preserve all workflow gates (ticket parsing, acceptance criteria extraction, traceability matrix, validation).
+
+Key steps in the workflow:
+- Parse ticket source (GitHub URL, Jira URL, Linear URL, file, or plain text)
+- Fetch ticket content (via `gh issue view`, WebFetch, or file read)
+- Extract acceptance criteria, user stories, edge cases
+- Scan dev repo for related source files
+- Extract locators from live app via Playwright MCP (if app URL available)
+- Generate test cases with traceability matrix (every AC maps to ≥1 test case)
+- Spawn executor agent to produce test files
+- Spawn validator agent for 4-layer validation
+- Print summary with AC coverage and traceability
+
+**Traceability guarantee:** Every acceptance criterion maps to at least one test case via the `traces_to` field.
+
+**Supported ticket sources:**
+
+| Format | Example | Detection |
+|--------|---------|-----------|
+| GitHub Issue URL | `https://github.com/org/repo/issues/123` | Contains `github.com` + `/issues/` |
+| GitHub shorthand | `org/repo#123` or `#123` | Contains `#` + digits |
+| Jira URL | `https://company.atlassian.net/browse/PROJ-123` | Contains `.atlassian.net/browse/` |
+| Linear URL | `https://linear.app/team/issue/TEAM-123` | Contains `linear.app` |
+| File path | `./tickets/feature-spec.md` | Path exists on disk |
+| Plain text | `"As a user I want to..."` | None of the above match |
+
+---
+
+### UPDATE MODE
+
+1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules, POM rules.
+2. Invoke validator agent in audit mode:
+
+Task(
+  prompt="
+    <objective>Audit existing test quality and produce QA_AUDIT_REPORT.md. If Playwright MCP is connected, verify E2E test locators against the live DOM via browser_navigate + browser_snapshot.</objective>
+    <execution_context>@agents/qaa-validator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: audit
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+3. Present audit results and wait for user approval.
+4. Invoke executor agent to apply approved improvements:
+
+Task(
+  prompt="
+    <objective>Apply approved improvements to existing tests without deleting working tests. If Playwright MCP is connected, use browser_navigate + browser_snapshot to extract real locators when upgrading from Tier 4 to Tier 1.</objective>
+    <execution_context>@agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - .qa-output/QA_AUDIT_REPORT.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: update
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+**Update scopes:**
+- `fix` — repair broken tests only
+- `improve` — upgrade locators, assertions, POM structure
+- `add` — add missing test cases without modifying existing
+- `full` — audit everything, then improve with approval (default)
+
+**Rule:** NEVER delete or rewrite working tests without user approval. Surgical: add, fix, improve — never replace.
+
+---
+
+### POM ONLY MODE (`--pom-only`)
+
+Generate only Page Object Model files — no test specs.
+
+1. Read `CLAUDE.md` — POM rules, locator tier hierarchy, naming conventions.
+2. Invoke executor agent in POM-only mode:
+
+Task(
+  prompt="
+    <objective>Generate Page Object Models following CLAUDE.md POM rules. If Playwright MCP is connected and an app URL is available, navigate each page first to extract real locators (data-testid, ARIA roles, labels) from the live DOM via browser_navigate + browser_snapshot before generating POMs. This ensures POM locators match the real app instead of guessing from source code.</objective>
+    <execution_context>@agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: pom-only
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+**Produces:**
+- BasePage file (if not already present)
+- Feature-specific POM files following `[PageName]Page.[ext]` naming convention
+- No test specs, no fixtures
+
+**POM rules enforced:**
+- One class per page — no god objects
+- No assertions in page objects — assertions belong ONLY in test specs
+- Locators as readonly properties — Tier 1 preferred (data-testid, ARIA roles)
+- Actions return void or next page — for fluent chaining
+- State queries return data — let the test decide what to assert
+- Every POM extends BasePage
+
+$ARGUMENTS

package/commands/qa-fix.md

@@ -0,0 +1,147 @@
+# QA Fix & Validate
+
+Validate, diagnose, and fix test files — all in one command. Runs 4-layer static validation (syntax, structure, dependencies, logic), classifies failures, and auto-fixes TEST CODE ERRORS. Uses Playwright MCP to reproduce E2E failures and verify locators against the live app when available. Never touches application code.
+
+## Usage
+
+```
+/qa-fix [<test-directory>] [options]
+```
+
+### Options
+
+- `<test-directory>` — path to test files (auto-detects if omitted)
+- `--validate-only` — run 4-layer static validation only, no test execution or classification
+- `--classify` — run tests and classify failures, but do NOT auto-fix
+- `--run --app-url <url>` — also execute E2E tests against live app after static validation
+- `--app-url <url>` — URL of running application (auto-detects if not provided)
+- `[error output]` — paste test runner output directly (skips running tests, classifies the pasted output)
+
+### Mode Detection
+
+```
+if --validate-only:
+  MODE = "validate"        → 4-layer static validation + VALIDATION_REPORT.md
+elif --classify:
+  MODE = "classify"        → run tests + classify failures (no auto-fix)
+else:
+  MODE = "fix"             → run tests + classify + auto-fix TEST CODE ERRORS (default)
+```
+
+## What It Produces
+
+| Mode | Artifacts |
+|------|-----------|
+| validate | VALIDATION_REPORT.md (syntax, structure, dependencies, logic per file) |
+| classify | FAILURE_CLASSIFICATION_REPORT.md (per-failure evidence, no fixes) |
+| fix | FAILURE_CLASSIFICATION_REPORT.md + auto-fixed test files |
+
+## Instructions
+
+### Step 1: Detect Mode and Test Directory
+
+Parse `$ARGUMENTS` for mode flags and test directory path.
+
+If no test directory provided, auto-detect:
+- Check for `tests/`, `cypress/`, `__tests__/`, `e2e/`, `spec/` directories
+- Check test config files for `testDir` setting
+
+Print banner:
+```
+=== QA Fix & Validate ===
+Mode: {validate | classify | fix}
+Test Directory: {path}
+App URL: {url or "auto-detect"}
+==========================
+```
+
+---
+
+### VALIDATE MODE (`--validate-only`)
+
+1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules.
+2. Execute static validation workflow:
+
+Follow the workflow defined in `@workflows/qa-validate.md` end-to-end.
+Preserve all workflow gates (fix loops, layer checks).
+
+The validator runs 4 layers per file:
+1. **Syntax** — code compiles without errors
+2. **Structure** — naming, folders, POM compliance
+3. **Dependencies** — all imports resolve
+4. **Logic** — concrete assertions, Tier 1-2 locators, no assertions in POMs
+
+**Optional Layer 5 (if Playwright MCP connected + app URL available):**
+- Navigate to each page referenced in E2E tests via `mcp__playwright__browser_navigate`
+- Take accessibility snapshot via `mcp__playwright__browser_snapshot`
+- Cross-reference test locators against real DOM elements
+- Flag locators that don't match, auto-fix mismatches
+
+Max 3 fix loop iterations. Produces VALIDATION_REPORT.md.
+
+If `--run` flag is also present and E2E test files exist, invoke E2E runner after static validation:
+
+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>
+  "
+)
+
+---
+
+### CLASSIFY MODE (`--classify`)
+
+Same as fix mode below but skip Step 4 (auto-fix). Only classify and report.
+
+---
+
+### FIX MODE (default)
+
+1. Read `CLAUDE.md` — classification rules, locator tiers, assertion quality.
+2. Invoke bug-detective agent:
+
+Task(
+  prompt="
+    <objective>Run tests, classify failures, and auto-fix TEST CODE ERRORS. Use Playwright MCP to reproduce E2E failures in the browser when available — navigate to failing pages, snapshot DOM, reproduce actions, and screenshot failure state for evidence.</objective>
+    <execution_context>@agents/qaa-bug-detective.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+**Classification categories:**
+- **APPLICATION BUG** — error in production code → Report only, NEVER auto-fix
+- **TEST CODE ERROR** — error in test code → Auto-fix if HIGH confidence
+- **ENVIRONMENT ISSUE** — missing env, connection refused → Report with resolution steps
+- **INCONCLUSIVE** — ambiguous → Report what's known, ask for more info
+
+**Auto-fix rules:**
+- Only TEST CODE ERROR at HIGH confidence
+- Allowed fixes: import paths, selectors, assertion values, config, missing await, fixture paths
+- Every fix verified by re-running the specific test
+- Never modify application code (src/, app/, lib/)
+
+**Browser reproduction (when Playwright MCP connected):**
+- Navigate to failing page → snapshot DOM → reproduce action → screenshot
+- Element not in DOM → TEST CODE ERROR (HIGH confidence)
+- Element exists, wrong behavior → APPLICATION BUG
+- Page doesn't load → ENVIRONMENT ISSUE
+
+3. Present results. APPLICATION BUGs are reported for developer action, not auto-fixed.
+
+$ARGUMENTS

package/commands/qa-map.md

@@ -0,0 +1,137 @@
+# QA Codebase Map & Analysis
+
+Deep-scan a codebase for QA-relevant information, produce a complete analysis, and generate test inventory. Runs codebase mapping (4 parallel agents) followed by full repository analysis. One command to fully understand a codebase before writing tests.
+
+## Usage
+
+```
+/qa-map [options]
+```
+
+### Options
+
+- No arguments — runs full map + analysis on current directory
+- `--focus <area>` — run a single map area only, skip analysis (testability, risk, patterns, existing-tests)
+- `--dev-repo <path>` — explicit path to developer repository
+- `--qa-repo <path>` — path to existing QA repository (produces gap analysis instead of blueprint)
+- `--skip-map` — skip codebase mapping, only run analysis (lighter, faster)
+
+## What It Produces
+
+### Stage 1: Codebase Map (4 parallel agents)
+
+| Focus Area | Documents Produced |
+|------------|-------------------|
+| **testability** | TESTABILITY.md + TEST_SURFACE.md — what's testable, entry points, mocking needs |
+| **risk** | RISK_MAP.md + CRITICAL_PATHS.md — business-critical paths, error handling gaps |
+| **patterns** | CODE_PATTERNS.md + API_CONTRACTS.md — naming conventions, API shapes, auth patterns |
+| **existing-tests** | TEST_ASSESSMENT.md + COVERAGE_GAPS.md — existing test quality, what's missing |
+
+All documents written to `.qa-output/codebase/`.
+
+### Stage 2: Repository Analysis
+
+| Document | Description |
+|----------|-------------|
+| 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 | If no QA repo — full repo structure, configs, CI/CD strategy |
+| GAP_ANALYSIS.md | If QA repo provided — coverage map, missing tests, broken tests, quality assessment |
+
+## Instructions
+
+1. Read `CLAUDE.md` — QA standards.
+
+2. Create output directories:
+```bash
+mkdir -p .qa-output/codebase
+```
+
+3. **Stage 1: Codebase Mapping**
+
+If `--skip-map` was NOT passed and `--focus` was NOT specified, spawn 4 agents in parallel (one per focus area):
+
+```
+Agent(
+  prompt="Analyze this codebase for QA purposes. Focus area: testability. Write TESTABILITY.md and TEST_SURFACE.md to .qa-output/codebase/. Follow your agent definition process.",
+  subagent_type="general-purpose",
+  execution_context="@agents/qaa-codebase-mapper.md"
+)
+
+Agent(
+  prompt="Analyze this codebase for QA purposes. Focus area: risk. Write RISK_MAP.md and CRITICAL_PATHS.md to .qa-output/codebase/. Follow your agent definition process.",
+  subagent_type="general-purpose",
+  execution_context="@agents/qaa-codebase-mapper.md"
+)
+
+Agent(
+  prompt="Analyze this codebase for QA purposes. Focus area: patterns. Write CODE_PATTERNS.md and API_CONTRACTS.md to .qa-output/codebase/. Follow your agent definition process.",
+  subagent_type="general-purpose",
+  execution_context="@agents/qaa-codebase-mapper.md"
+)
+
+Agent(
+  prompt="Analyze this codebase for QA purposes. Focus area: existing-tests. Write TEST_ASSESSMENT.md and COVERAGE_GAPS.md to .qa-output/codebase/. Follow your agent definition process.",
+  subagent_type="general-purpose",
+  execution_context="@agents/qaa-codebase-mapper.md"
+)
+```
+
+If `--focus <area>` was provided, spawn only that one agent and STOP after it completes (skip Stage 2).
+
+If `--skip-map` was passed, skip Stage 1 entirely and go to Stage 2.
+
+4. When all map agents complete, print summary of documents produced.
+
+5. **Stage 2: Repository Analysis**
+
+Initialize pipeline context:
+```bash
+node bin/qaa-tools.cjs init qa-start 2>/dev/null || true
+```
+
+Invoke scanner agent:
+
+Task(
+  prompt="
+    <objective>Scan repository and produce SCAN_MANIFEST.md</objective>
+    <execution_context>@agents/qaa-scanner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+Invoke analyzer agent:
+
+Task(
+  prompt="
+    <objective>Analyze repository and produce QA_ANALYSIS.md, TEST_INVENTORY.md, and blueprint or gap analysis. Use codebase map documents from .qa-output/codebase/ if they exist for deeper, more accurate analysis.</objective>
+    <execution_context>@agents/qaa-analyzer.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - .qa-output/SCAN_MANIFEST.md
+    - .qa-output/codebase/TESTABILITY.md (if exists)
+    - .qa-output/codebase/RISK_MAP.md (if exists)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
+    - .qa-output/codebase/TEST_ASSESSMENT.md (if exists)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists)
+    - .qa-output/codebase/CRITICAL_PATHS.md (if exists)
+    - .qa-output/codebase/API_CONTRACTS.md (if exists)
+    - .qa-output/codebase/COVERAGE_GAPS.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+6. Print final summary: all documents produced across both stages.
+   No git operations. No test generation.
+   Suggest `/qa-create-test` to generate tests from the analysis.
+
+$ARGUMENTS