@keber/qa-framework 1.6.2 → 1.7.0

package/CHANGELOG.md

@@ -33,6 +33,31 @@ has been removed or parameterized. See `docs/comparison-matrix.md` and `docs/gen
 
 ---
 
+## [1.7.0] - 2026-05-06
+
+### Changed
+
+- **Agent instructions moved to `.github/instructions/qa-framework.instructions.md`** — the
+  framework no longer writes to `.github/copilot-instructions.md`. The new file is a VS Code
+  `*.instructions.md` file with `applyTo: '**'` frontmatter, which Copilot loads automatically.
+  This eliminates the conflict between framework-owned rules and project-owned custom instructions:
+  both files coexist independently and the framework file is freely upgradeable.
+
+### Added
+
+- **`upgrade` step 2b — automatic migration of old `copilot-instructions.md`**:
+  - If the file contains only QA Framework content (any previous version) → the file is deleted.
+  - If the file contains custom instructions and a QA Framework section → the QA section is stripped and the custom content is preserved.
+  - If the file contains no QA Framework content → the file is left untouched.
+  The detection marker is the heading `# QA Framework Instructions`, consistent across all versions.
+
+### Migration
+
+Run `npx qa-framework upgrade`. No manual steps required.
+See `MIGRATION-NOTES.md` — section "Upgrading from a version that used `.github/copilot-instructions.md`".
+
+---
+
 ## [1.6.2] - 2026-05-05
 
 ### Added

package/README.md

@@ -1,7 +1,7 @@
 # qa-framework
 
 > Reusable, installable, agent-oriented QA framework for spec-driven automated testing.
-> Current version: **v1.6.2**
+> Current version: **v1.7.0**
 
 ---
 
@@ -61,7 +61,7 @@ npm install @keber/qa-framework
 1. Create the `qa/` directory tree in your project root
 2. Copy all base templates into place
 3. Create `qa/qa-framework.config.json` for project-specific settings
-4. Generate `.github/copilot-instructions.md` with QA agent behavior rules (11 rules + ADO detection)
+4. Generate `.github/instructions/qa-framework.instructions.md` with QA agent behavior rules (11 rules + ADO detection)
 5. Copy the `skills/` set to `.github/skills/` so the agent can load them on demand
 6. Create `qa/AGENT-NEXT-STEPS.md` with follow-up steps
 
@@ -73,9 +73,13 @@ After `npm update @keber/qa-framework`, run:
 npx qa-framework upgrade
 ```
 
-This overwrites **only** framework-owned files (skills, `copilot-instructions.md`,
+This overwrites **only** framework-owned files (skills, `qa-framework.instructions.md`,
 `QA-STRUCTURE-GUIDE.md`) and never touches your specs, test plans, automation code, or memory.
 
+If upgrading from a version that wrote to `.github/copilot-instructions.md`, `upgrade`
+automatically removes the QA section from that file (or deletes it if it contained only
+framework content), and creates `.github/instructions/qa-framework.instructions.md` instead.
+
 ---
 
 ## Repository Structure (this package)
@@ -148,7 +152,7 @@ qa-framework/
 │
 └── scripts/                          <- CLI commands
     ├── cli.js                        <- Entry point (qa-framework <command>)
-    ├── init.js                       <- Scaffold qa/ tree + skills + copilot-instructions
+    ├── init.js                       <- Scaffold qa/ tree + skills + qa-framework.instructions.md
     ├── upgrade.js                    <- Refresh framework-owned files after npm update
     ├── generate.js                   <- Generate individual artifact from template
     └── validate.js                   <- Check structure compliance
@@ -194,10 +198,15 @@ Additionally, `init` writes to the project root:
 
 ```
 .github/
-├── copilot-instructions.md      <- Generated agent rules (11 rules + ADO detection)
-└── skills/                      <- Copied from package skills/ (one folder per pipeline stage)
+├── instructions/
+│   └── qa-framework.instructions.md  <- QA agent rules (framework-owned, applyTo: '**')
+└── skills/                           <- Copied from package skills/ (one folder per pipeline stage)
 ```
 
+> `qa-framework.instructions.md` is a VS Code `*.instructions.md` file, separate from any
+> custom `.github/copilot-instructions.md` the project may already have. The two files
+> coexist without conflict and are independently upgradeable.
+
 See [docs/folder-structure-guide.md](docs/folder-structure-guide.md) for a full explanation of every folder.
 
 ---
@@ -218,7 +227,7 @@ them via `read_file` without touching `node_modules`.
 
 ### QA Pipeline
 
-Skills map to the pipeline stages enforced by `.github/copilot-instructions.md`:
+Skills map to the pipeline stages enforced by `.github/instructions/qa-framework.instructions.md`:
 
 | Stage | Skill | Task | Track | Prerequisite |
 |---|---|---|---|---|
@@ -254,7 +263,7 @@ Options:
   --version, -v               Show version
 ```
 
-**upgrade** overwrites only framework-owned files (skills, `copilot-instructions.md`,
+**upgrade** overwrites only framework-owned files (skills, `qa-framework.instructions.md`,
 `QA-STRUCTURE-GUIDE.md`) and never touches project-owned files. Run `--dry-run` to preview
 without writing.
 

package/docs/installation.md

@@ -51,7 +51,7 @@ qa/
 └── 08-azure-integration/README.md
 └── memory/INDEX.md
 
-.github/copilot-instructions.md     <- Generated agent rules
+.github/instructions/qa-framework.instructions.md  <- QA agent rules (framework-owned)
 .github/skills/                     <- 8 agent skill sets (SKILL.md + references/)
 ```
 
@@ -93,7 +93,7 @@ After `npm update @keber/qa-framework`:
 npx qa-framework upgrade
 ```
 
-This overwrites only framework-owned files (`.github/skills/`, `copilot-instructions.md`,
+This overwrites only framework-owned files (`.github/skills/`, `.github/instructions/qa-framework.instructions.md`,
 `QA-STRUCTURE-GUIDE.md`) and migrates the `07-automation/` structure if upgrading from
 v1.5.x. Your specs, tests, and memory are never touched.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.6.2",
+  "version": "1.7.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/init.js

@@ -253,9 +253,9 @@ if (fs.existsSync(structureGuideSrc)) {
   writeIfMissing(structureGuideDest, fs.readFileSync(structureGuideSrc, 'utf8'));
 }
 
-// --- .github/copilot-instructions.md ---
+// --- .github/instructions/qa-framework.instructions.md ---
 const githubDir         = path.join(cwd, '.github');
-const copilotInstrPath  = path.join(githubDir, 'copilot-instructions.md');
+const copilotInstrPath  = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
 
 // Detect whether the ado-qa skill is available (installed or already copied)
 const adoQaInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@keber', 'ado-qa'))
@@ -284,7 +284,10 @@ Refer to \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` for the full ADO
 > This will automatically copy the ADO skills to \`.github/skills/\` via postinstall.
 `;
 
-const copilotInstrContent = `# QA Framework Instructions
+const copilotInstrContent = `---
+applyTo: '**'
+---
+# QA Framework Instructions
 
 This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'} for spec-driven automated testing.
 
@@ -337,7 +340,7 @@ const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 ## What was scaffolded
 
 - \`qa/\` folder structure with spec templates and agent instructions
-- \`.github/copilot-instructions.md\` with QA agent behavior rules
+- \`.github/instructions/qa-framework.instructions.md\` with QA agent behavior rules (framework-owned, safe to upgrade)
 
 ## Required next steps
 

package/scripts/upgrade.js

@@ -81,12 +81,48 @@ if (!fs.existsSync(skillsSrc)) {
 }
 
 // ---------------------------------------------------------------------------
-// 2. .github/copilot-instructions.md — overwrite (framework-owned sequencer)
+// 2. .github/instructions/qa-framework.instructions.md — overwrite (framework-owned)
 // ---------------------------------------------------------------------------
-const copilotInstrPath = path.join(githubDir, 'copilot-instructions.md');
+const copilotInstrPath = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
 const copilotContent = buildCopilotInstructions(config);
 forceWrite(copilotInstrPath, copilotContent);
 
+// ---------------------------------------------------------------------------
+// 2b. Migration: strip QA Framework section from old copilot-instructions.md
+//
+// Handles all cases:
+//   A. File has custom instructions + QA section  → keep custom, strip QA section
+//   B. File has ONLY QA section (any version)     → delete the file
+//   C. File does not mention QA Framework         → leave untouched
+//
+// The QA section always starts with "# QA Framework Instructions" across all
+// previous versions, so that heading is the reliable split point.
+// ---------------------------------------------------------------------------
+const oldCopilotPath = path.join(githubDir, 'copilot-instructions.md');
+if (fs.existsSync(oldCopilotPath)) {
+  const oldContent = fs.readFileSync(oldCopilotPath, 'utf8');
+  const qaMarker   = '# QA Framework Instructions';
+  const qaIdx      = oldContent.indexOf(qaMarker);
+
+  if (qaIdx !== -1) {
+    // Extract anything before the QA section, removing any trailing separator
+    const before = oldContent.slice(0, qaIdx).replace(/\s*\n---\s*$/, '').trim();
+
+    if (before.length === 0) {
+      // Case B: file contained only QA Framework content → delete it
+      if (!dryRun) fs.unlinkSync(oldCopilotPath);
+      updated.push(oldCopilotPath);
+      console.log(`  [deleted]  .github/copilot-instructions.md (contained only QA Framework rules — now in .github/instructions/qa-framework.instructions.md)`);
+    } else {
+      // Case A: file had custom content too → write back only the custom part
+      if (!dryRun) fs.writeFileSync(oldCopilotPath, before + '\n', 'utf8');
+      updated.push(oldCopilotPath);
+      console.log(`  [cleaned]  .github/copilot-instructions.md — removed QA Framework section, kept custom instructions`);
+    }
+  }
+  // Case C: no QA marker found → leave untouched (no log noise)
+}
+
 // ---------------------------------------------------------------------------
 // 3. qa/QA-STRUCTURE-GUIDE.md — overwrite (framework doc)
 // ---------------------------------------------------------------------------
@@ -278,7 +314,10 @@ function copyDirForce(srcDir, destDir) {
 
 function buildCopilotInstructions(cfg) {
   const version = cfg.frameworkVersion ?? '1.0.0';
-  return `# QA Framework Instructions
+  return `---
+applyTo: '**'
+---
+# QA Framework Instructions
 
 This project uses \`@keber/qa-framework\` v${version} for spec-driven automated testing.