repo_Claude/.claude/commands/issues/execute-parallel.md

---
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)