@sublang/playbook 1.3.0 → 3.0.0

package/docs/configuration.md

@@ -0,0 +1,158 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Configuring agents
+
+`playbook` reads one config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`. The
+first launch seeds it from the bundled starter and prints the path;
+later launches reuse it untouched.
+
+```sh
+$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
+```
+
+## Anatomy
+
+The config is top-level (no `config:` wrapper): 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 either an adapter shorthand
+(`claude`, `codex`) or a block carrying that agent's own `adapter`,
+`model`, `effort`, and `permissions`. Settings are inline per agent, so
+tuning one player never changes another
+([DR-021](../specs/decisions/021-inline-agent-settings.md)). Other
+adapter ids pass through to `tmux-play` with a warning, because
+`playbook` cannot preflight their auth.
+
+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.
+
+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
+  effort: high
+  permissions:
+    mode: auto # protected auto mode for the Claude Captain
+
+playbooks:
+  code:
+    from: '@sublang/playbook/code/registry'
+    players:
+      coder:
+        adapter: claude
+        model: claude-opus-4-8[1m]
+        effort: xhigh
+        permissions:
+          mode: auto # protected auto mode for the Claude Coder
+      reviewer:
+        adapter: codex
+        model: gpt-5.5
+        effort: xhigh
+        permissions:
+          mode: auto
+          writablePaths:
+            - .git # allow git metadata writes under Codex auto mode
+    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
+credit the concrete model rather than the adapter family.
+
+## Choosing the Captain agent
+
+Hidden routing and adjudication calls run tool-free, which is what keeps
+the Captain routing instead of doing the work itself. Claude enforces
+that at the provider level. The Codex adapter cannot — it rejects any
+tool list — so a `captain:` on `codex` falls back to a prompt-level
+restriction
+([DR-013 A1](../specs/decisions/013-routing-only-captain-control.md#addendum-a1-prompt-level-isolation-for-adapters-without-tool-enforcement)).
+Codex remains a good choice for *players*, where full tools are wanted.
+
+Adapter readiness is intentionally light: `claude` is ready with local
+Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
+auth or `OPENAI_API_KEY`. A known adapter that is not ready blocks the
+launch and prints the help text.
+
+## Per-launch overlays
+
+To retune one launch without editing the 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.
+playbooks:
+  code:
+    players:
+      coder:
+        adapter: codex
+        model: gpt-5.5
+        effort: medium
+        permissions:
+          mode: auto
+          # The seeded `committer` is `coder`, so this role runs the commit
+          # turn; a Codex agent needs the `.git` grant to write git metadata.
+          writablePaths:
+            - .git
+```
+
+Fragments merge into the agent block rather than replacing it, so
+settings the base defines and the fragment omits — here `mode: auto` —
+survive. Anything the adapter itself requires must still be stated: a
+role switched to `codex` needs its own `writablePaths` grant, because
+the base Claude block had no reason to carry one.
+
+The global file is never modified, and `--with` is not forwarded to
+`tmux-play` ([PBCLI-25](../specs/user/playbook-cli.md#pbcli-25)).
+
+## Defaults for `playbook run`
+
+An optional top-level `run` block supplies the non-interactive host's
+lineup so you stop retyping flags — `run.captain`, `run.players.<role>`,
+and a `run.player` catch-all for any other required role, each an
+`<adapter>[:<model>][@<effort>]` string. Flags win per role, and
+`resume` always keeps the lineup stored with the parked session
+([PBCLI-28](../specs/user/playbook-cli.md#pbcli-28),
+[DR-017](../specs/decisions/017-run-defaults-config.md)).
+
+```yaml
+run:
+  captain: claude:claude-opus-4-8@high
+  players:
+    coder: claude:claude-opus-4-8[1m]@xhigh
+```
+
+## Migrating from `profiles`
+
+Configs written before 3.0.0 carried a top-level `profiles` map. The
+launcher rewrites such a config on the next launch — inlining each
+profile's settings into the agent that named it, keeping your comments,
+and saving the original as `<config>.bak` — then continues. Nothing to
+do by hand.
+
+## Using a raw tmux-play config
+
+For a one-off, pass a raw `tmux-play` config explicitly. This bypasses
+the seed, composition, and readiness gate, forwarding arguments to
+`tmux-play` verbatim ([PBCLI-1](../specs/user/playbook-cli.md#pbcli-1)):
+
+```sh
+playbook --config ./tmux-play.config.yaml
+```

package/docs/embedding.md

@@ -0,0 +1,161 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Embedding the runtime in your own host
+
+The playbook runtime is host-agnostic; cligent's `tmux-play` adapter is
+one host, and [spex](https://github.com/sublang-ai/spex) (the desktop
+app) is another. This guide shows how to wire a playbook runtime into
+your own host.
+
+> **Release note:** this guide targets the semver-stable 1.0 six-port
+> contract; see the [CHANGELOG](../CHANGELOG.md) for migration details.
+
+## The runtime contract
+
+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`, `PlaybookSession`, `PlayerCallOptions`,
+`CaptainCallOptions`, `CaptainResult`, `PlaybookTraceEvent`, and
+`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`, `PlaybookSession`, and
+`PlaybookRuntime` from `@sublang/playbook/code/playbook`;
+`PlaybookRuntimeFactory` is available from `@sublang/playbook/runtime`.
+
+Generated linked runtimes reuse the XState integration engine exposed
+as `@sublang/playbook/xstate-runtime`, including strict JSON
+validation, normalized snapshots, quiescence waiting, and the
+nested-playbook bridge.
+
+## Constructing a runtime against your own ports
+
+```ts
+import createPlaybookRuntime from '@sublang/playbook/code/playbook';
+import type {
+  CaptainCallOptions,
+  CaptainResult,
+  PlaybookPorts,
+} from '@sublang/playbook/runtime';
+import { randomUUID } from 'node:crypto';
+import PQueue from 'p-queue';
+
+declare const captainAdapter: {
+  run(
+    prompt: string,
+    options: {
+      signal: AbortSignal;
+      visibility: 'visible' | 'hidden';
+      resume: string | false;
+      allowedTools?: readonly string[];
+    },
+  ): Promise<CaptainResult>;
+};
+
+// Construct one host-wide lane and reuse it for every runtime. Passing each
+// call's signal to both the lane and adapter cancels queued and active work.
+const captainLane = new PQueue({ concurrency: 1 });
+
+async function runCaptain(
+  prompt: string,
+  signal: AbortSignal,
+  options: CaptainCallOptions,
+): Promise<CaptainResult> {
+  return await captainLane.add(
+    () => captainAdapter.run(prompt, { signal, ...options }),
+    { signal },
+  );
+}
+
+const ports: PlaybookPorts = {
+  callPlayer: async (playerId, prompt, signal, { resume }) => {
+    // `resume === false` starts fresh; a string selects that player's
+    // prior backend conversation. Return the adapter's next token.
+    return { status: 'ok', finalText: 'done', resumeToken: 'next-token' };
+  },
+  callCaptain: async (prompt, signal, options) => {
+    // Forward every option exactly: omission preserves configured tools, while
+    // an explicit empty allowlist requests a tool-free call and must fail closed
+    // when the adapter cannot enforce it.
+    return await runCaptain(prompt, signal, options);
+  },
+  callJudge: async (prompt, signal) => {
+    // Judge work is hidden control work: run it fresh and tool-free.
+    const result = await runCaptain(prompt, signal, {
+      visibility: 'hidden',
+      resume: false,
+      allowedTools: [],
+    });
+    if (result.status !== 'ok' || result.finalText === undefined) {
+      throw new Error(result.error ?? 'Judge call failed');
+    }
+    return result.finalText;
+  },
+  callPlaybook: async (request, signal) => {
+    throw new Error('No nested playbook host configured');
+  },
+  emitStatus: async (message, data) => {
+    /* … */
+  },
+  emitTelemetry: async ({ topic, payload }) => {
+    /* … */
+  },
+};
+
+const runtime = createPlaybookRuntime({
+  coderPlayer: 'claude',
+  reviewerPlayer: 'codex',
+});
+
+const playbookSessionId = randomUUID();
+await runtime.init({
+  sessionId: playbookSessionId,
+  playbookId: 'code',
+  rootSessionId: playbookSessionId,
+  depth: 0,
+  ports,
+});
+await runtime.handleBossInput({
+  text: 'Start fixing the bug',
+  signal: new AbortController().signal,
+});
+await runtime.dispose();
+```
+
+## Sessions and traces
+
+Every init-to-dispose lifecycle is one playbook session. Its
+`playbook.trace` telemetry carries that immutable ID plus a contiguous
+sequence across exact Boss input, judge/player calls, FSM transitions,
+visible Captain work, nested playbook calls, status, settlement, and
+disposal. Each resolved player starts fresh in a new playbook session
+and then resumes only from the latest opaque `resumeToken` its adapter
+returned; trace data and tokens never enter Boss-visible status text.
+Because trace observers do receive opaque resume tokens, persisted
+traces should be protected as sensitive data.
+
+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 four specs are [`slc/text2gears.md`](../slc/text2gears.md),
+[`slc/gears2fsm.md`](../slc/gears2fsm.md),
+[`slc/link.md`](../slc/link.md) — the FSM-to-runtime contract that
+`@sublang/playbook/runtime` projects into TypeScript — and
+[`slc/optimize.md`](../slc/optimize.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "1.3.0",
+  "version": "3.0.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -39,6 +39,8 @@
     "slc/text2gears.md",
     "slc/optimize.md",
     "reference/sdlc/captain.md",
+    "reference/sdlc/code.md",
+    "reference/sdlc/discuss.md",
     "reference/sdlc/captain.playbook/captain.gears.md",
     "reference/sdlc/captain.playbook/captain.fsm.ts",
     "reference/sdlc/captain.playbook/captain.fsm.js",
@@ -74,7 +76,8 @@
     "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"
+    "reference/sdlc/discuss.playbook/discuss.registry.d.ts",
+    "docs"
   ],
   "bin": {
     "playbook": "reference/sdlc/code.playbook/bin/playbook.js"
@@ -117,6 +120,7 @@
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
+    "test:acceptance": "vitest run --config vitest.acceptance.config.ts",
     "playbook": "node reference/sdlc/code.playbook/bin/playbook.js"
   },
   "publishConfig": {
@@ -126,7 +130,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.154",
     "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "^0.15.0",
+    "@sublang/cligent": "^0.16.0",
     "@sublang/spex": "^0.3.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/code.md

@@ -0,0 +1,105 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Code
+
+Players:
+
+- Coder
+- Reviewer
+- Committer = Coder | Reviewer
+
+## Coder
+
+When Boss gives a coding intent, Captain shall relay it to Coder along with the following prompt:
+> Assess whether this can be completed in a single commit, following best practices.
+> If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/intents (or @specs/iterations in older scaffolds) and stop without implementing any IR task.
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Ensure @specs/map.md reflects the changes.
+> Do not commit.
+The resulting changes are regarded as Initial Changes.
+
+When Reviewer raises any findings, Captain shall relay them to Coder along with the following prompt:
+> For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
+> Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.
+
+When a new IR or IR task passes review and is committed, Captain shall prompt Coder:
+> Continue to implement IR-<#> if not all deliverables and tasks are done.
+> Implement one task at a time (including corresponding tests if any).
+> Stop after each task for review — do not commit yet.
+> If relevant, mark progress in the IR.
+The resulting changes are regarded as Initial Changes.
+
+When an IR is done, Captain shall prompt Coder:
+> Read IR-<#> and corresponding commits.
+> According to @specs/meta.md, add or update spec items to fully capture:
+>
+> - the external behavior users rely on,
+> - the internal system behavior, and
+> - the integration/system test cases.
+>
+> The spec items should be the *minimal* set needed to reimplement code without the IR.
+> The set should be complete and coherent.
+> Avoid implementation specifics.
+> Avoid redundant spec items.
+> Ensure @specs/map.md reflects the changes.
+
+## Reviewer
+
+For each finding in a review round, Coder either addresses it with changes or challenges it with a rebuttal.
+Any code change to address findings starts a new round of review, even if some findings are also rebutted.
+Rounds continue until Reviewer raises no findings.
+
+Spec item files are the files under @specs/ that hold spec items — @specs/packages/ and @specs/compositions/ in the current layout, or @specs/user/, @specs/dev/, and @specs/test/ in the legacy one; decision and intent records (iteration records in older scaffolds), @specs/map.md, and @specs/meta.md are not spec item files.
+
+When Reviewer begins the first review round on changes from a Boss coding intent, Captain shall relay the intent to Reviewer.
+
+When Reviewer begins the first review round on changes from an IR task, Captain shall relay the IR's task description to Reviewer.
+
+When Committer commits Initial Changes, Captain shall prompt Reviewer to begin a review round:
+> Review the latest commit.
+> Refer to the commit message.
+
+When any changes are made by Coder but not reviewed (outside of any Initial Changes), Captain shall prompt Reviewer to begin a review round:
+> Review the unstaged and untracked changes in the context of the staged changes.
+> Understand the intent.
+
+When Reviewer begins a review round involving spec item files, Captain shall prompt Reviewer:
+> Verify any affected spec items are:
+>
+> - Complete & coherent: sufficient for you to reimplement code.
+> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
+> - Minimal: essential and concise; every item earns its place; also check with other items.
+> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
+>
+> Flag anything missing, redundant, over-specified, or under-specified.
+
+When Reviewer begins a review round involving any changes outside spec item files, Captain shall prompt Reviewer:
+> Flag any issues or improvements (numbered; no duplication).
+> Think thoroughly — don't just approve or reject.
+
+When Reviewer begins any review round, Captain shall prompt Reviewer:
+> For context discovery, @specs/map.md indexes all spec files and @specs/meta.md describes the spec format.
+> Verify @specs/map.md reflects the changes.
+> If the change is ready to commit or push, don't raise nitpicks.
+> Do not edit files or commit; report findings only.
+
+When Coder raises any rebuttals, Captain shall relay them to Reviewer along with the following prompt:
+> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
+> Do not edit files or commit; report findings only.
+
+## Committer
+
+When Coder makes any Initial Changes or Reviewer raises no findings on uncommitted changes, Captain shall prompt Committer:
+> Make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
+> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
+> Write the commit message concisely.
+
+When Captain prompts Committer and only Coder has played since the last commit, Captain shall also append:
+> Coder is \<coder-llm\>.
+
+When Captain prompts Committer and both Coder and Reviewer have played since the last commit, Captain shall also append:
+> Coder is \<coder-llm\>; Reviewer is \<reviewer-llm\>.
+
+When Captain prompts Committer, Captain shall also append:
+> Format the `Co-authored-by` `<model>` token as the conventional human form of the substituted id (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).