@keber/qa-framework 1.2.0-0 → 1.3.0-0

package/agent-instructions/00-module-analysis.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Module Analysis
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-module-analysis/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/00-module-analysis.md`  
 **Purpose**: Instructions for an AI agent to perform complete functional analysis of an application module and produce the 6-file specification set.
 

package/agent-instructions/01-spec-generation.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Specification Generation
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-spec-generation/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/01-spec-generation.md`  
 **Purpose**: Detailed instructions for generating the 6-file submodule specification set from a completed module analysis or from existing source material (UI observation, requirements docs, developer input).
 

package/agent-instructions/02-test-plan-generation.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Test Plan Generation
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-test-plan/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/02-test-plan-generation.md`  
 **Purpose**: Instructions for generating a test plan document for a module, after its spec set is complete.
 

package/agent-instructions/03-test-case-generation.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Test Case Generation
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-test-cases/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/03-test-case-generation.md`  
 **Purpose**: Instructions for writing detailed, standalone test case documents from approved spec scenarios.
 

package/agent-instructions/04-automation-generation.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Automation Generation
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-automation/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/04-automation-generation.md`  
 **Purpose**: Instructions for writing Playwright E2E automation tests that trace back to approved test cases in `01-specifications/`.
 

package/agent-instructions/04b-test-stabilization.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Test Stabilization
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-test-stabilization/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/04b-test-stabilization.md`  
 **Purpose**: Instructions for exhaustively reviewing and stabilizing generated Playwright tests to ensure they are logically correct, technically sound, and free of false positives and false negatives before ADO integration.
 

package/agent-instructions/05-ado-integration.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Azure DevOps Integration
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-ado-integration/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/05-ado-integration.md`  
 **Purpose**: Instructions for an agent to create, configure, and maintain Azure DevOps Test Plans integration with Playwright automation results.
 

package/agent-instructions/06-maintenance.md

@@ -1,5 +1,8 @@
 # Agent Instructions: Maintenance and Updates
 
+> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-maintenance/SKILL.md`.
+> Kept as reference during the transition period. Do not update this file.
+
 **File**: `agent-instructions/06-maintenance.md`  
 **Purpose**: Instructions for updating QA artifacts after application code changes.
 

package/docs/folder-structure-guide.md

@@ -15,7 +15,6 @@ qa/
 ├── QA-STRUCTURE-GUIDE.md        ← Copy of this guide (installed by framework)
 ├── qa-framework.config.json     ← Project configuration
 │
-├── 00-guides/                   ← Process guides and agent instructions
 ├── 00-standards/                ← Naming conventions and artifact templates
 ├── 01-specifications/           ← Functional specifications per module
 ├── 02-test-plans/               ← Test plans (scope + priority decisions)
@@ -28,28 +27,30 @@ qa/
 └── memory/                      ← Project QA learnings (project-maintained)
 ```
 
+Agent skills live in `.github/skills/` (not inside `qa/`). See the `.github/skills/` section below.
+
 ---
 
-## 00-guides/
+## .github/skills/
 
-**Purpose**: Process guides and operating instructions for both humans and agents.
+**Purpose**: 3-layer QA pipeline skills installed by the framework. Loaded by the agent on demand — only the relevant skill for the current task is loaded, not all skills at once.
 
-**Installed by framework** (not project-maintained):
+**Installed by framework** via `npm install @keber/qa-framework`:
 
-| File | Contents |
-|---|---|
-| `README.md` | Index with reading order by persona |
-| `AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md` | How to analyze a module (4-phase process) |
-| `AGENT-INSTRUCTIONS-SPEC-GENERATION.md` | How to produce the 6-file spec set |
-| `AGENT-INSTRUCTIONS-TEST-CASES.md` | How to write test case tables |
-| `AGENT-INSTRUCTIONS-AUTOMATION.md` | How to write Playwright E2E tests |
-| `AGENT-INSTRUCTIONS-ADO-INTEGRATION.md` | How to sync results with Azure DevOps |
-| `AGENT-INSTRUCTIONS-MAINTENANCE.md` | How to update QA artifacts after code changes |
-
-**Project-maintained** (added over time):
-- `DEBUG-ARTIFACTS-POLICY.md` — where to save screenshots and debug output
-- `NOTAS-TECNICAS-PLAYWRIGHT.md` — project-specific Playwright gotchas
-- `RETROSPECTIVA-*.md` — session debug chronicles (optional, high value)
+| Skill folder | Stage | When the agent loads it |
+|---|---|---|
+| `qa-module-analysis/` | 1 | Analyzing a new module or refreshing specs |
+| `qa-spec-generation/` | 2 | Writing the 6-file spec set |
+| `qa-test-plan/` | 3 | Creating a test plan document |
+| `qa-test-cases/` | 4 | Writing TC-*.md files |
+| `qa-automation/` | 5 | Implementing Playwright specs |
+| `qa-test-stabilization/` | 5b | Diagnosing and fixing failing tests |
+| `qa-ado-integration/` | opt | Syncing with Azure DevOps Test Plans |
+| `qa-maintenance/` | 6 | Updating specs and tests after app changes |
+
+Each skill folder contains:
+- `SKILL.md` — process outline (~400-600 tokens, always loaded when skill applies)
+- `references/` — detailed templates and code patterns (loaded on demand)
 
 ---
 

package/docs/skills-architecture.md

@@ -0,0 +1,136 @@
+# Skills Architecture
+
+> How QA agent skills are organized in `@keber/qa-framework`.
+
+---
+
+## Why Skills, Not Monolithic Instructions
+
+The previous `agent-instructions/` model loaded one large file (~2,500 tokens each) per task. For an automation session covering 3 submodules, the agent would load the full automation file whether it needed the ADO config or not. With 8 instruction files, that was 20,000+ tokens of constant context pressure.
+
+The 3-layer skill architecture reduces this to ~500 tokens for a typical task, loading detail only when needed.
+
+---
+
+## 3-Layer Model
+
+| Layer | Location | Size | Purpose |
+|---|---|---|---|
+| 1 — Descriptor | YAML frontmatter in `SKILL.md` | ~50 tokens | Name + description; used for relevance detection |
+| 2 — Process outline | `SKILL.md` body | ~400–600 tokens | Step-by-step process without code; always loaded when skill applies |
+| 3 — Reference material | `references/*.md` | ~500–1500 tokens each | Detailed templates, code patterns, decision trees; loaded on demand |
+
+The agent reads Layer 2 to understand what to do, then loads only the specific `references/` files it needs for the current step.
+
+---
+
+## Pipeline Sequence
+
+Skills map to the QA pipeline stages defined in `copilot-instructions.md`. The file acts as a **pipeline sequencer** — it defines which stage comes before which, and what the prerequisite is. Skills are the implementation of each stage.
+
+```
+Stage 1: qa-module-analysis      (no prerequisite)
+   │
+   ▼
+Stage 2: qa-spec-generation      (requires 00-inventory.md)
+   │
+   ▼
+Stage 3: qa-test-plan            (requires 05-test-scenarios.md)
+   │
+   ▼
+Stage 4: qa-test-cases           (requires test plan)
+   │
+   ▼
+Stage 5: qa-automation           (requires approved specs, no PENDING-CODE)
+   │
+   ├─ Stage 5b: qa-test-stabilization  (if tests fail)
+   │
+   ▼
+Stage 6: qa-maintenance          (after each application change)
+
+
+Optional (any time after Stage 4):
+   qa-ado-integration            (requires ADO enabled in config)
+```
+
+---
+
+## Skill Inventory
+
+| Skill | SKILL.md | References |
+|---|---|---|
+| `qa-module-analysis` | Stage 1 process (4 phases) | `exploration-checklist.md`, `spec-file-formats.md` |
+| `qa-spec-generation` | Stage 2 rules + anti-patterns | `spec-file-formats.md` (shared with qa-module-analysis) |
+| `qa-test-plan` | Stage 3 — priority + feasibility rules | `priority-and-feasibility.md` (includes full template) |
+| `qa-test-cases` | Stage 4 — TC document rules | `test-case-template.md` |
+| `qa-automation` | Stage 5 — patterns + completion checklist | `patterns.md`, `config-checklist.md` |
+| `qa-test-stabilization` | Stage 5b — 8 steps + confidence scoring | `classification-protocol.md` (includes report template) |
+| `qa-ado-integration` | Optional ADO sync — 6 steps | `scripts-and-config.md` |
+| `qa-maintenance` | Stage 6 — update rules | `update-rules.md` |
+
+---
+
+## How Skills Are Installed
+
+When a consumer project runs `npm install @keber/qa-framework`, the `postinstall` script (`scripts/init.js`) copies the entire `skills/` directory from the package to `.github/skills/` in the consumer project:
+
+```
+@keber/qa-framework/skills/
+  qa-module-analysis/
+    SKILL.md
+    references/
+      exploration-checklist.md
+      spec-file-formats.md
+  qa-spec-generation/
+    SKILL.md
+  ...
+
+→ copies to →
+
+{consumer-project}/.github/skills/
+  qa-module-analysis/
+    SKILL.md
+    references/
+      exploration-checklist.md
+      spec-file-formats.md
+  ...
+```
+
+The copy uses `writeIfMissing` — it will not overwrite files that already exist in the consumer project. This allows consumer projects to customize their `.github/skills/` without losing changes on re-install.
+
+---
+
+## How to Add a Project-Specific Skill
+
+Consumer projects can extend the skills by adding skill folders directly to `.github/skills/`:
+
+1. Create `.github/skills/{skill-name}/SKILL.md` with YAML frontmatter:
+   ```yaml
+   ---
+   name: my-custom-skill
+   description: >
+     Describe when this skill should be triggered.
+   ---
+   ```
+2. Add the skill body following the same 4-section structure: prerequisite → steps → rules → outputs
+3. Optionally add `references/*.md` for detailed templates
+4. Reference the skill from `copilot-instructions.md` if it's part of your pipeline
+
+Project-specific skills are not overwritten by `npm install` updates.
+
+---
+
+## Mapping: Old vs New
+
+| Former file | New skill | Token reduction |
+|---|---|---|
+| `agent-instructions/00-module-analysis.md` | `.github/skills/qa-module-analysis/SKILL.md` | ~2,500 → ~500 + on-demand references |
+| `agent-instructions/01-spec-generation.md` | `.github/skills/qa-spec-generation/SKILL.md` | ~2,800 → ~400 + shared references |
+| `agent-instructions/02-test-plan-generation.md` | `.github/skills/qa-test-plan/SKILL.md` | ~2,200 → ~400 + test-plan-template |
+| `agent-instructions/03-test-case-generation.md` | `.github/skills/qa-test-cases/SKILL.md` | ~2,100 → ~400 + tc-template |
+| `agent-instructions/04-automation-generation.md` | `.github/skills/qa-automation/SKILL.md` | ~3,500 → ~500 + patterns + config |
+| `agent-instructions/04b-test-stabilization.md` | `.github/skills/qa-test-stabilization/SKILL.md` | ~3,800 → ~500 + classification |
+| `agent-instructions/05-ado-integration.md` | `.github/skills/qa-ado-integration/SKILL.md` | ~2,400 → ~400 + scripts |
+| `agent-instructions/06-maintenance.md` | `.github/skills/qa-maintenance/SKILL.md` | ~1,700 → ~400 + update-rules |
+
+**Total context reduction**: ~21,000 tokens → ~3,500 tokens (Layer 2 only) + selective Layer 3 loading

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.2.0-0",
+  "version": "1.3.0-0",
   "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
   "keywords": [
     "qa",

package/scripts/cli.js

@@ -8,6 +8,7 @@
  *
  * Commands:
  *   init      Scaffold a qa/ folder structure from qa-framework.config.json
+ *   upgrade   Update framework-owned files after npm update (skills, copilot-instructions)
  *   generate  Generate an artifact (spec template, test plan, etc.)
  *   validate  Validate qa/ folder structure and conventions
  */
@@ -21,6 +22,7 @@ const [, , command, ...args] = process.argv;
 
 const commands = {
   init:     'init.js',
+  upgrade:  'upgrade.js',
   generate: 'generate.js',
   validate: 'validate.js',
 };
@@ -54,6 +56,7 @@ Usage:
 
 Commands:
   init [--config <path>]      Scaffold qa/ structure from config file
+  upgrade [--dry-run]         Update framework-owned files after npm update
   generate <artifact>         Generate from template
                                 artifact: spec | test-plan | test-case |
                                           execution-report | defect-report |
@@ -67,6 +70,8 @@ Options:
 Examples:
   qa-framework init
   qa-framework init --config ./my-project.config.json
+  qa-framework upgrade
+  qa-framework upgrade --dry-run
   qa-framework generate spec --module suppliers --submodule create
   qa-framework validate
   qa-framework validate --strict

package/scripts/init.js

@@ -77,7 +77,6 @@ process.stderr.write(`[qa-framework/init] Using config source: ${configSource}\n
 
 // --- Top-level folders ---
 const topLevelFolders = [
-  '00-guides',
   '00-standards',
   '01-specifications',
   '02-test-plans',
@@ -222,24 +221,18 @@ const adoDir = path.join(qaRoot, '08-azure-integration');
 writeIfMissing(path.join(adoDir, 'README.md'), `# ADO Integration\n\nSee keber/qa-framework integrations/ado-powershell/ for setup instructions.\n`);
 writeIfMissing(path.join(adoDir, 'module-registry.json'), JSON.stringify({ modules: [] }, null, 2));
 
-// --- Agent instructions → qa/00-guides/ ---
-const agentInstrSrc = path.resolve(__dirname, '..', 'agent-instructions');
-const guidesDir     = path.join(qaRoot, '00-guides');
-const agentFileMap  = {
-  '00-module-analysis.md':      'AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md',
-  '01-spec-generation.md':      'AGENT-INSTRUCTIONS-SPEC-GENERATION.md',
-  '02-test-plan-generation.md': 'AGENT-INSTRUCTIONS-TEST-PLAN.md',
-  '03-test-case-generation.md': 'AGENT-INSTRUCTIONS-TEST-CASES.md',
-  '04-automation-generation.md':'AGENT-INSTRUCTIONS-AUTOMATION.md',
-  '04b-test-stabilization.md':  'AGENT-INSTRUCTIONS-TEST-STABILIZATION.md',
-  '05-ado-integration.md':      'AGENT-INSTRUCTIONS-ADO-INTEGRATION.md',
-  '06-maintenance.md':          'AGENT-INSTRUCTIONS-MAINTENANCE.md',
-};
-for (const [src, dest] of Object.entries(agentFileMap)) {
-  const srcPath  = path.join(agentInstrSrc, src);
-  const destPath = path.join(guidesDir, dest);
-  if (fs.existsSync(srcPath)) {
-    writeIfMissing(destPath, fs.readFileSync(srcPath, 'utf8'));
+// --- Skills → .github/skills/ ---
+const skillsSrc = path.resolve(__dirname, '..', 'skills');
+const skillsDest = path.join(cwd, '.github', 'skills');
+fs.mkdirSync(skillsDest, { recursive: true });
+if (fs.existsSync(skillsSrc)) {
+  for (const skillName of fs.readdirSync(skillsSrc)) {
+    const skillSrcDir = path.join(skillsSrc, skillName);
+    if (!fs.statSync(skillSrcDir).isDirectory()) continue;
+    const skillDestDir = path.join(skillsDest, skillName);
+    fs.mkdirSync(skillDestDir, { recursive: true });
+    // Copy SKILL.md and references/ recursively
+    copyDirIfMissing(skillSrcDir, skillDestDir);
   }
 }
 
@@ -288,7 +281,7 @@ This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'}
 ## Agent behavior rules
 
 0. **On every conversation start:** check if \`qa/AGENT-NEXT-STEPS.md\` exists. If it does, read it and complete its steps before anything else.
-1. Before performing any QA task, read the relevant instruction file from \`qa/00-guides/\`. For project context, read \`qa/memory/INDEX.md\` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally.
+1. Before performing any QA task, load the relevant skill from \`.github/skills/\`. For project context, read \`qa/memory/INDEX.md\` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
 2. Always save artifacts in the correct \`qa/\` subfolder - refer to \`qa/QA-STRUCTURE-GUIDE.md\`
 3. Never hardcode credentials - always use env vars and \`<PLACEHOLDER>\` in documentation
 4. Follow the naming conventions in \`qa/00-standards/naming-conventions.md\`
@@ -301,18 +294,20 @@ This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'}
 1. Generate the output in \`UTF-8\` encoding without BOM (\`UTF-8\`, no signature).
 2. Ensure the raw output is \`UTF-8\` encoded with no \`EF BB BF\` bytes at the beginning.
 
-## Available agent instructions
+## QA Pipeline
 
-| Task | Instruction file |
-|---|---|
-| Analyze a module | \`qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md\` |
-| Generate specifications | \`qa/00-guides/AGENT-INSTRUCTIONS-SPEC-GENERATION.md\` |
-| Generate a test plan | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-PLAN.md\` |
-| Generate test cases | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-CASES.md\` |
-| Generate automation | \`qa/00-guides/AGENT-INSTRUCTIONS-AUTOMATION.md\` |
-| Stabilize failing tests | \`qa/00-guides/AGENT-INSTRUCTIONS-TEST-STABILIZATION.md\` |
-| Sync with Azure DevOps | \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` |
-| Maintenance after changes | \`qa/00-guides/AGENT-INSTRUCTIONS-MAINTENANCE.md\` |
+Stages must run in order. Never start a stage unless its prerequisite is met.
+
+| Stage | Task | Skill | Prerequisite |
+|---|---|---|---|
+| 1 | Analyze module | \`.github/skills/qa-module-analysis/SKILL.md\` | None |
+| 2 | Generate specifications | \`.github/skills/qa-spec-generation/SKILL.md\` | 00-inventory.md exists |
+| 3 | Generate test plan | \`.github/skills/qa-test-plan/SKILL.md\` | 05-test-scenarios.md exists |
+| 4 | Generate test cases | \`.github/skills/qa-test-cases/SKILL.md\` | Test plan exists |
+| 5 | Generate automation | \`.github/skills/qa-automation/SKILL.md\` | Specs approved, no PENDING-CODE |
+| 5b | Stabilize failing tests | \`.github/skills/qa-test-stabilization/SKILL.md\` | Failing tests exist |
+| 6 | Maintenance | \`.github/skills/qa-maintenance/SKILL.md\` | Application change delivered |
+| — | ADO integration | \`.github/skills/qa-ado-integration/SKILL.md\` | ADO enabled in config |
 
 ## Project KB
 1. \`qa/README.md\`          — The Living Index: module status, sprint history, blockers, quick-start commands.
@@ -368,6 +363,19 @@ function writeIfMissing(filePath, content) {
   }
 }
 
+function copyDirIfMissing(srcDir, destDir) {
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath  = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDirIfMissing(srcPath, destPath);
+    } else {
+      writeIfMissing(destPath, fs.readFileSync(srcPath, 'utf8'));
+    }
+  }
+}
+
 function specScaffold(modName, subName, modKey, subKey) {
   return `import { test, expect } from '@playwright/test';
 

package/scripts/upgrade.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * scripts/upgrade.js — Upgrade framework-owned files in an existing project
+ *
+ * Usage:
+ *   qa-framework upgrade
+ *   qa-framework upgrade --dry-run
+ *
+ * What this command does (safe by design):
+ *   ALWAYS updates (framework-owned):
+ *     - .github/skills/             ← New skills architecture; always current
+ *     - .github/copilot-instructions.md ← Pipeline sequencer; framework-owned
+ *     - qa/QA-STRUCTURE-GUIDE.md    ← Folder reference; framework-owned
+ *
+ *   NEVER touches (project-owned):
+ *     - qa/01-specifications/       ← Your specs
+ *     - qa/02-test-plans/           ← Your test plans
+ *     - qa/03-test-cases/           ← Your TCs
+ *     - qa/07-automation/           ← Your Playwright code
+ *     - qa/memory/                  ← Your learnings
+ *     - qa/README.md                ← Your living index
+ *     - qa/AGENT-NEXT-STEPS.md       ← Your sprint queue
+ *
+ *   REPORTS but does not delete:
+ *     - qa/00-guides/               ← Old location (can be deleted manually)
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const args   = process.argv.slice(2);
+const dryRun = args.includes('--dry-run');
+
+const cwd = process.env.INIT_CWD || process.cwd();
+
+// Resolve config (same logic as init.js)
+const rootConfigPath = path.resolve(cwd, 'qa-framework.config.json');
+const qaConfigPath   = path.resolve(cwd, 'qa', 'qa-framework.config.json');
+let config = {};
+
+const configFlag = args.indexOf('--config');
+if (configFlag !== -1 && args[configFlag + 1]) {
+  config = JSON.parse(fs.readFileSync(path.resolve(cwd, args[configFlag + 1]), 'utf8'));
+} else if (fs.existsSync(rootConfigPath)) {
+  config = JSON.parse(fs.readFileSync(rootConfigPath, 'utf8'));
+} else if (fs.existsSync(qaConfigPath)) {
+  config = JSON.parse(fs.readFileSync(qaConfigPath, 'utf8'));
+}
+
+const qaRoot     = path.join(cwd, 'qa');
+const githubDir  = path.join(cwd, '.github');
+const skillsDest = path.join(githubDir, 'skills');
+const skillsSrc  = path.resolve(__dirname, '..', 'skills');
+
+const updated  = [];
+const skipped  = [];
+const warnings = [];
+
+console.log(`\n[qa-framework/upgrade] ${dryRun ? '(dry-run) ' : ''}Upgrading framework-owned files`);
+console.log(`[qa-framework/upgrade] Project root: ${cwd}\n`);
+
+// ---------------------------------------------------------------------------
+// 1. .github/skills/ — always overwrite (framework-owned)
+// ---------------------------------------------------------------------------
+if (!fs.existsSync(skillsSrc)) {
+  warnings.push('skills/ source directory not found in package — skipping skill install');
+} else {
+  fs.mkdirSync(skillsDest, { recursive: true });
+  copyDirForce(skillsSrc, skillsDest);
+}
+
+// ---------------------------------------------------------------------------
+// 2. .github/copilot-instructions.md — overwrite (framework-owned sequencer)
+// ---------------------------------------------------------------------------
+const copilotInstrPath = path.join(githubDir, 'copilot-instructions.md');
+const copilotContent = buildCopilotInstructions(config);
+forceWrite(copilotInstrPath, copilotContent);
+
+// ---------------------------------------------------------------------------
+// 3. qa/QA-STRUCTURE-GUIDE.md — overwrite (framework doc)
+// ---------------------------------------------------------------------------
+const structureGuideSrc  = path.resolve(__dirname, '..', 'docs', 'folder-structure-guide.md');
+const structureGuideDest = path.join(qaRoot, 'QA-STRUCTURE-GUIDE.md');
+if (fs.existsSync(structureGuideSrc) && fs.existsSync(qaRoot)) {
+  forceWrite(structureGuideDest, fs.readFileSync(structureGuideSrc, 'utf8'));
+}
+
+// ---------------------------------------------------------------------------
+// 4. Migration: report qa/00-guides/ if still present
+// ---------------------------------------------------------------------------
+const oldGuidesDir = path.join(qaRoot, '00-guides');
+if (fs.existsSync(oldGuidesDir)) {
+  warnings.push(
+    `qa/00-guides/ still exists (old location). It can be deleted:\n` +
+    `    Remove-Item -Recurse -Force qa/00-guides`
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+console.log('\n--- Results ---');
+if (updated.length) {
+  console.log('\n  Updated (framework-owned):');
+  for (const f of updated) console.log(`    ✅ ${path.relative(cwd, f)}`);
+}
+if (skipped.length) {
+  console.log('\n  Skipped (already up to date):');
+  for (const f of skipped) console.log(`    — ${path.relative(cwd, f)}`);
+}
+if (warnings.length) {
+  console.log('\n  Warnings:');
+  for (const w of warnings) console.log(`    ⚠️  ${w}`);
+}
+
+console.log('\n[qa-framework/upgrade] Done.\n');
+
+// -----------------------------------------------------------------------
+// Helpers
+// -----------------------------------------------------------------------
+
+function forceWrite(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const exists  = fs.existsSync(filePath);
+  const changed = !exists || fs.readFileSync(filePath, 'utf8') !== content;
+  if (dryRun) {
+    if (changed) updated.push(filePath);
+    else skipped.push(filePath);
+    return;
+  }
+  fs.writeFileSync(filePath, content, 'utf8');
+  if (changed) updated.push(filePath);
+  else skipped.push(filePath);
+}
+
+function copyDirForce(srcDir, destDir) {
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath  = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      fs.mkdirSync(destPath, { recursive: true });
+      copyDirForce(srcPath, destPath);
+    } else {
+      forceWrite(destPath, fs.readFileSync(srcPath, 'utf8'));
+    }
+  }
+}
+
+function buildCopilotInstructions(cfg) {
+  const version = cfg.frameworkVersion ?? '1.0.0';
+  return `# QA Framework Instructions
+
+This project uses \`@keber/qa-framework\` v${version} for spec-driven automated testing.
+
+## Agent behavior rules
+
+0. **On every conversation start:** check if \`qa/AGENT-NEXT-STEPS.md\` exists. If it does, read it and complete its steps before anything else.
+1. Before performing any QA task, load the relevant skill from \`.github/skills/\`. For project context, read \`qa/memory/INDEX.md\` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
+2. Always save artifacts in the correct \`qa/\` subfolder — refer to \`qa/QA-STRUCTURE-GUIDE.md\`
+3. Never hardcode credentials — always use env vars and \`<PLACEHOLDER>\` in documentation
+4. Follow the naming conventions in \`qa/00-standards/naming-conventions.md\`
+5. Project QA config is at \`qa/qa-framework.config.json\`
+6. Save learnings in \`qa/memory/\` with proper naming and metadata. Always update \`qa/memory/INDEX.md\` after adding or updating any memory file.
+7. **On module/sprint completion** (all TCs passing): (1) update the module status row in \`qa/README.md\`; (2) move the completed sprint checklist from \`AGENT-NEXT-STEPS.md\` to the \`## Sprint History\` section of \`qa/README.md\`; (3) trim \`AGENT-NEXT-STEPS.md\` so it contains only the next sprint — never let it accumulate more than one active sprint.
+
+## QA Pipeline
+
+Stages must run in order. Never start a stage unless its prerequisite is met.
+
+| Stage | Task | Skill | Prerequisite |
+|---|---|---|---|
+| 1 | Analyze module | \`.github/skills/qa-module-analysis/SKILL.md\` | None |
+| 2 | Generate specifications | \`.github/skills/qa-spec-generation/SKILL.md\` | 00-inventory.md exists |
+| 3 | Generate test plan | \`.github/skills/qa-test-plan/SKILL.md\` | 05-test-scenarios.md exists |
+| 4 | Generate test cases | \`.github/skills/qa-test-cases/SKILL.md\` | Test plan exists |
+| 5 | Generate automation | \`.github/skills/qa-automation/SKILL.md\` | Specs approved, no PENDING-CODE |
+| 5b | Stabilize failing tests | \`.github/skills/qa-test-stabilization/SKILL.md\` | Failing tests exist |
+| 6 | Maintenance | \`.github/skills/qa-maintenance/SKILL.md\` | Application change delivered |
+| — | ADO integration | \`.github/skills/qa-ado-integration/SKILL.md\` | ADO enabled in config |
+
+## Project KB
+1. \`qa/README.md\`          — The Living Index: module status, sprint history, blockers, quick-start commands.
+2. \`qa/memory/INDEX.md\`    — Index of all memory files; load this before selecting which files to read.
+`;
+}