refacil-sdd-ai

Metodologia SDD-AI (Specification-Driven Development with AI) empaquetada como herramienta CLI.

Instala skills para Claude Code y Cursor que guian al desarrollador por un flujo estructurado de desarrollo usando OpenSpec como base de especificaciones.

Requisitos

• Node.js >= 20.19.0 (requerido por OpenSpec)
• Claude Code o Cursor instalado

Instalacion y Setup

Se recomienda instalar a nivel global para no tener que instalar el paquete en cada repositorio donde se use la metodologia.

# 1. Instalar de forma global (una sola vez)
npm install -g refacil-sdd-ai

# 2. En la raiz del repo donde quieras usar la metodologia:
refacil-sdd-ai init
#    Copia skills a .claude/ y .cursor/, crea CLAUDE.md y .cursorrules

# 3. IMPORTANTE: Reiniciar la sesion de Claude Code o Cursor
#    (las skills nuevas no se detectan hasta reiniciar)

# 4. En Claude Code o Cursor, ejecutar:
/refacil:setup
#    Esto hace:
#    - Verifica Node.js
#    - Verifica OpenSpec (si no esta instalado, lo instala globalmente)
#    - Inicializa openspec/ en el repo (openspec init --tools claude,cursor)
#    - Crea openspec/config.yaml con idioma espanol
#    - Genera AGENTS.md automaticamente analizando el repo

Actualizar a una nueva version

# Actualizar el paquete global
npm update -g refacil-sdd-ai

# En cada repo donde se use, re-copiar las skills actualizadas:
refacil-sdd-ai update

Nota: openspec init tambien instala sus propios comandos (opsx:*) en .claude/ y .cursor/. Esto es normal. Los refacil:* y opsx:* coexisten sin conflicto. El equipo debe usar refacil:* como interfaz principal.

Comandos del CLI

refacil-sdd-ai init      # Instalar skills y crear configs en el repo actual
refacil-sdd-ai update    # Actualizar skills a la ultima version
refacil-sdd-ai clean     # Eliminar skills del repo
refacil-sdd-ai help      # Ver ayuda

Skills disponibles

Una vez instalado, estos comandos estan disponibles en Claude Code y Cursor:

| Comando | Descripcion | |---------|-------------| | /refacil:setup | Instalar OpenSpec y generar AGENTS.md para el repo | | /refacil:guide | Guia interactiva — que comando usar segun lo que necesites | | /refacil:explore | Explorar el codebase sin hacer cambios | | /refacil:propose | Crear propuesta de cambio (proposal + specs + design + tasks) | | /refacil:apply | Implementar las tasks del cambio propuesto | | /refacil:test | Generar tests unitarios desde los artefactos | | /refacil:verify | Validar implementacion vs specs (con opcion de aplicar correcciones) | | /refacil:review | Review con checklist de calidad del equipo | | /refacil:archive | Archivar cambio completado | | /refacil:up-code | Subir codigo a rama de desarrollo (con validacion de ramas protegidas) | | /refacil:bug | Flujo guiado completo para investigar y corregir bugs |

Flujos de trabajo

Feature nuevo

/refacil:propose "descripcion del feature"
# → Revisar y aprobar artefactos (proposal, specs, design, tasks)
/refacil:apply
/refacil:test
/refacil:verify
# → Si hay correcciones: verify pregunta si aplicarlas automaticamente
# → Si aprueba: aplica fixes y re-verifica (max 2 rondas)
/refacil:review
/refacil:archive
/refacil:up-code

Bug fix

/refacil:bug "descripcion del error"
/refacil:review
/refacil:up-code

Explorar codigo

/refacil:explore "que quiero entender"

Como funciona

1. refacil-sdd-ai init copia las skills a .claude/skills/ y .cursor/skills/, y crea CLAUDE.md + .cursorrules
2. /refacil:setup (en Claude Code o Cursor) instala OpenSpec, analiza el repo y genera un AGENTS.md personalizado
3. Las demas skills (propose, apply, test, etc.) leen AGENTS.md para entender las convenciones del proyecto

refacil-sdd-ai init          →  Skills en .claude/ y .cursor/
                                 CLAUDE.md y .cursorrules creados

/refacil:setup               →  OpenSpec instalado
                                 AGENTS.md generado (analisis automatico del repo)

/refacil:propose             →  Artefactos en openspec/changes/
/refacil:apply               →  Codigo implementado
/refacil:test                →  Tests generados
/refacil:verify              →  Validacion PASS/FAIL (puede aplicar fixes con aprobacion)
/refacil:review              →  Review con checklist
/refacil:archive             →  Cambio archivado
/refacil:up-code             →  Push a rama de desarrollo

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)
AGENTS.md                    # Generado por /refacil:setup (NO por el CLI)
openspec/                    # Generado por /refacil:setup via OpenSpec

Desinstalar

# Eliminar skills del repo actual
refacil-sdd-ai clean

# Desinstalar paquete global (opcional)
npm uninstall -g refacil-sdd-ai

Tecnologias

• OpenSpec — Framework de especificaciones
• AGENTS.md — Estandar universal de instrucciones para IA
• Claude Code — CLI de Anthropic
• Cursor — IDE con IA

Licencia

MIT