@sublang/playbook 0.1.0

package/code.tmux-play.d.ts

@@ -0,0 +1,2 @@
+import type { Captain } from '@sublang/cligent/tmux-play';
+export default function createCodeTmuxPlayCaptain(options: unknown): Captain;

package/code.tmux-play.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime from './code.playbook.js';
+// Captain factory per TMUX-014: `(options: unknown) => Captain`.
+// `options` is whatever `captain.options` carries in the YAML config;
+// for the CODE playbook this is `CodePlaybookOptions` (coderPlayer,
+// reviewerPlayer, plus the rest of CodingInput).
+export default function createCodeTmuxPlayCaptain(options) {
+    const runtime = createPlaybookRuntime(options);
+    // CaptainSession is bound at init time and persists across turns;
+    // CaptainContext is rebuilt per turn and carries the call
+    // primitives. PlaybookPorts is built once at init, so the per-turn
+    // context lives in a closure-scoped slot the port callbacks query
+    // lazily.
+    let activeContext;
+    return {
+        async init(session) {
+            const ports = {
+                callPlayer: async (playerId, prompt, _signal) => {
+                    if (!activeContext) {
+                        throw new Error('callPlayer invoked outside a Boss turn');
+                    }
+                    // RoleRunResult per TMUX-033 already matches PlayerResult
+                    // (`status: 'ok' | 'aborted' | 'error'`, `finalText?`,
+                    // `error?`). cligent honors context.signal internally;
+                    // the runtime's signal is the same source forwarded
+                    // through handleBossInput, so dropping `_signal` is
+                    // safe.
+                    const r = await activeContext.callRole(playerId, prompt);
+                    return {
+                        status: r.status,
+                        finalText: r.finalText,
+                        error: r.error,
+                    };
+                },
+                callJudge: async (prompt, _signal) => {
+                    if (!activeContext) {
+                        throw new Error('callJudge invoked outside a Boss turn');
+                    }
+                    const r = await activeContext.callCaptain(prompt);
+                    if (r.status !== 'ok') {
+                        throw new Error(r.error ?? `callCaptain status "${r.status}"`);
+                    }
+                    if (r.finalText === undefined) {
+                        throw new Error('callCaptain returned status=ok with no finalText');
+                    }
+                    return r.finalText;
+                },
+                emitStatus: async (message, data) => {
+                    await session.emitStatus(message, data);
+                },
+                emitTelemetry: async (event) => {
+                    await session.emitTelemetry(event);
+                },
+            };
+            await runtime.init(ports);
+        },
+        async handleBossTurn(turn, context) {
+            activeContext = context;
+            try {
+                // Forward the Boss prompt + cligent's per-turn signal into
+                // the runtime; the runtime stashes the signal so the
+                // captain bridge passes it down to callPlayer / callJudge.
+                await runtime.handleBossInput({
+                    text: turn.prompt,
+                    signal: context.signal,
+                });
+            }
+            finally {
+                activeContext = undefined;
+            }
+        },
+        async dispose() {
+            await runtime.dispose();
+        },
+    };
+}

package/code.tmux-play.ts

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// tmux-play host adapter for the CODE playbook — DR-004 §11. This is
+// the only file in IR-004 that imports cligent; removing the import
+// shall not affect code.playbook.ts or its tests.
+
+import type {
+  BossTurn,
+  Captain,
+  CaptainContext,
+  CaptainSession,
+} from '@sublang/cligent/tmux-play';
+import createPlaybookRuntime, {
+  type CodePlaybookOptions,
+  type PlaybookPorts,
+  type PlaybookRuntime,
+} from './code.playbook.js';
+
+// Captain factory per TMUX-014: `(options: unknown) => Captain`.
+// `options` is whatever `captain.options` carries in the YAML config;
+// for the CODE playbook this is `CodePlaybookOptions` (coderPlayer,
+// reviewerPlayer, plus the rest of CodingInput).
+export default function createCodeTmuxPlayCaptain(
+  options: unknown,
+): Captain {
+  const runtime: PlaybookRuntime = createPlaybookRuntime(
+    options as CodePlaybookOptions,
+  );
+
+  // CaptainSession is bound at init time and persists across turns;
+  // CaptainContext is rebuilt per turn and carries the call
+  // primitives. PlaybookPorts is built once at init, so the per-turn
+  // context lives in a closure-scoped slot the port callbacks query
+  // lazily.
+  let activeContext: CaptainContext | undefined;
+
+  return {
+    async init(session: CaptainSession): Promise<void> {
+      const ports: PlaybookPorts = {
+        callPlayer: async (playerId, prompt, _signal) => {
+          if (!activeContext) {
+            throw new Error('callPlayer invoked outside a Boss turn');
+          }
+          // RoleRunResult per TMUX-033 already matches PlayerResult
+          // (`status: 'ok' | 'aborted' | 'error'`, `finalText?`,
+          // `error?`). cligent honors context.signal internally;
+          // the runtime's signal is the same source forwarded
+          // through handleBossInput, so dropping `_signal` is
+          // safe.
+          const r = await activeContext.callRole(playerId, prompt);
+          return {
+            status: r.status,
+            finalText: r.finalText,
+            error: r.error,
+          };
+        },
+        callJudge: async (prompt, _signal) => {
+          if (!activeContext) {
+            throw new Error('callJudge invoked outside a Boss turn');
+          }
+          const r = await activeContext.callCaptain(prompt);
+          if (r.status !== 'ok') {
+            throw new Error(
+              r.error ?? `callCaptain status "${r.status}"`,
+            );
+          }
+          if (r.finalText === undefined) {
+            throw new Error(
+              'callCaptain returned status=ok with no finalText',
+            );
+          }
+          return r.finalText;
+        },
+        emitStatus: async (message, data) => {
+          await session.emitStatus(
+            message,
+            data as Record<string, unknown> | undefined,
+          );
+        },
+        emitTelemetry: async (event) => {
+          await session.emitTelemetry(event);
+        },
+      };
+      await runtime.init(ports);
+    },
+
+    async handleBossTurn(
+      turn: BossTurn,
+      context: CaptainContext,
+    ): Promise<void> {
+      activeContext = context;
+      try {
+        // Forward the Boss prompt + cligent's per-turn signal into
+        // the runtime; the runtime stashes the signal so the
+        // captain bridge passes it down to callPlayer / callJudge.
+        await runtime.handleBossInput({
+          text: turn.prompt,
+          signal: context.signal,
+        });
+      } finally {
+        activeContext = undefined;
+      }
+    },
+
+    async dispose(): Promise<void> {
+      await runtime.dispose();
+    },
+  };
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@sublang/playbook",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and tmux-play adapter for a coder/reviewer/committer loop driven by GEARS spec items.",
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/sublang-ai/playbook#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sublang-ai/playbook.git"
+  },
+  "bugs": "https://github.com/sublang-ai/playbook/issues",
+  "keywords": [
+    "ai",
+    "agent",
+    "playbook",
+    "state-machine",
+    "xstate",
+    "gears",
+    "sdlc",
+    "cligent",
+    "tmux-play"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "code.fsm.ts",
+    "code.fsm.js",
+    "code.fsm.d.ts",
+    "code.fsm.introspect.ts",
+    "code.fsm.introspect.js",
+    "code.fsm.introspect.d.ts",
+    "code.playbook.ts",
+    "code.playbook.js",
+    "code.playbook.d.ts",
+    "code.tmux-play.ts",
+    "code.tmux-play.js",
+    "code.tmux-play.d.ts",
+    "code.gears.md",
+    "tmux-play.config.yaml",
+    "tmux-play.production.config.yaml",
+    "bin"
+  ],
+  "bin": {
+    "playbook-code": "./bin/playbook-code.js"
+  },
+  "exports": {
+    "./code/playbook": {
+      "types": "./code.playbook.d.ts",
+      "default": "./code.playbook.js"
+    },
+    "./code/tmux-play": {
+      "types": "./code.tmux-play.d.ts",
+      "default": "./code.tmux-play.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@sublang/cligent": "^0.3.0",
+    "xstate": "^5.0.0"
+  },
+  "devDependencies": {
+    "@sublang/cligent": "^0.3.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "xstate": "^5.19.4"
+  }
+}

package/tmux-play.config.yaml

@@ -0,0 +1,33 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+# Example tmux-play config for the CODE playbook — DR-004 §11.
+# Run with:
+#   tmux-play --config tmux-play.config.yaml
+
+captain:
+  # Dev form: sibling-path import of the compiled adapter. After
+  # @sublang/playbook is published, swap this for the package
+  # specifier — e.g.
+  #   from: "@sublang/playbook/code/tmux-play"
+  # (final form confirmed at publish time per DR-004 §11). Roles,
+  # options, and the rest of the config are unchanged.
+  from: ./code.tmux-play.js
+  adapter: claude
+  model: claude-opus-4-7
+  options:
+    # Substituted into the <coder-llm> placeholder in player prompts
+    # (DR-004 §6).
+    coderPlayer: claude
+    # Substituted into <reviewer-llm>.
+    reviewerPlayer: codex
+
+# `roles[].id` shall match the baked playerId strings the adapter
+# routes to. The CODE playbook bakes Coder→'coder' and
+# Reviewer→'reviewer' at link time (DR-004 §2); the adapter does
+# not remap, so changing these ids would break callRole routing.
+roles:
+  - id: coder
+    adapter: claude
+  - id: reviewer
+    adapter: codex

package/tmux-play.production.config.yaml

@@ -0,0 +1,21 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+# Production tmux-play config for the published CODE playbook package.
+# This intentionally imports the adapter through the package export, not
+# a local repo path. The runtime still expects the host app to provide the
+# @sublang/cligent peer dependency.
+
+captain:
+  from: "@sublang/playbook/code/tmux-play"
+  adapter: claude
+  model: claude-opus-4-7
+  options:
+    coderPlayer: claude
+    reviewerPlayer: codex
+
+roles:
+  - id: coder
+    adapter: claude
+  - id: reviewer
+    adapter: codex