claude-agent-framework 1.0.0

package/framework/commands/seeds.md

@@ -0,0 +1,230 @@
+# Comando: /seeds
+
+Genera datos de prueba realistas para la aplicación.
+
+## Flujo de trabajo
+
+### Paso 1: Analizar modelos existentes
+
+1. Leer todos los modelos en `app/models/`
+2. Identificar relaciones entre modelos
+3. Determinar validaciones y restricciones
+
+### Paso 2: Preguntar preferencias
+
+"¿Cuántos datos de prueba quieres generar?"
+- Mínimo (5-10 registros por modelo)
+- Medio (20-50 registros por modelo)
+- Extenso (100+ registros por modelo)
+
+"¿Quieres un usuario de prueba específico?"
+- Email: test@example.com
+- Contraseña: password123
+
+### Paso 3: Generar archivo de seeds
+
+```ruby
+# db/seeds.rb
+
+puts "🌱 Iniciando seed de datos..."
+
+# Limpiar datos existentes (en orden inverso de dependencias)
+puts "Limpiando datos existentes..."
+# [Modelos dependientes primero]
+Comment.destroy_all
+Article.destroy_all
+User.destroy_all
+
+# Crear usuario de prueba
+puts "Creando usuario de prueba..."
+test_user = User.create!(
+  email_address: "test@example.com",
+  password: "password123",
+  password_confirmation: "password123"
+)
+puts "  ✅ Usuario de prueba: test@example.com / password123"
+
+# Crear usuarios adicionales
+puts "Creando usuarios..."
+users = 10.times.map do |i|
+  User.create!(
+    email_address: Faker::Internet.unique.email,
+    password: "password123",
+    password_confirmation: "password123"
+  )
+end
+puts "  ✅ #{users.count} usuarios creados"
+
+# Crear artículos
+puts "Creando artículos..."
+all_users = [test_user] + users
+article_count = 0
+
+all_users.each do |user|
+  rand(3..8).times do
+    Article.create!(
+      title: Faker::Lorem.sentence(word_count: rand(4..8)),
+      body: Faker::Lorem.paragraphs(number: rand(3..8)).join("\n\n"),
+      published: [true, true, true, false].sample,
+      user: user,
+      created_at: Faker::Time.between(from: 6.months.ago, to: Time.current)
+    )
+    article_count += 1
+  end
+end
+puts "  ✅ #{article_count} artículos creados"
+
+# Crear comentarios
+puts "Creando comentarios..."
+comment_count = 0
+
+Article.where(published: true).each do |article|
+  rand(0..10).times do
+    Comment.create!(
+      body: Faker::Lorem.paragraph(sentence_count: rand(1..4)),
+      user: all_users.sample,
+      article: article,
+      created_at: Faker::Time.between(from: article.created_at, to: Time.current)
+    )
+    comment_count += 1
+  end
+end
+puts "  ✅ #{comment_count} comentarios creados"
+
+# Resumen final
+puts ""
+puts "=" * 50
+puts "🎉 Seed completado!"
+puts "=" * 50
+puts ""
+puts "Resumen:"
+puts "  - Usuarios: #{User.count}"
+puts "  - Artículos: #{Article.count} (#{Article.where(published: true).count} publicados)"
+puts "  - Comentarios: #{Comment.count}"
+puts ""
+puts "Usuario de prueba:"
+puts "  📧 Email: test@example.com"
+puts "  🔑 Contraseña: password123"
+puts ""
+```
+
+### Paso 4: Ejecutar seeds
+
+```bash
+rails db:seed
+```
+
+### Paso 5: Verificar datos
+
+```bash
+rails runner "puts 'Users: ' + User.count.to_s; puts 'Articles: ' + Article.count.to_s"
+```
+
+### Paso 6: Mostrar resumen
+
+```markdown
+# Datos de Prueba Generados
+
+## Resumen
+| Modelo | Cantidad |
+|--------|----------|
+| Users | 11 |
+| Articles | 55 |
+| Comments | 234 |
+
+## Usuario de prueba
+- **Email**: test@example.com
+- **Contraseña**: password123
+
+## Datos generados
+Los datos incluyen:
+- Usuarios con emails realistas
+- Artículos con títulos y contenido variado
+- Mezcla de artículos publicados y borradores
+- Comentarios en artículos publicados
+- Fechas distribuidas en los últimos 6 meses
+
+## Comandos útiles
+
+```bash
+# Regenerar datos
+rails db:seed
+
+# Limpiar y regenerar
+rails db:reset  # Cuidado: borra todo
+
+# Ver datos en consola
+rails console
+> User.all
+> Article.published.count
+```
+```
+
+## Variantes del comando
+
+### `/seeds [modelo]`
+Genera seeds solo para un modelo específico.
+
+### `/seeds reset`
+Limpia todos los datos y regenera.
+
+### `/seeds add [n]`
+Añade N registros más sin borrar existentes.
+
+## Datos específicos por modelo
+
+### Usuarios
+```ruby
+User.create!(
+  email_address: Faker::Internet.unique.email,
+  password: "password123",
+  # Si hay campos adicionales:
+  name: Faker::Name.name,
+  bio: Faker::Lorem.paragraph
+)
+```
+
+### Contenido con texto
+```ruby
+Article.create!(
+  title: Faker::Book.title,  # O Faker::Lorem.sentence
+  body: Faker::Markdown.sandwich(sentences: 6),
+  summary: Faker::Lorem.paragraph
+)
+```
+
+### Con fechas
+```ruby
+Event.create!(
+  name: Faker::Company.catch_phrase,
+  starts_at: Faker::Time.forward(days: 30),
+  ends_at: Faker::Time.forward(days: 60)
+)
+```
+
+### Con archivos (Active Storage)
+```ruby
+user = User.create!(...)
+user.avatar.attach(
+  io: URI.open(Faker::Avatar.image),
+  filename: "avatar.jpg"
+)
+```
+
+### Con enums
+```ruby
+Order.create!(
+  status: Order::STATUSES.sample,
+  # o
+  status: [:pending, :processing, :completed].sample
+)
+```
+
+## Notas importantes
+
+- Los seeds deben ser idempotentes (seguros de ejecutar múltiples veces)
+- Usar `destroy_all` con cuidado en producción
+- Faker genera datos en inglés por defecto
+- Para datos en español: `Faker::Config.locale = 'es'`
+- Siempre incluir un usuario de prueba conocido
+- Los datos de prueba no deben ir a producción

package/framework/commands/seguridad.md

@@ -0,0 +1,226 @@
+# Comando: /seguridad
+
+Ejecuta una auditoría de seguridad completa de la aplicación.
+
+## Descripción
+
+Este comando analiza la aplicación en busca de vulnerabilidades de seguridad, revisa la configuración, y genera un reporte detallado con recomendaciones.
+
+## Proceso
+
+### 1. Análisis estático con Brakeman
+
+```bash
+# Verificar si Brakeman está instalado
+bundle show brakeman || bundle add brakeman --group development
+
+# Ejecutar análisis
+bundle exec brakeman -q -o tmp/brakeman-report.json -f json
+bundle exec brakeman -o tmp/brakeman-report.html
+```
+
+### 2. Auditoría de dependencias
+
+```bash
+# Verificar si bundler-audit está instalado
+bundle show bundler-audit || bundle add bundler-audit --group development
+
+# Actualizar base de datos de vulnerabilidades
+bundle exec bundle-audit update
+
+# Ejecutar auditoría
+bundle exec bundle-audit check
+```
+
+### 3. Verificar configuración de seguridad
+
+Revisar los siguientes archivos:
+
+```ruby
+# config/environments/production.rb
+- [ ] config.force_ssl = true
+- [ ] config.consider_all_requests_local = false
+- [ ] config.hosts configurado
+
+# config/initializers/content_security_policy.rb
+- [ ] CSP configurado
+
+# config/initializers/filter_parameter_logging.rb
+- [ ] Parámetros sensibles filtrados
+
+# config/initializers/session_store.rb
+- [ ] Cookies seguras (secure, httponly, same_site)
+```
+
+### 4. Revisar autenticación
+
+```ruby
+# Verificar:
+- [ ] has_secure_password implementado
+- [ ] Validaciones de password (longitud, complejidad)
+- [ ] Rate limiting en login
+- [ ] Account lockout tras intentos fallidos
+```
+
+### 5. Revisar autorización
+
+```ruby
+# Verificar:
+- [ ] Pundit implementado
+- [ ] after_action :verify_authorized en controllers
+- [ ] Políticas restrictivas por defecto
+- [ ] verify_policy_scoped para index actions
+```
+
+### 6. Buscar patrones vulnerables
+
+```bash
+# SQL Injection potencial
+grep -rn "where.*\#{" app/ --include="*.rb"
+grep -rn "\.find_by_sql" app/ --include="*.rb"
+
+# XSS potencial
+grep -rn "\.html_safe" app/ --include="*.rb"
+grep -rn "raw(" app/ --include="*.erb"
+grep -rn "<%= raw" app/ --include="*.erb"
+
+# Mass assignment
+grep -rn "permit!" app/ --include="*.rb"
+
+# Hardcoded secrets
+grep -rn "password\s*=" app/ --include="*.rb" | grep -v "password_digest"
+grep -rn "api_key\s*=" app/ --include="*.rb"
+grep -rn "secret" app/ --include="*.rb" | grep -v credentials
+```
+
+### 7. Verificar headers de seguridad
+
+```ruby
+# Hacer request y verificar headers
+curl -I https://localhost:3000 2>/dev/null | grep -E "X-Frame|X-Content|X-XSS|Content-Security|Strict-Transport"
+
+# Headers esperados:
+# X-Frame-Options: DENY o SAMEORIGIN
+# X-Content-Type-Options: nosniff
+# X-XSS-Protection: 1; mode=block
+# Content-Security-Policy: ...
+# Strict-Transport-Security: max-age=...
+```
+
+## Output
+
+### Reporte de seguridad
+
+```markdown
+# Auditoría de Seguridad
+Fecha: [fecha actual]
+Proyecto: [nombre del proyecto]
+
+## Resumen Ejecutivo
+
+| Categoría | Estado |
+|-----------|--------|
+| Brakeman | ✅ / ⚠️ / ❌ |
+| Dependencias | ✅ / ⚠️ / ❌ |
+| Configuración | ✅ / ⚠️ / ❌ |
+| Autenticación | ✅ / ⚠️ / ❌ |
+| Autorización | ✅ / ⚠️ / ❌ |
+| Headers | ✅ / ⚠️ / ❌ |
+
+## Hallazgos por Severidad
+
+### Críticos (requieren acción inmediata)
+[Lista de hallazgos críticos]
+
+### Altos (resolver pronto)
+[Lista de hallazgos altos]
+
+### Medios (planificar corrección)
+[Lista de hallazgos medios]
+
+### Bajos (mejoras recomendadas)
+[Lista de hallazgos bajos]
+
+## Detalles
+
+### Brakeman
+[Resumen de warnings encontrados]
+
+### Dependencias vulnerables
+[Lista de gems con vulnerabilidades conocidas]
+
+### Configuración
+[Problemas de configuración encontrados]
+
+## Recomendaciones
+
+1. [Recomendación prioritaria con pasos]
+2. [Siguiente recomendación]
+...
+
+## Próximos pasos
+
+- [ ] Corregir hallazgos críticos
+- [ ] Actualizar dependencias vulnerables
+- [ ] Implementar mejoras de configuración
+- [ ] Programar siguiente auditoría
+```
+
+## Ejemplos de uso
+
+```bash
+# Usuario escribe:
+/seguridad
+
+# O en lenguaje natural:
+"Revisa la seguridad de la app"
+"Ejecuta una auditoría de seguridad"
+"Busca vulnerabilidades"
+"¿Es segura mi aplicación?"
+```
+
+## Automatización
+
+### GitHub Action para CI
+
+```yaml
+# .github/workflows/security.yml
+name: Security Audit
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: '0 0 * * 1'  # Lunes a medianoche
+
+jobs:
+  security:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - name: Run Brakeman
+        run: |
+          gem install brakeman
+          brakeman -q -w2 --no-pager
+
+      - name: Run Bundle Audit
+        run: |
+          gem install bundler-audit
+          bundle-audit check --update
+```
+
+## Notas
+
+- Ejecutar regularmente (al menos semanalmente)
+- Revisar antes de cada deploy a producción
+- Mantener dependencias actualizadas
+- Documentar excepciones de seguridad aceptadas

package/framework/commands/tasks.md

@@ -0,0 +1,157 @@
+# Comando: /tasks
+
+Crea tareas (historias de usuario) a partir del PRD del feature siguiendo el **Principio de Independencia**.
+
+## Argumentos
+- `feature_id` (requerido): ID del feature (ej. 2025-12-19-143052-mi-feature)
+
+## Principio: Independencia de Tareas
+
+Cada tarea debe cumplir:
+
+| Aspecto | Requisito |
+|---------|-----------|
+| **Independiente** | Puede implementarse sin depender de tareas no completadas |
+| **Atómica** | Una sola funcionalidad por tarea |
+| **Verificable** | Criterios de aceptación claros y testeables |
+| **Estimable** | Tamaño razonable para una sesión de trabajo |
+| **Ordenada** | Prioridad clara basada en dependencias y valor |
+
+### Detección de Violaciones
+
+**CRÍTICO**: Al generar tareas, detectar activamente:
+
+1. **Dependencias Circulares**: Tarea A depende de B, B depende de A
+2. **Tareas Muy Grandes**: Más de 5 criterios de aceptación
+3. **Tareas Duplicadas**: Misma funcionalidad en diferentes tareas
+4. **Conflictos con Otros Features**: Tareas que modifican los mismos archivos
+
+**Si se encuentran violaciones, dividir o reorganizar las tareas.**
+
+## Flujo de trabajo
+
+### Fase 1: Localizar y Validar el Feature
+
+1. Buscar en `features/{feature_id}/`
+2. Verificar que existe `feature.json` y `prd.md`
+3. Si falta el PRD, mostrar error y sugerir `/prd {feature_id}` primero
+
+### Fase 2: Análisis de Tareas Existentes (OBLIGATORIO)
+
+1. Listar todas las tareas en `features/*/tasks/*/`
+2. Identificar tareas con status `defined`, `planned`, `in_progress`
+3. Extraer archivos que planean modificar (de sus plan.md si existen)
+
+**Crear matriz de conflictos potenciales:**
+```
+| Archivo/Recurso | Este Feature | Otro Feature | Conflicto? |
+|-----------------|--------------|--------------|------------|
+| users_controller.rb | Tarea 001 | feature-abc/002 | REVISAR |
+```
+
+### Fase 3: Leer y Analizar el PRD
+
+1. Cargar `features/{feature_id}/prd.md`
+2. Identificar los requisitos funcionales (RF-XX)
+3. Entender el flujo de usuario
+4. Identificar dependencias entre funcionalidades
+5. Revisar el alcance (incluido vs excluido)
+
+### Fase 4: Crear Carpeta de Tareas
+
+```bash
+mkdir -p features/{feature_id}/tasks/
+```
+
+### Fase 5: Generar Tareas
+
+Aplicar criterios:
+
+1. **Una tarea por requisito funcional principal**
+2. **Ordenar por dependencias** (las base primero)
+3. **IDs secuenciales**: 001, 002, 003...
+4. **Slugs descriptivos**: `crear-comentario`, `responder-comentario`
+
+### Fase 6: Crear Estructura de Cada Tarea
+
+Para cada tarea, crear:
+```
+features/{feature_id}/tasks/{id}-{slug}/
+features/{feature_id}/tasks/{id}-{slug}/user-story.md
+```
+
+Usar el template de `.claude/templates/task-user-story.md`
+
+### Fase 7: Actualizar feature.json
+
+1. Agregar array `tasks` con cada tarea:
+   ```json
+   {
+     "id": "001",
+     "slug": "crear-comentario",
+     "title": "Crear comentario en artículo",
+     "status": "defined",
+     "priority": 1,
+     "requisito": "RF-01",
+     "depends_on": []
+   }
+   ```
+2. Cambiar `status` a `"tasks_created"`
+3. Cambiar `current_phase` a `"tasks"`
+4. Actualizar `updated_at`
+
+### Fase 8: Validar Tareas Creadas
+
+```bash
+# Verificar que existe al menos una tarea
+ls features/{feature_id}/tasks/*/user-story.md | wc -l
+
+# Verificar tamaño de tareas (máximo 5 criterios por tarea)
+for story in features/{feature_id}/tasks/*/user-story.md; do
+  count=$(grep -c "^\- \[ \]" "$story")
+  if [ "$count" -gt 5 ]; then
+    echo "WARNING: $story tiene $count criterios (máximo recomendado: 5)"
+  fi
+done
+```
+
+## Criterios de Priorización
+
+| Prioridad | Descripción | Ejemplo |
+|-----------|-------------|---------|
+| **1** | Funcionalidad base necesaria para otras tareas | Modelo de datos |
+| **2** | Funcionalidad de alto valor para el usuario | CRUD principal |
+| **3** | Funcionalidades complementarias o de mejora | Validaciones extra |
+| **4** | Funcionalidades opcionales o de bajo impacto | Mejoras de UX |
+
+## Report
+
+```
+Tareas generadas exitosamente!
+
+Feature: {título}
+Total: {N} tareas creadas
+
+TAREAS:
+001 - {título tarea 1} [defined] (RF-01) P1
+     Depende de: ninguna
+002 - {título tarea 2} [defined] (RF-02) P1
+     Depende de: 001
+003 - {título tarea 3} [defined] (RF-03) P2
+     Depende de: 001, 002
+
+Conflictos detectados: {M}
+- {descripción del conflicto si hay}
+
+Siguiente paso:
+/plan features/{feature_id}/tasks/001-{slug}
+```
+
+## Consideraciones
+
+- Las tareas deben ser independientes cuando sea posible
+- Si hay dependencias, la tarea dependiente debe tener prioridad mayor (número mayor)
+- Cada tarea debe ser lo suficientemente pequeña para completarse en una sesión
+- Los criterios de aceptación deben ser verificables objetivamente
+- Documentar conflictos con tareas de otros features
+- Máximo 5 criterios de aceptación por tarea (dividir si hay más)