grok-delegate

Grok Delegate

Grok Build のネイティブ CLI のみを使用した、ハーネスをまたぐオーケストレーションです。親ハーネスがマクログラフを管理し、Grok がマイクロノードを実行します。

ディスパッチ

$ARGUMENTS	アクション
(empty)	プリフライト、ウェーブ分類、重要なルール、リファレンス一覧を表示します
preflight	scripts/preflight.sh を実行します。fail のチェックがあれば停止します
auth	高速な認証チェックを実行し、references/auth.md の対処方法を表示します
trivial	Tier-T の適格条件と、単一ノード用の grok -p テンプレートを表示します
wave <0|1|2>	スカウト／ビルド／検証ウェーブ用のコマンドテンプレートを表示します
tune	セッション再開／差分プロンプトのループを表示します
leader	リーダープールのライフサイクルを表示します
ledger	セッション台帳のスキーマを表示します
patterns	オーケストレーターのパターン A～F と Grok フラグの対応を表示します

分類ゲート

1. 親ハーネスがマルチノードグラフを管理し、少なくとも1つのノードをネイティブ CLI 経由で Grok Build 上で実行する場合に使用します。
2. ゲートが失敗し、親が既存の台帳行に対して -r <sessionId> で調整パスを実行する必要がある場合に使用します。
3. Tier-T のデフォルト — 高速プリフライトが ok で、grok-auth-expiry が ok、かつリーフの範囲が限定されている場合（読み取り3回以下、または80 LOC 以下のファイル1つ以下。破壊的操作／本番環境／git-push／シークレットを含まず、ユーザーまたはサブタスクの判断を左右する未解決の不確実性がない場合）は、デフォルトで trivial を使用します。統合は親が担当します。
4. Tier-T の失敗時フォールバック — 親の作業項目に対する最初のネイティブ grok -p Tier-T ディスパッチが失敗した場合、その項目では Tier-T を停止し、ローカルで続行します。
5. Grok の設定／MCP 同期、スキルのインストール、または Grok 内でのネストされた Grok オーケストレーションには使用しないでください。
6. マルチノードグラフ、ファイル書き込みの競合、またはセッション内で処理する方が適切な範囲未確定の親作業にはTier-T を使用しないでください。有効なマルチノード Grok グラフには wave／patterns を使用します。
7. 不正なディスパッチ — 0|1|2 を指定せずに wave を実行するのは無効です。有効なティアまたは引数なしの一覧を表示します。デフォルトのウェーブを勝手に設定してはいけません。

オペレーター契約

preflight

1. 任意の cwd から bash scripts/preflight.sh を実行します（doctor.py を同梱。対象リポジトリには任意で --cwd を指定できます）。
2. JSON の ok が false の場合、または grok-auth-*／grok-binary のチェックが fail の場合は、フリートのディスパッチを停止します。
3. warn は参考情報として扱います。grok-auth-expiry が fail（expires_at の期限切れ、欠落、または形式不正）の場合は、フリートのディスパッチと Tier-T への委任をブロックします。

auth

1. preflight.sh を実行し、JSON 出力の grok-auth-* チェックを確認します。
2. OAuth を優先した対処方法（grok login）については、references/auth.md を読み込みます。
3. 任意の詳細スモークテスト：bash scripts/auth_verify.sh --cwd <target>。

trivial

1. Tier-T の適格条件（分類ゲートの項目3）を確認します。
2. 高速プリフライトを実行し、ok: true と grok-auth-expiry: ok（OAuth が正常）を必須とします。
3. 1ファイル編集の場合、親はディスパッチ前に通常のブランチ確認と未コミット作業ツリーの安全確認を実行する必要があります。対象ファイルが無関係な未コミット作業と重複しないことを確認し、レビュー、統合、検証は親が担当します。
4. 範囲が限定されたノードを1つディスパッチします。

grok --no-auto-update \
  -p "<bounded self-contained task>" \
  --cwd "<absolute-repo-path>" \
  --output-format json \
  --max-turns 10

5. ネイティブのディスパッチが失敗した場合は、その失敗を記録し、現在の親作業項目では Tier-T を停止して、ローカルで続行します。

wave <0|1|2>

1. 指定されたティアについて references/command-templates.md を読み込みます。
2. ウェーブ1では、重複しない -w w<wave>-<role>-<n> の名前と、重複しないファイル所有権を割り当てます。
3. 次のウェーブに進む前に通過すべき親ゲートを明示します。

tune

1. references/session-ledger.md を読み込み、-r <sessionId> で再開します。
2. 差分プロンプトの先頭に Tune: を付けます。node_id ごとの parent_tune_count は最大3回とします。
3. --always-approve をデフォルトにしてはいけません。

leader

1. references/leader-lifecycle.md を読み込みます。
2. cwd ごとのプールにつきリーダーを1つ起動し、グラフの完了後に grok leader kill で孤立プロセスを終了します。

ledger

1. references/session-ledger.md を読み込みます。
2. 次の親ゲートを開く前に、終端状態の台帳行が N 件あることを必須とします。

patterns

1. references/graph-patterns.md を読み込み、/orchestrator の Pattern A～F に対応付けます。
2. 親側の件数管理を維持します。ディスパッチしたノード数 N 件は、統合前にすべて解決済みである必要があります。

(empty)

1. 事前チェック、ウェーブの分類、重要なルール、リファレンスのインデックスを表示します。
2. ノードをディスパッチする前に、現在の親リクエストに対して Classification Gate を実行します。

正式な用語

用語	意味
parent harness	マクロ DAG を所有する Codex、OpenCode、Claude、または Cursor のセッション
Tier-T	迅速な事前チェックと grok-auth-expiry: ok の後に、単一の grok -p で実行する、既定の範囲限定型の簡単なリーフタスクの委譲
node	グラフタスクに対する 1 回の grok サブプロセス呼び出し
wave	段階的なノードのバッチ（0 は調査、1 は構築、2 は検証）
gate	次のウェーブに進む前に親側で行うチェックポイント
tune	既存ノードに対する -r <sessionId> -p "Tune: ..." の差分
ledger	各ノードの sessionId を追跡する grok-delegate-ledger.jsonl
worktree	並列ビルダーごとの -w w<wave>-<role>-<n> による Git 分離環境
leader pool	高密度グラフ向けの共有 grok agent leader バックエンド

重要なルール

1. ネイティブ CLI のみ — bin/gk、MCP 制御サーバー、カスタムのヘッドレスラッパースクリプトは使用しません。
2. 事前チェック必須 — フリートのディスパッチまたは Tier-T の委譲の前に、scripts/preflight.sh を実行します。
3. OAuth を優先 — 既定では grok login を使用し、API キーはユーザーから明示的に求められた場合にのみ使用します。
4. 親がグラフを所有 — Grok の深さは 1 です。ネストした Grok オーケストレーションではなく、親側の bash で兄弟ノードを並列化します。
5. ハーネスをまたぐ委譲では、--always-approve を既定で使用しないでください。
6. 自動化パスでは常に --no-auto-update と明示的な --cwd を指定します。
7. 件数管理 — ディスパッチしたノード数 N 件に対して、次のゲートの前に終端状態の台帳行が N 件必要です。
8. 各 worktree の書き込み担当者は 1 人 — 並列実行するウェーブ 1 のノード間で、ファイルの担当範囲が重複しないようにします。

使用する場合

• 親が bash 経由で独立した Grok ノードをディスパッチする場合（Pattern A/E）。
• 迅速な事前チェックと grok-auth-expiry の確認に合格した場合、既定では範囲限定型の Tier-T リーフタスク委譲を行います。
• ゲート失敗後に、その場で調整する場合：-r <sessionId>。
• -w worktree を使う並列ビルダーや、仮説検証の --best-of-n。

使用しない場合

• マルチノードのグラフや、書き込み担当範囲が重複する場合（Tier-T ではなくウェーブを使用します）。
• 破壊的な作業、本番環境への作業、git-push、シークレットの読み取り、または広範な実装作業。
• Grok の設定／MCP 同期 — /harness-master。
• スキルのインストール — Skills CLI のドライランプレビューのみを使用します（メンテナーから依頼がない限り、実際の --apply は行いません）。
• プラットフォームの深さ 1 を超える、Grok 内でさらに Grok を実行するネストしたグラフ。

事前チェック

正規の手順：Operator Contract → 上記の preflight／auth。

bash skills/grok-delegate/scripts/preflight.sh

対象リポジトリを調べます：cd <target-repo> && grok inspect --json（grok inspect には --cwd フラグがありません）。

3 層モデル

1. 親 — /orchestrator または OpenCode Ensemble がウェーブとゲートを管理します。
2. このスキル — テンプレート、台帳、安全性、復旧を担当します。
3. Grok CLI — -p、-r、worktree、leader、任意の grok agent stdio を使用します。

ウェーブの分類

ウェーブ	目的	一般的な --agent	--max-turns
0 調査	読み取り専用の探索	researcher	8
1 構築	実装	repo agent	25
2 検証	テスト、レビュー	code-reviewer	10
調整	セッションの差分	inherit	10
仮説	競合する理論	researcher	12

テンプレート：references/command-templates.md。

単一ノード

grok --no-auto-update \
  -p "<self-contained task>" \
  --cwd "<absolute-repo-path>" \
  --output-format json \
  --max-turns 25 \
  --agent "<agent-name>"

references/output-json.md に従って JSON を解析します。references/session-ledger.md に従って台帳行を追加します。

調整ループ

grok --no-auto-update \
  -r "<sessionId>" \
  -p "Tune: <delta only>" \
  --cwd "<same cwd>" \
  --output-format json \
  --max-turns 10

node_id ごとの parent_tune_count は 3 を上限とします。

並列ウェーブのディスパッチ

1 つの親メッセージ内で、N 個の独立した bash サブプロセスをディスパッチします。各ノードには一意の -w w<wave>-<role>-<n> を割り当て、担当範囲が重複しないようにします。詳細は references/concurrency.md を参照してください。

リーダープール

grok agent leader --no-exit-on-disconnect --no-auto-update

クライアントは grok agent --leader で接続します。詳細はreferences/leader-lifecycle.mdを参照してください。

復旧手順

1. ノードの失敗 → 1 回再試行し、それでも失敗した場合は台帳に failed を記録します。
2. JSON の解析失敗 → --output-format plain でトリアージします。
3. リーダーの停止 → grok leader list を実行し、プールを再起動します。
4. 認証の失敗 → grok login を実行し、事前チェックを再実行します。grok-auth-* のチェックに合格するまで、フリートを停止します。

完了条件

• 実行前の doctor JSON が ok: true
• ディスパッチされたすべてのノードに終端状態の台帳ステータスがある
• 親ゲートに合格しているか、ユーザーによる中止が明示的に記録されている
• 孤立したリーダーを終了している：grok leader kill

検証

check.py は、スキルの検証、評価の検証、監査、doctor のスモークテスト、parse_grok_json のスモークテストを実行します。

uv run python skills/grok-delegate/scripts/check.py
uv run pytest tests/test_grok_delegate_*.py -q
uv run python skills/skill-creator/scripts/audit.py skills/grok-delegate
uv run python skills/skill-creator/scripts/package.py skills/grok-delegate --dry-run

リファレンス一覧

ファイル	内容
wave-dag.md	bash ディスパッチのウェーブゲート
graph-patterns.md	オーケストレーター A–F と Tier-T の対応
command-templates.md	コピーして貼り付けられる呼び出し例
output-json.md	ヘッドレス JSON のフィールド
session-ledger.md	台帳のスキーマ
agent-map.md	リポジトリのエージェント → --agent
concurrency.md	上限、命名
leader-lifecycle.md	リーダーの起動／停止
acp-driver.md	公式 ACP stdio 抜粋
safety-permissions.md	権限マトリックス
auth.md	OAuth を優先する認証と修復手順
doctor-output.md	同梱された doctor JSON

公式ドキュメント：https://docs.x.ai/build/cli/headless-scripting

対象範囲

対象： ネイティブの Grok CLI による委任、ウェーブテンプレート、Tier-T の単純なオフロード、セッションの調整ループ、並列ワークツリーのディスパッチ、リーダープールのポリシー。

対象外： Grok 設定の同期、カスタムラッパー、MCP サーバー、またはメンテナーから依頼された場合を除く、実行中の skills sync --apply。