@ai-qa/workflow 2.0.11 → 2.0.13

package/README.md

@@ -1,8 +1,41 @@
-# AI QA Pipeline
+# AI QA Workflow Template
 
-**User Story → Test Plan → Test Generation → Execution → Self-Healing → Dashboard**
+**Turn any AI agent into an autonomous QA engineer.**
 
-One-command install into any web project. Works standalone or with any AI assistant (opencode, GitHub Copilot, Claude Code).
+This template gives an AI coding assistant (opencode, Copilot, Claude Code, Cursor, etc.) everything it needs to: explore your web app, plan tests, generate real Playwright code, execute them, debug failures, and visualize results.
+
+The template handles the **mechanical** parts (execution, reporting, dashboard). The AI handles the **creative** parts (planning, test generation, debugging, healing).
+
+---
+
+## How It Works
+
+```
+
+                                ┌──────────────────────────────────────┐
+                                │         AI AGENT (does thinking)     │
+                                │                                      │
+                                │  Phase 1: Environment check          │
+                                │  Phase 2: Explore app + write plan   │
+                                │  Phase 3: Generate Playwright tests  │
+                                │  Phase 4: Execute tests              │
+                                │  Phase 5: Debug + heal failures      │
+                                │  Phase 6: Report + update context    │
+                                └───────┬────────────────────┬────────┘
+                                        │                    │
+                          ┌─────────────┘                    └─────────────┐
+                          ▼                                                ▼
+              ┌─────────────────────────┐              ┌─────────────────────────┐
+              │  HUMAN SUPERVISION       │              │  SCRIPTS (mechanics)    │
+              │                         │              │                         │
+              │  At EVERY phase:        │              │  npm run qa:execute     │
+              │  AI proposes ──▶ you    │              │  npm run qa:report      │
+              │  approve ──▶ AI acts    │              │  npm run qa:retry       │
+              │                         │              │  npm run qa:status      │
+              │  You are always in      │              │  npm run qa:list        │
+              │  control.               │              │  npm run dashboard      │
+              └─────────────────────────┘              └─────────────────────────┘
+```
 
 ---
 
@@ -12,13 +45,13 @@ One-command install into any web project. Works standalone or with any AI assist
 npx @ai-qa/workflow init --yes
 ```
 
-That's it. This single command installs the full pipeline into your current project:
-
-- Copies pipeline scripts (planner, generator, executor, healer, reporter)
-- Installs Playwright + dashboard dependencies
-- Adds npm scripts (`qa:*` commands)
-- Creates directories (`user-story/`, `specs/`, `tests/`, `test-results/`)
-- Registers your project in the dashboard
+Installs the full template into your project:
+- Playwright MCP + GitHub MCP configuration (`opencode.json`)
+- AI agent definitions (`.github/agents/`)
+- Workflow prompts (`prompts/`)
+- CLI scripts for execution and reporting
+- QA Dashboard (web UI)
+- Directory structure (`user-story/`, `specs/`, `tests/`, `test-results/`, `docs/`, `.qa-context/`)
 
 ### Update an existing installation
 
@@ -26,68 +59,276 @@ That's it. This single command installs the full pipeline into your current proj
 npx @ai-qa/workflow update --yes
 ```
 
-Updates pipeline files while **preserving** your configuration (`.qa-workflow.json`, `opencode.json`), user stories, test specs, and run results.
+Updates template files while preserving your user stories, test specs, config, and run results.
+
+---
 
-### What you get
+## What You Get
 
 ```
 your-project/
-├── ai-qa-workflow.js          # CLI orchestrator (10 commands)
-├── .qa-workflow.json          # Project config (auto-detected, editable)
-├── scripts/                   # 6 automation modules
+├── ai-qa-workflow.js          # CLI orchestrator (8 commands)
+├── .qa-workflow.json          # Project config (auto-detected)
+├── scripts/
+│   ├── utils.js               # Config loading, shared helpers
+│   ├── executor.js            # Runs Playwright tests
+│   ├── retrier.js             # Re-runs failed tests (longer timeout)
+│   └── reporter.js            # Markdown + JSON reports
 ├── opencode.json              # MCP config (Playwright + GitHub)
 ├── .github/agents/            # AI agent definitions
-├── prompts/                   # AI workflow instructions
+│   ├── playwright-test-planner.agent.md
+│   ├── playwright-test-generator.agent.md
+│   └── playwright-test-healer.agent.md
+├── prompts/
+│   ├── QAe2eprompt.md         # Full 9-step AI workflow
+│   ├── general_prompt.md      # Quick-start prompt
+├── prompting_template.md       # Conversation guide — what to say to the AI at each phase
+├── router.md                  # AI entry point — routes to correct agent
 ├── qa-dashboard/              # Web UI (port 4000)
-├── user-story/                # Your .md stories
-├── specs/                     # Generated test plans
-├── tests/                     # Generated Playwright specs
-└── test-results/   
-           # Run results, reports, screenshots
+├── .qa-context/                # Persistent AI memory (pipeline state, selectors, healing history, traceability)
+├── .auth/                      # Auth credentials + Playwright storage state (gitignored)
+├── user-story/                 # Your .md stories
+├── specs/                     # AI-generated test plans
+├── tests/                     # AI-generated Playwright specs
+├── test-results/              # Run results, reports, screenshots
+└── docs/                      # Application context (AI knowledge base)
 ```
 
-### Quick start after install
+---
+
+## Quick Start
 
 ```bash
-# 1. Initialize (auto-detects project config)
+# 1. Install the template
+npx @ai-qa/workflow init --yes
+
+# 2. Initialize project config
 npm run qa:init
 
-# 2. Write a user story in user-story/ or let the AI create one
+# 3. Write a user story in user-story/my-feature.md (see format below)
+
+# 4. Open the project in your AI editor (opencode, Copilot, Cursor)
+#    The AI agent auto-detects its role and runs an environment check.
+#    It will report what's ready and what's missing.
+
+# 5. Send this one prompt to start:
+#    "Read router.md and follow the QA workflow for my-feature.md"
+
+# The AI will:
+#   - Read router.md → understand its mission
+#   - Read playwright-test-planner.agent.md
+#   - Run environment check (if not already done)
+#   - Explore your app with Playwright MCP
+#   - Save a test plan to specs/
+#   - STOP and ask for your approval
+#   - Once approved → generate tests → STOP again
+#   - Tell you when ready to execute
 
-# 3. Run full pipeline
-npm run qa:run my-story.md
+# 6. Execute tests
+npm run qa:execute
+
+# 7. If tests fail, tell your AI agent:
+#    "Debug and fix the failing tests"
 
-# 4. Start the dashboard
+# 8. Launch dashboard
 npm run dashboard
 ```
 
+> **💡 Full conversation guide:** See `prompting_template.md` for a complete script of what to say to the AI at every phase — from installation to final report.
+
 ---
 
-## How It Works
+## AI Agent Auto-Bootstrap
 
-The framework operates in two distinct, powerful phases:
+When you open this project in an AI-powered editor, the agent **automatically** understands its purpose:
 
-### Phase 1: Creation (Agent-Driven)
-You interact with an AI Agent in your IDE (Cursor, OpenCode, Copilot, Antigravity). You simply provide a URL or a Markdown User Story. The agent automatically:
-1. Loads its intelligence from `agents/router.md`
-2. Uses Playwright MCP to open a hidden browser
-3. Visually explores your application in real-time
-4. Generates a flawless test plan (`specs/`) and executable code (`tests/`) using **real** semantic selectors. No more hallucinated CSS classes!
+1. **Reads `.opencode/rules.md`** (or `.github/copilot-instructions.md`) → discovers it's an **AI QA Engineer**
+2. **Runs an environment check** → reports what's ready ✅ and what's missing ❌
+3. **Reads `router.md`** → learns the workflow and supervision rules
+4. **Stops and waits** for you to provide a user story
 
-### Phase 2: Execution & Tracking (Dashboard-Driven)
-Once the test scripts are generated by the Agent, you move to execution:
-1. Open the Web Dashboard (`npm run dashboard`)
-2. Click **Execute** or trigger it via your CI/CD pipeline
-3. The framework handles Playwright execution, auto-healing (fixing minor flakiness), and report generation
-4. View deep analytics, execution history, and Allure reports directly in the Dashboard UI.
+No manual instructions needed. The agent knows its role on first contact.
 
 ---
 
-## Zero-Config Design
+## Your First Prompt
+
+After installation and running `npm run qa:init`, open the project in your AI editor.
+
+The very first thing you should say to the AI agent:
+
+> **"Read router.md and follow the QA workflow for my-story.md"**
+
+(Replace `my-story.md` with the name of your user story file in `user-story/`.)
+
+> **📖 Need more prompts?** See `prompting_template.md` for the full conversation script — approval responses, healing prompts, report prompts, and an example session.
+
+### What happens when you send this prompt:
+
+| Step | AI does this | You do this |
+|------|-------------|-------------|
+| 1 | Runs environment check (if first time) | Read the status report |
+| 2 | Reads `router.md` → `playwright-test-planner.agent.md` | — |
+| 3 | Explores your app with Playwright MCP | — |
+| 4 | Writes test plan to `specs/` | **Review and approve** |
+| 5 | Reads `playwright-test-generator.agent.md` | — |
+| 6 | Generates test files to `tests/` | **Review and approve** |
+| 7 | Tells you tests are ready to run | Run `npm run qa:execute` |
+| 8 | If tests fail, debugs and proposes fix | **Review and approve fix** |
+
+**You are the supervisor.** The AI never moves to the next phase without your approval.
+
+---
+
+## For Humans: Understanding the Workflow
+
+The template follows a **9-step AI workflow** defined in `prompts/QAe2eprompt.md`. Here's what happens at each step:
+
+### Step 1 — Context Discovery
+The AI reads `docs/application-context.md` and explores your project to understand the tech stack, authentication, and environment.
+
+### Step 2 — Test Strategy & Plan
+The AI reads `playwright-test-planner.agent.md` and uses Playwright MCP to explore your app visually. It maps user flows, identifies critical paths, and designs comprehensive test scenarios. The plan is saved to `specs/`.
+
+> **⛔ Approval gate:** The AI **stops** after saving the plan and presents it to you. You review, give feedback, and say "approved" or "continue" before the AI proceeds to test generation.
+
+### Step 3 — Manual Exploratory Testing
+The AI executes each scenario manually using Playwright MCP, capturing real selectors, observing behavior, and noting issues.
+
+### Step 4 — Test Code Generation
+The AI reads `playwright-test-generator.agent.md` and writes real Playwright `.spec.ts` files using selectors it discovered during exploration. Generated files go in `tests/`.
+
+> **⛔ Approval gate:** The AI **stops** after generating test files and presents them to you. You review the code, check selectors and logic, then say "approved" or "execute" before the AI proceeds.
+
+### Step 5 — Execution
+Run the tests mechanically:
+
+```bash
+npm run qa:execute [test-name]
+```
+
+Or run all tests:
+```bash
+npm run qa:execute
+```
+
+The executor runs Playwright with the configured options and saves results to `test-results/`.
+
+### Step 6 — Debug & Heal (AI)
+If tests fail, the AI reads `playwright-test-healer.agent.md` and:
+1. Runs the failing test with `test_run`
+2. Debugs with `test_debug` — examines the actual UI state
+3. Classifies the failure and proposes a fix (1-3 line change)
+
+> **⛔ Approval gate:** The AI **stops** and presents its diagnosis to you. It shows what's broken, why, and what it wants to change. You approve the fix before the AI edits any file.
+
+4. Once approved, applies fix and re-runs once
+5. If still failing, marks as `test.fixme()` and reports as defect
+
+For a quick mechanical re-run (no AI diagnosis):
+
+```bash
+npm run qa:retry [run-id]
+```
+
+This re-runs failed tests with a longer timeout. If they still fail, the AI investigates.
+
+### Step 7 — Bug Classification (AI)
+The AI classifies every defect by severity, priority, type, root cause, and reproducibility. Results are saved to `test-results/defects-log.md`.
+
+### Step 8 — Report
+```bash
+npm run qa:report [run-id]
+```
+
+Generates a markdown report from execution results.
+
+### Step 9 — Knowledge Retention
+The AI updates `docs/application-context.md` with:
+- Stable selectors discovered
+- Known flaky areas
+- Healing strategies that worked
+- Environment observations
+
+---
+
+## Installation
+
+### Requirements
+
+| Component | Needed for | Install |
+|-----------|-----------|---------|
+| **Node.js 18+** | Running the pipeline | — |
+| **Playwright** | Test execution | `npm install @playwright/test` |
+| **Chromium** | Running tests | `npx playwright install chromium` |
+| **Playwright MCP** | AI browser automation | `npm install -D @playwright/mcp` |
+| **Applitools MCP** | Visual testing (screenshot comparison) | `npm install -D @applitools/mcp` + `APPLITOOLS_API_KEY` |
+| **GitHub MCP** | AI creating PRs/issues | `npm install -D @modelcontextprotocol/server-github` + `GITHUB_TOKEN` |
+
+### Install into a project
+
+```bash
+npx @ai-qa/workflow init --yes
+```
+
+Or from local template:
+```bash
+node install.js ../my-project --yes
+```
+
+### Update
+
+```bash
+npx @ai-qa/workflow update --yes
+```
+
+---
+
+## Visual Testing (Applitools)
+
+The template supports **Applitools MCP** for automated visual testing.
+
+If `APPLITOOLS_API_KEY` is configured in your environment, the AI agent automatically adds visual checkpoints to critical pages during test generation. It captures screenshots of pages like login, dashboard, and checkout, and compares them against baselines to detect visual regressions.
+
+### Setup
+
+```bash
+# 1. Install Applitools MCP
+npm install -D @applitools/mcp
+
+# 2. Set your API key (get it from https://applitools.com)
+# Option A: Export in terminal
+export APPLITOOLS_API_KEY=votre_clé_ici
+
+# Option B: Add to .env file
+echo "APPLITOOLS_API_KEY=votre_clé_ici" >> .env
+```
+
+The AI will detect the key during its environment check and use Applitools automatically. If the key is not set, visual testing is skipped entirely — no errors, no blocks.
+
+---
+
+## Commands
+
+| Command | Description | Who does it |
+|---------|-------------|-------------|
+| `npm run qa:init` | Create directories + auto-detect config | You (once) |
+| `npm run qa:execute [test]` | Run Playwright tests | You or CI |
+| `npm run qa:retry [run-id]` | Re-run failed tests (longer timeout) | You or CI |
+| `npm run qa:report [run-id]` | Generate markdown report | You or CI |
+| `npm run qa:status` | Show pipeline state | You |
+| `npm run qa:list` | List stories, plans, specs | You |
+| `node ai-qa-workflow.js context <phase> <story>` | Mark a pipeline phase complete for a story | AI agent or you |
+| `npm run dashboard` | Launch web UI at :4000 | You |
 
-The template works out of the box by **auto-detecting** your project configuration.
+> The commands `qa:plan`, `qa:generate`, and `qa:run` do not exist in this template.
+> Planning, test generation, and healing are done by the AI agent, not by scripts.
 
-On `npm run qa:init`, it scans your project and generates `.qa-workflow.json`:
+---
+
+## Zero-Config Design
+
+On `npm run qa:init`, the template auto-detects your project configuration:
 
 | Scan source | What it detects |
 |-------------|----------------|
@@ -98,15 +339,12 @@ On `npm run qa:init`, it scans your project and generates `.qa-workflow.json`:
 | `playwright.config.*` | Browser type (edge, webkit) |
 | Directory structure | Framework (Angular, Next.js, Python) |
 
-If a file is missing, the template falls back to sensible defaults. No manual setup required.
-
-### The Config File (`.qa-workflow.json`)
+Generated `.qa-workflow.json`:
 
 ```json
 {
   "project": {
     "name": "my-app",
-    "description": "My web application",
     "url": "http://localhost:5173",
     "environment": "Development"
   },
@@ -127,100 +365,121 @@ If a file is missing, the template falls back to sensible defaults. No manual se
 }
 ```
 
-Edit this file to override auto-detected values. The template merges your settings with defaults — you only need to set what differs.
+Edit this file to override auto-detected values.
 
-### Application Context (`docs/application-context.md`)
+---
 
-This file serves as a **knowledge base for AI agents** during test planning and healing. On `init` it's created from config values. As you use the pipeline, AI agents populate it with:
+## Application Context (`docs/application-context.md`)
+
+This file serves as the **AI's knowledge base**. On `init` it's auto-generated. The AI populates it during exploration and testing with:
 
 - **Stable selectors** — CSS/XPath selectors discovered during exploration
 - **Known flaky areas** — elements or flows that frequently break
 - **Auth details** — users, tokens, environments
 - **Tech stack notes** — framework specifics the AI should know
 
-For best results, edit this file with your project's specifics before running the pipeline.
+For best results, edit this file with your project's specifics before the AI starts.
 
 ---
 
-## Installation
+## Persistent AI Memory (`.qa-context/`)
 
-### Requirements
+The `.qa-context/` directory stores **structured memory** that persists between AI sessions and pipeline phases:
 
-| Component | Needed for | Install |
-|-----------|-----------|---------|
-| **Node.js 18+** | Running the pipeline | — |
-| **Playwright** | Test execution | `npm install @playwright/test` |
-| **Chromium** | Running tests | `npx playwright install chromium` |
-| **Playwright MCP** | AI browser automation (explore, click, type) | `npm install -D @playwright/mcp` |
-| **GitHub MCP** | AI creating PRs/issues from results | `npm install -D @modelcontextprotocol/server-github` + `GITHUB_TOKEN` env |
+| File | Content | Used by |
+|------|---------|---------|
+| `pipeline.json` | Current pipeline state: which phases are complete, current story, last run | All agents (read on start, write on complete) |
+| `selectors.json` | All discovered selectors with reliability scores, healing history, recommended alternatives | Generator (write best selectors), Healer (read alternatives) |
+| `heal-history.json` | Every healing attempt: what was tried, which strategy, whether it succeeded | Healer (avoid repeating failed attempts), Planner (avoid flaky pages) |
+| `traceability.json` | Full mapping: story → plan → spec → runs → healing | Reporter (link report to story), Dashboard (display traceability) |
 
-### Install into a project
+Each agent reads `.qa-context/` **before starting** and updates it **after completing**. This means:
+- The Generator reuses stable selectors discovered by the Planner
+- The Healer knows which selectors were tried and failed before
+- The Reporter links every run back to its original story
+- The Dashboard can display the full audit trail
 
-```bash
-# From npm (recommended — works anywhere)
-npx @ai-qa/workflow init --yes
+The AI automatically consults these files — no manual setup needed.
 
-# From local template
-node install.js ../my-project --yes
-```
+---
 
-The installer copies all pipeline files, creates directories, adds npm scripts, installs dashboard dependencies, and registers your project in the dashboard.
+## Authentication Management (`.auth/`)
 
-### Update an installed project
+The `.auth/` directory stores everything needed for automated login during tests:
 
-```bash
-# From npm
-npx @ai-qa/workflow update --yes
+| File | Content | Git |
+|------|---------|:---:|
+| `credentials.json` | Username + password for the app | ❌ ignored |
+| `storage-state.json` | Playwright session (cookies, localStorage, tokens) | ❌ ignored |
+| `.gitignore` | Ensures nothing in `.auth/` is committed | ✅ |
 
-# From local template
-node install.js ../my-project --update --yes
-```
+### How it works
 
-Updates pipeline files while preserving: `.qa-workflow.json`, `opencode.json`, `user-story/`, `specs/`, `tests/`, `test-results/`, `qa-dashboard/data/`, `qa-dashboard/node_modules/`.
+1. **`npm run qa:init`** creates `.auth/` with `.gitignore` — ready to use
+2. **AI discovers login** during Phase 1 (Plan) — navigates to `/login`, detects form fields, saves structure to `.qa-context/auth.json`
+3. **You provide credentials** once — the AI saves them to `.auth/credentials.json`
+4. **Session is persisted** — after first login, Playwright's storage state is saved to `.auth/storage-state.json`
+5. **Tests reuse the session** — generated `auth.setup.ts` loads storage state before each run
+6. **If credentials change**, the AI detects auth failures via `auth-manager.js` and prompts you to update `.auth/credentials.json`
 
-### Commands added to your project
+### First-time setup
 
 ```bash
-npm run qa:init          # Initialize + auto-detect config
-npm run qa:run <story>   # Full pipeline: plan → generate → execute → heal → report
-npm run qa:plan <story>  # Generate test plan only
-npm run qa:generate      # Generate test code from plan
-npm run qa:execute       # Run Playwright tests
-npm run qa:heal          # Self-heal failed tests
-npm run qa:report        # Generate final report
-npm run qa:status        # Check pipeline state
-npm run qa:list          # List stories, plans, specs
-npm run dashboard        # Launch web dashboard at :4000
+# 1. After qa:init, open the project in your AI editor
+# 2. The AI will ask for credentials during Phase 1 (Plan)
+# 3. Provide them once — they're saved to .auth/credentials.json
+# 4. All future runs reuse the stored session
 ```
 
----
+### Manual setup
 
-## How to Get the Most Out of It
+```json
+{
+  "username": "test@example.com",
+  "password": "your-password",
+  "url": "http://localhost:3000/login"
+}
+```
 
-### 1. Provide good context upfront
+Save this as `.auth/credentials.json`. The AI detects it automatically on next run.
 
-Before running the pipeline, populate `docs/application-context.md`:
+---
 
-```markdown
-## Project
-- Name: My App
-- URL: https://staging.myapp.com
-- Environment: Staging
-
-## Authentication
-- Login flow: email + password via /api/auth/login
-- Test user: test@example.com / TestPass123
-
-## Stable Selectors
-- Login button: button[data-testid="login-btn"]
-- Error toast: .toast-error
-```
+## How the AI Agents Work
+
+The template defines three specialized AI agents in `.github/agents/`:
+
+### Planner Agent
+Triggers when the AI needs to create a test plan. The AI:
+1. Opens your app with Playwright MCP
+2. Explores navigation, flows, UI components
+3. Maps critical paths and edge cases
+4. Saves a structured test plan to `specs/`
+5. **⛔ Stops and presents the plan to you for approval**
+
+### Generator Agent
+Triggers when the AI needs to write test code. The AI:
+1. Reads the test plan
+2. Uses Playwright to manually execute each step
+3. Captures real selectors (data-testid, aria-label, role)
+4. Adds visual checkpoints via Applitools on critical pages (if `APPLITOOLS_API_KEY` is set)
+5. Writes complete, executable Playwright tests to `tests/`
+6. **⛔ Stops and presents the code to you for approval**
+
+### Healer Agent
+Triggers when tests fail. The AI:
+1. Runs only the failing tests
+2. Debugs with `test_debug` — sees the actual UI state
+3. Classifies the failure (selector, timing, or bug)
+4. **⛔ Stops and presents diagnosis + proposed fix for your approval**
+5. Once approved, applies a targeted 1-3 line fix
+6. Re-runs once — if still failing, marks as `test.fixme()`
 
-The AI reads this file during test planning and healing. The more accurate this is, the better the generated tests.
+---
 
-### 2. Write structured user stories
+## Writing Good User Stories
 
-Your `user-story/*.md` files should follow this format:
+The AI reads your user stories to understand what to test. Write them in `user-story/`:
 
 ```markdown
 # User Login
@@ -243,122 +502,66 @@ As a registered user, I want to log in with my credentials so I can access the d
 4. User name displayed in header
 ```
 
-Well-structured stories produce better test plans. The planner extracts acceptance criteria, preconditions, and feature name automatically.
-
-### 3. Review generated test plans
-
-After `npm run qa:plan`, check `specs/*-test-plan.md`. The AI generates scenarios from acceptance criteria. Review and edit before generating test code:
-
-- Add edge cases the AI missed
-- Add negative test scenarios
-- Fix any incorrect assumptions about the app
-
-### 4. Use the run mode that fits your workflow
+Well-structured stories produce better test plans and better automated tests.
 
-| Mode | Command | Best for |
-|------|---------|----------|
-| **Full auto** | `npm run qa:run <story>` | Quick smoke tests, CI pipelines |
-| **Step by step** | plan → generate → execute → heal → report | Reviewing each stage, manual edits |
-| **Manual test only** | `npm run qa:execute <test>` | When tests are already written |
-| **Heal only** | `npm run qa:heal [runId]` | After manual test edits |
-
-### 5. Understand self-healing
-
-The healer makes up to **2 attempts** per failed test:
-
-1. **Standard re-run** — flakes due to timing or network
-2. **Longer timeout (60s)** — slow responses
-3. **Stop** — marks as defect, classifies the failure
-
-Failure classification:
-| Type | Label | Auto-healed? |
-|------|-------|-------------|
-| Selector not found | `selector` | ✅ Usually |
-| Timeout | `timing` | ✅ Usually |
-| Target closed | `environment` | ❌ Bug |
-| Network error | `environment` | ❌ Bug |
-| Test syntax error | `test-syntax` | ❌ Manual fix |
+---
 
-### 6. Check the dashboard
+## Dashboard
 
 ```bash
 npm run dashboard
 # → http://localhost:4000
 ```
 
-The dashboard shows multi-project management, execution history with pass/fail/healed stats, analytics charts (pass rate, duration, healing vs defects), and test data generation tools.
+The dashboard provides:
+- Multi-project management
+- Execution history with pass/fail/healed stats
+- Analytics charts (pass rate, duration, healing vs defects)
+- Allure report integration
+- Export to HTML / plain text
 
 ---
 
-## Self-Healing Rules
+## Self-Healing Protocol (AI-Driven)
 
-| Attempt | Strategy | If still fails |
-|---------|----------|----------------|
+This is **not** an automatic script. The AI agent follows this protocol:
+
+| Attempt | What happens | If still fails |
+|---------|-------------|----------------|
 | 1 | Standard re-run | Classify failure |
 | 2 | Longer timeout (60s) | Mark as defect |
 | STOP | — | `test.fixme()` + classify |
 
----
-
-## Project Structure
-
-```
-your-project/
-├── ai-qa-workflow.js          # CLI orchestrator (9 commands)
-├── .qa-workflow.json          # Project config (auto-detected, editable)
-├── scripts/
-│   ├── utils.js               # Config loading, auto-detection, shared helpers
-│   ├── planner.js             # user-story → test-plan template
-│   ├── generator.js           # test-plan → test spec skeleton
-│   ├── executor.js            # runs Playwright tests
-│   ├── healer.js              # 2 attempts max, classifies defects
-│   └── reporter.js            # markdown + JSON reports
-├── opencode.json              # MCP config (Playwright + GitHub)
-├── .github/agents/            # AI agent definitions
-├── prompts/                   # AI workflow instructions
-├── qa-dashboard/              # Web UI (port 4000)
-├── user-story/                # Your .md stories
-├── specs/                     # Generated test plans
-├── tests/                     # Generated Playwright specs
-├── test-results/              # Run results, reports, screenshots
-└── docs/                      # Application context (AI knowledge base)
-```
+The mechanical `npm run qa:retry` just re-runs. True healing (fixing selectors, adjusting waits, fixing assertions) is done by the AI agent using Playwright MCP.
 
 ---
 
-## Allure Reports
-
-The pipeline supports **Allure** for rich, interactive test reports.
-
-### Setup
-
-```bash
-# 1. Install Allure dependencies
-npm install -D allure-playwright
+## Human Supervision (You Are in Control)
 
-# 2. Add to Playwright config (playwright.config.ts or .js)
-# reporter: [["list"], ["allure-playwright"]],
+The AI agent **never acts without your approval**. Every major phase follows this cycle:
 
-# 3. Run tests (generates allure-results/)
-npm run qa:execute
-
-# 4. Generate the HTML report
-npm run qa:report:allure
+```
+AI proposes ──▶ You review ──▶ You approve ──▶ AI executes ──▶ You verify
 ```
 
-### View in Dashboard
+| Phase | AI does | You approve |
+|-------|---------|-------------|
+| Plan | Explore app, write test plan | Review plan content |
+| Generate | Write Playwright test code | Review selectors and logic |
+| Heal | Diagnose failure, propose fix | Review the fix before it's applied |
 
-Once generated, the Allure report is available from the dashboard:
+The only exception: `npm run qa:execute` runs tests mechanically — you run this yourself or via CI.
 
-- **Runs list** → "Allure Report" button on each run
-- **Run detail** → "Open Allure Report ↗" in the Report Actions card
-- Direct URL: `/allure-report?project=<project-id>`
+The AI never:
+- Generates tests without showing you the plan first
+- Edits test code without showing you the diagnosis first
+- Deploys, commits, or pushes without asking
 
-The dashboard auto-detects `allure-report/index.html` and shows the buttons only when the report exists.
+**You are the supervisor. The AI is your engineer.**
 
 ---
 
-## Token Efficiency (for AI)
+## Token Efficiency
 
 1. Body text assertions over complex selectors
 2. Screenshots off by default (only on failure)