#2 Plan-and-Solve / ReWOO

Plan-and-Solve sintetiza um plano estruturado antes do orquestrador começar a despachar. ReWOO (Reasoning Without Observation) estende: o plano usa placeholders #E1, #E2 que são resolvidos em runtime com os outputs dos passos anteriores. Combinados, evitam o padrão caro de “despachar um agente, esperar, pensar de novo, despachar outro”.

Quando ativa: /plan <task> força; CHATCLI_QUALITY_PLAN_FIRST_MODE=always sempre; auto (default) dispara quando ComplexityScore(task) >= 6. Para revisar o plano antes de executar, use /plan preview <task> (dry-run).

Formato do plano

O PlannerAgent, quando recebe a marcação PlannerStructuredOutputDirective no início da task, emite JSON estrito:

{
  "task_summary": "Add OAuth login with Google",
  "steps": [
    {"id": "E1", "agent": "search", "task": "Find existing auth code in cli/auth"},
    {"id": "E2", "agent": "planner", "task": "Design integration plan based on #E1", "deps": ["E1"]},
    {"id": "E3", "agent": "coder",   "task": "Implement based on #E2", "deps": ["E2"]},
    {"id": "E4", "agent": "tester",  "task": "Write tests for #E3", "deps": ["E3"]}
  ],
  "parallel_groups": [["E1"], ["E2"], ["E3", "E4"]]
}

Placeholders ReWOO

Qualquer passo pode injetar output de passos anteriores via #E<n>:

Sintaxe	Efeito
`#E1`	Substitui pelo output trimmed completo
`#E1.summary`	Primeira linha não vazia do output
`#E1.head=200`	Primeiros 200 runes com `…` se truncado
`#E1.last=200`	Últimos 200 runes com `…` no início

Use .head=N para tarefas grandes (ex: “dado este log #E1.head=500, diagnostique”) para bound o contexto que o próximo passo vê.

Heurística de complexidade

A função ComplexityScore(task) → int[0,10] é calibrada para disparar Plan-First só quando paga. O score blends três sinais:

Sinal	Cap	O que conta
Verbos de ação	5	`implement, add, create, fix, refactor, write, test, deploy, build, run, update, …` — bilíngue (en + pt-BR: `implementar, adicionar, criar, corrigir, escrever, …`)
Artefatos de arquivo	3	Matches em `\b[\w./-]+\.(go\|ts\|py\|md\|yaml\|…)\b` + `Dockerfile\|Makefile\|…`
Sequenciadores	2	`then, after, finally, e depois, e em seguida, por fim, após, …`

Exemplos

Trivial (score 1)
Multi-action (score 6+)
PT-BR (score 6+)

read main.go

auto não dispara Plan-First. Orquestrador lida direto.

update auth.go and add tests/auth_test.go then run go test

auto dispara Plan-First. 3 verbos (update, add, run) + 2 arquivos + 1 sequenciador = score 6.

criar handler em api.go e adicionar testes em api_test.go depois rodar go test

Idêntico ao anterior — bilíngue por design.

Fluxo de execução

Usuário dispara /agent ou /coder

A tarefa vai para AgentMode.Run().

runPlanFirstIfApplicable

Checa cli.pendingPlanFirst (one-shot) ou quality.ShouldPlanFirst(cfg, userQuery).

Planner dispatch

agentDispatcher.Dispatch([{Agent: planner, Task: PlannerStructuredOutputDirective + userQuery}]).

ParsePlan

Tolerante a markdown code fences e trailing prose. Valida: IDs únicos, deps apontam para passos anteriores, placeholders #E<n> apontam para IDs declarados.

TopologicalOrder + Execute

Ordem topológica estável (sort lex em ties) garante reprodutibilidade. Cada passo: resolve placeholders → dispatcher.Dispatch → armazena output.

Inject report

Dois messages sintéticos vão para cli.history:

assistant: o JSON do plano (o modelo vê o que foi tentado)
user: FinalReport determinístico com task/agent/status/output por passo + handoff

O segundo message é role=user (não system) desde o fix de abril/2026. Modelos como Claude Sonnet 4.6 recusam completion quando a conversa termina em assistant (“This model does not support assistant message prefill”). O turno de usuário sintético fecha a conversa corretamente e dá ao orquestrador um ponto-âncora explícito para finalizar.

ReAct loop continua (ou pula, se dry-run)

Com o report em history, o orquestrador finaliza sem re-executar os passos já concluídos. Em modo dry-run (/plan preview), o loop é pulado via planDryRunHandled — nenhuma chamada ao orquestrador é feita.

Tolerância a falhas

Um passo que falha não aborta a run. O comportamento é “continue downstream with substituted error”:

// cli/agent/quality/plan_runner.go:126
if res.Error != nil {
    hadErrors = true
    outputs[id] = fmt.Sprintf("<error: %s>", res.Error.Error())
    // continua — passos downstream verão a string "<error: …>" substituída em seus placeholders
}

Isso espelha como o orquestrador já reage a erros per-agent hoje (continua, sumariza, faz o modelo decidir). O flag HadErrors é setado para Reflexion decidir se escala.

`/plan` — invocação manual

O comando /plan aceita seis formas. Autocomplete (Tab) oferece os subcomandos.

/plan
# → "plan-first armado — seu próximo /agent ou /coder rodará um plano estruturado"
/agent refatorar auth package para usar OAuth
# → roda Plan-First mesmo se complexity score < threshold

# também funciona com /coder — o flag é consumido na primeira invocação subsequente

/plan refatorar auth package para usar OAuth
# → entra direto em agent mode com Plan-First armado e executa

# Equivalente explícito:
/plan agent refatorar auth package para usar OAuth

/plan coder refatorar auth package para usar OAuth
# → entra em coder mode (CoderSystemPrompt) com Plan-First armado e executa
# Recomendado para tarefas que modificam arquivos / rodam builds

/plan preview refatorar auth package para usar OAuth
# → roda só o PlannerAgent, renderiza o plano estruturado, NÃO executa nenhum passo
# Nenhuma chamada ao orquestrador é feita — ideal para revisar antes de commitar

# Alias:
/plan dry refatorar auth package para usar OAuth

Matriz de comportamento

Forma	Entra em	Executa passos?	Chama orquestrador?	Quando usar
`/plan`	— (arma flag)	depende do próximo `/agent` ou `/coder`	sim	Quer controle manual do modo consumidor
`/plan <task>`	agent	sim	sim	Fluxo padrão, mais rápido
`/plan agent <task>`	agent	sim	sim	Equivalente explícito (simetria com `coder`)
`/plan coder <task>`	coder	sim	sim	Tarefas de engenharia (edições, builds, testes)
`/plan preview <task>`	agent (temporário)	não	não	Revisar plano antes de rodar
`/plan dry <task>`	idem `preview`	não	não	Alias

O flag cli.pendingPlanFirst é consumido e cleared na primeira invocação de /agent ou /coder subsequente. O flag cli.pendingPlanDryRun (exclusivo dos modos preview/dry) é limpo no mesmo ponto e faz AgentMode.Run retornar antes do ReAct loop via planDryRunHandled.

Fluxo recomendado para mudanças grandes: /plan preview <task> primeiro → revise o JSON → se aprovado, rode /plan coder <mesma task>.

Variáveis de ambiente

Env var	Default	Valores	Efeito
`CHATCLI_QUALITY_PLAN_FIRST_MODE`	`auto`	`off\|auto\|always`	Modo de disparo
`CHATCLI_QUALITY_PLAN_FIRST_THRESHOLD`	`6`	0..10	Score mínimo para `auto` disparar

Override por persona (CHATCLI_AGENT_PLANNER_*)

O PlannerAgent respeita os overrides usuais de agent:

# Forçar planner a usar Opus com thinking máximo
export CHATCLI_AGENT_PLANNER_MODEL="claude-opus-4-8"
export CHATCLI_AGENT_PLANNER_EFFORT="max"

Observabilidade

Cada run emite logs estruturados:

{"level":"info","msg":"Plan-First triggered","forced":false,"mode":"auto","complexity":7}
{"level":"info","msg":"plan step dispatching","id":"E1","agent":"search","task":"Find existing..."}
{"level":"info","msg":"plan step dispatching","id":"E2","agent":"planner","task":"Design based on found auth code"}
{"level":"warn","msg":"plan step failed","id":"E3","agent":"coder","error":"timeout"}

E imprime no terminal um one-liner amigável:

  plan-first executed 4 step(s) before handing off to the orchestrator

Spinner durante Plan-First

O spinner “planning structured steps…” aparece somente durante a chamada pura do PlannerAgent (step 1). Durante a execução do PlanRunner (step 2), o spinner é intencionalmente desligado e um print estático é emitido:

  executing structured plan...

Isso é crítico para segurança: passos podem disparar approvals interativos (ShellAgent exec, CoderAgent write) via policy engine. Se o spinner ficasse ativo durante a execução, seu repaint \r\033[K sobrescreveria o prompt de aprovação e impediria a resposta. Ctrl+C continua cancelando normalmente — o ctx cancelado propaga para dispatcher e PlanRunner entre passos.

Modo dry-run: o que é renderizado

/plan preview <task> renderiza:

  Plano gerado (dry-run — nada será executado)

  Resumo: <task_summary do JSON>

  1. [E1] agent=search
     <task resolvida>
  2. [E2] agent=planner
     <task>
     deps: E1
  3. [E3] agent=coder
     <task>
     deps: E2

  Grupos paralelizáveis:
     [E1]
     [E2]
     [E3]

  Para executar este plano: /plan <mesma tarefa> (ou /plan coder <tarefa>)

Se o ParsePlan falhar (planner devolveu JSON malformado ou prose), o output bruto é impresso com um aviso — nunca é silencioso.

Quando desligar

Plan-First acrescenta +1 chamada LLM (o planner) por turn disparado. Em ambientes com budget apertado, off ou threshold=8 economizam.

# off: nunca dispara, mesmo com /plan
export CHATCLI_QUALITY_PLAN_FIRST_MODE=off

# threshold alto: só dispara em tarefas muito complexas
export CHATCLI_QUALITY_PLAN_FIRST_THRESHOLD=9

#3 Reflexion

Reflexion consome HadErrors do plan runner para gerar lições quando passos falham.

Multi-Agent Orchestration

O dispatcher que Plan-Runner reutiliza é o mesmo do orquestrador padrão.

PlannerAgent (pré-PR)

O agent existia desde antes do pipeline — esse padrão formaliza como invocá-lo de forma determinística.

Configuração completa

Todos os env vars e slashes num lugar só.

Início

Primeiros Passos

Conceitos Fundamentais

Funcionalidades

Segurança

Suporte

#2 Plan-and-Solve / ReWOO

Formato do plano

Placeholders ReWOO

Heurística de complexidade

Exemplos

Fluxo de execução

Tolerância a falhas

`/plan` — invocação manual

Matriz de comportamento

Variáveis de ambiente

Override por persona (CHATCLI_AGENT_PLANNER_*)

Observabilidade

Spinner durante Plan-First

Modo dry-run: o que é renderizado

Quando desligar

Leia também

#3 Reflexion

Multi-Agent Orchestration

PlannerAgent (pré-PR)

Configuração completa

​Formato do plano

​Placeholders ReWOO

​Heurística de complexidade

​Exemplos

​Fluxo de execução

​Tolerância a falhas

​/plan — invocação manual

​Matriz de comportamento

​Variáveis de ambiente

​Override por persona (CHATCLI_AGENT_PLANNER_*)

​Observabilidade

​Spinner durante Plan-First

​Modo dry-run: o que é renderizado

​Quando desligar

​Leia também

#3 Reflexion

Multi-Agent Orchestration

PlannerAgent (pré-PR)

Configuração completa

Formato do plano

Placeholders ReWOO

Heurística de complexidade

Exemplos

Fluxo de execução

Tolerância a falhas

`/plan` — invocação manual

Matriz de comportamento

Variáveis de ambiente

Override por persona (CHATCLI_AGENT_PLANNER_*)

Observabilidade

Spinner durante Plan-First

Modo dry-run: o que é renderizado

Quando desligar

Leia também