qaa-agent 1.3.0 → 1.5.0

package/docs/COMMANDS.md

@@ -0,0 +1,341 @@
+# QAA Commands Reference
+
+## When to Use What
+
+```
+"I have a project with no tests"                    → /qa-start
+"I want to understand the codebase first"            → /qa-map
+"I need tests for a specific feature"                → /create-test
+"I have a Jira/Linear ticket to cover"               → /qa-from-ticket
+"I want to check if my tests are good"               → /qa-validate
+"My tests are failing after a deploy"                → /qa-fix
+"I want to ship my tests as a PR"                    → /qa-pr
+"I want a full report for my manager"                → /qa-report
+"I need to know what's missing in our test suite"    → /qa-gap
+"I want to add data-testid to components"            → /qa-testid
+"I need Page Object Models"                          → /qa-pom
+"I want to audit test quality"                       → /qa-audit
+"I need a QA repo structure from scratch"            → /qa-blueprint
+"I want to see our testing pyramid balance"          → /qa-pyramid
+"I want to analyze without generating anything"      → /qa-analyze
+"I want to research best testing practices"          → /qa-research
+"I want to improve existing tests"                   → /update-test
+```
+
+---
+
+## Full Pipeline
+
+### /qa-start
+
+**What it does:** Runs the entire QA automation pipeline end-to-end. Scans the repo, maps the codebase, analyzes architecture, plans test cases, generates test files, validates them, runs E2E tests against the live app, and delivers everything as a draft PR.
+
+**When to use:** Starting QA from scratch on a project, or doing a full gap-fill on an existing QA repo.
+
+```
+/qa-start --dev-repo /path/to/project
+/qa-start --dev-repo /path/to/project --qa-repo /path/to/tests
+/qa-start --dev-repo /path/to/project --auto
+```
+
+**Pipeline:**
+```
+scan → map → analyze → [testid-inject] → plan → generate → validate → [e2e-run] → [bug-detective] → deliver
+```
+
+**Produces:** SCAN_MANIFEST.md, 8 codebase map documents, QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md, test files, POMs, fixtures, VALIDATION_REPORT.md, E2E_RUN_REPORT.md, draft PR.
+
+---
+
+## Discovery & Analysis
+
+### /qa-map
+
+**What it does:** Deep-scans the codebase with 4 parallel agents (testability, risk, patterns, existing tests) and produces 8 documents that become the shared context for all other commands. This is the "brain" of the system.
+
+**When to use:** Before using `/create-test` on a mature project. Run it once, and every subsequent command benefits from the codebase knowledge.
+
+```
+/qa-map
+/qa-map --focus testability
+/qa-map --focus risk
+```
+
+**Produces:** TESTABILITY.md, TEST_SURFACE.md, RISK_MAP.md, CRITICAL_PATHS.md, CODE_PATTERNS.md, API_CONTRACTS.md, TEST_ASSESSMENT.md, COVERAGE_GAPS.md — all in `.qa-output/codebase/`.
+
+---
+
+### /qa-analyze
+
+**What it does:** Scans and analyzes a repository without generating any tests. Produces assessment documents only — architecture overview, risk areas, test inventory with every test case specified, and a testing pyramid recommendation.
+
+**When to use:** You want to understand what needs testing before committing to generation. Good for presenting a plan to the team before executing.
+
+```
+/qa-analyze
+/qa-analyze --dev-repo /path/to/project
+/qa-analyze --dev-repo /path/to/project --qa-repo /path/to/tests
+```
+
+**Produces:** SCAN_MANIFEST.md, QA_ANALYSIS.md, TEST_INVENTORY.md, and either QA_REPO_BLUEPRINT.md (no QA repo) or GAP_ANALYSIS.md (QA repo provided).
+
+---
+
+### /qa-research
+
+**What it does:** Researches the best testing stack, frameworks, and patterns for a specific project. Checks official docs, community best practices, and produces opinionated recommendations with confidence levels.
+
+**When to use:** You're setting up testing for the first time and want to know which framework to use, or you're evaluating whether to switch from Jest to Vitest.
+
+```
+/qa-research
+/qa-research --focus api-testing
+/qa-research --focus e2e-strategy
+```
+
+**Produces:** TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md (depending on mode).
+
+---
+
+### /qa-gap
+
+**What it does:** Compares a dev repo against its QA repo to find coverage gaps. Shows what's tested, what's missing, what's broken, and what's low quality.
+
+**When to use:** You already have tests but suspect there are holes. Want a concrete list of what to add next.
+
+```
+/qa-gap --dev-repo /path/to/project --qa-repo /path/to/tests
+```
+
+**Produces:** GAP_ANALYSIS.md with coverage map, missing tests, broken tests, and prioritized recommendations.
+
+---
+
+### /qa-pyramid
+
+**What it does:** Analyzes the distribution of your test suite against the ideal testing pyramid (60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E). Shows where you're heavy and where you're light.
+
+**When to use:** You want to know if your test suite is balanced or if you're over-invested in E2E and under-invested in unit tests.
+
+```
+/qa-pyramid ./tests
+/qa-pyramid ./tests --dev-repo /path/to/project
+```
+
+**Produces:** PYRAMID_ANALYSIS.md with current vs target distribution and an action plan.
+
+---
+
+## Test Creation
+
+### /create-test
+
+**What it does:** Generates tests for a specific feature or module. Reads the codebase map (if available) to understand the project's code patterns, API contracts, and existing conventions. If E2E tests are generated and an app is running, opens a real browser, captures actual locators from the page, fixes any mismatches, and loops until tests pass.
+
+**When to use:** Daily work. A new feature shipped and you need tests for it.
+
+```
+/create-test login
+/create-test "checkout flow"
+/create-test "user API" --dev-repo /path/to/project
+/create-test login --app-url http://localhost:3000
+/create-test login --skip-run
+```
+
+**Produces:** Test spec files, POMs, fixtures. E2E_RUN_REPORT.md if tests were run against the app.
+
+---
+
+### /qa-from-ticket
+
+**What it does:** Fetches a ticket from Jira, Linear, GitHub Issues, or a file. Extracts acceptance criteria and edge cases. Maps each criterion to test cases with a traceability matrix. Generates test files and validates them.
+
+**When to use:** You work from tickets and want every acceptance criterion to have a corresponding test before the feature ships.
+
+```
+/qa-from-ticket https://company.atlassian.net/browse/PROJ-123
+/qa-from-ticket #456
+/qa-from-ticket ./tickets/feature-spec.md
+/qa-from-ticket "As a user I want to reset my password via email"
+```
+
+**Produces:** TEST_CASES_FROM_TICKET.md (traceability matrix), GENERATION_PLAN_TICKET.md, test files, VALIDATION_REPORT.md.
+
+---
+
+### /qa-pom
+
+**What it does:** Generates Page Object Model files for given pages. Follows CLAUDE.md POM rules: one class per page, no assertions, locators as properties, extends shared base.
+
+**When to use:** You have pages that need POMs but don't want to generate full test suites yet.
+
+```
+/qa-pom ./src/pages
+/qa-pom ./src/pages --framework playwright
+```
+
+**Produces:** POM files in `pages/` directory with BasePage and feature pages.
+
+---
+
+### /qa-testid
+
+**What it does:** Scans frontend source code, audits interactive elements for missing `data-testid` attributes, and injects them following the naming convention (`{context}-{description}-{element-type}` in kebab-case). Creates a separate branch for the changes.
+
+**When to use:** Before writing E2E tests. You want every button, input, and link to have a stable test ID.
+
+```
+/qa-testid ./src/components
+/qa-testid ./src
+```
+
+**Produces:** TESTID_AUDIT_REPORT.md (coverage score, proposed values) and modified source files with `data-testid` attributes.
+
+---
+
+## Validation & Fixing
+
+### /qa-validate
+
+**What it does:** Validates test files against CLAUDE.md standards. Runs 4 static layers (syntax, structure, dependencies, logic) with auto-fix up to 3 loops. Optionally runs E2E tests against a live app to verify locators and assertions with real page data.
+
+**When to use:** After writing or generating tests, before shipping. Or as a quality check on an existing test suite.
+
+```
+/qa-validate ./tests
+/qa-validate ./tests --classify
+/qa-validate ./tests --run --app-url http://localhost:3000
+```
+
+**Produces:** VALIDATION_REPORT.md. FAILURE_CLASSIFICATION_REPORT.md if `--classify` used. E2E_RUN_REPORT.md if `--run` used.
+
+---
+
+### /qa-fix
+
+**What it does:** Diagnoses and fixes broken test files. Reads failing tests, runs them, classifies each failure (app bug vs test code error vs environment issue), and auto-fixes test code errors.
+
+**When to use:** Tests that were passing started failing after a deploy or code change.
+
+```
+/qa-fix ./tests/e2e/checkout*
+/qa-fix ./tests --error "timeout waiting for selector"
+```
+
+**Produces:** Fixed test files. FAILURE_CLASSIFICATION_REPORT.md with evidence for each failure.
+
+---
+
+### /update-test
+
+**What it does:** Improves existing tests without rewriting them. Upgrades locator tiers, makes assertions more specific, fixes naming conventions, adds missing test IDs.
+
+**When to use:** Your tests work but don't follow current standards. You want incremental improvement, not a rewrite.
+
+```
+/update-test ./tests
+/update-test ./tests --scope locators
+/update-test ./tests --scope assertions
+```
+
+**Produces:** Updated test files with improvements applied.
+
+---
+
+## Reporting & Auditing
+
+### /qa-audit
+
+**What it does:** Full 6-dimension quality audit of a test suite. Scores: Locator Quality (20%), Assertion Specificity (20%), POM Compliance (15%), Test Coverage (20%), Naming Convention (15%), Test Data Management (10%). Gives a weighted overall score.
+
+**When to use:** You want a quality score for your test suite with concrete recommendations for improvement.
+
+```
+/qa-audit ./tests
+/qa-audit ./tests --dev-repo /path/to/project
+```
+
+**Produces:** QA_AUDIT_REPORT.md with scores, critical issues, and effort-estimated recommendations (S/M/L).
+
+---
+
+### /qa-report
+
+**What it does:** Generates a QA status report adapted to the audience. Team level gets file-level details. Management gets high-level metrics. Client gets a coverage summary.
+
+**When to use:** Standups, sprint reviews, client updates.
+
+```
+/qa-report ./tests
+/qa-report ./tests --audience management
+/qa-report ./tests --audience client
+```
+
+**Produces:** QA_STATUS_REPORT.md with metrics, pyramid distribution, risk areas, recommendations.
+
+---
+
+### /qa-blueprint
+
+**What it does:** Generates a complete QA repository structure blueprint — recommended stack, folder layout, config files, CI/CD pipeline, npm scripts, and definition of done.
+
+**When to use:** You're starting a QA repo from scratch and want a solid structure before writing the first test.
+
+```
+/qa-blueprint
+/qa-blueprint --dev-repo /path/to/project
+```
+
+**Produces:** SCAN_MANIFEST.md, QA_REPO_BLUEPRINT.md.
+
+---
+
+## Delivery
+
+### /qa-pr
+
+**What it does:** Creates a draft PR from QA artifacts already on disk. Auto-detects git platform (GitHub, Azure DevOps, GitLab). Applies your team's branch naming convention (asks once, remembers forever). Shows what will be committed and waits for your confirmation before pushing.
+
+**When to use:** After generating or fixing tests, you want to package them as a PR.
+
+```
+/qa-pr --ticket PROJ-123 --title "login tests"
+/qa-pr --scope e2e
+/qa-pr --ticket PROJ-456 --title "checkout" --base develop
+```
+
+**Produces:** Git branch (following your convention), commits, draft PR with summary. Returns the PR URL.
+
+---
+
+## Common Flows
+
+### New project, no tests
+```
+/qa-start --dev-repo ./myproject --auto
+```
+
+### Mature project, new feature
+```
+/qa-map                                    # once
+/create-test "password reset"              # generates + runs
+/qa-pr --ticket PROJ-123 "reset tests"     # ships as PR
+```
+
+### From a Jira ticket
+```
+/qa-from-ticket https://jira.company.com/browse/PROJ-456
+/qa-pr --ticket PROJ-456 "login flow"
+```
+
+### Fix broken tests after deploy
+```
+/qa-fix ./tests/e2e/checkout*
+/qa-pr --ticket PROJ-789 "fix checkout tests"
+```
+
+### Quality check before release
+```
+/qa-audit ./tests --dev-repo ./myproject
+/qa-report ./tests --audience management
+```

package/docs/DEMO.md

@@ -0,0 +1,182 @@
+# QAA — QA Automation Agent
+
+## What is it?
+
+QAA is a multi-agent system that automates QA test creation for any software project. You point it at a codebase, and it analyzes the architecture, maps the code, generates a full test suite following industry standards, validates everything, and delivers the result as a draft pull request — ready for review.
+
+No manual test writing. No guessing what to cover. One command, full pipeline.
+
+## The Problem
+
+Writing test suites is slow, repetitive, and often inconsistent. Teams face:
+
+- **Starting from zero is painful** — a new project with no tests means weeks of setup before the first real test runs
+- **Coverage gaps are invisible** — without analysis, teams don't know what's missing until something breaks in production
+- **Standards drift** — different team members write tests differently: inconsistent locators, vague assertions, mixed naming conventions
+- **QA is always behind dev** — features ship faster than tests get written, and the gap keeps growing
+- **Existing QA teams still spend hours on repetitive work** — even with a mature test suite, adding tests for new features means manually inspecting pages, finding locators, writing POMs, running tests, fixing failures, repeat
+
+## The Solution
+
+QAA runs a pipeline of specialized AI agents, each responsible for one stage:
+
+```
+scan → map → analyze → plan → generate → validate → deliver
+```
+
+| Stage | What happens | Output |
+|-------|-------------|--------|
+| **Scan** | Detects framework, language, testable surfaces | SCAN_MANIFEST.md |
+| **Map** | Deep-scans codebase for testability, risk, patterns, existing tests (4 parallel agents) | 8 codebase documents |
+| **Analyze** | Produces risk assessment, test inventory, testing pyramid | QA_ANALYSIS.md, TEST_INVENTORY.md |
+| **Plan** | Groups test cases by feature, assigns to files, resolves dependencies | GENERATION_PLAN.md |
+| **Generate** | Writes test files, POMs, fixtures, configs following project standards | Test suite on disk |
+| **Validate** | 4-layer validation (syntax, structure, dependencies, logic) with auto-fix | VALIDATION_REPORT.md |
+| **Deliver** | Creates branch, commits per stage, pushes, opens draft PR | Pull request URL |
+
+Every agent reads the project's QA standards (CLAUDE.md) before producing output. Every test case has a unique ID, concrete inputs, and explicit expected outcomes — never "works correctly."
+
+## Three Workflows
+
+QAA adapts to where the project is in its QA maturity:
+
+**1. No QA repo yet** — `/qa-start --dev-repo ./myproject`
+Full pipeline from scratch. Produces a complete test suite, QA repo blueprint, and a draft PR with everything.
+
+**2. Immature QA repo** — `/qa-start --dev-repo ./myproject --qa-repo ./tests`
+Scans both repos, identifies gaps, fixes broken tests, adds missing coverage, standardizes existing tests.
+
+**3. Mature QA repo** — `/qa-start --dev-repo ./myproject --qa-repo ./tests`
+Only adds surgical test additions where coverage is thin. Doesn't touch working tests.
+
+## The "Brain" — Codebase Map
+
+Before generating anything, QAA maps the entire codebase with 4 parallel agents:
+
+- **Testability** — what's testable, pure functions vs stateful code, mock boundaries
+- **Risk** — business-critical paths, security-sensitive areas, data integrity risks
+- **Patterns** — naming conventions, API shapes, import style, code patterns
+- **Existing tests** — current test quality, frameworks in use, coverage gaps
+
+These 8 documents become the shared context that every downstream agent reads. The analyzer uses risk data to prioritize tests. The planner uses testability data to estimate complexity. The executor uses code patterns to generate tests that match the project's style.
+
+Result: generated tests feel native to the codebase, not generic boilerplate.
+
+## Day-to-Day for a QA Engineer
+
+This is where QAA shines for teams that already have a mature QA repo. The full pipeline is for bootstrapping — but the real daily value is the targeted workflow.
+
+### The scenario
+
+You're a QA engineer. A developer just shipped a new "password reset" feature. You need tests. Here's what happens:
+
+### Step 1: Map the codebase (once)
+
+```
+/qa-map
+```
+
+QAA scans the entire project and builds its "brain" — 8 documents covering testability, risk areas, API contracts, code patterns, and existing test coverage. This runs once and stays valid until the codebase changes significantly.
+
+### Step 2: Create tests for the feature
+
+```
+/create-test "password reset"
+```
+
+QAA already knows the codebase. It reads the brain documents, finds the relevant source files (`auth.service.ts`, `reset.controller.ts`, the reset page component), understands the API contracts, and generates:
+
+- Unit tests for the reset token logic with concrete inputs and expected outputs
+- API tests for `POST /api/auth/reset-password` with real request/response shapes
+- E2E tests with Page Object Models that use the project's existing POM base class
+- Fixtures with test data (fake emails, expired tokens, invalid tokens)
+
+All following the project's naming conventions, import style, and assertion patterns.
+
+### Step 3: Validate and fix in a loop
+
+```
+/qa-validate ./tests
+```
+
+The validator runs 4 layers of checks on every generated file:
+
+1. **Syntax** — does it parse? Are imports correct?
+2. **Structure** — does it follow POM rules? Are locators in the right tier?
+3. **Dependencies** — do all imports resolve? Are mocks set up correctly?
+4. **Logic** — are assertions concrete? Do test IDs follow the convention?
+
+If issues are found, the validator auto-fixes them and re-checks — up to 3 loops. If something still fails, the bug detective classifies it: is it an application bug, a test code error, or an environment issue?
+
+### Step 4: Run the tests with Playwright
+
+QAA integrates with Playwright to actually execute the generated E2E tests against a running application. It opens the browser, navigates pages, fills forms, clicks buttons, and captures what happens. If a test fails, it reads the error, inspects the page state, and determines whether the locator is wrong, the page changed, or there's a real bug.
+
+The loop looks like this:
+
+```
+generate → validate → run → failures? → classify → fix test code → run again → pass
+```
+
+This continues until the tests pass or the issue is classified as an application bug that needs a developer fix.
+
+### Step 5: Ship it
+
+```
+/qa-pr --ticket PROJ-456 "password reset tests"
+```
+
+QAA creates a branch following your team's naming convention (it asked you once and remembers forever), commits the test files, pushes, and opens a draft PR on GitHub, Azure DevOps, or GitLab — whatever your team uses. You get the link.
+
+### The full daily flow
+
+```
+/qa-map                                          → builds the "brain" (once)
+/create-test "password reset"                    → generates tests using codebase knowledge
+/qa-validate ./tests/unit/auth*                  → validates + auto-fixes
+/qa-pr --ticket PROJ-456 "password reset tests"  → draft PR with link
+```
+
+From ticket to PR in minutes, not hours. And the tests follow the same standards as every other test in the repo because QAA read the existing patterns first.
+
+### What about tickets?
+
+If you work from Jira, Linear, or GitHub Issues, skip the manual description:
+
+```
+/qa-from-ticket https://company.atlassian.net/browse/PROJ-456
+```
+
+QAA fetches the ticket, extracts acceptance criteria and edge cases, maps each criterion to test cases with a traceability matrix, generates the tests, validates them, and gives you a report showing which AC is covered by which test.
+
+### When tests break after a deploy
+
+```
+/qa-fix ./tests/e2e/checkout*
+```
+
+QAA reads the failing tests, runs them, classifies each failure (app bug vs test code error vs environment issue), and auto-fixes the test code errors. Application bugs get flagged for the dev team with evidence — the exact assertion that failed, what was expected, and what was received.
+
+## Standards
+
+Every test artifact follows strict rules:
+
+- **Testing pyramid** — 60-70% unit, 10-15% integration, 20-25% API, 3-5% E2E
+- **Locator hierarchy** — data-testid first, ARIA roles, labels, CSS as last resort (with TODO)
+- **Page Object Model** — one class per page, no assertions in POMs, locators as properties
+- **Assertions** — concrete values only. `expect(status).toBe(200)` not `expect(status).toBeTruthy()`
+- **Naming** — unique IDs per test case: `UT-AUTH-001`, `API-USERS-003`, `E2E-CHECKOUT-001`
+
+## Learning System
+
+QAA remembers your preferences across sessions. When you correct it — "use Playwright, not Cypress" or "our branches start with feature/" — it saves the rule permanently. Next time, every agent reads your preferences before generating output.
+
+Preferences override defaults. Your team's conventions always win.
+
+## Numbers
+
+17 commands. 7 skills. 11 agents. 10 templates. 7 workflows.
+
+Supports GitHub, Azure DevOps, and GitLab. Works with Playwright, Cypress, Jest, Vitest, pytest, and more — detects what the project uses and matches it.
+
+One goal: you focus on building features, QAA handles the tests.

package/docs/TESTING.md

@@ -0,0 +1,156 @@
+# Testing Guide
+
+How to validate the QA Automation Agent against real repositories.
+
+## Test Repos
+
+Each workflow option requires a different type of repository to test against.
+
+### Option 1 — Dev Only (No QA Repo)
+
+Test the full generation pipeline: scan → codebase-map → analyze → generate → validate → [e2e-run] → deliver.
+
+| Repo | Stack | Why it's good |
+|------|-------|---------------|
+| [devdbrandy/restful-ecommerce](https://github.com/devdbrandy/restful-ecommerce) | Node.js, Express | Minimalist e-commerce API. Products, orders, auth. Almost no tests — agent generates everything from scratch. |
+| [themodernmonk7/E-commerce-API](https://github.com/themodernmonk7/E-commerce-API) | Express, MongoDB | Full CRUD: auth, products, orders, reviews. No QA repo. Good variety of endpoints. |
+| [dinushchathurya/nodejs-ecommerce-api](https://github.com/dinushchathurya/nodejs-ecommerce-api) | Express, MongoDB | Full e-commerce: users, categories, products, orders, images. No tests. |
+
+**How to test:**
+```bash
+git clone https://github.com/devdbrandy/restful-ecommerce.git /tmp/test-option1
+cd /tmp/test-option1
+# Open Claude Code in this directory, then:
+/qa-start --dev-repo .
+```
+
+**Expected output:**
+- SCAN_MANIFEST.md with Node.js/Express detection
+- QA_ANALYSIS.md with architecture overview and risk assessment
+- TEST_INVENTORY.md with 30+ test cases (pyramid-driven)
+- QA_REPO_BLUEPRINT.md (since no QA repo exists)
+- Generated test files (unit, API, E2E)
+- VALIDATION_REPORT.md
+- Draft PR with all artifacts
+
+### Option 2 — Dev + Immature QA Repo
+
+Test the gap analysis and augmentation pipeline.
+
+| DEV Repo | Stack | QA Repo |
+|----------|-------|---------|
+| [oozdal/to-do-list-api](https://github.com/oozdal/to-do-list-api) | FastAPI, SQLAlchemy | Create a crude QA repo manually (see below) |
+| [KenMwaura1/Fast-Api-example](https://github.com/KenMwaura1/Fast-Api-example) | FastAPI, PostgreSQL, SQLAlchemy | Create a crude QA repo manually (see below) |
+
+**Creating a crude QA repo for testing:**
+
+No open-source repos have intentionally bad tests. Create one manually:
+
+```bash
+mkdir /tmp/test-option2-qa
+cd /tmp/test-option2-qa
+
+# Create a broken test file with hardcoded tokens
+cat > tests/test_api.py << 'EOF'
+import requests
+
+# TODO: ask Juan for new token
+TOKEN = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.expired"
+BASE_URL = "http://localhost:8000"
+
+def test_get_todos():
+    r = requests.get(f"{BASE_URL}/todos", headers={"Authorization": f"Bearer {TOKEN}"})
+    assert r.status_code  # No specific assertion!
+
+def test_create_todo():
+    r = requests.post(f"{BASE_URL}/todos", json={"title": "test"})
+    # No assertion at all
+EOF
+
+# Create a broken Selenium test
+cat > old_tests/test_ui.py << 'EOF'
+from selenium import webdriver
+# This import doesn't work anymore
+from selenium.webdriver.common.keys import Keys
+
+def test_login():
+    driver = webdriver.Chrome()  # Will fail - no ChromeDriver
+    driver.get("http://localhost:3000/login")
+    driver.find_element_by_class_name("login-btn").click()  # Deprecated API
+EOF
+
+# Create empty postman collection
+echo '{"info": {"name": "Todo API"}, "item": []}' > postman/collection.json
+
+# Bad README
+echo "# QA Tests\nSome tests might need updating. Ask the team." > README.md
+
+git init && git add -A && git commit -m "initial qa setup"
+```
+
+**How to test:**
+```bash
+cd /tmp/test-option2-dev  # The FastAPI dev repo
+/qa-start --dev-repo . --qa-repo /tmp/test-option2-qa
+```
+
+**Expected output:**
+- Maturity score < 30 → Option 2 detected
+- GAP_ANALYSIS.md showing broken tests, missing coverage
+- Fixed test files (imports, assertions, configs)
+- New test cases added for uncovered features
+- VALIDATION_REPORT.md
+
+### Option 3 — Dev + Mature QA Repo
+
+Test the surgical additions pipeline.
+
+| QA Repo | Stack | Why it's good |
+|---------|-------|---------------|
+| [OmonUrkinbaev/playwright-qa-automation](https://github.com/OmonUrkinbaev/playwright-qa-automation) | Playwright, TypeScript, POM | Production-style: UI + API tests, POM, data-driven, flaky handling, CI pipelines. |
+| [idavidov13/Playwright-Framework](https://github.com/idavidov13/Playwright-Framework) | Playwright, TypeScript, POM | Custom fixtures, API mocking, Zod validation, GitHub Actions + GitLab CI. |
+| [nareshnavinash/playwright-TS-pom](https://github.com/nareshnavinash/playwright-TS-pom) | Playwright, TypeScript, POM | GitLab CI, DataDog integration, ESLint, junit + HTML reporting. |
+
+**How to test:**
+```bash
+# Clone the app being tested (the QA repo tests against a demo app)
+git clone https://github.com/OmonUrkinbaev/playwright-qa-automation.git /tmp/test-option3-qa
+
+# You need the DEV repo that the QA repo tests against
+# Check the QA repo's README for the target application URL/repo
+
+/qa-start --dev-repo /tmp/test-option3-dev --qa-repo /tmp/test-option3-qa
+```
+
+**Expected output:**
+- Maturity score > 70 → Option 3 detected
+- GAP_ANALYSIS.md showing thin coverage areas only
+- Only missing tests added — existing tests untouched
+- Existing POM conventions respected
+- VALIDATION_REPORT.md
+
+## Validation Checklist
+
+After each test run, verify:
+
+- [ ] Correct workflow option detected (1, 2, or 3)
+- [ ] SCAN_MANIFEST.md has correct framework detection
+- [ ] QA_ANALYSIS.md has real architecture info (not generic)
+- [ ] TEST_INVENTORY.md has concrete inputs and expected outcomes
+- [ ] Generated test files follow CLAUDE.md standards
+- [ ] All locators use Tier 1 (data-testid) or Tier 2 (ARIA roles)
+- [ ] No assertions use toBeTruthy/toBeDefined
+- [ ] POM has no assertions (if E2E tests generated)
+- [ ] VALIDATION_REPORT.md shows 4-layer check results
+- [ ] Draft PR created with full summary and reviewer checklist
+- [ ] No hardcoded credentials in any generated file
+
+## Troubleshooting Test Runs
+
+| Issue | Fix |
+|-------|-----|
+| `gh: command not found` | Install GitHub CLI: `brew install gh` or `winget install GitHub.cli` |
+| `gh auth` error | Run `gh auth login` first |
+| Agent detects wrong framework | Check SCAN_MANIFEST.md — may need to adjust scanner detection patterns |
+| Maturity score seems wrong | Review the 5 scoring dimensions in init.cjs cmdInitQaStart |
+| Tests fail to validate | Check if the test framework is installed in the target repo |