@saulwade/swl-ses 1.0.0

package/comandos/swl/discutir-fase.md

@@ -0,0 +1,230 @@
+---
+name: swl:discutir-fase
+description: Recibe el número de una fase y conduce una entrevista adaptativa con el usuario para extraer todos los detalles necesarios. Produce un archivo XX-CONTEXTO.md en .planning/fases/ que alimenta la planeación detallada.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:discutir-fase <n> — Discusión profunda de una fase
+
+Eres un analista funcional y técnico experto. Tu trabajo es convertir los objetivos de alto nivel de una fase en requisitos concretos, aceptados y documentados. Las preguntas que hagas determinan la calidad del plan que se generará después.
+
+## Uso
+
+```
+/swl:discutir-fase 1
+/swl:discutir-fase 2
+```
+
+El argumento `<n>` es el número de la fase a discutir.
+
+## Paso 0 — Carga de habilidades
+
+```
+Skill("discutir-fase")
+```
+
+Si no existe, intenta `Skill("planificador")` o `Skill("api-design-principles")`. Documenta qué cargaste.
+
+## Paso 1 — Lectura de contexto previo
+
+Antes de hacer cualquier pregunta, lee el contexto disponible:
+
+1. Lee `.planning/PROYECTO.md` — contexto general del proyecto.
+2. Lee `.planning/HOJA-RUTA.md` — para entender todas las fases y su posición.
+3. Lee `.planning/REQUISITOS.md` — requisitos globales del sistema.
+4. Busca si existe `.planning/fases/0N-CONTEXTO.md` (donde N es el número de fase). Si existe, léelo — puede ser un trabajo previo que se está retomando.
+5. Si la fase N > 1, lee el CONTEXTO.md de la fase anterior para entender dependencias.
+
+Si `.planning/PROYECTO.md` no existe, DETENTE y di:
+```
+No existe .planning/PROYECTO.md. Debes inicializar el proyecto primero con /swl:nuevo-proyecto.
+```
+
+## Paso 2 — Verificación de la fase solicitada
+
+Valida que la fase N existe en el HOJA-RUTA.md:
+
+- Si la fase existe: lee su descripción y objetivos del roadmap.
+- Si la fase NO existe en el roadmap: informa al usuario y pregunta si quiere agregar la fase al roadmap antes de continuar.
+- Si el número de fase es 0 o negativo: error, pide un número válido.
+
+Muestra al usuario el nombre y descripción de la fase según el roadmap:
+```
+Vamos a discutir la Fase N: [nombre de la fase]
+Descripción en el roadmap: [descripción]
+Dependencias declaradas: [fases previas requeridas]
+
+Haré algunas preguntas para entender los detalles. Puedes responder con todo el detalle que quieras.
+```
+
+## Paso 3 — Entrevista adaptativa por bloques
+
+La entrevista se adapta al tipo de fase. Primero determina el tipo leyendo la descripción:
+
+- **Fase de infraestructura/setup**: preguntas sobre entorno, herramientas, CI/CD
+- **Fase de backend/API**: preguntas sobre modelos de datos, endpoints, reglas de negocio
+- **Fase de frontend/UI**: preguntas sobre pantallas, flujos de usuario, componentes
+- **Fase de integración**: preguntas sobre sistemas externos, formatos, protocolos
+- **Fase de datos/migración**: preguntas sobre volumen, transformaciones, rollback
+- **Fase mixta**: combina bloques relevantes
+
+### Bloque universal (todas las fases)
+
+Presenta primero:
+
+1. ¿Cuál es el entregable más importante de esta fase? ¿Cómo sabremos que está terminada?
+2. ¿Hay algo en esta fase que NO quedó claro en el roadmap y que debemos aclarar ahora?
+3. ¿Cuáles son los riesgos más grandes que ves en esta fase?
+4. ¿Hay decisiones técnicas o de producto que debemos tomar antes de empezar a planear?
+
+### Bloque de dominio (según tipo de fase)
+
+**Si la fase es de backend/API:**
+5. ¿Qué entidades de datos nuevas introduce esta fase? Describe sus campos principales.
+6. ¿Qué endpoints o servicios necesita exponer esta fase?
+7. ¿Hay reglas de negocio complejas o cálculos que deben procesarse?
+8. ¿Qué validaciones son críticas? ¿Qué datos nunca deben llegar corruptos a la BD?
+9. ¿Quién tiene permiso de acceder a qué? ¿Hay roles o restricciones de seguridad?
+
+**Si la fase es de frontend/UI:**
+5. ¿Qué pantallas o vistas nuevas introduce esta fase? Descríbelas.
+6. ¿Cuál es el flujo principal del usuario en esta fase? (de dónde viene, qué hace, adónde va)
+7. ¿Hay componentes que deben reutilizarse del diseño existente o del sistema de diseño?
+8. ¿Qué datos consume cada pantalla? ¿De qué endpoints los obtiene?
+9. ¿Hay estados de carga, error y vacío que debemos considerar explícitamente?
+
+**Si la fase es de infraestructura:**
+5. ¿Cuál es el entorno objetivo? (dev, staging, prod — con diferencias entre ellos)
+6. ¿Hay secretos o variables de entorno que esta fase introduce?
+7. ¿Qué servicios gestionados (cloud) se van a usar?
+8. ¿Cuál es la estrategia de rollback si algo sale mal en despliegue?
+9. ¿Se necesita documentar el proceso de despliegue para el equipo?
+
+**Si la fase es de integración:**
+5. ¿Qué sistema externo se integra? ¿Tienes la documentación de su API?
+6. ¿El sistema externo tiene ambiente de pruebas (sandbox)?
+7. ¿Qué pasa si el sistema externo no responde? ¿Hay timeout y retry definidos?
+8. ¿Se sincronizan datos en tiempo real o en batch?
+9. ¿Hay transformaciones de datos entre los formatos de ambos sistemas?
+
+### Bloque de criterios de aceptación
+
+Siempre al final:
+
+10. ¿Qué debe demostrarle el equipo al usuario/cliente para que la fase se apruebe?
+11. ¿Hay pruebas específicas que deben pasar? (pruebas de humo, de carga, de usuario)
+12. ¿Quién da el visto bueno final de esta fase?
+
+## Paso 4 — Preguntas de seguimiento
+
+Después de las respuestas del Bloque de dominio, revisa si hay ambigüedades. Para cada respuesta ambigua, haz UNA pregunta de seguimiento específica. Ejemplos:
+
+- "Mencionaste que los usuarios pueden tener múltiples roles — ¿un usuario puede tener rol A y B al mismo tiempo, o son exclusivos?"
+- "Dijiste que los datos se sincronizan 'frecuentemente' — ¿cada cuánto tiempo exactamente?"
+- "Mencionaste 'validación del lado del cliente' — ¿también se valida en el servidor, o solo en frontend?"
+
+Máximo 5 preguntas de seguimiento por fase. Si hay más de 5 ambigüedades, documenta las restantes como "[PENDIENTE DE ACLARAR]" en el CONTEXTO.md.
+
+## Paso 5 — Confirmación del entendimiento
+
+Presenta un resumen de lo capturado:
+
+```
+Resumen de lo discutido para la Fase N — [nombre]:
+
+OBJETIVO PRINCIPAL:
+[lo que el usuario dijo]
+
+ENTREGABLES CLAVE:
+- [entregable 1]
+- [entregable 2]
+
+REQUISITOS TÉCNICOS IDENTIFICADOS:
+- [req 1]
+- [req 2]
+
+REGLAS DE NEGOCIO:
+- [regla 1]
+
+CRITERIOS DE ACEPTACIÓN:
+- [criterio 1]
+
+RIESGOS IDENTIFICADOS:
+- [riesgo 1]
+
+PUNTOS PENDIENTES DE ACLARAR:
+- [pendiente 1] (si hay)
+
+¿Hay algo que corregir o agregar antes de generar el archivo de contexto?
+```
+
+Espera confirmación. Si hay correcciones, ajusta y presenta el resumen nuevamente.
+
+## Paso 6 — Generación del archivo de contexto
+
+Una vez confirmado, crea `.planning/fases/0N-CONTEXTO.md` (donde N es el número de fase con cero a la izquierda si N < 10, ej: `01-CONTEXTO.md`, `02-CONTEXTO.md`).
+
+Estructura del archivo:
+
+```markdown
+# Contexto de la Fase N — [nombre de la fase]
+
+**Proyecto**: [nombre del proyecto]
+**Fase**: N de M (total de fases en el roadmap)
+**Fecha de discusión**: [fecha actual]
+**Estado**: Listo para planear
+
+## Objetivo de la fase
+[descripción clara del objetivo]
+
+## Entregables esperados
+[lista con formato de checklist: - [ ] entregable]
+
+## Requisitos técnicos
+[lista detallada]
+
+## Reglas de negocio
+[lista de reglas, numeradas]
+
+## Modelos de datos (si aplica)
+[descripción de entidades y campos clave]
+
+## Endpoints / servicios (si aplica)
+[lista de endpoints con método, ruta y propósito]
+
+## Pantallas / vistas (si aplica)
+[descripción de pantallas]
+
+## Criterios de aceptación
+[lista medible de criterios]
+
+## Riesgos identificados
+[lista con nivel de impacto: ALTO/MEDIO/BAJO]
+
+## Dependencias
+[qué fases previas deben estar completas, qué sistemas externos se necesitan]
+
+## Decisiones pendientes
+[preguntas que quedaron abiertas y deben resolverse antes o durante la ejecución]
+
+## Notas adicionales
+[todo lo que no encajó en las categorías anteriores pero es importante]
+```
+
+## Paso 7 — Reporte al usuario
+
+Al terminar:
+
+1. Ruta absoluta del archivo generado.
+2. Número de requisitos técnicos capturados.
+3. Número de decisiones pendientes (si hay, destacar como acción requerida).
+4. Próximo paso: "Ya puedes planear esta fase con `/swl:planear-fase N`"
+
+## Reglas de comportamiento
+
+- NUNCA hagas todas las preguntas de un bloque de golpe si son más de 4. Divide en sub-bloques.
+- NUNCA asumas la respuesta a una pregunta aunque parezca obvia.
+- Si el usuario dice "como siempre" o "igual que antes", pregunta para verificar — las asunciones son la fuente principal de retrabajo.
+- El archivo CONTEXTO.md debe ser comprensible sin haber participado en la conversación.
+- Escribe el archivo en español-MX con formato Markdown limpio.
+- Si el usuario no sabe algo importante, documenta "[POR DEFINIR]" y continúa — no bloquees el proceso.

package/comandos/swl/ejecutar-fase.md

@@ -0,0 +1,135 @@
+---
+name: swl:ejecutar-fase
+description: Recibe el número de una fase y la implementa siguiendo el PLAN.md. Delega al agente implementador-swl, hace commits atómicos por slice, produce RESUMEN.md y actualiza ESTADO.md y HOJA-RUTA.md al terminar.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:ejecutar-fase <n> — Ejecutar implementación de una fase
+
+Eres el coordinador de ejecución SWL. Orquestas la implementación real del código para una fase, delegando al agente implementador-swl, verificando cada slice y manteniendo el estado del proyecto actualizado.
+
+## Uso
+
+```
+/swl:ejecutar-fase 1
+/swl:ejecutar-fase 2
+```
+
+## Paso 0 — Carga de habilidades
+
+Carga obligatoria:
+```
+Skill("ejecutar-fase")
+```
+
+El skill define el protocolo completo de ejecución por tarea (leer > verificar dependencias > implementar > verificar > commit > actualizar ESTADO.md), el formato de commit atómico, las 3 reglas de desviación (menor/moderada/mayor), el manejo de tareas HITL, TDD opcional, el formato de ESTADO.md y el checklist de cierre de fase.
+
+Luego carga habilidades específicas del stack detectado en PLAN.md o PROYECTO.md:
+- Backend Python: `Skill("fastapi-experto")`, `Skill("patrones-python")`
+- Frontend Angular: `Skill("angular-moderno")`
+- Modelos de datos: `Skill("postgresql-experto")`
+- Autenticación: `Skill("auth-patrones")`
+- Siempre: `Skill("manejo-errores")`
+
+## Paso 1 — Verificación de prerrequisitos
+
+Verifica en orden:
+1. `.planning/PROYECTO.md` — debe existir
+2. `.planning/fases/0N-PLAN.md` — debe existir. Sin esto: "Ejecuta `/swl:planear-fase N` primero."
+3. `.planning/fases/0N-CONTEXTO.md` — debe existir
+4. Verifica que el PLAN.md no tenga "[REQUIERE REVISIÓN HUMANA]"
+5. **Requirement Freeze**: verifica que el frontmatter del PLAN.md contenga
+   `estado: aprobado`. Si contiene `estado: borrador` o no tiene campo `estado`:
+   - DETENER ejecución
+   - Reportar: "El PLAN.md no está aprobado. Ejecuta `/swl:planear-fase N` y
+     confirma el plan antes de ejecutar."
+   - NO proceder sin aprobación explícita del usuario
+
+Lee los tres archivos completos. Verifica estado de Git (`git status`, `git log --oneline -5`). Si hay cambios no commiteados, pregunta cómo proceder.
+
+**Nota sobre Requirement Freeze**: una vez que el plan está aprobado y la ejecución
+comienza, los slices y tareas del plan son inmutables. Si durante la ejecución se
+detecta que el scope necesita cambiar, el agente DEBE pausar y escalar al usuario
+en lugar de modificar silenciosamente el alcance. Esto previene el "goal drift"
+donde el resultado final diverge del plan acordado.
+
+## Paso 2 — Análisis del PLAN.md
+
+Extrae: lista ordenada de slices con tareas, slices HITL vs AFK, estimación total, comandos de verificación.
+
+Si hay slices HITL, preséntalos ANTES de comenzar:
+```
+Esta fase tiene [N] decisiones HITL:
+HITL 1 — [nombre]: [decisión requerida]
+¿Puedes resolverlas ahora, o prefieres que pause antes de cada una?
+```
+
+Espera respuesta.
+
+## Paso 3 — Inicio del registro de ejecución
+
+Crea o inicializa `.planning/ESTADO.md` siguiendo el formato definido en el skill (progreso, slices, última acción, próxima acción).
+
+## Paso 4 — Ejecución por slices
+
+Para cada slice del PLAN.md en orden:
+
+### 4.1 — Preparación
+Anuncia inicio del slice (nombre, tipo AFK/HITL, número de tareas). Si es HITL no resuelto, pide decisión y espera.
+
+### 4.2 — Delegación al implementador-swl
+Delega con instrucción precisa: contexto a leer (PROYECTO.md, PLAN.md, CONTEXTO.md, CLAUDE.md), tareas del slice, criterio de verificación. El skill define las reglas de commit atómico y formato.
+
+### 4.3 — Verificación del slice
+Ejecuta comandos de verificación del PLAN.md, verifica archivos, revisa commits (`git log --oneline -5`), corre tests. Si falla: máximo 2 reintentos antes de escalar al usuario.
+
+### 4.4 — Actualización del ESTADO.md
+Marca slice completado, actualiza contadores, registra desviaciones según las reglas del skill (menor: registrar; moderada: notificar; mayor: STOP).
+
+### 4.5 — Avanzar
+Reporta al usuario (1-3 líneas: qué se implementó, commits, tests). Continúa automáticamente (AFK) o espera confirmación (HITL).
+
+## Paso 5 — Manejo de errores
+
+Según tipo de error:
+- **Bug de implementación**: el agente lo resuelve. Si no puede en 2 intentos, presenta opciones al usuario.
+- **Desviación de la spec**: PARAR. Reportar: qué dice el plan, qué encontró la realidad, opciones.
+- **Dependencia faltante**: PARAR. Reportar.
+
+## Paso 6 — RESUMEN.md
+
+Al completar todos los slices, genera `.planning/fases/0N-RESUMEN.md` con: slices implementados (commits, archivos), resultados de tests, desviaciones del plan, decisiones técnicas, deuda técnica, estado final, criterios de aceptación verificados, próximos pasos.
+
+## Paso 7 — Actualización de HOJA-RUTA.md y ESTADO.md
+
+Marca fase completada en HOJA-RUTA.md con fecha. Actualiza ESTADO.md con estado general.
+
+## Paso 8 — Reporte final
+
+```
+Fase N — [nombre] completada.
+
+Slices implementados: [N de N]
+Commits creados: [N]
+Tests pasando: [N de N]
+Desviaciones del plan: [N, o "ninguna"]
+
+Archivos generados:
+- .planning/fases/0N-RESUMEN.md
+- .planning/ESTADO.md (actualizado)
+- .planning/HOJA-RUTA.md (actualizado)
+
+Próximo paso recomendado: /swl:verificar
+```
+
+## Reglas de comportamiento
+
+- NUNCA hagas commits grandes al final — commits atómicos por tarea.
+- NUNCA continúes con el siguiente slice si el anterior falló la verificación.
+- NUNCA modifiques archivos `.planning/` como parte de los commits de código.
+- Si la ejecución se interrumpe, ESTADO.md debe quedar actualizado para que `/swl:checkpoint` pueda retomar.
+- Documenta TODAS las desviaciones en el RESUMEN.md.
+- Si un criterio de aceptación no se puede cumplir, documenta por qué y escala al usuario.
+- NUNCA ejecutes un plan sin `estado: aprobado` — el requirement freeze es obligatorio.
+- NUNCA modifiques el scope del plan silenciosamente durante la ejecución.
+- Si el agente implementador propone cambios de scope, PARAR y escalar al usuario.