Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

chore: workflowの改善

Browse Source
This commit is contained in:
Hare
2026-05-30 05:35:54 +09:00
parent dda9910c30
commit aba7809fb9
4 changed files with 257 additions and 62 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.insomnia/manifest.toml
+17
View File
@@ -6,8 +6,25 @@ allow = [
[session] [session]
record_event_trace = true record_event_trace = true
[worker]
reasoning = "high"
[model]
ref = "codex-oauth/gpt-5.5"
[compaction]
compact_threshold = 200000
compact_request_threshold = 240000
compact_worker_max_input_tokens = 100000
[memory] [memory]
extract_threshold = 50000 extract_threshold = 50000
consolidation_threshold_files = 5 consolidation_threshold_files = 5
consolidation_threshold_bytes = 50000 consolidation_threshold_bytes = 50000
[web]
enabled = true
[web.search]
provider = "brave"
api_key_env = "BRAVE_SEARCH_API_KEY"
.insomnia/workflow/auto-maintain.md
+8 -3
View File
@@ -8,7 +8,7 @@ requires: []
insomnia を AI maintainer として運用するための半自動 loop。TODO / tickets から「今進められそうな作業」を選ぶだけでなく、課題の発見、設計判断の切り分け、次に人間へ戻すべき問いの整理までを扱う。 insomnia を AI maintainer として運用するための半自動 loop。TODO / tickets から「今進められそうな作業」を選ぶだけでなく、課題の発見、設計判断の切り分け、次に人間へ戻すべき問いの整理までを扱う。
これは unattended 自動開発ではない。実装の並列委譲は `multi-agent-workflow`、worktree の機械的作成は `worktree-workflow` に任せる。本 Workflow はその前段として、何を進めるべきか、何をまだ決めるべきかを整理する。 これは unattended 自動開発ではない。実装の並列委譲は `multi-agent-workflow`、worktree の機械的作成は `worktree-workflow` に任せる。本 Workflow はその前段として、何を進めるべきか、何をまだ決めるべきか、下位 orchestrator にどの intent packet を渡すべきかを整理する。
参照: 参照:
@@ -24,6 +24,7 @@ AI maintainer の目的は、コードを書くこと自体ではなく、プロ
- TODO / tickets / docs / git history を読んで現在地を把握する。 - TODO / tickets / docs / git history を読んで現在地を把握する。
- 実装可能な ticket と、方針決定が必要な ticket を分ける。 - 実装可能な ticket と、方針決定が必要な ticket を分ける。
- 小さく実装できる候補を提案する。 - 小さく実装できる候補を提案する。
- 複数 ticket からなる作業群は、下位 orchestrator に任せる単位として整理する。
- 設計相談が必要な論点を人間に戻す。 - 設計相談が必要な論点を人間に戻す。
- 運用上の問題や繰り返し発生する詰まりを report / ticket / workflow 改訂候補として整理する。 - 運用上の問題や繰り返し発生する詰まりを report / ticket / workflow 改訂候補として整理する。
@@ -65,7 +66,7 @@ TODO と ticket の不整合を見つけたら、勝手に修正せず、まず
- 大きな設計判断が不要。 - 大きな設計判断が不要。
- scope を狭く切れる。 - scope を狭く切れる。
この場合は、人間に候補として提示する。人間が実行を許可したら `$user/multi-agent-workflow` に進む。 この場合は、人間に候補として提示する。人間が実行を許可したら `$user/multi-agent-workflow` に進む。複数 ticket や連続した作業群では、最上位 Pod が直接 coder を抱えず、下位 orchestrator に intent packet を渡して coder / reviewer sibling loop を管理させる。
### B. 方針決定が必要 ### B. 方針決定が必要
@@ -89,6 +90,7 @@ TODO と ticket の不整合を見つけたら、勝手に修正せず、まず
- 同じ tool 問題が繰り返し出る。 - 同じ tool 問題が繰り返し出る。
- Workflow の指示が曖昧で実装 Pod が迷った。 - Workflow の指示が曖昧で実装 Pod が迷った。
- coder / reviewer / orchestrator の責務が混ざり、親 Pod が細かい code review に戻ってしまった。
- AI が過剰に Task tool を使うなど、運用上の癖が出た。 - AI が過剰に Task tool を使うなど、運用上の癖が出た。
- 通知や Pod completion tracking など、開発基盤の不足が観測された。 - 通知や Pod completion tracking など、開発基盤の不足が観測された。
@@ -114,9 +116,12 @@ TODO と ticket の不整合を見つけたら、勝手に修正せず、まず
- 「次に進めるなら X」を1つ推奨する。 - 「次に進めるなら X」を1つ推奨する。
- 理由を短く述べる。 - 理由を短く述べる。
- 実装委譲する場合の scope / test 方針を添える。 - 実装委譲する場合の scope / test 方針を添える。
- 複数 ticket の作業群なら、下位 orchestrator に任せる単位として提示する。
5. 実行への接続 5. 実行への接続
- 人間が「進めて」と言ったら `$user/multi-agent-workflow` に接続する。 - 人間が「進めて」と言ったら `$user/multi-agent-workflow` に接続する。
- 単発 ticket か、下位 orchestrator に任せる ticket 群かを明示する。
- 下位 orchestrator に渡す intent / requirements / invariants / non-goals / escalation 条件を短くまとめる。
- worktree 作成は `$user/worktree-workflow` に従う。 - worktree 作成は `$user/worktree-workflow` に従う。
## エスカレーション基準 ## エスカレーション基準
@@ -129,7 +134,7 @@ TODO と ticket の不整合を見つけたら、勝手に修正せず、まず
- 新 ticket の作成、既存 ticket の大幅変更、ticket 完了削除について合意がない。 - 新 ticket の作成、既存 ticket の大幅変更、ticket 完了削除について合意がない。
- test 不能、再現不能、または作業範囲外の不具合に遭遇した。 - test 不能、再現不能、または作業範囲外の不具合に遭遇した。
- WorkItem / Thread / Lease / maintainer state など、まだ設計中の概念が必要になる。 - WorkItem / Thread / Lease / maintainer state など、まだ設計中の概念が必要になる。
- 下位 orchestrator に委譲するには intent / invariant / escalation 条件が曖昧すぎる。
## まだ固定しないもの ## まだ固定しないもの
.insomnia/workflow/multi-agent-workflow.md
+196 -44
View File
@@ -1,75 +1,159 @@
--- ---
description: worktree と子 Pod を使って複数 ticket の実装・レビュー・修正・完了処理を並列に進める orchestration フロー description: worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が複数 ticket の実装・外部レビュー・修正・完了準備を管理する orchestration フロー
model_invokation: true model_invokation: true
user_invocable: true user_invocable: true
requires: [] requires: []
--- ---
# Multi-agent Worktree Workflow # Multi-agent Worktree Workflow
insomnia を insomnia で開発する際の、worktree + 実装 Pod + 親 Pod review の標準フロー。これは **実装を並列に進めるためのフロー** であり、worktree の機械的作成手順は `$user/worktree-workflow`、ticket 候補選定や方針探索の半自動 loop は `$user/auto-maintain` に分ける。 insomnia を insomnia で開発する際の、worktree + coder Pod + 外部 reviewer Pod + orchestrator Pod の標準フロー。これは **最上位 Pod が細かい code review を抱えず、下位 orchestrator が実装と外部レビューの loop を完了状態まで運ぶためのフロー** である。
worktree の機械的作成手順は `$user/worktree-workflow`、ticket 候補選定や方針探索の半自動 loop は `$user/auto-maintain` に分ける。
## 目的 ## 目的
- 実装差分を ticket ごとの child worktree に隔離する。 - 実装差分を ticket ごとの child worktree に隔離する。
- 実装 Pod に narrow write scope を渡して並列実装させる。 - coder Pod に narrow write scope を渡して実装させる。
- 親 Pod が diff / test / ticket 要件を review し、必要なら修正依頼する。 - reviewer Pod を coder の子ではなく **同じ orchestrator 配下の sibling** として立て、外部レビューを行わせる。
- approve 後に merge / ticket 完了処理 / main workspace での再検証を行う。 - 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 群が決まっている。
- ticket の背景・要件・完了条件から実装方針が概ね導ける。 - ticket の背景・要件・完了条件から実装方針が概ね導ける。
- worktree 作成と git 書き込み操作について、人間の許可がある。 - worktree 作成と git 書き込み操作について、人間の許可がある。
- main workspace の unrelated dirty changes を把握している。 - main workspace の unrelated dirty changes を把握している。
- 下位 orchestrator に渡す intent / invariant / non-goals / escalation 条件を短く書ける。
設計方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に人間へ戻す。 設計方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に人間へ戻す。ただし下位 orchestrator に探索だけを委譲することはできる。
## 親 Pod / 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. 状態確認 1. 状態確認
- `git status --short --branch` - `git status --short --branch`
- 対象 ticket - 対象 ticket / ticket 群
- 関連 TODO / docs / 既存 worktree - 関連 TODO / docs / 既存 worktree
2. worktree 作成 2. worktree 作成
- `$user/worktree-workflow` に従い `./.worktree/<task-name>` を作る。 - `$user/worktree-workflow` に従い `./.worktree/<task-name>` を作る。
- `.insomnia` を sparse checkout で除外する。 - `.insomnia` を sparse checkout で除外する。
3. 実装 Pod spawn 3. coder Pod spawn
- read scope: main workspace 全体。 - read scope: main workspace 全体。
- write scope: child worktree、または必要最小 directory。 - write scope: child worktree、または必要最小 directory。
- task には以下を明示する。 - task には以下を明示する。
- child worktree path / branch - child worktree path / branch
- 対象 ticket path - 対象 ticket path
- intent packet
- Bash は必ず child worktree に `cd` すること - Bash は必ず child worktree に `cd` すること
- main workspace の `TODO.md` / `tickets/` / `docs/report/` / `.insomnia` は編集しないこと - main workspace の `TODO.md` / `tickets/` / `docs/report/` / `.insomnia` は編集しないこと
- 範囲外事項 - 範囲外事項
- 実行すべき build / test / format - 実行すべき build / test / format
- 完了報告項目 - 完了報告項目
4. 監督 4. coder 完了確認
- `ReadPodOutput` で報告を読む。 - `ReadPodOutput` で報告を読む。
- 通知が来ない場合でも、worktree の `git status` / `git diff` / test で完了状態を確認する。 - 通知が来ない場合でも、worktree の `git status` / `git diff` / test で完了状態を確認する。
- 必要なら `SendToPod` で修正依頼する。 - coder が止まった場合、worktree 状態を見て再 spawn / rollback / 親 escalation を判断する。
5. review 5. reviewer Pod spawn
- ticket の背景・要件・完了条件・範囲外に照らして diff を確認する。 - reviewer は coder の子ではなく orchestrator 配下の sibling として立てる。
- build / test / `git diff --check` を確認する。 - 原則 read-only scope にする。
- 必要なら reviewer Pod を read-only で立てる。 - reviewer に渡すもの:
- ticket / intent packet
- branch / commit / diff の読み方
- 実行済み validation
- blocker / non-blocker / acceptable の分類基準
- reviewer の主目的は「コードの詳細を親の代わりに説明し、intent / invariant 違反を見つけること」。
6. merge / lifecycle 6. review → 修正 loop
- approve 後に main workspace へ merge する。 - reviewer finding を orchestrator が読む。
- `TODO.md` から該当行を削除し、`tickets/foo.md` を削除して完了 commit を作る。 - 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` を再実行する。 - main workspace で必要な test / `cargo check --workspace` / `cargo fmt --check` を再実行する。
## 実装 Pod の責務 ## coder Pod の責務
- child worktree 内でのみ実装する。 - child worktree 内でのみ実装する。
- main workspace の管理ファイルを書かない。 - main workspace の管理ファイルを書かない。
- intent / requirements / invariants / non-goals を読んでから実装する。
- 指定された build / test / format を実行する。 - 指定された build / test / format を実行する。
- ticket 要件外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて報告する。 - ticket 要件外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて orchestrator に報告する。
- 完了時に以下を報告する。 - 完了時に以下を報告する。
- worktree path / branch - worktree path / branch
- commit hash（commit した場合） - commit hash（commit した場合）
@@ -79,34 +163,54 @@ insomnia を insomnia で開発する際の、worktree + 実装 Pod + 親 Pod re
- 未解決事項 - 未解決事項
- review に回せるか - review に回せるか
## 実装 Pod の commit 方針 ## reviewer Pod の責務
実装 Pod には child worktree 内での commit を許可してよい。 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 内で意味のある粒度にする。 - commit は ticket 内で意味のある粒度にする。
- 例: `feat: ...`、`fix: ...`、`test: ...`、`docs: ...` - 例: `feat: ...`、`fix: ...`、`test: ...`、`docs: ...`
- 実装 Pod は merge / push / branch deletion / worktree remove をしない。 - coder Pod は merge / push / branch deletion / worktree remove をしない。
- 実装 Pod は `TODO.md` / `tickets/` の完了処理 commit をしない。 - coder Pod は `TODO.md` / ticket の完了処理 commit をしない。
- 親 Pod は review 時に commit 粒度も確認する。 - orchestrator は review 時に commit 粒度も確認する。
- 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。 - 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。
## Review → 修正 → 完了の標準形 ## Review → 修正 → 完了の標準形
### Approve ### Approve
1. 実装 Pod を停止し、scope を回収する。 1. coder Pod / reviewer Pod を停止し、scope を回収する。
2. 親 Pod が main workspace で `git merge --no-ff <branch>` する。 2. orchestrator が merge-ready dossier を確認する。
3. 親 Pod が `TODO.md` と `tickets/foo.md` を完了処理して commit する。 3. 最上位 orchestrator が必要最小限の spot check を行う。
4. main workspace で検証コマンドを再実行する。 4. main workspace で `git merge --no-ff <branch>` する。
5. 変更内容・commit・検証結果・残 dirty changes を報告する。 5. `TODO.md` と ticket を完了処理して commit する。
6. main workspace で検証コマンドを再実行する。
7. 変更内容・commit・検証結果・残 dirty changes を報告する。
### Request changes ### Request changes
1. blocking finding をファイル / 行 / 理由 / 修正方針つきで整理する。 1. reviewer finding または orchestrator finding を blocker / non-blocker に分ける。
2. 実装 Pod が生きていれば `SendToPod` で修正依頼する。 2. blocker はファイル / 行 / 理由 / 修正方針つきで coder に戻す。
3. 停止済みなら、同じ worktree / branch / scope で再 spawn するか、親 Pod が最小修正する。 3. coder が停止済みなら、同じ worktree / branch / scope で再 spawn する。
4. 修正後に focused test と必要な broader test を再実行する。 4. 修正後に focused test と必要な broader test を再実行する。
5. 再 review する。 5. 必要なら reviewer に再確認させる。
6. blocker が解消したら dossier を更新する。
### Non-blocking comments ### Non-blocking comments
@@ -118,28 +222,75 @@ insomnia を insomnia で開発する際の、worktree + 実装 Pod + 親 Pod re
- 1 ticket = 1 worktree = 1 branch を基本にする。 - 1 ticket = 1 worktree = 1 branch を基本にする。
- 複数 Pod に同じ write scope を渡さない。 - 複数 Pod に同じ write scope を渡さない。
- parent は child の write scope 配下を直接編集しない。 - parent / orchestrator は coder の write scope 配下を直接編集しない。
- reviewer は read-only を基本にする。review artifact を書かせる場合は ticket artifacts など限定 scope にする。
- 依存関係がある ticket は、土台 branch を merge してから次 worktree を切る。 - 依存関係がある ticket は、土台 branch を merge してから次 worktree を切る。
- parallel に走らせた Pod の完了通知は取りこぼしうるため、`ReadPodOutput` と worktree 状態で確認する。 - parallel に走らせた Pod の完了通知は取りこぼしうるため、`ReadPodOutput` と worktree 状態で確認する。
## 完了報告の標準形 ## merge-ready dossier の標準形
```text ```text
完了: Status:
- ticket: <path> - completed / blocked / needs parent decision
Scope:
- ticket(s): <path>
- branch: <name> - branch: <name>
- commits: - commits:
- <hash> <subject> - <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 fmt --check
- cargo check --workspace - cargo check --workspace
- cargo test ... - cargo test ...
- review: approve / approve with comments / request changes - ./tickets.sh doctor
- 未解決事項: ...
- 残 dirty changes: ... 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 で扱わないもの ## この Workflow で扱わないもの
以下は `$user/auto-maintain` または別の設計相談で扱う。 以下は `$user/auto-maintain` または別の設計相談で扱う。
@@ -148,3 +299,4 @@ insomnia を insomnia で開発する際の、worktree + 実装 Pod + 親 Pod re
- 新規 ticket 作成判断。 - 新規 ticket 作成判断。
- QA feedback / AI feedback を ticket / report / workflow に落とす判断。 - QA feedback / AI feedback を ticket / report / workflow に落とす判断。
- 長期 maintainer loop / WorkItemStore / LeaseStore の設計。 - 長期 maintainer loop / WorkItemStore / LeaseStore の設計。
- reviewer Pod の品質評価を機械的に採点する仕組み。
.insomnia/workflow/worktree-workflow.md
+33 -12
View File
@@ -1,26 +1,28 @@
--- ---
description: insomnia プロジェクトで child git worktree を作成・管理するための機械的手順。実装 Pod に作らせず、親 Pod が main workspace で実行する。 description: insomnia プロジェクトで child git worktree を作成・管理するための機械的手順。coder Pod に作らせず、orchestrator Pod が main workspace で実行する。
model_invokation: false model_invokation: true
user_invocable: true user_invocable: true
requires: [] requires: []
--- ---
# Worktree Workflow # Worktree Workflow
insomnia プロジェクトで実装差分を main workspace から分離するため、`./.worktree/<task-name>` に child git worktree を作る。これは **worktree の扱い方だけ** を定める Workflow であり、ticket 選定、実装委譲、review、merge の運用は `$user/multi-agent-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 はコード差分専用の作業面として扱う。 insomnia では Pod の write scope が排他的に委譲されるため、child worktree に `.insomnia` を置かない。main workspace は orchestration / ticket / docs / memory / workflow 管理の場所として残し、child worktree はコード差分専用の作業面として扱う。
## 適用範囲 ## 適用範囲
この Workflow は親 Pod / orchestrator が main workspace で実行する。 この Workflow は親 Pod / 下位 orchestrator が main workspace で実行する。
- 実装 Pod にこの Workflow を渡して worktree を作らせない。 - coder Pod にこの Workflow を渡して worktree を作らせない。
- 実装 Pod は、親 Pod が作成済みの child worktree を受け取り、その中で実装・build・test・報告を行う。 - 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 側で扱う。 - ticket 作成、TODO 更新、review artifact、docs/report は main workspace 側で扱う。
## 原則 ## 原則
- 1 ticket / 1 実装 task につき 1 worktree を作る。 - 1 ticket / 1 実装 task につき 1 worktree を作る。
- 複数 ticket を下位 orchestrator に任せる場合も、実装差分は ticket / bounded task ごとに worktree を分ける。
- worktree path は `./.worktree/<task-name>`。 - worktree path は `./.worktree/<task-name>`。
- branch 名は原則 `<task-name>` と同じ kebab-case。 - branch 名は原則 `<task-name>` と同じ kebab-case。
- child worktree には `.insomnia` を出さない。 - child worktree には `.insomnia` を出さない。
@@ -36,6 +38,7 @@ insomnia では Pod の write scope が排他的に委譲されるため、child
3. `git worktree add` を実行してよい許可があるか。 3. `git worktree add` を実行してよい許可があるか。
4. main workspace に混ぜてはいけない未保存差分がないか。 4. main workspace に混ぜてはいけない未保存差分がないか。
5. 同名 branch / worktree が既に存在しないか。 5. 同名 branch / worktree が既に存在しないか。
6. coder / reviewer を sibling として扱う orchestrator が誰か明確か。
同名 branch がある場合は、既存 branch を使うか、人間に確認する。`git worktree add -b` で上書きしない。 同名 branch がある場合は、既存 branch を使うか、人間に確認する。`git worktree add -b` で上書きしない。
@@ -62,18 +65,27 @@ test ! -e .worktree/<task-name>/.insomnia
失敗した場合は、worktree / branch / lock の状態を確認し、勝手に cleanup せず人間へ報告する。 失敗した場合は、worktree / branch / lock の状態を確認し、勝手に cleanup せず人間へ報告する。
## 子 Pod へ渡す scope ## Pod へ渡す scope
子 Pod を使う場合、子 Pod の cwd は main workspace のままになる。必ず作業対象が child worktree であることを明示し、Bash 実行時は毎回 `cd <repo>/.worktree/<task-name> && ...` させる。 Pod を使う場合、Pod の cwd は main workspace のままになる。必ず作業対象が child worktree であることを明示し、Bash 実行時は毎回 `cd <repo>/.worktree/<task-name> && ...` させる。
推奨 scope: coder Pod 推奨 scope:
```text ```text
read: <repo> read: <repo>
write: <repo>/.worktree/<task-name> write: <repo>/.worktree/<task-name>
``` ```
より狭く切れる場合は、write scope を変更対象 crate / directory まで狭めてよい。ただし build / test に必要な生成物を書けることを確認する。 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 内の禁止事項 ## child worktree 内の禁止事項
@@ -86,13 +98,22 @@ write: <repo>/.worktree/<task-name>
worktree 作成 Workflow としては、完了時に merge しない。merge、ticket 完了、TODO 削除は `$user/multi-agent-workflow` または人間の明示指示で行う。 worktree 作成 Workflow としては、完了時に merge しない。merge、ticket 完了、TODO 削除は `$user/multi-agent-workflow` または人間の明示指示で行う。
実装 Pod へ渡す完了報告項目の標準形: coder Pod へ渡す完了報告項目の標準形:
- worktree path - worktree path
- branch 名 - branch 名
- commit hash（実装 Pod に commit を許可した場合） - commit hash（coder Pod に commit を許可した場合）
- 変更ファイル - 変更ファイル
- 実装概要 - 実装概要
- 実行した build / test / format - 実行した build / test / format
- 未解決事項 - 未解決事項
- review に回せるか - review に回せるか
reviewer Pod へ渡す完了報告項目の標準形:
- 読んだ ticket / intent packet / diff
- 実際のコード変更の概念的説明
- intent / requirements / invariant との対応
- blocker / non-blocker / follow-up
- validation の妥当性
- 親または上位 orchestrator が判断すべき残論点