issue-implement の実装隔離を必須化し worktree 対応を最新 runtime に合わせる

[hirokisakabe]

Status: Ready

概要

issue-implement の実装開始前に、default branch を直接変更しないことと、並列実装時に専用 worktree へ隔離されていることを保証する。
あわせて worktree-start・README・AGENTS.md の runtime 別説明を、現在の Codex / Claude Code 公式仕様に合わせて更新する。

背景 / モチベーション

• 現在の issue-implement は Claude Code 以外では worktree 作成を skip して実装へ進むため、Codex CLI を default branch 上で起動した場合に main / master を直接変更し得る。
• 「ユーザーが事前に worktree / branch を切っている」という前提を記載しているが、実際にはその状態を必須条件として検証していない。
• Codex は現在、CLI・IDE・App で subagent workflow を利用できるが、書き込みを伴う並列 agent は作業ディレクトリを分離しなければ競合する。
• Claude Code は初期導入時の EnterWorktree に加え、claude --worktree、subagent の isolation: worktree、Agent view の自動 worktree 隔離、Desktop の session worktree を提供している。
• 現行 worktree-start の「既存 worktree からの再進入を拒否する」等の説明には、現在の公式仕様と一致しない一般化がある。
• 複数 issue の並列実装を追加する前に、単一 issue-implement の隔離契約を明確にする必要がある。

受け入れ条件

• issue-implement が default branch 上で実装を開始する場合、専用 worktree へ移るか、runtime が安全に移行できなければ実装・commit 前に停止する
• Codex CLI で default branch 上にいる場合、worktree 作成を単に skip して実装へ進まず、通常の git worktree と codex -C <path> を使った再開方法を案内する
• Codex App では managed worktree / Handoff を runtime 所有の機能として扱い、skill が App 管理 worktree を作成できるかのような記述をしない
• Claude Code では claude --worktree、EnterWorktree、subagent の isolation: worktree、Agent view の自動隔離、Desktop session の worktree 対応が runtime 別に整理されている
• すでに専用 worktree 内にいる場合、二重作成せずその worktree で続行する
• default branch 以外の既存 feature branch にいる単独実装では、ユーザーの branch を上書きしない既存方針が維持される
• 並列 worker として呼び出された場合は「1 worker = 1 worktree」を必須とし、同一 worktree を共有して実装しないことが明記されている
• EnterWorktree の現在の切り替え・再開・cleanup 仕様を公式ドキュメントで再確認し、古くなった断定が worktree-start から修正されている
• .worktreeinclude が必要になるケースと、依存関係・環境初期化・disk 使用量に関する注意が README または該当 skill に記載されている
• README と AGENTS.md の Codex / Claude Code worktree 説明、および skill graph が更新後の挙動と一致している
• 変更した SKILL.md の frontmatter version: だけが semver に従って bump されている

スコープ外

• 複数 issue を選定・dispatch する上位 orchestrator の追加
• Codex App の UI を skill から操作して新規 chat / managed worktree を作成する機能
• 外部ターミナルのタブ・ペインを自動作成する機能
• PR の自動 merge
• worktree に残ったユーザー変更を破棄する自動 cleanup
• 既存 feature branch 上の単独セッションを無条件に別 worktree へ移すこと

実装方針

1. issue-implement の step 4 を「Claude Code なら任意に作成」ではなく「実装隔離の preflight」として再定義する。
2. runtime と現在位置を 専用 worktree / feature branch / default branch に分類し、続行・切り替え・停止を明示する。
3. Claude Code では native worktree 機能を利用し、Codex App では App 所有の managed worktree / Handoff を案内する。
4. Codex CLI では起動済み session の cwd を skill が安全に移せると仮定せず、default branch 上なら実装前に停止して git worktree + codex -C の再開手順を返す。
5. worktree-start の no-op 方針自体は issuekit の安全策として維持してよいが、Claude Code primitive 自体の制約であるかのような古い説明は分離・修正する。

参考

• cwt 代替の worktree 起動 skill を issuekit に追加 #13
• feat(issue-implement): 冒頭で worktree-start を条件付き自動発火 #18
• Codex Subagents
• Codex Worktrees
• Codex CLI reference
• Claude Code: Run parallel sessions with worktrees
• Claude Code: Run agents in parallel
• Claude Code: Agent view