refacil-sdd-ai 4.2.4 → 4.4.0

package/skills/test/testing-patterns.md

@@ -1,63 +1,63 @@
-# Patrones de Testing — Referencia
-
-> **NOTA**: Este archivo es una referencia generica. Los tests generados deben seguir
-> los patrones reales del proyecto (detectados automaticamente). Si el proyecto ya tiene
-> tests, esos patrones tienen prioridad sobre los de este archivo.
-
-## Estructura de archivos de test
-
-La ubicacion de los tests depende del proyecto. Patrones comunes:
-
-```
-# Mismo directorio (comun en JS/TS, Go, Rust)
-archivo.ts          → archivo.spec.ts / archivo.test.ts
-archivo.go          → archivo_test.go
-
-# Directorio separado (comun en Java, Python, algunos JS/TS)
-src/servicio.java   → test/servicio_test.java
-src/modulo.py       → tests/test_modulo.py
-```
-
-## Principios universales
-
-### Arrange-Act-Assert (AAA)
-```
-// Arrange — preparar datos y mocks
-// Act — ejecutar la operacion
-// Assert — verificar resultado
-```
-
-### Naming conventions
-```
-# Formato recomendado (adaptar al idioma/framework):
-should [verbo] [resultado] when [condicion]
-
-# Ejemplos:
-"should return product when valid id is provided"
-"should throw error when input is empty"
-"should update status when payment is confirmed"
-```
-
-## Anti-patrones a evitar
-
-- NO testear propiedades/metodos privados directamente
-- NO testear implementacion interna (orden de llamadas) a menos que sea critico
-- NO crear tests sin assertions
-- NO crear tests que dependan del orden de ejecucion
-- NO mockear todo — solo los limites del sistema (DB, APIs externas, filesystem)
-- NO crear tests fragiles que se rompen con cambios cosmeticos
-- NO duplicar la logica del codigo en el test (el test debe verificar comportamiento, no reimplementar)
-
-## Mocks y Stubs
-
-Mockear solo lo que esta fuera del control del test:
-- Llamadas a bases de datos
-- APIs externas / servicios HTTP
-- Sistema de archivos (si aplica)
-- Colas de mensajes
-- Loggers (cuando interfieren con output)
-
-No mockear:
-- Funciones puras del propio modulo
-- DTOs, mappers, utilidades sin side effects
-- Constantes o configuracion estatica
+# Testing Patterns — Reference
+
+> **NOTE**: This file is a generic reference. Generated tests must follow
+> the actual project patterns (detected automatically). If the project already has
+> tests, those patterns take priority over the ones in this file.
+
+## Test file structure
+
+The location of tests depends on the project. Common patterns:
+
+```
+# Same directory (common in JS/TS, Go, Rust)
+file.ts          → file.spec.ts / file.test.ts
+file.go          → file_test.go
+
+# Separate directory (common in Java, Python, some JS/TS)
+src/service.java   → test/service_test.java
+src/module.py      → tests/test_module.py
+```
+
+## Universal principles
+
+### Arrange-Act-Assert (AAA)
+```
+// Arrange — prepare data and mocks
+// Act — execute the operation
+// Assert — verify the result
+```
+
+### Naming conventions
+```
+# Recommended format (adapt to language/framework):
+should [verb] [result] when [condition]
+
+# Examples:
+"should return product when valid id is provided"
+"should throw error when input is empty"
+"should update status when payment is confirmed"
+```
+
+## Anti-patterns to avoid
+
+- Do NOT test private properties/methods directly
+- Do NOT test internal implementation (call order) unless critical
+- Do NOT create tests without assertions
+- Do NOT create tests that depend on execution order
+- Do NOT mock everything — only system boundaries (DB, external APIs, filesystem)
+- Do NOT create brittle tests that break with cosmetic changes
+- Do NOT duplicate the code logic in the test (the test must verify behavior, not re-implement)
+
+## Mocks and Stubs
+
+Mock only what is outside the test's control:
+- Database calls
+- External APIs / HTTP services
+- File system (if applicable)
+- Message queues
+- Loggers (when they interfere with output)
+
+Do not mock:
+- Pure functions of the module itself
+- DTOs, mappers, utilities without side effects
+- Constants or static configuration

package/skills/up-code/SKILL.md

@@ -1,108 +1,108 @@
----
-name: refacil:up-code
-description: Subir codigo y crear PR para integracion — git add, commit, push y PR a la rama destino
-user-invocable: true
----
-
-# refacil:up-code — Integrar Codigo y Publicar Cambios
-
-Sube los cambios al repositorio remoto y genera el PR para integracion.
-Aplica la politica de ramas e integracion definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md` (sin excepciones).
-
-**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md` (politica de ramas aplica sin excepciones).
-
-## Instrucciones
-
-### Paso 1: Detectar y validar rama actual
-
-Ejecuta `git branch --show-current` para obtener el nombre de la rama.
-
-- Si la rama actual es protegida (segun `METHODOLOGY-CONTRACT.md`), **detente** e informa al usuario:
-  ```
-  No se puede subir codigo desde una rama protegida ([nombre]).
-  La validacion de rama se hace en /refacil:apply o /refacil:bug antes de escribir codigo.
-  Cambia a tu rama de trabajo (feature/*, fix/*, etc.) y vuelve a ejecutar /refacil:up-code.
-  ```
-- Si la rama es de trabajo (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continua.
-
-### Paso 2: Verificar review (obligatorio)
-
-Antes de continuar, verifica si hay cambios activos en `openspec/changes/` (excluir carpeta `archive/`).
-
-Si hay cambios activos:
-1. Para cada carpeta activa, verifica si existe el archivo `.review-passed` (marcador oculto: **`METHODOLOGY-CONTRACT.md` §8** — no concluyas por `ls` sin `-a`).
-2. Si **todas** tienen `.review-passed` → continua al paso 3.
-3. Si hay **una sola** carpeta sin `.review-passed`:
-   - Informa al usuario cual es.
-   - Ejecuta `/refacil:review <nombre-cambio>` automaticamente sobre ese cambio.
-   - Si el review aprueba (crea `.review-passed`) → continua al paso 3.
-   - Si el review requiere correcciones → detente e informa los hallazgos al usuario.
-4. Si hay **multiples** carpetas sin `.review-passed`:
-   - Deten el flujo y pide al usuario seleccionar explicitamente que cambio quiere subir.
-   - Ejecuta `/refacil:review <nombre-cambio-seleccionado>` solo para ese cambio.
-   - No ejecutes review automatico masivo en este caso.
-
-**IMPORTANTE**: `/refacil:review` verifica internamente si `.review-passed` existe y si hay cambios posteriores. Solo re-ejecuta si detecta cambios nuevos despues del ultimo review aprobado.
-
-Si no hay carpeta `openspec/changes/` o no hay cambios activos → continua al paso 3 (no hay nada que revisar).
-
-### Paso 3: Verificar cambios pendientes
-
-Ejecuta `git status` para verificar si hay cambios para subir.
-
-- Si no hay cambios pendientes ni commits sin push, informa al usuario y detente.
-- Si hay cambios sin commitear, continua al paso 4.
-- Si solo hay commits sin push (nada que commitear), salta directo al paso 5.
-
-### Paso 4: Commit de cambios
-
-1. Ejecuta `git status --short` y muestra al usuario la lista de archivos detectados.
-2. Pide confirmacion explicita antes de stagear todo.
-3. Si el usuario confirma stage global, usa `git add -A`.
-4. Si el usuario pide stage parcial, agrega solo las rutas indicadas.
-5. Si el usuario proporciono un mensaje como argumento (`$ARGUMENTS`), usalo como mensaje del commit.
-6. Si no se proporciono mensaje, genera uno descriptivo basado en los cambios detectados con `git diff --staged --stat`.
-7. Ejecuta `git commit -m "[mensaje]"`.
-
-### Paso 5: Push a remoto
-
-Ejecuta `git push -u origin [rama-actual]` para subir los cambios.
-
-### Paso 6: Confirmar y crear PR
-
-1. Muestra el resumen del push:
-```
-=== Codigo subido ===
- Rama: [nombre-rama]
- Commit: [hash-corto] [mensaje]
- Remote: origin/[nombre-rama]
-```
-
-2. **Pregunta al usuario** a que rama quiere crear el PR. Sugiere `testing` como destino por defecto:
-   ```
-   A que rama quieres crear el PR? (recomendado: testing)
-   ```
-
-   Si el usuario indica una rama distinta a `testing`, verifica que exista en el remoto con `git branch -r | grep <rama-indicada>` antes de generar el link. Si no existe, informa al usuario y pide que confirme o corrija el nombre.
-
-3. Obtén la URL del repositorio remoto con `git remote get-url origin` y determina el hosting para generar el link correcto:
-   - **GitHub** (url contiene `github.com`): `https://github.com/[owner]/[repo]/compare/[rama-destino]...[rama-actual]?expand=1`
-   - **Bitbucket** (url contiene `bitbucket.org`): `https://bitbucket.org/[workspace]/[repo]/pull-requests/new?source=[rama-actual]&dest=[rama-destino]`
-   - Si no se puede determinar el hosting, muestra ambos formatos para que el usuario elija.
-   - Nota: para URLs SSH (`git@github.com:owner/repo.git` o `git@bitbucket.org:workspace/repo.git`), extrae owner/workspace y repo del path tras el `:`.
-
-4. Muestra el link al usuario y recomienda PR a `testing`:
-```
- Crea tu PR aqui: [link]
-
- Tip: Se recomienda PR a testing para habilitar pruebas integradas
- antes de promover a otras ramas protegidas.
-```
-
-**Este es el paso terminal del flujo SDD.** No preguntes por siguiente skill — el ciclo se cierra aqui. Aplica la regla de paso terminal de `METHODOLOGY-CONTRACT.md §5`.
-
-## Reglas
-
-- Respetar estrictamente la politica de ramas protegidas e integracion por PR del `METHODOLOGY-CONTRACT.md`
-- Si la rama actual es protegida, **detener** — la validacion/cambio de rama se hace en `/refacil:apply` o `/refacil:bug`, no aqui
-- No forzar push (--force) a menos que el usuario lo pida explicitamente
+---
+name: refacil:up-code
+description: Push code and create PR for integration — git add, commit, push, and PR to the target branch
+user-invocable: true
+---
+
+# refacil:up-code — Integrate Code and Publish Changes
+
+Pushes changes to the remote repository and generates the PR for integration.
+Applies the branch and integration policy defined in `refacil-prereqs/METHODOLOGY-CONTRACT.md` (no exceptions).
+
+**Prerequisites**: `agents` profile from `refacil-prereqs/SKILL.md` + rules from `METHODOLOGY-CONTRACT.md` (branch policy applies without exceptions).
+
+## Instructions
+
+### Step 1: Detect and validate current branch
+
+Run `git branch --show-current` to get the branch name.
+
+- If the current branch is protected (according to `METHODOLOGY-CONTRACT.md`), **stop** and inform the user:
+  ```
+  Cannot push code from a protected branch ([name]).
+  Branch validation is done in /refacil:apply or /refacil:bug before writing code.
+  Switch to your working branch (feature/*, fix/*, etc.) and run /refacil:up-code again.
+  ```
+- If the branch is a working branch (`feature/*`, `fix/*`, `hotfix/*`, `refactor/*`, etc.), continue.
+
+### Step 2: Verify review (mandatory)
+
+Before continuing, verify if there are active changes in `refacil-sdd/changes/` (exclude the `archive/` folder).
+
+If there are active changes:
+1. For each active folder, verify if the `.review-passed` file exists (hidden marker: **`METHODOLOGY-CONTRACT.md` §8** — do not conclude from `ls` without `-a`).
+2. If **all** have `.review-passed` → continue to step 3.
+3. If there is **one single** folder without `.review-passed`:
+   - Inform the user which one.
+   - Automatically run `/refacil:review <change-name>` on that change.
+   - If the review approves (creates `.review-passed`) → continue to step 3.
+   - If the review requires corrections → stop and inform the user of the findings.
+4. If there are **multiple** folders without `.review-passed`:
+   - Stop the flow and ask the user to explicitly select which change to push.
+   - Run `/refacil:review <selected-change-name>` only for that change.
+   - Do not run automatic bulk review in this case.
+
+**IMPORTANT**: `/refacil:review` internally verifies if `.review-passed` exists and if there are changes after it. It only re-runs if it detects new changes after the last approved review.
+
+If there is no `refacil-sdd/changes/` folder or no active changes → continue to step 3 (nothing to review).
+
+### Step 3: Verify pending changes
+
+Run `git status` to verify if there are changes to push.
+
+- If there are no pending changes or unpushed commits, inform the user and stop.
+- If there are uncommitted changes, continue to step 4.
+- If there are only unpushed commits (nothing to commit), jump directly to step 5.
+
+### Step 4: Commit changes
+
+1. Run `git status --short` and show the user the list of detected files.
+2. Ask for explicit confirmation before staging everything.
+3. If the user confirms global staging, use `git add -A`.
+4. If the user requests partial staging, add only the indicated paths.
+5. If the user provided a message as argument (`$ARGUMENTS`), use it as the commit message.
+6. If no message was provided, generate a descriptive one based on the detected changes with `git diff --staged --stat`.
+7. Run `git commit -m "[message]"`.
+
+### Step 5: Push to remote
+
+Run `git push -u origin [current-branch]` to push the changes.
+
+### Step 6: Confirm and create PR
+
+1. Show the push summary:
+```
+=== Code pushed ===
+ Branch: [branch-name]
+ Commit: [short-hash] [message]
+ Remote: origin/[branch-name]
+```
+
+2. **Ask the user** which branch they want to create the PR to. Suggest `testing` as the default target:
+   ```
+   Which branch do you want to create the PR to? (recommended: testing)
+   ```
+
+   If the user indicates a different branch than `testing`, verify it exists on the remote with `git branch -r | grep <indicated-branch>` before generating the link. If it does not exist, inform the user and ask them to confirm or correct the name.
+
+3. Get the remote repository URL with `git remote get-url origin` and determine the hosting to generate the correct link:
+   - **GitHub** (url contains `github.com`): `https://github.com/[owner]/[repo]/compare/[target-branch]...[current-branch]?expand=1`
+   - **Bitbucket** (url contains `bitbucket.org`): `https://bitbucket.org/[workspace]/[repo]/pull-requests/new?source=[current-branch]&dest=[target-branch]`
+   - If hosting cannot be determined, show both formats for the user to choose.
+   - Note: for SSH URLs (`git@github.com:owner/repo.git` or `git@bitbucket.org:workspace/repo.git`), extract owner/workspace and repo from the path after `:`.
+
+4. Show the link to the user and recommend PR to `testing`:
+```
+ Create your PR here: [link]
+
+ Tip: PR to testing is recommended to enable integrated testing
+ before promoting to other protected branches.
+```
+
+**This is the terminal step of the SDD flow.** Do not ask for a next skill — the cycle closes here. Apply the terminal step rule from `METHODOLOGY-CONTRACT.md §5`.
+
+## Rules
+
+- Strictly respect the protected branch and PR integration policy from `METHODOLOGY-CONTRACT.md`
+- If the current branch is protected, **stop** — branch validation/change is done in `/refacil:apply` or `/refacil:bug`, not here
+- Do not force push (--force) unless the user explicitly asks for it

package/skills/update/SKILL.md

@@ -1,132 +1,109 @@
----
-name: refacil:update
-description: Detectar y aplicar migraciones pendientes de la metodologia SDD-AI al proyecto actual
-user-invocable: true
----
-
-# refacil:update — Migraciones de la Metodologia
-
-Detecta el estado actual del repo y aplica solo lo que este pendiente. No repite pasos de instalacion (OpenSpec, hooks, skills).
-
-El hook `notify-update` usa el **mismo motor** que este comando; no re-evalues a mano el repo para decidir si hay trabajo.
-
-## Paso 1: Validar con el CLI (obligatorio)
-
-En la **raiz del repo** (donde esta `AGENTS.md` o `.claude/`), ejecuta con `Bash`:
-
-```bash
-refacil-sdd-ai migration-pending
-```
-
-- **Codigo de salida 0**: no hay migraciones de metodologia pendientes → informa al usuario que todo esta al dia respecto a este criterio y **termina** (sin tocar archivos).
-- **Codigo de salida 1**: hay al menos una razon listada en stdout → continua al Paso 2.
-
-Opcional para parseo estable: `refacil-sdd-ai migration-pending --json` → objeto `{ "pending": bool, "reasons": string[] }`.
-
-No sustituyas este paso por inspeccion manual del arbol salvo que el comando falle (error de entorno); en ese caso documenta el error y pide reintentar.
-
-### Referencia (mapeo razon → accion en Paso 3)
-
-La implementacion vive en `lib/methodology-migration-pending.js` del paquete; la tabla resume lo que detecta:
-
-| # | Condicion (resumen) | Migracion en Paso 3 |
-|---|---|---|
-| 1 | `AGENTS.md` existe y no existe carpeta `.agents/` | Reestructurar en `.agents/` + reescribir como indice |
-| 2 | `CLAUDE.md` tiene mas de 5 lineas o no apunta a `AGENTS.md` | Reemplazar por indice minimo |
-| 3 | `.cursorrules` tiene mas de 5 lineas o no apunta a `AGENTS.md` | Reemplazar por indice minimo |
-| 4 | Skills `openspec-*` o commands `opsx-*` fuera del conjunto requerido | Eliminar sobrantes y reconfigurar OpenSpec |
-
-## Paso 2: Confirmar con el usuario
-
-Mostrar al usuario las mismas lineas que imprimio `migration-pending` (o el array `reasons` del JSON) y pedir confirmacion antes de aplicar cualquier cambio.
-
-## Paso 3: Aplicar migraciones confirmadas
-
-Ejecutar solo las migraciones que correspondan a las razones detectadas (ver tabla de referencia arriba).
-
-### Migracion 1 — AGENTS.md → `.agents/` + indice
-
-1. Lee el contenido completo de `AGENTS.md`.
-2. Identifica y separa el contenido que NO debe moverse a `.agents/`:
-   - Bloque `compact-guidance`: entre `<!-- refacil-sdd-ai:compact-guidance:start -->` y `<!-- refacil-sdd-ai:compact-guidance:end -->`
-   - Bloque de presentacion del bus: entre `<!-- refacil-bus:presentation:start -->` y `<!-- refacil-bus:presentation:end -->`
-   - Seccion `## Metodología SDD-AI`: tabla de comandos `refacil:*` — siempre permanece en `AGENTS.md`. Si existe, sobreescribirla con la tabla actualizada (ver Paso 6.2 de `refacil:setup`); si no existe, crearla.
-3. Crea la carpeta `.agents/`.
-4. Distribuye el contenido de proyecto (todo excepto los bloques gestionados) en archivos por area. Reglas:
-   - **`.agents/summary.md` es siempre obligatorio** — descripcion del proyecto, tabla mini de stack, scripts esenciales, reglas criticas condensadas. Si el AGENTS.md original no tiene resumen claro, sintetizalo a partir del contenido disponible.
-   - Los demas archivos se crean **solo si hay contenido relevante que redistribuir**. No crear archivos vacios:
-     - `.agents/architecture.md` — modulos, servicios, flujos principales, patrones clave.
-     - `.agents/stack.md` — dependencias, variables de entorno, bases de datos, integraciones.
-     - `.agents/testing.md` — estrategia de tests, comandos, convenciones, fixtures.
-     - `.agents/commands.md` — comandos de desarrollo, alias, scripts de CI/CD.
-   - Adaptar al tipo de proyecto: un monorepo puede necesitar `.agents/services.md`; una libreria simple puede combinar testing y stack en un solo archivo. Usar el mismo criterio que `/refacil:setup`.
-5. Reescribe `AGENTS.md` como indice puro en este orden:
-   - Primera linea: descripcion breve del proyecto.
-   - Por cada archivo en `.agents/`: nombre del area + enlace relativo + cuando leerlo (una frase).
-   - Seccion `## Metodología SDD-AI` con la tabla actualizada de comandos `refacil:*` (ver Paso 6.2 de `refacil:setup` para el contenido exacto).
-   - Bloques gestionados que ya existian (compact-guidance, bus presentation) al final, intactos.
-   - Si no existian, el bloque compact-guidance se re-inyectara automaticamente en el proximo SessionStart.
-
-### Migracion 2 y 3 — CLAUDE.md / .cursorrules → indice minimo
-
-Sobreescribir con exactamente este contenido:
-
-**CLAUDE.md:**
-```
-# CLAUDE.md
-
-Contexto completo del proyecto: ver `AGENTS.md`.
-Si no existe, ejecuta `/refacil:setup`.
-```
-
-**`.cursorrules`:**
-```
-# Cursor Rules
-
-Contexto completo del proyecto: ver `AGENTS.md`.
-Si no existe, ejecuta `/refacil:setup`.
-```
-
-### Migracion 4 — Skills y commands OpenSpec sobrantes
-
-Conjunto requerido de skills: `openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change`, `openspec-verify-change`.
-Conjunto requerido de commands: `.claude/commands/opsx/` → `apply.md`, `archive.md`, `explore.md`, `propose.md`, `verify.md`; `.cursor/commands/` → `opsx-apply.md`, `opsx-archive.md`, `opsx-explore.md`, `opsx-propose.md`, `opsx-verify.md`.
-
-1. Detecta skills `openspec-*` en `.claude/skills/` y `.cursor/skills/` fuera del conjunto requerido.
-2. Detecta commands `opsx-*.md` en `.cursor/commands/` y archivos `.md` en `.claude/commands/opsx/` fuera del conjunto requerido.
-3. Reconfigura OpenSpec con solo los 5 workflows necesarios:
-   ```bash
-   node -e "
-   const fs=require('fs');
-   const {execSync}=require('child_process');
-   const p=execSync('openspec config path',{encoding:'utf8'}).trim();
-   const c=JSON.parse(fs.readFileSync(p,'utf8'));
-   c.profile='custom';
-   c.workflows=['propose','explore','apply','archive','verify'];
-   fs.writeFileSync(p,JSON.stringify(c,null,2));
-   "
-   ```
-4. Elimina skills y commands sobrantes.
-5. Ejecuta `openspec init --tools claude,cursor` para dejar el estado limpio.
-
-## Paso 4: Limpiar flag de actualizacion pendiente
-
-Tras migrar, elimina el flag en la raiz del repo si sigue existiendo:
-
-```bash
-rm -f .refacil-pending-update
-```
-
-Si no hubo cambios (Paso 1 dio exit 0), el flag obsoleto suele borrarse solo al proximo `check-update` (SessionStart) o al ejecutar `refacil-sdd-ai migration-pending` con exit 0; el `rm` manual solo hace falta si aplicaste migraciones a mano o quedo un vestigio.
-
-## Paso 5: Resumen
-
-Informar que archivos se crearon o modificaron. Mencionar que el bloque `compact-guidance` se sincronizara automaticamente en el proximo SessionStart.
-
-## Reglas
-
-- **Deteccion**: confiar en `refacil-sdd-ai migration-pending` (mismo criterio que `check-update` / `notify-update`).
-- Solo aplica lo que este pendiente — no toca archivos que ya cumplen el patron.
-- No inventa contenido: distribuye lo que ya existe en AGENTS.md sin agregar ni eliminar informacion.
-- No ejecuta pasos de OpenSpec, hooks ni instalacion de skills.
-- Extensible: nuevas reglas de deteccion se agregan en el paquete (`methodology-migration-pending.js`); esta skill actualiza la tabla de referencia y los pasos de aplicacion cuando cambie el contrato.
+---
+name: refacil:update
+description: Detect and apply pending migrations of the SDD-AI methodology to the current project
+user-invocable: true
+---
+
+# refacil:update — Methodology Migrations
+
+Detects the current repo state and applies only what is pending. Does not repeat full setup (hooks/skills install, `/refacil:setup` steps).
+
+The `notify-update` hook uses the **same engine** as this command; do not manually re-evaluate the repo to decide if there is work to do.
+
+## Step 1: Validate with the CLI (mandatory)
+
+In the **repo root** (where `AGENTS.md` or `.claude/` is), run with `Bash`:
+
+```bash
+refacil-sdd-ai migration-pending
+```
+
+- **Exit code 0**: no pending methodology migrations → inform the user that everything is up to date regarding this criterion and **finish** (without touching files).
+- **Exit code 1**: at least one reason listed in stdout → continue to Step 2.
+
+Optional for stable parsing: `refacil-sdd-ai migration-pending --json` → object `{ "pending": bool, "reasons": string[] }`.
+
+Do not substitute this step with manual tree inspection unless the command fails (environment error); in that case document the error and ask to retry.
+
+### Reference (reason → action mapping in Step 3)
+
+The implementation lives in `lib/methodology-migration-pending.js` of the package; the table summarizes what it detects:
+
+| # | Condition (summary) | Migration in Step 3 |
+|---|---|---|
+| 1 | `AGENTS.md` exists and `.agents/` folder does not | Restructure into `.agents/` + rewrite as index |
+| 2 | `CLAUDE.md` has more than 5 lines or does not point to `AGENTS.md` | Replace with minimal index |
+| 3 | `.cursorrules` has more than 5 lines or does not point to `AGENTS.md` | Replace with minimal index |
+
+## Step 2: Confirm with the user
+
+Show the user the same lines printed by `migration-pending` (or the `reasons` array from the JSON) and ask for confirmation before applying any changes.
+
+## Step 3: Apply confirmed migrations
+
+Run only the migrations that correspond to the detected reasons (see reference table above).
+
+### Migration 1 — AGENTS.md → `.agents/` + index
+
+1. Read the full content of `AGENTS.md`.
+2. Identify and separate content that must NOT move to `.agents/`:
+   - `compact-guidance` block: between `<!-- refacil-sdd-ai:compact-guidance:start -->` and `<!-- refacil-sdd-ai:compact-guidance:end -->`
+   - Bus presentation block: between `<!-- refacil-bus:presentation:start -->` and `<!-- refacil-bus:presentation:end -->`
+   - Section `## SDD-AI Methodology`: table of `refacil:*` commands — always stays in `AGENTS.md`. If it exists, overwrite it with the updated table (see Step 6.2 of `refacil:setup`); if not, create it.
+3. Create the `.agents/` folder.
+4. Distribute the project content (everything except managed blocks) into files by area. Rules:
+   - **`.agents/summary.md` is always mandatory** — project description, mini stack table, essential scripts, critical rules condensed. If the original AGENTS.md does not have a clear summary, synthesize it from the available content.
+   - Other files are created **only if there is relevant content to redistribute**. Do not create empty files:
+     - `.agents/architecture.md` — modules, services, main flows, key patterns.
+     - `.agents/stack.md` — dependencies, environment variables, databases, integrations.
+     - `.agents/testing.md` — testing strategy, commands, conventions, fixtures.
+     - `.agents/commands.md` — development commands, aliases, CI/CD scripts.
+   - Adapt to the project type: a monorepo may need `.agents/services.md`; a simple library may combine testing and stack in one file. Use the same criterion as `/refacil:setup`.
+5. Rewrite `AGENTS.md` as a pure index in this order:
+   - First line: brief project description.
+   - For each file in `.agents/`: area name + relative link + when to read it (one sentence).
+   - Section `## SDD-AI Methodology` with the updated `refacil:*` command table (see Step 6.2 of `refacil:setup` for the exact content).
+   - Managed blocks that already existed (compact-guidance, bus presentation) at the end, intact.
+   - If they did not exist, the compact-guidance block will be re-injected automatically at the next SessionStart.
+
+### Migration 2 and 3 — CLAUDE.md / .cursorrules → minimal index
+
+Overwrite with exactly this content:
+
+**CLAUDE.md:**
+```
+# CLAUDE.md
+
+Full project context: see `AGENTS.md`.
+If it does not exist, run `/refacil:setup`.
+```
+
+**`.cursorrules`:**
+```
+# Cursor Rules
+
+Full project context: see `AGENTS.md`.
+If it does not exist, run `/refacil:setup`.
+```
+
+## Step 4: Clear the pending update flag
+
+After migrating, delete the flag in the repo root if it still exists:
+
+```bash
+rm -f .refacil-pending-update
+```
+
+If there were no changes (Step 1 gave exit 0), the obsolete flag usually clears itself at the next `check-update` (SessionStart) or when running `refacil-sdd-ai migration-pending` with exit 0; the manual `rm` is only needed if you applied migrations manually or there is a leftover.
+
+## Step 5: Summary
+
+Report which files were created or modified. Mention that the `compact-guidance` block will be synced automatically at the next SessionStart.
+
+## Rules
+
+- **Detection**: trust `refacil-sdd-ai migration-pending` (same criterion as `check-update` / `notify-update`).
+- Only apply what is pending — do not touch files that already meet the pattern.
+- Do not invent content: distribute what already exists in AGENTS.md without adding or removing information.
+- Does not re-run `refacil-sdd-ai init`, package hooks installation, or `/refacil:setup`-style scaffolding.
+- Extensible: new detection rules are added in the package (`methodology-migration-pending.js`); this skill updates the reference table and application steps when the contract changes.