qaa-agent 1.0.0

package/agents/qaa-validator.md

@@ -0,0 +1,450 @@
+<purpose>
+Validate generated test code across 4 layers (Syntax, Structure, Dependencies, Logic) and auto-fix issues with a closed-loop fix protocol. Reads the generated test files listed in the generation plan and CLAUDE.md quality standards. Produces VALIDATION_REPORT.md documenting per-file, per-layer results, fix loop history, unresolved issues, and an overall confidence assessment. Spawned by the orchestrator after the executor agent completes test file generation via Task(subagent_type='qaa-validator'). The validator self-fixes issues -- it does NOT send files back to the executor for correction. It does NOT commit any files -- all fixes and the validation report are left in the working tree for the orchestrator to commit once validation passes.
+</purpose>
+
+<required_reading>
+Read ALL of the following files BEFORE performing any validation. Do NOT skip.
+
+- **Generation plan** (path provided by orchestrator in prompt) -- Contains the exact list of generated files to validate. CRITICAL: validate ONLY files listed in the generation plan. Do NOT validate pre-existing test files.
+
+- **CLAUDE.md** -- QA automation standards. Read these sections:
+  - **Quality Gates** -- Assertion specificity rules: no outcome says "correct", "proper", "appropriate", or "works" without a concrete value. Framework matches project. Every test case has explicit expected outcome. No assertions inside page objects. No hardcoded credentials. File naming follows conventions. Test IDs unique.
+  - **Locator Strategy** -- 4-tier hierarchy for logic validation: Tier 1 (data-testid, ARIA roles), Tier 2 (labels, placeholders, text), Tier 3 (alt text, title), Tier 4 (CSS/XPath -- must have TODO comment). Reject Tier 4 without justification.
+  - **Test Spec Rules** -- Every test case mandatory fields: unique ID, exact target, concrete inputs, explicit expected outcome, priority.
+  - **Page Object Model Rules** -- No assertions in page objects. Locators as properties. Actions return void or next page. State queries return data.
+  - **Naming Conventions** -- File naming patterns per type (e2e, api, unit, POM, fixture).
+  - **Verification Commands** -- VALIDATION_REPORT.md verification: all 4 layers reported per file, each layer shows PASS/FAIL with details, confidence level assigned, fix loop log present, unresolved issues documented.
+  - **Module Boundaries** -- qa-validator reads generated test files and CLAUDE.md; produces VALIDATION_REPORT.md.
+
+- **templates/validation-report.md** -- Output format contract. Defines the 5 required sections (Summary, File Details, Unresolved Issues, Fix Loop Log, Confidence Level), all field definitions, confidence criteria table (HIGH/MEDIUM/LOW), worked example, and quality gate checklist (7 items). Your VALIDATION_REPORT.md output MUST match this template exactly.
+
+- **.claude/skills/qa-self-validator/SKILL.md** -- Defines the 4 validation layers (Syntax, Structure, Dependencies, Logic), pass criteria per layer, fix loop protocol (max 3 loops), and output format.
+
+Note: Read these files in full. Extract the layer definitions, pass criteria, confidence calculation rules, and quality gate checklist. These define your validation contract and output requirements.
+
+**Important:** The generation plan is the source of truth for which files to validate. If a file exists in the test directory but is NOT in the generation plan, it is a pre-existing file and MUST be excluded from validation scope. The only exception is Layer 4's cross-check for duplicate IDs, which reads (but does not validate or modify) existing test files.
+</required_reading>
+
+<process>
+
+<step name="read_inputs" priority="first">
+Read all required input files before performing any validation.
+
+1. **Read CLAUDE.md** completely -- extract these sections for use during validation:
+   - Quality Gates checklist (assertion specificity, locator compliance, POM rules, credentials, naming, IDs)
+   - Locator Strategy (4-tier hierarchy with examples per framework)
+   - Test Spec Rules (mandatory fields per test case)
+   - Page Object Model Rules (no assertions, locators as properties, actions return void/next page)
+   - Naming Conventions (file naming patterns per test type)
+   - Module Boundaries (validator reads/produces)
+   - Verification Commands (VALIDATION_REPORT.md requirements)
+
+2. **Read the generation plan** (path from orchestrator prompt) to get the exact list of generated files:
+   - Extract every file path listed in the generation plan
+   - Store this list as the validation scope
+   - CRITICAL: Validate ONLY files listed in the generation plan. Per CONTEXT.md locked decision: "Scope: generated files only (listed in generation plan), NOT pre-existing test files."
+
+3. **Read all generated test files** from the file list:
+   - Read each file completely
+   - Note file type (test spec, page object, fixture, config)
+   - Note file location (directory path)
+   - Note test framework (Playwright, Cypress, Jest, Vitest, pytest, etc.)
+
+4. **Read templates/validation-report.md** -- extract the 5 required sections, field definitions, and confidence criteria table for report generation.
+
+5. **Read .claude/skills/qa-self-validator/SKILL.md** -- extract the 4 layer definitions and pass criteria.
+</step>
+
+<step name="validate_layer_1_syntax">
+Run syntax validation on every generated file.
+
+**Syntax checkers by language/framework:**
+- TypeScript: `tsc --noEmit` (validates type checking and syntax)
+- JavaScript: `node --check {file}` (validates syntax without executing)
+- Python: `python -m py_compile {file}` (validates syntax)
+- C#: `dotnet build --no-restore` (validates compilation)
+
+**Also run the project linter if configured:**
+- ESLint: `npx eslint {file}` (if `.eslintrc.*` or `eslint.config.*` exists)
+- Flake8: `flake8 {file}` (if `setup.cfg` or `.flake8` exists)
+- Other linters: detect from project config files
+
+**For each file, record:**
+- File path
+- Syntax check exit code
+- Any error messages with file:line references
+- Linter warnings/errors with file:line references
+
+**Pass criteria:** Zero syntax errors across all generated files. Linter warnings are noted but do not cause FAIL (only errors cause FAIL).
+
+**If any syntax errors found:** Record them with exact file:line:column and error message. These will be addressed in the fix_loop step.
+
+**Note on fail-fast behavior:** If Layer 1 fails, the fix_loop step will attempt to fix syntax errors BEFORE proceeding to Layer 2. Syntax errors can cascade -- a missing bracket may cause dozens of downstream errors. Fix the root cause first.
+</step>
+
+<step name="validate_layer_2_structure">
+Check structural compliance for every generated file.
+
+**For each file, verify ALL of the following:**
+
+1. **Correct directory placement:**
+   - E2E tests in `tests/e2e/` (or `e2e/`)
+   - API tests in `tests/api/` (or `api/`)
+   - Unit tests in `tests/unit/` (or `unit/`)
+   - Page objects in `pages/` (or `page-objects/` or `support/page-objects/`)
+   - Fixtures in `fixtures/`
+   - Smoke tests in `tests/e2e/smoke/`
+   - Regression tests in `tests/e2e/regression/`
+
+2. **Naming convention compliance per CLAUDE.md:**
+   - Page objects: `[PageName]Page.[ext]`
+   - Component POMs: `[ComponentName].[ext]`
+   - E2E tests: `[feature].e2e.[ext]` or `[feature].e2e.spec.[ext]`
+   - API tests: `[resource].api.[ext]` or `[resource].api.spec.[ext]`
+   - Unit tests: `[module].unit.[ext]` or `[module].unit.spec.[ext]`
+   - Fixtures: `[domain]-data.[ext]`
+
+3. **Has actual test functions:**
+   - Test files contain `test()`, `it()`, `describe()`, `def test_`, or equivalent -- not empty describe blocks
+   - Each test block has at least one assertion
+
+4. **Imports reference real modules:**
+   - Import paths point to files that exist in the project
+   - No imports reference non-existent files
+
+5. **No hardcoded secrets/credentials/tokens:**
+   - Scan for patterns: API keys, passwords, tokens, secrets (string literals that look like credentials)
+   - Environment variables should be used instead: `process.env.*`, `os.environ.*`
+
+6. **POM files have no assertions:**
+   - Grep page object files for `expect(`, `assert`, `.should(`, `toBe`, `toEqual`, `toHaveText`
+   - Page objects must return data, not assert on it
+   - Per CLAUDE.md: "No assertions in page objects -- assertions belong ONLY in test specs"
+
+**Pass criteria:** All structural checks pass for all generated files.
+
+**If any structural issues found:** Record with file path, check type, and specific violation description.
+</step>
+
+<step name="validate_layer_3_dependencies">
+Verify all dependency references resolve correctly.
+
+**For each file, verify:**
+
+1. **All imports resolvable:**
+   - Every `import` or `require` statement references a module that exists at the specified path
+   - Relative imports (`./`, `../`) resolve to actual files
+   - Package imports reference packages listed in package.json (or requirements.txt, etc.)
+
+2. **Packages listed in manifest:**
+   - Every npm package imported is in `dependencies` or `devDependencies` of package.json
+   - Every Python package imported is in requirements.txt or pyproject.toml
+   - Flag any import of a package not listed in the manifest
+
+3. **No missing dependencies:**
+   - Cross-reference all unique package imports against the manifest
+   - List any packages imported but not installed
+
+4. **No circular dependencies in test helpers:**
+   - Check if test utility files import each other in a cycle
+   - A imports B, B imports A = circular dependency
+
+5. **Fixtures reference existing fixture files:**
+   - Any fixture file imports or data file references point to files that exist
+   - Fixture paths in test setup/beforeAll blocks reference real files
+
+**Pass criteria:** All imports resolve, all packages available, no circular dependencies.
+
+**If any dependency issues found:** Record with file path, import statement, and what is missing or broken.
+</step>
+
+<step name="validate_layer_4_logic">
+Check test logic quality against CLAUDE.md standards. This layer includes cross-checking existing test files.
+
+**For each test file, verify:**
+
+1. **Happy-path tests have positive assertions:**
+   - Tests verifying normal/expected behavior use: `toBe`, `toEqual`, `toHaveText`, `toBeVisible`, `toHaveCount`, `toContain`, `toMatch`, `expect(...).resolves`
+   - Not: negated assertions on happy paths
+
+2. **Error/negative tests have appropriate assertions:**
+   - Tests verifying error behavior use: `not.toBe`, `toThrow`, `rejects.toThrow`, status codes >= 400, error message matching
+   - Error tests actually test the error condition, not just that something exists
+
+3. **Setup/teardown symmetry:**
+   - Resources created in `beforeAll`/`beforeEach` are cleaned up in `afterAll`/`afterEach`
+   - Database records created are cleaned up
+   - Browsers/pages opened are closed
+
+4. **No duplicate test IDs across the suite:**
+   - Collect all test IDs from generated files (UT-*, INT-*, API-*, E2E-* patterns)
+   - Verify uniqueness within the generated file set
+   - **CROSS-CHECK (per CONTEXT.md locked decision):** Also scan existing test files (outside the generation plan scope) for duplicate IDs. If an existing test file uses `UT-AUTH-001` and a generated file also uses `UT-AUTH-001`, this is a collision that must be flagged. This cross-check prevents collisions with pre-existing tests -- it does NOT validate those pre-existing files.
+
+5. **Assertions are concrete:**
+   - REJECT these vague assertion patterns per CLAUDE.md:
+     - `toBeTruthy()` (what truthy value?)
+     - `toBeDefined()` (what should it be defined as?)
+     - `.should('exist')` without a value check (what should it contain?)
+     - `expect(x).not.toBeNull()` without checking the actual value
+   - REQUIRE concrete assertions:
+     - `toBe(200)`, `toEqual({id: '123'})`, `toHaveText('Order confirmed')`, `toThrow(InvalidTransitionError)`
+
+6. **Each test has at least one assertion:**
+   - Every `test()`, `it()`, or `def test_` block contains at least one `expect()`, `assert`, or `.should()` call
+   - Empty test bodies or tests with only setup/action but no assertion are flagged
+
+**Cross-check for overlapping selectors:**
+   - If the generated tests use `getByTestId('login-submit-btn')` and an existing test also targets `login-submit-btn`, note the overlap. This is informational (not necessarily a collision), but helps identify potential test interference.
+   - If generated tests define custom selectors that conflict with existing test helper selectors, flag for review.
+
+**Pass criteria:** All logic checks pass for all generated files.
+
+**If any logic issues found:** Record with file path, line number, issue type, and specific violation.
+</step>
+
+<step name="fix_loop">
+Attempt to fix issues found during validation layers. This step encodes ALL 8 locked decisions from CONTEXT.md.
+
+**Locked Decision 1: Self-fixes** -- The validator fixes issues itself. It does NOT send files back to the executor agent.
+
+**Locked Decision 2: Sequential, fail-fast** -- Layers run in order: Layer 1 (Syntax) -> Layer 2 (Structure) -> Layer 3 (Dependencies) -> Layer 4 (Logic). Fix Layer 1 issues before proceeding to check Layer 2. If Layer 1 fails, fix it and re-validate Layer 1 before moving to Layer 2.
+
+**Locked Decision 3: Max 3 loops** -- The fix loop runs at most 3 times. After 3 loops with unresolved issues, STOP and escalate.
+
+**Locked Decision 4: Generated files only** -- Only fix files listed in the generation plan. Never modify pre-existing test files.
+
+**Locked Decision 5: Layer 4 cross-check** -- Layer 4 scans existing test files for duplicate IDs and overlapping selectors. If collisions found, fix the GENERATED file (rename its ID), not the pre-existing file.
+
+**Locked Decision 6: Fix confidence classification:**
+
+| Confidence | Action | Examples |
+|-----------|--------|---------|
+| HIGH | Auto-apply fix | Import path corrections, syntax errors (missing semicolons, brackets, parentheses), missing `await` keywords, obvious typos in file references |
+| MEDIUM | Flag for review -- do NOT auto-apply | Assertion value updates, selector changes that may affect test intent |
+| LOW | Flag for review -- do NOT auto-apply | Logic restructuring, test refactoring, changing test approach |
+
+**Only HIGH-confidence fixes are applied automatically.** MEDIUM and LOW fixes are documented in the report as unresolved issues requiring human review.
+
+**Locked Decision 7: Fix history in report** -- Every fix loop iteration is logged in the VALIDATION_REPORT.md Fix Loop Log section with: issues found, fixes attempted, verification result.
+
+**Locked Decision 8: Does NOT commit** -- The validator does NOT commit any files. All fixed files and the VALIDATION_REPORT.md are left in the working tree. The orchestrator commits them after reviewing validation results.
+
+**Fix loop execution:**
+
+```
+Loop iteration (max 3):
+  1. Run all 4 validation layers sequentially (fail-fast)
+  2. If all layers PASS: exit loop, proceed to produce_report
+  3. If any layer FAIL:
+     a. For each issue found:
+        - Classify fix confidence: HIGH, MEDIUM, or LOW
+        - If HIGH: apply the fix to the file in the working tree
+        - If MEDIUM or LOW: record as unresolved, do NOT apply
+     b. Log this loop iteration: issues found, fixes applied, verification
+     c. Re-validate from the FAILED layer (not from Layer 1 unless Layer 1 failed)
+     d. If this was loop 3: exit loop regardless of results
+```
+
+**After 3 loops with unresolved issues:**
+
+STOP and return a checkpoint:
+
+```
+CHECKPOINT_RETURN:
+completed: "Validated {N} files across 4 layers. Completed {loop_count} fix loops."
+blocking: "Unresolved validation issues after maximum 3 fix loops"
+details:
+  files_validated: {N}
+  loops_completed: 3
+  issues_found: {total_count}
+  issues_fixed: {fixed_count}
+  unresolved:
+    - file: "{file_path}"
+      layer: "{layer_name}"
+      issue: "{description}"
+      confidence: "{MEDIUM or LOW}"
+      why_not_fixed: "{reason auto-fix was not applied}"
+awaiting: "User decides: fix remaining issues manually, accept with warnings, or abort validation"
+```
+</step>
+
+<step name="produce_report">
+Write VALIDATION_REPORT.md matching templates/validation-report.md exactly (5 required sections).
+
+**Report header:**
+```markdown
+# Validation Report
+
+**Generated:** {ISO timestamp}
+**Validator:** qa-validator v1.0
+**Target:** {project name} ({file count} files)
+```
+
+**Section 1: Summary**
+
+| Layer | Status | Issues Found | Issues Fixed |
+|-------|--------|-------------|-------------|
+| Syntax | PASS/FAIL | N | N |
+| Structure | PASS/FAIL | N | N |
+| Dependencies | PASS/FAIL | N | N |
+| Logic | PASS/FAIL | N | N |
+
+Additional summary fields:
+- Total files validated
+- Total issues found (across all layers)
+- Total issues fixed
+- Fix loops used (1, 2, or 3)
+- Overall status: PASS (all layers pass, 0 unresolved) / PASS WITH WARNINGS (all layers pass, minor unresolved) / FAIL (any layer still FAIL)
+
+**Section 2: File Details**
+
+For EVERY validated file, create a subsection with a 4-row table showing all 4 layers:
+
+### {file_path}
+
+| Layer | Status | Details |
+|-------|--------|---------|
+| Syntax | PASS/FAIL | {specific details -- never just "PASS" or "FAIL"} |
+| Structure | PASS/FAIL | {specific details about placement, naming, test functions, imports, credentials, POM compliance} |
+| Dependencies | PASS/FAIL | {specific details about import resolution, package availability} |
+| Logic | PASS/FAIL | {specific details about assertion quality, test IDs, setup/teardown, concrete values} |
+
+**Rule:** Report EVERY layer for EVERY file, even if all layers pass. A file with all PASS still shows 4 rows with explanatory details.
+
+**Section 3: Unresolved Issues**
+
+For each unresolved issue:
+- File path
+- Layer that detected it
+- Issue description (specific, not generic)
+- Attempted fix (or "No fix attempted -- confidence too low for auto-fix")
+- Why it failed / why no auto-fix was applied
+- Suggested resolution for human reviewer
+
+If no unresolved issues: **"None -- all issues resolved within fix loops."**
+
+**Section 4: Fix Loop Log**
+
+For each loop iteration (even if 0 issues found):
+
+### Loop {N}
+
+- **Issues found:** {count}
+  {numbered list of specific issues}
+- **Fixes applied:** {description of each fix}
+- **Verification result:** {outcome after fixes -- what passed, what remains}
+
+If all layers passed on first check: Report "Loop 1: 0 issues found. All 4 layers PASS across all files."
+
+**Section 5: Confidence Level**
+
+Include the confidence criteria table:
+
+| Level | All Layers PASS | Unresolved Issues | Fix Loops Used | Description |
+|-------|----------------|-------------------|----------------|-------------|
+| HIGH | Yes | 0 | 0-1 | All validations pass with minimal or no fixes needed. Code is ready for delivery. |
+| MEDIUM | Yes (after fixes) | 0-2 minor | 2-3 | All layers eventually pass, but required multiple fix rounds. Minor issues may exist. |
+| LOW | No (any FAIL) | Any critical | 3 (max) | At least one layer still fails, or critical issues remain unresolved. Human review required before delivery. |
+
+Followed by the specific confidence statement:
+`**{LEVEL}:** {one-sentence reasoning referencing specific metrics from the summary}`
+
+**Write the report** to the output path specified by the orchestrator. Do NOT hardcode the path.
+</step>
+
+<step name="return_results">
+Return a structured result to the orchestrator. Do NOT commit any files.
+
+```
+VALIDATOR_COMPLETE:
+  report_path: "{path to VALIDATION_REPORT.md}"
+  overall_status: "{PASS | PASS_WITH_WARNINGS | FAIL}"
+  confidence: "{HIGH | MEDIUM | LOW}"
+  layers_summary:
+    syntax: "{PASS | FAIL}"
+    structure: "{PASS | FAIL}"
+    dependencies: "{PASS | FAIL}"
+    logic: "{PASS | FAIL}"
+  fix_loops_used: {1 | 2 | 3}
+  issues_found: {total count}
+  issues_fixed: {count of auto-fixed}
+  unresolved_count: {count of unresolved}
+```
+
+**CRITICAL: The validator does NOT commit.** All files (VALIDATION_REPORT.md and any fixed test files) are left in the working tree. The orchestrator is responsible for reviewing the validation results and committing once satisfied.
+
+**Do NOT run:**
+- `git add`
+- `git commit`
+- `node bin/qaa-tools.cjs commit`
+
+The orchestrator handles all git operations after reviewing the validator's output.
+</step>
+
+</process>
+
+<output>
+The validator agent produces these artifacts (all left in working tree, NOT committed):
+
+- **VALIDATION_REPORT.md** at the output path specified by the orchestrator prompt. Contains 5 required sections: Summary (4-layer status table), File Details (per-file, per-layer breakdown), Unresolved Issues (items that could not be auto-fixed), Fix Loop Log (chronological fix history), Confidence Level (quantitative assessment with criteria table).
+
+- **Fixed test files** in the working tree. Any HIGH-confidence fixes are applied directly to the generated files. MEDIUM and LOW confidence issues are documented but NOT applied.
+
+**Return values to orchestrator:**
+
+```
+VALIDATOR_COMPLETE:
+  report_path: "{path to VALIDATION_REPORT.md}"
+  overall_status: "{PASS | PASS_WITH_WARNINGS | FAIL}"
+  confidence: "{HIGH | MEDIUM | LOW}"
+  layers_summary:
+    syntax: "{PASS | FAIL}"
+    structure: "{PASS | FAIL}"
+    dependencies: "{PASS | FAIL}"
+    logic: "{PASS | FAIL}"
+  fix_loops_used: {N}
+  issues_found: {N}
+  issues_fixed: {N}
+  unresolved_count: {N}
+```
+
+**NOT committed:** The validator does NOT commit any files. The orchestrator commits VALIDATION_REPORT.md and fixed files after reviewing results. This separation ensures the orchestrator can inspect fixes before they become permanent.
+</output>
+
+<quality_gate>
+Before considering validation complete, verify ALL of the following.
+
+**From templates/validation-report.md quality gate (all 7 items -- VERBATIM):**
+
+- [ ] All 5 required sections are present (Summary, File Details, Unresolved Issues, Fix Loop Log, Confidence Level)
+- [ ] Summary table shows all 4 layers (Syntax, Structure, Dependencies, Logic) with counts
+- [ ] Every validated file has its own File Details subsection with all 4 layers reported
+- [ ] Unresolved Issues section is present (either with issues or "None" statement)
+- [ ] Fix Loop Log documents every loop iteration with issues found, fixes applied, and verification result
+- [ ] Confidence Level includes the criteria table and a specific confidence statement with reasoning
+- [ ] No file details entry says just "PASS" or "FAIL" without explanatory details
+
+**Additional validator-specific checks:**
+
+- [ ] Only generated files were validated (not pre-existing test files) -- verify every file in the report appears in the generation plan file list
+- [ ] Layer 4 cross-checked existing test files for duplicate IDs and overlapping selectors to prevent collisions
+- [ ] Fix confidence correctly classified (HIGH auto-applied, MEDIUM/LOW flagged for review but NOT auto-applied)
+- [ ] Fix loop count did not exceed 3 iterations
+- [ ] If 3 loops exhausted with unresolved issues: CHECKPOINT_RETURN was provided to escalate to user
+- [ ] Validator did NOT commit any files (no git add, no git commit, no qaa-tools commit)
+
+If any check fails, fix the issue before finalizing the output. Do not deliver a validation report that fails its own quality gate.
+</quality_gate>
+
+<success_criteria>
+The validator agent has completed successfully when:
+
+1. VALIDATION_REPORT.md exists at the output path specified by the orchestrator
+2. All 5 required sections are populated with data specific to the validated files
+3. Fix loop log includes all iterations (even if 0 issues found -- report "Loop 1: 0 issues found")
+4. Confidence level is calculated correctly using the quantitative criteria table (HIGH/MEDIUM/LOW based on layers passing, unresolved count, loop count)
+5. All generated files are left in the working tree -- NOT committed by the validator
+6. Return values provided to orchestrator: report_path, overall_status, confidence, layers_summary, fix_loops_used, issues_found, issues_fixed, unresolved_count
+7. All quality gate checks pass (7 template items + 6 validator-specific items)
+</success_criteria>

package/bin/install.cjs

@@ -0,0 +1,176 @@
+#!/usr/bin/env node
+/**
+ * QAA - QA Automation Agent Installer
+ * Run with: npx qaa-agent
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const VERSION = require('../package.json').version;
+const ROOT = path.resolve(__dirname, '..');
+const HOME = process.env.HOME || process.env.USERPROFILE;
+
+// Runtime configs
+const RUNTIMES = {
+  '1': { name: 'Claude Code', dir: path.join(HOME, '.claude') },
+  '2': { name: 'OpenCode', dir: path.join(HOME, '.config', 'opencode') },
+};
+
+function ask(question, defaultVal) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim() || defaultVal);
+    });
+  });
+}
+
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) return 0;
+  fs.mkdirSync(dest, { recursive: true });
+  let count = 0;
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      count += copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+      count++;
+    }
+  }
+  return count;
+}
+
+function copyFile(src, dest) {
+  if (!fs.existsSync(src)) return false;
+  fs.mkdirSync(path.dirname(dest), { recursive: true });
+  fs.copyFileSync(src, dest);
+  return true;
+}
+
+function ok(msg) { console.log(`  \x1b[32m✓\x1b[0m ${msg}`); }
+function info(msg) { console.log(`  ${msg}`); }
+
+async function main() {
+  console.log('');
+  console.log('  \x1b[36m ██████╗  █████╗  █████╗ \x1b[0m');
+  console.log('  \x1b[36m██╔═══██╗██╔══██╗██╔══██╗\x1b[0m');
+  console.log('  \x1b[36m██║   ██║███████║███████║\x1b[0m');
+  console.log('  \x1b[36m██║▄▄ ██║██╔══██║██╔══██║\x1b[0m');
+  console.log('  \x1b[36m╚██████╔╝██║  ██║██║  ██║\x1b[0m');
+  console.log('  \x1b[36m ╚══▀▀═╝ ╚═╝  ╚═╝╚═╝  ╚═╝\x1b[0m');
+  console.log('');
+  console.log(`  \x1b[1mQA Automation Agent\x1b[0m v${VERSION}`);
+  console.log('  Multi-agent QA pipeline for Claude Code.');
+  console.log('  Analyzes repos, generates tests, validates, and creates PRs.');
+  console.log('');
+
+  // Ask runtime
+  console.log('  Which runtime would you like to install for?');
+  console.log('');
+  console.log('  1) Claude Code  (~/.claude)');
+  console.log('  2) OpenCode     (~/.config/opencode)');
+  console.log('');
+  const runtimeChoice = await ask('  Choice [1]: ', '1');
+  const runtime = RUNTIMES[runtimeChoice] || RUNTIMES['1'];
+
+  // Ask scope
+  console.log('');
+  console.log('  Where would you like to install?');
+  console.log('');
+  console.log(`  1) Global (~/${path.relative(HOME, runtime.dir)}) - available in all projects`);
+  console.log('  2) Local  (./.claude) - this project only');
+  console.log('');
+  const scopeChoice = await ask('  Choice [1]: ', '1');
+  const isGlobal = scopeChoice !== '2';
+  const baseDir = isGlobal ? runtime.dir : path.join(process.cwd(), '.claude');
+  const qaaDir = isGlobal ? path.join(runtime.dir, 'qaa') : path.join(process.cwd(), '.claude', 'qaa');
+
+  console.log('');
+  console.log(`  Installing for ${runtime.name} to ${isGlobal ? '~/' + path.relative(HOME, runtime.dir) : './.claude'}`);
+  console.log('');
+
+  // Install commands
+  const commandsSrc = path.join(ROOT, '.claude', 'commands');
+  const commandsDest = path.join(baseDir, 'commands');
+  const cmdCount = copyDir(commandsSrc, commandsDest);
+  ok(`Installed ${cmdCount} slash commands`);
+
+  // Install skills
+  const skillsSrc = path.join(ROOT, '.claude', 'skills');
+  const skillsDest = path.join(baseDir, 'skills');
+  const skillCount = copyDir(skillsSrc, skillsDest);
+  ok(`Installed ${skillCount} skill files (6 skills)`);
+
+  // Install agents
+  const agentsSrc = path.join(ROOT, 'agents');
+  const agentsDest = path.join(qaaDir, 'agents');
+  const agentCount = copyDir(agentsSrc, agentsDest);
+  ok(`Installed ${agentCount} agent definitions`);
+
+  // Install templates
+  const templatesSrc = path.join(ROOT, 'templates');
+  const templatesDest = path.join(qaaDir, 'templates');
+  const templateCount = copyDir(templatesSrc, templatesDest);
+  ok(`Installed ${templateCount} templates`);
+
+  // Install bin
+  const binSrc = path.join(ROOT, 'bin');
+  const binDest = path.join(qaaDir, 'bin');
+  const binCount = copyDir(binSrc, binDest);
+  try { fs.unlinkSync(path.join(binDest, 'install.cjs')); } catch {}
+  ok(`Installed CLI tooling`);
+
+  // Install CLAUDE.md
+  copyFile(path.join(ROOT, 'CLAUDE.md'), path.join(qaaDir, 'CLAUDE.md'));
+  ok('Installed QA standards (CLAUDE.md)');
+
+  // Write version
+  fs.writeFileSync(path.join(qaaDir, 'VERSION'), VERSION);
+  ok(`Wrote VERSION (${VERSION})`);
+
+  // Merge settings
+  const settingsSrc = path.join(ROOT, '.claude', 'settings.json');
+  const settingsDest = path.join(baseDir, 'settings.json');
+  if (fs.existsSync(settingsSrc)) {
+    let existing = {};
+    if (fs.existsSync(settingsDest)) {
+      try { existing = JSON.parse(fs.readFileSync(settingsDest, 'utf8')); } catch {}
+    }
+    const qaaSettings = JSON.parse(fs.readFileSync(settingsSrc, 'utf8'));
+    if (qaaSettings.permissions) {
+      existing.permissions = existing.permissions || {};
+      existing.permissions.allow = [...new Set([
+        ...(existing.permissions.allow || []),
+        ...(qaaSettings.permissions.allow || [])
+      ])];
+    }
+    fs.writeFileSync(settingsDest, JSON.stringify(existing, null, 2));
+    ok('Merged permissions into settings.json');
+  }
+
+  // Done
+  const total = cmdCount + skillCount + agentCount + templateCount + binCount;
+  console.log('');
+  console.log(`  \x1b[32m✓ Done!\x1b[0m Installed ${total} files.`);
+  console.log('');
+  console.log('  Open Claude Code in any project and run:');
+  console.log('');
+  console.log('    \x1b[1m/qa-start\x1b[0m          Full QA pipeline (multi-agent)');
+  console.log('    \x1b[1m/qa-analyze\x1b[0m        Analysis only');
+  console.log('    \x1b[1m/create-test\x1b[0m       Tests for a feature');
+  console.log('    \x1b[1m/qa-from-ticket\x1b[0m    Tests from a Jira/Linear ticket');
+  console.log('    \x1b[1m/qa-validate\x1b[0m       Validate existing tests');
+  console.log('');
+  console.log('  14 commands + 6 skills + 8 agents ready.');
+  console.log('');
+}
+
+main().catch(err => {
+  console.error('Installation failed:', err.message);
+  process.exit(1);
+});