feat: autopilot — Claude による Issue ライフサイクル自律オーケストレーター（EPIC + スパイク）

[smalruby3-editor-bot]

🆕 Smalruby 独自 — 開発運用のための自律オーケストレーター。upstream には存在しない。

Goal

複数の GitHub Issue を Claude が並行して、起票 → トリアージ（EPIC 分解 / size 重み付け）→ 実装 PR → 敵対的レビュー → 人間レビュー → DoD → マージ まで自律的に進める常駐プログラム autopilot を作る。状態は smalruby org の専用 GitHub Projects v2「Autopilot」#4 のフィールドで一元管理する（Issue のみ管理。PR は label/Draft/sticky で投影）。autopilot 自身が、この EPIC の sub-issue 群を最初の実ワークロードとして処理する（自己ブートストラップ）。

現状: スパイク完了 ✅（develop マージ済み）

A（設計確定）/ B（Project 構築）/ C（歩く骨格）を完了し develop に反映済み。成果物:

• docs/autopilot/autonomous-contract.md — 全 autopilot-* スキルと Runner の契約（非対話 / 結果ファイル+番兵 / bot identity / 冪等 / PR 投影 / HITL OR 解除）
• .claude/skills/autopilot-triage/ — triage スキル（分類・スコープ・size）
• bin/autopilot-worktree — 軽量 worktree（install/build 不要・状態共有）
• tools/autopilot/ — 歩く骨格（contract/phases/project/runner/cli + unit tests）
• Project「Autopilot」fix: restore Smalruby assets and fix scratch-gui unit tests #4 — Status / AI Status / HITL / Size / Kind / 補助テキスト

dogfood 実証済み: OR 解除セマンティクス、実 claude triage（#767）、merge-progression、PR ラベル/Draft/sticky。

アーキテクチャ

GitHub Projects v2 #4 (状態の単一の真実, Issue のみ)
        ▲ poll/更新 (gh GraphQL, bot)   │
   autopilot daemon (常駐・単独プロセス) ─┤  並行2 / pause・resume・force-stop / HTTP 割込
        ├ Claude runner (tmux send-keys + watchdog, worktree 隔離)
        ├ Web ステータスモニタ (一覧/ログ/操作)
        └ CLI (単発検証: あるフェーズだけ試す)

• Status（人間の Scrum 列）: New Item / Backlog / Icebox / Sprint Backlog(キュー) / In Progress / Review / DoD / Close
• AI Status（AI 専用の細フェーズ ≈ スキル）: Triaging / Understanding / Decomposing / EPIC Decomposed / Implementing / Creating PR / Self-Reviewing / Addressing Comments / Running DoD
• HITL(Yes/No): 人間の番か（set は全面一括 Yes / 解除は OR: どれか1つ No で proceed）
• 設計の詳細な決定ログは本 issue のコメント群、および docs/autopilot/autonomous-contract.md 参照（README は docs(autopilot): docs/autopilot/README.md を集約 #768 で集約）。

EPIC 運用方針

EPIC は「作業項目」ではなく「トラッカー」。daemon は leaf（Kind=Issue）だけをキューから拾う。
本 EPIC は子がすべて done になるまで In Progress のまま継続し、子 PR の merge では完了しない
（merge-progression は leaf にのみ適用）。畳むときは「納品スライスを Done + 残りをフォローアップ EPIC」。

Sub-issues（分解結果）

GitHub の Sub-issues として紐付け済み。size 付き:

• docs(autopilot): docs/autopilot/README.md を集約 #768 README 集約 — small（Sprint Backlog: 次に着手）
• feat(autopilot): bin/autopilot-worktree に既存ブランチ/PR checkout モードを追加 #767 autopilot-worktree 既存ブランチ/PR checkout モード — middle
• feat(autopilot): daemon 本体(ポーリング/state machine/並行2/HTTP) #769 daemon 本体（ポーリング/state machine/並行2/HTTP・単独プロセス） — large
• feat(autopilot): Claude runner 堅牢化(権限既定/merge検知/学び反映) #770 Claude runner 堅牢化（権限既定/merge検知/OOM・学び反映） — middle
• feat(autopilot): autopilot-decompose スキル #771 autopilot-decompose スキル — middle
• feat(autopilot): autopilot-understand スキル #772 autopilot-understand スキル — middle
• feat(autopilot): autopilot-implement スキル(TDD→PR/Draft) #773 autopilot-implement スキル（TDD→PR/Draft） — large
• feat(autopilot): autopilot-review スキル(敵対的レビュー) #774 autopilot-review スキル（敵対的レビュー） — middle
• feat(autopilot): autopilot-address-review スキル #775 autopilot-address-review スキル — middle
• feat(autopilot): autopilot-verify スキル(Playwright DoD) #776 autopilot-verify スキル（Playwright DoD） — middle
• feat(autopilot): Web ステータスモニタ(一覧/ログ/操作) #777 Web ステータスモニタ — large

[smalruby3-editor-bot]

スパイク A: 設計判断ログ（discussion 記録）

A「設計確定」の議論で合意した判断を記録する。詳細仕様は docs/autopilot/README.md に転記予定。

1. claude 駆動方式: 対話 claude を tmux + send-keys で駆動

• 理由: 課金ポリシー（対話モード = Claude サブスク枠を利用する想定。headless -p を従量課金と判断）。
• 最重要不変条件: claude を「カーソルで人間の入力を待つ状態」に 絶対にしない。
  • 権限プロンプトを出さない（settings allow-list / --permission-mode）
  • claude へ渡すプロンプトに「人間に対話的に質問しない。判断が必要なら Issue/PR にコメントして HITL 状態にして終了 せよ」を明示
  • tmux pane を監視して「ターン完了（入力欄に戻った）」「HITL シグナル」を検出
  • watchdog/timeout でストール時は force-stop
• ⚠️ スパイク C で実証すべき最大リスク: tmux 駆動で上記不変条件を確実に守れるか。
• 補足の検証項目: claude -p（headless）も OAuth サブスク認証なら従量課金にならない可能性がある。事実なら headless の方が堅牢なので、スパイク中に課金実態を1回確認し、結果次第で再検討の余地を残す。

2. HITL ゲートの位置: 分解承認 + マージ前 + EPIC 理解フェーズ

想定する状態遷移（HITL は複数回入る）:

Inbox
  → EPIC理解        → HITL
  → (再)EPIC整理     → HITL
  → sub-issue 分解   → HITL
  → 実装 → PR
  → Adversarial Review
  → HITL（人間レビュー） → approved = Reviewed
  → Playwright 最終チェック
  → Merge → Done

• 特に EPIC → sub-issue 分解フェーズは HITL が複数回入る想定。
• HITL? フィールドは「今この item が人間待ちか」を Status と直交で表す。
• claude が作業中に判断を要したら → Issue/PR にコメント + HITL に遷移（対話質問はしない）。

3. 並行数・割り込み（HTTP IPC）

• 既定の自律ワーカーは 並行 2 + 控えめの上限（--max-turns / --max-budget-usd 相当の運用上限）。
• ユーザーが CLI で 特定 Issue を割り込み投入可能。割り込み時は並行 2 を超えてよい。
• 割り込みは daemon への HTTP リクエスト（プロセス間通信） でタスク追加する。
• → daemon は HTTP サーバを兼ねる（Web モニタ配信 + CLI からのタスク投入 + pause / resume / force-stop）。

4. 実行環境: Node.js

• 本プロジェクト採用に合わせて Node.js。bun シングルバイナリ化は見送り（外部プロセス shell-out が主で旨味が薄い）。

5. 認証: bin/bot-token を流用

• 残り5分で自動リフレッシュ・idempotent な既存実装。新規実装不要。daemon は各 gh/git 操作の直前に呼ぶ。

6. 敵対的レビュー: 別 claude 実行 + 既存 skill

• 別の claude 実行で /code-review + /security-review skill を PR diff にかけ、bot が PR コメント投稿 → 修正 → 再レビューを上限付きループ。

7. クラッシュ復旧: Project = 単一の真実 + daemon ローカル journal

• daemon は軽量な journal（issue 毎に session / worktree / tmux 窓 / 現ステップ / heartbeat）を保持し、再起動時に Project + journal で突き合わせて復旧。

[smalruby3-editor-bot]

訂正・補強: 駆動方式の根拠（課金面）

上の判断ログの「claude -p も OAuth なら従量課金にならない可能性」という補足を 撤回 する。Web で確認した事実に基づき、tmux + send-keys（対話ターミナル Claude Code の駆動）が課金面で唯一安全な選択であることを確定する。

事実関係

• 2026-05-14 発表: Claude Agent SDK・claude -p（headless）・Claude Code GitHub Actions・サブスク認証する3rdパーティの4面を、2026-06-15 からサブスク枠の対象外にし、API レート課金の別建て月額クレジット（Pro≈$20 / Max5x≈$100 / Max20x≈$200、繰越なし）へ移す、と公表。
• 対話ターミナルの Claude Code と claude.ai チャットはサブスク枠のまま変更なし。線引きは「人間が enter を押す = サブスク / ロボットが押す = 新クレジット（従量）」。
• 2026-06-15 当日に Anthropic はこの変更を一時停止。本 issue 作成時点（2026-06-28）では claude -p もまだサブスク枠で動く。ただし発表済みで停止されているだけで、将来再開され得る。

結論

• 将来も確実にサブスク枠に留まる surface は 対話ターミナル Claude Code のみ。
• autopilot は tmux + send-keys で対話 Claude Code を「人間が enter を押すのと同じ形」で駆動する。これにより課金変更が再開されてもサブスク枠のままでいられる。
• claude -p / Agent SDK は名指しで従量化対象のため、採用しない。
• これは「ターン完了 / HITL を tmux pane 監視で検出する」難所を 歩く骨格 C で必ず実証する設計を正当化する。

出典

• https://the-decoder.com/claude-subscriptions-get-separate-budgets-for-programmatic-use-billed-at-full-api-prices/
• https://support.claude.com/en/articles/15036540-use-the-claude-agent-sdk-with-your-claude-plan
• https://www.digitalapplied.com/blog/anthropic-claude-credit-overhaul-june-15-2026
• https://tygartmedia.com/claude-code-billing-credit-pool-2026/

[smalruby3-editor-bot]

Runner 堅牢性要件（実運用フィードバックより）

tmux + send-keys で対話 Claude Code を駆動した実運用で判明した課題と、その対応を
Claude Runner + Watchdog の設計要件として記録する。歩く骨格 C で作り込む中核。

検出は2層構成

1. 番兵行で決定論的に検出（第一）: スキルが実行末尾に出力する
   • AUTOPILOT_RESULT: {json} … 正常完了（次ステータス / size / 作成 sub-issue 等）
   • AUTOPILOT_HITL: {json} … 人間待ち（コメント済み・理由）
2. pane スクレイピングのヒューリスティック（安全網）: claude が番兵を守れなかった
   場合に備え、pane テキストと pane プロセス情報を監視。

Watchdog ループ（一定間隔ポーリング、例: 3秒）

課題	検出	対応
1 起動しない（tmux/claude の起動表示中で最初の send-keys が受け付けられずプロンプト待ちで停止）	pane を監視し「入力プロンプト準備完了」パターンを検出してから最初の send-keys を送る。ブラインド sleep ではなくポーリング。T_ready 内に準備できなければ kill→再起動	send-keys リトライ+ジッタ / リトライ上限超で強制再起動
2 インタビューで停止	pane が「未変化が T_idle 継続」または AskUserQuestion / 権限プロンプトのパターンに一致	force-kill。再起動時に「対話質問するな・必要なら HITL 番兵+コメントで終了せよ」という指示を強めて再投入し、同じインタビューで再停止しないようにする
3 原因不明で長時間稼働	絶対上限 T_max 超過 / 手動 force-stop（HTTP API・Web モニタ）	tmux 窓を kill し、item を Blocked または再試行へ
4 終了したのにデーモン上で状態不変	一定間隔でサブプロセス実体をポーリング（tmux の pane_current_command がシェルに戻った / claude PID 消滅 / pane_dead）	最終番兵を読み DONE / 失敗を daemon 状態へ反映

Runner ライフサイクル

LAUNCHING → READY → RUNNING → { DONE | NEEDS_HUMAN | STALLED | TIMEOUT | CRASHED }

• 遷移はタイマー（T_ready / T_idle / T_max）と番兵で駆動。
• 再起動回数をカウントし、N 回超で Blocked + HITL に escalate（無限再起動を防ぐ）。
• force-stop は手動（HTTP API / Web モニタ）と自動（T_max）の両方。

スキル側（自律コントラクト）への影響

• 各フェーズスキルは末尾で必ず番兵行を出力する責務を負う（検出を決定論的にする）。
• 「対話質問しない／必要なら AUTOPILOT_HITL + コメントで終了」をコントラクトの第一条にする。
• 再起動時に強調する“no-interview”指示も、コントラクトの一部として再投入プロンプトに織り込む。

[smalruby3-editor-bot]

B 完了: 専用 Project 構築 + 確定した状態モデル（最終版）

専用 Project Autopilot (#4) を作成し、フィールドを構築した。
https://github.com/orgs/smalruby/projects/4

本コメントの状態モデルが確定版で、Issue 本文・初期コメントの旧ドラフト（Inbox/Triage/... の13ステータス）を置き換える。

Status（人間の Scrum ボード列 = 人間にとってのフェーズ）

New Item（=Status 未設定）→ Backlog（やると決めた）/ Icebox（やらない）→ Sprint Backlog（autopilot のキュー）→ In Progress（実装〜PR〜敵対的レビュー）→ Review（HITL レビュー待ち）→ DoD（approve 後に Playwright で DoD）→ Close（merge 後に自動）

AI Status（AI 専用の細フェーズ。各値 ≈ 1 スキル。Issue を状態の正とし、daemon 障害時も Issue を見れば現在地が分かる）

AI Status	対応スキル	主な Status
Triaging	autopilot-triage	New Item
Understanding	autopilot-understand	New Item/Backlog（EPIC）
Decomposing	autopilot-decompose	Backlog（EPIC→sub-issue+size）
Implementing	autopilot-implement	In Progress
Creating PR	autopilot-implement	In Progress
Self-Reviewing	autopilot-review（敵対的）	In Progress
Addressing Comments	autopilot-address-review	Review（HITL=No で差し戻し時）
Running DoD	autopilot-verify（Playwright）	DoD

HITL（Yes/No）= 人間の出番トグル

• In Progress で自律作業 → 敵対的レビュー完了で Status=Review, HITL=Yes
• 人間が approve → Status=DoD / PR にコメント + HITL=No → Claude が Addressing Comments → 完了で再び HITL=Yes
• DoD（Playwright）完了 → HITL=Yes → 人間が merge/release → Status=Close（自動）
• 人間は普段 Status ボードを見て、自分の出番は「HITL=Yes」のビューだけ確認すればよい

その他フィールド

Size(small/middle/large) / Kind(EPIC/Issue) / Current Step(text) / Worktree(text) / Tmux Window(text, observability)

dogfooding

この EPIC #760 自身を Project に載せ、現在 Status=In Progress / Kind=EPIC / AI Status=Decomposing / HITL=Yes（協働設計中なので人間の番）に設定した。autopilot が完成したら、この item を最初の実ワークロードとして自走させる。

[smalruby3-editor-bot]

決定: EPIC のステータス運用

EPIC は「作業項目」ではなく「トラッカー」として扱う。新ステータスは増やさず、
既存 Scrum Status + Kind + AI Status + Sub-issues progress で表現する。

原則 1: EPIC の Status は子 sub-issue の集約を表す

• daemon は leaf（Kind=Issue）だけを Sprint Backlog から拾う。EPIC は分解後キューに入れない。
• EPIC の AI Status は Understanding / Decomposing の間だけ能動。分解完了で
  EPIC Decomposed を設定し、「親トラッカー化＝分解作業は完了、以後は子で進む」を明示する
  （← 本決定で AI Status に新オプション EPIC Decomposed を追加）。
• 進捗は標準フィールド Sub-issues progress のバーで見る（件数を手で数えない）。

原則 2: EPIC の Status 意味（leaf と別セマンティクス）

Status	EPIC にとっての意味
Backlog	EPIC 受理・未分解
In Progress	分解済みで子のどれかを能動的に追っている間
Icebox	一時停止・パーク（「いくつかの sub-issue で十分、今は止める」）
Done	やると決めた子がすべて閉じた

Kind=EPIC でフィルタした EPICs ビュー（Status グルーピング + Sub-issues progress 列）で
「進行中/停止中/完了」を一目で把握する。

原則 3: 「もう十分」のときは EPIC を分割して納品ぶんを Done に

完了した子 → Done（既に閉じている）
残りの未着手 子:
  ├─ 後でやる    → フォローアップEPIC（◯◯の残り）に re-parent → Backlog/Icebox
  └─ もうやらない → won't-do で close（Icebox）
元の EPIC → Done（実際に届けたスライスを表す）

半分終わった EPIC を滞留させない。繰り越し分は新 EPIC として明示する。

原則 4: EPIC を Done にする遷移は HITL

autopilot は未クローズの子を持つ EPIC を勝手に Done/close しない。「もう十分か」は人間判断
なので HITL=Yes + コメントで尋ねる（原則3の分割指示もここで人間が行う）。

ビュー構成

• EPICs ビュー（Kind=EPIC）: 人間が EPIC の集約を見る
• Issues ビュー（Kind=Issue）: autopilot が leaf を回す

本決定は README（docs/autopilot/README.md）整備時に本文へ反映する。現時点では本コメントを
正とする。