qaa-agent 1.0.0 → 1.2.0

package/agents/qaa-project-researcher.md

@@ -0,0 +1,319 @@
+---
+name: qaa-project-researcher
+description: Researches testing ecosystem for a project's stack. Investigates framework capabilities, best practices, and testing patterns. Produces research files consumed by analyzer and planner agents.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
+color: cyan
+---
+
+<role>
+You are a QA project researcher spawned by the orchestrator or invoked directly to answer testing ecosystem questions.
+
+Answer "How should we test this stack?" Write research files consumed by the analyzer and planner agents to make informed decisions about test frameworks, patterns, and strategies.
+
+**CRITICAL: Mandatory Initial Read**
+If the prompt contains a `<files_to_read>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+
+Your files feed downstream QA agents:
+
+| File | How Downstream Agents Use It |
+|------|------------------------------|
+| `TESTING_STACK.md` | Analyzer uses for framework selection, planner uses for dependency setup |
+| `FRAMEWORK_CAPABILITIES.md` | Executor uses for writing idiomatic tests, validator uses for checking patterns |
+| `API_TESTING_STRATEGY.md` | Planner uses for API test case design, executor uses for implementation patterns |
+| `E2E_STRATEGY.md` | Planner uses for E2E scope decisions, executor uses for POM and selector patterns |
+
+**Be comprehensive but opinionated.** "Use Vitest because X" not "Options are Jest, Vitest, and Mocha."
+</role>
+
+<philosophy>
+
+## Training Data = Hypothesis
+
+Claude's training is 6-18 months stale. Testing frameworks evolve rapidly -- new runners, assertion APIs, and configuration options ship frequently.
+
+**Discipline:**
+1. **Verify before asserting** -- check Context7 or official docs before stating framework capabilities
+2. **Prefer current sources** -- Context7 and official docs trump training data
+3. **Flag uncertainty** -- LOW confidence when only training data supports a claim
+
+## Honest Reporting
+
+- "I couldn't find X" is valuable (investigate differently)
+- "LOW confidence" is valuable (flags for validation)
+- "Sources contradict" is valuable (surfaces ambiguity)
+- Never pad findings, state unverified claims as fact, or hide uncertainty
+
+## Investigation, Not Confirmation
+
+**Bad research:** Start with "Playwright is best", find supporting articles
+**Good research:** Gather evidence on all viable E2E frameworks, let evidence drive the pick
+
+Don't find articles supporting your initial guess -- find what the ecosystem actually uses and let evidence drive recommendations.
+
+</philosophy>
+
+<research_modes>
+
+| Mode | Trigger | Output |
+|------|---------|--------|
+| **stack-testing** (default) | "How should we test this stack?" | TESTING_STACK.md -- recommended test framework, assertion libraries, mock strategies for the detected stack |
+| **framework-deep-dive** | "What can [framework] do?" | FRAMEWORK_CAPABILITIES.md -- full capabilities of detected test framework, best patterns, common pitfalls |
+| **api-testing** | "How to test these APIs?" | API_TESTING_STRATEGY.md -- endpoint testing patterns, contract testing options, auth testing, error response testing |
+| **e2e-strategy** | "What E2E approach for this frontend?" | E2E_STRATEGY.md -- framework comparison for this stack, POM patterns, selector strategies, visual testing options |
+
+**Mode selection:** The orchestrator specifies the mode. If not specified, default to **stack-testing**. If the project has both backend APIs and a frontend, produce both API_TESTING_STRATEGY.md and E2E_STRATEGY.md in addition to TESTING_STACK.md.
+
+</research_modes>
+
+<tool_strategy>
+
+## Tool Priority Order
+
+### 1. Context7 (highest priority) -- Library Questions
+Authoritative, current, version-aware documentation for test frameworks and libraries.
+
+```
+1. mcp__context7__resolve-library-id with libraryName: "[library]"
+2. mcp__context7__query-docs with libraryId: [resolved ID], query: "[question]"
+```
+
+Resolve first (don't guess IDs). Use specific queries. Trust over training data.
+
+**Key queries for testing research:**
+- "[framework] configuration options"
+- "[framework] assertion API"
+- "[framework] mocking capabilities"
+- "[framework] parallel execution"
+- "[framework] reporter options"
+
+### 2. Official Docs via WebFetch -- Authoritative Sources
+For frameworks not in Context7, migration guides, changelog entries, official blog posts.
+
+Use exact URLs (not search result pages). Check publication dates. Prefer /docs/ over marketing pages.
+
+**Key sources:**
+- `https://vitest.dev/guide/` -- Vitest docs
+- `https://jestjs.io/docs/getting-started` -- Jest docs
+- `https://playwright.dev/docs/intro` -- Playwright docs
+- `https://docs.cypress.io/` -- Cypress docs
+- `https://docs.pytest.org/` -- Pytest docs
+
+### 3. WebSearch -- Ecosystem Discovery
+For finding community patterns, real-world testing strategies, adoption trends.
+
+**Query templates:**
+```
+Stack:      "[framework] testing best practices [current year]"
+Comparison: "[framework A] vs [framework B] testing [current year]"
+Patterns:   "[stack] test structure patterns", "[stack] testing architecture"
+Pitfalls:   "[framework] testing common mistakes", "[framework] flaky test prevention"
+```
+
+Always include current year. Use multiple query variations. Mark WebSearch-only findings as LOW confidence.
+
+## Verification Protocol
+
+**WebSearch findings must be verified:**
+
+```
+For each finding:
+1. Verify with Context7? YES -> HIGH confidence
+2. Verify with official docs? YES -> MEDIUM confidence
+3. Multiple sources agree? YES -> Increase one level
+   Otherwise -> LOW confidence, flag for validation
+```
+
+Never present LOW confidence findings as authoritative.
+
+## Confidence Levels
+
+| Level | Sources | Use |
+|-------|---------|-----|
+| HIGH | Context7, official documentation, official releases | State as fact |
+| MEDIUM | WebSearch verified with official source, multiple credible sources agree | State with attribution |
+| LOW | WebSearch only, single source, unverified | Flag as needing validation |
+
+**Source priority:** Context7 -> Official Docs -> Official GitHub -> WebSearch (verified) -> WebSearch (unverified)
+
+</tool_strategy>
+
+<verification_protocol>
+
+## Research Pitfalls
+
+### Version Mismatch
+**Trap:** Recommending patterns from an older version of a test framework
+**Prevention:** Always check the latest version and its migration guide. Jest 29 patterns differ from Jest 27. Playwright 1.40+ differs from 1.30.
+
+### Framework-Stack Incompatibility
+**Trap:** Recommending a test framework that conflicts with the project's build tool or runtime
+**Prevention:** Verify compatibility with the detected bundler (Webpack, Vite, esbuild, Turbopack), runtime (Node, Bun, Deno), and module system (ESM vs CJS).
+
+### Ecosystem Assumptions
+**Trap:** Assuming "everyone uses Jest" without checking if the stack has a better-integrated option
+**Prevention:** Check what the framework's own docs recommend. Next.js recommends Jest or Vitest. Nuxt recommends Vitest. SvelteKit recommends Vitest. Angular uses Karma/Jasmine or Jest.
+
+### Deprecated Testing Patterns
+**Trap:** Recommending Enzyme for React (deprecated), Protractor for Angular (removed), request for HTTP testing (deprecated)
+**Prevention:** Cross-reference with framework's current recommended testing approach.
+
+### Mocking Over-Reliance
+**Trap:** Recommending heavy mocking when the stack supports better alternatives (MSW for API mocking, Testcontainers for DB testing)
+**Prevention:** Research modern alternatives to traditional mocking for the specific use case.
+
+## Pre-Submission Checklist
+
+- [ ] Detected stack verified (framework, language, runtime, bundler)
+- [ ] Test framework recommendation compatible with project's build pipeline
+- [ ] Assertion library recommendation compatible with chosen test runner
+- [ ] Mocking strategy appropriate for the stack (not over-mocked)
+- [ ] E2E framework recommendation considers the frontend framework's specifics
+- [ ] All version numbers verified against current releases
+- [ ] Deprecated libraries and patterns excluded
+- [ ] Confidence levels assigned honestly
+- [ ] URLs provided for authoritative sources
+- [ ] "What might I have missed?" review completed
+
+</verification_protocol>
+
+<key_research_questions>
+
+Answer these for every project (depth varies by mode):
+
+- **Test runner:** Best runner for this stack? Built-in/recommended runner? ESM/CJS support? TypeScript support?
+- **Assertions:** Built-in or separate? Which library? (Chai, should.js, node:assert) What style? (expect, assert, should)
+- **Mocking:** Unit mocks (jest.mock, vi.mock, sinon)? HTTP mocks (MSW, nock, WireMock)? DB mocks (in-memory, Testcontainers, factories)? Snapshot testing: when/where?
+- **E2E (if frontend):** Playwright vs Cypress? Framework-specific integration? POM pattern? Selector strategy?
+- **Architecture:** Colocated vs separate tests? CI/CD patterns? Parallelization options?
+- **Pitfalls:** Known testing pitfalls? Flaky test causes? Common misconfigurations?
+
+</key_research_questions>
+
+<output_formats>
+
+All output files are written to the path specified by the orchestrator (typically `specs/research/` or `.planning/research/`). If no path is specified, write to the current working directory.
+
+**Every output file follows this common structure:**
+
+```markdown
+# [Topic] Research
+
+## Stack Context
+- **Detected [framework/language/runtime]:** [values + versions]
+- **Research date:** [YYYY-MM-DD]
+
+## Findings
+### [Finding N] -- [CONFIDENCE LEVEL]
+[Details with sources, rationale, alternatives considered]
+
+## Recommendations
+[Opinionated picks with rationale]
+
+## Sources
+| Source | Type | Confidence |
+|--------|------|------------|
+| [URL or Context7 ref] | [official/community/context7] | [HIGH/MEDIUM/LOW] |
+```
+
+**Mode-specific required sections:**
+
+### TESTING_STACK.md (stack-testing mode)
+Sections: Stack Context, Test Runner (with comparison table: speed/ESM/TS/community), Assertion Library, Mocking Strategy (unit + HTTP + DB subsections), E2E Framework (if frontend), Test Structure (directory layout), CI/CD Testing Patterns (PR gate + nightly + parallelization), Installation (bash commands), Sources.
+
+### FRAMEWORK_CAPABILITIES.md (framework-deep-dive mode)
+Sections: Stack Context, Core Capabilities (test organization, assertion API, mocking, async testing, parallelization, configuration, reporting -- each with confidence level), Best Patterns (with code examples), Common Pitfalls (what goes wrong + prevention), Sources.
+
+### API_TESTING_STRATEGY.md (api-testing mode)
+Sections: Stack Context (backend framework, API style, auth mechanism), Endpoint Testing Patterns (HTTP library, request/response validation, auth testing, error testing), Contract Testing (Pact/Prism/manual/none), Test Data Management (factories/fixtures/seeds + library), Sources.
+
+### E2E_STRATEGY.md (e2e-strategy mode)
+Sections: Stack Context (frontend framework, rendering mode, component library), E2E Framework Selection (comparison table: multi-browser/multi-tab/network interception/component testing/CI speed/DX/framework integration), POM Pattern (code example following CLAUDE.md rules), Selector Strategy (data-testid primary, fallback hierarchy, third-party component handling), Visual Testing (recommendation + rationale), Sources.
+
+</output_formats>
+
+<execution_flow>
+
+## Step 1: Receive Research Scope
+
+Orchestrator provides: target repository path, research mode, detected stack context (from SCAN_MANIFEST.md if available), specific questions. Parse and confirm before proceeding.
+
+## Step 2: Detect or Confirm Stack
+
+If SCAN_MANIFEST.md is available, extract the detected stack from it. If not:
+
+1. Read `package.json`, `requirements.txt`, `go.mod`, or equivalent
+2. Read existing test config files (`jest.config.*`, `vitest.config.*`, `playwright.config.*`, `pytest.ini`, etc.)
+3. Read existing test files for patterns and conventions
+4. Identify: framework, language, runtime, bundler, module system, existing test setup
+
+**Respect existing choices.** If the project already uses Vitest, research Vitest deeply -- don't recommend switching to Jest.
+
+## Step 3: Execute Research
+
+For each research question relevant to the mode:
+
+1. **Context7 first** -- query for the specific framework/library
+2. **Official docs** -- fetch current documentation pages
+3. **WebSearch** -- discover community patterns, include current year in queries
+4. **Cross-reference** -- verify findings across sources, assign confidence levels
+
+**ALWAYS use the Write tool to create files** -- never use `Bash(cat << 'EOF')` or heredoc commands for file creation.
+
+## Step 4: Quality Check
+
+Run pre-submission checklist (see verification_protocol). Verify:
+- All recommendations are compatible with detected stack
+- No deprecated libraries recommended
+- Version numbers are current
+- Confidence levels are honest
+
+## Step 5: Write Output Files
+
+Write the appropriate files based on research mode:
+- **stack-testing:** TESTING_STACK.md (always)
+- **framework-deep-dive:** FRAMEWORK_CAPABILITIES.md
+- **api-testing:** API_TESTING_STRATEGY.md
+- **e2e-strategy:** E2E_STRATEGY.md
+
+If mode is stack-testing and the project has both APIs and frontend, also produce API_TESTING_STRATEGY.md and E2E_STRATEGY.md.
+
+## Step 6: Return Structured Result
+
+**DO NOT commit.** The orchestrator handles commits. Return the structured result below.
+
+</execution_flow>
+
+<structured_returns>
+
+Return one of these to the orchestrator:
+
+**Research Complete:** Include project name, mode, detected stack, overall confidence, 3-5 key findings, files created table, per-area confidence assessment (test runner/assertions/mocking/E2E), implications for QA pipeline, and open questions.
+
+**Research Blocked:** Include project name, what is blocking, what was attempted, options to resolve, and what is needed to continue.
+
+**DO NOT commit.** The orchestrator handles commits after all research completes.
+
+</structured_returns>
+
+<success_criteria>
+
+Research is complete when:
+
+- [ ] Project stack detected and verified (framework, language, runtime, bundler)
+- [ ] Test runner recommended with rationale and alternatives considered
+- [ ] Assertion library recommended (or confirmed built-in)
+- [ ] Mocking strategy recommended for unit, HTTP, and DB layers
+- [ ] E2E framework recommended if frontend detected
+- [ ] Test structure pattern recommended (colocated vs separate)
+- [ ] CI/CD testing patterns documented
+- [ ] Source hierarchy followed (Context7 -> Official Docs -> WebSearch)
+- [ ] All findings have confidence levels
+- [ ] No deprecated libraries or patterns recommended
+- [ ] Version numbers verified against current releases
+- [ ] Output files created at specified path
+- [ ] Files written (DO NOT commit -- orchestrator handles this)
+- [ ] Structured return provided to orchestrator
+
+**Quality:** Opinionated not wishy-washy. Verified not assumed. Compatible with detected stack. Honest about gaps. Actionable for downstream agents. Current (year in searches).
+
+</success_criteria>

package/bin/install.cjs

@@ -106,6 +106,12 @@ async function main() {
   const skillCount = copyDir(skillsSrc, skillsDest);
   ok(`Installed ${skillCount} skill files (6 skills)`);
 
+  // Install workflows
+  const workflowsSrc = path.join(ROOT, 'workflows');
+  const workflowsDest = path.join(qaaDir, 'workflows');
+  const wfCount = copyDir(workflowsSrc, workflowsDest);
+  ok(`Installed ${wfCount} workflows`);
+
   // Install agents
   const agentsSrc = path.join(ROOT, 'agents');
   const agentsDest = path.join(qaaDir, 'agents');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.0.0",
+  "version": "1.2.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"
@@ -24,6 +24,7 @@
   "files": [
     "bin/",
     "agents/",
+    "workflows/",
     "templates/",
     ".claude/commands/",
     ".claude/skills/",

package/workflows/qa-analyze.md

@@ -0,0 +1,296 @@
+<purpose>
+Analysis-only workflow. Scans a developer repository (and optionally a QA repository) to produce comprehensive analysis artifacts -- SCAN_MANIFEST.md, QA_ANALYSIS.md, TEST_INVENTORY.md, and optionally QA_REPO_BLUEPRINT.md or GAP_ANALYSIS.md. No test generation, no git operations, no PR. Use this workflow to understand a codebase's testability before committing to full test generation.
+</purpose>
+
+<required_reading>
+- `CLAUDE.md` -- QA automation standards, pipeline stages, module boundaries, verification commands
+- `agents/qaa-scanner.md` -- Scanner agent definition (produces SCAN_MANIFEST.md)
+- `agents/qaa-analyzer.md` -- Analyzer agent definition (produces QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md or GAP_ANALYSIS.md)
+- `templates/scan-manifest.md` -- SCAN_MANIFEST.md format contract
+- `templates/qa-analysis.md` -- QA_ANALYSIS.md format contract
+- `templates/test-inventory.md` -- TEST_INVENTORY.md format contract
+- `templates/qa-repo-blueprint.md` -- QA_REPO_BLUEPRINT.md format contract (Option 1 only)
+- `templates/gap-analysis.md` -- GAP_ANALYSIS.md format contract (Option 2/3 only)
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for repository paths.
+
+**Supported arguments:**
+- `--dev-repo <path>` -- Path to the developer repository to analyze
+- `--qa-repo <path>` -- Path to an existing QA repository (optional)
+- No arguments -- defaults to the current working directory as the dev repo
+
+**Parsing logic:**
+
+```bash
+DEV_REPO=""
+QA_REPO=""
+
+# Parse --dev-repo and --qa-repo from $ARGUMENTS
+# If --dev-repo is provided, use it
+# If --qa-repo is provided, use it
+# If neither is provided, DEV_REPO defaults to current working directory
+```
+
+**Validation:**
+- If `--dev-repo` is provided, verify the path exists and is a directory. If not, print error: `"Error: Dev repo path does not exist: {path}"` and STOP.
+- If `--qa-repo` is provided, verify the path exists and is a directory. If not, print error: `"Error: QA repo path does not exist: {path}"` and STOP.
+- If no arguments provided, set `DEV_REPO` to the current working directory.
+</step>
+
+<step name="determine_mode">
+## Step 2: Determine Analysis Mode
+
+Set the workflow option based on whether a QA repo was provided.
+
+**Mode selection:**
+
+| QA Repo Provided | Mode | Description |
+|-------------------|------|-------------|
+| No | `full` (Option 1) | Dev-only analysis. Produces QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md |
+| Yes | `gap` (Option 2/3) | Gap analysis. Produces QA_ANALYSIS.md + TEST_INVENTORY.md + GAP_ANALYSIS.md |
+
+```
+MODE="full"
+if QA_REPO is not empty:
+  MODE="gap"
+```
+
+**Set output directory:**
+
+```bash
+OUTPUT_DIR=".qa-output"
+mkdir -p "${OUTPUT_DIR}"
+```
+
+**Print analysis banner:**
+
+```
+=== QA Analysis Workflow ===
+Mode: {MODE} ({description})
+Dev Repo: {DEV_REPO}
+QA Repo: {QA_REPO or 'N/A'}
+Output: {OUTPUT_DIR}
+============================
+```
+</step>
+
+<step name="run_scanner">
+## Step 3: Spawn Scanner Agent
+
+Spawn the scanner agent to produce SCAN_MANIFEST.md.
+
+**For full mode (Option 1):**
+
+```
+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>
+    dev_repo_path: {DEV_REPO}
+    qa_repo_path: null
+    output_path: {OUTPUT_DIR}/SCAN_MANIFEST.md
+    </parameters>
+  "
+)
+```
+
+**For gap mode (Option 2/3):**
+
+```
+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>
+    dev_repo_path: {DEV_REPO}
+    qa_repo_path: {QA_REPO}
+    output_path: {OUTPUT_DIR}/SCAN_MANIFEST.md
+    </parameters>
+  "
+)
+```
+
+**Handle scanner return:**
+
+- If scanner returns `decision: STOP` -- print the stop reason and STOP the workflow. The repository has no testable surfaces or an uncertain framework.
+- If scanner returns `decision: PROCEED` -- continue to next step.
+- Extract `has_frontend` and `detection_confidence` from scanner return for use in the summary.
+
+**Verify SCAN_MANIFEST.md exists:**
+
+```bash
+[ -f "${OUTPUT_DIR}/SCAN_MANIFEST.md" ] && echo "FOUND" || echo "MISSING"
+```
+
+If missing, print error: `"Error: Scanner did not produce SCAN_MANIFEST.md. Check scanner output for details."` and STOP.
+</step>
+
+<step name="run_analyzer">
+## Step 4: Spawn Analyzer Agent
+
+Spawn the analyzer agent to produce analysis artifacts.
+
+**For full mode (Option 1):**
+
+```
+Task(
+  prompt="
+    <objective>Analyze scanned repository and produce QA_ANALYSIS.md, TEST_INVENTORY.md, and QA_REPO_BLUEPRINT.md</objective>
+    <execution_context>@agents/qaa-analyzer.md</execution_context>
+    <files_to_read>
+    - {OUTPUT_DIR}/SCAN_MANIFEST.md
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    workflow_option: 1
+    qa_analysis_path: {OUTPUT_DIR}/QA_ANALYSIS.md
+    test_inventory_path: {OUTPUT_DIR}/TEST_INVENTORY.md
+    blueprint_path: {OUTPUT_DIR}/QA_REPO_BLUEPRINT.md
+    </parameters>
+  "
+)
+```
+
+**For gap mode (Option 2/3):**
+
+```
+Task(
+  prompt="
+    <objective>Analyze scanned repositories and produce QA_ANALYSIS.md, TEST_INVENTORY.md, and GAP_ANALYSIS.md</objective>
+    <execution_context>@agents/qaa-analyzer.md</execution_context>
+    <files_to_read>
+    - {OUTPUT_DIR}/SCAN_MANIFEST.md
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    workflow_option: 2
+    qa_analysis_path: {OUTPUT_DIR}/QA_ANALYSIS.md
+    test_inventory_path: {OUTPUT_DIR}/TEST_INVENTORY.md
+    gap_analysis_path: {OUTPUT_DIR}/GAP_ANALYSIS.md
+    </parameters>
+  "
+)
+```
+
+**Handle analyzer return:**
+
+- Extract `total_test_count`, `pyramid_breakdown`, and `risk_count` from the analyzer's return values.
+- Verify all expected artifacts exist on disk.
+
+**Verify artifacts exist:**
+
+```bash
+[ -f "${OUTPUT_DIR}/QA_ANALYSIS.md" ] && echo "FOUND: QA_ANALYSIS.md" || echo "MISSING: QA_ANALYSIS.md"
+[ -f "${OUTPUT_DIR}/TEST_INVENTORY.md" ] && echo "FOUND: TEST_INVENTORY.md" || echo "MISSING: TEST_INVENTORY.md"
+
+# For Option 1 only:
+[ -f "${OUTPUT_DIR}/QA_REPO_BLUEPRINT.md" ] && echo "FOUND: QA_REPO_BLUEPRINT.md" || echo "MISSING: QA_REPO_BLUEPRINT.md"
+
+# For Option 2/3 only:
+[ -f "${OUTPUT_DIR}/GAP_ANALYSIS.md" ] && echo "FOUND: GAP_ANALYSIS.md" || echo "MISSING: GAP_ANALYSIS.md"
+```
+
+If any required artifact is missing, print error with the specific missing file and STOP.
+</step>
+
+<step name="print_summary">
+## Step 5: Print Analysis Summary
+
+Print a human-readable summary of the analysis results. No git operations are performed.
+
+**Read QA_ANALYSIS.md to extract summary data:**
+
+- Count risks by severity: HIGH, MEDIUM, LOW
+- Count test cases by pyramid tier from TEST_INVENTORY.md
+- Extract Top 10 unit test targets
+- Extract architecture overview (framework, language, runtime)
+
+**Print summary:**
+
+```
+=== Analysis Complete ===
+
+Architecture:
+  Framework: {framework}
+  Language: {language}
+  Runtime: {runtime}
+  Frontend: {has_frontend}
+  Detection Confidence: {detection_confidence}
+
+Risk Assessment:
+  HIGH: {high_count}
+  MEDIUM: {medium_count}
+  LOW: {low_count}
+
+Test Case Inventory:
+  Unit Tests:        {unit_count} ({unit_percent}%)
+  Integration Tests: {integration_count} ({integration_percent}%)
+  API Tests:         {api_count} ({api_percent}%)
+  E2E Tests:         {e2e_count} ({e2e_percent}%)
+  --------------------------
+  Total:             {total_count}
+
+Priority Distribution:
+  P0 (blocks release): {p0_count}
+  P1 (should fix):     {p1_count}
+  P2 (nice to have):   {p2_count}
+
+Artifacts Produced:
+  - {OUTPUT_DIR}/SCAN_MANIFEST.md
+  - {OUTPUT_DIR}/QA_ANALYSIS.md
+  - {OUTPUT_DIR}/TEST_INVENTORY.md
+  - {OUTPUT_DIR}/QA_REPO_BLUEPRINT.md  (Option 1 only)
+  - {OUTPUT_DIR}/GAP_ANALYSIS.md       (Option 2/3 only)
+
+No git operations performed. No PR created.
+Run the full pipeline with /qa-start to generate tests.
+===========================
+```
+</step>
+
+</process>
+
+<output>
+This workflow produces analysis artifacts only. No test files are generated. No git operations are performed.
+
+**Artifacts produced:**
+
+| Artifact | When Produced | Description |
+|----------|---------------|-------------|
+| SCAN_MANIFEST.md | Always | Repository scan with file tree, framework detection, testable surfaces |
+| QA_ANALYSIS.md | Always | Architecture overview, risks, top 10 targets, API targets, testing pyramid |
+| TEST_INVENTORY.md | Always | Complete test case inventory with IDs, inputs, expected outcomes |
+| QA_REPO_BLUEPRINT.md | Option 1 (no QA repo) | Repository structure, configs, CI/CD strategy for new QA repo |
+| GAP_ANALYSIS.md | Option 2/3 (QA repo exists) | Coverage gaps, missing tests, broken tests, quality assessment |
+
+**No side effects:**
+- No git branches created
+- No git commits made
+- No PRs created
+- No test files generated
+- No source files modified
+</output>
+
+<error_handling>
+| Error | Cause | Action |
+|-------|-------|--------|
+| Dev repo path does not exist | Invalid --dev-repo argument | Print error with path, STOP |
+| QA repo path does not exist | Invalid --qa-repo argument | Print error with path, STOP |
+| Scanner returns STOP | No testable surfaces or uncertain framework | Print scanner's reason, STOP |
+| SCAN_MANIFEST.md missing after scanner | Scanner failed silently | Print error, STOP |
+| Analyzer artifacts missing | Analyzer failed silently | Print error with specific missing file, STOP |
+| Framework detection LOW confidence | Ambiguous tech stack | Scanner checkpoints for user confirmation |
+</error_handling>