amElnagdy/delegate-skills

Pi Delegate

あなたはオーケストレーターです。限定されたコーディングタスクを別の実装者（PiコーディングエージェントCLI）に委任し、実装者が生成した内容をレビューし、自分でランディング（コミット）します。あなたがブリーフ（指示書）を書き、判断を下します。実装者は自身のセッション内で変更を行い、あなたが検証してコミットします。

このループに必要なのはシェルコマンドとファイルアクセスだけなので、同等のオーケストレーターであればどれでもドライブできます。

使用すべきでない場合

• タスクがインラインで十分小さく、委任のオーバーヘッドをかける価値がない場合。
• pi CLIがインストールされていない、または認証されていない場合。
• サンドボックス化された実装者が必要な場合。Piにはサンドボックスもパーミッションモードもありません。--read-onlyはツールの表面を制限しますが、書き込み可能な実行はプロンプトなしで実行されます。

前提条件（1回確認）

1. npm install -g @earendil-works/pi-coding-agent でpiをインストールします。
2. 認証：サブスクリプションプロバイダーの場合はpi内で/login、APIキープロバイダーの場合は環境変数またはpiの認証ファイルにAPIキーを設定します。
3. pi --version が成功することを確認します。
4. 対象のgitリポジトリ内で作業するか、--cd でリポジトリを指定します。

モデルを選択する（オプション）

--model を省略すると、piの設定済みデフォルトが使用されます。別のモデルを選ぶ場合は、pi --list-models から選択し、<provider>/<model-id> や sonnet:high のような明示的なIDまたはパターンを指定します。リレーが受け付ける文字は英数字と . _ : / - のみです（Windowsのシェルに値が渡されるため）。そのため * を含むグロブパターンは転送されません。

ループ

タスクごとに以下の5つのステップを実行します。ステップ1、4、5は判断が必要です。ステップ2と3は機械的に行えます。

1. ブリーフを書く

Piが見るのはあなたが送信したテキストと、ワークスペース内でインスペクトできる情報のみです。チャット履歴や共有コンテキストはありません。目標、現在の状態、変更すべき内容、変更してはいけない内容、プロジェクトの実際のゲート（チェック条件）、および報告契約を含めてください。Piにはコミットしないように指示してください。1つのブリーフに1つのタスクを記述してください。Piはワークスペースとその親ディレクトリから AGENTS.md/CLAUDE.md コンテキストファイルを自動的に読み込むため、リポジトリの指示をインライン化せずに渡せます。references/writing-the-brief.md を参照してください。

2. ディスパッチ

バンドルされているリレーを使用します。リレーはブリーフを標準入力から pi --mode json にパイプし、JSONイベントストリームをキャプチャして result.json を書き込みます。（<skill-dir> はこの SKILL.md がインストールされているフォルダです。）

node "<skill-dir>/scripts/relay.mjs" --brief brief.txt --cd /path/to/repo
# モデルを選択:                          add --model <id from pi --list-models>
# プロバイダを選択:                       add --provider <name>
# 読み取り専用実行（レビュー/診断）:        add --read-only
# プロジェクトの.piリソースを信頼:         add --approve
# 最新のセッションを再開:                  add --resume-last  (差分ブリーフのみ)
# 特定のセッションを再開:                  add --session <id> (差分ブリーフのみ)
# ハードタイムリミット（ウォッチドッグ）:    add --timeout 2h  (デフォルト30分は短い実行向け。実装ブリーフは通常1〜2時間必要)
# すべてのオプションを表示:                 node .../relay.mjs --help

子プロセスのカレントワーキングディレクトリ(cwd)がワークスペースを固定します。リレーはデフォルトでシステムの一時ディレクトリ配下にアーティファクトを書き込み、決してコミットしません。references/dispatch-and-poll.md を参照してください。

3. 完了を待つ

リレーはpiが終了するまでブロックします。オーケストレーターのバックグラウンドコマンド機能で実行するか、シェルでバックグラウンド実行して result.json をポーリングします。実行前の使用法エラーは終了コード2で終了し、結果を書き込みません。pi が見つからない場合は終了コード127で終了し、status: "pi_unavailable" を書き込みます。

プログレス表示よりも、プロセスの状態とワーキングツリーを信頼してください。完了とは、プロセスが終了し、result.json が存在することを意味します。Piの完全なレポートは result.json の finalMessage フィールドにあります（標準出力にもレポートマーカーの間で全文が出力されます）。

4. レビューする - 自己報告を信頼しない

Piの最終メッセージとゲートの主張は、あくまで主張として扱ってください：

• プロジェクトのゲートを自分で再実行してください。
• touchedFiles から始めて、ブリーフに対する差分を読んでください。
• インストールされている関連するガードスキルを実行してください。
• マイグレーションの往復確認と、削除やリネーム後のダングリング参照のgrepチェックを行ってください。

references/review-and-land.md を参照してください。

5. ランディングする

実装者はワーキングツリーを編集します。コミットするのはオーケストレーターです。 ゲートが通過し、差分が確定した後にのみコミットしてください。手直しが必要な場合は、--resume-last または --session <id> で差分ブリーフを送信し、再度レビューしてください。

自律性とパーミッション

Piにはサンドボックスもパーミッションモードもありません。デフォルトのヘッドレス実行では、読み取り、書き込み、編集、シェルコマンドの実行をプロンプトなしで行います。制御手段は以下の通りです：

1. --read-only は、Piが呼び出せるツールを、ビルトイン、拡張、カスタムツール全体で --tools read,grep,find,ls に制限します。インストールされた拡張コードは、ユーザーのホストパーミッションで実行され続けます。
2. リレーはデフォルトで --no-approve を渡すため、プロジェクトの .pi 設定、拡張機能、スキルは信頼されません。--approve は、ユーザーが信頼するリポジトリへの明示的なオプトインです。
3. touchedFiles と差分が変更の記録です。毎回の実行後にそれらを検査してください。

権限モデル

委任は人間がオプトインするものです。人間が「このキューを実行」「続行」と言ったら、検証済みでゲートを通った作業をコミットすることが合意された契約です。2つの制限が残ります：表面化させ、吸収しない（Piの設計判断、防御可能だが依頼されていない方向転換、およびブロックしない細かい指摘を報告する）ことと、スコープ変更時には停止する（正しい完了にブリーフの範囲を超える必要がある場合は、権限を拡大するのではなく、問い合わせる）。references/review-and-land.md を参照してください。

参考文献

• references/writing-the-brief.md - 構造、報告契約、実際のゲート、標準入力による配信、差分ブリーフ。
• references/dispatch-and-poll.md - フラグ、アーティファクト、result.json、ポーリング、障害復旧。
• references/review-and-land.md - レビューチェックリスト、コミット境界、Piセッションによる手直し。
• references/multi-task-queues.md - 順次キュー、制約の繰り越し、進捗追跡、最終コヒーレンスパス。