エージェント実行・共通設計

SpecDojo CLIと外部エージェントCLIを組み合わせた実行モデルの入口を定義する。本書は共通の目的・責務境界と子設計への導線を保持し、横断的な必須ルールはsysd-cross-cutting-policyを正本とする。

1. 目的・適用範囲

対象はspecdojo exec runによる非対話実行と、対話型オーケストレーターからSpecDojoを操作する構成である。provider固有の認証・モデル・権限・agent定義は子設計、CLI更新操作はopr-agent-cli-updateへ委ねる。

2. 設計方針・責務境界

層	責務	責務外
SpecDojo CLI	task状態、依存、plan・result・eventを管理する	成果物内容の判断・編集
agent	渡されたplanを解釈し、editまたはreviewを実行する	claim、並列起動、統合制御
specdojo exec run	member選択、phase、並列数、worktree、失敗処理を制御する	成果物内容の判断・編集
orchestrator	人との対話から対象とコマンドを提案し、承認後に実行する	非対話executorの代替、最終承認

責務分離、member選択、設定解決、利用制限、イベント、worktreeの規範はsysd-cross-cutting-policyのRule IDを参照する。事故予防が必要な順序と失敗経路はsysd-critical-flowsを参照する。

3. 共通実行モデル

schedule / register item
  → plan生成・claim
  → phase要件に適合するmember選択
  → 必要なworktreeを割当
  → agentがeditまたはreview
  → 検証・result確定
  → commit・直列統合・complete、またはblockして再開条件を保持

設定の一次情報は .specdojo/exec-defaults.yaml と .specdojo/agent-members.yaml、人間名簿の一次情報は project 配下の pm-members.yaml、実行状態の一次情報は project 配下の plan・result・append-only event である。

register pipeline は、個票の difficulty と .specdojo/exec-defaults.yaml の routing がそろう場合、難易度別に executor・reporter・rate limit 対応を解決する。CLI の段別指定を最優先し、難易度または表がない場合は stage_role と priority による従来の自動選択へ戻す。夜間 orchestrator も独自選択を持たず、同じ exec run --register の解決を使用する。

agent が親 runner・Git hook・CI・agent 指示の内容を変更できないよう、package.json、lefthook 設定、.specdojo/**、commitlint 設定、CI 設定、agent 指示ディレクトリ、root の指示ファイルは provider 共通の固定保護パスとする。runner は agent 終了直後かつ親検証前に起動前との差分を検査し、worktree の commit 前には未 commit 差分と branch 上の commit 済み差分を再検査する。違反時は対象パスを標準エラーへ出力して block し、branch / worktree を保持する。provider 固有の permission / sandbox は第一層として維持するが、この判定の入力には使わない。

agent起動時は親プロセスのGIT_DIR、GIT_WORK_TREEその他のrepository固有環境変数を除去し、cwdから対象worktreeを再解決させる。runnerは各agent試行の前後でHEADとlocal configも比較し、agent自身のcommitまたはcore.bareを含む設定変更を検知した場合は親検証・reporter・統合を行わずblockする。この境界は通常実行、in-place、trial、分割worktree commandのすべてへ適用する。

4. 子設計一覧

子設計	対象	固有責務
Claude Codeエージェント設定	Claude Code	認証、モデル、agent定義、起動設定
Codexエージェント設定	Codex	sandbox、モデル、custom agent、起動設定
OpenCodeエージェント設定	OpenCode / Ollama	ローカルLLM、agent定義、起動設定
GitHub Copilotエージェント設定	GitHub Copilot CLI	認証、agent定義、非対話実行
Antigravity CLIエージェント設定	Antigravity CLI	認証、モデル、指示読込、起動設定
オーケストレーターエージェント設定	対話型orchestrator	提案・承認・実行境界、固定worktree起動

provider: customは共通の上書き拡張点であり、固有の標準provider設計は持たない。採用する場合は独立した子設計を追加する。

5. 検証観点・関連文書

種別	参照先	確認事項
全体入口	システム設計	設定・実装SSOTの所在
横断ルール	システム設計横断ルール	責務、設定、失敗、worktreeの必須事項
重要フロー	システム設計重要フロー	並列・統合・ID・PR・延期再開
Job	Job実行設計	Job Runからexec基盤への委譲
運用手順	外部エージェントCLI更新	CLI更新と証跡
検証	tests/src/exec/*.test.ts	member選択、worktree、retry、resume