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

21 KiB
Raw 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、validation、merge-ready dossier 作成に責任を持つ。
  • 最上位 orchestrator は、コードを直接理解し切ることではなく、委譲した intent / 要件 / invariant に沿って下位 orchestrator が完了まで運んだかを acceptance する。

Pod coordination model

基本形は以下。

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

標準形:

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 で動く場合でも、implementation worktree は Orchestrator cwd ではなく recorded original workspace root の .worktree 配下に作る。
    • merge-completion は recorded merge target workspace で行い、Orchestrator cwd を merge target とみなさない。
    • $user/worktree-workflow に従い <original-workspace-root>/.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: 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/approval/close は 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. merge-ready dossier 作成

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

  8. merge / lifecycle

    • 最上位 orchestrator または人間の許可を持つ orchestrator が recorded merge target workspace へ merge する。
    • Ticket を完了処理して commit する。TODO cleanup が対象 Ticket の明示要件なら recorded merge target workspace で行う。
    • recorded merge target 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 は recorded Ticket backend の 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. recorded merge target workspace で git merge --no-ff <branch> する。
  5. Ticket を完了処理して commit する。TODO cleanup が対象 Ticket の明示要件なら同じ merge target workspace で行う。
  6. recorded merge target 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 の標準形

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