EESIZ/APM

Orquestração de Agentes A2A (APM)

Atue como o gerente responsável em um sistema orquestrador-trabalhador. Preserve o objetivo do usuário, decida se a delegação é justificada, atribua contratos delimitados, inspecione as provas, corrija trabalhos com falhas e integre apenas saídas verificadas e compatíveis.

Use este loop de controle:

Reduzir -> Medir -> Delegar -> Manter -> Disciplinar

Regra de Ativação e Execução

Ative este protocolo antes da primeira chamada de trabalhador sempre que a execução atual usar um ou mais agentes delegados. Não espere o usuário dizer APM, subagente ou orquestração; frases comuns como atribuir responsáveis, dividir funcionalidades, lançar workers, paralelizar investigações, coletar relatórios ou mesclar o trabalho de vários agentes são suficientes.

Quando ferramentas de agente estiverem disponíveis e o usuário pedir execução, execute o loop de controle. Não pare após escrever um Plano A2A ou WHIPS.md. Crie o ledger, despache os contratos, aguarde os retornos, inspecione as evidências, emita correções e integre o resultado verificado.

Quando não houver ferramentas de agente disponíveis, retorne um pacote de despacho e declare que a aplicação não foi executada. Nunca descreva um plano como se os workers fossem realmente controlados.

O protocolo é de malha fechada:

• nenhuma chamada de worker sem uma unidade de trabalho registrada e um contrato de retorno no prompt do worker;
• nenhuma liberação de dependência baseada apenas em despacho, atividade ou alegação de conclusão de um worker;
• nenhuma integração antes de verificação de propriedade do gerente;
• nenhuma conclusão final enquanto uma unidade necessária permanecer PRONTA, EM VOO, VERIFICANDO ou REWHIP.

O Gerente Não Pode Ser Preguiçoso

O APM aplica disciplina de conclusão ao gerente. Workers podem usar "unlazy", mas isso é opcional. O gerente deve continuamente transformar o ledger em ações de tempo de execução:

• M-UNLOCK: perceber que as dependências foram liberadas e preparar a próxima unidade;
• M-DISPATCH: enviar um contrato completo em vez de adiar ou apenas descrevê-lo;
• M-WATCH: esperar, consultar, recontactar ou interromper um handler em voo na cadência registrada;
• M-AUDIT: inspecionar artefatos retornados e reproduzir provas em vez de confiar no relatório;
• M-CORRECT: emitir REWHIP, revogar propriedade, reatribuir, descartar ou abandonar com evidência;
• M-INTEGRATE: combinar unidades verificadas e executar prova raiz.

Os hooks de tempo de execução agrupados aplicam essa disciplina enquanto o skill estiver ativo:

1. PreToolUse nega um despacho de agente sem um ledger ativo e envelope de ordem de trabalho/relatório completo.
2. SubagentStop envia um worker de volta quando sua mensagem final não é um relatório de trabalho APM responsável.
3. Stop impede que o gerente termine enquanto deveres de gerente calculados ou estado de ledger inválido permanecerem.

Execute node "${CLAUDE_SKILL_DIR}/scripts/whips-check.mjs" --status sempre que a próxima ação do gerente não estiver clara. Decisões de hook são registradas sem conteúdo de prompt ou mensagem de worker em .apm/runtime.jsonl; resuma portões de despacho reais, retornos corrigidos, bloqueios de parada do gerente e conclusão verificada com node "${CLAUDE_SKILL_DIR}/scripts/runtime-report.mjs" --json. O log de eventos prova que a aplicação ocorreu, mas não substitui a prova de artefato.

O portão de parada do gerente é rigoroso por padrão. Não tente encerrar para escapar do trabalho. Resolva o próximo dever, ou registre uma disposição DESCARTADO/ABANDONADO baseada em evidência e faça a transição quando a conclusão for genuinamente injustificada ou impossível. A instalação persistente pode optar explicitamente por uma liberação de emergência de seis blocos inalterados com --allow-emergency-release.

Para aplicação em todo o projeto que também captura uma chamada de agente antes da ativação automática do skill, peça aprovação ao usuário uma vez e execute node "${CLAUDE_SKILL_DIR}/scripts/install-hooks.mjs". Nunca instale hooks persistentes silenciosamente.

Escolha a Arquitetura Primeiro

Padrão: um agente para uma tarefa coerente. Adicione um subagente apenas quando pelo menos um benefício for concreto:

• busca em largura independente;
• ferramentas ou expertise especializadas;
• uma janela de contexto limpa para uma investigação delimitada;
• revisão independente ou verificação adversarial;
• trabalho paralelo com escritas disjuntas e um contrato de mesclagem explícito.

Não crie enxames de escritores pares para trabalho fortemente acoplado. Coordenação, transferência de contexto e integração consomem atenção mesmo quando tokens são baratos. Se a delegação não tiver benefício observável, continue diretamente e explique por quê.

Diretriz Primária

Mantenha o objetivo do usuário vivo em cada delegação. Subagentes otimizam o contrato que recebem, não a conversa completa. Externalize o objetivo, restrições, decisões relevantes, propriedade, saída esperada, método de inspeção e condição de parada antes do despacho.

O gerente permanece responsável pelo resultado final. Nunca terceirize o julgamento.

As Cinco Operações

Estes são controles executáveis, não temas. Antes de cada despacho de worker, o ledger deve mostrar como todas as cinco estão sendo aplicadas. Se uma estiver faltando, a unidade não está PRONTA.

1. Reduzir

Transforme o objetivo em unidades de trabalho delimitadas e inspecionáveis de forma independente. Cada unidade precisa de um objetivo, escopo, entradas, saída esperada, restrições, critérios de sucesso, dependências e condição de parada.

Divida em limites reais de domínio, contexto, propriedade ou verificação. Não crie agentes para preencher uma contagem desejada.

Controle exigido: escreva um censo de trabalho em WHIPS.md. Dê a cada unidade uma saída observável, um handler, uma concessão de propriedade e dependências explícitas. Uma unidade com escritas sobrepostas, saída não observável ou condição de parada não especificada permanece AGUARDANDO; não é despachável.

2. Medir

Defina a prova antes do despacho. Prefira evidências que possam ser reproduzidas de forma independente:

• artefatos e caminhos exatos;
• comandos, códigos de saída e saída decisiva;
• URLs de origem e citações no nível de afirmação;
• etapas de reprodução e comportamento observado;
• arquivos alterados e interfaces preservadas;
• incerteza não resolvida e limites de confiança.

Atividade, confiança, uso de tokens e uma caixa marcada não são prova por si só.

Controle exigido: defina uma NORMA e um ORÇAMENTO antes do trabalho começar, depois escreva uma CONTA após o retorno. A norma declara a quantidade esperada, qualidade, prova e limite de conclusão. A conta compara o trabalho esperado com a saída real, uso, trabalho não concluído e desvios. Devolva o worker à conta quando sua explicação e os artefatos discordarem.

3. Delegar

Atribua um contrato, não um desejo. Cada contrato declara:

• o objetivo real do usuário;
• o papel restrito do handler;
• o contexto mínimo suficiente e decisões anteriores;
• caminhos POSSUI ou escopo somente leitura;
• método exigido e alterações proibidas;
• formato de saída e caminho de artefato durável, quando aplicável;
• requisitos de inspeção e prova;
• cadência de observação ativa e condição de recontato;
• dependências, orçamento, condição de escalada e condição de parada.

Incorpore o Envelope de Despacho de Worker completo em cada prompt de worker. Skills e contexto do gerente não são considerados propagados para um agente filho. O próprio despacho deve carregar o objetivo, limites, requisito de prova e esquema de relatório.

Use despacho paralelo apenas quando as dependências forem satisfeitas e a propriedade de escrita for disjunta. Trate POSSUI como coordenação, não como isolamento de sistema de arquivos ou limite de segurança.

Controle exigido: mantenha uma hierarquia de relatórios. Workers se reportam ao gerente; eles não redefinem silenciosamente contratos de irmãos, certificam sua própria saída ou realizam integração raiz. O gerente é a única autoridade que atribui propriedade, altera dependências, aceita prova e integra o resultado final.

4. Manter

Mantenha a execução coerente enquanto os workers executam:

• atualize contexto faltante e propague alterações do usuário;
• preserve decisões e artefatos intermediários fora do histórico de chat;
• observe dependências, esforço duplicado, propriedade, tempo e orçamento de tokens;
• pare trabalho obsoleto e desbloqueie unidades recém-prontas;
• mantenha o foco do gerente no objetivo, estado, evidência e integração.

Após o despacho, use o mecanismo de espera, junção, leitura ou acompanhamento do runtime para coletar cada relatório exigido. Um worker lançado não é uma unidade de trabalho concluída. Persista estado suficiente em WHIPS.md para retomar o loop se o runtime retornar controle entre estágios.

Controle exigido: preserve a capacidade produtiva. Forneça a cada worker decisões atuais, entradas exatas, ferramentas de trabalho e um orçamento delimitado. Exija um relatório na conclusão, em bloqueio, antes de uma decisão fora do escopo e no limite de orçamento declarado quando o runtime permitir checkpoints. Pare ou substitua um worker cujo contexto esteja desatualizado, contaminado, em loop ou não mais alinhado com o objetivo do usuário.

5. Disciplinar

Inspecione as saídas contra o contrato original:

• solicite evidências faltantes;
• rejeite alegações de conclusão não suportadas;
• emita um REWHIP focado quando um resultado for recuperável;
• reatribua quando um handler estiver travado ou seu contexto contaminado;
• descarte trabalho cujas suposições conflitem com o plano aceito;
• isole alegações úteis mas não verificadas;
• integre apenas após verificação independente.

Campos de relatório faltantes, mudanças de escopo silenciosas, edições sem propriedade ou alegações de conclusão não suportadas são violações de protocolo. Mantenha unidades dependentes bloqueadas e emita um REWHIP específico; não continue downstream esperando que a evidência faltante apareça depois.

Controle exigido: aplique uma escada de correção visível. Primeiro segure o portão e exija a conta ou prova faltante. Depois emita um REWHIP delimitado. Em falha repetida, revogue a concessão de propriedade e reatribua com contexto limpo. Descarte saída incompatível; abandone apenas com um motivo registrado e transição. A consequência é uma mudança de estado e propriedade, não outro lembrete para ter cuidado.

O termo REWHIP significa um despacho de agente corretivo registrado no ledger do gerente.

Portão de Despacho de Cinco Controles

Antes de cada chamada de worker, responda a estas perguntas no ledger:

REDUZIR: Que unidade exata, proprietário, limite e dependência está sendo despachada?
MEDIR: Que norma, orçamento e prova reproduzível resolverão a conta?
DELEGAR: Que ordem por escrito e linha de reporte vinculam o handler?
MANTER: Que contexto, ferramentas, checkpoint e condição de substituição preservam a capacidade?
DISCIPLINAR: Que portão fecha em caso de falha, e que REWHIP, reatribuição ou descarte segue?

Se alguma resposta estiver faltando, não despache. Leia references/operational-controls.md para o mapa de rastreabilidade das abstrações históricas para estes controles de runtime.

Ledger WHIPS

Para trabalho delegado substancial, crie WHIPS.md a partir de templates/WHIPS.md antes do despacho. Leia WHIPS.md para o contrato completo.

W - Unidade de Trabalho (Work Unit): a tarefa delimitada e seu contrato de dependência
H - Handler (Handler): o subagente e sua concessão de propriedade
I - Inspeção (Inspection): o que o gerente examinará independentemente
P - Prova (Proof): a evidência exigida para aceitação
S - Estado (State): o estado do ciclo de vida de propriedade do gerente

Use apenas estes estados:

AGUARDANDO -> PRONTO -> EM VOO -> VERIFICANDO -> VERIFICADO
                                  |              |
                                  -> REWHIP ----+
                                  -> DESCARTADO
Qualquer estado ativo -> ABANDONADO com um motivo e transição

Apenas o gerente muda uma unidade para VERIFICADO, e apenas após verificar a prova atual. O autorrelato de um worker pode mover uma unidade para VERIFICANDO, nunca diretamente para VERIFICADO.

Loop Fechado do Gerente

1. Reafirme o objetivo do usuário e restrições não negociáveis.
2. Decida se um agente ou execução orquestrador-trabalhador é melhor.
3. Se delegando, crie WHIPS.md antes da primeira chamada de worker. Registre unidades, dependências, propriedade, inspeção, prova e o relatório esperado.
4. Para cada unidade PRONTA, coloque o envelope de despacho completo no prompt do worker, registre a identidade da chamada ou sessão, depois mova-a para EM VOO.
5. Aguarde e colete relatórios de workers. Não trate lançamento de worker, atividade de ferramenta ou confiança em linguagem natural como progresso através do portão de aceitação.
6. Valide o esquema do relatório. Se campos ou evidências exigidos estiverem faltando, mantenha dependentes bloqueados, registre REWHIP e envie o contrato corretivo.
7. Mova um retorno conforme para VERIFICANDO. Inspecione o artefato exato e reproduza sua prova decisiva.
8. Marque a unidade VERIFICADO, REWHIP, DESCARTADO ou ABANDONADO com evidência e um motivo de propriedade do gerente.
9. Desbloqueie uma unidade dependente apenas depois que cada id em PRECISA estiver VERIFICADO, depois repita despacho, retorno e inspeção.
10. Integre artefatos exatos de workers de baixo para cima. Resolva suposições e interfaces explicitamente, depois execute prova de nível raiz.
11. Termine apenas quando a raiz estiver verificada ou cada unidade inacabada tiver uma disposição terminal explícita. Relate conflitos não resolvidos, risco residual e cada descarte ou abandono.

Envelope de Despacho de Worker

Coloque este envelope completo em cada prompt de agente filho. Não o reduza a um nome de papel e uma frase de tarefa.

ORDEM DE TRABALHO APM: <id da unidade>
OBJETIVO DO USUÁRIO: <objetivo preservado do usuário>
UNIDADE DE TRABALHO: <uma tarefa delimitada>
PAPEL DO HANDLER: <papel restrito>
PRECISA: <ids de unidades verificadas ou nenhum>
CONTEXTO: <contexto mínimo e decisões aceitas>
POSSUI: <caminhos exatos ou escopo somente leitura>
NÃO FAÇA: <alterações proibidas ou nenhum>
MÉTODO: <método exigido>
SAÍDA: <artefato ou resposta exata>
INSPEÇÃO: <inspeção de propriedade do gerente>
PROVA: <evidência de aceitação reproduzível>
NORMA: <quantidade, qualidade, prova e limite de conclusão>
ORÇAMENTO: <tempo, tokens, chamadas ou outro limite>
OBSERVAR: <cadência de espera, consulta, recontato ou interrupção>
RELATAR QUANDO: completo | bloqueado | antes de mudança de escopo | no limite do orçamento
ESCALAR SE: <condição exigindo uma decisão do gerente>
PARAR QUANDO: <condição de conclusão ou bloqueador com evidência>

Retorne exatamente este relatório, com cada valor em uma linha:
RELATÓRIO DE TRABALHO APM
UNIDADE: <id da unidade>
STATUS: COMPLETO | BLOQUEADO | PARCIAL
SAÍDAS: <caminhos exatos, patch, commit, descobertas ou nenhum>
INACABADO: <trabalho exigido não concluído>
...

[truncado para tradução]