specleap-framework 2.0.0

package/rules/development-rules.md

@@ -0,0 +1,113 @@
+# Reglas de Desarrollo — SpecLeap
+
+> Reglas obligatorias para todo desarrollo dentro de proyectos gestionados con SpecLeap.
+
+## 1. Centralización de Configuración
+
+**NUNCA hardcodear valores.** Todo valor configurable debe estar en:
+
+- Variables de entorno (`.env`)
+- Archivos de configuración (`config/`)
+- Constantes centralizadas
+
+```
+❌ $url = "https://api.example.com/v1";
+✅ $url = config('services.api.url');
+```
+
+**Sin excepciones.** URLs, credenciales, puertos, rutas de archivos, claves API — todo centralizado.
+
+## 2. Non-Destructive Development
+
+Antes de cualquier cambio, evaluar la **jerarquía de impacto**:
+
+| Nivel | Pregunta | Acción requerida |
+|-------|----------|-----------------|
+| 🔴 Crítico | ¿Puede romper producción? | Review obligatorio + rollback plan |
+| 🟡 Alto | ¿Afecta datos existentes? | Migración reversible + backup |
+| 🟢 Medio | ¿Cambia API pública? | Deprecación primero, luego cambio |
+| ⚪ Bajo | ¿Cambio interno sin impacto externo? | Proceder con tests |
+
+**Reglas:**
+- Toda migración de base de datos debe ser **reversible** (`up` + `down`)
+- Nunca eliminar columnas/tablas sin período de deprecación
+- Cambios en APIs públicas requieren versionado
+
+## 3. Análisis Previo Obligatorio
+
+**ANTES de crear código nuevo:**
+
+1. **Buscar** si ya existe funcionalidad similar en el proyecto
+2. **Revisar** specs existentes relacionadas
+3. **Verificar** patrones establecidos en el código
+4. **Consultar** `context/conventions.md` del proyecto
+
+```bash
+# Buscar código existente antes de crear
+grep -r "función_similar" src/
+# Revisar specs relacionadas
+ls openspec/specs/functional/ | grep "tema"
+```
+
+**Si existe algo similar:** reutilizar o extender, NO duplicar.
+
+## 4. Consistencia de Patrones
+
+**Replicar EXACTAMENTE los patrones existentes del proyecto.**
+
+- Si el proyecto usa Services → crear un Service, no inventar otra capa
+- Si los Controllers siguen un formato → seguir ese formato exacto
+- Si hay una convención de nombres → respetarla
+
+**Antes de introducir un patrón nuevo:**
+1. Documentar por qué el patrón actual no sirve
+2. Proponer el nuevo patrón en una spec
+3. Obtener aprobación antes de implementar
+
+## 5. Comunicación de Errores
+
+Cuando se detecta un error, documentar con esta estructura:
+
+```markdown
+### Error detectado
+- **Causa:** [descripción técnica de la causa raíz]
+- **Impacto:** [qué afecta y a quién]
+- **Solución:** [qué se hizo para resolverlo]
+- **Verificación:** [cómo se verificó que está resuelto]
+- **Prevención:** [qué se puede hacer para evitarlo en el futuro]
+```
+
+## 6. Fix de Errores por Análisis
+
+Al encontrar un error:
+
+1. **Primero:** Buscar código que YA funciona en el proyecto como referencia
+2. **Segundo:** Analizar la diferencia entre lo que funciona y lo que falla
+3. **Tercero:** Aplicar la corrección basándose en el patrón funcional
+4. **Nunca:** Copiar soluciones externas sin adaptarlas al proyecto
+
+## 7. Métodos Estáticos vs Instancia
+
+Guía para decidir cuándo usar cada uno:
+
+| Usar estático cuando | Usar instancia cuando |
+|---------------------|----------------------|
+| No necesita estado interno | Necesita estado o configuración |
+| Es una utilidad pura (helper) | Tiene dependencias inyectadas |
+| No necesita ser mockeado en tests | Debe ser testeable con mocks |
+| Operación sin efectos secundarios | Interactúa con DB, APIs, filesystem |
+
+## 8. Prohibición de Archivos en Raíz
+
+**JAMÁS crear archivos sueltos en la raíz del proyecto** sin autorización explícita.
+
+Todo archivo debe ir en su carpeta correspondiente:
+- Código → `src/`
+- Tests → `tests/`
+- Configuración → `config/`
+- Documentación → `docs/`
+- Specs → `openspec/specs/`
+
+---
+
+*Estas reglas son obligatorias. Cualquier excepción debe ser aprobada y documentada en `context/decisions.md`.*

package/rules/environment-protection.md

@@ -0,0 +1,97 @@
+# Protección del Entorno — SpecLeap
+
+> Reglas para proteger archivos críticos y mantener la integridad del proyecto.
+
+## Archivos Protegidos
+
+Los siguientes archivos y carpetas requieren **confirmación explícita** antes de ser modificados:
+
+### 🔴 Nivel Máximo — Nunca modificar sin aprobación
+
+| Archivo/Carpeta | Razón |
+|----------------|-------|
+| `openspec/specs/` | Contratos funcionales del proyecto |
+| `openspec/changes/` | Historial de propuestas de cambio |
+| `context/` | Memoria y contexto del proyecto |
+| `.env` | Variables de entorno sensibles |
+| `config/` | Configuración central |
+| `main` branch | Rama de producción |
+
+### 🟡 Nivel Alto — Confirmar antes de modificar
+
+| Archivo/Carpeta | Razón |
+|----------------|-------|
+| `rules/` | Reglas del proyecto |
+| `AGENTS.md` | Configuración de agentes AI |
+| `README.md` | Documentación principal |
+| Migraciones de DB | Afectan datos existentes |
+
+## Reglas de Protección
+
+### 1. Specs como Fuente de Verdad
+
+Las specs en `openspec/specs/` son **contratos**. Para modificar una spec:
+
+1. Crear una propuesta de cambio (`openspec/changes/`)
+2. Documentar QUÉ cambia y POR QUÉ
+3. Obtener aprobación
+4. Solo entonces modificar la spec
+
+**NUNCA** modificar una spec directamente sin propuesta.
+
+### 2. Context como Memoria del Proyecto
+
+Los archivos en `context/` documentan decisiones arquitectónicas. Para modificarlos:
+
+1. Verificar que el cambio refleja una decisión real (no una suposición)
+2. Documentar la fecha y razón del cambio
+3. Actualizar `context/decisions.md` con la nueva decisión
+
+### 3. Protección de Archivos en Producción
+
+Antes de tocar archivos que afectan producción:
+
+```
+⚠️ PREGUNTA: ¿Este cambio puede afectar al entorno de producción?
+
+SI → Requiere:
+  1. Review de al menos 1 persona
+  2. Plan de rollback documentado
+  3. Ventana de mantenimiento acordada
+
+NO → Proceder con el flujo normal
+```
+
+### 4. Archivos que NUNCA Deben Subirse al Repositorio
+
+| Archivo | Razón |
+|---------|-------|
+| `.env` | Credenciales sensibles |
+| `*.log` | Logs de desarrollo |
+| `node_modules/` | Dependencias (se instalan) |
+| `vendor/` | Dependencias PHP (se instalan) |
+| `storage/*.key` | Claves privadas |
+| `*.sqlite` | Bases de datos locales |
+
+Verificar que `.gitignore` incluye todos estos patrones.
+
+### 5. Backups Antes de Cambios Destructivos
+
+Antes de:
+- Eliminar archivos o carpetas
+- Modificar migraciones existentes
+- Cambiar estructura de base de datos
+- Resetear ramas
+
+**Hacer backup:**
+```bash
+# Backup de archivos
+cp -r carpeta/ carpeta.backup/
+
+# Backup de rama
+git branch backup/nombre-rama
+```
+
+---
+
+*La protección del entorno no es opcional. Estas reglas previenen pérdida de trabajo y datos.*

package/rules/git-workflow.md

@@ -0,0 +1,142 @@
+# Git Workflow — SpecLeap
+
+> Protocolo completo de control de versiones. Todas las reglas son obligatorias.
+
+## Reglas Críticas
+
+### 1. NUNCA push sin autorización
+
+```
+🚫 PROHIBIDO hacer push directamente sin aprobación explícita del responsable.
+```
+
+Flujo obligatorio:
+1. Desarrollar en rama local
+2. Verificar que tests pasan
+3. Solicitar aprobación
+4. Solo después de "aprobado" → push
+
+### 2. Reglas de Ramas Protegidas
+
+| Rama | Protección | Quién puede mergear |
+|------|-----------|---------------------|
+| `main` | 🔴 Máxima — solo releases | Lead/CTO |
+| `stage` | 🟡 Alta — solo PRs aprobados | Lead + reviewer |
+| `feature/*` | 🟢 Normal — desarrollo activo | Desarrollador asignado |
+| `fix/*` | 🟢 Normal — correcciones | Desarrollador asignado |
+
+**NUNCA:**
+- Hacer commit directo a `main`
+- Hacer commit directo a `stage`
+- Forzar push (`--force`) a ramas protegidas
+- Eliminar ramas protegidas
+
+### 3. Crear Ramas desde Stage
+
+**Toda rama nueva DEBE crearse desde `stage`:**
+
+```bash
+git checkout stage
+git pull origin stage
+git checkout -b feature/SCRUM-XX-descripcion
+```
+
+**Verificar** que la rama parte de stage:
+```bash
+git log --oneline stage..HEAD  # Debe mostrar solo tus commits
+```
+
+### 4. Convención de Nombres de Ramas
+
+```
+tipo/TICKET-ID-descripcion-corta
+```
+
+| Tipo | Uso |
+|------|-----|
+| `feature/` | Nueva funcionalidad |
+| `fix/` | Corrección de bug |
+| `refactor/` | Reestructuración sin cambio funcional |
+| `docs/` | Solo documentación |
+| `test/` | Solo tests |
+
+**Ejemplos:**
+```
+feature/SCRUM-23-integracion-jira
+fix/SCRUM-45-error-login-timeout
+refactor/SCRUM-12-optimizar-queries
+```
+
+### 5. Formato de Commits
+
+```
+TICKET-ID: tipo(alcance): descripción
+
+Cuerpo opcional con más detalle.
+
+Refs: SPEC-XXX
+```
+
+**Ejemplos:**
+```
+SCRUM-23: feat(auth): implementar login con 2FA
+SCRUM-45: fix(api): corregir timeout en endpoint /users
+SCRUM-12: refactor(db): optimizar queries de dashboard
+```
+
+**Tipos:** `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `style`
+
+### 6. Protocolo Antes de Operaciones Git
+
+Antes de cualquier operación Git significativa (merge, rebase, push):
+
+```
+1. VERIFICAR  → git status, git log, rama correcta
+2. PREGUNTAR  → ¿Es seguro? ¿Afecta a otros?
+3. GUARDAR    → Stash o commit de trabajo en progreso
+4. EJECUTAR   → La operación Git
+5. VERIFICAR  → Confirmar que todo está correcto
+```
+
+### 7. Acciones Post-Pull (Laravel)
+
+Después de un `git pull` en proyectos Laravel:
+
+```bash
+composer install          # Dependencias PHP
+npm install               # Dependencias JS
+php artisan migrate       # Migraciones pendientes
+php artisan cache:clear   # Limpiar cache
+php artisan config:clear  # Limpiar config cache
+php artisan view:clear    # Limpiar vistas compiladas
+```
+
+### 8. Pull Requests
+
+**Todo PR debe incluir:**
+
+- Referencia al ticket: `SCRUM-XX`
+- Referencia a la spec: `SPEC-XXX`
+- Descripción de cambios
+- Checklist de verificación:
+
+```markdown
+## Checklist
+- [ ] Tests pasan localmente
+- [ ] Spec actualizada si hubo cambios
+- [ ] Sin archivos hardcodeados
+- [ ] Code review solicitado
+- [ ] Documentación actualizada
+```
+
+### 9. Merge Strategy
+
+| Situación | Estrategia |
+|-----------|-----------|
+| Feature → stage | Squash merge (1 commit limpio) |
+| Stage → main | Merge commit (preservar historial) |
+| Hotfix → main | Cherry-pick + merge a stage |
+
+---
+
+*Estas reglas son obligatorias para todos los contribuidores del proyecto.*

package/rules/session-protocol.md

@@ -0,0 +1,121 @@
+# Protocolo de Inicio de Sesión — SpecLeap
+
+> Procedimiento obligatorio al iniciar cualquier sesión de desarrollo.
+
+## Al Iniciar Sesión
+
+### Paso 1: Identificar Proyecto
+
+```
+¿En qué proyecto vamos a trabajar?
+```
+
+Cargar el contexto del proyecto desde `context/`:
+- `context/brief.md` — Resumen del proyecto
+- `context/tech-stack.md` — Stack y versiones
+- `context/conventions.md` — Patrones y convenciones
+
+### Paso 2: Verificar Estado Git
+
+```bash
+git status                    # ¿Hay cambios pendientes?
+git branch                    # ¿En qué rama estamos?
+git log --oneline -5          # ¿Últimos commits?
+git stash list                # ¿Hay stashes pendientes?
+```
+
+Si hay trabajo en progreso sin commit → preguntar antes de continuar.
+
+### Paso 3: Identificar Tipo de Tarea
+
+| Tipo | Flujo |
+|------|-------|
+| **Nueva feature** | Ticket → Spec → Rama → Implementar → Test → PR |
+| **Fix/Bug** | Ticket → Analizar → Rama → Fix → Test → PR |
+| **Refactor** | Ticket → Spec de cambio → Rama → Refactor → Test → PR |
+| **Documentación** | Actualizar docs/context → Commit → PR |
+| **Investigación** | Documentar hallazgos en context/ |
+
+### Paso 4: Verificar Ticket
+
+```
+¿Hay un ticket en Jira asociado a esta tarea?
+```
+
+- **Sí** → Usar el ID del ticket (SCRUM-XX) en rama y commits
+- **No** → Crear el ticket antes de empezar
+
+**No se empieza desarrollo sin ticket.**
+
+### Paso 5: Verificar Spec
+
+```
+¿Existe una spec para esta funcionalidad?
+```
+
+- **Sí** → Leerla antes de implementar
+- **No** → Crearla con `openspec new` antes de codificar
+- **Parcial** → Completarla antes de implementar
+
+## Al Finalizar Sesión
+
+### 1. Guardar Progreso
+
+```bash
+git add -A
+git commit -m "SCRUM-XX: wip: descripción del progreso"
+```
+
+### 2. Actualizar Contexto (si aplica)
+
+Si durante la sesión se tomaron decisiones importantes:
+- Actualizar `context/decisions.md`
+- Actualizar specs si cambiaron requisitos
+
+### 3. Documentar Estado
+
+Dejar nota clara de:
+- Qué se completó
+- Qué queda pendiente
+- Bloqueos encontrados
+
+## Flujo Completo de Feature
+
+```
+1. TICKET (Jira)
+   └── Crear/asignar ticket SCRUM-XX
+
+2. SPEC (SpecLeap)
+   └── openspec new "feature"
+   └── Revisar spec → Aprobar
+
+3. PLANIFICACIÓN
+   └── openspec ff (genera design + tasks)
+   └── Revisar design → Aprobar
+
+4. DESARROLLO
+   ├── git checkout stage && git pull
+   ├── git checkout -b feature/SCRUM-XX-nombre
+   ├── Análisis previo (buscar código existente)
+   ├── Implementar siguiendo patrones del proyecto
+   └── Tests unitarios + integración
+
+5. VERIFICACIÓN
+   └── openspec verify
+
+6. REVIEW
+   ├── openspec code-review
+   └── PR con referencia a SCRUM-XX y SPEC-XXX
+
+7. MERGE
+   └── Squash merge a stage (con aprobación)
+
+8. POST-DESARROLLO
+   ├── Actualizar context/ si hubo decisiones
+   ├── Actualizar spec si cambió
+   └── Cerrar ticket en Jira
+```
+
+---
+
+*Seguir este protocolo garantiza que ninguna tarea se ejecuta sin contexto, sin ticket, ni sin spec.*

package/scripts/README.md

@@ -0,0 +1,129 @@
+# SpecLeap Scripts
+
+Colección de scripts de automatización para SpecLeap.
+
+---
+
+## 📋 Scripts Disponibles
+
+### `install-git-hooks.sh`
+
+**Propósito:** Instalar git hooks de validación automática en proyectos
+
+**Uso:**
+```bash
+# Desde la raíz del proyecto
+bash scripts/install-git-hooks.sh
+
+# O especificando ruta
+bash scripts/install-git-hooks.sh /path/to/proyecto
+```
+
+**Qué instala:**
+- **Pre-commit hook** — Validación rápida antes de cada commit
+
+**Validaciones incluidas:**
+- ✅ Sintaxis PHP (php -l)
+- ✅ ESLint (JS/TS)
+- ✅ Prettier (formateo)
+- ✅ PHPStan (análisis estático PHP)
+- ✅ PHP-CS-Fixer (estilo PHP)
+- ✅ CONTRATO.md no se modifica (es inmutable)
+- ✅ No hay TODOs críticos
+- ✅ No hay código debug (console.log, var_dump, dd())
+
+**Tiempo de ejecución:** <5 segundos
+
+**Saltarse validación (NO recomendado):**
+```bash
+git commit --no-verify -m "mensaje"
+```
+
+---
+
+### `setup-mcp.sh`
+
+**Propósito:** Instalación rápida de dependencias SpecLeap
+
+**Uso:**
+```bash
+bash scripts/setup-mcp.sh
+```
+
+**Instala:**
+- ✅ Cliente Asana (npm global)
+- ✅ 20 Agent Skills TIER 1
+- ✅ Context7 MCP (opcional)
+
+**Tiempo:** ~5 minutos
+
+---
+
+### `install-skills.sh`
+
+**Propósito:** Instalar Agent Skills manualmente
+
+**Uso:**
+```bash
+bash scripts/install-skills.sh
+```
+
+**Instala:** 20 Agent Skills TIER 1 en `~/.skills/`
+
+**Skills incluidas:**
+- 5 skills de seguridad (SAST, STRIDE, OWASP)
+- 3 skills de consistencia (verification-before-completion, DRY)
+- 6 skills de diseño (Vercel-style, Tailwind, shadcn/ui)
+- 6 skills de backend/dev (Laravel, React, TDD, API design)
+
+---
+
+## 🔧 Troubleshooting
+
+### Git hooks no se ejecutan
+
+**Causa:** Permisos incorrectos
+
+**Solución:**
+```bash
+chmod +x .git/hooks/pre-commit
+```
+
+### ESLint no encontrado
+
+**Solución:**
+```bash
+npm install -D eslint
+# o globalmente
+npm install -g eslint
+```
+
+### PHPStan no encontrado
+
+**Solución:**
+```bash
+composer require --dev phpstan/phpstan
+# o globalmente
+composer global require phpstan/phpstan
+```
+
+### Hook muy lento
+
+**Causa:** Demasiados archivos staged
+
+**Solución:** Commit en batches más pequeños
+```bash
+git add archivo1.js
+git commit -m "feat: archivo 1"
+git add archivo2.js
+git commit -m "feat: archivo 2"
+```
+
+---
+
+## 📚 Referencias
+
+- **Git Hooks:** https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks
+- **ESLint:** https://eslint.org
+- **PHPStan:** https://phpstan.org
+- **PHP-CS-Fixer:** https://cs.symfony.com