@keber/qa-framework 1.11.3 → 1.13.0

package/docs/final-report.md

@@ -1,4 +1,4 @@
-# Phase 6 — Final Report: keber/qa-framework
+# Phase 6 - Final Report: keber/qa-framework
 
 **Date**: 2025-01-15
 **Version analyzed**: 1.0.0
@@ -26,29 +26,29 @@ procedures documented in `MIGRATION-NOTES.md`.
 
 ## 2. Source Repository Findings
 
-### Repo A — redacted-repo-web
+### Repo A - redacted-repo-web
 
 | Category | Finding |
 |----------|---------|
 | Stack | ASP.NET MVC 5 + Web API 2 + SQL Server |
 | Frontend | jQuery + Select2 + toastr + SweetAlert2 + Metronic |
 | Auth | RUT-based login (`#m_login_signin_submit`) |
-| QA maturity | Medium — spec files present, standards missing |
+| QA maturity | Medium - spec files present, standards missing |
 | Automation | Sprint 40: 26 P0 tests (24 pass, 2 skip via DEF-001/DEF-002) |
 | ADO | Referenced (Plan 21992/Suite 21993) but not reporter-integrated |
 | Modules | 7 submodules documented (~160 TCs across 82 QA files) |
 | Strengths | EXEC_IDX pattern, POM structure, multi-role auth, skip+DEF |
 | Gaps | No `00-standards/`, no `08-azure-integration/`, no session summaries |
 
-### Repo B — redacted-repo
+### Repo B - redacted-repo
 
 | Category | Finding |
 |----------|---------|
 | Stack | Blazor WebAssembly + .NET + Radzen components |
 | Auth | Email-based (`#email-input` / `#password-input`) |
-| QA maturity | High — complete standards folder, ADO fully integrated |
+| QA maturity | High - complete standards folder, ADO fully integrated |
 | Automation | 67 automated TCs (53 pass / 2 fail / 12 skip) |
-| ADO | Full: Plans 22304/22794/22875, WI IDs 22957–23034, bi-directional sync |
+| ADO | Full: Plans 22304/22794/22875, WI IDs 22957-23034, bi-directional sync |
 | Modules | 4 modules × 17+ submodules (~894 TCs) |
 | Strengths | `00-standards/`, `08-azure-integration/`, module-registry, ado reporter |
 | Gaps | No EXEC_IDX pattern, no POM convention, no session summaries |
@@ -61,9 +61,9 @@ procedures documented in `MIGRATION-NOTES.md`.
 |---------|--------|----------|
 | 6-file submodule spec pattern | Both | Core framework pattern |
 | Playwright `@playwright/test` | Both | Standard automation library |
-| Priority levels P0–P3 | Both | Universal tagging via `@PX` |
+| Priority levels P0-P3 | Both | Universal tagging via `@PX` |
 | `test.skip()` + DEF reference | Repo A | Adopted as standard skip convention |
-| `06-defects/` folder | Repo A | Optional — recommended without ADO |
+| `06-defects/` folder | Repo A | Optional - recommended without ADO |
 | `00-standards/` folder | Repo B | Adopted; templates included |
 | `08-azure-integration/` folder | Repo B | Optional; fully documented |
 | `module-registry.json` | Repo B | Included in ADO integration |
@@ -85,7 +85,7 @@ procedures documented in `MIGRATION-NOTES.md`.
 | RUT-based username field | Repo A | Parameterized via `QA_LOGIN_EMAIL_SELECTOR` |
 | `#email-input` / `#password-input` | Repo B | Parameterized via env vars |
 | ADO Plan IDs (21992, 22304, etc.) | Both | Parameterized via `QA_ADO_PLAN_ID` |
-| ADO WI IDs (22957–23034) | Repo B | Injected per-project via inject-ado-ids.ps1 |
+| ADO WI IDs (22957-23034) | Repo B | Injected per-project via inject-ado-ids.ps1 |
 | Specific module names/selectors | Both | Remain in project-specific spec files |
 | Sprint numbers | Both | Remain in project-specific test plans |
 | Metronic theme selectors | Repo A | Project-specific; documented in Repo A specs |
@@ -110,7 +110,7 @@ Fifteen formal decisions were made and documented in `docs/generalization-decisi
 | §8 | POM pattern | Recommended (Repo A); inline acceptable |
 | §9 | Standards folder | Adopted from Repo B (more complete) |
 | §10 | Session summaries | New addition to both repos' patterns |
-| §11 | Priority levels | P0–P3 universal; `@P0` grep-tag convention |
+| §11 | Priority levels | P0-P3 universal; `@P0` grep-tag convention |
 | §12 | `08-azure-integration/` | Optional; fully documented scripts |
 | §13 | CI pipeline | Parameterized `azure-pipeline-qa.yml` |
 | §14 | Framework distribution | npm package (`keber/qa-framework`) |
@@ -122,23 +122,23 @@ Fifteen formal decisions were made and documented in `docs/generalization-decisi
 
 ```
 qa-framework/
-├── package.json                          ← npm package, CLI entry
-├── qa-framework.config.json             ← example project config
+├── package.json                          <- npm package, CLI entry
+├── qa-framework.config.json             <- example project config
 ├── README.md
 ├── CHANGELOG.md
 ├── MIGRATION-NOTES.md
 │
 ├── docs/
-│   ├── architecture.md                  ← 4-layer component map
-│   ├── comparison-matrix.md             ← Phase 1 artifact
-│   ├── generalization-decisions.md      ← Phase 2 artifact (15 decisions)
-│   ├── installation.md                  ← 3 install options
-│   ├── spec-driven-philosophy.md        ← Core methodology
-│   ├── folder-structure-guide.md        ← Full folder reference
-│   ├── usage-with-agent.md              ← Agent prompt patterns
-│   └── final-report.md                  ← This file
+│   ├── architecture.md                  <- 4-layer component map
+│   ├── comparison-matrix.md             <- Phase 1 artifact
+│   ├── generalization-decisions.md      <- Phase 2 artifact (15 decisions)
+│   ├── installation.md                  <- 3 install options
+│   ├── spec-driven-philosophy.md        <- Core methodology
+│   ├── folder-structure-guide.md        <- Full folder reference
+│   ├── usage-with-agent.md              <- Agent prompt patterns
+│   └── final-report.md                  <- This file
 │
-├── agent-instructions/                  ← Consumed by Copilot agent
+├── agent-instructions/                  <- Consumed by Copilot agent
 │   ├── 00-module-analysis.md
 │   ├── 01-spec-generation.md
 │   ├── 02-test-plan-generation.md
@@ -148,7 +148,7 @@ qa-framework/
 │   └── 06-maintenance.md
 │
 ├── templates/
-│   ├── specification/                   ← 6-file submodule template set
+│   ├── specification/                   <- 6-file submodule template set
 │   │   ├── 00-inventory.md
 │   │   ├── 01-business-rules.md
 │   │   ├── 02-workflows.md
@@ -188,7 +188,7 @@ qa-framework/
 │           ├── 00-inventory.md
 │           └── suppliers-create.spec.ts
 │
-└── scripts/                             ← CLI implementation
+└── scripts/                             <- CLI implementation
     ├── cli.js
     ├── init.js
     ├── generate.js

package/docs/folder-structure-guide.md

@@ -1,6 +1,6 @@
 # docs/folder-structure-guide.md
 
-## `qa/` Directory Structure — Full Reference Guide
+## `qa/` Directory Structure - Full Reference Guide
 
 This document explains the purpose, contents, and conventions for every folder in the `qa/` directory.
 
@@ -10,25 +10,28 @@ 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
+├── 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-standards/                ← Naming conventions and artifact templates
-├── 01-specifications/           ← Functional specifications per module
-├── 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
-├── 06-defects/                  ← Defect tracking (optional)
-├── 07-automation/               ← Automation code (Playwright, etc.)
-├── 08-azure-integration/        ← Azure DevOps integration (optional)
-└── memory/                      ← Project QA learnings (project-maintained)
+├── 00-standards/                <- Naming conventions and artifact templates
+├── 01-specifications/           <- Functional specifications per module
+├── 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
+├── 06-defects/                  <- Defect tracking (optional)
+├── 07-automation/               <- Automation code (Playwright, etc.)
+├── 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.
 
+`init`/`upgrade` also generate `.claude/rules/qa-framework.md` and `.claude/commands/qa-*.md`
+(Claude Code equivalents of the Copilot instructions/skills - see the section below).
+
 ---
 
 ## Dual-Track Pipeline
@@ -37,35 +40,35 @@ All pipeline paths share the same input: `01-specifications/`. From there, work
 two tracks that can run in parallel or independently depending on team maturity.
 
 ```
-01-specifications/  (source of truth — what the app does and what must be tested)
+01-specifications/  (source of truth - what the app does and what must be tested)
         │
         ├─── Automation track ──────────────────────────────────────────────────
         │         │
         │         ▼
-        │    02-test-plans/sprints/Sprint-{N}/    ← Plan de Pruebas (plan + TC table + steps)
+        │    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
+        │    07-automation/e2e/tests/      <- Playwright .spec.ts files
         │         │
         │         ▼
-        │    05-test-execution/automated/  ← execution reports
+        │    05-test-execution/automated/  <- execution reports
         │         │
         │         ▼
-        │    08-azure-integration/         ← ADO sync via playwright-azure-reporter
+        │    08-azure-integration/         <- ADO sync via playwright-azure-reporter
         │
         └─── Manual track ──────────────────────────────────────────────────────
                   │
                   ▼
-             02-test-plans/sprints/Sprint-{N}/    ← same Plan de Pruebas (shared artifact)
+             02-test-plans/sprints/Sprint-{N}/    <- same Plan de Pruebas (shared artifact)
                   │
                   ▼
-             03-test-cases/ (optional)     ← standalone TC-*.md for complex/reusable TCs
+             03-test-cases/ (optional)     <- standalone TC-*.md for complex/reusable TCs
                   │
                   ▼
-             05-test-execution/manual/     ← manual run evidence
+             05-test-execution/manual/     <- manual run evidence
                   │
                   ▼
-             08-azure-integration/         ← ADO sync via ado-integration skill
+             08-azure-integration/         <- ADO sync via ado-integration skill
                                               (reads Plan de Pruebas, creates TCs with steps)
 ```
 
@@ -73,21 +76,21 @@ two tracks that can run in parallel or independently depending on team maturity.
 
 | Scenario | Entry point | Tracks active |
 |---|---|---|
-| New system, no prior QA | Module analysis → spec generation | Automation (primary), Manual (as needed) |
-| Sprint with ADO stories | Stories → spec generation → test plan | Both, driven by sprint scope |
-| Maintenance/continuous improvement | Changed module → maintenance skill | Automation (update existing tests) |
+| New system, no prior QA | Module analysis -> spec generation | Automation (primary), Manual (as needed) |
+| Sprint with ADO stories | Stories -> spec generation -> test plan | Both, driven by sprint scope |
+| Maintenance/continuous improvement | Changed module -> maintenance skill | Automation (update existing tests) |
 
 **Track selection guidance:**
 - Use **automation track** when the goal is regression coverage and CI integration.
 - Use **manual track** when: (a) team has manual testers who need step-by-step documents; (b) auditability or traceability to external standards is required; (c) features are not yet automatable.
-- Both tracks use the same TC-IDs from `01-specifications/*/05-test-scenarios.md` — traceability is preserved regardless of which track executes a given TC.
+- Both tracks use the same TC-IDs from `01-specifications/*/05-test-scenarios.md` - traceability is preserved regardless of which track executes a given TC.
 - `04-test-data/` is optional in both tracks. Use it when test data factories or seeders are shared across multiple modules. Per-submodule data belongs in `01-specifications/*/04-test-data.md`.
 
 ---
 
 ## .github/skills/
 
-**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.
+**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** via `npm install @keber/qa-framework`:
 
@@ -103,8 +106,25 @@ two tracks that can run in parallel or independently depending on team maturity.
 | `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)
+- `SKILL.md` - process outline (~400-600 tokens, always loaded when skill applies)
+- `references/` - detailed templates and code patterns (loaded on demand)
+
+---
+
+## .claude/commands/ and .claude/rules/
+
+**Purpose**: Claude Code native equivalents of `.github/instructions/qa-framework.instructions.md`
+and `.github/skills/`, generated by `init`/`upgrade` in parallel with the Copilot artifacts
+(no agent detection - both are always generated).
+
+| File | Role |
+|---|---|
+| `.claude/rules/qa-framework.md` | Same 11 agent behavior rules + pipeline table as the Copilot instructions file. No frontmatter, so it loads unconditionally in every Claude Code session (equivalent to `applyTo: '**'`). |
+| `.claude/commands/qa-{name}.md` | One thin wrapper per skill folder under `.github/skills/`, discovered dynamically (not hardcoded). Each wrapper reads: `Read the full skill at .github/skills/qa-{name}/SKILL.md FIRST, then follow its instructions exactly`, plus the stage prerequisite. Invoked as `/qa-{name}` in a Claude Code session. |
+
+This is a "thin wrapper" pattern: the command never duplicates skill content, it only
+points back at `SKILL.md` as the single source of truth. Updating a skill automatically
+updates every command that references it - no regeneration needed, zero drift possible.
 
 ---
 
@@ -126,25 +146,25 @@ Each skill folder contains:
 
 ## 01-specifications/
 
-**Purpose**: Functional specifications — the primary source of truth for what the application does and what must be tested.
+**Purpose**: Functional specifications - the primary source of truth for what the application does and what must be tested.
 
 **Structure**:
 ```
 01-specifications/
-├── README.md                    ← Index of all modules
-├── shared/                      ← Shared artifacts (sitemap, shared templates)
-│   ├── ui-menu-map.md           ← Auto-generated from playwright session
-│   └── Instrucciones-analisis.md ← Checklist template for module analysis
+├── README.md                    <- Index of all modules
+├── shared/                      <- Shared artifacts (sitemap, shared templates)
+│   ├── ui-menu-map.md           <- Auto-generated from playwright session
+│   └── Instrucciones-analisis.md <- Checklist template for module analysis
 │
 └── module-{module-name}/
-    ├── README.md                ← Module index (submodule table + E2E flow)
+    ├── README.md                <- Module index (submodule table + E2E flow)
     └── submodule-{name}/
-        ├── 00-inventory.md      ← UI elements, routes, APIs, fields
-        ├── 01-business-rules.md ← RN-* rules the system enforces
-        ├── 02-workflows.md      ← FL-* user flow diagrams (Mermaid/ASCII)
-        ├── 03-roles-permissions.md ← Role matrix
-        ├── 04-test-data.md      ← Data shapes and prerequisites
-        └── 05-test-scenarios.md ← TC-* test cases with priority and steps
+        ├── 00-inventory.md      <- UI elements, routes, APIs, fields
+        ├── 01-business-rules.md <- RN-* rules the system enforces
+        ├── 02-workflows.md      <- FL-* user flow diagrams (Mermaid/ASCII)
+        ├── 03-roles-permissions.md <- Role matrix
+        ├── 04-test-data.md      <- Data shapes and prerequisites
+        └── 05-test-scenarios.md <- TC-* test cases with priority and steps
 ```
 
 **Naming rules**:
@@ -153,7 +173,7 @@ Each skill folder contains:
 - Module code: 2-6 uppercase letters (e.g., `OPER`, `PERS`, `ARCF`)
 - TC ID: `TC-{MODULE}-{SUBMODULE}-{3-digit}` (e.g., `TC-OPER-CAT-001`)
 
-**TC target per submodule**: 50–85 test cases is considered a well-analyzed submodule.
+**TC target per submodule**: 50-85 test cases is considered a well-analyzed submodule.
 
 ---
 
@@ -166,8 +186,8 @@ Each skill folder contains:
 ├── README.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)
+        ├── 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)
 ```
 
 **Naming convention**: `Plan-de-Pruebas-{proyecto}-Sprint-{NNN}-{modulo}.md`
@@ -179,7 +199,7 @@ Each skill folder 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)
+- Matriz de trazabilidad (Task <-> N)
 - Automation notes
 
 **Legacy migration**: `upgrade` Section 6 moves `automated/` and `manual/` subdirectories to `sprints/legacy-*` non-destructively.
@@ -194,7 +214,7 @@ Each skill folder contains:
 
 ```
 03-test-cases/
-├── README.md   ← explains optional/legacy status
+├── README.md   <- explains optional/legacy status
 └── TC-{ID}-{title}.md
 ```
 
@@ -212,10 +232,10 @@ Each skill folder contains:
 ```
 04-test-data/
 ├── README.md
-├── users.md         ← Test user definitions (roles, env var references, NOT passwords)
-├── fixtures/        ← Static data files (JSON/Markdown)
-├── factories/       ← Dynamic data generation patterns (Markdown or TS files)
-└── seeders/         ← DB/API seed scripts for complex test setup
+├── users.md         <- Test user definitions (roles, env var references, NOT passwords)
+├── fixtures/        <- Static data files (JSON/Markdown)
+├── factories/       <- Dynamic data generation patterns (Markdown or TS files)
+└── seeders/         <- DB/API seed scripts for complex test setup
 ```
 
 **Critical rules**:
@@ -228,14 +248,14 @@ Each skill folder contains:
 
 ## 05-test-execution/
 
-**Purpose**: Evidence of test runs — reports, results, and screenshots.
+**Purpose**: Evidence of test runs - reports, results, and screenshots.
 
 ```
 05-test-execution/
 ├── README.md
 ├── automated/
-│   ├── {YYYY-MM-DD_HH-MM-SS_desc}.md    ← Execution report (human-readable summary)
-│   └── test-results/                    ← Playwright output (gitignored if large)
+│   ├── {YYYY-MM-DD_HH-MM-SS_desc}.md    <- Execution report (human-readable summary)
+│   └── test-results/                    <- Playwright output (gitignored if large)
 │       └── .last-run.json
 └── manual/
     ├── exploratory/
@@ -271,8 +291,8 @@ Each skill folder contains:
 - `resolved/` - closed by fix or formal decision
 
 **Decision guide**:
-- ADO enabled → use ADO Work Items. `06-defects/` contains lightweight references only
-- ADO disabled → use this folder as primary defect tracker
+- ADO enabled -> use ADO Work Items. `06-defects/` contains lightweight references only
+- ADO disabled -> use this folder as primary defect tracker
 - Either way: `test.skip()` references a defect ID so the skip is traceable
 
 See `docs/generalization-decisions.md §7` for the full evaluation of this folder.
@@ -325,21 +345,21 @@ See `docs/generalization-decisions.md §7` for the full evaluation of this folde
 ```
 08-azure-integration/
 ├── README.md
-├── AGENT-ADO-INTEGRATION.md        ← Agent instructions for ADO operations
-├── PLAYWRIGHT-AZURE-REPORTER-PLAN.md ← Reporter setup and migration log
-├── module-registry.json            ← Module → spec path → ADO plan/suite IDs
-├── ado-ids-mapping-{project}.json  ← Complete TC → ADO WI ID registry
+├── AGENT-ADO-INTEGRATION.md        <- Agent instructions for ADO operations
+├── PLAYWRIGHT-AZURE-REPORTER-PLAN.md <- Reporter setup and migration log
+├── module-registry.json            <- Module -> spec path -> ADO plan/suite IDs
+├── ado-ids-mapping-{project}.json  <- Complete TC -> ADO WI ID registry
 ├── pipelines/
-│   └── azure-pipeline-qa.yml       ← CI/CD pipeline definition
+│   └── azure-pipeline-qa.yml       <- CI/CD pipeline definition
 └── scripts/
-    ├── inject-ado-ids.ps1          ← Injects [ID] prefix into spec files
-    ├── create-testplan-from-mapping.ps1 ← Creates ADO plan from mapping JSON
-    └── sync-ado-titles.ps1         ← Syncs spec titles with ADO TC titles
+    ├── inject-ado-ids.ps1          <- Injects [ID] prefix into spec files
+    ├── create-testplan-from-mapping.ps1 <- Creates ADO plan from mapping JSON
+    └── sync-ado-titles.ps1         <- Syncs spec titles with ADO TC titles
 ```
 
 ---
 
-## `qa/README.md` — The Living Index
+## `qa/README.md` - The Living Index
 
 The `qa/README.md` is the primary human-readable project status document. It should be updated whenever:
 - A new module is analyzed
@@ -352,46 +372,46 @@ Minimum contents:
 - 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`
+- **`## 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
+## `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
+- 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`
+- Does not repeat standing instructions already in `qa-framework.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.
+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
+## `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
+├── 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
+### `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}
+# Memory Index - {PROJECT_NAME}
 
 | File | Topic | When to load |
 |---|---|---|
@@ -403,7 +423,7 @@ The `INDEX.md` is the **gate** that the agent reads before loading any other mem
 **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
+- Never load all memory files unconditionally - always read `INDEX.md` first and select by relevance
 
 ---
 
@@ -414,4 +434,4 @@ Optionally, place `SESSION-SUMMARY-YYYY-MM-DD.md` at the `qa/` root after each m
 - Record any blockers encountered
 - Provide the starting point for the next session
 
-This is especially valuable for agents — a session summary provides continuity across multiple chat sessions.
+This is especially valuable for agents - a session summary provides continuity across multiple chat sessions.

package/docs/installation.md

@@ -13,7 +13,7 @@
 
 ---
 
-## Option A — npm install (recommended)
+## Option A - npm install (recommended)
 
 ```bash
 npm install --save-dev @keber/qa-framework
@@ -57,7 +57,7 @@ qa/
 
 ---
 
-## Option B — Clone or copy (no npm registry)
+## Option B - Clone or copy (no npm registry)
 
 ```bash
 # From your project root
@@ -69,7 +69,7 @@ node tools/qa-framework/scripts/cli.js init
 
 ---
 
-## Option C — Manual scaffold (advanced)
+## Option C - Manual scaffold (advanced)
 
 If you prefer to control exactly what gets created:
 
@@ -156,9 +156,44 @@ Edit `qa/qa-framework.config.json` (or `qa-framework.config.json` at project roo
 **Never** put `testPlanId`, `suiteId`, or `ADO_PAT` in the config file directly.  
 Use environment variables:
 
-- `ADO_PAT` — Personal Access Token
-- `ADO_PLAN_ID` — Test Plan ID (can also go in `module-registry.json`)
-- `ADO_SUITE_ID` — Suite ID
+- `ADO_PAT` - Personal Access Token
+
+#### Optional: ANALISIS/PLAN agent mode (Claude Code only)
+
+Gated by `integrations.azureDevOps.sprintCycle.enabled`. When `true`, `init`/`upgrade`
+generate six Claude Code subagents (`.claude/agents/qa-analisis.md`, `qa-plan.md`,
+`qa-asesoria.md`, `qa-reporte-ejecucion.md`, `qa-informe-resultados.md`,
+`qa-investigador.md`) for a sprint-centric manual testing
+workflow parallel to the 6-stage pipeline. See
+[docs/usage-with-agent.md](usage-with-agent.md) for details.
+
+```json
+{
+  "integrations": {
+    "azureDevOps": {
+      "enabled": true,
+      "sprintCycle": {
+        "enabled": true,
+        "sprintDurationDays": 8,
+        "manualTestingTimeboxDays": 2,
+        "dateFormat": "dd-mm-aaaa",
+        "timezone": "America/Santiago",
+        "approvalThresholdPercent": 85
+      }
+    }
+  }
+}
+```
+
+All `sprintCycle` fields are optional; omitted fields fall back to neutral framework
+defaults (8-day sprint, 2-day manual testing timebox, `dd-mm-aaaa`, `America/Santiago`,
+85% approval threshold over executed cases). Optional overrides under `conventions`:
+`decimalSeparator` (`","` or `"."`, otherwise derived from the locale) and
+`defectIdPrefix` (e.g. `"ACME"`, otherwise derived from `project.name`).
+`qa-investigador` gets Playwright MCP browser tools only for `parallelLanes.lanes[]`
+entries with an `mcpNamespace` (pattern `^mcp__[A-Za-z0-9_-]+__$`).
+- `ADO_PLAN_ID` - Test Plan ID (can also go in `module-registry.json`)
+- `ADO_SUITE_ID` - Suite ID
 
 ---
 
@@ -244,6 +279,6 @@ The `upgrade` command:
 1. Checks the current framework version in your project
 2. Shows a diff of changed template and instruction files
 3. Prompts before overwriting any file that has local modifications
-4. Never touches `01-specifications/`, `02-test-plans/`, `03-test-cases/`, `04-test-data/`, `05-test-execution/`, `06-defects/` — only framework-owned files are updated
+4. Never touches `01-specifications/`, `02-test-plans/`, `03-test-cases/`, `04-test-data/`, `05-test-execution/`, `06-defects/` - only framework-owned files are updated
 
 See `MIGRATION-NOTES.md` for version-specific migration instructions.