refacil-sdd-ai 4.0.1 → 4.0.3

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` | (`Stop` / `afterAgentResponse`) Notifica al LLM sobre migraciones pendientes al finalizar la primera respuesta; el agente ejecuta `/refacil:update` automaticamente |
+| `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` | `Stop` (Claude Code) / `afterAgentResponse` (Cursor) | Al finalizar la primera respuesta del agente, lee el flag de actualizacion pendiente. Si existe, inyecta la instruccion de ejecutar `/refacil:update` — el agente la ejecuta automaticamente y el usuario ve el resultado al final. 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 sin interaccion del usuario. `notify-update` en `Stop` se dispara al finalizar la primera respuesta del agente — la instruccion queda al final visible para el usuario y Claude la ejecuta automaticamente en el siguiente turno.
 
 ### Gate de review en el push
 

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] La metodologia fue actualizada (${fromLabel} → v${info.to}). ` +
+    'Ejecuta /refacil:update ahora para aplicar las migraciones pendientes e informa el resultado al usuario.',
+  );
+}
 
 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,20 @@ function installHooks(ideDir, projectRoot) {
     changed = true;
   }
 
+  // Claude Code usa "Stop"; Cursor usa "afterAgentResponse" (equivalente al fin de turno del agente)
+  const notifyEvent = ideDir === '.cursor' ? 'afterAgentResponse' : 'Stop';
+  if (!settings.hooks[notifyEvent]) settings.hooks[notifyEvent] = [];
+
+  const hasNotifyHook = settings.hooks[notifyEvent].some((h) => h._sdd_notify === true);
+  if (!hasNotifyHook) {
+    settings.hooks[notifyEvent].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 +101,15 @@ function uninstallHooks(ideDir, projectRoot) {
     if (settings.hooks.SessionStart.length === 0) delete settings.hooks.SessionStart;
   }
 
+  for (const notifyEvent of ['Stop', 'afterAgentResponse']) {
+    if (Array.isArray(settings.hooks[notifyEvent])) {
+      const original = settings.hooks[notifyEvent].length;
+      settings.hooks[notifyEvent] = settings.hooks[notifyEvent].filter((h) => h._sdd_notify !== true);
+      if (settings.hooks[notifyEvent].length !== original) changed = true;
+      if (settings.hooks[notifyEvent].length === 0) delete settings.hooks[notifyEvent];
+    }
+  }
+
   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.1",
+  "version": "4.0.3",
   "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/setup/SKILL.md

@@ -50,19 +50,42 @@ 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 de instalaciones anteriores. Después del init, elimina las carpetas sobrantes que no pertenezcan al conjunto requerido (`openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change`, `openspec-verify-change`):
+`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 required=new Set(['openspec-propose','openspec-explore','openspec-apply-change','openspec-archive-change','openspec-verify-change']);
+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-') && !required.has(d)){
+    if(d.startsWith('openspec-') && !requiredSkills.has(d)){
       fs.rmSync(path.join(base,d),{recursive:true,force:true});
-      console.log('Eliminada:',path.join(base,d));
+      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));
     }
   }
 }

package/skills/update/SKILL.md

@@ -17,7 +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-*` en `.claude/skills/` o `.cursor/skills/` que no estan en el conjunto requerido | Eliminar las sobrantes y reconfigurar OpenSpec |
+| 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.
 
@@ -72,12 +72,13 @@ Contexto completo del proyecto: ver `AGENTS.md`.
 Si no existe, ejecuta `/refacil:setup`.
 ```
 
-### Migracion 4 — Skills OpenSpec sobrantes
+### Migracion 4 — Skills y commands OpenSpec sobrantes
 
-Conjunto requerido: `openspec-propose`, `openspec-explore`, `openspec-apply-change`, `openspec-archive-change`, `openspec-verify-change`.
+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 las carpetas `openspec-*` presentes en `.claude/skills/` y `.cursor/skills/`.
-2. Identifica las sobrantes (las que no estan en el conjunto requerido).
+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 "
@@ -90,7 +91,7 @@ Conjunto requerido: `openspec-propose`, `openspec-explore`, `openspec-apply-chan
    fs.writeFileSync(p,JSON.stringify(c,null,2));
    "
    ```
-4. Elimina las carpetas sobrantes de `.claude/skills/` y `.cursor/skills/`.
+4. Elimina skills y commands sobrantes.
 5. Ejecuta `openspec init --tools claude,cursor` para dejar el estado limpio.
 
 ## Paso 4: Resumen