Flowsmith
KIKAIKAYA/flowsmith
Orquestra workflows de IA em YAML, retoma de interrupções, custa pouco.
Ver no GitHubOrquestrador de workflows para agentes Claude declarados em YAML único, com capacidade de retomar de pontos de interrupção. Implementa máquinas de estado com checkpoints linha-a-linha, gates mecânicos, loops com limite e difusão de lógica de decisão entre agentes.
Instalação
npx convez-ai KIKAIKAYA/flowsmith1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Processos de longa duração com 100+ iterações sem perda de progresso
- Fluxos com aprovação/rejeição em loop (survey → review → remake)
- Análise em lote com rastreamento de custo por etapa
- Migrações e refatorações assistidas (legado → novo código)
Veredito

Skill maduro (v5) com validação em carga real (160 arquivos, 15 etapas). Resolve 3 problemas práticos (sessão morrendo, autoavaliação LLM, falta de observabilidade). Design sólido com limites estruturais contra loops infinitos e decisões baseadas em máquina, não inferência. Limitação conhecida: logs não rastreiam custo com exatidão ainda (roadmap: migrar motor para código).
README
A tradução para o português deste README ainda está na fila.
flowsmith
AI エージェントの多段ワークフローを 1 つの YAML で宣言し、中断しても続きから動かすための Claude Code 向けオーケストレーション Skill。
flow(ワークフロー)を smith(鍛冶屋)のように打って仕上げる、という名前です。
steps:
- id: survey # 作る(make)
- id: review_gate # 作って検査、不合格なら差し戻し(make-check)
- id: accept # 判定して分岐、ダメなら前工程へ(branch)
- id: report # 仕上げ
なぜ作ったか
実務で AI エージェントに長い作業をさせると、毎回同じ 3 つの壁に当たります。
- セッションが死ぬと全部やり直し。 200 件の反復処理の 150 件目で切れたら、150 件を捨てるのか
- 「できました」が信用できない。 LLM の自己申告合否は、合っているときと合っていないときがある
- どこにいくらかかったか分からない。 終わってみたらトークンが溶けている
flowsmith はこの 3 つに対する設計回答です:状態は全部ディスクへ・合否はエンジンが機械的に判定・ ステップごとにコストを記録。
実績 — 実負荷での完走例
migration-factory の survey-unit (レガシー現状調査・15 ステップ)を JPetStore 6(160 ファイル / 15,007 行)に対して実行:
- コールドスタートで全 15 ステップ完走(事前文脈なしの新規セッション、約 35 分)
- 途中 2 回中断 → 2 回とも続きから再開(完了済みステップはスキップ)
- レビューループが実動:2 ステップが round 1 不合格 → 差し戻し → round 2 合格
- 出力: CSV 17 本 + 二層報告書。証跡(実行ログ・全レビュー表)込みで examples/jpetstore に公開
設計判断
| 判断 | 理由 |
|---|---|
| 1 フロー = 1 YAML | 小さなワークフローほど設定ファイルの分散が痛い。全体像は常に 1 ファイルで掴めるべき |
| 合否はエンジンが決める | checker は観点ごとの判定(verdicts)を構造化して返すだけ。エンジンが pass 条件を機械適用する。LLM の「自己申告の合格」は使わない |
| 二層検査 | 機械ゲート(ファイル存在・必須見出し・行数・表の行数・上流との件数照合)が先、LLM レビューは後。機械で落とせるものを LLM に回さない |
| チェックポイントは行単位 | 反復処理は 1 行終わるたびに状態を書く。中断後は未完了行だけ再開 |
| 行き詰まったら止まる(seized) | 解析不能・再試行上限超過は推測で進まず停止し、「何が・何回・なぜ通らないか」のサマリーを添えて人間に裁定を返す。黙って間違った道を進むほうが、止まるより百倍高くつく |
| 差し戻しは明示する | 判定理由を「参考情報」として渡すと、作業者はそれを現状肯定と誤読する(実験で実証済み)。「これは差し戻しである・変更不要という結論は禁止」と明示して初めて直る |
| 無限ループは構造的に塞ぐ | 戻りジャンプ・反復・レビューすべてに上限があり、超過は必ず seized。「いつまでも回り続ける」状態が存在できない |
| 質問は推測より安い(ask) | 指示が致命的に曖昧なとき、エージェントは推測せず人間に質問して回答を得て続行する。質問上限超過は brief 側の欠陥とみなして停止 |
| コスト可観測 | ステップ・行ごとに所要時間とトークンを JSONL に記録。終わってから「どこが高かったか」が分かる |
Quick Start
# 1. インストール:skills/flowsmith-run/ を ~/.claude/skills/ にコピー
# 2. このリポジトリのルートで実行
claude
> /flowsmith-run examples/hello/flow.yaml
2 ステップの最小フロー(ファイル一覧 → サマリー生成)が実行され、flowsmith-out/ に成果物が出ます。
中断したら同じコマンドをもう一度 — 続きから再開します。
ステップタイプ
| type | 動き |
|---|---|
make | 生産のみ。foreach で表駆動の行単位反復(行単位で再開可能) |
make-check | maker → 機械ゲート → checker → エンジンが合否判定。不合格は指摘付きで差し戻し、上限超過で停止 |
branch | arbiter が yes / no を判定し、エンジンがルーティング。戻りジャンプ+判定理由の引き継ぎ(carry)対応 |
loop | done / again の条件反復。上限超過で停止 |
フロー定義の書き方は docs/schema.md、 実行時ファイル(state / ログ)の仕様は docs/runtime.md を参照。
実行時ファイル
${OUT}/.flowsmith/
├── state.json # 断点(ステップ完了・行完了・レビューラウンドごとに更新)
├── run.jsonl # 流水ログ(開始/終了/差し戻し/再開/停止、所要時間・トークン)
└── runs/ # 完了フローのアーカイブ
${OUT}/reviews/ # checker のレビュー表(全ラウンド分が残る)
ステータス
v5。 4 ステップタイプ / 機械ゲート 5 種 / ステップ・行単位のチェックポイント再開 / 熔断(レビュー・反復・戻りジャンプ各上限)/ フロー目的の全エージェント共有(goal)/ 臨時質問(ask)— 実装済み。上記の実負荷完走で一通りの経路を検証済み。
エンジン本体は現在 Skill(プロンプト)として実装されています。この実装方式の既知の制約として、 実行ログの時刻・トークン記録が不正確です(プロンプト実装のエンジンは正確な計時・集計を 行えない——実負荷検証で判明)。設計の検証が済んだ段階で、決定的な部分 (YAML 解析・状態管理・ゲート判定・ルーティング・ログ記録)をコード化する計画で、 この制約はその直接の根拠になっています。
License
MIT © kikaikaya