qaa-agent 1.6.3 → 1.7.1

package/agents/qaa-validator.md

@@ -22,6 +22,21 @@ Read ALL of the following files BEFORE performing any validation. Do NOT skip.
 
 - **~/.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: assertion style, locator strategy, naming conventions, framework choices.
 
+- **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.
+  - **`.qa-output/locators/{feature}.locators.md`** -- Per-feature locator files with detailed page-by-page locator tables.
+
+  When locator registry files exist, use them during Layer 4 (Logic) validation:
+  - Verify that locators used in generated test files and POMs match the locators in the registry (real DOM values take precedence over guessed values)
+  - Flag any POM locator that uses a `data-testid` value NOT found in the registry as a potential mismatch
+  - Flag any POM using Tier 4 locators (CSS/XPath) when a Tier 1 locator exists in the registry for the same element
+
+- **Codebase map documents** (optional -- read if they exist in `.qa-output/codebase/`):
+  - **CODE_PATTERNS.md** -- Naming conventions, import patterns, code style. Use during Layer 2 (Structure) to verify generated files follow the project's naming conventions and import patterns.
+  - **TEST_SURFACE.md** -- Function signatures, parameter types, return types. Use during Layer 4 (Logic) to verify that test targets (file paths, function names) actually exist in the codebase and that mock setup matches real function signatures.
+  - **API_CONTRACTS.md** -- Request/response shapes, auth patterns. Use during Layer 4 (Logic) to verify API test payloads and assertions match the real API contracts.
+  If these files exist, they enable higher-quality validation that catches mismatches between generated tests and the actual codebase.
+
 Note: Read these files in full. Extract the layer definitions, pass criteria, confidence calculation rules, and quality gate checklist. These define your validation contract and output requirements.
 
 **Important:** The generation plan is the source of truth for which files to validate. If a file exists in the test directory but is NOT in the generation plan, it is a pre-existing file and MUST be excluded from validation scope. The only exception is Layer 4's cross-check for duplicate IDs, which reads (but does not validate or modify) existing test files.
@@ -55,6 +70,18 @@ Read all required input files before performing any validation.
 4. **Read templates/validation-report.md** -- extract the 5 required sections, field definitions, and confidence criteria table for report generation.
 
 5. **Read .claude/skills/qa-self-validator/SKILL.md** -- extract the 4 layer definitions and pass criteria.
+
+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)
+   - Extract all locators per page: element name, locator type, locator value, tier
+   - Index by page name and element for cross-referencing during Layer 4 validation
+
+7. **Read codebase map documents** (if they exist in `.qa-output/codebase/`):
+   - **CODE_PATTERNS.md** -- Extract naming conventions and import patterns for Layer 2 validation
+   - **TEST_SURFACE.md** -- Extract function signatures and component exports for Layer 4 target verification
+   - **API_CONTRACTS.md** -- Extract real API request/response shapes for Layer 4 assertion verification
+   If any of these files do not exist, proceed without them -- validation quality is improved but not dependent on them.
 </step>
 
 <step name="validate_layer_1_syntax">
@@ -196,6 +223,17 @@ Check test logic quality against CLAUDE.md standards. This layer includes cross-
    - Every `test()`, `it()`, or `def test_` block contains at least one `expect()`, `assert`, or `.should()` call
    - Empty test bodies or tests with only setup/action but no assertion are flagged
 
+7. **Locator registry cross-check (if registry exists):**
+   - For each POM file, compare every locator property against the locator registry
+   - If a POM uses `getByTestId('login-submit-btn')` but the registry shows the real `data-testid` is `login-submit-button-btn`, flag the mismatch
+   - If a POM uses a Tier 4 locator (CSS/XPath) but the registry has a Tier 1 locator for the same element, flag as upgradeable
+   - If a POM references a `data-testid` value that does NOT exist in the registry AND was not found in the codebase, flag as potentially incorrect
+
+8. **API contract cross-check (if API_CONTRACTS.md exists):**
+   - For each API test file, compare request payloads and response assertions against the real API contracts
+   - Flag payload fields not in the contract or missing required fields
+   - Flag assertion values that don't match the contract's response shape
+
 **Cross-check for overlapping selectors:**
    - If the generated tests use `getByTestId('login-submit-btn')` and an existing test also targets `login-submit-btn`, note the overlap. This is informational (not necessarily a collision), but helps identify potential test interference.
    - If generated tests define custom selectors that conflict with existing test helper selectors, flag for review.

package/bin/install.cjs

@@ -101,14 +101,14 @@ async function main() {
   console.log(`  Installing for ${runtime.name} to ${isGlobal ? '~/' + path.relative(HOME, runtime.dir) : './.claude'}`);
   console.log('');
 
-  // Install commands
-  const commandsSrc = path.join(ROOT, '.claude', 'commands');
+  // Install commands (from commands/ in package root to ~/.claude/commands/)
+  const commandsSrc = path.join(ROOT, 'commands');
   const commandsDest = path.join(baseDir, 'commands');
   const cmdCount = copyDir(commandsSrc, commandsDest);
   ok(`Installed ${cmdCount} slash commands`);
 
-  // Install skills (only to baseDir -- Claude Code reads from ~/.claude/skills/)
-  const skillsSrc = path.join(ROOT, '.claude', 'skills');
+  // Install skills (from skills/ in package root to ~/.claude/skills/)
+  const skillsSrc = path.join(ROOT, 'skills');
   const skillsDest = path.join(baseDir, 'skills');
   const skillCount = copyDir(skillsSrc, skillsDest);
   const skillDirCount = countEntries(skillsSrc, 'dirs');
@@ -143,20 +143,30 @@ async function main() {
   copyFile(path.join(ROOT, 'CLAUDE.md'), path.join(qaaDir, 'CLAUDE.md'));
   ok('Installed QA standards (CLAUDE.md)');
 
-  // Install .mcp.json (Playwright MCP server config)
+  // Install .mcp.json (Playwright MCP server config) -- both to qaaDir AND global baseDir
   const mcpSrc = path.join(ROOT, '.mcp.json');
   if (fs.existsSync(mcpSrc)) {
-    const mcpDest = path.join(qaaDir, '.mcp.json');
-    copyFile(mcpSrc, mcpDest);
-    ok('Installed Playwright MCP server config (.mcp.json)');
+    // Copy to qaa dir for reference
+    copyFile(mcpSrc, path.join(qaaDir, '.mcp.json'));
+    // Merge into global ~/.claude/.mcp.json so Playwright MCP is available in ALL projects
+    const globalMcpPath = path.join(baseDir, '.mcp.json');
+    let globalMcp = { mcpServers: {} };
+    if (fs.existsSync(globalMcpPath)) {
+      try { globalMcp = JSON.parse(fs.readFileSync(globalMcpPath, 'utf8')); } catch {}
+      globalMcp.mcpServers = globalMcp.mcpServers || {};
+    }
+    const qaaMcp = JSON.parse(fs.readFileSync(mcpSrc, 'utf8'));
+    Object.assign(globalMcp.mcpServers, qaaMcp.mcpServers);
+    fs.writeFileSync(globalMcpPath, JSON.stringify(globalMcp, null, 2));
+    ok('Installed Playwright MCP server config (global — available in all projects)');
   }
 
   // Write version
   fs.writeFileSync(path.join(qaaDir, 'VERSION'), VERSION);
   ok(`Wrote VERSION (${VERSION})`);
 
-  // Merge settings
-  const settingsSrc = path.join(ROOT, '.claude', 'settings.json');
+  // Merge settings (from settings.json in package root)
+  const settingsSrc = path.join(ROOT, 'settings.json');
   const settingsDest = path.join(baseDir, 'settings.json');
   if (fs.existsSync(settingsSrc)) {
     let existing = {};
@@ -184,9 +194,11 @@ async function main() {
   console.log('');
   console.log('    \x1b[1m/qa-start\x1b[0m          Full QA pipeline (multi-agent)');
   console.log('    \x1b[1m/qa-map\x1b[0m            Codebase map + analysis');
-  console.log('    \x1b[1m/create-test\x1b[0m       Tests for a feature');
-  console.log('    \x1b[1m/qa-from-ticket\x1b[0m    Tests from a Jira/Linear ticket');
-  console.log('    \x1b[1m/qa-validate\x1b[0m       Validate existing tests');
+  console.log('    \x1b[1m/qa-create-test\x1b[0m    Tests for a feature/ticket');
+  console.log('    \x1b[1m/qa-audit\x1b[0m          Audit existing tests');
+  console.log('    \x1b[1m/qa-fix\x1b[0m            Fix broken tests');
+  console.log('    \x1b[1m/qa-testid\x1b[0m         Inject data-testid attributes');
+  console.log('    \x1b[1m/qa-pr\x1b[0m             Create QA pull request');
   console.log('');
   console.log(`  ${cmdCount} commands + ${skillDirCount} skills + ${agentCount} agents ready.`);
   console.log('');

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