don-cheli-sdd 1.13.0

package/comandos/especdev/completo.md

@@ -0,0 +1,49 @@
+---
+description: Modo completo para proyectos grandes y complejos (Nivel 3)
+i18n: true
+---
+
+# /especdev:completo
+
+## Objetivo
+
+Iniciar modo completo (Nivel 3 - Complejo) para proyectos que requieren las 7 fases del ciclo de vida.
+
+## Uso
+
+```
+/especdev:completo <descripción del proyecto>
+```
+
+## Las 7 Fases
+
+| Fase | Duración | Actividades |
+|------|----------|-------------|
+| 1. Descubrimiento | 1-2 días | Validar problema, investigar, descubrimientos |
+| 2. Estrategia | 1 día | Hoja de ruta, hitos, decisiones |
+| 3. Diseño | 2-3 días | Arquitectura, UX, especificaciones |
+| 4. Desarrollo | Variable | TDD, implementación, iteración |
+| 5. Calidad | 1-2 días | Testing, validación, rendimiento |
+| 6. Lanzamiento | 1 día | Despliegue, documentación, release |
+| 7. Crecimiento | Continuo | Monitoreo, feedback, iteración |
+
+## Transiciones de Fase
+
+Cada fase requiere criterios de Avance/No-Avance:
+
+```markdown
+## Fase [N] Completada
+
+### Lista de Verificación Avance/No-Avance
+- [ ] Todas las tareas de la fase completadas
+- [ ] Entregables verificados
+- [ ] Sin bloqueadores
+- [ ] Listo para siguiente fase
+
+**Decisión:** AVANZAR / NO-AVANZAR
+**Motivo:** [por qué]
+```
+
+## Des-escalamiento
+
+Si después de la Estrategia el alcance es menor → des-escalar a `/especdev:rapido`

package/comandos/especdev/continuar.md

@@ -0,0 +1,59 @@
+---
+description: Recuperar sesión previa y generar reporte de puesta al día
+i18n: true
+---
+
+# /especdev:continuar
+
+## Objetivo
+
+Recuperar el contexto de una sesión previa y generar un reporte de puesta al día.
+
+## Uso
+
+```
+/especdev:continuar
+```
+
+## Comportamiento
+
+1. **Detectar** directorio `.especdev/` existente
+2. **Leer** archivos de contexto
+3. **Generar** Reporte de Puesta al Día:
+
+```markdown
+## 🔄 Recuperación de Sesión
+
+**Proyecto:** api-pagos
+**Última Sesión:** 2026-03-21 15:30
+
+**Estado Actual:**
+- Fase: 3/7 (Diseño)
+- Tarea: Diseñar esquema de base de datos
+- Progreso: 40%
+
+**Hallazgos Recientes:**
+- JWT preferido sobre sesiones
+- La API legacy tiene vulnerabilidades
+
+**Próximos Pasos:**
+1. Completar esquema de base de datos
+2. Agregar reset de contraseña
+```
+
+## Test de 5 Preguntas
+
+Para verificar que el contexto está completo:
+
+| # | Pregunta | Fuente | Estado |
+|---|----------|--------|--------|
+| 1 | ¿Dónde estoy? | `estado.md` | Fase actual |
+| 2 | ¿A dónde voy? | `plan.md` | Fases restantes |
+| 3 | ¿Cuál es la meta? | `config.yaml` | Objetivo del proyecto |
+| 4 | ¿Qué he aprendido? | `hallazgos.md` | Descubrimientos clave |
+| 5 | ¿Qué he hecho? | `progreso.md` | Acciones recientes |
+
+**Estado del Contexto:**
+- ✅ Completo (5/5) → Listo para continuar
+- ⚠️ Parcial (3-4/5) → Proceder con precaución
+- ❌ Incompleto (0-2/5) → Ejecutar `/especdev:iniciar --reparar`

package/comandos/especdev/contrato-api.md

@@ -0,0 +1,223 @@
+---
+description: Diseñar contratos de API, webhooks e integraciones con manejo de errores y reintentos
+i18n: true
+---
+
+# /especdev:contrato-api
+
+## Objetivo
+
+Diseñar contratos de API completos (REST o GraphQL), definir webhooks, planificar manejo de errores y reintentos para asegurar la resiliencia de integraciones con plataformas externas.
+
+## Uso
+
+```
+/especdev:contrato-api <descripción de la integración>
+/especdev:contrato-api --tipo rest "Integración con Stripe para pagos"
+/especdev:contrato-api --tipo graphql "API de catálogo de productos"
+/especdev:contrato-api --tipo webhook "Recibir eventos de Shopify"
+```
+
+## Diferencia con `/especdev:planificar-tecnico`
+
+| Aspecto | `planificar-tecnico` | `contrato-api` |
+|---------|---------------------|----------------|
+| **Alcance** | Blueprint completo de una feature | Solo el contrato de API/integración |
+| **Profundidad** | Contrato básico (request/response) | Contrato completo (errores, reintentos, webhooks, idempotencia) |
+| **Cuándo** | Después de spec | Cuando la integración es el foco principal |
+
+## Output para API REST
+
+```markdown
+## Contrato API: Integración de Pagos con Stripe
+
+### Endpoints
+
+#### POST /api/v1/pagos
+**Propósito:** Crear un cobro
+**Auth:** Bearer token (JWT)
+**Rate limit:** 100 req/min por usuario
+**Idempotencia:** Sí (header `Idempotency-Key`)
+
+**Request:**
+```json
+{
+  "monto": 5000,          // centavos, min: 100, max: 99999900
+  "moneda": "USD",        // ISO 4217
+  "cliente_id": "uuid",
+  "metodo_pago_id": "pm_xxx",
+  "descripcion": "Pedido #1234",
+  "metadata": {}          // opcional, max 50 keys
+}
+```
+
+**Responses:**
+| Status | Significado | Body |
+|--------|------------|------|
+| 201 | Cobro creado | `{ id, status, monto, stripe_id, created_at }` |
+| 400 | Datos inválidos | `{ error, field, message }` |
+| 402 | Pago rechazado | `{ error, decline_code, message }` |
+| 409 | Idempotency conflict | `{ error, original_id }` |
+| 429 | Rate limit | `{ error, retry_after }` |
+| 500 | Error interno | `{ error, request_id }` |
+
+**Headers de respuesta:**
+```
+X-Request-Id: uuid          // Para soporte/debugging
+X-RateLimit-Remaining: 95
+X-RateLimit-Reset: 1616544000
+```
+
+### Webhooks (recibir desde Stripe)
+
+#### POST /api/v1/webhooks/stripe
+**Verificación:** HMAC-SHA256 con `Stripe-Signature` header
+**Tolerancia de timestamp:** 300 segundos (5 min)
+**Respuesta esperada:** 200 OK (body vacío) en < 5s
+
+**Eventos soportados:**
+| Evento | Acción | Idempotente |
+|--------|--------|-------------|
+| `payment_intent.succeeded` | Marcar pedido como pagado | Sí |
+| `payment_intent.payment_failed` | Notificar al usuario | Sí |
+| `charge.refunded` | Procesar reembolso | Sí |
+| `charge.dispute.created` | Alertar al equipo | Sí |
+
+**Procesamiento:**
+```
+1. Verificar firma HMAC
+2. Parsear evento
+3. Verificar idempotencia (event.id en tabla processed_events)
+4. Responder 200 INMEDIATAMENTE
+5. Procesar en cola async (no bloquear respuesta)
+6. Registrar en audit log
+```
+
+### Manejo de Errores
+
+**Errores del cliente (4xx):**
+```json
+{
+  "error": {
+    "tipo": "validation_error",
+    "mensaje": "El monto debe ser mayor a $1.00",
+    "campo": "monto",
+    "codigo": "MONTO_INVALIDO"
+  }
+}
+```
+
+**Errores del servidor (5xx):**
+```json
+{
+  "error": {
+    "tipo": "internal_error",
+    "mensaje": "Error procesando el pago",
+    "request_id": "req_abc123"
+  }
+}
+```
+
+**Códigos de error consistentes:**
+| Código | Significado | HTTP |
+|--------|------------|------|
+| `MONTO_INVALIDO` | Monto fuera de rango | 400 |
+| `MONEDA_NO_SOPORTADA` | Moneda no en whitelist | 400 |
+| `PAGO_RECHAZADO` | Tarjeta rechazada | 402 |
+| `DUPLICADO` | Idempotency conflict | 409 |
+| `RATE_LIMIT` | Demasiadas requests | 429 |
+| `STRIPE_ERROR` | Error de comunicación con Stripe | 502 |
+
+### Política de Reintentos
+
+```
+Estrategia: Exponential backoff con jitter
+
+Intento 1: inmediato
+Intento 2: 1s + jitter (0-500ms)
+Intento 3: 2s + jitter (0-1000ms)
+Intento 4: 4s + jitter (0-2000ms)
+Max intentos: 4
+
+Reintentar en:
+  ✅ 429 (rate limit) — respetar Retry-After header
+  ✅ 500, 502, 503, 504 (errores transitorios)
+  ❌ 400, 401, 402, 403, 404, 409 (errores definitivos)
+
+Circuit breaker:
+  - Abrir después de 5 fallos consecutivos
+  - Half-open después de 30 segundos
+  - Cerrar después de 2 éxitos consecutivos
+```
+
+### Timeouts
+
+| Operación | Timeout | Acción si timeout |
+|-----------|---------|-------------------|
+| Crear cobro | 10s | Reintentar (idempotente) |
+| Verificar webhook | 2s | Rechazar (400) |
+| Procesar evento async | 30s | Cola de dead-letter |
+```
+
+## Output para GraphQL
+
+```markdown
+### Schema GraphQL
+
+```graphql
+type Mutation {
+  crearPago(input: CrearPagoInput!): PagoResult!
+  reembolsar(pagoId: ID!, monto: Int): ReembolsoResult!
+}
+
+type Query {
+  pago(id: ID!): Pago
+  pagos(filtro: PagoFiltro, paginacion: Paginacion): PagoConnection!
+}
+
+input CrearPagoInput {
+  monto: Int!          # centavos
+  moneda: Moneda!
+  clienteId: ID!
+  metodoPagoId: String!
+  descripcion: String
+}
+
+type PagoResult {
+  pago: Pago
+  error: APIError
+}
+```
+```
+
+## Almacenamiento
+
+```
+specs/api/
+├── openapi.yaml            # Spec completa (auto-generada)
+├── contratos/
+│   ├── pagos.contrato.md   # Contrato de pagos
+│   ├── webhooks.contrato.md
+│   └── catalogo.contrato.md
+└── postman/
+    └── coleccion.json      # Colección Postman exportada
+```
+
+## Integración con Pipeline
+
+```
+/especdev:contrato-api → contrato + OpenAPI parcial
+  → /especdev:planificar-tecnico → incorpora contrato al plan
+  → /especdev:desglosar → tareas incluyen implementación del contrato
+  → Documentación Viva → actualiza OpenAPI global
+```
+
+## Guardrails
+
+- **Nunca** diseñar API sin definir manejo de errores
+- **Nunca** omitir idempotencia en operaciones de escritura
+- **Nunca** confiar en input externo sin validación
+- **Siempre** definir timeouts y política de reintentos
+- **Siempre** incluir `request_id` en respuestas de error
+- **Siempre** verificar firma de webhooks antes de procesar
+- **Siempre** responder rápido a webhooks (< 5s), procesar async

package/comandos/especdev/contrato-ui.md

@@ -0,0 +1,245 @@
+---
+description: Bloquear estándares visuales antes de codear frontend (UI Design Contract)
+i18n: true
+---
+
+# /especdev:contrato-ui
+
+## Objetivo
+
+Definir y bloquear los estándares visuales de una feature frontend **antes** de escribir código. Previene el problema más común del desarrollo frontend con IA: inconsistencia visual entre componentes porque no hay un contrato de diseño.
+
+> Adaptado de Get Shit Done (gsd-build/get-shit-done) — UI Design Contracts: "lock visual standards before coding to prevent visually inconsistent AI-generated components."
+
+## Uso
+
+```
+/especdev:contrato-ui                          # Crear contrato para el proyecto
+/especdev:contrato-ui @specs/features/ui/      # Crear para un módulo específico
+/especdev:contrato-ui --desde @figma-export    # Derivar de un export de Figma
+/especdev:contrato-ui --extender               # Extender contrato existente
+```
+
+## Por Qué Existe
+
+| Sin Contrato UI | Con Contrato UI |
+|-----------------|-----------------|
+| Componente A usa `padding: 16px`, B usa `padding: 1rem`, C usa `padding: 20px` | Todos usan `--spacing-md: 1rem` |
+| Cada componente elige sus propios colores | Paleta definida, tokens de diseño |
+| Tipografía inconsistente entre páginas | Escala tipográfica fija |
+| Copywriting variable ("Click here" vs "Continuar" vs "Submit") | Voz y tono definidos |
+| IA genera componentes "bonitos" pero incompatibles entre sí | Todos los componentes siguen el mismo contrato |
+
+## Comportamiento
+
+### Paso 1: Detectar Stack Frontend
+
+```
+Detectando stack frontend...
+├── Framework: React 19 / Next.js 15
+├── Estilos: TailwindCSS 4.x
+├── Componentes: shadcn/ui
+├── Iconos: Lucide Icons
+└── Design system existente: No detectado
+```
+
+### Paso 2: Definir Contrato
+
+El contrato cubre 6 dimensiones:
+
+#### 1. Espaciado (Spacing)
+
+```yaml
+spacing:
+  base: 4px  # Unidad mínima
+  scale:
+    xs: 4px    # 1 unidad
+    sm: 8px    # 2 unidades
+    md: 16px   # 4 unidades (default)
+    lg: 24px   # 6 unidades
+    xl: 32px   # 8 unidades
+    2xl: 48px  # 12 unidades
+  regla: "Todo espaciado DEBE ser múltiplo de 4px"
+```
+
+#### 2. Tipografía (Typography)
+
+```yaml
+typography:
+  familia:
+    primaria: "Inter, system-ui, sans-serif"
+    monospace: "JetBrains Mono, monospace"
+  escala:
+    xs: "0.75rem / 1rem"     # 12px, captions
+    sm: "0.875rem / 1.25rem"  # 14px, labels
+    base: "1rem / 1.5rem"     # 16px, body
+    lg: "1.125rem / 1.75rem"  # 18px, lead
+    xl: "1.25rem / 1.75rem"   # 20px, h4
+    2xl: "1.5rem / 2rem"      # 24px, h3
+    3xl: "1.875rem / 2.25rem" # 30px, h2
+    4xl: "2.25rem / 2.5rem"   # 36px, h1
+  peso:
+    normal: 400
+    medium: 500
+    semibold: 600
+    bold: 700
+```
+
+#### 3. Color (Palette)
+
+```yaml
+color:
+  brand:
+    primary: "#2563EB"      # Acciones principales
+    primary-hover: "#1D4ED8"
+    secondary: "#64748B"     # Acciones secundarias
+  semantic:
+    success: "#16A34A"
+    warning: "#D97706"
+    error: "#DC2626"
+    info: "#2563EB"
+  neutral:
+    background: "#FFFFFF"
+    surface: "#F8FAFC"
+    border: "#E2E8F0"
+    text-primary: "#0F172A"
+    text-secondary: "#64748B"
+    text-muted: "#94A3B8"
+  modo_oscuro: true  # Si aplica, definir variantes
+```
+
+#### 4. Componentes (Patterns)
+
+```yaml
+componentes:
+  botones:
+    primario: "bg-primary text-white rounded-md px-4 py-2 font-medium"
+    secundario: "bg-white border border-border text-secondary rounded-md px-4 py-2"
+    destructivo: "bg-error text-white rounded-md px-4 py-2"
+    fantasma: "text-secondary hover:bg-surface rounded-md px-4 py-2"
+    tamanos: [sm, md, lg]
+  inputs:
+    estilo: "border rounded-md px-3 py-2 focus:ring-2 focus:ring-primary"
+    error: "border-error focus:ring-error"
+    label: "text-sm font-medium text-text-primary mb-1"
+  cards:
+    estilo: "bg-white border rounded-lg p-6 shadow-sm"
+  modales:
+    overlay: "bg-black/50 backdrop-blur-sm"
+    contenido: "bg-white rounded-xl shadow-xl max-w-md mx-auto p-6"
+```
+
+#### 5. Layout
+
+```yaml
+layout:
+  contenedor: "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8"
+  grid: "12 columnas"
+  breakpoints:
+    sm: "640px"
+    md: "768px"
+    lg: "1024px"
+    xl: "1280px"
+  sidebar: "w-64 fixed"
+  navbar: "h-16 fixed top-0"
+```
+
+#### 6. Voz y Tono (Copywriting)
+
+```yaml
+copywriting:
+  idioma_ui: "es"  # Del config.yaml
+  voz: "Profesional pero cercano"
+  reglas:
+    - "Usar 'tú' (no 'usted') para el usuario"
+    - "Botones: verbos en infinitivo ('Crear', 'Guardar', 'Cancelar')"
+    - "Errores: explicar qué pasó Y qué hacer ('El email ya existe. Intenta con otro.')"
+    - "Éxito: confirmar la acción completada ('Usuario creado exitosamente')"
+    - "Vacíos: guiar al usuario ('Aún no tienes proyectos. Crea el primero.')"
+  prohibido:
+    - "Click here / Haga clic aquí"
+    - "Error genérico sin contexto"
+    - "Jerga técnica en mensajes al usuario"
+```
+
+### Paso 3: Generar Artefacto
+
+```
+Contrato UI generado:
+  → specs/ui/contrato-ui.yaml (contrato completo)
+  → specs/ui/tokens.css (custom properties generadas)
+```
+
+## Output
+
+### Archivo de Contrato (`specs/ui/contrato-ui.yaml`)
+
+YAML completo con las 6 dimensiones definidas arriba.
+
+### Tokens CSS generados (`specs/ui/tokens.css`)
+
+```css
+:root {
+  /* Spacing */
+  --spacing-xs: 4px;
+  --spacing-sm: 8px;
+  --spacing-md: 16px;
+  --spacing-lg: 24px;
+  --spacing-xl: 32px;
+
+  /* Colors */
+  --color-primary: #2563EB;
+  --color-primary-hover: #1D4ED8;
+  --color-success: #16A34A;
+  --color-error: #DC2626;
+  --color-text-primary: #0F172A;
+  --color-text-secondary: #64748B;
+  --color-border: #E2E8F0;
+  --color-surface: #F8FAFC;
+
+  /* Typography */
+  --font-primary: 'Inter', system-ui, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+}
+```
+
+## Integración con Pipeline
+
+```
+/especdev:contrato-ui → contrato-ui.yaml + tokens.css
+  → /especdev:especificar → escenarios referencian tokens
+  → /especdev:planificar-tecnico → plan incluye contrato como dependencia
+  → /especdev:implementar → agente usa tokens, NO inventa estilos
+  → /especdev:revisar → verifica cumplimiento del contrato
+```
+
+## Verificación de Cumplimiento
+
+Durante `/especdev:revisar`, se verifica:
+
+| Verificación | Criterio | Severidad |
+|--------------|----------|-----------|
+| Colores | Solo usa colores del contrato | ❌ Crítico |
+| Espaciado | Múltiplos de la base (4px) | ⚠️ Alto |
+| Tipografía | Solo usa escala definida | ⚠️ Alto |
+| Copywriting | Sigue reglas de voz y tono | ℹ️ Info |
+| Componentes | Usa patterns definidos | ⚠️ Alto |
+| Responsive | Respeta breakpoints | ⚠️ Alto |
+
+## Cuándo Usar
+
+| Situación | Usar contrato |
+|-----------|--------------|
+| Feature con UI nueva | ✅ Sí |
+| Modificación de UI existente | ✅ Sí (extender contrato existente) |
+| API/backend sin UI | ❌ No |
+| Fix de bug visual | ❌ No (contrato ya existe) |
+| Prototipo/POC | ⚠️ Opcional (contrato mínimo) |
+
+## Guardrails
+
+- **Nunca** generar componentes frontend sin contrato UI vigente
+- **Nunca** usar valores hardcoded de color/spacing en código (usar tokens)
+- **Siempre** verificar cumplimiento del contrato en revisión
+- **Siempre** extender (no reemplazar) el contrato cuando se agregan patrones
+- **Siempre** generar tokens CSS/variables junto al contrato