agi-connect/agent-collaboration-protocol

Protocolo de Colaboração entre Agentes

ACP é um protocolo de coordenação baseado em pasta compartilhada para agentes que não podem se comunicar diretamente. É uma máquina de estados com eventos JSONL estruturados, posse de turno, portões de prontidão e uma entrega congelada. Não é uma discussão solta em Markdown.

Qualquer agente compatível deve ser capaz de ler e escrever Markdown/JSON, anexar eventos JSONL e executar ou reproduzir exatamente o comportamento do script fornecido. Não confie em estado de thread oculto, APIs específicas de fornecedor ou memória de conversação para a correção do protocolo.

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.
• objective_gates: portões específicos do objetivo. O protocolo gera portões de entrega automaticamente.
• participants: IDs de todos os participantes, como server, reader, reviewer ou agent-a.
• participant_id: a identidade do agente atual.
• primary_deliverable_type: um de adr, design-spec, implementation-plan, decision-memo, review-report, test-plan ou custom.
• primary_deliverable_file: opcional para tipos embutidos, obrigatório para custom; deve ser Markdown.
• primary_deliverable_checklist: obrigatório para custom.
• deliverables_mode: opcional, padrão é internal; external requer repoRoot.
• deliverables_dir: opcional, padrão é deliverables.

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

Arquivos

Pastas do esquema v2 do ACP usam estes arquivos de protocolo:

• protocol.json: protocol: "acp", schemaVersion: 2, objetivo, participantes, portões gerados e de objetivo, declaração de entrega, fase atual, proprietário da proposta, participantes em espera e timestamps.
• events.jsonl: registro de eventos somente anexo. Cada linha é um objeto JSON compacto.
• proposal.md: resumo da proposta/alteração atual.
• review.md: revisões estruturadas dos participantes.
• decisions.md: índice conciso de decisões aceitas com IDs estáveis.
• readiness.md: classificação de perguntas abertas, portões de objetivo, portões de entrega gerados, instantâneo da entrega, bloqueadores e resultado de prontidão.
• conclusion.md: recibo final do protocolo. Não é o entregável primário.
• deliverables/: entregáveis reais em Markdown e anexos opcionais.

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

Entregáveis

O ACP separa o estado do protocolo dos artefatos de entrega:

• Toda colaboração concluível requer um entregável primário declarado em Markdown.
• conclusion.md é o recibo final; ele referencia o entregável congelado e o resultado de prontidão.
• Tipos de entregável embutidos são adr, design-spec, implementation-plan, decision-memo, review-report e test-plan.
• custom requer um arquivo Markdown explícito e uma checklist.
• Entregáveis de suporte são Markdown. Anexos podem ser arquivos não-Markdown no diretório de entregáveis.
• Modo internal armazena entregáveis dentro da pasta de colaboração.
• Modo external armazena entregáveis em um diretório relativo à raiz do repositório e usa referências external:<file> em eventos, prontidão e conclusão.
• Um entregável deve incluir Status: Draft, Status: In Review ou Status: Frozen.
• O proprietário da proposta congela o entregável primário com deliverable_frozen; o congelamento é estrito e não há caminho para descongelar/recongelar.

Inicialização

Prefira o script fornecido:

python3 <skill>/scripts/init_collaboration.py \
  --folder <pasta_de_colaboracao> \
  --participant <id_do_participante> \
  --participant <id_de_outro_participante> \
  --objective "<objetivo>" \
  --primary-deliverable-type design-spec \
  --completion "<portao_do_objetivo>" \
  --completion "<outro_portao_do_objetivo>"

Para entregáveis externos:

python3 <skill>/scripts/init_collaboration.py \
  --folder <repo>/.acp/<execucao> \
  --participant <id_do_participante> \
  --participant <id_de_outro_participante> \
  --objective "<objetivo>" \
  --primary-deliverable-type adr \
  --deliverables-mode external \
  --repo-root ../.. \
  --deliverables-dir docs/architecture \
  --completion "<portao_do_objetivo>"

O inicializador cria modelos para arquivos de protocolo e o entregável primário. Ele falha se protocol.json já existir, a menos que --resume seja fornecido.

Eventos

Use scripts/append_event.py ou reproduza exatamente seu comportamento. 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 ISO-8601 UTC.
• summary: uma frase curta.

Eventos permitidos:

• initialized
• deliverable_drafted
• deliverable_revised
• deliverable_frozen
• proposal_submitted
• review_submitted
• proposal_revised
• question_classified
• decision_proposed
• decision_accepted
• readiness_passed
• completed
• blocked

Todos os eventos após initialized exigem reply_to apontando para um evento anterior. Referências doc são relativas à pasta de colaboração no modo interno, ou external:<file> no modo externo.

Todos os eventos deliverable_* exigem:

• doc: a referência resolvida do entregável.
• role: primary ou supporting.

deliverable_frozen também exige sha256 de nível superior, um hash SHA-256 hexadecimal de 64 caracteres em minúsculas do arquivo referenciado. Uma vez congelado, o conteúdo do arquivo deve continuar correspondendo ao hash.

Fases

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

• drafting: o proprietário da proposta redige o entregável primário, anexa deliverable_drafted, atualiza proposal.md e, em seguida, anexa proposal_submitted.
• reviewing: os revisores listados revisam tanto proposal.md quanto o entregável primário, anexam revisões estruturadas a review.md e, em seguida, anexam review_submitted.
• revising: o proprietário da proposta atualiza proposal.md e entregáveis conforme necessário, anexa deliverable_revised se um entregável mudou, e então anexa proposal_revised.
• decision_review: o proprietário da proposta classifica todas as perguntas abertas em readiness.md e anexa question_classified; os participantes então aceitam entradas explícitas em decisions.md com decision_accepted.
• readiness_check: o proprietário da proposta congela os entregáveis obrigatórios, registra instantâneos em readiness.md, executa validação e, em seguida, anexa readiness_passed.
• completed: pare a menos que o usuário inicie explicitamente uma nova rodada.
• blocked: pare até que o bloqueador seja resolvido ou uma nova rodada comece.

completed é válido somente após readiness_passed e deve referenciar conclusion.md.

Formato da Revisão

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

## <ISO-8601 UTC> - <id_do_participante> - seq <seq_do_evento_review_submitted>

Contexto:
- Leia `proposal.md` após o evento seq `<seq>`.
- Revisado entregável primário: `<caminho_resolvido>`
- Revisados entregáveis de suporte: `<caminhos ou nenhum>`

Escopo da Revisão:
- Coerência da proposta
- Completude do entregável primário
- Rastreabilidade de decisões aceitas
- Prontidão para implementação

Posição:
- ...

Preocupações:
- ...

Alterações Necessárias:
- ...

Perguntas:
- ...

Decisões

decisions.md é um índice de decisões aceitas, não o entregável. Cada decisão aceita deve usar um ID estável:

### D1. <título curto>

- Decisão: ...
- Justificativa: ...
- Refletido em: `deliverables/design-spec.md#section`

IDs devem ser sequenciais (D1, D2, ...). Refletido em: deve apontar para um entregável primário ou de suporte declarado.

Portão de Prontidão

Antes de readiness_passed ou completed:

• Cada pergunta aberta está [resolved], [deferred_nonblocking] ou [blocking].
• Cada item [deferred_nonblocking] inclui Reason: ....
• Nenhum item [blocking] ou [unresolved] permanece.
• Portões de objetivo são verificados.
• Portões de entrega gerados são verificados.
• O entregável primário tem Status: Frozen.
• O instantâneo SHA-256 do entregável primário está registrado.
• Ready to implement está marcado.
• validate_collaboration.py passa.

Itens de prontidão bloqueadores ou não resolvidos também impedem decision_accepted.

Conclusão Final

Antes de completed, escreva conclusion.md como um recibo final. Deve incluir:

• Resultado da Decisão: exatamente um de [proceed], [do_not_proceed] ou [defer].
• Justificativa.
• Recibo do Entregável: caminho primário, tipo, SHA-256, entregáveis de suporte e anexos.
• Resumo das Decisões Aceitas.
• Resultado de Prontidão.
• Premissas.
• Acompanhamentos Adiados.
• Bloqueadores de Implementação.
• Próxima Ação.

blocked é uma fase/evento, não um resultado concluível.

Polling e Observadores

Os participantes devem permanecer ativos pelo loop de colaboração até que a fase seja completed, blocked ou um prazo explícito do coordenador seja atingido.

Se não houver observador, use:

python3 <skill>/scripts/next_action.py \
  --folder <pasta_de_colaboracao> \
  --participant <id_do_participante>

Para participantes autônomos, prefira:

python3 <skill>/scripts/wait_for_turn.py \
  --folder <pasta_de_colaboracao> \
  --participant <id_do_participante>

wait_for_turn.py retorna quando o participante está listado em waitingFor, ou quando a colaboração se torna completed ou blocked. O padrão é um tempo limite de 30 minutos; use --timeout 0 apenas quando um supervisor externo for responsável pelo cancelamento.

Validação

Execute:

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

O validador verifica arquivos de protocolo obrigatórios, campos do esquema v2, declarações de entregável, segurança de caminho, formato de eventos, funções e hashes de entregáveis, transições de fase, cabeçalhos de revisão, IDs de decisão, portões de prontidão, conteúdo do entregável congelado, recibo de conclusão e ordenação de conclusão.

Códigos de saída:

• 0: validação passou.
• 1: validação passou com avisos.
• 2: validação falhou.