benjinus/agent-collaboration-protocol

Agent Collaboration Protocol

Verwenden Sie einen gemeinsamen Ordner als portablen Koordinationsbus für Agenten, die sich nicht direkt Nachrichten senden können. ACP ist ein zustandsbasiertes Protokoll: Es handelt sich um eine Zustandsmaschine mit strukturierten Ereignissen und Bereitschaftsgattern, nicht um ein lockeres Markdown-Gespräch.

Jeder kompatible Agent muss in der Lage sein, Markdown und JSON zu lesen, Markdown zu schreiben, JSONL-Ereignisse anzuhängen und das gebündelte Skriptverhalten auszuführen oder exakt zu reproduzieren. Verlassen Sie sich für die Korrektheit nicht auf Codex-Thread-APIs, Claude-spezifische Hooks, OpenCode-exklusive Zustände, Kiro-exklusive Metadaten oder versteckten Konversationsspeicher.

Erforderliche Eingaben

Fordern Sie vor dem Start Folgendes an:

• collaboration_folder: Absoluter oder repository-relativer Pfad zum gemeinsamen Ordner.
• objective: Was die Zusammenarbeit entscheiden oder hervorbringen muss.
• completion_gates: Konkrete Gatter für den Abschluss der Zusammenarbeit.
• participants: Alle Teilnehmer-IDs wie server, reader, reviewer oder agent-a.
• participant_id: Die Identität des aktuellen Agenten.

Wenn eine erforderliche Eingabe fehlt, fragen Sie danach, bevor Sie Dateien erstellen oder Ereignisse schreiben. Erfinden Sie keine Abschlussgatter.

Dateien

ACP-Ordner verwenden die folgenden Dateien:

• protocol.json: Zielsetzung, Teilnehmer, Abschlussgatter, aktuelle Phase, Vorschlagsbesitzer, wartende Teilnehmer und Zeitstempel.
• events.jsonl: Nur-Anhängen-Ereignisprotokoll. Jede Zeile ist ein kompaktes JSON-Objekt.
• proposal.md: Nur der aktuelle Vorschlag.
• review.md: Strukturierte Teilnehmerbewertungen.
• decisions.md: Nur akzeptierte Entscheidungen.
• readiness.md: Klassifizierung offener Fragen, Blocker, zurückgestellte nicht blockierende Elemente und Implementierungsbereitschaft.
• conclusion.md: Endgültige Schlussfolgerung der Diskussion. Sie gibt an, ob fortgefahren werden soll, nicht fortgefahren werden soll, verschoben werden soll oder ob ein Blocker vorliegt; warum; wie zu implementieren ist oder warum nicht; und die nächste Aktion.

Erstellen oder verwenden Sie nicht state.log, discussion.md oder opinions.md. Es handelt sich nicht um Protokolldateien und sie dürfen nicht in Abschlussgattern oder Anweisungen erscheinen.

Initialisierung

Bevorzugen Sie das gebündelte Skript:

python3 <skill>/scripts/init_collaboration.py \
  --folder <collaboration_folder> \
  --participant <participant_id> \
  --participant <other_participant_id> \
  --objective "<objective>" \
  --completion "<completion gate>" \
  --completion "<another gate>"

Der Initialisierer schlägt fehl, wenn protocol.json bereits existiert, es sei denn, --resume wird angegeben. Wiederholte Initialisierung ist kein Anhängevorgang.

Ereignisse

Verwenden Sie scripts/append_event.py oder reproduzieren Sie dessen Verhalten exakt. Schreiben Sie Ereignisse nicht von Hand, es sei denn, die Laufzeitumgebung kann keine Skripte ausführen.

Erforderliche Ereignisfelder:

• seq: fortlaufende Ganzzahl in events.jsonl.
• from: Teilnehmer-ID aus protocol.json.
• event: Erlaubter Ereignisname.
• at: ISO-8601 UTC Zeitstempel.
• summary: Ein kurzer Satz.

Empfohlene Felder:

• doc: Pfad relativ zum Kollaborationsordner.
• reply_to: Frühere Ereignis-seq.

Erlaubte Ereignisse:

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

Alle Antworten müssen reply_to verwenden, wenn sie auf ein vorheriges Ereignis antworten. reply_to muss auf ein früheres, vorhandenes Ereignis verweisen. Ereigniszeitstempel dürfen mit steigendem seq nicht rückwärts gehen. Wenn ein Fehler entdeckt wird, hängen Sie blocked oder ein neues korrigierendes Ereignis an; überschreiben Sie keine früheren Ereignisse.

Phasen

Agenten müssen gemäß protocol.json.currentPhase und protocol.json.waitingFor handeln:

• drafting: Der Vorschlagsbesitzer aktualisiert proposal.md und hängt dann proposal_submitted an.
• reviewing: Nur die in waitingFor aufgeführten Teilnehmer hängen strukturierte Bewertungen an review.md an und hängen dann review_submitted an.
• revising: Der Vorschlagsbesitzer adressiert erforderliche Änderungen und hängt proposal_revised an.
• decision_review: Der Vorschlagsbesitzer klassifiziert zunächst jede offene Frage in readiness.md und hängt question_classified an; erst dann akzeptieren die in waitingFor aufgeführten Teilnehmer explizite Entscheidungen in decisions.md, indem sie decision_accepted anhängen.
• readiness_check: Teilnehmer klassifizieren jede Frage, räumen Blocker aus und bestehen die Bereitschaft, dann schreibt der Vorschlagsbesitzer conclusion.md.
• completed: Anhalten, es sei denn, der Benutzer startet explizit eine neue Runde.
• blocked: Anhalten, bis der Blocker aufgelöst ist.

completed ist nur gültig nach einem vorherigen readiness_passed-Ereignis. completed muss auf conclusion.md verweisen. Schließen Sie nicht nur mit decisions.md ab; Entscheidungen sind Eingaben, während conclusion.md die endgültige Antwort auf das Kooperationsziel ist.

Der Vorschlagsbesitzer muss nach proposal_submitted warten. Solange die Phase reviewing ist, darf der Besitzer auf die nächste Aktion warten oder blocked für einen echten Timeout/Blocker anhängen, aber proposal.md, decisions.md, readiness.md oder protocol.json nicht bearbeiten und keine voranschreitenden Ereignisse anhängen, bis die erforderliche Bewertung eingereicht wurde.

Bewertungsformat

Jedes review_submitted-Ereignis muss eine passende review.md-Überschrift haben, deren seq der seq dieses Ereignisses entspricht:

## <ISO-8601 UTC> - <participant_id> - seq <review_submitted event seq>

Kontext:
- `proposal.md` nach Ereignis seq `<seq>` gelesen.

Position:
- ...

Bedenken:
- ...

Erforderliche Änderungen:
- ...

Fragen:
- ...

Verwenden Sie nicht die seq des beantworteten Ereignisses in der Bewertungsüberschrift. Setzen Sie den Kontext der Antwort in Kontext und reply_to.

Bereitschaftsgatter

Vor readiness_passed oder completed:

• Jede offene Frage muss als [resolved], [deferred_nonblocking] oder [blocking] klassifiziert sein.
• Jeder [deferred_nonblocking]-Eintrag muss Reason: ... enthalten.
• Es darf kein [blocking]- oder [unresolved]-Eintrag mehr vorhanden sein.
• Die endgültige Design-Checkliste muss Ready to implement enthalten und abgehakt sein.
• validate_collaboration.py muss erfolgreich sein.

Blockierende Bereitschaftselemente verhindern auch decision_accepted. Nicht aufgelöste Fragen und zurückgestellte Elemente ohne Reason: ... verhindern ebenfalls decision_accepted.

Endgültige Designdokumente müssen trennen:

• Akzeptierte Entscheidungen
• Annahmen
• Zurückgestellte Folgemaßnahmen
• Implementierungsblocker
• Bereit zur Implementierung

Endgültige Schlussfolgerung

Schreiben Sie vor completed conclusion.md als Schlussfolgerungsdokument, nicht als Protokoll. Es muss Folgendes enthalten:

• Entscheidungsergebnis: genau eines von [proceed], [do_not_proceed] oder [defer].
• Begründung.
• Akzeptierte Entscheidungen.
• Implementierungsansatz.
• Annahmen.
• Zurückgestellte Folgemaßnahmen.
• Implementierungsblocker.
• Nächste Aktion.

Verwenden Sie [proceed], wenn die Implementierung sofort beginnen soll, [do_not_proceed], wenn die Funktion oder der Plan nicht umgesetzt werden soll, und [defer], wenn vor der Implementierung Folgemaßnahmen erforderlich sind. Ein [blocked]-Ergebnis kann existieren, während die Zusammenarbeit blockiert ist, ist aber nicht abschließbar.

Abfrage und Beobachter

Teilnehmer müssen für die Zusammenarbeitsschleife aktiv bleiben, bis die Phase completed, blocked oder eine explizite Frist des Benutzers/Koordinators erreicht ist. Hören Sie nicht auf, nur weil Sie ein gültiges Ereignis angehängt haben. Lesen Sie nach jeder Aktion erneut protocol.json und führen Sie entweder die nächste zulässige Aktion aus oder warten Sie auf das nächste Ereignis.

Wenn die Laufzeitumgebung einen Beobachter hat, kann dieser den Teilnehmer benachrichtigen, wenn sich events.jsonl oder protocol.json ändert. Der Beobachter muss dumm bleiben: Er bemerkt nur Änderungen und schreibt niemals Analysen oder Entscheidungen.

Wenn es keinen Beobachter gibt, verwenden Sie:

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

Für autonome Teilnehmer bevorzugen Sie den blockierenden Helfer:

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

wait_for_turn.py kehrt zurück, wenn der Teilnehmer in waitingFor aufgeführt ist oder wenn die Zusammenarbeit completed oder blocked wird. Standardmäßig beträgt das Timeout 30 Minuten, um dauerhaft hängende Teilnehmerprozesse zu vermeiden; verwenden Sie --timeout 0 nur, wenn ein externer Supervisor die Abbrechen steuert. Überprüfen Sie bei Rückkehr next_action.py, handeln Sie, wenn Sie an der Reihe sind, hängen Sie das erforderliche Ereignis an und wiederholen Sie die Warten/Handeln-Schleife. Manuelle Benutzeraufforderungen wie "Prüfen Sie die neue Meinung" sind nur ein Fallback, nicht die beabsichtigte Kooperationsschleife.

Koordinator-Prompts, die Teilnehmer starten, sollten jeden Teilnehmer bitten, diese Schleife auszuführen, anstatt nur eine Phase zu machen und zu beenden. Ein Teilnehmer, der nicht in waitingFor aufgeführt ist, kann in wait_for_turn.py blocken, aber während des Wartens darf er keinen gemeinsamen Zustand bearbeiten.

Validierung

Führen Sie aus:

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

Der Validator prüft erforderliche Dateien, Abwesenheit veralteter Dateien, Ereignisstruktur, seq-Kontinuität, Zeitstempel-Monotonie, Phasenübergänge, waitingFor-Besitz, reply_to, Bewertungsüberschriften-seqs, Bereitschaftsklassifizierung, Vollständigkeit der Schlussfolgerung und Abschlussreihenfolge.

Exit-Codes:

• 0: gültig.
• 1: gültig mit Warnungen.
• 2: ungültig.