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

version, updated, tags

version	updated	tags
1.0.0	2026-03-11	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

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

/issues:execute-parallel

Ejemplo 2: Ejecutar solo el Grupo 1

/issues:execute-parallel --group 1

Ejemplo 3: Ejecutar TODOS los grupos secuencialmente (sin paralelismo)

/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

# 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

# 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

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

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:

/issues:parallel

Advertencia: "Quedaron N worktrees sin limpiar"

Causa: Alguna issue falló y el worktree no pudo ser limpiado

Solución:

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