don-cheli-sdd 1.13.0

package/comandos/especdev/migrar.md

@@ -0,0 +1,237 @@
+---
+description: Planificar y ejecutar migración entre stacks tecnológicos o versiones mayores
+i18n: true
+---
+
+# /especdev:migrar
+
+## Objetivo
+
+Planificar y ejecutar migraciones de stacks tecnológicos (Vue→React, Express→Fastify) o actualizaciones de versiones mayores (Next.js 14→15, Python 3.9→3.12), minimizando riesgo de regresión.
+
+## Uso
+
+```
+/especdev:migrar --de "Vue 3" --a "React 19"
+/especdev:migrar --de "Express 4" --a "Fastify 5"
+/especdev:migrar --de "Next.js 14" --a "Next.js 15"
+/especdev:migrar --de "Python 3.9" --a "Python 3.12"
+/especdev:migrar --de "REST" --a "GraphQL"
+/especdev:migrar --de "JavaScript" --a "TypeScript"
+/especdev:migrar --solo-plan                          # Solo generar plan, no ejecutar
+```
+
+## Tipos de Migración
+
+| Tipo | Ejemplo | Riesgo | Enfoque |
+|------|---------|--------|---------|
+| **Framework** | Vue→React, Django→FastAPI | Alto | Rewrite incremental |
+| **Versión mayor** | Next 14→15, Angular 17→19 | Medio | Upgrade guiado por changelog |
+| **Lenguaje** | JS→TS, Python 2→3 | Alto | Codemods + revisión manual |
+| **Paradigma** | REST→GraphQL, Monolito→Micro | Muy alto | Strangler Fig pattern |
+| **Base de datos** | MySQL→PostgreSQL, Mongo→PG | Alto | Dual-write + migración |
+
+## Proceso (6 fases)
+
+### Fase 1: Inventario (automático)
+
+Mapear el estado actual del proyecto:
+
+```markdown
+## Inventario de Migración: Vue 3 → React 19
+
+### Stack Actual
+- Framework: Vue 3.4 + Composition API
+- Estado: Pinia 2.1
+- Router: vue-router 4.3
+- UI: Vuetify 3
+- Build: Vite 5
+- Tests: Vitest + Vue Test Utils
+
+### Alcance
+- Componentes: 47
+- Stores: 8
+- Rutas: 23
+- Tests: 112
+- LOC: 12,400
+
+### Dependencias Vue-Específicas
+| Dependencia | Alternativa React | Complejidad |
+|-------------|-------------------|-------------|
+| Pinia | Zustand / Redux Toolkit | Baja |
+| vue-router | React Router v7 | Media |
+| Vuetify | shadcn/ui + TailwindCSS | Alta |
+| Vue Test Utils | React Testing Library | Media |
+| Composables (12) | Custom hooks | Baja |
+```
+
+### Fase 2: Mapa de Equivalencias
+
+Traducir conceptos entre ecosistemas:
+
+```markdown
+## Equivalencias Vue → React
+
+| Vue | React | Notas |
+|-----|-------|-------|
+| `<template>` | JSX | Diferente sintaxis, misma función |
+| `ref()` / `reactive()` | `useState()` | Reactividad automática vs explícita |
+| `computed()` | `useMemo()` | Semántica similar |
+| `watch()` / `watchEffect()` | `useEffect()` | Cuidado con el array de deps |
+| `onMounted()` | `useEffect(() => {}, [])` | Lifecycle → effects |
+| `provide/inject` | `Context API` | Para estado compartido profundo |
+| `v-if` / `v-for` | `{condition && ...}` / `.map()` | JSX condicional |
+| `v-model` | `value` + `onChange` | Two-way vs one-way binding |
+| Pinia store | Zustand store | API muy similar |
+| `<slot>` | `children` / `render props` | Composición de componentes |
+| Directive (`v-tooltip`) | HOC o hook | Sin equivalente directo |
+| `<Transition>` | `framer-motion` | Animaciones |
+```
+
+### Fase 3: Estrategia de Migración
+
+Elegir enfoque según riesgo:
+
+#### Opción A: Big Bang (riesgo alto, rápido)
+```
+Reescribir todo de una vez.
+✅ Para: proyectos pequeños (< 20 componentes)
+❌ No para: proyectos en producción con usuarios activos
+```
+
+#### Opción B: Strangler Fig (riesgo bajo, gradual) ← Recomendado
+```
+Migrar componente por componente, coexistiendo ambos frameworks.
+
+Fase 1: Setup React junto a Vue (micro-frontend o iframe)
+Fase 2: Migrar componentes leaf (sin hijos Vue)
+Fase 3: Migrar componentes intermedios
+Fase 4: Migrar componentes root
+Fase 5: Remover Vue
+```
+
+#### Opción C: Parallel Run (riesgo medio)
+```
+Construir la versión React en paralelo, switchear cuando esté lista.
+✅ Para: aplicaciones críticas que no pueden tener downtime
+❌ Costoso en tiempo (mantener dos codebases)
+```
+
+### Fase 4: Plan de Migración
+
+Genera `.especdev/migracion/plan-migracion.md`:
+
+```markdown
+## Plan de Migración: Vue → React
+
+### Orden de Migración (por dependencias)
+
+#### Wave 1: Infraestructura (sin UI)
+- [ ] M001: Setup React + Vite + TypeScript
+- [ ] M002: Configurar React Router (mapear rutas existentes)
+- [ ] M003: Configurar Zustand (mapear stores Pinia)
+- [ ] M004: Setup React Testing Library
+
+#### Wave 2: Componentes Atómicos (sin dependencias internas)
+- [ ] M005: Migrar Button, Input, Modal (Vuetify → shadcn/ui)
+- [ ] M006: Migrar layout components (Header, Sidebar, Footer)
+- [ ] M007: Tests para componentes migrados
+
+#### Wave 3: Componentes con Estado
+- [ ] M008: Migrar stores Pinia → Zustand (uno por uno)
+- [ ] M009: Migrar composables → custom hooks
+- [ ] M010: Migrar formularios con validación
+
+#### Wave 4: Páginas y Rutas
+- [ ] M011: Migrar páginas leaf (sin sub-rutas)
+- [ ] M012: Migrar páginas con sub-rutas
+- [ ] M013: Migrar guards de ruta → loader/middleware
+
+#### Wave 5: Cleanup
+- [ ] M014: Remover dependencias Vue
+- [ ] M015: Actualizar CI/CD
+- [ ] M016: Actualizar documentación
+
+### Tests de Regresión por Wave
+Cada wave ejecuta:
+1. Tests unitarios de componentes migrados
+2. Tests de integración de rutas migradas
+3. Tests end-to-end del flujo completo
+4. Comparación visual (screenshot diff) si aplica
+```
+
+### Fase 5: Ejecución
+
+Cada tarea de migración sigue el ciclo:
+
+```
+1. Leer componente/módulo Vue
+2. Mapear a equivalencia React
+3. Escribir test React (RED)
+4. Implementar componente React (GREEN)
+5. Verificar paridad funcional
+6. Commit atómico: "migrate: ComponentName Vue→React"
+```
+
+### Fase 6: Verificación Post-Migración
+
+```markdown
+## Checklist Post-Migración
+
+### Funcionalidad
+- [ ] Todas las rutas funcionan
+- [ ] Formularios envían datos correctamente
+- [ ] Estado se persiste entre navegaciones
+- [ ] Auth flow completo funciona
+
+### Rendimiento
+- [ ] Bundle size ≤ original (o justificar)
+- [ ] LCP ≤ original
+- [ ] No memory leaks en SPA navigation
+
+### Calidad
+- [ ] Coverage de tests ≥ original
+- [ ] 0 dependencias Vue restantes
+- [ ] Sin TODOs de migración pendientes
+- [ ] CI/CD actualizado y pasando
+```
+
+## Formato de Commits de Migración
+
+```
+migrate: <componente/módulo> <origen>→<destino>
+migrate: Button component Vue→React
+migrate: auth store Pinia→Zustand
+migrate: /dashboard route vue-router→react-router
+```
+
+## Almacenamiento
+
+```
+.especdev/migracion/
+├── inventario.md          # Estado actual del proyecto
+├── equivalencias.md       # Mapa de traducciones
+├── plan-migracion.md      # Plan con waves y tareas
+├── progreso-migracion.md  # Tracking de avance
+└── post-migracion.md      # Checklist de verificación
+```
+
+## Integración con Pipeline
+
+```
+/especdev:migrar → inventario + equivalencias + plan
+  → /especdev:poc (opcional) → validar enfoque en módulo piloto
+  → /especdev:implementar → ejecutar por waves
+  → /especdev:auditar-seguridad → verificar que migración no introduce vulnerabilidades
+  → /especdev:revisar → review final
+```
+
+## Guardrails
+
+- **Nunca** migrar sin tests de regresión del sistema original
+- **Nunca** migrar todo de una vez en proyectos en producción (usar Strangler Fig)
+- **Siempre** mantener paridad funcional (no agregar features durante migración)
+- **Siempre** commit atómico por componente/módulo migrado
+- **Siempre** verificar rendimiento post-migración (bundle size, LCP)
+- **Siempre** ejecutar tests e2e del flujo completo después de cada wave
+- Si la migración afecta > 30% del codebase → confirmar con usuario antes de cada wave

package/comandos/especdev/minar-referencias.md

@@ -0,0 +1,214 @@
+---
+description: Buscar repos open-source relevantes como referencia antes de implementar
+i18n: true
+---
+
+# /especdev:minar-referencias
+
+## Objetivo
+
+Buscar y evaluar repositorios open-source, snippets y patrones de referencia relevantes para la tarea actual. Reduce el "empezar de cero" proporcionando implementaciones probadas como guía.
+
+> Adaptado de DeepCode (HKUDS/DeepCode) — Code Reference Mining Agent: "descubrir repositorios relevantes y construir knowledge graphs para informar la generación de código."
+
+## Uso
+
+```
+/especdev:minar-referencias "webhook handler con verificación de firma"
+/especdev:minar-referencias "rate limiter con sliding window"
+/especdev:minar-referencias --stack node,typescript "auth con JWT refresh"
+/especdev:minar-referencias --max 5 "graphql subscriptions"
+```
+
+## Por Qué Existe
+
+| Sin Minar | Con Minar |
+|-----------|-----------|
+| Implementar desde cero | Partir de patrones probados |
+| Descubrir anti-patrones tarde | Conocer pitfalls de antemano |
+| Reinventar soluciones comunes | Reutilizar lo que funciona |
+| Estimaciones imprecisas | Complejidad real visible |
+
+## Comportamiento
+
+### Paso 1: Análisis de la Query
+
+```
+Query: "webhook handler con verificación de firma"
+├── Conceptos clave: webhook, handler, signature verification
+├── Stack detectado: Node.js + TypeScript (de config.yaml)
+├── Dominio: API integration, security
+└── Complejidad estimada: Media
+```
+
+### Paso 2: Búsqueda Multi-Fuente
+
+El comando busca en múltiples fuentes (según disponibilidad):
+
+| Fuente | Método | Qué Busca |
+|--------|--------|-----------|
+| **GitHub** | API search / web search | Repos con implementaciones similares |
+| **Proyecto actual** | Grep local | Código existente reutilizable |
+| **CodeRAG** | Índice local | Patrones ya indexados |
+| **Memoria** | Engram | Decisiones previas sobre el tema |
+
+### Paso 3: Evaluación de Relevancia
+
+Cada resultado se evalúa en 4 dimensiones:
+
+| Dimensión | Peso | Criterio |
+|-----------|------|----------|
+| **Relevancia** | 40% | ¿Resuelve el mismo problema? |
+| **Calidad** | 25% | Stars, mantenimiento, tests, docs |
+| **Compatibilidad** | 20% | ¿Mismo stack/framework? |
+| **Simplicidad** | 15% | ¿Es adoptable sin refactor mayor? |
+
+Score = suma ponderada (0.0 - 1.0)
+
+### Paso 4: Extracción de Patrones
+
+De los top resultados, se extraen:
+
+```
+1. Patrón arquitectónico usado
+2. Dependencias clave
+3. Manejo de errores
+4. Edge cases cubiertos
+5. Snippet representativo (≤ 30 líneas)
+```
+
+## Output
+
+```markdown
+## Referencias Minadas: "webhook handler con verificación de firma"
+
+Fecha: 2026-03-21 | Stack: Node.js + TypeScript | Resultados: 3
+
+---
+
+### 1. stripe/stripe-node — Webhook Verification (score: 0.91)
+**Repo:** github.com/stripe/stripe-node
+**Archivo:** src/Webhooks.ts
+**Por qué es relevante:** Implementación de referencia de Stripe para verificar firmas HMAC-SHA256.
+
+**Patrón:**
+- Verificar firma antes de procesar
+- Tolerancia de timestamp (5 min por defecto)
+- Comparación timing-safe para prevenir timing attacks
+
+**Snippet:**
+```typescript
+function verifySignature(payload: string, header: string, secret: string): boolean {
+  const timestamp = extractTimestamp(header);
+  const signature = extractSignature(header);
+
+  if (Date.now() / 1000 - timestamp > TOLERANCE) {
+    throw new WebhookSignatureError('Timestamp too old');
+  }
+
+  const expected = crypto
+    .createHmac('sha256', secret)
+    .update(`${timestamp}.${payload}`)
+    .digest('hex');
+
+  return crypto.timingSafeEqual(
+    Buffer.from(signature),
+    Buffer.from(expected)
+  );
+}
+```
+
+**Lecciones:**
+- Usar `timingSafeEqual` (no `===`) para comparar firmas
+- Validar timestamp para prevenir replay attacks
+- Lanzar error específico (no genérico)
+
+---
+
+### 2. svix/svix-webhooks — Webhook Handler Pattern (score: 0.84)
+**Repo:** github.com/svix/svix-webhooks
+**Por qué es relevante:** SDK de webhooks con patrón de handler idempotente.
+
+**Patrón:**
+- Idempotency key en header
+- Queue para procesamiento async
+- Retry automático con backoff
+
+**Lecciones:**
+- Separar verificación de procesamiento
+- Idempotencia es obligatoria para webhooks
+- Responder 200 antes de procesar (async)
+
+---
+
+### 3. [Proyecto actual] src/utils/crypto.ts (score: 0.72)
+**Archivo:** src/utils/crypto.ts:15-30
+**Por qué es relevante:** Ya existe un helper de HMAC en el proyecto.
+
+**Nota:** Reutilizar `createHmacSignature()` existente en vez de reimplementar.
+
+---
+
+## Resumen de Decisiones
+
+| Decisión | Recomendación | Fuente |
+|----------|--------------|--------|
+| Verificación de firma | HMAC-SHA256 + timestamp | stripe/stripe-node |
+| Comparación de firma | `timingSafeEqual` | stripe/stripe-node |
+| Procesamiento | Async (queue) + responder 200 | svix/svix-webhooks |
+| Helper de HMAC | Reutilizar existente | Proyecto actual |
+| Idempotencia | Idempotency key en header | svix/svix-webhooks |
+
+## Próximo Paso
+→ `/especdev:especificar` usando estas referencias como base
+→ O `/especdev:planificar-tecnico` para incorporar los patrones al blueprint
+```
+
+## Integración con Pipeline
+
+```
+/especdev:minar-referencias → referencias
+  → /especdev:especificar → specs informadas
+  → /especdev:planificar-tecnico → plan con patrones reales
+  → CodeRAG → indexar patrones útiles para futuro
+
+/especdev:minar-referencias → referencias
+  → /especdev:estimar → estimados más precisos (complejidad real)
+```
+
+## Integración con CodeRAG
+
+Los patrones encontrados se pueden indexar automáticamente:
+
+```
+¿Indexar los patrones encontrados en CodeRAG? (s/n)
+> s
+Indexados 3 patrones en .especdev/code-rag/patterns.json
+```
+
+## Almacenamiento
+
+```
+.especdev/referencias/
+├── webhook-handler-2026-03-21.md    # Resultado de esta búsqueda
+├── rate-limiter-2026-03-15.md       # Búsqueda anterior
+└── _index.md                        # Índice de búsquedas
+```
+
+## Modelo Recomendado
+
+| Paso | Modelo | Razón |
+|------|--------|-------|
+| Búsqueda | Haiku | Solo buscar y filtrar |
+| Evaluación de relevancia | Haiku | Scoring simple |
+| Extracción de patrones | Sonnet | Requiere comprensión de código |
+| Resumen de decisiones | Haiku | Formateo |
+
+## Guardrails
+
+- **Nunca** copiar código con licencias incompatibles sin verificar
+- **Nunca** incluir credenciales o tokens de repos de referencia
+- **Siempre** priorizar código existente en el proyecto sobre externo
+- **Siempre** indicar la fuente y licencia de cada referencia
+- **Siempre** limitar snippets a ≤30 líneas (respetar fair use)
+- **Máximo** 5 referencias por búsqueda (evitar analysis paralysis)

package/comandos/especdev/planificar-tecnico.md

@@ -0,0 +1,186 @@
+---
+description: Generar blueprint técnico desde una especificación Gherkin
+i18n: true
+---
+
+# /especdev:planificar-tecnico
+
+## Objetivo
+
+Generar un blueprint técnico (contratos API, modelos, arquitectura de servicios) desde una especificación Gherkin, incluyendo verificación de constitución y contexto técnico estructurado.
+
+> Alineado con spec-kit (github/spec-kit) — Constitution Check, Technical Context y Complexity Tracking
+
+## Uso
+
+```
+/especdev:planificar-tecnico @specs/features/<dominio>/<Feature>.feature
+```
+
+## Comportamiento
+
+1. **Verificar Puerta 2** — El `.feature` debe tener tag `@lista` (pasó `/especdev:clarificar`)
+2. **Verificar** que no hay marcadores `[NECESITA CLARIFICACIÓN]` pendientes
+3. **Ejecutar Chequeo de Constitución** — Validar contra los principios de `reglas/constitucion.md`
+4. **Documentar Contexto Técnico** — Stack, dependencias, restricciones
+5. **Ratificar DBML** — Convertir campos `@provisional` a ratificados
+6. **Generar** contratos API, modelos, arquitectura de servicios
+7. **Registrar Complejidad** — Justificar desviaciones de simplicidad
+8. **Crear** archivo `.plan.md` en `specs/features/<dominio>/`
+
+## Output
+
+Genera `specs/features/<dominio>/<Feature>.plan.md`:
+
+```markdown
+# Blueprint Técnico: CrearUsuario
+
+**Rama:** feature/crear-usuario
+**Spec:** specs/features/usuario/CrearUsuario.feature
+**Fecha:** 2026-03-21
+**Estado:** Borrador
+
+---
+
+## Resumen
+
+Implementar registro de usuarios con email/contraseña, incluyendo
+validación, hashing de contraseña y generación de JWT.
+Enfoque técnico: API REST con patrón Controller → Service → Repository.
+
+---
+
+## Chequeo de Constitución
+
+Verificación obligatoria contra `reglas/constitucion.md`:
+
+| Artículo | Principio | Estado | Notas |
+|----------|-----------|--------|-------|
+| I | Gherkin es Rey | ✅ | Spec @lista aprobada |
+| I-B | Schema como Verdad Viva | ✅ | DBML ratificado |
+| II | Precisión Quirúrgica | ✅ | Cambio mínimo, 1 feature |
+| III | Arquitectura Plug-and-Play | ✅ | Nuevo módulo, no infla existentes |
+| IV | Regla Las Vegas | ✅ | Tests herméticos planificados |
+| IV-B | Punto de Entrada | ✅ | Validación en Controller |
+| V | Estándares Modernos | ✅ | Type hints + Pydantic/Zod |
+| VI | Adaptabilidad | ✅ | Stack detectado: FastAPI |
+| VII | Codificación Defensiva | ✅ | Excepciones custom planificadas |
+
+**Resultado: ✅ PASA** — El plan es compatible con la constitución.
+
+---
+
+## Contexto Técnico
+
+| Aspecto | Valor |
+|---------|-------|
+| **Lenguaje** | Python 3.12 / TypeScript 5.x |
+| **Framework** | FastAPI 0.115 / Next.js 15 |
+| **Dependencias** | bcryptjs, python-jose, pydantic |
+| **Almacenamiento** | PostgreSQL 16 + Prisma/SQLAlchemy |
+| **Testing** | pytest + pytest-asyncio / vitest |
+| **Plataforma** | Docker + Linux |
+| **Rendimiento** | < 500ms p95 (de criterios de éxito) |
+| **Escala** | ~1,000 registros/día (estimado) |
+| **Restricciones** | Sin OAuth en v1 (definido en clarificación) |
+
+---
+
+## Contrato API
+
+POST /api/v1/usuarios
+Content-Type: application/json
+
+Request:
+{
+  "email": "string (required, email format)",
+  "password": "string (required, min 8 chars)",
+  "nombre": "string (required, max 100 chars)"
+}
+
+Response 201:
+{
+  "id": "uuid",
+  "email": "string",
+  "nombre": "string",
+  "token": "jwt-string",
+  "createdAt": "datetime"
+}
+
+Response 400:
+{
+  "error": "string",
+  "field": "string (optional)"
+}
+
+Response 409:
+{
+  "error": "El email ya está registrado"
+}
+
+---
+
+## Modelo de Datos
+
+Usuario (ratificado desde DBML):
+  - id: UUID (PK, auto-gen)
+  - email: String (unique, indexed, NOT NULL)
+  - password_hash: String (NOT NULL)
+  - nombre: String (max 100, NOT NULL)
+  - created_at: DateTime (default: now())
+
+---
+
+## Arquitectura de Servicios
+
+Controller → Service → Repository → Database
+                 ↓
+           EmailService (async)
+
+---
+
+## Dependencias
+
+- bcryptjs (hash de contraseña)
+- python-jose / jsonwebtoken (generación JWT)
+- pydantic / zod (validación de DTOs)
+
+---
+
+## Tracking de Complejidad
+
+Justificar cualquier decisión que añade complejidad por encima de la alternativa más simple:
+
+| Decisión | Alternativa Simple | Por Qué Se Rechazó |
+|----------|--------------------|---------------------|
+| JWT con refresh token | Solo JWT simple | Requerimiento de seguridad: tokens de corta duración |
+| Email async con cola | Email síncrono | Bloquea respuesta al usuario, riesgo de timeout |
+| Repository pattern | Queries directas | Testabilidad: inyección de dependencias para mocks |
+
+Si la tabla está vacía, no hay desviaciones de simplicidad.
+```
+
+## Secciones Obligatorias del Plan
+
+| Sección | Propósito | Falla si falta |
+|---------|-----------|----------------|
+| **Resumen** | Qué y cómo en 2-3 líneas | Sí |
+| **Chequeo de Constitución** | Validar contra principios | Sí |
+| **Contexto Técnico** | Stack y restricciones | Sí |
+| **Contrato API** | Interfaces públicas | Sí (si hay API) |
+| **Modelo de Datos** | Entidades y relaciones | Sí (si hay datos) |
+| **Arquitectura** | Componentes y flujo | Sí |
+| **Dependencias** | Librerías externas | Sí |
+| **Tracking de Complejidad** | Justificar desviaciones | Sí (puede estar vacía) |
+
+## Puerta de Calidad
+
+Este comando implementa la **Puerta 4 (Aprobación de Plan)**:
+
+- Chequeo de constitución pasa (todos ✅)
+- Sin `[NECESITA CLARIFICACIÓN]` pendiente
+- Contexto técnico completo
+- DBML ratificado (sin campos `@provisional`)
+- Tracking de complejidad documentado
+
+Si algún artículo de la constitución no pasa → **NO-AVANZAR** hasta resolver.