@sublang/playbook 5.0.0 → 7.0.0

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

@@ -1,10 +1,10 @@
 # SPDX-License-Identifier: Apache-2.0
 # SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-# Generic `playbook` launcher config.
+# 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 launches cligent's tmux-play under the Playbook Captain shell.
+# players, then 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
@@ -20,7 +20,7 @@
 # Every seeded agent runs in cligent's protected auto mode
 # (permissions.mode: auto): claude maps it to permissionMode auto, codex to
 # on-request + auto_review. Codex roles also grant writablePaths: ['.git']
-# so commit turns can write git metadata under the codex sandbox.
+# 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
@@ -33,18 +33,33 @@ captain:
   permissions:
     mode: auto
 
-# Host notifications. Omitting turn_aborted resolves it to off.
+# Interactive host notifications. Headless runs ignore presentation fields.
+# Omitting turn_aborted resolves it to off.
 notifications:
   player_finished: bell
   turn_finished: desktop
 
 # 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 (e.g. CODE's `committer`)
-# is that playbook's option slice.
+# `players` 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.
 playbooks:
   code:
     from: "@sublang/playbook/code/registry"
+    players:
+      coder:
+        adapter: claude
+        model: claude-opus-4-8[1m]
+        effort: xhigh
+        permissions:
+          mode: auto
+
+  review:
+    from: "@sublang/playbook/review/registry"
     players:
       coder:
         adapter: claude
@@ -59,34 +74,20 @@ playbooks:
         permissions:
           mode: auto
           writablePaths: ['.git']
-    committer: coder
-
-# The DISCUSS playbook: two agents converge on spec items or decision
-# records. `committer` picks which player runs Committer commits
-# (default: host).
-#  discuss:
-#    from: "@sublang/playbook/discuss/registry"
-#    players:
-#      host:
-#        adapter: claude
-#        model: claude-opus-4-8
-#        permissions:
-#          mode: auto
-#      participant:
-#        adapter: codex
-#        model: gpt-5.5
-#        permissions:
-#          mode: auto
-#          writablePaths: ['.git']
-#    committer: host
 
-# Non-interactive `playbook run` defaults (optional). Each value is an
-# agent string <adapter>[:<model>][@<effort>]; `player` is the catch-all
-# for any required role without its own `players.<role>` entry, across
-# every playbook. Flags override per role (--player / --captain), and
-# `playbook run resume` keeps the lineup stored with the parked session.
-#run:
-#  captain: claude:claude-opus-4-8@high
-#  player: claude:claude-opus-4-8@high
-#  players:
-#    coder: claude:claude-opus-4-8[1m]@xhigh
+  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']

package/reference/sdlc/decide.md

@@ -0,0 +1,54 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# Decide
+
+Players:
+
+- Coder
+- Reviewer
+
+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:
+
+```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/.
+Propose your design.
+Keep your proposal coherent, focused, and concise.
+Consult @specs/map.md for relevant context and @specs/meta.md for spec requirements, if needed.
+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.
+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:
+
+```markdown
+Turn your proposal into the necessary spec items or DRs.
+Follow @specs/meta.md and update @specs/map.md when needed.
+Do not inspect or incorporate Reviewer's proposal before this commit.
+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.
+Coder is <coder-llm>; format the model token in conventional human form.
+```
+
+After Coder commits, Captain shall call playbook `review`:
+
+> Review the latest commit as a spec-design change against the initial intent.
+> Compare it with your independent proposal and take the best of both.
+> Make your suggestions.
+>
+> Initial intent: \<caller-topic\>.
+> Coder's independent proposal: \<coder-proposal\>.
+
+`decide` is complete when `review` returns the approved latest commit and the fact that no unsettled findings remain.
+When `review` returns an authored abort or failure, or a terminal result that does not prove exact approval, `decide` shall report the failure and the last `decide`-owned commit to its caller.
+When the nested `review` call fails outside that authored result contract, `decide` shall park as failed and retain the control-plane error instead of reporting an authored review outcome.

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

@@ -0,0 +1,261 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+type Player = 'Coder' | 'Reviewer';
+type JumpableStateId = 'independentProposals';
+type ResumableStateId = 'askCoderProposal' | 'askReviewerProposal' | 'commitCoderProposal';
+export interface PendingBossQuestion {
+    questionId: ResumableStateId;
+    resumeStateId: ResumableStateId;
+    sourceItem: string;
+    player: Player;
+    question: string;
+}
+type PendingBossQuestions = Partial<Record<ResumableStateId, PendingBossQuestion>>;
+type BossReplies = Partial<Record<ResumableStateId, string>>;
+type PendingBossQuestionParams = Omit<PendingBossQuestion, 'questionId'>;
+export interface ReviewSuccessOutput {
+    approvedCommit: 'latest';
+    noUnsettledFindings: true;
+}
+export interface DecideFailureOutput {
+    lastDecideCommit: string;
+    noUnsettledFindings: false;
+    reviewStatus: 'aborted' | 'error';
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export type DecideOutput = ReviewSuccessOutput | DecideFailureOutput;
+interface ChildFailure {
+    status: 'aborted' | 'error';
+    playbookId: 'review';
+    error?: {
+        name: string;
+        message: string;
+    };
+}
+export interface DecideContext {
+    coderLlm: string;
+    callerTopic?: string;
+    coderProposal?: string;
+    reviewerProposal?: string;
+    latestCommit?: string;
+    reviewResult?: ReviewSuccessOutput;
+    reviewFailure?: ChildFailure;
+    lastResult?: PlayerOutput;
+    lastError?: unknown;
+    pendingBossQuestions?: PendingBossQuestions;
+    bossReplies?: BossReplies;
+    stagedCoderResult?: PlayerOutput;
+    stagedReviewerResult?: PlayerOutput;
+}
+export type DecideEvent = {
+    type: 'START_DECIDE';
+    callerTopic: string;
+} | {
+    type: 'BOSS_INTERRUPT';
+    targetId: JumpableStateId;
+    bossIntent: string;
+} | {
+    type: 'BOSS_REPLY';
+    questionId?: ResumableStateId;
+    answer: string;
+};
+export interface DecideInput {
+    coderLlm: string;
+}
+export interface PlayerInput {
+    stateId: ResumableStateId;
+    sourceItem: string;
+    prompt: string;
+    result: Record<string, string>;
+    player: Player;
+    callerTopic?: string;
+    coderLlm?: string;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
+}
+type AdditionalPlayerFields = {
+    coderProposal?: string;
+    reviewerProposal?: string;
+    coderOutput?: string;
+    latestCommit?: string;
+    question?: string;
+    readonly [key: string]: unknown;
+};
+export type PlayerOutput = ({
+    guard: 'proposed';
+    coderProposal: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'proposed';
+    reviewerProposal: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'committed';
+    coderOutput: string;
+    latestCommit: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'needsBossReply';
+    question: string;
+} & AdditionalPlayerFields);
+export interface PlaybookInput {
+    stateId: 'reviewCommit';
+    sourceItem: 'DECIDE-4';
+    playbookId: 'review';
+    text: string;
+}
+export declare const decideMachine: import("xstate").StateMachine<DecideContext, {
+    type: "START_DECIDE";
+    callerTopic: string;
+} | {
+    type: "BOSS_INTERRUPT";
+    targetId: JumpableStateId;
+    bossIntent: string;
+} | {
+    type: "BOSS_REPLY";
+    questionId?: ResumableStateId;
+    answer: string;
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<JsonValue | undefined, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "player";
+    logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearBossReplyContext";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyInterruptedTopic";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyStartTopic";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "stageCoderProposal";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "stageReviewerProposal";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "promoteProposals";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCommit";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewSuccess";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewProtocolFailure";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedActorOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingBossQuestion";
+    params: PendingBossQuestionParams;
+} | {
+    type: "clearBranchBossReplyContext";
+    params: {
+        stateId: ResumableStateId;
+    };
+} | {
+    type: "clearProposalRoundContext";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "authoredReviewFailure";
+    params: unknown;
+} | {
+    type: "committed";
+    params: unknown;
+} | {
+    type: "coderProposed";
+    params: unknown;
+} | {
+    type: "reviewerProposed";
+    params: unknown;
+} | {
+    type: "needsBossReplyWithQuestion";
+    params: unknown;
+} | {
+    type: "needsBossReplyWithoutQuestion";
+    params: unknown;
+} | {
+    type: "validReviewSuccess";
+    params: unknown;
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "commitCoderProposal" | "reviewCommit" | "reportedReviewFailure" | {
+    independentProposals: {
+        coder: "complete" | "working" | "waiting";
+        reviewer: "complete" | "working" | "waiting";
+    };
+}, string, DecideInput, ReviewSuccessOutput | DecideFailureOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "decide";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly independentProposals: {
+            id: "independentProposals";
+            states: {
+                readonly coder: {
+                    states: {
+                        readonly working: {
+                            id: "askCoderProposal";
+                        };
+                        readonly waiting: {
+                            id: "waitCoderProposalReply";
+                        };
+                        readonly complete: {};
+                    };
+                };
+                readonly reviewer: {
+                    states: {
+                        readonly working: {
+                            id: "askReviewerProposal";
+                        };
+                        readonly waiting: {
+                            id: "waitReviewerProposalReply";
+                        };
+                        readonly complete: {};
+                    };
+                };
+            };
+        };
+        readonly commitCoderProposal: {
+            id: "commitCoderProposal";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly reviewCommit: {
+            id: "reviewCommit";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly reportedReviewFailure: {
+            id: "reportedReviewFailure";
+        };
+        readonly done: {
+            id: "done";
+        };
+    };
+}>;
+export default decideMachine;