@ai-qa/workflow 2.0.11 → 2.0.14

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,14 +36,12 @@ 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' },
+      { 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/opencode.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "playwright": {
+      "type": "local",
+      "command": ["npx", "-y", "@playwright/mcp"],
+      "enabled": true,
+      "description": "Browser automation - navigate, click, type, screenshot. Required for test generation. Install: npm install -D @playwright/mcp"
+    },
+    "github": {
+      "type": "local",
+      "command": ["npx", "-y", "@modelcontextprotocol/server-github"],
+      "enabled": true,
+      "description": "GitHub integration - PRs, issues, commits. Requires GITHUB_TOKEN env var. Install: npm install -D @modelcontextprotocol/server-github"
+    },
+     "applitools-mcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@applitools/mcp@latest"],
+      "enabled": true,
+       "description": "Visual testing - requires APPLITOOLS_API_KEY env var",
+       "env": {
+    "APPLITOOLS_API_KEY": "${APPLITOOLS_API_KEY}"
+  }
+    }
+  },
+  "agent": {
+    "qa-planner": {
+      "description": "Reads user story, explores website via Playwright MCP, creates test plan in specs/",
+      "mode": "subagent"
+    },
+    "qa-generator": {
+      "description": "Opens browser via MCP, captures real selectors, writes Playwright .spec.ts files from test plans",
+      "mode": "subagent"
+    },
+    "qa-healer": {
+      "description": "Debugs failing Playwright tests, fixes selectors/timing, classifies defects (2 attempts max)",
+      "mode": "subagent"
+    }
+  },
+  "default_agent": "general"
+}

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.14",
+  "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,20 +16,20 @@
     "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/",
+    "opencode.json",
     ".qa-workflow.json",
     "router.md",
     ".github/"
@@ -50,9 +50,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",