@ai-qa/workflow 2.0.16 → 2.0.18

package/.opencode/qa-workflow-skill.md

@@ -0,0 +1,232 @@
+---
+name: ai-qa-workflow
+description: AI QA Workflow skill — Playwright E2E testing with Allure, Applitools, self-healing, and QA Dashboard integration
+agents: [qa-planner, qa-generator, qa-healer]
+---
+
+# AI QA Workflow Skill
+
+You are an expert QA automation engineer working on the **AI QA Workflow Template** project.
+
+This project has a complete pipeline: user story → test plan → test generation → execution → self-healing → reporting + dashboard.
+
+## 1. Project Architecture
+
+### Directory Structure
+```
+user-story/          # User stories (input)
+specs/               # Test plans (generated by planner)
+tests/               # Playwright .spec.ts files (generated by generator)
+test-results/        # Run outputs (execution-output.json, execution-result.json, healing-report.json)
+allure-results/      # Allure raw results (generated by allure-playwright reporter)
+qa-dashboard/        # Express dashboard for visualizing results
+scripts/             # Workflow engine (executor.js, reporter.js, healer.js, etc.)
+.opencode/agents/    # Subagent definitions (qa-planner, qa-generator, qa-healer)
+.qa-context/         # Pipeline state, selectors, traceability, heal history
+```
+
+### Pipeline Phases
+1. **Plan** → `specs/<story>.md`
+2. **Generate** → `tests/<story>.spec.ts`
+3. **Execute** → `test-results/run-<timestamp>/`
+4. **Heal** → auto-fix failing tests
+5. **Report** → markdown report + Allure + Dashboard
+
+## 2. Playwright Configuration
+
+### Required Reporters in `playwright.config.ts`
+```typescript
+reporter: [
+  ['list'],
+  ['json', { outputFile: 'test-results/playwright-report.json' }],
+  ['html', { outputFolder: 'playwright-report' }],
+  ['allure-playwright'],
+]
+```
+
+The **json** reporter feeds `executor.js` parsing. The **allure-playwright** reporter writes to `allure-results/`. Both are critical.
+
+### Output Paths
+- Playwright HTML report: `playwright-report/index.html`
+- JSON results: `test-results/playwright-report.json`
+- Allure results: `allure-results/`
+- Screenshots (on failure): `test-results/screenshots/` or `test-results/run-<id>/`
+
+### Running Tests
+| Command | What it does |
+|---------|-------------|
+| `npx playwright test` | Direct run — saves results to JSON, HTML, Allure (via config) |
+| `npm run qa:execute` | Workflow run — saves to `test-results/run-<id>/` with full pipeline tracking |
+| `npm run qa:execute -- <test-name>` | Run a specific test via the workflow |
+
+## 3. Executor Compatibility
+
+The `scripts/executor.js` parses Playwright's stdout to extract test results.
+
+### What the Executor Expects
+- **Passed tests** → lines matching `  √  <test-name>` (checkmark)
+- **Failed tests** → lines matching `  ×  <test-name>` (cross mark)
+
+### Best Practices for Executor-Friendly Tests
+- Use descriptive test names (no special chars that break regex)
+- Keep test names concise
+- Avoid ANSI codes in test names
+- Each `test()` block = 1 scenario in the report
+
+## 4. Allure Integration
+
+### Reporter Setup
+```typescript
+reporter: [
+  ['allure-playwright'],
+]
+```
+
+### Commands
+```bash
+# Generate HTML report from raw results
+npx allure generate allure-results --clean -o allure-report
+
+# Open report in browser
+npx allure open allure-report
+
+# Generate and serve on-the-fly
+npx allure serve allure-results
+```
+
+Allure results are auto-generated by `executor.js` after each workflow run if `allure-commandline` is installed.
+
+The QA Dashboard serves Allure reports at `/allure-report?project=<id>`.
+
+### Allure Labels (optional enrichment)
+```typescript
+import { allure } from 'allure-playwright';
+
+test('login with valid credentials', async ({ page }) => {
+  await allure.feature('Authentication');
+  await allure.story('User Login');
+  await allure.severity('critical');
+  // ... test body
+});
+```
+
+## 5. Applitools Eyes — Visual Testing
+
+This project integrates `@applitools/eyes-playwright` for visual regression testing.
+
+### Setup
+```typescript
+import { BatchInfo, Configuration, EyesRunner, VisualGridRunner } from '@applitools/eyes-playwright';
+```
+
+### Key Practices
+- Use `eyes.open()` with a unique test name
+- Use `eyes.check()` with `Target.window()` or `Target.region()`
+- Use `eyes.close()` to submit results
+- Configure `APPLITOOLS_API_KEY` in `.env`
+
+### Applitools MCP Tools Available
+- `eyes_setup_project` — initial setup instructions
+- `eyes_verify_api_key` — validate the API key
+- `eyes_fetch_visual_results` — fetch results after a run
+- `eyes_add_checkpoints_to_test` — add visual checkpoints to existing tests
+- `eyes_analyze_batch` — analyze visual diffs from a batch URL
+
+## 6. Self-Healing Patterns
+
+Tests must be written to maximize auto-healing success.
+
+### DO
+- Use **stable selectors**: `data-testid` > `aria-label` > `role` > `text`
+- Store frequently-used selectors in `.qa-context/selectors.json`
+- Wrap flaky interactions in retry logic (Playwright auto-retries by default)
+- Keep tests **independent** (no shared state)
+- Use `test.beforeEach` for setup, `test.afterEach` for cleanup
+
+### AVOID
+- Hardcoded CSS selectors (e.g., `div.container > ul > li:nth-child(3)`)
+- `page.waitForTimeout()` — use auto-waiting instead
+- Fragile text matching (use regex or `toContainText` over `toHaveText`)
+- Tests that depend on execution order (breaks in parallel mode)
+
+### Healer Protocol
+1. The healer reads `.qa-context/heal-history.json` to avoid known failures
+2. It uses Playwright MCP to debug and find new selectors
+3. If healing fails after 2 attempts, the test gets `test.fixme()` and is classified as a defect
+4. Updated selectors are saved to `.qa-context/selectors.json`
+
+## 7. QA Dashboard
+
+The dashboard is an Express + EJS app at `qa-dashboard/`.
+
+### Starting the Dashboard
+```bash
+npm run dashboard           # Start on port 4000
+npm run dashboard:dev       # Dev mode with auto-reload
+```
+
+### Dashboard Pages
+| Route | Content |
+|-------|---------|
+| `/` | Project overview |
+| `/runs` | All test runs with pass/fail/heal stats |
+| `/runs/:runId` | Single run details (output, result, healing report) |
+| `/analytics` | Aggregated analytics (pass rate, heal rate, duration) |
+| `/allure-report` | Allure HTML report viewer |
+| `/stories` | Story traceability |
+
+The dashboard auto-shuts down 10s after the browser tab closes.
+
+## 8. Agent Routing
+
+This project has 3 specialized subagents in `.opencode/agents/`:
+
+| Agent | When to use | File |
+|-------|-------------|------|
+| **qa-planner** | Reading user story, exploring website, writing test plan | `.opencode/agents/qa-planner.md` |
+| **qa-generator** | Converting test plan into Playwright `.spec.ts` files | `.opencode/agents/qa-generator.md` |
+| **qa-healer** | Debugging and fixing failing tests | `.opencode/agents/qa-healer.md` |
+
+Route user requests to the appropriate agent based on the current pipeline phase.
+
+## 9. Test Template (Project-Style)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('Feature: <name>', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('/<path>');
+  });
+
+  test('<description>', async ({ page }) => {
+    await page.getByRole('button', { name: '<label>' }).click();
+    await expect(page.getByText('<expected>')).toBeVisible();
+  });
+});
+```
+
+Tests go directly in `tests/` (flat structure, not nested) and follow the naming convention `<story-name>.spec.ts`.
+
+## 10. Quick Reference
+
+```bash
+# Workflow commands
+npm run qa:plan              # Phase 1: Plan
+npm run qa:generate          # Phase 2: Generate
+npm run qa:execute           # Phase 3: Execute
+npm run qa:heal              # Phase 4: Heal
+npm run qa:report            # Phase 5: Report
+
+# Allure
+npm run qa:report:allure     # Generate Allure HTML report
+npx allure serve allure-results  # Serve Allure report
+
+# Dashboard
+npm run dashboard            # Open QA Dashboard at http://localhost:4000
+
+# Playwright
+npx playwright test          # Run all tests (direct)
+npx playwright test --ui     # UI mode
+npx playwright show-report   # View Playwright HTML report
+```

package/PROJECT_GUIDE.md

@@ -1,102 +1,142 @@
-# 📘 Guide d'Architecture & Navigation du Projet
+# Guide d'utilisation — AI QA Workflow
 
-Bienvenue dans le code source de **AI QA Workflow**, votre plateforme de test E2E augmentée par l'Intelligence Artificielle.
-Ce document a pour but de vous aider à naviguer dans le projet, comprendre la structure des dossiers et le rôle exact de chaque fichier.
+## 1. Prérequis
 
-Le projet est divisé en deux grandes parties : le **Moteur CLI (Ligne de commande)** qui s'occupe de la logique d'IA et de Playwright, et le **QA Dashboard (Interface Web)** qui offre une expérience utilisateur premium.
+- **IDE avec agent IA** : VS Code (Copilot), Cursor, Codex, OpenCode, Claude Code...
+- **Node.js 18+**
+- Navigateur Chromium
 
 ---
 
-## 🏗️ Structure Globale
+## 2. Créer un dossier de test
 
-```text
-ai-qa-workflow-template/
-├── 📄 ai-qa-workflow.js        # Point d'entrée principal du CLI
-├── 📄 package.json             # Dépendances (Express, Playwright, Groq-SDK, etc.)
-├── 📁 scripts/                 # Cœur de l'intelligence artificielle (Génération & Exécution)
-├── 📁 prompts/                 # Directives et prompts envoyés à l'IA
-├── 📁 user-story/              # Les besoins métiers rédigés par l'équipe (Point de départ)
-├── 📁 plans/                   # [Généré] Les plans de tests créés par l'IA
-├── 📁 tests/                   # [Généré] Les scripts Playwright (.spec.ts)
-├── 📁 test-results/            # [Généré] Résultats bruts, traces et logs des exécutions
-└── 📁 qa-dashboard/            # Application Web Express.js (Interface Graphique)
+```bash
+mkdir mon-projet-qa
+cd mon-projet-qa
+```
+
+---
+
+## 3. Installer le template
+
+```bash
+npx @ai-qa/workflow init --yes
+```
+
+---
+
+## 4. Installer les dépendances
+
+Consultez le fichier `README.md` → section **Dépendances requises** puis installez :
+
+```bash
+npm install -D @playwright/test @types/node allure-playwright allure-commandline
+npx playwright install chromium
+```
+
+---
+
+## 5. Rédiger une User Story
+
+Créez un fichier dans le dossier `user-story/` :
+
+```markdown
+# US-ALIM-01 : Alimentation de Solde
+
+**Rôle** : Agent SB
+**Étapes** :
+- Se connecter
+- Naviguer vers "Demande alimentation et CASH"
+- Saisir Montant=100, Mode=Virement
+- Joindre un fichier, cliquer Suivant
 ```
 
 ---
 
-## 🧠 1. Le Moteur CLI & IA (Dossier racine & `scripts/`)
+## 6. Lancer le pipeline IA
+
+Ouvrez le projet dans votre IDE avec agent IA, puis envoyez ce prompt :
 
-C'est ici que l'intelligence artificielle interagit avec le code et Playwright.
+```text
+"Read router.md and follow the QA workflow for user-story/US-ALIM-01.md"
+```
+
+### C'est quoi `router.md` ?
+
+Le fichier `router.md` est le **plan de mission** de l'agent IA. Il définit :
+- Les phases du workflow (Environment Check → Plan → Generate → Execute → Heal → Report)
+- Les fichiers agents à utiliser (`playwright-test-planner.agent.md`, etc.)
+- Les règles de validation humaine à chaque étape
+
+En bref : **router.md dit à l'IA comment faire son travail.**
 
-* **`ai-qa-workflow.js`**
-  * **Rôle :** C'est le chef d'orchestre en ligne de commande. Il intercepte vos commandes (`plan`, `generate`, `execute`, `run`, `heal`) et appelle le bon script dans le dossier `scripts/`.
+---
 
-* **`scripts/planner.js`**
-  * **Rôle :** Lit une "User Story" (Markdown) et utilise l'IA pour rédiger un Plan de Test complet (cas nominaux, cas d'erreurs, assertions attendues).
+## 7. Résultat attendu
 
-* **`scripts/generator.js`**
-  * **Rôle :** Lit le Plan de Test généré, et demande à l'IA de le traduire en **vrai code exécutable** Playwright (fichiers `.spec.ts`).
+L'IA va :
+1. Explorer l'application via le navigateur
+2. Générer un plan de test dans `specs/`
+3. **STOP** → vous validez
 
-* **`scripts/executor.js`**
-  * **Rôle :** Lance Playwright sur les tests générés. Il capture les succès, les échecs, la durée, et enregistre un rapport complet (`execution-result.json`) ainsi que les logs bruts (`execution-output.json`).
+---
 
-* **`scripts/healer.js`**
-  * **Rôle :** Le module d'auto-guérison (Self-Healing). Si un test échoue, ce script lit la trace d'erreur, l'envoie à l'IA pour comprendre pourquoi (sélecteur cassé, timeout, etc.), corrige le fichier `.spec.ts` et relance le test automatiquement.
+## 8. Superviser chaque étape
 
-* **`scripts/reporter.js`**
-  * **Rôle :** Lit les résultats JSON froids et demande à l'IA d'en faire un résumé Markdown humain et lisible (`final-test-report.md`).
+### Phase Plan
+- Vérifiez le fichier `specs/US-ALIM-01-test-plan.md`
+- Approuvez ou demandez des modifications
 
-* **`scripts/utils.js`**
-  * **Rôle :** Fichier utilitaire contenant des fonctions communes (création de dossiers, écriture de fichiers, formatage des dates).
+### Phase Generate
+- Vérifiez le fichier `tests/US-ALIM-01.spec.ts`
+- Vérifiez les sélecteurs, les assertions
+- Approuvez avant exécution
 
 ---
 
-## 🎨 2. L'Interface Web (Dossier `qa-dashboard/`)
-
-Le dashboard est une application Node.js (Express) qui lit les fichiers générés par le CLI et permet de lancer les commandes visuellement.
-
-### Serveur & Services
-* **`qa-dashboard/app.js`**
-  * **Rôle :** Lance le serveur web (sur le port 4000 par défaut). Contient aussi un mécanisme d'extinction automatique si aucun onglet navigateur n'est ouvert (pour économiser de la mémoire).
-* **`qa-dashboard/services/project-manager.js`**
-  * **Rôle :** Permet au dashboard de "découvrir" automatiquement où se trouve votre projet E2E sur votre disque.
-* **`qa-dashboard/services/cli-bridge.js`**
-  * **Rôle :** C'est le **pont** entre l'interface et le CLI. C'est ici qu'on exécute les scripts de façon asynchrone (`spawn`), qu'on capture les logs pour les afficher en direct, et qu'on lit les fichiers de résultat avec des sécurités (`try-catch`) pour éviter les plantages.
-
-### Routes (Contrôleurs) (`qa-dashboard/routes/`)
-Chaque fichier gère une page spécifique :
-* **`index.js`** : Page d'accueil, calcule les statistiques globales (taux de succès, nombre de tests).
-* **`stories.js`** : Liste vos User Stories et gère les boutons pour déclencher l'IA (Plan, Generate, Run). C'est lui qui envoie le texte en temps réel à votre navigateur.
-* **`runs.js`** : Gère l'affichage de l'historique des exécutions. Permet de voir un run en cours d'exécution, de lister les succès/échecs et de comparer deux exécutions.
-* **`analytics.js`** : Prépare les données mathématiques pour les graphiques (durée moyenne, taux de healing).
-* **`export.js`** : Transforme vos rapports Markdown en fichiers PDF ou HTML téléchargeables.
-
-### Vues (Gabarits HTML/EJS) (`qa-dashboard/views/`)
-Ce sont les interfaces que vous voyez à l'écran, stylisées selon les guidelines "Clay" (esthétique premium, bords arrondis, couleurs vibrantes).
-* **`layouts/main.ejs`** : Le "squelette" de toutes les pages. Contient la barre de navigation, les polices Google (Outfit, Inter) et le script `marked.js` pour rendre le Markdown.
-* **`story.ejs`** : L'écran le plus interactif. Affiche le terminal noir avec le retour de l'IA en direct.
-* **`runs.ejs`** : La liste globale des tests passés.
-* **`run.ejs`** : Le détail d'un seul passage de test (avec les erreurs empilées et le log du healing).
-* **`analytics.ejs`** : Les superbes graphiques Chart.js (rose fluo, vert, etc.).
-
-### Styles & Assets (`qa-dashboard/public/`)
-* **`css/style.css`** : Le cœur de l'esthétique du projet (variables CSS, ombres, effets de survol, animations, classes `card-lavender`, `card-peach`, etc.).
-* **`js/main.js`** : Les petits scripts front-end (ex: interactions mineures de l'interface).
+## 9. Exécuter les tests
+
+```bash
+npx playwright test tests/US-ALIM-01.spec.ts
+```
+
+Ou via le pipeline :
+
+```bash
+npm run qa:execute US-ALIM-01
+```
 
 ---
 
-## 🚀 Résumé du Nouveau Flux de Travail (Workflow à 2 Phases)
+## 10. Visualiser les résultats
+
+### Option A : Rapport Allure
+
+```bash
+npm run qa:report:allure
+allure open allure-report
+```
+
+### Option B : Dashboard local
 
-Le framework a évolué pour utiliser pleinement la puissance des Agents IA modernes (MCP). La création se fait via le chat de votre éditeur, et l'exécution via le Dashboard.
+```bash
+npm run dashboard
+# → http://localhost:4000
+```
 
-### Phase 1 : La Création (Via l'Agent IA dans votre éditeur)
-1. Vous ajoutez un fichier `.md` dans le dossier `user-story/` ou vous donnez simplement un lien à votre Agent IA (Copilot, Cursor, OpenCode, Antigravity).
-2. Vous dites à l'Agent dans le chat : *"Teste cette story ou ce lien"*.
-3. L'Agent lit automatiquement son cerveau (`agents/router.md`), allume son navigateur interne via MCP, explore votre site réel, et **génère le plan de test (dans `specs/`) ainsi que le code exact (dans `tests/`)**. Il n'y a plus aucune hallucination de sélecteurs CSS !
+---
 
-### Phase 2 : L'Exécution & Le Suivi (Via le Dashboard Web)
-4. Une fois que l'Agent a fait le gros du travail de création, vous ouvrez le Dashboard (`http://localhost:4000`).
-5. Vous cliquez sur **Full Pipeline** ou **Execute**. Le script `executor.js` lance Playwright en fond. Si une petite erreur de timing survient, le `healer.js` tente de la corriger.
-6. Les résultats JSON atterrissent dans `test-results/`.
-7. Vous naviguez dans **Runs** ou **Analytics**, pour voir l'historique complet, les rapports PDF/HTML et les graphiques de qualité !
+## Résumé du workflow
 
+```text
+1. Prérequis (IDE + Node.js)
+2. Dossier de test
+3. npx init
+4. npm install dépendances
+5. User story → user-story/
+6. Prompt : "Read router.md..."
+7. L'IA explore + plan → specs/  ← vous validez
+8. L'IA génère tests → tests/    ← vous validez
+9. npx playwright test
+10. allure open ou npm run dashboard
+```

package/README.md

@@ -260,38 +260,51 @@ The AI updates `docs/application-context.md` with:
 
 ---
 
-## Installation
+## Dépendances requises
 
-### Requirements
+Installez les dépendances selon vos besoins :
 
-| Component | Needed for | Install |
-|-----------|-----------|---------|
-| **Node.js 18+** | Running the pipeline | — |
-| **Playwright** | Test execution | Pre-installed via `npm install` |
-| **Chromium** | Running tests | `npx playwright install chromium` |
-| **Playwright MCP** | AI browser automation | Pre-installed via `npm install` |
-| **Applitools Eyes** | Visual testing + MCP | Pre-installed via `npm install` + `APPLITOOLS_API_KEY` |
-| **Allure** | Rich test reports | Pre-installed via `npm install` |
-| **GitHub MCP** | AI creating PRs/issues | `npm install -D @modelcontextprotocol/server-github` + `GITHUB_TOKEN` |
+### @playwright/test
+```bash
+npm install -D @playwright/test
+```
+Moteur de test E2E. **Requis.**
 
-### Install into a project
+### @types/node
+```bash
+npm install -D @types/node
+```
+Types Node.js (`process`, `Buffer`...). **Requis.**
 
+### allure-playwright
 ```bash
-npx @ai-qa/workflow init --yes
+npm install -D allure-playwright
 ```
+Reporter Allure pour Playwright. **Requis pour les rapports.**
 
-Or from local template:
+### allure-commandline
 ```bash
-node install.js ../my-project --yes
+npm install -D allure-commandline
 ```
+Génération du rapport HTML Allure. **Requis pour les rapports.**
 
-### Update
+### @applitools/eyes-playwright
+```bash
+npm install -D @applitools/eyes-playwright
+```
+Tests visuels Applitools Eyes. **Optionnel** (nécessite `APPLITOOLS_API_KEY`).
 
+### @modelcontextprotocol/server-github
 ```bash
-npx @ai-qa/workflow update --yes
+npm install -D @modelcontextprotocol/server-github
 ```
+Intégration GitHub (PRs, issues). **Optionnel** (nécessite `GITHUB_TOKEN`).
 
-> **Note:** The installer creates a `.env` template (`APPLITOOLS_API_KEY=""` and `GITHUB_TOKEN=""`...) only on fresh installs. If the `.env` file was not created (e.g., during an update), create it manually in your project root with those two keys.
+### Installation rapide (tout en une ligne)
+```bash
+npm install -D @playwright/test @types/node allure-playwright allure-commandline @applitools/eyes-playwright
+npx playwright install chromium
+```
 
 ---
 

package/install.js

@@ -8,12 +8,14 @@ const TEMPLATE_DIR =   __dirname;
 const YES = process.argv.includes('--yes') || process.argv.includes('-y');
 const IS_UPDATE = process.argv.includes('--update') || process.argv.includes('-u');
 const IS_SELF = process.argv.includes('--self') || process.argv.includes('-s');
+const IS_FORCE = process.argv.includes('--force') || process.argv.includes('-f');
 
 // Files that belong to the user — NEVER overwritten
 const USER_FILES = new Set([
   '.qa-workflow.json',
   'opencode.json',
   'docs/application-context.md',
+  'package.json',
 ]);
 
 // Directories that are pure user data — NEVER touched
@@ -24,7 +26,7 @@ const USER_DIRS = new Set([
   'test-results',
   '.qa-context',
   '.auth',
-  '.env'
+  '.env',
 ]);
 
 // Template files to copy/update
@@ -47,11 +49,13 @@ const QA_ITEMS = [
     { src: 'cli.js', dest: 'cli.js' },
     { src: 'package.json', dest: 'package.json' },
     { src: 'install.js', dest: 'install.js' },
+    { src: 'tsconfig.json', dest: 'tsconfig.json' },
+
 
     ];
 
-// Files to copy even during update (excludes user config files)
-const UPDATE_ITEMS = QA_ITEMS.filter(item => {
+// Files to copy even during update (excludes user config files unless --force)
+const UPDATE_ITEMS = IS_FORCE ? QA_ITEMS : QA_ITEMS.filter(item => {
   if (item.dir) return !USER_DIRS.has(item.dest);
   return !USER_FILES.has(item.dest);
 });
@@ -73,7 +77,7 @@ function copyRecursive(src, dest, skipDirs) {
     if (!fs.existsSync(dest)) fs.mkdirSync(dest, { recursive: true });
     fs.readdirSync(src).forEach(item => copyRecursive(path.join(src, item), path.join(dest, item), skipDirs));
   } else {
-    if (!fs.existsSync(dest) || fs.readFileSync(src).length !== fs.readFileSync(dest).length) {
+    if (!fs.existsSync(dest) || !fs.readFileSync(src).equals(fs.readFileSync(dest))) {
       fs.copyFileSync(src, dest);
       return true;
     }
@@ -125,6 +129,28 @@ async function install(targetPath, mode) {
     }
   }
 
+  // Warn about protected user files not updated during update
+  if (isUpdate && !IS_FORCE) {
+    const skipped = QA_ITEMS.filter(item => {
+      if (item.dir) return USER_DIRS.has(item.dest);
+      return USER_FILES.has(item.dest);
+    });
+    if (skipped.length) {
+      console.log(`\n  ── Protected files (use --force to overwrite) ──`);
+      for (const item of skipped) {
+        const srcStat = fs.existsSync(path.join(TEMPLATE_DIR, item.src));
+        const destStat = fs.existsSync(path.join(targetPath, item.dest));
+        if (srcStat && destStat) {
+          const changed = !fs.readFileSync(path.join(TEMPLATE_DIR, item.src))
+            .equals(fs.readFileSync(path.join(targetPath, item.dest)));
+          if (changed) {
+            console.log(`  ⚠  ${item.dest} (modified locally, skipped)`);
+          }
+        }
+      }
+    }
+  }
+
   // 2. Create directories (fresh install only)
   if (!isUpdate) {
     console.log(`\n  ── Step 2: Project Directories ──`);
@@ -160,11 +186,20 @@ async function install(targetPath, mode) {
       try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps installed`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
     } else {
       const skipDirs = new Set(['node_modules', 'data']);
+
+      // Detect if dashboard package.json changed
+      const dashPkgSrc = path.join(dashboardSrc, 'package.json');
+      const dashPkgDest = path.join(dashboardDest, 'package.json');
+      const pkgChanged = fs.existsSync(dashPkgSrc) && fs.existsSync(dashPkgDest) &&
+        !fs.readFileSync(dashPkgSrc).equals(fs.readFileSync(dashPkgDest));
+
       copyRecursive(dashboardSrc, dashboardDest, skipDirs);
       console.log(`  ✓ Dashboard updated (preserved data/, node_modules/)`);
-      if (!isUpdate) {
-        console.log(`  → Installing dashboard dependencies...`);
-        try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps installed`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
+
+      const needsInstall = !isUpdate || pkgChanged;
+      if (needsInstall) {
+        console.log(`  → ${pkgChanged ? 'package.json changed, updating' : 'Installing'} dashboard dependencies...`);
+        try { execSync('npm install', { cwd: dashboardDest, stdio: 'pipe', timeout: 120000 }); console.log(`  ✓ Dashboard deps ${pkgChanged ? 'updated' : 'installed'}`); } catch (e) { console.log(`  ⚠  cd qa-dashboard && npm install`); }
       }
     }
   }
@@ -208,6 +243,7 @@ async function install(targetPath, mode) {
 
   if (isUpdate) {
     console.log(`  Pipeline files updated. Your config and data are preserved.`);
+    if (!IS_FORCE) console.log(`  Use --force to overwrite protected files (package.json, .qa-workflow.json, etc.)`);
     console.log(`  Restart the dashboard if it was running.\n`);
   } else {
     console.log(`  Files: ~${totalFiles} scripts + ${dashboardCount} dashboard files`);
@@ -217,6 +253,7 @@ async function install(targetPath, mode) {
     console.log(`  npm run qa:init      Initialize pipeline (config + dirs + auth)`);
     console.log(`  npm run qa:execute   Run Playwright tests (auto-generates Allure report)`);
     console.log(`  npm run qa:status    Check pipeline state`);
+    console.log(`  npm run qa:update    Update pipeline files from template`);
     console.log(`  npm run dashboard    Start dashboard (port 4000)\n`);
   }
 }
@@ -243,11 +280,14 @@ AI QA Pipeline Installer
   FLAGS:
     --yes, -y    Skip all prompts
     --update,-u  Update mode (preserves config, stories, results)
+    --force,-f   Overwrite protected user files (package.json, .qa-workflow.json, ...)
 
   EXAMPLES:
     npx ai-qa-workflow init --yes
+    npx ai-qa-workflow update           Update pipeline in current project
     node install.js ../my-project --yes
     node install.js ../my-project --update
+    node install.js ../my-project --update --force
 `);
   process.exit(0);
 }

package/opencode.json

@@ -23,6 +23,12 @@
    }
      }
   },
+  "skill": {
+    "ai-qa-workflow": {
+      "description": "AI QA Workflow skill — Playwright E2E testing with Allure, Applitools, self-healing, and QA Dashboard integration. Use when writing, debugging, or reviewing tests in this project.",
+      "file": ".opencode/qa-workflow-skill.md"
+    }
+  },
   "agent": {
     "qa-planner": {
       "description": "Reads user story, explores website via Playwright MCP, creates test plan in specs/",