refacil-sdd-ai 2.2.0 → 2.4.0

package/README.md

@@ -97,13 +97,15 @@ Para mantener trazabilidad y calidad sin pasos innecesarios:
 2. `/refacil:apply`
 3. `/refacil:test`
 4. `/refacil:verify`
-5. `/refacil:review` (automatico si no se ejecuto — ver [Hooks automaticos](#hooks-automaticos))
+5. `/refacil:review` (si lo omites, `/refacil:up-code` lo dispara antes del push)
 6. `/refacil:archive`
 7. `/refacil:up-code`
 
-Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
+Si es bugfix, inicia con `/refacil:bug` (ya genera tests de regresion internamente) y continua con `/refacil:review` → `/refacil:archive` → `/refacil:up-code`.
 
-> **Nota**: `/refacil:up-code` verifica automaticamente que el review se haya completado. Si no se ejecuto `/refacil:review`, lo lanza automaticamente antes del push como medida de seguridad.
+> **Nota — dos capas independientes de chequeo de review**:
+> - `/refacil:up-code` detecta si falta `.review-passed` y **ejecuta `/refacil:review` automaticamente** antes del push.
+> - El hook `check-review` (en `.claude/settings.json`) intercepta tambien `git push` manuales y **bloquea** la operacion si falta `.review-passed`. El hook NO invoca skills por si mismo — solo bloquea y emite instrucciones para ejecutar `/refacil:review` manualmente.
 >
 
 ## Flujos de trabajo
@@ -117,7 +119,7 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 /refacil:test
 /refacil:verify
 # → Si hay correcciones: verify pregunta si aplicarlas automaticamente
-# → Si aprueba: aplica fixes y re-verifica (max 2 rondas)
+# → Si aprueba: aplica fixes y re-verifica (maximo 2 rondas de correccion automatica)
 /refacil:review
 /refacil:archive
 /refacil:up-code
@@ -147,7 +149,7 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 >
 > **Importante**: `/refacil:archive` requiere review aprobado (`.review-passed`). Si no existe, bloquea el archivado. Para bugs, el archive no delega a OpenSpec — hace el archivado manual y documenta el bug en `openspec/specs/` como spec individual en formato OpenSpec estandar, con `review.yaml` separado.
 >
-> En cambios regulares (feature/mejora) que se archivan con OpenSpec, Refacil tambien persiste la metadata del `.review-passed` en `review.yaml` dentro de cada spec afectado (o en `openspec/specs/review-metadata.yaml` si no hay mapeo preciso).
+> En cambios regulares (feature/mejora) que se archivan con OpenSpec, Refacil **extrae los campos** de `.review-passed` (JSON) y los persiste como `review.yaml` dentro de cada spec afectado (o en `openspec/specs/review-metadata.yaml` si no hay mapeo preciso). El archivo `.review-passed` original no se copia: solo su contenido convertido a YAML.
 
 ### Explorar codigo
 
@@ -155,6 +157,143 @@ Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar con `/refacil:
 /refacil:explore "que quiero entender"
 ```
 
+## Diagrama de flujo completo
+
+Vista unica del ciclo de vida de un cambio — desde la necesidad hasta el PR integrado.
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│              INICIO: Necesidad de cambio                        │
+└────────────────────────────────┬────────────────────────────────┘
+                                 │
+                                 ▼
+                    ┌────────────────────────┐
+                    │  ¿Repo configurado?    │
+                    └───┬────────────────┬───┘
+                      NO│                │SI
+                        ▼                │
+              ┌──────────────────┐       │
+              │ refacil-sdd-ai   │       │
+              │ init             │       │
+              │ /refacil:setup   │       │
+              └────────┬─────────┘       │
+                       └────────┬────────┘
+                                ▼
+                    ┌────────────────────────┐
+                    │   ¿Que tipo de tarea?  │
+                    └───┬────────┬───────┬───┘
+                        │        │       │
+              ┌─────────┘        │       └─────────┐
+              ▼                  ▼                 ▼
+     ┌────────────────┐  ┌──────────────┐  ┌──────────────┐
+     │ FEATURE NUEVO  │  │     BUG      │  │  EXPLORAR    │
+     └───────┬────────┘  └──────┬───────┘  └──────┬───────┘
+             │                  │                 │
+             ▼                  ▼                 ▼
+    ┌─────────────────┐ ┌──────────────┐ ┌─────────────────┐
+    │/refacil:propose │ │/refacil:bug  │ │/refacil:explore │
+    │                 │ │              │ │                 │
+    │ Genera:         │ │ Investiga +  │ │ Analiza codigo  │
+    │ • proposal.md   │ │ fix + test   │ │ sin modificar   │
+    │ • specs/        │ │ de regresion │ │                 │
+    │ • design.md     │ │ (interno)    │ │     (FIN)       │
+    │ • tasks.md      │ │              │ └─────────────────┘
+    └────────┬────────┘ └──────┬───────┘
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ REVISAR         │        │
+    │ artefactos      │        │
+    │ (aprobacion     │        │
+    │  humana)        │        │
+    └────────┬────────┘        │
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ /refacil:apply  │        │
+    │ Implementa      │        │
+    │ tasks           │        │
+    └────────┬────────┘        │
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ /refacil:test   │        │
+    │ Tests unitarios │        │
+    │ + edge cases    │        │
+    └────────┬────────┘        │
+             │                 │
+             ▼                 │
+    ┌─────────────────┐        │
+    │ /refacil:verify │        │
+    │ ¿Cumple specs?  │        │
+    │ (max 2 rondas   │        │
+    │  autofix)       │        │
+    └────────┬────────┘        │
+             │                 │
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │ /refacil:review │
+             │ Checklist       │──► genera .review-passed
+             │ calidad         │    (JSON con veredicto)
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │/refacil:archive │
+             │ Mueve a archive/│
+             │ Sincroniza specs│
+             │ (bug → fix-*/   │
+             │  spec OpenSpec) │
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │/refacil:up-code │
+             │ commit + push   │
+             │ + PR            │
+             └────────┬────────┘
+                      ▼
+             ┌─────────────────┐
+             │   PR creado     │
+             │     (FIN)       │
+             └─────────────────┘
+```
+
+### Gate de review en el push
+
+Vista del mecanismo de dos capas que protege `git push`:
+
+```
+                ┌──────────────────────────────┐
+                │ Dev ejecuta /refacil:up-code │
+                │       o git push manual      │
+                └────────────────┬─────────────┘
+                                 │
+          ┌──────────────────────┴──────────────────────┐
+          │ Via /refacil:up-code                        │ git push directo
+          ▼                                             ▼
+┌─────────────────────────┐                ┌───────────────────────────┐
+│ up-code detecta         │                │ Hook check-review          │
+│ .review-passed faltante │                │ (PreToolUse en Bash)       │
+│                         │                │                            │
+│ INVOCA /refacil:review  │                │ Verifica .review-passed    │
+│ automaticamente         │                │ en openspec/changes/*      │
+└────────────┬────────────┘                └────────────┬───────────────┘
+             │                                          │
+             ▼                                          ▼
+      ┌──────────────┐                         ┌─────────────────┐
+      │ Review OK?   │                         │ Falta alguno?   │
+      └──┬────────┬──┘                         └──┬───────────┬──┘
+       SI│      NO│                              SI│         NO│
+         ▼        ▼                                ▼           ▼
+   ┌─────────┐ ┌────────────┐              ┌─────────────┐ ┌────────┐
+   │ push OK │ │ informa    │              │ block +     │ │ allow  │
+   │         │ │ correccion │              │ instruccion │ │ push   │
+   │         │ │ no pushea  │              │ a ejecutar  │ │        │
+   │         │ │            │              │ /refacil:   │ │        │
+   │         │ │            │              │ review      │ │        │
+   └─────────┘ └────────────┘              └─────────────┘ └────────┘
+```
+
 ## Reglas metodologicas transversales
 
 Para mantener consistencia entre todas las skills, el paquete define un contrato metodologico unico en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
@@ -188,22 +327,36 @@ El paquete instala hooks en `.claude/settings.json` durante `init` y `update`:
 
 | Hook | Evento | Que hace |
 |------|--------|----------|
-| `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente |
-| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, ejecuta `/refacil:review` automaticamente |
+| `check-update` | `SessionStart` | Verifica si hay nueva version del paquete en npm y la instala automaticamente. Tambien **sincroniza el bloque `compact-guidance`** en `AGENTS.md` (ver [Eficiencia de tokens](#eficiencia-de-tokens-bloque-auto-gestionado-en-agentsmd)). |
+| `check-review` | `PreToolUse` (Bash) | Intercepta `git push` y verifica que exista `.review-passed` en cada cambio activo de `openspec/changes/`. Si falta, **bloquea el push** y emite instrucciones para ejecutar `/refacil:review`. El hook no invoca skills por si mismo. |
 
 #### Flujo del hook de review
 
+El hook unicamente decide `allow` o `block`. La ejecucion automatica de `/refacil:review` la realiza `/refacil:up-code`, no el hook.
+
 ```
-/refacil:up-code (o git push manual)
-  → Hook check-review se dispara
-  → Busca carpetas en openspec/changes/ (excluye archive/)
-  → ¿Todas tienen .review-passed?
-      SI → permite el push
-      NO y hay 1 pendiente → bloquea y ejecuta /refacil:review <cambio> automaticamente
-            → Si APROBADO: crea .review-passed, reintenta push
-            → Si REQUIERE CORRECCIONES: informa al usuario, no pushea
-      NO y hay multiples pendientes → bloquea y pide seleccionar cambio explicito
-            → luego ejecutar /refacil:review <cambio-seleccionado>
+git push (manual o via /refacil:up-code)
+  │
+  ▼
+Hook check-review se dispara
+  │
+  ▼
+Busca carpetas activas en openspec/changes/ (excluye archive/)
+  │
+  ▼
+¿Todas tienen .review-passed?
+  │
+  ├─ SI ──► allow → el push procede
+  │
+  └─ NO ──► block → emite mensaje instructivo:
+             • 1 pendiente   → sugiere "/refacil:review <cambio>"
+             • N pendientes  → lista cambios y pide seleccionar uno
+
+Capa adicional cuando se usa /refacil:up-code:
+  /refacil:up-code detecta el faltante ANTES de llamar a git push,
+  invoca /refacil:review y solo entonces intenta el push.
+    • Si el review APRUEBA      → genera .review-passed → push procede
+    • Si requiere CORRECCIONES  → informa al usuario, no pushea
 ```
 
 #### Evidencia de review
@@ -225,6 +378,43 @@ openspec/changes/fix-session-timeout-redis/
 
 El archivo `.review-passed` contiene: veredicto, fecha, resumen, cantidad de hallazgos y si hubo blockers.
 
+### Eficiencia de tokens (bloque auto-gestionado en AGENTS.md)
+
+La metodologia SDD-AI genera consumo elevado de contexto (artefactos, specs, prompts de skills). Para compensarlo, `refacil-sdd-ai` mantiene un bloque de guia de eficiencia de tokens dentro de `AGENTS.md` que instruye a la IA sobre como pedir salidas compactas (Read con offset/limit, `git log --oneline`, tests solo con failures, etc.).
+
+**Caracteristicas**:
+- Delimitado por marcadores HTML: `<!-- refacil-sdd-ai:compact-guidance:start -->` y `<!-- refacil-sdd-ai:compact-guidance:end -->`
+- Fuente de verdad: `templates/compact-guidance.md` dentro del paquete
+- Se sincroniza automaticamente en tres momentos:
+  1. `refacil-sdd-ai init` (al instalar)
+  2. `refacil-sdd-ai update` (al actualizar manualmente)
+  3. Hook `check-update` en cada `SessionStart` (garantiza que repos ya instalados reciban las guias nuevas sin intervencion manual)
+- Si `AGENTS.md` aun no existe (el usuario no ha corrido `/refacil:setup`), la sincronizacion no hace nada — no se crea el archivo a espaldas del usuario
+- `refacil-sdd-ai clean` remueve el bloque de forma limpia
+
+> **IMPORTANTE**: No edites manualmente el contenido entre los marcadores. Cualquier cambio se sobrescribira en la proxima sesion. Si tienes sugerencias sobre reglas de eficiencia, proponlas al paquete (`templates/compact-guidance.md`).
+
+**Flujo del refresh automatico**:
+
+```
+Nueva sesion de Claude Code
+  │
+  ▼
+Hook SessionStart → ejecuta "refacil-sdd-ai check-update"
+  │
+  ├─► syncCompactGuidance()
+  │     │
+  │     ├─ AGENTS.md no existe → skip (sin ruido)
+  │     ├─ sin marcadores      → append del bloque al final
+  │     ├─ con marcadores      → reemplaza contenido entre ellos
+  │     └─ contenido identico  → no-op (no ensucia git status)
+  │
+  └─► chequeo de version npm
+        │
+        └─ si hay version nueva → npm update -g + refacil-sdd-ai update
+                                  (que vuelve a sincronizar el bloque)
+```
+
 ## Como funciona
 
 1. **`refacil-sdd-ai init`** copia las skills a `.claude/skills/` y `.cursor/skills/`, crea `CLAUDE.md` + `.cursorrules`, y configura hooks automaticos en `.claude/settings.json`
@@ -240,6 +430,7 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 
 /refacil:setup               →  OpenSpec instalado
                                  AGENTS.md generado (analisis automatico del repo)
+                                 + bloque compact-guidance inyectado automaticamente
 
 /refacil:propose             →  Artefactos en openspec/changes/
 /refacil:apply               →  Codigo implementado
@@ -258,10 +449,11 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 .claude/skills/refacil-*/    # Claude Code (refacil-prereqs incluye OPENSPEC-DELTAS.md)
 .claude/settings.json        # Hooks automaticos (check-update + check-review)
 .cursor/skills/refacil-*/    # Cursor — copia equivalente
-.../refacil-setup/           # troubleshooting.md si falla install/PATH
+.claude/skills/refacil-setup/troubleshooting.md  # guia incluida en refacil-setup si falla install/PATH
 CLAUDE.md                    # Claude Code — apunta a AGENTS.md
 .cursorrules                 # Cursor — apunta a AGENTS.md
 AGENTS.md                    # Generado por /refacil:setup (NO por el CLI)
+                             # Incluye bloque compact-guidance auto-gestionado por el hook SessionStart
 openspec/                    # Generado por /refacil:setup via OpenSpec
 ```
 

package/bin/cli.js

@@ -2,6 +2,10 @@
 
 const fs = require('fs');
 const path = require('path');
+const {
+  syncCompactGuidance,
+  removeCompactGuidance,
+} = require('../lib/compact-guidance');
 
 const SKILLS = [
   'setup',
@@ -64,44 +68,47 @@ function extractSddSection(templateContent) {
   return templateContent.substring(idx);
 }
 
-function createClaudeMd() {
-  const dest = path.join(projectRoot, 'CLAUDE.md');
-  const template = fs.readFileSync(path.join(packageRoot, 'templates', 'claude-md.md'), 'utf8');
+function readMethodologyGuide() {
+  return fs.readFileSync(
+    path.join(packageRoot, 'templates', 'methodology-guide.md'),
+    'utf8',
+  );
+}
 
-  if (fs.existsSync(dest)) {
-    const existing = fs.readFileSync(dest, 'utf8');
+function writeGuideFile(destPath, header, label) {
+  const guide = readMethodologyGuide();
+  const content = `# ${header}\n\n${guide}`;
+
+  if (fs.existsSync(destPath)) {
+    const existing = fs.readFileSync(destPath, 'utf8');
     if (existing.includes(SDD_SECTION_MARKER)) {
-      console.log('  CLAUDE.md ya tiene la seccion SDD-AI. Sin cambios.');
+      console.log(`  ${label} ya tiene la seccion SDD-AI. Sin cambios.`);
       return false;
     }
-    const sddSection = extractSddSection(template);
-    fs.writeFileSync(dest, existing.trimEnd() + '\n\n' + sddSection + '\n');
-    console.log('  CLAUDE.md existente — seccion SDD-AI agregada al final.');
+    const sddSection = extractSddSection(guide);
+    fs.writeFileSync(destPath, existing.trimEnd() + '\n\n' + sddSection + '\n');
+    console.log(`  ${label} existente — seccion SDD-AI agregada al final.`);
     return true;
   }
 
-  fs.writeFileSync(dest, template);
+  fs.writeFileSync(destPath, content);
   return true;
 }
 
-function createCursorRules() {
-  const dest = path.join(projectRoot, '.cursorrules');
-  const template = fs.readFileSync(path.join(packageRoot, 'templates', 'cursorrules.md'), 'utf8');
-
-  if (fs.existsSync(dest)) {
-    const existing = fs.readFileSync(dest, 'utf8');
-    if (existing.includes(SDD_SECTION_MARKER)) {
-      console.log('  .cursorrules ya tiene la seccion SDD-AI. Sin cambios.');
-      return false;
-    }
-    const sddSection = extractSddSection(template);
-    fs.writeFileSync(dest, existing.trimEnd() + '\n\n' + sddSection + '\n');
-    console.log('  .cursorrules existente — seccion SDD-AI agregada al final.');
-    return true;
-  }
+function createClaudeMd() {
+  return writeGuideFile(
+    path.join(projectRoot, 'CLAUDE.md'),
+    'CLAUDE.md',
+    'CLAUDE.md',
+  );
+}
 
-  fs.writeFileSync(dest, template);
-  return true;
+function createCursorRules() {
+  return writeGuideFile(
+    path.join(projectRoot, '.cursorrules'),
+    'Cursor Rules',
+    '.cursorrules',
+  );
 }
 
 function removeSkills() {
@@ -245,6 +252,15 @@ function checkUpdate() {
   const { execSync } = require('child_process');
   const localVersion = require(path.join(packageRoot, 'package.json')).version;
 
+  // Always ensure AGENTS.md has current compact-guidance block (silent unless error)
+  try {
+    syncCompactGuidance(projectRoot, packageRoot);
+  } catch (err) {
+    process.stderr.write(
+      `[refacil-sdd-ai] No se pudo sincronizar compact-guidance: ${err.message}\n`,
+    );
+  }
+
   try {
     const latest = execSync('npm view refacil-sdd-ai version', {
       encoding: 'utf8',
@@ -319,8 +335,7 @@ function checkReview() {
     const reason =
       missing.length === 1
         ? `[refacil-sdd-ai] Review pendiente para: ${names}. ` +
-          'Ejecuta /refacil:review automaticamente ahora sobre ese cambio pendiente. ' +
-          'Informa al usuario que el review se esta ejecutando automaticamente antes de subir el codigo. ' +
+          'Deten el push y ejecuta /refacil:review sobre ese cambio antes de subir codigo. ' +
           'Si el review aprueba, reintenta el git push. ' +
           'Si el review requiere correcciones, informa los hallazgos al usuario y NO reintentar el push.'
         : `[refacil-sdd-ai] Hay multiples cambios sin review aprobado: ${names}. ` +
@@ -366,6 +381,18 @@ function init() {
     console.log('  Hook check-update agregado a .claude/settings.json');
   }
 
+  // Sync compact-guidance block in AGENTS.md (if it exists)
+  try {
+    const result = syncCompactGuidance(projectRoot, packageRoot);
+    if (result.status === 'appended') {
+      console.log('  Bloque compact-guidance agregado a AGENTS.md');
+    } else if (result.status === 'replaced') {
+      console.log('  Bloque compact-guidance actualizado en AGENTS.md');
+    }
+  } catch (err) {
+    console.error(`  Advertencia: no se pudo sincronizar compact-guidance: ${err.message}`);
+  }
+
   console.log('\n  Siguientes pasos:\n');
   console.log('  1. REINICIA tu sesion de Claude Code o Cursor');
   console.log('     (las skills nuevas no se detectan hasta reiniciar)\n');
@@ -386,6 +413,18 @@ function update() {
     console.log('  Hook check-update agregado a .claude/settings.json');
   }
 
+  // Sync compact-guidance block in AGENTS.md
+  try {
+    const result = syncCompactGuidance(projectRoot, packageRoot);
+    if (result.status === 'appended') {
+      console.log('  Bloque compact-guidance agregado a AGENTS.md');
+    } else if (result.status === 'replaced') {
+      console.log('  Bloque compact-guidance actualizado en AGENTS.md');
+    }
+  } catch (err) {
+    console.error(`  Advertencia: no se pudo sincronizar compact-guidance: ${err.message}`);
+  }
+
   console.log('\n  REINICIA tu sesion de Claude Code o Cursor para aplicar los cambios.\n');
 }
 
@@ -398,6 +437,17 @@ function clean() {
   } else {
     console.log('  No se encontraron hooks SDD-AI para remover.');
   }
+
+  // Remove compact-guidance block from AGENTS.md if present
+  try {
+    const result = removeCompactGuidance(projectRoot);
+    if (result.status === 'removed') {
+      console.log('  Bloque compact-guidance removido de AGENTS.md');
+    }
+  } catch (err) {
+    console.error(`  Advertencia: no se pudo limpiar compact-guidance: ${err.message}`);
+  }
+
   console.log('  AGENTS.md, CLAUDE.md y .cursorrules no fueron eliminados.');
   console.log('\n  Nota: Los comandos opsx:* de OpenSpec no se eliminan.');
   console.log('  Para eliminar OpenSpec: rm -rf openspec/ .claude/commands/opsx .cursor/commands/opsx\n');
@@ -410,7 +460,7 @@ 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
+    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)
     clean         Elimina skills y remueve hooks SDD-AI de .claude/settings.json
     help          Muestra esta ayuda

package/lib/compact-guidance.js

@@ -0,0 +1,77 @@
+const fs = require('fs');
+const path = require('path');
+
+const MARKER_START = '<!-- refacil-sdd-ai:compact-guidance:start -->';
+const MARKER_END = '<!-- refacil-sdd-ai:compact-guidance:end -->';
+
+function readTemplate(packageRoot) {
+  const tplPath = path.join(packageRoot, 'templates', 'compact-guidance.md');
+  return fs.readFileSync(tplPath, 'utf8').trimEnd();
+}
+
+function buildBlock(templateContent) {
+  return `${MARKER_START}\n${templateContent}\n${MARKER_END}`;
+}
+
+function syncCompactGuidance(projectRoot, packageRoot) {
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    return { status: 'skipped-no-agents-md' };
+  }
+
+  const template = readTemplate(packageRoot);
+  const block = buildBlock(template);
+  const existing = fs.readFileSync(agentsPath, 'utf8');
+
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+
+  let next;
+  let action;
+
+  if (startIdx === -1 || endIdx === -1) {
+    next = existing.trimEnd() + '\n\n' + block + '\n';
+    action = 'appended';
+  } else {
+    const before = existing.substring(0, startIdx);
+    const after = existing.substring(endIdx + MARKER_END.length);
+    next = before + block + after;
+    action = 'replaced';
+  }
+
+  if (next === existing) {
+    return { status: 'unchanged' };
+  }
+
+  fs.writeFileSync(agentsPath, next);
+  return { status: action };
+}
+
+function removeCompactGuidance(projectRoot) {
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    return { status: 'skipped-no-agents-md' };
+  }
+
+  const existing = fs.readFileSync(agentsPath, 'utf8');
+  const startIdx = existing.indexOf(MARKER_START);
+  const endIdx = existing.indexOf(MARKER_END);
+
+  if (startIdx === -1 || endIdx === -1) {
+    return { status: 'not-present' };
+  }
+
+  const before = existing.substring(0, startIdx).trimEnd();
+  const after = existing.substring(endIdx + MARKER_END.length);
+  const next = (before + '\n' + after.replace(/^\s+/, '')).trimEnd() + '\n';
+
+  fs.writeFileSync(agentsPath, next);
+  return { status: 'removed' };
+}
+
+module.exports = {
+  syncCompactGuidance,
+  removeCompactGuidance,
+  MARKER_START,
+  MARKER_END,
+};

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "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"
   },
   "files": [
     "bin/",
+    "lib/",
     "skills/",
     "templates/",
     "config/",

package/skills/apply/SKILL.md

@@ -8,10 +8,7 @@ user-invocable: true
 
 Este comando envuelve la funcionalidad de OpenSpec apply y agrega las convenciones del equipo.
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `openspec`** antes de continuar.
-Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del flujo.
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
 ## Instrucciones
 
@@ -79,7 +76,6 @@ Al terminar la implementacion de OpenSpec, agrega este resumen:
 
 ## Reglas
 
-- NUNCA implementar codigo sin proposal, design, tasks y **especificacion** (`specs.md` y/o `specs/**/*.md` segun la tabla del Paso 0)
 - NUNCA generar artefactos SDD desde este comando — eso es responsabilidad exclusiva de `/refacil:propose`
-- SIEMPRE leer los artefactos completos antes de escribir codigo
+- Antes de implementar, cumplir las precondiciones del Paso 0 (artefactos completos) y del Paso 1 (rama de trabajo valida)
 - Si `openspec/changes/` no tiene cambios activos o estan incompletos, informar y redirigir a `/refacil:propose`

package/skills/archive/SKILL.md

@@ -8,10 +8,7 @@ user-invocable: true
 
 Este comando envuelve la funcionalidad de OpenSpec archive (que internamente llama a sync-specs) y agrega verificaciones previas del equipo.
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `openspec`** antes de continuar.
-Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del flujo.
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
 ## Instrucciones
 

package/skills/bug/SKILL.md

@@ -8,10 +8,7 @@ user-invocable: true
 
 Eres un asistente especializado en investigacion y correccion de bugs. Guias al desarrollador por un flujo estructurado paso a paso.
 
-## Contexto
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `agents`** antes de continuar.
-Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del flujo.
+**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
 ## Instrucciones
 
@@ -29,52 +26,22 @@ Este flujo crea evidencia en `openspec/changes/`. Antes de continuar:
 
 ### Paso 1: Describir el bug
 
-Preguntale al usuario (si no lo proporciono en $ARGUMENTS):
-
-1. **Que esta pasando?** — Comportamiento actual (el error)
-2. **Que deberia pasar?** — Comportamiento esperado
-3. **Pasos para reproducir** — Como llegar al error
-4. **Evidencia** — Logs, screenshots, stack traces (pedir que los peguen)
-5. **Desde cuando ocurre?** — Siempre, desde un deploy, desde un cambio especifico
-6. **Severidad** — Critico (bloquea produccion), Alto, Medio, Bajo
-
-### Paso 2: Investigar la causa raiz
-
-Con la informacion del paso 1:
+Si `$ARGUMENTS` no los trae, pregunta al usuario: comportamiento actual, esperado, pasos de reproduccion, evidencia (logs/stack traces), cuando empezo a ocurrir, severidad (Critico/Alto/Medio/Bajo).
 
-1. **Buscar en el codebase**:
-   - Busca las funciones/archivos mencionados en los logs o stack traces
-   - Busca el flujo de datos del escenario que falla
-   - Revisa commits recientes si el bug es nuevo (`git log --oneline -20`)
+### Paso 2: Investigar causa raiz
 
-2. **Trazar el flujo**:
-   - Desde el punto de entrada (controller/endpoint) hasta donde falla
-   - Identifica cada componente en la cadena
-   - Busca donde se rompe la cadena
-
-3. **Formular hipotesis**:
-   - Presenta al usuario 1-3 hipotesis de causa raiz
-   - Para cada una, muestra el archivo y linea sospechosa
-   - Pide al usuario que confirme o descarte
+- Busca en codebase los simbolos/archivos de logs o stack traces.
+- Traza el flujo desde entrada (controller/endpoint) hasta el punto de falla.
+- Revisa commits recientes si el bug es nuevo: `git log --oneline -20`.
+- Presenta al usuario 1-3 hipotesis con archivo y linea sospechosa; pide que confirme o descarte.
 
 ### Paso 3: Diagnosticar
 
-Una vez confirmada la hipotesis:
-
-1. **Confirmar la causa raiz**: Muestra el codigo exacto que causa el bug
-2. **Explicar por que falla**: Que condicion o caso no esta manejado
-3. **Evaluar impacto**: Que mas podria estar afectado
+Con la hipotesis confirmada: muestra el codigo exacto que falla, explica que condicion no se maneja, evalua impacto en otras zonas.
 
 ### Paso 4: Proponer correccion
 
-Presenta la correccion propuesta:
-
-1. **Cambio minimo**: La correccion mas pequeña posible que resuelve el bug
-2. **Archivos a modificar**: Lista con descripcion del cambio
-3. **Riesgos**: Que podria romperse con el fix
-4. **Alternativas**: Si hay mas de una forma de corregirlo
-
-Espera aprobacion del usuario antes de implementar.
+Presenta: cambio minimo, archivos a modificar, riesgos, alternativas (si existen). Espera aprobacion antes de implementar.
 
 ### Paso 5: Validar rama de trabajo (antes de escribir codigo)
 

package/skills/explore/SKILL.md

@@ -8,9 +8,7 @@ user-invocable: true
 
 Este comando envuelve la funcionalidad de OpenSpec explore y agrega contexto del proyecto.
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `openspec`** antes de continuar (incluye el uso continuo de `AGENTS.md` durante la exploracion, segun ese archivo).
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` — usa `AGENTS.md` como contexto activo durante toda la exploracion.
 
 ## Instrucciones
 

package/skills/prereqs/SKILL.md

@@ -4,39 +4,30 @@ description: Referencia interna — prerequisitos SDD-AI compartidos por el rest
 user-invocable: false
 ---
 
-# Prerequisitos SDD-AI (centralizado)
+# Prerequisitos SDD-AI
 
-La metodologia SDD-AI es **la misma** en **Claude Code** y **Cursor**: `refacil-sdd-ai init` instala copias equivalentes bajo `.claude/skills/refacil-*` y `.cursor/skills/refacil-*`. Usa la ruta del directorio que corresponda al IDE que tengas abierto.
+Metodologia identica en Claude Code (`.claude/skills/refacil-*`) y Cursor (`.cursor/skills/refacil-*`). Usa la ruta del IDE abierto.
 
-Las demas skills `refacil:*` remiten aqui para no duplicar instrucciones. **Lee esta skill cuando otra skill indique un perfil** y ejecuta los pasos en orden; si uno falla, **detente** y muestra al usuario el mensaje indicado.
-Ademas, lee y aplica `METHODOLOGY-CONTRACT.md` (misma carpeta) para reglas transversales: estados del flujo, politica de ramas, tests multi-stack y modo de salida.
+Reglas transversales (estados, ramas, tests, salida): `METHODOLOGY-CONTRACT.md` en esta misma carpeta.
 
-## Perfil `openspec` (OpenSpec + repo + AGENTS.md)
+## Perfil `openspec`
 
-Usar cuando la skill diga: *Aplica el perfil `openspec`.*
+Una skill pide este perfil cuando usa OpenSpec y necesita `AGENTS.md`. Estas validaciones son obligatorias en cada ejecucion de skill que declare este perfil.
 
-1. **OpenSpec instalado**: Ejecuta `openspec --version 2>&1`. Si el comando falla o no se reconoce, informa al usuario: "OpenSpec no esta instalado. Ejecuta `/refacil:setup` para instalarlo y configurar el repositorio." y **detente**.
+1. Verifica comando OpenSpec: `openspec --version 2>&1`. Si falla: *"OpenSpec no esta instalado o no esta en PATH. Ejecuta `/refacil:setup`"* y **detente**.
+2. Verifica `openspec/` en la raiz del repo. Si falta: *"OpenSpec no esta inicializado en este repo. Ejecuta `/refacil:setup`"* y **detente**.
+3. Lee `AGENTS.md` de la raiz. Si falta: *"No se encontro AGENTS.md. Ejecuta `/refacil:setup`"* y **detente**.
+4. Si un comando de OpenSpec falla despues, consulta `.claude/skills/refacil-setup/troubleshooting.md`.
+5. Si `AGENTS.md` incluye bloque `compact-guidance`, aplica esas reglas de eficiencia de tokens en toda la ejecucion.
 
-2. **OpenSpec inicializado**: Verifica que exista la carpeta `openspec/` en la raiz del proyecto. Si no existe, informa al usuario: "OpenSpec no esta inicializado en este repositorio. Ejecuta `/refacil:setup` para configurarlo." y **detente**.
+Caso especial: en `refacil:explore`, `AGENTS.md` es contexto activo durante toda la exploracion.
 
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender convenciones, arquitectura y patrones. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+## Perfil `agents`
 
-   - Si la skill activa es **`refacil:explore`**, usa lo leido en `AGENTS.md` como **contexto activo** durante toda la exploracion (no solo al inicio).
+Solo requiere `AGENTS.md`. Si existe, leelo y aplica `compact-guidance` si esta presente. Si falta: continua con baseline generico y avisa al usuario: *"No se encontro AGENTS.md; ejecuta `/refacil:setup` para reglas del proyecto."*
 
-## Perfil `agents` (solo AGENTS.md)
+## OPENSPEC-DELTAS.md
 
-Usar cuando la skill diga: *Aplica el perfil `agents`.*
+Convenciones Refacil al delegar a skills `openspec-*`: ver `OPENSPEC-DELTAS.md` (misma carpeta), leer junto a la skill OpenSpec que se invoque.
 
-Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender convenciones, arquitectura y patrones.
-Si NO existe, informa al usuario: "No se encontro AGENTS.md. Continuare con baseline generico; para reglas del proyecto ejecuta `/refacil:setup`." y continua.
-
-## Ubicacion de este archivo
-
-En el repo del proyecto (elige segun herramienta):
-
-- Claude Code: `.claude/skills/refacil-prereqs/SKILL.md`
-- Cursor: `.cursor/skills/refacil-prereqs/SKILL.md`
-
-En la **misma carpeta** esta `OPENSPEC-DELTAS.md`: convenciones Refacil al delegar en skills `openspec-*` (leer junto a la skill OpenSpec indicada).
-
-Si ninguna existe, ejecuta `refacil-sdd-ai update` (o `init`).
+Si faltan estos archivos, ejecuta `refacil-sdd-ai update` (o `init`).

package/skills/propose/SKILL.md

@@ -8,9 +8,7 @@ user-invocable: true
 
 Este comando envuelve la funcionalidad de OpenSpec fast-forward (ff) y agrega las convenciones del equipo.
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `openspec`** antes de continuar.
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
 ## Instrucciones
 

package/skills/review/SKILL.md

@@ -8,12 +8,9 @@ user-invocable: true
 
 Eres un reviewer exigente pero constructivo que evalua el codigo contra el checklist de calidad del equipo.
 
-## Contexto
+**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + modo de salida de `METHODOLOGY-CONTRACT.md`.
 
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `agents`** antes de continuar.
-Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` y aplica el modo de salida definido ahi.
-
-### Cargar checklists
+## Checklists a cargar
 
 1. **Siempre** lee el checklist general: [checklist.md](checklist.md)
 2. **Detecta el tipo de proyecto** inspeccionando dependencias, `AGENTS.md`, o la estructura del repo:
@@ -77,62 +74,27 @@ Usa severidad para priorizar correcciones, no para inflar el reporte.
 
 ### Paso 4: Reporte
 
+Por defecto, usa salida **concisa** (segun `METHODOLOGY-CONTRACT.md`):
+
 ```
 === Review Report ===
-
 VEREDICTO: APROBADO | APROBADO CON OBSERVACIONES | REQUIERE CORRECCIONES
 BLOCKERS: [si/no]
 
-## Hallazgos priorizados (solo FAIL)
+## Hallazgos priorizados (solo FAIL, maximo 5)
 1. [CRITICO|ALTO|MEDIO|BAJO] [seccion/item] — [problema]
    - Evidencia: [archivo/rango o comportamiento]
    - Correccion sugerida: [accion concreta]
 
-## Checklist General
-- Alcance y foco: [PASS/FAIL/N/A]
-- Conformidad con Spec: [PASS/FAIL/N/A]
-- Calidad de Codigo: [PASS/FAIL/N/A]
-- Arquitectura: [PASS/FAIL/N/A]
-- Manejo de errores: [PASS/FAIL/N/A]
-- Testing: [PASS/FAIL/N/A]
-- Seguridad: [PASS/FAIL/N/A]
-- Dependencias: [PASS/FAIL/N/A]
-- Mantenibilidad y observabilidad: [PASS/FAIL/N/A]
-- Git y Deploy: [PASS/FAIL/N/A]
-- Reglas del proyecto (AGENTS.md): [PASS/FAIL/N/A]
-
-## Checklist Backend (si aplica)
-- Validacion de entrada: [PASS/FAIL/N/A]
-- Contratos de API: [PASS/FAIL/N/A]
-- Manejo de errores: [PASS/FAIL/N/A]
-- Arquitectura y patrones: [PASS/FAIL/N/A]
-- Concurrencia y atomicidad: [PASS/FAIL/N/A]
-- Consultas a BD: [PASS/FAIL/N/A]
-- Caching: [PASS/FAIL/N/A]
-- Resiliencia y conexiones: [PASS/FAIL/N/A]
-- Colas y mensajeria: [PASS/FAIL/N/A]
-- Performance: [PASS/FAIL/N/A]
-- Logging: [PASS/FAIL/N/A]
-- Testing backend: [PASS/FAIL/N/A]
-
-## Checklist Frontend (si aplica)
-- Componentes y estructura: [PASS/FAIL/N/A]
-- Estado y datos: [PASS/FAIL/N/A]
-- Manejo de errores en UI: [PASS/FAIL/N/A]
-- Integracion con APIs: [PASS/FAIL/N/A]
-- Validacion de formularios: [PASS/FAIL/N/A]
-- Ruteo y navegacion: [PASS/FAIL/N/A]
-- Consistencia visual: [PASS/FAIL/N/A]
-- Performance frontend: [PASS/FAIL/N/A]
-- Accesibilidad: [PASS/FAIL/N/A]
-- Seguridad frontend: [PASS/FAIL/N/A]
-- Testing frontend: [PASS/FAIL/N/A]
-
 ## Correcciones minimas para aprobar
 1. [item accionable]
 2. [item accionable]
+
+Siguiente paso: [/refacil:archive | /refacil:verify]
 ```
 
+Si el usuario pide modo **detallado**, agrega tras el bloque conciso una seccion por cada checklist cargado (`checklist.md`, `checklist-back.md`, `checklist-front.md` segun aplique) con cada item y su estado `[PASS/FAIL/N/A]`. No inventes items; usa literalmente los de los archivos. Marca N/A si un item no aplica.
+
 ### Paso 5: Marcador de review (obligatorio si APROBADO)
 
 Si el veredicto es **APROBADO** o **APROBADO CON OBSERVACIONES**, crea un archivo marcador en el directorio del cambio activo:

package/skills/setup/SKILL.md

@@ -64,6 +64,12 @@ Analiza el repo y genera `AGENTS.md` (espanol, terminos tecnicos en ingles). Si
 
 **6.4** — Muestra el resultado; si el usuario aprueba, escribe en la raiz.
 
+**6.5 Eficiencia de tokens (hook + bloque auto-gestionado)**:
+- Explica al usuario que `refacil-sdd-ai` mantiene en `AGENTS.md` un bloque `compact-guidance` para reducir consumo de contexto.
+- Ese bloque se sincroniza automaticamente por el hook `check-update` en cada `SessionStart` (y tambien en `init`/`update`).
+- Si `AGENTS.md` aun no existe, la sincronizacion se omite sin error.
+- Indica que no debe editar manualmente el contenido entre marcadores `compact-guidance` porque se sobrescribe.
+
 ### Paso 7: 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`.

package/skills/test/SKILL.md

@@ -8,34 +8,20 @@ user-invocable: true
 
 Eres un asistente de testing que genera pruebas unitarias de alta calidad, adaptandose al stack tecnologico del proyecto.
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `openspec`** antes de continuar.
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + comando de tests segun `METHODOLOGY-CONTRACT.md §3`.
 
 ### Detectar stack tecnologico
 
-**IMPORTANTE**: Este skill NO asume ningun stack. Antes de generar tests, detecta automaticamente:
-
-1. **Lenguaje**: Lee `package.json`, `pom.xml`, `build.gradle`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, o los archivos fuente para determinar el lenguaje principal.
-
-2. **Framework de testing**: Busca la configuracion de tests existente:
-   - JavaScript/TypeScript: `jest.config.*`, `vitest.config.*`, `.mocharc.*`, `karma.conf.*`, seccion `jest` en `package.json`
-   - Python: `pytest.ini`, `pyproject.toml` (seccion `[tool.pytest]`), `setup.cfg`
-   - Java/Kotlin: `pom.xml` (JUnit/Mockito), `build.gradle` (dependencias de test)
-   - Go: archivos `_test.go` existentes
-   - Rust: archivos con `#[cfg(test)]`
-   - Otro: busca archivos de test existentes para inferir patron
-
-3. **Patrones existentes**: Busca tests existentes en el proyecto (`*.spec.*`, `*.test.*`, `test_*`, `*_test.*`) y analiza:
-   - Estructura de archivos (donde se ubican los tests)
-   - Convencion de nombrado
-   - Como se hacen los mocks/stubs
-   - Framework de assertions usado
-   - Setup/teardown patterns
+NO asumir stack. Antes de generar tests, detecta:
 
-4. **Script de ejecucion**: Identifica como se ejecutan los tests (`npm test`, `pytest`, `go test`, `cargo test`, `mvn test`, etc.)
+| Fuente | Que buscar |
+|---|---|
+| Lenguaje | `package.json`, `pom.xml`, `build.gradle`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile` |
+| Framework de tests | JS/TS: `jest.config.*`, `vitest.config.*`, `.mocharc.*`, campo `jest` en `package.json`. Python: `pytest.ini`, `[tool.pytest]` en `pyproject.toml`. Java: `pom.xml`/`build.gradle`. Go: `*_test.go`. Rust: `#[cfg(test)]` |
+| Patrones del proyecto | Tests existentes (`*.spec.*`, `*.test.*`, `test_*`, `*_test.*`): ubicacion, nombrado, mocks, assertions, setup/teardown |
+| Comando de ejecucion | `METHODOLOGY-CONTRACT.md §3` |
 
-Si existe [testing-patterns.md](testing-patterns.md) en esta misma carpeta de skill, usalo como **referencia adicional**, pero **siempre prioriza los patrones reales detectados en el proyecto**. Si los patrones del proyecto difieren de testing-patterns.md, sigue los del proyecto.
+Si existe `testing-patterns.md` junto a esta skill, usalo como referencia secundaria. Los patrones reales del proyecto siempre tienen prioridad.
 
 ## Instrucciones
 
@@ -88,6 +74,7 @@ Si el usuario pasa un archivo: `/refacil:test src/mi-archivo.ext`
 ## Reglas
 
 - **NUNCA hardcodear un stack** — siempre detectar del proyecto real
+- Resolver y ejecutar el comando de tests segun `METHODOLOGY-CONTRACT.md` §3
 - Cada criterio de aceptacion (CA-XX) debe tener al menos 1 test
 - Cada criterio de rechazo (CR-XX) debe tener al menos 1 test
 - Coverage minimo del 80% en archivos nuevos

package/skills/up-code/SKILL.md

@@ -7,13 +7,9 @@ user-invocable: true
 # refacil:up-code — Integrar Codigo y Publicar Cambios
 
 Sube los cambios al repositorio remoto y genera el PR para integracion.
-Toda integracion a ramas protegidas requiere PR — sin excepciones (incluye `testing`).
-NUNCA se hacen ajustes directos en `master` o `main`.
+Aplica la politica de ramas e integracion definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md` (sin excepciones).
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `agents`** antes de continuar.
-Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del flujo.
+**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md` (politica de ramas aplica sin excepciones).
 
 ## Instrucciones
 
@@ -21,7 +17,7 @@ Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del
 
 Ejecuta `git branch --show-current` para obtener el nombre de la rama.
 
-- Si la rama actual es protegida (`master`, `main`, `develop`, `dev`, `testing`, `qa`), **detente** e informa al usuario:
+- 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.
@@ -103,7 +99,6 @@ A que rama quieres crear el PR? (recomendado: testing)
 
 ## Reglas
 
-- NUNCA hacer push directo a ramas protegidas: master, main, develop, dev, testing, qa
-- Si la rama actual es protegida, **detener** — la validacion de rama se hace en `/refacil:apply` o `/refacil:bug`, no aqui
-- Toda integracion a cualquier rama protegida requiere PR
+- 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

package/skills/verify/SKILL.md

@@ -8,10 +8,7 @@ user-invocable: true
 
 Este comando envuelve la funcionalidad de OpenSpec verify y agrega verificacion de tests.
 
-## Antes de empezar
-
-Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/` (misma skill en Claude Code y Cursor) y aplica el **perfil `openspec`** antes de continuar.
-Lee `METHODOLOGY-CONTRACT.md` en `refacil-prereqs` para reglas transversales del flujo.
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
 ## Instrucciones
 

package/templates/compact-guidance.md

@@ -0,0 +1,45 @@
+<!-- AUTO-GENERADO por refacil-sdd-ai. No edites entre los marcadores; el contenido se refresca en cada sesion. -->
+
+## Eficiencia de tokens
+
+Reglas para minimizar el consumo de contexto al trabajar en este repositorio.
+
+**Lectura de archivos**
+- Usa `Read` con `offset` y `limit` cuando conozcas la zona relevante del archivo.
+- No leas archivos de mas de 500 lineas completos; segmenta por rango.
+- Para descubrir estructura del repo: usa `Glob` en lugar de `ls -R` o `find`.
+- No releas el archivo completo si ya leiste el bloque relevante; continua desde ese contexto.
+- Antes de leer un archivo largo, ubica simbolos con busqueda y luego lee solo rangos candidatos.
+
+**Busqueda**
+- Usa `Grep` con `head_limit` en vez de dump crudo.
+- Cuando solo necesites ubicaciones, usa `output_mode: "files_with_matches"`.
+- Acota siempre con `glob` o `type` para no escanear de mas.
+
+**Git (via Bash)**
+- Historial: `git log --oneline -20` por defecto; amplia solo si es insuficiente.
+- Diffs: empieza con `git diff --stat`; pide el diff completo solo del archivo que vas a tocar.
+- Status: `git status -s` (short format).
+- Show: `git show --stat` antes del full.
+
+**Tests**
+- Reporta solo failures; no enumeres los passes en el output visible.
+- Si el runner tiene modo silencioso o summary (`jest --silent --reporters=summary`, `pytest -q`), usalo.
+- Si el runner es verboso por defecto, redirige: `2>&1 | tail -80`.
+
+**Logs y errores**
+- No pegues stack traces enteros; extrae solo el frame relevante con el mensaje.
+- Resume logs repetidos: "(N ocurrencias de <mensaje>)".
+- Para archivos de log: `tail -100` o filtra por nivel ERROR/WARN.
+
+**Build y lint**
+- `tsc`, `eslint`, `biome`: agrupa errores por archivo o por regla; no enumeres linea por linea.
+- Construccion exitosa: confirma con una sola linea, no pegues el output completo.
+- Si hay muchos errores similares: muestra un ejemplo y el conteo.
+
+**Docker y contenedores**
+- `docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Image}}"`.
+- `docker logs --tail 100` siempre; nunca logs completos.
+
+**Regla general**
+Cuando dudes entre verbosidad y concision, elige concision. El usuario puede pedir detalle bajo demanda.

package/templates/{claude-md.md → methodology-guide.md}

@@ -1,11 +1,8 @@
-# CLAUDE.md
-
-Las instrucciones completas del proyecto estan en [AGENTS.md](AGENTS.md).
-Si AGENTS.md no existe, ejecuta `/refacil:setup` para generarlo automaticamente.
+Instrucciones completas del proyecto: ver `AGENTS.md`. Si falta, ejecuta `/refacil:setup`.
 
 ## Metodologia SDD-AI (Refacil)
 
-Este proyecto usa la metodologia SDD-AI en **Claude Code** y **Cursor** con el mismo conjunto de skills: estan en `.claude/skills/refacil-*/` y en `.cursor/skills/refacil-*/` (copias equivalentes; `refacil-sdd-ai init` instala ambas). Comandos disponibles:
+Skills identicas en `.claude/skills/refacil-*/` (Claude Code) y `.cursor/skills/refacil-*/` (Cursor). Instaladas por `refacil-sdd-ai init`.
 
 | Comando | Descripcion |
 |---------|-------------|
@@ -18,7 +15,14 @@ Este proyecto usa la metodologia SDD-AI en **Claude Code** y **Cursor** con el m
 | `/refacil:verify` | Validar implementacion vs specs |
 | `/refacil:review` | Review con checklist de calidad |
 | `/refacil:archive` | Archivar cambio completado |
-| `/refacil:up-code` | Subir codigo a rama de desarrollo |
+| `/refacil:up-code` | Subir codigo y crear PR |
 | `/refacil:bug` | Flujo guiado de bugfix |
 
 Flujo: `setup` → `propose` → `apply` → `test` → `verify` → `review` → `archive` → `up-code`
+
+## Eficiencia de tokens (automatica)
+
+- El hook `check-update` en `SessionStart` sincroniza el bloque `compact-guidance` en `AGENTS.md`.
+- El bloque define reglas de salida compacta (lectura por rango, busqueda acotada, tests/logs resumidos).
+- Si `AGENTS.md` aun no existe, la sincronizacion se omite sin error.
+- No editar manualmente el contenido entre marcadores `compact-guidance`; se sobreescribe automaticamente.

package/templates/cursorrules.md

@@ -1,22 +0,0 @@
-# Cursor Rules
-
-Las instrucciones completas del proyecto estan en AGENTS.md.
-Si AGENTS.md no existe, ejecuta /refacil:setup para generarlo automaticamente.
-
-## Metodologia SDD-AI (Refacil)
-
-Metodologia equivalente en Claude Code (`.claude/skills/refacil-*/`) y Cursor (`.cursor/skills/refacil-*/`). Comandos (en este IDE, bajo `.cursor/skills/refacil-*/`):
-
-- /refacil:setup — Instalar OpenSpec y generar AGENTS.md
-- /refacil:guide — Guia interactiva
-- /refacil:explore — Explorar codebase
-- /refacil:propose — Crear propuesta de cambio
-- /refacil:apply — Implementar tasks
-- /refacil:test — Generar tests unitarios
-- /refacil:verify — Validar vs specs
-- /refacil:review — Review con checklist
-- /refacil:archive — Archivar cambio
-- /refacil:up-code — Subir codigo a rama de desarrollo
-- /refacil:bug — Flujo guiado de bugfix
-
-Flujo: setup → propose → apply → test → verify → review → archive → up-code