aep-autopilot

オートパイロット

1つのコマンドで自律実行を開始します。状態を初期化し、最初のティックを実行して、現在のレイヤーが完了するまでティックを続けます。デフォルトのドライバーはゴール駆動（/goal。Claude Code と Codex でネイティブ対応）です。各ティックでレイヤーを進め、完了条件が満たされていない場合にのみランタイムが再実行するため、現在のレイヤーのすべてのストーリーがマージされ、ラップアップされるか、人間の判断が必要なゲートに達すると、オートパイロットは自動的に停止します。その後、レイヤーゲート／/aep-reflect に進み、次のレイヤーで再度実行します。--loop は固定間隔のフォールバックドライバーを選択します。根拠： docs/decisions/goal-driven-autopilot.md。

この機能の位置づけ： /aep-envision → /aep-map → /aep-validate → /aep-autopilot （goal: "layer N complete"） → /aep-reflect。

セッション： メインセッションのみ — ステップ①でガードされます。 状態： .dev-workflow/autopilot-state.json（機械可読）と .dev-workflow/autopilot-status.md（人間可読）。すべての有効なフィールドの型は references/autopilot-state.schema.json で定義されています。 references/state-schema.md には、アトミック書き込みとティックロックのプロトコル、および状態ファイルを検証する実行可能なコマンド（共有の scripts/json-schema.mjs を使用する scripts/validate-state.mjs）が記載されています。

---

停止 — オーケストレーターの境界

あなたはオーケストレーターであり、実行者ではありません。すべてのコード操作はワークスペースエージェント内で行われ、メインセッションはシグナルファイルと git メタデータのみで進捗を評価し、executor.nudge() を通じてワークスペースの作業を誘導します。この境界を越えることがオートパイロットで最もよくある失敗の原因であるため、禁止事項は2つだけとし、ここにまとめています。

絶対に禁止することが2つあります。 どちらもオーケストレーター自身のツール使用を制限するもので、外部からプローブで観測できません。そのため、AEP のほかのすべてのルールとは異なり、機械的なチェックはありません。それぞれの禁止事項は、その代わりに行うべきことと組み合わせて一度だけ記載します。

• ワークスペースのソースファイルを読まないでください（Read／Grep／Bash を使ってワークツリーにアクセスしないでください）。評価には、シグナルファイル（.dev-workflow/signals/）とgit メタデータ（gh pr view、git diff --stat）のみを使用してください。実装コードをオーケストレーターのコンテキストに取り込むと、コード品質について意見を持ち、それに基づいて行動するようになります。メインセッションから起動したコードレビュアーも、形を変えただけで同じ境界越えです。シグナルのみの分析はコードレビューではなく、そのエージェントにワークツリーを渡すだけでも境界越えになります。
• オーケストレーターから gh pr merge を実行しないでください。ワークスペースエージェントにマージを促してください。 ワーカーはフェーズ12（リベース、CI、コメント解決）を担当し、チェックが通ったらマージします。「PR の準備完了」はワーカーの停止地点ではありません。このルールが適用されるのは MAIN のみです。ワーカープロンプトに持ち込んではいけません。ワーカーに「マージしないでください」／「準備完了の時点で停止してください」と伝えると、CLEAN でマージ可能な PR がいつまでも放置されます（codex-subagent の共有セッションにおける失敗）。マージを促すメッセージには必ず "フェーズ12を通過したらマージしてください。" と書いてください。

オーケストレーターが行うこと（許可されている操作）

必要な操作	オーケストレーターのアクション
ワークスペースの進捗を読む	.feature-workspaces/<name>/.dev-workflow/signals/status.json を読みます
PR の状態を確認する	gh pr view <number> --json state（参照のみ）
コードレビュー／gen-eval を起動する	executor.nudge(<ws>, "<trigger>") — ワークスペースが独自の評価を実行します
フィードバック／指示を送る	executor.nudge() または .feature-workspaces/<name>/.dev-workflow/signals/feedback.md に書き込みます
停滞しているエージェントを促す	executor.nudge(<ws>, "<nudge>")
人による承認ゲートを提示する	signals/needs-human.md を読み、人の回答をそのモードのチャネルで伝えます
コードの修正／テスト／評価／マージを依頼する	executor.nudge() — ワークスペースがビルド、テスト、評価、Phase-12 のマージを担当します。結果については eval-response-*.md を監視します

CHECK デリゲート（以下）がシグナルを読むことは、境界違反ではありません。シグナルの記録管理をオーケストレーター自身から低コストなコンテキストに委ねるものであり、コードは読みません。

2 つの gen/eval の懸念事項 — 厳密に分離

懸念事項	担当	評価対象	実行場所
コード品質	ワークスペースエージェント	正確性、セキュリティ、完全性	ワークスペースワーカー内
オーケストレーション学習	Autopilot（メインセッション）	ワークスペース横断のパターン：失敗、コスト、再試行	メインセッション → /aep-reflect（references/orchestration-learning.md を参照）

ワークスペースの gen/eval をいつ起動するかを決める検出ロジックについては、references/review-trigger.md を参照してください。

Executor のトランスポート

ワークスペースに対するすべてのアクションは、3 つの executor 動詞を通じて実行されます。 executor.nudge(ws, msg)（指示を送る）、executor.liveness(ws)（本当に動作しているか — プロセスが存在し、かつ worktree がアクティブであること。roster/state のメンバーシップは決して使いません）、executor.check(prompt, schema)（低コストでコンテキスト分離された読み取り）。モードごとのトランスポート、ドライバー × バックエンドのマトリックス、spawn 後の liveness プローブ、spawn／孤立状態からの再採用手順は、/aep-executor の references/backends.md に正式に記載されています。検出したモードについては、こちらを参照してください。Autopilot には操作可能で、ドライバーと互換性のあるモードが必要です。検出されたのが workflow/headless のみの場合（中間ステージを操作する手段がない場合 — このバッチパスは /aep-dispatch … with workflow オーケストレーターのものであり、Autopilot が操作するものではありません）、Autopilot には操作可能なモードが必要であると報告して停止してください。

---

/aep-autopilot — 開始

Autopilot を初期化し、最初のティックを実行して、ドライバーを開始します。1 つのコマンドだけで完了し、2 つ目の手順は不要です。

/aep-autopilot                  # goal driver (default) — drives the current layer to completion, then stops
/aep-autopilot --floor 3m       # goal driver, custom per-tick wait floor (default 5m)
/aep-autopilot --loop 10m       # fixed-interval loop driver (fallback), custom interval
/aep-autopilot status           # progress + escalations
/aep-autopilot stop             # gracefully stop the driver

ドライバーの選択： --loop <interval> を指定するとループドライバーが選択され、指定しない場合はゴールドライバー（デフォルト）が選択されます。--floor <dur> はゴールドライバーにのみ適用されます（ティックごとの待機時間。デフォルトは 5m）。--max-turns <n> は暴走を防ぐための上限としてゴールドライバーに適用されます（デフォルトは 200）。

前提条件

# 1. Must be on main workspace (not inside a feature workspace)
pwd | grep -q '.feature-workspaces' && echo "ABORT: Run from main workspace only" && exit 1

# 2. Product context must exist
[ -f product-context.yaml ] || echo "ABORT: Run /aep-envision and /aep-map first"

# 3. Autonomous routing must be enabled
# Check topology.routing.autonomous: true in product-context.yaml

続行する前に確認してください。

• メインワークスペースのガード： pwd に .feature-workspaces が含まれていないこと
• プロダクトコンテキストが存在すること： product-context.yaml が存在し、stories セクションがあること
• 自律実行が有効であること： topology.routing.autonomous: true が設定されていること
• ストーリーが利用可能であること： 少なくとも 1 つのストーリーが ready または in_progress であること
• 検証済みであること： プロダクトコンテキストが /aep-validate の検証に合格していること（両方のパス）

開始プロトコル

1. .dev-workflow/ が存在しない場合は作成します。

   mkdir -p .dev-workflow
   

2. .dev-workflow/autopilot-state.json を初期化します（references/autopilot-state.schema.json に定義されたすべてのフィールドを入力します）。

   {
     "version": 1,
     "status": "running",
     "started_at": "<ISO8601>",
     "last_tick_at": null,
     "tick_count": 0,
     "workspaces": {},
     "escalations": [],
     "stats": {
       "stories_completed": 0,
       "stories_failed": 0,
       "total_ticks": 0,
       "total_cost_usd": 0
     }
   }
   

3. 初期の .dev-workflow/autopilot-status.md を作成します（Status: Running、tick count 0、アクティブなワークスペースはまだありません。templates/autopilot-status.md.tmpl に入力します）。

4. 起動モードとドライバーの組み合わせを解決します（executor detect() と driver × backend マトリックスを使用）。Claude Code では、デフォルトのモードは native-bg-subagent です（作成するチームはありません。agent-teams のチームがアクティブな場合は、チームなしのバックグラウンド起動に影響するため、先に TeamDelete で削除します）。組み合わせを通知します（例：「native-bg-subagent + /goal」または「codex-exec + launchd」）。

5. 直ちに最初の tick を実行します（以下の /aep-autopilot tick を参照）。

6. 以下のセレクターに従ってドライバーを起動します。

ドライバーセレクター

どちらのドライバーでもオーケストレーターは長時間稼働し続けるため、制御可能なモードであればどれでも動作します。goal ドライバーは、レイヤーの完了時に自動的に終了する機能も備えています。 どちらのドライバーでも tick の処理内容は同じです。異なるのは次の tick の起動方法だけです。詳細な手順（ゴール条件のテキスト、ホストごとの /goal / /loop コマンド、Codex の codex exec を使った launchd のスニペット）：references/drivers.md。

ホスト / 実行	ドライバー	開始
Claude Code / Codex、対話あり	goal（デフォルト）	/aep-autopilot が /goal "<layer-N condition>" を設定し、レイヤーが完了するか一時停止されるまで各ターンで再実行します
任意のホスト、固定間隔または /goal なし	loop（--loop）	/loop <interval> /aep-autopilot tick
OS スケジュール、対話なし	cron/launchd 経由の loop	codex exec … "/aep-autopilot tick" をスケジュールします（OS バインドモードのみ）

ドライバー × バックエンドの互換性： 長時間稼働するドライバー（goal、またはセッション内の /loop）は、制御可能な任意のモードに対応します。cron/launchd による tick ごとの新規セッション実行は、OS バインドモード（claude-bg、codex-exec、legacy）のみをサポートします。/goal はセッション内で動作するため、/loop または外部スケジューラーで実行します。完全なマトリックス：/aep-executor references/backends.md。 goal ドライバーの不変条件： 対象は 1 つのレイヤーに限定されます。評価器は、表面化されたステータス行（シグナルのみ、手順 ⑦）のみを評価します。tick ごとの待機時間の下限は必須です（これがないと、ターン終了直後に /goal が過剰にループします）。また、--max-turns（および Codex の token_budget）で常に実行範囲を制限します。

戦略的なゲート — full_auto と auto_design

2 つの topology.routing フラグが、戦略的な（「何を構築するか」／アーキテクチャ）人間によるゲートを制御します。どちらもデフォルトでは人間が制御を維持します。

• auto_design（デフォルトは false）：ディスパッチ可能な状態に達していない段階のストーリー、または標準の再試行回数超過による上書き条件に該当するストーリーは、人間の判断を待つために一時停止します。auto_design: true の場合は、代わりに /aep-design（非対話型）へルーティングし、準備状況を再計算してから /aep-launch を実行します。一時停止はありません。
• full_auto（デフォルトは false）：より細かいフラグ（auto_design、auto_outcome_eval、watch.auto_create）の上位にあるマスタースイッチです。full_auto: true はこれらすべてを有効にするため、設計エスカレーションによる一時停止も、定性的な成果契約の評価も、エージェントの判断により自動で続行します。デフォルトでは、戦略的な一時停止はすべて人間が判断します。これらのフラグが有効でも、再試行回数超過による上書き条件は常にエスカレーションします。

ルーティングのしきい値と一時停止のプロトコルは、それらを適用する tick ステップに記載されています（references/tick-protocol.md の Step ⑥）。エスカレーションのエントリーは references/autopilot-state.schema.json で型定義され、一時停止中の autopilot-status.md のセクションは templates/autopilot-status.md.tmpl に記載されています。

full_auto はジャーニーの作成には関与しません。 ジャーニーファイルは常にマージ前のビルド成果物です（/aep-build の Phase 6 Step A でレイヤーの受け入れ基準から作成し、機能とともにコミットします）。そのため、full_auto: false と journey_timing: post-deploy の組み合わせでは、デプロイ後のレイヤーゲートで引き継ぎを行う前に、ジャーニーがすでに存在している必要があります。引き継ぎ処理は実行して切り替えるだけで、作成はしません。ジャーニーファイルがないままレイヤーがゲートに到達した場合は、ゲートで人間が作成する作業ではなく、/aep-wrap の COVERAGE FAILURE（ビルド時に作成されているはずです）です。

---

/aep-autopilot tick

ドライバー（ゴールまたはループ）が呼び出す、tick ごとのハンドラーです。いつでも手動で実行できます。冪等であり、外部状態に変化がない状態で再実行しても、アクションは重複しません。

実行モデル — CHECK → ACT。 各 tick では、軽量でコンテキストから分離されたエージェント（Claude Code では Haiku サブエージェントの executor.check()、Codex では codex exec の単発実行）が読み取りを行い、更新済みの autopilot-state.json と autopilot-status.md を書き込み、アクションリストを返します。その後、オーケストレーターがアクション（nudge、wrap、launch、escalate／design）を実行するため、トークンを多く消費する読み取り処理を長時間実行されるセッションから切り離せます。Codex では tick 全体がすでに分離された codex exec で実行されるため、CHECK をインラインで実行できます。各ステップがどちらの処理に属するかは references/tick-protocol.md に記載されています。アクションリストは /aep-executor の references/action-list.schema.json で型定義されています。

Tick の概要（①～⑦、各ステップで不変条件を適用）。 完全なステップ手順（CHECK のプロンプト内容、④b／④c のナッジ用プロンプト文を含む ACT テンプレート、およびすべてのしきい値）は、references/tick-protocol.md が正準の定義です。

① READ STATE       cat autopilot-state.json; exit if status≠running or a fresh tick lock is held; else take the tick lock.
② SYNC SIGNALS     fold each workspace signals/status.json into state; blocked_on==human → escalate human_gate (not stuck); orphan (session-bound mode, by real liveness) → emit a re-adopt launch into the existing worktree.
③ WRAP COMPLETED   story_status==completed → /aep-wrap (max one per tick, [one-wrap-per-tick]); remove from state; then skip to ⑦.
③.5 POST-MERGE GUARD  for each merged story, watch deploy health + host-aware dogfood across a window; UX finding → /aep-reflect story; confirmed hard regression → escalate (or revert if auto_revert). See references/post-merge-guard.md.
④ GUIDE COMPLETION per workspace: ④a check PR state; ④b quality gate — no eval PASS → trigger the workspace's own gen/eval via executor.nudge(); ④c eval PASS + PR open → nudge toward Phase-12 merge (once).
⑤ DETECT STUCK     (phase, completion_pct) unchanged vs last tick → run executor.liveness() before counting; then the stuck ladder (observe → nudge → escalate); human-gate exempt.
⑥ DISPATCH NEW WORK  capacity? run /aep-dispatch scoring (steps 1-3); wave + layer-gate + grouped-change ordering; dispatch-ready → /aep-launch, otherwise escalate or auto-design; max one launch per tick ([one-launch-per-tick]); runs after ③ ([wrap-before-dispatch]).
⑦ WRITE STATE + SURFACE + WAIT  atomic write state (.tmp → rename); append autopilot-history.jsonl; update autopilot-status.md; release the tick lock. Goal driver only: surface the signals-only AUTOPILOT status line, then wait the per-tick floor before ending the turn.

[角括弧で囲まれた]タグは機械的な順序の不変条件です。説明文から想起するとずれが生じる、決定論的な WHEN＋SHAPE ルールであり、型付きゲートによって保護されています。このループを拡張するプロジェクトでは、独自の型付き動詞の配下に移行してください。docs/decisions/deterministic-orchestration.md（カタログは references/deterministic-orchestration.md）を参照してください。

---

/aep-autopilot status

現在のオートパイロットの状態を読み取り、表示します。

cat .dev-workflow/autopilot-status.md
ROOT=$(git rev-parse --show-toplevel); AP="$ROOT/.agents/skills/aep-autopilot"; [ -d "$AP" ] || AP="$ROOT/.claude/skills/aep-autopilot"
node "$AP/scripts/derive-workspace-state.mjs"   # logical state + flags per workspace

人間向けの説明は、/aep-easy-explain の文体で表示します。最初に背景を一行で示し、ASD-STE100 に準拠した平易な英語と、プロジェクト独自の用語を使います。

また、.dev-workflow/autopilot-state.json を解析し、次の情報を表示します。Status（実行中／一時停止／停止）、Uptime（started_at からの経過時間、tick 数）、Active workspaces（名前、story_id、フェーズ、completion_pct、last_action）、Pending escalations（タイプ、story_id、理由）、Stats（完了数、失敗数、総コスト）。**一時停止中の場合：**理由、人間に求められるフィードバック、再開方法。

---

/aep-autopilot stop

オートパイロットを正常に停止し、アクティブなドライバーをキャンセルします。

1. .dev-workflow/autopilot-state.json の status: "stopped" を設定します。
2. .dev-workflow/autopilot-status.md を停止状態に更新します。
3. 停止イベントを .dev-workflow/autopilot-history.jsonl に記録します。
4. ドライバーをキャンセルします。
   • Goal driver: /goal clear（Claude Code / Codex）。以降のターンで再実行されることはありません。（ゴールドライバーはレイヤー完了時にも自動でクリアされるため、stop は主に早期終了に使用します。）
   • Loop driver: /loop（loop スキルのキャンセル機能）をキャンセルするか、OS スケジュールで実行している場合は cron/launchd ジョブを削除します。
5. native-bg-subagent: バックグラウンドサブエージェントはセッションに紐づいており、オーケストレーターのセッション終了時に停止します。作業を保持したまま早期停止するには、各実行中のワーカーがフェーズ境界に達するまで待つか、TaskStop <agentId> を実行します。すべての状態は worktree と .dev-workflow/ に保存されるため、後続の /aep-autopilot が生存確認プローブによって孤立したワーカーを再び引き継ぎます。

効果： ティックは停止します。実行中のワークスペースは自律的に作業を続けます（オートパイロットには依存しません。ただし、リードセッションが終了するとセッションに紐づくワーカーは孤立し、次回の開始時に再び引き継がれます）。プロダクトコンテキストは変更されず、ラップやマージも実行されません。再開するには /aep-autopilot を実行します。

---

ガードレール

自然に当てはまる手順がないルール（順序に関する不変条件、アトミックな書き込み、ティックロックは references/tick-protocol.md / references/state-schema.md に記載されています。WIP 上限の topology.routing.concurrency_limit と dependencies-completed ゲートは Step ⑥ のディスパッチチェックに含まれます）：

• マージを促す前に、実際の PASS を必須とします — 統合／テストのストーリーでは、少なくとも 1 つのチェックに合格するか、評価レスポンスで明示的に PASS とされている必要があります。SKIP のみの結果や「チェックなし」は、証拠がない状態であり、合格ではありません。

---

次のステップ

オートパイロットがレイヤーを完了した後、または停止した後：

アクション	タイミング
/aep-reflect	レイヤー完了後 — 成果の契約を評価し（Step 2.75）、フィードバックを分類します
/aep-autopilot status	いつでも — 進捗とエスカレーションを確認します
/aep-autopilot	一時停止を解消した後 — ドライバーを再開します（レイヤーのゴールを再設定します）
/aep-dispatch	手動モード — 特定のストーリーを対話形式で選択します