@sublang/playbook 0.9.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)
 
@@ -91,6 +131,51 @@ bypass permissions. The seeded Codex Reviewer additionally grants
 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:
@@ -99,33 +184,44 @@ Edit the seeded user config when you want different coding agents:
 $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
+```
+
+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` Judge agent, optional `layout` /
-`notifications` / `theme`, and a `playbooks` map of enabled playbooks. Each
-`captain` or `players.<role>` value is a profile id or an adapter
+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 `coder` /
-`reviewer` 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 (e.g. CODE's `committer`) is that
-playbook's option slice. The launcher injects `captain.from` and the
-namespaced `<id>-<role>` host players, so you do not write those by
+`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.
 
-CODE's per-run `<coder-llm>` / `<reviewer-llm>` prompt strings come from
-each role's pinned `model`, else its `adapter`
-([PBRT-4](specs/user/playbook-runtime.md#pbrt-4)) — 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`).
-`committer` is an optional CODE alias naming which role — `coder` or
-`reviewer` — runs the commit turn; the seeded config points it at the
-Coder, and absent the alias the Committer falls back to the Coder
-([PBRT-8](specs/user/playbook-runtime.md#pbrt-8)).
-
 For example, the seeded config runs the Coder on Claude Opus 4.8 1m and
-the Reviewer on GPT-5.5, with the Committer aliased to the Coder:
+the Reviewer on GPT-5.5:
 
 ```yaml
 profiles:
@@ -134,13 +230,13 @@ profiles:
     model: claude-opus-4-8
     reasoningEffort: high
     permissions:
-      mode: auto        # protected auto mode for the Claude Captain
+      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        # protected auto mode for the Claude Coder
+      mode: auto # protected auto mode for the Claude Coder
   codex-gpt:
     adapter: codex
     model: gpt-5.5
@@ -148,19 +244,27 @@ profiles:
     permissions:
       mode: auto
       writablePaths:
-        - .git          # allow git metadata writes under Codex auto mode
+        - .git # allow git metadata writes under Codex auto mode
 
 captain: claude-opus
 
 playbooks:
   code:
-    from: "@sublang/playbook/code/registry"
+    from: '@sublang/playbook/code/registry'
     players:
       coder: claude-opus-1m
       reviewer: codex-gpt
-    committer: coder      # which role commits — `coder` or `reviewer`
+    committer: coder # which role commits — `coder` or `reviewer`
 ```
 
+`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
@@ -172,33 +276,23 @@ 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.
+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
@@ -218,87 +312,33 @@ globally.
 
 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 import the shell adapter from
-`@sublang/playbook/playbook-captain` and enable CODE through a
-`captain.options.playbooks.code` block whose `from` is
-`@sublang/playbook/code/registry`. The generic `playbook` launcher
-composes this for you from the top-level `profiles` / `playbooks`
-config above.
+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
 
@@ -306,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` launcher 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
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.9.0",
+  "version": "1.0.0",
   "type": "module",
-  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and Playbook Captain shell for a coder/reviewer/committer loop driven by GEARS spec items.",
+  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -28,9 +28,21 @@
     "src/runtime.ts",
     "src/runtime.js",
     "src/runtime.d.ts",
+    "src/xstate-runtime.ts",
+    "src/xstate-runtime.js",
+    "src/xstate-runtime.d.ts",
     "slc/link.md",
     "slc/gears2fsm.md",
     "slc/text2gears.md",
+    "slc/optimize.md",
+    "reference/sdlc/captain.md",
+    "reference/sdlc/captain.playbook/captain.gears.md",
+    "reference/sdlc/captain.playbook/captain.fsm.ts",
+    "reference/sdlc/captain.playbook/captain.fsm.js",
+    "reference/sdlc/captain.playbook/captain.fsm.d.ts",
+    "reference/sdlc/captain.playbook/captain.playbook.ts",
+    "reference/sdlc/captain.playbook/captain.playbook.js",
+    "reference/sdlc/captain.playbook/captain.playbook.d.ts",
     "reference/sdlc/code.playbook/code.fsm.ts",
     "reference/sdlc/code.playbook/code.fsm.js",
     "reference/sdlc/code.playbook/code.fsm.d.ts",
@@ -48,7 +60,18 @@
     "reference/sdlc/code.playbook/playbook-captain.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
-    "reference/sdlc/code.playbook/bin/playbook.js"
+    "reference/sdlc/code.playbook/bin/playbook.js",
+    "reference/sdlc/code.playbook/bin/run.js",
+    "reference/sdlc/discuss.playbook/discuss.gears.md",
+    "reference/sdlc/discuss.playbook/discuss.fsm.ts",
+    "reference/sdlc/discuss.playbook/discuss.fsm.js",
+    "reference/sdlc/discuss.playbook/discuss.fsm.d.ts",
+    "reference/sdlc/discuss.playbook/discuss.playbook.ts",
+    "reference/sdlc/discuss.playbook/discuss.playbook.js",
+    "reference/sdlc/discuss.playbook/discuss.playbook.d.ts",
+    "reference/sdlc/discuss.playbook/discuss.registry.ts",
+    "reference/sdlc/discuss.playbook/discuss.registry.js",
+    "reference/sdlc/discuss.playbook/discuss.registry.d.ts"
   ],
   "bin": {
     "playbook": "reference/sdlc/code.playbook/bin/playbook.js"
@@ -58,6 +81,14 @@
       "types": "./src/runtime.d.ts",
       "default": "./src/runtime.js"
     },
+    "./xstate-runtime": {
+      "types": "./src/xstate-runtime.d.ts",
+      "default": "./src/xstate-runtime.js"
+    },
+    "./captain/playbook": {
+      "types": "./reference/sdlc/captain.playbook/captain.playbook.d.ts",
+      "default": "./reference/sdlc/captain.playbook/captain.playbook.js"
+    },
     "./code/playbook": {
       "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
       "default": "./reference/sdlc/code.playbook/code.playbook.js"
@@ -70,7 +101,15 @@
       "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
       "default": "./reference/sdlc/code.playbook/playbook-captain.js"
     },
-    "./slc/*": "./slc/*"
+    "./slc/*": "./slc/*",
+    "./discuss/playbook": {
+      "types": "./reference/sdlc/discuss.playbook/discuss.playbook.d.ts",
+      "default": "./reference/sdlc/discuss.playbook/discuss.playbook.js"
+    },
+    "./discuss/registry": {
+      "types": "./reference/sdlc/discuss.playbook/discuss.registry.d.ts",
+      "default": "./reference/sdlc/discuss.playbook/discuss.registry.js"
+    }
   },
   "scripts": {
     "build": "tsc",
@@ -82,9 +121,10 @@
     "provenance": true
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.143",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.154",
     "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "^0.13.0",
+    "@sublang/cligent": "^0.15.0",
+    "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },

package/reference/sdlc/captain.md

@@ -0,0 +1,102 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Captain
+
+This is the default generic Captain playbook.
+It has no players beyond Boss and Captain.
+
+At runtime Captain receives the exact original Boss intent and a catalog of enabled callable playbooks.
+Each catalog entry contains only a stable playbook id, its command, and its intent.
+The catalog is immutable host input for the session; Boss events and Captain decisions cannot replace it.
+Captain shall call only ids in that catalog and shall never call this Captain playbook itself.
+Captain is a router, not the specialist that performs the requested work.
+Captain shall decide only from the supplied Boss text and catalog, without investigating the task, inspecting the workspace, using tools, or relying on ambient project evidence.
+Captain shall keep a finite ordered plan and issue at most one child call at a time.
+`remainingPlan` shall contain only calls after the selected next call; every continuation shall strictly reduce its length.
+After Captain consumes an answer to its own routing or reassessment question,
+that question and answer are no longer pending before Captain calls a child or
+completes.
+
+The host guarantees that this Captain receives Boss input only while it is the active leaf and resumes only from a matching child return.
+That guarantee is an execution precondition, not a behavior for Captain to perform and not a source item to compile.
+An ordinary non-empty Boss turn at the ready state enters as a new intent with the exact Boss text and does not require model classification.
+When parked work can accept either an answer or a fresh directive, a classifier may select only the event kind and routing metadata; the runtime attaches the exact Boss text as the answer or fresh intent.
+These input-provenance rules are linker preconditions, not behaviors for Captain to perform and not source items to compile.
+
+When Boss gives a new intent while Captain is the active playbook, Captain shall ask Boss one material routing question or select the first call in a one- or multi-playbook plan, using the following prompt:
+> Boss intent: <boss-intent>
+> Enabled playbooks: <enabled-playbooks>
+> You are routing this intent, not performing the requested work.
+> Use only the Boss intent and enabled-playbooks catalog supplied here.
+> Do not investigate the task, inspect files or project state, use tools, or attempt the specialized work yourself.
+> Preserve Boss's intended outcome and constraints.
+> If the supplied evidence identifies a useful route, select an enabled playbook; do not finish the intent yourself.
+> Ask exactly one concise question only when its answer is necessary to choose a useful route or call order.
+> For a complex intent, divide it into the smallest finite ordered plan of useful playbook calls.
+> Name the selected first playbook and state its complete standalone request containing only the context it needs.
+> List any later playbook calls in their intended order after the selected first call.
+> Do not call a playbook merely to restate or classify the intent.
+> Write only concise human-facing routing prose or the one routing question.
+> Do not emit JSON, guard names, result property names, or control instructions.
+> Do not expose internal state ids, session ids, call ids, stack data, hidden control data, or private reasoning.
+
+Results:
+- `question`: Captain asked the one material routing question. Output shall include `question: <verbatim final text from the visible Captain call>`.
+- `delegation`: Captain selected the first useful call. Output shall include `remainingPlan: <finite JSON-safe array of only later calls>`, `nextPlaybookId: <selected stable enabled-playbook id>`, and `nextPlaybookInput: <complete standalone request>`.
+
+A fresh directive that interrupts any parked Captain work shall restart this
+routing behavior with that fresh intent. It shall not jump directly into
+reassessment or retain the prior question, answer, plan, call history,
+evidence, selection, response, or error.
+
+A question decision shall carry one concise `question` and wait for Boss without losing the original intent.
+Boss's answer resumes this same routing decision with continuation context; it is not a separate Captain behavior.
+A delegation decision shall carry a finite `remainingPlan` plus non-empty `nextPlaybookId` and `nextPlaybookInput` for its first call.
+The compiled routing result guards are exactly `question` and `delegation`, respectively; these names are part of this default playbook's stable machine contract.
+The initial routing state has no direct or terminal outcome.
+
+When Captain selects a next call with a non-empty `nextPlaybookId` from the enabled catalog, Captain shall call playbook selected by `nextPlaybookId`:
+> <nextPlaybookInput>
+
+When the called playbook returns successfully, aborts, or fails, Captain shall reassess the original intent, remaining plan, and completed call results using the following prompt:
+> Boss intent: <boss-intent>
+> Enabled playbooks: <enabled-playbooks>
+> Remaining plan: <remaining-plan>
+> Completed call results: <completed-call-results>
+> Preserve Boss's intended outcome and constraints.
+> Treat each returned result as evidence and revise the remaining plan when needed.
+> A continuing decision must strictly reduce the remaining plan length.
+> Do not repeat an equivalent failed or completed call without new information.
+> If the intent is fulfilled, give Boss one concise final response that states the result or actionable conclusion.
+> Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.
+> If information from Boss is now necessary, ask exactly one concise question.
+> Otherwise name exactly one next enabled playbook and state its complete standalone request containing only the context it needs.
+> List any still-later playbook calls in their intended order after the selected next call.
+> Write only concise human-facing final, question, or routing prose.
+> Do not emit JSON, guard names, result property names, or control instructions.
+> Do not expose internal state ids, session ids, call ids, stack data, hidden control data, or private reasoning.
+
+Results:
+- `final`: Captain gave Boss the concrete result or actionable conclusion. Output shall include `response: <verbatim final text from the visible Captain call>`.
+- `followUpQuestion`: Captain asked one necessary follow-up question. Output shall include `question: <verbatim final text from the visible Captain call>`.
+- `continuing`: Captain selected another useful call. Output shall include `remainingPlan: <strictly shorter finite JSON-safe array of only later calls>`, `nextPlaybookId: <selected stable enabled-playbook id>`, and `nextPlaybookInput: <complete standalone request>`.
+
+For the machine's deterministic safety floor, two calls are the same only when
+both the stable target id and complete standalone input match exactly.
+Captain shall record that exact pair before invoking the child, so an `ok`,
+`aborted`, or `error` return all prevent the same later attempt. An input
+revised with new information is different for this exact check; Captain still
+owns the broader semantic no-repeat instruction above.
+
+Each completed call result shall contain only the selected playbook id, its `ok`, `aborted`, or `error` status, and either the child's actual JSON-safe output or a compact error with only `name` and `message`.
+It shall never retain or expose a child session id, call id, child state, stack trace, or an opaque runtime result object.
+
+A final decision shall carry a concise JSON-safe `response` and complete.
+A follow-up question shall carry one concise `question` and wait for Boss without losing the original intent, plan, or completed results.
+Boss's answer resumes this same reassessment with continuation context; it is not a separate Captain behavior.
+A continuing decision shall carry a strictly shorter finite `remainingPlan` plus non-empty `nextPlaybookId` and `nextPlaybookInput`.
+The compiled reassessment result guards are exactly `final`,
+`followUpQuestion`, and `continuing`, respectively; these names are part of
+this default playbook's stable machine contract.
+A child abort or failure is a completed call result for reassessment and shall not route this playbook directly to its generic failure state.