@saulwade/swl-ses 1.0.0

package/habilidades/notificaciones-multicanal/recursos/configuracion-y-templates.md

@@ -0,0 +1,303 @@
+# Notificaciones Multicanal — Configuración y Templates
+
+Referencia extendida de la skill `notificaciones-multicanal`. Contiene
+configuración completa de canales, formatos de mensaje, rate limiting,
+templates y flujo de diagnóstico.
+
+---
+
+## Configuración completa de canales (config.json)
+
+```jsonc
+// ~/.claude/notifications/config.json
+{
+  "version": "2",
+  "defaults": {
+    "canal_primario": "desktop",
+    "prioridad_minima": "normal",
+    "idioma": "es-MX",
+    "zona_horaria": "America/Mexico_City"
+  },
+
+  "canales": {
+    "desktop": {
+      "habilitado": true,
+      "motor": "auto",
+      "icono": "~/.claude/assets/swl-icon.png",
+      "sonido": true,
+      "duracion_ms": 5000,
+      "persistente_si_prioridad": "urgente"
+    },
+
+    "telegram": {
+      "habilitado": true,
+      "bot_token": "${TELEGRAM_BOT_TOKEN}",
+      "chat_id": "${TELEGRAM_CHAT_ID}",
+      "parse_mode": "HTML",
+      "disable_preview": true,
+      "timeout_segundos": 10
+    },
+
+    "whatsapp": {
+      "habilitado": false,
+      "proveedor": "twilio",
+      "account_sid": "${TWILIO_ACCOUNT_SID}",
+      "auth_token": "${TWILIO_AUTH_TOKEN}",
+      "from_number": "${TWILIO_WHATSAPP_FROM}",
+      "to_number": "${WHATSAPP_TO_NUMBER}"
+    },
+
+    "email": {
+      "habilitado": false,
+      "smtp_host": "${SMTP_HOST}",
+      "smtp_port": 587,
+      "smtp_user": "${SMTP_USER}",
+      "smtp_password": "${SMTP_PASSWORD}",
+      "from": "swl-notifier@empresa.com",
+      "to": ["dev@empresa.com"],
+      "asunto_prefijo": "[SWL]"
+    },
+
+    "webhook": {
+      "habilitado": false,
+      "url": "${WEBHOOK_URL}",
+      "metodo": "POST",
+      "headers": {
+        "Authorization": "Bearer ${WEBHOOK_TOKEN}",
+        "Content-Type": "application/json"
+      },
+      "timeout_segundos": 5,
+      "reintentos": 2
+    }
+  }
+}
+```
+
+---
+
+## Formato de Mensaje por Canal
+
+### Desktop
+
+Limitaciones: título 64 chars, cuerpo 256 chars, sin formato enriquecido.
+
+```json
+{
+  "canal": "desktop",
+  "titulo": "Fase 2 completada — SWL",
+  "cuerpo": "8/8 tareas ejecutadas. 0 errores. Listo para revision.",
+  "accion_click": "abrir_terminal"
+}
+```
+
+### Telegram
+
+Soporte completo de HTML. Máximo 4096 chars por mensaje.
+
+```html
+<b>Fase 2 Completada</b>
+<code>Proyecto: sigaf-backend</code>
+
+<b>Resumen:</b>
+- 8 tareas ejecutadas
+- 0 errores criticos
+- 2 advertencias menores
+
+<b>Artefactos generados:</b>
+- <code>PLAN.md</code> — Plan actualizado
+- <code>RESUMEN.md</code> — Resumen de ejecucion
+
+<b>Accion requerida:</b>
+Revisa los artefactos y responde con: <code>aprobar</code> o <code>ajustar: [feedback]</code>
+```
+
+### WhatsApp
+
+Sin HTML. Soporte de *negrita* y _cursiva_ con markdown simple.
+
+```
+*SWL — Fase 2 Completada*
+
+Proyecto: sigaf-backend
+Tareas: 8/8
+
+Artefactos listos para revision:
+- PLAN.md
+- RESUMEN.md
+
+Responde APROBAR o AJUSTAR para continuar.
+```
+
+### Email
+
+```
+Asunto: [SWL] Fase 2 Completada — sigaf-backend
+
+Proyecto:   sigaf-backend
+Fase:       2 de 4
+Estado:     COMPLETADA
+Fecha/hora: 2024-03-20 14:32 CST
+
+TAREAS EJECUTADAS (8/8):
+  - Setup de base de datos
+  - Modelos SQLAlchemy
+  - Endpoints FastAPI
+  ... (ver RESUMEN.md adjunto)
+
+ARTEFACTOS ADJUNTOS:
+  - RESUMEN.md
+  - VERIFICACION.md
+
+ACCION REQUERIDA:
+  Revisar artefactos y aprobar para continuar con Fase 3.
+  Responder a este email con: APROBAR o AJUSTAR [feedback]
+
+---
+SWL Software Engineering System v2
+```
+
+### Webhook
+
+Payload JSON normalizado:
+
+```json
+{
+  "version": "2",
+  "evento": {
+    "id": "evt-20240320-1432-001",
+    "tipo": "checkpoint",
+    "subtipo": "human-verify",
+    "timestamp": "2024-03-20T20:32:00Z",
+    "proyecto": "sigaf-backend",
+    "fase": 2,
+    "prioridad": "normal"
+  },
+  "mensaje": {
+    "titulo": "Fase 2 Completada",
+    "cuerpo": "8/8 tareas ejecutadas sin errores.",
+    "accion_requerida": true,
+    "opciones": ["aprobar", "ajustar", "rechazar"]
+  },
+  "metadatos": {
+    "agente": "ejecutor",
+    "duracion_fase_ms": 84500,
+    "artefactos": ["RESUMEN.md", "VERIFICACION.md"]
+  }
+}
+```
+
+---
+
+## Rate Limiting y Supresión
+
+### Configuración de rate limiting
+
+```jsonc
+{
+  "rate_limiting": {
+    "ventana_segundos": 300,
+    "maximo_por_ventana": {
+      "desktop":  10,
+      "telegram": 20,
+      "whatsapp":  5,
+      "email":     3,
+      "webhook":  50
+    },
+    "excepcion_prioridades": ["critico", "urgente"]
+  }
+}
+```
+
+### Supresión por horario (No molestar)
+
+```jsonc
+{
+  "no_molestar": {
+    "habilitado": true,
+    "inicio": "22:00",
+    "fin": "08:00",
+    "zona_horaria": "America/Mexico_City",
+    "excepciones": ["critico"],
+    "acumulacion": {
+      "habilitada": true,
+      "resumen_en": "08:00",
+      "canal_resumen": "telegram"
+    }
+  }
+}
+```
+
+### Supresión de duplicados
+
+```jsonc
+{
+  "deduplicacion": {
+    "habilitada": true,
+    "ventana_segundos": 60,
+    "clave": "evento.tipo + evento.proyecto + mensaje.titulo"
+  }
+}
+```
+
+---
+
+## Templates de Mensajes
+
+Los templates usan sintaxis `{{variable}}` con soporte de condicionales simples:
+
+```
+# templates/checkpoint-verify.telegram.html
+<b>{{icono_estado}} {{titulo}}</b>
+{{#si proyecto}}<code>Proyecto: {{proyecto}}</code>{{/si}}
+
+<b>Resumen:</b>
+{{resumen}}
+
+{{#si artefactos}}
+<b>Artefactos:</b>
+{{#cada artefactos}}- <code>{{nombre}}</code>{{/cada}}
+{{/si}}
+
+{{#si accion_requerida}}
+<b>Accion requerida:</b>
+{{accion_descripcion}}
+{{/si}}
+```
+
+### Variables disponibles en todos los templates
+
+| Variable | Descripción |
+|----------|-------------|
+| `{{proyecto}}` | Nombre del proyecto actual |
+| `{{fase}}` | Número de fase actual |
+| `{{agente}}` | Agente que emite la notificación |
+| `{{timestamp}}` | Fecha/hora local formateada |
+| `{{titulo}}` | Título del evento |
+| `{{resumen}}` | Cuerpo principal del evento |
+| `{{prioridad}}` | Nivel de prioridad del evento |
+
+---
+
+## Flujo de Diagnóstico
+
+Si una notificación no llega:
+
+```
+1. Verificar que el broker este activo:
+   claude-notifications-go status
+
+2. Verificar variables de entorno:
+   echo $TELEGRAM_BOT_TOKEN | head -c 10
+
+3. Probar canal especifico:
+   claude-notifications-go test --canal telegram
+
+4. Revisar log de errores:
+   claude-notifications-go log --nivel error --ultimas 10
+
+5. Verificar rate limiting:
+   claude-notifications-go stats --canal telegram
+
+6. Verificar horario No Molestar:
+   claude-notifications-go no-molestar --estado
+```

package/habilidades/nuevo-proyecto/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: nuevo-proyecto
+description: Flujo para inicializar un proyecto de software nuevo. Recopila visión, restricciones técnicas y de negocio, stack tecnológico y contexto del equipo. Genera la carpeta .planning/ con PROYECTO.md, REQUISITOS.md y HOJA-RUTA.md como artefactos de arranque.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar para incorporar un proyecto existente al sistema SWL; usar el comando `/swl:adoptar-proyecto`."
+  - "No cargar si `.planning/PROYECTO.md` ya existe y el objetivo es actualizar requisitos; editar ese archivo directamente."
+  - "No cargar para generar solo el PLAN.md de una fase puntual sin visión de proyecto; usar `discutir-fase` + `planear-fase`."
+  - "No cargar para instalar componentes SWL en el proyecto recién creado; usar `instalar-sistema` como paso siguiente."
+evolvable: true  # default para skill estandar
+---
+# Habilidad: Inicializar Proyecto Nuevo
+
+## Propósito
+
+Establecer una base sólida de documentación y contexto antes de escribir la primera
+línea de código. Un proyecto sin contexto escrito acumula deuda de decisiones desde
+el día uno. Esta habilidad evita ese antipatrón.
+
+## Cuándo activar
+
+- El usuario dice "quiero crear un proyecto", "empecemos un sistema", "nuevo proyecto"
+- No existe carpeta `.planning/` en el directorio de trabajo
+- Se recibe un brief o documento de requisitos sin estructura técnica
+
+## Cuándo NO cargar
+
+- El proyecto ya tiene `.planning/PROYECTO.md` — se está inicializando un proyecto ya iniciado. En ese caso actualizar el archivo existente.
+- El usuario quiere incorporar un codebase existente al sistema SWL; usar `/swl:adoptar-proyecto` que hace análisis automático del código.
+- El usuario solo quiere planear una fase de trabajo dentro de un proyecto ya definido; usar `discutir-fase` + `planear-fase`.
+- El objetivo es instalar componentes SWL (agentes, skills, hooks) en el directorio; eso lo hace `instalar-sistema` después de la inicialización.
+
+---
+
+## Fase 1 — Recopilación de contexto (cuestionario)
+
+Antes de generar cualquier archivo, haz las siguientes preguntas. Agrupa las que
+puedas en un solo mensaje para no saturar al usuario.
+
+### Bloque A — Visión y alcance
+
+1. ¿Cuál es el problema de negocio que resuelve este sistema? (1-3 oraciones)
+2. ¿Quiénes son los usuarios finales? ¿Cuántos usuarios concurrentes se esperan?
+3. ¿Hay una fecha límite o MVP en mente?
+4. ¿Existe algún sistema legado que este proyecto reemplaza o integra?
+
+### Bloque B — Stack y restricciones técnicas
+
+5. ¿Hay lenguajes, frameworks o plataformas mandatorias (por política o equipo)?
+6. ¿La solución es on-premise, cloud (cuál proveedor) o híbrida?
+7. ¿Existe una base de datos preferida o mandatoria?
+8. ¿Hay restricciones de licencia (OSS only, sin GPL, etc.)?
+
+### Bloque C — Equipo y proceso
+
+9. ¿Cuántas personas trabajarán en el proyecto y cuáles son sus roles?
+10. ¿Se usa algún proceso formal (Scrum, Kanban, waterfall)?
+11. ¿Hay un repositorio de código ya creado? ¿Rama principal?
+12. ¿Hay pipelines CI/CD existentes o se crean desde cero?
+
+### Bloque D — Calidad y seguridad
+
+13. ¿Existen políticas de cobertura de tests mínima?
+14. ¿El sistema maneja datos sensibles (PII, financieros, médicos)?
+15. ¿Hay requerimientos regulatorios (GDPR, HIPAA, SOC 2, etc.)?
+
+---
+
+## Fase 2 — Generación de artefactos
+
+Una vez obtenidas las respuestas, crea la carpeta `.planning/` y los tres documentos.
+
+### Plantilla: `.planning/PROYECTO.md`
+
+```markdown
+# PROYECTO.md — [Nombre del Proyecto]
+
+## Visión
+[1 párrafo describiendo el problema y la solución]
+
+## Objetivos del MVP
+- [ ] Objetivo 1
+- [ ] Objetivo 2
+
+## Usuarios y contexto de uso
+| Actor | Descripción | Volumen estimado |
+|-------|-------------|-----------------|
+|       |             |                 |
+
+## Stack tecnológico
+| Capa        | Tecnología | Justificación |
+|-------------|-----------|---------------|
+| Backend     |           |               |
+| Frontend    |           |               |
+| Base de datos |         |               |
+| Infraestructura |       |               |
+
+## Restricciones no negociables
+1.
+2.
+
+## Equipo
+| Rol | Responsabilidad |
+|-----|----------------|
+|     |                |
+
+## Fechas clave
+- Kick-off:
+- MVP:
+- Producción:
+
+## Criterios de éxito
+- [ ] Criterio medible 1
+- [ ] Criterio medible 2
+```
+
+### Plantilla: `.planning/REQUISITOS.md`
+
+```markdown
+# REQUISITOS.md — [Nombre del Proyecto]
+
+## Requerimientos Funcionales
+
+### RF-001: [Nombre]
+- **Descripción**:
+- **Actores**:
+- **Prioridad**: Alta / Media / Baja
+- **Criterios de aceptación**:
+  - [ ] CA-1
+  - [ ] CA-2
+
+[Repetir para cada RF]
+
+## Requerimientos No Funcionales
+
+| ID     | Categoría     | Descripción | Métrica de aceptación |
+|--------|--------------|-------------|----------------------|
+| RNF-001 | Rendimiento  |             | p95 < 200ms          |
+| RNF-002 | Disponibilidad|            | 99.5% uptime         |
+| RNF-003 | Seguridad    |             |                      |
+
+## Requerimientos de Integración
+- Sistema externo 1: [protocolo, frecuencia, volumen]
+- Sistema externo 2:
+
+## Fuera de alcance (explícito)
+- X no está incluido en este proyecto.
+- Y se abordará en una fase posterior.
+```
+
+### Plantilla: `.planning/HOJA-RUTA.md`
+
+```markdown
+# HOJA-RUTA.md — [Nombre del Proyecto]
+
+## Fase 0 — Infraestructura base
+- [ ] Repositorio y branching strategy
+- [ ] CI/CD pipeline básico
+- [ ] Entorno local de desarrollo documentado
+- **Duración estimada**:
+
+## Fase 1 — [Nombre del primer bloque funcional]
+- [ ] Tarea 1
+- [ ] Tarea 2
+- **Objetivo**:
+- **Duración estimada**:
+
+## Fase N — ...
+
+## Hitos de revisión
+| Hito | Criterio de salida | Fecha estimada |
+|------|-------------------|---------------|
+|      |                   |               |
+```
+
+---
+
+## Fase 3 — Checklist de arranque
+
+Antes de cerrar la sesión de inicialización, verifica:
+
+- [ ] PROYECTO.md tiene todos los campos poblados (no hay `[TBD]` en restricciones)
+- [ ] Cada RF tiene al menos un criterio de aceptación medible
+- [ ] El HOJA-RUTA.md tiene fases con duración estimada
+- [ ] Las restricciones "no negociables" están identificadas y documentadas
+- [ ] Se registró quién tomó cada decisión de stack (para futura referencia)
+
+## Gotchas / Errores comunes no obvios
+
+- **PROYECTO.md generado con `[TBD]` en restricciones no negociables**: el agente deja campos sin resolver para no bloquear al usuario, pero las restricciones vacías generan retrabajos costosos cuando se descubren tardíamente. Causa: el checklist de cierre de la Fase 3 no se aplicó rigurosamente. Solución: no cerrar la sesión de inicialización hasta que no quede ningún `[TBD]` en el bloque de restricciones — si el usuario no puede responder, registrar la restricción como "pendiente" en la sección `## Decisiones pendientes` con ticket asignado.
+- **Fase 1 de HOJA-RUTA.md sin duración estimada**: el usuario acepta el documento sin notar que las fases no tienen estimaciones. Causa: el agente genera el template sin poblar las duraciones. Solución: antes de entregar HOJA-RUTA.md, pedir al usuario una estimación rough (días, semanas) para cada fase — sin eso el roadmap es decorativo.
+- **Stack seleccionado sin verificar restricciones del Bloque B**: el agente sugiere un stack "moderno" que viola una restricción de licencia OSS o de plataforma mandatoria del equipo. Causa: el Bloque B se procesó en orden pero las respuestas no se cruzaron con las sugerencias del Bloque A. Solución: al proponer stack, citar explícitamente cada restricción del Bloque B y confirmar que ninguna es violada.
+- **No preguntar por sistemas legados cuando el usuario menciona "reemplazar"**: el agente omite la pregunta 4 del Bloque A asumiendo que el proyecto es greenfield. Causa: mala clasificación del proyecto como nuevo cuando el usuario usó la palabra "reemplazar". Solución: si el usuario menciona "reemplazar", "migrar" o "integrar con" en la descripción, la pregunta 4 es obligatoria, no opcional.
+
+## Señales de alerta
+
+Detente y escala si el usuario no puede responder:
+- Qué problema resuelve el sistema (visión indefinida)
+- Quiénes son los usuarios finales (alcance sin ancla)
+- Si hay sistemas legados involucrados (riesgo de integración oculto)
+
+Estos huecos de información generan retrabajos costosos. Registra las preguntas
+sin respuesta en PROYECTO.md bajo la sección `## Decisiones pendientes`.