Skip to main content
O Task Graph transforma um plano aprovado em um DAG persistido executado por squad workers paralelos — com uma regra inegociável: done nunca é a autodeclaração do executor.
Com vários agentes em paralelo, uma task erroneamente autodeclarada como concluída libera as dependentes sobre uma premissa falsa. O task graph torna a verificação estrutural em vez de narrativa: o orquestrador é código Go determinístico (não um LLM), os comandos de validação são executados pelo próprio engine, e o veredito vem de um reviewer worker de contexto limpo que nunca compartilha contexto com o executor.

​
Quando usar

A skill embutida task-graph ensina ao modelo essa régua, o schema do plano e a disciplina (“você nunca declara done”).

​
O schema do plano

Um único objeto JSON descreve a entrega inteira:
  • deps só pode referenciar tasks declaradas antes (o que também elimina ciclos).
  • prompt precisa ser autocontido — workers não veem a conversa. #<depID> é substituído pelo output daquela dependência.
  • Os comandos de validation[].run são executados pelo engine (herdando o sandbox do coder e a denylist de comandos perigosos) — nunca pelo executor. expect é prosa para o reviewer. Uma string simples vale como contrato só-prosa (o reviewer verifica por inspeção).
  • agent tem default coder (qualquer worker type do squad funciona); max_attempts default 3; require_review default true, por grafo ou por task.

​
Execução: ready-set scheduling

Tasks disparam no instante em que suas dependências concluem — sem barreiras de nível, sem wall-clock desperdiçado. A concorrência é limitada pela env já existente do squad, CHATCLI_AGENT_MAX_WORKERS (o max_parallel do próprio grafo pode reduzi-la); nenhuma variável de ambiente nova foi adicionada para essa feature. Cada task passa por um loop de tentativas:
  1. Checkpoint — um snapshot shadow-git do workspace, best-effort, antes do executor começar.
  2. Executor — um worker fresco recebe o prompt (mais o feedback do reviewer nos retries).
  3. Gate — o engine executa ele mesmo cada comando de validation[].run e grava a saída; exit diferente de zero falha a tentativa sem gastar reviewer.
  4. Review — um reviewer worker fresco (ferramentas read-only) recebe o contrato, as saídas do gate e o relato do executor, e precisa terminar com VERDICT: PASS — evidência ou VERDICT: FAIL — o que falta.
  5. Promoção ou retry — gate verde + PASS promove a done com a evidência gravada; FAIL repete com o feedback injetado, até max_attempts, quando a task falha e suas sucessoras ficam blocked.
O engine recusa: ciclos de dependência, iniciar task com deps não satisfeitas, promover sem gate + veredito quando o review é exigido, e reviewer = executor (cada um é um dispatch distinto — os dois run IDs ficam gravados na tentativa como prova). Estados: pending → running → reviewing → done | failed | blocked. Cada tentativa também carrega seu custo real: cada chamada LLM de worker é atribuída ao nó do grafo que a originou, com a mesma contabilidade por chamada do cost tracking.

​
Superfícies

​
@taskgraph (para a IA)

run executa o grafo inteiro em uma única tool call, streamando eventos conforme acontecem. Resume é inerente: tasks concluídas ficam done, então re-executar um grafo que falhou continua de onde parou.

​
/taskgraph (para humanos)

/taskgraph é permitido como side command mid-run — digite enquanto o grafo executa para inspecionar o progresso sem tocar no loop do orquestrador.

​
A dashboard live

/taskgraph dash (ou {"cmd":"dash"}) serve uma dashboard no browser a partir de uma porta efêmera em 127.0.0.1 — um único arquivo embarcado, zero CDN, zero configuração:
  • Canvas de DAG animado — swimlanes por fase, béziers de dependência com traços animados nas tasks em execução, cards coloridos por status com contagem de tentativas e custo por task; arraste para pan, ctrl/⌘+scroll para zoom, 0 para ajustar, highlight de linhagem no hover.
  • Popovers de evidência — clique numa task para ver prompt, contrato de validação, saídas do gate, veredito + evidência do reviewer e os run IDs de executor e reviewer.
  • Aba Results — critical path, wall-clock vs tempo de agente, fator de paralelismo e o custo real por task.
  • Live — a página consulta o estado persistido a cada segundo e acompanha o feed de eventos.
O servidor é estritamente read-only: lê state.json e events.ndjson do disco a cada request. Fechar a dashboard nunca afeta uma run, e runs finalizadas renderizam igualmente bem.

​
Persistência

Cada run possui ~/.chatcli/taskgraph/<runID>/: As runs aparecem em /agents (e no Conversation Hub) como uma run-mãe com cada executor e reviewer registrados como filhos — o cancelamento propaga pela árvore.
O task graph foi inspirado na disciplina executor ≠ reviewer das skills de orquestração em grafo: autodeclaração não é veredito. No ChatCLI o orquestrador é código determinístico nativo, então o grafo, os gates e a promoção a done ficam estruturalmente fora do alcance de alucinação do modelo.