@sublang/playbook 0.4.0 → 0.4.2

package/README.md

@@ -95,12 +95,14 @@ $EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml"
 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 player's `adapter`. Keep
-`captain.from` and the `players[].id` values fixed; the runtime binds
-to those host-configuration invariants per
+`captain.adapter`, `captain.model`, each player's `adapter`, and each
+player's `model`. Keep `captain.from` and the `players[].id` values
+fixed; 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
-player entry's `adapter`.
+player entry's `model` when pinned and `adapter` otherwise — so the
+Committer's commit-message trailers can name the concrete model
+(e.g. `claude-opus-4-7`) rather than the adapter family (`claude`).
 
 For example, this swaps the Coder to Codex and the Reviewer to Claude:
 
@@ -108,17 +110,22 @@ For example, this swaps the Coder to Codex and the Reviewer to Claude:
 captain:
   from: "@sublang/playbook/code/tmux-play"
   adapter: claude
-  model: claude-opus-4-7
+  model: claude-sonnet-4-6
+  reasoningEffort: high
   permissions:
     mode: auto
 
 players:
   - id: coder      # must stay `coder` — see PBRT-4
     adapter: codex
+    model: gpt-5.5
+    reasoningEffort: xhigh
     permissions:
       mode: auto
   - id: reviewer   # must stay `reviewer` — see PBRT-4
     adapter: claude
+    model: claude-opus-4-7
+    reasoningEffort: xhigh
     permissions:
       mode: auto
 ```
@@ -145,8 +152,21 @@ pnpm build
 pnpm test
 ```
 
-`pnpm install` resolves `@sublang/cligent` (^0.6.0) from the registry;
-no local link required. To point pnpm at a local `cligent` checkout
+`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
+`latest`, so an end-user install with no lockfile (e.g., `npm
+install -g @sublang/playbook`) instead resolves whichever cligent
+release currently carries the `latest` dist-tag at install time
+(see [RELEASE-14](specs/dev/release.md#release-14)). To bump the
+contributor pin to today's `latest`, run
+`pnpm update @sublang/cligent` and commit the resulting
+`pnpm-lock.yaml` change — a plain `pnpm install` won't refresh the
+pin, since pnpm sees `specifier: latest` in the lockfile as
+already matching `package.json` and skips re-resolving the tag.
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "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",
@@ -67,7 +67,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.130.0",
-    "@sublang/cligent": "^0.6.0",
+    "@sublang/cligent": "latest",
     "xstate": "^5.19.4"
   },
   "devDependencies": {

package/reference/sdlc/code.playbook/bin/playbook-code.js

@@ -175,7 +175,9 @@ function helpText({ userConfigPath, failingAdapters = [] }) {
     '',
     'Agent swap recipe:',
     '  - change captain.adapter and captain.model for the Captain/Judge',
-    '  - change each player adapter for the Coder and Reviewer',
+    '  - change each player adapter and (optional) model for the Coder',
+    '    and Reviewer; model when pinned, else adapter, is substituted',
+    '    into <coder-llm>/<reviewer-llm> player prompts (PBRT-4)',
     '  - keep captain.from and players[].id fixed',
     '',
   ].join('\n');

package/reference/sdlc/code.playbook/code.fsm.js

@@ -1066,6 +1066,7 @@ export const codingMachine = setup({
                     prompt: [
                         'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
                         'Coder is <coder-llm>.',
+                        '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`).',
                     ].join('\n'),
                     result: {
                         committedSpecs: 'Committed changes that touch only @specs/{user,dev,test}/.',
@@ -1127,6 +1128,7 @@ export const codingMachine = setup({
                     prompt: [
                         'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
                         'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
+                        '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`).',
                     ].join('\n'),
                     result: {
                         committed: 'Relevant changes were committed.',

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

@@ -1319,6 +1319,7 @@ export const codingMachine = setup({
           prompt: [
             'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
             'Coder is <coder-llm>.',
+            '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`).',
           ].join('\n'),
           result: {
             committedSpecs: 'Committed changes that touch only @specs/{user,dev,test}/.',
@@ -1382,6 +1383,7 @@ export const codingMachine = setup({
           prompt: [
             'Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).',
             'Coder is <coder-llm>; Reviewer is <reviewer-llm>.',
+            '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`).',
           ].join('\n'),
           result: {
             committed: 'Relevant changes were committed.',

package/reference/sdlc/code.playbook/code.gears.md

@@ -239,6 +239,7 @@ When Coder makes unreviewed changes (outside of any Initial Changes) involving c
 When Coder makes any Initial Changes and Reviewer has not played since the last commit, Captain shall prompt Committer:
 > Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
 > Coder is <coder-llm>.
+> 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`).
 
 Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.
 
@@ -247,5 +248,6 @@ Result guard: `needsBossInput` — Committing requires additional Boss input or
 When Coder makes any Initial Changes and Reviewer has played since the last commit, or Reviewer raises no findings on uncommitted changes and Coder has played since the last commit, Captain shall prompt Committer:
 > Make a commit of the changes that belong in the repo, following @specs/dev/git.md (reread if necessary).
 > Coder is <coder-llm>; Reviewer is <reviewer-llm>.
+> 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`).
 
 Result guard: `needsBossInput` — Committing requires additional Boss input or rescoping rather than a specific answer to resume this same state.

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

@@ -4,8 +4,12 @@ import createPlaybookRuntime from './code.playbook.js';
 // Captain factory per TMUX-014: `(options: unknown) => Captain`.
 // `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; any
-// same-named keys in `options` are ignored.
+// 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) {
     // CaptainSession is bound at init time and persists across turns;
     // CaptainContext is rebuilt per turn and carries the call
@@ -17,8 +21,12 @@ export default function createCodeTmuxPlayCaptain(options) {
     let activeContext;
     return {
         async init(session) {
-            const coderPlayer = session.players.find((p) => p.id === 'coder')?.adapter;
-            const reviewerPlayer = session.players.find((p) => p.id === 'reviewer')?.adapter;
+            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,

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

@@ -20,8 +20,12 @@ import createPlaybookRuntime, {
 // Captain factory per TMUX-014: `(options: unknown) => Captain`.
 // `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; any
-// same-named keys in `options` are ignored.
+// 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 {
@@ -36,12 +40,12 @@ export default function createCodeTmuxPlayCaptain(
 
   return {
     async init(session: CaptainSession): Promise<void> {
-      const coderPlayer = session.players.find(
-        (p) => p.id === 'coder',
-      )?.adapter;
-      const reviewerPlayer = session.players.find(
-        (p) => p.id === 'reviewer',
-      )?.adapter;
+      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,

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

@@ -6,22 +6,27 @@
 #   ${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml
 #
 # Safe tuning points:
-# - Change captain.adapter / captain.model to pick the judge/Captain agent.
-# - Change each player's adapter to pick the Coder and Reviewer agents.
+# - 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 player prompts) from
-#   each entry's adapter.
+#   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 and model.
+  # Tunable: the Captain/Judge adapter, model, and reasoning effort.
   adapter: claude
-  model: claude-opus-4-7
+  model: claude-sonnet-4-6
+  reasoningEffort: high
   permissions:
     mode: auto
 
@@ -29,10 +34,14 @@ 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

@@ -14,7 +14,8 @@ captain:
   # 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:
@@ -24,14 +25,21 @@ captain:
 # 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 callPlayer routing.
-# Each entry's `adapter` is also substituted into the <coder-llm> /
-# <reviewer-llm> placeholders in player prompts (DR-004 §6).
+# 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,16 +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
 
 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