🤖 Loop Avancado: Orchestrator Multi-Agent

No nivel avancado, o input nao e mais um plan.md com 5 tarefas. E um spec document completo que descreve uma aplicacao inteira. O orchestrator le a spec, divide em rounds, e despacha workers para construir tudo.

"We send in our initial spec to the orchestrator and it has to reason about that and then figure out how many workers to spin off."

# 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 demonstrou exatamente esse cenario: "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." O orchestrator recebeu a spec e dividiu o trabalho em rounds automaticamente.

O orchestrator analisa a spec e decide a estrategia: quantos rounds, quantos workers por round, e quais tarefas cada worker recebe. Essa e a decisao mais critica do sistema, e por isso requer um modelo forte.

"The orchestrator is deciding how to split up the work right now. The orchestrator spent 6,000 tokens with that initial planning and then prompting our first three workers in round number one."

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 recebe uma tarefa especifica do orchestrator e opera em sessao propria com worktree e database branch isolados. Ao concluir, grava os resultados no state store (Postgres), nao no context window.

"Those workers are going to go back and they're going to update the state that we have in our database. And so this is our loop, right? Because then the next time the orchestrator runs, it's going to get that updated state from the 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.

Apos cada round, o orchestrator le os resultados do state store, valida se os criterios da spec foram atendidos, e decide se lanca outro round ou declara conclusao. Esse e o ponto de controle que diferencia um sistema robusto de um loop cego.

"It'll go round by round, doing validation each time. And we can even have human in the loop so that we get to actually take a look at what has happened in the first round before the orchestrator moves on to the next."

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

O human-in-the-loop (HITL) e o que separa um sistema confiavel de um experimento. Sem HITL, voce corre o risco de deixar o loop rodar por horas e voltar para descobrir que o resultado e inutilizavel.

"A lot of times people set up these systems to just go, go, go, go. And then you have a run for a day. And by the time it comes back, you just have crap."

O orchestrator multi-agent e o pico da complexidade. Questoes que surgem na pratica real.