slang-workflows

███████╗██╗      █████╗ ███╗   ██╗ ██████╗
██╔════╝██║     ██╔══██╗████╗  ██║██╔════╝
███████╗██║     ███████║██╔██╗ ██║██║  ███╗
╚════██║██║     ██╔══██║██║╚██╗██║██║   ██║
███████║███████╗██║  ██║██║ ╚████║╚██████╔╝
╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝
     provable, declarative multi-agent workflows for Claude Code
     a non-LLM executor runs your typed .slang files

slang-workflows

Claude Code 内で、証明可能な .slang 駆動のマルチエージェントワークフローを実行します。

LLM を使わないステートマシン（slang executor）が MCP サーバー内で動作し、エージェントを調整します。 各エージェントは Claude Agent SDK セッションです。型付きの .slang ファイルでコラボレーションを宣言すると、モデルに調整を任せるのではなく、executor が型付き出力コントラクト、静的解析、ツールのスコープ設定、そして 証明可能な終了を強制します。最上位の Claude Code セッションは、トリガーと監視のみを行い、調整に関する判断は一切行いません。

Claude Code のネイティブな動的ワークフローもオーケストレーションをコード化します（Claude が JS スクリプトを作成します）。 slang との違いは、その構造が強制され、静的解析が可能であり、実行結果が Mermaid のトポロジー図とトレース図として表示されることです。A/B/C の直接比較については、ベンチマークをご覧ください。

由来。 .slang ワークフローエンジンは、AI エージェント向け VS Code 拡張機能である Shofer で誕生しました。決定論的な非 LLM executor は、そこで初めて構築されました。この プラグインにより、Claude Code で利用できるようになります。

設計と根拠：DESIGN.md。言語リファレンス：slang_specs.md。プライバシー：PRIVACY.md。

仕組み

flowchart TB
    You(["You"])
    CC["Claude Code<br/>top-level session"]

    subgraph server["slang-workflows · MCP server"]
        direction TB
        SL["your .slang workflow<br/>agents · stakes · contracts · converge"]
        EX["slang executor<br/>deterministic · non-LLM state machine"]
        MB[("FlowState + mailbox")]
        SL -->|"parsed once"| EX
        EX <--> MB
    end

    subgraph Agents["Agent SDK sessions — the agents your .slang declares"]
        direction LR
        A1["Agent A"]
        A2["Agent B"]
        A3["Agent …"]
    end

    You <-->|"ask · approve escalations"| CC
    CC -->|"run_workflow"| EX
    EX -->|"topology + trace diagrams"| CC
    EX ==>|"dispatch stake — one session per agent, resumed"| Agents
    Agents ==>|"typed result → output-contract check + retry"| EX
    EX -.->|"escalate @Human"| CC

    classDef brain fill:#eaeaff,stroke:#5b5bd6,stroke-width:2px;
    class EX brain;

最上位の Claude Code セッションは、トリガーと監視のみを行い、調整に関する判断は一切行いません。非 LLM のexecutorが .slang ファイルを読み込み、各 stake を Agent SDK セッションにディスパッチします（エージェントごとに 1 つの長期セッションを作成し、各ラウンドで再開します）。すべての結果を 出力コントラクトに照らして確認し（失敗時は再試行します）、メールボックス経由でルーティングします。その後、ワークフローの converge 条件を満たすか、ラウンド予算に達するまで各ラウンドを繰り返します。実行結果は Mermaid のトポロジー図とトレース図として表示されます。escalate @Human を使うと、通常のチャットであなたに通知されます。

ユースケース

具体的なワークフロー（それぞれ .slang ファイルであり、run_workflow を使って実行します）：

• 人による設計承認ゲートを設けて機能を実装する（implement-feature.slang）— Architect が依頼を分解し、設計ドキュメントを作成します。ただし、コードを物理的に書けないようスコープが制限され （write_paths: ["**/*.md"]、deny: [Bash]）、委任が必須です。設計を承認すると（escalate @Human）、 Developer が機能をスライスごとに実装し、Reviewer が各ラウンドを承認します。コミットの前には最終レビューゲートがあります。
• 検証済みの成果物を個別にそろえて機能をリリースする（implement-feature-complex.slang）— 設計 → 実装 → テスト → レビュー → ドキュメント作成の直線的なパイプラインで、5 人の専門家がそれぞれ1 つの成果物（実装、合格する vitest テスト仕様、使用方法のドキュメント）を作成し、他者の作業を代行できないようにします。これにより、コード、テスト、ドキュメントが実際に設計と一致します。すべての段階でコミットが完了した場合にのみ収束します。
• 2 人の独立した調査担当者でバグをトラブルシューティングする（debug.slang）— 症状と再現手順を貼り付けると、2 人の開発者が並行して、厳密な読み取り専用で根本原因を特定します（誤ってファイルを編集することはありません）。Orchestrator が独立した調査結果を 1 つの修正計画にまとめ、1 人の開発者が実装し、もう 1 人が納得するまでループで修正をピアレビューします。
• 確認はできても編集は一切できないレビュアー — レビューエージェントに read／execute の権限を与え、書き込みスコープを与えないようにします。これにより、「作業を確認して」という実行ではテストの実行やコードの読み取りはできますが、変更はできません。これはプロンプトで依頼するだけでなく、強制されます。

特徴

• 再現可能なマルチエージェントパイプライン — コラボレーションは .slang ファイルにコード化され、決定論的な（LLM を使用しない）実行エンジンによって実行されるため、毎回同じように進行します。場当たり的で再現不可能なサブエージェントの連携はありません。
• エージェントごとのツール範囲を強制 — write_paths により、各エージェントの Write/Edit をパスの glob に制限し、deny によりツール（例：Bash）を除外します。これは SDK の canUseTool によって強制され、プロンプトで要求するだけではありません。
• 実行前の静的解析 — validate_workflow は解析時にデッドロック、未知の参照、孤立した出力を検出するため、トークンを消費する前に問題を見つけられます。
• 型付き出力コントラクト — 各 stake は、構造的にも意味的にも有効な結果（output: {…} where <expr>）を返す必要があります。有効でない結果は、下流にそのまま伝播するのではなく再試行されます。
• 終了の保証 — ラウンド予算（budget: rounds(N)）と stake ごとのタイムアウトにより、すべての実行が確実に終了します。
• 図を自動生成 — 実行ごとに Mermaid のトポロジー（get_topology）とシーケンス図のトレース（get_trace）が生成され、実行中や事後の調査に利用できます。
• 収束を重視したコラボレーション — エージェントはメールボックス経由で連携し、宣言された収束条件に達するか予算を使い切るまで反復します。また、セッションを再開できるため、エージェントはラウンドをまたいでコンテキストを維持します。

Claude Code のネイティブな 動的ワークフロー との違い

Claude Code には、すでに組み込みの 動的ワークフロー 機能があります。タスクにオーケストレーションが必要な場合、Claude は JavaScript スクリプト（Agent SDK の Workflow ツール経由）を作成し、サブエージェントを起動して連携させます。これは場当たり的な一度限りのサブエージェント呼び出しからの大きな進歩です。スクリプトがオーケストレーションをコード化し、いったん作成されれば決定論的に実行され、追加の LLM コストをほぼかけずに連携を行います。slang も同じ目標を共有しています。ベンチマーク では、どちらのアプローチでも連携にかかる LLM コストをほぼゼロに抑えながら、実際に動作する実装に到達できることが示されています。違いは、オーケストレーションが 何であるか、そして何が 保証されるか です。

	ネイティブな動的ワークフロー	slang-workflows
オーケストレーションの実体	LLM が作成する JavaScript スクリプト	固定の LLM 非使用実行エンジンが実行する 型付きの宣言的な .slang ファイル
連携ロジックの作成者	Claude がタスクごとに汎用言語で作成	実行環境が理解するドメイン固有言語で、あなた（または LLM が一度だけ）作成
ステージ間の出力コントラクト	スクリプトがたまたまチェックする内容	実行環境が 強制 — 構造的かつ意味的（output: {…} where <expr>）。無効な場合は再試行
エージェントごとのツール範囲	スクリプト次第	SDK の canUseTool 経由で write_paths / deny を 強制
構造の正しさ	JS をチェックするものはない	実行前の静的解析 — デッドロック／未知の参照／孤立した出力
終了	スクリプト次第	保証可能 — budget: rounds(N) と stake ごとのタイムアウト
可観測性	自分で計測する	Mermaid のトポロジーとシーケンス図のトレースを 自動生成
再利用可能な成果物	モデルが毎回再生成するスクリプト	バージョン管理された .slang ファイル と固定のインタープリター

要するに、ネイティブな動的ワークフローでは、オーケストレーションは 信頼する必要がある LLM 作成のコード に置かれます。一方、slang では、実行環境が検証して強制する 型付きの宣言 に置かれます。実行前に解析でき、実行中は範囲とコントラクトが検証され、実行後には図として表示されます。slang は、単に「今回はモデルがいくつかのサブエージェントを連携させた」だけではなく、保証と監査可能性（安全性を考慮したエージェントの範囲設定、終了の保証、コントラクトに適合した引き継ぎ、再利用可能でバージョン管理されたワークフロー）が必要な場合に選んでください。どちらも、構造化されていないサブエージェントよりはるかに優れています。slang は、強制力と再現性を得るために、最初に少し宣言を記述する手間をかけます。

現在利用できる機能

• .slang ワークフローの検出／検証／実行 — 作成済みまたは LLM がインラインで生成したもの（以下の MCP ツールを使用）。
• 決定論的な実行エンジン：ステーク → 出力コントラクトの検証と再試行 → メールボックスへのルーティング → 収束処理；マルチエージェントのフロー；セッションの再開（エージェントごとに 1 つのセッションをすべてのステークで継続）； escalate @Human。
• 出力コントラクト：構造的（output: {...}、SDK の outputFormat 経由）＋意味的（where <expr>）。
• ツールのスコープを強制：write_paths（PreToolUse コマンドフック経由で Write/Edit の対象をパスの glob に制限）および deny（ネイティブツールまたは MCP ツールを削除）。
• 静的解析（validate_workflow）：実行前にデッドロック／不明な参照／孤立した出力を検出。
• 終了を保証：budget: rounds(N) ＋ステークごとのタイムアウト — 実行は必ず終了します。
• 図：get_topology（Mermaid フローチャート）＋ get_trace（Mermaid シーケンス図＋イベントログ）。
• 同期またはバックグラウンドで実行（background:true）し、状態／トポロジー／トレースをリアルタイムでポーリングできます。

全体の一覧は DESIGN.md § 実装状況 を参照してください。

要件

• Node.js 22+ および pnpm。
• Claude Code がインストールされ、認証済みであること（PATH 上の claude CLI） — Agent SDK がこれを起動してエージェントを実行します。

インストール

cd server
pnpm install

Agent SDK に関する注意。 @anthropic-ai/claude-agent-sdk は、一部の内部レジストリにミラーがないため、オプションの依存関係として宣言されています。pnpm install でインストールされない場合は、パブリックレジストリから追加してください。

pnpm add @anthropic-ai/claude-agent-sdk --registry=https://registry.npmjs.org/

サーバーはこの依存関係がなくてもワークフローを解析／検証できますが、エージェントの実行には必要です。

インストールを確認します。

pnpm typecheck   # type-checks the whole server
pnpm test        # runs the unit suite (mock-based, no model calls)

使用方法

実行時に、サーバーはプロジェクトの .claude/workflows/（および ~/.claude/workflows/）にある .slang ファイルを検出します。ここはユーザーが独自のワークフローを置く場所です。プラグインには、サンプル用のワークフローが server/test/fixtures/ に含まれています。試すには、そこからコピーしてください。

mkdir -p .claude/workflows
cp /PATH/TO/slang-orchestrator/server/test/fixtures/*.slang .claude/workflows/

最も手軽な方法：MCP サーバーを Claude Code に登録する

実行したい .claude/workflows/ があるプロジェクトから、次を実行します。

claude mcp add slang-workflows -- npx tsx /ABSOLUTE/PATH/TO/slang-orchestrator/server/src/main.ts

その後、Claude Code にツールを使うよう指示します。たとえば、「slang ワークフローを一覧表示して」、*「where-clause ワークフローを実行して」*などです。

Claude Code プラグインとして使用する

このディレクトリは自己完結型のプラグインです。.claude-plugin/plugin.json ＋ .mcp.json（npx tsx ${CLAUDE_PLUGIN_ROOT}/server/src/main.ts として起動する stdio サーバー）で構成されています。 Claude Code のプラグイン機能からインストールすると、ツールが自動的に利用できるようになります。

スラッシュコマンド

プラグインを読み込むと、次のコマンドで直接操作できます（Claude Code ではプラグイン名が名前空間として付与されるため、/ メニューには slang-workflows:… と表示されます）。

コマンド	機能
/slang-workflows:slang-run <name or path> [k=v …]	ワークフローを最後まで実行します — 同期実行なので、@Human のゲートで入力を促されます。
/slang-workflows:slang-list	認識できる .slang ワークフローを一覧表示します。
/slang-workflows:slang-new <description>	説明からワークフローを生成し、検証して実行します。
/slang-workflows:slang-trace [workflow_id]	実行のトポロジーとシーケンス図のトレースを描画します。

これらは以下の MCP ツールを薄くラップしたものです。代わりに、いつでも Claude に自然言語で指示できます（たとえば、「where-clause ワークフローを実行して」）。

MCP ツール

ツール	目的
list_workflows	.slang ファイルを検出します（名前、タイトル、パラメーター、エージェント数）。
get_slang_grammar	LLM がインラインで実行するワークフローを生成できるよう、簡潔な文法チートシートと例を提供します。
validate_workflow	実行せずに解析と静的解析（デッドロック、不明な参照、孤立した出力）を行います。name／path、またはインラインの source を受け取ります。
run_workflow	name／path、またはインラインの source でワークフローを実行します（最初に解析／静的解析エラーを拒否します）。デフォルトでは同期実行です。background:true を指定すると、すぐに workflow_id を返し、実行状況をポーリングできます。
get_workflow_state	workflow_id によるシリアライズ済みの FlowState（エージェントごとのステータス、ラウンド、予算）を返します。background 実行中も取得できます。
get_topology	workflow_id による実行トポロジーを、Mermaid のフローチャート（ステータスを色分けしたスナップショット）として返します。
get_trace	workflow_id による実行トレースを、Mermaid のシーケンス図と生のイベントログ（誰が誰にステーク／ルーティングしたか、コミット、エスカレーション、終了状態）として返します。

生成して実行するループ： get_slang_grammar → slang を作成 → validate_workflow{source} → run_workflow{source, background:true} → 実行中に get_topology／get_trace をポーリングします。ワークフローは LLM が作成しますが、決定論的に実行されます（コントラクトが適用され、必ず終了します）。@Human へのエスカレーションは同期実行でのみ機能します（対話型の情報取得には、ツール呼び出しを開いたままにする必要があります）。

開発

pnpm dev        # run the server over stdio (logs to stderr)
pnpm typecheck  # tsc --noEmit
pnpm test       # node:test suite

エグゼキューターは Dispatcher インターフェースのみに依存します。FakeDispatcher を使うと、Agent SDK やモデル呼び出しなしで VM 全体をテストできます（server/test/ を参照）。

構成

.claude-plugin/plugin.json   plugin manifest
.mcp.json                    stdio MCP server declaration
server/
  src/
    main.ts                  MCP server + tool surface
    constants.ts             tunable defaults in one place (round cap, retry budget, stake timeout, loop guard)
    executor.ts              deterministic round loop + output contracts
    dispatcher.ts            Dispatcher interface + FakeDispatcher (the agent-runtime seam)
    agent-sdk-dispatcher.ts  production backend (Claude Agent SDK)
    tool-group-map.ts        slang tool-groups → Claude Code tools
    workflows.ts             .slang discovery + validation
    slang/                   vendored, framework-agnostic slang VM (lexer/parser/interpreter/…)
  test/                      node:test unit + conformance suite
    fixtures/                showcase .slang workflows (also the conformance fixtures)

ライセンス

Apache-2.0。詳細は LICENSE を参照してください。