refacil-sdd-ai 4.0.0 → 4.0.2

package/README.md

@@ -71,9 +71,10 @@ npm uninstall -g refacil-sdd-ai
 
 | Comando | Descripcion |
 |---|---|
-| `refacil-sdd-ai check-update` | Verifica nueva version + sincroniza `compact-guidance` en AGENTS.md |
-| `refacil-sdd-ai check-review` | Bloquea `git push` si falta `.review-passed` en algun cambio activo |
-| `refacil-sdd-ai compact-bash` | Reescribe comandos Bash bare via `updatedInput` |
+| `refacil-sdd-ai check-update` | (`SessionStart`) Verifica nueva version, sincroniza skills y `compact-guidance` en AGENTS.md |
+| `refacil-sdd-ai notify-update` | (`UserPromptSubmit`) Notifica al LLM sobre migraciones pendientes en el primer mensaje del usuario |
+| `refacil-sdd-ai check-review` | (`PreToolUse`) Bloquea `git push` si falta `.review-passed` en algun cambio activo |
+| `refacil-sdd-ai compact-bash` | (`PreToolUse`) Reescribe comandos Bash bare via `updatedInput` |
 
 ### Control del rewrite de comandos (`compact-bash`)
 
@@ -232,11 +233,14 @@ Se instalan en `.claude/settings.json` **y** `.cursor/settings.json` durante `in
 
 | Hook | Evento | Que hace |
 |---|---|---|
-| `check-update` | `SessionStart` | Chequea nueva version en npm, la instala, y **sincroniza el bloque `compact-guidance`** en `AGENTS.md`. |
+| `check-update` | `SessionStart` | Chequea nueva version en npm, la instala, sincroniza skills y **sincroniza el bloque `compact-guidance`** en `AGENTS.md`. Si hubo actualizacion, escribe un flag de notificacion para el siguiente hook. |
+| `notify-update` | `UserPromptSubmit` | Lee el flag de actualizacion pendiente. Si existe, lo inyecta como `[ACCION REQUERIDA]` en el contexto del primer mensaje del usuario para que el LLM lo procese y ofrezca ejecutar `/refacil:update`. El flag se borra tras notificar. |
 | `compact-bash` | `PreToolUse` (Bash) | Reescribe silenciosamente comandos Bash bare via `updatedInput`. Sin turnos extra, sin que el IDE vea el cambio. Requiere Claude Code >= 2.1.89. |
 | `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y bloquea si falta `.review-passed` en algun cambio activo. |
 
-Los tres hooks se instalan en paralelo en `.claude/settings.json` (Claude Code) y `.cursor/settings.json` (Cursor) con la misma logica parametrica.
+Los cuatro hooks se instalan en `.claude/settings.json` (Claude Code) y `.cursor/settings.json` (Cursor) con la misma logica parametrica.
+
+> **Por que dos hooks para el update?** `SessionStart` hace el sync silencioso al abrir la sesion, pero el LLM no genera respuesta hasta que el usuario escribe algo. `notify-update` en `UserPromptSubmit` garantiza que la notificacion llegue pegada al primer mensaje real del usuario y no sea ignorada.
 
 ### Gate de review en el push
 
@@ -356,7 +360,7 @@ Bus local (WebSocket sobre `127.0.0.1`) para que los agentes de distintos repos
 
 **Observador puro** (0 tokens): `refacil-sdd-ai bus watch <session>` o `refacil-sdd-ai bus view` para la UI web.
 
-> **Diagramas, escenarios y pitch**: ver [`refacil-bus-diagrams.md`](./refacil-bus-diagrams.md) — incluye arquitectura, flujo con attend, flujo sin attend, tabla comparativa de impacto y guia de decision visual (Mermaid).
+> **Diagramas, escenarios y pitch**: ver `refacil-bus-diagrams.md` (incluido en el paquete) — incluye arquitectura, flujo con attend, flujo sin attend, tabla comparativa de impacto y guia de decision visual (Mermaid).
 >
 
 ### Limitaciones conocidas

package/bin/cli.js

@@ -29,7 +29,38 @@ const { syncIgnoreFiles } = require('../lib/ignore-files');
 const packageRoot = path.resolve(__dirname, '..');
 const projectRoot = process.cwd();
 
-// --- Check update (SessionStart hook) ---
+// --- check-update (SessionStart) + notify-update (UserPromptSubmit) ---
+
+function ideBaseDir(root) {
+  const claudeDir = path.join(root, '.claude');
+  const cursorDir = path.join(root, '.cursor');
+  return fs.existsSync(claudeDir) ? claudeDir : fs.existsSync(cursorDir) ? cursorDir : null;
+}
+
+function writePendingUpdateFlag(root, fromVersion, toVersion) {
+  const base = ideBaseDir(root);
+  if (!base) return;
+  try {
+    fs.writeFileSync(path.join(base, '.refacil-pending-update'), JSON.stringify({ from: fromVersion, to: toVersion }));
+  } catch (_) {}
+}
+
+function notifyUpdate() {
+  const base = ideBaseDir(projectRoot);
+  if (!base) return;
+  const flagPath = path.join(base, '.refacil-pending-update');
+  if (!fs.existsSync(flagPath)) return;
+
+  let info = {};
+  try { info = JSON.parse(fs.readFileSync(flagPath, 'utf8')); } catch (_) {}
+  try { fs.unlinkSync(flagPath); } catch (_) {}
+
+  const fromLabel = info.from ? `v${info.from}` : 'version desconocida';
+  console.log(
+    `[refacil-sdd-ai] ACCION REQUERIDA: La metodologia fue actualizada (${fromLabel} → v${info.to}). ` +
+    'Antes de responder al usuario, informa del cambio y ofrece ejecutar /refacil:update para aplicar las migraciones pendientes.',
+  );
+}
 
 function repoIsInitialized() {
   return (
@@ -65,9 +96,7 @@ function checkUpdate() {
   try {
     syncCompactGuidance(projectRoot, packageRoot);
   } catch (err) {
-    process.stderr.write(
-      `[refacil-sdd-ai] No se pudo sincronizar compact-guidance: ${err.message}\n`,
-    );
+    process.stderr.write(`[refacil-sdd-ai] No se pudo sincronizar compact-guidance: ${err.message}\n`);
   }
 
   const syncResult = syncRepoSkillsIfStale(localVersion);
@@ -77,10 +106,7 @@ function checkUpdate() {
       `[refacil-sdd-ai] Skills de este repo sincronizadas (${fromLabel} -> v${syncResult.to}). ` +
       'Reinicia la sesion de Claude Code o Cursor para detectar los cambios.',
     );
-    console.log(
-      '[refacil-sdd-ai] La metodologia fue actualizada. ' +
-      'Pregunta al usuario si desea aplicar las migraciones pendientes y, si confirma, ejecuta /refacil:update.',
-    );
+    writePendingUpdateFlag(projectRoot, syncResult.from, syncResult.to);
   } else if (syncResult && syncResult.failed) {
     console.log(
       `[refacil-sdd-ai] Skills de este repo estan desactualizadas respecto al paquete global (v${syncResult.to}) ` +
@@ -98,16 +124,8 @@ function checkUpdate() {
     if (!latest || latest === localVersion) return;
 
     try {
-      execSync('npm update -g refacil-sdd-ai', {
-        encoding: 'utf8',
-        timeout: 60000,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
-      execSync('refacil-sdd-ai update', {
-        encoding: 'utf8',
-        timeout: 30000,
-        stdio: ['pipe', 'pipe', 'pipe'],
-      });
+      execSync('npm update -g refacil-sdd-ai', { encoding: 'utf8', timeout: 60000, stdio: ['pipe', 'pipe', 'pipe'] });
+      execSync('refacil-sdd-ai update', { encoding: 'utf8', timeout: 30000, stdio: ['pipe', 'pipe', 'pipe'] });
       writeRepoVersion(projectRoot, latest);
       console.log(
         `[refacil-sdd-ai] La metodologia SDD-AI se actualizo automaticamente de v${localVersion} a v${latest}. Skills y hooks sincronizados.`,
@@ -327,8 +345,9 @@ function help() {
   Comandos:
     init          Instala skills en .claude/ y .cursor/, crea CLAUDE.md y .cursorrules
     update        Re-copia skills (para actualizar a nueva version del paquete)
-    check-update  Verifica si hay una version mas reciente en npm y sincroniza compact-guidance en AGENTS.md
-    check-review  Verifica que el review se haya completado (usado por hook PreToolUse)
+    check-update   Sincroniza skills y compact-guidance al inicio de sesion (hook SessionStart)
+    notify-update  Notifica al LLM sobre migraciones pendientes (hook UserPromptSubmit)
+    check-review   Verifica que el review se haya completado (usado por hook PreToolUse)
     compact-bash  Reescribe comandos Bash bare para reducir tokens (usado por hook PreToolUse)
     compact       Subcomandos del hook compact-bash:
                     compact stats      - Estadisticas completas (hook + ya-compacto) y ahorro estimado
@@ -380,6 +399,9 @@ switch (command) {
   case 'check-update':
     checkUpdate();
     break;
+  case 'notify-update':
+    notifyUpdate();
+    break;
   case 'check-review':
     checkReview();
     break;

package/lib/hooks.js

@@ -31,6 +31,18 @@ function installHooks(ideDir, projectRoot) {
     changed = true;
   }
 
+  if (!settings.hooks.UserPromptSubmit) settings.hooks.UserPromptSubmit = [];
+
+  const hasNotifyHook = settings.hooks.UserPromptSubmit.some((h) => h._sdd_notify === true);
+  if (!hasNotifyHook) {
+    settings.hooks.UserPromptSubmit.push({
+      _sdd_notify: true,
+      matcher: '',
+      hooks: [{ type: 'command', command: 'refacil-sdd-ai notify-update' }],
+    });
+    changed = true;
+  }
+
   if (!settings.hooks.PreToolUse) settings.hooks.PreToolUse = [];
 
   // compact-bash debe correr ANTES de check-review para que el rewrite sea visible
@@ -87,6 +99,15 @@ function uninstallHooks(ideDir, projectRoot) {
     if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
   }
 
+  if (Array.isArray(settings.hooks.UserPromptSubmit)) {
+    const original = settings.hooks.UserPromptSubmit.length;
+    settings.hooks.UserPromptSubmit = settings.hooks.UserPromptSubmit.filter(
+      (h) => h._sdd_notify !== true,
+    );
+    if (settings.hooks.UserPromptSubmit.length !== original) changed = true;
+    if (settings.hooks.UserPromptSubmit.length === 0) delete settings.hooks.UserPromptSubmit;
+  }
+
   if (Array.isArray(settings.hooks.PreToolUse)) {
     const original = settings.hooks.PreToolUse.length;
     settings.hooks.PreToolUse = settings.hooks.PreToolUse.filter(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "SDD-AI: Specification-Driven Development with AI — metodologia de desarrollo con IA usando OpenSpec, Claude Code y Cursor",
   "bin": {
     "refacil-sdd-ai": "./bin/cli.js"

package/skills/prereqs/OPENSPEC-DELTAS.md

@@ -8,7 +8,7 @@ Lee este archivo **ademas** de la skill `openspec-*` que indique el comando `ref
 
 - Respuestas al usuario y artefactos bajo `openspec/`: **español**; terminos tecnicos (API, REST, nombres de tipos, etc.) en **ingles**.
 
-## propose — `openspec-ff-change`
+## propose — `openspec-propose`
 
 - Criterios de aceptacion: formato **Dado / Cuando / Entonces**.
 - Incluir **criterios de rechazo** (edge cases) en specs.

package/skills/propose/SKILL.md

@@ -6,7 +6,7 @@ user-invocable: true
 
 # refacil:propose — Propuesta de Cambio
 
-Este comando envuelve la funcionalidad de OpenSpec fast-forward (ff) y agrega las convenciones del equipo.
+Este comando envuelve la funcionalidad de OpenSpec propose y agrega las convenciones del equipo.
 
 **Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
@@ -23,7 +23,7 @@ Si $ARGUMENTS ya es claro, no preguntes de nuevo.
 
 ### Paso 2: Delegar a OpenSpec ff (fast-forward)
 
-1. Lee `openspec-ff-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
+1. Lee `openspec-propose/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
 2. Lee `OPENSPEC-DELTAS.md` en la carpeta `refacil-prereqs` (misma ruta dual que en prereqs).
 3. Ejecuta la skill OpenSpec siguiendo sus instrucciones y aplicando los deltas Refacil para generar los artefactos (proposal, specs, design, tasks) en una sola pasada.
 

package/skills/setup/SKILL.md

@@ -16,17 +16,31 @@ Guia al desarrollador **paso a paso**. Tras cada paso, informa resultado; si fal
 
 ### Paso 2: OpenSpec
 
-`openspec --version 2>&1`. Si falla: ofrecer `npm install -g @fission-ai/openspec@latest`, re-verificar. Si sigue fallando: **troubleshooting.md**.
+```bash
+openspec --version 2>&1
+```
+
+Version minima requerida: **1.3.0**. Si falla o es inferior: `npm install -g @fission-ai/openspec@latest`, re-verificar. Si sigue fallando: **troubleshooting.md**.
 
-### Paso 3: Perfil OpenSpec
+### Paso 3: Configurar todos los workflows de OpenSpec
+
+`openspec config set workflows` no acepta arrays por CLI. La unica forma de configurar los workflows es editando el archivo de config directamente:
 
 ```bash
-openspec config set profile custom
-openspec config set workflows "explore,new,continue,apply,ff,sync,archive,bulk-archive,verify,onboard"
+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));
+console.log('Workflows configurados:',c.workflows.join(', '));
+"
 openspec config list
 ```
 
-Debe verse `profile: custom` y los 10 workflows.
+Debe verse `profile: custom` y exactamente estos 5 workflows: `propose`, `explore`, `apply`, `archive`, `verify` — los unicos que usan los comandos `refacil:*`.
 
 ### Paso 4: Init en el repo
 
@@ -36,6 +50,48 @@ openspec init --tools claude,cursor
 
 `openspec init` instala `opsx:*` en `.claude/` y `.cursor/`; convive con `refacil:*` — el equipo usa **refacil:*** como interfaz principal.
 
+`openspec init` no elimina skills ni commands de instalaciones anteriores. Después del init, ejecuta este script para limpiar todo lo sobrante:
+
+```bash
+node -e "
+const fs=require('fs');
+const path=require('path');
+const requiredSkills=new Set(['openspec-propose','openspec-explore','openspec-apply-change','openspec-archive-change','openspec-verify-change']);
+const requiredCmdsOpsx=new Set(['apply.md','archive.md','explore.md','propose.md','verify.md']);
+const requiredCmdsCursor=new Set(['opsx-apply.md','opsx-archive.md','opsx-explore.md','opsx-propose.md','opsx-verify.md']);
+// Skills sobrantes
+for(const base of ['.claude/skills','.cursor/skills']){
+  if(!fs.existsSync(base)) continue;
+  for(const d of fs.readdirSync(base)){
+    if(d.startsWith('openspec-') && !requiredSkills.has(d)){
+      fs.rmSync(path.join(base,d),{recursive:true,force:true});
+      console.log('Eliminada skill:',path.join(base,d));
+    }
+  }
+}
+// Commands sobrantes — .claude/commands/opsx/ (archivos .md)
+const claudeCmds='.claude/commands/opsx';
+if(fs.existsSync(claudeCmds)){
+  for(const f of fs.readdirSync(claudeCmds)){
+    if(f.endsWith('.md') && !requiredCmdsOpsx.has(f)){
+      fs.rmSync(path.join(claudeCmds,f),{force:true});
+      console.log('Eliminado command:',path.join(claudeCmds,f));
+    }
+  }
+}
+// Commands sobrantes — .cursor/commands/ (archivos opsx-*.md)
+const cursorCmds='.cursor/commands';
+if(fs.existsSync(cursorCmds)){
+  for(const f of fs.readdirSync(cursorCmds)){
+    if(f.startsWith('opsx-') && f.endsWith('.md') && !requiredCmdsCursor.has(f)){
+      fs.rmSync(path.join(cursorCmds,f),{force:true});
+      console.log('Eliminado command:',path.join(cursorCmds,f));
+    }
+  }
+}
+"
+```
+
 ### Paso 5: `openspec/config.yaml`
 
 Si no existe, crear con `language: spanish` (y comentario de terminos tecnicos en ingles). Si existe, asegurar `language: spanish`.
@@ -62,7 +118,35 @@ Un monorepo puede agregar `.agents/services.md`; una libreria puede combinar tes
 `AGENTS.md` es el **indice puro** — no contiene detalle de proyecto, solo:
 1. Una linea de descripcion del proyecto.
 2. Por cada archivo en `.agents/`: nombre del area + enlace relativo + cuando leer ese archivo (una frase).
-3. Bloque `compact-guidance` (auto-gestionado por `refacil-sdd-ai`, no editar).
+3. Seccion `## Metodología SDD-AI` con la tabla completa de comandos `refacil:*` — siempre en `AGENTS.md`, nunca en `.agents/`. Si ya existe, sobreescribirla con el contenido actualizado; si no existe, crearla.
+4. Bloque `compact-guidance` (auto-gestionado por `refacil-sdd-ai`, no editar).
+
+**Contenido obligatorio de `## Metodología SDD-AI`** (insertar literalmente, antes del bloque `compact-guidance`):
+
+```markdown
+## Metodología SDD-AI
+
+| Comando | Descripcion |
+|---------|-------------|
+| `/refacil:setup` | Instalar y configurar la metodologia en el repo |
+| `/refacil:guide` | Ver guia de flujo y elegir siguiente paso |
+| `/refacil:explore` | Explorar el codebase sin modificar archivos |
+| `/refacil:propose` | Crear propuesta de cambio (proposal, specs, design, tasks) |
+| `/refacil:apply` | Implementar las tasks de una propuesta aprobada |
+| `/refacil:test` | Ejecutar y revisar tests del cambio actual |
+| `/refacil:verify` | Verificar implementacion contra las specs |
+| `/refacil:review` | Auditoria de calidad del codigo implementado |
+| `/refacil:archive` | Archivar el cambio y sincronizar specs al historico |
+| `/refacil:up-code` | Actualizar codigo existente a patrones actuales |
+| `/refacil:bug` | Crear propuesta de fix para un bug detectado |
+| `/refacil:update` | Migrar documentacion al patron actual de la metodologia |
+| `/refacil:join` | Unirse al bus cross-repo (primer setup del servicio) |
+| `/refacil:say` | Enviar mensaje a otro agente via bus |
+| `/refacil:ask` | Hacer consulta a otro agente y esperar respuesta |
+| `/refacil:reply` | Responder a una consulta recibida via bus |
+| `/refacil:attend` | Atender y responder mensajes pendientes del bus |
+| `/refacil:inbox` | Ver mensajes pendientes en el bus |
+```
 
 **6.3 Fallback** — Si el analisis falla: crear `.agents/summary.md` con resumen minimo + tabla refacil + TODOs, y `AGENTS.md` como indice apuntando a ese unico archivo.
 
@@ -104,7 +188,7 @@ Si el usuario quiere personalizar exclusiones adicionales, puede editarlos direc
 
 ### Paso 8: Verificar skills
 
-- OpenSpec: 10 carpetas bajo `.claude/skills/` y `.cursor/skills/`: `openspec-apply-change`, `openspec-archive-change`, `openspec-bulk-archive-change`, `openspec-continue-change`, `openspec-explore`, `openspec-ff-change`, `openspec-new-change`, `openspec-onboard`, `openspec-sync-specs`, `openspec-verify-change`. Si falta alguna: sugerir `openspec init --tools claude,cursor` o `openspec config list`.
+- OpenSpec: 5 carpetas bajo `.claude/skills/` y `.cursor/skills/`: `openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change`, `openspec-verify-change`. Si falta alguna: re-ejecutar el Paso 3 y luego `openspec init --tools claude,cursor`.
 - Refacil: carpetas `refacil-*` en esas rutas. Si no: `refacil-sdd-ai init` + reiniciar sesion.
 
 ### Paso 9: Resumen final

package/skills/setup/troubleshooting.md

@@ -11,10 +11,16 @@ Consulta este archivo **solo** si un paso de setup falla. No forma parte del flu
 
 - OpenSpec exige **Node >= 20.19.0**. Actualiza Node y vuelve a intentar.
 
-## `openspec init` no crea todas las skills
+## `openspec init` no crea las 5 skills requeridas
 
-- Ejecuta `openspec config list` y confirma `profile: custom` y los 10 workflows del proceso principal de setup.
-- Repite `openspec init --tools claude,cursor` desde la raiz del repo.
+- Ejecuta `openspec config list` y confirma `profile: custom` y los 5 workflows: `propose, explore, apply, archive, verify`.
+- Si faltan workflows, repite el Paso 3 del setup (script `node -e "..."`) y luego `openspec init --tools claude,cursor` desde la raiz del repo.
+- Las skills esperadas son: `openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change`, `openspec-verify-change`.
+
+## `openspec config set workflows` falla con error de array
+
+- El CLI de OpenSpec no acepta arrays via `config set`. Usa el script `node -e "..."` del Paso 3 para editar el JSON de configuracion directamente.
+- La ruta del archivo de config se obtiene con `openspec config path`.
 
 ## Falta `openspec/config.yaml`
 

package/skills/update/SKILL.md

@@ -17,6 +17,7 @@ Evalua cada condicion y marca si aplica:
 | 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 | Existen skills `openspec-*` o commands `opsx-*` fuera del conjunto requerido en `.claude/` o `.cursor/` | Eliminar los sobrantes y reconfigurar OpenSpec |
 
 Si ninguna condicion aplica: informar al usuario que todo esta al dia y salir sin cambios.
 
@@ -31,9 +32,10 @@ Ejecutar solo las migraciones marcadas en el Paso 1.
 ### Migracion 1 — AGENTS.md → `.agents/` + indice
 
 1. Lee el contenido completo de `AGENTS.md`.
-2. Identifica y separa los **bloques gestionados** — NO deben moverse a `.agents/`:
+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.
@@ -43,9 +45,10 @@ Ejecutar solo las migraciones marcadas en el Paso 1.
      - `.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 preservando los bloques gestionados al final:
+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.
 
@@ -69,6 +72,28 @@ 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: Resumen
 
 Informar que archivos se crearon o modificaron. Mencionar que el bloque `compact-guidance` se sincronizara automaticamente en el proximo SessionStart.