haboshi Orca Spinoff
本流の作業中に見つけた課題を、チケットに残しつつ別 worktree の新セッションへ手渡す。手渡し方は2モード:
- フルハンドオフ(既定): 起動して報告したら手離れ。進捗はカードとチケットで人が見る。
- 監督モード(opt-in): 親セッションが完遂まで監視し、子からの質問に応答し、検収・撤収・キャッチアップ報告まで閉じる。
コマンドの詳細規約(セレクタ構文・エラーリカバリ)は orca-cli スキル、orchestration コマンドの詳細規約(メッセージ種別・待機ルール)は orchestration スキルに従う。Linux では orca を orca-ide に読み替える。
0. 前提確認
command -v orca || command -v orca-ide
orca status --json
- CLI が無ければ「orca CLI が見つからない」と明言して止まる。ソース探索や代替実装をしない。
- Orca 未起動なら
orca open --json→orca status --jsonで再確認。 orca worktree current --jsonで現在の worktree を確認する(repo 推論と報告に使う)。
1. モード選択
既定はフルハンドオフ。監督モードは、ユーザーが完遂までの監視・応答・取り込みを明示したときだけ選ぶ(例:「監視して」「完遂まで見て」「終わったらマージして続けて」「終わり次第取り込んで」)。明示が無ければ質問せずフルハンドオフにする(スピンオフはワンアクションであることが価値)。
| フルハンドオフ | 監督モード | |
|---|---|---|
| 向く課題 | 本流と独立・急がない | 本流が完了に依存・すぐ検収まで必要 |
| 親のコスト | ゼロ(手離れ) | 待機ターン+セッション拘束 |
| 完了検知・検収 | 人がカード/チケットで判断 | 親が worker_done 受領 → 検収 → 撤収 |
監督モードを選んだら、orchestration が使えることを先に確認する:
orca orchestration task-list --json
失敗したら(experimental 未有効等)その旨を報告し、フルハンドオフに縮退する(勝手に Settings を変更しない)。
2. 課題の言語化
会話文脈から次の3点を抽出する。揃わない要素があるときだけ AskUserQuestion で 1 問だけ 確認する(スピンオフはワンアクションであることが価値。質問を重ねない):
- 何が起きたか / 何を見つけたか(1〜3文)
- 該当ファイル・再現手順(分かる範囲で。パスは repo 相対)
- 完了定義(何をもって解決とするか。1〜2行)
設計凍結チェック: 解決アプローチに複数案があり選定が済んでいない、またはユーザー決裁が絡む見込みがあるなら、実装をスピンオフしない。チケットに「実装方針は判断待ち。着手ブロック」と明記して起票のみ行うか、スピンオフのブリーフを「判断材料の整理まで」に限定する(設計が揺れたまま実装を渡すと、方針転換で成果物が丸ごと破棄になる)。
3. チケット起票(承認必須)
起票先の決定順:
- ユーザーが明示した先
- プロジェクトの CLAUDE.md / docs に記載の課題管理先(Backlog プロジェクトキー等)
gh repo view --json nameWithOwnerが通れば GitHub Issues- それでも不明なら AskUserQuestion で確認
投稿前に AskUserQuestion でタイトル・本文の承認を得る(外向き操作)。本文には課題の言語化3点をそのまま書く。
- GitHub:
gh issue create --title "<title>" --body "<body>" - Backlog:
backlog-apiスキルに委譲(そのスキルの投稿前確認フローに従う)
起票に失敗したらスピンオフを中止して報告する。チケット無しで worktree 起動に進むのは、ユーザーが「チケットは要らない」と明示したときだけ。
4. ブリーフ作成
スピンオフ先エージェントへの初期プロンプトを組む。含めるもの:
[課題] <1〜3文の要約> (チケット: <URL または キー>)
[再現/該当箇所] <ファイル・手順>
[完了定義] <解決条件>
[文脈] <現ブランチ由来の情報が必要なら文章で渡す。worktree は repo 既定 base から切られる>
[報告規約] 着手時・PR 作成時・完了時・ブロック時はチケットにコメントする(進捗の観測点はチケット。
worktree comment は補助)。方針に迷ったら実装せずチケットに質問を書く
[品質ゲート] <プロジェクトの完了定義(typecheck/lint/build 等)> + PR 前に /code-review で自己レビュー
し CRITICAL/HIGH を修正(--fix 適用可)。視覚変更はスクショ実証を PR に添付
[完了時] チケットを更新し、PR を作る場合はチケットにリンクする
エージェント別の読み替え: /code-review・/evaluator-gate・/evaluate は Claude Code のコマンド。--agent が claude 以外(codex 等)のときはブリーフに書かず、「PR 前に差分を自己レビューし CRITICAL/HIGH 相当を修正する」等の同等指示に読み替える。
evaluator-gate は worktree に継承されない: ゲートの有効判定は worktree 自身の絶対パス×config 照合
(git rev-parse --show-toplevel)のため、親リポジトリで有効でもスピンオフ先では素通りになる。
実装スピンオフでゲートを効かせたい場合はブリーフに「着手前に /evaluator-gate on でこの worktree を
登録」を含める(過去に worktree 単位で個別登録した運用実績あり)。軽微な課題では省略可(毎 Stop の
外部評価はコストがかかる)。advisory の外部所見が欲しいだけなら完了前の /evaluate 一発で足りる。
真実源はチケット側に置く: 設計・受け入れ基準など長い内容はチケット本文に書き、ブリーフには要約+チケット参照を渡す。ブリーフに全文を複製しない(後述の方針変更時に古い指示が残る)。
監督モードの読み替え: ブリーフは --prompt でなく task-create --spec に渡す(§5)。dispatch --inject が worker_done / ask の報告規約を preamble として自動注入するため、[報告規約] の「方針に迷ったらチケットに質問」は「ask で親に質問(チケットにも要点を残す)」に読み替える。チケットコメント(着手時・PR 作成時・完了時)は人間の観測点としてそのまま維持する。
5. worktree 起動
二重スピンオフ検知(両モード共通): orca worktree ps --json で同じ課題・同名の worktree が既に無いか確認する。あれば起動せず、その worktree を報告する。
フルハンドオフの起動
orca worktree create --name <slug> --parent-worktree active --agent <agent> --prompt "<ブリーフ>" --json
--parent-worktree activeは Orca のカード階層(lineage)の紐づけのみで、Git base には影響しない。スピンオフは現作業から派生した課題なので、カード上は子として見せる。ユーザーが「独立した作業として」と明示したときだけ--no-parentにする。フルハンドオフ方針(lifecycle 監視をしない)は lineage とは無関係に維持する。--base-branchは渡さない(repo 既定 base を使う)。現在のブランチを base にするのは、ユーザーが stacked 作業を明示したときだけ。<slug>はチケットキー/番号を含む短い英数字(例:fix-123-login-css)。<agent>はユーザー指定 > そのプロジェクトの直近の慣行 >claude。- 旧 CLI が
--agent/--promptを拒否した場合のフォールバック:worktree create→orca terminal create --worktree id:<id> --command "<agent>" --json→orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json→orca terminal send --terminal <handle> --text "<ブリーフのポインタ 1 行(チケット参照 + 一意トークン)>" --enter --json→orca terminal read --screenでトークンの出現を確認(ブリーフ全文は send に載せない。§7 の送達契約)
監督モードの起動
--prompt でブリーフを渡す代わりに task を作って dispatch する(worker_done / ask を返せる preamble が注入される)。--parent-worktree / --base-branch / <slug> / <agent> の規約はフルハンドオフと同じ:
# ブリーフは一時ファイルに書いてから渡す(本文中のバッククォート・$() がシェル評価される事故の予防。2026-08-27 実測: `permission denied: lib/...`)
orca orchestration task-create --spec "$(cat <brief-file>)" --json
orca worktree create --name <slug> --parent-worktree active --agent <agent> --json
orca terminal list --worktree id:<newId> --json # エージェントの terminal handle を取る
orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json
orca orchestration dispatch --task <task_id> --to <handle> --inject --json
パーミッションモードを都度注入する場合は次節の「都度」経路に従う(最後のブリーフ注入だけ terminal send でなく dispatch --inject になる)。
パーミッションモード(Claude スピンオフ時)
スピンオフ先は無人セッションのため、default/manual のままだと最初の許可プロンプトで停止する(誰もそのターミナルを見ていないと待ち続ける)。Claude を起動する場合は --permission-mode auto を推奨する(確認済み: claude --help の choices に存在、claude auto-mode defaults の分類器は「読み取り・プロジェクト内ローカル操作・宣言済み依存・origin への push 等を allow / 破壊的操作・本番・secret・認証情報漏洩・レビューなしマージ等を soft_deny / データ持ち出しを hard_deny」)。acceptEdits は bash で結局止まり、bypassPermissions は安全弁を全部外すため、無人用途では auto が最適。このフラグは Claude Code 専用で、--agent codex 等には付けない。
これは監督モードでも同じ(ツール許可プロンプトは orchestration メッセージに乗らず TUI 側で止まるため、監視していても応答できない)。
注入経路(--agent プリセットはその場限りのフラグを受けないため、いずれか):
- 恒久(推奨): Orca の Settings → Agents で起動コマンドが
claude --permission-mode autoのカスタムエージェントを定義し、--agent <そのID>を使う。上の 1 行起動フローをそのまま保てる。 - 都度:
--agentを付けずにorca worktree create --name <slug> --parent-worktree active --json→orca terminal create --worktree id:<newId> --command "claude --permission-mode auto" --json→orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 60000 --json→ ブリーフ注入(フルハンドオフはterminal send、監督モードはdispatch --inject)。
これは worktree に継承されない settings.local.json の許可蓄積を補う意味もある(スピンオフ先は蓄積済み許可を持たないため、モードで姿勢を与える)。ユーザーが姿勢を明示したらそれに従う。
6. カード設定(best-effort)
worktree create の応答から id を取り:
orca worktree set --worktree id:<newId> --comment "spun off: <チケット参照>" --workspace-status in-progress --json
失敗してもスピンオフ自体は成立している。警告として報告に含めるだけでよい。
7. フルハンドオフ: 報告して本流へ復帰
1 ブロックで報告し、元の作業に戻る:
- チケット: URL / キー
- worktree: 名前と id
- 様子を見る:
orca worktree ps --json/orca terminal read --terminal <handle> --json
以後、元セッションはこの課題の lifecycle を監視しない(フルハンドオフ)。完了検知・検収はカードとチケットの更新で人が判断する。
追加指示・方針変更の作法
スピンオフ後に方針が変わったら、先にチケット本文を更新し、send では要旨と再読指示だけを送る:
orca terminal send --terminal <handle> --text "【方針更新】<変更の要旨1〜2文>。チケット <キー> の最新本文を再読してから続行。着手済みの旧方針差分は破棄すること" --enter --json
send に変更内容の全文を書かない(チケットとの二重管理になり、古い指示が残って事故る)。
処理中に送った入力は消失する(2026-09-02 実測。旧記述「処理中でもキューされる」は誤りだった)。送る前に orca terminal wait --terminal <handle> --for tui-idle --timeout-ms 600000 --json で idle を待ち、送った後は orca terminal read --terminal <handle> --screen --json で要旨の一部が画面に出たことを確認する。ok:true は到達の証明ではない(idle 受信でも先頭が欠落して末尾 1 文だけ届き、worker が逆の方針を実装した実例あり)。届いていなければ 1 回だけ再送し、それでも届かなければ人に報告する。
8. 監督モード: 監視と完遂
dispatch 後、ローリング待機で子からのメッセージを受ける:
orca orchestration check --ack <直前に受けた delivery_id> --wait --types worker_done,escalation,decision_gate,ask --timeout-ms 540000 --json
--ackを省略しない(2026-09-02)。check は最古の未 ack Delivery を replay し続けるため、heartbeat を ack しないと後ろに並んだ子のask/worker_doneが永久に見えない(実測: 同一 delivery を 3 回 replay、子の ask 900s は親が AskUserQuestion で待つ間に失効し、子は仮定で実装した)。AskUserQuestion に入る前に必ず 1 回check --ackを回す。- タイムアウトや
{count:0}はチェックポイントであって失敗ではない。terminal read/task-listで生存確認し、待機を続ける(コーディング課題は 15〜60 分が普通。heartbeat や画面の動きは「生きている」であって「完了」ではない。止めない・再起動しない)。 - 待機は
run_in_backgroundで回してよい。その間に本流作業を進めて構わないが、スピンオフ先と同一ファイルは編集しない。 - decision_gate / ask への応答: チケットに書いた完了定義の範囲内の技術判断は親が即
replyする。設計変更・スコープ変更・破壊的/外向き操作に踏み込む判断は AskUserQuestion でユーザーに確認してから返す。 - escalation: 内容を確認し、親で解決できるものは対処して返答、できないものはユーザーへ。
- 途中の方針変更は §7 の「追加指示・方針変更の作法」と同じ(チケット先更新 → send で要旨)。
worker_done 受領 → 検収
自己申告を信用せず、現物で確認する:
orca worktree show --worktree id:<id> --json # 応答の path を <worktreePath> に使う
git -C <worktreePath> log --oneline origin/<base>..HEAD # 差分の実在
git -C <worktreePath> status --porcelain # 未コミットの残り
gh pr view <n> # PR を作らせた場合は実在確認
あわせてチケットの完了コメントと、ブリーフで課した品質ゲートの証跡を確認する。
- 検収 OK:
orca orchestration task-update --id <task_id> --status completed --json→ §9 撤収へ。 - 取り込みを明示されていた場合(「終わったらマージして続けて」「終わり次第取り込んで」等): 検収 OK 後・撤収前に PR のマージまたは base への取り込みを行う。マージは外向き操作のため、対象 PR の実在と CI 状態を確認したうえで AskUserQuestion で最終承認を得てから実行する(スピンオフ時の包括指示だけで無承認マージしない)。
- 検収 NG: チケットに差し戻し理由を書いてから、同一 task を再 dispatch する:
orca orchestration dispatch --task <task_id> --to <handle> --inject --json。worker_done は dispatch 1 回につき 1 度きりのため、send の差し戻しでは次の完了通知が来ない — 再 dispatch で preamble が再注入され完了検知が再び成立する。その後待機に戻る。差し戻しは 2 回まで。それでも NG なら AskUserQuestion でユーザーに判断を仰ぐ(親が引き取る / 続行 / 中止)。
異常系
- 同一 task で 3 連続 dispatch 失敗すると circuit-break で task が failed になる → 状況をまとめてユーザーに報告する。
- terminal が exit・消滅した →
terminal list/worktree psで確認し、成果物の状態(git 差分)を添えてユーザーに報告する。勝手に再起動して同じブリーフを再投入しない(二重実装の温床)。
キャッチアップ報告
撤収まで終えたら 1 ブロックで報告する: 達成内容(完了定義に対して)/ コミット・PR / チケット最終状態 / 残課題・申し送り。
9. 撤収(検収後の後片付け)
監督モードでは検収 OK の直後に親がここまで実施する。フルハンドオフでは、チケットが解決・検収済みになったことを人が確認してから実施する:
# 0. worktreePath を取得
orca worktree show --worktree id:<id> --json # 応答の path を <worktreePath> に使う
# 1. そのworktreeのブランチに未コミット・未pushが無いことを確認(必須)
git -C <worktreePath> status --porcelain
git -C <worktreePath> log --oneline @{u}..HEAD 2>/dev/null # upstream 無しなら origin/<base>..HEAD
# 2. 完了マークして削除
orca worktree set --worktree id:<id> --workspace-status completed --json
orca terminal stop --worktree id:<id> --json
orca worktree rm --worktree id:<id> --force --json
- 未 push の確認はそのworktreeのブランチに限定する。
git log --branches --not --remotesはリポジトリ全体を見るため、他の worktree で進行中の作業まで拾って混同する(現在チェックアウト中のブランチ + upstream 比較で判定する)。 - 未 push コミットが見つかったら削除を中止してユーザーに報告する。
やらないこと
- (既定のフルハンドオフ時)
orca orchestration dispatch --inject/worker_doneの待ち受け。監督モードはユーザーが明示 opt-in したときだけ(§1)。 - チケットのクローズ — スピンオフ先セッションの責務(監督モードでも親は検収・撤収まで。クローズされたかの確認はする)。
- 複数課題の計画分解・並列ディスパッチ — 監督モードは単一スピンオフの監督のみ。DAG・並列・複数 worker の束ねは
orchestrationスキルをそのまま使う。