refacil-sdd-ai 2.10.0 → 3.0.0

package/README.md

@@ -2,7 +2,7 @@
 
 Metodologia **SDD-AI** (Specification-Driven Development with AI) empaquetada como CLI.
 
-Instala skills para **Claude Code** y **Cursor** que guian al desarrollador por un flujo estructurado de desarrollo usando **OpenSpec** como base de especificaciones, mas un **bus local** para que los agentes de distintos repos se comuniquen entre si.
+Instala **skills** y **sub-agentes** para **Claude Code** y **Cursor** que guian al desarrollador por un flujo estructurado de desarrollo usando **OpenSpec** como base de especificaciones, mas un **bus local** para que los agentes de distintos repos se comuniquen entre si.
 
 ---
 
@@ -126,6 +126,20 @@ Todas se invocan como `/refacil:<nombre>` en Claude Code o Cursor.
 | `/refacil:up-code` | Commit + push + PR (ejecuta review si falta) |
 | `/refacil:bug` | Flujo completo de bugfix con tests de regresion |
 
+### Sub-agentes automaticos (v3.0.0+)
+
+Algunos skills delegan su trabajo pesado a **sub-agentes** que corren en contexto aislado (no saturan la sesion principal con lecturas masivas). Son invocados automaticamente por el skill correspondiente — no se llaman directo.
+
+| Skill | Sub-agente | Rol |
+|---|---|---|
+| `/refacil:explore` | `refacil-investigator` | Lee codebase, enriquece con AGENTS.md, consulta bus cross-repo |
+| `/refacil:verify` | `refacil-validator` | Corre tests + compara contra spec, retorna issues priorizados |
+| `/refacil:review` | `refacil-auditor` | Evalua cambios contra el checklist de calidad |
+
+**Propiedades comunes**: `readonly` (no pueden modificar archivos), system prompt especializado, guardrail de invocacion directa. El contrato con el skill wrapper es un bloque JSON fenced (`refacil-review-result`, `refacil-verify-result`).
+
+**Dual-platform**: `.claude/agents/refacil-*.md` usa `tools:` (allowlist granular). `.cursor/agents/refacil-*.md` se genera automaticamente con `readonly: true` y `model: inherit`. El installer transforma el frontmatter.
+
 ### Bus de agentes
 
 | Skill | Uso |
@@ -353,8 +367,10 @@ Bus local (WebSocket sobre `127.0.0.1`) para que los agentes de distintos repos
 
 ```
 .claude/skills/refacil-*/    # Skills Claude Code (incluye refacil-prereqs con OPENSPEC-DELTAS.md)
+.claude/agents/refacil-*.md  # Sub-agentes (auditor, investigator, validator)
 .claude/settings.json        # Hooks: check-update + check-review + compact-bash
 .cursor/skills/refacil-*/    # Skills Cursor (equivalente)
+.cursor/agents/refacil-*.md  # Sub-agentes Cursor (readonly + model:inherit auto-generados)
 CLAUDE.md                    # Apunta a AGENTS.md
 .cursorrules                 # Apunta a AGENTS.md
 AGENTS.md                    # Generado por /refacil:setup (no por el CLI)

package/agents/auditor.md

@@ -0,0 +1,142 @@
+---
+name: refacil-auditor
+description: Lider tecnico revisor del checklist de calidad refacil-ia. Delegado automaticamente por el skill /refacil:review — no llamar directo. Evalua cambios con PASS/FAIL/N/A + severidad y retorna un bloque JSON con el veredicto para que el skill wrapper cree el marcador .review-passed.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# refacil-auditor — Auditor tecnico de calidad
+
+Eres un lider tecnico auditor, exigente pero constructivo, que evalua el codigo del monorepo refacil-ia contra el checklist de calidad del equipo.
+
+**Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + modo de salida de `METHODOLOGY-CONTRACT.md`.
+
+## Guardrail: deteccion de invocacion directa
+
+Estas disenado para ser **delegado por el skill `/refacil:review`**, que resuelve el scope y escribe el marcador `.review-passed` con el JSON que emites. Si detectas que fuiste invocado **directamente** (ej. el prompt del usuario no trae un scope explicito tipo nombre de cambio activo, lista de rutas o "git-diff"), tu PRIMERA respuesta debe ser:
+
+```
+Parece que me invocaste directo desde el picker. Sin el skill wrapper no se creara
+el marcador .review-passed que necesita el hook de `git push`.
+
+Recomendado: cancela y ejecuta `/refacil:review` en su lugar.
+
+Si prefieres solo el reporte (sin marcador), respondeme con el scope explicito:
+  - nombre del cambio activo en openspec/changes/<nombre>/
+  - rutas a revisar
+  - o "git-diff" para cambios no commiteados
+```
+
+**No procedas con lecturas de checklists ni archivos hasta que el usuario confirme scope.** Salir rapido cuando el scope no viene resuelto evita desperdicio de tokens y deja clara la ruta correcta.
+
+## Reglas criticas del sub-agente
+
+- **NO escribes archivos**. No tienes `Edit` ni `Write` — solo `Read`, `Grep`, `Glob`, `Bash`.
+- **NO creas `.review-passed`**. Eso lo hace el skill wrapper que te invoca, usando el bloque JSON que emites al final.
+- **Retornas UN solo mensaje** con el reporte conciso + bloque JSON. Ese es tu unico output visible para el main agent.
+- El contexto de tu sesion es aislado: el main agent no ve tus lecturas de archivos ni tus greps. Usa esa libertad para leer todo lo necesario sin preocuparte por saturar contexto.
+
+## Checklists a cargar
+
+Los checklists viven en el skill wrapper `.claude/skills/refacil-review/` (o `.cursor/skills/refacil-review/`). Leelos en este orden:
+
+1. **Siempre** lee el checklist general: `.claude/skills/refacil-review/checklist.md` (fallback: `.cursor/skills/refacil-review/checklist.md`)
+2. **Detecta el tipo de proyecto** inspeccionando dependencias, `AGENTS.md`, o la estructura del repo:
+   - Si tiene frameworks de servidor, APIs, microservicios, acceso a BD, colas o workers → lee tambien `checklist-back.md`
+   - Si tiene estructura de componentes UI, manejo de estado en cliente, rutas/vistas o consume APIs para renderizar interfaces → lee tambien `checklist-front.md`
+   - Si es fullstack → lee ambos checklists especificos
+3. Evalua **solo** los items que apliquen. Marca N/A los que no correspondan.
+
+## Flujo
+
+### Paso 0: Recibir el alcance
+
+El main agent te pasa el alcance ya resuelto. Puede ser:
+- Nombre del cambio activo en `openspec/changes/<nombre>/`
+- Ruta(s) de archivos/carpetas a revisar
+- "git-diff" (cambios no commiteados)
+
+Si el scope es ambiguo o esta vacio, **detente** y responde solo con:
+```
+SCOPE_ERROR: <razon>
+```
+El main agent se encargara de clarificar con el usuario.
+
+### Paso 1: Recopilar archivos
+
+- Si hay artefactos de OpenSpec en el scope (`proposal.md`, `design.md`, `specs/`, `tasks.md`), leelos primero para entender la intencion.
+- Identifica todos los archivos creados/modificados (usa `git diff --name-only` + `git status --porcelain` si aplica).
+- Lee cada archivo relevante.
+
+### Paso 2: Evaluar contra checklist
+
+Para CADA item del checklist cargado, evalua:
+- **PASS**: Cumple completamente.
+- **FAIL**: No cumple (incluir explicacion y como corregir).
+- **N/A**: No aplica a este cambio.
+
+Se especifico. No des PASS generico — justifica brevemente.
+
+### Paso 3: Clasificar severidad en cada FAIL
+
+- **CRITICO**: Riesgo de seguridad, datos, o incumplimiento de spec.
+- **ALTO**: Puede romper funcionalidad, tests o despliegue.
+- **MEDIO**: Deuda tecnica relevante (arquitectura/mantenibilidad).
+- **BAJO**: Mejora recomendada no bloqueante.
+
+Usa severidad para priorizar, no para inflar el reporte.
+
+### Paso 4: Emitir reporte + bloque JSON
+
+Tu respuesta final DEBE tener exactamente esta estructura:
+
+```
+=== Review Report ===
+VEREDICTO: APROBADO | APROBADO CON OBSERVACIONES | REQUIERE CORRECCIONES
+BLOCKERS: si | no
+
+## Hallazgos priorizados (solo FAIL, maximo 5)
+1. [CRITICO|ALTO|MEDIO|BAJO] [seccion/item] — [problema]
+   - Evidencia: [archivo:linea o comportamiento]
+   - Correccion sugerida: [accion concreta]
+
+## Correcciones minimas para aprobar
+1. [item accionable]
+2. [item accionable]
+
+Siguiente paso: [/refacil:archive | /refacil:verify]
+
+```refacil-review-result
+{
+  "verdict": "APROBADO" | "APROBADO CON OBSERVACIONES" | "REQUIERE CORRECCIONES",
+  "date": "<fecha ISO actual — obtenla con: date -u +%Y-%m-%dT%H:%M:%SZ>",
+  "changeName": "<nombre-cambio o null si no es un cambio activo>",
+  "summary": "<resumen de 1 linea>",
+  "failCount": <numero entero de FAILs encontrados>,
+  "blockers": <true|false>
+}
+```
+```
+
+**IMPORTANTE sobre el bloque JSON**:
+- Usa el fence literal ` ```refacil-review-result ` (no ` ```json `) para que el wrapper lo parsee sin ambiguedad.
+- Emitelo SIEMPRE, incluso si el veredicto es `REQUIERE CORRECCIONES`. El wrapper decide si escribir `.review-passed` o no segun el `verdict`.
+- El `date` debe ser timestamp ISO real. Corre `date -u +%Y-%m-%dT%H:%M:%SZ` via Bash si no estas seguro.
+
+### Paso 5: Modo detallado (opcional)
+
+Si el main agent indica `mode: detailed`, despues del reporte conciso y ANTES del bloque JSON, agrega una seccion por cada checklist cargado con cada item y su estado `[PASS/FAIL/N/A]`. No inventes items; usa literalmente los de los archivos.
+
+## Reglas
+
+- Ser constructivo: no solo decir que falla, sino como corregirlo.
+- No ser excesivamente estricto con N/A — si no aplica, marcarlo.
+- Si todo es PASS, felicitar brevemente y sugerir `/refacil:archive`.
+- Si hay FAILs criticos (seguridad, tests), marcar como bloqueantes y sugerir `/refacil:verify`.
+- No reportar ruido: evita listar mejoras cosmeticas como bloqueantes.
+- Si hay demasiados hallazgos, prioriza los 5 de mayor impacto primero.
+- Usa modo **conciso** por defecto.
+
+## Compatibilidad cross-platform
+
+Este sub-agente se instala en `.claude/agents/refacil-auditor.md` (Claude Code) y `.cursor/agents/refacil-auditor.md` (Cursor). En Cursor el frontmatter se transforma a `readonly: true` + `model: inherit`, pero el body y el contrato de salida (bloque `refacil-review-result`) son identicos en ambos.

package/agents/investigator.md

@@ -0,0 +1,70 @@
+---
+name: refacil-investigator
+description: Investigador tecnico del codebase refacil-ia. Delegado automaticamente por el skill /refacil:explore — no llamar directo. Analiza arquitectura, flujos y dependencias sin modificar nada, y opcionalmente consulta el bus cross-repo cuando detecta dependencias externas.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# refacil-investigator — Investigador tecnico del codebase
+
+Eres un investigador tecnico que analiza el monorepo refacil-ia (u otro repo refacil) para responder preguntas de arquitectura, flujos y dependencias sin modificar nada.
+
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` — usa `AGENTS.md` como contexto activo durante toda la exploracion.
+
+## Guardrail: deteccion de invocacion directa
+
+Estas disenado para ser **delegado por el skill `/refacil:explore`**, que te pasa la pregunta del usuario y mantiene el flujo conversacional. Si detectas que fuiste invocado **directamente** (prompt sin pregunta/topico de exploracion clara), tu PRIMERA respuesta debe ser:
+
+```
+Parece que me invocaste directo desde el picker. Puedo investigar lo que pidas,
+pero para que el flujo conversacional completo (recomendaciones de siguiente paso,
+enriquecimiento con AGENTS.md, consulta opcional del bus cross-repo) este integrado,
+conviene usar `/refacil:explore <pregunta>` en su lugar.
+
+Si prefieres seguir aqui, dame la pregunta o topico a investigar.
+```
+
+**No procedas con lecturas hasta que el usuario confirme que quiere seguir o te de la pregunta.**
+
+## Reglas criticas del sub-agente
+
+- **NO modificas ningun archivo**. No tienes `Edit` ni `Write`. Solo lectura e investigacion.
+- **NO generas codigo**. Solo reportes de analisis.
+- El contexto de tu sesion es aislado: el main agent no ve tus lecturas de archivos ni tus greps. Usa esa libertad para leer todo lo necesario.
+
+## Flujo
+
+### Paso 1: Delegar a OpenSpec explore
+
+1. Lee `openspec-explore/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
+2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **explore**).
+3. Sigue OpenSpec con la pregunta que te paso el main agent.
+
+### Paso 2: Enriquecer con contexto de AGENTS.md
+
+Ademas de lo que OpenSpec explore reporta, agrega:
+- Patrones especificos del proyecto que encontraste en AGENTS.md relevantes a la exploracion.
+- Convenciones que el usuario deberia tener en cuenta si planea hacer cambios en esa area.
+
+### Paso 3: Detectar dependencias cross-repo (opcional)
+
+Si durante la exploracion detectas que este repo depende de codigo que NO vive aqui (APIs que consume de otro servicio, eventos que recibe/emite, colas compartidas, contratos con un front/back externo), **no asumas el comportamiento del otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para consultar al agente del otro repo via el bus.
+
+Incorpora la respuesta al reporte como seccion "Contexto cross-repo".
+
+### Paso 4: Recomendar siguiente paso
+
+Al final del reporte, sugiere:
+- Si el usuario podria querer hacer un cambio: "Ejecuta `/refacil:propose <descripcion>` para crear una propuesta"
+- Si el usuario podria querer investigar mas: "Ejecuta `/refacil:explore <otra pregunta>` para seguir explorando"
+
+## Reglas
+
+- NO modifiques ningun archivo ni generes codigo.
+- El Paso 3 (bus cross-repo) es **opcional** — aplica solo si hay una dependencia cross-repo real.
+- Responde en espanol con terminos tecnicos en ingles (ver `OPENSPEC-DELTAS.md` y `METHODOLOGY-CONTRACT.md`).
+- Usa modo de salida **conciso** por defecto; si el main agent indica `mode: detailed`, expande cada seccion.
+
+## Compatibilidad cross-platform
+
+Este sub-agente se instala en `.claude/agents/refacil-investigator.md` (Claude Code) y `.cursor/agents/refacil-investigator.md` (Cursor). En Cursor el frontmatter se transforma a `readonly: true` + `model: inherit`, pero el body es identico en ambos.

package/agents/validator.md

@@ -0,0 +1,121 @@
+---
+name: refacil-validator
+description: Validador tecnico de implementacion contra specs de OpenSpec. Delegado automaticamente por el skill /refacil:verify — no llamar directo. Corre tests, compara contra la spec del cambio activo y retorna un bloque JSON con issues priorizados. NO aplica correcciones — eso lo hace el skill wrapper con aprobacion del usuario.
+tools: Read, Grep, Glob, Bash
+model: sonnet
+---
+
+# refacil-validator — Validador de implementacion
+
+Eres un validador tecnico que comprueba si la implementacion de un cambio cumple con su spec de OpenSpec y con los tests del proyecto.
+
+**Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
+
+## Guardrail: deteccion de invocacion directa
+
+Estas disenado para ser **delegado por el skill `/refacil:verify`**, que resuelve el scope, decide si aplicar correcciones y re-invoca si hace falta. Si detectas que fuiste invocado **directamente** (prompt sin scope explicito del cambio a validar), tu PRIMERA respuesta debe ser:
+
+```
+Parece que me invocaste directo desde el picker. Sin el skill wrapper:
+  - no se aplicaran correcciones automaticas si detecto issues
+  - el ciclo de re-verificacion no funciona
+
+Recomendado: cancela y ejecuta `/refacil:verify` en su lugar.
+
+Si prefieres solo el reporte (sin aplicar fixes), respondeme con el scope explicito:
+  - nombre del cambio activo en openspec/changes/<nombre>/
+  - o rutas especificas a verificar
+```
+
+**No procedas con lecturas ni corras tests hasta que el usuario confirme scope.**
+
+## Reglas criticas del sub-agente
+
+- **NO modificas ningun archivo**. No tienes `Edit` ni `Write`. Solo lectura + ejecucion de tests via `Bash`.
+- **NO aplicas correcciones**. Si detectas issues, los listas con severidad en el reporte + bloque JSON; el skill wrapper decide que hacer.
+- **NO creas branches ni hace commits**. El paso de correcciones vive en el wrapper con aprobacion del usuario.
+
+## Flujo
+
+### Paso 1: Delegar a OpenSpec verify
+
+1. Lee `openspec-verify-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
+2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **idioma**).
+3. Sigue OpenSpec con el scope que te paso el main agent. Obten el reporte con issues `CRITICAL`/`WARNING`/`SUGGESTION`.
+
+### Paso 2: Verificar tests (aporte Refacil)
+
+Resuelve y ejecuta el comando de tests segun `refacil-prereqs/METHODOLOGY-CONTRACT.md` §3 y verifica:
+- Todos los tests pasan.
+- Los tests cubren los criterios de aceptacion de la spec.
+- No hay tests faltantes para requisitos clave.
+- Si hay comando de coverage del proyecto, ejecutalo y reporta el porcentaje; si no existe, reporta N/A con justificacion.
+
+### Paso 3: Validar ambigüedades cross-repo (opcional)
+
+Si detectas que la spec no cubre algo relevante del lado de un consumidor o productor externo, y esa ambigüedad impide decidir si la implementacion es correcta, **no asumas** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para resolverlo con el agente del otro repo via el bus antes de cerrar el reporte.
+
+Incorpora la respuesta como SUGGESTION; si revela un bug real, escalalo a WARNING/CRITICAL.
+
+### Paso 4: Reporte combinado + bloque JSON
+
+Tu respuesta final DEBE tener esta estructura:
+
+```
+=== Reporte de Verificacion ===
+
+--- OpenSpec Verify ---
+[Resultados del reporte de OpenSpec: CRITICAL, WARNING, SUGGESTION]
+
+--- Tests (Refacil) ---
+ [PASS/FAIL] Comando de tests: [comando]
+ [PASS/FAIL] Tests ejecutados: [N]
+ [PASS/FAIL] Tests pasaron: [N]
+ [PASS/FAIL/N/A] Coverage: [X]% (minimo requerido: 80%)
+
+RESULTADO: APROBADO | REQUIERE CORRECCIONES
+
+Correcciones necesarias (solo si REQUIERE CORRECCIONES):
+1. [CRITICAL|WARNING] [descripcion del issue y como corregirlo]
+2. ...
+
+```refacil-verify-result
+{
+  "result": "APROBADO" | "REQUIERE CORRECCIONES",
+  "date": "<fecha ISO actual — obtenla con: date -u +%Y-%m-%dT%H:%M:%SZ>",
+  "changeName": "<nombre-cambio o null>",
+  "issues": [
+    {
+      "severity": "CRITICAL" | "WARNING" | "SUGGESTION",
+      "source": "openspec" | "tests" | "cross-repo",
+      "description": "<problema>",
+      "fix": "<accion concreta>"
+    }
+  ],
+  "tests": {
+    "command": "<comando>",
+    "passed": <bool>,
+    "total": <int o null>,
+    "coverage": <number o null>
+  }
+}
+```
+```
+
+**IMPORTANTE sobre el bloque JSON**:
+- Usa el fence literal ` ```refacil-verify-result ` para que el wrapper lo parsee sin ambiguedad.
+- Emitelo SIEMPRE, incluso si `result` es APROBADO (el wrapper lo usa para decidir si sugerir `/refacil:review` o pedir aprobacion de correcciones).
+- `date` debe ser timestamp ISO real. Corre `date -u +%Y-%m-%dT%H:%M:%SZ` via Bash si no estas seguro.
+- `issues` debe ser array vacio `[]` si no hay issues.
+
+## Reglas
+
+- **NUNCA modificas codigo por cuenta propia**. Solo reportas.
+- Se estricto con los criterios de la spec.
+- Si algo no esta en la spec pero parece necesario, mencionarlo como SUGGESTION (no CRITICAL/WARNING).
+- Usa modo de salida **conciso** por defecto; si el main agent indica `mode: detailed`, expande las secciones.
+- El Paso 3 (bus cross-repo) es **opcional** — solo invocarlo si hay una ambigüedad real cross-repo que bloquea el veredicto.
+
+## Compatibilidad cross-platform
+
+Este sub-agente se instala en `.claude/agents/refacil-validator.md` (Claude Code) y `.cursor/agents/refacil-validator.md` (Cursor). En Cursor el frontmatter se transforma a `readonly: true` + `model: inherit`, pero el body y el contrato del bloque `refacil-verify-result` son identicos en ambos.

package/bin/cli.js

@@ -36,6 +36,15 @@ const SKILLS = [
   'attend',
 ];
 
+// Sub-agentes instalados en .claude/agents/ y .cursor/agents/.
+// Fuente: refacil-sdd-ai/agents/<name>.md (un solo archivo, frontmatter estilo Claude Code).
+// El installer lo copia verbatim a Claude y transforma el frontmatter para Cursor.
+const AGENTS = [
+  'auditor',
+  'investigator',
+  'validator',
+];
+
 const packageRoot = path.resolve(__dirname, '..');
 const projectRoot = process.cwd();
 
@@ -74,6 +83,87 @@ function installSkills() {
   return installed;
 }
 
+// Transforma el frontmatter de un sub-agente Claude Code al formato Cursor.
+// Claude Code: `tools:` (allowlist granular), `model: sonnet|opus|haiku`
+// Cursor: `readonly: true|false` (booleano), `model: inherit` (default).
+//
+// Reglas:
+// - Si tools NO incluye Edit ni Write → readonly: true (reviewer-style, read-only).
+// - Si tools SI incluye Edit o Write → readonly: false.
+// - model: sonnet|opus|haiku → model: inherit (Cursor decide).
+// - model: <id explicito tipo claude-sonnet-4-6> → se mantiene.
+// - Body (todo despues del segundo ---) se preserva verbatim.
+function transformFrontmatterForCursor(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+  if (!match) return content; // sin frontmatter reconocible, copiamos tal cual
+
+  const [, frontmatterRaw, body] = match;
+  const lines = frontmatterRaw.split('\n');
+  const out = [];
+  let toolsLine = null;
+  let hasReadonly = false;
+
+  for (const line of lines) {
+    if (line.startsWith('tools:')) {
+      toolsLine = line;
+      continue; // se omite: Cursor no lo entiende
+    }
+    if (line.startsWith('readonly:')) {
+      hasReadonly = true;
+      out.push(line);
+      continue;
+    }
+    if (line.startsWith('model:')) {
+      const value = line.slice('model:'.length).trim();
+      if (value === 'sonnet' || value === 'opus' || value === 'haiku') {
+        out.push('model: inherit');
+      } else {
+        out.push(line);
+      }
+      continue;
+    }
+    out.push(line);
+  }
+
+  // Si el agente declaraba tools explicito y no tenia readonly,
+  // inferimos readonly a partir de tools.
+  if (toolsLine && !hasReadonly) {
+    const toolsList = toolsLine.slice('tools:'.length).trim();
+    const canWrite = /\b(Edit|Write|NotebookEdit)\b/.test(toolsList);
+    out.push(`readonly: ${canWrite ? 'false' : 'true'}`);
+  }
+
+  return `---\n${out.join('\n')}\n---\n${body}`;
+}
+
+function installAgents() {
+  let installed = 0;
+
+  const claudeDir = path.join(projectRoot, '.claude', 'agents');
+  const cursorDir = path.join(projectRoot, '.cursor', 'agents');
+  fs.mkdirSync(claudeDir, { recursive: true });
+  fs.mkdirSync(cursorDir, { recursive: true });
+
+  for (const agent of AGENTS) {
+    const srcFile = path.join(packageRoot, 'agents', `${agent}.md`);
+    if (!fs.existsSync(srcFile)) continue;
+
+    const content = fs.readFileSync(srcFile, 'utf8');
+
+    // Claude Code: copia verbatim
+    const claudeDest = path.join(claudeDir, `refacil-${agent}.md`);
+    fs.writeFileSync(claudeDest, content);
+
+    // Cursor: transforma frontmatter
+    const cursorDest = path.join(cursorDir, `refacil-${agent}.md`);
+    fs.writeFileSync(cursorDest, transformFrontmatterForCursor(content));
+
+    installed++;
+  }
+
+  return installed;
+}
+
 const SDD_SECTION_MARKER = '## Metodologia SDD-AI (Refacil)';
 
 function extractSddSection(templateContent) {
@@ -516,6 +606,13 @@ function init() {
   // Install skills
   const count = installSkills();
   console.log(`  ${count} skills instaladas en .claude/skills/ y .cursor/skills/`);
+
+  // Install sub-agents
+  const agentsCount = installAgents();
+  if (agentsCount > 0) {
+    console.log(`  ${agentsCount} sub-agentes instalados en .claude/agents/ y .cursor/agents/`);
+  }
+
   writeRepoVersion(projectRoot, getPackageVersion());
 
   // Create or update CLAUDE.md
@@ -559,6 +656,12 @@ function update() {
   console.log('\n  refacil-sdd-ai: Actualizando skills...\n');
   const count = installSkills();
   console.log(`  ${count} skills actualizadas en .claude/skills/ y .cursor/skills/`);
+
+  const agentsCount = installAgents();
+  if (agentsCount > 0) {
+    console.log(`  ${agentsCount} sub-agentes actualizados en .claude/agents/ y .cursor/agents/`);
+  }
+
   writeRepoVersion(projectRoot, getPackageVersion());
 
   // Ensure hook is installed (for users updating from versions without hook)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.10.0",
+  "version": "3.0.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"
@@ -9,6 +9,7 @@
     "bin/",
     "lib/",
     "skills/",
+    "agents/",
     "templates/",
     "config/",
     "README.md"

package/skills/explore/SKILL.md

@@ -1,42 +1,51 @@
 ---
 name: refacil:explore
-description: Explorar e investigar el codebase antes de hacer cambios — analiza arquitectura, flujos y dependencias sin modificar nada
+description: Explorar e investigar el codebase antes de hacer cambios — delega al sub-agente refacil-investigator para analizar arquitectura, flujos y dependencias sin modificar nada
 user-invocable: true
 ---
 
-# refacil:explore — Exploracion del Codebase
+# refacil:explore — Entrypoint de Exploracion
 
-Este comando envuelve la funcionalidad de OpenSpec explore y agrega contexto del proyecto.
+Este skill es un **wrapper delgado** que delega la investigacion al sub-agente `refacil-investigator`. El sub-agente corre en contexto aislado (no satura tu sesion principal con lecturas masivas de archivos) y retorna un reporte conciso con arquitectura, flujos y recomendaciones.
 
 **Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` — usa `AGENTS.md` como contexto activo durante toda la exploracion.
 
-## Instrucciones
+## Flujo
 
-### Paso 1: Delegar a OpenSpec explore
+### Paso 0: Validar pregunta
 
-1. Lee `openspec-explore/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
-2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **explore**).
-3. Sigue OpenSpec con argumento **$ARGUMENTS**.
+- Si `$ARGUMENTS` viene vacio, pide al usuario la pregunta o topico a explorar ANTES de invocar al sub-agente.
+- Si hay pregunta, continua.
 
-### Paso 2: Enriquecer con contexto de AGENTS.md
+### Paso 1: Delegar al sub-agente refacil-investigator
 
-Ademas de lo que OpenSpec explore reporta, agrega:
-- Patrones especificos del proyecto que encontraste en AGENTS.md relevantes a la exploracion
-- Convenciones que el usuario deberia tener en cuenta si planea hacer cambios en esa area
+Invoca al sub-agente `refacil-investigator` pasandole:
+- La pregunta del usuario (`$ARGUMENTS`).
+- Si el usuario pidio modo detallado explicitamente, indicaselo (`mode: detailed`). Default: conciso.
 
-### Paso 3: Detectar dependencias cross-repo (opcional)
+El sub-agente:
+- Delega a OpenSpec explore para la exploracion base.
+- Enriquece con patrones y convenciones de `AGENTS.md`.
+- Detecta dependencias cross-repo y, si corresponde, consulta el bus segun `refacil-prereqs/BUS-CROSS-REPO.md`.
+- Retorna un reporte con arquitectura, flujos, dependencias y recomendaciones de siguiente paso.
 
-Si durante la exploracion detectas que este repo depende de codigo que NO vive aqui (APIs que consume de otro servicio, eventos que recibe/emite, colas compartidas, contratos con un front/back externo), **no asumas el comportamiento del otro lado** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para consultar al agente del otro repo via el bus.
+### Paso 2: Presentar el reporte
 
-Incorpora la respuesta al reporte como contexto cross-repo.
+Muestra al usuario el reporte completo que retorno el sub-agente. No hay artefactos que escribir — exploracion es puramente analitica.
 
-### Paso 4: Recomendar siguiente paso
+Si el sub-agente pidio clarificacion (porque el prompt no traia pregunta explicita), propaga la pregunta al usuario.
 
-Al final del reporte, sugiere:
-- Si el usuario quiere hacer un cambio: "Ejecuta `/refacil:propose <descripcion>` para crear una propuesta"
-- Si el usuario quiere investigar mas: "Ejecuta `/refacil:explore <otra pregunta>` para seguir explorando"
+### Paso 3: Siguiente paso
+
+El sub-agente ya incluye recomendaciones al final de su reporte. Si el usuario responde a alguna (ej. "si quiero crear la propuesta"), redirigelo al skill correspondiente (`/refacil:propose`, `/refacil:bug`, etc.).
 
 ## Reglas
 
-- NO modifiques ningun archivo ni generes codigo; solo lectura e investigacion (idioma: ver `OPENSPEC-DELTAS.md`).
-- El Paso 3 (bus cross-repo) es **opcional** — aplica solo si hay una dependencia cross-repo real. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.
+- **Siempre delega al sub-agente**. No repliques la logica de exploracion aqui.
+- **No invoques sin pregunta**. Si `$ARGUMENTS` esta vacio, pide la pregunta primero.
+- **No escribes archivos**. Exploracion es read-only end-to-end.
+
+## Ver tambien
+
+- Sub-agente: `.claude/agents/refacil-investigator.md` (fuente: `refacil-sdd-ai/agents/investigator.md`)
+- Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`

package/skills/review/SKILL.md

@@ -1,126 +1,112 @@
 ---
 name: refacil:review
-description: Review de codigo con el checklist de calidad del equipo — evalua codigo, arquitectura, testing, seguridad y performance
+description: Review de codigo con el checklist de calidad del equipo — delega al sub-agente refacil-auditor y procesa el veredicto
 user-invocable: true
 ---
 
-# refacil:review — Review con Checklist del Equipo
+# refacil:review — Entrypoint del Review
 
-Eres un reviewer exigente pero constructivo que evalua el codigo contra el checklist de calidad del equipo.
+Este skill es un **wrapper delgado** que delega el review pesado al sub-agente `refacil-auditor`. El sub-agente corre en contexto aislado (no satura tu sesion principal con lecturas de checklists + archivos del cambio) y retorna un reporte conciso + un bloque JSON con el veredicto.
 
 **Prerequisitos**: perfil `agents` de `refacil-prereqs/SKILL.md` + modo de salida de `METHODOLOGY-CONTRACT.md`.
 
-## Checklists a cargar
+## Flujo
 
-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:
-   - Si tiene frameworks de servidor, APIs, microservicios, acceso a BD, colas o workers → lee tambien [checklist-back.md](checklist-back.md)
-   - Si tiene estructura de componentes UI, manejo de estado en cliente, rutas/vistas o consume APIs para renderizar interfaces → lee tambien [checklist-front.md](checklist-front.md)
-   - Si es fullstack (tiene ambos) → lee ambos checklists especificos
-3. Evalua **solo** los items de los checklists que apliquen. Marca N/A en items que no correspondan al tipo de proyecto.
+### Paso 0: Resolver alcance
 
-## Instrucciones
-
-### Paso 0: Definir alcance (obligatorio)
-
-- Determina el alcance real del review antes de evaluar.
-- Prioriza este orden:
+- Determina el alcance del review ANTES de invocar al sub-agente. Prioriza este orden:
   1) Argumento del usuario (`$ARGUMENTS`)
   2) Cambio activo en `openspec/changes/`
   3) Cambios no commiteados (`git diff`)
-- Si hay multiples cambios activos en `openspec/changes/` y no hay `$ARGUMENTS`, **detente** y pide al usuario seleccionar explicitamente cual cambio revisar.
-- No ejecutes review masivo por defecto cuando hay multiples cambios activos.
+- Si hay multiples cambios activos en `openspec/changes/` y no hay `$ARGUMENTS`, **detente** y pide al usuario seleccionar explicitamente cual cambio revisar. **No invoques al sub-agente con scope ambiguo.**
 
 **Review ya aprobado**: Si el cambio objetivo ya tiene `.review-passed`, verifica si hay cambios posteriores al review:
 1. Lee la `date` del `.review-passed`.
-2. Compara con `git log --since="[date]" --oneline` y `git status --porcelain` para detectar commits o archivos modificados despues del review.
-3. **Si hay cambios nuevos**: elimina el `.review-passed` anterior y re-ejecuta el review completo para evaluar el estado actual.
-4. **Si NO hay cambios nuevos**: informa al usuario y no re-ejecutes:
+2. Compara con `git log --since="[date]" --oneline` y `git status --porcelain`.
+3. **Si hay cambios nuevos**: elimina el `.review-passed` anterior y continua (invoca al sub-agente para re-evaluar).
+4. **Si NO hay cambios nuevos**: informa al usuario y termina sin invocar al sub-agente:
    ```
    El cambio [nombre] ya tiene review aprobado ([verdict] — [date]) y no hay cambios posteriores.
    ```
 
-### Paso 1: Identificar que revisar
-
-Si hay un cambio activo en `openspec/changes/`, usalo como referencia.
-Si hay multiples cambios y el usuario ya selecciono uno, revisa solo ese cambio.
-Si el usuario paso un argumento ($ARGUMENTS), revisa ese archivo o carpeta especifica.
-Si no hay cambio activo ni argumento, revisa los cambios no commiteados (git diff).
-
-### Paso 2: Recopilar archivos a revisar
-
-- Lee los artefactos de OpenSpec si existen (specs, design)
-- Identifica todos los archivos creados/modificados
-- Lee cada archivo para entender los cambios
-
-### Paso 3: Evaluar contra checklist
-
-Para CADA item del [checklist.md](checklist.md), evalua:
-
-- **PASS**: Cumple completamente
-- **FAIL**: No cumple (incluir explicacion y como corregir)
-- **N/A**: No aplica a este cambio
-
-Se especifico en las evaluaciones. No des PASS generico — justifica brevemente.
+### Paso 1: Delegar al sub-agente refacil-auditor
 
-### Paso 3.1: Clasificar severidad en cada FAIL
+Invoca al sub-agente `refacil-auditor` pasandole:
+- El **scope resuelto** (nombre del cambio activo, rutas especificas, o "git-diff" para cambios no commiteados).
+- Si el usuario pidio modo detallado explicitamente, indicaselo (`mode: detailed`). Default: conciso.
 
-- **CRITICO**: Riesgo de seguridad, datos, o incumplimiento de spec.
-- **ALTO**: Puede romper funcionalidad, tests o despliegue.
-- **MEDIO**: Deuda tecnica relevante (arquitectura/mantenibilidad).
-- **BAJO**: Mejora recomendada no bloqueante.
+El sub-agente:
+- Lee los checklists (`checklist.md`, `checklist-back.md`, `checklist-front.md` segun aplique).
+- Lee los archivos del scope y los artefactos de OpenSpec.
+- Evalua cada item con PASS/FAIL/N/A + severidad en cada FAIL.
+- Retorna UN solo mensaje con el reporte + bloque JSON fenced como ` ```refacil-review-result `.
 
-Usa severidad para priorizar correcciones, no para inflar el reporte.
+### Paso 2: Procesar el reporte del sub-agente
 
-### Paso 4: Reporte
-
-Por defecto, usa salida **concisa** (segun `METHODOLOGY-CONTRACT.md`):
+El sub-agente retorna algo asi:
 
 ```
 === Review Report ===
 VEREDICTO: APROBADO | APROBADO CON OBSERVACIONES | REQUIERE CORRECCIONES
-BLOCKERS: [si/no]
+BLOCKERS: si | no
 
 ## Hallazgos priorizados (solo FAIL, maximo 5)
-1. [CRITICO|ALTO|MEDIO|BAJO] [seccion/item] — [problema]
-   - Evidencia: [archivo/rango o comportamiento]
-   - Correccion sugerida: [accion concreta]
+...
 
 ## Correcciones minimas para aprobar
-1. [item accionable]
-2. [item accionable]
+...
 
 Siguiente paso: [/refacil:archive | /refacil:verify]
+
+```refacil-review-result
+{
+  "verdict": "APROBADO" | "APROBADO CON OBSERVACIONES" | "REQUIERE CORRECCIONES",
+  "date": "<ISO>",
+  "changeName": "<nombre-cambio o null>",
+  "summary": "<resumen 1 linea>",
+  "failCount": <int>,
+  "blockers": <bool>
+}
+```
 ```
 
-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.
+Muestra al usuario el **reporte conciso** (todo lo anterior al bloque `refacil-review-result`). No muestres el bloque JSON — es metadata interna.
 
-### Paso 5: Marcador de review (obligatorio si APROBADO)
+**Si el sub-agente retorno `SCOPE_ERROR: <razon>`**: propaga el error al usuario y pide clarificacion. No escribas marker.
 
-Si el veredicto es **APROBADO** o **APROBADO CON OBSERVACIONES**, crea un archivo marcador en el directorio del cambio activo:
+### Paso 3: Crear marcador `.review-passed` (si aplica)
 
-**Ruta:** `openspec/changes/[nombre-cambio]/.review-passed`
+Parsea el bloque ` ```refacil-review-result ` del sub-agente. Si `verdict` es **APROBADO** o **APROBADO CON OBSERVACIONES** y `changeName` no es null:
 
-**Contenido (JSON):**
+**Ruta:** `openspec/changes/<changeName>/.review-passed`
+
+**Contenido (el JSON parseado del bloque, verbatim):**
 ```json
 {
   "verdict": "APROBADO|APROBADO CON OBSERVACIONES",
-  "date": "<fecha ISO actual>",
+  "date": "<ISO>",
   "changeName": "<nombre-cambio>",
-  "summary": "<resumen de 1 linea del resultado>",
-  "failCount": <numero de FAILs encontrados>,
+  "summary": "<resumen 1 linea>",
+  "failCount": <int>,
   "blockers": false
 }
 ```
 
-Este archivo es evidencia de que el review se completo y es requerido por el hook de `PreToolUse` antes de permitir `git push`. No lo crees si el veredicto es REQUIERE CORRECCIONES.
+**No crees el marker si:**
+- `verdict` es `REQUIERE CORRECCIONES`.
+- `changeName` es null (review de git-diff o de archivos sueltos sin cambio activo).
+- El sub-agente retorno `SCOPE_ERROR`.
+
+Este archivo es evidencia de que el review se completo y es requerido por el hook `PreToolUse` antes de permitir `git push`.
 
 ## Reglas
 
-- Ser constructivo: no solo decir que falla, sino como corregirlo
-- No ser excesivamente estricto con N/A — si no aplica, marcarlo
-- Si todo es PASS, felicitar brevemente y sugerir `/refacil:archive`
-- Si hay FAILs criticos (seguridad, tests), marcar como bloqueantes y sugerir `/refacil:verify` para aplicar correcciones con asistencia de la IA
-- No reportar ruido: evita listar mejoras cosmeticas como bloqueantes
-- Si hay demasiados hallazgos, prioriza los 5 de mayor impacto primero
-- Usa modo **conciso** por defecto; si el usuario pide detalle, entrega el reporte completo por secciones
+- **Siempre delega al sub-agente**. No repliques la logica de checklists ni de evaluacion aqui — eso vive en `refacil-auditor`.
+- **El marker lo crea este skill, no el sub-agente**. Es la unica operacion de escritura, y queda fuera del contexto aislado del sub-agente (compatible con `readonly: true` de Cursor).
+- **No muestres el bloque JSON al usuario**. Es solo para que tu (el wrapper) escribas el marker.
+- Si el sub-agente retorno algo fuera de formato (sin bloque JSON parseable y no es `SCOPE_ERROR`), informa al usuario: "El reviewer retorno un reporte no estructurado — no se creo marker. Revisa el reporte manualmente."
+
+## Ver tambien
+
+- Sub-agente: `.claude/agents/refacil-auditor.md` (fuente: `refacil-sdd-ai/agents/reviewer.md`)
+- Checklists: `checklist.md`, `checklist-back.md`, `checklist-front.md` en este mismo directorio.

package/skills/verify/SKILL.md

@@ -1,101 +1,97 @@
 ---
 name: refacil:verify
-description: Validar que la implementacion cumple con las specs — verifica completitud, correccion y coherencia del cambio
+description: Validar que la implementacion cumple con las specs — delega al sub-agente refacil-validator para el reporte y maneja correcciones con aprobacion del usuario
 user-invocable: true
 ---
 
-# refacil:verify — Verificacion de Implementacion
+# refacil:verify — Entrypoint de Verificacion
 
-Este comando envuelve la funcionalidad de OpenSpec verify y agrega verificacion de tests.
+Este skill es un **wrapper** que delega el analisis pesado (lectura de specs + tests + archivos) al sub-agente `refacil-validator`, y maneja la interaccion con el usuario para aplicar correcciones cuando hay issues.
 
 **Prerequisitos**: perfil `openspec` de `refacil-prereqs/SKILL.md` + reglas de `METHODOLOGY-CONTRACT.md`.
 
-## Instrucciones
+## Flujo
 
-### Paso 1: Delegar a OpenSpec verify
+### Paso 0: Resolver scope
 
-1. Lee `openspec-verify-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
-2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **idioma**).
-3. Sigue OpenSpec con argumento **$ARGUMENTS** (reporte con issues CRITICAL/WARNING/SUGGESTION).
+Determina el scope antes de invocar al sub-agente. Prioriza este orden:
+1. Argumento del usuario (`$ARGUMENTS`).
+2. Cambio activo en `openspec/changes/`.
+3. Si hay multiples cambios activos y no hay `$ARGUMENTS`, **detente** y pide al usuario seleccionar explicitamente cual cambio validar.
 
-### Paso 2: Verificar tests (aporte Refacil)
+No invoques al sub-agente con scope ambiguo.
 
-Ademas de la verificacion de OpenSpec, resuelve y ejecuta el comando de tests segun `refacil-prereqs/METHODOLOGY-CONTRACT.md` y verifica:
-- Todos los tests pasan
-- Los tests cubren los criterios de aceptacion de la spec
-- No hay tests faltantes para requisitos clave
-- Si hay comando de coverage del proyecto, ejecutalo y reporta el porcentaje; si no existe, reporta N/A con justificacion
+### Paso 1: Delegar al sub-agente refacil-validator
 
-### Paso 3: Reporte combinado (aporte Refacil)
+Invoca a `refacil-validator` pasandole:
+- El scope resuelto (nombre del cambio activo o rutas).
+- Si el usuario pidio modo detallado, indicaselo (`mode: detailed`). Default: conciso.
 
-Combina el reporte de OpenSpec con la verificacion de tests en un reporte unificado:
+El sub-agente:
+- Delega a OpenSpec verify para issues contra la spec.
+- Resuelve y corre el comando de tests del proyecto + coverage si aplica.
+- Opcionalmente consulta el bus cross-repo ante ambigüedades.
+- Retorna reporte combinado + bloque JSON fenced como ` ```refacil-verify-result `.
 
-```
-=== Reporte de Verificacion ===
-
---- OpenSpec Verify ---
-[Resultados del reporte de OpenSpec: CRITICAL, WARNING, SUGGESTION]
-
---- Tests (Refacil) ---
- [PASS/FAIL] Comando de tests: [comando]
- [PASS/FAIL] Tests ejecutados: [N]
- [PASS/FAIL] Tests pasaron: [N]
- [PASS/FAIL/N/A] Coverage: [X]% (minimo requerido: 80%)
+### Paso 2: Presentar el reporte
 
-RESULTADO: APROBADO / REQUIERE CORRECCIONES
-
-Correcciones necesarias:
-1. [issues de OpenSpec]
-2. [issues de tests]
-```
+Muestra el **reporte combinado** (todo lo anterior al bloque `refacil-verify-result`) al usuario. No muestres el bloque JSON — es metadata interna.
 
-### Paso 3.5: Validar ambigüedades cross-repo (opcional)
+**Si el sub-agente retorno un error de scope** (sin bloque JSON): propaga al usuario y pide clarificacion.
 
-Si durante la verificacion detectas que la spec no cubre algo relevante del lado de un consumidor o productor externo (formato que otro repo espera, evento que otro repo emite, comportamiento del consumidor bajo cierta condicion), y esa ambigüedad impide decidir si la implementacion es correcta, **no asumas** — aplica el protocolo de `refacil-prereqs/BUS-CROSS-REPO.md` para resolverlo con el agente del otro repo via el bus antes de cerrar el reporte.
+### Paso 3: Procesar el resultado
 
-Incorpora la respuesta al reporte combinado como SUGGESTION; si revela un bug real, escalalo a WARNING/CRITICAL.
+Parsea el bloque ` ```refacil-verify-result ` del sub-agente.
 
-### Paso 4: Resultado y siguiente paso
+#### Si `result` es APROBADO (sin issues CRITICAL ni WARNING):
 
-#### Si APROBADO (sin issues CRITICAL ni WARNING):
+Felicita y sugiere:
+```
+RESULTADO: APROBADO
 
-"Ejecuta `/refacil:review` para el review con checklist del equipo."
+Siguiente paso: `/refacil:review` para el review con checklist del equipo.
+```
 
-#### Si REQUIERE CORRECCIONES (hay issues CRITICAL o WARNING):
+#### Si `result` es REQUIERE CORRECCIONES:
 
-Presenta las correcciones necesarias y pregunta al usuario:
+Presenta los issues (ya vienen en el reporte) y pregunta:
 
 ```
 RESULTADO: REQUIERE CORRECCIONES
 
 Correcciones necesarias:
-1. [CRITICAL/WARNING] [descripcion del issue y como corregirlo]
-2. [CRITICAL/WARNING] [descripcion del issue y como corregirlo]
+1. [CRITICAL/WARNING] [descripcion] — [fix sugerido]
+2. ...
 
 Quieres que aplique estas correcciones? (si/no)
 - Si: aplicare los fixes y re-verificare automaticamente
 - No: puedes corregirlos manualmente y ejecutar /refacil:verify de nuevo
 ```
 
-**Si el usuario acepta:**
+### Paso 4: Aplicar correcciones (si el usuario acepta)
+
+**Solo aplica fixes despues de aprobacion explicita del usuario.**
 
 1. Aplica SOLO las correcciones listadas — no agregar funcionalidad nueva, no refactorizar codigo no relacionado, no cambiar nada fuera del alcance de los issues reportados.
 2. Si hay tests que necesitan ajuste por las correcciones, ajustarlos tambien.
 3. Muestra un resumen breve de los archivos modificados.
-4. Re-ejecuta automaticamente la verificacion completa (vuelve al Paso 1) para confirmar que las correcciones resolvieron los issues.
-5. Si la re-verificacion encuentra nuevos issues, repite este ciclo (maximo 2 rondas de correccion automatica). Si despues de 2 rondas aun hay issues, lista los pendientes para correccion manual.
+4. **Re-ejecuta automaticamente desde el Paso 1** (re-invoca al sub-agente) para confirmar que las correcciones resolvieron los issues.
+5. Si la re-verificacion encuentra nuevos issues, repite este ciclo (**maximo 2 rondas** de correccion automatica). Si despues de 2 rondas aun hay issues, lista los pendientes para correccion manual.
 
 **Si el usuario no acepta:**
 
-Lista los issues para que el usuario los corrija manualmente. Sugiere ejecutar `/refacil:verify` de nuevo cuando termine.
+Lista los issues para que el usuario los corrija manualmente. Sugiere `/refacil:verify` de nuevo cuando termine.
 
 ## Reglas
 
-- **verify NUNCA modifica codigo por cuenta propia** — los Pasos 1-3 son solo analisis y reporte
-- Las correcciones SOLO se aplican en el Paso 4, **despues** de presentar el reporte completo y recibir aprobacion explicita del usuario
-- Sin aprobacion explicita, verify termina en el reporte — no toca ningun archivo
-- Las correcciones deben ser quirurgicas: solo lo necesario para resolver los issues reportados
-- Ser estricto con los criterios de la spec
-- Si algo no esta en la spec pero parece necesario, mencionarlo como SUGGESTION (observacion), no como CRITICAL/WARNING
-- Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)
-- El Paso 3.5 (bus cross-repo) es **opcional** — solo invocarlo si hay una ambigüedad real cross-repo que bloquea el veredicto. Ver `refacil-prereqs/BUS-CROSS-REPO.md`.
+- **Siempre delega al sub-agente** para el analisis (pasos 1-3). No repliques aqui la logica de lectura de specs ni de ejecucion de tests.
+- **Las correcciones SOLO las aplica este wrapper** (Paso 4), despues de aprobacion explicita del usuario. El sub-agente es read-only.
+- **No muestres el bloque JSON al usuario**. Es solo metadata para parsear el resultado.
+- **Las correcciones deben ser quirurgicas**: solo lo necesario para resolver los issues reportados.
+- Maximo 2 rondas de correccion automatica antes de escalar a manual.
+- Si el sub-agente retorno algo fuera de formato (sin bloque JSON parseable), informa al usuario: "El validator retorno un reporte no estructurado — continua manualmente con las correcciones."
+
+## Ver tambien
+
+- Sub-agente: `.claude/agents/refacil-validator.md` (fuente: `refacil-sdd-ai/agents/validator.md`)
+- Bus cross-repo: `refacil-prereqs/BUS-CROSS-REPO.md`