@keber/qa-framework 1.1.3 → 1.3.0-0

package/README.md

@@ -41,7 +41,7 @@ The postinstall script scaffolds the `qa/` structure automatically. No need to r
 Use this prompt in your IDE agent chat:
 
 ```
-Install @keber/qa-framework and set up the project following qa/AGENT-NEXT-STEPS.md
+Install @keber/qa-framework, check it's 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.).

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/`.
 
@@ -308,3 +311,33 @@ After writing automation for a module, create `COVERAGE-MAPPING.md` in the test
 | TC-OPER-CAT-003 | Duplicate rejection | ... | tests/operacion/... | ⚠️ Partially (UI only) |
 | TC-OPER-ASI-001 | Access assistance list | ... | — | ⛔ Blocked (BLOCKED-PERMISSIONS) |
 ```
+
+---
+
+## Module Completion Checklist
+
+Run this checklist when all P0 tests for a module are passing.
+
+### Stability gate
+- [ ] All P0 tests pass on **2 consecutive runs** with different `EXEC_IDX` values (≥ 60 seconds apart)
+- [ ] No `waitForTimeout(N)` longer than 2000ms left in the suite
+- [ ] All skipped tests have a `DEF-` or ADO WI reference in their skip message
+
+### Artifacts
+- [ ] `COVERAGE-MAPPING.md` created or updated in the test directory
+- [ ] Execution report written to `qa/05-test-execution/automated/`
+
+### Living Index update — `qa/README.md`
+- [ ] Update the module's row in the status table (TCs automated, date, status → ✅)
+- [ ] Add a row to the `## Sprint History` section with: sprint name, date, submódulos covered, TC count, link to execution report
+
+### AGENT-NEXT-STEPS.md — trim
+- [ ] Move the completed sprint checklist block to `qa/README.md` under `## Sprint History`
+- [ ] Delete the completed sprint section from `AGENT-NEXT-STEPS.md`
+- [ ] Verify `AGENT-NEXT-STEPS.md` now contains **only one active sprint** (the next one)
+
+### Memory
+- [ ] If new patterns or environment quirks were discovered: add them to `qa/memory/` with a descriptive filename
+- [ ] Update `qa/memory/INDEX.md` to reflect any new or updated files
+
+> **Rule**: `AGENT-NEXT-STEPS.md` is a task queue, not a log. Completed sprints live in `qa/README.md`. The file must never accumulate more than one active sprint.

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.
 
@@ -114,6 +117,13 @@ After every maintenance session, update the master index:
 - Automation status (if changed)
 - Last updated date for the module
 
+If a **sprint was fully completed** as part of this maintenance pass (all TCs passing after the changes):
+1. Move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`
+2. Delete the completed sprint block from `AGENT-NEXT-STEPS.md`
+3. Confirm `AGENT-NEXT-STEPS.md` contains **only one active sprint** — never let it accumulate history
+
+Also update `qa/memory/INDEX.md` if any memory files were created or modified.
+
 ---
 
 ## Step 6: Write a Session Summary

package/docs/folder-structure-guide.md

@@ -11,10 +11,10 @@ This document explains the purpose, contents, and conventions for every folder i
 ```
 qa/
 ├── README.md                    ← Living master index (project-maintained)
+├── AGENT-NEXT-STEPS.md          ← Active sprint queue for the agent (project-maintained)
 ├── 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)
@@ -23,31 +23,34 @@ qa/
 ├── 05-test-execution/           ← Execution reports and results
 ├── 06-defects/                  ← Defect tracking (optional)
 ├── 07-automation/               ← Automation code (Playwright, etc.)
-└── 08-azure-integration/        ← Azure DevOps integration (optional)
+├── 08-azure-integration/        ← Azure DevOps integration (optional)
+└── 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)
 
 ---
 
@@ -267,17 +270,69 @@ See `docs/generalization-decisions.md §7` for the full evaluation of this folde
 
 ## `qa/README.md` — The Living Index
 
-The `qa/README.md` is the **only project-maintained file at the root of `qa/`**. It should be updated whenever:
+The `qa/README.md` is the primary human-readable project status document. It should be updated whenever:
 - A new module is analyzed
 - A new test execution is completed
 - A blocker is identified or resolved
-- A major milestone is reached
+- A major milestone or sprint is completed
 
 Minimum contents:
 - Module status table (name, TCs documented, TCs automated, ADO plan link)
 - Quick-start commands for common tasks
 - Active blockers section
 - Last execution results summary
+- **`## Sprint History`** section — completed sprint checklists moved here from `AGENT-NEXT-STEPS.md`
+
+Template: `templates/qa-readme.md`
+
+---
+
+## `qa/AGENT-NEXT-STEPS.md` — Sprint Queue
+
+The `AGENT-NEXT-STEPS.md` is the agent's task queue for the current sprint. It is read by the agent at the start of every conversation.
+
+**Design principles (SRP + KISS)**:
+- Contains **one active sprint only** — no history, no completed checklists
+- Three sections maximum: module status table, active sprint checklist, context references
+- Does not repeat standing instructions already in `copilot-instructions.md`
+- Detailed environment notes and patterns belong in `qa/memory/`, referenced from here
+
+When a sprint completes, the agent **moves** the completed checklist to `qa/README.md → ## Sprint History` and **deletes** that section from this file.
+
+Template: `templates/agent-next-steps.md`
+
+---
+
+## `qa/memory/` — Project QA Learnings
+
+Project-maintained folder for accumulated knowledge about the application under test: environment quirks, DOM patterns, Playwright gotchas, sprint-specific discoveries.
+
+```
+qa/memory/
+├── INDEX.md                          ← Required entry point — index of all files
+├── {technology}-patterns.md          ← Framework/stack-specific patterns (e.g., playwright-blazor-wasm-patterns.md)
+├── {sprint-name}-discovery.md        ← DOM/UI findings for an in-progress sprint
+└── {sprint-name}-lessons.md          ← Retrospective patterns after a sprint completes
+```
+
+### `qa/memory/INDEX.md` — Required
+
+The `INDEX.md` is the **gate** that the agent reads before loading any other memory file. Its purpose is to let the agent load only what is relevant to the current task, rather than loading all files.
+
+```markdown
+# Memory Index — {PROJECT_NAME}
+
+| File | Topic | When to load |
+|---|---|---|
+| playwright-blazor-wasm-patterns.md | Blazor/Radzen DOM patterns | Any Playwright automation task |
+| sprint4-discovery.md | DOM quirks for BusinessPartner module | Sprint 4 automation only |
+| sprint3-lessons.md | Patterns from Sprint 3 | Reference when working on similar modules |
+```
+
+**Rules for `qa/memory/`**:
+- Always update `INDEX.md` when adding or modifying a memory file
+- Sprint-specific discovery files (`sprint-N-discovery.md`) are for the duration of that sprint; consolidate long-term patterns into a technology-specific file afterwards
+- Never load all memory files unconditionally — always read `INDEX.md` first and select by relevance
 
 ---
 

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.1.3",
+  "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/qa-framework.config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./qa-framework.config.schema.json",
-  "frameworkVersion": "1.0.0",
+  "frameworkVersion": "1.1.3",
 
   "project": {
     "name": "{{PROJECT_NAME}}",

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,13 +77,17 @@ process.stderr.write(`[qa-framework/init] Using config source: ${configSource}\n
 
 // --- Top-level folders ---
 const topLevelFolders = [
-  '00-guides',
   '00-standards',
-  '05-test-plans',
+  '01-specifications',
+  '02-test-plans',
+  '03-test-cases',
+  '04-test-data',
+  '05-test-execution',
   '06-defects/open',
   '06-defects/resolved',
   '07-automation/e2e',
   '08-azure-integration',
+  'memory',
 ];
 
 for (const folder of topLevelFolders) {
@@ -92,12 +96,47 @@ for (const folder of topLevelFolders) {
   console.log(`  [created] ${path.relative(cwd, fullPath)}/`);
 }
 
+// --- qa/README.md ---
+const qaReadmeTemplate = path.resolve(__dirname, '..', 'templates', 'qa-readme.md');
+if (fs.existsSync(qaReadmeTemplate)) {
+  let readmeContent = fs.readFileSync(qaReadmeTemplate, 'utf8');
+  readmeContent = readmeContent
+    .replace(/\{PROJECT_DISPLAY_NAME\}/g, config.project?.displayName ?? config.project?.name ?? 'Project')
+    .replace(/\{VERSION\}/g, config.frameworkVersion ?? '1.0.0')
+    .replace(/\{LANGUAGE\}/g, config.conventions?.language ?? 'en')
+    .replace(/\{QA_BASE_URL\}/g, config.project?.qaBaseUrl ?? '<QA_BASE_URL>');
+  writeIfMissing(path.join(qaRoot, 'README.md'), readmeContent);
+}
+
+// --- qa/memory/INDEX.md ---
+const memoryDir = path.join(qaRoot, 'memory');
+writeIfMissing(path.join(memoryDir, 'INDEX.md'),
+`# Memory Index — ${config.project?.displayName ?? config.project?.name ?? 'Project'}
+
+> The agent reads this file first before loading any memory file.
+> Add a row here whenever you create or update a file in this directory.
+
+| File | Topic | When to load |
+|---|---|---|
+
+_No memory files yet. Add files to this directory and register them above._
+`);
+
 // --- Standards placeholder ---
 const stdDir = path.join(qaRoot, '00-standards');
 writeIfMissing(path.join(stdDir, 'naming-conventions.md'), `# Naming Conventions\n\n> Fill in per your project. See keber/qa-framework docs/spec-driven-philosophy.md.\n`);
 writeIfMissing(path.join(stdDir, 'bug-report-template.md'), fs.readFileSync(
   path.resolve(__dirname, '..', 'templates', 'defect-report.md'), 'utf8'
 ));
+writeIfMissing(path.join(stdDir, 'test-case-template.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'test-case.md'), 'utf8'
+));
+writeIfMissing(path.join(stdDir, 'execution-report-template.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'execution-report.md'), 'utf8'
+));
+writeIfMissing(path.join(stdDir, 'test-data-guidelines.md'), fs.readFileSync(
+  path.resolve(__dirname, '..', 'templates', 'test-data-guidelines.md'), 'utf8'
+));
 
 // --- Per-module folders ---
 const modules = config.modules ?? [];
@@ -182,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);
   }
 }
 
@@ -248,24 +281,37 @@ 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/\`
+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\`
-
-## Available agent instructions
-
-| 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\` |
+5. Read previous test suites code in \`qa/07-automation/e2e/tests/\` if available before writing new automation to maintain consistency in style and approach
+6. Project QA config is at \`qa/qa-framework.config.json\`
+7. Save learnings in \`qa/memory/\` with proper naming and metadata. Always update \`qa/memory/INDEX.md\` after adding or updating any memory file.
+8. **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.
+
+## Formatting rules for generated content
+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.
+
+## 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.
 `;
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
@@ -317,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.
+`;
+}

package/templates/agent-next-steps.md

@@ -0,0 +1,58 @@
+# AGENT-NEXT-STEPS — {PROJECT_NAME}
+
+> **Sprint activo: Sprint {N} — {SPRINT_NAME}**
+> Lee este archivo primero. Lee los archivos referenciados solo cuando la tarea lo requiera.
+
+---
+
+## Estado del módulo
+
+| Módulo / Submódulo | Specs | Plan | Auto | Estado |
+|---|---|---|---|---|
+| {MODULE_NAME} / {SUBMODULE_NAME} | ✅ | ✅ | ⬜ | Sprint {N} activo |
+
+> Actualizar esta tabla cuando un sprint se complete. Historial de sprints completados → `qa/README.md ## Sprint History`.
+
+---
+
+## Sprint {N} — Tareas pendientes
+
+- [ ] {Tarea 1}
+- [ ] {Tarea 2}
+- [ ] {Tarea 3}
+- [ ] Actualizar `qa/README.md` (fila del módulo + Sprint History)
+- [ ] Trim este archivo: dejar solo el sprint siguiente
+
+**Precondiciones**: {Dependencias de datos o módulos previos, si aplica}
+
+**Notas específicas**: {Quirks del DOM, rutas, selectores problemáticos conocidos — o eliminar esta línea}
+→ Si las notas son extensas, guardarlas en `qa/memory/{sprint-name}-discovery.md` y referenciar aquí.
+
+---
+
+## Contexto obligatorio antes de codificar
+
+- Patrones del proyecto: `qa/memory/INDEX.md` → cargar solo los archivos relevantes
+- Referencia de estilo: `qa/07-automation/e2e/tests/{module}/` (leer suite existente más reciente)
+
+---
+
+## Sprints siguientes (solo referencia — sin checklists)
+
+- **Sprint {N+1}**: {Descripción breve — qué módulo/submódulo}
+- **Sprint {N+2}**: {Descripción breve}
+
+---
+
+<!-- ═══════════════════════════════════════════════════════════════════
+  REGLAS DE MANTENIMIENTO DE ESTE ARCHIVO (para el agente)
+  ——————————————————————————————————————————————————————————————————
+  1. MÁXIMO UN SPRINT ACTIVO. Cuando un sprint se completa:
+       a. Mover su checklist al README.md bajo ## Sprint History
+       b. Borrar esa sección de este archivo
+       c. Promover el siguiente sprint a "activo"
+  2. NO repetir instrucciones permanentes que ya estén en copilot-instructions.md.
+  3. Los detalles técnicos (DOM, patrones) van en qa/memory/, no aquí.
+  4. Los sprints "siguientes" son bullets de 1 línea, sin checklists.
+  Este archivo es una cola de trabajo. No es un log ni una bitácora.
+  ══════════════════════════════════════════════════════════════════ -->

package/templates/qa-readme.md

@@ -0,0 +1,86 @@
+# QA — {PROJECT_DISPLAY_NAME}
+
+> Framework: `@keber/qa-framework` v{VERSION}
+> Language: {LANGUAGE} | Base URL: `{QA_BASE_URL}`
+
+---
+
+## Module Status
+
+| Module | Submodule | TCs Total | TCs Automated | Plan | ADO Suite | Status | Last Run |
+|---|---|---|---|---|---|---|---|
+| {MODULE_NAME} | {SUBMODULE_NAME} | — | — | ⬜ | — | 🔲 Not started | — |
+
+**Legend**: ✅ Done · ⚠️ Partial · 🔲 Not started · ⛔ Blocked
+
+---
+
+## Quick-Start Commands
+
+```bash
+# Run all automated tests
+cd qa/07-automation
+npx playwright test
+
+# Run a specific module
+npx playwright test tests/{module-folder}/
+
+# Run with UI (debug mode)
+npx playwright test --ui
+
+# Generate HTML report
+npx playwright show-report
+
+# Re-run only failed tests
+npx playwright test --last-failed
+```
+
+> Set credentials in `qa/07-automation/.env` (copy from `.env.example`).
+
+---
+
+## Active Blockers
+
+| ID | Description | Affects | Opened | Status |
+|---|---|---|---|---|
+| — | No active blockers | — | — | — |
+
+---
+
+## Last Execution
+
+| Date | Suite | Pass | Skip | Fail | Duration | Report |
+|---|---|---|---|---|---|---|
+| — | — | — | — | — | — | — |
+
+---
+
+## Sprint History
+
+<!-- Completed sprint checklists are moved here from AGENT-NEXT-STEPS.md -->
+<!-- Format per sprint: -->
+<!--
+### Sprint N — {SPRINT_NAME} ({YYYY-MM-DD})
+
+**Submodules**: {list}
+**TCs automated**: {N} P0 + {M} P1
+**Execution report**: `qa/05-test-execution/automated/{date-slug}.md`
+
+Checklist (completed):
+- [x] {Task 1}
+- [x] {Task 2}
+-->
+
+_No sprints completed yet._
+
+---
+
+## Resources
+
+| Resource | Link |
+|---|---|
+| QA Structure Guide | `qa/QA-STRUCTURE-GUIDE.md` |
+| Naming Conventions | `qa/00-standards/naming-conventions.md` |
+| Memory Index | `qa/memory/INDEX.md` |
+| Agent Next Steps | `qa/AGENT-NEXT-STEPS.md` |
+| Automation Config | `qa/07-automation/playwright.config.ts` |

package/templates/test-data-guidelines.md

@@ -0,0 +1,130 @@
+# Test Data Guidelines
+
+> Reference: `qa/04-test-data/`  
+> All test data definitions must follow these rules. No exceptions for credentials.
+
+---
+
+## Rules
+
+### 1. Never hardcode credentials
+
+All user emails, passwords, API keys, and tokens must come from environment variables.
+
+```typescript
+// ✅ CORRECT
+const email    = process.env.QA_USER_EMAIL!;
+const password = process.env.QA_USER_PASSWORD!;
+
+// ❌ WRONG — never commit credentials
+const email    = 'admin@example.com';
+const password = 'secret123';
+```
+
+Document env var names in `qa/04-test-data/users.md`. Use `<PLACEHOLDER>` for values in all documentation.
+
+### 2. Use EXEC_IDX for unique values per run
+
+Never create records with static names — they collide between runs and can leave leftover data.
+
+```typescript
+const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
+
+// Names / codes
+const name = `Test-Entity-${EXEC_IDX}`;
+
+// Future-safe dates (year 2120+ avoids real production data overlap)
+const year  = 2120 + (EXEC_IDX % 10);
+const month = String((EXEC_IDX % 12) + 1).padStart(2, '0');
+const day   = String((EXEC_IDX % 28) + 1).padStart(2, '0');
+const date  = `${year}-${month}-${day}`;
+```
+
+### 3. Provision in `beforeAll`, not `beforeEach`
+
+Create required records once per suite, not once per test. Each test that **consumes** a record needs its own provisioned record — never share a single record among multiple tests.
+
+```typescript
+test.beforeAll(async ({ browser }) => {
+  const page = await browser.newPage();
+  // If 3 tests each need 1 record, create 3:
+  for (let i = 0; i < 3; i++) {
+    await createEntity(page, `Record-${EXEC_IDX}-${i}`);
+  }
+  await page.close();
+});
+```
+
+### 4. Seed scripts go in `04-test-data/seeders/`
+
+Complex setup that cannot be done via the UI goes in a seeder script, not inside a spec file.
+
+```
+qa/04-test-data/
+├── users.md          ← Role catalog + env var names (no real values)
+├── fixtures/         ← Static JSON/Markdown for reference data
+├── factories/        ← Dynamic data generation patterns
+└── seeders/          ← DB/API seed scripts for complex prerequisites
+```
+
+### 5. Add `.env` and `.auth/` to `.gitignore`
+
+```
+qa/07-automation/.env
+qa/07-automation/.auth/
+```
+
+The `.env.example` file (committed) lists all required keys with `<PLACEHOLDER>` as the value.
+
+---
+
+## User Table Format (`04-test-data/users.md`)
+
+```markdown
+| Role | Env var (email) | Env var (password) | Permissions |
+|---|---|---|---|
+| Admin | QA_ADMIN_EMAIL | QA_ADMIN_PASSWORD | Full access |
+| Read-only | QA_READONLY_EMAIL | QA_READONLY_PASSWORD | View only |
+```
+
+---
+
+## Fixture Files (`04-test-data/fixtures/`)
+
+Use Markdown tables or JSON for static reference data that tests depend on (catalogs, option lists, etc.).
+
+```markdown
+# fixtures/catalogs.md
+## Labor Types
+| Code | Name |
+|---|---|
+| LT-01 | Consulting |
+| LT-02 | Development |
+```
+
+Reference fixtures in specs via `import` (JSON) or inline expectations matching the fixture values.
+
+---
+
+## Factory Pattern (`04-test-data/factories/`)
+
+Document how to generate complex data shapes needed by multiple tests:
+
+```typescript
+// factories/supplier.ts
+export function buildSupplier(idx: number) {
+  return {
+    name:  `Supplier-${idx}`,
+    rut:   `${76_000_000 + idx}-0`,
+    email: `supplier-${idx}@test.example`,
+  };
+}
+```
+
+---
+
+## On test teardown
+
+Do **not** delete test data after each run unless the test explicitly requires a clean state. Leftover data from old EXEC_IDX values does not affect subsequent runs because EXEC_IDX generates distinct names.
+
+Exception: if the system enforces uniqueness on a field that EXEC_IDX cannot make unique (e.g., a singleton config), document the teardown strategy in `04-test-data/seeders/`.