エージェント連携

エージェント連携は、作業手順を定めるスキル、進行表を渡すHook、変更や回答を待つwaitで構成されます。このページでは、それぞれの役割と、agboard setupによるアクセス設定を説明します。利用者向けの作業の流れはエージェントとの連携、エージェントが受け取るJSONはHook・進行表・waitの出力にあります。

各部分の関係

部分	場所	役割
スキルagent-board	.agents/skills/agent-board/SKILL.md	判断。作業の選び方、進捗の報告、判断依頼の出し方、下書きとDoneのタスクの扱い。
Hook	agboard hook（src/agent/hook.rs）	取得と整形。ツールの呼び出しの後に、現在の進行表をエージェントのコンテキストに添える。
進行表	src/progress.rs	進められるタスクの一覧。agboard progressとHookが共有する。
wait	src/agent/wait.rs	プロジェクトが変わるか、判断依頼に回答があるまで待つ。

スキルの名前はagent-board、実行ファイルはagboardです。典型的な流れは次のとおりです。Hookが進行表を見せる → エージェントは必要なEPIC.mdとTASK.mdだけを読む → タイトルが分かりにくければ原依頼を保持してagboard edit --titleで整理する → タスクをDoingとRunningにする → history addで進捗を記録する → ユーザーの判断が必要になったら判断依頼を出して回答を待つ → 条件を満たしていき、自動Doneがタスクを完了させる。タイトル整理は、通常ループと組手に共通するスキルの指示であり、サーバーによる自動要約機能ではありません。

エージェントは、開始・意味のある進捗・判断・検証・中断・再開のときに、項目ごとの承認なしで進捗を追加し、操作時に自動で記録された履歴は重複して追加しません。本文には計画と簡潔な検証結果を記録します。見た目の確認が有用な場合は画像を添付できます。

スキルでは、BUGとENHANCEMENTを継続的な分類用エピックとし、本文を固定する例外を設けます。正本の本文はスキル内のassets/BUG-EPIC.mdとassets/ENHANCEMENT-EPIC.mdです。ボードの言語で一度だけ初期設定し、その後の通常作業・組手では計画と結果を各タスクだけに記録します。空でない本文の置き換えにはユーザーの明示的な依頼を必要とし、有用な旧本文は関連するタスクの本文に残します。優先順のfrontmatterは引き続き変更できます。サーバー側の編集禁止機能ではありません。

進行表とHook

進行表は、Pending以外のTodoとDoingのタスクを、エピックごとにpriorityの順で並べた一覧です。各タスクのID・タイトル・担当・状態・受入条件の件数と、EPIC.mdとTASK.mdのパスを含み、本文や履歴は含みません。優先するタスクがPendingでも、後続のタスクは進められます。回答を受け取り、まだ完了していないタスクは一覧に戻ります。

src/progress.rsは、Includeに応じて任意のpending節とdone節を作ります。agboard progressとagboard hookが--include-pendingと--include-doneからIncludeを作ります。既定のIncludeは何も追加しないため、既定の表は変わりません。オプションはエピックと進行表を参照してください。

Hookは、入力のcwd（なければプロセスのcwd）に最も近い紐付け済みの祖先からプロジェクトを識別します。セッションIDは使わず、紐付けがないときに全プロジェクトを選ぶこともありません。一覧はhookSpecificOutput.additionalContextにAGBOARD_PROGRESSのJSONとして返し、失敗したときはfolder_unboundなどのAGBOARD_ERRORを返します。

• Claude Code。 integrations/claude-code/のテンプレートが、プロジェクト名を固定せずにagboard hookをPostToolUseに、失敗の後はPostToolUseFailureに登録します。汎用スキルのfrontmatterのHookは使いません。スキルは最初の読み込み時にスナップショットを読み、コンテキスト圧縮後（SessionStartのcompact）か次のツールの完了時に一覧を取り直します。
• Codex。 integrations/codex/のテンプレートがagboard hook --agent codexをPostToolUseに登録し、最初の利用時とコンテキスト圧縮後にも取得します。既存の設定に自動で書き込むことはなく、利用者がテンプレートを確認して信頼します。
• 上限。 入力はUTF-8で64 KiB、一覧は256 KiB、一回の実行は10秒が上限です。CodexのadditionalContextLimitは0にし、Hookが自分の上限を守ります。超えたらcontext_too_largeを報告し、切り詰めて成功として報告することはありません。一覧を作れない、または入力の全体が届かなかったときは、Hookがそれを伝え、元のツールの結果を保ちます。
• 安全性。 コマンドは固定で、タスクのテキストやtool_inputから何も組み立てません。Hookがエージェントのツールを呼ぶことも、自分自身を起動することも、ファイルを変えることもありません。パスはローカルのCLIとHookの出力にだけ現れ、リモート向けのJSONには出しません。

エージェントは、一覧を読めるまでボードに依存する変更をせず、コンテキスト圧縮後には一覧を新しく読みます。

スキルでは、作業に関する質問をすべて選択肢つきのボードの判断依頼で行います。pending --request-jsonはwaitを省略しても既定で無期限に待機し、互換のwait: {}も使えます。質問を登録してすぐに戻るようユーザーから明示された場合だけ、スキルで--no-waitを使います。ボードに接続できない場合も、チャットやエージェント固有の質問ツールで代用しません。

変更を待つ

agboard wait --after <cursor>は、プロジェクトが変わるまで待ちます。

1. 同じデータ領域のserve.jsonからpidとportを読み、GET /api/eventsに接続します。
2. プロジェクト名をcursorと照合して、ProjectIdを固定します。別のプロジェクトや旧形式のcursorはcursor_invalidです。
3. readyの後に、プロジェクトの現在のversionとcursorを比べます。違えばすぐに返します。これにより、初回取得から購読開始までに起きた変更も検知できます。
4. 同じならchangedを待ちます。読み直してもversionが同じ（ほかのプロジェクトが変わった）なら、待ち続けます。

• changed・ready・接続維持のコメントは区別します。名前変更では同じプロジェクトのスナップショットを返し、削除ではproject_not_foundを返して、作り直したプロジェクトへは移りません。
• 接続の上限は3秒で、待機そのものは既定で無期限です。任意の--timeoutを付けると、最後にversionをもう一度確かめ、変わっていなければwait_timeoutを返します。切断はboard_unavailableです。自動で短い再試行を繰り返すことも、定期的にポーリングすることもありません。
• 切断・時間切れ・Ctrl+Cでタスクや履歴が変わることはなく、「変更なし」として扱うことも、終了したエージェントを起動し直すこともありません。
• CLIの通知はベストエフォートなので、通知を取りこぼした場合は、次の接続、実際のchanged、または時間切れ時の最終読み込みで変更を検知します。

判断依頼は保存後にCLIがserveへ通知し、既存のSSEイベントを待ちます。既定の待機にはserveが必要です。CLIは保存前に起動を確認するため、サーバーが利用できない場合に質問は作られません。waitの省略とwait: {}はどちらも無期限待機です。整数のtimeoutSeconds（1〜86,400）はCLIプロセスの待機だけを制限し、質問と一緒に保存されません。wait: nullとtimeoutSeconds: nullは期限なしです。

成功時、待機コマンドは{task, answer}を返します。--no-waitは保存と通知の後に{task}を返し、serveを必要としません。wait: {}との併用はできますが、整数timeoutとは併用できません。時間切れ・中断・接続断の後も質問はPendingのままで、request_changedは質問が取り下げられたことを示します。ブラウザで回答するとタスクはIdleに戻ります。エージェントは回答と履歴を読み、理由を添えて明示的にRunningへ戻します。利用手順は判断依頼を参照してください。

次のタスクを待つ

agboard --project <name> wait --until task --idle-timeout <seconds> --jsonも、同じイベント駆動の待機エンジンを使います。購読前に対象タスクを読み、SSEのready後と各changedイベントの後にも確認します。初回の読み込みで対象がなかったとき、単調時計に基づく期限を一度だけ設定します。無関係なプロジェクトの変更や接続維持コメントでは期限を延長しません。期限に達すると最後に一度読み直し、境界時刻までに到着したタスクがあれば返します。なければ終了コード0でidle_timeoutを返します。

対象の順序には進行表と同じordered_tasksを使います。エピックID順に、各エピックの保存済み優先順とタスクID、最後に未所属タスクのID順です。返すのはAI担当でTodoまたはDoing、かつIdleで、下書きでもアーカイブでもないタスク一件です。開始前の初回読み込みで、リッスン前に作成されたタスクも対象になります。結果には、そのsnapshotのcursor、タスク、ローカルのTASK.mdパス、エピックに所属する場合はEPIC.mdのパスが含まれます。取得は読み取りだけでタスクを占有しないため、操作を始める前に最新状態を読み直します。リッスン手順では全体snapshotを確認し、既存AIタスクのrunningまたはpendingを先に解決します。DoingのタスクもIdleなら再開候補です。対象なしでの期限到達は正常な結果ですが、読取不備・サーバー停止・プロジェクト削除はエラーです。

同一セッションでの組手手順として、タスク情報の補完、承認確認、Pendingの回答、直列処理、中断後の復帰をagent-boardスキルのリッスン手順に定めています。Pendingのタスクは、既存の依頼に回答が届くまでそのセッションを止めます。次のタスクへ飛ばず、待ち時間も対象なし時間として扱いません。

自動Done

規則はデータモデルで定めています。評価は次のように行います。

• FileStoreのプロジェクトロックの中で、最新のTASK.mdとタスクの項目を読み直し、共通の判定を一つ適用します。
• serveは起動時、最初のスナップショットを公開する前に既存のタスクを評価します。稼働中は、FileStoreの保存の後と、監視が捉えた原子的なファイル更新の後に評価します。自分の通知で再び評価が始まることはなく、同じタスクを評価し直しても履歴は重複しません。
• エピックも変えるCLIの編集は、すべての変更を適用した後に評価します。AI向けのCLIとFileStoreの入口は、Doneの制限を適用します。
• Pendingのタスクは飛ばし、回答の後に評価し直します。Doneのタスクが自動で再開することはありません。
• エージェントは、検証を履歴に記録し、簡潔な結果を本文に書いてから、最後の条件をdone: trueにします。
• 新しい版のserveを起動すると、条件を満たした既存のタスクが完了します。通常の利用に導入する前に、対象のタスクを一覧にしてバックアップを取ってください。

この制限は、ルールに従うエージェントの誤操作を防ぐためのものです。ファイルの直接編集やactorの偽装を防ぐ認証機能ではありません。

初回案内のサンプルカード

初回の案内は 2 枚のサンプルカードを作ります。それぞれに onboardingSample の識別があり、実行 ID と順番（1 または 2）を保持します。進行表、hook、wait --until task は、この識別のあるカードをレーンや実行状態に関係なく除外します。そのためエージェントはカードを取り上げません。

識別は案内だけが書き込みます。作成と編集の要求には識別のフィールドがなく、移動・履歴の更新・アーカイブ・復元のあいだも識別は保たれます。ボードにはカードが表示されます。利用者から見た動きは始める前にを参照してください。

setupでアクセスを準備する

agboard setupは、エージェントが共有ファイルを編集できるよう、Agent Boardのデータ領域をエージェントの許可されたフォルダに加えます。利用者が一度だけ実行する手順で、プロジェクトの作成やHookの登録はしません。

内部処理は次のように分かれています。

• 通常のストアの処理より前に分岐し、共通のパス解決でデータ領域を一度だけ解決します。
• 環境とパスの解決、変更計画、CodexのTOMLの編集（toml_editでコメント・ほかのキー・配列を保つ）、Claude CodeのJSONの編集（未知のキーを保つ）、退避と適用を別の段階に分けます。変更計画は各ファイルの元の内容と更新後の内容を持ち、dry runも同じ検証を使います。
• 許可モードや管理設定は切り替えません。現在の方式で変更できるかを確かめ、書き込む前にすべての対象を検証し、その間に元のファイルが変わっていないことを確かめます。ファイルを書いたことと、エージェントがそれを読み込んだことは分けて報告します。

失敗したとき:

• 不正なJSONやTOML、対応しない権限の方式、並行する変更があれば、何も書く前に止まり、対象・理由・次の手順を報告します。
• 変更するファイルは、同じフォルダの一意なファイルに退避してから、一時ファイルで置き換えます。変わらないファイルは退避も書き込みもしません。
• 実行が途中で失敗したら、その実行が書いたものだけを、外部の変更を上書きせずに戻します。戻せなければ完了として報告せず、何が変わり、退避先がどこかを示します。
• シンボリックリンクは解決して実体のファイルを編集します。解決できないパスは、推測せずに止まります。
• dry runはフォルダ・設定ファイル・退避を作りません。setupは古いデータや、稼働中のサーバーの通知先を変えません。

付与するアクセス権の範囲は、セキュリティモデルの一部です。