@sublang/playbook 0.2.0 → 0.4.1

package/reference/sdlc/code.playbook/code.playbook.ts

@@ -65,10 +65,15 @@ const BOSS_REPLY_ERRORS = {
 
 // Player-prompt composer — DR-004 §6.
 // Substitutes the three placeholder tokens in `input.prompt` (literal
-// string replace, no escaping) and prepends labelled blocks for any
-// populated structured field. When a state resumes from a Boss reply,
-// the continuation preamble and Q/A blocks precede the ordinary
-// labelled blocks. The FSM's prompt body is never re-flowed.
+// string replace, no escaping) and arranges labelled blocks around
+// the prompt body. Context blocks the body refers to as prior
+// material (`Boss intent:`, `Task description:`) are prepended;
+// action blocks the body refers to as material below
+// (`Review items:`, `Rebuttals:`) are appended after the body so the
+// CODE-N prompts' "review item below" / "rebuttal below" phrasing
+// matches the rendered layout. When a state resumes from a Boss
+// reply, the continuation preamble and Q/A blocks precede every
+// ordinary block. The FSM's prompt body is never re-flowed.
 
 function composePlayerPrompt(input: CaptainInput): string {
   const blocks: string[] = [];
@@ -85,12 +90,6 @@ function composePlayerPrompt(input: CaptainInput): string {
   if (input.intent !== undefined) {
     blocks.push(`Boss intent:\n${input.intent}`);
   }
-  if (input.reviews !== undefined) {
-    blocks.push(`Review items:\n${input.reviews}`);
-  }
-  if (input.challenges !== undefined) {
-    blocks.push(`Rebuttals:\n${input.challenges}`);
-  }
   if (input.taskDescription !== undefined) {
     blocks.push(`Task description:\n${input.taskDescription}`);
   }
@@ -107,6 +106,14 @@ function composePlayerPrompt(input: CaptainInput): string {
   }
 
   blocks.push(body);
+
+  if (input.reviews !== undefined) {
+    blocks.push(`Review items:\n${input.reviews}`);
+  }
+  if (input.challenges !== undefined) {
+    blocks.push(`Rebuttals:\n${input.challenges}`);
+  }
+
   return blocks.join('\n\n');
 }
 
@@ -478,14 +485,23 @@ function captainBridge(
 }
 
 // Captain pane display — PBRT-3 / PBRT-14.
-// The Captain pane is a stream keyed on four glyphs so a reader can
-// parse each line at a glance:
-//   ◆  basic idle entry (ready / done / failed)
-//   ▸  Boss input echo
-//   ⮕  captain-invoking state entry (label + player + CODE-N)
-//   ⤷  transition (guard fired by the just-finished captain call)
-// Prompts and full player output ride the player panes; the Captain
-// pane keeps to the state-machine shape.
+// The Captain pane is a stream of three glyphs plus one bare
+// captain-speech act, designed so a reader can parse each line at a
+// glance:
+//   (no glyph)  bare FSM event type — host renders as captain speech
+//               (e.g., `captain> START_CODING`)
+//   ⤷           captain-invoking state entry: `<Player>: <label>`
+//   →           transition guard outcome (`· field=N` tallies
+//               appended); the host presenter owns any visual
+//               nesting under the preceding ⤷ entry
+
+//   ◆           failure state (with `lastError` data) and the
+//               `awaitBossReply` suspension state (custom payload)
+// The runtime emits no status line on entry to the idle state
+// (`ready`) or the terminal state (`done`); the next `boss>` prompt
+// is the implicit "turn over" signal. Prompts and full player output
+// ride the player panes; the Captain pane keeps to the state-machine
+// shape.
 
 const STATE_LABELS: Readonly<Record<string, string>> = {
   planAndImplement: 'plan & implement',
@@ -569,16 +585,21 @@ const QUIESCENT_STATES: ReadonlySet<string> = new Set([
   'failed',
 ]);
 
-// awaitBossReply is quiescent too, but uses a custom single-line
-// status frame rather than the plain `◆ <state>` entry.
-const BASIC_IDLE_GLYPH_STATES: ReadonlySet<string> = new Set(
-  [...QUIESCENT_STATES].filter((stateId) => stateId !== 'awaitBossReply'),
-);
+// States whose entry the runtime does not surface on the Captain
+// pane per PBRT-3: the readline returning to its `boss>` prompt is
+// the implicit "turn over" signal, so a `◆ ready` / `◆ done`
+// tombstone is redundant.
+const SUPPRESSED_ENTRY_STATES: ReadonlySet<string> = new Set([
+  'ready',
+  'done',
+]);
 
 // Captain-pane surface (PBRT-3): every captain-invoking state plus
-// the quiescent states. Wider than the prior
-// "Boss-relevant" set per slc/link.md's default "emit on every
-// transition; let the host filter."
+// the quiescent states whose entry still carries information
+// (failure with `lastError`, awaitBossReply with the pending
+// question). `ready` and `done` flow through the inspect handler
+// but their entries are dropped before emitStatus per
+// SUPPRESSED_ENTRY_STATES above.
 const CAPTAIN_PANE_STATES: ReadonlySet<string> = new Set([
   ...stateMetadata.keys(),
   ...QUIESCENT_STATES,
@@ -633,12 +654,13 @@ function formatAwaitBossReplyEntry(context: Record<string, unknown>): string {
 function formatStateEntry(
   stateId: string,
   context: Record<string, unknown> = {},
-): string {
+): string | undefined {
   if (stateId === 'awaitBossReply') return formatAwaitBossReplyEntry(context);
-  if (BASIC_IDLE_GLYPH_STATES.has(stateId)) return `◆ ${stateId}`;
+  if (SUPPRESSED_ENTRY_STATES.has(stateId)) return undefined;
+  if (stateId === 'failed') return '◆ failed';
   const meta = stateMetadata.get(stateId);
-  if (!meta) return `⮕ ${stateId}`;
-  return `⮕ ${meta.label}  ${meta.player} per ${meta.sourceItem}`;
+  if (!meta) return `⤷ ${stateId}`;
+  return `⤷ ${meta.player}: ${meta.label}`;
 }
 
 function formatTransition(event: unknown): string | undefined {
@@ -652,32 +674,16 @@ function formatTransition(event: unknown): string | undefined {
       tallies.push(`${field}=${items ? items.length : 1}`);
     }
   }
-  const suffix = tallies.length > 0 ? `  ${tallies.join(' ')}` : '';
-  return `⤷ ${output.guard}${suffix}`;
-}
-
-function formatBossEcho(text: string, eventType?: string): string {
-  return eventType !== undefined
-    ? `▸ BOSS  ${text}  → ${eventType}`
-    : `▸ BOSS  ${text}`;
+  const suffix = tallies.length > 0 ? ` · ${tallies.join(' · ')}` : '';
+  // No leading whitespace: visual nesting under the preceding ⤷
+  // entry is the host presenter's concern (cligent's writeStatusLine
+  // emits status messages verbatim, with its own chrome but no
+  // continuation indent; layout is its job, not ours).
+  return `→ ${output.guard}${suffix}`;
 }
 
-// Rider fields PBRT-14 names — surfaced inline on a state entry
-// whenever the FSM context populates them, regardless of which
-// captain-invoking state is being entered. Routing-only context
-// (reviewSubject, afterReview, etc.) stays out of the pane and is
-// visible via emitTelemetry instead.
-const RIDER_FIELDS = ['intent', 'irNumber', 'taskDescription'] as const;
-
-function formatRiders(context: Record<string, unknown>): string {
-  const parts: string[] = [];
-  for (const f of RIDER_FIELDS) {
-    const v = context[f];
-    if (typeof v === 'string' && v.length > 0) {
-      parts.push(`${f}=${JSON.stringify(v)}`);
-    }
-  }
-  return parts.length > 0 ? `  ${parts.join(' ')}` : '';
+function formatClassification(eventType: string): string {
+  return eventType;
 }
 
 function stateTelemetryPayload(
@@ -712,8 +718,7 @@ export const _internal = {
   formatAwaitBossReplyEntry,
   formatStateEntry,
   formatTransition,
-  formatBossEcho,
-  formatRiders,
+  formatClassification,
   stateTelemetryPayload,
 };
 
@@ -805,16 +810,13 @@ export default function createPlaybookRuntime(
             enqueueEmit(() => ports.emitStatus(transitionLine));
           }
           const entryLine = formatStateEntry(to, context);
-          const riderSuffix = stateMetadata.has(to)
-            ? formatRiders(context)
-            : '';
-          const message = entryLine + riderSuffix;
+          if (entryLine === undefined) return;
           if (to === 'failed') {
             const lastError = (snap.context as { lastError?: unknown })
               ?.lastError;
-            enqueueEmit(() => ports.emitStatus(message, { lastError }));
+            enqueueEmit(() => ports.emitStatus(entryLine, { lastError }));
           } else {
-            enqueueEmit(() => ports.emitStatus(message));
+            enqueueEmit(() => ports.emitStatus(entryLine));
           }
         },
       },
@@ -856,13 +858,14 @@ export default function createPlaybookRuntime(
           await drainEmissions();
           return;
         }
-        // 2. Captain-pane Boss-input echo (PBRT-14): the verbatim
-        //    Boss text and the FSM event it classified to, before
-        //    the FSM advances. Enqueued so it interleaves cleanly
-        //    with the inspect-driven transition emissions.
+        // 2. Captain-pane classification line (PBRT-14): the bare
+        //    FSM event type, emitted before the FSM advances so the
+        //    host can render it as captain speech (e.g.,
+        //    `captain> START_CODING`). Enqueued so it interleaves
+        //    cleanly with the inspect-driven transition emissions.
         const echoPorts = savedPorts;
         enqueueEmit(() =>
-          echoPorts.emitStatus(formatBossEcho(text, event.type)),
+          echoPorts.emitStatus(formatClassification(event.type)),
         );
         // 3. final state ('done') cannot accept new events — dispose
         //    and reconstruct per DR-004 §5.

package/reference/sdlc/code.playbook/code.tmux-play.js

@@ -2,31 +2,48 @@
 // 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).
+// `options` is whatever `captain.options` carries in the YAML config.
+// The per-run player identity strings (`coderPlayer`, `reviewerPlayer`)
+// are derived from `session.players` at init time per PBRT-4 —
+// preferring each entry's `model` and falling back to `adapter` when
+// no model is pinned — so player prompts and commit-message trailers
+// carry the concrete model identity (e.g. `claude-opus-4-7`) rather
+// than the adapter family name (e.g. `claude`). Any same-named keys
+// in `options` are ignored.
 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.
+    // primitives. The runtime is constructed in `init` so identity
+    // strings derived from `session.players` can flow into its options;
+    // PlaybookPorts is built once at init, so the per-turn context
+    // lives in a closure-scoped slot the port callbacks query lazily.
+    let runtime;
     let activeContext;
     return {
         async init(session) {
+            const playerIdentity = (id) => {
+                const entry = session.players.find((p) => p.id === id);
+                return entry?.model ?? entry?.adapter;
+            };
+            const coderPlayer = playerIdentity('coder');
+            const reviewerPlayer = playerIdentity('reviewer');
+            runtime = createPlaybookRuntime({
+                ...options,
+                coderPlayer,
+                reviewerPlayer,
+            });
             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
+                    // PlayerRunResult 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);
+                    const r = await activeContext.callPlayer(playerId, prompt);
                     return {
                         status: r.status,
                         finalText: r.finalText,
@@ -56,6 +73,9 @@ export default function createCodeTmuxPlayCaptain(options) {
             await runtime.init(ports);
         },
         async handleBossTurn(turn, context) {
+            if (!runtime) {
+                throw new Error('init must be called first');
+            }
             activeContext = context;
             try {
                 // Forward the Boss prompt + cligent's per-turn signal into
@@ -71,7 +91,7 @@ export default function createCodeTmuxPlayCaptain(options) {
             }
         },
         async dispose() {
-            await runtime.dispose();
+            await runtime?.dispose();
         },
     };
 }

package/reference/sdlc/code.playbook/code.tmux-play.ts

@@ -18,37 +18,51 @@ 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).
+// `options` is whatever `captain.options` carries in the YAML config.
+// The per-run player identity strings (`coderPlayer`, `reviewerPlayer`)
+// are derived from `session.players` at init time per PBRT-4 —
+// preferring each entry's `model` and falling back to `adapter` when
+// no model is pinned — so player prompts and commit-message trailers
+// carry the concrete model identity (e.g. `claude-opus-4-7`) rather
+// than the adapter family name (e.g. `claude`). Any same-named keys
+// in `options` are ignored.
 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.
+  // primitives. The runtime is constructed in `init` so identity
+  // strings derived from `session.players` can flow into its options;
+  // PlaybookPorts is built once at init, so the per-turn context
+  // lives in a closure-scoped slot the port callbacks query lazily.
+  let runtime: PlaybookRuntime | undefined;
   let activeContext: CaptainContext | undefined;
 
   return {
     async init(session: CaptainSession): Promise<void> {
+      const playerIdentity = (id: string): string | undefined => {
+        const entry = session.players.find((p) => p.id === id);
+        return entry?.model ?? entry?.adapter;
+      };
+      const coderPlayer = playerIdentity('coder');
+      const reviewerPlayer = playerIdentity('reviewer');
+      runtime = createPlaybookRuntime({
+        ...(options as CodePlaybookOptions),
+        coderPlayer,
+        reviewerPlayer,
+      });
       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
+          // PlayerRunResult 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);
+          const r = await activeContext.callPlayer(playerId, prompt);
           return {
             status: r.status,
             finalText: r.finalText,
@@ -89,6 +103,9 @@ export default function createCodeTmuxPlayCaptain(
       turn: BossTurn,
       context: CaptainContext,
     ): Promise<void> {
+      if (!runtime) {
+        throw new Error('init must be called first');
+      }
       activeContext = context;
       try {
         // Forward the Boss prompt + cligent's per-turn signal into
@@ -104,7 +121,7 @@ export default function createCodeTmuxPlayCaptain(
     },
 
     async dispose(): Promise<void> {
-      await runtime.dispose();
+      await runtime?.dispose();
     },
   };
 }

package/reference/sdlc/code.playbook/playbook-code.config.template.yaml

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+# Seed template for the user-level playbook-code config.
+# First run copies this file to:
+#   ${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml
+#
+# Safe tuning points:
+# - Change captain.adapter / captain.model / captain.reasoningEffort to
+#   pick the judge/Captain agent and its reasoning tier.
+# - Change each player's adapter, model, and reasoningEffort to pick
+#   the Coder and Reviewer agents.
+#
+# PBRT-4 host-configuration invariants:
+# - captain.from must keep pointing at the CODE tmux-play adapter module.
+# - players[].id must remain exactly "coder" and "reviewer"; the runtime routes
+#   to those baked ids and does not remap them. The adapter derives the
+#   per-run player identity strings (substituted into <coder-llm> /
+#   <reviewer-llm> in player prompts) from each entry's model when pinned
+#   and falls back to its adapter when no model is set, so the Committer's
+#   commit-message trailers can name the concrete model.
+
+captain:
+  # PBRT-4 invariant: keep this adapter module path unchanged.
+  from: "@sublang/playbook/code/tmux-play"
+  # Tunable: the Captain/Judge adapter, model, and reasoning effort.
+  adapter: claude
+  model: claude-sonnet-4-6
+  reasoningEffort: high
+  permissions:
+    mode: auto
+
+players:
+  # PBRT-4 invariant: keep id: coder. Tune adapter/model if desired.
+  - id: coder
+    adapter: claude
+    model: claude-opus-4-7
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto
+  # PBRT-4 invariant: keep id: reviewer. Tune adapter/model if desired.
+  - id: reviewer
+    adapter: codex
+    model: gpt-5.5
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto

package/reference/sdlc/code.playbook/tmux-play.config.yaml

@@ -10,32 +10,36 @@ captain:
   # @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,
+  # (final form confirmed at publish time per DR-004 §11). Players,
   # options, and the rest of the config are unchanged.
   from: ./code.tmux-play.js
   adapter: claude
-  model: claude-opus-4-7
+  model: claude-sonnet-4-6
+  reasoningEffort: high
   # Agents run in cligent's classifier/reviewer-protected auto mode
   # (cligent DR-005): claude → permissionMode auto, codex → auto_review.
   permissions:
     mode: auto
-  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
+# `players[].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:
+# not remap, so changing these ids would break callPlayer routing.
+# Each entry's `model` (when pinned) or `adapter` (otherwise) is
+# substituted into the <coder-llm> / <reviewer-llm> placeholders in
+# player prompts (DR-004 §6, PBRT-4) — pin a concrete `model:` if
+# you want the Committer's commit-message trailers to name the
+# specific model rather than the adapter family.
+players:
   - id: coder
     adapter: claude
+    model: claude-opus-4-7
+    reasoningEffort: xhigh
     permissions:
       mode: auto
   - id: reviewer
     adapter: codex
+    model: gpt-5.5
+    reasoningEffort: xhigh
     permissions:
       mode: auto

package/reference/sdlc/code.playbook/tmux-play.production.config.yaml

@@ -9,19 +9,21 @@
 captain:
   from: "@sublang/playbook/code/tmux-play"
   adapter: claude
-  model: claude-opus-4-7
+  model: claude-sonnet-4-6
+  reasoningEffort: high
   permissions:
     mode: auto
-  options:
-    coderPlayer: claude
-    reviewerPlayer: codex
 
-roles:
+players:
   - id: coder
     adapter: claude
+    model: claude-opus-4-7
+    reasoningEffort: xhigh
     permissions:
       mode: auto
   - id: reviewer
     adapter: codex
+    model: gpt-5.5
+    reasoningEffort: xhigh
     permissions:
       mode: auto