@ai-qa/workflow 2.0.11 → 2.0.13

package/ai-qa-workflow.js

@@ -1,33 +1,33 @@
 #!/usr/bin/env node
 
 const { DIRS, ROOT, CONFIG, ensureDir, listUserStories, listTestPlans, listTestSpecs, timestamp, log, reloadConfig, autoDetectConfig } = require('./scripts/utils');
-const { generateTestPlan } = require('./scripts/planner');
-const { generateTestSpec } = require('./scripts/generator');
+const context = require('./scripts/context-manager');
 const { executeTests } = require('./scripts/executor');
 const { selfHeal } = require('./scripts/healer');
 const { generateReport } = require('./scripts/reporter');
 const path = require('path');
 const fs = require('fs');
 
-const PROJECT_NAME = CONFIG.project.name;
-
 const COMMANDS = {
   init:    { desc: 'Create required directories and config', fn: cmdInit },
-  plan:    { desc: '<user-story.md>  Generate test plan from user story', fn: cmdPlan },
-  generate:{ desc: '<test-plan.md>   Generate test spec from test plan', fn: cmdGenerate },
+  plan:    { desc: '(handled by AI agent — see playwright-test-planner.agent.md)', fn: cmdPlan },
+  generate:{ desc: '(handled by AI agent — see playwright-test-generator.agent.md)', fn: cmdGenerate },
   execute: { desc: '[test-name]      Run tests with Playwright', fn: cmdExecute },
-  heal:    { desc: '[run-id]         Self-heal failed tests', fn: cmdHeal },
+  heal:    { desc: '[run-id]         Retry failed tests (AI handles deeper diagnosis)', fn: cmdHeal },
   report:  { desc: '[run-id]         Generate execution report', fn: cmdReport },
   'report:allure': { desc: '[run-id]   Generate Allure report from test results', fn: cmdAllure },
-  run:     { desc: '<story-name.md>  Full pipeline: plan → generate → execute → heal → report', fn: cmdRun },
   status:  { desc: 'Show workflow state', fn: cmdStatus },
   list:    { desc: 'List user stories, test plans, and test specs', fn: cmdList },
+  context: { desc: '[phase] [story]  Mark a pipeline phase complete for a story', fn: cmdContext },
 };
 
 function cmdInit() {
   log('INIT', 'Creating required directories...');
   Object.values(DIRS).forEach(dir => ensureDir(dir));
 
+  const created = ['user-story', 'specs', 'tests', 'test-results', 'docs', '.qa-context', '.auth'];
+  log('INIT', `Directories: ${created.join(', ')}`);
+
   const configPath = path.join(ROOT, '.qa-workflow.json');
   if (!fs.existsSync(configPath)) {
     log('INIT', 'Scanning project to auto-detect configuration...');
@@ -65,36 +65,38 @@ function cmdInit() {
     log('INIT', 'docs/application-context.md created — AI agents will use this for context');
   }
 
-  log('INIT', 'Ready. Directories: user-story/, specs/, tests/, test-results/, docs/');
-  log('INIT', 'Edit .qa-workflow.json to override auto-detected values');
+  context.init();
+  log('INIT', '.qa-context/ initialized (pipeline.json, selectors.json, heal-history.json, traceability.json)');
+
+  const authGitignore = path.join(DIRS.auth, '.gitignore');
+  if (!fs.existsSync(authGitignore)) {
+    fs.writeFileSync(authGitignore, '# Auth credentials and Playwright storage state — never commit\n*\n', 'utf-8');
+    log('INIT', '.auth/ created (credentials.json, storage-state.json) — gitignored');
+  }
+
+  log('INIT', 'Ready. Edit .qa-workflow.json to override auto-detected values');
 }
 
 function cmdPlan() {
-  const storyName = process.argv[3];
-  if (!storyName) {
-    console.log('  Usage: node ai-qa-workflow.js plan <user-story-file.md>');
-    console.log(`  Available: ${listUserStories().join(', ')}`);
-    process.exit(1);
-  }
-  ensureDir(DIRS.specs);
-  const result = generateTestPlan(storyName);
-  console.log(`\n  ✓ Test plan generated: specs/${path.basename(result.planPath)}`);
-  console.log(`\n  Next step: Review and edit the test plan, then run:`);
-  console.log(`  node ai-qa-workflow.js generate ${path.basename(result.planPath)}`);
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════╗');
+  console.log('║  PLANNING is handled by the AI agent                   ║');
+  console.log('║                                                         ║');
+  console.log('║  Tell your AI agent:                                    ║');
+  console.log('║  "Read router.md and plan tests for my-story.md"        ║');
+  console.log('╚══════════════════════════════════════════════════════════╝');
+  console.log('');
 }
 
 function cmdGenerate() {
-  const planName = process.argv[3];
-  if (!planName) {
-    console.log('  Usage: node ai-qa-workflow.js generate <test-plan-file.md>');
-    console.log(`  Available: ${listTestPlans().join(', ')}`);
-    process.exit(1);
-  }
-  ensureDir(DIRS.tests);
-  const result = generateTestSpec(planName);
-  console.log(`\n  ✓ Test spec generated: tests/${result.specName}.spec.ts`);
-  console.log(`\n  Next step: Implement test logic in the spec file, then run:`);
-  console.log(`  node ai-qa-workflow.js execute ${result.specName}`);
+  console.log('');
+  console.log('╔══════════════════════════════════════════════════════════╗');
+  console.log('║  TEST GENERATION is handled by the AI agent            ║');
+  console.log('║                                                         ║');
+  console.log('║  Tell your AI agent:                                    ║');
+  console.log('║  "Generate tests for the plan in specs/"                ║');
+  console.log('╚══════════════════════════════════════════════════════════╝');
+  console.log('');
 }
 
 function cmdExecute() {
@@ -123,22 +125,18 @@ function cmdExecute() {
 
 function cmdHeal() {
   const runId = process.argv[3];
-  const result = selfHeal(runId, PROJECT_NAME);
+  const result = selfHeal(runId);
 
-  if (result.healed.length > 0) {
-    console.log(`\n  ✓ Healed: ${result.healed.length} test(s)`);
-    result.healed.forEach(h => console.log(`    - ${h.test || h.file} (${h.strategy})`));
+  if (result.rerun.length > 0) {
+    console.log(`\n  Re-ran ${result.rerun.length} test(s) with longer timeout`);
   }
-  if (result.remaining.length > 0) {
-    console.log(`\n  ✗ Still failing: ${result.remaining.length} test(s)`);
-    result.remaining.forEach(ft => console.log(`    - ${ft.test || ft.file}`));
+  if (result.stillFailing.length > 0) {
+    console.log(`\n  ${result.stillFailing.length} test(s) still failing — AI agent should diagnose`);
+    console.log(`  Tell your AI agent: "Debug the failing tests in test-results/"`);
   }
-  if (result.healed.length === 0 && result.remaining.length === 0) {
-    console.log('\n  No failures to heal.');
+  if (result.rerun.length === 0 && result.stillFailing.length === 0) {
+    console.log('\n  No failures to retry.');
   }
-
-  console.log(`\n  Next step: Generate report:`);
-  console.log(`  node ai-qa-workflow.js report ${result.reportPath ? path.basename(path.dirname(result.reportPath)) : runId || '(latest)'}`);
 }
 
 function cmdReport() {
@@ -187,60 +185,6 @@ function cmdAllure() {
   }
 }
 
-function cmdRun() {
-  const storyName = process.argv[3];
-  if (!storyName) {
-    console.log('  Usage: node ai-qa-workflow.js run <user-story-file.md>');
-    console.log(`  Available: ${listUserStories().join(', ')}`);
-    process.exit(1);
-  }
-
-  console.log('\n╔════════════════════════════════════════╗');
-  console.log('║   AI QA WORKFLOW - FULL PIPELINE      ║');
-  console.log('╚════════════════════════════════════════╝\n');
-
-  // Step 1: Plan
-  log('RUN', 'Step 1/5: Generating test plan...');
-  ensureDir(DIRS.specs);
-  const plan = generateTestPlan(storyName);
-  console.log(`  → specs/${path.basename(plan.planPath)}\n`);
-
-  // Step 2: Generate
-  log('RUN', 'Step 2/5: Generating test spec...');
-  ensureDir(DIRS.tests);
-  const spec = generateTestSpec(path.basename(plan.planPath));
-  console.log(`  → tests/${spec.specName}.spec.ts\n`);
-
-  // Step 3: Execute
-  log('RUN', 'Step 3/5: Executing tests...');
-  ensureDir(DIRS.testResults);
-  const execResult = executeTests(spec.specName);
-  console.log(`  → ${execResult.success ? '✓ PASSED' : '✗ FAILED'} (${(execResult.duration / 1000).toFixed(1)}s)\n`);
-
-  // Step 4: Heal (if needed)
-  if (!execResult.success) {
-    log('RUN', 'Step 4/5: Self-healing...');
-    const healResult = selfHeal(execResult.runId, PROJECT_NAME);
-    console.log(`  → Healed: ${healResult.healed.length} | Remaining: ${healResult.remaining.length}\n`);
-  } else {
-    log('RUN', 'Step 4/5: Skipped (all tests passed)');
-    console.log('');
-  }
-
-  // Step 5: Report
-  log('RUN', 'Step 5/5: Generating report...');
-  const report = generateReport(execResult.runId);
-  console.log(`  → ${report ? report.reportPath : 'N/A'}\n`);
-
-  console.log('╔════════════════════════════════════════╗');
-  console.log('║   WORKFLOW COMPLETE                    ║');
-  console.log('╚════════════════════════════════════════╝');
-  if (report) {
-    console.log(`\n  Report: test-results/${execResult.runId}/final-test-report.md`);
-    console.log(`  Passed: ${report.stats.passed} | Failed: ${report.stats.failed} | Healed: ${report.stats.healed}`);
-  }
-}
-
 function cmdStatus() {
   console.log('\n📊 AI QA Workflow Status\n');
 
@@ -298,6 +242,35 @@ function cmdList() {
   console.log('');
 }
 
+function cmdContext() {
+  const phase = process.argv[3];
+  const story = process.argv[4];
+
+  if (!phase || !story) {
+    console.log('\nUsage: node ai-qa-workflow.js context <phase> <story>');
+    console.log('Phases: plan, generate, execute, heal, report');
+    console.log('Example: node ai-qa-workflow.js context plan login\n');
+    process.exit(1);
+  }
+
+  const validPhases = ['plan', 'generate', 'execute', 'heal', 'report'];
+  if (!validPhases.includes(phase)) {
+    console.log(`\nInvalid phase: ${phase}`);
+    console.log(`Valid: ${validPhases.join(', ')}\n`);
+    process.exit(1);
+  }
+
+  context.phaseComplete(phase, story);
+  context.setCurrentStory(story);
+
+  const pipeline = context.getPipeline();
+  const storyData = pipeline.phases[phase];
+  const completed = storyData ? storyData.completed.join(', ') : '—';
+
+  console.log(`\n  ✓ Phase "${phase}" marked complete for story "${story}"`);
+  console.log(`  Completed for this phase: ${completed}\n`);
+}
+
 const cmd = process.argv[2];
 
 if (!cmd || cmd === '--help' || cmd === '-h') {
@@ -307,14 +280,19 @@ if (!cmd || cmd === '--help' || cmd === '-h') {
   for (const [name, { desc }] of Object.entries(COMMANDS)) {
     console.log(`  ${name.padEnd(12)} ${desc}`);
   }
-  console.log('\nExamples:');
+  console.log('\nNote: Planning and test generation are done by the AI agent, not CLI commands.');
+  console.log('See: .github/agents/ and prompts/ for AI instructions.\n');
+  console.log('Examples:');
   console.log('  node ai-qa-workflow.js init');
-  console.log('  node ai-qa-workflow.js plan US-EXPLORE-01.md');
-  console.log('  node ai-qa-workflow.js generate us-explore-01-test-plan.md');
-  console.log('  node ai-qa-workflow.js execute us-explore-01');
-  console.log('  node ai-qa-workflow.js run US-EXPLORE-01.md');
+  console.log('  node ai-qa-workflow.js execute');
+  console.log('  node ai-qa-workflow.js execute my-feature');
+  console.log('  node ai-qa-workflow.js heal');
+  console.log('  node ai-qa-workflow.js heal run-2026-05-24');
+  console.log('  node ai-qa-workflow.js report');
   console.log('  node ai-qa-workflow.js report:allure');
-  console.log('  node ai-qa-workflow.js status\n');
+  console.log('  node ai-qa-workflow.js status');
+  console.log('  node ai-qa-workflow.js list');
+  console.log('  node ai-qa-workflow.js context plan login\n');
   process.exit(0);
 }
 

package/install.js

@@ -22,11 +22,8 @@ const USER_DIRS = new Set([
   'specs',
   'tests',
   'test-results',
-  
- 
-  
-  
-  
+  '.qa-context',
+  '.auth',
 ]);
 
 // Template files to copy/update
@@ -39,13 +36,11 @@ const QA_ITEMS = [
   { src: '.opencode', dest: '.opencode', dir: true },
    { src: 'README.md', dest: 'README.md' },
   { src: 'PROJECT_GUIDE.md', dest: 'PROJECT_GUIDE.md' },
+    { src: 'prompting_template.md', dest: 'prompting_template.md' },
     { src: '.cursorrules', dest: '.cursorrules' },
      { src: '.geminirules', dest: '.geminirules' },
      { src: '.github/copilot-instructions.md', dest: '.github/copilot-instructions.md' },
       { src: 'router.md', dest: 'router.md' },
-      { src: 'user-story', dest: 'user-story', dir: true },
-      { src: 'specs', dest: 'specs', dir: true },
-      { src: 'tests', dest: 'tests', dir: true },
   { src: '.opencode.json', dest: '.opencode.json' },
 
     ];
@@ -56,7 +51,7 @@ const UPDATE_ITEMS = QA_ITEMS.filter(item => {
   return !USER_FILES.has(item.dest);
 });
 
-const DIRS_TO_CREATE = ['user-story', 'specs', 'tests', 'test-results'];
+const DIRS_TO_CREATE = ['user-story', 'specs', 'tests', 'test-results', '.qa-context', '.auth', 'templates'];
 
 const NPM_SCRIPTS = {
   'qa': 'node ai-qa-workflow.js',
@@ -65,9 +60,9 @@ const NPM_SCRIPTS = {
   'qa:generate': 'node ai-qa-workflow.js generate',
   'qa:execute': 'node ai-qa-workflow.js execute',
   'qa:heal': 'node ai-qa-workflow.js heal',
+  'qa:retry': 'node ai-qa-workflow.js heal',
   'qa:report': 'node ai-qa-workflow.js report',
   'qa:report:allure': 'node ai-qa-workflow.js report:allure',
-  'qa:run': 'node ai-qa-workflow.js run',
   'qa:status': 'node ai-qa-workflow.js status',
   'qa:list': 'node ai-qa-workflow.js list',
   'dashboard': 'cd qa-dashboard && npm start',
@@ -239,8 +234,8 @@ async function install(targetPath, mode) {
   } else {
     console.log(`  Files: ~${totalFiles} scripts + ${dashboardCount} dashboard files`);
     console.log(`  Next:\n`);
-    console.log(`  npm run qa:init      Initialize pipeline (auto-detect config)`);
-    console.log(`  npm run qa:run       Run a user story through full pipeline`);
+    console.log(`  npm run qa:init      Initialize pipeline (config + dirs + auth)`);
+    console.log(`  npm run qa:execute   Run Playwright tests`);
     console.log(`  npm run qa:status    Check pipeline state`);
     console.log(`  npm run dashboard    Start dashboard (port 4000)\n`);
   }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ai-qa/workflow",
-  "version": "2.0.11",
-  "description": "One-command AI QA Pipeline — User Story to Test Report. Auto-detects project config, generates Playwright tests, self-heals failures, dashboard UI.",
+  "version": "2.0.13",
+  "description": "AI QA Workflow Template — transforms any AI agent into an autonomous QA engineer. AI explores, plans, generates tests, and heals. Scripts execute and report.",
   "keywords": [
     "qa",
     "testing",
@@ -16,17 +16,16 @@
     "prompts/",
     "scripts/",
     "qa-dashboard/",
-    "user-story/",
-    "specs/",
-    "tests/",
     "test-results/",
     "docs/",
+    ".qa-context/",
     "templates/",
     "ai-qa-workflow.js",
     "cli.js",
     "install.js",
     "README.md",
     "PROJECT_GUIDE.md",
+    "prompting_template.md",
     ".cursorrules",
     ".geminirules",
     ".opencode/",
@@ -50,9 +49,9 @@
     "qa:generate": "node ai-qa-workflow.js generate",
     "qa:execute": "node ai-qa-workflow.js execute",
     "qa:heal": "node ai-qa-workflow.js heal",
+    "qa:retry": "node ai-qa-workflow.js heal",
     "qa:report": "node ai-qa-workflow.js report",
     "qa:report:allure": "node ai-qa-workflow.js report:allure",
-    "qa:run": "node ai-qa-workflow.js run",
     "qa:status": "node ai-qa-workflow.js status",
     "qa:list": "node ai-qa-workflow.js list",
     "dashboard": "cd qa-dashboard && npm start",

package/prompting_template.md

@@ -0,0 +1,283 @@
+# Prompting Template — How to Talk to the AI QA Agent
+
+This guide covers every prompt you need — from installation to final report. Use it as your conversation script.
+
+---
+
+## Quick Start (Copy-Paste Ready)
+
+After installing the template and writing a user story, open your AI editor and send:
+
+> **"Read router.md and follow the QA workflow for my-story.md"**
+
+That's it. The AI handles everything from there, stopping at each phase for your approval.
+
+---
+
+## Phase-by-Phase Prompts
+
+### Phase 0: First Contact (Environment Check)
+
+When you open the project for the **first time**, the AI automatically runs an environment check. If it doesn't, or if you want to re-check:
+
+> **"Run the environment check and tell me what's ready and what's missing"**
+
+The AI will report:
+- ✅ What's installed and configured
+- ✅ Pipeline state from `.qa-context/pipeline.json` (phases completed, last run)
+- ✅ Auth status from `.auth/credentials.json` (credentials found or missing)
+- ❌ What's missing (with commands to fix)
+- 📋 What it needs from you (user story, credentials, etc.)
+
+The AI **automatically reads `.qa-context/pipeline.json`, `.qa-context/selectors.json`, and `.qa-context/heal-history.json`** to understand the current state before starting any phase.
+
+---
+
+### Phase 1: Test Planning
+
+You have a user story. You want the AI to explore the app and write a test plan.
+
+> **"Read router.md and plan tests for my-story.md"**
+
+The AI will:
+1. Read `router.md` → routes to `playwright-test-planner.agent.md`
+2. Open your app with Playwright MCP
+3. Explore navigation, flows, and UI components
+4. Map critical paths and edge cases
+5. Write a test plan to `specs/my-story-test-plan.md`
+6. **STOP and present the plan to you**
+
+#### What you should review in the plan:
+- Are all acceptance criteria covered?
+- Are edge cases and negative scenarios included?
+- Are the preconditions accurate?
+- Does the environment URL match your running app?
+
+#### Approval responses:
+| You say | Result |
+|---------|--------|
+| "Looks good, continue" | AI proceeds to test generation |
+| "Approved" | Same |
+| "Add a scenario for X" | AI updates the plan, then waits again |
+| "I'll review later, proceed" | AI proceeds (use with caution) |
+
+---
+
+### Phase 2: Test Generation
+
+The plan is approved. Now you want the AI to write real Playwright tests.
+
+> **"Generate tests from the plan in specs/my-story-test-plan.md"**
+
+Or simply (if already in context):
+
+> **"Generate the tests"**
+
+The AI will:
+1. Read `playwright-test-generator.agent.md`
+2. Read `prompts/QAe2eprompt.md` for conventions
+3. Use Playwright MCP to manually execute each scenario
+4. Capture real selectors from the actual page
+5. Add visual checkpoints via Applitools on critical pages (if `APPLITOOLS_API_KEY` is set)
+6. Write complete Playwright `.spec.ts` files to `tests/`
+7. **STOP and present the code to you**
+
+#### What you should review in the test code:
+- Are selectors using real elements? (no hallucinated CSS classes)
+- Are assertions meaningful?
+- Are visual checkpoints added on critical pages? (login, dashboard, checkout)
+- Does the test handle auth/state correctly?
+- Are there timeouts or waits that might flake?
+
+#### Approval responses:
+| You say | Result |
+|---------|--------|
+| "Code looks good, execute" | User runs tests, or AI suggests running |
+| "Approved" | Same |
+| "Fix the selector on line 23" | AI corrects it, presents again |
+| "Add a test for X edge case" | AI adds the scenario, presents again |
+
+---
+
+### Phase 3: Execution
+
+Tests are written and approved. Time to run them.
+
+> **User runs:** `npm run qa:execute [test-name]`
+
+Or, if you want the AI to trigger execution (if it has shell access):
+
+> **"Execute the tests and report back"**
+
+The AI runs Playwright and reports:
+- ✅ Tests passed → ready for report
+- ❌ Tests failed → moves to healing phase
+
+---
+
+### Phase 4: Healing (Debugging Failures)
+
+Tests failed. You want the AI to fix them.
+
+> **"Debug and fix the failing tests"**
+
+Or specifically:
+
+> **"Read playwright-test-healer.agent.md and debug the failures in test-results/latest-run"**
+
+The AI will:
+1. Read `playwright-test-healer.agent.md`
+2. Run the failing tests with `test_run`
+3. Debug with `test_debug` — examine the actual UI state
+4. Classify the failure:
+   - **Selector broken** → proposes 1-3 line fix
+   - **Timing issue** → proposes adding a wait
+   - **App bug** → marks `test.fixme()`, logs defect
+5. **STOP and present diagnosis + proposed fix to you**
+
+#### What you should review in the diagnosis:
+- What exactly failed and why
+- What the AI wants to change (which file, which lines)
+- Is it a test issue or a real bug in your app?
+
+#### Approval responses:
+| You say | Result |
+|---------|--------|
+| "Fix it" | AI applies the 1-3 line fix and re-runs |
+| "Approved, apply the fix" | Same |
+| "That's a real bug, file it" | AI marks as defect, moves on |
+| "Try a different approach" | AI suggests alternative fix |
+| "Skip it, I'll investigate later" | AI marks as `test.fixme()` |
+
+---
+
+### Phase 5: Report
+
+Tests are done. You want a summary.
+
+> **"Generate the execution report"**
+
+Or manually:
+
+> **User runs:** `npm run qa:report [run-id]`
+
+The AI will:
+1. Run `npm run qa:report` (or read the results directly)
+2. Present a summary: passed, failed, healed, defects found
+3. Update `docs/application-context.md` with learned selectors and flaky areas
+
+---
+
+## Quick Reference — All Prompts in One Table
+
+| Phase | Your prompt | AI does | You do |
+|-------|------------|---------|--------|
+| **0** | *(automatic on first open)* | Environment check | Read status report |
+| **0** | "Run the environment check" | Re-check setup | Fix any missing items |
+| **1** | "Read router.md and plan tests for my-story.md" | Explore app, write plan | **Review + approve** |
+| **2** | "Generate tests from the plan" | Write Playwright code | **Review + approve** |
+| **3** | `npm run qa:execute` | Run tests | Check results |
+| **4** | "Debug and fix the failing tests" | Diagnose, propose fix | **Review + approve** |
+| **5** | "Generate the report" | Summarize results | Review final report |
+
+---
+
+## Best Practices
+
+### For Best Results
+
+1. **Write structured user stories** — Use the format in the README. Clear acceptance criteria produce better test plans.
+
+2. **Review the plan first** — The AI's understanding of your app is only as good as its exploration. Catch incorrect assumptions early.
+
+3. **Don't skip the approval gates** — Each gate is a chance to redirect the AI before it wastes time on the wrong approach.
+
+4. **Be specific in your feedback** — Instead of "this looks wrong", say "the selector on line 23 should use `data-testid` instead of class name".
+
+5. **Provide context upfront** — Populate `docs/application-context.md` with stable selectors, auth details, and tech stack notes before starting. The AI also reads `.qa-context/` automatically — you don't need to tell it.
+
+6. **Memory is persistent** — The AI stores its learning in `.qa-context/` (selectors, healing history, pipeline state). This means each session starts smarter than the last. Don't delete this folder unless you want to reset the AI's memory.
+
+7. **Credentials are stored once** — The AI saves your login to `.auth/credentials.json` after first use. If your password changes, just update that file or delete it and the AI will ask again.
+
+6. **Use `npm run qa:retry` for simple flakes** — If a test fails intermittently, try the mechanical retry first before asking the AI to debug.
+
+7. **Token efficiency works both ways** — Keep your feedback concise. The AI is designed for 1-3 line fixes and targeted edits.
+
+### Common Mistakes to Avoid
+
+| Mistake | Better approach |
+|---------|----------------|
+| Sending a vague "test my app" prompt | "Read router.md and plan tests for user-story/login.md" |
+| Approving without reviewing the plan | Always check: does it cover the acceptance criteria? |
+| Letting the AI generate tests without a plan | Always do Phase 1 before Phase 2 |
+| Running tests before reviewing the code | AI can hallucinate selectors — verify them first |
+| Asking the AI to fix everything at once | One test at a time: "Debug the login test failure" |
+| Skipping the approval gate | You're the supervisor for a reason |
+
+---
+
+## Example Full Session
+
+```
+You: "Read router.md and plan tests for login-story.md"
+
+AI: [Explores app, writes plan to specs/login-story-test-plan.md]
+    "Plan is ready. Here's what I found:
+     - 3 scenarios: login success, wrong password, locked account
+     - 1 concern: no visible error toast for locked accounts
+     Do you approve?"
+
+You: "Looks good, but add a scenario for empty email field."
+
+AI: [Updates plan]
+    "Added. 4 scenarios now. Approve?"
+
+You: "Approved, generate the tests."
+
+AI: [Writes tests/login-story.spec.ts]
+    "Tests generated. I used getByRole for buttons and getByLabel for inputs.
+    Do you approve the code?"
+
+You: "Looks good, execute."
+
+AI: "Run: npm run qa:execute login-story"
+
+You: [Runs it] "Two tests failed — wrong password and locked account."
+
+AI: [Debugs]
+    "Diagnosis:
+     - Wrong password: error message class changed, needs new selector
+     - Locked account: the lock icon isn't rendering (app bug)
+     Fix the selector on line 42? Approve?"
+
+You: "Fix the selector, mark the lock icon as a bug."
+
+AI: [Applies fix, re-runs, marks test.fixme()]
+    "Fixed: wrong password now passes. Locked account marked as defect.
+    Generate the report?"
+
+You: "Yes, generate it."
+```
+
+---
+
+## Quick Copy-Paste
+
+### Minimal workflow (5 prompts total)
+
+```
+1. "Read router.md and plan tests for my-story.md"
+2. "Approved" (after reviewing plan)
+3. "Approved" (after reviewing tests)
+   (run npm run qa:execute)
+4. "Debug and fix the failing tests"
+5. "Approved, apply the fix" (after reviewing diagnosis)
+   (run npm run qa:report)
+```
+
+### Single command to start everything
+
+```
+"Read router.md and follow the QA workflow for my-story.md"
+```

package/qa-dashboard/app.js

@@ -86,6 +86,7 @@ app.use('/', require('./routes/index'));
 app.use('/projects', require('./routes/projects'));
 app.use('/stories', require('./routes/stories'));
 app.use('/runs', require('./routes/runs'));
+app.use('/review', require('./routes/review'));
 app.use('/analytics', require('./routes/analytics'));
 app.use('/export', require('./routes/export'));
 app.use('/data', require('./routes/test-data'));