flow-planner

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 から

# flow-planner を計画役に指定
agent-flow run "<要求>" --planner flow-planner

# 設定ファイルで既定に
# agent-flow.yaml:
#   planner: flow-planner

スクリプト直接呼び出し

# 全段パイプライン（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（コンポーネント特定・依存分析）を内包。

出力:

{
  "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-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）

--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   # 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、失敗時自動細分化（将来フック）