Playbook: Reliability Is All You Need

Skills made reliable through state machines and diverse LLMs.

Natural-language skills are flexible and easy to use, but less predictable than scripted workflows, especially on long-horizon jobs. And even the best LLMs make mistakes, partly because plain-language descriptions rarely eliminate vagueness or guarantee completeness.

SubLang Playbook addresses both:

• The companion SLC compiler turns plain-language procedures, such as a SKILL.md, into playbooks with deterministic state-machine control flow.
• A playbook can assign different agents or LLMs to its steps and have them review and challenge one another, helping catch mistakes before delivery.

Vocabulary: the Boss is you; the Captain is the coordinating agent you talk to; a role is a playbook-local job such as coder; and a player is a stable Captain-session agent and provider conversation to which one or more roles bind. Roles describe the workflow, while player IDs decide which work shares conversation continuity.

Run playbook for an interactive tmux UI powered by cligent, or playbook run for the same Captain session without tmux in scripts and CI.

Quick start

Out of the box, Playbook includes CODE for implementation, REVIEW for commit-based review and fixes, DECIDE for independently proposed and reviewed specification decisions, DEV for repository-aware planning of a development request, BRANCH for checking out a new branch for a GitHub issue, and PR for publishing, checking, and merging that branch through a pull request. CODE and DECIDE call REVIEW as a nested playbook; DEV calls CODE, or DECIDE and then CODE, and wraps them in BRANCH and PR when the request names a GitHub issue or asks for a pull request.

The shared starter config selects one adapter for the Captain and all players from locally visible credentials: Claude first, then Codex. If neither is configured, it seeds Claude and prints a notice. CODE, REVIEW, DECIDE, BRANCH, and PR bind their local roles explicitly to dev.coder and dev.reviewer, so nested and later engagements share a conversation only where their bindings name the same player ID; DEV’s Analyst binds a distinct dev.analyst player.

npm install -g @sublang/playbook
npm install -g @anthropic-ai/claude-agent-sdk @openai/codex-sdk

Custom configurations need the SDKs required by their providers; see Configuring agents. If an SDK is missing or older than cligent supports, Playbook prints the pinned install command before launching anything; see Installing agent SDKs for upgrades, npx, and other adapters.

Prerequisites:

• Node.js >= 20.6.0
• Credentials for the configured adapter: authenticated Claude Code or ANTHROPIC_API_KEY for Claude; authenticated Codex CLI or OPENAI_API_KEY for Codex
• GitHub CLI (gh) authenticated for the repository’s GitHub remote, for /branch, /pr, and /dev requests that name an issue or ask for a pull request

Interactive playbook additionally needs tmux 3.3 or newer and glow on PATH; headless playbook run does not.

CODE works in the current directory and can edit and commit autonomously, so use a clean branch or worktree.

cd /path/to/your/project
playbook

Type a task, enter /code for implementation, or enter /decide for an independently proposed and reviewed decision.

On first launch, Playbook writes its config to ${SPEX_HOME:-$HOME/.spex}/config/playbook.config.yaml. A config left at either former location — the root’s playbook/playbook.config.yaml or ${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml — is moved there once on the next launch, unless a relative primary locator would change targets; that case is rejected unchanged with absolute replacements.

The same config, compiled Captain, enabled playbooks, stable players, and nested calls power headless turns. Both front ends create the same durable logical session: copy the reported session ID to reopen an interactive session headlessly or a headless session interactively. Run REVIEW explicitly, or pipe a longer request to Captain:

playbook run "/review review the latest commit"
printf '%s\n' 'Implement the approved specification, then review it.' | playbook run
# Later, either presentation can reopen the returned/reported session id:
playbook --session 4f2c0000-0000-4000-8000-000000009ab1
playbook run --session 4f2c0000-0000-4000-8000-000000009ab1 "continue"

playbook run prints the one Boss-visible Captain reply to stdout and operational status to stderr; CODE and DECIDE can complete their nested REVIEW calls there too.

See Using the CLI for flags and durable continuation, Configuring agents for the shared lineup, Embedding for custom hosts, and the changelog for releases.

Create your own playbook

The separate SLC compiler requires Node.js >= 23.6 and compiles a plain-language .md or .txt procedure:

npm install -g @sublang/slc
slc playbook my-workflow.md
# After enabling /absolute/path/to/my-workflow.ts in the shared config:
playbook run "/my-workflow "

SLC writes my-workflow.ts, a registry entry ready for Playbook, beside the source, and the inspectable intermediates and tests under my-workflow.playbook/. Enable that entry and bind each role it declares under playbooks.my-workflow in the shared config, then invoke /my-workflow; see External playbooks and the SLC documentation.

How it compiles

SLC’s playbook pipeline has three phases:

1. text → GEARS (slc/text2gears.md) — makes each behavior explicit with its trigger, actor, prompt, and outcomes.
2. GEARS → FSM (slc/gears2fsm.md) — maps each item to an XState state that invokes the Captain, a player, another playbook, or a local script.
3. FSM → runtime (slc/link.md) — links the machine to a host-independent interface for user input, agent calls, status, and telemetry.

The default optimization pass replaces eligible mechanical steps with local shell scripts; --no-optimize skips it. Inspect the complete Captain, CODE, REVIEW, and DECIDE examples.

Contributing

We welcome contributions of all kinds.

• 🌟 Star our repo if you find Playbook useful.
• Open an issue for bugs or feature requests.
• Open a PR for fixes or improvements.
• Discuss on Discord for support or new ideas.

From source:

git clone https://github.com/sublang-ai/playbook.git
cd playbook
pnpm install --frozen-lockfile
pnpm build
pnpm test
pnpm playbook   # drive a Boss turn against the source tree

Playbook is itself spec-driven: the compiler phases are specs in slc/, and the reference playbooks are regenerated from their prose sources. Edit a source, regenerate its GEARS, FSM, and runtime artifacts, sync the tests and downstream specs until pnpm test passes, and commit with co-author trailers per specs/packages/git.md. The gears↔FSM contract (the playbook package) and runtime contract (the playbook-runtime package) are pinned in specs/packages/ and verified by the test suite.

License

Apache-2.0