qaa-agent 1.6.3 → 1.7.0

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

@@ -1,164 +0,0 @@
-# Create Automated Tests
-
-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>] [--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
-
-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. 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, 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-audit.md

@@ -1,37 +0,0 @@
-# Full QA Audit
-
-Comprehensive quality audit of a test suite against CLAUDE.md standards. Scores across 6 dimensions: Locator Quality (20%), Assertion Specificity (20%), POM Compliance (15%), Test Coverage (20%), Naming Convention (15%), Test Data Management (10%).
-
-## Usage
-
-/qa-audit <path-to-tests> [--dev-repo <path>]
-
-- path-to-tests: directory containing test files to audit
-- --dev-repo: path to developer repository (for coverage cross-reference)
-
-## What It Produces
-
-- QA_AUDIT_REPORT.md -- 6-dimension scoring, critical issues list, prioritized recommendations with effort estimates
-
-## Instructions
-
-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</objective>
-    <execution_context>@agents/qaa-validator.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: audit
-    </parameters>
-  "
-)
-
-3. Present results with overall score and prioritized recommendations.
-
-$ARGUMENTS

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

@@ -1,54 +0,0 @@
-# QA Repository Blueprint
-
-Generate a complete QA repository structure blueprint for a project that has no existing QA repo. Includes recommended stack, folder structure, config files, CI/CD pipeline, and definition of done.
-
-## Usage
-
-/qa-blueprint [--dev-repo <path>]
-
-- No arguments: analyzes current directory
-- --dev-repo: explicit path to developer repository
-
-## What It Produces
-
-- SCAN_MANIFEST.md -- dev repo scan with framework detection
-- QA_REPO_BLUEPRINT.md -- folder structure, recommended stack, config files, CI/CD strategy
-
-## Instructions
-
-1. Read `CLAUDE.md` -- repo structure, naming conventions, testing pyramid.
-2. Invoke scanner agent:
-
-Task(
-  prompt="
-    <objective>Scan developer 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>
-  "
-)
-
-3. Invoke analyzer agent in full mode (blueprint):
-
-Task(
-  prompt="
-    <objective>Produce QA_REPO_BLUEPRINT.md with complete repository structure</objective>
-    <execution_context>@agents/qaa-analyzer.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - .qa-output/SCAN_MANIFEST.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: full
-    </parameters>
-  "
-)
-
-4. Present blueprint to user. No git operations.
-
-$ARGUMENTS

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

@@ -1,36 +0,0 @@
-# Fix Broken Tests
-
-Diagnose and fix broken test files. Classifies each failure as APPLICATION BUG, TEST CODE ERROR, ENVIRONMENT ISSUE, or INCONCLUSIVE. Auto-fixes only TEST CODE ERRORS. Never touches application code -- only reports APP BUGs for developer attention.
-
-## Usage
-
-/qa-fix <path-to-tests> [error output]
-
-- path-to-tests: directory or specific test files with failures
-- error output: paste test runner output (optional -- agent will run tests if not provided)
-
-## What It Produces
-
-- FAILURE_CLASSIFICATION_REPORT.md -- per-failure classification with evidence, confidence, and auto-fix log
-
-## Instructions
-
-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</objective>
-    <execution_context>@agents/qaa-bug-detective.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    </parameters>
-  "
-)
-
-3. Present results. APPLICATION BUGs are reported for developer action, not auto-fixed.
-
-$ARGUMENTS

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

@@ -1,24 +0,0 @@
-# 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. 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>] [--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
-
-1. Read `CLAUDE.md` -- all QA standards.
-2. Execute the workflow:
-
-Follow the workflow defined in `@workflows/qa-from-ticket.md` end-to-end.
-Preserve all workflow gates (ticket parsing, traceability, validation).
-
-$ARGUMENTS

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

@@ -1,20 +0,0 @@
-# QA Gap Analysis
-
-Compare a developer repository against its QA repository to identify coverage gaps. Requires both repo paths. Produces a detailed gap report showing missing tests, broken tests, and quality assessment.
-
-## Usage
-
-/qa-gap --dev-repo <path> --qa-repo <path>
-
-- --dev-repo: path to the developer repository (required)
-- --qa-repo: path to the existing QA repository (required)
-
-## Instructions
-
-1. Read `CLAUDE.md` -- testing pyramid, test spec rules, quality gates.
-2. Execute the workflow:
-
-Follow the workflow defined in `@workflows/qa-gap.md` end-to-end.
-Preserve all workflow gates (both-repo scanning, gap metrics).
-
-$ARGUMENTS

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

@@ -1,47 +0,0 @@
-# QA Codebase Map & Analysis
-
-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>] [--dev-repo <path>] [--qa-repo <path>]
-
-- 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.
-2. Create output directory: `.qa-output/codebase/`
-3. If no --focus flag, spawn 4 agents in parallel (one per focus area):
-
-For each focus area, spawn:
-
-Agent(
-  prompt="Analyze this codebase for QA purposes. Focus area: {focus}. Write documents to .qa-output/codebase/. Follow the process in your agent definition.",
-  subagent_type="general-purpose",
-  execution_context="@agents/qaa-codebase-mapper.md"
-)
-
-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-pom.md

@@ -1,36 +0,0 @@
-# Generate Page Object Models
-
-Create or update Page Object Model files following CLAUDE.md POM rules. Checks for existing BasePage before creating one. Generates feature-specific POMs with Tier 1 locators, no assertions, and fluent action chaining.
-
-## Usage
-
-/qa-pom <path-to-pages> [--framework <name>]
-
-- path-to-pages: directory containing page/view source files or URLs to model
-- --framework: override framework auto-detection (playwright, cypress, selenium)
-
-## What It Produces
-
-- BasePage file (if not already present)
-- Feature-specific POM files following `[PageName]Page.[ext]` naming convention
-
-## Instructions
-
-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</objective>
-    <execution_context>@agents/qaa-executor.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: pom-only
-    </parameters>
-  "
-)
-
-$ARGUMENTS

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

@@ -1,37 +0,0 @@
-# Testing Pyramid Analysis
-
-Analyze a project's test distribution against the ideal testing pyramid from CLAUDE.md. Compares actual percentages to targets and produces an action plan to reach the recommended distribution.
-
-## Usage
-
-/qa-pyramid <path-to-tests> [--dev-repo <path>]
-
-- path-to-tests: directory containing test files
-- --dev-repo: path to developer repository (for architecture-aware target adjustment)
-
-## What It Produces
-
-- PYRAMID_ANALYSIS.md -- current vs target distribution, gap table, prioritized action plan
-
-## Instructions
-
-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</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 action plan to user.
-
-$ARGUMENTS

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

@@ -1,38 +0,0 @@
-# QA Status Report
-
-Generate a summary report of current QA status for a project. Adapts detail level to audience: team (file-level details), management (high-level metrics), or client (coverage summary).
-
-## Usage
-
-/qa-report <path-to-tests> [--dev-repo <path>] [--audience <team|management|client>]
-
-- path-to-tests: directory containing test files
-- --dev-repo: path to developer repository (for coverage calculation)
-- --audience: report detail level (default: team)
-
-## What It Produces
-
-- QA_STATUS_REPORT.md -- metrics, testing pyramid distribution, risk areas, recommendations
-
-## Instructions
-
-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</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/.claude/commands/qa-research.md

@@ -1,33 +0,0 @@
-# QA Research
-
-Research the best testing approach for a project's stack. Investigates framework capabilities, best practices, and testing patterns using official docs and community sources.
-
-## Usage
-
-/qa-research [--mode <mode>]
-
-- No arguments: auto-detects stack and researches testing approach
-- --mode: specific research mode (stack-testing, framework-deep-dive, api-testing, e2e-strategy)
-
-## What It Produces
-
-- TESTING_STACK.md — recommended test framework, assertion libraries, mock strategies
-- FRAMEWORK_CAPABILITIES.md — deep dive into detected test framework
-- API_TESTING_STRATEGY.md — endpoint testing patterns for this stack
-- E2E_STRATEGY.md — E2E approach for the frontend (if detected)
-
-## Instructions
-
-1. Read `CLAUDE.md` — QA standards.
-2. Detect project stack from package.json, requirements.txt, or similar.
-3. Spawn researcher agent:
-
-Agent(
-  prompt="Research the testing ecosystem for this project. Mode: {mode}. Write findings to .qa-output/research/. Follow the process in your agent definition.",
-  subagent_type="general-purpose",
-  execution_context="@agents/qaa-project-researcher.md"
-)
-
-4. Present findings with confidence levels.
-
-$ARGUMENTS

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

@@ -1,42 +0,0 @@
-# QA Test Validation
-
-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] [--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 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/commands/update-test.md

@@ -1,58 +0,0 @@
-# Update and Improve Existing Tests
-
-Audit existing test files and apply targeted improvements. NEVER deletes or rewrites working tests without user approval. Surgical: add, fix, improve -- never replace.
-
-## Usage
-
-/update-test <path-to-tests> [--scope fix|improve|add|full]
-
-- path-to-tests: directory or specific test files to improve
-- --scope: what to do (default: full)
-  - 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
-
-## What It Produces
-
-- QA_AUDIT_REPORT.md -- current quality assessment
-- Improved test files (after user approval of audit findings)
-
-## Instructions
-
-1. Read `CLAUDE.md` -- quality gates, locator tiers, assertion rules, POM rules.
-2. Invoke validator agent in audit mode first:
-
-Task(
-  prompt="
-    <objective>Audit existing test quality and produce QA_AUDIT_REPORT.md</objective>
-    <execution_context>@agents/qaa-validator.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: audit
-    </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</objective>
-    <execution_context>@agents/qaa-executor.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - .qa-output/QA_AUDIT_REPORT.md
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: update
-    </parameters>
-  "
-)
-
-$ARGUMENTS