# Flow Planner

> agent-flow の orchestrator 向け高精度タスク分解・戦略選択スキル。要求を分析し、7パターン（map-reduce 含む）＋複合パターンから最適な戦略を選定し、実行可能なタスクグラフを生成する。decomposition スキルの分解能力を内包し、agent-flow の `--planner flow-planner` で利用する。

- Skill: `ynitto/flow-planner` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ynitto/flow-planner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ynitto/flow-planner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: ynitto (https://skillmd.com/u/ynitto)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ynitto/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） |

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