refacil-sdd-ai 2.0.6 → 2.0.8

package/README.md

@@ -73,6 +73,34 @@ Una vez instalado, estos comandos estan disponibles en Claude Code y Cursor:
 | `/refacil:up-code` | Subir codigo a rama de desarrollo (con validacion de ramas protegidas) |
 | `/refacil:bug` | Flujo guiado completo para investigar y corregir bugs |
 
+## Uso rapido (guia de decision)
+
+Si no tienes claro que comando usar, aplica esta regla simple:
+
+- Quiero entender el sistema sin tocar codigo -> `/refacil:explore`
+- Quiero construir algo nuevo o cambiar comportamiento -> `/refacil:propose`
+- Ya aprobe artefactos y quiero implementar -> `/refacil:apply`
+- Quiero generar o completar pruebas -> `/refacil:test`
+- Quiero validar cumplimiento contra spec -> `/refacil:verify`
+- Quiero evaluacion de calidad tecnica -> `/refacil:review`
+- Ya termine y quiero cerrar el cambio en OpenSpec -> `/refacil:archive`
+- Quiero subir cambios y abrir PR -> `/refacil:up-code`
+- Tengo un error en produccion o bug funcional -> `/refacil:bug`
+
+## Flujo minimo recomendado (equipo)
+
+Para mantener trazabilidad y calidad sin pasos innecesarios:
+
+1. `/refacil:propose` (aprobacion humana obligatoria)
+2. `/refacil:apply`
+3. `/refacil:test`
+4. `/refacil:verify`
+5. `/refacil:review`
+6. `/refacil:archive`
+7. `/refacil:up-code`
+
+Si es bugfix, puedes iniciar con `/refacil:bug` y luego continuar en `review -> up-code`.
+
 ## Flujos de trabajo
 
 ### Feature nuevo
@@ -104,6 +132,26 @@ Una vez instalado, estos comandos estan disponibles en Claude Code y Cursor:
 /refacil:explore "que quiero entender"
 ```
 
+## Reglas metodologicas transversales
+
+Para mantener consistencia entre todas las skills, el paquete define un contrato metodologico unico en `skills/prereqs/METHODOLOGY-CONTRACT.md`:
+
+- Estados del flujo (Ready for Propose/Apply/Verify/Review/Archive/Merge)
+- Politica de `AGENTS.md` por perfil (`openspec` vs `agents`)
+- Resolucion de comando de tests multi-stack (sin hardcodear `npm test`)
+- Politica unificada de ramas protegidas y creacion de ramas
+- Modo de salida estandar: `conciso` por defecto, `detallado` bajo demanda
+
+### Checkpoints de estado (DoR/DoD)
+
+Antes de avanzar de etapa, valida estos estados:
+
+- `READY_FOR_APPLY`: artefactos SDD completos + aprobacion explicita
+- `READY_FOR_VERIFY`: implementacion terminada y enfocada al alcance
+- `READY_FOR_REVIEW`: verify ejecutado y bloqueantes tratados
+- `READY_FOR_ARCHIVE`: cambio funcionalmente cerrado
+- `READY_FOR_MERGE`: rama lista para PR
+
 ## Como funciona
 
 1. **`refacil-sdd-ai init`** copia las skills a `.claude/skills/` y `.cursor/skills/`, y crea `CLAUDE.md` + `.cursorrules`

package/bin/cli.js

@@ -135,6 +135,68 @@ function checkNodeVersion() {
   return true;
 }
 
+// --- Hook installation ---
+
+function installHook() {
+  const settingsDir = path.join(projectRoot, '.claude');
+  const settingsPath = path.join(settingsDir, 'settings.json');
+  let settings = {};
+
+  if (fs.existsSync(settingsPath)) {
+    settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8'));
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.SessionStart) settings.hooks.SessionStart = [];
+
+  // Skip if already installed (marked with _sdd)
+  const alreadyInstalled = settings.hooks.SessionStart.some(h => h._sdd === true);
+  if (alreadyInstalled) {
+    console.log('  Hook check-update ya configurado.');
+    return false;
+  }
+
+  settings.hooks.SessionStart.push({
+    _sdd: true,
+    matcher: '',
+    hooks: [
+      {
+        type: 'command',
+        command: 'refacil-sdd-ai check-update',
+      },
+    ],
+  });
+
+  fs.mkdirSync(settingsDir, { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  return true;
+}
+
+// --- Check update ---
+
+function checkUpdate() {
+  const { execSync } = require('child_process');
+  const localVersion = require(path.join(packageRoot, 'package.json')).version;
+
+  try {
+    const latest = execSync('npm view refacil-sdd-ai version', {
+      encoding: 'utf8',
+      timeout: 10000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+
+    if (latest && latest !== localVersion) {
+      console.log(
+        `[refacil-sdd-ai] La metodologia SDD-AI tiene una nueva version disponible: v${localVersion} (instalada) -> v${latest} (disponible en npm). ` +
+        'Informa al usuario que hay una actualizacion disponible y preguntale si desea actualizar ahora. ' +
+        `Si acepta, ejecuta: npm update -g refacil-sdd-ai && refacil-sdd-ai update`,
+      );
+    }
+  } catch (_) {
+    // Silent on error (no internet, registry unreachable, etc.)
+  }
+}
+
 // --- Commands ---
 
 function init() {
@@ -160,6 +222,11 @@ function init() {
     console.log('  .cursorrules OK');
   }
 
+  // Install SessionStart hook for version check
+  if (installHook()) {
+    console.log('  Hook check-update agregado a .claude/settings.json');
+  }
+
   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');
@@ -192,10 +259,11 @@ function help() {
   refacil-sdd-ai — Metodologia SDD-AI con OpenSpec
 
   Comandos:
-    init      Instala skills en .claude/ y .cursor/, crea CLAUDE.md y .cursorrules
-    update    Re-copia skills (para actualizar a nueva version del paquete)
-    clean     Elimina skills de .claude/ y .cursor/
-    help      Muestra esta ayuda
+    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
+    clean         Elimina skills de .claude/ y .cursor/
+    help          Muestra esta ayuda
 
   Flujo completo:
     1. npm install -g refacil-sdd-ai
@@ -220,6 +288,9 @@ switch (command) {
   case 'update':
     update();
     break;
+  case 'check-update':
+    checkUpdate();
+    break;
   case 'clean':
     clean();
     break;

package/package.json

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

package/skills/apply/SKILL.md

@@ -11,74 +11,48 @@ Este comando envuelve la funcionalidad de OpenSpec apply y agrega las convencion
 ## 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.
 
 ## Instrucciones
 
 ### Paso 0: Verificar que existan artefactos SDD
 
-Busca carpetas en `openspec/changes/` que contengan los artefactos requeridos: `proposal.md`, `specs.md`, `design.md`, `tasks.md`.
+Por cada carpeta bajo `openspec/changes/` (excluye `archive/` si aplica), comprueba:
 
-- **Si `openspec/changes/` no existe o esta vacia**: Informa al usuario:
-  ```
-  No hay cambios propuestos. Antes de implementar necesitas definir los artefactos SDD.
-  Ejecuta: /refacil:propose "descripcion del cambio"
-  ```
-  **Detente.**
+| Artefacto | Requisito |
+|-----------|-----------|
+| `proposal.md` | Obligatorio en la raiz del cambio |
+| `design.md` | Obligatorio en la raiz del cambio |
+| `tasks.md` | Obligatorio en la raiz del cambio |
+| **Especificacion** | **`specs.md` en la raiz** **O** al menos un `.md` bajo `specs/` del cambio (recursivo, ej. `specs/foo/spec.md`) |
+
+OpenSpec a veces solo genera el arbol `specs/**/*.md`; eso **cumple** la fila de especificacion. Ver `OPENSPEC-DELTAS.md` (seccion **Specs: archivo unico vs arbol**).
+
+- **Si `openspec/changes/` no existe o no hay cambios activos**: informa que ejecute `/refacil:propose` y **detente**.
 
-- **Si hay carpetas pero les faltan artefactos** (falta proposal.md, specs.md, design.md o tasks.md): Informa al usuario:
+- **Si falta proposal, design o tasks**, o **no hay ni `specs.md` ni ningun `.md` bajo `specs/`**:
   ```
   El cambio en openspec/changes/[nombre]/ esta incompleto.
-  Faltan: [lista de artefactos faltantes]
+  Faltan: [lista]
   Ejecuta: /refacil:propose para completar los artefactos antes de implementar.
   ```
   **Detente.**
 
-- **Si hay multiples cambios activos**: Lista las carpetas y pregunta cual implementar.
+- **Multiples cambios activos**: lista carpetas y pregunta cual implementar.
 
-- **Si los 4 artefactos existen**: Continua al siguiente paso.
+- **Antes de implementar**: lee **toda** la especificacion relevante — si hay `specs.md` y ademas `specs/**/*.md`, lee **ambos**; si hay contradiccion, pregunta al usuario.
 
-**IMPORTANTE**: Este comando NUNCA genera artefactos SDD. Si no existen, el usuario debe usar `/refacil:propose`. La separacion entre planificacion e implementacion es fundamental en la metodologia SDD-AI.
+**IMPORTANTE**: Este comando NUNCA genera artefactos SDD. Si no existen, el usuario debe usar `/refacil:propose`.
 
 ### Paso 1: Validar rama de trabajo
 
 Ejecuta `git branch --show-current` para obtener la rama actual.
 
-#### Ramas protegidas: `master`, `main`, `develop`, `dev`, `testing`, `qa`
-
-- **Si la rama es cualquier rama protegida** (`master`, `main`, `develop`, `dev`, `testing`, `qa`):
-
-  Informa al usuario que no se pueden hacer cambios directamente en esa rama y **pidele el numero de tarea de Jira**:
-  ```
-  Estas en la rama '[nombre-rama]' que es una rama protegida.
-  No se deben hacer cambios directamente aqui.
-
-  Cual es el numero de tarea de Jira para este cambio? (ejemplo: RF-5088)
-  ```
+Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
 
-  **Crear la rama siempre desde develop/dev actualizado:**
-  1. **Verificar working directory limpio**: Ejecuta `git status --porcelain`. Si hay cambios sin commitear (archivos modificados o sin trackear), informa al usuario:
-     ```
-     Hay cambios sin commitear en la rama actual.
-     Para cambiar de rama de forma segura, necesito guardarlos temporalmente con git stash.
-     Quieres que haga git stash antes de continuar?
-     ```
-     - Si acepta: ejecuta `git stash push -m "stash-automatico-refacil"` y continua. Al final del proceso (despues de crear la rama), ejecuta `git stash pop` para restaurar los cambios.
-     - Si no acepta: **detente**.
-  2. Detecta cual existe en el repo: `develop` o `dev` (ejecuta `git branch --list develop dev`)
-  3. Cambia a esa rama: `git checkout develop` (o `dev`)
-  4. Actualiza: `git pull origin develop` (o `dev`)
-  5. Determina el nombre de la nueva rama:
-     - Si el usuario entrego el numero de Jira (ej: `RF-5088`): la rama sera `feature/RF-5088`
-     - Si el usuario no tiene tarea de Jira: usa un nombre descriptivo corto basado en el cambio activo en openspec/changes/ (ej: `feature/agregar-filtro-productos`). Pero **recomienda crear la tarea en Jira** para trazabilidad.
-  6. Verifica que la rama no exista ya: `git branch --list [nombre-rama]`
-     - Si ya existe, informa al usuario y pregunta si quiere cambiarse a esa rama existente o elegir otro nombre.
-  7. Crea la rama: `git checkout -b [nombre-rama]`
-  8. Si se hizo stash en el paso 1, ejecuta `git stash pop` para restaurar los cambios.
-
-  Si el usuario no acepta crear rama, **detente**.
-
-- **Si la rama es cualquier otra** (feature/, fix/, hotfix/, refactor/, etc.):
-  La rama es valida. Continua con el siguiente paso sin interrumpir.
+- Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
+- Para `refacil:apply`, el prefijo sugerido de rama es `feature/`.
+- Si la rama actual ya es de trabajo (feature/fix/hotfix/refactor/etc.), continuar sin interrumpir.
 
 ### Paso 2: Delegar a OpenSpec apply
 
@@ -104,7 +78,7 @@ Al terminar la implementacion de OpenSpec, agrega este resumen:
 
 ## Reglas
 
-- NUNCA implementar codigo sin los 4 artefactos SDD completos (proposal.md, specs.md, design.md, tasks.md)
+- 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
 - Si `openspec/changes/` no tiene cambios activos o estan incompletos, informar y redirigir a `/refacil:propose`

package/skills/archive/SKILL.md

@@ -11,6 +11,7 @@ Este comando envuelve la funcionalidad de OpenSpec archive (que internamente lla
 ## 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.
 
 ## Instrucciones
 
@@ -20,7 +21,7 @@ Antes de archivar, verifica que el cambio esta realmente completo:
 
 1. **Tasks completadas**: Busca el `tasks.md` del cambio y verifica que todas las tasks tienen checkbox marcado (`[x]`). Si hay tasks sin completar, informa al usuario y pregunta si quiere continuar de todas formas.
 
-2. **Tests pasan**: Ejecuta `npm test` y verifica que pasan. Si hay tests que fallan, informa y pregunta si quiere continuar.
+2. **Tests pasan**: Resuelve y ejecuta el comando de tests segun `refacil-prereqs/METHODOLOGY-CONTRACT.md`. Si hay tests que fallan, informa y pregunta si quiere continuar.
 
 3. **Sin archivos pendientes**: Ejecuta `git status` y verifica si hay cambios sin commitear relacionados al feature. Si los hay, sugiere hacer commit antes de archivar.
 
@@ -38,7 +39,7 @@ Despues de que OpenSpec archive, verifica que `openspec/specs/` fue actualizada:
 
 1. Revisa si hay archivos nuevos o modificados en `openspec/specs/`
 2. Si la sincronizacion no ocurrio (OpenSpec la salto o fallo), ejecuta manualmente la sincronizacion:
-   - Lee el `specs.md` del cambio archivado
+   - Lee la especificacion del cambio archivado: `specs.md` si existe **y** todos los `.md` bajo `specs/` de esa carpeta (misma regla que `refacil:apply`)
    - Busca el spec principal relevante en `openspec/specs/`
    - Si existe, integra los cambios (ADDED → agregar, MODIFIED → actualizar, REMOVED → eliminar)
    - Si NO existe, crea un spec principal nuevo con nombre descriptivo
@@ -70,3 +71,4 @@ Tip: Ejecuta /refacil:up-code para subir los cambios a tu rama de desarrollo.
 - Siempre verificar completitud antes de archivar
 - La sincronizacion de specs es OBLIGATORIA en la metodologia Refacil
 - No eliminar artefactos, solo moverlos a archive/ para trazabilidad
+- Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)

package/skills/bug/SKILL.md

@@ -11,6 +11,7 @@ Eres un asistente especializado en investigacion y correccion de bugs. Guias al
 ## 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.
 
 ## Instrucciones
 
@@ -67,42 +68,11 @@ Espera aprobacion del usuario antes de implementar.
 
 **ANTES de implementar cualquier cambio**, ejecuta `git branch --show-current` para obtener la rama actual.
 
-#### Ramas protegidas: `master`, `main`, `develop`, `dev`, `testing`, `qa`
-
-- **Si la rama es cualquier rama protegida** (`master`, `main`, `develop`, `dev`, `testing`, `qa`):
-
-  Informa al usuario que no se pueden hacer cambios directamente en esa rama y **pidele el numero de tarea de Jira**:
-  ```
-  Estas en la rama '[nombre-rama]' que es una rama protegida.
-  No se deben hacer cambios directamente aqui.
-
-  Cual es el numero de tarea de Jira para este fix? (ejemplo: RF-5088)
-  ```
-
-  **Crear la rama siempre desde develop/dev actualizado:**
-  1. **Verificar working directory limpio**: Ejecuta `git status --porcelain`. Si hay cambios sin commitear (archivos modificados o sin trackear), informa al usuario:
-     ```
-     Hay cambios sin commitear en la rama actual.
-     Para cambiar de rama de forma segura, necesito guardarlos temporalmente con git stash.
-     Quieres que haga git stash antes de continuar?
-     ```
-     - Si acepta: ejecuta `git stash push -m "stash-automatico-refacil"` y continua. Al final del proceso (despues de crear la rama), ejecuta `git stash pop` para restaurar los cambios.
-     - Si no acepta: **detente**.
-  2. Detecta cual existe en el repo: `develop` o `dev` (ejecuta `git branch --list develop dev`)
-  3. Cambia a esa rama: `git checkout develop` (o `dev`)
-  4. Actualiza: `git pull origin develop` (o `dev`)
-  5. Determina el nombre de la nueva rama:
-     - Si el usuario entrego el numero de Jira (ej: `RF-5088`): la rama sera `fix/RF-5088`
-     - Si el usuario no tiene tarea de Jira: usa un nombre descriptivo corto del bug (ej: `fix/error-calculo-total`). Pero **recomienda crear la tarea en Jira** para trazabilidad.
-  6. Verifica que la rama no exista ya: `git branch --list [nombre-rama]`
-     - Si ya existe, informa al usuario y pregunta si quiere cambiarse a esa rama existente o elegir otro nombre.
-  7. Crea la rama: `git checkout -b [nombre-rama]`
-  8. Si se hizo stash en el paso 1, ejecuta `git stash pop` para restaurar los cambios.
-
-  Si el usuario no acepta crear rama, **detente**.
-
-- **Si la rama es cualquier otra** (feature/, fix/, hotfix/, etc.):
-  La rama es valida. Continua sin interrumpir.
+Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
+
+- Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
+- Para `refacil:bug`, el prefijo sugerido de rama es `fix/`.
+- Si la rama actual ya es de trabajo (feature/fix/hotfix/refactor/etc.), continuar sin interrumpir.
 
 ### Paso 6: Implementar el fix
 
@@ -135,7 +105,7 @@ describe('Bug Fix: [descripcion corta]', () => {
 
 ### Paso 8: Verificar
 
-1. Ejecuta `npm test` — todos los tests deben pasar
+1. Resuelve el comando de tests segun `METHODOLOGY-CONTRACT.md` y ejecutalo — todos los tests deben pasar
 2. Muestra resumen del fix
 
 ```
@@ -145,7 +115,7 @@ describe('Bug Fix: [descripcion corta]', () => {
  Fix: [que se cambio]
  Archivos modificados: [lista]
  Tests de regresion: [N] tests agregados
- npm test: PASS
+ [comando-test]: PASS
 
  Siguientes pasos:
  1. /refacil:review — Review del fix (recomendado para bugs criticos)
@@ -156,7 +126,7 @@ describe('Bug Fix: [descripcion corta]', () => {
 
 Si el bug es significativo, preguntar al usuario si quiere documentarlo en OpenSpec:
 - Crear carpeta en `openspec/changes/fix-[nombre]/`
-- Generar proposal.md y specs.md con los detalles del bug y fix
+- Generar `proposal.md`, `design.md`, `tasks.md` y especificacion (`specs.md` y/o `specs/**/*.md`, misma regla que `refacil:propose`)
 
 ## Reglas
 
@@ -166,3 +136,4 @@ Si el bug es significativo, preguntar al usuario si quiere documentarlo en OpenS
 - Los tests de regresion son OBLIGATORIOS
 - Si el bug es en produccion (critico), priorizar velocidad pero sin saltarse tests
 - Responder en español con terminos tecnicos en ingles
+- Usa modo de salida **conciso** por defecto y **detallado** solo si el usuario lo pide (ver `METHODOLOGY-CONTRACT.md`)

package/skills/prereqs/METHODOLOGY-CONTRACT.md

@@ -0,0 +1,57 @@
+# Contrato Metodologico SDD-AI (Refacil)
+
+Este archivo centraliza reglas transversales para evitar duplicacion e inconsistencias entre skills.
+
+## 1) Estados del flujo (Definition of Ready / Done)
+
+- **READY_FOR_PROPOSE**: problema entendido (objetivo, alcance, restricciones) y contexto minimo del repo.
+- **READY_FOR_APPLY**: artefactos SDD completos (`proposal.md`, `design.md`, `tasks.md`, especificacion en `specs.md` y/o `specs/**/*.md`) y aprobacion explicita del usuario.
+- **READY_FOR_VERIFY**: implementacion terminada, sin cambios fuera de alcance.
+- **READY_FOR_REVIEW**: verify ejecutado, issues criticos resueltos o explicitamente aceptados por el usuario.
+- **READY_FOR_ARCHIVE**: tasks completas o excepciones aprobadas, verificacion ejecutada, cambio funcionalmente cerrado.
+- **READY_FOR_MERGE**: review aprobado y rama remota actualizada para PR.
+
+## 2) Politica AGENTS.md
+
+- Si una skill requiere perfil `openspec`: `AGENTS.md` es obligatorio (si falta, detener y redirigir a `/refacil:setup`).
+- Si una skill requiere perfil `agents`: si falta `AGENTS.md`, continuar con baseline generico y reportar limitacion al usuario.
+
+## 3) Resolucion de comando de tests (multi-stack)
+
+No hardcodear `npm test` salvo que sea realmente el comando del proyecto.
+
+Orden de deteccion:
+1. Si `AGENTS.md` define comando oficial de tests, usar ese.
+2. Si existe script de package manager (ej. `npm test`, `pnpm test`, `yarn test`, `bun test`), usar el correspondiente.
+3. Si es Python: `pytest`.
+4. Si es Go: `go test ./...`.
+5. Si es Rust: `cargo test`.
+6. Si es Java/Gradle: `./gradlew test` o `gradle test`.
+7. Si es Java/Maven: `mvn test`.
+
+Coverage (si aplica): detectar comando del proyecto (`test:cov`, `coverage`, `pytest --cov`, etc.). Si no existe, reportar N/A con justificacion.
+
+## 4) Politica de ramas protegidas y creacion de rama
+
+Ramas protegidas: `master`, `main`, `develop`, `dev`, `testing`, `qa`.
+
+Si la rama actual es protegida:
+1. Informar y pedir identificador de tarea (Jira u otro).
+2. Verificar working directory limpio (`git status --porcelain`).
+3. Si hay cambios sin commitear, pedir aprobacion para `git stash push -m "stash-automatico-refacil"`.
+4. Detectar base (`develop` o `dev`), cambiar y actualizar (`git pull origin <base>`).
+5. Crear rama de trabajo:
+   - Feature: `feature/<ID>`
+   - Bugfix: `fix/<ID>`
+   - Sin ID: nombre descriptivo corto y recomendar crear ticket.
+6. Restaurar `stash` si se uso.
+7. Si el usuario no aprueba el proceso, detener.
+
+## 5) Politica de salida (UX)
+
+Modo por defecto: **conciso**.
+
+- **Conciso**: veredicto + blockers + maximo 5 hallazgos priorizados + siguiente paso.
+- **Detallado**: reporte completo por seccion.
+
+Si el usuario no pide detalle, usa modo conciso.

package/skills/prereqs/OPENSPEC-DELTAS.md

@@ -15,12 +15,26 @@ Lee este archivo **ademas** de la skill `openspec-*` que indique el comando `ref
 - Tasks con estimacion de esfuerzo **S / M / L**.
 - Design alineado a **patrones existentes** del repo (desde `AGENTS.md` o exploracion acotada).
 
+### Specs: archivo unico vs arbol `specs/` (compatibilidad Refacil)
+
+OpenSpec puede indicar `specs/**/*.md` y crear **un archivo por capability** (ej. `specs/product-amount-percentile/spec.md`). Los comandos **refacil:*** deben soportar **ambas** formas:
+
+| Forma | Validacion |
+|-------|------------|
+| **A** | `specs.md` en la raiz del cambio (`openspec/changes/<id>/specs.md`) |
+| **B** | Sin `specs.md`, pero existe al menos un `.md` bajo `openspec/changes/<id>/specs/` (recursivo) |
+
+- **Si OpenSpec solo genera B:** no es error. **No hace falta** duplicar obligatoriamente en `specs.md` salvo que el equipo quiera un indice unico para humanos.
+- **Si coexisten A y B:** lee **ambos**; si hay contradiccion clara entre `specs.md` y los fragmentos, **pregunta al usuario** cual manda antes de `apply`.
+- Al cerrar **propose**, en el resumen de revision lista **todas** las rutas de spec (archivo raiz y/o cada `specs/**.md`).
+
 ## apply — `openspec-apply-change`
 
 - Respetar **estrictamente** `AGENTS.md`.
 - No agregar funcionalidad fuera del alcance de las specs aprobadas.
 - No refactorizar codigo no relacionado con el cambio.
 - Si una task es ambigua, **preguntar** antes de implementar.
+- **Especificacion**: aplica la tabla del Paso 0 de `refacil:apply` (`specs.md` y/o `specs/**/*.md`); no asumas que solo existe `specs.md` en la raiz.
 
 ## archive — `openspec-archive-change`
 

package/skills/prereqs/SKILL.md

@@ -9,6 +9,7 @@ user-invocable: false
 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.
 
 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.
 
 ## Perfil `openspec` (OpenSpec + repo + AGENTS.md)
 
@@ -26,7 +27,8 @@ Usar cuando la skill diga: *Aplica el perfil `openspec`.*
 
 Usar cuando la skill diga: *Aplica el perfil `agents`.*
 
-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**.
+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
 

package/skills/propose/SKILL.md

@@ -36,7 +36,7 @@ Si $ARGUMENTS ya es claro, no preguntes de nuevo.
 Despues de que OpenSpec genere los artefactos, presenta al usuario un resumen claro para su revision:
 
 1. **Proposal**: Objetivo, alcance y justificacion del cambio
-2. **Specs**: Criterios de aceptacion y rechazo — verificar que cubran todos los escenarios
+2. **Specs**: Criterios de aceptacion y rechazo — listar **rutas reales**: `specs.md` y/o cada `specs/**/spec.md` (OpenSpec puede usar solo el arbol `specs/`)
 3. **Design**: Archivos a crear/modificar y patrones a usar — verificar que se alineen con la arquitectura
 4. **Tasks**: Lista de tareas con estimacion — verificar que el desglose sea correcto y completo
 
@@ -46,7 +46,7 @@ Pregunta explicitamente:
 === Revision requerida ===
 Los artefactos estan listos para tu revision:
  - openspec/changes/[nombre]/proposal.md
- - openspec/changes/[nombre]/specs.md
+ - Especificacion: openspec/changes/[nombre]/specs.md y/o openspec/changes/[nombre]/specs/**/*.md (listar archivos)
  - openspec/changes/[nombre]/design.md
  - openspec/changes/[nombre]/tasks.md
 
@@ -69,7 +69,7 @@ Siguiente paso: ejecuta /refacil:apply para implementar las tasks.
 
 ## Reglas
 
-- **NUNCA escribir, modificar o generar codigo fuente** en esta fase — solo artefactos SDD (proposal.md, specs.md, design.md, tasks.md)
+- **NUNCA escribir, modificar o generar codigo fuente** en esta fase — solo artefactos SDD: `proposal.md`, `design.md`, `tasks.md`, y especificacion en `specs.md` y/o `specs/**/*.md` (convencion OpenSpec)
 - Aunque el usuario pase una descripcion completa y detallada en $ARGUMENTS, la salida es EXCLUSIVAMENTE artefactos de planificacion
 - Si el usuario pide que tambien implemente, responder: "La implementacion se hace con `/refacil:apply` despues de aprobar los artefactos."
 - Siempre explorar el codebase ANTES de generar artefactos (para que el design sea realista)

package/skills/review/SKILL.md

@@ -11,10 +11,19 @@ Eres un reviewer exigente pero constructivo que evalua el codigo contra el check
 ## 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` y aplica el modo de salida definido ahi.
 Lee el archivo [checklist.md](checklist.md) para conocer los criterios de evaluacion.
 
 ## Instrucciones
 
+### Paso 0: Definir alcance (obligatorio)
+
+- Determina el alcance real del review antes de evaluar.
+- Prioriza este orden:
+  1) Argumento del usuario (`$ARGUMENTS`)
+  2) Cambio activo en `openspec/changes/`
+  3) Cambios no commiteados (`git diff`)
+
 ### Paso 1: Identificar que revisar
 
 Si hay un cambio activo en `openspec/changes/`, usalo como referencia.
@@ -37,67 +46,42 @@ Para CADA item del [checklist.md](checklist.md), evalua:
 
 Se especifico en las evaluaciones. No des PASS generico — justifica brevemente.
 
+### Paso 3.1: 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 correcciones, no para inflar el reporte.
+
 ### Paso 4: Reporte
 
 ```
 === Review Report ===
 
-## 1. Conformidad con Spec
- [PASS/FAIL/N/A] Todos los criterios de aceptacion cubiertos
- [PASS/FAIL/N/A] No hay funcionalidad fuera del alcance
- [PASS/FAIL/N/A] Edge cases manejados
-
-## 2. Calidad de Codigo
- [PASS/FAIL/N/A] Sigue patrones del repo
- [PASS/FAIL/N/A] Sin codigo duplicado
- [PASS/FAIL/N/A] Nombres claros y descriptivos
- [PASS/FAIL/N/A] Sin console.log/TODO/codigo comentado
- [PASS/FAIL/N/A] Imports usan alias del proyecto
-
-## 3. Arquitectura
- [PASS/FAIL/N/A] Limites de dominio respetados
- [PASS/FAIL/N/A] Dependencias en direccion correcta
- [PASS/FAIL/N/A] Sin logica de negocio en infraestructura
-
-## 4. Testing
- [PASS/FAIL/N/A] Cada archivo tiene su .spec.ts
- [PASS/FAIL/N/A] Tests cubren criterios de aceptacion
- [PASS/FAIL/N/A] Edge cases testeados
- [PASS/FAIL/N/A] Coverage >= 80%
- [PASS/FAIL/N/A] npm test pasa sin errores
-
-## 5. Seguridad
- [PASS/FAIL/N/A] Sin secrets hardcodeados
- [PASS/FAIL/N/A] Inputs validados
- [PASS/FAIL/N/A] Sin inyeccion SQL
- [PASS/FAIL/N/A] Endpoints con autorizacion
-
-## 6. Performance
- [PASS/FAIL/N/A] Queries usan indices
- [PASS/FAIL/N/A] Sin queries N+1
- [PASS/FAIL/N/A] Operaciones pesadas son async
-
-## 7. Mantenibilidad
- [PASS/FAIL/N/A] Codigo autoexplicativo
- [PASS/FAIL/N/A] Funciones hacen una sola cosa
- [PASS/FAIL/N/A] Archivos < 300 lineas
-
-## 8. Git y Deploy
- [PASS/FAIL/N/A] Commits atomicos
- [PASS/FAIL/N/A] Sin archivos generados en commit
- [PASS/FAIL/N/A] Migraciones reversibles (si aplica)
-
-## 9. Reglas especificas del proyecto
- [PASS/FAIL/N/A] Cumple reglas de "Siempre hacer" de AGENTS.md
- [PASS/FAIL/N/A] No viola reglas de "Nunca hacer" de AGENTS.md
- [PASS/FAIL/N/A] Reglas adicionales del proyecto (si aplica)
-
----
-RESUMEN: [X] PASS | [Y] FAIL | [Z] N/A
-VEREDICTO: APROBADO / REQUIERE CORRECCIONES
-
-Correcciones necesarias:
-1. [FAIL] [seccion] — [que corregir y como]
+VEREDICTO: APROBADO | APROBADO CON OBSERVACIONES | REQUIERE CORRECCIONES
+BLOCKERS: [si/no]
+
+## Hallazgos priorizados (solo FAIL)
+1. [CRITICO|ALTO|MEDIO|BAJO] [seccion/item] — [problema]
+   - Evidencia: [archivo/rango o comportamiento]
+   - Correccion sugerida: [accion concreta]
+
+## Checklist resumido
+- Conformidad con Spec: [PASS/FAIL/N/A]
+- Calidad de Codigo: [PASS/FAIL/N/A]
+- Arquitectura: [PASS/FAIL/N/A]
+- Testing: [PASS/FAIL/N/A]
+- Seguridad: [PASS/FAIL/N/A]
+- Performance: [PASS/FAIL/N/A]
+- Mantenibilidad: [PASS/FAIL/N/A]
+- Git y Deploy: [PASS/FAIL/N/A]
+- Reglas del proyecto (AGENTS.md): [PASS/FAIL/N/A]
+
+## Correcciones minimas para aprobar
+1. [item accionable]
+2. [item accionable]
 ```
 
 ## Reglas
@@ -106,3 +90,6 @@ Correcciones necesarias:
 - 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

package/skills/review/checklist.md

@@ -1,6 +1,15 @@
 # Checklist de Calidad — Equipo Refacil
 
 > **IMPORTANTE**: Este checklist es generico. Antes de evaluar, lee `AGENTS.md` del proyecto para adaptar cada seccion al stack, arquitectura y convenciones reales del repositorio. Si AGENTS.md indica patrones, frameworks o reglas especificas, usalas en lugar de los ejemplos genericos de abajo.
+> Si `AGENTS.md` no existe, aplica este checklist como baseline y marca N/A en reglas que dependan de convenciones no documentadas.
+
+## Como usar este checklist (metodologia)
+1. Define alcance de revision: `$ARGUMENTS` > `openspec/changes/` > `git diff`.
+2. Evalua primero bloqueantes: Spec, Testing y Seguridad.
+3. Luego evalua Calidad, Arquitectura, Performance y Mantenibilidad.
+4. Marca cada item como PASS, FAIL o N/A con una justificacion breve.
+5. Para cada FAIL, agrega severidad: CRITICO, ALTO, MEDIO o BAJO.
+6. Si hay muchos FAIL, prioriza los 5 de mayor impacto.
 
 ## 1. Conformidad con Spec
 - Todos los criterios de aceptacion de la spec estan cubiertos
@@ -12,7 +21,7 @@
 - El codigo sigue los patrones existentes del repo (consultar AGENTS.md seccion de arquitectura/convenciones)
 - No hay codigo duplicado que pueda extraerse
 - Los nombres de variables, funciones y clases son claros y descriptivos
-- No hay console.log, TODO, o codigo comentado sin razon
+- No hay `console.log` fuera de bloques `catch` (permitido solo para diagnostico de errores), TODO, o codigo comentado sin razon
 - Los imports usan los alias configurados del proyecto (consultar AGENTS.md seccion de alias de rutas, si aplica)
 - No hay dependencias circulares nuevas
 
@@ -50,7 +59,7 @@
 ## 7. Mantenibilidad
 - El codigo es autoexplicativo (comentarios solo donde la logica no es obvia)
 - Las funciones hacen una sola cosa
-- Los archivos no son excesivamente largos (< 300 lineas como guia)
+- Los archivos no son excesivamente largos (< 400 lineas como guia)
 - El manejo de errores es consistente con el resto del proyecto
 
 ## 8. Git y Deploy
@@ -63,3 +72,8 @@
 - Consultar la seccion "Reglas criticas" de AGENTS.md
 - Evaluar contra las reglas de "Siempre hacer", "Nunca hacer" y "Preguntar primero"
 - Si AGENTS.md define reglas adicionales (ej: zona horaria, formato de fechas, naming conventions), verificar su cumplimiento
+
+## Criterio de salida del review
+- **APROBADO**: No hay FAILs CRITICOS/ALTOS.
+- **APROBADO CON OBSERVACIONES**: Solo FAILs MEDIOS/BAJOS.
+- **REQUIERE CORRECCIONES**: Existe al menos un FAIL CRITICO/ALTO.

package/skills/test/SKILL.md

@@ -46,7 +46,7 @@ Si el usuario ejecuta `/refacil:test` sin argumentos:
 1. **Buscar cambio activo**: Lista carpetas en `openspec/changes/` y pregunta cual testear si hay mas de uno.
 
 2. **Leer artefactos**:
-   - `specs.md` — Extraer criterios de aceptacion (CA-XX) y criterios de rechazo (CR-XX)
+   - **Especificacion**: lee `specs.md` si existe **y** todos los `.md` bajo `specs/` del cambio (recursivo). De ahi extrae criterios de aceptacion (CA-XX) y rechazo (CR-XX).
    - `design.md` — Identificar componentes y archivos creados/modificados
    - `tasks.md` — Identificar archivos implementados
 

package/skills/up-code/SKILL.md

@@ -11,6 +11,7 @@ Sube los cambios al repositorio remoto asegurando que NUNCA se haga push directo
 ## 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.
 
 ## Instrucciones
 
@@ -20,44 +21,11 @@ Ejecuta `git branch --show-current` para obtener el nombre de la rama.
 
 ### Paso 2: Validar rama
 
-Verifica que la rama actual **NO** sea ninguna de las siguientes ramas protegidas:
-- `master`
-- `main`
-- `develop`
-- `testing`
-- `qa`
-- `dev`
+Aplica la **Politica de ramas protegidas y creacion de rama** definida en `refacil-prereqs/METHODOLOGY-CONTRACT.md`.
 
-Si la rama actual es una rama protegida, **DETENTE** y **pide el numero de tarea de Jira**:
-
-```
-ERROR: Estas en la rama '[nombre-rama]' que es una rama protegida.
-No se puede hacer push directo a ramas protegidas (master, main, develop, testing, qa, dev).
-
-Cual es el numero de tarea de Jira para este cambio? (ejemplo: RF-5088)
-```
-
-**Crear la rama siempre desde develop/dev actualizado:**
-1. **Verificar working directory limpio**: Ejecuta `git status --porcelain`. Si hay cambios sin commitear (archivos modificados o sin trackear), informa al usuario:
-   ```
-   Hay cambios sin commitear en la rama actual.
-   Para cambiar de rama de forma segura, necesito guardarlos temporalmente con git stash.
-   Quieres que haga git stash antes de continuar?
-   ```
-   - Si acepta: ejecuta `git stash push -m "stash-automatico-refacil"` y continua. Al final del proceso (despues de crear la rama), ejecuta `git stash pop` para restaurar los cambios.
-   - Si no acepta: **detente**.
-2. Detecta cual existe en el repo: `develop` o `dev` (ejecuta `git branch --list develop dev`)
-3. Cambia a esa rama: `git checkout develop` (o `dev`)
-4. Actualiza: `git pull origin develop` (o `dev`)
-5. Determina el nombre de la nueva rama:
-   - Si el usuario entrego el numero de Jira (ej: `RF-5088`): la rama sera `feature/RF-5088`
-   - Si el usuario no tiene tarea de Jira: usa un nombre descriptivo corto (ej: `feature/ajuste-validacion`). Pero **recomienda crear la tarea en Jira** para trazabilidad.
-6. Verifica que la rama no exista ya: `git branch --list [nombre-rama]`
-   - Si ya existe, informa al usuario y pregunta si quiere cambiarse a esa rama existente o elegir otro nombre.
-7. Crea la rama: `git checkout -b [nombre-rama]`
-8. Si se hizo stash en el paso 1, ejecuta `git stash pop` para restaurar los cambios.
-
-Si el usuario no quiere crear una rama, **detente**. No continuar con el push.
+- Si la rama actual es protegida, ejecutar ese protocolo completo antes de continuar.
+- Para `refacil:up-code`, el prefijo sugerido de rama es `feature/` (o `fix/` si el cambio es bugfix).
+- Si el usuario no aprueba la creacion/cambio de rama, detener. No continuar con commit/push.
 
 ### Paso 3: Verificar cambios pendientes
 
@@ -69,10 +37,13 @@ Ejecuta `git status` para verificar si hay cambios para subir.
 
 ### Paso 4: Commit de cambios
 
-1. Ejecuta `git add .` para agregar todos los cambios.
-2. Si el usuario proporciono un mensaje como argumento (`$ARGUMENTS`), usalo como mensaje del commit.
-3. Si no se proporciono mensaje, genera uno descriptivo basado en los cambios detectados con `git diff --staged --stat`.
-4. Ejecuta `git commit -m "[mensaje]"`.
+1. Ejecuta `git status --short` y muestra al usuario la lista de archivos detectados.
+2. Pide confirmacion explicita antes de stagear todo.
+3. Si el usuario confirma stage global, usa `git add -A`.
+4. Si el usuario pide stage parcial, agrega solo las rutas indicadas.
+5. Si el usuario proporciono un mensaje como argumento (`$ARGUMENTS`), usalo como mensaje del commit.
+6. Si no se proporciono mensaje, genera uno descriptivo basado en los cambios detectados con `git diff --staged --stat`.
+7. Ejecuta `git commit -m "[mensaje]"`.
 
 ### Paso 5: Push a remoto
 

package/skills/verify/SKILL.md

@@ -11,6 +11,7 @@ Este comando envuelve la funcionalidad de OpenSpec verify y agrega verificacion
 ## 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.
 
 ## Instrucciones
 
@@ -22,11 +23,11 @@ Lee `SKILL.md` en `.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-pr
 
 ### Paso 2: Verificar tests (aporte Refacil)
 
-Ademas de la verificacion de OpenSpec, ejecuta `npm test` y verifica:
+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 un comando de coverage (`npm run test:cov`), ejecutalo y reporta el porcentaje
+- Si hay comando de coverage del proyecto, ejecutalo y reporta el porcentaje; si no existe, reporta N/A con justificacion
 
 ### Paso 3: Reporte combinado (aporte Refacil)
 
@@ -39,9 +40,10 @@ Combina el reporte de OpenSpec con la verificacion de tests en un reporte unific
 [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] Coverage: [X]% (minimo requerido: 80%)
+ [PASS/FAIL/N/A] Coverage: [X]% (minimo requerido: 80%)
 
 RESULTADO: APROBADO / REQUIERE CORRECCIONES
 
@@ -91,3 +93,4 @@ Lista los issues para que el usuario los corrija manualmente. Sugiere ejecutar `
 - 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`)