yoi/.insomnia/workflow/worktree-workflow.md

description	model_invokation	user_invocable	requires
insomnia プロジェクトで child git worktree を作成・管理するための機械的手順。実装 Pod に作らせず、親 Pod が main workspace で実行する。	false	true

Worktree Workflow

insomnia プロジェクトで実装差分を main workspace から分離するため、./.worktree/<task-name> に child git worktree を作る。これは worktree の扱い方だけ を定める Workflow であり、ticket 選定、実装委譲、review、merge の運用は $user/multi-agent-workflow 側で扱う。

insomnia では Pod の write scope が排他的に委譲されるため、child worktree に .insomnia を置かない。main workspace は orchestration / ticket / docs / memory / workflow 管理の場所として残し、child worktree はコード差分専用の作業面として扱う。

適用範囲

この Workflow は親 Pod / orchestrator が main workspace で実行する。

• 実装 Pod にこの Workflow を渡して worktree を作らせない。
• 実装 Pod は、親 Pod が作成済みの child worktree を受け取り、その中で実装・build・test・報告を行う。
• ticket 作成、TODO 更新、review artifact、docs/report は main workspace 側で扱う。

原則

• 1 ticket / 1 実装 task につき 1 worktree を作る。
• worktree path は ./.worktree/<task-name>。
• branch 名は原則 <task-name> と同じ kebab-case。
• child worktree には .insomnia を出さない。
• child worktree は実装差分用。TODO.md / tickets/ / docs/report/ / workflow / memory は原則 main workspace 側で扱う。
• push はしない。

事前確認

作成前に以下を確認する。

1. 対象 ticket / task が決まっているか。
2. <task-name> が branch / path 名に使える kebab-case か。
3. git worktree add を実行してよい許可があるか。
4. main workspace に混ぜてはいけない未保存差分がないか。
5. 同名 branch / worktree が既に存在しないか。

同名 branch がある場合は、既存 branch を使うか、人間に確認する。git worktree add -b で上書きしない。

作成手順

main workspace で実行する。

git worktree add .worktree/<task-name> -b <task-name>

git -C .worktree/<task-name> sparse-checkout init --no-cone
git -C .worktree/<task-name> sparse-checkout set --no-cone \
  '/*' \
  '!/.insomnia/' \
  '!/.insomnia/**'

確認する。

git -C .worktree/<task-name> status --short --branch
test ! -e .worktree/<task-name>/.insomnia

失敗した場合は、worktree / branch / lock の状態を確認し、勝手に cleanup せず人間へ報告する。

子 Pod へ渡す scope

子 Pod を使う場合、子 Pod の cwd は main workspace のままになる。必ず作業対象が child worktree であることを明示し、Bash 実行時は毎回 cd /home/hare/Projects/insomnia/.worktree/<task-name> && ... させる。

推奨 scope:

read:  /home/hare/Projects/insomnia
write: /home/hare/Projects/insomnia/.worktree/<task-name>

より狭く切れる場合は、write scope を変更対象 crate / directory まで狭めてよい。ただし build / test に必要な生成物を書けることを確認する。

child worktree 内の禁止事項

• .insomnia を作らない / コピーしない。
• main workspace の TODO.md / tickets/ / docs/report/ を編集しない。
• merge / push / branch deletion / worktree remove をしない。
• scope / permission / history persistence / prompt context 加工原則に関わる設計変更を無断で行わない。

完了時の扱い

worktree 作成 Workflow としては、完了時に merge しない。merge、ticket 完了、TODO 削除は $user/multi-agent-workflow または人間の明示指示で行う。

実装 Pod へ渡す完了報告項目の標準形:

• worktree path
• branch 名
• commit hash（実装 Pod に commit を許可した場合）
• 変更ファイル
• 実装概要
• 実行した build / test / format
• 未解決事項
• review に回せるか