qaa-agent 1.6.3 → 1.7.0

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

package/package.json

@@ -1,41 +1,40 @@
-{
-  "name": "qaa-agent",
-  "version": "1.6.3",
-  "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
-  "bin": {
-    "qaa-agent": "./bin/install.cjs"
-  },
-  "keywords": [
-    "qa",
-    "automation",
-    "testing",
-    "claude-code",
-    "playwright",
-    "jest",
-    "pytest",
-    "ai-agent"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Backhaus7997/qaa-agent.git"
-  },
-  "author": "Backhaus7997",
-  "license": "MIT",
-  "dependencies": {
-    "@playwright/mcp": "latest"
-  },
-  "files": [
-    "bin/",
-    "agents/",
-    "workflows/",
-    "templates/",
-    "docs/",
-    ".claude/commands/",
-    ".claude/skills/",
-    ".claude/settings.json",
-    ".mcp.json",
-    "CLAUDE.md",
-    "CHANGELOG.md",
-    "README.md"
-  ]
-}
+{
+  "name": "qaa-agent",
+  "version": "1.7.0",
+  "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
+  "bin": {
+    "qaa-agent": "./bin/install.cjs"
+  },
+  "keywords": [
+    "qa",
+    "automation",
+    "testing",
+    "claude-code",
+    "playwright",
+    "jest",
+    "pytest",
+    "ai-agent"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/capmation/qaa-testing.git"
+  },
+  "author": "Backhaus7997",
+  "license": "MIT",
+  "dependencies": {
+    "@playwright/mcp": "latest"
+  },
+  "files": [
+    "bin/",
+    "agents/",
+    "workflows/",
+    "templates/",
+    "docs/",
+    "commands/",
+    "skills/",
+    "settings.json",
+    ".mcp.json",
+    "CLAUDE.md",
+    "CHANGELOG.md"
+  ]
+}

package/{.claude/settings.json → settings.json}

@@ -1,20 +1,19 @@
-{
-  "permissions": {
-    "allow": [
-      "Bash(*)",
-      "Read",
-      "Write",
-      "Edit",
-      "Glob",
-      "Grep",
-      "Agent",
-      "WebFetch",
-      "WebSearch",
-      "NotebookEdit",
-      "mcp__playwright__*"
-    ]
-  },
-  "env": {
-    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
-  }
-}
+{
+  "permissions": {
+    "allow": [
+      "Bash(*)",
+      "Read",
+      "Write",
+      "Edit",
+      "Glob",
+      "Grep",
+      "Agent",
+      "WebFetch",
+      "WebSearch",
+      "NotebookEdit"
+    ]
+  },
+  "env": {
+    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
+  }
+}

package/{.claude/skills → skills}/qa-bug-detective/SKILL.md

@@ -1,122 +1,122 @@
----
-name: qa-bug-detective
-description: QA Bug Detective. Runs generated tests and classifies failures as APPLICATION BUG, TEST CODE ERROR, ENVIRONMENT ISSUE, or INCONCLUSIVE with evidence and confidence levels. Use when user wants to run tests and classify results, investigate test failures, determine if failures are bugs or test issues, debug failing tests, triage test results, or understand why tests are failing. Triggers on "run tests", "classify failures", "why is this failing", "test failures", "debug tests", "triage results", "is this a bug or test error", "investigate failures".
----
-
-# QA Bug Detective
-
-## Purpose
-
-Run generated tests and classify every failure into one of four categories with evidence and confidence levels. Auto-fix TEST CODE ERRORS when confidence is HIGH.
-
-## Classification Decision Tree
-
-```
-Test fails
-├── Syntax/import error in TEST file?
-│   └── YES → TEST CODE ERROR
-├── Error occurs in PRODUCTION code path?
-│   ├── Known bug / unexpected behavior? → APPLICATION BUG
-│   └── Code works as designed but test expectation wrong? → TEST CODE ERROR
-├── Connection refused / timeout / missing env var?
-│   └── YES → ENVIRONMENT ISSUE
-└── Can't determine?
-    └── INCONCLUSIVE
-```
-
-## Classification Categories
-
-### APPLICATION BUG
-- Error manifests in production code (not test code)
-- Stack trace points to src/ or app/ code
-- Behavior contradicts documented requirements or API contracts
-- **Action**: Report only. NEVER auto-fix application code.
-
-### TEST CODE ERROR
-- Import/require fails (wrong path, missing module)
-- Selector doesn't match current DOM
-- Assertion expects wrong value (test written incorrectly)
-- Missing await, wrong API usage, stale fixture reference
-- **Action**: Auto-fix if HIGH confidence. Report if MEDIUM or lower.
-
-### ENVIRONMENT ISSUE
-- Connection refused (database, API, external service)
-- Timeout waiting for resource
-- Missing environment variable
-- File/directory not found (test infrastructure)
-- **Action**: Report with suggested resolution steps.
-
-### INCONCLUSIVE
-- Error is ambiguous
-- Could be multiple root causes
-- Insufficient data to classify
-- **Action**: Report with what's known, request more info.
-
-## Evidence Requirements
-
-Every classification MUST include:
-1. **File path**: Exact file where error occurs
-2. **Line number**: Specific line of failure
-3. **Error message**: Complete error text
-4. **Code snippet**: The specific code proving the classification
-5. **Confidence level**: HIGH / MEDIUM-HIGH / MEDIUM / LOW
-6. **Reasoning**: Why this classification, not another
-
-## Confidence Levels
-
-| Level | Definition |
-|-------|------------|
-| HIGH | Clear evidence in one direction, no ambiguity |
-| MEDIUM-HIGH | Strong evidence but minor ambiguity |
-| MEDIUM | Evidence points one way but alternatives exist |
-| LOW | Insufficient data, multiple possible causes |
-
-## Auto-Fix Rules
-
-Only auto-fix when:
-- Classification = TEST CODE ERROR
-- Confidence = HIGH
-- Fix is mechanical (import path, selector, assertion value, config)
-
-Fix types:
-- Import path corrections
-- Selector updates (match current DOM/data-testid)
-- Assertion value updates (match current actual behavior)
-- Config fixes (baseURL, timeout values)
-- Missing await keywords
-- Fixture path corrections
-
-**NEVER auto-fix**: Application bugs, environment issues, anything with confidence < HIGH.
-
-## Output: FAILURE_CLASSIFICATION_REPORT.md
-
-```markdown
-# Failure Classification Report
-
-## Summary
-| Classification | Count | Auto-Fixed | Needs Attention |
-|---------------|-------|-----------|----------------|
-| APPLICATION BUG | N | 0 | N |
-| TEST CODE ERROR | N | N | N |
-| ENVIRONMENT ISSUE | N | 0 | N |
-| INCONCLUSIVE | N | 0 | N |
-
-## Detailed Analysis
-
-### Failure 1: [test name]
-- **Classification**: [category]
-- **Confidence**: [level]
-- **File**: [path]:[line]
-- **Error**: [message]
-- **Evidence**: [code snippet + reasoning]
-- **Action Taken**: [auto-fixed / reported]
-- **Resolution**: [what was fixed / what needs human attention]
-```
-
-## Quality Gate
-
-- [ ] Every failure classified with evidence
-- [ ] Confidence level assigned to each
-- [ ] No application bugs auto-fixed
-- [ ] Auto-fixes only applied at HIGH confidence
-- [ ] FAILURE_CLASSIFICATION_REPORT.md produced
+---
+name: qa-bug-detective
+description: QA Bug Detective. Runs generated tests and classifies failures as APPLICATION BUG, TEST CODE ERROR, ENVIRONMENT ISSUE, or INCONCLUSIVE with evidence and confidence levels. Use when user wants to run tests and classify results, investigate test failures, determine if failures are bugs or test issues, debug failing tests, triage test results, or understand why tests are failing. Triggers on "run tests", "classify failures", "why is this failing", "test failures", "debug tests", "triage results", "is this a bug or test error", "investigate failures".
+---
+
+# QA Bug Detective
+
+## Purpose
+
+Run generated tests and classify every failure into one of four categories with evidence and confidence levels. Auto-fix TEST CODE ERRORS when confidence is HIGH.
+
+## Classification Decision Tree
+
+```
+Test fails
+├── Syntax/import error in TEST file?
+│   └── YES → TEST CODE ERROR
+├── Error occurs in PRODUCTION code path?
+│   ├── Known bug / unexpected behavior? → APPLICATION BUG
+│   └── Code works as designed but test expectation wrong? → TEST CODE ERROR
+├── Connection refused / timeout / missing env var?
+│   └── YES → ENVIRONMENT ISSUE
+└── Can't determine?
+    └── INCONCLUSIVE
+```
+
+## Classification Categories
+
+### APPLICATION BUG
+- Error manifests in production code (not test code)
+- Stack trace points to src/ or app/ code
+- Behavior contradicts documented requirements or API contracts
+- **Action**: Report only. NEVER auto-fix application code.
+
+### TEST CODE ERROR
+- Import/require fails (wrong path, missing module)
+- Selector doesn't match current DOM
+- Assertion expects wrong value (test written incorrectly)
+- Missing await, wrong API usage, stale fixture reference
+- **Action**: Auto-fix if HIGH confidence. Report if MEDIUM or lower.
+
+### ENVIRONMENT ISSUE
+- Connection refused (database, API, external service)
+- Timeout waiting for resource
+- Missing environment variable
+- File/directory not found (test infrastructure)
+- **Action**: Report with suggested resolution steps.
+
+### INCONCLUSIVE
+- Error is ambiguous
+- Could be multiple root causes
+- Insufficient data to classify
+- **Action**: Report with what's known, request more info.
+
+## Evidence Requirements
+
+Every classification MUST include:
+1. **File path**: Exact file where error occurs
+2. **Line number**: Specific line of failure
+3. **Error message**: Complete error text
+4. **Code snippet**: The specific code proving the classification
+5. **Confidence level**: HIGH / MEDIUM-HIGH / MEDIUM / LOW
+6. **Reasoning**: Why this classification, not another
+
+## Confidence Levels
+
+| Level | Definition |
+|-------|------------|
+| HIGH | Clear evidence in one direction, no ambiguity |
+| MEDIUM-HIGH | Strong evidence but minor ambiguity |
+| MEDIUM | Evidence points one way but alternatives exist |
+| LOW | Insufficient data, multiple possible causes |
+
+## Auto-Fix Rules
+
+Only auto-fix when:
+- Classification = TEST CODE ERROR
+- Confidence = HIGH
+- Fix is mechanical (import path, selector, assertion value, config)
+
+Fix types:
+- Import path corrections
+- Selector updates (match current DOM/data-testid)
+- Assertion value updates (match current actual behavior)
+- Config fixes (baseURL, timeout values)
+- Missing await keywords
+- Fixture path corrections
+
+**NEVER auto-fix**: Application bugs, environment issues, anything with confidence < HIGH.
+
+## Output: FAILURE_CLASSIFICATION_REPORT.md
+
+```markdown
+# Failure Classification Report
+
+## Summary
+| Classification | Count | Auto-Fixed | Needs Attention |
+|---------------|-------|-----------|----------------|
+| APPLICATION BUG | N | 0 | N |
+| TEST CODE ERROR | N | N | N |
+| ENVIRONMENT ISSUE | N | 0 | N |
+| INCONCLUSIVE | N | 0 | N |
+
+## Detailed Analysis
+
+### Failure 1: [test name]
+- **Classification**: [category]
+- **Confidence**: [level]
+- **File**: [path]:[line]
+- **Error**: [message]
+- **Evidence**: [code snippet + reasoning]
+- **Action Taken**: [auto-fixed / reported]
+- **Resolution**: [what was fixed / what needs human attention]
+```
+
+## Quality Gate
+
+- [ ] Every failure classified with evidence
+- [ ] Confidence level assigned to each
+- [ ] No application bugs auto-fixed
+- [ ] Auto-fixes only applied at HIGH confidence
+- [ ] FAILURE_CLASSIFICATION_REPORT.md produced