🤖 Loop avanzado: Orchestrator Multi-Agent

En el nivel avanzado, el input ya no es un plan.md con 5 tareas. Es un documento completo de spec que describe una aplicación completa. El orchestrator lee la spec, la divide en rounds y envía workers para construirlo todo.

"Enviamos nuestra especificación inicial al orquestador y este tiene que analizarla y decidir cuántos workers iniciar."

# Spec: Single Page Kanban Board

## Objetivo
Criar um Kanban board como web app estatico (HTML + CSS + JS).

## Requisitos
- 3 colunas: To Do, In Progress, Done
- Drag and drop entre colunas
- Persistencia via localStorage
- Responsivo (mobile-first)
- Tema dark com cores amber/neutral

## Criterios de Aceitacao
- App carrega sem erros no browser
- Drag and drop funcional
- Dados persistem apos reload
- Layout correto em mobile (320px+)

Cole Medin demostró exactamente este escenario: "building a single page Kanban board as a static web app, I just take this prompt and I'll show you it running live right now." El orchestrator recibió la spec y dividió el trabajo en rounds automáticamente.

El orchestrator analiza la spec y decide la estrategia: cuántas rondas, cuántos workers por ronda y qué tareas recibe cada worker. Esta es la decisión más crítica del sistema y por eso requiere un modelo potente.

"El orquestador está decidiendo cómo dividir el trabajo ahora mismo. Usó 6,000 tokens en la planificación inicial y luego en las instrucciones para nuestros primeros tres workers de la primera ronda."

You are the orchestrator for a multi-agent build system.

Input: spec.md (attached)
State store: Postgres (Neon) at DATABASE_URL

Your job:
1. Read spec.md and break it into independent work units
2. Plan rounds: group units that can run in parallel
3. For each round, dispatch workers with specific prompts
4. After each round, read worker results from state store
5. Validate: does the output match spec requirements?
6. If validation passes, plan next round. If fails, retry or escalate.
7. When all spec requirements are met, report completion.

Pause for human approval before starting each new round.

Cada worker recibe una tarea específica del orquestador y opera en sesión propia con una worktree y una rama de base de datos aisladas. Al terminar, guarda los resultados en el almacén de estado (Postgres), no en la ventana de contexto.

"Esos workers volverán y actualizarán el estado que tenemos en nuestra base de datos. Y ese es nuestro loop, ¿verdad? Porque la próxima vez que se ejecute el orquestador, recibirá el estado actualizado de los workers."

You are Worker {{worker_id}} in Round {{round_number}}.

Your task: {{task_description}}
Spec context: {{relevant_spec_section}}
Previous round results: {{previous_results_summary}}

Instructions:
1. Execute the task in your worktree
2. Run validation: {{validation_command}}
3. Report results to state store:
   - Status: success/failure
   - Files changed: list
   - Test results: pass/fail count
   - Notes: any issues encountered

Do NOT modify files outside your assigned scope.

Después de cada round, el orchestrator lee los resultados del state store, valida si se cumplieron los criterios de la spec y decide si inicia otro round o declara que terminó. Ese es el punto de control que diferencia un sistema robusto de un loop ciego.

"Avanzará ronda por ronda y validará en cada una. Incluso podemos incluir a una persona en el proceso para revisar lo que ocurrió en la primera ronda antes de que el orquestador pase a la siguiente."

After Round {{N}} completes:

1. Query state store for all worker results in this round
2. Check: did all workers report success?
   - If any failed: retry failed workers (max 2 retries)
   - If still failing: pause and escalate to human
3. Check: do combined results satisfy spec requirements?
   - Run integration tests across merged worktrees
   - Compare output against spec acceptance criteria
4. If all good: plan Round {{N+1}} with remaining work
5. If spec is fully satisfied: merge all branches, report done

El human-in-the-loop (HITL) es lo que separa un sistema confiable de un experimento. Sin HITL, corres el riesgo de dejar que el loop se ejecute durante horas y volver para descubrir que el resultado no sirve.

"Muchas veces la gente configura estos sistemas para que sigan, sigan, sigan y sigan. Luego los deja funcionando durante un día. Y cuando vuelve, solo encuentra basura."

El orchestrator multi-agent es el punto máximo de complejidad. Preguntas que surgen en la práctica real.