{
  "markdown": "```\n███████╗██╗      █████╗ ███╗   ██╗ ██████╗\n██╔════╝██║     ██╔══██╗████╗  ██║██╔════╝\n███████╗██║     ███████║██╔██╗ ██║██║  ███╗\n╚════██║██║     ██╔══██║██║╚██╗██║██║   ██║\n███████║███████╗██║  ██║██║ ╚████║╚██████╔╝\n╚══════╝╚══════╝╚═╝  ╚═╝╚═╝  ╚═══╝ ╚═════╝\n     provable, declarative multi-agent workflows for Claude Code\n     a non-LLM executor runs your typed .slang files\n```\n\n# slang-workflows\n\nRun **provable**, `.slang`-driven **multi-agent workflows** inside Claude Code.\n\nA non-LLM state machine (the *slang executor*) runs inside an MCP server and coordinates agents;\neach agent is a Claude **Agent SDK** session. You declare the collaboration in a typed `.slang`\nfile and the executor *enforces* it — typed output contracts, static analysis, tool-scoping, and\nprovable termination — instead of leaving coordination to the model. The top-level Claude Code\nsession only *triggers* and *observes*; it never makes a coordination decision.\n\nClaude Code's native **dynamic workflows** also codify orchestration (Claude writes a JS script);\nslang's difference is that the structure is **enforced and statically analyzable**, and runs render\nas **Mermaid topology + trace diagrams**. See the [benchmark](benchmark/) for the A/B/C head-to-head.\n\n> **Origin.** The `.slang` Workflow engine was born in [**Shofer**](https://shofer.dev) — the\n> AI-agent VS Code extension — where the deterministic, non-LLM executor was first built. This\n> plugin brings it to Claude Code.\n\n> Design and rationale: [`DESIGN.md`](DESIGN.md). Language reference: [`slang_specs.md`](slang_specs.md). Privacy: [`PRIVACY.md`](PRIVACY.md).\n\n![slang-workflows running implement-feature.slang deterministically — the guaranteed review loop, 0 coordination LLM tokens, converged](media/slang-workflows.gif)\n\n## How it works\n\n```mermaid\nflowchart TB\n    You([\"You\"])\n    CC[\"Claude Code<br/>top-level session\"]\n\n    subgraph server[\"slang-workflows · MCP server\"]\n        direction TB\n        SL[\"your .slang workflow<br/>agents · stakes · contracts · converge\"]\n        EX[\"slang executor<br/>deterministic · non-LLM state machine\"]\n        MB[(\"FlowState + mailbox\")]\n        SL -->|\"parsed once\"| EX\n        EX <--> MB\n    end\n\n    subgraph Agents[\"Agent SDK sessions — the agents your .slang declares\"]\n        direction LR\n        A1[\"Agent A\"]\n        A2[\"Agent B\"]\n        A3[\"Agent …\"]\n    end\n\n    You <-->|\"ask · approve escalations\"| CC\n    CC -->|\"run_workflow\"| EX\n    EX -->|\"topology + trace diagrams\"| CC\n    EX ==>|\"dispatch stake — one session per agent, resumed\"| Agents\n    Agents ==>|\"typed result → output-contract check + retry\"| EX\n    EX -.->|\"escalate @Human\"| CC\n\n    classDef brain fill:#eaeaff,stroke:#5b5bd6,stroke-width:2px;\n    class EX brain;\n```\n\nThe top-level Claude Code session only **triggers and observes** — it never makes a coordination\ndecision. The non-LLM **executor** reads your `.slang` file, dispatches each *stake* to an Agent\nSDK session (one long-lived session per agent, resumed across rounds), checks every result against\nits **output contract** (retrying on failure), routes it through the **mailbox**, and repeats each\nround until the workflow's `converge` condition or round budget is met. Runs render as Mermaid\n**topology** and **trace** diagrams; `escalate @Human` surfaces back to you in the normal chat.\n\n## Use cases\n\nConcrete workflows (each is a `.slang` file you run with `run_workflow`):\n\n- **Implement a feature with a human design-approval gate** (`implement-feature.slang`) — an *Architect*\n  decomposes your request and writes the design doc, but is scoped so it **physically cannot write code**\n  (`write_paths: [\"**/*.md\"]`, `deny: [Bash]`) and must delegate. You approve the design (`escalate @Human`),\n  then a *Developer* implements it slice-by-slice while a *Reviewer* signs off each round, with a final\n  review gate before it commits.\n- **Ship a feature as separate, verified deliverables** (`implement-feature-complex.slang`) — a linear\n  Design → Implement → Test → Review → Document pipeline where five specialists each produce **one** artifact\n  (the implementation, a *passing* vitest spec, usage docs) and can't do another's job — so code, tests, and\n  docs actually match the design. Converges only when every stage has committed.\n- **Troubleshoot a bug with two independent investigators** (`debug.slang`) — paste the symptom/repro; two\n  developers root-cause it **in parallel, strictly read-only** (no accidental edits), an *Orchestrator*\n  consolidates their independent findings into one fix plan, one developer implements it, and the other\n  **peer-reviews the fix in a loop** until satisfied.\n- **A reviewer that can inspect but never edit** — give the review agent `read`/`execute` and no write\n  scope, so a \"check my work\" run can run tests and read code but cannot alter it — enforced, not just prompted.\n\n## Features\n\n- **Reproducible multi-agent pipelines** — the collaboration is codified in a `.slang` file and driven by a\n  deterministic (non-LLM) executor, so a run unfolds the same way every time — no improvised, unrepeatable\n  subagent coordination.\n- **Enforced per-agent tool-scoping** — `write_paths` restricts each agent's Write/Edit to path globs and\n  `deny` removes tools (e.g. `Bash`), enforced via the SDK's `canUseTool` — not merely requested in a prompt.\n- **Static analysis before running** — `validate_workflow` detects deadlocks, unknown references, and\n  orphaned outputs at parse time, before any tokens are spent.\n- **Typed output contracts** — each stake must return a structurally *and* semantically valid result\n  (`output: {…} where <expr>`); invalid results retry instead of silently propagating downstream.\n- **Provable termination** — round budgets (`budget: rounds(N)`) + per-stake timeouts guarantee every run finishes.\n- **Auto-generated diagrams** — every run renders a Mermaid topology (`get_topology`) and a sequence-diagram\n  trace (`get_trace`), for live or post-mortem inspection.\n- **Convergence-driven collaboration** — agents route via mailboxes and iterate until a declared convergence\n  condition or budget is reached, with session resume so an agent keeps its context across rounds.\n\n## How this differs from Claude Code's native *dynamic workflows*\n\nClaude Code already has a built-in **dynamic workflows** feature: when a task needs orchestration, Claude\nwrites a **JavaScript script** (via the Agent SDK / `Workflow` tool) that spawns and coordinates subagents.\nThat's a real step up from improvised, one-off subagent calls — the script codifies the orchestration and,\nonce written, runs deterministically and coordinates for ~0 extra LLM cost. slang shares those goals; our\n[benchmark](benchmark/) shows **both** approaches reach real, working implementations with near-zero\ncoordination-LLM cost. **The difference is what the orchestration *is*, and what's *guaranteed* about it:**\n\n| | Native dynamic workflows | slang-workflows |\n|---|---|---|\n| The orchestration is… | an **LLM-authored JavaScript** script | a **typed, declarative `.slang`** file run by a fixed non-LLM executor |\n| Who wrote the coordination logic | Claude, per task, in a general-purpose language | you (or an LLM, once) in a domain-specific language the runtime understands |\n| Output contracts between stages | whatever the script happens to check | **enforced** by the runtime — structural + semantic (`output: {…} where <expr>`); invalid → retry |\n| Per-agent tool scoping | up to the script | **enforced** — `write_paths` / `deny` via the SDK's `canUseTool` |\n| Correctness of the structure | nothing checks the JS | **static analysis before running** — deadlock / unknown-ref / orphan-output |\n| Termination | up to the script | **provable** — `budget: rounds(N)` + per-stake timeouts |\n| Observability | instrument it yourself | **auto-generated** Mermaid topology + sequence-diagram trace |\n| The reusable artifact | a script the model regenerates each time | a **versioned `.slang` file** + a fixed interpreter |\n\nIn short: native dynamic workflows put the orchestration in **LLM-written code you have to trust**; slang\nputs it in a **typed declaration the runtime validates and enforces** — analyzable *before* it runs, scoped\nand contract-checked *while* it runs, and rendered as diagrams *after*. Reach for slang when you want\n**guarantees and auditability** (safety-scoped agents, provable termination, contract-valid hand-offs, a\nreusable versioned workflow), not just \"the model coordinated some subagents this time.\" Both are far better\nthan unstructured subagents — slang trades a bit of up-front declaration for enforcement and repeatability.\n\n## What works today\n\n- Discover / validate / run `.slang` workflows — **authored or LLM-generated inline** (MCP tools below).\n- Deterministic executor: stake → **output-contract** validation + retry → mailbox routing →\n  convergence; **multi-agent** flows; **session resume** (one agent = one session across stakes);\n  `escalate @Human`.\n- **Output contracts**: structural (`output: {...}`, via SDK `outputFormat`) + semantic (`where <expr>`).\n- **Enforced tool scoping**: `write_paths` (Write/Edit restricted to path globs, via a PreToolUse\n  command hook) and `deny` (remove native or MCP tools).\n- **Static analysis** (`validate_workflow`): deadlock / unknown-ref / orphan-output detection before running.\n- **Provable termination**: `budget: rounds(N)` + per-stake timeouts — the run always finishes.\n- **Diagrams**: `get_topology` (Mermaid flowchart) + `get_trace` (Mermaid sequence + event log).\n- **Synchronous or background** runs (`background:true`) with live polling of state/topology/trace.\n\nSee [`DESIGN.md` § Implementation Status](DESIGN.md#implementation-status) for the full matrix.\n\n## Requirements\n\n- **Node.js 22+** and **pnpm**.\n- **Claude Code** installed and authenticated (the `claude` CLI on your `PATH`) — the Agent SDK\n  spawns it to run agents.\n\n## Install\n\n```bash\ncd server\npnpm install\n```\n\n> **Agent SDK note.** `@anthropic-ai/claude-agent-sdk` is declared as an *optional* dependency\n> because some internal registries don't mirror it. If `pnpm install` skips it, add it from the\n> public registry:\n>\n> ```bash\n> pnpm add @anthropic-ai/claude-agent-sdk --registry=https://registry.npmjs.org/\n> ```\n>\n> The server *parses/validates* workflows without it; *running* agents requires it.\n\nVerify the install:\n\n```bash\npnpm typecheck   # type-checks the whole server\npnpm test        # runs the unit suite (mock-based, no model calls)\n```\n\n## Use it\n\nAt runtime the server discovers `.slang` files in **your project's** `.claude/workflows/` (and\n`~/.claude/workflows/`) — that's the user's space for their own workflows. The plugin ships\nshowcase workflows in [`server/test/fixtures/`](server/test/fixtures); copy them in to try them:\n\n```bash\nmkdir -p .claude/workflows\ncp /PATH/TO/slang-orchestrator/server/test/fixtures/*.slang .claude/workflows/\n```\n\n### Quickest: register the MCP server with Claude Code\n\nFrom the project whose `.claude/workflows/` you want to run:\n\n```bash\nclaude mcp add slang-workflows -- npx tsx /ABSOLUTE/PATH/TO/slang-orchestrator/server/src/main.ts\n```\n\nThen in Claude Code, ask it to use the tools — e.g. *\"list the slang workflows\"*, *\"run the\nwhere-clause workflow\"*.\n\n### As a Claude Code plugin\n\nThis directory is a self-contained plugin: [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json)\n+ [`.mcp.json`](.mcp.json) (a stdio server launched as `npx tsx ${CLAUDE_PLUGIN_ROOT}/server/src/main.ts`).\nInstall it through Claude Code's plugin mechanism to expose the tools automatically.\n\n### Slash commands\n\nOnce the plugin is loaded, these commands drive it directly (Claude Code namespaces them by the\nplugin, so your `/` menu shows `slang-workflows:…`):\n\n| Command | Does |\n|---------|------|\n| `/slang-workflows:slang-run <name or path> [k=v …]` | Run a workflow to completion — synchronous, so `@Human` gates prompt you. |\n| `/slang-workflows:slang-list` | List the `.slang` workflows it can see. |\n| `/slang-workflows:slang-new <description>` | Generate a workflow from a description, validate it, and run it. |\n| `/slang-workflows:slang-trace [workflow_id]` | Render the topology + sequence-diagram trace of a run. |\n\nThey're thin wrappers over the MCP tools below — you can always just ask Claude in natural\nlanguage instead (e.g. *\"run the where-clause workflow\"*).\n\n## MCP tools\n\n| Tool | Purpose |\n|------|---------|\n| `list_workflows` | Discover `.slang` files (name, title, params, agent count). |\n| `get_slang_grammar` | Concise grammar cheatsheet + example, so an LLM can **generate** a workflow to run inline. |\n| `validate_workflow` | Parse + static analysis (deadlocks, unknown refs, orphan outputs) without running. Accepts a `name`/`path` **or** inline `source`. |\n| `run_workflow` | Run a workflow by `name`/`path` **or** inline `source` (rejects parse/static-analysis errors first). Synchronous by default; `background:true` returns a `workflow_id` immediately to poll live. |\n| `get_workflow_state` | Serialized `FlowState` (per-agent status, round, budget) by `workflow_id` — live during a `background` run. |\n| `get_topology` | Run topology as a Mermaid **flowchart** (status-colored snapshot) by `workflow_id`. |\n| `get_trace` | Execution **trace** as a Mermaid **sequenceDiagram** + raw event log (who staked/routed to whom, commits, escalations, terminal) by `workflow_id`. |\n\n**Generate-and-run loop:** `get_slang_grammar` → author slang → `validate_workflow{source}` → `run_workflow{source, background:true}` → poll `get_topology` / `get_trace` while it runs. The workflow is authored by an LLM but **executed deterministically** (contracts enforced, always terminates). `@Human` escalation works in synchronous runs only (interactive elicitation needs the tool call to stay open).\n\n## Develop\n\n```bash\npnpm dev        # run the server over stdio (logs to stderr)\npnpm typecheck  # tsc --noEmit\npnpm test       # node:test suite\n```\n\nThe executor depends only on a `Dispatcher` interface; `FakeDispatcher` makes the whole VM\ntestable without the Agent SDK or any model calls (see [`server/test/`](server/test)).\n\n## Layout\n\n```\n.claude-plugin/plugin.json   plugin manifest\n.mcp.json                    stdio MCP server declaration\nserver/\n  src/\n    main.ts                  MCP server + tool surface\n    constants.ts             tunable defaults in one place (round cap, retry budget, stake timeout, loop guard)\n    executor.ts              deterministic round loop + output contracts\n    dispatcher.ts            Dispatcher interface + FakeDispatcher (the agent-runtime seam)\n    agent-sdk-dispatcher.ts  production backend (Claude Agent SDK)\n    tool-group-map.ts        slang tool-groups → Claude Code tools\n    workflows.ts             .slang discovery + validation\n    slang/                   vendored, framework-agnostic slang VM (lexer/parser/interpreter/…)\n  test/                      node:test unit + conformance suite\n    fixtures/                showcase .slang workflows (also the conformance fixtures)\n```\n\n## License\n\nApache-2.0. See [`LICENSE`](LICENSE).\n",
  "bytes": 15131,
  "sha": "3cb935ec5c4c753dddbffd62f3e5a9ecaf3c9b6c9d9a085652ed38d07fd64693",
  "repo_slug": "shofer-dev/claude-code-slang-orchestrator",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shofer_dev_slang_workflows_adaf4a2c/readme"
}