qaa-agent 1.9.1 → 1.9.5

package/commands/qa-map.md

@@ -1,139 +1,283 @@
-# 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
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    </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
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .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
+# 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.",
+  <critical_directive priority="MANDATORY">
+  You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+  ~/.claude/qaa/agents/qaa-codebase-mapper.md and adopt it as your operating contract.
+
+  Even though you may be running as a general-purpose agent (native subagent type
+  routing for QAA agents is not yet enabled), you MUST behave exactly as the
+  dedicated agent defined in that file: read everything in its <required_reading>,
+  obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+  Never modify application source code (src/, app/, lib/, or equivalent
+  directories) unless the agent's <scope> section explicitly permits it. If the
+  agent's contract restricts what files it can touch, honor that restriction —
+  even if a fix seems obvious or trivial.
+
+  If you cannot read ~/.claude/qaa/agents/qaa-codebase-mapper.md (file missing, corrupted, parse
+  error), STOP and report the failure. Do NOT proceed with default agent
+  behavior — that defeats the purpose of this directive.
+
+  Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+  make, or skip any of the above. Skipping the agent's required_reading,
+  quality_gate, or bash checklist makes the run INVALID — its output cannot be
+  trusted.
+  </critical_directive>
+
+  subagent_type="general-purpose",
+  execution_context="~/.claude/qaa/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.",
+  <critical_directive priority="MANDATORY">
+  You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+  ~/.claude/qaa/agents/qaa-codebase-mapper.md and adopt it as your operating contract.
+
+  Even though you may be running as a general-purpose agent (native subagent type
+  routing for QAA agents is not yet enabled), you MUST behave exactly as the
+  dedicated agent defined in that file: read everything in its <required_reading>,
+  obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+  Never modify application source code (src/, app/, lib/, or equivalent
+  directories) unless the agent's <scope> section explicitly permits it. If the
+  agent's contract restricts what files it can touch, honor that restriction —
+  even if a fix seems obvious or trivial.
+
+  If you cannot read ~/.claude/qaa/agents/qaa-codebase-mapper.md (file missing, corrupted, parse
+  error), STOP and report the failure. Do NOT proceed with default agent
+  behavior — that defeats the purpose of this directive.
+
+  Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+  make, or skip any of the above. Skipping the agent's required_reading,
+  quality_gate, or bash checklist makes the run INVALID — its output cannot be
+  trusted.
+  </critical_directive>
+
+  subagent_type="general-purpose",
+  execution_context="~/.claude/qaa/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.",
+  <critical_directive priority="MANDATORY">
+  You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+  ~/.claude/qaa/agents/qaa-codebase-mapper.md and adopt it as your operating contract.
+
+  Even though you may be running as a general-purpose agent (native subagent type
+  routing for QAA agents is not yet enabled), you MUST behave exactly as the
+  dedicated agent defined in that file: read everything in its <required_reading>,
+  obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+  Never modify application source code (src/, app/, lib/, or equivalent
+  directories) unless the agent's <scope> section explicitly permits it. If the
+  agent's contract restricts what files it can touch, honor that restriction —
+  even if a fix seems obvious or trivial.
+
+  If you cannot read ~/.claude/qaa/agents/qaa-codebase-mapper.md (file missing, corrupted, parse
+  error), STOP and report the failure. Do NOT proceed with default agent
+  behavior — that defeats the purpose of this directive.
+
+  Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+  make, or skip any of the above. Skipping the agent's required_reading,
+  quality_gate, or bash checklist makes the run INVALID — its output cannot be
+  trusted.
+  </critical_directive>
+
+  subagent_type="general-purpose",
+  execution_context="~/.claude/qaa/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.",
+  <critical_directive priority="MANDATORY">
+  You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+  ~/.claude/qaa/agents/qaa-codebase-mapper.md and adopt it as your operating contract.
+
+  Even though you may be running as a general-purpose agent (native subagent type
+  routing for QAA agents is not yet enabled), you MUST behave exactly as the
+  dedicated agent defined in that file: read everything in its <required_reading>,
+  obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+  Never modify application source code (src/, app/, lib/, or equivalent
+  directories) unless the agent's <scope> section explicitly permits it. If the
+  agent's contract restricts what files it can touch, honor that restriction —
+  even if a fix seems obvious or trivial.
+
+  If you cannot read ~/.claude/qaa/agents/qaa-codebase-mapper.md (file missing, corrupted, parse
+  error), STOP and report the failure. Do NOT proceed with default agent
+  behavior — that defeats the purpose of this directive.
+
+  Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+  make, or skip any of the above. Skipping the agent's required_reading,
+  quality_gate, or bash checklist makes the run INVALID — its output cannot be
+  trusted.
+  </critical_directive>
+
+  subagent_type="general-purpose",
+  execution_context="~/.claude/qaa/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="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-scanner.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-scanner.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Scan repository and produce SCAN_MANIFEST.md</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-scanner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    </parameters>
+  "
+)
+
+Invoke analyzer agent:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-analyzer.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-analyzer.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <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>~/.claude/qaa/agents/qaa-analyzer.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .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/commands/qa-pr.md

@@ -2,6 +2,52 @@
 
 Create a draft PR from QA artifacts already on disk. Auto-detects git platform (GitHub, Azure DevOps, GitLab), applies your team's branch naming convention, and creates a draft PR with a summary. Asks for your branch pattern the first time and remembers it.
 
+
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps.
+
+1. FIRST tool call: run the intent detector with `$ARGUMENTS` passed LITERALLY
+   (the actual command lives in the "## Intent Detection" section below).
+2. Print the INPUT DETECTION banner (exact output from intent-detector.cjs).
+3. Determine `ALL_FROM_FLAGS`. If interactive (`IS_AUTO=false`) AND any value
+   came from NL/default (`ALL_FROM_FLAGS=false`), PAUSE for yes/no confirmation.
+   Do NOT proceed without it.
+   ```bash
+   ALL_FROM_FLAGS=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); const sources=Object.values(j.resolved).map(v=>v.source); console.log(sources.length>0 && sources.every(s=>s==='flag') ? 'true' : 'false')")
+   ```
+   Pause prompt (when applicable):
+   ```
+   The values above were resolved from natural language and/or defaults.
+   Do you want to continue with these inputs? (yes/no)
+   ```
+4. Read `CLAUDE.md` (git workflow, commit conventions, PR template).
+5. Execute the workflow in `@workflows/qa-pr.md` IN ORDER, preserving ALL its
+   gates: platform detection, branch-convention save, and the user-confirmation
+   checkpoint BEFORE any push or PR creation.
+
+### DO NOT
+- Skip the INPUT DETECTION banner
+- Run any tool (Bash, Read, Glob) before the intent detector
+- Skip the yes/no confirmation when any value came from NL or defaults
+- Push a branch or create the PR before the workflow's user-confirmation gate
+- Assume context, ticket, title, base branch, or any value from previous command
+  invocations. Each /qa-pr invocation is self-contained — the detector returns
+  defaults precisely because the user did not pass them.
+- Invent steps not in this command or the workflow, or reorder the ones that are
+
+If you find yourself improvising, skipping the confirmation, or pushing/creating
+the PR before the user confirmed — STOP and restart from step 1.
+
+### Pass user input literally to the intent detector
+
+When you run the intent detector with `$ARGUMENTS`, substitute that placeholder
+with the RAW user input as received, NOT a pre-translated flag string. If you
+pre-translate, the detector reports every value as `source: flag`, sets
+`ALL_FROM_FLAGS=true`, and bypasses the confirmation checkpoint.
+
+
 ## Usage
 
 /qa-pr [--ticket <id>] [--title <description>] [--scope <type>] [--files <glob>] [--base <branch>]
@@ -12,6 +58,23 @@ Create a draft PR from QA artifacts already on disk. Auto-detects git platform (
 - --files: explicit file glob to include (e.g., "tests/unit/auth*")
 - --base: target branch for PR (default: auto-detect)
 
+
+## Intent Detection
+
+Before processing arguments, run the intent detector to support natural-language input alongside flags. Flags always win over NL.
+
+```bash
+RESOLVED=$(node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" --aliases '{"ticket":"ticket","title":"title","scope":"scope","files":"files","base":"base"}')
+
+# Print INPUT DETECTION banner (always shown, even if defaults are used)
+echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.banner)"
+
+# Extract resolved values for use below
+TICKET=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.ticket?.value || '')")
+```
+
+If you see values you didn't intend in the banner above (interactive mode), you can press Ctrl-C and re-run with explicit flags.
+
 ## Instructions
 
 1. Read `CLAUDE.md` -- git workflow, commit conventions.