@sublang/playbook 7.0.0 → 8.0.0

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

@@ -2,14 +2,15 @@
 # SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 # Shared `playbook` and `playbook run` launcher config.
-# Top-level host fields only — no `config:` wrapper, no top-level `players`.
-# The launcher injects captain.from and the namespaced <id>-<role> host
-# players, then hosts the same Playbook Captain shell interactively or headlessly.
+# Top-level host fields only — no `config:` wrapper. The launcher injects
+# captain.from, retains only players named by a role binding, and hosts the
+# same Playbook Captain shell interactively or headlessly.
 
-# Every agent — the Captain and each playbook role — carries its own
-# settings inline: an adapter shorthand (claude, codex) or a block with
-# adapter/model/effort/permissions. Retuning one agent never changes
-# another.
+# The Captain and each stable session player carries its own defaults inline:
+# an adapter shorthand (claude, codex) or a block with
+# adapter/model/effort/permissions. A role may override only model or effort.
+# Omit an override to inherit the player default; set it to false to select
+# that provider's current default explicitly.
 
 # Each adapter needs its vendor SDK installed as its own top-level
 # install root — they are optional peer dependencies, so you pay only
@@ -23,9 +24,9 @@
 # so they can inspect and work with repository metadata under the sandbox.
 
 # The Captain/Judge agent.
-# Captain routing/adjudication calls run tool-free. Claude enforces that at
-# the provider level; the codex adapter cannot enforce a tool list, so a
-# codex captain degrades to a prompt-level restriction (DR-013 A1).
+# Captain routing/adjudication calls run tool-free. Claude and Gemini enforce
+# that at the provider level; codex, kimi, and opencode cannot enforce a tool
+# list, so those captains degrade to a prompt-level restriction (DR-013 A1).
 captain:
   adapter: claude
   model: claude-opus-4-8
@@ -39,55 +40,46 @@ notifications:
   player_finished: bell
   turn_finished: desktop
 
+# Stable player ids are flat exact strings. Dots are a naming convention, not
+# YAML hierarchy. Naming the same id in several role bindings deliberately
+# shares one provider conversation across those playbooks.
+players:
+  dev.coder:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    effort: xhigh
+    permissions:
+      mode: auto
+
+  dev.reviewer:
+    adapter: codex
+    model: gpt-5.5
+    effort: xhigh
+    permissions:
+      mode: auto
+      writablePaths: ['.git']
+
 # Enabled playbooks. Each is loaded from its explicit `from` module; the
 # `<id>` key must equal that module's manifest id. `from`, `command`, and
-# `players` are launcher-owned; every other key is that playbook's option
+# `roles` are launcher-owned; every other key is that playbook's option
 # slice.
 #
-# Nested calls map roles by exact id. CODE and DECIDE call REVIEW with the
-# same `coder` and `reviewer` ids, so those child roles continue the nearest
-# ancestor sessions. A standalone REVIEW uses its own bindings below.
+# Every manifest role is bound explicitly. These three playbooks intentionally
+# reuse the same two stable players; change an id to isolate its conversation.
 playbooks:
   code:
     from: "@sublang/playbook/code/registry"
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
+    roles:
+      coder: dev.coder
 
   review:
     from: "@sublang/playbook/review/registry"
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths: ['.git']
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer
 
   decide:
     from: "@sublang/playbook/decide/registry"
-    players:
-      coder:
-        adapter: claude
-        model: claude-opus-4-8[1m]
-        effort: xhigh
-        permissions:
-          mode: auto
-      reviewer:
-        adapter: codex
-        model: gpt-5.5
-        effort: xhigh
-        permissions:
-          mode: auto
-          writablePaths: ['.git']
+    roles:
+      coder: dev.coder
+      reviewer: dev.reviewer

package/reference/sdlc/decide.md

@@ -4,7 +4,7 @@
 
 # Decide
 
-Players:
+Roles:
 
 - Coder
 - Reviewer
@@ -13,7 +13,7 @@ The caller supplies the topic including any specific context.
 
 When the caller gives a topic, Captain shall relay the complete topic in quotes (`>`) to Coder and Reviewer concurrently and independently.
 Captain shall not wait for either proposal before requesting the other.
-Captain shall give each player the following instruction:
+Captain shall give the player bound to each role the following instruction:
 
 ```markdown
 Assess whether the topic is better expressed as a few spec items under @specs/packages/ or requires one or more DRs under @specs/decisions/.
@@ -23,7 +23,7 @@ Consult @specs/map.md for relevant context and @specs/meta.md for spec requireme
 Do not change any files.
 ```
 
-Neither player shall receive the other's proposal until both proposals are complete and Coder has committed Coder's own proposal.
+Neither role's player shall receive the other role's proposal until both proposals are complete and Coder has committed Coder's own proposal.
 A Boss interrupt during the parallel proposal pair shall restart the whole pair so both players receive the same new topic and remain independent.
 
 When both proposals are complete, Captain shall then give Coder the following instruction:
@@ -36,7 +36,7 @@ Do not change code or implement the proposal.
 
 Commit the result as one new commit, following @specs/packages/git.md.
 Make the commit message explain concisely what changed and why.
-Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
+Include exactly one final-response line beginning `Commit: `, followed only by the exact commit identity; other final-response content may appear on other lines.
 Coder is <coder-llm>; format the model token in conventional human form.
 ```
 

package/reference/sdlc/decide.playbook/decide.fsm.d.ts

@@ -1,14 +1,18 @@
 export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
     readonly [key: string]: JsonValue;
 };
-type Player = 'Coder' | 'Reviewer';
+type Role = 'coder' | 'reviewer';
+export declare const concurrentRoleSets: readonly [readonly ["coder", "reviewer"]];
 type JumpableStateId = 'independentProposals';
 type ResumableStateId = 'askCoderProposal' | 'askReviewerProposal' | 'commitCoderProposal';
 export interface PendingBossQuestion {
     questionId: ResumableStateId;
     resumeStateId: ResumableStateId;
     sourceItem: string;
-    player: Player;
+    asker: {
+        kind: 'role';
+        roleId: Role;
+    };
     question: string;
 }
 type PendingBossQuestions = Partial<Record<ResumableStateId, PendingBossQuestion>>;
@@ -37,7 +41,6 @@ interface ChildFailure {
     };
 }
 export interface DecideContext {
-    coderLlm: string;
     callerTopic?: string;
     coderProposal?: string;
     reviewerProposal?: string;
@@ -63,17 +66,14 @@ export type DecideEvent = {
     questionId?: ResumableStateId;
     answer: string;
 };
-export interface DecideInput {
-    coderLlm: string;
-}
+export type DecideInput = Readonly<Record<string, never>>;
 export interface PlayerInput {
     stateId: ResumableStateId;
     sourceItem: string;
     prompt: string;
     result: Record<string, string>;
-    player: Player;
+    role: Role;
     callerTopic?: string;
-    coderLlm?: string;
     pendingBossQuestion?: PendingBossQuestion;
     bossReply?: string;
 }
@@ -205,7 +205,7 @@ export declare const decideMachine: import("xstate").StateMachine<DecideContext,
         coder: "complete" | "working" | "waiting";
         reviewer: "complete" | "working" | "waiting";
     };
-}, string, DecideInput, ReviewSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+}, string, Readonly<Record<string, never>>, ReviewSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
     id: "decide";
     states: {
         readonly ready: {

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

@@ -4,6 +4,7 @@
 // This module defines only the machine, actor contracts, and typed inputs.
 // The linked runtime supplies the player and nested-playbook actors.
 import { assign, fromPromise, setup } from 'xstate';
+export const concurrentRoleSets = [['coder', 'reviewer']];
 const NEEDS_BOSS_REPLY_DESCRIPTION = "The acting agent's prose surfaces a clarifying question for Boss that the agent cannot answer alone. Output shall include `question: <verbatim question text from the acting agent's prose>`.";
 const INDEPENDENT_PROPOSAL_PROMPT = [
     '> <caller-topic>',
@@ -22,7 +23,7 @@ const COMMIT_CODER_PROMPT = [
     '',
     'Commit the result as one new commit, following @specs/packages/git.md.',
     'Make the commit message explain concisely what changed and why.',
-    'Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.',
+    'Include exactly one final-response line beginning `Commit: `, followed only by the exact commit identity; other final-response content may appear on other lines.',
     'Coder is <coder-llm>; format the model token in conventional human form.',
 ].join('\n');
 const REVIEW_INPUT_TEMPLATE = [
@@ -275,9 +276,18 @@ function resumableStates(ids) {
     }));
 }
 const stateMetadata = {
-    askCoderProposal: { sourceItem: 'DECIDE-1', player: 'Coder' },
-    askReviewerProposal: { sourceItem: 'DECIDE-2', player: 'Reviewer' },
-    commitCoderProposal: { sourceItem: 'DECIDE-3', player: 'Coder' },
+    askCoderProposal: {
+        sourceItem: 'DECIDE-1',
+        asker: { kind: 'role', roleId: 'coder' },
+    },
+    askReviewerProposal: {
+        sourceItem: 'DECIDE-2',
+        asker: { kind: 'role', roleId: 'reviewer' },
+    },
+    commitCoderProposal: {
+        sourceItem: 'DECIDE-3',
+        asker: { kind: 'role', roleId: 'coder' },
+    },
 };
 export const decideMachine = setup({
     types: {
@@ -424,9 +434,7 @@ export const decideMachine = setup({
 }).createMachine({
     id: 'decide',
     initial: 'ready',
-    context: ({ input }) => ({
-        coderLlm: input.coderLlm,
-    }),
+    context: () => ({}),
     output: ({ context }) => {
         if (context.reviewResult)
             return context.reviewResult;
@@ -486,7 +494,7 @@ export const decideMachine = setup({
                                 playbook: {
                                     stateId: 'askCoderProposal',
                                     description: 'Coder independently proposes a spec design.',
-                                    player: 'Coder',
+                                    role: 'coder',
                                 },
                             },
                             invoke: {
@@ -494,7 +502,7 @@ export const decideMachine = setup({
                                 input: ({ context }) => ({
                                     stateId: 'askCoderProposal',
                                     sourceItem: 'DECIDE-1',
-                                    player: 'Coder',
+                                    role: 'coder',
                                     prompt: INDEPENDENT_PROPOSAL_PROMPT,
                                     result: withNeedsBossReply({
                                         proposed: 'Coder completed an independent proposal. Output shall include `coderProposal: <verbatim final text>`.',
@@ -602,7 +610,7 @@ export const decideMachine = setup({
                                 playbook: {
                                     stateId: 'askReviewerProposal',
                                     description: 'Reviewer independently proposes a spec design.',
-                                    player: 'Reviewer',
+                                    role: 'reviewer',
                                 },
                             },
                             invoke: {
@@ -610,7 +618,7 @@ export const decideMachine = setup({
                                 input: ({ context }) => ({
                                     stateId: 'askReviewerProposal',
                                     sourceItem: 'DECIDE-2',
-                                    player: 'Reviewer',
+                                    role: 'reviewer',
                                     prompt: INDEPENDENT_PROPOSAL_PROMPT,
                                     result: withNeedsBossReply({
                                         proposed: 'Reviewer completed an independent proposal. Output shall include `reviewerProposal: <verbatim final text>`.',
@@ -721,7 +729,7 @@ export const decideMachine = setup({
                 playbook: {
                     stateId: 'commitCoderProposal',
                     description: 'Coder writes and commits Coder’s independent proposal.',
-                    player: 'Coder',
+                    role: 'coder',
                 },
             },
             invoke: {
@@ -729,12 +737,11 @@ export const decideMachine = setup({
                 input: ({ context }) => ({
                     stateId: 'commitCoderProposal',
                     sourceItem: 'DECIDE-3',
-                    player: 'Coder',
+                    role: 'coder',
                     prompt: COMMIT_CODER_PROMPT,
                     result: withNeedsBossReply({
                         committed: "Coder committed Coder's proposal. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
                     }),
-                    coderLlm: context.coderLlm,
                     ...bossReplyFields(context, 'commitCoderProposal'),
                 }),
                 onDone: [

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

@@ -15,7 +15,9 @@ export type JsonValue =
   | readonly JsonValue[]
   | { readonly [key: string]: JsonValue };
 
-type Player = 'Coder' | 'Reviewer';
+type Role = 'coder' | 'reviewer';
+
+export const concurrentRoleSets = [['coder', 'reviewer']] as const;
 
 type JumpableStateId = 'independentProposals';
 
@@ -28,7 +30,7 @@ export interface PendingBossQuestion {
   questionId: ResumableStateId;
   resumeStateId: ResumableStateId;
   sourceItem: string;
-  player: Player;
+  asker: { kind: 'role'; roleId: Role };
   question: string;
 }
 
@@ -67,7 +69,6 @@ interface ChildFailure {
 }
 
 export interface DecideContext {
-  coderLlm: string;
   callerTopic?: string;
   coderProposal?: string;
   reviewerProposal?: string;
@@ -95,18 +96,15 @@ export type DecideEvent =
       answer: string;
     };
 
-export interface DecideInput {
-  coderLlm: string;
-}
+export type DecideInput = Readonly<Record<string, never>>;
 
 export interface PlayerInput {
   stateId: ResumableStateId;
   sourceItem: string;
   prompt: string;
   result: Record<string, string>;
-  player: Player;
+  role: Role;
   callerTopic?: string;
-  coderLlm?: string;
   pendingBossQuestion?: PendingBossQuestion;
   bossReply?: string;
 }
@@ -159,7 +157,7 @@ const COMMIT_CODER_PROMPT = [
   '',
   'Commit the result as one new commit, following @specs/packages/git.md.',
   'Make the commit message explain concisely what changed and why.',
-  'Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.',
+  'Include exactly one final-response line beginning `Commit: `, followed only by the exact commit identity; other final-response content may appear on other lines.',
   'Coder is <coder-llm>; format the model token in conventional human form.',
 ].join('\n');
 
@@ -503,11 +501,20 @@ function resumableStates(ids: readonly ResumableStateId[]): any[] {
 
 const stateMetadata: Record<
   ResumableStateId,
-  { sourceItem: string; player: Player }
+  { sourceItem: string; asker: { kind: 'role'; roleId: Role } }
 > = {
-  askCoderProposal: { sourceItem: 'DECIDE-1', player: 'Coder' },
-  askReviewerProposal: { sourceItem: 'DECIDE-2', player: 'Reviewer' },
-  commitCoderProposal: { sourceItem: 'DECIDE-3', player: 'Coder' },
+  askCoderProposal: {
+    sourceItem: 'DECIDE-1',
+    asker: { kind: 'role', roleId: 'coder' },
+  },
+  askReviewerProposal: {
+    sourceItem: 'DECIDE-2',
+    asker: { kind: 'role', roleId: 'reviewer' },
+  },
+  commitCoderProposal: {
+    sourceItem: 'DECIDE-3',
+    asker: { kind: 'role', roleId: 'coder' },
+  },
 };
 
 export const decideMachine = setup({
@@ -671,9 +678,7 @@ export const decideMachine = setup({
 }).createMachine({
   id: 'decide',
   initial: 'ready',
-  context: ({ input }): DecideContext => ({
-    coderLlm: input.coderLlm,
-  }),
+  context: (): DecideContext => ({}),
   output: ({ context }): DecideOutput => {
     if (context.reviewResult) return context.reviewResult;
     if (!context.latestCommit || !context.reviewFailure) {
@@ -732,7 +737,7 @@ export const decideMachine = setup({
                 playbook: {
                   stateId: 'askCoderProposal',
                   description: 'Coder independently proposes a spec design.',
-                  player: 'Coder',
+                  role: 'coder',
                 },
               },
               invoke: {
@@ -740,7 +745,7 @@ export const decideMachine = setup({
                 input: ({ context }): PlayerInput => ({
                   stateId: 'askCoderProposal',
                   sourceItem: 'DECIDE-1',
-                  player: 'Coder',
+                  role: 'coder',
                   prompt: INDEPENDENT_PROPOSAL_PROMPT,
                   result: withNeedsBossReply({
                     proposed:
@@ -851,7 +856,7 @@ export const decideMachine = setup({
                   stateId: 'askReviewerProposal',
                   description:
                     'Reviewer independently proposes a spec design.',
-                  player: 'Reviewer',
+                  role: 'reviewer',
                 },
               },
               invoke: {
@@ -859,7 +864,7 @@ export const decideMachine = setup({
                 input: ({ context }): PlayerInput => ({
                   stateId: 'askReviewerProposal',
                   sourceItem: 'DECIDE-2',
-                  player: 'Reviewer',
+                  role: 'reviewer',
                   prompt: INDEPENDENT_PROPOSAL_PROMPT,
                   result: withNeedsBossReply({
                     proposed:
@@ -974,7 +979,7 @@ export const decideMachine = setup({
         playbook: {
           stateId: 'commitCoderProposal',
           description: 'Coder writes and commits Coder’s independent proposal.',
-          player: 'Coder',
+          role: 'coder',
         },
       },
       invoke: {
@@ -982,13 +987,12 @@ export const decideMachine = setup({
         input: ({ context }): PlayerInput => ({
           stateId: 'commitCoderProposal',
           sourceItem: 'DECIDE-3',
-          player: 'Coder',
+          role: 'coder',
           prompt: COMMIT_CODER_PROMPT,
           result: withNeedsBossReply({
             committed:
               "Coder committed Coder's proposal. Output shall include `coderOutput: <verbatim final text>` and `latestCommit: <commit identity>`.",
           }),
-          coderLlm: context.coderLlm,
           ...bossReplyFields(context, 'commitCoderProposal'),
         }),
         onDone: [

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

@@ -3,10 +3,8 @@
 
 # Decide
 
-## Players
+## Roles
 
-- Boss: the human user (default)
-- Captain: the coordinating agent (default)
 - Coder
 - Reviewer
 
@@ -14,7 +12,7 @@
 
 The caller supplies a topic as `callerTopic`.
 Coder and Reviewer receive the complete topic concurrently and independently.
-Neither player receives the other player's proposal before both proposals finish and Coder commits Coder's own proposal.
+Neither role's player receives the other role's proposal before both proposals finish and Coder commits Coder's own proposal.
 A Boss interrupt during the parallel proposal pair restarts the complete pair with the new `callerTopic`.
 
 ### DECIDE-1
@@ -64,7 +62,7 @@ When both independent proposals are complete, Captain shall prompt Coder:
 >
 > Commit the result as one new commit, following @specs/packages/git.md.
 > Make the commit message explain concisely what changed and why.
-> Report it as exactly one final-response line beginning `Commit: `, followed only by the exact commit identity.
+> Include exactly one final-response line beginning `Commit: `, followed only by the exact commit identity; other final-response content may appear on other lines.
 > Coder is <coder-llm>; format the model token in conventional human form.
 
 Results:

package/reference/sdlc/decide.playbook/decide.playbook.d.ts

@@ -1,12 +1,10 @@
 import { type PlayerInput, type PlayerOutput, type DecideEvent, type DecideInput, type PendingBossQuestion } from './decide.fsm.js';
 import type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlayerSessionStore, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlAction, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType } from '@sublang/playbook/runtime';
 export type { CaptainCallOptions, CaptainResult, JsonValue, NormalizedError, PlayerCallOptions, PlayerResult, PlayerSessionStore, PlaybookCallRequest, PlaybookCallResult, PlaybookCallStart, PlaybookControlAction, PlaybookControlReceipt, PlaybookControlView, PlaybookPendingCall, PlaybookPorts, PlaybookRunResult, PlaybookRuntime, PlaybookRuntimeFactory, PlaybookRuntimeSnapshot, PlaybookSession, PlaybookState, PlaybookStateValue, PlaybookTraceEvent, PlaybookTraceType, };
-type PlayerName = 'Coder' | 'Reviewer';
-export interface PlaybookRuntimeOptions extends DecideInput {
-    playerBinding?: Partial<Record<PlayerName, string>>;
-}
-declare function composePlayerPrompt(input: PlayerInput): string;
-declare function resolvePlayerId(input: PlayerInput, binding: Record<PlayerName, string>): string;
+type RoleId = 'coder' | 'reviewer';
+export type PlaybookRuntimeOptions = DecideInput;
+type PromptIdentity = (roleId: RoleId) => string;
+declare function composePlayerPrompt(input: PlayerInput, promptIdentity: PromptIdentity): string;
 declare function requiredFieldsFor(description: string): string[];
 declare function extractJson(raw: string): Record<string, unknown> | null;
 declare function buildClassifierPrompt(text: string, ctx: {
@@ -32,7 +30,6 @@ declare function pendingQuestionsFromContext(context: Record<string, unknown>):
 export declare const createPlaybookRuntime: PlaybookRuntimeFactory<PlaybookRuntimeOptions>;
 export declare const _internal: {
     composePlayerPrompt: typeof composePlayerPrompt;
-    resolvePlayerId: typeof resolvePlayerId;
     requiredFieldsFor: typeof requiredFieldsFor;
     extractJson: typeof extractJson;
     buildClassifierPrompt: typeof buildClassifierPrompt;
@@ -43,22 +40,21 @@ export declare const _internal: {
     pendingQuestionsFromContext: typeof pendingQuestionsFromContext;
     normalizeErrorCompact: typeof normalizeErrorCompact;
     normalizeErrorFull: typeof normalizeErrorFull;
-    DEFAULT_PLAYER_BINDING: Readonly<Record<PlayerName, string>>;
     STATE_DESCRIPTIONS: Readonly<Record<string, string>>;
-    PLAYER_STATES: readonly [{
+    ROLE_STATES: readonly [{
         readonly stateId: "askCoderProposal";
-        readonly player: "Coder";
+        readonly role: "coder";
         readonly sourceItem: "DECIDE-1";
     }, {
         readonly stateId: "askReviewerProposal";
-        readonly player: "Reviewer";
+        readonly role: "reviewer";
         readonly sourceItem: "DECIDE-2";
     }, {
         readonly stateId: "commitCoderProposal";
-        readonly player: "Coder";
+        readonly role: "coder";
         readonly sourceItem: "DECIDE-3";
     }];
-    PLAYER_STATE_IDS: ReadonlySet<string>;
+    ROLE_STATE_IDS: ReadonlySet<string>;
     VERBATIM_PAYLOAD_FIELDS: ReadonlySet<string>;
     BOSS_INTERRUPT_TARGETS: readonly ["independentProposals"];
     CONTINUATION_PREAMBLE: string;