@saulwade/swl-ses 1.0.0

package/habilidades/generacion-mermaid/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: generacion-mermaid
+description: >
+  Generación automática de diagramas Mermaid desde planes de ejecución, workflows
+  y estructuras de agentes. Convierte planes textuales en diagramas flowchart,
+  sequence y state. Cargar cuando se necesite documentación visual de un plan,
+  workflow o flujo de agentes en /swl:planear-fase, /swl:ejecutar-fase o docs.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+user-invocable: false
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para diagramas de arquitectura de sistemas con componentes visuales enriquecidos (cajas con colores, leyendas, fondos oscuros) — para diagramas de arquitectura visual cargar `diagrama-arquitectura`."
+  - "No cargar para diagramas de entidad-relación de base de datos — para ER cargar `dbml-experto` (DBML) o usar la sintaxis `erDiagram` de Mermaid directamente si el alcance es simple."
+  - "No cargar para diagramas de arquitectura C4 en formato as-code versionable — para C4 cargar `likec4-experto`."
+  - "No cargar para wireframes o mockups de interfaz de usuario — para UI prototyping cargar `wireframes-flujos`."
+---
+# Generación de Diagramas Mermaid
+
+Convierte planes de ejecución, workflows y flujos de agentes en diagramas Mermaid
+renderizables en Markdown. Basado en patrones de CC Workflow Studio.
+
+## Cuándo NO cargar
+
+- La tarea requiere diagramas de arquitectura con paleta de colores, leyendas y fondo oscuro enriquecido: cargar `diagrama-arquitectura`.
+- La tarea es modelar un esquema de base de datos (ER): cargar `dbml-experto` o usar `erDiagram` directamente.
+- El proyecto ya adoptó LikeC4/C4 model y el diagrama debe ser versionable as-code: cargar `likec4-experto`.
+- La tarea es prototipar flujos de UI o wireframes: cargar `wireframes-flujos`.
+
+## Cuándo cargar
+
+- `planificador-swl` genera un plan y necesita visualización
+- `documentador-swl` documenta flujos de ejecución
+- `/swl:planear-fase` necesita diagrama del plan generado
+- Cualquier ADR o RFC que necesite diagrama de flujo
+
+## Tipos de diagrama soportados
+
+### 1. Flowchart (para planes de ejecución)
+
+```mermaid
+flowchart TD
+    Start([Inicio]) --> Slice1[Slice 1: API endpoints]
+    Start --> Slice2[Slice 2: Frontend forms]
+    Slice1 --> Test1{Tests pasan?}
+    Slice2 --> Test2{Tests pasan?}
+    Test1 -->|Sí| Review[Revisión de código]
+    Test1 -->|No| Fix1[Corregir slice 1]
+    Fix1 --> Test1
+    Test2 -->|Sí| Review
+    Test2 -->|No| Fix2[Corregir slice 2]
+    Fix2 --> Test2
+    Review --> Deploy([Deploy])
+```
+
+### 2. Sequence (para flujos de agentes)
+
+```mermaid
+sequenceDiagram
+    participant U as Usuario
+    participant O as Orquestador
+    participant A as Arquitecto
+    participant I as Implementador
+    participant R as Revisor
+
+    U->>O: Feature request
+    O->>A: Diseñar arquitectura
+    A-->>O: Plan aprobado
+    O->>I: Implementar slice 1
+    O->>I: Implementar slice 2
+    I-->>O: Implementación completa
+    O->>R: Revisar código
+    R-->>O: Aprobado
+    O-->>U: Feature lista
+```
+
+### 3. State (para ciclo de vida)
+
+```mermaid
+stateDiagram-v2
+    [*] --> Discutir
+    Discutir --> Planear: Contexto completo
+    Planear --> Ejecutar: Plan aprobado
+    Ejecutar --> Verificar: Implementación completa
+    Verificar --> Ejecutar: Correcciones necesarias
+    Verificar --> [*]: Verificación exitosa
+```
+
+## Patrones de conversión plan → Mermaid
+
+### Plan con slices independientes (paralelo)
+
+```markdown
+Plan:
+  Slice 1: API de usuarios (backend-api-swl)
+  Slice 2: Formulario de registro (frontend-react-swl)
+  Slice 3: Tests E2E (tdd-qa-swl)
+  Dependencias: Slice 3 depende de Slice 1 y Slice 2
+```
+
+```mermaid
+flowchart TD
+    S([Inicio]) --> S1[Slice 1: API usuarios]
+    S --> S2[Slice 2: Form registro]
+    S1 --> S3[Slice 3: Tests E2E]
+    S2 --> S3
+    S3 --> E([Fin])
+```
+
+### Plan con branching (decisión)
+
+```markdown
+Plan:
+  Paso 1: Analizar si el módulo existe
+  Decisión: ¿Existe el módulo?
+    Sí → Paso 2a: Modificar módulo existente
+    No → Paso 2b: Crear módulo nuevo
+  Paso 3: Tests
+```
+
+```mermaid
+flowchart TD
+    S([Inicio]) --> P1[Analizar módulo]
+    P1 --> D{¿Existe?}
+    D -->|Sí| P2a[Modificar existente]
+    D -->|No| P2b[Crear nuevo]
+    P2a --> P3[Tests]
+    P2b --> P3
+    P3 --> E([Fin])
+```
+
+### Plan con agentes específicos
+
+```markdown
+Plan:
+  Fase 1: Discovery (investigador-swl)
+  Fase 2: Arquitectura (arquitecto-swl) 
+  Fase 3: Implementación paralela
+    - backend-api-swl: API REST
+    - frontend-react-swl: UI
+  Fase 4: Calidad (tdd-qa-swl + revisor-codigo-swl)
+```
+
+```mermaid
+flowchart TD
+    S([Inicio]) --> F1[🔍 Discovery<br/>investigador-swl]
+    F1 --> F2[📐 Arquitectura<br/>arquitecto-swl]
+    F2 --> F3a[⚙️ API REST<br/>backend-api-swl]
+    F2 --> F3b[🖥️ UI<br/>frontend-react-swl]
+    F3a --> F4[✅ Calidad<br/>tdd-qa + revisor]
+    F3b --> F4
+    F4 --> E([Fin])
+```
+
+## Reglas de generación
+
+### Nodos
+
+| Tipo de paso | Forma Mermaid | Ejemplo |
+|-------------|---------------|---------|
+| Inicio/Fin | `([texto])` | `([Inicio])`, `([Deploy])` |
+| Acción/Tarea | `[texto]` | `[Implementar API]` |
+| Decisión | `{texto}` | `{¿Tests pasan?}` |
+| Subproceso | `[[texto]]` | `[[Workflow anidado]]` |
+| Base de datos | `[(texto)]` | `[(PostgreSQL)]` |
+
+### Conexiones
+
+| Tipo | Sintaxis | Cuándo |
+|------|---------|--------|
+| Secuencial | `-->` | Paso A antes que paso B |
+| Con etiqueta | `-->|etiqueta|` | Ramas de decisión |
+| Paralelo | Mismo origen, múltiples destinos | Slices independientes |
+| Punteado | `-.->` | Dependencia débil/opcional |
+
+### Estilo
+
+- Máximo 15 nodos por diagrama (si más, dividir en sub-diagramas)
+- Nombres de nodos: 3-5 palabras máximo
+- Incluir agente responsable en nodos de implementación
+- Usar `TD` (top-down) para planes lineales, `LR` (left-right) para pipelines
+- No incluir detalles de implementación — solo flujo de alto nivel
+
+## Integración con swl-ses
+
+El diagrama Mermaid se incluye automáticamente en:
+- `PLAN.md` generado por `/swl:planear-fase`
+- ADRs en `.planning/adrs/`
+- Documentación generada por `documentador-swl`
+- Exports de `/swl:revisar-impacto` (blast radius visual)
+
+## Ejemplo: conversión completa
+
+**Input (plan textual):**
+```
+Feature: Sistema de notificaciones push
+Slices:
+  1. Modelo de datos y migraciones (backend-python-swl) — 2h
+  2. API de suscripción (backend-api-swl) — 3h
+  3. Worker de envío (backend-workers-swl) — 4h, depende de 1
+  4. UI de preferencias (frontend-react-swl) — 3h, depende de 2
+  5. Tests E2E (tdd-qa-swl) — 2h, depende de 3 y 4
+Gate: Revisión de código antes de merge
+```
+
+**Output (Mermaid):**
+```mermaid
+flowchart TD
+    S([Inicio]) --> S1[1. Modelo de datos<br/>backend-python-swl]
+    S --> S2[2. API suscripción<br/>backend-api-swl]
+    S1 --> S3[3. Worker envío<br/>backend-workers-swl]
+    S2 --> S4[4. UI preferencias<br/>frontend-react-swl]
+    S3 --> S5[5. Tests E2E<br/>tdd-qa-swl]
+    S4 --> S5
+    S5 --> G{Gate: Revisión}
+    G -->|Aprobado| E([Merge])
+    G -->|Rechazado| Fix[Correcciones]
+    Fix --> S5
+```
+
+## Gotchas / Errores comunes no obvios
+
+**Los caracteres de paréntesis `(` `)` en etiquetas de nodos rompen el render de flowchart sin error visible**: Mermaid interpreta `[nombre (acción)]` correctamente, pero `[(nombre)]` o `((nombre))` tienen significados especiales (cilindros, círculos). Si el nombre del nodo contiene paréntesis del dominio (ej: nombres de funciones), el diagrama renderiza mal o produce un nodo vacío. Causa: Mermaid usa paréntesis como operadores de forma de nodo. Fix: escapar el contenido con comillas dentro del corchete: `["nombre (acción)"]` para texto con paréntesis literales.
+
+**Los nodos con IDs largos (más de 20 caracteres) generan conexiones que se solapan visualmente en diagramas `LR`**: Mermaid calcula el ancho de las cajas basándose en el ID del nodo en `flowchart LR`, no en el texto de la etiqueta. IDs largos crean cajas anchas que se solapan con las flechas. Causa: el layouter de Mermaid (Dagre) usa el ID para calcular el bbox inicial. Fix: usar IDs cortos (S1, P2, D3) y poner el texto descriptivo en la etiqueta: `S1[Slice 1: API de usuarios]` en lugar de `implementar-api-usuarios[Implementar API de usuarios]`.
+
+**En diagramas `sequenceDiagram`, los mensajes con `-->>` (línea punteada) en bucles producen un loop infinito visual si el `loop` y el `end` no están correctamente indentados en el código Mermaid**: Mermaid no reporta error de sintaxis, simplemente renderiza el diagrama sin el bloque `loop`, perdiendo la semántica del flujo. Causa: el parser de `sequenceDiagram` es sensible a la indentación de las palabras clave `loop`, `alt`, `opt` y sus `end` correspondientes. Fix: usar siempre indentación de 4 espacios para el contenido de bloques `loop`/`alt`/`opt` y verificar el render en [mermaid.live](https://mermaid.live) antes de incluir en documentación.
+
+**Los diagramas con más de 15 nodos en `flowchart TD` se renderizan con cruce de flechas inevitables porque Dagre no garantiza planarity para grafos densos**: aunque se sigan las reglas de diseño, los grafos con muchas aristas no pueden ser planares y el layout de Dagre produce cruce de aristas que confunden la lectura. Causa: el algoritmo de layout Dagre es heurístico y no garantiza planarity. Fix: dividir el diagrama en dos subdiagramas (por capa o por subsistema) con un nodo de conexión explícito entre ellos, o cambiar a `flowchart LR` que Dagre maneja mejor para grafos anchos.

package/habilidades/git-worktrees-paralelo/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: git-worktrees-paralelo
+description: Uso de git worktrees para ejecución paralela de agentes. Crear, usar y limpiar worktrees de forma segura para que múltiples agentes trabajen sin conflictos.
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para trabajo secuencial de un solo agente — un checkout normal es suficiente; los worktrees añaden complejidad sin beneficio."
+  - "No cargar para gestión de ramas sin paralelismo real (feature branching estándar) — para flujo de ramas estándar seguir la regla `git-workflow.md`."
+  - "No cargar para repositorios monorepo con submódulos Git — los worktrees en repos con submódulos tienen comportamiento inconsistente; usar contenedores o directorios de trabajo separados."
+  - "No cargar para tareas que requieren estado compartido entre agentes (mismo archivo modificado simultáneamente) — los worktrees aíslan pero no resuelven conflictos de edición concurrente."
+---
+# Git Worktrees para Ejecución Paralela
+
+## Cuándo NO cargar
+
+- Solo hay un agente trabajando en el repo: un checkout normal es suficiente.
+- La tarea es feature branching secuencial sin paralelismo real: seguir `git-workflow.md`.
+- El repo tiene submódulos Git: los worktrees con submódulos tienen comportamiento inconsistente.
+- Los agentes paralelos modificarían los mismos archivos simultáneamente: los worktrees aíslan ramas pero no resuelven conflictos de edición concurrente.
+
+## Qué es un worktree
+
+Un **git worktree** permite tener múltiples directorios de trabajo conectados al mismo
+repositorio. Cada worktree tiene su propio árbol de trabajo y puede estar en una rama
+distinta, pero comparten el objeto store de Git (commits, blobs, trees). Esto es ideal
+para agentes paralelos: cada uno trabaja en su propia rama y su propio directorio sin
+interferir con los demás.
+
+---
+
+## Cuándo usar worktrees
+
+- Múltiples agentes ejecutando tareas en paralelo sobre el mismo repo.
+- Trabajar en un hotfix mientras el desarrollo principal sigue en `main`.
+- Revisar el código de una rama sin perder el contexto de la rama actual.
+- Ejecutar la suite de tests de una rama sin hacer checkout.
+- Comparar implementaciones de dos ramas side-by-side.
+
+**No usar worktrees cuando:**
+- Solo hay un agente trabajando. Un checkout normal es suficiente.
+- Las tareas tienen dependencias de orden entre sí.
+
+---
+
+## Comandos esenciales
+
+### Crear un worktree
+
+```bash
+# Sintaxis básica
+git worktree add <ruta> <rama>
+
+# Crear worktree en rama existente
+git worktree add ../mi-proyecto-feature feature/login
+
+# Crear worktree con nueva rama desde HEAD
+git worktree add -b feature/nueva-ruta ../mi-proyecto-nueva-ruta
+
+# Crear worktree con nueva rama desde commit específico
+git worktree add -b hotfix/auth ../mi-proyecto-hotfix origin/main
+```
+
+### Listar worktrees activos
+
+```bash
+git worktree list
+# Salida:
+# /ruta/repo-principal     abc1234 [main]
+# /ruta/repo-feature       def5678 [feature/login]
+# /ruta/repo-hotfix        ghi9012 [hotfix/auth]
+```
+
+### Eliminar un worktree
+
+```bash
+# Primero quitar el directorio, luego limpiar la referencia
+git worktree remove ../mi-proyecto-feature
+
+# Forzar si el directorio tiene cambios sin commitear (cuidado)
+git worktree remove --force ../mi-proyecto-feature
+
+# Limpiar referencias a worktrees eliminados manualmente
+git worktree prune
+```
+
+### Mover un worktree
+
+```bash
+git worktree move ../mi-proyecto-feature ../nueva-ubicacion
+```
+
+---
+
+## Patrón de trabajo para agentes paralelos
+
+### Estructura de directorios recomendada
+
+```
+proyectos/
+├── mi-app/              # Worktree principal (main)
+├── mi-app-agente-1/     # Worktree para Agente 1 (feature/modulo-a)
+├── mi-app-agente-2/     # Worktree para Agente 2 (feature/modulo-b)
+└── mi-app-agente-3/     # Worktree para Agente 3 (feature/modulo-c)
+```
+
+### Flujo completo: lanzar agentes paralelos
+
+```bash
+# 1. Asegurarse de estar en main actualizado
+cd /ruta/mi-app
+git checkout main
+git pull origin main
+
+# 2. Crear worktrees para cada agente
+git worktree add -b feature/modulo-usuarios ../mi-app-agente-1
+git worktree add -b feature/modulo-reportes ../mi-app-agente-2
+git worktree add -b feature/modulo-notificaciones ../mi-app-agente-3
+
+# 3. Cada agente trabaja en su propio directorio
+# Agente 1 → cd ../mi-app-agente-1
+# Agente 2 → cd ../mi-app-agente-2
+# Agente 3 → cd ../mi-app-agente-3
+
+# 4. Los agentes hacen commits normalmente dentro de su worktree
+cd ../mi-app-agente-1
+git add .
+git commit -m "feat(usuarios): implementa CRUD de usuarios"
+
+# 5. Al terminar, crear PRs o mergear
+cd /ruta/mi-app
+git merge feature/modulo-usuarios
+
+# 6. Limpiar worktrees terminados
+git worktree remove ../mi-app-agente-1
+git worktree remove ../mi-app-agente-2
+git worktree remove ../mi-app-agente-3
+git worktree prune
+```
+
+---
+
+## Reglas de seguridad para worktrees paralelos
+
+### La misma rama NO puede estar en dos worktrees
+
+Git prohíbe hacer checkout de la misma rama en dos worktrees. Si se intenta:
+
+```bash
+git worktree add ../copia-main main
+# fatal: 'main' is already checked out at '/ruta/repo-principal'
+```
+
+Solución: cada agente SIEMPRE trabaja en su propia rama, nunca en la misma.
+
+### Archivos de bloqueo compartidos
+
+Los hooks de Git se ejecutan desde el directorio `.git` compartido. Si dos agentes
+ejecutan hooks simultáneamente puede haber condiciones de carrera. Usar ramas
+completamente independientes minimiza este riesgo.
+
+### Variables de entorno por worktree
+
+Cada proceso de agente debe tener `GIT_DIR` implícito resuelto desde su CWD, no
+configurado manualmente. Nunca exportar `GIT_DIR` de forma global si hay múltiples
+worktrees activos.
+
+---
+
+## Integración con agentes del sistema SWL
+
+### Estado en ESTADO.md por worktree
+
+Cada agente debe registrar en su `ESTADO.md` local:
+
+```markdown
+## Worktree
+- Ruta: /ruta/mi-app-agente-1
+- Rama: feature/modulo-usuarios
+- Worktree base: /ruta/mi-app (main @ abc1234)
+- Creado: 2026-03-25T10:00:00
+```
+
+### Protocolo de limpieza
+
+El agente coordinador (orquestador) es responsable de:
+1. Crear los worktrees ANTES de lanzar los agentes.
+2. Verificar que cada agente terminó (commit final presente).
+3. Mergear las ramas al trunk.
+4. Eliminar los worktrees con `git worktree remove`.
+5. Borrar las ramas de feature si ya fueron mergeadas.
+
+### Script de limpieza completa
+
+```bash
+#!/usr/bin/env bash
+# cleanup-worktrees.sh
+set -euo pipefail
+
+REPO_ROOT="/ruta/mi-app"
+cd "$REPO_ROOT"
+
+echo "Worktrees activos:"
+git worktree list
+
+echo "Limpiando worktrees terminados..."
+git worktree prune
+
+echo "Estado final:"
+git worktree list
+```
+
+---
+
+## Troubleshooting común
+
+### El worktree quedó en estado corrupto
+
+```bash
+# Verificar integridad
+git fsck
+
+# Si el directorio ya no existe pero el worktree está registrado
+git worktree prune --verbose
+```
+
+### Conflicto al intentar hacer checkout en el worktree principal
+
+```bash
+# Ver en qué worktree está cada rama
+git worktree list --porcelain
+
+# Ir al worktree donde está la rama y hacer el trabajo ahí
+cd /ruta/worktree-con-esa-rama
+```
+
+### Cambios sin commitear en un worktree al intentar eliminarlo
+
+```bash
+# Opción 1: Commitear antes
+cd ../mi-app-agente-1
+git stash  # o git commit
+
+# Opción 2: Forzar eliminación (se pierden cambios)
+cd /ruta/mi-app
+git worktree remove --force ../mi-app-agente-1
+```
+
+---
+
+## Resumen de comandos
+
+| Comando | Acción |
+|---------|--------|
+| `git worktree add <ruta> <rama>` | Crear worktree en rama existente |
+| `git worktree add -b <rama> <ruta>` | Crear worktree con rama nueva |
+| `git worktree list` | Listar todos los worktrees |
+| `git worktree remove <ruta>` | Eliminar worktree limpiamente |
+| `git worktree prune` | Limpiar referencias obsoletas |
+| `git worktree move <src> <dst>` | Mover worktree a nueva ruta |
+
+## Gotchas / Errores comunes no obvios
+
+**`git worktree add` falla con "fatal: already checked out" aunque la rama aparezca como no activa en `git branch`**: si un worktree anterior fue eliminado manualmente (borrando el directorio sin `git worktree remove`), Git mantiene la referencia del worktree en `.git/worktrees/` y cree que la rama sigue en uso. Causa: Git no detecta automáticamente que el directorio del worktree desapareció. Fix: ejecutar `git worktree prune` primero para limpiar referencias obsoletas, luego volver a intentar el `add`.
+
+**Las hooks de Git (pre-commit, pre-push) se ejecutan desde `.git/hooks/` compartido entre todos los worktrees y pueden fallar si usan rutas relativas al directorio del worktree principal**: los hooks que asumen que `$PWD` es el directorio raíz del repositorio principal fallan cuando se ejecutan desde un worktree secundario porque `$PWD` apunta al directorio del worktree hijo. Causa: los hooks no tienen acceso automático al worktree actual — solo a `$GIT_DIR` y `$GIT_WORK_TREE`. Fix: en los hooks, usar `git rev-parse --show-toplevel` para obtener el directorio del worktree actual en lugar de rutas hardcodeadas, y `git rev-parse --git-common-dir` para encontrar el `.git` compartido.
+
+**`git stash` en un worktree guarda el stash en el stash global del repositorio compartido, no en el worktree**: si el Agente 1 hace `git stash` en `mi-app-agente-1/` y luego el Agente 2 hace `git stash pop` en `mi-app-agente-2/`, aplica el stash del Agente 1 en la rama incorrecta. Causa: el stash de Git es una referencia global en `.git/refs/stash`, no por worktree. Fix: NUNCA usar `git stash` en flujos con múltiples worktrees. En su lugar, hacer un commit temporal con mensaje `WIP:` y usar `git reset HEAD~1` para deshacer cuando se necesite.
+
+**Eliminar un worktree con `git worktree remove --force` mientras hay un agente activo escribiendo archivos en ese directorio produce corrupción del objeto store de Git**: si el agente tiene archivos en proceso de escritura (commit parcial, `git add` pendiente) y otro proceso ejecuta `remove --force`, Git puede quedar con objetos huérfanos o referencias rotas. Causa: `--force` no verifica si hay procesos con file handles abiertos en el worktree. Fix: el orquestador debe verificar que cada agente emitió su commit final antes de ejecutar `git worktree remove`. Usar `git worktree list --porcelain` para confirmar que la rama del worktree tiene el commit esperado.