swl-ses 3.3.2

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

@@ -0,0 +1,246 @@
+---
+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.
+---
+
+# Git Worktrees para Ejecución Paralela
+
+## 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 STATE.md por worktree
+
+Cada agente debe registrar en su `STATE.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 |