---
name: handoff-multiagente
description: Delegar tareas desde un agente orquestador a agentes ejecutores especializados (código / volumen-contenido) vía cola en disco, con lanzamiento en background por Bash y aviso automático al terminar.
---

# Handoff a agentes ejecutores especializados

Patrón para coordinar un orquestador con dos (o más) agentes ejecutores, sin que el usuario tenga que copiar y pegar prompts manualmente ni que las tareas se pisen entre sí.

## Roles

- **Orquestador**: recibe la petición, la descompone en una tarea acotada, escribe la tarea en la cola, lanza al ejecutor, valida el resultado final contra el estado real del proyecto (nunca acepta a ciegas lo que el ejecutor reporta).
- **Ejecutor de código**: cambios estructurales, lógica de aplicación, refactors.
- **Ejecutor de volumen/contenido**: generación de datos en bloque, redacción repetitiva, traducciones.

## 1. Cola de trabajo en disco

Cada tarea es un archivo `.md` autocontenido (no depende de memoria de conversación):

```
cola/
  pendiente/   -> tareas por procesar
  hecho/       -> tareas terminadas (se mueven, no se borran ni se editan)
  salida/      -> resúmenes y artefactos generados por el ejecutor
```

Reglas del ejecutor (documentarlas en un archivo de instrucciones fijo que el ejecutor lea siempre antes de trabajar):

- Procesar una tarea a la vez, en orden, nunca en paralelo consigo mismo.
- Nunca modificar el archivo de la tarea — solo moverlo de `pendiente/` a `hecho/` al terminar.
- Guardar cualquier resultado en disco, nunca solo en el chat.
- Si queda algo a medias, dejar la tarea en `pendiente/` y anotar por qué en el resumen.
- Escribir siempre un resumen en `salida/` con nombre predecible — es la señal de "terminé", no la simple aparición de cualquier archivo.

## 2. Lanzar el ejecutor por Bash en background

Dos detalles no negociables: desacoplar stdin (si el proceso espera una entrada que nunca llega, se cuelga) y `disown` (desliga el proceso del shell padre, así el aviso de "se lanzó" no se confunde con "terminó").

```bash
<comando-del-ejecutor> \
  --output "cola/salida/log-<tarea>.md" \
  "Lee y sigue las instrucciones de cola/INSTRUCCIONES.md \
   para procesar la tarea pendiente cola/pendiente/<archivo-tarea>.md" \
  < /dev/null > "cola/log-proceso-<tarea>.log" 2>&1 &
disown
```

Que el lanzamiento no dé error solo confirma que el proceso arrancó — no que la tarea esté hecha.

## 3. Observador: enterarse sin hacer polling agresivo

Vigilar una señal de finalización explícita y única, no cualquier archivo nuevo (el ejecutor puede dejar artefactos intermedios mientras sigue trabajando).

```bash
while true; do
  if [ -e "cola/salida/resumen-<tarea>.md" ]; then
    echo "TAREA TERMINADA"
    break
  fi
  sleep 10
done
```

Cuando aparece la señal: leer el resumen, validar el resultado contra el código/archivo real (build, grep, lectura directa), y solo entonces dar la tarea por cerrada.

## 4. Evitar que dos tareas se crucen

- Un solo ejecutor procesando la cola a la vez.
- Nunca reencolar ni relanzar una tarea "porque tarda" — lento no es igual a fallido.
- Si dos orquestadores/sesiones pueden escribir en la misma cola, usar un candado simple (archivo de lock) antes de lanzar un nuevo proceso sobre la misma carpeta `pendiente/`.

## 5. Reglas compartidas como fuente única

Las convenciones del proyecto (qué no tocar, formato de salida esperado, idioma, etc.) viven en **un solo archivo de instrucciones**, referenciado por ruta explícita en cada prompt de lanzamiento — nunca reescritas a mano en cada tarea. Actualizar la regla una vez, en un solo lugar, para que todos los ejecutores queden sincronizados.

## 6. Registro de avance

Mantener el estado de las tareas delegadas en un tablero externo (Kanban o similar), no solo en la cola en disco — permite retomar el proyecto sin depender de memoria de conversación.