claude-agent-framework 1.0.0

package/framework/commands/deshacer.md

@@ -0,0 +1,120 @@
+# Comando: /deshacer
+
+Revierte el último cambio realizado en el proyecto.
+
+## Flujo de trabajo
+
+### Paso 1: Identificar el último cambio
+
+1. Lee `.claude/history/changelog.md`
+2. Identifica la entrada más reciente
+3. Muestra al usuario qué se va a deshacer:
+   ```
+   El último cambio fue:
+   - Fecha: [fecha]
+   - Descripción: [qué se hizo]
+   - Archivos afectados: [lista]
+
+   ¿Quieres deshacer este cambio?
+   ```
+
+### Paso 2: Confirmar con el usuario
+
+**Importante**: Siempre pedir confirmación antes de deshacer.
+
+Si el usuario confirma, continuar. Si no, preguntar qué cambio específico quiere deshacer.
+
+### Paso 3: Verificar disponibilidad de backup
+
+1. Buscar en `.claude/history/legacy/` si existe backup del estado anterior
+2. Si existe, usarlo para restaurar
+3. Si no existe, intentar revertir manualmente
+
+### Paso 4: Revertir el cambio
+
+#### Si hay backup:
+```bash
+# Restaurar archivos desde backup
+cp -r .claude/history/legacy/[timestamp]/* [destino]
+```
+
+#### Si es un cambio de código simple:
+1. Identificar los archivos modificados
+2. Revertir cada archivo a su estado anterior
+
+#### Si es una migración de base de datos:
+```bash
+# Revertir última migración
+rails db:rollback
+
+# Si son varias migraciones
+rails db:rollback STEP=n
+```
+
+### Paso 5: Verificar
+
+1. Ejecutar tests: `bundle exec rspec`
+2. Verificar que la app funciona
+3. Confirmar visualmente si aplica
+
+### Paso 6: Actualizar historial
+
+Añadir entrada en `.claude/history/changelog.md`:
+```markdown
+## [Fecha] - Revertido: [Descripción del cambio deshecho]
+
+### Motivo
+[Por qué se deshizo - si el usuario lo especificó]
+
+### Estado restaurado
+La aplicación ha vuelto al estado anterior a [descripción del cambio].
+```
+
+### Paso 7: Confirmar al usuario
+
+```
+✅ Cambio deshecho exitosamente.
+
+Se ha revertido: [descripción]
+La aplicación está ahora en el estado de [fecha/descripción del estado anterior].
+```
+
+## Casos especiales
+
+### Cambios que no se pueden deshacer fácilmente
+
+Algunos cambios son difíciles de revertir:
+- Eliminación de datos de la base de datos
+- Cambios en archivos que luego fueron modificados de nuevo
+- Múltiples cambios interdependientes
+
+En estos casos:
+1. Explicar la situación al usuario
+2. Ofrecer alternativas:
+   - Crear una nueva versión que "arregle" el problema
+   - Restaurar desde un backup de base de datos si existe
+   - Recrear manualmente el estado anterior
+
+### Deshacer varios cambios
+
+Si el usuario quiere deshacer más de un cambio:
+
+1. Mostrar lista de cambios recientes
+2. Preguntar cuántos quiere deshacer
+3. Advertir sobre posibles conflictos
+4. Proceder paso a paso, confirmando cada uno
+
+## Ejemplos de uso
+
+- "Deshaz el último cambio"
+- "Vuelve atrás"
+- "Eso no me gusta, déjalo como estaba"
+- "Revierte los cambios de hoy"
+
+## Notas importantes
+
+- **Siempre confirmar** antes de deshacer
+- Mantener el historial actualizado
+- Si no hay backup, ser honesto sobre las limitaciones
+- Para cambios de base de datos, verificar que no haya pérdida de datos
+- Si el cambio afectó múltiples archivos, revertir todos juntos

package/framework/commands/estado.md

@@ -0,0 +1,218 @@
+# Comando: /estado
+
+Muestra un resumen del estado actual del proyecto.
+
+## Flujo de trabajo
+
+### Paso 1: Recopilar información
+
+Leer archivos de contexto:
+- `.claude/contexts/requirements.md`
+- `.claude/contexts/architecture.md`
+- `.claude/history/changelog.md`
+- `.claude/history/active/`
+
+### Paso 1b: Verificar Features (si existen)
+
+Buscar en `features/*/feature.json`:
+
+```bash
+ls features/*/feature.json 2>/dev/null
+```
+
+Si hay features, incluir en el resumen:
+
+```markdown
+## Features Activos
+
+| Feature | Estado | Progreso | Siguiente Acción |
+|---------|--------|----------|------------------|
+| {título} | {status} | {X}% | /plan {path} |
+
+### Detalle de Feature en Progreso
+{Para cada feature con status in_progress}
+- Tareas completadas: X/Y
+- Tarea actual: {nombre}
+- Próxima acción: {comando sugerido}
+```
+
+### Paso 2: Analizar el proyecto
+
+```bash
+# Contar modelos
+ls -la app/models/*.rb 2>/dev/null | wc -l
+
+# Contar controladores
+ls -la app/controllers/*.rb 2>/dev/null | wc -l
+
+# Contar vistas
+find app/views -name "*.erb" 2>/dev/null | wc -l
+
+# Contar tests
+find spec -name "*_spec.rb" 2>/dev/null | wc -l
+
+# Verificar estado de tests
+bundle exec rspec --format progress 2>/dev/null || echo "Tests no configurados"
+```
+
+### Paso 3: Generar resumen
+
+```markdown
+# Estado del Proyecto: [Nombre]
+
+## Información General
+- **Nombre**: [nombre del proyecto]
+- **Creado**: [fecha de creación]
+- **Última modificación**: [fecha]
+- **Stack**: Rails 8.1 + SQLite3 + Tailwind + Hotwire
+
+## Estructura Actual
+
+### Modelos (X)
+| Modelo | Campos principales | Relaciones |
+|--------|-------------------|------------|
+| User | email, name | has_many :articles |
+| Article | title, body, published | belongs_to :user |
+
+### Controladores (X)
+- `ApplicationController`
+- `SessionsController`
+- `ArticlesController`
+- ...
+
+### Vistas (X páginas)
+- Home
+- Artículos (index, show, new, edit)
+- Autenticación (login, registro)
+
+## Funcionalidades
+
+### ✅ Implementadas
+- [x] Autenticación de usuarios
+- [x] CRUD de artículos
+- [x] Sistema de comentarios
+
+### 🔄 En progreso
+- [ ] [Funcionalidad en desarrollo]
+
+### 📋 Pendientes
+- [ ] [Funcionalidad planificada]
+- [ ] [Otra funcionalidad]
+
+## Tests
+
+| Tipo | Total | Pasando | Fallando |
+|------|-------|---------|----------|
+| Modelos | X | X | 0 |
+| Controladores | X | X | 0 |
+| Features | X | X | 0 |
+
+**Cobertura estimada**: X%
+
+## Últimos Cambios
+
+### [Fecha más reciente]
+- [Cambio 1]
+- [Cambio 2]
+
+### [Fecha anterior]
+- [Cambio 3]
+
+## Métricas del Proyecto
+
+| Métrica | Valor |
+|---------|-------|
+| Archivos Ruby | X |
+| Líneas de código | ~X |
+| Migraciones | X |
+| Rutas | X |
+
+## Dependencias Principales
+
+```ruby
+# Gemfile highlights
+rails (~> 8.1)
+sqlite3
+tailwindcss-rails
+turbo-rails
+stimulus-rails
+pundit
+```
+
+## Próximos Pasos Sugeridos
+
+1. [Sugerencia basada en el estado actual]
+2. [Otra sugerencia]
+3. [Tercera sugerencia]
+
+## Comandos Útiles
+
+```bash
+# Iniciar servidor
+bin/dev
+
+# Correr tests
+bundle exec rspec
+
+# Consola de Rails
+rails console
+
+# Ver rutas
+rails routes
+```
+```
+
+### Paso 4: Mostrar al usuario
+
+Presentar el resumen de forma amigable:
+
+1. Estado general (todo bien / hay problemas)
+2. Lo que está funcionando
+3. Lo que falta por hacer
+4. Recomendaciones
+
+## Variantes del comando
+
+### `/estado breve`
+Muestra solo un resumen corto:
+```
+📊 Proyecto: [Nombre]
+✅ 5 modelos, 8 controladores, 15 vistas
+🧪 45 tests pasando
+📝 Última modificación: hace 2 horas
+```
+
+### `/estado modelos`
+Muestra detalle de los modelos y sus relaciones.
+
+### `/estado tests`
+Muestra estado detallado de los tests.
+
+### `/estado cambios`
+Muestra los últimos cambios realizados.
+
+## Información adicional
+
+### Si hay problemas
+```
+⚠️ Se detectaron algunos problemas:
+- 3 tests fallando
+- 1 migración pendiente
+
+¿Quieres que los arregle?
+```
+
+### Si todo está bien
+```
+✅ Todo en orden
+- Tests pasando
+- Sin migraciones pendientes
+- Sin errores detectados
+```
+
+## Notas importantes
+
+- Mantener actualizado el archivo de requirements
+- Actualizar changelog con cada cambio
+- Si falta información, sugerir crearla
+- Usar lenguaje sencillo y visual (emojis para estado)

package/framework/commands/explica.md

@@ -0,0 +1,227 @@
+# Comando: /explica
+
+Explica cualquier concepto técnico en lenguaje sencillo.
+
+## Flujo de trabajo
+
+### Paso 1: Identificar qué explicar
+
+El usuario puede preguntar sobre:
+- Conceptos técnicos ("¿qué es una migración?")
+- Código específico ("explícame este archivo")
+- Arquitectura ("¿cómo funciona el sistema de usuarios?")
+- Errores ("¿qué significa este error?")
+- Decisiones ("¿por qué usamos SQLite?")
+
+### Paso 2: Adaptar la explicación
+
+Usar analogías del mundo real y evitar jerga técnica:
+
+#### Ejemplo: Explicar una base de datos
+```
+❌ Técnico:
+"SQLite es un sistema de gestión de bases de datos relacional
+que implementa un motor SQL autónomo, sin servidor, de
+configuración cero y transaccional."
+
+✅ Sencillo:
+"La base de datos es como un archivador muy organizado donde
+guardamos toda la información de tu app.
+
+Imagina que tienes:
+- Una carpeta para usuarios
+- Una carpeta para artículos
+- Una carpeta para comentarios
+
+Cada carpeta tiene fichas ordenadas, y podemos encontrar
+cualquier información rápidamente. SQLite es el encargado
+de mantener todo esto ordenado."
+```
+
+### Paso 3: Estructurar la respuesta
+
+```markdown
+## [Concepto]
+
+### ¿Qué es?
+[Explicación en una o dos frases simples]
+
+### ¿Para qué sirve?
+[Propósito práctico]
+
+### Analogía
+[Comparación con algo cotidiano]
+
+### En tu proyecto
+[Cómo se usa específicamente en este proyecto]
+
+### Ejemplo práctico
+[Código o demostración simple si aplica]
+```
+
+## Explicaciones comunes
+
+### MVC (Model-View-Controller)
+```markdown
+## MVC - Cómo se organiza tu app
+
+### ¿Qué es?
+Es una forma de organizar el código en tres partes separadas.
+
+### Analogía: Un restaurante
+- **Modelo (Cocina)**: Donde se prepara la comida (los datos)
+- **Vista (Mesa)**: Lo que ve el cliente (las páginas web)
+- **Controlador (Mesero)**: Conecta pedidos con cocina (la lógica)
+
+### En tu proyecto
+```
+app/
+├── models/      ← Los datos (User, Article)
+├── views/       ← Las páginas HTML
+└── controllers/ ← La lógica que conecta todo
+```
+
+Cuando alguien visita /articles:
+1. El controlador recibe la visita
+2. Pide los artículos al modelo
+3. Los envía a la vista para mostrarlos
+```
+
+### Migraciones
+```markdown
+## Migraciones - Cambios en la base de datos
+
+### ¿Qué es?
+Son instrucciones para modificar la estructura de tu base de datos.
+
+### Analogía: Reformas en una casa
+Imagina que tu base de datos es una casa:
+- Añadir un campo = añadir un enchufe
+- Crear una tabla = construir una habitación nueva
+- Una migración = el plano de la reforma
+
+Las migraciones guardan el historial de todos los cambios,
+así que siempre puedes ver qué modificaciones se hicieron.
+
+### Ejemplo
+```ruby
+# "Añadir columna 'avatar' a la tabla 'users'"
+add_column :users, :avatar, :string
+```
+```
+
+### Rutas
+```markdown
+## Rutas - Las direcciones de tu app
+
+### ¿Qué es?
+Las rutas conectan las URLs con el código que debe ejecutarse.
+
+### Analogía: Recepción de un edificio
+Cuando alguien llega y dice "quiero ir a contabilidad",
+el recepcionista le indica el piso y oficina correctos.
+
+Las rutas hacen lo mismo:
+- Alguien visita `/articles`
+- Rails lo envía al controlador de artículos
+- Se muestra la lista de artículos
+
+### En tu proyecto
+```ruby
+# config/routes.rb
+resources :articles
+# Esto crea automáticamente:
+# GET /articles        → ver todos
+# GET /articles/1      → ver uno
+# GET /articles/new    → formulario nuevo
+# POST /articles       → crear
+# GET /articles/1/edit → formulario editar
+# PATCH /articles/1    → actualizar
+# DELETE /articles/1   → borrar
+```
+```
+
+### Hotwire
+```markdown
+## Hotwire - Páginas rápidas sin JavaScript complejo
+
+### ¿Qué es?
+Una forma de hacer páginas web rápidas y dinámicas sin escribir
+mucho JavaScript.
+
+### Analogía: Remodelación vs Reconstrucción
+Sin Hotwire: Cada vez que haces clic, se derriba toda la casa
+y se construye de nuevo (la página se recarga completamente).
+
+Con Hotwire: Solo se cambia la habitación que necesita cambios
+(se actualiza solo una parte de la página).
+
+### Componentes
+- **Turbo Drive**: Hace clics más rápidos automáticamente
+- **Turbo Frames**: Actualiza solo partes de la página
+- **Turbo Streams**: Actualiza varias partes a la vez
+- **Stimulus**: JavaScript simple para interacciones
+
+### Ejemplo
+Cuando añades un comentario, solo aparece el comentario nuevo
+sin recargar toda la página.
+```
+
+## Variantes del comando
+
+### `/explica [concepto]`
+Explica un concepto técnico general.
+
+### `/explica [archivo]`
+Explica qué hace un archivo específico.
+
+### `/explica [error]`
+Explica qué significa un mensaje de error.
+
+### `/explica arquitectura`
+Explica cómo está organizado el proyecto.
+
+## Formato de respuesta
+
+Para errores:
+```markdown
+## Error: [mensaje de error]
+
+### ¿Qué significa?
+[Explicación en lenguaje sencillo]
+
+### ¿Por qué ocurre?
+[Causa común]
+
+### ¿Cómo solucionarlo?
+[Pasos para arreglarlo]
+```
+
+Para código:
+```markdown
+## Este código hace...
+
+### Resumen
+[Una frase explicando el propósito]
+
+### Línea por línea
+```ruby
+# Esta línea busca al usuario por su email
+user = User.find_by(email: params[:email])
+
+# Esta comprueba si la contraseña es correcta
+if user&.authenticate(params[:password])
+```
+
+### En contexto
+[Cómo encaja en el resto de la aplicación]
+```
+
+## Notas importantes
+
+- Siempre usar lenguaje sencillo
+- Incluir analogías del mundo real
+- Evitar acrónimos sin explicarlos
+- Si algo es complejo, dividirlo en partes
+- Usar ejemplos concretos del proyecto
+- Preguntar si la explicación fue clara

package/framework/commands/feature.md

@@ -0,0 +1,120 @@
+# Comando: /feature
+
+Gestiona features del proyecto: crea nuevos, lista existentes, o detecta automáticamente el trabajo pendiente.
+
+## Argumentos
+- `description` (opcional): Descripción del feature a crear
+
+## Comportamiento
+
+### Sin argumentos: Listar y Recomendar
+
+1. Buscar `features/*/feature.json`
+2. Mostrar cada feature con: ID, título, estado, progreso, lista de tareas
+3. **Detectar siguiente acción** para features en progreso:
+
+| Estado de Tarea | Siguiente Comando |
+|-----------------|-------------------|
+| `defined` | `/plan {task_path}` |
+| `planned` | `/code {task_path}` |
+| `in_progress` | `/code {task_path}` |
+
+Buscar la primera tarea no completada (ordenadas por priority) y recomendar el comando apropiado.
+
+**Ejemplo de salida:**
+```
+FEATURES DEL PROYECTO
+=====================
+
+ID: 2025-12-19-175523-crm-rails
+Título: CRM con Rails y Tailwind
+Estado: in_progress
+Progreso: [███████░░░░░░░░░] 43% (3/7 tareas)
+
+  Tareas:
+  ✓ 001 - Setup del Proyecto
+  ✓ 002 - CRUD de Empresas
+  ✓ 003 - CRUD de Contactos
+  ○ 004 - CRUD de Oportunidades (planned)    ← PRIMERA PENDIENTE
+  ○ 005 - Dashboard con Métricas (defined)
+  ○ 006 - Búsqueda (defined)
+  ○ 007 - Vista Pipeline (defined)
+
+═══════════════════════════════════════════════════════════════
+SIGUIENTE ACCIÓN:
+
+/code features/.../tasks/004-crud-oportunidades
+═══════════════════════════════════════════════════════════════
+```
+
+**Si no hay features:**
+```
+No hay features creados todavía.
+
+Para crear uno nuevo:
+/feature "Descripción de lo que quieres construir..."
+```
+
+### Con descripción: Crear Feature
+
+1. **Verificar solapamiento** con features existentes (revisar títulos, descripciones, PRDs)
+   - Si hay solapamiento potencial, alertar y pedir confirmación
+2. **Generar ID**: `{YYYY-MM-DD-hhmmss}-{slug}`
+   - Slug: palabras clave, lowercase, sin acentos, guiones, max 30 chars
+3. **Crear estructura**:
+   ```
+   features/{id}/
+   features/{id}/feature.json
+   ```
+4. **Crear feature.json** usando template de `.claude/templates/feature.json`:
+   ```json
+   {
+     "version": "1.0",
+     "id": "{id}",
+     "title": "{título inferido}",
+     "description": "{descripción}",
+     "original_request": "{texto exacto del usuario}",
+     "created_at": "{ISO timestamp}",
+     "updated_at": "{ISO timestamp}",
+     "status": "created",
+     "progress": 0,
+     "current_phase": "initial",
+     "tasks": []
+   }
+   ```
+
+   **IMPORTANTE:** El campo `original_request` debe contener el texto EXACTO que el usuario proporcionó, sin modificaciones.
+
+5. **Validar** que se creó correctamente
+6. **Actualizar** `.claude/history/changelog.md`
+
+## Report de Creación
+
+```
+Feature creado exitosamente!
+
+## Metadata
+id: `{id}`
+created_at: `{timestamp}`
+
+## Detalles
+Título: {título}
+Ubicación: features/{id}/
+
+## Request Original
+> {original_request}
+
+## Análisis de Solapamiento
+Features revisados: {N}
+Solapamientos detectados: {M}
+{lista de solapamientos si hay}
+
+## Siguiente Paso
+/prd {id}
+```
+
+## Notas importantes
+
+- Siempre mostrar el siguiente paso recomendado
+- Mantener el historial actualizado
+- Detectar y alertar sobre solapamientos antes de crear