agi-connect/agent-collaboration-protocol

Agent Collaboration Protocol

ACP ist ein Shared-Folder-Koordinationsprotokoll für Agenten, die nicht direkt miteinander kommunizieren können. Es ist ein Zustandsautomat mit strukturierten JSONL-Ereignissen, Turn-Besitzer, Bereitschaftsgates und einem eingefrorenen Arbeitsergebnis. Es handelt sich nicht um eine lockere Markdown-Diskussion.

Jeder kompatible Agent muss in der Lage sein, Markdown/JSON zu lesen und zu schreiben, JSONL-Ereignisse anzuhängen und das gebündelte Skriptverhalten auszuführen oder exakt nachzubilden. Verlassen Sie sich für die Korrektheit des Protokolls nicht auf versteckte Thread-Zustände, anbieterspezifische APIs oder Gesprächsspeicher.

Erforderliche Eingaben

Vor dem Start müssen folgende Angaben vorliegen:

• collaboration_folder: absoluter oder repo-relativer Pfad zum gemeinsamen Ordner.
• objective: was die Zusammenarbeit entscheiden oder erzeugen soll.
• objective_gates: objektive spezifische Gates. Das Protokoll generiert Arbeitsergebnis-Gates automatisch.
• participants: alle Teilnehmer-IDs, z.B. server, reader, reviewer, oder agent-a.
• participant_id: die Identität des aktuellen Agenten.
• primary_deliverable_type: einer von adr, design-spec, implementation-plan, decision-memo, review-report, test-plan oder custom.
• primary_deliverable_file: optional für integrierte Typen, erforderlich für custom; muss Markdown sein.
• primary_deliverable_checklist: erforderlich für custom.
• deliverables_mode: optional, Standardwert internal; external erfordert repoRoot.
• deliverables_dir: optional, Standardwert deliverables.

Wenn eine erforderliche Eingabe fehlt, fragen Sie nach, bevor Sie Dateien anlegen oder Ereignisse schreiben. Erfinden Sie keine objective gates.

Dateien

ACP-Schema-v2-Ordner verwenden diese Protokolldateien:

• protocol.json: protocol: "acp", schemaVersion: 2, objective, Teilnehmer, generierte und objektive Gates, Arbeitsergebnis-Deklaration, aktuelle Phase, Vorschlagsbesitzer, wartende Teilnehmer und Zeitstempel.
• events.jsonl: Nur-Anhängen-Ereignislog. Jede Zeile ist ein kompaktes JSON-Objekt.
• proposal.md: aktuelle Vorschlags-/Änderungszusammenfassung.
• review.md: strukturierte Teilnehmerbewertungen.
• decisions.md: knapper Index akzeptierter Entscheidungen mit stabilen IDs.
• readiness.md: Klassifizierung offener Fragen, objective gates, generierte Arbeitsergebnis-Gates, Arbeitsergebnis-Snapshot, Blocker und Bereitschaftsergebnis.
• conclusion.md: endgültiger Protokollbeleg. Es ist nicht das primäre Arbeitsergebnis.
• deliverables/: tatsächliche Markdown-Arbeitsergebnisse und optionale Anhänge.

Erstellen oder verwenden Sie nicht state.log, discussion.md oder opinions.md. Es sind keine Protokolldateien und dürfen nicht in Gates oder Anweisungen erscheinen.

Arbeitsergebnisse

ACP trennt den Protokollzustand von Arbeitsergebnis-Artefakten:

• Jede abschließbare Zusammenarbeit erfordert ein deklariertes primäres Markdown-Arbeitsergebnis.
• conclusion.md ist der endgültige Beleg; es referenziert das eingefrorene Arbeitsergebnis und das Bereitschaftsergebnis.
• Integrierte Arbeitsergebnis-Typen sind adr, design-spec, implementation-plan, decision-memo, review-report und test-plan.
• custom erfordert eine explizite Markdown-Datei und Checkliste.
• Unterstützende Arbeitsergebnisse sind Markdown. Anhänge können Nicht-Markdown-Dateien im Arbeitsergebnisverzeichnis sein.
• Der Modus internal speichert Arbeitsergebnisse im Kollaborationsordner.
• Der Modus external speichert Arbeitsergebnisse in einem repo-root-relativen Verzeichnis und verwendet external:<file>-Referenzen in Ereignissen, Bereitschaft und Schlussfolgerung.
• Ein Arbeitsergebnis muss Status: Draft, Status: In Review oder Status: Frozen enthalten.
• Der Vorschlagsbesitzer friert das primäre Arbeitsergebnis mit deliverable_frozen ein; Einfrieren ist strikt und hat keinen Auftau-/Wiedereinfrier-Pfad.

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>" \
  --primary-deliverable-type design-spec \
  --completion "<objective gate>" \
  --completion "<weiteres objective gate>"

Für externe Arbeitsergebnisse:

python3 <skill>/scripts/init_collaboration.py \
  --folder <repo>/.acp/<run> \
  --participant <participant_id> \
  --participant <other_participant_id> \
  --objective "<objective>" \
  --primary-deliverable-type adr \
  --deliverables-mode external \
  --repo-root ../.. \
  --deliverables-dir docs/architecture \
  --completion "<objective gate>"

Der Initialisierer erstellt Vorlagen für Protokolldateien und das primäre Arbeitsergebnis. Er schlägt fehl, wenn protocol.json bereits existiert, es sei denn, --resume wird bereitgestellt.

Ereignisse

Verwenden Sie scripts/append_event.py oder reproduzieren Sie dessen Verhalten exakt. Erforderliche Ereignisfelder:

• seq: fortlaufende ganze Zahl in events.jsonl.
• from: Teilnehmer-ID, die in protocol.json aufgeführt ist.
• event: zulässiger Ereignisname.
• at: ISO-8601 UTC-Zeitstempel.
• summary: ein kurzer Satz.

Zulässige Ereignisse:

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

Alle Ereignisse nach initialized erfordern reply_to, das auf ein früheres Ereignis verweist. doc-Referenzen sind relativ zum Kollaborationsordner im internen Modus oder external:<file> im externen Modus.

Alle deliverable_*-Ereignisse erfordern:

• doc: die aufgelöste Arbeitsergebnis-Referenz.
• role: primary oder supporting.

deliverable_frozen erfordert außerdem das Top-Level-Feld sha256, einen 64-stelligen hexadezimalen SHA-256 in Kleinbuchstaben der referenzierten Datei. Nach dem Einfrieren muss der Dateiinhalt weiterhin mit dem Hash übereinstimmen.

Phasen

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

• drafting: Vorschlagsbesitzer erstellt das primäre Arbeitsergebnis, hängt deliverable_drafted an, aktualisiert proposal.md, hängt dann proposal_submitted an.
• reviewing: aufgelistete Prüfer überprüfen sowohl proposal.md als auch das primäre Arbeitsergebnis, hängen strukturierte Bewertungen an review.md an, hängen dann review_submitted an.
• revising: Vorschlagsbesitzer aktualisiert proposal.md und Arbeitsergebnisse nach Bedarf, hängt deliverable_revised an, wenn sich ein Arbeitsergebnis geändert hat, hängt dann proposal_revised an.
• decision_review: Vorschlagsbesitzer klassifiziert jede offene Frage in readiness.md und hängt question_classified an; Teilnehmer akzeptieren dann explizite decisions.md-Einträge mit decision_accepted.
• readiness_check: Vorschlagsbesitzer friert erforderliche Arbeitsergebnisse ein, zeichnet Snapshots in readiness.md auf, führt die Validierung durch, hängt dann readiness_passed an.
• completed: anhalten, es sei denn, der Benutzer startet explizit eine neue Runde.
• blocked: anhalten, bis der Blocker aufgelöst ist oder eine neue Runde beginnt.

completed ist nur nach readiness_passed gültig und muss conclusion.md referenzieren.

Bewertungsformat

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

## <ISO-8601 UTC> - <participant_id> - seq <seq des review_submitted-Ereignisses>

Kontext:
- `proposal.md` gelesen nach Ereignis seq `<seq>`.
- Primäres Arbeitsergebnis geprüft: `<aufgelöster Pfad>`
- Unterstützende Arbeitsergebnisse geprüft: `<Pfade oder none>`

Prüfumfang:
- Kohärenz des Vorschlags
- Vollständigkeit des primären Arbeitsergebnisses
- Rückverfolgbarkeit akzeptierter Entscheidungen
- Implementierungsbereitschaft

Position:
- ...

Bedenken:
- ...

Erforderliche Änderungen:
- ...

Fragen:
- ...

Entscheidungen

decisions.md ist ein Index akzeptierter Entscheidungen, nicht das Arbeitsergebnis. Jede akzeptierte Entscheidung muss eine stabile ID verwenden:

### D1. <kurzer Titel>

- Entscheidung: ...
- Begründung: ...
- Reflektiert in: `deliverables/design-spec.md#abschnitt`

IDs müssen fortlaufend sein (D1, D2, ...). Reflektiert in: muss auf ein deklariertes primäres oder unterstützendes Arbeitsergebnis verweisen.

Bereitschafts-Gate

Vor readiness_passed oder completed:

• Jede offene Frage ist [resolved], [deferred_nonblocking] oder [blocking].
• Jeder [deferred_nonblocking]-Eintrag enthält Reason: ....
• Kein [blocking]- oder [unresolved]-Eintrag ist mehr vorhanden.
• Objective gates werden überprüft.
• Generierte Arbeitsergebnis-Gates werden überprüft.
• Das primäre Arbeitsergebnis hat Status: Frozen.
• Der SHA-256-Snapshot des primären Arbeitsergebnisses wird aufgezeichnet.
• Ready to implement ist aktiviert.
• validate_collaboration.py bestanden.

Blockierende oder ungelöste Bereitschaftseinträge verhindern auch decision_accepted.

Abschließende Schlussfolgerung

Vor completed schreiben Sie conclusion.md als endgültigen Beleg. Er muss enthalten:

• Entscheidungsergebnis: genau eines von [proceed], [do_not_proceed] oder [defer].
• Begründung.
• Arbeitsergebnis-Beleg: primärer Pfad, Typ, SHA-256, unterstützende Arbeitsergebnisse und Anhänge.
• Zusammenfassung akzeptierter Entscheidungen.
• Bereitschaftsergebnis.
• Annahmen.
• Zurückgestellte Folgemaßnahmen.
• Implementierungsblocker.
• Nächste Aktion.

blocked ist eine Phase/ein Ereignis, kein abschließbares Ergebnis.

Abfragen und Beobachter

Teilnehmer müssen für die Kollaborationsschleife aktiv bleiben, bis die Phase completed, blocked oder eine explizite Koordinatorfrist erreicht ist.

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:

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

wait_for_turn.py gibt die Kontrolle zurück, wenn der Teilnehmer in waitingFor aufgeführt ist oder wenn die Zusammenarbeit completed oder blocked wird. Das Standard-Timeout beträgt 30 Minuten; verwenden Sie --timeout 0 nur, wenn ein externer Supervisor den Abbruch übernimmt.

Validierung

Führen Sie aus:

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

Der Validator prüft erforderliche Protokolldateien, Schema-v2-Felder, Arbeitsergebnis-Deklarationen, Pfadsicherheit, Ereignisstruktur, Arbeitsergebnis-Rollen und -Hashes, Phasenübergänge, Prüfungsüberschriften, Entscheidungs-IDs, Bereitschafts-Gates, eingefrorenen Arbeitsergebnis-Inhalt, Abschlussbeleg und Abschlussreihenfolge.

Exit-Codes:

• 0: Validierung bestanden.
• 1: Validierung mit Warnungen bestanden.
• 2: Validierung fehlgeschlagen.