rename: adopt yoi identity

2026-06-01 18:49:23 +09:00
parent 6e133a7229
commit e6c458021c
115 changed files with 945 additions and 732 deletions
@@ -0,0 +1,148 @@
+---
+description: TODO / tickets / docs / git history から次の作業候補を見繕い、課題発見や方針決定を半自動でイテレーションする WIP maintainer workflow
+model_invokation: false
+user_invocable: true
+requires: []
+---
+# Auto Maintain Workflow (WIP)
+
+insomnia を AI maintainer として運用するための半自動 loop。TODO / tickets から「今進められそうな作業」を選ぶだけでなく、課題の発見、設計判断の切り分け、次に人間へ戻すべき問いの整理までを扱う。
+
+これは unattended 自動開発ではない。実装の並列委譲は `multi-agent-workflow`、worktree の機械的作成は `worktree-workflow` に任せる。本 Workflow はその前段として、何を進めるべきか、何をまだ決めるべきか、下位 orchestrator にどの intent packet を渡すべきかを整理する。
+
+参照:
+
+- `docs/plan/ai-maintainer.md`
+- `tickets/auto-maintain-workflow.md`
+
+## 位置づけ
+
+AI maintainer の目的は、コードを書くこと自体ではなく、プロジェクト状態を前に進めることである。
+
+この Workflow は WIP として、以下を行う。
+
+- TODO / tickets / docs / git history を読んで現在地を把握する。
+- 実装可能な ticket と、方針決定が必要な ticket を分ける。
+- 小さく実装できる候補を提案する。
+- 複数 ticket からなる作業群は、下位 orchestrator に任せる単位として整理する。
+- 設計相談が必要な論点を人間に戻す。
+- 運用上の問題や繰り返し発生する詰まりを report / ticket / workflow 改訂候補として整理する。
+
+## 非目標
+
+現時点では以下をしない。
+
+- 常駐 scheduler として自動実行する。
+- 人間の合意なしに新規 ticket を作る。
+- 人間の合意なしに既存 ticket を大幅変更する。
+- 人間の合意なしに ticket 完了削除を行う。
+- push する。
+- Workflow を自律生成・自律改訂する。
+- scope / permission / history persistence / prompt context 加工原則に関わる判断を勝手に決める。
+
+## 入力として読むもの
+
+必要に応じて以下を読む。
+
+1. `TODO.md`
+2. `tickets/*.md`
+3. `docs/plan/`
+4. `docs/report/`
+5. `git log --oneline` / ticket file の git history
+6. 既存 worktree / branch 状態
+7. 最近の失敗や通知、ユーザーからの観測
+
+TODO と ticket の不整合を見つけたら、勝手に修正せず、まず報告する。ただしユーザーが明示的に「直して」と言った場合は Mode 1 として整理してよい。
+
+## 分類
+
+候補を以下に分ける。
+
+### A. 実装委譲可能
+
+- 要件と完了条件が具体的。
+- 影響範囲が限定的。
+- test / build で確認できる。
+- 大きな設計判断が不要。
+- scope を狭く切れる。
+
+この場合は、人間に候補として提示する。人間が実行を許可したら `$user/multi-agent-workflow` に進む。複数 ticket や連続した作業群では、最上位 Pod が直接 coder を抱えず、下位 orchestrator に intent packet を渡して coder / reviewer sibling loop を管理させる。
+
+### B. 方針決定が必要
+
+- 複数の設計方針が自然に導ける。
+- protocol / permission / scope / persistence / prompt context に触れる。
+- UX の仕様が未確定。
+- 既存 ticket の要件が古い。
+
+この場合は、実装せず、決めるべき問いを短く提示する。
+
+### C. ticket 整理が必要
+
+- TODO にあるが ticket がない。
+- ticket があるが TODO にない。
+- 完了済みに見えるが残っている。
+- ticket の前提が変わっている。
+
+この場合は、不整合と修正案を提示する。修正は人間の許可後に行う。
+
+### D. report / workflow 改善候補
+
+- 同じ tool 問題が繰り返し出る。
+- Workflow の指示が曖昧で実装 Pod が迷った。
+- coder / reviewer / orchestrator の責務が混ざり、親 Pod が細かい code review に戻ってしまった。
+- AI が過剰に Task tool を使うなど、運用上の癖が出た。
+- 通知や Pod completion tracking など、開発基盤の不足が観測された。
+
+この場合は、すぐ ticket 化するか、`docs/report/` に観測として残すか、人間に確認する。
+
+## 半自動 iteration
+
+1. 状態把握
+   - TODO / tickets / git status を読む。
+   - 最近完了した流れや未完了 branch を確認する。
+
+2. 候補抽出
+   - 実装可能そうな ticket を 2〜5 件挙げる。
+   - correctness / developer experience / user-visible UX / cleanup で分類する。
+
+3. 推奨順位
+   - blocking correctness を最優先。
+   - 実害が出ている運用問題を次点。
+   - 小さく完了できる UX / cleanup を次点。
+   - 大きな設計変更は方針相談に回す。
+
+4. 人間への提示
+   - 「次に進めるなら X」を1つ推奨する。
+   - 理由を短く述べる。
+   - 実装委譲する場合の scope / test 方針を添える。
+   - 複数 ticket の作業群なら、下位 orchestrator に任せる単位として提示する。
+
+5. 実行への接続
+   - 人間が「進めて」と言ったら `$user/multi-agent-workflow` に接続する。
+   - 単発 ticket か、下位 orchestrator に任せる ticket 群かを明示する。
+   - 下位 orchestrator に渡す intent / requirements / invariants / non-goals / escalation 条件を短くまとめる。
+   - worktree 作成は `$user/worktree-workflow` に従う。
+
+## エスカレーション基準
+
+以下では実装に進まず、人間へ戻す。
+
+- ticket の要件から複数の設計方針が自然に導ける。
+- 長期構造、crate boundary、protocol、permission、scope、history persistence に触れる。
+- prompt context 加工原則に関わる。
+- 新 ticket の作成、既存 ticket の大幅変更、ticket 完了削除について合意がない。
+- test 不能、再現不能、または作業範囲外の不具合に遭遇した。
+- WorkItem / Thread / Lease / maintainer state など、まだ設計中の概念が必要になる。
+- 下位 orchestrator に委譲するには intent / invariant / escalation 条件が曖昧すぎる。
+
+## まだ固定しないもの
+
+以下は `docs/plan/ai-maintainer.md` の上位設計に残し、本 Workflow では詳細を固定しない。
+
+- WorkItemStore / LeaseStore。
+- operation inbox / trial log。
+- QA feedback を ticket / review / report のどれに落とすか。
+- AI 自身の feedback を Knowledge / report / ticket / workflow 改訂のどれにするか。
+- maintainer doctor。
+- reviewer Pod の評価基準の機械化。
@@ -0,0 +1,306 @@
+---
+description: worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が複数 ticket の実装・外部レビュー・修正・完了準備を管理する orchestration フロー
+model_invokation: true
+user_invocable: true
+requires: []
+---
+# Multi-agent Worktree Workflow
+
+insomnia を insomnia で開発する際の、worktree + coder Pod + 外部 reviewer Pod + orchestrator Pod の標準フロー。これは **最上位 Pod が細かい code review を抱えず、下位 orchestrator が実装と外部レビューの loop を完了状態まで運ぶためのフロー** である。
+
+worktree の機械的作成手順は `$user/worktree-workflow`、実装前の要件同期・反証 preflight は `$user/ticket-preflight-workflow`、ticket 候補選定や方針探索の半自動 loop は `$user/auto-maintain` に分ける。
+
+この Workflow は、対象 ticket が implementation-ready であることを前提にする。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に `ticket-preflight-workflow` を通す。
+
+## 目的
+
+- 実装差分を ticket ごとの child worktree に隔離する。
+- coder Pod に narrow write scope を渡して実装させる。
+- reviewer Pod を coder の子ではなく **同じ orchestrator 配下の sibling** として立て、外部レビューを行わせる。
+- orchestrator は coder / reviewer のやり取り、修正 loop、validation、merge-ready dossier 作成に責任を持つ。
+- 最上位 orchestrator は、コードを直接理解し切ることではなく、委譲した intent / 要件 / invariant に沿って下位 orchestrator が完了まで運んだかを acceptance する。
+
+## 階層モデル
+
+基本形は以下。
+
+```text
+最上位 orchestrator Pod
+  - 人間との会話相手
+  - intent / 要件 / invariant / escalation 条件を定義
+  - 複数の作業群を並列管理
+  - final merge / ticket close / main workspace validation を行う
+  - 原則として line-by-line code review を主業務にしない
+
+下位 orchestrator Pod（area / epic / ticket-group coordinator）
+  - 連続した複数 ticket または大きめの ticket 群を完了状態まで運ぶ
+  - worktree / branch / coder / reviewer / validation / 修正 loop を管理する
+  - coder と reviewer を sibling として扱う
+  - 親には merge-ready dossier と残論点だけを返す
+
+coder Pod
+  - 指定 worktree / branch に実装する
+  - ticket 外判断や設計衝突は orchestrator に戻す
+  - reviewer に直接反論・修正依頼を完結させず、orchestrator に報告する
+
+reviewer Pod
+  - 原則 read-only
+  - ticket / intent packet / diff / validation 結果を読む
+  - 実際のコード変更が概念的に何を変えたかを説明する
+  - intent / 要件 / invariant に反する blocker を分類して返す
+```
+
+一段だけで足りる小さい ticket では、最上位 orchestrator が直接 coder / reviewer sibling を扱ってよい。複数 ticket や設計境界をまたぐ作業では、最上位の下に下位 orchestrator を挟む。
+
+## 開始条件
+
+以下が揃っている時に使う。
+
+- 対象 ticket または ticket 群が決まっている。
+- ticket の背景・要件・完了条件から実装方針が概ね導ける。
+- worktree 作成と git 書き込み操作について、人間の許可がある。
+- main workspace の unrelated dirty changes を把握している。
+- 下位 orchestrator に渡す intent / invariant / non-goals / escalation 条件を短く書ける。
+- 設計境界・仕様・authority boundary に不確定要素がある場合、`ticket-preflight-workflow` の結果が ticket thread に記録されている。
+
+設計方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に `ticket-preflight-workflow` を通し、必要なら人間へ戻す。ただし下位 orchestrator に探索だけを委譲することはできる。
+
+## Intent packet
+
+階層化すると人間の意図が劣化しやすい。下位 orchestrator や coder / reviewer へは、自然文の依頼だけでなく intent packet を渡す。
+
+標準形:
+
+```text
+Intent:
+- 何を実現するか。
+
+Requirements:
+- 完了時に満たすべき observable な要件。
+
+Invariants:
+- 壊してはいけない設計境界。
+- 残してはいけない旧概念や互換層。
+
+Non-goals:
+- 今回やらないこと。
+
+Escalate if:
+- 親へ戻すべき判断条件。
+
+Validation:
+- 実行すべき format / build / test / doctor。
+```
+
+reviewer には coder の実装方針ではなく、この intent packet と diff を中心に読ませる。
+
+## orchestrator の責務
+
+下位 orchestrator を挟まない場合は、以下を最上位 orchestrator が行う。下位 orchestrator を挟む場合は、最上位は intent packet を渡し、以下の実務を下位に委譲する。
+
+1. 状態確認
+   - `git status --short --branch`
+   - 対象 ticket / ticket 群
+   - 関連 TODO / docs / 既存 worktree
+   - preflight が必要な ticket では、`ticket-preflight-workflow` の分類・要件同期・critical risks
+
+2. worktree 作成
+   - `$user/worktree-workflow` に従い `./.worktree/<task-name>` を作る。
+   - `.insomnia` を sparse checkout で除外する。
+
+3. coder Pod spawn
+   - read scope: main workspace 全体。
+   - write scope: child worktree、または必要最小 directory。
+   - task には以下を明示する。
+     - child worktree path / branch
+     - 対象 ticket path
+     - intent packet
+     - Bash は必ず child worktree に `cd` すること
+     - main workspace の `TODO.md` / `tickets/` / `docs/report/` / `.insomnia` は編集しないこと
+     - 範囲外事項
+     - 実行すべき build / test / format
+     - 完了報告項目
+
+4. coder 完了確認
+   - `ReadPodOutput` で報告を読む。
+   - 通知が来ない場合でも、worktree の `git status` / `git diff` / test で完了状態を確認する。
+   - coder が止まった場合、worktree 状態を見て再 spawn / rollback / 親 escalation を判断する。
+
+5. reviewer Pod spawn
+   - reviewer は coder の子ではなく orchestrator 配下の sibling として立てる。
+   - 原則 read-only scope にする。
+   - reviewer に渡すもの:
+     - ticket / intent packet
+     - branch / commit / diff の読み方
+     - 実行済み validation
+     - blocker / non-blocker / acceptable の分類基準
+   - reviewer の主目的は「コードの詳細を親の代わりに説明し、intent / invariant 違反を見つけること」。
+
+6. review → 修正 loop
+   - reviewer finding を orchestrator が読む。
+   - blocker は coder に修正依頼する。
+   - reviewer の指摘を却下する場合は、orchestrator が理由を dossier に残す。
+   - 修正後は focused validation を実行し、必要なら reviewer に再確認させる。
+   - reviewer の blocker が未解決のまま親に提出しない。
+
+7. merge-ready dossier 作成
+   - 親がコードを直接理解しなくても判断できるよう、変更の概念的説明と evidence をまとめる。
+
+8. merge / lifecycle
+   - 最上位 orchestrator または人間の許可を持つ orchestrator が main workspace へ merge する。
+   - `TODO.md` から該当行を削除し、ticket を完了処理して commit する。
+   - main workspace で必要な test / `cargo check --workspace` / `cargo fmt --check` を再実行する。
+
+## coder Pod の責務
+
+- child worktree 内でのみ実装する。
+- main workspace の管理ファイルを書かない。
+- intent / requirements / invariants / non-goals を読んでから実装する。
+- 指定された build / test / format を実行する。
+- ticket 要件外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて orchestrator に報告する。
+- 完了時に以下を報告する。
+  - worktree path / branch
+  - commit hash（commit した場合）
+  - 変更ファイル
+  - 実装概要
+  - 実行した build / test / format
+  - 未解決事項
+  - review に回せるか
+
+## reviewer Pod の責務
+
+reviewer は coder の subordinate ではない。orchestrator 配下の sibling として、実装 diff を外部から読む。
+
+- 原則 read-only で作業する。
+- ticket / intent packet / diff / validation 結果を読む。
+- 実際のコード変更が概念的に何を変えたかを説明する。
+- 親や上位 orchestrator が line-by-line diff を読まずに判断できるよう、以下を整理する。
+  - 変更の概念モデル
+  - intent / requirements との対応
+  - invariant 違反の有無
+  - 旧概念・禁止語彙・不要な互換層の残存
+  - validation の妥当性
+  - blocker / non-blocker / follow-up
+- reviewer は直接 merge しない。
+- reviewer は coder に直接作業指示を出さず、orchestrator に finding を返す。
+
+## commit 方針
+
+coder Pod には child worktree 内での commit を許可してよい。
+
+- commit は ticket 内で意味のある粒度にする。
+  - 例: `feat: ...`、`fix: ...`、`test: ...`、`docs: ...`
+- coder Pod は merge / push / branch deletion / worktree remove をしない。
+- coder Pod は `TODO.md` / ticket の完了処理 commit をしない。
+- orchestrator は review 時に commit 粒度も確認する。
+- 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。
+
+## Review → 修正 → 完了の標準形
+
+### Approve
+
+1. coder Pod / reviewer Pod を停止し、scope を回収する。
+2. orchestrator が merge-ready dossier を確認する。
+3. 最上位 orchestrator が必要最小限の spot check を行う。
+4. main workspace で `git merge --no-ff <branch>` する。
+5. `TODO.md` と ticket を完了処理して commit する。
+6. main workspace で検証コマンドを再実行する。
+7. 変更内容・commit・検証結果・残 dirty changes を報告する。
+
+### Request changes
+
+1. reviewer finding または orchestrator finding を blocker / non-blocker に分ける。
+2. blocker はファイル / 行 / 理由 / 修正方針つきで coder に戻す。
+3. coder が停止済みなら、同じ worktree / branch / scope で再 spawn する。
+4. 修正後に focused test と必要な broader test を再実行する。
+5. 必要なら reviewer に再確認させる。
+6. blocker が解消したら dossier を更新する。
+
+### Non-blocking comments
+
+- ticket 要件外の改善はその場で混ぜない。
+- 必要なら後続 ticket / docs/report にする。
+- non-blocking を理由に completion を遅らせない。
+
+## 並列実装時の注意
+
+- 1 ticket = 1 worktree = 1 branch を基本にする。
+- 複数 Pod に同じ write scope を渡さない。
+- parent / orchestrator は coder の write scope 配下を直接編集しない。
+- reviewer は read-only を基本にする。review artifact を書かせる場合は ticket artifacts など限定 scope にする。
+- 依存関係がある ticket は、土台 branch を merge してから次 worktree を切る。
+- parallel に走らせた Pod の完了通知は取りこぼしうるため、`ReadPodOutput` と worktree 状態で確認する。
+
+## merge-ready dossier の標準形
+
+```text
+Status:
+- completed / blocked / needs parent decision
+
+Scope:
+- ticket(s): <path>
+- branch: <name>
+- commits:
+  - <hash> <subject>
+
+Intent check:
+- invariant 1: ok / violated / not applicable, evidence ...
+- invariant 2: ok / violated / not applicable, evidence ...
+
+Implementation summary:
+- 変更の概念的説明: ...
+- 主要変更ファイル: ...
+- compatibility / migration: ...
+
+Coder loop:
+- coder pod: <name>
+- produced commits: ...
+- unresolved coder notes: ...
+
+External review:
+- reviewer pod: <name>
+- blockers found: ...
+- blockers fixed: ...
+- rejected findings and reasons: ...
+- non-blocking follow-ups: ...
+
+Validation:
+- cargo fmt --check
+- cargo check --workspace
+- cargo test ...
+- ./tickets.sh doctor
+
+Parent decision needed:
+- none / specific question
+
+Residual risk:
+- ...
+
+Dirty state:
+- ...
+```
+
+## 最上位 orchestrator の acceptance
+
+最上位 orchestrator は、下位 orchestrator の成果を code review するのではなく acceptance する。
+
+確認するもの:
+
+- intent packet が保持されているか。
+- reviewer が coder と独立した sibling として機能したか。
+- blocker が未解決のまま握りつぶされていないか。
+- 変更の概念的説明が要件と対応しているか。
+- validation が ticket のリスクに対して十分か。
+- escalation すべき判断を下位が勝手に決めていないか。
+
+必要なら spot check するが、常態的な line-by-line review に戻らない。
+
+## この Workflow で扱わないもの
+
+以下は `$user/auto-maintain` または別の設計相談で扱う。
+
+- ticket 候補を見繕うこと。
+- 新規 ticket 作成判断。
+- QA feedback / AI feedback を ticket / report / workflow に落とす判断。
+- 長期 maintainer loop / WorkItemStore / LeaseStore の設計。
+- reviewer Pod の品質評価を機械的に採点する仕組み。
@@ -0,0 +1,167 @@
+---
+description: ticket を実装委譲する前に、要件・前提・設計境界・反証観点を同期し、tickets.sh に記録する preflight フロー
+model_invokation: true
+user_invocable: true
+requires: []
+---
+# Ticket Preflight Workflow
+
+insomnia プロジェクトで ticket を実装に渡す前に、要件・前提・設計境界・反証観点を同期するための Workflow。これは **実装前の gate** であり、worktree 作成や coder / reviewer Pod の起動は `multi-agent-workflow` / `worktree-workflow` 側で扱う。
+
+目的は「ticket があるから実装する」状態を避け、ticket が **実装可能な仕様** なのか、**調査 ticket** なのか、**人間との仕様同期が必要な未決定 ticket** なのかを明確にすることである。
+
+## 適用する場面
+
+以下のいずれかに当てはまる ticket は、実装委譲前にこの Workflow を通す。
+
+- profile / manifest / scope / permission / session / history / pod-store / prompt context など authority boundary に触れる。
+- ticket の文面から複数の自然な設計方針が導ける。
+- 「どう実装するか」以前に「何を仕様とするか」が曖昧である。
+- 既存 implementation plan があるが、抽象化・責務境界・ユーザー体験に疑問がある。
+- 過去 decision / memory / docs / ticket thread と矛盾しそうである。
+- coder Pod に渡す intent packet を短く書けない。
+
+小さなバグ修正や仕様が明確な局所変更では、この Workflow は省略してよい。ただし省略理由が曖昧な場合は preflight する。
+
+## tickets.sh 運用方針
+
+作業管理の authority は `work-items/` と `tickets.sh` である。preflight の結果は、口頭の会話だけで終わらせず、ticket の `thread.md` または `item.md` に残す。
+
+- 新規の前提・要件・受け入れ条件は、必要に応じて `item.md` を更新する。
+- 調査結果・実装前 plan は `./tickets.sh comment <ticket> --role plan --file <file>` で残す。
+- 採用/却下した設計判断、実装停止判断、仕様同期の結論は `--role decision` で残す。
+- 実装に入ってよい状態になったら、その根拠を intent packet として ticket thread に残す。
+- 仕様が未決定なら、実装 ticket にせず requirements-sync / spike / design ticket として切り分ける。
+- ticket の timestamp/frontmatter が更新される場合は、関連変更と一緒に commit する。
+- ticket 作成・更新・レビュー・完了は git commit で記録する。push はしない。
+
+## 手順
+
+### 1. 状態確認
+
+- `git status --short --branch`
+- 対象 ticket の `item.md` / `thread.md` / artifacts
+- 関連 ticket / docs / workflow / Knowledge / memory decision
+- 既存 worktree / branch / running Pod の有無
+
+この段階で unrelated dirty changes がある場合は、preflight の記録だけを行うか、人間に確認してから進める。
+
+### 2. ticket の種類を分類する
+
+以下のどれかに分類する。
+
+```text
+implementation-ready:
+- 要件・受け入れ条件・invariant が明確で、実装方針が一意または十分絞れている。
+
+requirements-sync-needed:
+- ticket の目的は見えているが、仕様・用語・責務境界・ユーザー体験の同期が必要。
+
+spike-needed:
+- 技術的実現性・依存関係・ライセンス・性能・diagnostics などを先に調べる必要がある。
+
+blocked-needs-human-decision:
+- 複数方針があり、AI が勝手に決めると設計境界や product API を固定してしまう。
+```
+
+`implementation-ready` 以外は、coder Pod に実装を委譲しない。
+
+### 3. 要件同期
+
+最低限、以下を確認する。
+
+- 完了時に observable に何が変わるか。
+- ticket の主語は何か: user-facing behavior / internal architecture / cleanup / investigation。
+- 用語が既存設計と一致しているか。
+- 何をやらないか。
+- 後方互換が必要か、不要な互換層を作ろうとしていないか。
+- 既存の authority boundary を変えるか。
+- runtime state / persisted state / config / profile / manifest / session log / pod metadata のどれが authority か。
+
+必要なら ticket `item.md` の Background / Requirements / Acceptance criteria を更新する。
+
+### 4. 現行コードと過去判断の map を作る
+
+実装前に、少なくとも関連する current code paths を列挙する。
+
+```text
+Current code map:
+- file/function: 現在の責務
+- file/function: 変更候補
+- file/function: 触ってはいけない境界
+```
+
+この map は簡潔でよい。目的は coder Pod が blind に探しながら設計を固定するのを防ぐこと。
+
+### 5. 批判的 preflight
+
+実装方針を一度疑う。以下の問いに答える。
+
+- この ticket は本当に実装 ticket か、それとも仕様同期 ticket か。
+- 最も自然に見える実装が失敗するとしたらどこか。
+- 抽象化に失敗して「別名の同じもの」を作っていないか。
+- runtime-bound な値を reusable config に混ぜていないか。
+- profile / manifest / scope / session / pod-store などの authority を逆転させていないか。
+- user-facing API を安易に public contract 化していないか。
+- external dependency / license / portability / packaging の問題はないか。
+- reviewer が diff だけ読んでも見落とす設計リスクは何か。
+
+この問いへの答えを `plan` または `decision` として ticket thread に残す。
+
+### 6. intent packet を作る
+
+実装に入ってよい場合だけ、`multi-agent-workflow` に渡す intent packet を作る。
+
+```text
+Intent:
+- 何を実現するか。
+
+Requirements:
+- observable な完了条件。
+
+Invariants:
+- 壊してはいけない authority boundary / design boundary。
+
+Non-goals:
+- 今回やらないこと。
+
+Escalate if:
+- 親/人間に戻す判断条件。
+
+Validation:
+- focused test / broader check / doctor / docs 更新。
+
+Current code map:
+- 実装対象と触ってはいけない場所。
+
+Critical risks:
+- reviewer にも見てほしい失敗パターン。
+```
+
+この intent packet が短く書けない場合は、実装委譲せず requirements-sync-needed とする。
+
+## review への引き継ぎ
+
+preflight で出た critical risks は reviewer Pod にも渡す。reviewer は diff だけでなく、ticket の前提・要件・invariant と preflight の反証観点を読む。
+
+reviewer に期待すること:
+
+- 実装が preflight の intent に対応しているか。
+- 抽象化失敗や authority boundary 違反がないか。
+- preflight で挙げた失敗パターンに落ちていないか。
+- validation がリスクに対して十分か。
+
+## 完了条件
+
+この Workflow 自体の完了条件は、次のいずれかである。
+
+- ticket が `implementation-ready` になり、intent packet が thread に記録されている。
+- ticket が `requirements-sync-needed` / `spike-needed` / `blocked-needs-human-decision` として整理され、次に人間へ戻す問いまたは follow-up ticket が明確になっている。
+- ticket 自体が不要/誤りと判断され、理由が decision として記録されている。
+
+## この Workflow でしないこと
+
+- worktree を作成しない。
+- coder Pod に実装を委譲しない。
+- merge / close しない。
+- 仕様未決定のまま「小さく実装してみる」ことで public API を固定しない。
@@ -0,0 +1,119 @@
+---
+description: insomnia プロジェクトで child git worktree を作成・管理するための機械的手順。coder Pod に作らせず、orchestrator Pod が main workspace で実行する。
+model_invokation: true
+user_invocable: true
+requires: []
+---
+# Worktree Workflow
+
+insomnia プロジェクトで実装差分を main workspace から分離するため、`./.worktree/<task-name>` に child git worktree を作る。これは **worktree の扱い方だけ** を定める Workflow であり、ticket 選定、coder / reviewer sibling の起動、外部レビュー、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 で実行する。
+
+- coder Pod にこの Workflow を渡して worktree を作らせない。
+- coder Pod は、orchestrator が作成済みの child worktree を受け取り、その中で実装・build・test・報告を行う。
+- reviewer Pod は、coder Pod の子ではなく orchestrator 配下の sibling として、原則 read-only で main workspace と child worktree を読む。
+- ticket 作成、TODO 更新、review artifact、docs/report は main workspace 側で扱う。
+
+## 原則
+
+- 1 ticket / 1 実装 task につき 1 worktree を作る。
+- 複数 ticket を下位 orchestrator に任せる場合も、実装差分は ticket / bounded task ごとに 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 が既に存在しないか。
+6. coder / reviewer を sibling として扱う orchestrator が誰か明確か。
+
+同名 branch がある場合は、既存 branch を使うか、人間に確認する。`git worktree add -b` で上書きしない。
+
+## 作成手順
+
+main workspace で実行する。
+
+```bash
+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/**'
+```
+
+確認する。
+
+```bash
+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 <repo>/.worktree/<task-name> && ...` させる。
+
+coder Pod 推奨 scope:
+
+```text
+read:  <repo>
+write: <repo>/.worktree/<task-name>
+```
+
+reviewer Pod 推奨 scope:
+
+```text
+read: <repo>
+read: <repo>/.worktree/<task-name>  # main workspace の read に含まれるなら別指定不要
+```
+
+reviewer は原則 write scope を持たない。review artifact を書かせる必要がある場合だけ、ticket artifacts など限定 directory を write scope として渡す。
+
+より狭く切れる場合は、coder の 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` または人間の明示指示で行う。
+
+coder Pod へ渡す完了報告項目の標準形:
+
+- worktree path
+- branch 名
+- commit hash（coder Pod に commit を許可した場合）
+- 変更ファイル
+- 実装概要
+- 実行した build / test / format
+- 未解決事項
+- review に回せるか
+
+reviewer Pod へ渡す完了報告項目の標準形:
+
+- 読んだ ticket / intent packet / diff
+- 実際のコード変更の概念的説明
+- intent / requirements / invariant との対応
+- blocker / non-blocker / follow-up
+- validation の妥当性
+- 親または上位 orchestrator が判断すべき残論点