flow-planner

# flow-planner — agent-flow 向け高精度タスク分解・戦略選択 ## 概要 agent-flow の orchestrator がタスクグラフを生成する際に、3段階パイプラインで 高精度な分解と最適な戦略選択を行うスキル。 既存の `decomposition` スキルのタスク分解能力を内包しつつ、 agent-flow の7パターン戦略（記事の6パターン＋ agent-flow 追加の map-reduce）に特化した計画を生成する。 ## アーキテクチャ ``` 要求 → [Phase 1: 要求分析] → [Phase 2: 戦略選定] → [Phase 3: グラフ生成] → タスクグラフ ↑ ↑ ↑ (分解軸の特定) (パターンDB+ (テンプレート駆動 WBS的分析) Decision Matrix) + 制約検証) ``` 単一LLM呼び出しでの一発生成（現行 `plan_strategy_agent`）を、 制約付きの3フェーズに分割して各段の精度を向上させる。 ## 利用方法 ### agent-flow CLI から ```bash # flow-planner を計画役に指定 agent-flow run "<要求>" --planner flow-planner # 設定ファイルで既定に # agent-flow.yaml: # planner: flow-planner ``` ### スクリプト直接呼び出し ```bash # 全段パイプライン（agent-flow が内部で呼ぶ） python3 .github/skills/flow-planner/scripts/plan.py "<要求>" \ [--model <model>] [--review auto|true|false] [--granularity auto|coarse|fine|finest] \ [--context <text>] [--tier <tier>] [--split-directive <text>] ``` `--context`（案 H・オプトイン）: agent-flow が渡すプロジェクト文脈（charter/rules.md/ リポジトリ理解のスナップショット）。agent-project の `stable_prefix` 設定が有効なとき、 これらは要求本文から外されるため、分解の質を落とさないよう Phase 1（分析）・Phase 3 （グラフ生成）のプロンプト先頭へこの内容を前置する。未指定なら従来どおり要求本文だけを見る。 `--tier`（オプトイン）: 実行ティア（agent-control の `workloads.flow.tier`。agent-flow が 渡す）。`basic` のときは (1) `granularity: auto` を finest へ倒す（明示指定は優先）、 (2) Phase 3 へ「1 ノード = 1 短手順・goal に対象/成果/確認方法を明記」の分解指示を足す、 (3) `review: auto` を常時有効へ倒す（basic の成果を無検証で集約しない）。予算逼迫の緊急時に 普段は任せない役割へ basic ワーカーを投入するときの、計画側のお膳立て。空なら従来どおり。 `--split-directive`（オプトイン）: 分割の単位（どこで切るか）の指示文。**値名ではなく解決済みの テキスト**を agent-flow が渡し、Phase 3 のプロンプトへそのまま差し込む。`--tier` の指示文と違って スキル側に文面の複製を置かないのは、正典が agent-tuning の手法カタログ（`split-policy-<policy>`）に あり、対象リポジトリの `.agents/methods/` による差し替えをこの経路にも届けるため——スキルが 自前の文面を持つと、差し替えがこの経路にだけ効かなくなる。空なら従来どおり。 ## 3段階パイプライン ### Phase 1: 要求分析（Request Analysis） 要求を構造化し、戦略選定に必要な属性を抽出する。 `decomposition` スキルの Step 1–2（コンポーネント特定・依存分析）を内包。 **出力**: ```json { "intent": "要求の本質（1文要約）", "decomposition_axes": ["分割軸1", "分割軸2"], "subtasks": ["サブタスク1", "サブタスク2"], "data_flow": "static|dynamic|unknown", "quality_focus": "speed|accuracy|coverage|exploration", "complexity": "simple|moderate|complex", "estimated_steps": 6, "granularity_target": "fine", "constraints": ["制約1"], "domain_hints": ["ヒント1"], "enumerable": { "same_procedure": true, "independent": true, "per_target_deliverable": true, "target_kind": "API エンドポイント", "how_to_enumerate": "src/routes/**/*.ts のルート定義を走査", "estimated_count": null } } ``` - `data_flow`: 入力データが事前確定（static）か実行時に判明（dynamic）か - `quality_focus`: 速度重視か精度重視か網羅性重視か探索重視か - `decomposition_axes`: WBS的に分割する観点（機能別、フェーズ別、データ別等） - `estimated_steps`: 最小限必要な作業ステップ数の見積り（整数。読めなければ null）。 Phase 3 へ目安として渡すだけで、**成果ノード数のレンジは上書きしない** - `granularity_target`: complexity（または明示 `--granularity`）から決定的に導出 - `enumerable`: 列挙駆動の判定材料（下記） #### 列挙駆動の 3 条件（`enumerable`） 「同一手順を多数の独立した対象へ繰り返す」タスクかを、**3 条件を個別に**判定する （`is_enumerable` はその AND。単一フラグにしない）: | 条件 | 意味 | |------|------| | `same_procedure` | 対象ごとに手順が同一か | | `independent` | 対象間に依存が無いか（先の結果が次に要らないか） | | `per_target_deliverable` | 成果が対象単位で完結するか | ファイル・関数・モジュールは「見ようと思えば常に列挙可能」なので、単一フラグを LLM に判定させると**単一成果物の実装まで map-reduce へ倒れる**（他パターンを侵食する 単一戦略への崩壊）。新機能実装・バグ修正は多数のファイルに触れても後ろ 2 条件が偽になる。 `estimated_count` は要求から確定できるときだけ整数、不明なら null（推測で埋めない）。 ### Phase 2: 戦略選定（Strategy Selection） Phase 1 の分析結果から最適なパターン（複合含む）を選ぶ。 **Decision Matrix**: 属性とパターンのスコアリングで候補を2-3に絞り、 LLMには「候補から最適を選べ」と制約付き選択をさせる。 **列挙駆動のハイブリッド発動**（Matrix の上に乗る決定的ルール）: | 状況 | 発動 | 挙動 | |------|------|------| | 3 条件全充足 ＋ 件数 > 3 が確定 | `force` | Matrix のスコアに関わらず `patterns` の先頭へ map-reduce を入れる（**追加**であって排他ではない。複合は潰さない） | | 3 条件全充足だが件数不明 | `boost` | map-reduce へ +5 加点し、最終判断は LLM に委ねる | | 条件のどれかが偽 / 件数 ≤ 3 | `off` | **何もしない**（従来経路と完全に同一＝回帰なし） | 件数は probe（決定的走査の実測）を Phase 1 の見積りより優先する。 Matrix だけだと、リポジトリ内に静的に存在する対象一覧（API 群・ファイル群）は `data_flow=static` と判定されて fan-out-and-synthesize に吸われ、対象単位のノードが 生まれない。発動根拠は `strategy.reason` と `strategy.enumeration` に必ず残す （観測できないと誤爆に気づけない）。 **列挙 probe**（`--probe-root`、既定 cwd。LLM を呼ばない）: `how_to_enumerate` / `target_kind` からグロブ（`src/routes/**/*.ts`）を、無ければ ディレクトリパスを取り出して実際に走査し件数を数える。依存物（`node_modules` 等）と 隠しディレクトリは除外。**0 件は「不明」として扱う**——計画時点ではワークスペースが 手元に無いことがあり、0 を「対象なし」と読むと列挙駆動を誤って止める。 列挙そのものは実行時に split が行うので、probe は判定材料に徹する。 **出力**: ```json { "patterns": ["fan-out-and-synthesize", "adversarial-verification"], "parallelism": 4, "reason": "選定理由", "composite_template": "fanout-then-verify", "review": true } ``` ### Phase 3: グラフ生成（Graph Construction） 選定した戦略をタスクグラフに変換する。テンプレート駆動で構造を保証し、 LLMには各ノードの goal 具体化のみを依頼。 列挙駆動が `force` / `boost` のときは、split の goal に**実行時の列挙手順**を埋め込ませる （「実際に走査して一覧を作る・推測で列挙しない」を明記）。`force` のときは決定的ゲートで **split の存在**も検査し、無ければ 1 回だけ作り直す——強制したのに split が出ないと、 対象単位の展開が起きず「まとめて 1 ノード」へ戻ってしまう。 **出力**: agent-flow 互換の `{strategy, tasks}` 形式。Phase 3 が LLM へ求める出力契約は **JSON オブジェクト `{"tasks": [...]}`**（裸の配列も受ける）。オブジェクトで縛るのは、ollama の JSON モード（`--format json`）が配列を返せないため——配列契約のままだと agent-ollama 経路の Phase 3 は構造的に必ず落ち、agent-flow は黙って組み込み planner → stub へ縮退する （`planner_eval` 2026-08-23 で発見・修正）。 ## パターンカタログ `patterns-catalog.yaml` に以下を定義: - 各パターンの詳細な使用条件（when_to_use / when_not_to_use） - 典型的な並列数レンジ - 組み合わせ可能なパターン - ユースケース別推奨パターン（複合テンプレート） - バリアント（基本パターンの実行モード。`variants`） ## バリアント（pilot-then-batch / 見本先行） `variants.pilot-then-batch` は **map-reduce の実行モード**で、同様手順を多数の対象に 繰り返すとき「まず 1 件(pilot)を走らせて検証・レビューで指示を固め、その定義で残りを 生成・実行する」。全件を一斉に流して全滅する無駄を避ける。2 実装がある: - **agent-flow `exemplar_first`**（自動ゲート）: split→pilot map→verify ゲート→残り map→reduce。 設定 `exemplar_first: true` か `--exemplar-first` で有効化。 - **agent-project `cohort`**（人ゲート）: pilot に `review:human`。人が approve(+feedback) で指示を固めてから残りを生成。`enqueue --cohort-items a,b,c` か charter プランナーが `{title, verify, cohort_items:[…]}` で自動生成。 **バリアントは `patterns` ではない**（`patterns` 配列には書かない）。基本パターン （map-reduce）を選んだうえで、繰り返し量産・見本先行が要るときに上記フラグ/cohort で 有効化する選択肢。詳細な when_to_use / when_not_to_use / 例示 / 適用具体例は `patterns-catalog.yaml` の `variants` を参照。 ## ユースケース別推奨戦略 要求の「型」から複合テンプレート（`patterns-catalog.yaml` の `composites`）と その正規パターン構成を引くための索引。**表に現れる語はすべて `patterns-catalog.yaml` に実在する正規名のみ**で、Phase 2 はこの語彙の外に出ない。 トリガキーワードは `use_case_mapping` のキーワードと同じものを使うため、 人間が読む本表と Phase 2 の機械的マッチングは常に一致する。 | ユースケース | トリガキーワード（例） | 複合テンプレート | 正規パターン構成 | |-------------|----------------------|----------------|----------------| | マイグレーション・大規模リファクタリング | マイグレーション, 移行, リファクタリング, 一括変更 | `migration-pipeline` | fan-out-and-synthesize → adversarial-verification → loop-until-done | | 根本原因の調査・デバッグ | 原因, 根本, なぜ, 障害, root cause, debug | `root-cause-analysis` | generate-and-filter → adversarial-verification → loop-until-done | | 深いリサーチ・多観点調査 | リサーチ, 調査, 深く, research, investigate | `deep-research` | fan-out-and-synthesize → adversarial-verification | | 多観点の並列レビュー（精度ゲート） | レビュー, 監査, 観点, セキュリティ, パフォーマンス, 可読性 | `fanout-then-verify` | fan-out-and-synthesize → adversarial-verification | | 大規模トリアージ・振り分け | トリアージ, 振り分け, 分類, 仕分け, triage, classify | `classify-then-fanout` | classify-and-act → fan-out-and-synthesize | | 大量アイテムの順位付け・ソート | ソート, 順位, ランキング, pairwise, sort, rank | `tournament-rank` | tournament（ペアワイズ比較。候補生成は伴わない） | | デザイン・命名・案の探索 | デザイン, 命名, ネーミング, 案, design, naming | `generate-filter-tournament` | generate-and-filter → tournament | | 軽量 Eval（実行+採点+改善） | eval, 評価, 採点, ベンチ, grade, benchmark | `lightweight-eval` | fan-out-and-synthesize → adversarial-verification → loop-until-done | | 件数不定の一覧・コレクション処理 | それぞれ, 各, ごとに, 一覧, 件 | （単体パターン） | map-reduce | | 完了条件付きの反復改善 | テスト通過, lint, 型チェック, 緑, 反復, until done | （単体パターン） | loop-until-done | ### 語彙ロック（決定がブレないための規約） ユースケースとパターンの取り違えを防ぐため、Phase 2 は次の閉じた語彙だけを使う。 派生語・同義語の即興導入を禁じることで、戦略選定の再現性を保証する。 - **`patterns` に書ける名前は7つの基本パターンのみ**: `fan-out-and-synthesize` / `adversarial-verification` / `classify-and-act` / `generate-and-filter` / `tournament` / `loop-until-done` / `map-reduce` - **`composite_template` は `composites` のキーか `null`**: `migration-pipeline` / `root-cause-analysis` / `deep-research` / `fanout-then-verify` / `classify-then-fanout` / `tournament-rank` / `generate-filter-tournament` / `lightweight-eval` - **`synthesize` / `generate` / `verify` / `judge` / `filter` / `reduce` / `split` / `map` / `classify` / `work` はノード種別（`kind`）であって パターンではない**。`patterns` には書かない。 旧版にあった "panel of verifiers"・"tournament with rubric"・"synthesize" 単体 のような派生語は、対応する正規名（順に adversarial-verification・tournament・ fan-out-and-synthesize）へ読み替える。 ### 該当ユースケースが無いとき 表のどれにも当てはまらない要求は、**戦略を即興で作らず** Phase 2 の Decision Matrix（`data_flow` / `quality_focus` / `complexity` のスコアリング）で 上位の基本パターンを 1–2 個組み合わせる。集約パターン （fan-out-and-synthesize / map-reduce）を含む場合は、統合前に検証 gate （adversarial-verification）を挟むかどうかを `review` で判断する。 ## タスク粒度（内側 DAG） 自律開発では二層で粒度を分ける（設計: `docs/plans/2026-07-25-flow-planner-granularity-design.md`）: | 層 | ツール | 粒度 | 本スキル | |----|--------|------|----------| | 外側 | agent-project backlog | INVEST + verify | 改修しない | | 内側 | agent-flow / flow-planner | スコープ上限 | **本スキルが制御** | ### 操作定義（成果ノード: work / generate / map） - 1 モジュール相当（または明示された単一結合点） - 想定変更 ≤ 約 30 行 - goal 先頭に `[scope]` と `[out_of_scope]` を付ける ### complexity → 目標粒度（`granularity: auto` 時） | complexity | target | work 系ノード数 | |------------|--------|-----------------| | simple | coarse | 1–3 | | moderate | fine | 3–8 | | complex | finest | 6–12（上限16） | `--size small|medium|large`（規模の目安。agent-flow が渡す）があるときは、ノード総数を 5 / 10 / 50 未満に収め、成果ノードの上限を「目安 − 2」へ下げる。粒度が auto なら下限を 1 にし、 「約 30 行」の上限を外して「1 つの担当が 1 回で終えられる範囲」とする（明示の粒度と `--tier basic` では従来どおり）。未指定・`unrestricted` なら従来どおり。 `--granularity coarse|fine|finest` の明示指定が優先。Phase 3 後に決定的ゲート（個数・scope・重複）で 不合格なら最大1回再生成する。verify コマンドの有無は検査しない。 ## decomposition スキルとの統合 本スキルは `decomposition` スキルの以下の能力を Phase 1 に統合している: - **コードベース探索**（Step 1）: プロジェクト構造の把握 - **コンポーネント特定**（Step 2）: 依存関係・並列化の分析 - **不明点の整理**（Step 3）: 制約の洗い出し 違い: - `decomposition`: 人間が実行する ToDo リストを生成（20-60分粒度） - `flow-planner`: agent-flow worker が実行するタスクグラフを生成（上記スコープ上限） ## 設定 agent-flow の設定ファイル（`agent-flow.yaml`）で planner を指定: ```yaml planner: flow-planner # flow-planner | agent | stub granularity: auto # auto | coarse | fine | finest reduce_width: 8 # 集約1つが受け持つ依存の上限（超過分は中間集約へ畳む） ``` または CLI で `--planner flow-planner` / `--granularity auto`。 スクリプト直接呼び出しでは `--probe-root <dir>` で列挙 probe の走査起点を指定できる（既定 cwd）。 `reduce_width` は agent-flow 側（実行時 fan-out の展開）の設定で、列挙駆動と対になる。 対象単位へ正しく展開できるほど集約への入力が増えるため、幅を超えた分は中間集約へ畳んで 木構造にする（単段集約は規模で破綻する）。幅以下なら従来と同一構造。 ## 注意事項 - エージェント CLI（既定 kiro-cli）が必要（LLM呼び出しに使用）。`--agent-cli` は `agents/<name>.json` の定義名を受け付ける（組み込み 4 種に限らない）。argv の組み立ては agentcore へ委譲するので、agent-flow から呼ばれるときは PYTHONPATH 経由で解決される - 3 フェーズはいずれも材料をプロンプトで受け取って JSON を返すだけなので readonly（道具なし）で 呼ぶ。道具付きだとツールループ型の CLI が契約どおりの JSON 応答を規約違反として蹴る - 3段パイプラインのため、現行 `agent` planner より LLM 呼び出し回数が多い（2-3回、ゲート再生成で+1） - フォールバック: いずれかの段で失敗した場合は現行 `plan_strategy_agent` に倒す （呼び出し側がログと `strategy.reason` に理由を残す） - 非目標: 内側 verify 必須化、分解批評 Phase 3.5、失敗時自動細分化（将来フック）