@sublang/playbook 0.8.0 → 1.0.0

package/README.md

@@ -7,28 +7,49 @@
 [![Node.js](https://img.shields.io/node/v/@sublang/playbook)](https://nodejs.org/)
 [![CI](https://github.com/sublang-ai/playbook/actions/workflows/ci.yml/badge.svg)](https://github.com/sublang-ai/playbook/actions/workflows/ci.yml)
 
-*Skills made reliable through state machines and visualization.*
+_Skills made reliable through state machines and visualization._
 
 playbook is a compiler stack and reference implementation for turning a
 natural-language procedure into a runnable, inspectable state-machine
-agent — a *playbook* — that orchestrates other AI agents (players) per a
-spec written in plain prose. Three phases take prose to runtime:
-
-1. **text → GEARS** ([slc/text2gears.md](slc/text2gears.md)) — normative
-   spec items, one per state behavior, partitioned by trigger and prompt
-   content.
+agent — a _playbook_ — that orchestrates other AI agents per a spec
+written in plain prose. Instead of a free-form LLM deciding what to do
+next, an explicit finite state machine drives the workflow, every
+Captain-, player-, and nested-playbook-invoking state pinned 1:1 to a
+human-readable spec item and contract-tested.
+
+A quick vocabulary, used throughout: the **Boss** is you, the human in
+charge; the **Captain** is the agent pane the Boss talks to;
+**players** are the coding agents a playbook delegates work to; and a
+hidden **judge** classifies free-text Boss input into state-machine
+events, so playbooks need no slash commands of their own. Playbooks run
+inside a *host* built on
+[cligent](https://github.com/sublang-ai/cligent), the sibling SDK that
+drives coding-agent CLIs; cligent's `tmux-play` terminal app is the
+reference host.
+
+Three phases take prose to runtime:
+
+1. **text → GEARS** ([slc/text2gears.md](slc/text2gears.md)) — GEARS is
+   the intermediate representation: normative spec items, one per state
+   behavior, partitioned by trigger and prompt content.
 2. **GEARS → FSM** ([slc/gears2fsm.md](slc/gears2fsm.md)) — an XState v5
-   finite state machine; each gear maps to one captain-invoking state
-   with a typed Captain actor contract.
+   finite state machine; each gear maps to one direct-Captain,
+   delegated-player, or nested-playbook state with a typed actor
+   contract. The compiled FSM can be visualized and simulated with the
+   bundled [XState sketch visualizer](views/sketch).
 3. **FSM → runtime** ([slc/link.md](slc/link.md)) — a host-agnostic
    module that drives Boss turns through ports the host wires up
    (cligent's `tmux-play` is one such host).
 
-The repository is itself an end-to-end worked example: this
-package — `@sublang/playbook` — is the SDLC coding workflow,
-generated from [`reference/sdlc/code.md`](reference/sdlc/code.md)
-as its prose source. The runtime drives a coder / reviewer /
-committer loop end to end.
+The repository contains end-to-end worked examples. The generic default
+Captain is generated from
+[`reference/sdlc/captain.md`](reference/sdlc/captain.md), CODE — a
+coder / reviewer / committer development loop — from
+[`reference/sdlc/code.md`](reference/sdlc/code.md), and DISCUSS — two
+agents converging on spec items — from
+[`reference/sdlc/discuss.md`](reference/sdlc/discuss.md). Together they
+show direct Captain work, sequential nested playbook calls, and
+parallel players.
 
 ## Getting started — the reference CODE playbook
 
@@ -40,7 +61,26 @@ the runtime registered behind the built-in Playbook Captain shell for
 cligent's `tmux-play` host out of the box.
 The compiled artifacts live under
 [`reference/sdlc/code.playbook/`](reference/sdlc/code.playbook),
-the slc pipeline's `<basename>.<pipeline>/` output directory.
+the [slc](https://github.com/sublang-ai/slc) compiler pipeline's
+`<basename>.<pipeline>/` output directory.
+
+> **Release status:** 1.0.0 is the first release of the composed system: the
+> compiled default Captain, CODE and DISCUSS, nested playbook calls, the
+> semver-stable six-port runtime contract (see
+> [docs/embedding.md](docs/embedding.md)), and non-interactive `playbook run`
+> with parked-session resume and per-run agent tuning.
+
+### Requirements
+
+- Node.js >= 20.6.0.
+- `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation)
+  on `PATH` — the `tmux-play` host renders Markdown pane output with
+  glow and fails fast without it.
+- Auth for the seeded agents: a signed-in
+  [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)
+  (`~/.claude`) or `ANTHROPIC_API_KEY`, and a signed-in
+  [Codex CLI](https://github.com/openai/codex) (`~/.codex`) or
+  `OPENAI_API_KEY`.
 
 ### Install (users)
 
@@ -55,232 +95,250 @@ npm install -g @sublang/playbook
 Then launch the reference playbook in a `tmux-play` session:
 
 ```sh
-playbook-code
+playbook
 ```
 
-For a one-shot run without a global install, use the same command
-through npx:
+For a one-shot run without a global install, invoke the scoped
+package through npx (it runs the package's `playbook` bin):
 
 ```sh
-npx playbook-code
+npx @sublang/playbook
 ```
 
-On first run, `playbook-code` creates a commented user config at
-`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml`
-from the bundled template, prints that path to stderr, then checks the
-declared adapters before launching. Later runs reuse that file and do
-not overwrite it.
+On first run, `playbook` creates a commented user config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`
+from the bundled starter, prints that path to stderr, then composes a
+`tmux-play` config and checks the declared adapters before launching.
+Later runs reuse that file and do not overwrite it.
 
 Known adapter readiness is intentionally light: `claude` is ready when
 local Claude Code auth exists or `ANTHROPIC_API_KEY` is set; `codex` is
 ready when local Codex CLI auth exists or `OPENAI_API_KEY` is set. If a
-known adapter is not ready, `playbook-code` prints its own help text
-with the config path, auth pointers, and agent-swap recipe, then exits
-without launching. You can view the same recovery text at any time:
+known adapter is not ready, `playbook` prints its own help text with the
+config path, auth pointers, and agent-swap recipe, then exits without
+launching. You can view the same recovery text at any time:
 
 ```sh
-playbook-code --help
+playbook --help
 ```
 
-The seed template runs each agent in cligent's protected auto mode
-(`permissions.mode: auto`), suppressing routine approval prompts. Its
-Codex Reviewer also grants `permissions.writablePaths: [.git]` so git
-metadata writes stay available under auto mode without switching to
-bypass permissions.
+`playbook --list` prints the configured playbooks with their slash
+commands and intents. Every seeded agent — the Captain and both roles —
+runs in cligent's protected auto mode (`permissions.mode: auto`), so
+routine in-session approval prompts are suppressed without switching to
+bypass permissions. The seeded Codex Reviewer additionally grants
+`permissions.writablePaths: [.git]` so git metadata writes stay
+available under the Codex sandbox; the Claude agents need no such grant
+under their auto mode.
+
+### Run a playbook non-interactively
+
+`playbook run <from> [task]` runs one playbook once, without tmux-play
+and without a config entry — point it straight at a registry module:
+
+```sh
+playbook run @sublang/playbook/code/registry "add a test for parseArgs" \
+  --player coder=claude --player reviewer=codex --cwd ./my-repo
+```
+
+`[task]` is read from stdin when omitted — pipe long or multi-line
+intents the same way you would to `claude -p` or `codex exec`. Roles
+and the captain default to `claude`; bind them with
+`--player <role>=<agent>` and `--captain <agent>`, where `<agent>` is
+`<adapter>[:<model>][@<effort>]` — say `codex:gpt-5.5@xhigh`, or
+`claude@high` for the default model at high reasoning effort; the
+model keeps every interior colon (`opencode:ollama/llama3:8b@max`),
+and unsupported efforts are rejected up front naming the adapter's
+supported values. Pass a playbook option with
+`--option <key>=<value>`, and add `--json` to print one JSON envelope
+(`outcome`, `sessionId`, and the output or pending questions) instead
+of plain text. It exits `0` on a terminal outcome, `2` on failure, `3`
+when the playbook needs a Boss reply, and `1` on a bad argument or
+module. See [PBCLI-18](specs/user/playbook-cli.md#pbcli-18).
+
+When the playbook stops to ask the Boss something, the run is parked,
+not lost: the question prints to stdout, the session is saved under
+`${XDG_STATE_HOME:-$HOME/.local/state}/playbook/sessions/`, and stderr
+names the exact command that continues it. Answer with `resume`:
+
+```sh
+playbook run resume 4f2c…9ab1 "keep the scope small; skip the docs"
+playbook run resume --last   # most recently parked session; reply on stdin
+```
+
+A resumed run picks the playbook up exactly where it parked — same
+session id, same workflow state, and each agent continues its own
+conversation — then prints the final output and exits `0`, or parks
+again with the next question and exits `3`. The agent lineup, options,
+and working directory are stored with the session, so `resume` takes no
+binding flags. In scripts, capture the session id from the `--json`
+envelope, like Claude Code's `session_id` or `codex exec resume`. See
+[PBCLI-22](specs/user/playbook-cli.md#pbcli-22) and
+[DR-014](specs/decisions/014-durable-one-shot-run-sessions.md).
 
 ### Configure agents
 
 Edit the seeded user config when you want different coding agents:
 
 ```sh
-$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml"
+$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
+```
+
+To retune a single launch without editing that file, overlay a
+fragment in the same format with `--with` (repeatable, later files
+win; maps merge recursively, other values replace):
+
+```sh
+playbook --with fast-lineup.yaml
+```
+
+```yaml
+# fast-lineup.yaml — swap the Coder for one run; nothing is written back.
+profiles:
+  codex-fast: { adapter: codex, model: gpt-5.5, reasoningEffort: medium }
+playbooks:
+  code:
+    players:
+      coder: codex-fast
 ```
 
-Both CODE players can use `claude` or `codex`; other adapter ids are
-passed through to `tmux-play` with a warning because `playbook-code`
-does not know how to preflight their auth. The safe tuning points are
-`captain.adapter`, `captain.model`, and each role's `adapter` and
-`model` under `players.coder` / `players.reviewer`. The composer owns
-`captain.from` and points it at the Playbook Captain shell adapter, and
-it owns the `coder` / `reviewer` role keys, so leave those keys as-is;
-the runtime binds to those host-configuration invariants per
-[PBRT-4](specs/user/playbook-runtime.md#pbrt-4) and derives the
-`<coder-llm>` / `<reviewer-llm>` substitution strings from each role's
-`model` when pinned and `adapter` otherwise — so the Committer's
-commit-message trailers can name the concrete model
-(e.g. `claude-opus-4-8[1m]`) rather than the adapter family
-(`claude`).
-
-`players.committer` is an optional alias naming which role — `coder`
-or `reviewer` — runs the commit turn; the seeded overlay points it at
-the Coder. Absent the alias the Committer falls back to the Coder
-([PBRT-8](specs/user/playbook-runtime.md#pbrt-8)).
-
-For example, the seeded overlay runs the Coder on Claude Opus 4.8 1m
-and the Reviewer on GPT-5.5, with the Committer aliased to the Coder:
+See [PBCLI-25](specs/user/playbook-cli.md#pbcli-25) and
+[DR-015](specs/decisions/015-per-run-agent-tuning.md).
+
+The config is top-level (no `config:` wrapper): a `profiles` map of
+reusable agent settings, a `captain` agent (it runs both visible
+Captain work and hidden judge calls), optional `layout` /
+`notifications` / `theme`, and a `playbooks` map of enabled playbooks.
+Each `captain` or `players.<role>` value is a profile id or an adapter
+shorthand (`claude`, `codex`); other adapter ids are passed through to
+`tmux-play` with a warning because `playbook` cannot preflight their
+auth. Name profiles by their underlying agent/model (e.g. `claude-opus`,
+`codex-gpt`) so the profile ids read distinctly from the player roles
+that reference them. Within a `playbooks.<id>` block, `from` (the
+registry module), `command` (an optional slash-command override), and
+`players` are launcher-owned; every other key is that playbook's option
+slice. The launcher injects the rest — you do not write host wiring by
+hand.
+
+For example, the seeded config runs the Coder on Claude Opus 4.8 1m and
+the Reviewer on GPT-5.5:
 
 ```yaml
-captain:
-  adapter: claude
-  model: claude-opus-4-8
-  reasoningEffort: high
-  permissions:
-    mode: auto
-
-players:
-  coder:              # role key must stay `coder` — see PBRT-4
+profiles:
+  claude-opus:
+    adapter: claude
+    model: claude-opus-4-8
+    reasoningEffort: high
+    permissions:
+      mode: auto # protected auto mode for the Claude Captain
+  claude-opus-1m:
     adapter: claude
     model: claude-opus-4-8[1m]
     reasoningEffort: xhigh
     permissions:
-      mode: auto
-  reviewer:           # role key must stay `reviewer` — see PBRT-4
+      mode: auto # protected auto mode for the Claude Coder
+  codex-gpt:
     adapter: codex
     model: gpt-5.5
     reasoningEffort: xhigh
     permissions:
       mode: auto
       writablePaths:
-        - .git          # allow git metadata writes under Codex auto mode
-  committer: coder      # which role commits — `coder` or `reviewer`
+        - .git # allow git metadata writes under Codex auto mode
+
+captain: claude-opus
+
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    players:
+      coder: claude-opus-1m
+      reviewer: codex-gpt
+    committer: coder # which role commits — `coder` or `reviewer`
 ```
 
-Normal `playbook-code` runs use the seeded path above. If you need a
-separate config file for a one-off run, pass it explicitly; this bypasses
-the seed and readiness gate and forwards the arguments to `tmux-play`
-verbatim, as pinned in
-[PBCODE-1](specs/user/playbook-code.md#pbcode-1):
+`committer` is CODE's one option: an alias naming which role runs the
+commit turn (fallback semantics:
+[PBRT-8](specs/dev/playbook-runtime.md#pbrt-8)). Each role's per-run
+prompt names its pinned `model`, else its `adapter`
+([PBRT-4](specs/user/playbook-runtime.md#pbrt-4)), so commit trailers
+can credit the concrete model (e.g. `claude-opus-4-8[1m]`) rather than
+the adapter family.
+
+If you need a separate config file for a one-off run, pass a raw
+`tmux-play` config explicitly; this bypasses the seed, composition, and
+readiness gate and forwards the arguments to `tmux-play` verbatim
+([PBCLI-1](specs/user/playbook-cli.md#pbcli-1)):
 
 ```sh
-playbook-code --config ./playbook-code.config.yaml
+playbook --config ./tmux-play.config.yaml
 ```
 
 ### Install (contributors / from source)
 
-Clone, install, and run the suite locally:
+The checked-in lockfile resolves every runtime contract required by the
+source tree:
 
 ```sh
 git clone https://github.com/sublang-ai/playbook.git
 cd playbook
-pnpm install
+pnpm install --frozen-lockfile
 pnpm build
 pnpm test
 ```
 
-`pnpm install` here installs the `@sublang/cligent` version pinned
-in the checked-in `pnpm-lock.yaml` — the same version CI installs
-via `--frozen-lockfile`, so contributor checkouts and CI agree.
-The published `package.json` declares `@sublang/cligent` as
-`^0.13.0`, so an end-user install with no lockfile (e.g., `npm
-install -g @sublang/playbook`) resolves a compatible cligent 0.13.x
-release (see [RELEASE-14](specs/dev/release.md#release-14)). To
-refresh the contributor pin within that range, run
-`pnpm update @sublang/cligent` and commit the resulting
-`pnpm-lock.yaml` change. To adopt a later cligent minor, update the
-`package.json` specifier and lockfile together.
-No local link required for any of this. To point pnpm at a local
-`cligent` checkout
-instead, copy
-[`pnpm-workspace.yaml.example`](pnpm-workspace.yaml.example)
-into place; the override is gitignored so it never leaks into a
-production install.
-
-Drive a Boss turn against the source tree (uses the developer
-[`tmux-play.config.yaml`](reference/sdlc/code.playbook/tmux-play.config.yaml)
-that imports the compiled Playbook Captain shell via relative path):
+To co-develop Playbook with an unreleased cligent checkout, clone
+cligent beside this repository, build it, and copy
+`pnpm-workspace.yaml.example` to the gitignored
+`pnpm-workspace.yaml`. That optional override links the sibling checkout
+in place of the registry version. Do not commit the local lockfile
+rewrite it produces ([RELEASE-11](specs/dev/release.md#release-11)).
+
+Drive a Boss turn against the source tree with the launcher, which
+resolves `tmux-play`, the Playbook Captain shell, and the CODE registry
+from the local package:
 
 ```sh
-pnpm exec tmux-play --config reference/sdlc/code.playbook/tmux-play.config.yaml
+pnpm playbook
 ```
 
-`pnpm exec` resolves `tmux-play` from the package's local
-`node_modules/.bin/`, so this works whether or not `@sublang/cligent` is
-installed globally.
+On first run this seeds the generic config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`
+(see [Configure agents](#configure-agents)) and launches the composed
+session, so this works whether or not `@sublang/cligent` is installed
+globally.
 
 ### Running a Boss turn
 
 The Boss pane starts at the Playbook Captain shell. Use `/code <task>`
 to explicitly select the CODE playbook, or use ordinary text and let the
-shell route it. Once a turn reaches CODE, the CODE judge classifies it
-into an FSM event (start a coding turn, continue or summarize an IR,
-interrupt to a named state, or nothing) per
+compiled default Captain ask a material routing question or plan one or more
+enabled playbook calls. It cannot answer the initial intent directly;
+calls run sequentially so Captain can reassess after every child result
+and then return a concrete result or actionable conclusion. Once a turn
+reaches CODE, the CODE judge classifies it into an FSM event (start a coding
+turn, continue or summarize an iteration, interrupt to a named state, or
+nothing) per
 [PBRT-1](specs/user/playbook-runtime.md#pbrt-1).
 When a player surfaces a clarifying question
-the FSM parks at `awaitBossReply` and the pane shows the question; your
-next turn is normally classified as the reply, or a fresh directive
+the FSM parks, the pane shows the question, and your
+next turn is normally classified as the reply — or a fresh directive
 abandons it ([PBRT-2](specs/user/playbook-runtime.md#pbrt-2)).
 
 The Captain pane shows `/code` start/stop/finished status with `◇` lines
-and streams the CODE state machine with the four-glyph vocabulary `◆ ▸ ⮕ ⤷` per
-[PBRT-3](specs/user/playbook-runtime.md#pbrt-3), while player prompts
-ride their own panes.
-
-Published configs should import the shell adapter from
-`@sublang/playbook/playbook-captain`. Existing explicit configs that
-still import `@sublang/playbook/code/tmux-play` keep resolving through
-a compatibility shim that delegates to the same shell with CODE
-registered.
+and streams CODE progress with captain-speech classification/questions
+per [PBRT-3](specs/user/playbook-runtime.md#pbrt-3), while player
+prompts ride their own panes.
 
 ### Embedding the runtime in your own host
 
-The runtime is host-agnostic; the `tmux-play` adapter is one host.
-The port and runtime contracts live in the type-only module
-[`@sublang/playbook/runtime`](src/runtime.ts) — a public, semver-stable
-surface (`PlayerResult`, `PlaybookPorts`, `PlaybookRuntime`,
-`PlaybookRuntimeFactory`) that imports no CODE or FSM types, so a host
-satisfies it once and inherits every playbook. The CODE runtime
-re-exports `PlayerResult`, `PlaybookPorts`, and `PlaybookRuntime` from
-`@sublang/playbook/code/playbook`; `PlaybookRuntimeFactory` is available
-from `@sublang/playbook/runtime`.
-Construct the runtime against your own ports:
-
-```ts
-import createPlaybookRuntime from '@sublang/playbook/code/playbook';
-import type { PlaybookPorts } from '@sublang/playbook/runtime';
-
-const ports: PlaybookPorts = {
-  callPlayer: async (playerId, prompt, signal) => { /* … */ },
-  callJudge: async (prompt, signal) => { /* … */ },
-  emitStatus: async (message, data) => { /* … */ },
-  emitTelemetry: async ({ topic, payload }) => { /* … */ },
-};
-
-const runtime = createPlaybookRuntime({
-  coderPlayer: 'claude',
-  reviewerPlayer: 'codex',
-});
-
-await runtime.init(ports);
-await runtime.handleBossInput({
-  text: 'Start fixing the bug',
-  signal: new AbortController().signal,
-});
-await runtime.dispose();
-```
-
-See
-[`code.playbook.test.ts`](reference/sdlc/code.playbook/code.playbook.test.ts)
-for the full range of port shapes (classifier, judge, abort, interrupt,
-status/telemetry) the runtime is contract-tested against.
-
-### Reading the published spec contracts
-
-The authored compiler-phase specs ship in the package and are exposed
-as a public, semver-stable surface under `@sublang/playbook/slc/*`.
-Resolve and read one with `import.meta.resolve` plus `fs`:
-
-```ts
-import { readFile } from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-
-const url = import.meta.resolve('@sublang/playbook/slc/link.md');
-const link = await readFile(fileURLToPath(url), 'utf8');
-```
-
-The three specs are [`slc/text2gears.md`](slc/text2gears.md),
-[`slc/gears2fsm.md`](slc/gears2fsm.md), and [`slc/link.md`](slc/link.md)
-— the FSM-to-runtime contract that `@sublang/playbook/runtime` projects
-into TypeScript.
+The runtime is host-agnostic — the `tmux-play` adapter is one host. The
+port and runtime contracts live in the type-only, semver-stable module
+[`@sublang/playbook/runtime`](src/runtime.ts): a host satisfies the six
+ports once and inherits every playbook. See
+[docs/embedding.md](docs/embedding.md) for the contract surface, a
+complete ports example, session/trace semantics, and how to read the
+published compiler-phase specs from the package.
 
 ## Workflow
 
@@ -288,33 +346,25 @@ playbook is itself spec-driven: the compiler phases are specs in `slc/`,
 and the reference playbook is regenerated from its prose source. The
 loop:
 
-1. **Edit source.** For the reference, that's
-   [`reference/sdlc/code.md`](reference/sdlc/code.md).
+1. **Edit source.** The worked examples include
+   [`reference/sdlc/code.md`](reference/sdlc/code.md) and the generic
+   [`reference/sdlc/captain.md`](reference/sdlc/captain.md).
 2. **Recompile gears** per [`slc/text2gears.md`](slc/text2gears.md) into
-   the package's `code.gears.md`.
-3. **Recompile FSM** per [`slc/gears2fsm.md`](slc/gears2fsm.md) into
-   the package's `code.fsm.ts`.
+   the source's `<name>.playbook/<name>.gears.md`.
+3. **Recompile FSM and runtime** per
+   [`slc/gears2fsm.md`](slc/gears2fsm.md) and
+   [`slc/link.md`](slc/link.md) into that playbook artifact directory.
 4. **Sync runtime, tests, and downstream specs** so `pnpm test` stays
    green and the introspect contract holds 1:1 between gear items and
-   FSM captain-invoking states.
+   FSM direct-Captain, delegated-player, and nested-playbook states.
 5. **Commit** with co-author trailers per
    [`specs/dev/git.md`](specs/dev/git.md).
 
 The behavioral contract between gears and FSM
 ([PLAYBOOK-1..6](specs/dev/playbook.md)) and the runtime contract that
-ports satisfy ([PBRT-5..16](specs/dev/playbook-runtime.md)) are pinned
-in [`specs/dev/`](specs/dev/) and verified by tests under the reference
-package.
-
-## Requirements
-
-- Node.js ≥ 20.6.0 (the `playbook-code` shim uses
-  `import.meta.resolve`, unflagged since this release)
-- pnpm 9 (for the reference package)
-- A configured `tmux-play` host (for live Boss turns) — requires
-  `tmux` and [`glow`](https://github.com/charmbracelet/glow#installation)
-  on `PATH`; cligent 0.4+ uses `glow` to render Markdown pane
-  output and fails fast without it
+ports satisfy ([the PBRT dev items](specs/dev/playbook-runtime.md)) are
+pinned in [`specs/dev/`](specs/dev/) and verified by tests under the
+reference package.
 
 ## Contributing