specleap-framework 2.1.1 → 2.1.5

package/README.md

@@ -1,624 +1,264 @@
-# 🏛️ SpecLeap — Spec-Driven Development Framework
-
-> **Forja tu arquitectura de software con IA.**
-
-Un framework de desarrollo que combina contratos inmutables, agentes conversacionales y standards de código para entregar software de calidad sin improvisación.
+<p align="center">
+  <img src="assets/specleap-logo.png" alt="SpecLeap Framework" width="420" />
+</p>
+
+<p align="center">
+  <strong>Framework de Spec-Driven Development para desarrollo asistido por IA.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/ConceptualCreative/specleap-framework/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-3b82f6.svg" alt="MIT License" /></a>
+  <a href="https://www.npmjs.com/package/specleap-framework"><img src="https://img.shields.io/npm/v/specleap-framework.svg?color=22c55e&label=npm" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/agents-3-6366f1" alt="3 agents" />
+  <img src="https://img.shields.io/badge/commands-10-f97316" alt="10 commands" />
+  <img src="https://img.shields.io/badge/skills-34-22c55e" alt="34 Agent Skills" />
+  <img src="https://img.shields.io/badge/hooks-1-ec4899" alt="1 hook" />
+  <img src="https://img.shields.io/badge/rules-4-eab308" alt="4 rules" />
+  <img src="https://img.shields.io/badge/built%20for-Claude%20Code-000000" alt="Built for Claude Code" />
+  <a href="https://ko-fi.com/specleap"><img src="https://img.shields.io/badge/Ko--fi-Support%20SpecLeap-FF5E5B?logo=ko-fi&logoColor=white" alt="Ko-fi" /></a>
+</p>
+
+SpecLeap convierte cualquier IDE con asistente de IA en un entorno de desarrollo spec-first. Combina un contrato de proyecto inmutable, agentes conversacionales especializados, 34 Agent Skills profesionales y un pipeline de validación en tres capas para entregar código consistente y probado sin improvisación.
+
+**Versión actual:** 2.1.5 · **Licencia:** MIT · **Autor:** Styng Arias ([ConceptualCreative](https://conceptualcreative.com))
 
 ---
 
-## 🎯 ¿Qué es SpecLeap?
-
-SpecLeap transforma cualquier IDE con asistente de IA en una máquina de desarrollo **spec-first**:
-
-- 📋 **CONTRATO.md inmutable** — Define alcance y nunca cambia
-- 🤖 **Agentes especializados** — Backend, Frontend, Producto
-- 💬 **Comandos en español** — `refinar`, `planificar`, `implementar`
-- 📦 **Multi-proyecto** — Cada proyecto independiente con su contrato
-- 📚 **Standards globales** — Laravel, React, documentación
-- 🔧 **CLI opcional** — `openspec` para automatización
+## Tabla de Contenidos
+
+- [Instalación Rápida](#instalación-rápida)
+- [Qué Aporta](#qué-aporta)
+- [Comandos Conversacionales](#comandos-conversacionales)
+- [Agent Skills](#agent-skills)
+- [Cuestionario Interactivo](#cuestionario-interactivo)
+- [Pipeline de Validación](#pipeline-de-validación)
+- [Estructura del Framework](#estructura-del-framework)
+- [Tokens Requeridos](#tokens-requeridos)
+- [IDEs Compatibles](#ides-compatibles)
+- [Dos Modos de Trabajo](#dos-modos-de-trabajo)
+- [Documentación](#documentación)
+- [Licencia y Contribución](#licencia-y-contribución)
 
 ---
 
-## 💡 El Problema que Resuelve
+## Instalación Rápida
 
-❌ **Sin SpecLeap:**
-- La IA improvisa código sin contexto
-- Specs incompletas → implementación incorrecta
-- Sin memoria → repite errores
-- Cambios de scope sin control
-
-✅ **Con SpecLeap:**
-- CONTRATO define alcance inmutable
-- Context/ guarda decisiones arquitectónicas
-- Agentes especializados siguen standards
-- Comandos conversacionales guían el flujo
-- Memoria persistente por proyecto
-
----
-
-## 🚀 Instalación
-
-### Opción 1: Instalación desde npm (Recomendado)
+### Vía npm (recomendado)
 
 ```bash
 npx specleap-framework@latest
 ```
 
-**Instalador interactivo que pide todos los tokens:**
-- ✅ GitHub token (control versiones + CodeRabbit)
-- ✅ Asana token + workspace (backlog automático)
-- ✅ Instala 34 Agent Skills automáticamente
-- ✅ Configura CodeRabbit (.coderabbit.yaml)
-- ✅ Crea estructura completa
-- ⏱️ **Tiempo total: 10-15 minutos**
-
-### Opción 2: Clonar desde GitHub
+### Desde GitHub
 
 ```bash
-git clone https://github.com/iapanderson/specleap-framework.git
-cd specleap-framework/
+git clone https://github.com/ConceptualCreative/specleap-framework.git
+cd specleap-framework
 bash setup.sh
 ```
 
-**Mismo instalador interactivo. La diferencia es solo el método de descarga.**
-
----
-
-## 📋 Tokens Necesarios (se piden durante instalación)
+El instalador interactivo solicita los tokens de GitHub y Asana, instala los 34 Agent Skills en `~/.skills/` y genera la estructura base. Tiempo total: 10 a 15 minutos.
 
-### GitHub Token (Obligatorio)
-
-**Cómo obtener los tokens:**
-
-1. **GitHub Token:**
-   - Ve a https://github.com/settings/tokens
-   - "Generate new token (classic)"
-   - Scopes: `repo`, `workflow`
-
-2. **Asana Token:**
-   - Ve a https://app.asana.com/0/my-apps
-   - "Create new token"
-   - Nombre: "SpecLeap Integration"
-   - Copia el token (empieza con `0/`)
-
-**El instalador te pedirá estos tokens y configurará todo automáticamente.**
-
----
-
-## ⭐ Agent Skills — Lo Que Hace la Diferencia
-
-SpecLeap incluye **20 skills especializadas** que transforman la calidad del código:
-
-### Sin Skills vs Con Skills
-
-| Aspecto | Sin Skills | Con Skills TIER 1 |
-|---------|-----------|-------------------|
-| **Diseño** | Bootstrap genérico | Estilo Vercel/Linear profesional |
-| **Seguridad** | Vulnerabilidades básicas | OWASP Top 10 + STRIDE threat modeling |
-| **Código** | Duplicación frecuente | DRY automático, verifica antes de crear |
-| **APIs** | Diseño inconsistente | REST/GraphQL best practices |
-| **Tests** | Coverage <60% | TDD methodology, coverage >=90% |
-
-### 34 Agent Skills Profesionales
-
-SpecLeap instala automáticamente **34 skills de calidad profesional** durante el setup.
-
-#### 🔄 Consistencia & Code Quality (6)
-- **Verification-before-completion** ⭐ **CRÍTICO**
-- Systematic debugging
-- Code review (requesting + receiving)
-- Security reviewer
-- GDPR/DSGVO compliance expert
-
-#### 🎨 Diseño & Frontend (7)
-- Frontend design (Anthropic)
-- Web design guidelines (Vercel)
-- Vercel composition patterns
-- Agent browser automation
-- Canvas design
-- Algorithmic art
-- Skill creator
-
-#### 🛠️ Backend & APIs (8)
-- Laravel specialist
-- API designer
-- Database optimizer
-- Code documenter
-- Python pro
-- React expert
-- TypeScript pro
-- Debugging wizard
-
-#### ☁️ DevOps & Infrastructure (5)
-- DevOps engineer
-- Cloud architect
-- Architecture designer
-- Terraform engineer
-- Monitoring expert
-
-#### 🧪 Testing (5)
-- Test-driven development
-- Playwright expert (E2E)
-- Test master
-- Code reviewer
-- Receiving code review
-
-#### 📱 Mobile Development (2)
-- React Native expert
-- Flutter expert
-
-#### 💡 Otros (1)
-- Brainstorming
-- PDF analysis
-
-**Instalación:** Automática durante `setup.sh` — Total: **34 skills** — [Ver SETUP.md](SETUP.md)
+**Requisitos previos:** Node.js ≥ 18, Git, Bash.
 
 ---
 
-## 🎯 Cuestionario Interactivo — De Idea a CONTRATO en 20 Minutos
+## Qué Aporta
 
-**Nuevo en SpecLeap:** Sistema de 58 preguntas que genera tu CONTRATO.md automáticamente.
+El desarrollo asistido por IA suele improvisar sin contexto, repetir errores pasados y dejar que el alcance se escape silenciosamente. SpecLeap impone una disciplina spec-first:
 
-### ¿Cómo Funciona?
+- Un **CONTRATO.md inmutable** define el proyecto y no cambia una vez aprobado. Las mejoras posteriores se registran en `ANEXOS.md`.
+- Un banco de memoria `context/` guarda arquitectura, stack, convenciones y un log de decisiones técnicas.
+- Tres agentes especializados (`backend`, `frontend`, `producto`) adoptan el rol adecuado según la tarea.
+- Comandos conversacionales en español guían los ciclos de refinamiento, planificación, implementación y documentación.
+- Un pipeline de validación de tres capas (pre-commit hooks, tests en `implementar` y CodeRabbit en el PR) bloquea merges de baja calidad.
 
-```bash
-# Ejecuta el cuestionario
-./scripts/generate-contrato.sh
-
-# Te hace 58 preguntas sobre tu proyecto
-# Guarda progreso cada 10 preguntas (puedes interrumpir)
-# Genera CONTRATO.md completo con YAML frontmatter
-```
-
-### Lo Que Obtienes
-
-✅ **CONTRATO.md completo** con:
-- Información del proyecto (nombre, responsable, fecha)
-- Identidad (objetivo, problema que resuelve, público objetivo)
-- Stack tecnológico (backend, frontend, base de datos, DevOps)
-- Funcionalidades core y secundarias
-- Sistema de usuarios (roles, autenticación, permisos)
-- Diseño (colores, estilo visual, responsive)
-- Arquitectura (patrón, separación)
-- Seguridad (nivel, GDPR, datos sensibles)
-- Rendimiento (targets de carga, usuarios concurrentes)
-- Testing (unit, integration, e2e, coverage)
-- Restricciones (plazo, presupuesto, fuera de alcance)
-
-✅ **Validaciones inteligentes:**
-- Tipos de datos (string, select, boolean, number, array)
-- Rangos y longitudes
-- Patterns regex (slug, hexcolor, etc.)
-- Skip condicional (si no tiene auth, no pregunta métodos)
-- Auto-sugerencias (si eliges Laravel, sugiere PHP 8.3)
-
-✅ **Guardado parcial:**
-- Checkpoint cada 10 preguntas
-- Puedes interrumpir y continuar después
-- Detecta sesiones incompletas automáticamente
-
-✅ **Integración Asana:**
-- Genera backlog (secciones + user tareas)
-- Preview visual antes de crear
-- Confirmación manual
-- Actualiza CONTRATO.md con metadata Asana
-
-### Workflow Completo
-
-```
-1. Ejecuta cuestionario (20 min)
-   ↓
-2. Responde 58 preguntas
-   ↓
-3. CONTRATO.md generado automáticamente
-   ↓
-4. Push a GitHub (OBLIGATORIO — control de versiones)
-   ↓
-5. planificar → crea backlog Asana
-   ↓
-6. implementar → desarrolla según spec
-```
-
-**⚠️ IMPORTANTE:** El CONTRATO.md DEBE guardarse en GitHub. Es la fuente de verdad del proyecto y debe estar versionado junto con el código.
+---
 
-### Ejemplo de Uso
+## Comandos Conversacionales
 
-```bash
-$ cd specleap
-$ ./scripts/generate-contrato.sh
+Los comandos se escriben como palabras planas, sin prefijo (ni `/` ni `.`). El asistente detecta la palabra clave y ejecuta las instrucciones definidas en `.commands/*.md`.
 
-🎯 SpecLeap — Generador de CONTRATO.md
-════════════════════════════════════════
+| Comando | Descripción |
+|---------|-------------|
+| `Hola` | Inicia sesión: lista proyectos o arranca uno nuevo con el cuestionario |
+| `refinar [proyecto]-XXX` | Refina la user story de una tarea Asana |
+| `planificar [proyecto]-XXX` | Genera un plan de implementación desde el contrato |
+| `implementar @plan.md` | Ejecuta el plan: rama, código, tests, PR |
+| `explicar [concepto]` | Explica código, arquitectura o decisiones |
+| `documentar` | Actualiza la documentación técnica |
+| `adoptar` | Analiza un proyecto legacy y genera un CONTRATO retroactivo |
+| `crear-tickets` | Alias de `planificar` |
+| `ayuda` | Lista todos los comandos disponibles |
 
-⏱️  Tiempo estimado: 15-20 minutos
-💾 Guardado automático cada 10 preguntas
-🔄 Puedes interrumpir con Ctrl+C
+El prefijo `/` está reservado por Claude Code para sus propios slash commands (`/help`, `/clear`, etc.), por lo que los comandos de SpecLeap deben escribirse sin él para evitar colisión.
 
-¿Listo para comenzar? [s/N]: s
-
-━━━ Información del Proyecto ━━━
+---
 
-Pregunta 1/56: ¿Nombre del proyecto? (slug-style)
-💡 Usa solo minúsculas, números y guiones
-📝 Ejemplo: mi-proyecto
-> mi-tienda-online
+## Agent Skills
 
-Pregunta 2/56: ¿Nombre completo para mostrar?
-💡 Puede tener mayúsculas, espacios
-📝 Ejemplo: Mi Proyecto Awesome
-> Mi Tienda Online
+SpecLeap instala **34 Agent Skills profesionales** en `~/.skills/` durante el setup. Se activan automáticamente cuando el contexto lo requiere.
 
-... (54 preguntas más)
+### TIER 1 — 20 skills base
 
-✅ ¡Cuestionario completado! 🎉
+| Categoría | Skills |
+|-----------|--------|
+| Consistencia | `verification-before-completion`, `systematic-debugging`, `requesting-code-review`, `receiving-code-review`, `code-reviewer`, `debugging-wizard` |
+| Backend | `laravel-specialist`, `api-designer`, `database-optimizer`, `python-pro`, `react-expert`, `typescript-pro` |
+| Diseño | `frontend-design`, `canvas-design`, `algorithmic-art`, `skill-creator` |
+| DevOps | `devops-engineer`, `cloud-architect`, `architecture-designer` |
+| Testing | `test-driven-development` |
 
-━━━ Generando CONTRATO.md ━━━
+### TIER 2 — 14 skills añadidas en v2.1
 
-✅ CONTRATO.md generado exitosamente
-📄 Ubicación: proyectos/mi-tienda-online/CONTRATO.md
-```
+| Categoría | Skills |
+|-----------|--------|
+| Frontend web | `web-design-guidelines`, `vercel-composition-patterns`, `agent-browser` |
+| Mobile | `react-native-expert`, `flutter-expert` |
+| Testing avanzado | `playwright-expert`, `test-master` |
+| Seguridad | `security-reviewer`, `gdpr-dsgvo-expert` |
+| Infraestructura | `terraform-engineer`, `monitoring-expert` |
+| Otras | `brainstorming`, `code-documenter`, `pdf` |
 
-**Más información:** Ver [docs/SPEC-CUESTIONARIO-INTERACTIVO.md](docs/SPEC-CUESTIONARIO-INTERACTIVO.md)
+La skill `verification-before-completion` obliga al asistente a verificar si el código solicitado ya existe antes de crearlo, evitando duplicación de lógica.
 
 ---
 
-## 📦 Estructura del Framework
+## Cuestionario Interactivo
 
-```
-specleap/
-├── proyectos/                    # Proyectos independientes
-│   ├── _template/                # Template para nuevos proyectos
-│   │   ├── CONTRATO.md           # 🔒 Contrato inmutable
-│   │   ├── ANEXOS.md             # ✏️ Mejoras/módulos adicionales
-│   │   ├── context/              # Memory-bank del proyecto
-│   │   │   ├── brief.md
-│   │   │   ├── architecture.md
-│   │   │   ├── tech-stack.md
-│   │   │   ├── conventions.md
-│   │   │   ├── decisions.md
-│   │   │   ├── personas.md
-│   │   │   └── user-stories.md
-│   │   └── openspec/             # CLI state (propuestas)
-│   │       └── proposals/
-│   └── mi-proyecto/              # Tu proyecto activo
-│       └── [misma estructura]
-├── .agents/                      # Agentes especializados
-│   ├── backend.md
-│   ├── frontend.md
-│   └── producto.md
-├── .commands/                    # Comandos conversacionales
-│   ├── inicio.md                 # Cuestionario 58 preguntas
-│   ├── refinar.md
-│   ├── planificar.md
-│   ├── implementar.md
-│   ├── documentar.md
-│   ├── explicar.md
-│   └── adoptar.md
-├── rules/                        # Standards globales
-│   ├── PHP-LARAVEL.md
-│   ├── JAVASCRIPT-REACT.md
-│   ├── CSS-TAILWIND.md
-│   └── DOCS.md
-├── scripts/                      # Automatización
-│   ├── generate-contrato.sh      # Cuestionario interactivo ⭐
-│   ├── generate-jira-structure.sh
-│   ├── analyze-project.sh
-│   ├── setup-mcp.sh              # Install Asana + Skills
-│   └── install-skills.sh         # Agent Skills installer
-├── openspec/                     # CLI (opcional)
-│   ├── bin/openspec
-│   └── src/
-├── CLAUDE.md                     # Reglas generales para IA
-├── AGENTS.md                     # Orquestación de agentes
-└── SETUP.md                      # Guía completa de setup
-```
+Tras decir `Hola` y elegir "Proyecto nuevo", SpecLeap arranca un cuestionario de **58 preguntas** con checkpoint automático cada 10 preguntas. Duración estimada: 15 a 20 minutos.
 
----
+El cuestionario cubre 20 secciones que van desde la identidad del proyecto (objetivo, problema, audiencia) hasta restricciones (plazo, presupuesto, fuera de alcance), pasando por stack, funcionalidades, sistema de usuarios, panel de administración, almacenamiento, pagos, notificaciones, diseño, arquitectura, despliegue, seguridad, rendimiento y testing.
 
-## 🎮 Comandos Conversacionales
+Al finalizar se genera:
 
-Habla con Claude/Cursor/Continue usando comandos en español:
+- `proyectos/[nombre]/CONTRATO.md` con YAML frontmatter
+- `context/` completo (`brief.md`, `architecture.md`, `tech-stack.md`, `conventions.md`, `decisions.md`)
+- Propuesta de estructura Asana (con confirmación manual antes de crear las tareas)
 
-### Para Nuevos Proyectos
-
-```
-Hola
-→ Inicia cuestionario de 58 preguntas
-→ Genera CONTRATO.md completo automáticamente
-```
-
-### Para Proyectos Existentes
-
-```
-refinar "añadir sistema de notificaciones push"
-→ Analiza viabilidad
-→ Genera propuesta de cambio
-→ Actualiza context/
-
-planificar
-→ Lee CONTRATO.md
-→ Genera backlog Asana
-→ Crea secciones + user stories
-
-implementar "login con google"
-→ Verifica si está en CONTRATO
-→ Lee context/ para contexto
-→ Genera código siguiendo standards
-
-documentar "api de usuarios"
-→ Genera docs API (OpenAPI/Swagger)
-→ Actualiza README técnico
-
-explicar "arquitectura del sistema"
-→ Genera diagrama + explicación
-→ Basado en context/architecture.md
-
-adoptar
-→ Analiza proyecto existente
-→ Genera CONTRATO retroactivo
-→ Extrae arquitectura y decisiones
-```
-
-**Detalle completo:** Ver [docs/COMANDOS.md](docs/COMANDOS.md)
+El sistema detecta sesiones incompletas al reiniciarlo y permite reanudar desde la última pregunta respondida.
 
 ---
 
-## 🤔 Dos Formas de Trabajar: Conversacional vs CLI Formal
+## Pipeline de Validación
 
-SpecLeap ofrece **dos workflows** que conviven perfectamente según tus necesidades:
+Un cambio solo llega a merge si pasa las tres capas automáticas:
 
-### 🗣️ **Modo Conversacional** (Recomendado para empezar)
+| Capa | Momento | Duración | Valida |
+|------|---------|----------|--------|
+| Git hooks pre-commit | Antes de cada commit | <5 s | Sintaxis, linters, formato, inmutabilidad del CONTRATO |
+| Validación en `implementar` | Al terminar una feature | 1 a 5 min | Tests unitarios e integración, specs, cobertura ≥ 80% |
+| CodeRabbit en PR | Al abrir el Pull Request | 5 a 10 min | Arquitectura, seguridad, lógica de negocio, complejidad |
 
-**Usa comandos en chat** con tu asistente IA (Claude, Copilot, etc.):
-
-```
-# Ver todos los comandos disponibles
-ayuda
-
-# Comandos principales
-refinar "Como usuario quiero login"
-planificar
-implementar
-documentar
-```
-
-**Cuándo usarlo:**
-- ✅ Equipos pequeños (1-3 devs) o desarrollo individual
-- ✅ Prefieres chat natural vs terminal
-- ✅ Desarrollo ágil y rápido
-- ✅ Proyectos personales o startups
-
----
-
-### ⚙️ **Modo CLI Formal** (OpenSpec)
-
-**Usa comandos de terminal** para workflow estructurado:
+Instalación de los hooks desde la raíz del proyecto:
 
 ```bash
-# Ver todos los comandos CLI
-openspec --help
-
-# Workflow completo con propuestas formales
-openspec new CHANGE-001 "Añadir autenticación JWT"
-openspec ff CHANGE-001        # Fast-forward: genera propuesta completa
-openspec apply CHANGE-001     # Implementa
-openspec verify CHANGE-001    # Verifica tests + specs
-openspec code-review CHANGE-001  # Review con CodeRabbit
-openspec archive CHANGE-001   # Archiva completado
+bash scripts/install-git-hooks.sh
 ```
 
-**Cuándo usarlo:**
-- ✅ Equipos grandes (4+ devs) o distribuidos
-- ✅ Necesitas propuestas de cambio formales y trazables
-- ✅ Workflow enterprise con auditoría y trazabilidad completa
+La configuración de CodeRabbit vive en `.coderabbit.yaml` con perfil `assertive` y comentarios en español.
 
 ---
 
-### 🔄 **¿Se Pueden Combinar?**
-
-**¡Sí!** Usa conversacional para el día a día y CLI para cambios grandes:
+## Estructura del Framework
 
 ```
-# Desarrollo normal (conversacional)
-implementar "fix bug en login"
-
-# Feature grande (CLI formal con trazabilidad)
-openspec new CHANGE-015 "Rediseño completo sistema de permisos"
-openspec ff CHANGE-015
-openspec apply CHANGE-015
+specleap/
+├── proyectos/                Proyectos independientes
+│   └── mi-proyecto/
+│       ├── CONTRATO.md       Contrato inmutable
+│       ├── ANEXOS.md         Mejoras y módulos adicionales
+│       ├── context/          Memory bank del proyecto
+│       └── specs/            Planes de implementación por ticket
+├── .agents/                  Agentes (backend, frontend, producto)
+├── .commands/                Comandos conversacionales
+├── rules/                    Standards globales (PHP/Laravel, React, Tailwind, docs)
+├── scripts/                  Automatización (cuestionario, Asana, skills, hooks)
+├── openspec/                 CLI opcional para workflow formal
+├── CLAUDE.md                 Contexto para Claude Code
+├── AGENTS.md                 Contexto genérico multi-IDE
+├── GEMINI.md                 Contexto para Google Gemini
+├── codex.md                  Contexto para GitHub Copilot
+└── SETUP.md                  Guía de instalación completa
 ```
 
-**Detalle completo CLI:** Ver `openspec/README.md` y `openspec/cli/COMMAND_REFERENCE.md`
+Cada proyecto dentro de `proyectos/` es independiente, con su propio contrato y memoria, y se crea dinámicamente durante el flujo de `Hola`.
 
 ---
 
-## 🎨 Funciona con tu IDE Favorito
-
-**SpecLeap es agnóstico al IDE.** Funciona con **cualquier editor que tenga asistente de IA**:
+## Tokens Requeridos
 
-- ✅ **VSCode** — Con GitHub Copilot, Claude Code, Continue extension
-- ✅ **Cursor** — IDE nativo con Claude integrado
-- ✅ **JetBrains** (IntelliJ, PhpStorm, WebStorm) — Con AI Assistant
-- ✅ **Vim/Neovim** — Con plugins de IA (copilot.vim, etc.)
-- ✅ **Zed** — Editor moderno con IA integrada
-- ✅ **Cualquier IDE con asistente IA** — Si tu editor tiene IA, SpecLeap funciona
+Durante el setup se solicitan dos tokens que el instalador guarda en la configuración del IDE:
 
-**Cómo funciona:**
-- Lee archivos del proyecto (CLAUDE.md, GEMINI.md, .cursorrules, .copilot-instructions.md)
-- Aplica Agent Skills automáticamente
-- Usa comandos conversacionales o CLI según tu preferencia
+**GitHub Personal Access Token**
+URL: https://github.com/settings/tokens
+Tipo: classic · Scopes: `repo`, `workflow`
 
-**No hay IDE "recomendado"** — Usa el que más te guste. SpecLeap se adapta.
+**Asana Personal Access Token**
+URL: https://app.asana.com/0/my-apps
+El token empieza por `0/`.
 
 ---
 
-## 🛡️ Sistema de Validación en 3 Capas
-
-SpecLeap garantiza calidad de código con **3 capas de validación automática**:
-
-### **🔹 Capa 1: Git Hooks Pre-Commit** (Validación rápida - <5 seg)
-
-**Se ejecuta ANTES de cada commit automáticamente.**
-
-✅ **Valida:**
-- Sintaxis (PHP, JS/TS)
-- Linters (ESLint, PHPStan)
-- Formatters (Prettier, PHP-CS-Fixer)
-- CONTRATO.md no se modifica (es inmutable)
-- No hay console.log / var_dump olvidados
-
-❌ **Si falla:** Rechaza el commit y muestra errores
-
-**Instalación:**
-```bash
-cd tu-proyecto
-bash scripts/install-git-hooks.sh
-```
-
-**Para saltarte (NO recomendado):**
-```bash
-git commit --no-verify -m "mensaje"
-```
-
----
-
-### **🔹 Capa 2: Validación Completa en `implementar`** (1-5 min)
-
-**Se ejecuta al terminar una feature antes de push.**
+## IDEs Compatibles
 
-✅ **Valida:**
-- Tests unitarios
-- Tests de integración
-- Validación vs CONTRATO.md
-- Validación vs specs
-- Coverage > 80%
+SpecLeap es agnóstico al editor. Funciona con cualquier IDE que incorpore un asistente de IA:
 
-❌ **Si falla:** NO hace push ni crea PR
+- VSCode con Claude Code, GitHub Copilot o Continue
+- Cursor
+- JetBrains (IntelliJ, PhpStorm, WebStorm) con AI Assistant
+- Vim y Neovim con plugins de IA
+- Zed
 
-✅ **Si pasa:** Commit + Push + Crea PR automáticamente
-
-**Uso:**
-```
-implementar "login con Google"
-→ Escribe código
-→ Valida TODO automáticamente
-→ Si pasa: push + PR creado
-```
+El framework detecta el IDE y aplica los archivos de contexto apropiados (`CLAUDE.md`, `.cursorrules`, `GEMINI.md`, `codex.md`).
 
 ---
 
-### **🔹 Capa 3: CodeRabbit en PR** (Revisión profunda - 5-10 min)
-
-**Se ejecuta automáticamente al crear PR en GitHub.**
+## Dos Modos de Trabajo
 
-✅ **Valida:**
-- Arquitectura y patrones
-- Seguridad (vulnerabilidades)
-- Lógica de negocio
-- Cumplimiento de specs
-- Complejidad ciclomática
-- Documentación
+**Modo conversacional** — Recomendado para equipos pequeños o desarrollo individual. El flujo se ejecuta escribiendo los comandos en el chat con el asistente.
 
-✅ **Comenta en el PR con:**
-- Problemas encontrados
-- Sugerencias de mejora
-- Labels automáticos
-- Estimación de esfuerzo de review
+**Modo CLI formal (OpenSpec)** — Recomendado para equipos grandes o distribuidos con requisitos de trazabilidad. Expone comandos de terminal para gestionar propuestas de cambio con design, tasks y testing report estructurado:
 
-**Setup:**
 ```bash
-# 1. .coderabbit.yaml ya está incluido en SpecLeap
-# 2. Instala CodeRabbit en tu repo: https://github.com/apps/coderabbit-ai
-# 3. Crea un PR → CodeRabbit revisa automáticamente
-```
-
-**Perfil configurado:** "assertive" (riguroso pero constructivo)  
-**Idioma:** Español  
-**Más info:** Ver `.coderabbit.yaml`
-
----
-
-### **🎯 Resultado: Código de Calidad Garantizado**
-
-```
-Escribes código
-     ↓
-🔹 Capa 1: Pre-commit hook valida básicos
-     ↓ (si pasa)
-git commit exitoso
-     ↓
-Comando `implementar` termina
-     ↓
-🔹 Capa 2: Validación completa (tests + specs)
-     ↓ (si pasa)
-Push + PR creado
-     ↓
-🔹 Capa 3: CodeRabbit revisa arquitectura + seguridad
-     ↓
-Merge (solo si las 3 capas pasan)
+openspec new CHANGE-001 "Añadir autenticación JWT"
+openspec ff CHANGE-001
+openspec apply CHANGE-001
+openspec verify CHANGE-001
+openspec code-review CHANGE-001
+openspec archive CHANGE-001
 ```
 
-**Beneficios:**
-- ✅ Menos bugs en producción
-- ✅ Code reviews más rápidos (lo obvio ya está validado)
-- ✅ Aprendes de CodeRabbit (explica el "por qué")
-- ✅ Cumplimiento de specs garantizado
+Ambos modos coexisten. Lo habitual es trabajar conversacionalmente en el día a día y reservar el CLI para cambios grandes con auditoría completa.
 
 ---
 
-## 📚 Documentación Completa
+## Documentación
 
-- 📖 [SETUP.md](SETUP.md) — Instalación paso a paso
-- 🎯 `.commands/inicio.md` — Sistema 58 preguntas interactivo
-- 💬 `.commands/ayuda.md` — Lista completa de comandos
-- 🛠️ `openspec/README.md` — CLI formal OpenSpec
-- 🤖 `.agents/` — Agentes especializados (backend, frontend, producto)
-- ⭐ `scripts/install-skills.sh` — 34 Agent Skills profesionales
-- 📋 `proyectos/_template/CONTRATO.md` — Template contrato
-- 🏗️ `CLAUDE.md` — Configuración para Claude Code
+- [SETUP.md](SETUP.md) — Guía de instalación paso a paso
+- [openspec/README.md](openspec/README.md) — Referencia del CLI formal
+- `.commands/ayuda.md` — Lista completa de comandos conversacionales
+- `.agents/` — Definiciones de los tres roles especializados
+- `rules/` — Standards globales por tecnología
+- `proyectos/_template/CONTRATO.md` — Plantilla de contrato
 
 ---
 
-## 💖 Apoya el Proyecto
+## Licencia y Contribución
 
-SpecLeap es **100% gratuito y open-source**. Si te resulta útil, puedes apoyar su desarrollo:
+Distribuido bajo licencia MIT. Ver [LICENSE](LICENSE).
 
-[![Ko-fi](https://img.shields.io/badge/Ko--fi-Support%20SpecLeap-FF5E5B?style=for-the-badge&logo=ko-fi&logoColor=white)](https://ko-fi.com/specleap)
+Para contribuir:
 
-Las donaciones nos ayudan a:
-- ✅ Mantener el framework actualizado
-- ✅ Desarrollar nuevas features
-- ✅ Mejorar documentación
-- ✅ Crear más Agent Skills
-- ✅ Soporte a la comunidad
+1. Haz fork del repositorio.
+2. Crea una rama: `git checkout -b feature/mi-cambio`.
+3. Aplica los cambios y verifica que las tres capas de validación pasan.
+4. Abre un Pull Request siguiendo Conventional Commits.
 
----
+Mantenido por Styng Arias — [ConceptualCreative](https://conceptualcreative.com).
 
-## 📜 Licencia
-
-MIT License - Ver [LICENSE](LICENSE)
-
----
-
-## 🤝 Contribuciones
-
-¡Contribuciones bienvenidas! Por favor:
-
-1. Fork el proyecto
-2. Crea una branch (`git checkout -b feature/nueva-feature`)
-3. Commit tus cambios (`git commit -am 'Add nueva feature'`)
-4. Push a la branch (`git push origin feature/nueva-feature`)
-5. Abre un Pull Request
-
----
-
-## 🔗 Enlaces
-
-- 🌐 **Website:** [specleap.com](https://specleap.com)
-- 📦 **GitHub:** [github.com/iapanderson/specleap](https://github.com/iapanderson/specleap-framework)
-- 💬 **Comunidad:** (próximamente Discord/Slack)
-- 📧 **Contacto:** [Abrir Issue en GitHub](https://github.com/iapanderson/specleap-framework/issues)
-
----
+**Repositorio:** https://github.com/ConceptualCreative/specleap-framework
+**Issues y feedback:** https://github.com/ConceptualCreative/specleap-framework/issues
+**Sitio web:** https://specleap.com
 
-**Hecho con ❤️ por la comunidad SpecLeap**
+Si SpecLeap te resulta útil y quieres apoyar el mantenimiento, puedes hacerlo en [Ko-fi](https://ko-fi.com/specleap).