benjinus/agent-collaboration-protocol

Agent Collaboration Protocol（エージェント連携プロトコル）

直接メッセージを送信できないエージェント同士が、共有フォルダをポータブルな協調バスとして使用します。ACPは破壊的プロトコルです。つまり、疎なMarkdown会話ではなく、構造化されたイベントと準備ゲートを持つステートマシンです。

互換性のあるエージェントは、MarkdownとJSONを読み取り、Markdownを書き込み、JSONLイベントを追記し、バンドルされたスクリプトの動作を実行または完全に再現できなければなりません。正しさのために、CodexスレッドAPI、Claude固有のフック、OpenCodeのみの状態、Kiroのみのメタデータ、または隠された会話メモリに依存してはなりません。

必須入力

開始前に、以下が必要です：

• collaboration_folder: 絶対パスまたはリポジトリ相対パスの共有フォルダパス。
• objective: 協調動作で決定または生成する必要があるもの。
• completion_gates: 協調動作を終了するための具体的なゲート。
• participants: 全参加者ID。例：server、reader、reviewer、agent-a。
• participant_id: 現在のエージェントの識別子。

必須入力が不足している場合は、ファイルを作成したりイベントを書き込んだりする前に、それを要求してください。完了ゲートを独自に発明してはいけません。

ファイル

ACPフォルダは以下のファイルを使用します：

• protocol.json: 目的、参加者、完了ゲート、現在のフェーズ、提案所有者、待機中の参加者、タイムスタンプ。
• events.jsonl: 追記専用のイベントログ。各行はコンパクトなJSONオブジェクトです。
• proposal.md: 現在の提案のみ。
• review.md: 構造化された参加者レビュー。
• decisions.md: 受け入れられた決定のみ。
• readiness.md: 未解決質問の分類、ブロッカー、延期された非ブロッキング項目、実装準備状況。
• conclusion.md: 最終議論の結論。進めるか、進めないか、延期するか、ブロックするかを示し、その理由、実装方法または実装しない理由、次のアクションを含みます。

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

初期化

バンドルされたスクリプトを使用することを推奨します：

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

初期化は、protocol.jsonがすでに存在する場合は--resumeが指定されていない限り失敗します。繰り返しの初期化は追記操作ではありません。

イベント

scripts/append_event.pyを使用するか、その動作を正確に再現してください。ランタイムがスクリプトを実行できない場合を除き、イベントを手書きしてはいけません。

必須イベントフィールド：

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

推奨フィールド：

• doc: 協調フォルダからの相対パス。
• reply_to: 以前のイベントのseq。

許可されたイベント：

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

すべての応答は、以前のイベントに対する応答である場合にreply_toを使用しなければなりません。reply_toは以前に存在するイベントを指していなければなりません。イベントのタイムスタンプは、seqが増加するにつれて過去に戻ってはいけません。誤りが発見された場合は、blockedまたは新しい修正イベントを追記してください。以前のイベントを書き換えてはいけません。

フェーズ

エージェントはprotocol.json.currentPhaseおよびprotocol.json.waitingForに従って行動しなければなりません：

• drafting: 提案所有者がproposal.mdを更新し、その後proposal_submittedを追記します。
• reviewing: waitingForにリストされている参加者のみがreview.mdに構造化レビューを追記し、その後review_submittedを追記します。
• revising: 提案所有者が必須の変更に対応し、proposal_revisedを追記します。
• decision_review: 提案所有者はまずreadiness.mdのすべての未解決質問を分類し、question_classifiedを追記します。その後、waitingForにリストされている参加者だけがdecisions.mdで明示的な決定を受け入れ、decision_acceptedを追記します。
• readiness_check: 参加者がすべての質問を分類し、ブロッカーをクリアし、準備状況をパスした後、提案所有者がconclusion.mdを作成します。
• completed: ユーザーが明示的に新しいラウンドを開始しない限り停止します。
• blocked: ブロッカーが解決されるまで停止します。

completedは、事前にreadiness_passedイベントがあった場合にのみ有効です。completedはconclusion.mdを参照しなければなりません。decisions.mdだけで完了してはいけません。決定は入力であり、conclusion.mdは協調動作の目的に対する最終的な答えです。

提案所有者はproposal_submittedの後、待機しなければなりません。フェーズがreviewingの間、所有者は次のアクションをポーリングするか、実際のタイムアウト/ブロッカーのためにblockedを追記することはできますが、proposal.md、decisions.md、readiness.md、protocol.jsonを編集してはいけません。また、必要なレビューが提出されるまで、進行イベントを追記してはいけません。

レビュー形式

すべてのreview_submittedイベントには、そのイベントのseqと等しいseqを持つ、対応するreview.mdの見出しがなければなりません：

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

Context:
- Read `proposal.md` after event seq `<seq>`.

Position:
- ...

Concerns:
- ...

Required Changes:
- ...

Questions:
- ...

返信先イベントのseqをレビューの見出しに使用してはいけません。返信先のコンテキストはContextとreply_toに記述してください。

準備ゲート

readiness_passedまたはcompletedの前に：

• すべての未解決質問は、[resolved]、[deferred_nonblocking]、または[blocking]のいずれかに分類されていなければなりません。
• すべての[deferred_nonblocking]項目にはReason: ...が含まれていなければなりません。
• [blocking]または[unresolved]の項目が残っていてはいけません。
• 最終設計チェックリストには「Ready to implement」が含まれ、チェックされていなければなりません。
• validate_collaboration.pyがパスしなければなりません。

ブロッキング準備項目はdecision_acceptedも防止します。未解決の質問やReason: ...が欠けている延期項目もdecision_acceptedを防止します。

最終設計文書は以下を分離しなければなりません：

• Accepted Decisions（受け入れられた決定）
• Assumptions（前提条件）
• Deferred Follow-ups（延期されたフォローアップ）
• Implementation Blockers（実装ブロッカー）
• Ready to Implement（実装準備完了）

最終結論

completedの前に、conclusion.mdをログではなく結論文書として作成してください。以下を含める必要があります：

• Decision Outcome: 正確に[proceed]、[do_not_proceed]、[defer]のいずれか。
• Rationale（根拠）。
• Accepted Decisions（受け入れられた決定）。
• Implementation Approach（実装アプローチ）。
• Assumptions（前提条件）。
• Deferred Follow-ups（延期されたフォローアップ）。
• Implementation Blockers（実装ブロッカー）。
• Next Action（次のアクション）。

実装を今すぐ開始すべき場合は[proceed]、機能や計画を実行すべきでない場合は[do_not_proceed]、実装前にフォローアップ作業が必要な場合は[defer]を使用してください。コラボレーションがブロックされている間は[blocked]の結果が存在する可能性がありますが、完了可能ではありません。

ポーリングとウォッチャー

参加者は、フェーズがcompleted、blocked、または明示的なユーザー/コーディネーターの期限に達するまで、コラボレーションループのためにアクティブであり続けなければなりません。単に1つの有効なイベントを追記しただけで停止してはいけません。すべてのアクションの後、protocol.jsonを再度読み取り、次の許可されたアクションを実行するか、次のイベントを待機してください。

ランタイムにウォッチャーがある場合、events.jsonlまたはprotocol.jsonが変更されたときに参加者に通知する場合があります。ウォッチャーはダム（機能限定）でなければなりません：変更に気づくだけで、分析や決定を書き込んではいけません。

ウォッチャーがない場合は、以下を使用します：

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を使用します。戻ったら、next_action.pyを検査し、自分の番であれば行動し、必要なイベントを追記し、待機/アクションループを繰り返します。「新しい意見を確認してください」などの手動ユーザープロンプトはフォールバックに過ぎず、意図されたコラボレーションループではありません。

参加者を起動するコーディネータープロンプトは、各参加者に1つのフェーズを実行して終了するのではなく、このループを実行するように指示する必要があります。waitingForにリストされていない参加者はwait_for_turn.pyでブロックされる可能性がありますが、待機中に共有状態を編集してはいけません。

検証

以下を実行します：

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

バリデーターは、必要なファイル、廃止されたファイルの不在、イベントの形状、seqの連続性、タイムスタンプの単調増加、フェーズ遷移、waitingForの所有権、reply_to、レビュー見出しのseq、準備状況の分類、結論の完全性、完了順序をチェックします。

終了コード：

• 0: 有効。
• 1: 警告付きで有効。
• 2: 無効。