@sublang/playbook 0.8.0 → 1.0.0

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

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0
+# SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+# Generic `playbook` 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.
+
+# Reusable agent settings. A profile id must not be an adapter shorthand
+# (claude, codex). Reference a profile by id from captain / players below.
+# Profile ids name the underlying agent/model (e.g. claude-opus,
+# codex-gpt) so they read distinctly from the captain / coder / reviewer
+# player roles that reference them.
+# 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.
+profiles:
+  claude-opus:
+    adapter: claude
+    model: claude-opus-4-8
+    reasoningEffort: high
+    permissions:
+      mode: auto
+  claude-opus-1m:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto
+  codex-gpt:
+    adapter: codex
+    model: gpt-5.5
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto
+      writablePaths: ['.git']
+
+# The Captain/Judge agent: a profile id, an adapter shorthand, or a full
+# tmux-play agent block (which may carry a `profile:` key).
+captain: claude-opus
+
+# Host notifications. 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.
+playbooks:
+  code:
+    from: "@sublang/playbook/code/registry"
+    players:
+      coder: claude-opus-1m
+      reviewer: codex-gpt
+    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: claude-opus
+#      participant: codex-gpt
+#    committer: host

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

@@ -0,0 +1,396 @@
+type Player = 'Host' | 'Participant' | 'Committer';
+type ReviewScope = 'specItems' | 'decisionRecords' | 'mixed';
+type JumpableStateId = 'ready' | 'initialProposalRound' | 'reconciliationRound' | 'hostWritesAgreement' | 'commitInitialChanges' | 'reviewSpecInitialCommit' | 'reviewSpecHostChanges' | 'reviewDrInitialCommit' | 'reviewDrHostChanges' | 'reviewMixedInitialCommit' | 'reviewMixedHostChanges' | 'hostAddressesFindings' | 'participantAddressesRebuttals' | 'commitReviewedChanges' | 'failed';
+type ResumableStateId = 'askHostInitial' | 'askParticipantInitial' | 'hostInitialRound' | 'participantInitialRound' | Exclude<JumpableStateId, 'ready' | 'initialProposalRound' | 'reconciliationRound' | 'failed'>;
+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 DiscussContext {
+    hostPlayer?: string;
+    participantPlayer?: string;
+    committerPlayer?: string;
+    topic?: string;
+    hostLlm?: string;
+    participantLlm?: string;
+    hostProposal?: string;
+    participantProposal?: string;
+    agreement?: string;
+    latestChanges?: string;
+    reviewScope?: ReviewScope;
+    reviewItems?: string;
+    rebuttals?: string;
+    lastResult?: PlayerOutput;
+    lastError?: unknown;
+    pendingBossQuestions?: PendingBossQuestions;
+    bossReplies?: BossReplies;
+    stagedHostResult?: PlayerOutput;
+    stagedParticipantResult?: PlayerOutput;
+}
+export type DiscussEvent = {
+    type: 'START_DISCUSSION';
+    topic: string;
+    hostLlm?: string;
+    participantLlm?: string;
+} | {
+    type: 'START_REVIEW';
+    latestChanges: string;
+    reviewScope: ReviewScope;
+    rebuttals?: string;
+} | {
+    type: 'BOSS_INTERRUPT';
+    targetId: JumpableStateId;
+} | {
+    type: 'BOSS_REPLY';
+    questionId?: ResumableStateId;
+    answer: string;
+};
+export interface DiscussInput {
+    host?: string;
+    participant?: string;
+    committer?: string;
+}
+export interface PlayerInput {
+    stateId: ResumableStateId;
+    sourceItem: string;
+    prompt: string;
+    result: Record<string, string>;
+    player: Player;
+    topic?: string;
+    hostLlm?: string;
+    participantLlm?: string;
+    hostProposal?: string;
+    participantProposal?: string;
+    agreement?: string;
+    latestChanges?: string;
+    reviewScope?: ReviewScope;
+    reviewItems?: string;
+    rebuttals?: string;
+    hostPlayer?: string;
+    participantPlayer?: string;
+    committerPlayer?: string;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
+}
+type AdditionalPlayerFields = {
+    proposal?: string;
+    agreement?: string;
+    latestChanges?: string;
+    reviewScope?: ReviewScope;
+    reviewItems?: string;
+    rebuttals?: string;
+    question?: string;
+    readonly [key: string]: unknown;
+};
+export type PlayerOutput = ({
+    guard: 'proposalMade';
+    proposal: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'endedInitialDiscussion';
+    agreement?: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'wroteChanges';
+    latestChanges: string;
+    reviewScope: ReviewScope;
+} & AdditionalPlayerFields) | ({
+    guard: 'committed';
+    latestChanges?: string;
+    reviewScope?: ReviewScope;
+} & AdditionalPlayerFields) | ({
+    guard: 'noFindings';
+} & AdditionalPlayerFields) | ({
+    guard: 'findingsRaised';
+    reviewItems: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'changesMade';
+    latestChanges?: string;
+    reviewScope?: ReviewScope;
+} & AdditionalPlayerFields) | ({
+    guard: 'rebuttalsRaised';
+    rebuttals: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'rebuttalsAddressed';
+    rebuttals?: string;
+} & AdditionalPlayerFields) | ({
+    guard: 'needsBossReply';
+    question: string;
+} & AdditionalPlayerFields);
+type DiscussActionName = 'copyStartDiscussion' | 'copyStartReview' | 'rememberHostProposal' | 'rememberParticipantProposal' | 'rememberAgreement' | 'rememberWrittenChanges' | 'rememberCommittedChanges' | 'rememberReviewFindings' | 'rememberHostReviewResponse' | 'rememberParticipantRebuttalResponse' | 'rememberCaptainResult' | 'rememberCaptainError' | 'rememberMalformedCaptainOutput' | 'rememberMalformedBossReply' | 'setPendingBossQuestion' | 'rememberBossReply' | 'clearBranchBossReplyContext' | 'clearParallelRoundContext' | 'clearBossReplyContext';
+declare function bossInterrupts(ids: readonly JumpableStateId[], actions?: DiscussActionName | DiscussActionName[]): any[];
+declare function resumableStates(ids: readonly string[]): any[];
+export declare const discussMachine: import("xstate").StateMachine<DiscussContext, {
+    type: "START_DISCUSSION";
+    topic: string;
+    hostLlm?: string;
+    participantLlm?: string;
+} | {
+    type: "START_REVIEW";
+    latestChanges: string;
+    reviewScope: ReviewScope;
+    rebuttals?: string;
+} | {
+    type: "BOSS_INTERRUPT";
+    targetId: JumpableStateId;
+} | {
+    type: "BOSS_REPLY";
+    questionId?: ResumableStateId;
+    answer: string;
+}, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "player";
+    logic: import("xstate").PromiseActorLogic<PlayerOutput, PlayerInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "copyStartDiscussion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyStartReview";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberHostProposal";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberParticipantProposal";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberAgreement";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberWrittenChanges";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCommittedChanges";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewFindings";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberHostReviewResponse";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberParticipantRebuttalResponse";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCaptainResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCaptainError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedCaptainOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingBossQuestion";
+    params: PendingBossQuestionParams;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearBranchBossReplyContext";
+    params: {
+        stateId: ResumableStateId;
+    };
+} | {
+    type: "clearParallelRoundContext";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearBossReplyContext";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "stageHostResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "stageParticipantResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "promoteInitialResults";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "promoteReconciliationResults";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "noFindings";
+    params: unknown;
+} | {
+    type: "committed";
+    params: unknown;
+} | {
+    type: "proposalMade";
+    params: unknown;
+} | {
+    type: "endedInitialDiscussion";
+    params: unknown;
+} | {
+    type: "wroteChanges";
+    params: unknown;
+} | {
+    type: "findingsRaised";
+    params: unknown;
+} | {
+    type: "changesMade";
+    params: unknown;
+} | {
+    type: "rebuttalsRaised";
+    params: unknown;
+} | {
+    type: "rebuttalsAddressed";
+    params: unknown;
+} | {
+    type: "needsBossReplyWithQuestion";
+    params: unknown;
+} | {
+    type: "needsBossReplyWithoutQuestion";
+    params: unknown;
+} | {
+    type: "emptyBossReply";
+    params: unknown;
+} | {
+    type: "bothEndedInitialDiscussion";
+    params: unknown;
+} | {
+    type: "specReview";
+    params: unknown;
+} | {
+    type: "drReview";
+    params: unknown;
+} | {
+    type: "mixedReview";
+    params: unknown;
+}, never, "done" | "failed" | "ready" | "awaitBossReply" | "hostWritesAgreement" | "commitInitialChanges" | "reviewSpecInitialCommit" | "reviewSpecHostChanges" | "reviewDrInitialCommit" | "reviewDrHostChanges" | "reviewMixedInitialCommit" | "reviewMixedHostChanges" | "hostAddressesFindings" | "participantAddressesRebuttals" | "commitReviewedChanges" | {
+    initialProposalRound: {
+        host: "working" | "waiting" | "complete";
+        participant: "working" | "waiting" | "complete";
+    };
+} | {
+    reconciliationRound: {
+        host: "working" | "waiting" | "complete";
+        participant: "working" | "waiting" | "complete";
+    };
+}, string, DiscussInput, import("xstate").NonReducibleUnknown, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "discuss";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly initialProposalRound: {
+            id: "initialProposalRound";
+            states: {
+                readonly host: {
+                    id: "initialProposalHost";
+                    states: {
+                        readonly working: {
+                            id: "askHostInitial";
+                        };
+                        readonly waiting: {
+                            id: "waitHostInitialReply";
+                        };
+                        readonly complete: {
+                            id: "hostInitialProposalComplete";
+                        };
+                    };
+                };
+                readonly participant: {
+                    id: "initialProposalParticipant";
+                    states: {
+                        readonly working: {
+                            id: "askParticipantInitial";
+                        };
+                        readonly waiting: {
+                            id: "waitParticipantInitialReply";
+                        };
+                        readonly complete: {
+                            id: "participantInitialProposalComplete";
+                        };
+                    };
+                };
+            };
+        };
+        readonly reconciliationRound: {
+            id: "reconciliationRound";
+            states: {
+                readonly host: {
+                    id: "reconciliationHost";
+                    states: {
+                        readonly working: {
+                            id: "hostInitialRound";
+                        };
+                        readonly waiting: {
+                            id: "waitHostReconciliationReply";
+                        };
+                        readonly complete: {
+                            id: "hostReconciliationComplete";
+                        };
+                    };
+                };
+                readonly participant: {
+                    id: "reconciliationParticipant";
+                    states: {
+                        readonly working: {
+                            id: "participantInitialRound";
+                        };
+                        readonly waiting: {
+                            id: "waitParticipantReconciliationReply";
+                        };
+                        readonly complete: {
+                            id: "participantReconciliationComplete";
+                        };
+                    };
+                };
+            };
+        };
+        readonly hostWritesAgreement: {
+            id: "hostWritesAgreement";
+        };
+        readonly commitInitialChanges: {
+            id: "commitInitialChanges";
+        };
+        readonly reviewSpecInitialCommit: {
+            id: "reviewSpecInitialCommit";
+        };
+        readonly reviewSpecHostChanges: {
+            id: "reviewSpecHostChanges";
+        };
+        readonly reviewDrInitialCommit: {
+            id: "reviewDrInitialCommit";
+        };
+        readonly reviewDrHostChanges: {
+            id: "reviewDrHostChanges";
+        };
+        readonly reviewMixedInitialCommit: {
+            id: "reviewMixedInitialCommit";
+        };
+        readonly reviewMixedHostChanges: {
+            id: "reviewMixedHostChanges";
+        };
+        readonly hostAddressesFindings: {
+            id: "hostAddressesFindings";
+        };
+        readonly participantAddressesRebuttals: {
+            id: "participantAddressesRebuttals";
+        };
+        readonly commitReviewedChanges: {
+            id: "commitReviewedChanges";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly done: {
+            id: "done";
+        };
+    };
+}>;
+export { bossInterrupts, resumableStates };
+export default discussMachine;