---
description: worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が concrete Ticket 群の実装・外部レビュー・修正・完了準備を管理する orchestration フロー
model_invokation: true
user_invocable: true
requires: []
---
# Multi-agent Worktree Workflow

yoi を yoi で開発する際の、worktree + coder Pod + 外部 reviewer Pod + orchestrator Pod の標準フロー。これは **最上位 Pod が細かい code review を抱えず、下位 orchestrator が実装と外部レビューの loop を完了状態まで運ぶためのフロー** である。

worktree の機械的作成手順は `$user/worktree-workflow`、ユーザー依頼の Ticket 化は `$user/ticket-intake-workflow`、Ticket の next action 分類は `$user/ticket-orchestrator-routing`、実装前の planning/requirements sync は compatibility canonical id `$user/ticket-preflight-workflow` に分ける。

この Workflow は、対象 ticket が implementation-ready であることを前提にする。implementation-ready は full implementation plan ではなく、recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions に基づいて coder が bounded investigation を進め、reviewer が判断できる状態を指す。設計境界・仕様・authority boundary が未同期の場合は、worktree 作成や coder Pod 起動の前に planning/requirements sync 互換入口として `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 する。

## Pod coordination model

基本形は以下。

```text
最上位 orchestrator Pod
  - 人間との会話相手
  - intent / 要件 / invariant / escalation 条件を定義
  - 複数の作業群を並列管理
  - final merge / ticket close / main workspace validation を行う
  - 原則として line-by-line code review を主業務にしない

下位 orchestrator Pod（area / concrete-ticket-set coordinator）
  - 連続した複数 concrete Ticket または大きめの concrete 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 を分類して返す
```

一段だけで足りる小さい concrete Ticket では、最上位 orchestrator が直接 coder / reviewer sibling を扱ってよい。複数 concrete Ticket や設計境界をまたぐ作業では、最上位の下に下位 orchestrator を挟む。

この Pod coordination model は runtime delegation の形であり、Ticket hierarchy を作る根拠ではない。複数 Ticket を扱う場合も各 Ticket は concrete work item として独立に実装・レビュー・検証・close できる必要がある。broad effort の進捗コンテナとして umbrella Ticket、parent/child Ticket、sub-ticket、part-of、contains などを作らない。中期的な目的や戦略は Objective context に置き、typed Ticket relations が利用可能な場合も dependency / related / blocking / replacement などの非階層メタデータに限る。

明示的な queue review や routing kick の中で、独立した queued Ticket が複数あり coder/reviewer capacity が残っているなら、最初の Ticket の完了を待つことを default にしない。Orchestrator は各 Ticket の relation metadata、OrchestrationPlan records、Ticket thread、workspace/worktree dirty state、visible Pods、既存 branch、conflict notes を確認し、blocking relation や `do_not_parallelize` がなく、write surface が disjoint または conflict risk が小さく機械的に処理できるものを、別 worktree・別 branch・別 narrow write scope で並列開始する。これは background scheduler や queue drain loop ではなく、人間が queued にした Ticket だけを、その場の明示的な acceptance 判断で `queued -> inprogress` に進める運用である。

## 開始条件

以下が揃っている時に使う。

- 対象 concrete Ticket または concrete Ticket 群が決まっている。
- Ticket lifecycle を使う場合、対象はすでに `inprogress` であるか、worktree 作成・Pod spawn・coder routing の前に Orchestrator が個別に `queued -> inprogress` acceptance を記録できる `queued` Ticket に限る。unqueued Ticket は capacity 埋めの対象にしない。
- ticket の背景・意図・制約・受け入れ条件から、実装調査と局所 tactic 選択を coder に委ねても product / API / UX / authority / design-boundary decision を silently 固定しないと判断できる。
- worktree 作成と git 書き込み操作について、人間の許可がある。
- main workspace の unrelated dirty changes を把握している。
- 下位 orchestrator に渡す binding decisions / invariants、implementation latitude、escalation conditions を短く書ける。
- 設計境界・仕様・authority boundary に不確定要素があり、bounded project-context checks 後も concrete missing decision / information が残る場合、planning/requirements sync 互換入口 `ticket-preflight-workflow` の結果が ticket thread に記録されている。

product / API / UX / authority / design-boundary 方針が複数自然に導ける場合、ticket 自体の再定義が必要な場合、または protocol / scope / permission / history persistence に触れる作業で bounded project-context checks 後も concrete missing decision / information が残る場合は、実装委譲前に planning/requirements sync 互換入口 `ticket-preflight-workflow` を通し、必要なら人間へ戻す。scope / Pod / permission / persistence のような authority-adjacent domain は reviewer focus と context lookup の signal であり、intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions が明確なら coder に委ねてよい。実装ファイルの探索、既存コード読解、局所的な構成選択のような bounded implementation uncertainty も同様に coder に委ねてよい。

## Intent packet

階層化すると人間の意図が劣化しやすい。下位 orchestrator や coder / reviewer へは、自然文の依頼だけでなく intent packet を渡す。

標準形:

```text
Intent:
- 何を実現するか。

Binding decisions / invariants:
- 人間/Orchestrator/Ticket に記録済みで coder / reviewer が従うべき decision。
- 壊してはいけない設計境界、authority boundary、明示制約。
- 残してはいけない旧概念や互換層。

Requirements / acceptance criteria:
- 完了時に満たすべき observable な要件と reviewer が判断できる基準。

Implementation latitude:
- Coder が調査しながら選んでよい local tactic / file-local organization / bounded uncertainty。

Escalate if:
- 親へ戻すべき判断条件。特に product / API / UX / authority boundary / explicit design constraint を変える必要が出た場合。

Validation:
- 実行すべき format / build / test / doctor。

Reviewer focus:
- reviewer が確認すべき critical risks。
```

reviewer には coder の実装方針ではなく、この intent packet と diff を中心に読ませる。reviewer は recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions に照らして判断し、不記録の preferred tactic を基準にしない。

## orchestrator の責務

下位 orchestrator を挟まない場合は、以下を最上位 orchestrator が行う。下位 orchestrator を挟む場合は、最上位は intent packet を渡し、以下の実務を下位に委譲する。

1. 状態確認
   - `git state --short --branch`
   - 対象 ticket / ticket 群
   - relation metadata / OrchestrationPlan records / do_not_parallelize / conflict or dependency notes
   - visible Pods、既存 worktree/branch、coder/reviewer follow-up capacity
   - 関連 TODO / docs / 既存 worktree
   - planning sync が必要な ticket では、互換入口 `ticket-preflight-workflow` の分類・要件同期・critical risks

2. worktree 作成
   - 対象 Ticket が `queued` なら、この step の前に typed Ticket backend/tool path で `queued -> inprogress` を記録する。これより前に branch 作成、worktree 作成、Pod spawn、実装調査依頼などの implementation side effect を行わない。
   - `$user/worktree-workflow` に従い `./.worktree/<task-name>` を作る。
   - `.yoi` 自体は除外しない。tracked project records は child worktree に存在してよく、`.yoi/memory` と local/runtime/log/lock/secret-like paths だけを sparse checkout で除外する。

3. coder Pod spawn
   - read scope: main workspace 全体。
   - write scope: child worktree、または必要最小 directory。
   - task には以下を明示する。
     - child worktree path / branch
     - 対象 ticket path
     - intent packet
     - SpawnPod の `cwd` は child worktree に設定すること（`cwd` は process/tool default cwd であり、scope/authority ではない）
     - main workspace の `TODO.md` / `tickets/` / `docs/report/` / `.yoi` は編集しないこと
     - child worktree 内の tracked `.yoi` project records は実装対象に必要な branch-local artifacts/dossiers として編集してよいが、`.yoi/memory` や local/runtime/secret-like files は作らないこと
     - active orchestration progress と最終 review/approval/close は main workspace の責任として残すこと
     - 遵守すべき binding decisions / invariants と escalation conditions
     - 実行すべき build / test / format
     - 完了報告項目

4. coder 完了確認
   - `ReadPodOutput` で報告を読む。
   - 通知が来ない場合でも、worktree の `git state` / `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 の管理ファイルを書かない。
- child worktree 内の tracked `.yoi` project records は ticket 要件に必要な branch-local artifact/dossier として扱ってよい。
- `.yoi/memory`、local/runtime state、logs、locks、secret-like files を child worktree に作らない。
- intent / requirements / acceptance criteria / binding decisions / invariants / implementation latitude / escalation conditions を読んでから実装する。
- 実装ファイルの探索、既存コード読解、局所的な tactic 選択は、intent packet の implementation latitude 内で行ってよい。
- 指定された build / test / format を実行する。
- ticket 要件外または binding decisions/invariants 外の設計変更、依存関係追加、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 を読まずに判断できるよう、以下を整理する。
  - 変更の概念モデル
  - recorded intent / binding decisions / invariants / implementation latitude / acceptance criteria / explicit escalation conditions との対応
  - binding decisions / invariants 違反の有無
  - 旧概念・禁止語彙・不要な互換層の残存
  - 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 は main workspace の Ticket 完了処理 commit、最終 review/approval/close をしない。child worktree 側には branch-local dossier や実装証跡を残してよい。
- orchestrator は review 時に commit 粒度も確認する。
- 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。

## Review → 修正 → 完了の標準形

### Approve

reviewer が approve し blocker が残っていない場合、明示的な standing policy として merge / validate / close / cleanup まで進める。migration boundary、runtime refresh boundary、未解決の human gate が明示されている時だけ、merge-ready dossier で止める。

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 を渡さない。parallel Coder Pod は別 worktree と narrow write scope を持つ。
- parent / orchestrator は coder の write scope 配下を直接編集しない。
- reviewer は read-only を基本にする。明示的に別 scope を与える判断がない限り、review artifact を書かせる場合も ticket artifacts など限定 scope にする。
- independent queued Ticket は、blocking relation/dependency がなく、`do_not_parallelize` や relevant `conflicts_with` がなく、source/write surface が disjoint または conflict risk が小さく機械的で、coder/reviewer follow-up capacity があり、workspace records を side effect 前に commit でき、別 worktree/branch/scope を切れる場合に並列開始を優先する。
- 依存関係がある ticket、同一 migration boundary や同一 schema/tool/panel surface を大きく触る ticket、または reviewer/coder bottleneck がある ticket は、土台 branch を merge してから次 worktree を切るか、bounded defer reason を記録して idle にする。
- capacity が見えるのに queued Ticket を開始しない場合、dependency / conflict / capacity / missing planning decision / dirty workspace / reviewer-coder bottleneck / migration boundary / human gate のいずれかを bounded reason として Ticket thread または `TicketOrchestrationPlanRecord` に残す。
- parallel に走らせた Pod の完了通知は取りこぼしうるため、`ReadPodOutput` と worktree 状態で確認する。
- この節は自動 scheduler、background runner、resource graph solver、automatic queue drain loop を導入しない。parallel start は明示的な routing/acceptance の結果であり、unqueued Ticket を開始する根拠ではない。

## 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 ...
- yoi ticket 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/ticket-intake-workflow`、`$user/ticket-orchestrator-routing`、または別の設計相談で扱う。

- ユーザー依頼を Ticket 化すること。
- Ticket の next action を分類すること。
- QA feedback / AI feedback を Ticket / report / workflow に落とす判断。
- 長期 maintainer loop / scheduler / LeaseStore の設計。
- reviewer Pod の品質評価を機械的に採点する仕組み。
