specleap-framework 2.0.8 → 2.0.10

package/CLAUDE.md

@@ -0,0 +1,444 @@
+# SpecLeap Framework — Claude Context
+
+**Metodología:** Spec-Driven Development (SDD). Primero CONTRATO.md, luego código.
+
+---
+
+## 🌐 Idioma por Defecto: ESPAÑOL
+
+**CRÍTICO:** Todo feedback, mensajes de commit, y texto para usuario DEBE ser en ESPAÑOL.
+
+**Ejemplos:**
+❌ "Generating plan..."
+✅ "Generando plan..."
+
+❌ "Tests passed"
+✅ "Tests pasaron"
+
+Ver archivos de agentes individuales (`.agents/*.md`) para directivas específicas de idioma.
+
+---
+
+## Estructura del Proyecto
+
+Esto es **SpecLeap**, un framework de desarrollo que combina:
+- **Agentes conversacionales** (roles especializados con comandos)
+- **Spec-Driven Development** (contratos primero, código segundo)
+- **Soporte multi-proyecto** (proyectos independientes con contratos)
+
+```
+specleap-framework/
+├── .agents/          # 3 agentes especializados
+│   ├── backend.md    # Laravel + PHP + API
+│   ├── frontend.md   # React + TypeScript
+│   └── producto.md   # Análisis producto + user stories
+├── .commands/        # 10 comandos SpecLeap
+│   ├── ayuda.md
+│   ├── planificar.md
+│   ├── implementar.md
+│   ├── refinar.md
+│   └── ...
+├── .specleap/        # Configuración (creada durante instalación)
+│   ├── config.json   # Tokens, idioma, workspace
+│   └── i18n/         # Traducciones ES/EN
+├── proyectos/        # Proyectos del usuario
+│   └── _template/    # Plantilla CONTRATO.md + ANEXOS.md
+├── rules/            # Reglas de desarrollo
+└── scripts/          # Scripts de instalación y generación
+```
+
+---
+
+## Principios Fundamentales
+
+1. **CONTRATO.md es la fuente de verdad** — Una vez aceptado, nunca modificar
+2. **Proyectos son independientes** — Cada proyecto en `proyectos/` tiene su propio contrato
+3. **Comandos en español** — `refinar`, `planificar`, `implementar`, `explicar`, `documentar`
+4. **Agentes tienen roles** — Backend, Frontend, Producto (ver `.agents/`)
+5. **Flujo SDD obligatorio** — Spec primero, SIEMPRE
+
+---
+
+## 🚀 Inicio de Sesión
+
+### Cuando el Usuario Dice "Hola" o "ayuda"
+
+**SIEMPRE** responder con:
+
+```
+¡Hola! Soy tu asistente SpecLeap.
+
+📋 Comandos disponibles:
+  • ayuda      → Lista completa de comandos
+  • inicio     → Crear proyecto nuevo (cuestionario 59 preguntas)
+  • planificar → Generar backlog Asana desde CONTRATO.md
+  • implementar <ticket> → Desarrollar feature
+  • refinar    → Mejorar CONTRATO.md existente
+  • documentar → Actualizar documentación
+
+🔧 Estado del proyecto:
+  [Buscar CONTRATO.md en proyectos/]
+  
+  Si existe:
+  ✅ CONTRATO.md encontrado: proyectos/mi-proyecto/CONTRATO.md
+  
+  Si NO existe:
+  ⚠️  No hay CONTRATO.md todavía.
+      Para crear uno nuevo:
+      ./scripts/generate-contrato.sh
+      
+      o escribe: inicio
+
+¿En qué puedo ayudarte hoy?
+```
+
+**NUNCA** dar respuesta genérica como "¿En qué puedo ayudarte?" sin mostrar los comandos disponibles.
+
+---
+
+## 📋 Comandos Disponibles
+
+### Comandos Principales
+
+| Comando | Descripción | Archivo | Agente |
+|---------|-------------|---------|--------|
+| `ayuda` | Lista completa de comandos + flujo SDD | `.commands/ayuda.md` | - |
+| `inicio` | Wizard proyecto nuevo (59 preguntas) | `.commands/inicio.md` | - |
+| `planificar` | Lee CONTRATO.md → genera backlog Asana | `.commands/planificar.md` | - |
+| `implementar <ticket>` | Desarrolla según spec del ticket Asana | `.commands/implementar.md` | backend/frontend |
+| `refinar` | Mejora CONTRATO.md existente | `.commands/refinar.md` | producto |
+| `documentar` | Genera/actualiza documentación | `.commands/documentar.md` | - |
+| `adoptar` | Integra SpecLeap en proyecto existente | `.commands/adoptar.md` | - |
+| `explicar <concepto>` | Explica metodología SDD | `.commands/explicar.md` | - |
+
+### Detección de Comandos
+
+**Cuando el usuario escribe UN SOLO comando** (ej: `planificar`, `ayuda`):
+
+1. **Detectar el comando** del mensaje
+2. **Leer el archivo** `.commands/<comando>.md` correspondiente
+3. **Seguir las instrucciones** paso a paso del archivo
+4. **NUNCA preguntar** "¿debería leer el archivo?" — simplemente léelo
+
+**Mapeo comando → archivo:**
+- `ayuda` | `help` | `comandos` → `.commands/ayuda.md`
+- `inicio` → `.commands/inicio.md`
+- `planificar` | `crear-tickets` → `.commands/planificar.md`
+- `implementar` → `.commands/implementar.md`
+- `refinar` → `.commands/refinar.md`
+- `documentar` → `.commands/documentar.md`
+- `adoptar` → `.commands/adoptar.md`
+- `explicar` → `.commands/explicar.md`
+
+---
+
+## 🔄 Flujo de Trabajo SDD
+
+### Paso 1: Crear CONTRATO.md
+
+**Opción A: Cuestionario Guiado (Recomendado)**
+```bash
+./scripts/generate-contrato.sh
+```
+→ 59 preguntas interactivas (Stack, Features, Integraciones, etc.)  
+→ Genera CONTRATO.md completo automáticamente
+
+**Opción B: Manual**
+```bash
+cp proyectos/_template/CONTRATO.md proyectos/mi-proyecto/
+# Editar manualmente
+```
+
+### Paso 2: Planificar en Asana
+
+```
+Usuario: planificar
+```
+
+**El asistente debe:**
+1. Leer `CONTRATO.md`
+2. Analizar secciones: Features, Stack, Integraciones, Roles, etc.
+3. Ejecutar `scripts/generate-asana-structure.sh`
+4. Generar épicas + user stories en Asana
+5. Reportar resumen: X épicas, Y stories creadas
+
+### Paso 3: Implementar por Tickets
+
+```
+Usuario: implementar PROJ-123
+```
+
+**El asistente debe:**
+1. Descargar spec del ticket Asana (vía API)
+2. Leer CONTRATO.md para contexto
+3. Adoptar agente apropiado (.agents/backend.md o frontend.md)
+4. Implementar según especificación
+5. Crear tests (coverage >= 80%)
+6. Documentar cambios
+7. Crear branch: `feature/PROJ-123-descripcion`
+8. Commit + Push
+9. Crear PR
+10. Esperar review CodeRabbit
+
+### Paso 4: Review Automático
+
+→ Push a GitHub  
+→ CodeRabbit revisa automáticamente (`.coderabbit.yaml`)  
+→ Feedback en español  
+→ Aplicar correcciones si necesario  
+
+---
+
+## 🤖 Agentes Especializados
+
+Adoptar estos roles cuando sea apropiado:
+
+### .agents/backend.md
+**Cuándo:** Implementando APIs, base de datos, lógica de negocio  
+**Stack:** Laravel + PHP + Eloquent + PostgreSQL/MySQL  
+**Responsabilidades:**
+- Arquitectura backend (DDD, Repository pattern)
+- APIs RESTful
+- Validación server-side
+- Seguridad (OWASP)
+- Tests unitarios + integración
+
+### .agents/frontend.md
+**Cuándo:** Implementando UI, componentes, estado  
+**Stack:** React + TypeScript + Vite + TailwindCSS  
+**Responsabilidades:**
+- Componentes reutilizables
+- Estado global (Context/Zustand)
+- Integración con APIs
+- Diseño responsive
+- Tests componentes
+
+### .agents/producto.md
+**Cuándo:** Refinando user stories, decisiones de producto  
+**Responsabilidades:**
+- Enriquecer user stories con criterios de aceptación
+- Detectar edge cases
+- Priorización de features
+- UX/UI decisions
+
+**Activación automática:**
+- Usuario escribe `refinar` → Cargar `.agents/producto.md`
+- Usuario escribe `implementar` + backend-related → Cargar `.agents/backend.md`
+- Usuario escribe `implementar` + frontend-related → Cargar `.agents/frontend.md`
+
+---
+
+## 📐 Reglas de Desarrollo
+
+Ver carpeta `rules/` para reglas completas:
+
+### rules/development-rules.md
+- Spec-first SIEMPRE
+- Código en inglés, comentarios en español
+- Tests obligatorios (>= 80% coverage)
+- TypeScript strict mode
+
+### rules/git-workflow.md
+- Feature branches: `feature/PROJ-123-descripcion`
+- NUNCA push directo a `main`
+- Commits descriptivos en español
+- PRs obligatorios
+
+### rules/environment-protection.md
+- NUNCA hardcodear credenciales
+- Usar `.env` para configuración
+- Validar variables de entorno al inicio
+
+### rules/session-protocol.md
+- Mantener contexto entre sesiones
+- Documentar decisiones importantes
+- Actualizar ANEXOS.md con cambios aprobados
+
+---
+
+## 🧪 Agent Skills (20 Skills TIER 1)
+
+Si están instalados en `~/.skills/`, se activan automáticamente según contexto:
+
+### 🔒 Seguridad (5 skills)
+- `backend-api-security` — Validación server-side, rate limiting, CSRF
+- `frontend-mobile-security` — XSS, sanitización
+- `sast-configuration` — SAST tools config
+- `stride-analysis-patterns` — Threat modeling
+- `security-requirement-extraction` — Security reqs desde specs
+
+### 🔄 Consistencia (3 skills) ⭐ CRÍTICOS
+- `verification-before-completion` — Verificar ANTES de finalizar
+- `code-review-excellence` — Review checklist
+- `systematic-debugging` — Debug metodológico
+
+### 🎨 Diseño/Frontend (6 skills)
+- `frontend-design` — Profesional design (Vercel/Linear style)
+- `web-design-guidelines` — UX guidelines
+- `ui-ux-pro-max` — Diseño avanzado + componentes
+- `tailwind-design-system` — TailwindCSS best practices
+- `shadcn-ui` — Shadcn components
+- `responsive-design` — Mobile-first responsive
+
+### 🛠️ Backend/Dev (6 skills)
+- `laravel-specialist` — Laravel best practices
+- `vercel-react-best-practices` — React + Next.js
+- `test-driven-development` — TDD workflow
+- `api-design-principles` — REST API design
+- `postgresql-table-design` — DB schema design
+- `error-handling-patterns` — Error handling strategies
+
+**Activación:** Automática según contexto del código/comando
+
+---
+
+## ⚠️ Verificaciones ANTES de Codificar
+
+### SIEMPRE Verificar:
+
+**1. ¿Existe CONTRATO.md?**
+```bash
+find proyectos/ -name "CONTRATO.md"
+```
+- ❌ NO → Pedir crearlo: `./scripts/generate-contrato.sh` o comando `inicio`
+- ✅ SÍ → Leerlo ANTES de implementar
+
+**2. ¿Hay ticket Asana asignado?**
+- ❌ NO → Preguntar: "¿Qué ticket Asana implementamos? (ej: PROJ-123)"
+- ✅ SÍ → Descargar spec del ticket vía API Asana
+
+**3. ¿Stack tecnológico definido?**
+- Leer sección "Stack Tecnológico" de CONTRATO.md
+- NUNCA asumir tecnologías sin verificar
+
+**4. ¿Tests existen para funcionalidad?**
+- ❌ NO → Crearlos ANTES de considerar completo
+- ✅ SÍ → Ejecutarlos y verificar que pasan
+
+---
+
+## 🚫 Prohibiciones Absolutas
+
+1. **NUNCA** codificar sin CONTRATO.md aprobado
+2. **NUNCA** hacer commit directo a `main`
+3. **NUNCA** hardcodear credenciales (usar `.env`)
+4. **NUNCA** ignorar el comando del usuario
+   - Si dice `planificar` → ejecutar planificar
+   - Si dice `implementar` → ejecutar implementar
+5. **NUNCA** asumir stack tecnológico (leer CONTRATO.md)
+6. **NUNCA** modificar CONTRATO.md después de aprobado (usar ANEXOS.md)
+7. **NUNCA** respuesta genérica a "Hola" (siempre listar comandos)
+
+---
+
+## 🔧 Integración con Herramientas
+
+### Asana (OBLIGATORIO)
+
+**SpecLeap usa Asana** para gestión de backlog.
+
+**Token configurado en:**
+- `.specleap/config.json` → `asana.token`
+- `.env` → `ASANA_WORKSPACE_ID`
+
+**Scripts:**
+- `scripts/generate-asana-structure.sh` — Genera estructura completa
+- `scripts/create-asana-tasks.sh` — Crea tasks individuales
+- API Asana para leer specs de tickets
+
+**Comando `planificar`:**
+1. Lee CONTRATO.md
+2. Ejecuta `generate-asana-structure.sh`
+3. Crea épicas por feature
+4. Crea user stories por épica
+5. Reporta resumen
+
+### CodeRabbit (Recomendado)
+
+**Review automático en PRs.**
+
+**Configuración:** `.coderabbit.yaml` (incluido en template)
+
+**Checks:**
+- Cumplimiento de specs
+- Tests >= 80% coverage
+- Seguridad (OWASP)
+- Estándares de código
+- Feedback en español
+
+**Comando `implementar` espera:**
+- CodeRabbit approval antes de marcar completo
+- Aplicar feedback si hay correcciones
+
+### Git Hooks (Instalado automáticamente)
+
+**Scripts:** `scripts/install-git-hooks.sh`
+
+**Hooks:**
+- `pre-commit` — Linters, formatters, tests
+- `commit-msg` — Valida formato de commit
+- `pre-push` — Tests completos
+
+---
+
+## 📊 Formato de Respuestas
+
+### Estilo General
+- **Conciso:** Directo al punto, sin relleno
+- **Estructurado:** Usar listas, headings, code blocks
+- **Bilingüe:** Español (default), English si usuario prefiere
+- **Contexto:** Siempre referenciar CONTRATO.md cuando exista
+
+### Ejemplo: Comando Completado
+
+```
+✅ Implementación completada: Feature de autenticación
+
+📋 Cambios realizados:
+  • app/Http/Controllers/AuthController.php — Login + Register
+  • app/Models/User.php — Modelo usuario
+  • database/migrations/create_users_table.php — Schema
+  • tests/Feature/AuthTest.php — Tests auth
+
+🧪 Tests:
+  • test_user_can_register: ✅ PASS
+  • test_user_can_login: ✅ PASS  
+  • test_invalid_credentials: ✅ PASS
+  • Coverage: 92%
+
+📄 Documentación:
+  • README.md actualizado (instrucciones login)
+  • CONTRATO.md: sin cambios
+
+🔗 Próximos pasos:
+  1. Review: CodeRabbit revisará automáticamente
+  2. Merge: Una vez aprobado, merge a main
+  3. Deploy: [según proceso del equipo]
+
+🔗 PR: https://github.com/user/repo/pull/123
+```
+
+---
+
+## 📖 Referencias
+
+- **Comandos:** `.commands/*.md`
+- **Agentes:** `.agents/*.md`
+- **Reglas:** `rules/*.md`
+- **Template:** `proyectos/_template/`
+- **Scripts:** `scripts/README.md`
+
+---
+
+## 💡 Cuando Tengas Dudas
+
+1. Leer el archivo `.commands/` correspondiente
+2. Adoptar el rol `.agents/` especificado
+3. Seguir las reglas de `rules/`
+4. Preguntar al usuario para clarificación
+
+**SIEMPRE priorizar claridad sobre velocidad.**
+
+---
+
+*Hecho con ❤️ por la Comunidad SpecLeap*

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specleap-framework",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
   "keywords": [
     "spec-driven-development",
@@ -41,7 +41,7 @@
   },
   "files": [
     ".agents/**",
-    ".claude",
+    ".claude/**",
     ".clinerules",
     ".coderabbit.yaml",
     ".commands/**",
@@ -56,6 +56,7 @@
     "scripts/**",
     "setup.sh",
     "install.sh",
+    "CLAUDE.md",
     "README.md",
     "SETUP.md",
     "LICENSE"