convez.ai
SkillAutomaçãoAvançado
KIKAIKAYA

Flowsmith

KIKAIKAYA/flowsmith

Orquestra workflows de IA em YAML, retoma de interrupções, custa pouco.

Ver no GitHub
InicialPluginScore · de 0 a 100

Orquestrador 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/flowsmith

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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 つの壁に当たります。

  1. セッションが死ぬと全部やり直し。 200 件の反復処理の 150 件目で切れたら、150 件を捨てるのか
  2. 「できました」が信用できない。 LLM の自己申告合否は、合っているときと合っていないときがある
  3. どこにいくらかかったか分からない。 終わってみたらトークンが溶けている

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-checkmaker → 機械ゲート → checker → エンジンが合否判定。不合格は指摘付きで差し戻し、上限超過で停止
brancharbiter が yes / no を判定し、エンジンがルーティング。戻りジャンプ+判定理由の引き継ぎ(carry)対応
loopdone / 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

Ver o original no GitHub

Bom para

Relacionados