don-cheli-sdd 1.13.0

package/scripts/.claude/commands/especdev/explorar.md

@@ -0,0 +1,175 @@
+---
+description: Explorar e investigar el codebase antes de proponer cambios
+i18n: true
+---
+
+# /especdev:explorar
+
+## Objetivo
+
+Investigar el codebase existente antes de comprometer un cambio. Entender la arquitectura, patrones, convenciones y dependencias ANTES de modificar nada.
+
+> Adaptado de `sdd-explore` de Gentle-AI — fase que Don Cheli no tenía.
+> Mejorado con Modo Supuestos de Get Shit Done (gsd-build/get-shit-done).
+
+## Uso
+
+```
+/especdev:explorar <área o concepto a investigar>
+/especdev:explorar --profundidad <superficial|media|profunda>
+/especdev:explorar --modo supuestos                            # Modo Supuestos (nuevo)
+```
+
+## Dos Modos de Exploración
+
+### Modo Interactivo (default)
+
+El modo original: el agente investiga y hace preguntas al usuario.
+
+**Flujo:** Escanear → Preguntar → Documentar → Repetir (15-20 interacciones típicas)
+
+### Modo Supuestos (nuevo)
+
+El agente analiza el codebase, forma **supuestos con evidencia**, y el usuario solo confirma o corrige.
+
+**Flujo:** Analizar → Presentar supuestos → Usuario confirma/corrige (2-4 interacciones típicas)
+
+**Cuándo usar cada modo:**
+
+| Situación | Modo recomendado |
+|-----------|------------------|
+| Proyecto nuevo sin código | Interactivo |
+| Codebase existente con >10 archivos | **Supuestos** |
+| Usuario conoce bien el proyecto | **Supuestos** |
+| Dominio complejo o desconocido | Interactivo |
+| Quiero terminar rápido | **Supuestos** |
+
+## Comportamiento — Modo Interactivo
+
+1. **Escanear** estructura del proyecto (directorios, archivos clave)
+2. **Identificar** stack tecnológico (package.json, requirements.txt, etc.)
+3. **Mapear** patrones existentes (naming, estructura, imports)
+4. **Detectar** convenciones (estilo de código, formato de tests)
+5. **Documentar** hallazgos en `.especdev/hallazgos.md`
+
+## Comportamiento — Modo Supuestos
+
+### Paso 1: Análisis Silencioso
+
+El agente analiza 5-15 archivos relevantes **sin preguntar nada**:
+
+```
+Analizando codebase...
+├── Archivos escaneados: 12
+├── Patrones detectados: 8
+├── Convenciones inferidas: 5
+└── Supuestos formados: 7
+```
+
+### Paso 2: Presentar Supuestos
+
+Cada supuesto incluye **evidencia** y **nivel de confianza**:
+
+```markdown
+## Supuestos sobre el Módulo de Autenticación
+
+### S1: El proyecto usa Repository Pattern [ALTA confianza]
+**Evidencia:**
+- `src/repositories/user_repo.py` existe con interface definida (línea 5-15)
+- `src/services/auth_service.py` recibe repositorio por inyección (línea 8)
+- 3 repositorios más siguen el mismo patrón
+
+**Supuesto:** Los nuevos componentes DEBEN seguir Repository Pattern con DI.
+→ ¿Correcto? [sí/no/matiz]
+
+---
+
+### S2: Los tests de integración usan base de datos real [MEDIA confianza]
+**Evidencia:**
+- `tests/conftest.py` crea una BD de test (línea 12-20)
+- No hay mocks de BD en `tests/integration/`
+- Pero `tests/unit/` sí usa mocks
+
+**Supuesto:** Integration tests = BD real. Unit tests = mocks.
+→ ¿Correcto? [sí/no/matiz]
+
+---
+
+### S3: No hay sistema de permisos/roles [ALTA confianza]
+**Evidencia:**
+- No existe archivo de roles ni middleware de permisos
+- El JWT solo contiene `user_id`, sin `role` ni `permissions`
+- No hay tests relacionados con autorización
+
+**Supuesto:** La feature nueva NO necesita considerar roles/permisos.
+→ ¿Correcto? [sí/no/matiz]
+```
+
+### Paso 3: Confirmar/Corregir
+
+El usuario responde con:
+- **"sí"** → Supuesto confirmado
+- **"no"** → Supuesto rechazado (el agente pide la corrección)
+- **"matiz: ..."** → Parcialmente correcto (el agente ajusta)
+
+### Paso 4: Generar Hallazgos
+
+Los supuestos confirmados se documentan en `.especdev/hallazgos.md` con la misma estructura que el modo interactivo, pero **más rápido**.
+
+## Niveles de Confianza
+
+| Nivel | Significado | Evidencia requerida |
+|-------|-------------|---------------------|
+| **ALTA** | Patrón consistente en 3+ archivos | ≥3 archivos coinciden |
+| **MEDIA** | Patrón en 1-2 archivos o con excepciones | 1-2 archivos, con contraejemplos |
+| **BAJA** | Inferencia sin evidencia directa | Sin archivos que lo demuestren directamente |
+
+**Regla:** Solo presentar supuestos con confianza MEDIA o ALTA. Los de confianza BAJA se descartan o se convierten en preguntas abiertas.
+
+## Output
+
+```markdown
+## Exploración: Módulo de Autenticación
+
+### Stack Detectado
+- Framework: FastAPI 0.115
+- ORM: SQLAlchemy 2.0
+- Auth: JWT con python-jose
+- Tests: pytest + pytest-asyncio
+
+### Estructura
+app/
+├── services/auth_service.py  (342 líneas)
+├── routers/auth.py           (89 líneas)
+├── models/user.py            (45 líneas)
+└── middleware/jwt.py          (67 líneas)
+
+### Convenciones Encontradas
+- Servicios usan async/await
+- Repository pattern con inyección de dependencias
+- Tests unitarios en tests/unit/, integración en tests/integration/
+- Naming: snake_case para todo
+
+### Funcionalidad Existente Relevante
+- `auth_service.create_user()` ya existe
+- `jwt.verify_token()` ya existe
+- `UserRepository` interface definida
+
+### Supuestos Confirmados (Modo Supuestos)
+- S1 ✅ Repository Pattern con DI es obligatorio
+- S2 ✅ Integration tests = BD real, unit tests = mocks
+- S3 ✅ No hay sistema de roles/permisos
+
+### ⚠️ Notas
+- El middleware de auth no cubre rutas /admin/*
+- No hay tests para refresh token
+```
+
+## Integración con Pipeline
+
+```
+/especdev:explorar → hallazgos.md
+→ /especdev:proponer → propuesta de cambio
+→ /especdev:especificar → .feature
+→ ... (pipeline normal)
+```

package/scripts/.claude/commands/especdev/guardian.md

@@ -0,0 +1,99 @@
+---
+description: Revisión de código IA como pre-commit hook — Guardian Angel
+i18n: true
+---
+
+# /especdev:guardian
+
+## Objetivo
+
+Ejecutar revisión de código automatizada usando IA como puerta de calidad antes de cada commit. Actúa como un "Ángel Guardián" que valida que el código cumple con los estándares del equipo.
+
+> Inspirado en GGA (Gentleman Guardian Angel) de Gentle-AI.
+
+## Uso
+
+```
+/especdev:guardian                    # Revisar archivos staged
+/especdev:guardian --modo pr          # Revisar todos los cambios del branch vs base
+/especdev:guardian --modo ci          # Para integración continua
+/especdev:guardian --instalar-hook    # Instalar como pre-commit hook
+```
+
+## Cómo Funciona
+
+```
+git add <archivos>
+git commit -m "feat: agregar login"
+    │
+    ├── Hook pre-commit se activa
+    │   └── /especdev:guardian
+    │       ├── Lee archivos staged
+    │       ├── Lee reglas de .especdev/estandares.md
+    │       ├── Envía al LLM para revisión
+    │       └── Resultado:
+    │           ├── ✅ PASS → commit permitido
+    │           ├── ⚠️ WARN → commit con advertencias
+    │           └── ❌ FAIL → commit BLOQUEADO
+    │
+    └── Resultado del commit
+```
+
+## Estandares de Revisión
+
+El archivo `.especdev/estandares.md` define las reglas que el Guardian valida:
+
+```markdown
+# Estándares de Código
+
+## Obligatorios (❌ si falta)
+- [ ] Type hints en todas las firmas de función
+- [ ] No hay `any` / `Any` sin justificación
+- [ ] Tests para lógica de negocio nueva
+- [ ] No credenciales en código fuente
+- [ ] Manejo de errores (no try/catch vacíos)
+
+## Recomendados (⚠️ si falta)
+- [ ] Docstrings en funciones públicas
+- [ ] Nombres descriptivos (no variables de 1 letra)
+- [ ] Imports organizados
+```
+
+## Output
+
+```
+=== Guardian Angel: Revisión de Código ===
+
+Archivos revisados: 3
+Modelo usado: sonnet
+
+✅ PASS: app/services/auth_service.py
+  • Type hints completos
+  • Manejo de errores correcto
+  • Tests existentes
+
+⚠️ WARN: app/routers/auth.py
+  • Falta docstring en endpoint /login (recomendado)
+  • Import no usado: `from typing import Optional`
+
+❌ FAIL: app/config.py
+  • Línea 23: API_KEY hardcodeada — usar variable de entorno
+  • Línea 45: try/except vacío que engulre errores
+
+RESULTADO: BLOQUEADO (1 FAIL)
+→ Corregir los issues marcados con ❌ antes de commitear
+```
+
+## Caché Inteligente
+
+- SHA256 por archivo — solo re-revisa archivos que cambiaron
+- Solo archivos con `PASS` se cachean
+- El caché se invalida si `.especdev/estandares.md` cambia
+
+## Selección de Modelo
+
+| Tipo de Revisión | Modelo |
+|-----------------|--------|
+| Style / lint | `haiku` (rápido, barato) |
+| Lógica de negocio | `sonnet` (balance) |
+| Seguridad / crypto | `opus` (profundidad) |

package/scripts/.claude/commands/especdev/historial.md

@@ -0,0 +1,14 @@
+---
+description: Listar sesiones pasadas guardadas en el historial
+i18n: true
+---
+
+# /especdev:historial
+
+## Uso
+
+```
+/especdev:historial
+```
+
+Lista las sesiones almacenadas en `.especdev/historial/`.

package/scripts/.claude/commands/especdev/implementar.md

@@ -0,0 +1,227 @@
+---
+description: Ejecutar tareas TDD fase por fase dentro de Docker hasta que todos los tests pasen
+i18n: true
+---
+
+# /especdev:implementar
+
+## Objetivo
+
+Ejecutar las tareas generadas por `/especdev:desglosar` de forma automatizada, siguiendo el ciclo TDD (RED → GREEN → REFACTOR) dentro de un entorno Docker aislado, con checkpoints formalizados para intervención humana.
+
+> Adaptado del comando `speckit.implement` de Specular.
+> Mejorado con Taxonomía de Checkpoints de Get Shit Done (gsd-build/get-shit-done).
+
+## Uso
+
+```
+/especdev:implementar @specs/features/<dominio>/<Feature>.tasks.md
+/especdev:implementar --fase <numero>
+/especdev:implementar --seco   # Solo mostrar plan sin ejecutar
+```
+
+## Comportamiento
+
+1. **Leer** archivo `.tasks.md`
+2. **Verificar** que Docker está disponible
+3. **Verificar Nyquist** — Validar mapeo tests↔requisitos (Puerta 5)
+4. **Ejecutar** tareas fase por fase con checkpoints
+
+### Flujo por Fase
+
+```
+┌─ Fase 1: Setup ───────────────────────────────┐
+│  Crear archivos vacíos: modelos, servicios,    │
+│  repositorios, controladores, tests            │
+│  → Verificar: archivos existen                 │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 2: Tests Unitarios (RED) ───────────────┐
+│  Escribir tests que FALLAN                     │
+│  → docker compose run --rm test                │
+│  → Verificar: tests existen y FALLAN (RED)     │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 3: Tests BDD/Integración (RED) ────────┐
+│  Escribir tests BDD desde Gherkin              │
+│  → Aplicar patrones ISA (isa.yml)             │
+│  → docker compose run --rm test                │
+│  → Verificar: tests BDD existen y FALLAN       │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 4: Lógica de Negocio (GREEN) ──────────┐
+│  Implementar código que hace pasar los tests   │
+│  → docker compose run --rm test                │
+│  → [DETECCIÓN STUBS] automática                │
+│  → Verificar: TODOS los tests PASAN (GREEN)    │
+└────────────────────────────────────────────────┘
+         │
+┌─ Fase 5: Lint & Tipos ───────────────────────┐
+│  → docker compose run --rm lint                │
+│  → Verificar: sin errores de lint/tipos        │
+└────────────────────────────────────────────────┘
+```
+
+## Taxonomía de Checkpoints
+
+Durante la ejecución, hay momentos donde el agente DEBE pausar para intervención humana. Estos se clasifican en 3 tipos:
+
+### 1. `[checkpoint:verificar]` — Verificación Humana (90% de los casos)
+
+El agente completó una tarea y necesita que el usuario **verifique el resultado** visualmente o funcionalmente.
+
+```markdown
+⏸️ CHECKPOINT: verificar
+Tarea: T013 — Implementar UsuarioController
+Verificación: Abrir http://localhost:3000/register y verificar:
+  - [ ] El formulario renderiza correctamente
+  - [ ] Los campos tienen labels y placeholders
+  - [ ] El submit envía los datos al backend
+  - [ ] Los errores de validación se muestran al usuario
+
+→ ¿Verificado? [sí/no/parcial]
+```
+
+**Cuándo usar:**
+- UI implementada que requiere verificación visual
+- Flujo de usuario completo que requiere testing manual
+- Integración con servicio externo (OAuth, pagos)
+
+### 2. `[checkpoint:decision]` — Decisión Humana (9% de los casos)
+
+El agente llegó a un punto donde hay **múltiples opciones válidas** y necesita una decisión del usuario.
+
+```markdown
+⏸️ CHECKPOINT: decisión
+Tarea: T010 — Implementar UsuarioService
+Decisión requerida: Estrategia de hashing de contraseña
+
+  A) bcrypt (estándar, bien conocido, ~100ms/hash)
+  B) argon2id (más moderno, más seguro, ~200ms/hash)
+  C) scrypt (alternativa, menos popular)
+
+Recomendación: B (argon2id) — mejor resistencia a ataques GPU
+→ Tu elección: [A/B/C]
+```
+
+**Cuándo usar:**
+- Elección de librería/dependencia externa
+- Decisión arquitectónica con trade-offs
+- Configuración de seguridad
+- Proveedor de servicio externo
+
+### 3. `[checkpoint:accion-humana]` — Acción Humana (1% de los casos)
+
+El agente necesita que el usuario **haga algo** que no puede automatizarse.
+
+```markdown
+⏸️ CHECKPOINT: acción-humana
+Tarea: T015 — Configurar OAuth con Google
+Acción requerida: Crear credenciales en Google Cloud Console
+
+  1. Ir a https://console.cloud.google.com/apis/credentials
+  2. Crear OAuth 2.0 Client ID
+  3. Agregar redirect URI: http://localhost:3000/api/auth/callback/google
+  4. Copiar Client ID y Client Secret
+
+→ Proporcionar:
+  - GOOGLE_CLIENT_ID: ___
+  - GOOGLE_CLIENT_SECRET: ___
+```
+
+**Cuándo usar:**
+- Configuración de servicios externos (OAuth, DNS, certificados)
+- Acciones en dashboards que no tienen API/CLI
+- Aprobaciones organizacionales
+- Configuración de hardware/dispositivos
+
+### Principio: "Si el agente puede ejecutarlo, el agente lo ejecuta"
+
+Los checkpoints son **excepciones**, no la norma. Solo usar cuando genuinamente se necesita intervención humana.
+
+| Automatizable | NO checkpoint | Ejemplo |
+|---------------|---------------|---------|
+| Instalar dependencia | `npm install bcrypt` | El agente lo ejecuta |
+| Crear migración | `prisma migrate dev` | El agente lo ejecuta |
+| Ejecutar tests | `pytest` | El agente lo ejecuta |
+| Formatear código | `prettier --write .` | El agente lo ejecuta |
+
+| No automatizable | SÍ checkpoint | Tipo |
+|------------------|---------------|------|
+| ¿Se ve bien la UI? | Verificar | `verificar` |
+| ¿bcrypt o argon2? | Decidir | `decisión` |
+| Crear API key en dashboard | Acción | `acción-humana` |
+
+## Regla Stop-Loss
+
+> Si una tarea falla (luz ROJA) más de **3 veces** durante la implementación, el trabajo DEBE detenerse y se DEBE solicitar guía humana. Los ciclos infinitos de fix-break están **PROHIBIDOS**.
+
+Integración con **Detección de Loops** (habilidad): si se detecta un loop, escalar según los 3 niveles de escape antes de llegar al stop-loss.
+
+## Ejemplo
+
+```bash
+/especdev:implementar @specs/features/usuario/CrearUsuario.tasks.md
+
+=== Implementando: CrearUsuario ===
+
+📁 Fase 1: Setup
+  ✅ app/models/usuario.py (creado)
+  ✅ app/services/usuario_service.py (creado)
+  ✅ tests/unit/test_usuario_service.py (creado)
+  ✅ tests/integracion/test_crear_usuario.py (creado)
+
+🔴 Fase 2: Tests Unitarios (RED)
+  ✅ 3 tests escritos
+  ✅ 3/3 FALLAN (RED esperado)
+
+🔴 Fase 3: Tests BDD (RED)
+  ✅ 4 escenarios BDD escritos (desde .feature)
+  ✅ 4/4 FALLAN (RED esperado)
+  ✅ ISA patterns aplicados
+
+⏸️ CHECKPOINT: decisión
+  Estrategia de hashing: bcrypt vs argon2id
+  → Usuario elige: argon2id
+
+🟢 Fase 4: Lógica de Negocio (GREEN)
+  ✅ UsuarioService.crear() implementado
+  ✅ Detección de stubs: 0 stubs encontrados
+  ✅ 7/7 tests PASAN (GREEN)
+
+⏸️ CHECKPOINT: verificar
+  Abrir http://localhost:3000/register
+  → Usuario verifica: ✅ OK
+
+✨ Fase 5: Lint
+  ✅ Sin errores de lint
+  ✅ 0 type errors
+
+=== COMPLETO ===
+Todos los tests pasan. Feature implementada exitosamente.
+```
+
+## Integración con Docker
+
+```yaml
+# docker-compose.yml (requerido)
+services:
+  test:
+    build: .
+    command: pytest -v
+    volumes:
+      - .:/app
+  lint:
+    build: .
+    command: |
+      flake8 app/ &&
+      mypy app/ --strict
+    volumes:
+      - .:/app
+  reporte:
+    build: .
+    command: pytest --html=reports/test-report.html --self-contained-html
+    volumes:
+      - .:/app
+      - ./reports:/app/reports
+```

package/scripts/.claude/commands/especdev/incorporar.md

@@ -0,0 +1,71 @@
+---
+description: Incorporar nuevo desarrollador al proyecto con contexto completo
+i18n: true
+---
+
+# /especdev:incorporar
+
+## Objetivo
+
+Generar un briefing completo del proyecto para incorporar a un nuevo desarrollador (humano o agente IA) con el contexto necesario para ser productivo inmediatamente.
+
+> Adaptado de `/opsx:onboard` de OpenSpec.
+
+## Uso
+
+```
+/especdev:incorporar
+/especdev:incorporar --rol <backend|frontend|fullstack|devops>
+/especdev:incorporar --profundidad <rapido|completo>
+```
+
+## Output (modo rápido)
+
+```markdown
+# Briefing del Proyecto: Mi-App
+
+## Tech Stack
+- Framework: Next.js 15 + TypeScript 5.7
+- BD: PostgreSQL 16 + Prisma
+- Auth: NextAuth.js v5
+- Tests: Vitest + Playwright
+
+## Arquitectura
+app/
+├── (auth)/          → Rutas de autenticación
+├── (dashboard)/     → Panel principal
+├── api/             → API routes
+└── components/      → UI compartida
+
+## Convenciones
+- Código en inglés, commits en español
+- Branches: feature/, fix/, hotfix/
+- Tests obligatorios para lógica de negocio
+- PR máximo 400 líneas
+
+## Estado Actual
+- Fase: Desarrollo (4 de 7)
+- Cambios activos: 2
+  - agregar-oauth (70% completado)
+  - corregir-timeout (pendiente)
+
+## Para Empezar
+1. `npm install`
+2. `cp .env.example .env.local`
+3. `docker compose up -d` (PostgreSQL)
+4. `npx prisma migrate dev`
+5. `npm run dev`
+
+## Specs Activas
+Ver specs/ para documentación de comportamiento.
+Ver .especdev/cambios/ para cambios en progreso.
+```
+
+## Output (modo completo)
+
+Agrega adicionalmente:
+- Decisiones arquitectónicas (ADRs) desde memoria
+- Errores conocidos y workarounds
+- Guía de debugging
+- Patrones de código con ejemplos
+- Flujo completo de un feature típico

package/scripts/.claude/commands/especdev/iniciar.md

@@ -0,0 +1,82 @@
+---
+description: Inicializar Don Cheli en un proyecto nuevo o existente
+i18n: true
+---
+
+# /especdev:iniciar
+
+## Objetivo
+
+Crear el directorio `.especdev/` con todos los archivos de contexto necesarios para comenzar a trabajar con el framework.
+
+## Uso
+
+```
+/especdev:iniciar [opciones]
+```
+
+### Opciones
+
+| Opción | Descripción | Ejemplo |
+|--------|-------------|---------|
+| `--tipo` | Tipo de proyecto | `--tipo cli` |
+| `--nombre` | Nombre del proyecto | `--nombre "mi-app"` |
+| `--gitignore` | Agregar .gitignore template | `--gitignore` |
+| `--con-hooks` | Inicializar hooks locales | `--con-hooks` |
+| `--reparar` | Reparar archivos faltantes | `--reparar` |
+
+## Comportamiento
+
+1. **Detectar idioma** — Leer `${FRAMEWORK_HOME}/locale` (set durante instalación). Si no existe, preguntar al usuario.
+2. **Verificar** si `.especdev/` ya existe
+   - Si existe: preguntar si desea sobrescribir o reparar
+   - Si no existe: continuar
+3. **Crear** directorio `.especdev/`
+4. **Copiar** plantillas desde `plantillas/especdev/`
+5. **Configurar** `config.yaml` con nombre, tipo de proyecto y `framework.idioma` (del locale detectado)
+6. **Inicializar** `estado.md`, `plan.md`, `hallazgos.md`, `progreso.md` — todos en el idioma configurado
+7. **Opcionalmente** crear hooks locales (`--con-hooks`)
+
+**IMPORTANTE:** Todos los archivos generados (.md) deben usar la terminología del idioma configurado. Consultar `locales/{locale}.json` para las traducciones correctas de fases, estados, tipos de proyecto, etc.
+
+## Archivos Creados
+
+```
+.especdev/
+├── config.yaml      # Configuración del proyecto
+├── estado.md        # Estado actual → Fase 1
+├── plan.md          # Plan vacío listo para definir
+├── hallazgos.md     # Descubrimientos (vacío)
+├── progreso.md      # Log de sesión (vacío)
+└── sesion/          # Directorio para PRD y datos de sesión
+```
+
+## Tipos de Proyecto
+
+| Tipo | Descripción |
+|------|-------------|
+| `producto` | Producto completo nuevo |
+| `cli` | Aplicación de línea de comandos |
+| `app` | Aplicación desktop/móvil |
+| `libreria` | Paquete reutilizable |
+| `servicio` | Microservicio/API |
+| `refactor` | Refactoring existente |
+| `correccion` | Corrección de bug |
+
+## Ejemplo
+
+```bash
+/especdev:iniciar --tipo servicio --nombre "api-pagos" --gitignore
+```
+
+Output:
+```
+✅ Don Cheli inicializado
+
+Proyecto: api-pagos
+Tipo: servicio
+Directorio: .especdev/
+Archivos: 5 creados
+
+Próximo paso: edita .especdev/plan.md para definir tus fases
+```