qaa-agent 1.0.0

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

@@ -0,0 +1,40 @@
+# Create Automated Tests
+
+Generate production-ready test files with POM pattern for a specific feature or module. Reads existing QA_ANALYSIS.md and TEST_INVENTORY.md if available.
+
+## Usage
+
+/create-test <feature-name> [--dev-repo <path>]
+
+- feature-name: which feature to test (e.g., "login", "checkout", "user API")
+- --dev-repo: path to developer repository (default: current directory)
+
+## 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)
+
+## 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. Invoke executor agent:
+
+Task(
+  prompt="
+    <objective>Generate test files for the specified feature following CLAUDE.md standards</objective>
+    <execution_context>@agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: feature-test
+    </parameters>
+  "
+)
+
+$ARGUMENTS

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

@@ -0,0 +1,60 @@
+# QA Repository Analysis
+
+Analysis-only mode. Scans a repository, detects framework and stack, and produces QA assessment documents. No test generation. No PR creation.
+
+## Usage
+
+/qa-analyze [--dev-repo <path>] [--qa-repo <path>]
+
+- No arguments: analyzes current directory
+- --dev-repo: explicit path to developer repository
+- --qa-repo: path to existing QA repository (produces gap analysis instead of blueprint)
+
+## What It Produces
+
+- SCAN_MANIFEST.md -- file tree, framework detection, testable surfaces
+- QA_ANALYSIS.md -- architecture overview, risk assessment, testing pyramid
+- TEST_INVENTORY.md -- prioritized test cases with IDs and explicit outcomes
+- QA_REPO_BLUEPRINT.md (if no QA repo) or GAP_ANALYSIS.md (if QA repo provided)
+
+## Instructions
+
+1. Read `CLAUDE.md` -- all QA standards.
+2. Initialize pipeline context:
+   ```bash
+   node bin/qaa-tools.cjs init qa-start [user arguments]
+   ```
+3. 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>
+  "
+)
+
+4. Invoke analyzer agent:
+
+Task(
+  prompt="
+    <objective>Analyze repository and produce QA_ANALYSIS.md, TEST_INVENTORY.md, and blueprint or gap analysis</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
+    </parameters>
+  "
+)
+
+5. Present results to user. No git operations. No test generation.
+
+$ARGUMENTS

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

@@ -0,0 +1,37 @@
+# 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

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,88 @@
+# 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.
+
+## Usage
+
+/qa-from-ticket <ticket-source> [--dev-repo <path>]
+
+- ticket-source: one of:
+  - URL to Jira/Linear/GitHub issue (e.g., https://linear.app/team/PROJ-123)
+  - 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)
+
+## What It Produces
+
+- TEST_CASES_FROM_TICKET.md -- test cases derived from acceptance criteria
+- Test spec files (unit, API, E2E as appropriate)
+- Page Object Model files (for E2E tests if needed)
+- Fixture files (test data)
+- Traceability matrix: which test covers which acceptance criterion
+
+## Instructions
+
+1. Read `CLAUDE.md` -- all QA standards.
+
+2. Parse the ticket source:
+
+   **If URL:** Fetch the ticket content using WebFetch or gh CLI (for GitHub issues).
+   ```bash
+   # GitHub Issues
+   gh issue view <number> --json title,body,labels,assignees
+
+   # For other URLs, use WebFetch to read the page
+   ```
+
+   **If plain text:** Use the text directly as the ticket content.
+
+   **If file path:** Read the file content.
+
+3. Extract from the ticket:
+   - **Title/Summary**: what the feature or bug is about
+   - **Acceptance Criteria**: the specific conditions that must be met (look for "AC:", "Given/When/Then", checkboxes, numbered criteria)
+   - **User Story**: "As a [role] I want [action] so that [benefit]"
+   - **Edge Cases**: any mentioned edge cases, error states, or constraints
+   - **Priority**: ticket priority if available (maps to test priority P0/P1/P2)
+
+4. Read the dev repo source code related to the ticket:
+   - Search for files matching keywords from the ticket title
+   - Read routes, controllers, services, models related to the feature
+   - Identify the actual implementation (or lack of it if the feature is not built yet)
+
+5. Generate test cases that map 1:1 to acceptance criteria:
+   - Each acceptance criterion becomes at least one test case
+   - Add negative tests for each criterion (what should NOT happen)
+   - Add edge case tests if mentioned in the ticket
+   - Every test case follows CLAUDE.md rules: unique ID, concrete inputs, explicit expected outcome
+
+6. Write TEST_CASES_FROM_TICKET.md with:
+   ```markdown
+   # Test Cases from Ticket: [TICKET-ID] [Title]
+
+   ## Source
+   - Ticket: [URL or "manual input"]
+   - Date: [YYYY-MM-DD]
+
+   ## Acceptance Criteria Mapping
+
+   | AC # | Criterion | Test ID(s) | Status |
+   |------|-----------|------------|--------|
+   | AC-1 | [criterion text] | UT-XXX-001, E2E-XXX-001 | Covered |
+   | AC-2 | [criterion text] | API-XXX-001 | Covered |
+
+   ## Test Cases
+   [test cases following CLAUDE.md format]
+   ```
+
+7. Generate executable test files using the qa-template-engine skill.
+
+8. Validate generated tests using the qa-self-validator skill.
+
+9. Present summary:
+   - How many acceptance criteria found
+   - How many test cases generated (by pyramid level)
+   - Traceability: every AC is covered
+   - Any ACs that could not be tested (and why)
+
+$ARGUMENTS

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

@@ -0,0 +1,54 @@
+# 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)
+
+## What It Produces
+
+- SCAN_MANIFEST.md -- scan of both repositories
+- GAP_ANALYSIS.md -- coverage map, missing tests with IDs, broken tests, quality assessment
+
+## Instructions
+
+1. Read `CLAUDE.md` -- testing pyramid, test spec rules, quality gates.
+2. Invoke scanner agent to scan both repositories:
+
+Task(
+  prompt="
+    <objective>Scan both developer and QA repositories 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 gap mode:
+
+Task(
+  prompt="
+    <objective>Produce GAP_ANALYSIS.md comparing dev repo against QA repo</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: gap
+    </parameters>
+  "
+)
+
+4. Present results. No test generation. No git operations.
+
+$ARGUMENTS

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

@@ -0,0 +1,36 @@
+# 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

@@ -0,0 +1,37 @@
+# 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

@@ -0,0 +1,38 @@
+# 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-start.md

@@ -0,0 +1,33 @@
+# QA Automation -- Full Pipeline
+
+Run the complete QA automation pipeline. Analyzes a repository, generates a standards-compliant test suite, validates it, and delivers everything as a draft PR.
+
+## Usage
+
+/qa-start [--dev-repo <path>] [--qa-repo <path>] [--auto]
+
+- No arguments: uses current directory as dev repo (Option 1)
+- --dev-repo: explicit path to developer repository
+- --qa-repo: path to existing QA repository (triggers Option 2 or 3)
+- --auto: enable auto-advance mode (no pauses at safe checkpoints)
+
+## Instructions
+
+1. Read `CLAUDE.md` -- all QA standards that govern the pipeline.
+2. Read `agents/qa-pipeline-orchestrator.md` -- the pipeline controller.
+3. Invoke the orchestrator:
+
+Task(
+  prompt="
+    <objective>Run complete QA automation pipeline</objective>
+    <execution_context>@agents/qa-pipeline-orchestrator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+$ARGUMENTS

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

@@ -0,0 +1,54 @@
+# Inject Test IDs
+
+Scan frontend source code, audit missing data-testid attributes, and inject them following the naming convention in CLAUDE.md. Creates a separate branch for the changes.
+
+## Usage
+
+/qa-testid <path-to-frontend-source>
+
+- path-to-frontend-source: directory containing React/Vue/Angular/HTML components
+
+## What It Produces
+
+- TESTID_AUDIT_REPORT.md -- coverage score, missing elements, proposed values by priority
+- Modified source files with data-testid attributes injected
+
+## Instructions
+
+1. Read `CLAUDE.md` -- data-testid Convention section for naming rules.
+2. Initialize context:
+   ```bash
+   node bin/qaa-tools.cjs init qa-start --dev-repo [user path]
+   ```
+3. Invoke scanner to identify component files:
+
+Task(
+  prompt="
+    <objective>Scan repository to identify frontend component files</objective>
+    <execution_context>@agents/qaa-scanner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+4. Invoke testid-injector agent:
+
+Task(
+  prompt="
+    <objective>Audit missing data-testid attributes and inject following naming convention</objective>
+    <execution_context>@agents/qaa-testid-injector.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - .qa-output/SCAN_MANIFEST.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+$ARGUMENTS

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

@@ -0,0 +1,54 @@
+# QA Test Validation
+
+Validate existing test files against CLAUDE.md standards. Runs 4-layer validation (syntax, structure, dependencies, logic) and classifies any failures found.
+
+## Usage
+
+/qa-validate <path-to-tests> [--framework <name>]
+
+- path-to-tests: directory or specific test files to validate
+- --framework: override framework auto-detection (playwright, cypress, jest, etc.)
+
+## What It Produces
+
+- VALIDATION_REPORT.md -- pass/fail per file per validation layer, confidence level
+- FAILURE_CLASSIFICATION_REPORT.md -- if failures found, classifies as APP BUG / TEST ERROR / ENV ISSUE / INCONCLUSIVE
+
+## Instructions
+
+1. Read `CLAUDE.md` -- quality gates, locator tiers, assertion rules.
+2. Invoke validator agent:
+
+Task(
+  prompt="
+    <objective>Validate test files with 4-layer validation and produce VALIDATION_REPORT.md</objective>
+    <execution_context>@agents/qaa-validator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: validation
+    </parameters>
+  "
+)
+
+3. If failures detected, invoke bug-detective agent:
+
+Task(
+  prompt="
+    <objective>Classify test failures and auto-fix TEST CODE ERRORS</objective>
+    <execution_context>@agents/qaa-bug-detective.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - .qa-output/VALIDATION_REPORT.md
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+4. Present results. No git operations.
+
+$ARGUMENTS

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

@@ -0,0 +1,58 @@
+# 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