benjinus/protocolo-de-colaboracao-entre-agentes

Protocolo de Colaboração entre Agentes

Use uma pasta compartilhada como um barramento de coordenação portátil para agentes que não podem se comunicar diretamente. ACP é um protocolo rigoroso: é uma máquina de estados com eventos estruturados e portões de prontidão, não uma conversa solta em Markdown.

Qualquer agente compatível deve ser capaz de ler Markdown e JSON, escrever Markdown, anexar eventos JSONL e executar ou reproduzir exatamente o comportamento dos scripts incluídos. Não dependa de APIs de thread do Codex, hooks específicos do Claude, estado exclusivo do OpenCode, metadados exclusivos do Kiro ou memória de conversa oculta para garantir a correção.

Entradas Obrigatórias

Antes de começar, exija:

• collaboration_folder: caminho absoluto ou relativo ao repositório da pasta compartilhada.
• objective: o que a colaboração deve decidir ou produzir.
• completion_gates: portões concretos para encerrar a colaboração.
• participants: todos os IDs dos participantes, como servidor, leitor, revisor, ou agente-a.
• participant_id: a identidade do agente atual.

Se alguma entrada obrigatória estiver faltando, pergunte por ela antes de criar arquivos ou escrever eventos. Não invente portões de conclusão.

Arquivos

As pastas ACP usam estes arquivos:

• protocol.json: objetivo, participantes, portões de conclusão, fase atual, dono da proposta, participantes em espera e timestamps.
• events.jsonl: registro de eventos somente anexável. Cada linha é um objeto JSON compacto.
• proposal.md: apenas a proposta atual.
• review.md: revisões estruturadas dos participantes.
• decisions.md: apenas decisões aceitas.
• readiness.md: classificação de perguntas em aberto, bloqueadores, itens não bloqueantes adiados e prontidão para implementação.
• conclusion.md: conclusão final da discussão. Indica se deve prosseguir, não prosseguir, adiar ou bloquear; por quê; como implementar ou por que não; e a próxima ação.

Não crie nem use state.log, discussion.md ou opinions.md. Eles não são arquivos do protocolo e não devem aparecer em portões de conclusão ou instruções.

Inicialização

Prefira o script incluído:

python3 <skill>/scripts/init_collaboration.py \
  --folder <collaboration_folder> \
  --participant <participant_id> \
  --participant <outro_participante_id> \
  --objective "<objetivo>" \
  --completion "<portão de conclusão>" \
  --completion "<outro portão>"

O inicializador falha se protocol.json já existir, a menos que --resume seja fornecido. Inicialização repetida não é uma operação de anexação.

Eventos

Use scripts/append_event.py ou reproduza exatamente seu comportamento. Não escreva eventos manualmente, a menos que o ambiente de execução não consiga executar scripts.

Campos obrigatórios do evento:

• seq: inteiro contínuo em events.jsonl.
• from: ID do participante listado em protocol.json.
• event: nome do evento permitido.
• at: timestamp UTC ISO-8601.
• summary: uma frase curta.

Campos recomendados:

• doc: caminho relativo à pasta de colaboração.
• reply_to: seq de um evento anterior.

Eventos permitidos:

• initialized
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

Todas as respostas devem usar reply_to quando estiverem respondendo a um evento anterior. reply_to deve apontar para um evento anterior existente. Os timestamps dos eventos não devem retroceder conforme seq aumenta. Se um erro for descoberto, anexe blocked ou um novo evento corretivo; não reescreva eventos anteriores.

Fases

Os agentes devem agir de acordo com protocol.json.currentPhase e protocol.json.waitingFor:

• drafting: o dono da proposta atualiza proposal.md e, em seguida, anexa proposal_submitted.
• reviewing: apenas os participantes listados em waitingFor anexam revisões estruturadas a review.md e, em seguida, anexam review_submitted.
• revising: o dono da proposta aborda as alterações obrigatórias e anexa proposal_revised.
• decision_review: o dono da proposta primeiro classifica todas as perguntas em aberto em readiness.md e anexa question_classified; só então os participantes listados em waitingFor aceitam decisões explícitas em decisions.md anexando decision_accepted.
• readiness_check: os participantes classificam todas as perguntas, limpam bloqueadores e passam na verificação de prontidão; em seguida, o dono da proposta escreve conclusion.md.
• completed: pare, a menos que o usuário inicie explicitamente uma nova rodada.
• blocked: pare até que o bloqueador seja resolvido.

completed é válido apenas após um evento readiness_passed anterior. completed deve fazer referência a conclusion.md. Não complete apenas com decisions.md; decisões são entradas, enquanto conclusion.md é a resposta final para o objetivo da colaboração.

O dono da proposta deve esperar após proposal_submitted. Enquanto a fase for reviewing, o dono pode consultar pela próxima ação ou anexar blocked para um timeout/bloqueador real, mas não deve editar proposal.md, decisions.md, readiness.md ou protocol.json, e não deve anexar eventos de avanço até que a revisão obrigatória seja enviada.

Formato de Revisão

Cada evento review_submitted deve ter um cabeçalho correspondente em review.md cujo seq seja igual ao seq daquele evento:

## <ISO-8601 UTC> - <participant_id> - seq <seq do evento review_submitted>

Contexto:
- Li `proposal.md` após o evento seq `<seq>`.

Posição:
- ...

Preocupações:
- ...

Alterações Obrigatórias:
- ...

Perguntas:
- ...

Não use o seq do evento respondido no cabeçalho da revisão. Coloque o contexto do respondido em Contexto e reply_to.

Portão de Prontidão

Antes de readiness_passed ou completed:

• Cada pergunta em aberto deve ser classificada como [resolvido], [adiado_nao_bloqueante] ou [bloqueante].
• Cada item [adiado_nao_bloqueante] deve incluir Motivo: ....
• Nenhum item [bloqueante] ou [nao_resolvido] pode permanecer.
• A lista de verificação de design final deve incluir e marcar Pronto para implementar.
• validate_collaboration.py deve passar.

Itens de prontidão bloqueantes também impedem decision_accepted. Perguntas não resolvidas e itens adiados sem Motivo: ... também impedem decision_accepted.

Os documentos finais de design devem separar:

• Decisões Aceitas
• Suposições
• Acompanhamentos Adiados
• Bloqueadores de Implementação
• Pronto para Implementar

Conclusão Final

Antes de completed, escreva conclusion.md como um documento de conclusão, não um registro. Ele deve incluir:

• Resultado da Decisão: exatamente um de [prosseguir], [nao_prosseguir] ou [adiar].
• Justificativa.
• Decisões Aceitas.
• Abordagem de Implementação.
• Suposições.
• Acompanhamentos Adiados.
• Bloqueadores de Implementação.
• Próxima Ação.

Use [prosseguir] quando a implementação deve começar agora, [nao_prosseguir] quando a funcionalidade ou plano não deve ser feito, e [adiar] quando trabalho de acompanhamento deve acontecer antes da implementação. Um resultado [bloqueado] pode existir enquanto a colaboração estiver bloqueada, mas não é conclusível.

Consulta e Observadores

Os participantes devem permanecer ativos no loop de colaboração até que a fase seja completed, blocked, ou um prazo explícito do usuário/coordenador seja atingido. Não pare apenas porque anexou um evento válido. Após cada ação, leia protocol.json novamente e tome a próxima ação permitida ou aguarde o próximo evento.

Se o ambiente de execução tiver um observador, ele pode notificar o participante quando events.jsonl ou protocol.json mudar. O observador deve permanecer simples: ele apenas percebe mudanças e nunca escreve análises ou decisões.

Se não houver observador, use:

python3 <skill>/scripts/next_action.py \
  --folder <collaboration_folder> \
  --participant <participant_id>

Para participantes autônomos, prefira o auxiliar de bloqueio:

python3 <skill>/scripts/wait_for_turn.py \
  --folder <collaboration_folder> \
  --participant <participant_id>

wait_for_turn.py retorna quando o participante é listado em waitingFor, ou quando a colaboração se torna completed ou blocked. O padrão é um tempo limite de 30 minutos para evitar processos de participantes permanentemente travados; use --timeout 0 apenas quando um supervisor externo possui o cancelamento. Ao retornar, inspecione next_action.py, aja se for sua vez, anexe o evento obrigatório e repita o loop de espera/ação. Solicitações manuais ao usuário como "verifique a nova opinião" são apenas um fallback, não o loop de colaboração pretendido.

Comandos do coordenador que lançam participantes devem pedir a cada participante para executar este loop em vez de fazer uma fase e sair. Um participante que não estiver listado em waitingFor pode bloquear em wait_for_turn.py, mas não deve editar estado compartilhado enquanto espera.

Validação

Execute:

python3 <skill>/scripts/validate_collaboration.py --folder <collaboration_folder>

O validador verifica arquivos obrigatórios, ausência de arquivos obsoletos, formato do evento, continuidade do seq, monotonicidade do timestamp, transições de fase, propriedade de waitingFor, reply_to, seqs do cabeçalho de revisão, classificação de prontidão, integralidade da conclusão e ordenação da conclusão.

Códigos de saída:

• 0: válido.
• 1: válido com avisos.
• 2: inválido.