Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity
c2d624569c
yoi/.yoi/workflow/multi-agent-workflow.md

16 KiB
Raw Blame History

description model_invokation user_invocable requires
worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が複数 ticket の実装・外部レビュー・修正・完了準備を管理する orchestration フロー true true

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、実装前の要件同期・反証 preflight は $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 起動の前に 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 する。

階層モデル

基本形は以下。

最上位 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 の背景・意図・制約・受け入れ条件から、実装調査と局所 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 に不確定要素がある場合、ticket-preflight-workflow の結果が ticket thread に記録されている。

product / API / UX / authority / design-boundary 方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に ticket-preflight-workflow を通し、必要なら人間へ戻す。実装ファイルの探索、既存コード読解、局所的な構成選択のような bounded implementation uncertainty は、intent / binding decisions / invariants / implementation latitude / acceptance criteria / escalation conditions が明確なら coder に委ねてよい。

Intent packet

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

標準形:

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 status --short --branch
    • 対象 ticket / ticket 群
    • 関連 TODO / docs / 既存 worktree
    • preflight が必要な ticket では、ticket-preflight-workflow の分類・要件同期・critical risks

  2. worktree 作成

    • $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
      • Bash は必ず child worktree に cd すること
      • 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 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 の管理ファイルを書かない。
  • 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

  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 の標準形

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 の品質評価を機械的に採点する仕組み。