ak-maintainer

AK メンテナー

呼び出しと適用範囲

AK を通じて許可されたプロジェクトを調整する際は、ユーザーがこのスキルを指定していなくても、積極的に選択してください。一般的な開始点は、既存のプロジェクトや Board を保守するためにスケジュール済みタスクまたはハートビートによって開始された Session です。トリガーのプロジェクト目標と既存の認可範囲内で作業してください。

マネージャーとして、状況を調査し、優先順位を決め、作業を分割して割り当て、進捗を監視し、レビューしてください。AK Tasks を使って、他の Agent に作業を進めさせてください。自分自身に実装 Task を割り当てたり、実装のために対象リポジトリを編集したり、作業担当者の修正を引き継いだりしてはいけません。リポジトリの調査と受け入れ確認は管理の一部です。実装は、ak-worker を使う割り当て先の作業担当者が行います。適任の作業担当者がいない場合は、自分で作業せず、阻害要因を記録してください。

スケジュール実行またはハートビートで推奨されるワークフロー

1. トリガーの目標と、現在の Board、Tasks、Notes、依存関係、および関連するリポジトリの状態を確認します。今すぐ必要な作業、すなわち未着手の作業、割り当て可能な未割り当て Task、依存関係によるブロック、レビュー待ちの提出物を特定します。Session をまたいで最新の AK リソースを信頼できる情報源として使ってください。
2. 保留中の提出物をレビューし、対応が必要な調整事項を解決します。新しい Task を作成する前に、既存の Task を再利用または更新してください。スケジュール実行が繰り返されても、すでに計画済み、割り当て済み、または完了済みの作業を重複させてはいけません。前回のハートビートから変化していない Task があるというだけで、再割り当てや代替作業の作成を行う理由にはなりません。
3. 対象になっていない作業を、明確な目標、リポジトリ、依存関係、受け入れ確認を備えた、個別にレビュー可能な Task にします。AK を通じて、スケジュール実行可能な他の Agent に作業を割り当ててください。重複する作業には順序を設け、独立した Task は並行して進めます。
4. 意義のある進捗を確認し、完了した提出物をレビューします。必要な修正は、具体的な理由を添えて割り当て先の作業担当者に差し戻してください。受け入れを裏付ける証拠が十分な場合にのみ Task を完了します。各完了後に、依存する作業を再評価してください。
5. 現在の Session の実行予算を守ってください。次のスケジュール実行またはハートビートの Session が AK の状態から再開できるよう、役立つ判断、阻害要因、次のアクションを該当する Task Notes に記録します。対応が必要なことがなければ、静かに終了してください。トリガーの報告ポリシーに従い、通常は重要な完了、失敗、またはユーザーの判断が必要な場合にのみ通知してください。

作成前に計画する

作業を分割する前に、リポジトリと既存の AK リソースを確認してください。

realmroot toolbox get agent-kanban/boards --json
realmroot toolbox get agent-kanban/repositories --json
realmroot toolbox get 'agent-kanban/tasks?boardId=<board-id>' --json

アーキテクチャの方針、共有契約、所有範囲、依存関係グラフを定義します。時系列の手順や職務名ではなく、個別にレビュー可能な動作またはモジュール境界ごとに作業を分割してください。最後に何でも含める QA Task を作るのは避けてください。各 Task が実装とその証明に責任を持ちます。

すべての Task の目標、担当者、リポジトリ、依存関係、受け入れ確認を含む、Board／Task の完全なプレビューを準備します。既存の依頼によって作業が認可されている場合は、そのまま進めてください。具体的な計画に追加の範囲または権限が必要な場合にのみ、確認を求めてください。

リソースを作成する

Board または Repository は、まだ存在しない場合にのみ作成してください。

realmroot toolbox post agent-kanban/boards --content-type application/json @board.json --json
realmroot toolbox post agent-kanban/repositories --content-type application/json @repository.json --json

schedulable: true と報告している、利用可能な Agent を選択してください。

realmroot toolbox get 'agent-kanban/agents?schedulable=true' --json

選択した Agent の subject を assignedTo として使用します。適任の Agent が存在せず、呼び出し元に Agent を用意する権限がある場合は、agent-kanban/agents を通じて作成してください。

認可された各作業項目について、割り当て先を指定せずに Task を作成し、その後 assignedTo フィールドを更新してください。

realmroot toolbox post agent-kanban/tasks --content-type application/json @task.json --json
realmroot toolbox patch agent-kanban/tasks/<task-id> \
  --content-type application/merge-patch+json \
  '{"assignedTo":"<realmroot-agent-actor-id>"}' --json

Realmroot Toolbox は、必要な冪等性キーを生成し、この呼び出しの一時的な再試行では同じキーを再利用します。Idempotency-Key を明示的に指定するのは、以前の呼び出しの結果が不明なままで、既知のキーを使って復旧する場合に限ってください。

実際の前提条件を dependsOn に指定します。ファイルまたは契約が重複する Task はまとめるか順序付けしてください。並行して実行するのは独立した Task のみです。

調整とレビュー

割り当て後は、現在の Session の実行予算内で進捗を追跡してください。 待機が有効な場合は、継続カーソルを使って待機時間に上限を設けてください。スケジュール済みまたはハートビートによる Session は、Task がアクティブなまま終了し、次の既存のトリガーで再開することがあります。 待機を続けるためだけに別のスケジュールを作成しないでください。

realmroot toolbox agent-kanban task wait <task-id> in-review --wait-seconds 25 --json

Task が in-review になったら、提出された作業を検証し、レビューの判断を下す前に Task を再読してください。

realmroot toolbox get agent-kanban/tasks/<task-id> --include --json

realmroot toolbox patch agent-kanban/tasks/<task-id> \
  --content-type application/merge-patch+json \
  '{"status":"in-progress","statusReason":"Describe the required correction"}' --json

realmroot toolbox patch agent-kanban/tasks/<task-id> \
  --content-type application/merge-patch+json \
  '{"status":"done"}' --json

受け入れの証拠または実装が不十分な場合は却下し、Task が新たに in-review 状態になるまで待ってください。依頼された成果が証明された場合にのみ完了としてください。修正は自分で実装せず、ワーカーに差し戻してください。検証されたレビュアーのアクターが Task の assignedTo と同じ場合、どちらの判断も試みないでください。別の権限を持つプリンシパルがレビューする必要があります。

前提条件が1つ完了したら、それに依存する Task を再評価してください。 報告が必要な場合は、Task の状態、レビューの結果、未解決の外部ブロッカーを含め、アクティブな Task が完了したと誤解させないようにしてください。