summon

Summon

概要

Summon は egregore のオーケストレーションループです。 マニフェスト（.egregore/manifest.json）を読み込み、 次に実行するアクティブな作業項目を選択し、 現在のパイプラインステップを専門スキルに対応付けて、 そのスキルを呼び出します。 各ステップの後にパイプラインを進め、コンテキストと トークンの予算を確認し、すべての項目が完了するか、 予算を使い切るまで繰り返します。

オーケストレーターがフェーズのロジックを再実装することはありません。 各パイプラインステップは、既存のスキルに Skill() 呼び出しを介して委譲します。 Summon は状態遷移、再試行、予算のガードのみを管理します。

使用する場合

• 1 つ以上の作業項目を、intake-build-quality-ship パイプライン全体を通して処理する場合。
• 中断された egregore セッションを再開する場合（マニフェストがすでに存在し、アクティブな項目がある場合）。
• 終了時に再起動するウォッチドッグのもとで自律的に実行する場合。

使用しない場合

• 単一のスキルを単独で実行する場合（代わりにスキルを直接呼び出してください）。
• パイプラインが適用されない探索的な作業を行う場合。
• 各ステップの前に人間によるレビューが必要な場合（手動でスキルを呼び出してください）。

オーケストレーターの起動

オーケストレーターエージェントは必ずフォアグラウンドで起動してください。 run_in_background: true は使用しないでください。メインセッションが egregore となり、egregore が完了するか終了されるまで、 オーケストレーターエージェントの処理を待ちます。

Agent(
  subagent_type: "egregore:orchestrator",
  prompt: "<context about work items and current state>",
  run_in_background: false   // Required
)

オーケストレーターをバックグラウンドで起動すると、メイン セッションは何もすることがなくなり、停止します。これは egregore の 目的そのものを損ないます。バックグラウンドエージェントは切り離されるため、 停止フックでこれを防ぐことはできません。

無人で実行する夜間ラン

上記のオーケストレーターは、セッション内のエージェントです。夜間 ランはもう一つの起動方法で、ウォッチドッグが再起動できる通常の プロセスです。何時間も続く間、セッションが維持される保証はありません。このプロセスは 引き渡された項目を 1 つ処理します（gate、walk、proof）。項目が拒否され、 何も実行されなかった場合は gate 自身の終了コード（1 から 4）で終了し、 walk の開始後に失敗した場合は 5 で終了します。

python3 "${CLAUDE_PLUGIN_ROOT}/scripts/night_run.py" \
  --item-dir .egregore/handoff/<item> --root .

セッション内からこのプロセスが起動されることはありません。手動で実行するか、 設定したスケジューラーから実行してください。 /egregore:install-watchdog のウォッチドッグはこのプロセスを起動しません。 このウォッチドッグは、このスキルを呼び出す claude -p セッションを 再起動します。クールダウンの経路が異なる理由については、 modules/budget.md を参照してください。

マニフェストモード

オーケストレーターを起動する前に、マニフェストの 実行モードが正しいことを確認してください。

• デフォルト（--bounded フラグなし）：マニフェストで "indefinite": true を設定します。egregore はすべての項目を完了した後に新しい作業をスキャンし、 終了されるまで実行を続けます。
• --bounded フラグあり：マニフェストで "mode": "bounded" を設定します。 egregore はすべての項目が完了または失敗した時点で停止します。

マニフェストがすでに存在し、"mode": "bounded" が設定されている一方で、 ユーザーが --bounded を指定していない場合は、起動する前にマニフェストを "indefinite": true に更新してください。

起動後は、概要、ステータステーブル、 「現在の状況」に関する出力を一切生成しないでください。以降、このセッションは オーケストレーターが担います。そのまま実行させてください。

オーケストレーションループ

以下の手順に正確に従ってください。 各反復では、1 つの作業項目に対して 1 つのパイプラインステップを処理します。

1. 状態を読み込む

manifest  = Read(".egregore/manifest.json")
config    = Read(".egregore/config.json")
budget    = Read(".egregore/budget.json")

manifest.json が存在しない場合は、次のエラーで停止します。 "No manifest found. Run egregore init first."

2. 次の作業項目を選択する

item = manifest.next_active_item()

item が None の場合、すべての作業が完了しています。 マニフェストを保存し、完了を報告して終了します。

3. 現在のステップをスキルに対応付ける

以下の「パイプラインとスキルの対応表」で item.pipeline_stage と item.pipeline_step を確認します。 呼び出すスキル名またはアクションを特定します。

4. スキルを呼び出す

Skill() を呼び出すか、対応するアクションを実行します。 作業項目から必要なコンテキスト（ブランチ名、issue の参照など）を 渡します。

5. 結果を処理する

成功した場合：

• manifest.advance(item.id) を呼び出して、次のステップに進みます。
• item.attempts を 0 にリセットします。
• マニフェストを保存します。

失敗した場合：

• manifest.fail_current_step(item.id, reason) を呼び出します。
• item.attempts < item.max_attempts の場合は、次の反復で同じ ステップを再試行します。
• item.status が "failed" になった場合は、失敗をログに記録して、 次の作業項目に進みます。
• マニフェストを保存します。

6. コンテキスト予算を確認する

コンテキストウィンドウの使用量を推定します。 使用量が 80% を超えた場合：

1. マニフェストをディスクに保存します。
2. 現在の項目 ID、ステージ、ステップを記載した 継続メモを .egregore/continuation.json に書き込みます。
3. Skill(conserve:clear-context) を呼び出します。
4. ウォッチドッグまたは呼び出し元が新しいセッションを再起動し、 保存された状態から再開します。

7. トークン予算を確認する

最後のスキル呼び出しでレート制限エラーが返された場合：

1. budget.record_rate_limit(cooldown_minutes) を使って budget.json にレート制限を記録します。
2. budget.json を保存します。
3. オーバーシーアに通知します（notify.py を参照）。
4. セッション内での復旧をスケジュールします（有人セッションのみ）。 CronCreate を使って、クールダウン終了時に一度だけ再開するよう設定します。 ジョブは実行中のセッション内にのみ存在するため、ウィンドウの更新時に そのセッションが稼働中かつアイドル状態の場合に限り機能します。
5. それ以外の場合は、正常に終了します。これは無人実行時のデフォルトです。 ウォッチドッグが記録されたクールダウンを読み取り、ウィンドウの更新後に 再起動します。手動で選択するのではなく、window.plan_resume() を呼び出します。

8. 繰り返す

ステップ 2 に戻ります。 すべての項目が完了するか、すべての項目が失敗するか、予算の上限に達するまで続けます。

パイプラインとスキルの対応

ステージ	ステップ	スキル／アクション
intake	parse	プロンプトを解析するか、gh issue view で issue を取得
intake	validate	要件が実行可能であることを検証
intake	prioritize	複雑さに応じて順序付け（項目が 1 つの場合はスキップ）
build	brainstorm	Skill(attune:project-brainstorming)
build	specify	Skill(attune:project-specification)
build	blueprint	Skill(attune:project-planning)
build	execute	Skill(attune:project-execution)
quality	code-review	Skill(pensive:code-refinement)
quality	unbloat	Skill(conserve:bloat-detector)
quality	code-refinement	Skill(pensive:code-refinement)
quality	update-tests	Skill(sanctum:test-updates)
quality	update-docs	Skill(sanctum:doc-updates)
ship	prepare-pr	Skill(sanctum:pr-prep)
ship	pr-review	Skill(sanctum:pr-review)
ship	fix-pr	レビューの修正を適用
ship	merge	gh pr merge（auto_merge が有効な場合）

intake ステージのステップ（parse、validate、prioritize）は、 オーケストレーターがインラインで処理します。 詳細は modules/intake.md を参照してください。

ループ内での委任

build ステージと quality ステージでは、デフォルトで Skill(conjure:delegation-core) を通じて実行を委任します。 無人ループでは、このデフォルトが最も効果を発揮します。外部 CLI が利用可能なのに 使われていないことに気づく人がいないためです。

オーケストレーターはタスクごとに判断しません。 対応するスキルを呼び出し、そのスキルが独自の Keep Local 条項に基づいて 委任方針を適用します。

providers_exhausted の結果はステップの失敗ではありません。 オーケストレーターはそのステップを再試行したり、それを理由に作業項目を失敗扱いにしたりしてはなりません。 スキルは Skill(attune:project-execution) モジュールの subagent-fallback.md に従って、 セッションモデルのサブエージェントに作業を引き継ぎ、パイプラインは次に進みます。 これを失敗として扱うと、何も壊れていないマシンで再試行予算を浪費します。

外部モデルを使わずに egregore を実行するには、起動する環境で CONJURE_DELEGATION=off をエクスポートします。

コンテキストあふれプロトコル

オーケストレーターは、有限のコンテキストウィンドウ内で動作します。 ウィンドウがいっぱいになったときに状態を失わないよう、次の手順を実行します。

1. 使用量を監視します。 スキルを呼び出すたびに、コンテキストウィンドウがどの程度消費されたかを推定します。
2. 容量が80%に達したら、コンテキストを保存します。
   • マニフェスト全体をディスクに保存します。
   • 現在の位置のスナップショットを .egregore/continuation.json に書き込みます。
   • Skill(conserve:clear-context) を呼び出します。
3. 再起動時に continuation.json を読み込み、保存した位置から再開します。パイプラインの進行状況を示す信頼できる情報源は、ディスク上のマニフェストです。
4. コンテキストあふれによる引き継ぎが発生するたびに、manifest.continuation_count をインクリメントします。

このプロトコルにより、コンテキストの境界をまたいでも進行状況が失われることはありません。

進行状況の監視と自己修復（2.1.71+）

状態の読み込み後（ステップ1）、状況を報告するとともに、停止したパイプラインを復旧する定期的なハートビートをスケジュールします。

CronCreate(
  cron: "*/5 * * * *",
  prompt: "Check .egregore/manifest.json. If there are pending or active items that are not being processed, resume the orchestration loop by invoking Skill(egregore:summon). Otherwise, report status via /egregore:status.",
  recurring: true
)

これは、次の2つの目的を果たします。

1. 可視性：5分ごとに状況の概要を出力し、自律実行の状況を確認できるようにします。
2. 自己修復：ユーザープロンプト、コンテキストの圧縮、または予期しないエラーによってオーケストレーションループが中断された場合、次のハートビートが停止した項目を検出し、パイプラインに自動で再投入します。

どちらもセッションが継続していることが前提です。定期ジョブは作成したセッション内でのみ有効で、REPL がアイドル状態のときにのみ実行されます。定期ジョブは7日後に自動的に期限切れとなり、削除前に最後の1回が実行されるため、1週間を超える実行ではハートビートを再スケジュールする必要があります。

durable: true を指定しても、再起動後にジョブが維持されることはありません。このパラメーターは受け付けられますが、ツールの説明では「効果がない」とされ、永続化には対応していません。ジョブを早期にキャンセルするには CronDelete を使用し、セッションをまたいで維持する必要がある場合はウォッチドッグを使用してください。

トークン予算プロトコル

Egregore のセッションでは、予算ウィンドウ（デフォルト：5時間）内で API トークンを消費します。 予算プロトコルにより、過剰な支出を防ぎます。

1. 各スキル呼び出しの前に、budget.json で有効なクールダウンがないか確認します。is_in_cooldown(budget) が true を返す場合は終了し、ウォッチドッグによる後の再試行を待ちます。
2. レート制限エラーが発生した場合、budget.record_rate_limit(cooldown_minutes) を使ってそのイベントを記録します。クールダウン時間は、API の retry-after ヘッダーの値に config.budget.cooldown_padding_minutes を加えた時間です。
3. 保存して終了します。 budget.json を書き込み、監督者に通知して、コード0で終了します。
4. ウォッチドッグは、再起動前に budget.json を確認します。クールダウンが終了するまで、新しいセッションは開始しません。

計算方法と状態スキーマの詳細については、modules/budget.md を参照してください。

失敗への対処

各作業項目では、ステップごとに最大 max_attempts 回再試行できます（デフォルト：3回。config.json で設定可能）。

• 再試行：ステップが失敗し、attempts < max_attempts の場合、オーケストレーターは次のイテレーションで同じステップを再試行します。再試行の間にマニフェストが保存されます。
• 失敗としてマーク：attempts >= max_attempts の場合、項目のステータスを "failed" に変更し、failure_reason を設定します。オーケストレーターは次のアクティブな項目に進みます。
• 通知：失敗時には、設定された通知チャネルを通じて監督者に通知します。
• 処理を止めない：オーケストレーターは、人間からの入力を待ってはなりません。ステップで確認が必要な場合は、判断を記録し（modules/decisions.md を参照）、利用可能な最善の選択肢で処理を続行します。

モジュールリファレンス

• pipeline.md：ステージとステップの定義、遷移ルール、冪等性の保証。
• budget.md：トークンウィンドウの管理、レート制限の検出、クールダウンの計算、正常なシャットダウン。
• intake.md：プロンプトと GitHub のイシューからの作業項目の解析、ブレインストーミングのスキップロジック。
• decisions.md：自律的な意思決定のフレームワーク、判断ログの形式、例。

終了条件

• オーケストレーションループの開始前に .egregore/manifest.json が正常に読み込まれる。不在の場合、スキルは「No manifest found. Run egregore init first.」と表示して停止する
• パイプラインの各ステップが完了すると、マニフェスト内の item.pipeline_stage が進み、マニフェストがディスクに保存される
• コンテキストが 80% に達すると、ハンドオフ前に、現在のアイテム ID、ステージ、ステップを含む .egregore/continuation.json の書き込みが実行される
• レート制限エラーが発生すると、セッションが終了コード 0 で終了する前に、budget.json がクールダウン時間で更新される
• すべてのアイテムが完了または失敗すると、オーケストレーターはアイテムのステータスを一覧にした完了レポートを出して終了する