elsabro 2.2.0 → 3.7.0

package/references/parallel-worktrees.md

@@ -0,0 +1,293 @@
+---
+name: parallel-worktrees
+description: Guia para trabajo paralelo con git worktrees en ELSABRO
+version: 1.0.0
+---
+
+# Trabajo Paralelo con Git Worktrees
+
+## Concepto
+
+Cuando ELSABRO ejecuta multiples agentes en paralelo, cada uno puede trabajar
+en su propio worktree de git para evitar conflictos de archivos.
+
+Un **worktree** es una copia de trabajo adicional del repositorio que comparte
+el mismo directorio `.git` pero tiene su propio directorio de trabajo y branch.
+
+## Beneficios
+
+- **Aislamiento**: Cada agente trabaja en archivos separados
+- **Sin conflictos**: No hay race conditions en archivos
+- **Merge controlado**: Los cambios se integran explicitamente
+- **Rollback facil**: Cada branch puede descartarse independientemente
+
+## Flujo Automatico
+
+```
+1. /elsabro:execute detecta wave con multiples planes
+   |
+2. Crea worktrees automaticos:
+   - elsabro-worktrees/analyst-wt/
+   - elsabro-worktrees/executor-wt/
+   - elsabro-worktrees/verifier-wt/
+   |
+3. Cada agente trabaja en su worktree aislado
+   |
+4. Al completar, merge automatico a branch principal
+   |
+5. Cleanup de worktrees temporales
+```
+
+## Estructura de Directorios
+
+```
+proyecto/                      # Repo principal
+  .git/                        # Git compartido
+  src/
+  ...
+
+elsabro-worktrees/             # Directorio de worktrees (hermano del repo)
+  analyst-wt/                  # Worktree del Analyst
+    src/
+    ...
+  executor-wt/                 # Worktree del Executor
+    src/
+    ...
+  verifier-wt/                 # Worktree del Verifier
+    src/
+    ...
+```
+
+## Comandos del Script
+
+### Crear Worktrees
+
+```bash
+# Crear worktrees para agentes especificos
+./scripts/setup-parallel-worktrees.sh create analyst executor
+
+# Crear worktrees para una wave completa
+./scripts/setup-parallel-worktrees.sh create analyst executor verifier
+```
+
+### Merge Trabajo
+
+```bash
+# Merge trabajo de agentes al branch actual
+./scripts/setup-parallel-worktrees.sh merge analyst executor
+
+# El merge usa --no-edit con mensaje automatico
+# Si hay conflictos, se pausa para resolucion manual
+```
+
+### Completar Wave
+
+```bash
+# Merge Y cleanup de una wave completa
+./scripts/setup-parallel-worktrees.sh complete analyst executor verifier
+
+# Equivalente a:
+#   merge analyst executor verifier
+#   cleanup analyst executor verifier
+```
+
+### Limpiar
+
+```bash
+# Limpiar worktrees especificos
+./scripts/setup-parallel-worktrees.sh cleanup analyst
+
+# Limpiar TODOS los worktrees de ELSABRO
+./scripts/setup-parallel-worktrees.sh cleanup
+```
+
+### Ver Estado
+
+```bash
+# Mostrar status de worktrees y branches
+./scripts/setup-parallel-worktrees.sh status
+
+# Listar worktrees activos (git nativo)
+./scripts/setup-parallel-worktrees.sh list
+```
+
+## Integracion con Orquestador
+
+El `elsabro-orchestrator` usa worktrees automaticamente cuando:
+
+1. **Multiples agentes en wave**: Hay mas de 1 agente en una wave
+2. **Archivos conflictivos**: Los agentes modifican archivos potencialmente compartidos
+3. **Profile careful**: Siempre aislado cuando profile es "careful"
+
+### Configuracion en SESSION-STATE.json
+
+```json
+{
+  "parallel": {
+    "useWorktrees": true,
+    "activeWorktrees": [
+      {
+        "agent": "analyst",
+        "path": "../elsabro-worktrees/analyst-wt",
+        "branch": "elsabro/analyst"
+      },
+      {
+        "agent": "executor",
+        "path": "../elsabro-worktrees/executor-wt",
+        "branch": "elsabro/executor"
+      }
+    ]
+  }
+}
+```
+
+## Resolucion de Conflictos
+
+Si hay conflictos en el merge:
+
+### Flujo Automatico
+
+1. ELSABRO pausa la ejecucion
+2. Muestra los conflictos al usuario
+3. Presenta opciones interactivas
+
+### Opciones del Usuario
+
+```
+Conflictos detectados en merge de 'executor':
+
+Archivos en conflicto:
+  - src/api/user.ts
+  - src/utils/validation.ts
+
+Opciones:
+  [r] Resolver manualmente (abre editor)
+  [k] Keep mine (descartar cambios del agente)
+  [t] Take theirs (aceptar cambios del agente)
+  [a] Abort (cancelar merge, mantener worktree)
+```
+
+### Resolucion Manual
+
+```bash
+# Navegar al repo principal
+cd proyecto
+
+# Ver conflictos
+git status
+
+# Editar archivos conflictivos
+# (buscar marcadores <<<<<<<, =======, >>>>>>>)
+
+# Marcar como resueltos
+git add src/api/user.ts
+
+# Completar merge
+git commit
+```
+
+## Limites y Requisitos
+
+### Requisitos
+
+- **Git >= 2.15**: Soporte completo de worktrees
+- **Espacio en disco**: Cada worktree es una copia de trabajo completa
+- **Permisos**: Escritura en directorio padre del repo
+
+### Limites
+
+| Limite | Valor | Razon |
+|--------|-------|-------|
+| Worktrees simultaneos | 5 | Performance y recursos |
+| Ubicacion | `../elsabro-worktrees/` | Relativo al repo |
+| Branches | `elsabro/*` | Namespace aislado |
+
+### Verificar Requisitos
+
+```bash
+# Version de git
+git --version
+# Debe ser >= 2.15
+
+# Espacio disponible
+df -h .
+
+# Permisos
+ls -la ..
+```
+
+## Troubleshooting
+
+### Worktree Huerfano
+
+```bash
+# Si un worktree queda en estado inconsistente
+git worktree prune
+
+# Forzar cleanup
+./scripts/setup-parallel-worktrees.sh cleanup
+```
+
+### Branch No Existe
+
+```bash
+# Error: Branch elsabro/analyst no existe
+# Solucion: Crear worktree de nuevo
+./scripts/setup-parallel-worktrees.sh create analyst
+```
+
+### Merge Fallido
+
+```bash
+# Cancelar merge en progreso
+git merge --abort
+
+# Limpiar y reintentar
+./scripts/setup-parallel-worktrees.sh cleanup analyst
+./scripts/setup-parallel-worktrees.sh create analyst
+# Re-ejecutar trabajo del agente
+```
+
+### Directorio Base No Existe
+
+```bash
+# El script crea automaticamente el directorio
+# Si hay problemas de permisos:
+mkdir -p ../elsabro-worktrees
+chmod 755 ../elsabro-worktrees
+```
+
+## Ejemplo Completo
+
+```bash
+# 1. Iniciar wave paralela
+./scripts/setup-parallel-worktrees.sh create analyst executor verifier
+
+# 2. Ver estado
+./scripts/setup-parallel-worktrees.sh status
+
+# Worktrees activos:
+# /path/to/project                    abc1234 [main]
+# /path/to/elsabro-worktrees/analyst-wt  abc1234 [elsabro/analyst]
+# /path/to/elsabro-worktrees/executor-wt abc1234 [elsabro/executor]
+# /path/to/elsabro-worktrees/verifier-wt abc1234 [elsabro/verifier]
+
+# 3. Agentes trabajan en sus worktrees...
+
+# 4. Completar wave (merge + cleanup)
+./scripts/setup-parallel-worktrees.sh complete analyst executor verifier
+
+# 5. Verificar
+git log --oneline -5
+# abc1234 Merge: ELSABRO verifier parallel work
+# def5678 Merge: ELSABRO executor parallel work
+# ghi9012 Merge: ELSABRO analyst parallel work
+```
+
+## Mejores Practicas
+
+1. **Siempre usar `complete`**: Combina merge y cleanup en un paso
+2. **Verificar antes de merge**: Revisar cambios con `git diff elsabro/agent`
+3. **Cleanup regular**: No dejar worktrees huerfanos
+4. **Commits atomicos**: Cada agente debe hacer commits completos
+5. **Mensajes descriptivos**: Los commits en worktrees deben ser claros