agi-connect/protocolo-de-colaboración-entre-agentes

Protocolo de Colaboración entre Agentes

ACP es un protocolo de coordinación basado en carpetas compartidas para agentes que no pueden comunicarse directamente entre sí. Es una máquina de estados con eventos JSONL estructurados, propiedad de turnos, compuertas de preparación y un entregable congelado. No es una discusión informal en Markdown.

Cualquier agente compatible debe ser capaz de leer y escribir Markdown/JSON, agregar eventos JSONL y ejecutar (o reproducir exactamente) el comportamiento de los scripts incluidos. No confíe en estado oculto del hilo, APIs específicas de proveedores ni memoria de conversación para la corrección del protocolo.

Entradas Requeridas

Antes de comenzar, requiera:

• collaboration_folder: ruta de carpeta compartida absoluta o relativa al repositorio.
• objective: lo que la colaboración debe decidir o producir.
• objective_gates: compuertas específicas del objetivo. El protocolo genera compuertas de entregable automáticamente.
• participants: todos los IDs de participantes, como server, reader, reviewer o agent-a.
• participant_id: la identidad del agente actual.
• primary_deliverable_type: uno de adr, design-spec, implementation-plan, decision-memo, review-report, test-plan o custom.
• primary_deliverable_file: opcional para tipos integrados, obligatorio para custom; debe ser Markdown.
• primary_deliverable_checklist: obligatorio para custom.
• deliverables_mode: opcional, por defecto internal; external requiere repoRoot.
• deliverables_dir: opcional, por defecto deliverables.

Si falta alguna entrada requerida, pregunte antes de crear archivos o escribir eventos. No invente compuertas de objetivo.

Archivos

Las carpetas ACP esquema v2 usan estos archivos de protocolo:

• protocol.json: protocol: "acp", schemaVersion: 2, objetivo, participantes, compuertas generadas y de objetivo, declaración de entregable, fase actual, propietario de propuesta, participantes en espera y marcas de tiempo.
• events.jsonl: registro de eventos de solo añadidura. Cada línea es un objeto JSON compacto.
• proposal.md: resumen de propuesta/cambio actual.
• review.md: revisiones estructuradas de participantes.
• decisions.md: índice conciso de decisiones aceptadas con IDs estables.
• readiness.md: clasificación de preguntas abiertas, compuertas de objetivo, compuertas de entregable generadas, instantánea del entregable, bloqueadores y resultado de preparación.
• conclusion.md: recibo final del protocolo. No es el entregable principal.
• deliverables/: entregables reales en Markdown y archivos adjuntos opcionales.

No cree ni use state.log, discussion.md ni opinions.md. No son archivos de protocolo y no deben aparecer en compuertas ni instrucciones.

Entregables

ACP separa el estado del protocolo de los artefactos entregables:

• Toda colaboración completable requiere un entregable primario en Markdown declarado.
• conclusion.md es el recibo final; referencia el entregable congelado y el resultado de preparación.
• Los tipos de entregable integrados son adr, design-spec, implementation-plan, decision-memo, review-report y test-plan.
• custom requiere un archivo Markdown explícito y una lista de verificación.
• Los entregables de soporte son Markdown. Los archivos adjuntos pueden ser archivos no Markdown en el directorio de entregables.
• El modo internal almacena los entregables dentro de la carpeta de colaboración.
• El modo external almacena los entregables en un directorio relativo a la raíz del repositorio y usa referencias external:<file> en eventos, preparación y conclusión.
• Un entregable debe incluir Estado: Borrador, Estado: En Revisión o Estado: Congelado.
• El propietario de la propuesta congela el entregable primario con deliverable_frozen; la congelación es estricta y no tiene ruta de descongelación/recongelación.

Inicialización

Prefiera el script incluido:

python3 <skill>/scripts/init_collaboration.py \
  --folder <carpeta_colaboracion> \
  --participant <id_participante> \
  --participant <id_otro_participante> \
  --objective "<objetivo>" \
  --primary-deliverable-type design-spec \
  --completion "<compuerta_objetivo>" \
  --completion "<otra_compuerta_objetivo>"

Para entregables externos:

python3 <skill>/scripts/init_collaboration.py \
  --folder <repo>/.acp/<ejecucion> \
  --participant <id_participante> \
  --participant <id_otro_participante> \
  --objective "<objetivo>" \
  --primary-deliverable-type adr \
  --deliverables-mode external \
  --repo-root ../.. \
  --deliverables-dir docs/architecture \
  --completion "<compuerta_objetivo>"

El inicializador crea plantillas para los archivos de protocolo y el entregable primario. Falla si protocol.json ya existe a menos que se proporcione --resume.

Eventos

Use scripts/append_event.py o reproduzca exactamente su comportamiento. Campos requeridos del evento:

• seq: entero continuo en events.jsonl.
• from: ID de participante listado en protocol.json.
• event: nombre de evento permitido.
• at: marca de tiempo ISO-8601 UTC.
• summary: una oración corta.

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 los eventos posteriores a initialized requieren reply_to que apunte a un evento anterior. Las referencias doc son relativas a la carpeta de colaboración en modo interno, o external:<file> en modo externo.

Todos los eventos deliverable_* requieren:

• doc: la referencia resuelta del entregable.
• role: primary o supporting.

deliverable_frozen también requiere sha256 de nivel superior, un hash SHA-256 hexadecimal en minúsculas de 64 caracteres del archivo referenciado. Una vez congelado, el contenido del archivo debe seguir coincidiendo con el hash.

Fases

Los agentes deben actuar según protocol.json.currentPhase y protocol.json.waitingFor:

• drafting: el propietario de la propuesta redacta el entregable primario, añade deliverable_drafted, actualiza proposal.md, luego añade proposal_submitted.
• reviewing: los revisores listados revisan tanto proposal.md como el entregable primario, añaden revisiones estructuradas a review.md, luego añaden review_submitted.
• revising: el propietario de la propuesta actualiza proposal.md y los entregables según sea necesario, añade deliverable_revised si un entregable cambió, luego añade proposal_revised.
• decision_review: el propietario de la propuesta clasifica cada pregunta abierta en readiness.md y añade question_classified; los participantes luego aceptan entradas explícitas de decisions.md con decision_accepted.
• readiness_check: el propietario de la propuesta congela los entregables requeridos, registra instantáneas en readiness.md, ejecuta validación, luego añade readiness_passed.
• completed: deténgase a menos que el usuario inicie explícitamente una nueva ronda.
• blocked: deténgase hasta que el bloqueador se resuelva o comience una nueva ronda.

completed solo es válido después de readiness_passed y debe referenciar conclusion.md.

Formato de Revisión

Cada evento review_submitted debe tener un encabezado review.md cuyo seq coincida con el seq de ese evento:

## <ISO-8601 UTC> - <id_participante> - seq <seq evento review_submitted>

Contexto:
- Leer `proposal.md` después del evento seq `<seq>`.
- Entregable primario revisado: `<ruta resuelta>`
- Entregables de soporte revisados: `<rutas o ninguno>`

Alcance de la Revisión:
- Coherencia de la propuesta
- Integridad del entregable primario
- Trazabilidad de decisiones aceptadas
- Preparación para implementación

Posición:
- ...

Preocupaciones:
- ...

Cambios Requeridos:
- ...

Preguntas:
- ...

Decisiones

decisions.md es un índice de decisiones aceptadas, no el entregable. Cada decisión aceptada debe usar un ID estable:

### D1. <título corto>

- Decisión: ...
- Justificación: ...
- Reflejado en: `deliverables/design-spec.md#seccion`

Los IDs deben ser secuenciales (D1, D2, ...). Reflejado en: debe apuntar a un entregable primario o de soporte declarado.

Compuerta de Preparación

Antes de readiness_passed o completed:

• Cada pregunta abierta está [resuelta], [diferida_no_bloqueante] o [bloqueante].
• Cada elemento [diferido_no_bloqueante] incluye Motivo: ....
• No queda ningún elemento [bloqueante] o [no_resuelto].
• Las compuertas de objetivo se verifican.
• Las compuertas de entregable generadas se verifican.
• El entregable primario tiene Estado: Congelado.
• La instantánea SHA-256 del entregable primario está registrada.
• Listo para implementar está marcado.
• validate_collaboration.py pasa.

Los elementos de preparación bloqueantes o no resueltos también impiden decision_accepted.

Conclusión Final

Antes de completed, escriba conclusion.md como recibo final. Debe incluir:

• Resultado de la Decisión: exactamente uno de [proceder], [no_proceder] o [diferir].
• Justificación.
• Recibo del Entregable: ruta primaria, tipo, SHA-256, entregables de soporte y archivos adjuntos.
• Resumen de Decisiones Aceptadas.
• Resultado de Preparación.
• Suposiciones.
• Seguimientos Diferidos.
• Bloqueadores de Implementación.
• Próxima Acción.

blocked es una fase/evento, no un resultado completable.

Sondeo y Vigilantes

Los participantes deben permanecer activos para el bucle de colaboración hasta que la fase sea completed, blocked o se alcance una fecha límite explícita del coordinador.

Si no hay vigilante, use:

python3 <skill>/scripts/next_action.py \
  --folder <carpeta_colaboracion> \
  --participant <id_participante>

Para participantes autónomos, prefiera:

python3 <skill>/scripts/wait_for_turn.py \
  --folder <carpeta_colaboracion> \
  --participant <id_participante>

wait_for_turn.py regresa cuando el participante está listado en waitingFor, o cuando la colaboración pasa a completed o blocked. Por defecto tiene un tiempo de espera de 30 minutos; use --timeout 0 solo cuando un supervisor externo posea la cancelación.

Validación

Ejecute:

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

El validador verifica archivos de protocolo requeridos, campos del esquema v2, declaraciones de entregables, seguridad de rutas, forma de eventos, roles y hashes de entregables, transiciones de fase, encabezados de revisión, IDs de decisión, compuertas de preparación, contenido de entregable congelado, recibo de conclusión y orden de finalización.

Códigos de salida:

• 0: validación exitosa.
• 1: validación exitosa con advertencias.
• 2: validación fallida.