n0ctx/dag-engineering

DAG Engineering

Divida tarefas de engenharia de grande porte em subtarefas (nós) com dependências. Cada nó é implementado por um subagente em seu próprio worktree e branch. O agente principal mescla e verifica cada nó sequencialmente no worktree de integração. A retificação também segue esse isolamento: subagentes não alteram ou fazem commit no worktree de integração. O agente principal é responsável pela investigação, planejamento, distribuição, integração, retificação e aceitação final. Subagentes de investigação respondem a perguntas específicas de forma somente leitura. Subagentes de nós primeiro refinam as etapas, depois implementam e fazem commit de um único nó. Subagentes de revisão fazem revisão somente leitura.

A profundidade da investigação, o número de subagentes e o escopo da verificação são determinados pela complexidade real da tarefa. Não crie subagentes desnecessariamente quando não houver trabalho independente.

Ao distribuir qualquer subagente no Codex, defina explicitamente fork_turns="none".

0. Continuando um Plano Existente

Antes de começar, verifique .dag/ no workspace principal. Se existir um plano com "status do plano: em andamento", leia-o e continue a partir do progresso atual, combinando com o estado real do Git. Não o divida novamente. Se o plano e o Git estiverem inconsistentes, corrija o plano com base no estado do código verificado.

1. Se o worktree de integração tiver um MERGE_HEAD (git -C <integracao_wt> rev-parse -q --verify MERGE_HEAD): a integração foi interrompida, o resultado é desconhecido. Execute git merge --abort e reintegre o nó como submetido.
2. Verifique cada nó individualmente:
   • done: Confirme se o commit do nó já foi mesclado no branch de integração (git -C <integracao_wt> merge-base --is-ancestor <commit> HEAD). Não execute novamente.
   • submitted: Se o commit do nó já foi mesclado no branch de integração, marque-o como done (commits de mesclagem só são criados após verificação bem-sucedida). Caso contrário, integre conforme a Etapa 6.
   • running: Se o agente ainda estiver em execução, espere. Se o agente não existir mais, verifique os commits e as alterações não commitadas no worktree do nó e envie um novo agente para continuar no mesmo worktree a partir do progresso existente. Não crie um novo worktree.
   • blocked: Leia o motivo e determine se a condição já foi resolvida.
   • pending: Escalone conforme a Etapa 5. Se o nó ainda estiver no formato antigo (objetivo, escopo, etapas, verificação, aceitação), reescreva-o usando o modelo da Etapa 4 antes de distribuir.
3. Se todos os nós estiverem done: vá para a Etapa 7.

Não delete worktrees, branches ou alterações não commitadas quando o estado não estiver claro.

1. Criar Worktree de Integração

Para cada DAG, crie um worktree e um branch de integração. Apenas o agente principal escreve nele. O workspace principal permanece inalterado.

git worktree add "../<repo>-<plan-id>" -b "dag/<plan-id>"

• <plan-id>: use uma descrição curta em kebab-case. Se o branch ou diretório já existir, use um nome diferente.
• Se houver alterações não commitadas no workspace principal, informe ao usuário que elas não entrarão no worktree e peça para ele decidir se fará o commit ou continuará.
• Se os comandos de verificação dependerem de etapas de instalação (ex.: node_modules, ambiente virtual), conclua a instalação no worktree de integração primeiro.
• Registre o commit de partida (git rev-parse HEAD). A revisão geral usará este commit como base.

2. Investigação e Design Chave

Ordem: Análise de requisitos → Investigação de código direcionada → Design chave unificado.

O agente principal primeiro localiza a implementação existente, módulos relacionados, relacionamentos de chamada e testes com base nos requisitos. Liste perguntas desconhecidas que afetam o planejamento. Se ambiguidades puderem alterar o objetivo, escopo ou critérios de aceitação, pergunte ao usuário primeiro. Caso contrário, escreva incertezas como "suposições" no plano.

Se houver várias perguntas de investigação independentes, distribua subagentes de investigação somente leitura em paralelo na mesma mensagem. Se as perguntas forem poucas ou interdependentes, o agente principal investiga por conta própria. Divida a investigação por perguntas específicas (implementação existente e reutilização, interfaces e cadeias de chamada principais, estado compartilhado e recursos externos, testes e restrições de engenharia, etc.), não mecanicamente por diretório. Os subagentes de investigação leem diretamente o worktree de integração e não precisam do seu próprio worktree. As instruções devem especificar:

Investigação somente leitura <integracao_wt>. Não modifique nenhum arquivo. Não distribua outros agentes. Objetivo: <...>. Escopo: <...>. Perguntas a responder: . Pare quando as perguntas forem respondidas; não explore além do escopo. Relate apenas: fatos chave e suas localizações (arquivo:símbolo), implementações existentes reutilizáveis, restrições de engenharia e itens não confirmados. Diferencie fatos confirmados de suposições.

O agente principal integra os resultados, lida com conclusões conflitantes e investiga apenas as lacunas que afetam o planejamento. Pare a investigação quando os fatos forem suficientes para escrever os goal, scope, verify e stop dos nós. Deixe os detalhes das etapas (steps) para quando os subagentes iniciarem (Etapa 5). A investigação durante o planejamento é apenas até a profundidade necessária para definir os limites do nó: use consultas estruturais (arquivo e linhas, relacionamentos de chamada, arestas de dependência, entradas de manifesto) para responder; não leia implementações de funções. Entender a implementação é tarefa do subagente do nó.

Fatos entre módulos (quem chama um símbolo, do que um módulo depende, o tamanho de um conjunto de arquivos com suas dependências) devem ser respondidos usando Language Server, ast-grep ou pesquisa, sob demanda. Não derive lendo o código-fonte inteiro. Uma vez descoberto, reutilize: fatos descobertos pelo agente principal ou subagentes de investigação são escritos nos resultados de refinamento ou na nota do nó relevante. Os subagentes de nós listam quaisquer novos fatos entre nós que descobrem em seus relatórios, e o agente principal os registra no refinamento dos nós downstream que os usarão. Quando um nó downstream começa, ele verifica esses registros primeiro. Se os registros forem insuficientes ou potencialmente desatualizados (código relevante foi alterado por nós subsequentes), ele pesquisa novamente.

Em seguida, determine e escreva o "design chave" no plano:

• Comportamento alvo e não alvo.
• Implementação existente, dependências ou capacidades da plataforma a serem reutilizadas diretamente.
• Atribuição de funcionalidades e código.
• Interfaces, estruturas de dados e restrições de arquitetura que devem ser consistentes entre os nós.
• Recursos compartilhados e condições de integração.

Fixar apenas o design necessário para a colaboração entre nós. Deixe a implementação interna dos nós para seus subagentes. Não adicione abstrações para necessidades futuras. Não reimplemente capacidades existentes.

3. Dividir o DAG

• Granularidade do nó: Uma unidade de comportamento que pode ser aceita independentemente, incluindo os ganchos necessários para executá-lo e verificá-lo. Configuração, andaime e documentação usados por apenas um nó são incorporados a esse nó. Se usados por vários nós, são transformados em um nó upstream. Trabalho altamente acoplado que, se dividido, criaria um estado intermediário não verificável ou exigiria modificações duplicadas extensas deve ser mesclado em um nó. Trabalho fracamente acoplado deve ser dividido para permitir paralelismo. Não force a divisão para aumentar o paralelismo.
• Verificação item por item: Quando um nó precisar cobrir muitos arquivos ou entradas, primeiro identifique os itens a serem verificados e os critérios de aceitação item por item. Subagentes somente leitura processam paralelamente os escopos que podem ser verificados independentemente. Após resumir as lacunas, implemente. Reutilize conclusões de verificação ainda válidas em vez de reexaminar.
• Dependências: Apenas escreva dependências quando um nó downstream realmente precisar do código, decisão ou comportamento verificado de um upstream, ou se a falha de um upstream invalidar o downstream. Se as interfaces compartilhadas já estiverem determinadas no design chave e ambos os lados puderem implementar e testar independentemente, não escreva dependências. Permita paralelismo; verificação de integração testará a interação real. Não crie dependências artificiais para controlar a ordem.
• Conflitos: Marque apenas nós que não podem ser executados com segurança em paralelo: modificações logicamente conflitantes, recursos de execução compartilhados (banco de dados, portas), recursos que exigem atribuição serial (números de migração). Sobreposições normais no mesmo arquivo não são conflitos; permita paralelismo e deixe o Git mesclar. Só marque conflito se a sobreposição for densa e o custo da mesclagem for claramente maior do que a execução serial.
• Solução ainda não determinada (precisa de experimentação): Crie um nó de investigação para produzir conclusões. Nós downstream dependem dele.

Escreva cada nó usando o modelo da Etapa 4. Escreva goal, scope, verify, stop e refine durante o planejamento. As steps são detalhadas pelo subagente do nó ao iniciar (Etapa 5) com base no refine. Se você já sabe as etapas durante o planejamento, pode escrevê-las primeiro.

• goal: Uma ou duas frases. Qual comportamento estará presente após a conclusão.
• scope: Arquivos ou diretórios permitidos para modificação, partes explicitamente proibidas de serem alteradas e design chave e restrições de negócios que devem ser respeitadas.
• verify: Resultados de aceitação observáveis e comandos reais executáveis. Inclua guardas existentes afetados pelas alterações deste nó, como verificações de tamanho da documentação, complexidade do código, camadas e contratos. Priorize pontos de entrada estreitos. Execute verificações completas apenas se não houver ponto de entrada estreito. Verificações completas não são executadas simultaneamente com outras verificações.
• stop: Condições específicas deste nó para parar e relatar. Exemplo: "Não é possível determinar a atribuição pelas regras." "Uma certa interface não existe." Não repita as condições genéricas já nas instruções de distribuição.
• refine: Escreva itens que as steps precisam descobrir como consultas executáveis. Exemplo: "Liste todas as entradas com prefixo X e suas dependências de módulos não processados." "Liste todos os chamadores de Y." O subagente do nó conclui isso no primeiro segmento. Se conclusões já foram descobertas durante o planejamento ou investigação, escreva-as diretamente no refine e marque como "descoberta". O subagente as usa diretamente sem reexaminar. Apenas deixe itens não respondidos como consultas. Escreva "Nenhum" se não houver itens a serem descobertos.
• steps: Etapas ordenadas, cada uma fazendo uma coisa verificável. Escreva no nível do módulo, comando, interface: o que fazer, onde cai, qual é o comportamento externo. Escreva no nível da função apenas nos limites: quando o mesmo arquivo deve ser dividido entre nós, ou quando houver disputa sobre a qual função pertence a qual nó, liste as funções de cada lado.

Valores, condições e limites já determinados pelos materiais de origem e design chave devem ser escritos diretamente nos nós relevantes. Não deixe para o subagente derivar. Arquivos, símbolos e comandos devem vir do código real; não os invente. Corrija as seguintes escritas:

• Descrições não executáveis como "implemente conforme apropriado", "trate casos de limite".
• Critérios de aceitação que apenas reiteram ações de implementação (ex.: "X implementado").
• Comportamento de aceitação apenas provado por existência de arquivo, capacidade de importar ou pesquisa de palavra-chave.
• Classificações ou decisões que apenas se referem a nomes de regras ou seções de documentos (ex.: "julgar por D7"), sem escrever a ação padrão e condições de exceção.

Antes de distribuir, verifique o plano respondendo a dois conjuntos de perguntas.

Se o plano for concluído, os critérios de aceitação globais serão necessariamente atendidos. Procure lacunas em cada item:

1. Enumere o escopo a partir de fontes reais, não apenas dos requisitos: código envolvido, configuração, arquivos fora do repositório e estado da máquina, modo de instalação e implantação, outras plataformas de execução, chamadores externos. Cada item pertence a exatamente um nó ou é escrito como um não objetivo.
2. Cada verificação é válida: ela pode ser executada no ambiente alvo; não escreve em dados de produção ou sistemas externos; se precisar escrever, o nó especifica a estratégia de isolamento; a aprovação implica a conclusão de aceitação correspondente; a ferramenta usada para verificação já foi verificada.
3. Isenções temporárias, camadas de compatibilidade, dados de transição e ferramentas introduzidas pelo plano têm nós responsáveis por removê-los ou promovê-los.
4. Caminhos que escrevem em sistemas externos, alternam para ambientes de produção ou executam apenas em outras plataformas têm pelo menos um nó que realmente executa uma vez no ambiente real antes da entrega.
5. Interfaces e arquitetura entre nós são consistentes. Nenhum erro ou omissão em dependências ou conflitos. Existe um nó responsável pela integração entre nós. O refine de cada nó pode descobrir as steps, e o verify pode ser executado.

Preencha as lacunas como nós. Se não puder preencher ou o custo exigir compensação do usuário, escreva em "lacunas de completude" do plano e deixe o usuário decidir.

O design está perdendo tempo?

6. Cada nó tem um consumidor downstream; a verificação também conta. Exclua nós sem consumidores.
7. Nós que exigem decisão ou presença do usuário, ou que alterarão o comportamento existente, não devem fazer outros nós esperar. Se um nó downstream deve esperar, divida-o em uma parte que não altera o comportamento (faça primeiro) e uma parte que altera (faça depois).
8. Se dois ou mais nós usam a mesma capacidade ou ferramenta, promova-a para um nó upstream. Não deixe cada nó fazer a mesma coisa. Verifique individualmente cada verify dos nós: se dois ou mais nós usam o mesmo método de verificação (comparação antigo/novo, reprodução, comparação de artefatos), também promova isso para uma ferramenta de nó upstream. O verify dessa ferramenta deve incluir a demonstração de que ela pode relatar diferenças usando uma amostra com diferença conhecida. Se dois ou mais nós precisam consultar repetidamente o mesmo material grande (lista, tabela de mapeamento, documento de decisão), e o projeto não tem uma entrada de consulta sob demanda, também crie um nó upstream para adicionar um ponto de entrada de consulta.
9. Estime a quantidade de leitura e modificação para cada nó (com base em arquivos dentro do escopo mais o código não processado do qual depende). Se a quantidade for grande demais para um subagente lidar confiavelmente, ou abranger módulos não relacionados que podem ser aceitos independentemente, divida. Se o acoplamento for apertado e a divisão criar estados intermediários não verificáveis, não divida, mesmo que a quantidade seja grande. As linhas são apenas um julgamento auxiliar; não defina um limite fixo. Se não puder estimar, escreva o que precisa ser calculado no refine. O subagente do nó estima no primeiro segmento. O método de divisão deve ser decidido antes de criar o worktree. Primeiro, envie um subagente de investigação para estimar de acordo com a Etapa 5.
10. Nenhuma capacidade existente é reimplementada. Sem divisão desnecessária ou design excessivo. Nós que podem ser paralelizados com segurança não são serializados.

Se houver 5 nós ou menos, o agente principal verifica. Se houver mais de 5, primeiro escreva um rascunho em .dag/<plan-id>.md seguindo o modelo da Etapa 4. Em seguida, envie um subagente de revisão somente leitura. Forneça a ele apenas o plano, os requisitos e a localização do código. Não forneça o raciocínio do agente principal:

Revisão somente leitura <caminho_do_plano>. Não modifique nenhum arquivo. Não distribua outros agentes. Requisitos: <requisitos originais ou localização>. Código: <integracao_wt>. Verifique cada item, um por um: <os itens 1–10 acima literalmente>. Relate apenas: lacunas para atingir o objetivo, designs que perdem tempo e itens que exigem decisão do usuário. Para cada um, escreva a localização, a evidência (arquivo:símbolo, saída de comando ou texto do plano) e a sugestão de alteração mínima. Diferencie problemas certos de suposições.

O agente principal modifica apenas problemas com evidências específicas.

4. Salvar o Plano

Escreva NO workspace principal .dag/<plan-id>.md. Não o coloque em nenhum worktree para evitar commit. Se .dag/ não for ignorado pelo Git, adicione-o a .git/info/exclude.

# <plan-id>

-   Objetivo:
-   Critérios de aceitação globais:
-   Não objetivos:
-   Suposições:
-   Lacunas de completude: <Partes que, após a conclusão do plano, ainda podem não ser garantidas e a decisão do usuário. Escreva "Nenhum" se não houver.>
-   Design chave:
-   status do plano: Em andamento
-   Worktree de integração: <caminho>   Branch: dag/<plan-id>   Início: <sha>
-   Registro de interface: `.dag/<plan-id>-interfaces.md`

## Nós

### N1 <título>
#### goal
#### scope
#### steps
<A ser detalhado pelo subagente do nó ao iniciar>
#### verify
#### stop
#### refine
#### state
-   Dependências: Nenhum
-   Conflitos: Nenhum
-   Estado: pending
-   worktree:   branch:   commit:

## Registro de execução
-   N1: <sha do commit de mesclagem> <resultado em uma frase>. <Retificação, anomalia ou problema pendente; omita se não houver>

O arquivo de registro de interface fica junto com o plano. Cada nó acrescenta uma seção após a mesclagem. Os subagentes de nós podem lê-lo como somente leitura:

## N1 (<sha do commit de mesclagem>)
-   <interface, nome e localização>: <forma e uso>

O registro de execução contém apenas resultados e problemas pendentes. As interfaces externas são escritas no arquivo de registro de interface. Fatos entre nós são escritos no refine dos nós downstream que os usarão. Detalhes como comparação de diferenças permanecem na mensagem de commit do nó e no arquivo de relatório.

goal a refine são passados para o subagente do nó. state é apenas para uso do agente principal.

Valores de estado:

• pending: Não distribuído.
• running: O subagente está implementando ou retificando.
• submitted: O subagente fez commit, aguardando integração.
• done: Mesclado no branch de integração e aprovado na aceitação do agente principal.
• blocked: Não pode continuar; o motivo é registrado no registro de execução.

Apenas o agente principal modifica o plano. Atualize imediatamente a cada mudança de estado. É a base para continuar o trabalho entre sessões.

Após salvar, mostre brevemente ao usuário os nós, dependências, nós que podem ser paralelizados, lacunas de completude e todos os itens que exigem decisão do usuário (liste todos de uma vez, não faça perguntas separadas). Pare aqui se o usuário pediu apenas um plano. Caso contrário, continue a execução.

5. Distribuição Dinâmica

Nós pending com todas as dependências done e sem conflito com nós running/submitted estão prontos. Encontre todos os nós prontos e distribua-os em paralelo na mesma mensagem. Não defina um limite fixo de concorrência. A concorrência real depende da ferramenta do agente e do ambiente. Depois que um nó se torna done, encontre e distribua imediatamente nós recém-prontos. Não espere outros nós independentes terminarem.

Antes de distribuir cada nó, o agente principal apenas faz uma verificação prévia: liste as decisões, interfaces, nomes e regras upstream usadas por este nó e confirme se elas já foram mescladas no HEAD do branch de integração. Se algum deles ainda puder ser alterado por um nó running ou pending, adicione uma dependência para este nó e não o distribua ainda.

As consultas em refine são concluídas pelo subagente do nó no primeiro segmento. O agente principal não as executa. Há duas exceções em que o agente principal primeiro envia subagentes de investigação somente leitura de acordo com a Etapa 2, apenas recebendo as conclusões:

• Um nó pode precisar ser dividido em vários nós paralelizáveis, e o método de divisão deve ser decidido antes de criar o worktree: o subagente de investigação estima o volume e o acoplamento com base no refine. O agente principal divide de acordo com o item 9 da Etapa 3 e depois distribui separadamente.
• Vários nós prontos precisam responder à mesma pergunta: envie um subagente de investigação para responder a todas, não um subagente por nó.

Em seguida, crie um worktree de nó a partir do HEAD atual do branch de integração (último commit de integração aprovado). Escreva o caminho e o branch no plano e marque como running:

git -C <integracao_wt> worktree add "../<repo>-<plan-id>-<node-id>" -b "dag-node/<plan-id>/<node-id>" HEAD

Se a verificação depender de etapas de instalação, instrua o subagente do nó a concluir a instalação em seu próprio worktree primeiro.

Organize as instruções para o subagente do nó na seguinte ordem. Inclua apenas este conteúdo:

1. Caminho e branch do worktree.
2. Texto original de goal, scope, steps (se houver), verify, stop e refine do plano para este nó.
3. note (escrito apenas nas instruções, não no plano):
   • Caminho absoluto para o arquivo de registro de interface. Apenas o caminho; não refaça as interfaces upstream nas instruções.
   • Complementos específicos para este nó: limites e compensações definidos pelo agente principal, texto original da decisão do usuário, fatos upstream relevantes apenas para este nó, armadilhas conhecidas, comandos para pesquisar dados. Geralmente, não exceda cerca de 20 linhas. Se o material exceder cerca de 200 linhas ou apenas parte for necessária, forneça extrato ou comandos de consulta, não apenas o caminho do arquivo. As regras já escritas no arquivo de descrição do projeto (que o subagente carrega automaticamente) não precisam ser repetidas. Se a saída de um comando em verify for muito longa, indique qual parte observar (ex.: linha de resumo no final).
   • Caminho do arquivo de relatório: .dag/<plan-id>-reports/<node-id>.md (caminho absoluto no workspace principal).
4. Os seguintes requisitos, colocados no final das instruções:

Trabalhe apenas no worktree fornecido. Não opere no branch de integração, outros branches de nó ou worktrees. Não distribua outros agentes. Não modifique arquivos sob .dag/, exceto o arquivo de relatório fornecido. Não leia arquivos sob .dag/, exceto o arquivo de registro de interface. As etapas de inicialização e encerramento escritas para a sessão principal no arquivo de descrição do projeto (ler o plano, executar verificação de estado, restaurar o plano, etc.) não se aplicam a você. Para pesquisar dados, use primeiro os comandos e extratos fornecidos no note. Se o note não cobrir, pesquise você mesmo. Não leia o plano inteiro, documentos de decisão ou grandes listas.

Trabalhe em dois segmentos. Primeiro segmento: Descubra os fatos de acordo com o refine (conclusões marcadas como "descoberta" em refine são usadas diretamente; responda apenas a itens não respondidos). Determine as steps (no nível do módulo, comando, interface; ao dividir o mesmo arquivo entre nós, liste as funções de cada lado) sem alterar goal, interface e escopo. Estime a quantidade de leitura e modificação necessária. Pare e relate um resumo de não mais que cerca de 30 linhas (rascunho das steps, estimativa, método de divisão sugerido, itens que exigem decisão do agente principal ou do usuário) se ocorrer qualquer uma das seguintes situações: O limite ou a atribuição não pode ser determinado; É necessário alterar a interface entre nós ou modificar arquivos fora do escopo; O código real entra em conflito com a descrição do nó; A quantidade é muito grande para um subagente lidar confiavelmente ou abrange módulos que podem ser aceitos independentemente; Ocorre uma condição em stop. Se nenhum dos casos acima ocorrer, não pare. Vá diretamente para o segundo segmento. Coloque o resumo no relatório final.

Segundo segmento: Implemente de acordo com as steps. Decida a implementação local de forma autônoma, sem alterar goal, interface e escopo. Execute os comandos em verify. Após a aprovação, faça o commit de todas as alterações deste nó. A mensagem de commit deve ser <plan-id>/<no>: <resumo>. Confirme se git status está limpo. Se a verificação falhar, não faça o commit. Se, no segundo segmento, ocorrer uma das condições de parada listadas no primeiro segmento, ou a quantidade real exceder aproximadamente o dobro da estimativa do primeiro segmento, pare e relate. Não se expanda por conta própria. Se a parte concluída puder passar pelos comandos aplicáveis de verify, faça o commit primeiro. Caso contrário, mantenha-a no worktree, não faça o commit. Liste o trabalho concluído e o restante no relatório.

Ao terminar ou parar, escreva o relatório completo (resumo das alterações, comandos de verificação e resultados completos, diferenças de comparação, explicação de desvios) no arquivo de relatório. Envie de volta ao agente principal não mais que cerca de 40 linhas: status (DONE: concluído e verificado; DONE_WITH_CONCERNS: concluído com preocupações; BLOCKED: não pode ser concluído ou parou), sha do commit, resultado da verificação em uma linha, novas ou alteradas interfaces externas, novos fatos entre nós descobertos (ex.: quais módulos ainda usam um símbolo, a forma real de uma interface), motivo da preocupação ou bloqueio e itens que exigem decisão.

Quando o subagente parar no primeiro segmento para retornar um resumo, o agente principal verifica os limites e os itens que exigem decisão (pergunte ao usuário primeiro). Escreva as steps confirmadas de volta no plano. Em seguida, use a capacidade de continuação da ferramenta do agente (SendMessage do Claude Code; Codex envia entrada subsequente para o mesmo agente) para permitir que o mesmo subagente continue no segundo segmento. Não distribua um novo agente para evitar que ele releia o código que já leu. Se for sugerida uma divisão, divida de acordo com a regra "erro no plano em si" (Etapa 6): o agente original continua com uma parte; o restante é tratado como novos nós, distribuídos da Etapa 5. Se o agente original não puder ser continuado, distribua um novo agente no mesmo worktree para continuar e anexe o resumo.

Depois que o subagente retornar o commit, escreva o sha do commit no plano, marque como submitted e vá para a Etapa 6.

Regra de espera (aplica-se também a subagentes de investigação e revisão):

• Se houver trabalho independente específico que não entre em conflito com o escopo do subagente (ex.: integrar um nó submetido), faça-o primeiro. Caso contrário, entre em espera nativa.
• Claude Code usa notificação de conclusão de agente em segundo plano ou espera nativa. Codex chama a ferramenta de agente diretamente, não a coloca em functions.exec ou functions.wait. Defina wait_agent com timeout_ms=600000. Se o parâmetro da ferramenta não suportar esse valor, use o tempo de espera mais longo permitido. Se a ferramenta só puder retornar resultados em lote, lide com isso de acordo com sua capacidade; não simule notificações inexistentes.
• Não use loops curtos de sleep, consultas repetidas à lista de agentes ou verificações repetidas do estado do Git para substituir a espera. Não encurte a espera para enviar atualizações de progresso.
• Processe os resultados ou mensagens do usuário imediatamente após o recebimento. Um tempo limite de espera não significa falha. Continue esperando. Não redistribua nós que ainda estão em execução.

6. Integração e Aceitação de Cada Nó

O agente principal integra um nó submitted por vez no worktree de integração. Outros subagentes continuam trabalhando. Não confie cegamente no relatório do subagente:

1. git -C <integracao_wt> diff --stat HEAD...<branch_do_no>: os arquivos alterados estão dentro do escopo do nó. git status no worktree do nó não mostra alterações não commitadas restantes. Em seguida, verifique o diff completo dos arquivos compartilhados com outros nós (módulos públicos, configuração, linha de base de guardas, listas, testes de contrato) para garantir que estejam em conformidade com goal e design chave. Julgue o código novo do nó com base na verificação da Etapa 3 e no comportamento real; não leia linha por linha. Se precisar de detalhes, leia as seções relevantes do arquivo de relatório.
2. Mesclar, mas não commitar ainda:

   git -C <integracao_wt> merge --no-ff --no-commit "dag-node/<plan-id>/<node-id>"
   

3. Execute os comandos de verify deste nó e quaisquer verificações de integração afetadas pela mesclagem no worktree de integração. Verifique cada resultado de aceitação um por um. Pelo menos verifique um comportamento real. Novas falhas em guardas afetadas são corrigidas neste nó, não deixe para a aceitação final. Falhas existentes são registradas separadamente; não relaxe limites ou linhas de base. Não é necessário executar o conjunto completo de testes a cada vez.
4. Se tudo passar: git -C <integracao_wt> commit --no-edit. Marque o nó como done. Escreva uma linha no registro de execução. Anexe as interfaces externas ao arquivo de registro de interface. Escreva os fatos entre nós no refine dos nós downstream que os usarão. Em seguida, retorne à Etapa 5 para distribuir nós recém-desbloqueados.

Para aceitação que cobre listas, registre as conclusões verificadas, os itens a serem verificados e as lacunas, item por item. Somente quando todo o escopo declarado tiver sido verificado e atender aos critérios de aceitação, marque como done. A existência do arquivo, o texto não vazio ou a amostragem aprovada não substituem a cobertura item por item.

Se a mesclagem resultar em conflito: se a intenção de ambos os lados em uma sobreposição comum for clara, o agente principal resolve diretamente e executa a Etapa 3.

Para outros conflitos ou se a verificação falhar: desfaça a mesclagem incompleta (git -C <integracao_wt> merge --abort). O branch de integração é mantido no último commit aprovado. O commit do nó é mantido em seu branch. Lide de acordo com a atribuição do problema:

• Defeito de implementação do nó: Marque o nó de volta como running. Devolva o problema específico ao subagente do nó original para correção no worktree e reenvie o commit. Se o agente original não puder ser continuado, distribua um novo agente no mesmo worktree para continuar. O agente principal não reescreve a implementação do nó por padrão.
• Conflito que requer que o nó faça referência ao resultado de integração mais recente: Faça o subagente do nó mesclar dag/<plan-id> em seu worktree, resolver o conflito, verificar novamente e fazer o commit.
• Conflito de interface ou lógica entre nós: O agente principal determina o design correto, atualiza o design chave do plano e os nós relevantes e, em seguida, entrega aos subagentes dos nós relevantes para ajuste.
• Erro no plano em si (escopo, steps, dependências ou verify não correspondem ao código real): Com base nos fatos recém-descobertos, modifique apenas os nós afetados, dependências e aceitação. Mantenha os resultados bem-sucedidos existentes. Não redesenhe todo o DAG. Se a modificação envolver critérios de aceitação globais ou não objetivos, pergunte ao usuário primeiro.
• Subagente relata DONE_WITH_CONCERNS: Se a preocupação afetar os critérios de aceitação, trate como não aprovado. Caso contrário, integre normalmente e registre a preocupação no registro de execução.
• Subagente para porque a quantidade real excedeu a estimativa: Se a parte commitada puder ser aceita independentemente, altere goal, scope e verify deste nó para a parte concluída e integre de acordo com esta etapa. O trabalho restante é dividido em novos nós de acordo com a regra "erro no plano em si" e distribuído da Etapa 5. Se a parte commitada não puder ser aceita independentemente, não integre. Mantenha o nó running. Escreva o trabalho restante nas steps deste nó. Distribua um novo agente no mesmo worktree para continuar do progresso existente.
• Subagente relata BLOCKED ou o nó não pode continuar: Marque como blocked e registre o motivo específico. Não distribua nós que dependem dele. Continue com outros nós. Se não houver nós prontos ou em execução, mas ainda houver nós blocked, pare e relate o motivo do bloqueio ao usuário. Aguarde a decisão do usuário antes de continuar. Não vá para a Etapa 7.

Depois que um nó se torna done, limpe seu worktree e branch. Se o worktree tiver alterações não commitadas, pare e verifique. Não use --force ou -D.

git -C <no_wt> status --porcelain
git -C <integracao_wt> worktree remove "<no_wt>"
git -C <integracao_wt> branch -d "dag-node/<plan-id>/<node-id>"

Mantenha worktrees e branches para nós blocked, em retificação ou com estado desconhecido.

7. Revisão Geral

Depois que todos os nós estiverem done, envie um subagente de revisão somente leitura para revisar todas as alterações no branch de integração:

Revisão somente leitura de todas as alterações em <integracao_wt> no intervalo <sha_inicio>..HEAD. Não modifique nenhum arquivo. Não distribua outros agentes. Verifique em relação ao seguinte objetivo, critérios de aceitação globais e não objetivos: cobertura de requisitos, consistência de interface e comportamento entre nós, implementação duplicada, arquitetura que se desvia do design chave, defeitos de correção, código de depuração ou temporário restante, testes importantes ausentes ou que não cobrem o comportamento alegado. Para cada problema, forneça localização, evidência e nós envolvidos. Diferencie problemas certos de suposições. Liste separadamente os itens que exigem decisão do usuário.

Anexe o objetivo, os critérios de aceitação globais, os não objetivos e o design chave do plano às instruções.

O agente principal verifica cada problema e organiza a correção de acordo com a atribuição: problemas que exigem implementação são escritos como nós de correção (ex.: F1) no plano, distribuídos das Etapas 5-6 e integrados. O agente principal pode modificar e commitar diretamente problemas locais e óbvios (ex.: instrução de depuração restante) no worktree de integração. Não decida por conta própria itens que exigem decisão do usuário; escreva-os no relatório.

8. Aceitação Final e Relatório

O agente principal conclui as seguintes verificações no worktree de integração:

1. Veja o diff completo de <sha_inicio>..HEAD. Confirme que não há alterações além do objetivo do plano.
2. Execute os comandos de verify de todos os nós, bem como testes, build e lint do projeto que cobrem os módulos alterados.
3. Verifique cada critério de aceitação global um por um.

Se a verificação falhar: se o problema estiver dentro do objetivo do plano, corrija de acordo com a regra de atribuição da Etapa 7 e verifique novamente. Se o problema estiver fora do objetivo do plano (ex.: teste já falhava antes do início), não corrija, mas escreva no relatório. Após a conclusão, altere "status do plano" para "Concluído".

O relatório final inclui: nós concluídos e commits de mesclagem correspondentes, descobertas e tratamento da revisão, resultados da verificação, itens não concluídos ou em risco, itens que exigem decisão do usuário, caminho e branch do worktree de integração e worktrees de nós mantidos. A mesclagem no branch alvo e a exclusão do worktree de integração só são feitas quando solicitado pelo usuário.