@keber/qa-framework 1.5.2 → 1.6.2

package/CHANGELOG.md

@@ -33,21 +33,80 @@ has been removed or parameterized. See `docs/comparison-matrix.md` and `docs/gen
 
 ---
 
-## [Unreleased]
+## [1.6.2] - 2026-05-05
 
 ### Added
 
-- **Stage 3.5 — Test Stabilization** (`agent-instructions/04b-test-stabilization.md`) — new agent
-  instruction file for exhaustively reviewing and stabilizing generated Playwright tests before
-  ADO integration. Covers baseline collection, failure classification (9 categories), false-positive
-  validation, confidence scoring (≥90% exit threshold), `STABILIZATION-REPORT.md` schema, and
-  upstream artifact update rules. Sits between Stage 4 (Automation Generation) and Stage 5
-  (ADO Integration) and is mandatory before any CI pipeline registration.
+- **`tests/helpers/debug/`** — diagnostic scripts directory created by `init` and `upgrade` inside
+  `07-automation/e2e/tests/`. Scripts here are excluded from test runs via `testIgnore`.
+- **`tests/seeds/`** — data seeding specs directory created by `init` and `upgrade` inside
+  `07-automation/e2e/tests/`. Excluded from test runs via `testIgnore`.
+- **`testIgnore`** in `playwright.config.ts` template — excludes `**/helpers/debug/**` and
+  `**/seeds/**` from Playwright test discovery.
+- **`upgrade` step 5e** — patches existing `playwright.config.ts` in `e2e/`: replaces
+  `testDir: '.'` with `'./tests'`, injects `testIgnore` if missing, creates `helpers/debug/`
+  and `seeds/` if absent.
+- **Dual-Track Pipeline** section in `docs/folder-structure-guide.md` and `qa/QA-STRUCTURE-GUIDE.md`
+  — documents the automation track and manual track as parallel paths sharing `01-specifications/`
+  as source of truth. Includes entry point table (3 scenarios) and track selection guidance.
+  Clarifies that `03-test-cases/` is the manual track artifact and `04-test-data/` is optional.
+
+### Fixed
+
+- `qa/QA-STRUCTURE-GUIDE.md` — removed stale reference to deleted `docs/generalization-decisions.md`
+  from the `06-defects/` section.
+- `README.md` — pipeline table updated with Track column; `03-test-cases/` and `04-test-data/`
+  annotated as manual-track / optional in the directory tree.
+
+---
+
+## [1.6.0] - 2026-04-29
+
+### Changed (breaking - automated by `upgrade`)
+
+- **`07-automation/` restructured**: the Playwright project root moves from `07-automation/` to
+  `07-automation/e2e/`. Affected files: `playwright.config.ts`, `global-setup.ts`, `package.json`,
+  `.env.example`, `fixtures/`. Spec stubs move from `07-automation/e2e/{module}/` to
+  `07-automation/e2e/tests/{module}/`. Run `npx qa-framework upgrade` to migrate automatically.
+- `testDir` in `playwright.config.ts` template is now `'./tests'` (was `'.'`).
+- `QA_DIR` in the Azure Pipeline template now points to `qa/07-automation/e2e` (was `qa/07-automation`).
+- CI commands: `cd qa/07-automation/e2e && npm install && npx playwright install chromium`.
+
+### Removed
+
+- `agent-instructions/` directory (legacy monolithic per-task instruction files) — superseded by `skills/`
+  architecture since v1.5.0. All behavior is now in `skills/*/SKILL.md` + `references/`.
+- `docs/comparison-matrix.md` — superseded by `docs/skills-architecture.md`.
+- `docs/generalization-decisions.md` — internal design notes; no longer relevant.
+
+### Documentation
+
+- `docs/architecture.md` — updated for v1.6.0: correct 07-automation/e2e/ tree, removed blazor-radzen
+  stub, added `.github/skills/` and `memory/` to target project box.
+- `docs/installation.md` — rewritten: correct `npm install` command, no interactive prompts, correct
+  directory tree with e2e/integration/load, added `upgrade` command section.
+- `docs/usage-with-agent.md` — rewritten: all `00-guides/` references replaced with `.github/skills/`,
+  session workflows updated to reflect skills model, DO/DON'T list corrected (e2e/ is now correct run location).
+- `README.md` — version bumped, `agent-instructions/` entry removed from package tree.
+
+### Added
+
+- `07-automation/integration/` — placeholder for API/integration tests (k6, JMeter, Azure Load Testing);
+  created on `init` and `upgrade`.
+- `07-automation/load/` — placeholder for load and performance tests; created on `init` and `upgrade`.
+- **`scripts/upgrade.js` migration section 5** — detects old v1.5.x structure and relocates all
+  affected files non-destructively (moves only when destination does not exist; warns on conflict).
+- **Stage 5b - Test Stabilization** (`skills/qa-test-stabilization/`) — skill for exhaustively
+  reviewing and stabilizing generated Playwright tests before ADO integration. Covers baseline
+  collection, failure classification (9 categories), false-positive validation, confidence scoring
+  (>=90% exit threshold), `STABILIZATION-REPORT.md` schema, and upstream artifact update rules.
 
 ### Planned
 
 - `qa-framework generate spec <module-name>` — scaffold a full spec set from CLI
 - `qa-framework validate` — check `qa/` structure for compliance with conventions
-- `qa-framework upgrade` — migrate old embedded structure to package-based layout
 - Integration: `jest` support alongside Playwright
 - Integration: GitHub Actions pipeline template (alongside existing Azure Pipelines template)
+
+---
+

package/README.md

@@ -1,16 +1,17 @@
 # qa-framework
 
 > Reusable, installable, agent-oriented QA framework for spec-driven automated testing.
+> Current version: **v1.6.2**
 
 ---
 
 ## What is this?
 
-`qa-framework` is a methodology package that provides:
+`@keber/qa-framework` is a methodology package that provides:
 
 - **A standardized `qa/` directory structure** for any project
 - **Reusable templates** for specifications, test plans, test cases, defect reports, and execution reports
-- **Agent instructions** (for GitHub Copilot and equivalent IDE agents) that enable AI-assisted QA work
+- **Agent skills** (for GitHub Copilot and equivalent IDE agents) that enable AI-assisted QA work via a 3-layer skills architecture
 - **Optional integrations** for Playwright and Azure DevOps
 - **Bootstrap commands** to scaffold the structure into any project in seconds
 
@@ -20,7 +21,7 @@ This framework was designed to be:
 |---|---|
 | **Reusable** | Not tied to any specific project, domain, or tech stack |
 | **Decoupled** | Core is independent from Azure DevOps, Playwright, or any other tool |
-| **Agent-oriented** | Instructions are written for IDE agents (Copilot, etc.) to consume |
+| **Agent-oriented** | Skills are written for IDE agents (Copilot, etc.) to consume with minimal token overhead |
 | **Spec-driven** | Every automation artifact traces back to a specification |
 | **Extensible** | Adapters/plugins for optional integrations are well-separated |
 
@@ -34,17 +35,19 @@ This framework was designed to be:
 npm install @keber/qa-framework
 ```
 
-The postinstall script scaffolds the `qa/` structure automatically. No need to run `init` manually.
+The `postinstall` script runs `init --skip-if-exists` automatically, scaffolding the `qa/`
+structure on first install without overwriting existing files.
 
 ### Using with an AI agent (GitHub Copilot, Claude, etc.)
 
 Use this prompt in your IDE agent chat:
 
 ```
-Install @keber/qa-framework, check it's readme file and set up the project for integration with azure devops
+Install @keber/qa-framework, check its readme file and set up the project for integration with azure devops
 ```
 
-The install creates `qa/AGENT-NEXT-STEPS.md` with the exact steps the agent needs to complete the setup (optional integrations, module configuration, credentials, etc.).
+The install creates `qa/AGENT-NEXT-STEPS.md` with the exact steps the agent needs to complete
+the setup (optional integrations, module configuration, credentials, etc.).
 
 ### Using manually (without an agent)
 
@@ -53,13 +56,25 @@ npm install @keber/qa-framework
 # then read qa/AGENT-NEXT-STEPS.md for next steps
 ```
 
-The `init` command will:
+`init` will:
 
 1. Create the `qa/` directory tree in your project root
-2. Copy all base templates and agent instructions into place
+2. Copy all base templates into place
 3. Create `qa/qa-framework.config.json` for project-specific settings
-4. Create `.github/copilot-instructions.md` with QA agent behavior rules
-5. Create `qa/AGENT-NEXT-STEPS.md` with follow-up steps
+4. Generate `.github/copilot-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
+
+### Upgrading
+
+After `npm update @keber/qa-framework`, run:
+
+```bash
+npx qa-framework upgrade
+```
+
+This overwrites **only** framework-owned files (skills, `copilot-instructions.md`,
+`QA-STRUCTURE-GUIDE.md`) and never touches your specs, test plans, automation code, or memory.
 
 ---
 
@@ -67,33 +82,32 @@ The `init` command will:
 
 ```
 qa-framework/
-├── README.md                         ← This file
-├── CHANGELOG.md                      ← Version history
-├── MIGRATION-NOTES.md                ← How to migrate from embedded to package
-├── package.json                      ← npm descriptor
-├── qa-framework.config.json          ← Example config (copy to project)
+├── README.md                         <- This file
+├── CHANGELOG.md                      <- Version history
+├── package.json                      <- npm descriptor
+├── qa-framework.config.json          <- Example config (copy to project)
 │
-├── docs/                             ← Framework documentation
-│   ├── architecture.md               ← Design decisions and component map
-│   ├── comparison-matrix.md          ← Source-repo analysis (Phase 1 artifact)
-│   ├── generalization-decisions.md   ← What was abstracted and why (Phase 2 artifact)
-│   ├── installation.md               ← Detailed installation guide
-│   ├── usage-with-agent.md           ← How to use the framework with an IDE agent
-│   ├── spec-driven-philosophy.md     ← Core QA methodology
-│   └── folder-structure-guide.md     ← Explanation of every qa/ folder
+├── docs/                             <- Framework documentation
+│   ├── architecture.md               <- Design decisions and component map
+│   ├── skills-architecture.md        <- 3-layer skills model explanation
+│   ├── installation.md               <- Detailed installation guide
+│   ├── usage-with-agent.md           <- How to use the framework with an IDE agent
+│   ├── spec-driven-philosophy.md     <- Core QA methodology
+│   └── folder-structure-guide.md     <- Explanation of every qa/ folder
 │
-├── agent-instructions/               ← Instructions for AI agents, per task
-│   ├── 00-module-analysis.md
-│   ├── 01-spec-generation.md
-│   ├── 02-test-plan-generation.md
-│   ├── 03-test-case-generation.md
-│   ├── 04-automation-generation.md
-│   ├── 04b-test-stabilization.md
-│   ├── 05-ado-integration.md
-│   └── 06-maintenance.md
+├── skills/                           <- Agent skills (3-layer model; copied to .github/skills/ on init)
+│   ├── qa-module-analysis/           <- Stage 1: analyze a module, produce 6-file spec set
+│   ├── qa-spec-generation/           <- Stage 2: generate/update the 6-file spec set
+│   ├── qa-test-plan/                 <- Stage 3: generate a test plan
+│   ├── qa-test-cases/                <- Stage 4: generate individual TC-{ID}.md files
+│   ├── qa-automation/                <- Stage 5: implement Playwright automation
+│   ├── qa-test-stabilization/        <- Stage 5b: stabilize failing tests
+│   ├── qa-maintenance/               <- Stage 6: update artifacts after app changes
+│   └── qa-ado-integration/           <- Optional: sync with Azure DevOps
+│       (each skill contains SKILL.md + references/*.md)
 │
-├── templates/                        ← Reusable file templates
-│   ├── specification/                ← 6-file submodule set
+├── templates/                        <- Reusable file templates
+│   ├── specification/                <- 6-file submodule set
 │   │   ├── 00-inventory.md
 │   │   ├── 01-business-rules.md
 │   │   ├── 02-workflows.md
@@ -105,15 +119,17 @@ qa-framework/
 │   ├── execution-report.md
 │   ├── defect-report.md
 │   ├── session-summary.md
-│   └── automation-scaffold/          ← Files to bootstrap a Playwright E2E project
+│   ├── qa-readme.md                  <- Template for qa/README.md
+│   └── automation-scaffold/          <- Files to bootstrap a Playwright E2E project
 │       ├── package.json
 │       ├── playwright.config.ts
 │       ├── global-setup.ts
 │       ├── .env.example
 │       └── fixtures/
-│           └── auth.ts
+│           ├── auth.ts
+│           └── test-helpers.ts
 │
-├── integrations/                     ← Optional integration adapters
+├── integrations/                     <- Optional integration adapters
 │   ├── playwright/
 │   │   └── README.md
 │   ├── playwright-azure-reporter/
@@ -125,16 +141,17 @@ qa-framework/
 │           ├── create-testplan-from-mapping.ps1
 │           └── sync-ado-titles.ps1
 │
-├── examples/                         ← Reference examples (non-project-specific)
+├── examples/                         <- Reference examples (non-project-specific)
 │   └── module-example/
 │       ├── README.md
-│       └── submodule-example/        ← Full 6-file spec example
+│       └── submodule-example/        <- Full 6-file spec example
 │
-└── scripts/                          ← CLI commands
-    ├── cli.js                        ← Entry point (qa-framework <command>)
-    ├── init.js                       ← Scaffold qa/ tree
-    ├── generate.js                   ← Generate individual artifact
-    └── validate.js                   ← Check structure compliance
+└── scripts/                          <- CLI commands
+    ├── cli.js                        <- Entry point (qa-framework <command>)
+    ├── init.js                       <- Scaffold qa/ tree + skills + copilot-instructions
+    ├── upgrade.js                    <- Refresh framework-owned files after npm update
+    ├── generate.js                   <- Generate individual artifact from template
+    └── validate.js                   <- Check structure compliance
 ```
 
 ---
@@ -145,46 +162,102 @@ When you run `qa-framework init`, this structure is created inside your project:
 
 ```
 qa/
-├── README.md                    ← Living index of all QA artifacts
-├── QA-STRUCTURE-GUIDE.md        ← Local copy of the structure guide
+├── README.md                    <- Living index of all QA artifacts
+├── QA-STRUCTURE-GUIDE.md        <- Local copy of the structure guide (framework-owned)
+├── AGENT-NEXT-STEPS.md          <- Active sprint checklist for the agent
 │
-├── 00-guides/                   ← Process guides and agent instructions
-├── 00-standards/                ← Naming conventions, templates, data policies
-├── 01-specifications/           ← Functional specs by module/submodule
-├── 02-test-plans/               ← Test plans (automated + manual)
-├── 03-test-cases/               ← Explicit test case documents
-├── 04-test-data/                ← Test data, fixtures, factories
-├── 05-test-execution/           ← Execution reports and results
-├── 06-defects/                  ← Defect tracking (optional)
-├── 07-automation/               ← Automation code and config
-└── 08-azure-integration/        ← Azure DevOps integration (optional)
+├── 00-standards/                <- Naming conventions, templates, data policies
+├── 01-specifications/           <- Functional specs (used by generate command)
+├── {module}/{submodule}/        <- 6-file spec sets created per module/submodule in config
+├── 02-test-plans/               <- Test plans (automated + manual)
+├── 03-test-cases/               <- TC-*.md step-by-step docs (manual track; optional if fully automated)
+├── 04-test-data/                <- Shared test data factories/seeders (optional — per-module data lives in 01-specs)
+├── 05-test-execution/           <- Execution reports and results
+├── 06-defects/open|resolved/    <- Defect tracking
+├── 07-automation/               <- Playwright automation code and config
+│   ├── e2e/                     <- Playwright E2E project (self-contained)
+│   │   ├── playwright.config.ts
+│   │   ├── package.json
+│   │   ├── global-setup.ts
+│   │   ├── .env.example
+│   │   ├── fixtures/auth.ts
+│   │   ├── fixtures/test-helpers.ts
+│   │   └── tests/{module}/      <- Generated .spec.ts stubs per submodule
+│   ├── integration/             <- API / integration tests (k6, JMeter...)
+│   └── load/                    <- Load / performance tests (future)
+├── 08-azure-integration/        <- Azure DevOps integration (optional)
+└── memory/                      <- Agent learnings and session notes
+    └── INDEX.md
+```
+
+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)
 ```
 
 See [docs/folder-structure-guide.md](docs/folder-structure-guide.md) for a full explanation of every folder.
 
 ---
 
-## Agent Instructions
+## Skills Architecture
 
-The `agent-instructions/` folder contains Markdown documents designed for IDE agents
-(such as GitHub Copilot in VS Code). Each file covers one specific task:
+The `skills/` folder contains agent skills organized in a **3-layer model** that minimizes
+token overhead compared to the legacy monolithic per-task instruction file approach.
 
-| File | Agent Task |
-|---|---|
-| `00-module-analysis.md` | Analyze a module and produce the 6-file spec set |
-| `01-spec-generation.md` | Generate functional specifications |
-| `02-test-plan-generation.md` | Create a test plan for a module |
-| `03-test-case-generation.md` | Generate detailed test cases |
-| `04-automation-generation.md` | Write Playwright E2E tests |
-| `04b-test-stabilization.md` | Exhaustively review and stabilize generated tests (Stage 3.5) |
-| `05-ado-integration.md` | Sync with Azure DevOps Test Plans |
-| `06-maintenance.md` | Update QA artifacts after code changes |
-
-To use: copy the relevant instruction into a Copilot/agent chat, or reference it from a
-`.github/copilot-instructions.md` or equivalent workspace instruction file.
+| Layer | Location | Purpose |
+|---|---|---|
+| 1 - Descriptor | YAML frontmatter in `SKILL.md` | Name + description; used for relevance detection (~50 tokens) |
+| 2 - Process outline | `SKILL.md` body | Step-by-step process; always loaded when the skill applies (~400-600 tokens) |
+| 3 - Reference material | `references/*.md` | Detailed templates, code patterns, decision trees; loaded on demand (~500-1500 tokens each) |
+
+On `init`, the full `skills/` tree is copied to `.github/skills/` so the agent can load
+them via `read_file` without touching `node_modules`.
+
+### QA Pipeline
+
+Skills map to the pipeline stages enforced by `.github/copilot-instructions.md`:
+
+| Stage | Skill | Task | Track | Prerequisite |
+|---|---|---|---|---|
+| 1 | `qa-module-analysis` | Analyze module, produce 6-file spec set | Both | None |
+| 2 | `qa-spec-generation` | Generate/update 6-file spec set | Both | `00-inventory.md` exists |
+| 3 | `qa-test-plan` | Generate test plan | Both | `05-test-scenarios.md` exists |
+| 4 | `qa-test-cases` | Generate TC-{ID}.md files | Manual | Test plan exists |
+| 5 | `qa-automation` | Implement Playwright tests | Automation | Specs approved, no PENDING-CODE |
+| 5b | `qa-test-stabilization` | Stabilize failing tests | Automation | Failing tests exist |
+| 6 | `qa-maintenance` | Update artifacts after app changes | Both | Delivered change |
+| - | `qa-ado-integration` | Sync with Azure DevOps Test Plans | Both | ADO enabled in config |
+
+See [docs/skills-architecture.md](docs/skills-architecture.md) for the full design rationale.
 
 ---
 
+## CLI Reference
+
+```
+qa-framework <command> [options]
+
+Commands:
+  init [--config <path>]      Scaffold qa/ structure from config file
+  upgrade [--dry-run]         Refresh framework-owned files after npm update
+  generate <artifact>         Generate from template
+                                artifact: spec | test-plan | test-case |
+                                          execution-report | defect-report |
+                                          session-summary
+  validate [--strict]         Validate qa/ structure and naming conventions
+
+Options:
+  --help, -h                  Show help
+  --version, -v               Show version
+```
+
+**upgrade** overwrites only framework-owned files (skills, `copilot-instructions.md`,
+`QA-STRUCTURE-GUIDE.md`) and never touches project-owned files. Run `--dry-run` to preview
+without writing.
+
 ## Configuration
 
 `qa-framework init` now bootstraps a default config automatically at `qa/qa-framework.config.json` if none exists.
@@ -214,10 +287,11 @@ See [docs/installation.md](docs/installation.md) for full config documentation.
 ## Design Principles
 
 1. **UI is the source of truth.** Test cases are defined from what is observable in the running QA environment, not from source code or requirements docs alone.
-2. **Spec before automation.** Every automated test traces back to a written specification (TC-ID → spec file).
+2. **Spec before automation.** Every automated test traces back to a written specification (TC-ID -> spec file).
 3. **Credentials never in documentation.** All credentials are handled via environment variables and sanitized from markdown with `<PLACEHOLDER>`.
 4. **Agent-readable conventions.** File names, folder names, and IDs follow strict, predictable patterns so agents can navigate without guessing.
 5. **Optional integrations don't pollute the core.** Azure DevOps and Playwright configuration live in separate, opt-in sections.
+6. **Assertion polarity.** A test must assert what the spec requires, not what the app currently does. A failing test that exposes a real defect is more valuable than a passing test that hides one.
 
 ---
 
@@ -225,8 +299,8 @@ See [docs/installation.md](docs/installation.md) for full config documentation.
 
 This framework follows [Semantic Versioning](https://semver.org/):
 
-- **MAJOR**: breaking changes to the `qa/` directory structure or agent instruction APIs
-- **MINOR**: new templates, new optional integrations, new agent instruction files
+- **MAJOR**: breaking changes to the `qa/` directory structure or skill APIs
+- **MINOR**: new templates, new optional integrations, new skills
 - **PATCH**: bug fixes in CLI scripts, documentation corrections
 
 See [CHANGELOG.md](CHANGELOG.md) for detailed history.
@@ -241,4 +315,4 @@ This framework is designed to be forked and adapted. If you need a project-speci
 2. Place your adapter config and scripts there
 3. Reference it from `qa-framework.config.json` under `integrations`
 
-Do **not** put project-specific configuration inside `agent-instructions/` or `templates/`. Those must remain generic.
+Do **not** put project-specific configuration inside `skills/` or `templates/`. Those must remain generic.

package/docs/architecture.md

@@ -2,8 +2,8 @@
 
 ## Framework Architecture
 
-**Version**: 1.0.0  
-**Date**: 2026-03-04
+**Version**: 1.6.0  
+**Date**: 2026-04-29
 
 ---
 
@@ -27,16 +27,17 @@
 │  │                        FRAMEWORK CORE                               │   │
 │  │                                                                      │   │
 │  │  ┌────────────────┐  ┌──────────────────┐  ┌─────────────────────┐  │   │
-│  │  │  qa/ structure │  │  Agent           │  │  Standards &        │  │   │
-│  │  │  (9 folders)   │  │  instructions    │  │  Naming conventions │  │   │
-│  │  │                │  │  (7 files)       │  │                     │  │   │
+│  │  │  qa/ structure │  │  Agent skills    │  │  Standards &        │  │   │
+│  │  │  (10 folders)  │  │  (8 skill sets,  │  │  Naming conventions │  │   │
+│  │  │                │  │  3-layer model)  │  │                     │  │   │
 │  │  └────────────────┘  └──────────────────┘  └─────────────────────┘  │   │
 │  │                                                                      │   │
 │  │  ┌────────────────┐  ┌──────────────────┐  ┌─────────────────────┐  │   │
 │  │  │  6-file        │  │  CLI commands    │  │  Config schema      │  │   │
-│  │  │  submodule     │  │  (init/generate/ │  │  (qa-framework.     │  │   │
-│  │  │  templates     │  │   validate)      │  │   config.json)      │  │   │
-│  │  └────────────────┘  └──────────────────┘  └─────────────────────┘  │   │
+│  │  │  submodule     │  │  (init/upgrade/  │  │  (qa-framework.     │  │   │
+│  │  │  templates     │  │  generate/       │  │   config.json)      │  │   │
+│  │  └────────────────┘  │  validate)       │  └─────────────────────┘  │   │
+│  │                       └──────────────────┘                           │   │
 │  └──────────────────────────────────────────────────────────────────────┘   │
 │                                                                             │
 │  ┌──────────────────────────────────────────────────────────────────────┐   │
@@ -44,18 +45,18 @@
 │  │                                                                      │   │
 │  │  ┌─────────────────────────┐    ┌──────────────────────────────┐    │   │
 │  │  │  playwright/            │    │  playwright-azure-reporter/  │    │   │
-│  │  │  - playwright.config.ts │    │  - reporter config template  │    │   │
-│  │  │  - global-setup.ts      │    │  - ado-ids-mapping.json      │    │   │
-│  │  │  - fixtures/auth.ts     │    │  - inject-ado-ids.ps1        │    │   │
-│  │  │  - .env.example         │    │  - module-registry.json      │    │   │
+│  │  │  - e2e/playwright.cfg   │    │  - reporter config template  │    │   │
+│  │  │  - e2e/global-setup.ts  │    │  - ado-ids-mapping.json      │    │   │
+│  │  │  - e2e/fixtures/        │    │  - inject-ado-ids.ps1        │    │   │
+│  │  │  - e2e/.env.example     │    │  - module-registry.json      │    │   │
 │  │  └─────────────────────────┘    └──────────────────────────────┘    │   │
 │  │                                                                      │   │
-│  │  ┌─────────────────────────┐    ┌──────────────────────────────┐    │   │
-│  │  │  ado-powershell/        │    │  blazor-radzen/ (stub)       │    │   │
-│  │  │  - create-testplan.ps1  │    │  - openDropdownAndSelect()   │    │   │
-│  │  │  - sync-ado-titles.ps1  │    │  - waitForBlazorRender()     │    │   │
-│  │  │  - azure-pipeline.yml   │    │  - toBeAttached() guidance   │    │   │
-│  │  └─────────────────────────┘    └──────────────────────────────┘    │   │
+│  │  ┌─────────────────────────┐                                        │   │
+│  │  │  ado-powershell/        │                                        │   │
+│  │  │  - create-testplan.ps1  │                                        │   │
+│  │  │  - sync-ado-titles.ps1  │                                        │   │
+│  │  │  - azure-pipeline.yml   │                                        │   │
+│  │  └─────────────────────────┘                                        │   │
 │  └──────────────────────────────────────────────────────────────────────┘   │
 └─────────────────────────────────────────────────────────────────────────────┘
 
@@ -65,20 +66,26 @@
 │                         TARGET PROJECT                                      │
 │                                                                             │
 │  qa/                                                                        │
-│  ├── README.md                   ← living index (project-specific)          │
-│  ├── QA-STRUCTURE-GUIDE.md       ← copy from framework                      │
-│  ├── qa-framework.config.json    ← project config (parameterized)           │
+│  ├── README.md                   <- living index (project-specific)         │
+│  ├── AGENT-NEXT-STEPS.md         <- active sprint queue (project-specific)  │
+│  ├── QA-STRUCTURE-GUIDE.md       <- copy from framework (framework-owned)   │
+│  ├── qa-framework.config.json    <- project config (parameterized)          │
 │  │                                                                          │
-│  ├── 00-guides/                  ← agent instructions (copied from pkg)     │
-│  ├── 00-standards/               ← naming + templates (copied from pkg)     │
-│  ├── 01-specifications/          ← generated per module (project work)      │
-│  ├── 02-test-plans/              ← generated (project work)                 │
-│  ├── 03-test-cases/              ← generated (project work)                 │
-│  ├── 04-test-data/               ← project data (project work)              │
-│  ├── 05-test-execution/          ← execution reports (project work)         │
-│  ├── 06-defects/                 ← optional defect cache                    │
-│  ├── 07-automation/              ← Playwright code (project work)           │
-│  └── 08-azure-integration/       ← optional ADO integration                 │
+│  ├── 00-standards/               <- naming + templates (copied from pkg)    │
+│  ├── 01-specifications/          <- generated per module (project work)     │
+│  ├── 02-test-plans/              <- generated (project work)                │
+│  ├── 03-test-cases/              <- generated (project work)                │
+│  ├── 04-test-data/               <- project data (project work)             │
+│  ├── 05-test-execution/          <- execution reports (project work)        │
+│  ├── 06-defects/open|resolved/   <- optional defect cache                   │
+│  ├── 07-automation/e2e/          <- Playwright project (self-contained)     │
+│  ├── 07-automation/integration/  <- API/integration tests                   │
+│  ├── 07-automation/load/         <- load/performance tests                  │
+│  ├── 08-azure-integration/       <- optional ADO integration                │
+│  └── memory/                     <- agent learnings (project-maintained)    │
+│                                                                             │
+│  .github/copilot-instructions.md <- generated (framework-owned)            │
+│  .github/skills/                 <- copied from package (framework-owned)  │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -107,7 +114,7 @@ Module analysis (agent)
                               │
                               ▼
                   07-automation/e2e/tests/{module}/
-                    *.spec.ts  ←── test title contains TC-ID
+                    *.spec.ts  <--- test title contains TC-ID
                                                    │
                               ┌────────────────────┘
                               │
@@ -129,21 +136,25 @@ Module analysis (agent)
 
 Installed always. Contains:
 
-- `qa/` directory skeleton (9 folders)
-- `00-guides/` — agent instructions
+- `qa/` directory skeleton (10 folders)
+- `.github/skills/` — 8 agent skill sets (3-layer model: SKILL.md + references/)
 - `00-standards/` — naming conventions, templates
 - `QA-STRUCTURE-GUIDE.md`
+- `.github/copilot-instructions.md` — generated pipeline sequencer
 - `qa-framework.config.json` schema
 
 ### Layer 2 — Playwright Integration (opt-in)
 
-Installed when `integrations.playwright.enabled = true`:
+Installed always (scaffold is always created by `init`):
 
 - `qa/07-automation/e2e/playwright.config.ts`
 - `qa/07-automation/e2e/global-setup.ts`
 - `qa/07-automation/e2e/.env.example`
 - `qa/07-automation/e2e/fixtures/auth.ts`
+- `qa/07-automation/e2e/fixtures/test-helpers.ts`
 - `qa/07-automation/e2e/package.json`
+- `qa/07-automation/integration/README.md` (placeholder)
+- `qa/07-automation/load/README.md` (placeholder)
 
 ### Layer 3 — Azure DevOps Integration (opt-in)
 
@@ -155,13 +166,6 @@ Installed when `integrations.azureDevOps.enabled = true`:
 - PowerShell scripts (inject, create-plan, sync)
 - Azure Pipeline YAML template
 
-### Layer 4 — Framework Adapters (opt-in per adapter)
-
-Technology-specific extensions. Currently available:
-
-- `blazor-radzen` — Playwright helpers for Radzen Blazor apps (STUB - v1.1 planned)
-- `aspnet-mvc` — Select2/jQuery datatable helpers (STUB - v1.1 planned)
-
 ---
 
 ## Configuration Architecture
@@ -188,10 +192,11 @@ The framework uses **Semantic Versioning**:
 
 | Change type | Version bump |
 |---|---|
-| New folder added to `qa/` tree | MAJOR (breaks existing structure) |
+| New folder added to `qa/` tree or restructured | MAJOR |
 | New template file | MINOR |
 | New integration adapter | MINOR |
-| Agent instruction update | PATCH |
+| New skill or skill update | MINOR |
+| CLI command update | PATCH |
 | Documentation correction | PATCH |
 
 **Upgrade path**: When a new MAJOR version changes the `qa/` structure, the `MIGRATION-NOTES.md` in the package provides a step-by-step migration script. Projects should pin their framework version in `package.json` and upgrade deliberately.