| name | flow-planner |
| description | agent-flow の orchestrator 向け高精度タスク分解・戦略選択スキル。要求を分析し、7パターン（map-reduce 含む）＋複合パターンから最適な戦略を選定し、実行可能なタスクグラフを生成する。decomposition スキルの分解能力を内包し、agent-flow の `--planner flow-planner` で利用する。 |
| metadata | {"version":"1.0.1","tier":"experimental","category":"planning","tags":["agent-flow","orchestration","task-decomposition","strategy-selection","dynamic-workflow","planning"]} |
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 から
agent-flow run "<要求>" --planner flow-planner
スクリプト直接呼び出し
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（コンポーネント特定・依存分析）を内包。
出力:
{
"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"
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 は判定材料に徹する。
出力:
{
"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-reducecomposite_template は composites のキーか null:
migration-pipeline / root-cause-analysis / deep-research /
fanout-then-verify / classify-then-fanout / tournament-rank /
generate-filter-tournament / lightweight-evalsynthesize / 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） |
--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 を指定:
planner: flow-planner
granularity: auto
reduce_width: 8
または 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、失敗時自動細分化（将来フック）
