claude-agent-framework 1.0.0

package/framework/commands/nuevo.md

@@ -0,0 +1,118 @@
+# Comando: /nuevo
+
+Inicia el proceso de creación de un nuevo proyecto desde cero.
+
+## Flujo de trabajo
+
+### Paso 1: Descubrimiento inicial
+
+Actúa como el **Product Owner** y realiza una entrevista amigable para entender la idea del usuario:
+
+1. Saluda y pregunta por la idea general del proyecto
+2. Haz preguntas clarificadoras:
+   - ¿Quiénes van a usar la aplicación?
+   - ¿Cuál es el problema principal que resuelve?
+   - ¿Hay alguna app de referencia que te guste?
+   - ¿Qué es lo más importante que debe poder hacer un usuario?
+
+3. Resume lo entendido y confirma con el usuario antes de continuar
+
+### Paso 1b: Ofrecer Flujo Estructurado (Opcional)
+
+Después del discovery inicial, ofrecer al usuario la opción de usar el flujo estructurado:
+
+```
+Tu proyecto parece [simple/complejo]. Puedo proceder de dos formas:
+
+1. **Empezar directamente** - Creo el proyecto y funcionalidades básicas (más rápido)
+2. **Usar flujo estructurado** - Creo un feature con PRD, tareas y planes detallados (más trazabilidad)
+
+¿Qué prefieres?
+```
+
+**Si elige flujo estructurado:**
+1. Ejecutar `/feature "{descripción del proyecto}"`
+2. Continuar con `/prd`, `/tasks`, `/plan`, `/code`
+3. El proceso guiará paso a paso
+
+**Si elige empezar directamente:**
+Continuar con el Paso 2 tradicional
+
+### Paso 2: Definición de requisitos
+
+Una vez confirmada la idea:
+
+1. Crea el archivo `.claude/contexts/requirements.md` con:
+   - Nombre del proyecto
+   - Descripción breve
+   - Usuarios objetivo
+   - Funcionalidades principales (MVP)
+   - Funcionalidades futuras (nice to have)
+
+2. Presenta el resumen al usuario para aprobación
+
+### Paso 3: Arquitectura técnica
+
+Actúa como el **Tech Lead**:
+
+1. Define la estructura de modelos necesarios
+2. Establece las relaciones entre entidades
+3. Crea el archivo `.claude/contexts/architecture.md` con:
+   - Diagrama de modelos
+   - Relaciones
+   - Decisiones técnicas clave
+
+### Paso 4: Diseño visual
+
+Actúa como el **Design Lead**:
+
+1. Define el sistema de diseño básico
+2. Actualiza `.claude/contexts/design-system.md` con:
+   - Paleta de colores
+   - Tipografía
+   - Componentes principales
+
+### Paso 5: Creación del proyecto Rails
+
+Ejecuta los comandos necesarios:
+
+```bash
+# Crear proyecto Rails
+rails new [nombre_proyecto] --database=sqlite3 --css=tailwind --skip-jbuilder
+
+# Entrar al directorio
+cd [nombre_proyecto]
+
+# Instalar dependencias de testing
+bundle add rspec-rails factory_bot_rails faker --group "development, test"
+bundle add shoulda-matchers --group test
+
+# Configurar RSpec
+rails generate rspec:install
+
+# Instalar autenticación
+rails generate authentication
+
+# Ejecutar migraciones
+rails db:migrate
+```
+
+### Paso 6: Estructura inicial
+
+1. Crea los modelos base identificados
+2. Configura las rutas iniciales
+3. Crea las vistas principales con layout base
+
+### Paso 7: Resumen
+
+Presenta al usuario:
+- Lo que se ha creado
+- Cómo ejecutar el proyecto (`bin/dev`)
+- Próximos pasos sugeridos
+
+## Notas importantes
+
+- Siempre confirma con el usuario antes de ejecutar comandos destructivos
+- Guarda el progreso en `.claude/history/changelog.md`
+- Usa lenguaje sencillo, sin jerga técnica innecesaria
+- Si algo no está claro, pregunta antes de asumir

package/framework/commands/plan.md

@@ -0,0 +1,134 @@
+# Comando: /plan
+
+Genera un plan detallado para implementar una tarea específica siguiendo el **Principio de Responsabilidad Única**.
+
+## Argumentos
+- `task_path` (requerido): Path de la tarea (ej. features/2025-12-19-143052/tasks/001-crear-comentario)
+
+## Principio: Responsabilidad Única
+
+Cada tarea planificada debe cumplir:
+
+| Aspecto | Requisito |
+|---------|-----------|
+| **Una Funcionalidad** | Una capacidad por tarea - no agrupar |
+| **Auto-contenido** | Sin dependencias de código no commiteado |
+| **Trazabilidad** | Nombres claros para vincular a código/tests |
+| **Testeable** | Validación pass/fail posible |
+| **Reversible** | Puede revertirse sin romper otros componentes |
+
+### Detección de Violaciones de Diseño
+
+**CRÍTICO**: Al analizar el código existente, detectar activamente:
+
+1. **Código Duplicado**: Misma lógica implementada en múltiples lugares
+2. **Scope Creep**: Componente que hace más de lo que debería
+3. **Ejemplos Redundantes**: Mismos patrones usados inconsistentemente
+4. **Conflictos de Responsabilidad**: Múltiples componentes modificando lo mismo
+
+**Si se encuentran violaciones, el plan DEBE incluir tareas de refactorización.**
+
+## Flujo de trabajo
+
+### Fase 1: Localizar y Validar la Tarea
+
+1. Verificar que existe `{task_path}/user-story.md`
+2. Si no existe, mostrar error con el path correcto
+3. Extraer el feature_id del path (segundo segmento)
+4. Cargar `features/{feature_id}/feature.json` para contexto
+5. Cargar `features/{feature_id}/prd.md` para requisitos
+
+### Fase 2: Análisis del Feature
+
+1. **Leer `CLAUDE.md`**: Convenciones del proyecto
+2. **User Story**: Cargar `{task_path}/user-story.md`
+3. **Criterios de Aceptación**: Identificar todos los escenarios
+4. **PRD del Feature**: Entender el contexto completo
+
+### Fase 3: Análisis de Código Existente (OBLIGATORIO)
+
+1. **Buscar implementaciones similares** en el codebase
+2. **Identificar patrones** que se deben seguir
+3. **Detectar código que necesita modificación** vs creación
+
+**Crear una matriz de impacto:**
+```
+| Componente | Archivo Existente | Líneas | Impacto |
+|------------|-------------------|--------|---------|
+| Model | app/models/x.rb | 45-67 | MODIFICAR |
+| Controller | app/controllers/y.rb | 12-30 | MODIFICAR |
+| View | app/views/z/index.html.erb | N/A | CREAR |
+| Test | spec/models/x_spec.rb | 80-95 | EXTENDER |
+```
+
+### Fase 4: Detección de Conflictos (OBLIGATORIO)
+
+Verificar conflictos potenciales:
+
+1. **Conflictos de Archivo**: Otras tareas pendientes modificando los mismos archivos
+2. **Conflictos de Schema**: Migraciones que podrían conflicturar
+3. **Conflictos de Rutas**: Patrones de URL que se solapan
+4. **Conflictos de Tests**: Fixtures o datos de test compartidos
+
+**Crear matriz de conflictos:**
+```
+| Tipo | Recurso | Otra Tarea | Resolución |
+|------|---------|------------|------------|
+| Archivo | users_controller.rb | task-002 | Secuenciar |
+| Schema | add_column :users | task-003 | Combinar migración |
+```
+
+### Fase 5: Evaluación de Atomicidad
+
+Determinar si esta tarea debe ser:
+- Ejecutada como unidad única
+- Dividida en sub-tareas más pequeñas
+- Combinada con otra tarea relacionada
+
+### Fase 6: Generar el Plan
+
+Escribir el plan en `{task_path}/plan.md` usando el template de `.claude/templates/task-plan.md`
+
+### Fase 7: Actualizar Estado de la Tarea
+
+1. Cargar `features/{feature_id}/feature.json`
+2. Encontrar la tarea en el array `tasks`
+3. Cambiar `status` a `"planned"`
+4. Actualizar `updated_at` del feature
+5. Guardar el archivo
+
+### Fase 8: Validar el Plan Creado
+
+```bash
+# Verificar que el plan existe
+test -f {task_path}/plan.md
+
+# Verificar secciones obligatorias
+grep -q "## Metadata" {task_path}/plan.md
+grep -q "## Matriz de Impacto" {task_path}/plan.md
+grep -q "## Pasos de Implementación" {task_path}/plan.md
+grep -q "## Criterios de Aceptación" {task_path}/plan.md
+```
+
+## Report
+
+```
+Plan creado: {task_path}/plan.md
+
+Resumen:
+- Archivos a crear: {N}
+- Archivos a modificar: {M}
+- Conflictos detectados: {C}
+
+Siguiente paso:
+/code {task_path}
+```
+
+## Consideraciones
+
+- El plan debe ser lo suficientemente detallado para ejecutarse sin ambigüedad
+- Seguir las convenciones y patrones existentes en el proyecto
+- Incluir tests desde el principio (TDD cuando sea apropiado)
+- Los comandos de validación deben ejecutarse sin errores al finalizar
+- Documentar cualquier conflicto o dependencia encontrada
+- NO duplicar lógica existente - reutilizar siempre que sea posible

package/framework/commands/prd.md

@@ -0,0 +1,113 @@
+# Comando: /prd
+
+Genera un documento PRD (Product Requirements Document) estructurado a partir de la descripción del feature siguiendo el **Principio de Fuente Única de Verdad**.
+
+## Argumentos
+- `feature_id` (requerido): ID del feature (ej. 2025-12-19-143052-mi-feature)
+
+## Principio: Fuente Única de Verdad
+
+Cada PRD debe cumplir:
+
+| Aspecto | Requisito |
+|---------|-----------|
+| **Único** | No duplicar requisitos de otros PRDs existentes |
+| **Completo** | Toda la información del feature en un solo lugar |
+| **Trazable** | Cada requisito con ID único para referenciar |
+| **Verificable** | Requisitos específicos que se pueden probar |
+| **Delimitado** | Alcance claro de qué incluye y qué excluye |
+
+### Detección de Violaciones
+
+**CRÍTICO**: Al analizar PRDs existentes, detectar activamente:
+
+1. **Requisitos Duplicados**: Mismo requisito en múltiples PRDs
+2. **Scope Overlap**: Funcionalidades que se solapan con otros features
+3. **Dependencias Ocultas**: Requisitos que dependen de otros PRDs sin documentar
+4. **Conflictos**: Requisitos que contradicen otros PRDs
+
+**Si se encuentran violaciones, el PRD DEBE documentarlas y proponer resolución.**
+
+## Flujo de trabajo
+
+### Fase 1: Localizar y Validar el Feature
+
+1. Buscar en `features/{feature_id}/`
+2. Verificar que existe `feature.json`
+3. Si no existe, mostrar error y sugerir `/feature` primero
+4. Cargar `feature.json` y extraer `title` y `description`
+
+### Fase 2: Análisis de PRDs Existentes (OBLIGATORIO)
+
+1. Listar todos los `features/*/prd.md` existentes
+2. Para cada PRD, extraer:
+   - Requisitos funcionales (RF-XX)
+   - Alcance (incluido/excluido)
+   - Flujos de usuario
+
+**Crear matriz de solapamiento:**
+```
+| Aspecto | Este PRD | PRD Existente | Conflicto? |
+|---------|----------|---------------|------------|
+| Login flow | RF-01 | feature-abc/RF-03 | REVISAR |
+| User model | RF-02 | feature-xyz/RF-01 | NO |
+```
+
+### Fase 3: Investigar el Proyecto
+
+1. **Leer `CLAUDE.md`**: Convenciones del proyecto
+2. **Revisar estructura**: Modelos, controladores, vistas existentes
+3. **Identificar patrones**: Cómo se implementan features similares
+4. **Detectar constraints**: Limitaciones técnicas o de negocio
+
+### Fase 4: Generar el PRD
+
+Escribir el PRD en `features/{feature_id}/prd.md` usando el template de `.claude/templates/prd-template.md`
+
+### Fase 5: Actualizar Estado del Feature
+
+1. Cargar `features/{feature_id}/feature.json`
+2. Cambiar `status` a `"prd_created"`
+3. Cambiar `current_phase` a `"prd"`
+4. Actualizar `updated_at`
+5. Guardar el archivo
+
+### Fase 6: Validar el PRD Creado
+
+```bash
+# Verificar que el PRD existe
+test -f features/{feature_id}/prd.md
+
+# Verificar secciones obligatorias
+grep -q "## Metadata" features/{feature_id}/prd.md
+grep -q "## Requisitos" features/{feature_id}/prd.md
+grep -q "### Funcionales" features/{feature_id}/prd.md
+grep -q "## Alcance" features/{feature_id}/prd.md
+```
+
+## Report
+
+```
+PRD creado exitosamente!
+
+Feature: {título}
+Archivo: features/{feature_id}/prd.md
+
+Resumen del PRD:
+- {N} requisitos funcionales identificados
+- {M} requisitos no funcionales
+- Alcance definido con {P} funcionalidades incluidas
+- {S} solapamientos detectados con otros PRDs
+
+Siguiente paso:
+/tasks {feature_id}
+```
+
+## Consideraciones
+
+- El PRD debe ser comprensible para personas no técnicas
+- Usar lenguaje claro y evitar jerga técnica innecesaria
+- Los requisitos deben ser específicos y verificables
+- El alcance debe ser realista y bien delimitado
+- NO duplicar requisitos de otros PRDs - referenciar en su lugar
+- Documentar todas las dependencias con otros features

package/framework/commands/probar.md

@@ -0,0 +1,148 @@
+# Comando: /probar
+
+Prueba la aplicación como si fueras un usuario real.
+
+## Flujo de trabajo
+
+### Paso 1: Verificar que la app está corriendo
+
+```bash
+# Verificar si hay un servidor corriendo
+curl -s http://localhost:3000/up || echo "El servidor no está corriendo"
+```
+
+Si no está corriendo, sugerir:
+```bash
+bin/dev
+```
+
+### Paso 2: Identificar qué probar
+
+Preguntar al usuario:
+- "¿Quieres que pruebe algo específico o hago una prueba general?"
+
+#### Prueba general
+Probar los flujos principales de la aplicación.
+
+#### Prueba específica
+Probar la funcionalidad que el usuario indique.
+
+### Paso 3: Ejecutar pruebas automatizadas
+
+```bash
+# Correr todos los tests
+bundle exec rspec
+
+# Si hay tests específicos
+bundle exec rspec spec/features/
+bundle exec rspec spec/system/
+```
+
+### Paso 4: Pruebas manuales (CUA)
+
+Usar el skill de Computer Use Agent para navegar la app visualmente:
+
+#### Prueba de registro/login
+1. Ir a la página de registro
+2. Completar el formulario
+3. Verificar que el registro funciona
+4. Cerrar sesión
+5. Iniciar sesión con las credenciales
+
+#### Prueba de funcionalidades principales
+1. Navegar por las páginas principales
+2. Crear contenido (si aplica)
+3. Editar contenido
+4. Eliminar contenido
+5. Verificar que todo funciona
+
+### Paso 5: Pruebas de responsive
+
+1. Probar en viewport de escritorio (1920px)
+2. Probar en viewport de tablet (768px)
+3. Probar en viewport móvil (375px)
+
+### Paso 6: Pruebas de accesibilidad
+
+1. Verificar navegación con teclado
+2. Verificar contraste de colores
+3. Verificar que los formularios tienen labels
+
+### Paso 7: Generar reporte
+
+```markdown
+# Reporte de Pruebas
+Fecha: [fecha]
+
+## Resumen
+- Tests automatizados: ✅ X pasaron / ❌ Y fallaron
+- Tests manuales: ✅ X OK / ❌ Y problemas encontrados
+
+## Tests Automatizados
+[Salida de RSpec]
+
+## Tests Manuales
+
+### Flujo de autenticación
+- [✅/❌] Registro de usuario
+- [✅/❌] Inicio de sesión
+- [✅/❌] Cierre de sesión
+- [✅/❌] Recuperación de contraseña
+
+### Funcionalidades principales
+- [✅/❌] [Funcionalidad 1]
+- [✅/❌] [Funcionalidad 2]
+
+### Responsive
+- [✅/❌] Desktop
+- [✅/❌] Tablet
+- [✅/❌] Móvil
+
+### Accesibilidad
+- [✅/❌] Navegación con teclado
+- [✅/❌] Contraste de colores
+- [✅/❌] Labels en formularios
+
+## Problemas Encontrados
+
+### Problema 1: [Título]
+- **Severidad**: Alta/Media/Baja
+- **Descripción**: [Qué pasa]
+- **Pasos para reproducir**: [Cómo reproducirlo]
+- **Comportamiento esperado**: [Qué debería pasar]
+
+## Recomendaciones
+- [Recomendación 1]
+- [Recomendación 2]
+```
+
+### Paso 8: Presentar resultados
+
+Mostrar al usuario:
+1. Resumen de resultados
+2. Problemas encontrados (si los hay)
+3. Recomendaciones de mejora
+4. Ofrecer arreglar los problemas encontrados
+
+## Tipos de pruebas
+
+### Por funcionalidad
+- `/probar login` - Prueba solo autenticación
+- `/probar formularios` - Prueba todos los formularios
+- `/probar navegación` - Prueba menús y enlaces
+
+### Por página
+- `/probar /articles` - Prueba la página de artículos
+- `/probar /users/1` - Prueba el perfil de usuario
+
+### Por dispositivo
+- `/probar móvil` - Prueba responsive en móvil
+- `/probar tablet` - Prueba responsive en tablet
+
+## Notas importantes
+
+- Asegurarse de que el servidor está corriendo
+- Usar datos de prueba, no datos reales
+- Documentar todos los problemas encontrados
+- Ofrecer soluciones para los problemas
+- Mantener las pruebas actualizadas con los cambios

package/framework/commands/revisar.md

@@ -0,0 +1,208 @@
+# Comando: /revisar
+
+Analiza el código del proyecto para detectar problemas de calidad, seguridad y rendimiento.
+
+## Flujo de trabajo
+
+### Paso 1: Preguntar alcance
+
+"¿Quieres que revise todo el proyecto o algo específico?"
+
+Opciones:
+- Todo el proyecto
+- Un archivo específico
+- Una funcionalidad
+- Solo seguridad
+- Solo rendimiento
+
+### Paso 2: Ejecutar análisis automatizados
+
+```bash
+# Tests
+bundle exec rspec --format documentation
+
+# Seguridad (si está instalado brakeman)
+bundle exec brakeman -q
+
+# Auditoría de dependencias
+bundle audit check --update
+```
+
+### Paso 3: Revisión manual de código
+
+Usar el skill de Code Review para analizar:
+
+#### Seguridad
+- [ ] SQL injection
+- [ ] XSS vulnerabilities
+- [ ] CSRF protection
+- [ ] Mass assignment
+- [ ] Authentication/Authorization
+- [ ] Secrets hardcoded
+
+#### Rendimiento
+- [ ] N+1 queries
+- [ ] Missing indexes
+- [ ] Inefficient queries
+- [ ] Memory usage
+- [ ] Caching opportunities
+
+#### Calidad de código
+- [ ] Convenciones de Rails
+- [ ] DRY (Don't Repeat Yourself)
+- [ ] Single Responsibility
+- [ ] Naming clarity
+- [ ] Code complexity
+
+#### Tests
+- [ ] Cobertura adecuada
+- [ ] Tests significativos
+- [ ] Edge cases cubiertos
+
+### Paso 4: Generar reporte
+
+```markdown
+# Reporte de Revisión de Código
+Fecha: [fecha]
+Alcance: [todo el proyecto / archivo específico / etc.]
+
+## Resumen Ejecutivo
+
+| Área | Estado | Problemas |
+|------|--------|-----------|
+| Seguridad | 🟢/🟡/🔴 | X |
+| Rendimiento | 🟢/🟡/🔴 | X |
+| Calidad | 🟢/🟡/🔴 | X |
+| Tests | 🟢/🟡/🔴 | X |
+
+## Hallazgos de Seguridad
+
+### 🔴 Críticos
+[Ninguno / Lista de problemas]
+
+### 🟡 Advertencias
+[Ninguna / Lista de advertencias]
+
+### ✅ Buenas prácticas encontradas
+[Lista de cosas bien hechas]
+
+## Hallazgos de Rendimiento
+
+### Problemas encontrados
+1. **[Título del problema]**
+   - Ubicación: `archivo.rb:línea`
+   - Problema: [Descripción]
+   - Impacto: [Alto/Medio/Bajo]
+   - Solución sugerida: [Cómo arreglarlo]
+
+### Oportunidades de mejora
+- [Sugerencia 1]
+- [Sugerencia 2]
+
+## Calidad de Código
+
+### Problemas
+- [Lista de problemas de calidad]
+
+### Sugerencias
+- [Lista de mejoras sugeridas]
+
+## Cobertura de Tests
+
+- Modelos: X/Y testeados
+- Controladores: X/Y testeados
+- Features: X/Y testeados
+
+### Tests faltantes
+- [Lista de áreas sin tests]
+
+## Recomendaciones Prioritarias
+
+1. **[Más urgente]**: [Descripción y cómo resolverlo]
+2. **[Segundo]**: [Descripción y cómo resolverlo]
+3. **[Tercero]**: [Descripción y cómo resolverlo]
+
+## Acciones Sugeridas
+
+- [ ] [Acción 1]
+- [ ] [Acción 2]
+- [ ] [Acción 3]
+```
+
+### Paso 5: Presentar resultados
+
+Explicar al usuario:
+1. Estado general del código
+2. Problemas críticos (si los hay)
+3. Mejoras recomendadas
+4. Ofrecer implementar las correcciones
+
+### Paso 6: Ofrecer correcciones
+
+"¿Quieres que arregle alguno de estos problemas?"
+
+Si el usuario acepta:
+1. Priorizar por criticidad
+2. Implementar correcciones una por una
+3. Verificar que no se rompe nada
+4. Actualizar el reporte
+
+## Tipos de revisión
+
+### `/revisar seguridad`
+Enfocarse solo en vulnerabilidades de seguridad.
+
+### `/revisar rendimiento`
+Enfocarse solo en problemas de rendimiento.
+
+### `/revisar [archivo]`
+Revisar un archivo específico en detalle.
+
+### `/revisar tests`
+Analizar la cobertura y calidad de tests.
+
+## Checklist rápido de seguridad
+
+```ruby
+# ❌ Malo - SQL Injection
+User.where("name = '#{params[:name]}'")
+
+# ✅ Bueno
+User.where(name: params[:name])
+
+# ❌ Malo - XSS
+<%= raw user_input %>
+
+# ✅ Bueno
+<%= user_input %>
+
+# ❌ Malo - Mass Assignment
+params.permit!
+
+# ✅ Bueno
+params.require(:user).permit(:name, :email)
+```
+
+## Checklist rápido de rendimiento
+
+```ruby
+# ❌ Malo - N+1
+Article.all.each { |a| puts a.user.name }
+
+# ✅ Bueno
+Article.includes(:user).each { |a| puts a.user.name }
+
+# ❌ Malo - Carga innecesaria
+User.all.count
+
+# ✅ Bueno
+User.count
+```
+
+## Notas importantes
+
+- No alarmar innecesariamente al usuario
+- Priorizar problemas por severidad
+- Explicar los problemas en lenguaje sencillo
+- Ofrecer soluciones concretas
+- Celebrar las buenas prácticas encontradas