Agent Flow

agent-flow — 分散 Dynamic Workflow CLI スキル

agent-flow CLI（tools/agent-flow/agent-flow.py）を呼び出して、要求を動的にタスク分解 → 複数ワーカーで分散実行 → 結果を評価して再計画 → 統合する。LLM 実行は kiro-cli が既定 （設定 agent_cli で claude / copilot / codex ヘッドレスへ切替可）。 kiro-cli が無い環境では --planner stub --executor stub で挙動を確認できる。

前提

• Python 3.11+（標準ライブラリのみ）。git は分散モード（--git）で必要。実運用には kiro-cli。
• 未インストールなら python3 tools/agent-flow/agent-flow.py … で代用。インストール済みなら agent-flow …。

KF="agent-flow"   # 未インストールなら KF="python3 tools/agent-flow/agent-flow.py"

ロール選択ガイド

よく使う呼び出し

単発実行（既存 run-id なら自動で再開）

$KF run "要件整理; API設計; テスト" --workers 3
$KF run --run-id <run-id>                      # 中断した run を再開
# kiro-cli 無しで動作確認:
$KF run "a; b; c" --planner stub --executor stub

要求の書き方でパターン/並列数が変わる:

• ; 区切り＝並列、->＝逐次依存（例 "setup -> build -> test; docs"）。
• xN / 並列N で並列数を指定。
• 「分類して振り分け」→ classify-and-act、「最良/tournament」→ tournament、 「候補/フィルタ」→ generate-and-filter、「検証/レビュー」→ adversarial、 「繰り返し/通るまで」→ loop-until-done、「それぞれ/各/一覧」→ map-reduce（データ駆動 fan-out）。
• --review で統合（synthesize/reduce）前に検証 gate を挟む。
• --max-fanout N（既定50）でデータ駆動 fan-out の上限。--max-iterations N（既定3）で再計画上限。

デーモン（オンデマンド起動・推奨）

daemon は同一バスにつき 1 つだけ起動する（既に稼働中なら何もせず終了＝冪等）。 「デーモンを起動して」と言われたら、まず起動コマンドを実行してよい（重複起動の心配は不要）。

submit でタスクを投入する手順（daemon の確保 ＋ git 自動設定）

submit は要求を inbox に置くだけで、実際に実行するのは daemon。したがって submit の前に必ず daemon を確保する（稼働確認は不要 — daemon は冪等で、既に動いていれば 自動でスキップされるので、そのまま起動コマンドを実行すればよい）。さらに カレントディレクトリが git リポジトリなら、その origin（GitHub）リモートを共有バスにして起動し、 複数 PC でそのまま分散できるようにする。

# 1) バスモードを決定: git リポジトリ内なら GitHub 共有バス、そうでなければローカル
if BUS_REMOTE=$(git remote get-url origin 2>/dev/null); then
  REPO=$(basename -s .git "$(git rev-parse --show-toplevel)")
  # 専用ブランチ agent-flow-bus を使い、プロジェクトの main/作業ブランチには一切 push しない。
  # クローンはリポジトリ外（~/.agents/flow-clones/<repo>）に置き、作業中のリポジトリを汚さない。
  BUS="--git $BUS_REMOTE --git-branch agent-flow-bus --bus $HOME/.agents/flow-clones/$REPO"
else
  BUS="--bus ./bus"                             # git 外: ローカルバス（既定。agent-project の <root>/bus と同じ）
fi

# 2) daemon を確保（冪等 — 既に稼働していれば自動スキップ。そのまま実行してよい）
$KF $BUS daemon --max-workers 4 &

# 3) 要求を投入 → run-id 取得 → 監視 → 最終結果
RID=$($KF $BUS submit "<要求>")
$KF $BUS status --run-id "$RID" --follow --until-done
$KF $BUS result --run-id "$RID"

同一バスで揃える: daemon/submit/status/result は必ず同じ $BUS フラグで呼ぶ （別バスを指すと投入した要求が拾われない）。毎回フラグを渡す代わりに、リポジトリの ./.agents/agent-flow.yaml に git / git_branch / bus を書けば全コマンドが自動で同じバスを使う （優先順位 CLI > 設定ファイル > 既定）。git モードは初回に agent-flow-bus ブランチを origin へ 作成・push する（main は変更しない）。

分散（複数 PC）

上の手順で git リポジトリ内なら自動で GitHub 共有バスになる。他の PC は同じリポジトリで 同じ手順を実行するだけで同一バスに参加する。リポジトリ外から明示的に指定する場合:

$KF --git <repo-url> --git-branch agent-flow-bus daemon --max-workers 4 &   # PC ごとに（冪等）
$KF --git <repo-url> --git-branch agent-flow-bus submit "<要求>"

状態確認・掃除

$KF status --run-id <run-id>      # 公式風ダッシュボード（進捗バー/エージェント状態/アクティビティ）
$KF status --follow               # ライブ監視（tmux ペイン向け）
$KF status --list                 # run 一覧
$KF gc --older-than 7 --status done --dry-run   # 古い done を掃除（まず dry-run）

最終結果の提示

このスキルはワークフローの最終結果を提示する役割も担う。状態確認を求められて （「結果を見せて」「終わった？」「成果物は？」等）対象 run が完了しているなら、 進捗ダッシュボードだけでなく最終結果そのものを探し出して提示する。

$KF result                        # 最新 run の最終結果（run_id 省略で自動選択）
$KF result --run-id <run-id>      # 指定 run の最終結果
$KF result --json                 # 機械可読（final_nodes に sink ノードの全文 output/data）

• 「最終結果」＝集約／末端（sink）ノードの全文出力を自動特定して返す。 集約 kind（synthesize / reduce / judge / filter）があればそれを優先し、無ければ 他から依存されない末端ノードを採る（例: fan-out→synth、tournament→judge、 map-reduce→reduce）。status の ├─ result 欄にも要約が出るが、全文は result。
• 未完了の run に対しては「まだ完了していません（X/Y 完了）」と知らせ、status --follow を案内する。確定済みの成果があれば参考として表示する。

判断指針: 進捗・経過を知りたい → status。出来上がった成果が欲しい → result。 完了済み run について「結果」を問われたら result を使う。

環境ごとの設定

環境依存値（bus / git / planner / executor / max_workers / poll / lease 等）は設定ファイルに置ける （優先順位 CLI > 設定ファイル > 既定）。検索順: --config → ./.agents/agent-flow.{yaml,yml,json} → ~/.agents/agent-flow.{yaml,yml,json}。サンプル: tools/agent-flow/agent-flow.yaml.example。

使い分けの指針

• すぐ結果が欲しい単発タスク → run（フォアグラウンドで待機、完了で自動停止）。
• 継続的に要求を捌く / 複数 PC で回す → daemon を常駐させ submit で投入。
• 長時間タスク → --lease を実行時間より十分大きく（実行中はハートビートが自動延長）。
• 動作確認やデモは必ず --planner stub --executor stub（エージェント CLI を消費しない・即時）。

詳細仕様は tools/agent-flow/README.md と docs/designs/agent-flow-design.md を参照。