@keber/qa-framework 1.7.2 → 1.8.0

package/CHANGELOG.md

@@ -33,6 +33,49 @@ has been removed or parameterized. See `docs/comparison-matrix.md` and `docs/gen
 
 ---
 
+## [1.8.0] - 2026-05-07
+
+### Changed
+
+- **Pipeline Stage 3 now produces "Plan de Pruebas"** — a single document per sprint+module
+  that combines test plan context (scope, strategy, preconditions, test data) with a full TC
+  table including numbered steps and expected results. Replaces the previous split between a
+  high-level plan and separate TC-{ID}.md files for most workflows.
+- **Stage 4 (`qa-test-cases`) role redefined** — from "generate TC-{ID}.md files" to
+  "expand steps in Plan de Pruebas table when Stage 3 produced summary-level steps". Standalone
+  `TC-{ID}.md` files are now optional and used only for complex/reusable TCs.
+- **ADO integration prerequisite updated** — `qa-ado-integration` now reads from
+  `Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` (Tabla de Pruebas) instead of
+  `qa/03-test-cases/automated/`. Each module file → one ADO Test Suite; each table row → one
+  ADO Test Case with steps.
+- **`02-test-plans/` restructured** — from flat `automated/` and `manual/` subdirectories to
+  `sprints/Sprint-{N}/` per-sprint structure. Both tracks share the same Plan de Pruebas document.
+
+### Added
+
+- **`templates/test-plan-sprint.md`** — new primary Plan de Pruebas template. Includes header,
+  12 sections, and Tabla de Pruebas with column guide. Uses `{{PLACEHOLDERS}}` throughout.
+- **`skills/qa-test-plan/references/plan-de-pruebas-template.md`** — full template with example
+  table rows, steps writing conventions, priority decision tree, and automation feasibility rules.
+  Replaces `references/priority-and-feasibility.md` (old file kept for reference, now legacy).
+- **`upgrade` Section 6** — non-destructive migration of old `02-test-plans/` structure:
+  moves `automated/` → `sprints/legacy-automated/`, `manual/` → `sprints/legacy-manual/`, and
+  flat `.md` plan files → `sprints/legacy/`. Creates `03-test-cases/README.md` if missing.
+
+### Deprecated
+
+- **`templates/test-plan.md`** — use `templates/test-plan-sprint.md` instead.
+  Old file kept for reference; contains deprecation notice at top.
+- **`02-test-plans/automated/` and `02-test-plans/manual/` subdirectory convention** —
+  replaced by `02-test-plans/sprints/Sprint-{N}/` per-sprint structure.
+
+### Migration
+
+Run `npx qa-framework upgrade`. Section 6 of the upgrade script handles the `02-test-plans/`
+migration non-destructively: existing plan files are moved, not deleted.
+
+---
+
 ## [1.7.2] - 2026-05-06
 
 ### Fixed

package/README.md

@@ -1,7 +1,7 @@
 # qa-framework
 
 > Reusable, installable, agent-oriented QA framework for spec-driven automated testing.
-> Current version: **v1.7.2**
+> Current version: **v1.8.0**
 
 ---
 
@@ -102,8 +102,8 @@ qa-framework/
 ├── 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-test-plan/                 <- Stage 3: Plan de Pruebas (plan + TC table with steps)
+│   ├── qa-test-cases/                <- Stage 4: expand steps in Plan de Pruebas table
 │   ├── qa-automation/                <- Stage 5: implement Playwright automation
 │   ├── qa-test-stabilization/        <- Stage 5b: stabilize failing tests
 │   ├── qa-maintenance/               <- Stage 6: update artifacts after app changes
@@ -118,7 +118,8 @@ qa-framework/
 │   │   ├── 03-roles-permissions.md
 │   │   ├── 04-test-data.md
 │   │   └── 05-test-scenarios.md
-│   ├── test-plan.md
+│   ├── test-plan-sprint.md           <- Plan de Pruebas template (v1.7.0+, primary)
+│   ├── test-plan.md                  <- Legacy test plan template (deprecated)
 │   ├── test-case.md
 │   ├── execution-report.md
 │   ├── defect-report.md
@@ -233,12 +234,12 @@ Skills map to the pipeline stages enforced by `.github/instructions/qa-framework
 |---|---|---|---|---|
 | 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 |
+| 3 | `qa-test-plan` | Generate Plan de Pruebas (plan + TC table with steps) | Both | `05-test-scenarios.md` exists |
+| 4 | `qa-test-cases` | Expand steps in Plan de Pruebas table | Both (optional) | Plan de Pruebas 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 |
+| - | `qa-ado-integration` | Sync with Azure DevOps Test Plans | Both | Plan de Pruebas with steps exists |
 
 See [docs/skills-architecture.md](docs/skills-architecture.md) for the full design rationale.
 

package/docs/folder-structure-guide.md

@@ -17,7 +17,7 @@ qa/
 │
 ├── 00-standards/                ← Naming conventions and artifact templates
 ├── 01-specifications/           ← Functional specifications per module
-├── 02-test-plans/               ← Test plans (scope + priority decisions)
+├── 02-test-plans/               ← Plan de Pruebas per sprint/module (plan + TC table + steps)
 ├── 03-test-cases/               ← Standalone test case documents
 ├── 04-test-data/                ← Test data definitions and factories
 ├── 05-test-execution/           ← Execution reports and results
@@ -42,8 +42,8 @@ two tracks that can run in parallel or independently depending on team maturity.
         ├─── Automation track ──────────────────────────────────────────────────
         │         │
         │         ▼
-        │    02-test-plans/automated/      ← scope + priority decisions
-        │         │
+        │    02-test-plans/sprints/Sprint-{N}/    ← Plan de Pruebas (plan + TC table + steps)
+        │         │                                  Stage 4 expands steps if needed
         │         ▼
         │    07-automation/e2e/tests/      ← Playwright .spec.ts files
         │         │
@@ -56,16 +56,17 @@ two tracks that can run in parallel or independently depending on team maturity.
         └─── Manual track ──────────────────────────────────────────────────────
                   │
                   ▼
-             02-test-plans/manual/         ← scope + manual test approach
+             02-test-plans/sprints/Sprint-{N}/    ← same Plan de Pruebas (shared artifact)
                   │
                   ▼
-             03-test-cases/manual/         ← TC-*.md with steps (for human testers)
+             03-test-cases/ (optional)     ← standalone TC-*.md for complex/reusable TCs
                   │
                   ▼
              05-test-execution/manual/     ← manual run evidence
                   │
                   ▼
              08-azure-integration/         ← ADO sync via ado-integration skill
+                                              (reads Plan de Pruebas, creates TCs with steps)
 ```
 
 **Entry points:**
@@ -158,43 +159,50 @@ Each skill folder contains:
 
 ## 02-test-plans/
 
-**Purpose**: Documents that define the scope, priorities, and approach for testing a module or sprint.
+**Purpose**: Plan de Pruebas documents per sprint and module. Each document combines test plan context (scope, strategy, preconditions) with a detailed test case table including numbered steps. This is the primary artifact for both the automation track and ADO integration.
 
 ```
 02-test-plans/
 ├── README.md
-├── automated/
-│   └── {module}-automated-test-plan.md
-└── manual/
-    ├── {module}-manual-test-plan.md
-    └── exploratory/
-        └── {module}-exploratory-session.md
+└── sprints/
+    └── Sprint-{NNN}/
+        ├── Plan-de-Pruebas-{proyecto}-Sprint-{NNN}-{modulo}.md  ← one per module
+        └── Plan-de-Pruebas-{proyecto}-Sprint-{NNN}.md           ← consolidado (generated by @keber/ado-qa, not by agent)
 ```
 
-A test plan specifies:
-- Which TCs from `01-specifications/` are in scope
-- Priority assignment (P0/P1/P2/P3)
-- Which TCs will be automated vs manual
-- Estimated automation feasibility (fully/partially/not automatable)
-- ADO Test Suite mapping (if ADO is enabled)
+**Naming convention**: `Plan-de-Pruebas-{proyecto}-Sprint-{NNN}-{modulo}.md`
+- `{proyecto}` = `project.name` from `qa-framework.config.json`
+- `{NNN}` = zero-padded sprint number (e.g., `040`)
+- `{modulo}` = module code from specs (e.g., `RCL-Casino`, `ARCF`)
+
+**What each Plan de Pruebas contains**:
+- Header (project, sprint, dates, ADO Test Plan link)
+- Scope, strategy, preconditions, test data
+- **Tabla de Pruebas**: TC-ID | Suite | Título | Descripción | Steps (numbered `<br>`-separated) | Resultado Esperado | Confirma (Task ID or N/A) | Tipo | Prioridad
+- Matriz de trazabilidad (Task ↔ N)
+- Automation notes
+
+**Legacy migration**: `upgrade` Section 6 moves `automated/` and `manual/` subdirectories to `sprints/legacy-*` non-destructively.
 
 ---
 
 ## 03-test-cases/
 
-**Purpose**: Standalone, detailed test case documents when more depth is needed than `05-test-scenarios.md` provides.
+**Purpose**: Optional standalone test case documents for complex or reusable TCs.
 
-Most projects will have sparse content here — the 05-test-scenarios.md files inside specs contain the TC tables. This folder is for cases that are too complex to fit in a table row.
+> **Note (v1.7.0+)**: The primary test case artifact is the Tabla de Pruebas inside each Plan de Pruebas (`02-test-plans/sprints/`). This folder is for edge cases where a TC is too complex to fit in a table row, or where a TC is shared across multiple sprints unchanged.
 
 ```
 03-test-cases/
-├── README.md
-├── automated/
-│   └── TC-{ID}-{title}.md
-└── manual/
-    └── TC-{ID}-{title}.md
+├── README.md   ← explains optional/legacy status
+└── TC-{ID}-{title}.md
 ```
 
+**When to create standalone TCs here**:
+- TC requires multi-role, multi-session, or multi-system steps that don't fit a table row
+- TC is reused across multiple sprints with no changes (cross-reference from Plan de Pruebas table)
+- Legacy TCs migrated from pre-v1.7.0 structure
+
 ---
 
 ## 04-test-data/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.7.2",
+  "version": "1.8.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

@@ -79,7 +79,7 @@ process.stderr.write(`[qa-framework/init] Using config source: ${configSource}\n
 const topLevelFolders = [
   '00-standards',
   '01-specifications',
-  '02-test-plans',
+  '02-test-plans/sprints',
   '03-test-cases',
   '04-test-data',
   '05-test-execution',
@@ -124,6 +124,21 @@ writeIfMissing(path.join(memoryDir, 'INDEX.md'),
 _No memory files yet. Add files to this directory and register them above._
 `);
 
+// --- 03-test-cases README (optional directory marker) ---
+writeIfMissing(path.join(qaRoot, '03-test-cases', 'README.md'),
+`# 03-test-cases/ — Optional Standalone Test Cases
+
+> **v1.7.0+:** The primary location for test cases (with detailed steps) is now
+> \`qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{project}-Sprint-{N}-{module}.md\`.
+>
+> Use this directory only for test cases that are:
+> - Too complex to fit in a table row (multi-scenario, multi-role)
+> - Reused across multiple sprints without change
+> - Required as standalone documents for audit or external review
+>
+> Naming: \`TC-{MODULE}-{SUBMODULE}-{NNN}-{slug}.md\`
+`);
+
 // --- 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`);

package/scripts/upgrade.js

@@ -20,7 +20,14 @@
  *     - qa/07-automation/fixtures/             -> qa/07-automation/e2e/fixtures/
  *     - qa/07-automation/e2e/{module}/         -> qa/07-automation/e2e/tests/{module}/
  *     - Creates integration/ and load/ placeholders *     - Patches playwright.config.ts: testDir '.' -> './tests', adds testIgnore
- *     - Creates tests/helpers/debug/ and tests/seeds/ if absent *
+ *     - Creates tests/helpers/debug/ and tests/seeds/ if absent
+ *
+ *   MIGRATES (v1.6.x -> v1.7.0, non-destructive):
+ *     - qa/02-test-plans/automated/  -> qa/02-test-plans/sprints/legacy-automated/
+ *     - qa/02-test-plans/manual/     -> qa/02-test-plans/sprints/legacy-manual/
+ *     - qa/02-test-plans/*.md        -> qa/02-test-plans/sprints/legacy/
+ *     - Creates qa/02-test-plans/sprints/ if absent
+ *     - Creates qa/03-test-cases/README.md optional marker if absent *
  *   NEVER touches (project-owned):
  *     - qa/01-specifications/       <- Your specs
  *     - qa/02-test-plans/           <- Your test plans
@@ -265,6 +272,80 @@ for (const subdir of ['tests/helpers/debug', 'tests/seeds']) {
   }
 }
 
+// ---------------------------------------------------------------------------
+// 6. Migration v1.6.x -> v1.7.0: restructure qa/02-test-plans/
+//    Safe: only moves files when source exists and destination does NOT.
+//    automated/ -> sprints/legacy-automated/
+//    manual/    -> sprints/legacy-manual/
+//    *.md flat  -> sprints/legacy/
+// ---------------------------------------------------------------------------
+const testPlansDir = path.join(qaRoot, '02-test-plans');
+const sprintsDir   = path.join(testPlansDir, 'sprints');
+
+if (fs.existsSync(testPlansDir)) {
+  const legacySubdirs = ['automated', 'manual'];
+  for (const sub of legacySubdirs) {
+    const oldDir = path.join(testPlansDir, sub);
+    const newDir = path.join(sprintsDir, `legacy-${sub}`);
+    if (fs.existsSync(oldDir) && !fs.existsSync(newDir)) {
+      if (!dryRun) {
+        fs.mkdirSync(sprintsDir, { recursive: true });
+        fs.renameSync(oldDir, newDir);
+      }
+      updated.push(newDir);
+      console.log(`  [migrated] 02-test-plans/${sub}/ -> 02-test-plans/sprints/legacy-${sub}/`);
+    }
+  }
+
+  // Move any .md files sitting flat in 02-test-plans/ (not in sprints/)
+  if (fs.existsSync(testPlansDir)) {
+    const legacyDir = path.join(sprintsDir, 'legacy');
+    for (const entry of fs.readdirSync(testPlansDir, { withFileTypes: true })) {
+      if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+      const oldFile = path.join(testPlansDir, entry.name);
+      const newFile = path.join(legacyDir, entry.name);
+      if (!fs.existsSync(newFile)) {
+        if (!dryRun) {
+          fs.mkdirSync(legacyDir, { recursive: true });
+          fs.renameSync(oldFile, newFile);
+        }
+        updated.push(newFile);
+        console.log(`  [migrated] 02-test-plans/${entry.name} -> 02-test-plans/sprints/legacy/${entry.name}`);
+      } else {
+        warnings.push(`Cannot migrate 02-test-plans/${entry.name} — target already exists. Move manually.`);
+      }
+    }
+  }
+
+  // Ensure sprints/ exists
+  if (!fs.existsSync(sprintsDir)) {
+    if (!dryRun) fs.mkdirSync(sprintsDir, { recursive: true });
+    updated.push(sprintsDir);
+    console.log(`  [created] 02-test-plans/sprints/`);
+  }
+}
+
+// Ensure 03-test-cases/README.md exists (optional marker)
+const testCasesReadme = path.join(qaRoot, '03-test-cases', 'README.md');
+if (!fs.existsSync(testCasesReadme)) {
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(testCasesReadme), { recursive: true });
+    fs.writeFileSync(testCasesReadme,
+      '# 03-test-cases/ — Optional Standalone Test Cases\n\n' +
+      '> **v1.7.0+:** The primary location for test cases (with detailed steps) is now\n' +
+      '> `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{project}-Sprint-{N}-{module}.md`.\n' +
+      '>\n' +
+      '> Use this directory only for test cases that are:\n' +
+      '> - Too complex to fit in a table row (multi-scenario, multi-role)\n' +
+      '> - Reused across multiple sprints without change\n' +
+      '> - Required as standalone documents for audit or external review\n' +
+      '>\n' +
+      '> Naming: `TC-{MODULE}-{SUBMODULE}-{NNN}-{slug}.md`\n', 'utf8');
+  }
+  updated.push(testCasesReadme);
+  console.log(`  [created] 03-test-cases/README.md`);
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

package/skills/qa-ado-integration/SKILL.md

@@ -12,22 +12,26 @@ description: >
 
 # QA Skill: ADO Integration (Optional Stage)
 
-**Stage**: Optional — ADO Integration (no pipeline order dependency)  
-**Prerequisite**: ADO configuration in `qa/qa-framework.config.json`; valid `ADO_PAT` env var  
-**Output**: ADO Test Plan populated + `qa/08-azure-integration/module-registry.json` updated  
-**Use any time** after Stage 4 (Test Cases) or Stage 5 (Automation) are ready to sync
+**Stage**: Optional — ADO Integration (no pipeline order dependency)
+**Prerequisite**: `Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` exists with a complete Tabla de Pruebas (steps filled in); valid `ADO_PAT` env var
+**Output**: ADO Test Plan populated with Test Suites and Test Cases (with steps) + `qa/08-azure-integration/module-registry.json` updated
+**Use any time** after Stage 3 (Plan de Pruebas) is ready — Stage 4 and 5 are not required
 
 > **Credential rule**: NEVER hardcode PAT, username, or organization URL in any file. Always read from env vars or `<PLACEHOLDER>` in documentation.
+> **Steps rule**: ADO Test Cases must have steps. Do not sync TCs from a Plan de Pruebas with empty or summary-only steps — run Stage 4 first to expand them.
 
 ---
 
 ## Inputs Required
 
 1. `qa/qa-framework.config.json` — ADO org URL, project name, test plan ID (or "create new")
-2. `qa/03-test-cases/automated/` — TC files with IDs to sync
+2. `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` — one file per module; each file's Tabla de Pruebas becomes one Test Suite in ADO
 3. `ADO_PAT` environment variable — personal access token with Test Plans read/write
 4. Optionally: `qa/08-azure-integration/module-registry.json` for existing ID mapping
 
+> **Note**: The consolidated `Plan-de-Pruebas-{proyecto}-Sprint-{N}.md` (without module suffix)
+> is for human reference only — do not use it as input for ADO scripts.
+
 ---
 
 ## Process
@@ -55,11 +59,21 @@ Required env vars:
 - `$env:ADO_PROJECT` — project name
 - `$env:ADO_PAT` — PAT token
 
-### Step 3 — Sync test cases
+### Step 3 — Sync test cases from Plan de Pruebas
+
+For each `Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` file:
+1. Read the Tabla de Pruebas
+2. Create one **Test Suite** in ADO named after the module (or use the suite groupings from section 5 of the plan)
+3. For each row in the table, create one **Test Case** with:
+   - Title: the Título column value
+   - Steps: the Steps column value (numbered steps, `<br>`-separated → each becomes one ADO step)
+   - Expected result: the Resultado Esperado column value
+   - Tags: Tipo + Prioridad values
+4. Write the returned ADO Test Case IDs back into the table (column "ADO WI") and into `module-registry.json`
 
-Use `inject-ado-ids.ps1` to push TCs to ADO and write the returned ADO test case IDs back into local TC files.
+Use `inject-ado-ids.ps1` to automate the create + inject cycle.
 
-After sync, each TC file must have `adoId: <NNN>` in its YAML frontmatter block.
+After sync, each row in the Plan de Pruebas table must have an ADO WI ID.
 
 ### Step 4 — Configure Playwright ADO reporter
 

package/skills/qa-test-cases/SKILL.md

@@ -1,22 +1,101 @@
 ---
 name: qa-test-cases
 description: >
-  Stage 4 of the QA pipeline. Generates individual test case documents from
-  approved specifications and the test plan. Produces TC-{ID}.md files with
-  preconditions, steps, and expected results.
-  Use when asked to write test cases, create TCs, expand scenarios into steps,
-  document test procedures, or generate TC-{ID} files.
-  Requires existing specs (Stage 2) and, ideally, a test plan (Stage 3).
+  Stage 4 of the QA pipeline. Expands or completes the test case steps in an
+  existing Plan de Pruebas document (from Stage 3). Use when: the Plan de Pruebas
+  was generated with summary steps that need to be expanded into concrete,
+  observable UI steps; or when standalone TC-*.md files are needed for complex
+  or reusable test cases. Use when asked to expand steps, complete test cases,
+  detail test procedures, or write standalone TC-*.md files.
+  Requires a Plan de Pruebas (Stage 3) for the target module/sprint.
 ---
 
-# QA Skill: Test Case Generation (Stage 4 of 6)
+# QA Skill: Test Case Step Expansion (Stage 4 of 6)
 
-**Stage**: 4 — Test Cases  
-**Prerequisite**: Submodule specs exist (Stage 2). Test plan is optional but strongly recommended.  
-**Output**: `qa/03-test-cases/automated/TC-{ID}.md` (one file per TC)  
-**Next stage**: Stage 5 — Automation (`qa-automation`)
+**Stage**: 4 — Test Case Steps (expand / complete Plan de Pruebas)
+**Prerequisite**: Plan de Pruebas exists at `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md`
+**Output**: Updated Plan de Pruebas table (primary) OR `qa/03-test-cases/TC-{ID}.md` files (standalone, optional)
+**Next stage**: Stage 5 — Automation (`qa-automation`) or ADO Integration (`qa-ado-integration`)
 
 > **Pipeline rule**: TC IDs must be unique across the module. Never reuse a TC ID.
+> **Primary output** is the table in the Plan de Pruebas, not standalone files.
+
+---
+
+## When to use this skill
+
+| Situation | Action |
+|-----------|--------|
+| Plan de Pruebas has summary steps (from `05-test-scenarios.md`) that aren't concrete enough | Expand steps row by row in the table |
+| A specific TC requires multi-scenario, multi-role documentation | Create standalone `TC-{ID}.md` in `qa/03-test-cases/` |
+| TC is reused across multiple sprints unchanged | Create standalone file with cross-reference |
+| All steps in the table are already concrete and observable | Stage 4 not needed — proceed to Stage 5 or ADO |
+
+---
+
+## Inputs Required
+
+1. `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` — table to expand
+2. `qa/01-specifications/module-{name}/submodule-{name}/00-inventory.md` — UI field names, button labels, routes
+3. `qa/01-specifications/module-{name}/submodule-{name}/05-test-scenarios.md` — original scenario text
+
+---
+
+## Process
+
+### Step 1 — Identify rows needing expansion
+
+Review the Tabla de Pruebas. Flag rows where Steps are:
+- Summary-level (e.g., "Navegar al módulo y verificar comportamiento")
+- Missing intermediate steps (fewer than 2 steps for a non-trivial scenario)
+- Using vague verbs ("hacer lo necesario", "verificar que funciona")
+
+### Step 2 — Expand steps in-table
+
+For each flagged row, rewrite the Steps cell using:
+- `00-inventory.md` for exact UI element names and routes
+- `05-test-scenarios.md` for the original intent
+- Steps format: `1) Navegar a {QA_BASE_URL}/ruta<br>2) Ingresar...<br>3) Verificar que...`
+
+Quality rules per step:
+- Concrete verb: Navegar, Ingresar, Hacer click, Seleccionar, Verificar, Revisar
+- One action + one verification per step (when applicable)
+- Resultado Esperado must be measurable (specific text, state, count)
+
+### Step 3 — Standalone TC files (only when needed)
+
+If a TC requires standalone documentation (see "When to use" table above):
+- Save as `qa/03-test-cases/TC-{ID}.md`
+- Use template from `references/test-case-template.md`
+- Add a note in the Plan de Pruebas table row: "See qa/03-test-cases/TC-{ID}.md"
+
+### Step 4 — Quality gates
+
+Before marking stage complete:
+- [ ] Every row in the table has ≥ 2 numbered steps
+- [ ] Every step uses a concrete UI verb
+- [ ] Every Resultado Esperado is measurable
+- [ ] No blank cells in Confirma column (Task ID or `N/A`)
+- [ ] Standalone TC files (if created) are cross-referenced in the table
+
+---
+
+## Key Rules
+
+| Rule | Correct | Wrong |
+|---|---|---|
+| Primary output | Expand rows in Plan de Pruebas table | Create files for every TC |
+| Step granularity | One action + one observable result | Multi-action vague steps |
+| Data references | `{QA_USER_EMAIL}`, `EXEC_IDX`, named env var | Hardcoded credentials |
+| ID stability | Never re-number existing TC-IDs | Renaming breaks ADO links |
+
+---
+
+## Outputs
+
+- Updated `Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` (rows with expanded steps)
+- Optionally: `qa/03-test-cases/TC-{ID}.md` for complex/reusable TCs
+
 
 ---
 

package/skills/qa-test-plan/SKILL.md

@@ -1,20 +1,125 @@
 ---
 name: qa-test-plan
 description: >
-  Stage 3 of the QA pipeline. Generates a test plan document from completed
-  submodule specifications. Defines scope, priority distribution, automation
-  feasibility, ADO mapping, and TC selection for a sprint or release.
-  Use when asked to create a test plan, define test scope, plan a sprint,
-  prioritize test cases, or decide what to automate vs test manually.
+  Stage 3 of the QA pipeline. Generates a "Plan de Pruebas" document per sprint
+  and module. The document combines test plan context (scope, strategy, preconditions)
+  with a detailed test case table (steps, expected results, ADO Task reference).
+  This is the primary artifact consumed by the ADO integration skill to create
+  Test Suites and Test Cases with steps in Azure DevOps.
+  Use when asked to create a test plan, plan a sprint, write test cases with steps,
+  or produce the QA plan for a module or sprint.
   Requires completed specs (Stage 2).
 ---
 
-# QA Skill: Test Plan Generation (Stage 3 of 6)
+# QA Skill: Plan de Pruebas (Stage 3 of 6)
+
+**Stage**: 3 — Plan de Pruebas (test plan + detailed test case table)
+**Prerequisite**: `05-test-scenarios.md` must exist for all in-scope submodules (Stage 2 complete)
+**Output**: `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md`
+**Next stage**: Stage 4 — Expand steps (`qa-test-cases`) if steps need more detail; or Stage 5 — Automation (`qa-automation`)
+
+> **Pipeline rule**: Do not automate TCs that are not in an active Plan de Pruebas.
+> **ADO rule**: The Plan de Pruebas is the source for ADO Test Cases — steps in the table become steps in ADO.
+
+---
+
+## Inputs Required
+
+1. `qa/01-specifications/module-{name}/submodule-{name}/` — spec files, especially:
+   - `00-inventory.md` — UI fields, buttons, routes (source for concrete step text)
+   - `05-test-scenarios.md` — TC list with summary steps and expected results
+2. Sprint number and module name (ask the user if not given)
+3. ADO sprint tasks/stories (if available; use for "Confirma" column; `N/A` if not)
+4. Project name from `qa/qa-framework.config.json` → `project.name`
+
+---
+
+## Process
+
+### Step 1 — Collect TC inventory
+
+For each in-scope submodule, read `05-test-scenarios.md` and aggregate:
+- Total TC count by priority (P0/P1/P2/P3)
+- TC count by type: Manual / Automatizado / Ambos
+- TCs marked `BLOCKED-PERMISSIONS` or `PENDING-CODE` → include in table but mark type as `Bloqueado`
+
+### Step 2 — Apply priority rules
+
+Use the priority decision tree (see `references/plan-de-pruebas-template.md`):
+- **P0**: happy path confirmation; show-stopper risk; data corruption
+- **P1**: common negative; cross-module; state transitions; smoke E2E
+- **P2**: secondary features (export, pagination, search); regression adjacent
+- **P3**: edge cases; exploratory charters (timeboxed)
+
+### Step 3 — Define TestSuites (ADO grouping)
+
+Group TCs by functional area. Each group → one ADO Test Suite:
+- 3–7 suites per module is typical
+- Name suites after the functional area, not the priority (e.g., "Solicitud Individual", "Aprobación Web")
+- Last suite: "Exploratoria" if there are P3 charters
+
+### Step 4 — Write the Plan de Pruebas document
+
+Full template: `references/plan-de-pruebas-template.md`
+
+Required sections:
+1. Header (Proyecto, Sprint, Módulo, Fecha planificación, Ventana QA, ADO Test Plan link)
+2. Objetivo
+3. Alcance (en alcance / fuera de alcance)
+4. Items del Sprint normalizados (grouped by area; Task IDs if available)
+5. Priorización (P0–P3 summary)
+6. TestSuites (agrupación para ADO)
+7. Precondiciones generales (ambiente, roles, datos base)
+8. Datos mínimos sugeridos (table with env var references)
+9. Supuestos & Faltantes críticos (TODO items before execution)
+10. **Tabla de Pruebas** (see Step 4a)
+11. Matriz de Trazabilidad (Task ↔ N)
+12. Notas de automatización
+
+#### Step 4a — Tabla de Pruebas (most important section)
+
+Each row in the table is one test case. Columns:
+
+| Column | Rules |
+|--------|-------|
+| **N** | Sequential number (1, 2, 3...) — used in trazabilidad matrix |
+| **TC-ID** | `TC-{MODULE}-{SUB}-{NNN}` from specs; or assign sequentially if new |
+| **Suite / Área Funcional** | Suite name from Step 3 |
+| **Título** | `[ETIQUETA][P#] Descripción concisa` — etiquetas: CONFIRMACION, SMOKE, REGRESION, EXPLORATORIA |
+| **Descripción** | What scenario this validates (1-2 sentences) |
+| **Steps** | Numbered, separated by `<br>`. Use concrete UI verbs from `00-inventory.md`: "Navegar a", "Ingresar", "Hacer click en", "Verificar que", "Seleccionar". Reference env vars as `{ENV_VAR}` |
+| **Resultado Esperado** | Observable outcome: specific text, state change, notification. Not vague ("works correctly") |
+| **Confirma** | `Task NNNNN` if an ADO task covers this; `N/A` if no task or exploratory |
+| **Tipo** | `Manual` \| `Automatizado` \| `Ambos` \| `Bloqueado` |
+| **Prioridad** | `P0` \| `P1` \| `P2` \| `P3` |
+
+**Steps quality rules**:
+- Each step = one observable action + one observable verification (when applicable)
+- Reference UI elements by name as seen in `00-inventory.md` (exact button label, field name)
+- Reference test data by env var name (`{QA_USER_EMAIL}`) or pattern (`EXEC_IDX`)
+- Exploratory charters: steps = "Timebox N min" + charter goal + "Registrar hallazgos"
+
+### Step 5 — Update status
+
+- Update `qa/README.md` module row (plan status → ✅)
+- If ADO enabled: stub the ADO Plan ID field for the ADO integration skill
+
+---
+
+## Outputs
+
+- `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md`
+- Updated `qa/README.md` module status row
+
+## Quality gates before marking complete
+
+- [ ] All in-scope TCs from `05-test-scenarios.md` appear in the table
+- [ ] Every row has at least 2 numbered steps
+- [ ] Every step uses a concrete UI verb (not vague like "do the action")
+- [ ] Resultado Esperado is measurable (specific text/state, not "works correctly")
+- [ ] Matriz de Trazabilidad covers all Tasks mentioned in the table
+- [ ] `Confirma` column has no blank cells (must be Task ID or `N/A`)
 
-**Stage**: 3 — Test Plan  
-**Prerequisite**: `05-test-scenarios.md` must exist for all in-scope submodules (Stage 2 complete)  
-**Output**: `qa/02-test-plans/automated/{module}-test-plan.md`  
-**Next stage**: Stage 4 — Test Cases (`qa-test-cases`) or Stage 5 — Automation (`qa-automation`)
 
 > **Pipeline rule**: Do not automate TCs that are not in an approved or active test plan.
 

package/skills/qa-test-plan/references/plan-de-pruebas-template.md

@@ -0,0 +1,148 @@
+# Reference: Plan de Pruebas — Template and Conventions
+
+> Loaded by `skills/qa-test-plan/` when generating a Plan de Pruebas document.
+
+---
+
+## File Naming Convention
+
+```
+qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md
+```
+
+Where `{modulo}` is the module code (e.g., `RCL-Casino`, `PortalProveedores`, `ARCF`).
+
+---
+
+## Complete Document Template
+
+```markdown
+# Plan de Pruebas — {PROYECTO} — Sprint {NNN} — {MODULO_NOMBRE}
+
+**Proyecto:** {PROYECTO}
+**Sprint:** {NNN}
+**Módulo:** {MODULO_NOMBRE}
+**Código módulo:** {MODULO_CODE}
+**Fecha planificación:** {YYYY-MM-DD}
+**Ventana QA:** {YYYY-MM-DD} y {YYYY-MM-DD}
+**ADO Test Plan:** [Plan {ADO_PLAN_ID}]({ADO_TEST_PLAN_URL})  ← omit if ADO disabled
+
+---
+
+## 1. Objetivo
+## 2. Alcance
+### En alcance
+### Fuera de alcance
+## 3. Items del Sprint (normalizados)
+## 4. Priorización (P0–P3 summary)
+## 5. TestSuites (agrupación para ADO)
+## 6. Precondiciones generales
+## 7. Datos mínimos sugeridos
+## 8. Supuestos & Faltantes críticos
+## 9. Tabla de Pruebas    ← PRIMARY ARTIFACT
+## 10. Matriz de Trazabilidad
+## 11. Notas de automatización
+```
+
+---
+
+## Tabla de Pruebas — Column Conventions
+
+| Column | Type | Rules |
+|--------|------|-------|
+| N | int | Sequential 1,2,3... Used in trazabilidad matrix |
+| TC-ID | string | `TC-{MODULE}-{SUB}-{NNN}` from specs; or `TC-{MODULE}-{NNN}` if no submodule code |
+| Suite / Área Funcional | string | Matches a suite name from section 5 |
+| Título | string | `[ETIQUETA][P#] Description` |
+| Descripción | string | What scenario this validates (1-2 sentences) |
+| Steps | markdown | Numbered, `<br>`-separated. Concrete UI verbs. |
+| Resultado Esperado | string | Observable, measurable outcome |
+| Confirma | string | `Task NNNNN` or `N/A` |
+| Tipo | enum | `Manual` \| `Automatizado` \| `Ambos` \| `Bloqueado` |
+| Prioridad | enum | `P0` \| `P1` \| `P2` \| `P3` |
+
+### Title Etiquetas
+- `[CONFIRMACION]` — confirms a specific sprint item is implemented
+- `[SMOKE]` — happy path end-to-end
+- `[REGRESION]` — validates no regression in adjacent functionality
+- `[EXPLORATORIA]` — charter-based, timeboxed, no fixed expected result
+
+---
+
+## Steps Writing Rules
+
+**DO:**
+- `1) Navegar a {QA_BASE_URL}/ruta/modulo`
+- `2) Ingresar usuario {QA_USER_EMAIL} y contraseña {QA_USER_PASSWORD}`
+- `3) Hacer click en el botón "Guardar"`
+- `4) Verificar que aparece el mensaje "Registro guardado correctamente"`
+- `5) Revisar bandeja de correo del usuario {QA_NOTIFY_EMAIL}`
+
+**DO NOT:**
+- `1) Ejecutar la funcionalidad` ← too vague
+- `2) Verificar que funciona` ← not measurable
+- `3) Hacer las acciones necesarias` ← not observable
+
+**References to test data:**
+- Env vars: `{QA_USER_EMAIL}`, `{QA_ADMIN_EMAIL}`, `{QA_BASE_URL}`
+- Dynamic values: `EXEC_IDX` (unique run suffix)
+- Specific values: write the actual value if it's fixed (e.g., a range of dates like `01-03-2026 a 07-03-2026`)
+
+**Exploratory charters:**
+```
+1) Timebox: 45–60 min
+2) Objetivo: {CHARTER_GOAL}
+3) Explorar {AREA} variando {VARIABLES}
+4) Registrar hallazgos con evidencia (screenshot + descripción)
+```
+
+---
+
+## Priority Decision Tree
+
+```
+Is it the primary happy path?                    → P0
+Is it a show-stopper risk or data corruption?    → P0
+Is it a common negative scenario?                → P1
+Is it a cross-module dependency?                 → P1
+Is it a state machine transition?                → P1
+Is it a secondary feature (export/search)?       → P2
+Is it regression in adjacent functionality?      → P2
+Is it an edge case or low-frequency scenario?    → P3
+Is it exploratory / cosmetic?                    → P3
+```
+
+---
+
+## Automation Feasibility Rules
+
+| Feasibility | Criteria | Column `Tipo` |
+|---|---|---|
+| Fully automatable | Deterministic, observable via browser, no external deps | `Automatizado` |
+| Partially automatable | Some steps require human inspection OR external can be mocked | `Ambos` |
+| Not automatable | Physical access; irreversible QA side effects; BLOCKED-PERMISSIONS | `Manual` |
+| Blocked | Feature not deployed or BLOCKED-PERMISSIONS | `Bloqueado` |
+
+---
+
+## Matriz de Trazabilidad Template
+
+```markdown
+## 10. Matriz de Trazabilidad
+
+| Task ADO | N casos (tabla) |
+|----------|-----------------|
+| Task 20112 | 4, 5, 6 |
+| Task 21944 | 1, 2, 3 |
+```
+
+If no ADO tasks: substitute with requirement IDs or user story references.
+
+---
+
+## Multi-Module Sprint
+
+When a sprint covers multiple modules:
+- Create one `Plan-de-Pruebas-{proyecto}-Sprint-{N}-{modulo}.md` per module
+- The consolidated `Plan-de-Pruebas-{proyecto}-Sprint-{N}.md` is generated by `@keber/ado-qa consolidate-sprint`
+- **Do not create the consolidated file manually** — it is a derived artifact

package/templates/test-plan-sprint.md

@@ -0,0 +1,152 @@
+# Plan de Pruebas — {{PROYECTO}} — Sprint {{NNN}} — {{MODULO_NOMBRE}}
+
+**Proyecto:** {{PROYECTO}}
+**Sprint:** {{NNN}}
+**Módulo:** {{MODULO_NOMBRE}}
+**Código módulo:** {{MODULO_CODE}}
+**Fecha planificación:** {{YYYY-MM-DD}}
+**Ventana QA:** {{YYYY-MM-DD}} y {{YYYY-MM-DD}}
+**ADO Test Plan:** [Plan {{ADO_PLAN_ID}} — {{PROYECTO}} Sprint {{NNN}}]({{ADO_TEST_PLAN_URL}}) *(omitir si ADO no está habilitado)*
+
+---
+
+## 1. Objetivo
+
+> Definir la estrategia de pruebas para el Sprint {{NNN}}, orientada a:
+> - Confirmar la correcta implementación de las tareas comprometidas en el sprint.
+> - Cubrir los flujos críticos del módulo **{{MODULO_NOMBRE}}**.
+> - Identificar riesgos funcionales, de datos y de integración.
+
+---
+
+## 2. Alcance
+
+### En alcance
+- {{FUNCIONALIDAD_1}}
+- {{FUNCIONALIDAD_2}}
+
+### Fuera de alcance
+- {{EXCLUSION_1}} *(motivo: {{RAZON}})*
+- {{EXCLUSION_2}}
+
+---
+
+## 3. Items del Sprint (normalizados)
+
+> Listar las tareas/historias ADO incluidas en este sprint, agrupadas por área funcional.
+> Si no hay ADO, listar los requerimientos o módulos abordados.
+
+### {{AREA_FUNCIONAL_1}}
+- Task {{ID}} — {{DESCRIPCION}}
+- Task {{ID}} — {{DESCRIPCION}}
+
+### {{AREA_FUNCIONAL_2}}
+- Task {{ID}} — {{DESCRIPCION}}
+
+---
+
+## 4. Priorización
+
+**P0 – Confirmación (obligatorio)**
+- {{ESCENARIO_CRITICO_1}}
+- {{ESCENARIO_CRITICO_2}}
+
+**P1 – Smoke (camino feliz)**
+- {{FLUJO_PRINCIPAL}}
+
+**P2 – Regresión mínima adyacente**
+- {{REGRESION_1}}
+
+**P3 – Exploratoria (timeboxed)**
+- Charter 1 ({{N}} min): {{DESCRIPCION_CHARTER}}
+
+---
+
+## 5. TestSuites (agrupación para ADO)
+
+> Cada suite se crea como un Test Suite dentro del Test Plan ADO.
+> Si ADO no está habilitado, usar como agrupación lógica de la tabla de pruebas.
+
+1. **{{SUITE_1}}**
+2. **{{SUITE_2}}**
+3. **{{SUITE_3}}**
+
+---
+
+## 6. Precondiciones generales
+
+- Ambiente QA disponible en `{{QA_BASE_URL}}`
+- Roles disponibles:
+  - Usuario **{{ROL_1}}** — para {{ACCION}}
+  - Usuario **{{ROL_2}}** — para {{ACCION}}
+- Datos base:
+  - {{DATO_BASE_1}}
+  - {{DATO_BASE_2}}
+
+---
+
+## 7. Datos mínimos sugeridos
+
+| Item | Valor / Referencia |
+|------|--------------------|
+| {{DATO_1}} | `process.env.{{ENV_VAR}}` |
+| {{DATO_2}} | {{VALOR_O_PATRON}} |
+
+---
+
+## 8. Supuestos & Faltantes críticos
+
+**Supuestos:**
+- **Supuesto:** {{SUPUESTO_1}}
+
+**Faltantes críticos (TODO antes de ejecutar):**
+1. **TODO:** {{PENDIENTE_1}}
+2. **TODO:** {{PENDIENTE_2}}
+
+---
+
+## 9. Tabla de Pruebas
+
+> Convenciones:
+> - **TC-ID:** `TC-{{MODULO_CODE}}-{{SUBMODULO_CODE}}-NNN` (o `N/A` si no hay ID asignado aún)
+> - **Steps:** numerados, separados por `<br>` — verbos concretos de UI (`Navegar a`, `Ingresar`, `Hacer click`, `Verificar`)
+> - **Confirma:** `Task NNNNN` si hay tarea ADO relacionada; `N/A` si no aplica
+> - **Tipo:** `Manual` | `Automatizado` | `Ambos`
+> - **Prioridad:** `P0` | `P1` | `P2` | `P3`
+
+| N | TC-ID | Suite / Área Funcional | Título | Descripción | Steps | Resultado Esperado | Confirma | Tipo | Prioridad |
+|---|-------|------------------------|--------|-------------|-------|--------------------|----------|------|-----------|
+| 1 | TC-{{MODULO_CODE}}-{{SUB}}-001 | {{SUITE_1}} | [{{ETIQUETA}}][{{P}}] {{TITULO}} | {{DESCRIPCION}} | 1) {{PASO_1}}<br>2) {{PASO_2}}<br>3) {{PASO_3}} | {{RESULTADO_ESPERADO}} | Task {{ID}} | Manual | P0 |
+| 2 | TC-{{MODULO_CODE}}-{{SUB}}-002 | {{SUITE_1}} | [{{ETIQUETA}}][{{P}}] {{TITULO}} | {{DESCRIPCION}} | 1) {{PASO_1}}<br>2) {{PASO_2}} | {{RESULTADO_ESPERADO}} | N/A | Automatizado | P1 |
+
+> **Etiquetas de título:** `[CONFIRMACION]` | `[SMOKE]` | `[REGRESION]` | `[EXPLORATORIA]`
+
+---
+
+## 10. Matriz de Trazabilidad
+
+| Task ADO | N casos (tabla) |
+|----------|-----------------|
+| Task {{ID}} | 1, 3, 5 |
+| Task {{ID}} | 2, 4 |
+
+> Si no hay Tasks ADO, usar esta sección para mapear requerimientos o funcionalidades a N.
+
+---
+
+## 11. Notas de automatización
+
+> Para los TCs marcados como `Automatizado` o `Ambos`, el spec file de referencia es:
+> `qa/07-automation/e2e/tests/{{modulo-kebab}}/{{submodulo-kebab}}.spec.ts`
+>
+> Los steps de esta tabla son la fuente autoritativa para los `test.step()` en el spec.
+
+---
+
+## Consolidado de sprint
+
+> Si este sprint cubre múltiples módulos, existe un documento consolidado generado automáticamente:
+> `qa/02-test-plans/sprints/Sprint-{{NNN}}/Plan-de-Pruebas-{{PROYECTO}}-Sprint-{{NNN}}.md`
+>
+> El consolidado se genera con el script `@keber/ado-qa consolidate-sprint --sprint {{NNN}}`.
+> **No editar manualmente** — es derivado de los archivos por módulo.

package/templates/test-plan.md

@@ -1,3 +1,9 @@
+> **Deprecation notice (v1.7.0):** This template is superseded by `templates/test-plan-sprint.md`,
+> which combines the test plan and detailed test case table (steps included) in a single document
+> organized by sprint and module. Use `test-plan-sprint.md` for all new work.
+>
+> This file is retained for reference only.
+
 # Test Plan — {{MODULE_NAME}}
 
 **Plan ID**: TP-{{MODULE}}-{{VERSION}}