refacil-sdd-ai 2.0.3 → 2.0.7

package/README.md

@@ -129,10 +129,11 @@ refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
 ## Que se instala en tu repo
 
 ```
-.claude/skills/refacil-*/    # Skills para Claude Code
-.cursor/skills/refacil-*/    # Skills para Cursor
-CLAUDE.md                    # Config para Claude Code (apunta a AGENTS.md)
-.cursorrules                 # Config para Cursor (apunta a AGENTS.md)
+.claude/skills/refacil-*/    # Claude Code (refacil-prereqs incluye OPENSPEC-DELTAS.md)
+.cursor/skills/refacil-*/    # Cursor — copia equivalente
+.../refacil-setup/           # troubleshooting.md 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)
 openspec/                    # Generado por /refacil:setup via OpenSpec
 ```

package/bin/cli.js

@@ -5,6 +5,7 @@ const path = require('path');
 
 const SKILLS = [
   'setup',
+  'prereqs',
   'guide',
   'explore',
   'propose',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refacil-sdd-ai",
-  "version": "2.0.3",
+  "version": "2.0.7",
   "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

@@ -10,40 +10,38 @@ Este comando envuelve la funcionalidad de OpenSpec apply y agrega las convencion
 
 ## Antes de empezar
 
-### Verificar prerequisitos
-
-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**.
-
-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**.
-
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones, arquitectura y patrones. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+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.
 
 ## 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
 
@@ -88,15 +86,9 @@ Ejecuta `git branch --show-current` para obtener la rama actual.
 
 ### Paso 2: Delegar a OpenSpec apply
 
-Ejecuta internamente las instrucciones de la skill `openspec-apply-change` que esta instalada en `.claude/skills/openspec-apply-change/SKILL.md` (o `.cursor/skills/openspec-apply-change/SKILL.md`).
-
-Lee esa skill y sigue sus instrucciones pasandole el argumento del usuario: **$ARGUMENTS**
-
-**Indicaciones adicionales durante la implementacion:**
-- Respetar estrictamente las convenciones de `AGENTS.md`
-- No agregar funcionalidad fuera del alcance de las specs
-- No hacer refactors no solicitados en codigo existente
-- Si una task es ambigua, preguntar antes de implementar
+1. Lee `openspec-apply-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
+2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **apply**).
+3. Sigue OpenSpec con argumento **$ARGUMENTS** aplicando esos deltas.
 
 ### Paso 3: Resumen y siguiente paso (aporte Refacil)
 
@@ -116,7 +108,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

@@ -10,13 +10,7 @@ Este comando envuelve la funcionalidad de OpenSpec archive (que internamente lla
 
 ## Antes de empezar
 
-### Verificar prerequisitos
-
-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**.
-
-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**.
-
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+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.
 
 ## Instrucciones
 
@@ -34,16 +28,9 @@ Si alguna verificacion falla, informa al usuario pero permite que decida si cont
 
 ### Paso 2: Delegar a OpenSpec archive
 
-Ejecuta internamente las instrucciones de la skill `openspec-archive-change` que esta instalada en `.claude/skills/openspec-archive-change/SKILL.md` (o `.cursor/skills/openspec-archive-change/SKILL.md`).
-
-Lee esa skill y sigue sus instrucciones pasandole el argumento del usuario: **$ARGUMENTS**
-
-OpenSpec archive internamente:
-- Verifica el estado de los artefactos
-- Ofrece sincronizar delta specs a `openspec/specs/` (via `openspec-sync-specs`)
-- Mueve la carpeta del cambio a `openspec/changes/archive/` (con prefijo de fecha)
-
-**IMPORTANTE**: Cuando OpenSpec pregunte si sincronizar specs, responde **SI**. La sincronizacion de specs es obligatoria en la metodologia Refacil — `openspec/specs/` debe reflejar siempre el estado actual del sistema.
+1. Lee `openspec-archive-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
+2. Lee `OPENSPEC-DELTAS.md` en `refacil-prereqs` (seccion **archive**).
+3. Sigue OpenSpec con argumento **$ARGUMENTS** (sync de specs segun deltas).
 
 ### Paso 3: Verificar sincronizacion (aporte Refacil)
 
@@ -51,7 +38,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

package/skills/bug/SKILL.md

@@ -10,8 +10,7 @@ Eres un asistente especializado en investigacion y correccion de bugs. Guias al
 
 ## Contexto
 
-Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones, arquitectura y patrones.
-Si NO existe `AGENTS.md`, informa al usuario: "No se encontro AGENTS.md. Ejecuta /refacil:setup para generarlo." y detente.
+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.
 
 ## Instrucciones
 
@@ -157,7 +156,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
 

package/skills/explore/SKILL.md

@@ -10,21 +10,15 @@ Este comando envuelve la funcionalidad de OpenSpec explore y agrega contexto del
 
 ## Antes de empezar
 
-### Verificar prerequisitos
-
-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**.
-
-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**.
-
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones, arquitectura y patrones del repositorio. Usa esa informacion como contexto durante la exploracion. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+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).
 
 ## Instrucciones
 
 ### Paso 1: Delegar a OpenSpec explore
 
-Ejecuta internamente las instrucciones de la skill `openspec-explore` que esta instalada en `.claude/skills/openspec-explore/SKILL.md` (o `.cursor/skills/openspec-explore/SKILL.md`).
-
-Lee esa skill y sigue sus instrucciones pasandole el argumento del usuario: **$ARGUMENTS**
+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**.
 
 ### Paso 2: Enriquecer con contexto de AGENTS.md
 
@@ -40,7 +34,4 @@ Al final del reporte, sugiere:
 
 ## Reglas
 
-- NO modifiques ningun archivo
-- NO generes codigo nuevo
-- Solo lectura e investigacion
-- Responde en español con terminos tecnicos en ingles
+- NO modifiques ningun archivo ni generes codigo; solo lectura e investigacion (idioma: ver `OPENSPEC-DELTAS.md`).

package/skills/guide/SKILL.md

@@ -6,197 +6,26 @@ user-invocable: true
 
 # refacil:guide — Guia de la Metodologia SDD-AI
 
-Eres un guia interactivo que ayuda al desarrollador a entender la metodologia y elegir el comando correcto.
+Eres un guia **breve**: eliges el siguiente comando; el detalle de cada flujo esta en el **README de refacil-sdd-ai** (npm / repo del CLI, seccion "Flujos de trabajo") — no lo repitas aqui palabra por palabra.
 
 ## Instrucciones
 
-Preguntale al usuario que necesita hacer. Basandote en su respuesta, explicale el flujo correspondiente y el comando que debe ejecutar.
+1. Pregunta que necesita el usuario (o usa su primer mensaje).
+2. Muestra el menu numerado (abajo).
+3. Responde con: **comando** a ejecutar + **orden de pasos en una linea** (ej: `propose` → revisar artefactos → `apply` → `test` → `verify` → `review` → `archive` → `up-code`).
+4. Si pide mas detalle: "Ver README de refacil-sdd-ai (npm o repo del paquete): Flujos de trabajo y Comandos del CLI."
 
-Presenta estas opciones:
+## Menu
 
-1. **Crear un feature nuevo** — Quiero implementar una funcionalidad nueva
-2. **Corregir un bug** — Tengo un error que necesito investigar y corregir
-3. **Explorar el codigo** — Quiero entender como funciona algo antes de hacer cambios
-4. **Generar tests** — Necesito crear pruebas unitarias para codigo existente o nuevo
-5. **Revisar mi implementacion** — Quiero validar que mi codigo cumple los estandares
-6. **Subir mi codigo** — Quiero hacer push de mis cambios a mi rama de desarrollo
-7. **Configurar el repo** — Necesito instalar/configurar las herramientas
+1. Feature nuevo → `/refacil:propose` luego flujo estandar hasta `/refacil:up-code`
+2. Bug → `/refacil:bug` → opcional `/refacil:review` → `/refacil:up-code`
+3. Explorar → `/refacil:explore`
+4. Tests → `/refacil:test`
+5. Validar implementacion → `/refacil:verify` (luego `/refacil:review` si aplica)
+6. Subir codigo → `/refacil:up-code`
+7. Configurar repo → `refacil-sdd-ai init` (global + por repo) y `/refacil:setup`
 
-## Respuestas por opcion
+## Tips (una linea por herramienta)
 
-### Opcion 1: Feature nuevo
-
-```
-FLUJO PARA NUEVO FEATURE:
-
-1. /refacil:propose <descripcion>
-   Crea una propuesta completa con: proposal, specs, design y tasks.
-   La IA te guia para definir todos los artefactos.
-
-2. REVISION DEL DESARROLLADOR (Human-in-the-Loop)
-   Revisa los artefactos generados (proposal, specs, design, tasks).
-   Confirma que los criterios, el design y las tasks son correctos.
-   La IA NO continua hasta que apruebes explicitamente.
-
-3. /refacil:apply
-   Valida que NO estes en una rama protegida (master, main, develop, dev, testing, qa).
-   Si estas en una, te pide el numero de tarea de Jira y crea la rama desde develop.
-   Luego implementa las tasks aprobadas siguiendo el plan.
-
-4. /refacil:test
-   Genera tests unitarios basados en las specs y el design.
-   Cada criterio de aceptacion se convierte en al menos 1 test.
-
-5. /refacil:verify
-   Valida que la implementacion cumple con las specs.
-   Revisa completitud, correccion y coherencia.
-
-   Si encuentra correcciones necesarias (CRITICAL o WARNING):
-   - Te muestra el reporte con los issues encontrados
-   - Te pregunta si quieres que aplique las correcciones automaticamente
-   - Si aceptas: aplica SOLO los fixes necesarios y re-verifica
-   - Maximo 2 rondas de correccion automatica
-   - Si despues de 2 rondas quedan issues, los lista para correccion manual
-   - Si no aceptas: lista los issues para que los corrijas manualmente
-     y luego ejecutes /refacil:verify de nuevo
-
-   Solo avanza a review cuando la verificacion pasa completamente.
-
-6. /refacil:review
-   Review con el checklist de calidad del equipo.
-   Evalua conformidad con specs, codigo, arquitectura, testing,
-   seguridad, performance y reglas especificas del proyecto.
-
-7. /refacil:archive
-   Archiva el cambio completado. Mueve artefactos a archive/.
-
-8. /refacil:up-code
-   Sube los cambios a tu rama de desarrollo.
-   Valida que NO estes en ramas protegidas (master, main, develop, dev, testing, qa).
-   Si necesita crear rama, te pide el numero de tarea de Jira.
-```
-
-### Opcion 2: Bug fix
-
-```
-FLUJO PARA BUG FIX:
-
-1. /refacil:bug <descripcion del error>
-   Flujo guiado completo:
-   - Describes el bug (que pasa, que deberia pasar)
-   - La IA investiga la causa raiz en el codebase
-   - Te presenta hipotesis para confirmar
-   - Propone la correccion y espera tu aprobacion
-   - Valida rama: si estas en rama protegida, te pide el numero
-     de tarea de Jira y crea la rama desde develop
-   - Implementa el fix y genera tests de regresion
-   - Ejecuta los tests para verificar
-
-2. /refacil:review (opcional)
-   Review con checklist si el fix es complejo.
-
-3. /refacil:up-code
-   Sube los cambios a tu rama de desarrollo.
-```
-
-### Opcion 3: Explorar
-
-```
-FLUJO PARA EXPLORACION:
-
-1. /refacil:explore <que quieres entender>
-   Investiga el codebase sin hacer cambios.
-   Analiza arquitectura, flujos, dependencias.
-   Genera un reporte con hallazgos.
-   Util antes de proponer un cambio grande.
-```
-
-### Opcion 4: Tests
-
-```
-FLUJO PARA GENERAR TESTS:
-
-1. /refacil:test
-   Si hay un cambio activo en openspec/changes/, genera tests
-   basados en los artefactos (specs, design, tasks).
-
-   Si no hay cambio activo, puedes pasar un archivo o directorio:
-   /refacil:test src/mi-servicio.ts
-   Genera tests para ese archivo especifico.
-```
-
-### Opcion 5: Review
-
-```
-FLUJO PARA REVIEW:
-
-1. /refacil:review
-   Evalua la implementacion contra el checklist del equipo:
-   - Conformidad con specs
-   - Calidad de codigo y patrones
-   - Arquitectura (segun convenciones de AGENTS.md)
-   - Testing (coverage >= 80%)
-   - Seguridad (OWASP top 10)
-   - Performance (N+1, async, indices)
-   - Reglas especificas del proyecto (de AGENTS.md)
-
-   Genera un reporte PASS/FAIL/N/A por cada item.
-```
-
-### Opcion 6: Subir codigo
-
-```
-FLUJO PARA SUBIR CODIGO:
-
-1. /refacil:up-code
-   Sube tus cambios al repositorio remoto de forma segura:
-   - Detecta la rama actual
-   - Valida que NO sea una rama protegida (master, main, develop, dev, testing, qa)
-   - Si estas en rama protegida, te pide el numero de tarea de Jira
-     y crea la rama desde develop
-   - Ejecuta git add, commit y push
-
-   Opcionalmente puedes pasar el mensaje del commit:
-   /refacil:up-code "mensaje del commit"
-
-   Usa este comando despues de /refacil:archive o en cualquier momento
-   que quieras subir tu trabajo a tu rama de desarrollo.
-```
-
-### Opcion 7: Setup
-
-```
-CONFIGURACION:
-
-Pre-requisito (una sola vez, instalacion global):
-  npm install -g refacil-sdd-ai
-
-En cada repo nuevo:
-  refacil-sdd-ai init
-  (reiniciar sesion de Claude Code o Cursor)
-
-1. /refacil:setup
-   Verifica e instala todo lo necesario:
-   - Node.js >= 20.19.0
-   - OpenSpec (si no esta instalado, lo instala globalmente)
-   - Inicializacion del repo
-   - Configuracion de convenciones
-   - Verificacion de AGENTS.md y skills
-
-Actualizar a nueva version:
-  npm update -g refacil-sdd-ai
-  refacil-sdd-ai update   (en cada repo)
-```
-
-## Tips
-
-Despues de explicar el flujo, ofrece estos tips segun la herramienta:
-
-**Claude Code:**
-- Los comandos se ejecutan escribiendo `/refacil:comando` en el chat
-- Usa `/plan` antes de implementar para ver el plan sin escribir codigo
-
-**Cursor:**
-- Los comandos se ejecutan en Composer (Ctrl+I / Cmd+I) escribiendo `/refacil:comando`
-- Usa @ para agregar archivos de contexto adicionales
-- Activa "Codebase" en Composer para contexto completo del repo
+- **Claude Code:** comandos `/refacil:*` en el chat.
+- **Cursor:** comandos `/refacil:*` en Composer; `@` para archivos de contexto.

package/skills/prereqs/OPENSPEC-DELTAS.md

@@ -0,0 +1,50 @@
+# Deltas Refacil sobre OpenSpec
+
+Lee este archivo **ademas** de la skill `openspec-*` que indique el comando `refacil:*`. No sustituye a OpenSpec; solo fija convenciones del equipo.
+
+**Ubicacion en el repo:** mismo directorio que `SKILL.md` de `refacil-prereqs` (`.claude/skills/refacil-prereqs/` o `.cursor/skills/refacil-prereqs/`).
+
+## Idioma (todas las delegaciones)
+
+- Respuestas al usuario y artefactos bajo `openspec/`: **español**; terminos tecnicos (API, REST, nombres de tipos, etc.) en **ingles**.
+
+## propose — `openspec-ff-change`
+
+- Criterios de aceptacion: formato **Dado / Cuando / Entonces**.
+- Incluir **criterios de rechazo** (edge cases) en specs.
+- 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`
+
+- Si OpenSpec pregunta si sincronizar specs delta a `openspec/specs/`: responder **SI**. La sincronizacion es **obligatoria** en esta metodologia.
+
+## explore — `openspec-explore`
+
+- Solo lectura; no modificar archivos ni generar codigo.
+- Enriquecer el informe con puntos de `AGENTS.md` relevantes al tema explorado (ya indicado en la skill `refacil:explore`).
+
+## verify — `openspec-verify-change`
+
+- Sin reglas extra sobre OpenSpec: aplica solo el bloque **Idioma** de arriba a informes y mensajes al usuario.

package/skills/prereqs/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: refacil:prereqs
+description: Referencia interna — prerequisitos SDD-AI compartidos por el resto de skills refacil (no invocar manualmente)
+user-invocable: false
+---
+
+# Prerequisitos SDD-AI (centralizado)
+
+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.
+
+## Perfil `openspec` (OpenSpec + repo + AGENTS.md)
+
+Usar cuando la skill diga: *Aplica el perfil `openspec`.*
+
+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**.
+
+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**.
+
+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**.
+
+   - Si la skill activa es **`refacil:explore`**, usa lo leido en `AGENTS.md` como **contexto activo** durante toda la exploracion (no solo al inicio).
+
+## Perfil `agents` (solo AGENTS.md)
+
+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**.
+
+## 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`).

package/skills/propose/SKILL.md

@@ -10,13 +10,7 @@ Este comando envuelve la funcionalidad de OpenSpec fast-forward (ff) y agrega la
 
 ## Antes de empezar
 
-### Verificar prerequisitos
-
-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**.
-
-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**.
-
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones, arquitectura y patrones. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+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.
 
 ## Instrucciones
 
@@ -31,16 +25,9 @@ Si $ARGUMENTS ya es claro, no preguntes de nuevo.
 
 ### Paso 2: Delegar a OpenSpec ff (fast-forward)
 
-Ejecuta internamente las instrucciones de la skill `openspec-ff-change` que esta instalada en `.claude/skills/openspec-ff-change/SKILL.md` (o `.cursor/skills/openspec-ff-change/SKILL.md`).
-
-Lee esa skill y sigue sus instrucciones para generar todos los artefactos (proposal, specs, design, tasks) en una sola pasada.
-
-**Indicaciones adicionales para la generacion de artefactos:**
-- Los artefactos deben generarse en **español con terminos tecnicos en ingles**
-- Los criterios de aceptacion deben usar formato **Dado/Cuando/Entonces**
-- Incluir siempre **criterios de rechazo** (edge cases) en las specs
-- Las tasks deben incluir **estimacion de esfuerzo** (S/M/L)
-- El design debe referenciar **patrones existentes** del repo (encontrados en AGENTS.md o explorando el codebase)
+1. Lee `openspec-ff-change/SKILL.md` en `.claude/skills/` o `.cursor/skills/`.
+2. Lee `OPENSPEC-DELTAS.md` en la carpeta `refacil-prereqs` (misma ruta dual que en prereqs).
+3. Ejecuta la skill OpenSpec siguiendo sus instrucciones y aplicando los deltas Refacil para generar los artefactos (proposal, specs, design, tasks) en una sola pasada.
 
 ### Paso 3: Revision del desarrollador (Human-in-the-Loop)
 
@@ -49,7 +36,7 @@ Lee esa skill y sigue sus instrucciones para generar todos los artefactos (propo
 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
 
@@ -59,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
 
@@ -82,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

@@ -10,8 +10,7 @@ Eres un reviewer exigente pero constructivo que evalua el codigo contra el check
 
 ## Contexto
 
-Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones, arquitectura y patrones.
-Si NO existe `AGENTS.md`, informa al usuario: "No se encontro AGENTS.md. Ejecuta /refacil:setup para generarlo." y detente.
+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 el archivo [checklist.md](checklist.md) para conocer los criterios de evaluacion.
 
 ## Instrucciones

package/skills/setup/SKILL.md

@@ -6,220 +6,75 @@ user-invocable: true
 
 # refacil:setup — Configuracion del Repositorio
 
-Eres un asistente de setup que guia al desarrollador paso a paso para configurar el repositorio con la metodologia SDD-AI.
+Guia al desarrollador **paso a paso**. Tras cada paso, informa resultado; si falla, **detente** y da el error. Fallos de instalacion o PATH: ver [troubleshooting.md](troubleshooting.md) en esta skill (`refacil-setup`).
 
-## Proceso paso a paso
+## Proceso
 
-Ejecuta cada paso secuencialmente. Informa al usuario del resultado de cada paso antes de continuar. Si un paso falla, NO continues — informa el error y como resolverlo.
+### Paso 1: Node.js
 
-### Paso 1: Verificar Node.js
+`node --version` >= 20.19.0. Si no: indicar requisito y detener.
 
-Ejecuta `node --version` y verifica que sea >= 20.19.0 (requerido por OpenSpec).
+### Paso 2: OpenSpec
 
-- Si la version es correcta: "Node.js [version] OK"
-- Si la version es < 20.19.0: informa que OpenSpec requiere Node.js >= 20.19.0. Pide que actualice Node.js y detente.
-- Si no esta instalado: informa que necesita instalar Node.js >= 20.19.0 y detente.
+`openspec --version 2>&1`. Si falla: ofrecer `npm install -g @fission-ai/openspec@latest`, re-verificar. Si sigue fallando: **troubleshooting.md**.
 
-### Paso 2: Verificar OpenSpec
-
-Ejecuta `openspec --version 2>&1`.
-
-- Si esta instalado: "OpenSpec [version] OK"
-- Si no esta instalado o el comando falla, pregunta al usuario si desea instalarlo. Si acepta:
-  ```bash
-  npm install -g @fission-ai/openspec@latest
-  ```
-  Despues de instalar, ejecuta `openspec --version` de nuevo para verificar. Si falla, sugiere:
-  - Verificar permisos (puede necesitar `sudo` en Linux/Mac)
-  - Verificar que npm global bin esta en el PATH
-
-### Paso 3: Configurar perfil OpenSpec con todos los workflows
-
-Antes de inicializar, configura el perfil global para garantizar que se instalen TODOS los workflows requeridos:
+### Paso 3: Perfil OpenSpec
 
 ```bash
 openspec config set profile custom
 openspec config set workflows "explore,new,continue,apply,ff,sync,archive,bulk-archive,verify,onboard"
-```
-
-Verifica que la configuracion quedo correcta:
-```bash
 openspec config list
 ```
 
-Debe mostrar `profile: custom` y los 10 workflows listados.
-
-### Paso 4: Inicializar OpenSpec en el repo
-- ejecuta:
-  ```bash
-  openspec init --tools claude,cursor
-  ```
-
-**IMPORTANTE**: `openspec init` tambien instala sus propios comandos (`opsx:*`) en `.claude/` y `.cursor/`. Esto es normal y esperado. Los comandos `opsx:*` de OpenSpec y los `refacil:*` de esta metodologia coexisten sin conflicto. Los `refacil:*` son los que el equipo debe usar — los `opsx:*` son los comandos nativos de OpenSpec que funcionan por debajo.
-
-### Paso 5: Configurar OpenSpec
-
-Verifica si existe `openspec/config.yaml`.
+Debe verse `profile: custom` y los 10 workflows.
 
-**Si NO existe** (esto es comun porque `openspec init` en modo no-interactivo no lo crea), crealo:
+### Paso 4: Init en el repo
 
-```yaml
-# OpenSpec Configuration — Equipo Refacil
-language: spanish
-# Los terminos tecnicos (API, REST, gRPC, etc.) permanecen en ingles.
-# Las descripciones, propuestas y specs se generan en espanol.
+```bash
+openspec init --tools claude,cursor
 ```
 
-**Si ya existe**, verifica que tenga `language: spanish`. Si no lo tiene, sugiere agregarlo.
-
-### Paso 6: Generar AGENTS.md
-
-**Este es el paso mas importante.** Analiza el repositorio automaticamente para generar un `AGENTS.md` personalizado.
-
-Verifica si ya existe `AGENTS.md` en la raiz. Si existe, pregunta al usuario si quiere regenerarlo. Si no quiere, salta este paso.
-
-#### 6.1 Analizar el repositorio
-
-Lee estos archivos si existen (no falles si alguno no existe, simplemente omitelo):
-- `package.json` — nombre, scripts, dependencias (tech stack)
-- `tsconfig.json` o `tsconfig.base.json` — paths aliases, target
-- `nest-cli.json` — estructura monorepo NestJS (si aplica)
-- `angular.json` — estructura Angular (si aplica)
-- `README.md` — descripcion del proyecto
-- `.eslintrc.*` o `eslint.config.*` — reglas de linting
-- Seccion jest en package.json o `jest.config.*` — configuracion de tests
-- Estructura de carpetas del primer nivel (ejecuta `ls` en la raiz)
-- `Dockerfile` o `docker-compose.yml` — info de deployment
-- `.env.example` — variables de entorno
-
-#### 6.2 Generar el AGENTS.md
-
-Con la informacion recopilada, genera un archivo `AGENTS.md` completo. El contenido debe ser en espanol con terminos tecnicos en ingles.
-
-Secciones obligatorias:
-
-1. **Encabezado**: Nombre del proyecto, descripcion breve y proposito. Incluir nota de compatibilidad con el estandar agents.md.
+`openspec init` instala `opsx:*` en `.claude/` y `.cursor/`; convive con `refacil:*` — el equipo usa **refacil:*** como interfaz principal.
 
-2. **Metodologia SDD-AI**: Tabla con TODOS los comandos refacil:* y sus descripciones. Incluir los dos flujos principales (feature y bug).
+### Paso 5: `openspec/config.yaml`
 
-3. **Comandos de desarrollo**: Extraer TODOS los scripts de package.json y documentarlos con su proposito. Agrupar por categoria (build, dev, test, lint).
+Si no existe, crear con `language: spanish` (y comentario de terminos tecnicos en ingles). Si existe, asegurar `language: spanish`.
 
-4. **Arquitectura**: Estructura de carpetas detectada. Si es monorepo, listar apps y libs. Indicar patron de diseno usado (DDD, MVC, Clean Architecture, etc.) basandose en la estructura.
+### Paso 6: Generar `AGENTS.md`
 
-5. **Stack tecnologico**: Tabla con framework, lenguaje, BD, cache, comunicacion, testing, etc. Todo extraido de dependencies en package.json.
+Analiza el repo y genera `AGENTS.md` (espanol, terminos tecnicos en ingles). Si ya existe `AGENTS.md`, pregunta si regenerar.
 
-6. **Alias de rutas**: Path mappings de tsconfig.json si existen. Indicar que SIEMPRE se deben usar en imports.
+**6.1 Analisis** — Lee si existen: `package.json`, `tsconfig*.json`, `nest-cli.json`, `angular.json`, `README.md`, eslint, jest, `ls` raiz, Docker, `.env.example`.
 
-7. **Base de datos**: ORM detectado (TypeORM, Prisma, Sequelize, Mongoose, etc.), tipo de BD, convenciones de entidades si se pueden inferir.
+**6.2 Estructura obligatoria del archivo**
 
-8. **Testing**: Framework de test, comandos, configuracion de coverage, convenciones de naming para tests.
+1. **Resumen para IA (primero, obligatorio)** — Lo que un asistente necesita en **como mucho ~120 lineas** (una pantalla):
+   - Titulo + descripcion breve (2-4 lineas)
+   - Tabla mini: lenguaje, framework, tests, package manager
+   - Scripts esenciales (build, test, lint) con una linea de proposito cada uno
+   - **Reglas criticas condensadas**: Siempre / Nunca / Preguntar (hasta ~5 bullets por bloque si aplica)
+   - Tabla **comandos refacil:*** (nombre + una frase; no copiar el README entero)
+   - Linea fija: *Detalle ampliado debajo. Si hay anexos en `docs/agents-*.md`, leerlos solo cuando trabajes en esa area.*
 
-9. **Reglas criticas**: Tres secciones:
-   - "Siempre hacer": convenciones obligatorias del proyecto
-   - "Nunca hacer": anti-patrones especificos para el stack
-   - "Preguntar primero": cambios de alto impacto que requieren confirmacion
+2. **Detalle del proyecto** — Arquitectura, stack ampliado, alias, BD, testing extendido, comandos de desarrollo completos, reglas ampliadas.
 
-#### 6.3 Fallback si el analisis falla
+3. **Anexos (opcional)** — Si el detalle seria muy largo (>~250 lineas en una sola seccion), crear `docs/agents-architecture.md`, `docs/agents-testing.md`, etc., y en `AGENTS.md` dejar solo enlaces + cuando leer cada uno.
 
-Si por cualquier razon no puedes generar un AGENTS.md completo (archivos no legibles, repo vacio, error inesperado), genera un AGENTS.md minimo con esta estructura:
+**6.3 Fallback** — Si el analisis falla, `AGENTS.md` minimo con: resumen corto + tabla refacil + TODOs + linea que invite a re-ejecutar setup; misma idea de resumen primero.
 
-```markdown
-# [nombre del proyecto]
-
-> Generado por /refacil:setup — completar manualmente las secciones marcadas con TODO.
-
-## Metodologia SDD-AI
-
-| Comando | Descripcion |
-|---------|-------------|
-| `/refacil:setup` | Instalar OpenSpec y generar AGENTS.md |
-| `/refacil:guide` | Guia interactiva — que comando usar |
-| `/refacil:explore` | Explorar el codebase sin cambios |
-| `/refacil:propose` | Crear propuesta de cambio |
-| `/refacil:apply` | Implementar tasks del cambio |
-| `/refacil:test` | Generar tests unitarios |
-| `/refacil:verify` | Validar implementacion vs specs (con opcion de aplicar correcciones) |
-| `/refacil:review` | Review con checklist de calidad |
-| `/refacil:archive` | Archivar cambio completado |
-| `/refacil:up-code` | Subir codigo a rama de desarrollo |
-| `/refacil:bug` | Flujo guiado de bugfix |
-
-## Stack tecnologico
-TODO: Completar con el stack del proyecto
-
-## Arquitectura
-TODO: Completar con la estructura del proyecto
-
-## Comandos de desarrollo
-TODO: Completar con los scripts de package.json
-
-## Reglas criticas
-TODO: Completar con las convenciones del equipo
-```
-
-Informa al usuario que el AGENTS.md fue generado con secciones TODO que debe completar manualmente o ejecutando `/refacil:setup` de nuevo.
-
-#### 6.4 Mostrar al usuario
-
-Muestra el AGENTS.md generado completo. Pregunta si quiere ajustar algo antes de guardarlo.
-
-Si el usuario aprueba (o no tiene cambios), escribe el archivo en la raiz del proyecto.
+**6.4** — Muestra el resultado; si el usuario aprueba, escribe en la raiz.
 
 ### Paso 7: Verificar skills
 
-#### 7.1 Verificar skills de OpenSpec
-
-Verifica que existan las 10 carpetas de skills de OpenSpec en `.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 las 10 existen: "Skills OpenSpec: 10/10 instaladas OK"
-- Si faltan algunas: informa cuales faltan. Sugiere ejecutar de nuevo `openspec init --tools claude,cursor` o verificar el perfil con `openspec config list`.
-
-#### 7.2 Verificar skills de Refacil
-
-Verifica que existan las carpetas `.claude/skills/refacil-*` y/o `.cursor/skills/refacil-*`.
-
-- Si existen: "Skills de Refacil: [N] instaladas OK"
-- Si NO existen: informa al usuario:
-  ```
-  Las skills de Refacil no estan instaladas.
-
-  Si ya tienes refacil-sdd-ai instalado globalmente:
-    refacil-sdd-ai init
-
-  Si no lo tienes instalado globalmente:
-    npm install -g refacil-sdd-ai
-    refacil-sdd-ai init
-
-  Luego reinicia esta sesion de Claude Code / Cursor.
-  ```
+- 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`.
+- Refacil: carpetas `refacil-*` en esas rutas. Si no: `refacil-sdd-ai init` + reiniciar sesion.
 
 ### Paso 8: Resumen final
 
 ```
 === refacil:setup completado ===
- Node.js:         [version] OK
- OpenSpec:         [version] OK
- Perfil workflows: custom (10 workflows) OK
- openspec/:        Inicializado OK
- config.yaml:      Configurado OK
- AGENTS.md:        Generado OK
- Skills OpenSpec:  10/10 instaladas OK
- Skills Refacil:   [N] instaladas OK
-
- IMPORTANTE: Si acabas de instalar las skills por primera vez,
- debes REINICIAR la sesion de Claude Code o Cursor para que
- los comandos /refacil:* aparezcan disponibles.
-
- El repositorio esta listo para usar la metodologia SDD-AI.
- Ejecuta /refacil:guide para ver los comandos disponibles.
+ Node.js / OpenSpec / perfil / openspec/ / config / AGENTS.md / skills OK
+
+ Reiniciar sesion Claude Code o Cursor si es la primera instalacion de skills.
+ Siguiente: /refacil:guide
 ```

package/skills/setup/troubleshooting.md

@@ -0,0 +1,29 @@
+# refacil:setup — Resolucion de problemas
+
+Consulta este archivo **solo** si un paso de setup falla. No forma parte del flujo feliz.
+
+## OpenSpec: comando no encontrado tras `npm install -g`
+
+- Comprueba donde instala npm los binarios: `npm config get prefix`, luego anade `[prefix]/bin` (Linux/Mac) o `[prefix]` (Windows) al **PATH** y abre de nuevo la terminal / el IDE.
+- En Linux/Mac a veces hace falta `sudo` para install global; preferible arreglar permisos de prefijo de npm (`npm config set prefix ~/.npm-global`) antes que usar sudo.
+
+## `openspec --version` falla con error de Node
+
+- OpenSpec exige **Node >= 20.19.0**. Actualiza Node y vuelve a intentar.
+
+## `openspec init` no crea todas las skills
+
+- Ejecuta `openspec config list` y confirma `profile: custom` y los 10 workflows del proceso principal de setup.
+- Repite `openspec init --tools claude,cursor` desde la raiz del repo.
+
+## Falta `openspec/config.yaml`
+
+- Crealo manualmente con al menos:
+
+```yaml
+language: spanish
+```
+
+## Skills `refacil-*` no aparecen en el IDE
+
+- Ejecuta `refacil-sdd-ai init` en la raiz del repo y **reinicia** la sesion de Claude Code o Cursor.

package/skills/test/SKILL.md

@@ -10,13 +10,7 @@ Eres un asistente de testing que genera pruebas unitarias de alta calidad, adapt
 
 ## Antes de empezar
 
-### Verificar prerequisitos
-
-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**.
-
-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**.
-
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones, arquitectura y patrones. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+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.
 
 ### Detectar stack tecnologico
 
@@ -52,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

@@ -10,8 +10,7 @@ Sube los cambios al repositorio remoto asegurando que NUNCA se haga push directo
 
 ## Antes de empezar
 
-Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones.
-Si NO existe `AGENTS.md`, informa al usuario: "No se encontro AGENTS.md. Ejecuta /refacil:setup para generarlo." y detente.
+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.
 
 ## Instrucciones
 

package/skills/verify/SKILL.md

@@ -10,23 +10,15 @@ Este comando envuelve la funcionalidad de OpenSpec verify y agrega verificacion
 
 ## Antes de empezar
 
-### Verificar prerequisitos
-
-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**.
-
-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**.
-
-3. **AGENTS.md**: Si existe `AGENTS.md` en la raiz del proyecto, leelo para entender las convenciones. Si NO existe, informa al usuario: "No se encontro AGENTS.md. Ejecuta `/refacil:setup` para generarlo." y **detente**.
+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.
 
 ## Instrucciones
 
 ### Paso 1: Delegar a OpenSpec verify
 
-Ejecuta internamente las instrucciones de la skill `openspec-verify-change` que esta instalada en `.claude/skills/openspec-verify-change/SKILL.md` (o `.cursor/skills/openspec-verify-change/SKILL.md`).
-
-Lee esa skill y sigue sus instrucciones pasandole el argumento del usuario: **$ARGUMENTS**
-
-Esto generara un reporte de verificacion con issues CRITICAL/WARNING/SUGGESTION.
+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).
 
 ### Paso 2: Verificar tests (aporte Refacil)
 

package/templates/claude-md.md

@@ -5,7 +5,7 @@ Si AGENTS.md no existe, ejecuta `/refacil:setup` para generarlo automaticamente.
 
 ## Metodologia SDD-AI (Refacil)
 
-Este proyecto usa la metodologia SDD-AI. Skills disponibles:
+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:
 
 | Comando | Descripcion |
 |---------|-------------|

package/templates/cursorrules.md

@@ -5,7 +5,7 @@ Si AGENTS.md no existe, ejecuta /refacil:setup para generarlo automaticamente.
 
 ## Metodologia SDD-AI (Refacil)
 
-Skills disponibles en .cursor/skills/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