Agentes ACP (Protocolo de Colaboración entre Agentes)

Protocolo de Colaboración entre Agentes (ACP)

Utiliza una carpeta compartida como un bus de coordinación portátil para agentes que no pueden darse mensajes directamente. ACP es un protocolo de ruptura: es una máquina de estados con eventos estructurados y compuertas de preparación, no una conversación informal en Markdown.

Cualquier agente compatible debe ser capaz de leer Markdown y JSON, escribir Markdown, añadir eventos JSONL, y ejecutar o reproducir exactamente el comportamiento de los scripts incluidos. No dependas de las APIs de hilos de Codex, ganchos específicos de Claude, estado exclusivo de OpenCode, metadatos solo de Kiro, o memoria de conversación oculta para la corrección.

Entradas Requeridas

Antes de comenzar, solicita:

• carpeta_colaboracion: ruta absoluta o relativa al repositorio de la carpeta compartida.
• objetivo: qué debe decidir o producir la colaboración.
• compuertas_finalizacion: compuertas concretas para finalizar la colaboración.
• participantes: todos los identificadores de los participantes, como servidor, lector, revisor, o agente-a.
• id_participante: la identidad del agente actual.

Si falta alguna entrada requerida, pídela antes de crear archivos o escribir eventos. No inventes compuertas de finalización.

Archivos

Las carpetas ACP utilizan estos archivos:

• protocolo.json: objetivo, participantes, compuertas de finalización, fase actual, propietario de la propuesta, participantes en espera y marcas de tiempo.
• eventos.jsonl: registro de eventos solo de añadidura. Cada línea es un objeto JSON compacto.
• propuesta.md: solo la propuesta actual.
• revision.md: revisiones estructuradas de los participantes.
• decisiones.md: solo las decisiones aceptadas.
• preparacion.md: clasificación de preguntas abiertas, bloqueadores, elementos diferidos no bloqueantes y preparación para la implementación.
• conclusion.md: conclusión final de la discusión. Indica si proceder, no proceder, diferir o bloquear; por qué; cómo implementar o por qué no; y la siguiente acción.

No crees ni uses estado.log, discusion.md o opiniones.md. No son archivos del protocolo y no deben aparecer en compuertas de finalización ni instrucciones.

Inicialización

Prefiere el script empaquetado:

python3 <skill>/scripts/init_colaboracion.py \
  --carpeta <carpeta_colaboracion> \
  --participante <id_participante> \
  --participante <otro_id_participante> \
  --objetivo "<objetivo>" \
  --finalizacion "<compuerta finalizacion>" \
  --finalizacion "<otra compuerta>"

El inicializador falla si protocolo.json ya existe a menos que se proporcione --reanudar. La inicialización repetida no es una operación de añadidura.

Eventos

Usa scripts/anadir_evento.py o reproduce exactamente su comportamiento. No escribas eventos a mano a menos que el entorno de ejecución no pueda ejecutar scripts.

Campos obligatorios del evento:

• sec: entero continuo en eventos.jsonl.
• de: identificador del participante listado en protocolo.json.
• evento: nombre del evento permitido.
• en: marca de tiempo UTC ISO-8601.
• resumen: una oración corta.

Campos recomendados:

• doc: ruta relativa a la carpeta de colaboración.
• respuesta_a: sec de un evento anterior.

Eventos permitidos:

• inicializado
• propuesta_enviada
• revision_enviada
• propuesta_revisada
• pregunta_clasificada
• decision_propuesta
• decision_aceptada
• preparacion_superada
• completado
• bloqueado

Todas las respuestas deben usar respuesta_a cuando responden a un evento anterior. respuesta_a debe apuntar a un evento existente anterior. Las marcas de tiempo de los eventos no deben retroceder a medida que aumenta sec. Si se descubre un error, añade bloqueado o un nuevo evento correctivo; no reescribas eventos anteriores.

Fases

Los agentes deben actuar según protocolo.json.faseActual y protocolo.json.esperandoA:

• borrador: el propietario de la propuesta actualiza propuesta.md, luego añade propuesta_enviada.
• revision: solo los participantes listados en esperandoA añaden revisiones estructuradas a revision.md, luego añaden revision_enviada.
• revision: el propietario de la propuesta aborda los cambios requeridos y añade propuesta_revisada.
• revision_decision: el propietario de la propuesta primero clasifica cada pregunta abierta en preparacion.md y añade pregunta_clasificada; solo entonces los participantes listados en esperandoA aceptan decisiones explícitas en decisiones.md añadiendo decision_aceptada.
• verificacion_preparacion: los participantes clasifican cada pregunta, eliminan bloqueadores y superan la preparación, luego el propietario de la propuesta escribe conclusion.md.
• completado: detente a menos que el usuario inicie explícitamente una nueva ronda.
• bloqueado: detente hasta que se resuelva el bloqueador.

completado solo es válido después de un evento preparacion_superada anterior. completado debe hacer referencia a conclusion.md. No completes solo con decisiones.md; las decisiones son entradas, mientras que conclusion.md es la respuesta final al objetivo de la colaboración.

El propietario de la propuesta debe esperar después de propuesta_enviada. Mientras la fase sea revision, el propietario puede sondear la siguiente acción o añadir bloqueado para un tiempo de espera/bloqueador real, pero no debe editar propuesta.md, decisiones.md, preparacion.md o protocolo.json, y no debe añadir eventos de avance hasta que se haya enviado la revisión requerida.

Formato de Revisión

Cada evento revision_enviada debe tener un encabezado coincidente en revision.md cuyo sec sea igual a la sec de ese evento:

## <UTC ISO-8601> - <id_participante> - sec <sec de evento revision_enviada>

Contexto:
- Leer `propuesta.md` después del evento sec `<sec>`.

Posición:
- ...

Preocupaciones:
- ...

Cambios Requeridos:
- ...

Preguntas:
- ...

No uses la sec del evento al que se responde en el encabezado de la revisión. Pon el contexto de la respuesta en Contexto y respuesta_a.

Compuerta de Preparación

Antes de preparacion_superada o completado:

• Cada pregunta abierta debe clasificarse como [resuelta], [diferida_no_bloqueante] o [bloqueante].
• Cada elemento [diferido_no_bloqueante] debe incluir Razón: ....
• No puede quedar ningún elemento [bloqueante] o [no_resuelto].
• La lista de verificación de diseño final debe incluir y marcar Listo para implementar.
• validar_colaboracion.py debe pasar.

Los elementos de preparación bloqueantes también impiden decision_aceptada. Las preguntas no resueltas y los elementos diferidos que carecen de Razón: ... también impiden decision_aceptada.

Los documentos de diseño final deben separar:

• Decisiones Aceptadas
• Suposiciones
• Seguimientos Diferidos
• Bloqueadores de Implementación
• Listo para Implementar

Conclusión Final

Antes de completado, escribe conclusion.md como un documento de conclusión, no un registro. Debe incluir:

• Resultado de la Decisión: exactamente uno de [proceder], [no_proceder] o [diferir].
• Justificación.
• Decisiones Aceptadas.
• Enfoque de Implementación.
• Suposiciones.
• Seguimientos Diferidos.
• Bloqueadores de Implementación.
• Siguiente Acción.

Usa [proceder] cuando la implementación deba comenzar ahora, [no_proceder] cuando la característica o el plan no deba realizarse, y [diferir] cuando deba realizarse un trabajo de seguimiento antes de la implementación. Un resultado [bloqueado] puede existir mientras la colaboración está bloqueada, pero no es completable.

Sondeo y Vigilantes

Los participantes deben permanecer activos para el bucle de colaboración hasta que la fase sea completado, bloqueado, o se alcance un plazo explícito del usuario/coordinador. No te detengas solo porque añadiste un evento válido. Después de cada acción, lee protocolo.json nuevamente y toma la siguiente acción permitida o espera el siguiente evento.

Si el entorno de ejecución tiene un vigilante, puede notificar al participante cuando eventos.jsonl o protocolo.json cambien. El vigilante debe permanecer tonto: solo nota los cambios y nunca escribe análisis o decisiones.

Si no hay vigilante, usa:

python3 <skill>/scripts/siguiente_accion.py \
  --carpeta <carpeta_colaboracion> \
  --participante <id_participante>

Para participantes autónomos, prefiere el ayudante de bloqueo:

python3 <skill>/scripts/esperar_turno.py \
  --carpeta <carpeta_colaboracion> \
  --participante <id_participante>

esperar_turno.py retorna cuando el participante está listado en esperandoA, o cuando la colaboración se vuelve completado o bloqueado. Por defecto tiene un tiempo de espera de 30 minutos para evitar procesos participantes atascados permanentemente; usa --tiempo_espera 0 solo cuando un supervisor externo gestiona la cancelación. Al retornar, inspecciona siguiente_accion.py, actúa si es tu turno, añade el evento requerido y repite el bucle de espera/acción. Las indicaciones manuales del usuario como "verifica la nueva opinión" son solo un respaldo, no el bucle de colaboración previsto.

Las indicaciones del coordinador que inician participantes deben pedir a cada participante que ejecute este bucle en lugar de hacer una fase y salir. Un participante que no esté listado en esperandoA puede bloquearse en esperar_turno.py, pero no debe editar el estado compartido mientras espera.

Validación

Ejecuta:

python3 <skill>/scripts/validar_colaboracion.py --carpeta <carpeta_colaboracion>

El validador verifica archivos requeridos, ausencia de archivos obsoletos, forma de los eventos, continuidad de sec, monotonicidad de marcas de tiempo, transiciones de fase, propiedad de esperandoA, respuesta_a, secuencias de encabezados de revisión, clasificación de preparación, integridad de la conclusión y orden de finalización.

Códigos de salida:

• 0: válido.
• 1: válido con advertencias.
• 2: inválido.