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

22 KiB
Raw Permalink Blame History

description model_invokation user_invocable requires
worktree と sibling の coder / reviewer Pod を使い、下位 orchestrator が concrete 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、実装前の 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、orchestration branch への integration、validation、Ticket 記録、child worktree cleanup に責任を持つ。
  • 最上位 orchestrator は、コードを直接理解し切ることではなく、委譲した intent / 要件 / invariant に沿って下位 orchestrator が完了まで運んだかを acceptance する。

Pod coordination model

基本形は以下。

最上位 orchestrator Pod
  - 人間との会話相手
  - intent / 要件 / invariant / escalation 条件を定義
  - 複数の作業群を並列管理
  - root/original workspace での read/write/validation/cleanup/git 操作を行う
  - 原則として 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 として扱う
  - orchestration branch 上の integration 結果と残論点だけを返す

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 書き込み操作について、人間の許可がある。
  • 下位 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 を渡す。

標準形:

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 群
    • 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 を行わない。
    • Orchestrator が dedicated orchestration worktree で動く場合、作業対象は Orchestrator workspace/orchestration branch と child implementation worktree に限定する。root/original workspace は read/write/validation/cleanup/git 操作の対象ではない。
    • implementation worktree は記録済み implementation worktree root の .worktree 配下に置く。root/original workspace は配置基準としてだけ扱い、作業対象にしない。
    • implementation branch は Orchestrator workspace の current HEAD/orchestration branch HEAD から作り、reviewer approve 後は orchestration branch へ自動 integration する。
    • .yoi 自体は除外しない。tracked project records は child worktree に存在してよく、.yoi/memory と local/runtime/log/lock/secret-like paths だけを sparse checkout で除外する。

  3. coder Pod spawn

    • read scope: original workspace root 全体、または実装に必要な bounded read scope。
    • 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 ではない）
      • Orchestrator workspace / recorded Ticket backend の TODO.md / Ticket records / docs/report/ / .yoi は編集しないこと
      • child worktree 内の tracked .yoi project records は実装対象に必要な branch-local artifacts/dossiers として編集してよいが、.yoi/memory や local/runtime/secret-like files は作らないこと
      • active orchestration progress、review、integration、Ticket lifecycle update は Orchestrator workspace または recorded Ticket backend の責任として残すこと
      • 遵守すべき 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. orchestration branch integration

    • 親がコードを直接理解しなくても判断できるよう、変更の概念的説明と evidence をまとめる。

  8. integration / lifecycle

    • reviewer approve と blocker 解消を確認し、implementation branch を Orchestrator workspace の orchestration branch へ integration する。
    • Orchestrator workspace で必要な validation を実行し、Ticket thread に integration と validation の結果を記録する。
    • Ticket を完了処理して commit する。TODO cleanup が対象 Ticket の明示要件なら child implementation worktree/branch に限定して行う。root/original workspace は触らない。

coder Pod の責務

  • child worktree 内でのみ実装する。
  • root/original 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 は recorded Ticket backend の Ticket 完了処理 commit、最終 review/approval/close をしない。child worktree 側には branch-local dossier や実装証跡を残してよい。
  • orchestrator は review 時に commit 粒度も確認する。
  • 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。

Review → 修正 → 完了の標準形

Approve

reviewer が approve し blocker が残っていない場合、Orchestrator workspace の orchestration branch への integration、validation、Ticket 記録、child worktree cleanup まで自動的に進める。root/original workspace への read/write/validation/cleanup/git 操作は行わない。

  1. coder Pod / reviewer Pod を停止し、scope を回収する。
  2. orchestrator が Ticket、child worktree/branch、commits、reviewer verdict、validation evidence を確認する。
  3. 最上位 orchestrator が必要最小限の spot check を行う。
  4. Orchestrator workspace の orchestration branch で implementation branch を merge または project-agreed method で integration する。
  5. Ticket を完了処理して commit する。TODO cleanup が対象 Ticket の明示要件なら child implementation worktree/branch に限定して行う。
  6. Orchestrator workspace/orchestration branch で検証コマンドを再実行する。root/original 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 を開始する根拠ではない。

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