Añadidos arhcivos basicos de repos

2026-03-18 21:27:21 +01:00
commit 4bc7a7d291
31 changed files with 6506 additions and 0 deletions
@@ -0,0 +1,359 @@
+---
+version: 1.0.0
+updated: 2026-03-11
+tags: [issues, parallel, execution, automation, worktree, golang]
+---
+
+# Command: execute-parallel-issues
+
+Ejecuta automáticamente las issues de un grupo paralelo del plan generado por `/issues:parallel`. Crea worktrees, ejecuta `/issues:fix-issue` en cada uno, mergea los cambios y limpia los worktrees al finalizar.
+
+**Flujo completo:**
+1. Validar que existe `PARALLEL_EXECUTION_ORDER.md`
+2. Compilar programa Go si es necesario
+3. Ejecutar el orquestador Go para el grupo especificado
+4. El programa Go maneja:
+   - Creación de worktrees y ramas
+   - Ejecución paralela de `claude -p /issues:fix-issue`
+   - Push de cada rama al completar
+   - Limpieza de worktrees y ramas
+   - Logging estructurado en `logs/`
+
+## Para el usuario
+
+### Cuándo usar este comando
+
+- Después de ejecutar `/issues:parallel` y revisar el plan
+- Cuando quieres ejecutar issues automáticamente
+- Para aprovechar la ejecución paralela de issues independientes
+- Cuando prefieres automatización completa vs ejecutar manualmente cada issue
+
+### Sintaxis
+
+```bash
+# Ejecutar TODOS los grupos secuencialmente (por defecto)
+/issues:execute-parallel [--sequential]
+
+# Ejecutar un grupo específico
+/issues:execute-parallel --group <numero> [--sequential]
+```
+
+### Parámetros
+
+- `--group <numero>` (opcional): Ejecutar solo un grupo específico (1, 2, 3, etc.). Si no se especifica, ejecuta TODOS los grupos.
+- `--sequential` (opcional): Ejecutar issues una por una en vez de en paralelo
+
+### Ejemplos
+
+**Ejemplo 1: Ejecutar TODOS los grupos (comportamiento por defecto)**
+
+```bash
+/issues:execute-parallel
+```
+
+**Ejemplo 2: Ejecutar solo el Grupo 1**
+
+```bash
+/issues:execute-parallel --group 1
+```
+
+**Ejemplo 3: Ejecutar TODOS los grupos secuencialmente (sin paralelismo)**
+
+```bash
+/issues:execute-parallel --sequential
+```
+
+Comportamiento por defecto:
+- Ejecuta todos los grupos secuencialmente: Grupo 1 → Grupo 2 → Grupo 3 → etc.
+- Dentro de cada grupo, las issues se ejecutan en paralelo
+- Genera resumen consolidado de TODOS los grupos al final
+- Log detallado en `logs/consolidated-summary.txt`
+
+## Para Claude
+
+### Precondiciones
+
+Verificar antes de ejecutar:
+
+- [ ] Si no existe `PARALLEL_EXECUTION_ORDER.md`, generarlo automáticamente con `/issues:parallel`
+- [ ] El usuario está en la rama correcta (usualmente `main`)
+- [ ] No hay cambios sin commitear que puedan causar conflictos
+
+### Inputs
+
+**Por defecto, ejecuta TODOS los grupos automáticamente.** No es necesario preguntar al usuario.
+
+Parámetros opcionales:
+- `--group <numero>` (opcional): Ejecutar solo un grupo específico
+- `--sequential` (opcional): Ejecutar secuencialmente en vez de en paralelo
+
+**IMPORTANTE:** Si no se especifica `--group`, ejecuta todos los grupos automáticamente.
+
+### Flujo obligatorio
+
+#### 1. Validar precondiciones
+
+```bash
+# Verificar que existe el plan, si no existe, generarlo automáticamente
+if [ ! -f "PARALLEL_EXECUTION_ORDER.md" ]; then
+  echo "📋 PARALLEL_EXECUTION_ORDER.md no existe, generando plan automáticamente..."
+  echo ""
+
+  # Ejecutar /issues:parallel para generar el plan
+  claude -p /issues:parallel
+
+  # Verificar que se generó correctamente
+  if [ ! -f "PARALLEL_EXECUTION_ORDER.md" ]; then
+    echo "❌ Error: No se pudo generar PARALLEL_EXECUTION_ORDER.md"
+    exit 1
+  fi
+
+  echo ""
+  echo "✓ Plan de ejecución generado exitosamente"
+  echo ""
+fi
+
+# Verificar que no hay cambios sin commitear (solo advertir, no bloquear)
+UNCOMMITTED=$(git status --porcelain | wc -l)
+if [ "$UNCOMMITTED" -gt 0 ]; then
+  echo "⚠️  Advertencia: Hay cambios sin commitear"
+  git status --short
+  echo ""
+  echo "Continuando de todas formas..."
+  echo ""
+fi
+```
+
+#### 2. Parsear argumentos
+
+```bash
+# Por defecto ejecutar todos los grupos
+GRUPO=""
+ALL_GROUPS=true
+SEQUENTIAL=false
+
+# Parsear argumentos
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --group)
+      if [ -z "$2" ] || [[ ! "$2" =~ ^[0-9]+$ ]]; then
+        echo "Error: --group requiere un número"
+        exit 1
+      fi
+      GRUPO=$2
+      ALL_GROUPS=false
+      shift 2
+      ;;
+    --sequential)
+      SEQUENTIAL=true
+      shift
+      ;;
+    *)
+      echo "Error: Flag desconocido '$1'"
+      echo "Uso: /issues:execute-parallel [--group <numero>] [--sequential]"
+      exit 1
+      ;;
+  esac
+done
+```
+
+#### 3. Ejecutar programa Go
+
+```bash
+echo ""
+
+# Mensaje de inicio
+if [ "$ALL_GROUPS" = true ]; then
+  echo "🚀 Iniciando ejecución de TODOS los grupos secuencialmente"
+else
+  echo "🚀 Iniciando ejecución paralela del Grupo $GRUPO"
+fi
+
+echo ""
+
+# Construir argumentos para el programa Go
+if [ "$ALL_GROUPS" = true ]; then
+  ARGS="--all-groups"
+else
+  ARGS="--group $GRUPO"
+fi
+
+if [ "$SEQUENTIAL" = true ]; then
+  ARGS="$ARGS --sequential"
+fi
+
+# Ejecutar el orquestador
+./cmd/parallel-executor/parallel-executor $ARGS
+
+EXIT_CODE=$?
+
+# Verificar resultado
+if [ $EXIT_CODE -eq 0 ]; then
+  echo ""
+  echo "✓ Ejecución completada exitosamente"
+  echo ""
+
+  if [ "$ALL_GROUPS" = true ]; then
+    echo "Logs guardados en:"
+    echo "  - logs/parallel-execution-*.log (logs individuales)"
+    echo "  - logs/consolidated-summary.txt (resumen consolidado)"
+  else
+    echo "Logs guardados en: logs/parallel-execution-*.log"
+  fi
+
+  # Eliminar el archivo PARALLEL_EXECUTION_ORDER.md después de ejecución exitosa
+  if [ -f "PARALLEL_EXECUTION_ORDER.md" ]; then
+    rm -f PARALLEL_EXECUTION_ORDER.md
+    echo ""
+    echo "✓ Plan de ejecución eliminado (PARALLEL_EXECUTION_ORDER.md)"
+  fi
+else
+  echo ""
+  echo "❌ Ejecución falló con código $EXIT_CODE"
+  echo ""
+  echo "Revisa los logs para más detalles:"
+  echo "  ls -lt logs/parallel-execution-*.log | head -1"
+  exit $EXIT_CODE
+fi
+```
+
+#### 4. Mostrar resumen
+
+```bash
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Resumen de ejecución:"
+echo ""
+
+# El programa Go debe generar un archivo de resumen
+if [ -f "logs/last-execution-summary.txt" ]; then
+  cat logs/last-execution-summary.txt
+fi
+
+echo ""
+echo "Estado de worktrees:"
+git worktree list | grep -v "(bare)" || echo "  (ninguno - todos limpiados)"
+
+echo ""
+echo "Próximos pasos:"
+echo "  1. Verificar que todas las issues fueron mergeadas"
+if [ "$ALL_GROUPS" = false ]; then
+  echo "  2. Si el Grupo $GRUPO fue exitoso, ejecutar siguiente grupo"
+fi
+echo "  3. Si hubo errores, revisar logs y reintentar"
+```
+
+### Arquitectura del programa Go
+
+El comando invoca un programa Go en `cmd/parallel-executor/` con la siguiente estructura:
+
+```
+cmd/parallel-executor/
+├── main.go              → Entry point, parseo de CLI
+├── parser.go            → Parse PARALLEL_EXECUTION_ORDER.md
+├── worktree.go          → Git worktree operations (shell layer)
+├── executor.go          → Execute claude commands (shell layer)
+├── logger.go            → Structured logging
+├── orchestrator.go      → Orchestration logic con goroutines
+└── types.go             → Estructuras de datos (core types)
+```
+
+**Responsabilidades del programa Go:**
+
+1. **Parser** (`parser.go`):
+   - Leer `PARALLEL_EXECUTION_ORDER.md`
+   - Extraer issues del grupo especificado
+   - Parsear archivos afectados, dependencias, etc.
+
+2. **Worktree Manager** (`worktree.go`):
+   - Crear worktrees: `git worktree add worktrees/issue-NNNN -b issue/NNNN-slug`
+   - Eliminar worktrees después de merge
+   - Verificar estado de worktrees
+
+3. **Executor** (`executor.go`):
+   - Ejecutar `claude -p /issues:fix-issue NNNN` en cada worktree
+   - Capturar output en tiempo real
+   - Detectar éxito/fallo del comando
+   - Ejecutar `/git:push` al completar exitosamente
+
+4. **Logger** (`logger.go`):
+   - Logging estructurado con timestamps
+   - Archivo por ejecución: `logs/parallel-execution-YYYYMMDD-HHMMSS.log`
+   - Output a consola + archivo simultáneamente
+   - Niveles: INFO, WARN, ERROR, SUCCESS
+
+5. **Orchestrator** (`orchestrator.go`):
+   - Coordinar goroutines para ejecución paralela
+   - Manejar canales de comunicación entre workers
+   - Recolectar resultados y errores
+   - Implementar timeout por issue (configurable)
+   - Rollback en caso de fallo crítico
+
+**Flujo del programa Go:**
+
+```
+1. Parse CLI args (grupo, flags)
+2. Parse PARALLEL_EXECUTION_ORDER.md
+3. Extraer issues del grupo especificado
+4. Para cada issue en el grupo:
+   4.1. Crear worktree + rama
+   4.2. En el worktree:
+        → cd worktrees/issue-NNNN
+        → claude -p /issues:fix-issue NNNN
+        → Esperar a que termine
+        → Si exitoso: ejecutar /git:push
+        → Si fallo: reportar error y continuar
+   4.3. Limpiar worktree y rama
+5. Generar resumen de ejecución
+6. Return exit code (0 si todo OK, 1 si hubo errores)
+```
+
+### Verificación final
+
+El programa Go se encarga de limpiar los worktrees automáticamente. El resumen final mostrará el estado de todas las ejecuciones.
+
+## Convenciones
+
+- **Logs persistentes:** Cada ejecución genera un archivo en `logs/parallel-execution-YYYYMMDD-HHMMSS.log`
+- **Resumen ejecutivo:** Archivo `logs/last-execution-summary.txt` con métricas clave
+- **Timeouts:** 30 minutos por issue por defecto (configurable en código Go)
+- **Paralelismo:** Por defecto ejecuta issues en paralelo con `runtime.NumCPU()` goroutines
+- **Limpieza automática:** Siempre limpia worktrees al terminar (éxito o fallo)
+- **Eliminación del plan:** El archivo `PARALLEL_EXECUTION_ORDER.md` se elimina automáticamente al completar exitosamente
+
+## Troubleshooting
+
+### Error: "No existe PARALLEL_EXECUTION_ORDER.md"
+
+**Causa:** No se ha generado el plan de ejecución paralela
+
+**Solución:**
+El comando genera automáticamente el plan si no existe. Si este error persiste:
+```bash
+/issues:parallel
+```
+
+### Advertencia: "Quedaron N worktrees sin limpiar"
+
+**Causa:** Alguna issue falló y el worktree no pudo ser limpiado
+
+**Solución:**
+```bash
+# Revisar el error en los logs
+cat logs/parallel-execution-*.log | grep ERROR
+
+# Limpiar manualmente
+/workspace:cleanup-worktrees --all
+```
+
+## Reglas críticas
+
+- **SIEMPRE generar plan automáticamente** si no existe `PARALLEL_EXECUTION_ORDER.md`
+- **SIEMPRE ejecutar todos los grupos por defecto** - no preguntar al usuario
+- **SOLO advertir si hay cambios sin commitear** - nunca bloquear la ejecución
+- **SIEMPRE capturar logs** en archivo persistente
+- **SIEMPRE limpiar worktrees** incluso si hubo errores (usar defer en Go)
+- **NUNCA bloquear indefinidamente** - implementar timeouts razonables
+- **SIEMPRE reportar progreso** en tiempo real
+- **SIEMPRE eliminar el plan** después de ejecución exitosa
+- **VERIFICAR estado de git** antes de la ejecución (solo advertencia, no bloqueante)