specleap-framework 2.0.0

package/SETUP.md

@@ -0,0 +1,351 @@
+# SpecLeap — Instalación Rápida
+
+## ⚡ Quick Start (5 minutos)
+
+### Paso 1: Clonar el repositorio
+
+```bash
+git clone https://github.com/iapanderson/specleap-framework.git
+cd specleap-framework
+```
+
+### Paso 2: Ejecutar instalador
+
+```bash
+bash install.sh
+```
+
+**Qué hace:**
+- Selecciona idioma (Español/English)
+- Crea estructura de carpetas
+- Genera archivos base
+
+### Paso 3: Responder cuestionario
+
+El instalador te hará **58 preguntas** sobre tu proyecto:
+- Nombre del proyecto
+- Objetivo y problema que resuelve
+- Stack tecnológico (Laravel, React, etc.)
+- Funcionalidades principales
+- Usuarios y roles
+- Seguridad y rendimiento
+
+**Tiempo:** 10-15 minutos
+
+**Resultado:** Genera automáticamente:
+- `CONTRATO.md` — Especificación inmutable del proyecto
+- `context/` — Arquitectura, diseño, decisiones técnicas
+- `.agents/` — 3 agentes especializados (Backend, Frontend, Producto)
+- `.commands/` — 8 comandos conversacionales
+
+### Paso 4: Abrir en tu IDE
+
+```bash
+code .        # VSCode
+# o
+cursor .      # Cursor
+```
+
+**¡Listo!** Di **"Hola"** en el chat con Claude/Cursor y empieza a trabajar.
+
+---
+
+## 🎯 Primeros Pasos
+
+### Comandos Conversacionales
+
+Escribe estos comandos directamente en el chat con Claude/Cursor:
+
+| Comando | Qué hace |
+|---------|----------|
+| `ayuda` | Lista TODOS los comandos disponibles |
+| `refinar "añadir login social"` | Propone cambios al CONTRATO |
+| `planificar` | Genera backlog en Asana |
+| `implementar "crear API usuarios"` | Valida contra CONTRATO e implementa |
+| `documentar "API REST"` | Genera docs OpenAPI/Swagger |
+| `explicar arquitectura` | Explica decisiones técnicas |
+
+### OpenSpec CLI Formal (Enterprise)
+
+Alternativa al workflow conversacional. Para equipos que requieren propuestas formales y trazabilidad:
+
+```bash
+# Proponer cambio
+./openspec/cli/openspec new "añadir carrito de compras"
+
+# Ver propuesta
+./openspec/cli/openspec show 001-carrito
+
+# Aprobar
+./openspec/cli/openspec approve 001-carrito
+
+# Verificar implementación
+./openspec/cli/openspec verify 001-carrito
+```
+
+---
+
+## 🔌 Sistema de Calidad (Componentes Obligatorios)
+
+**⚠️ IMPORTANTE:** Estos NO son opcionales. SpecLeap requiere estos componentes para SDD profesional:
+- **Asana** — Gestión de backlog (comando `planificar`)
+- **CodeRabbit** — Code review automático en PRs
+- **Agent Skills** — Best practices automáticas (20 skills TIER 1)
+- **Git Hooks** — Validación pre-commit local
+- **GitHub** — Control de versiones y colaboración
+
+Sin estos componentes, SpecLeap es solo un conjunto de archivos markdown.
+
+---
+
+### 1. Asana (Gestión de Backlog)
+
+**¿Por qué?** Comando `planificar` genera automáticamente épicas y user stories en Asana.
+
+#### Setup en 3 pasos:
+
+**1. Obtener token Asana:**
+- Ve a [app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)
+- Click **"Create new token"**
+- Nombre: `SpecLeap Integration`
+- Copia el token (empieza con `0/`)
+
+**2. Obtener Workspace ID:**
+
+```bash
+curl -H "Authorization: Bearer TU_TOKEN_AQUI" \
+     https://app.asana.com/api/1.0/workspaces
+```
+
+Copia el `"gid"` de tu workspace.
+
+**3. Configurar .env:**
+
+Edita `.env` en la raíz de SpecLeap:
+
+```bash
+ASANA_ACCESS_TOKEN="0/1234567890abcdef..."
+ASANA_WORKSPACE_ID="1234567890123456"
+```
+
+**Verificar:**
+
+```bash
+# En el chat con Claude:
+planificar
+
+# Debería crear proyecto en Asana con:
+# - Épicas (Features principales)
+# - User Stories (Funcionalidades)
+# - Tasks (Tareas técnicas)
+```
+
+---
+
+### 2. CodeRabbit (Code Review Automático)
+
+**¿Qué es?** Bot que revisa PRs automáticamente en GitHub.
+
+#### Setup:
+
+```bash
+# 1. Copiar config al proyecto
+cp .coderabbit.yaml tu-proyecto/.coderabbit.yaml
+
+# 2. Commit y push
+git add .coderabbit.yaml
+git commit -m "Add CodeRabbit config"
+git push origin main
+
+# 3. Instalar app GitHub
+# Ve a: https://github.com/apps/coderabbitai
+# Click "Install"
+```
+
+**Resultado:** CodeRabbit revisará automáticamente tus PRs con:
+- ✅ Security analysis
+- ✅ Best practices
+- ✅ Performance suggestions
+- ✅ Code smells
+
+---
+
+### 3. Agent Skills (20 Skills Profesionales)
+
+**¿Qué son?** Extensiones para Claude/Cursor que aplican best practices automáticamente.
+
+#### Instalación automática:
+
+```bash
+bash scripts/setup-mcp.sh
+```
+
+**Qué instala:**
+- 🔒 5 skills seguridad (SAST, STRIDE, OWASP)
+- 🔄 3 skills consistencia (verification-before-completion ⭐)
+- 🎨 6 skills diseño (Vercel-style, Tailwind, UI/UX)
+- 🛠️ 6 skills backend/dev (Laravel, React, TDD, API design)
+
+**Ver skills instaladas:**
+
+```bash
+ls ~/.skills/
+```
+
+**Más info:** Ver [docs/SKILLS-REFERENCE.md](docs/SKILLS-REFERENCE.md)
+
+---
+
+### 4. Git Hooks (Validación Local Pre-Commit)
+
+**Diferencia Git Hooks vs GitHub:**
+- **Git Hooks** = Validación LOCAL (en tu máquina) ANTES de hacer commit
+- **GitHub** = Repositorio REMOTO para push, pull, PRs y colaboración
+- Ambos son OBLIGATORIOS para SDD profesional
+
+**¿Por qué?** Valida código ANTES de hacer commit (linters, formatters, tests).
+
+#### Instalación:
+
+```bash
+cd tu-proyecto
+bash scripts/install-git-hooks.sh
+```
+
+**Qué valida:**
+- ✅ ESLint (JavaScript/React)
+- ✅ Prettier (formato código)
+- ✅ PHPStan (análisis estático PHP)
+- ✅ PHP-CS-Fixer (estándares PSR-12)
+- ✅ Previene debug code (console.log, var_dump)
+- ✅ Previene modificación CONTRATO.md
+
+**Ejemplo:**
+
+```bash
+git commit -m "feat: add login"
+
+→ 🔍 SpecLeap: Validando commit...
+→   ✓ ESLint: OK
+→   ✓ Prettier: OK
+→   ✓ PHPStan: OK
+→ ✅ Validación pre-commit exitosa
+
+[main a1b2c3d] feat: add login
+ 3 files changed, 45 insertions(+)
+```
+
+**Si falla:**
+
+```bash
+git commit -m "feat: add login"
+
+→ 🔍 SpecLeap: Validando commit...
+→   ✗ ESLint: 2 errores encontrados
+→     - src/Login.jsx:15 - 'userName' is defined but never used
+→     - src/Login.jsx:23 - Missing return statement
+→ ❌ Validación fallida. Corrige los errores y vuelve a intentar.
+```
+
+El commit es rechazado. Corrige y vuelve a intentar.
+
+---
+
+## 📚 Documentación Completa
+
+### Guías Detalladas
+
+- 📖 [README.md](README.md) — Overview del framework
+- 💬 [docs/COMANDOS.md](docs/COMANDOS.md) — 8 comandos conversacionales explicados
+- 🛠️ [docs/CLI-OPENSPEC.md](docs/CLI-OPENSPEC.md) — OpenSpec CLI formal (enterprise)
+- 🤖 [docs/AGENTES.md](docs/AGENTES.md) — 3 agentes especializados
+- ⭐ [docs/SKILLS-REFERENCE.md](docs/SKILLS-REFERENCE.md) — Quick reference 20 Agent Skills
+- 🎯 [docs/SPEC-CUESTIONARIO-INTERACTIVO.md](docs/SPEC-CUESTIONARIO-INTERACTIVO.md) — Sistema 58 preguntas
+
+### Prerequisitos del Sistema
+
+- **Git** — Control de versiones
+- **Node.js v20+** — Para cliente npm packages
+- **npm** o **pnpm** — Gestor de paquetes
+
+#### Opcional (según tu stack):
+
+- **PHP 8.3+** — Para proyectos Laravel
+- **Composer** — Gestor dependencias PHP
+- **PostgreSQL/MySQL** — Base de datos
+- **Docker** — Entornos containerizados
+
+---
+
+## 🆘 Troubleshooting
+
+### "Command not found: openspec"
+
+```bash
+# Usa ruta relativa
+./openspec/cli/openspec --version
+
+# O agrega a PATH (opcional)
+export PATH="$PATH:$(pwd)/openspec/cli"
+```
+
+### "Agent Skills no aparecen en mi IDE"
+
+1. Verifica instalación:
+```bash
+ls -la ~/.skills/
+```
+
+2. Reinicia tu IDE (VSCode/Cursor/JetBrains)
+
+3. Verifica config MCP:
+```bash
+cat ~/.config/claude/claude_desktop_config.json
+```
+
+### "Error al generar backlog Asana"
+
+1. Verifica que `.env` tiene token correcto:
+```bash
+cat .env | grep ASANA
+```
+
+2. Test API:
+```bash
+curl -H "Authorization: Bearer $ASANA_ACCESS_TOKEN" \
+     https://app.asana.com/api/1.0/users/me
+```
+
+Si da error 401: Token inválido. Genera uno nuevo en Asana.
+
+### "Git hooks no se ejecutan"
+
+```bash
+# Verifica permisos
+ls -la .git/hooks/pre-commit
+
+# Debe ser ejecutable (-rwxr-xr-x)
+# Si no lo es:
+chmod +x .git/hooks/pre-commit
+```
+
+---
+
+## ✅ Checklist de Setup Completo
+
+- [ ] SpecLeap clonado y `install.sh` ejecutado
+- [ ] Cuestionario 58 preguntas completado
+- [ ] CONTRATO.md generado automáticamente
+- [ ] IDE abierto (VSCode/Cursor) y chat con Claude funcional
+- [ ] Comando `ayuda` ejecutado exitosamente
+- [ ] **Asana configurado en `.env`** (OBLIGATORIO)
+- [ ] **20 Agent Skills instaladas en ~/.skills/** (OBLIGATORIO)
+- [ ] **Git hooks instalados** (OBLIGATORIO)
+- [ ] **CodeRabbit configurado en GitHub** (OBLIGATORIO)
+- [ ] **Repositorio pusheado a GitHub** (OBLIGATORIO)
+
+---
+
+**¡Listo para construir software spec-first! 🚀**
+
+**Próximo paso:** Di `"ayuda"` en el chat para ver todos los comandos disponibles.

package/install.sh

@@ -0,0 +1,152 @@
+#!/bin/bash
+# SpecLeap Installer
+# Language selection + initial setup
+
+set -e
+
+# Colors
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+CYAN='\033[0;36m'
+NC='\033[0m'
+
+# Detect terminal width
+COLS=$(tput cols 2>/dev/null || echo 80)
+LINE=$(printf '%*s\n' "$COLS" '' | tr ' ' '=')
+
+# Clear screen and show banner (only if TTY)
+if [ -t 0 ]; then
+    clear
+fi
+echo -e "${CYAN}${LINE}${NC}"
+echo -e "${CYAN}"
+cat << "EOF"
+   _____ ____  ___________    __    _________    ____ 
+  / ___// __ \/ ____/ ____/   / /   / ____/   |  / __ \
+  \__ \/ /_/ / __/ / /       / /   / __/ / /| | / /_/ /
+ ___/ / ____/ /___/ /___    / /___/ /___/ ___ |/ ____/ 
+/____/_/   /_____/\____/   /_____/_____/_/  |_/_/      
+                                                        
+EOF
+echo -e "${NC}${CYAN}${LINE}${NC}"
+echo ""
+echo -e "${GREEN}  Spec-Driven Development Framework${NC}"
+echo -e "${YELLOW}  v1.0.0${NC}"
+echo ""
+echo -e "${CYAN}${LINE}${NC}"
+echo ""
+
+# Language selection
+echo -e "${BLUE}Please select your language / Por favor selecciona tu idioma:${NC}"
+echo ""
+echo "  1) English"
+echo "  2) Español"
+echo ""
+read -p "$(echo -e ${YELLOW}Choose an option [1-2]:${NC} )" lang_choice
+
+# Set language
+case $lang_choice in
+    1)
+        SPECLEAP_LANG="en"
+        WELCOME_MSG="Welcome to SpecLeap!"
+        SETUP_MSG="Starting installation..."
+        CREATING_CONFIG="Creating configuration file..."
+        INSTALLING_DEPS="Installing dependencies..."
+        SETUP_COMPLETE="✅ Installation complete!"
+        NEXT_STEPS="Next steps:"
+        STEP_1="1. Read SETUP.md for detailed configuration"
+        STEP_2="2. Run: npm install (if using landing/web components)"
+        STEP_3="3. Configure your project in proyectos/"
+        STEP_4="4. Run: ./scripts/generate-contrato.sh to start"
+        ENJOY="Enjoy SpecLeap!"
+        ;;
+    2)
+        SPECLEAP_LANG="es"
+        WELCOME_MSG="¡Bienvenido a SpecLeap!"
+        SETUP_MSG="Iniciando instalación..."
+        CREATING_CONFIG="Creando archivo de configuración..."
+        INSTALLING_DEPS="Instalando dependencias..."
+        SETUP_COMPLETE="✅ Instalación completa!"
+        NEXT_STEPS="Próximos pasos:"
+        STEP_1="1. Lee SETUP.md para configuración detallada"
+        STEP_2="2. Ejecuta: npm install (si usas landing/componentes web)"
+        STEP_3="3. Configura tu proyecto en proyectos/"
+        STEP_4="4. Ejecuta: ./scripts/generate-contrato.sh para empezar"
+        ENJOY="¡Disfruta SpecLeap!"
+        ;;
+    *)
+        echo -e "${RED}Invalid option. Defaulting to English.${NC}"
+        SPECLEAP_LANG="en"
+        WELCOME_MSG="Welcome to SpecLeap!"
+        SETUP_MSG="Starting installation..."
+        CREATING_CONFIG="Creating configuration file..."
+        INSTALLING_DEPS="Installing dependencies..."
+        SETUP_COMPLETE="✅ Installation complete!"
+        NEXT_STEPS="Next steps:"
+        STEP_1="1. Read SETUP.md for detailed configuration"
+        STEP_2="2. Run: npm install (if using landing/web components)"
+        STEP_3="3. Configure your project in proyectos/"
+        STEP_4="4. Run: ./scripts/generate-contrato.sh to start"
+        ENJOY="Enjoy SpecLeap!"
+        ;;
+esac
+
+echo ""
+echo -e "${GREEN}${WELCOME_MSG}${NC}"
+echo -e "${YELLOW}${SETUP_MSG}${NC}"
+echo ""
+
+# Create config directory
+mkdir -p .specleap
+
+# Create proyectos directory (for user projects - NOT tracked in git)
+mkdir -p proyectos
+
+# Create config file
+echo -e "${CYAN}${CREATING_CONFIG}${NC}"
+cat > .specleap/config.json <<EOF
+{
+  "version": "1.0.0",
+  "language": "${SPECLEAP_LANG}",
+  "installed_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
+  "features": {
+    "asana_integration": false,
+    "coderabbit_integration": false,
+    "agent_skills_installed": false
+  }
+}
+EOF
+
+# Create .env file if it doesn't exist
+if [ ! -f .env ]; then
+    cat > .env <<EOF
+# SpecLeap Configuration
+SPECLEAP_LANG=${SPECLEAP_LANG}
+
+# Asana Integration (optional - for automatic backlog generation)
+ASANA_ACCESS_TOKEN=""
+ASANA_WORKSPACE_ID=""
+EOF
+fi
+
+# Make scripts executable
+chmod +x scripts/*.sh 2>/dev/null || true
+
+echo ""
+echo -e "${GREEN}${SETUP_COMPLETE}${NC}"
+echo ""
+echo -e "${CYAN}${LINE}${NC}"
+echo ""
+echo -e "${YELLOW}${NEXT_STEPS}${NC}"
+echo ""
+echo -e "  ${STEP_1}"
+echo -e "  ${STEP_2}"
+echo -e "  ${STEP_3}"
+echo -e "  ${STEP_4}"
+echo ""
+echo -e "${CYAN}${LINE}${NC}"
+echo ""
+echo -e "${GREEN}${ENJOY}${NC}"
+echo ""

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "specleap-framework",
+  "version": "2.0.0",
+  "description": "Spec-Driven Development Framework — Transform VSCode, Cursor, JetBrains into spec-first development machines",
+  "keywords": [
+    "spec-driven-development",
+    "sdd",
+    "framework",
+    "ai",
+    "claude",
+    "cursor",
+    "vscode",
+    "contract",
+    "agent-skills",
+    "asana",
+    "coderabbit",
+    "laravel",
+    "react"
+  ],
+  "homepage": "https://specleap.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iapanderson/specleap-framework.git"
+  },
+  "bugs": {
+    "url": "https://github.com/iapanderson/specleap-framework/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "SpecLeap Community",
+    "url": "https://specleap.com"
+  },
+  "bin": {
+    "specleap": "./setup.sh"
+  },
+  "scripts": {
+    "postinstall": "bash setup.sh",
+    "setup": "bash setup.sh",
+    "skills": "bash scripts/install-skills.sh",
+    "generate": "bash scripts/generate-contrato.sh"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    ".agents/**",
+    ".commands/**",
+    "proyectos/_template/**",
+    "rules/**",
+    "scripts/**",
+    "setup.sh",
+    "install.sh",
+    "README.md",
+    "SETUP.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/proyectos/_template/.gitkeep

@@ -0,0 +1 @@
+Template project structure

package/proyectos/_template/ANEXOS.md

@@ -0,0 +1,21 @@
+# ANEXOS — [Nombre del Proyecto]
+
+> **Cambios y mejoras propuestas fuera del CONTRATO original**
+
+Este archivo registra propuestas de cambio que están fuera del alcance del CONTRATO.md inmutable.
+
+## Propuestas Pendientes
+
+(Vacío)
+
+## Propuestas Aprobadas
+
+(Vacío)
+
+## Propuestas Rechazadas
+
+(Vacío)
+
+---
+
+**Nota:** Para proponer cambios usa el comando `refinar` o `openspec new`.

package/proyectos/_template/CONTRATO.md

@@ -0,0 +1,26 @@
+# CONTRATO — [Nombre del Proyecto]
+
+> **Estado:** PLANTILLA (ejecutar comando `inicio` para generar)
+
+Este archivo será generado automáticamente después de responder el cuestionario de 56 preguntas.
+
+## Cómo Empezar
+
+1. Abre tu agente IA (Claude, Cursor, Continue)
+2. Escribe: **"Hola"**
+3. Selecciona: **"Proyecto nuevo"**
+4. Responde las preguntas interactivas
+
+El agente generará el CONTRATO completo con:
+- Objetivo del proyecto
+- Alcance detallado
+- Casos de uso
+- Módulos y features
+- Stack tecnológico
+- Criterios de aceptación
+- Restricciones y dependencias
+- Estimación de esfuerzo
+
+---
+
+**SpecLeap** — Framework Spec-Driven Development

package/proyectos/_template/context/.gitkeep

@@ -0,0 +1 @@
+# Context files will be generated here