agi-connect/agent-collaboration-protocol

エージェント協調プロトコル (ACP)

ACPは、直接メッセージを送り合えないエージェント向けの共有フォルダベースの協調プロトコルです。これは、構造化されたJSONLイベント、ターン所有権、準備状況ゲート、確定成果物を持つ状態機械です。緩いMarkdownの議論ではありません。

互換性のあるエージェントは、Markdown/JSONの読み書き、JSONLイベントの追記、バンドルされたスクリプトの動作を実行または正確に再現できなければなりません。プロトコルの正確性のために、隠れたスレッド状態、ベンダー固有API、会話メモリに依存してはいけません。

必須入力

開始前に以下を要求します：

• collaboration_folder: 絶対パスまたはリポジトリ相対の共有フォルダパス。
• objective: 協調作業が決定または生成するもの。
• objective_gates: 目的固有のゲート。プロトコルは成果物ゲートを自動生成します。
• participants: すべての参加者ID（例：server, reader, reviewer, agent-a）。
• participant_id: 現在のエージェントのID。
• primary_deliverable_type: adr、design-spec、implementation-plan、decision-memo、review-report、test-plan、または custom のいずれか。
• primary_deliverable_file: 組み込み型の場合は任意、custom の場合は必須。Markdownである必要があります。
• primary_deliverable_checklist: custom の場合に必須。
• deliverables_mode: 任意、デフォルトは internal。external の場合は repoRoot が必要。
• deliverables_dir: 任意、デフォルトは deliverables。

必須入力が不足している場合は、ファイルを作成したりイベントを書き込んだりする前に質問してください。目的ゲートを独自に作成しないでください。

ファイル

ACP スキーマ v2 フォルダは以下のプロトコルファイルを使用します：

• protocol.json: protocol: "acp"、schemaVersion: 2、目的、参加者、生成ゲートと目的ゲート、成果物宣言、現在のフェーズ、提案所有者、待機中の参加者、タイムスタンプ。
• events.jsonl: 追記専用のイベントログ。各行は1つのコンパクトなJSONオブジェクト。
• proposal.md: 現在の提案/変更概要。
• review.md: 構造化された参加者レビュー。
• decisions.md: 安定したIDを持つ簡潔な承認済み決定インデックス。
• readiness.md: 未解決質問の分類、目的ゲート、生成済み成果物ゲート、成果物スナップショット、ブロッカー、準備状況結果。
• conclusion.md: 最終プロトコル受領書。これは主要成果物ではありません。
• deliverables/: 実際のMarkdown成果物と任意の添付ファイル。

state.log、discussion.md、opinions.md を作成または使用しないでください。これらはプロトコルファイルではなく、ゲートや指示に含めてはいけません。

成果物

ACPはプロトコル状態と成果物アーティファクトを分離します：

• 完了可能なすべての協調作業には、宣言された主要Markdown成果物が必要です。
• conclusion.md は最終受領書であり、確定成果物と準備状況結果を参照します。
• 組み込み成果物タイプは adr、design-spec、implementation-plan、decision-memo、review-report、test-plan です。
• custom には明示的なMarkdownファイルとチェックリストが必要です。
• 補助成果物はMarkdownです。添付ファイルは、成果物ディレクトリ下の非Markdownファイルでも構いません。
• internal モードでは成果物を協調フォルダ内に保存します。
• external モードでは成果物をリポジトリルート相対のディレクトリに保存し、イベント、準備状況、結論で external:<file> 参照を使用します。
• 成果物には Status: Draft、Status: In Review、または Status: Frozen を含める必要があります。
• 提案所有者は deliverable_frozen で主要成果物を確定します。確定は厳格で、確定解除や再確定のパスはありません。

初期化

バンドルされたスクリプトを推奨します：

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 "<another objective gate>"

外部成果物の場合：

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>"

初期化スクリプトはプロトコルファイルと主要成果物のテンプレートを作成します。--resume が指定されていない場合、protocol.json がすでに存在するときは失敗します。

イベント

scripts/append_event.py を使用するか、その動作を正確に再現してください。必須イベントフィールド：

• seq: events.jsonl 内の連続する整数。
• from: protocol.json にリストされた参加者ID。
• event: 許可されたイベント名。
• at: ISO-8601 UTC タイムスタンプ。
• summary: 1つの短い文。

許可されたイベント：

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

initialized 以降のすべてのイベントには、以前のイベントを指す reply_to が必要です。doc 参照は、内部モードでは協調フォルダからの相対パス、外部モードでは external:<file> です。

すべての deliverable_* イベントには以下が必要です：

• doc: 解決された成果物参照。
• role: primary または supporting。

deliverable_frozen にはトップレベルの sha256 も必要です。これは参照ファイルの64文字小文字16進SHA-256です。確定後、ファイルの内容はハッシュと一致し続ける必要があります。

フェーズ

エージェントは protocol.json.currentPhase と protocol.json.waitingFor に従って行動する必要があります：

• drafting: 提案所有者が主要成果物を起草し、deliverable_drafted を追記し、proposal.md を更新した後、proposal_submitted を追記します。
• reviewing: リストされたレビューアが proposal.md と主要成果物の両方をレビューし、構造化レビューを review.md に追記した後、review_submitted を追記します。
• revising: 提案所有者が必要に応じて proposal.md と成果物を更新し、成果物が変更された場合は deliverable_revised を追記した後、proposal_revised を追記します。
• decision_review: 提案所有者が readiness.md のすべての未解決質問を分類し、question_classified を追記します。その後、参加者は decisions.md の明示的なエントリを decision_accepted で受け入れます。
• readiness_check: 提案所有者が必要な成果物を確定し、スナップショットを readiness.md に記録し、検証を実行した後、readiness_passed を追記します。
• completed: ユーザーが明示的に新しいラウンドを開始しない限り停止します。
• blocked: ブロッカーが解決されるか新しいラウンドが開始されるまで停止します。

completed は readiness_passed の後でのみ有効であり、conclusion.md を参照する必要があります。

レビュー形式

すべての review_submitted イベントには、そのイベントの seq と一致する review.md の見出しが必要です：

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

Context:
- Read `proposal.md` after event seq `<seq>`.
- Reviewed primary deliverable: `<resolved path>`
- Reviewed supporting deliverables: `<paths or none>`

Review Scope:
- Proposal coherence
- Primary deliverable completeness
- Accepted decision traceability
- Implementation readiness

Position:
- ...

Concerns:
- ...

Required Changes:
- ...

Questions:
- ...

決定

decisions.md は成果物ではなく、承認済み決定のインデックスです。承認されたすべての決定には安定したIDを使用する必要があります：

### D1. <short title>

- Decision: ...
- Rationale: ...
- Reflected in: `deliverables/design-spec.md#section`

IDは連続している必要があります（D1、D2、...）。Reflected in: は宣言された主要または補助成果物を指す必要があります。

準備状況ゲート

readiness_passed または completed の前：

• すべての未解決質問が [resolved]、[deferred_nonblocking]、または [blocking] である。
• すべての [deferred_nonblocking] 項目に Reason: ... が含まれている。
• [blocking] または [unresolved] の項目が残っていない。
• 目的ゲートがチェックされている。
• 生成済み成果物ゲートがチェックされている。
• 主要成果物に Status: Frozen がある。
• 主要成果物の SHA-256 スナップショットが記録されている。
• Ready to implement がチェックされている。
• validate_collaboration.py が通過する。

ブロッキングまたは未解決の準備状況項目は、decision_accepted も妨げます。

最終結論

completed の前に、最終受領書として conclusion.md を書き込みます。以下を含める必要があります：

• Decision Outcome: [proceed]、[do_not_proceed]、[defer] のいずれか1つ。
• Rationale。
• Deliverable Receipt: 主要パス、タイプ、SHA-256、補助成果物、添付ファイル。
• Accepted Decisions Summary。
• Readiness Result。
• Assumptions。
• Deferred Follow-ups。
• Implementation Blockers。
• Next Action。

blocked はフェーズ/イベントであり、完了可能な結果ではありません。

ポーリングと監視

参加者は、フェーズが completed、blocked、または明示的なコーディネーターの期限に達するまで、協調ループのために生存し続ける必要があります。

監視機能がない場合は、以下を使用します：

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

自律的な参加者の場合、以下を推奨します：

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

wait_for_turn.py は、参加者が waitingFor にリストされたとき、または協調が completed または blocked になったときに戻ります。デフォルトは30分のタイムアウトです。外部スーパーバイザーがキャンセルを担当する場合のみ --timeout 0 を使用してください。

検証

実行：

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

バリデーターは、必要なプロトコルファイル、スキーマ v2 フィールド、成果物宣言、パスの安全性、イベントの形状、成果物のロールとハッシュ、フェーズ遷移、レビュー見出し、決定ID、準備状況ゲート、確定成果物の内容、結論受領書、完了順序をチェックします。

終了コード：

• 0: 検証成功。
• 1: 警告ありで検証成功。
• 2: 検証失敗。