@sublang/playbook 0.8.0 → 1.0.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.8.0",
+  "version": "1.0.0",
   "type": "module",
-  "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and Playbook Captain shell for a coder/reviewer/committer loop driven by GEARS spec items.",
+  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, and DISCUSS workflows driven by GEARS specs.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -28,9 +28,21 @@
     "src/runtime.ts",
     "src/runtime.js",
     "src/runtime.d.ts",
+    "src/xstate-runtime.ts",
+    "src/xstate-runtime.js",
+    "src/xstate-runtime.d.ts",
     "slc/link.md",
     "slc/gears2fsm.md",
     "slc/text2gears.md",
+    "slc/optimize.md",
+    "reference/sdlc/captain.md",
+    "reference/sdlc/captain.playbook/captain.gears.md",
+    "reference/sdlc/captain.playbook/captain.fsm.ts",
+    "reference/sdlc/captain.playbook/captain.fsm.js",
+    "reference/sdlc/captain.playbook/captain.fsm.d.ts",
+    "reference/sdlc/captain.playbook/captain.playbook.ts",
+    "reference/sdlc/captain.playbook/captain.playbook.js",
+    "reference/sdlc/captain.playbook/captain.playbook.d.ts",
     "reference/sdlc/code.playbook/code.fsm.ts",
     "reference/sdlc/code.playbook/code.fsm.js",
     "reference/sdlc/code.playbook/code.fsm.d.ts",
@@ -46,50 +58,73 @@
     "reference/sdlc/code.playbook/playbook-captain.ts",
     "reference/sdlc/code.playbook/playbook-captain.js",
     "reference/sdlc/code.playbook/playbook-captain.d.ts",
-    "reference/sdlc/code.playbook/code.tmux-play.ts",
-    "reference/sdlc/code.playbook/code.tmux-play.js",
-    "reference/sdlc/code.playbook/code.tmux-play.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
-    "reference/sdlc/code.playbook/tmux-play.config.yaml",
-    "reference/sdlc/code.playbook/tmux-play.production.config.yaml",
-    "reference/sdlc/code.playbook/playbook-code.config.template.yaml",
-    "reference/sdlc/code.playbook/bin/playbook-code.js"
+    "reference/sdlc/code.playbook/playbook.config.template.yaml",
+    "reference/sdlc/code.playbook/bin/playbook.js",
+    "reference/sdlc/code.playbook/bin/run.js",
+    "reference/sdlc/discuss.playbook/discuss.gears.md",
+    "reference/sdlc/discuss.playbook/discuss.fsm.ts",
+    "reference/sdlc/discuss.playbook/discuss.fsm.js",
+    "reference/sdlc/discuss.playbook/discuss.fsm.d.ts",
+    "reference/sdlc/discuss.playbook/discuss.playbook.ts",
+    "reference/sdlc/discuss.playbook/discuss.playbook.js",
+    "reference/sdlc/discuss.playbook/discuss.playbook.d.ts",
+    "reference/sdlc/discuss.playbook/discuss.registry.ts",
+    "reference/sdlc/discuss.playbook/discuss.registry.js",
+    "reference/sdlc/discuss.playbook/discuss.registry.d.ts"
   ],
   "bin": {
-    "playbook-code": "reference/sdlc/code.playbook/bin/playbook-code.js"
+    "playbook": "reference/sdlc/code.playbook/bin/playbook.js"
   },
   "exports": {
     "./runtime": {
       "types": "./src/runtime.d.ts",
       "default": "./src/runtime.js"
     },
+    "./xstate-runtime": {
+      "types": "./src/xstate-runtime.d.ts",
+      "default": "./src/xstate-runtime.js"
+    },
+    "./captain/playbook": {
+      "types": "./reference/sdlc/captain.playbook/captain.playbook.d.ts",
+      "default": "./reference/sdlc/captain.playbook/captain.playbook.js"
+    },
     "./code/playbook": {
       "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
       "default": "./reference/sdlc/code.playbook/code.playbook.js"
     },
+    "./code/registry": {
+      "types": "./reference/sdlc/code.playbook/code.registry.d.ts",
+      "default": "./reference/sdlc/code.playbook/code.registry.js"
+    },
     "./playbook-captain": {
       "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
       "default": "./reference/sdlc/code.playbook/playbook-captain.js"
     },
-    "./code/tmux-play": {
-      "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
-      "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
+    "./slc/*": "./slc/*",
+    "./discuss/playbook": {
+      "types": "./reference/sdlc/discuss.playbook/discuss.playbook.d.ts",
+      "default": "./reference/sdlc/discuss.playbook/discuss.playbook.js"
     },
-    "./slc/*": "./slc/*"
+    "./discuss/registry": {
+      "types": "./reference/sdlc/discuss.playbook/discuss.registry.d.ts",
+      "default": "./reference/sdlc/discuss.playbook/discuss.registry.js"
+    }
   },
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "playbook-code": "node reference/sdlc/code.playbook/bin/playbook-code.js"
+    "playbook": "node reference/sdlc/code.playbook/bin/playbook.js"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.3.143",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.154",
     "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "^0.13.0",
+    "@sublang/cligent": "^0.15.0",
+    "p-queue": "^9.3.1",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },

package/reference/sdlc/captain.md

@@ -0,0 +1,102 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# Captain
+
+This is the default generic Captain playbook.
+It has no players beyond Boss and Captain.
+
+At runtime Captain receives the exact original Boss intent and a catalog of enabled callable playbooks.
+Each catalog entry contains only a stable playbook id, its command, and its intent.
+The catalog is immutable host input for the session; Boss events and Captain decisions cannot replace it.
+Captain shall call only ids in that catalog and shall never call this Captain playbook itself.
+Captain is a router, not the specialist that performs the requested work.
+Captain shall decide only from the supplied Boss text and catalog, without investigating the task, inspecting the workspace, using tools, or relying on ambient project evidence.
+Captain shall keep a finite ordered plan and issue at most one child call at a time.
+`remainingPlan` shall contain only calls after the selected next call; every continuation shall strictly reduce its length.
+After Captain consumes an answer to its own routing or reassessment question,
+that question and answer are no longer pending before Captain calls a child or
+completes.
+
+The host guarantees that this Captain receives Boss input only while it is the active leaf and resumes only from a matching child return.
+That guarantee is an execution precondition, not a behavior for Captain to perform and not a source item to compile.
+An ordinary non-empty Boss turn at the ready state enters as a new intent with the exact Boss text and does not require model classification.
+When parked work can accept either an answer or a fresh directive, a classifier may select only the event kind and routing metadata; the runtime attaches the exact Boss text as the answer or fresh intent.
+These input-provenance rules are linker preconditions, not behaviors for Captain to perform and not source items to compile.
+
+When Boss gives a new intent while Captain is the active playbook, Captain shall ask Boss one material routing question or select the first call in a one- or multi-playbook plan, using the following prompt:
+> Boss intent: <boss-intent>
+> Enabled playbooks: <enabled-playbooks>
+> You are routing this intent, not performing the requested work.
+> Use only the Boss intent and enabled-playbooks catalog supplied here.
+> Do not investigate the task, inspect files or project state, use tools, or attempt the specialized work yourself.
+> Preserve Boss's intended outcome and constraints.
+> If the supplied evidence identifies a useful route, select an enabled playbook; do not finish the intent yourself.
+> Ask exactly one concise question only when its answer is necessary to choose a useful route or call order.
+> For a complex intent, divide it into the smallest finite ordered plan of useful playbook calls.
+> Name the selected first playbook and state its complete standalone request containing only the context it needs.
+> List any later playbook calls in their intended order after the selected first call.
+> Do not call a playbook merely to restate or classify the intent.
+> Write only concise human-facing routing prose or the one routing question.
+> Do not emit JSON, guard names, result property names, or control instructions.
+> Do not expose internal state ids, session ids, call ids, stack data, hidden control data, or private reasoning.
+
+Results:
+- `question`: Captain asked the one material routing question. Output shall include `question: <verbatim final text from the visible Captain call>`.
+- `delegation`: Captain selected the first useful call. Output shall include `remainingPlan: <finite JSON-safe array of only later calls>`, `nextPlaybookId: <selected stable enabled-playbook id>`, and `nextPlaybookInput: <complete standalone request>`.
+
+A fresh directive that interrupts any parked Captain work shall restart this
+routing behavior with that fresh intent. It shall not jump directly into
+reassessment or retain the prior question, answer, plan, call history,
+evidence, selection, response, or error.
+
+A question decision shall carry one concise `question` and wait for Boss without losing the original intent.
+Boss's answer resumes this same routing decision with continuation context; it is not a separate Captain behavior.
+A delegation decision shall carry a finite `remainingPlan` plus non-empty `nextPlaybookId` and `nextPlaybookInput` for its first call.
+The compiled routing result guards are exactly `question` and `delegation`, respectively; these names are part of this default playbook's stable machine contract.
+The initial routing state has no direct or terminal outcome.
+
+When Captain selects a next call with a non-empty `nextPlaybookId` from the enabled catalog, Captain shall call playbook selected by `nextPlaybookId`:
+> <nextPlaybookInput>
+
+When the called playbook returns successfully, aborts, or fails, Captain shall reassess the original intent, remaining plan, and completed call results using the following prompt:
+> Boss intent: <boss-intent>
+> Enabled playbooks: <enabled-playbooks>
+> Remaining plan: <remaining-plan>
+> Completed call results: <completed-call-results>
+> Preserve Boss's intended outcome and constraints.
+> Treat each returned result as evidence and revise the remaining plan when needed.
+> A continuing decision must strictly reduce the remaining plan length.
+> Do not repeat an equivalent failed or completed call without new information.
+> If the intent is fulfilled, give Boss one concise final response that states the result or actionable conclusion.
+> Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.
+> If information from Boss is now necessary, ask exactly one concise question.
+> Otherwise name exactly one next enabled playbook and state its complete standalone request containing only the context it needs.
+> List any still-later playbook calls in their intended order after the selected next call.
+> Write only concise human-facing final, question, or routing prose.
+> Do not emit JSON, guard names, result property names, or control instructions.
+> Do not expose internal state ids, session ids, call ids, stack data, hidden control data, or private reasoning.
+
+Results:
+- `final`: Captain gave Boss the concrete result or actionable conclusion. Output shall include `response: <verbatim final text from the visible Captain call>`.
+- `followUpQuestion`: Captain asked one necessary follow-up question. Output shall include `question: <verbatim final text from the visible Captain call>`.
+- `continuing`: Captain selected another useful call. Output shall include `remainingPlan: <strictly shorter finite JSON-safe array of only later calls>`, `nextPlaybookId: <selected stable enabled-playbook id>`, and `nextPlaybookInput: <complete standalone request>`.
+
+For the machine's deterministic safety floor, two calls are the same only when
+both the stable target id and complete standalone input match exactly.
+Captain shall record that exact pair before invoking the child, so an `ok`,
+`aborted`, or `error` return all prevent the same later attempt. An input
+revised with new information is different for this exact check; Captain still
+owns the broader semantic no-repeat instruction above.
+
+Each completed call result shall contain only the selected playbook id, its `ok`, `aborted`, or `error` status, and either the child's actual JSON-safe output or a compact error with only `name` and `message`.
+It shall never retain or expose a child session id, call id, child state, stack trace, or an opaque runtime result object.
+
+A final decision shall carry a concise JSON-safe `response` and complete.
+A follow-up question shall carry one concise `question` and wait for Boss without losing the original intent, plan, or completed results.
+Boss's answer resumes this same reassessment with continuation context; it is not a separate Captain behavior.
+A continuing decision shall carry a strictly shorter finite `remainingPlan` plus non-empty `nextPlaybookId` and `nextPlaybookInput`.
+The compiled reassessment result guards are exactly `final`,
+`followUpQuestion`, and `continuing`, respectively; these names are part of
+this default playbook's stable machine contract.
+A child abort or failure is a completed call result for reassessment and shall not route this playbook directly to its generic failure state.

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

@@ -0,0 +1,227 @@
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export type EnabledPlaybook = {
+    readonly id: string;
+    readonly command: string;
+    readonly intent: string;
+};
+export type NormalizedError = {
+    readonly name: string;
+    readonly message: string;
+    readonly stack?: string;
+};
+export type PlaybookStateValue = string | {
+    readonly [key: string]: PlaybookStateValue;
+};
+export type PlaybookState = {
+    readonly value: PlaybookStateValue;
+    readonly activeStateIds: readonly string[];
+    readonly tags: readonly string[];
+    readonly status: 'active' | 'done' | 'error' | 'stopped';
+    readonly quiescent: boolean;
+    readonly stateId?: string;
+};
+export type CompletedCallResult = {
+    readonly playbookId: string;
+    readonly status: 'ok';
+    readonly output?: JsonValue;
+} | {
+    readonly playbookId: string;
+    readonly status: 'aborted' | 'error';
+    readonly error: NormalizedError;
+};
+export type PendingBossQuestion = {
+    readonly questionId: ResumableStateId;
+    readonly resumeStateId: ResumableStateId;
+    readonly sourceItem: 'CAPTAIN-1' | 'CAPTAIN-3';
+    readonly player: 'Captain';
+    readonly question: string;
+};
+export type ResumableStateId = 'routing' | 'reassessing';
+export type CaptainMachineInput = {
+    readonly enabledPlaybooks: readonly EnabledPlaybook[];
+    readonly selfPlaybookId: string;
+    readonly bossIntent?: string;
+};
+export type CaptainMachineOutput = {
+    readonly response: string;
+};
+export type CaptainInput = {
+    readonly stateId: ResumableStateId;
+    readonly sourceItem: 'CAPTAIN-1' | 'CAPTAIN-3';
+    readonly prompt: string;
+    readonly result: Record<string, string>;
+    readonly bossIntent: string;
+    readonly enabledPlaybooks: readonly EnabledPlaybook[];
+    readonly remainingPlan?: readonly JsonValue[];
+    readonly completedCallResults?: readonly CompletedCallResult[];
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type CaptainOutput = {
+    readonly guard: 'question';
+    readonly question: string;
+} | {
+    readonly guard: 'delegation';
+    readonly remainingPlan: readonly JsonValue[];
+    readonly nextPlaybookId: string;
+    readonly nextPlaybookInput: string;
+} | {
+    readonly guard: 'final';
+    readonly response: string;
+} | {
+    readonly guard: 'followUpQuestion';
+    readonly question: string;
+} | {
+    readonly guard: 'continuing';
+    readonly remainingPlan: readonly JsonValue[];
+    readonly nextPlaybookId: string;
+    readonly nextPlaybookInput: string;
+} | {
+    readonly guard: 'needsBossReply';
+    readonly question: string;
+};
+export type PlaybookInput = {
+    readonly stateId: 'callPlaybook';
+    readonly sourceItem?: 'CAPTAIN-2';
+    readonly playbookId: string;
+    readonly text: string;
+    readonly playbookIdContext: 'nextPlaybookId';
+    readonly textContext: 'nextPlaybookInput';
+};
+export type PlaybookOutput = JsonValue | undefined;
+type Context = {
+    readonly bossIntent: string;
+    readonly enabledPlaybooks: readonly EnabledPlaybook[];
+    readonly selfPlaybookId: string;
+    readonly remainingPlan: readonly JsonValue[];
+    readonly completedCallResults: readonly CompletedCallResult[];
+    readonly nextPlaybookId: string;
+    readonly nextPlaybookInput: string;
+    readonly callHistory: readonly string[];
+    readonly response?: string;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+    readonly lastError?: JsonValue;
+};
+type BossIntentEvent = {
+    readonly type: 'BOSS_INTENT';
+    readonly bossIntent: string;
+};
+type BossInterruptEvent = {
+    readonly type: 'BOSS_INTERRUPT';
+    readonly targetId: 'routing';
+    readonly bossIntent: string;
+};
+type BossReplyEvent = {
+    readonly type: 'BOSS_REPLY';
+    readonly answer: string;
+    readonly questionId?: string;
+};
+export declare const captainMachine: import("xstate").StateMachine<Context, BossIntentEvent | BossInterruptEvent | BossReplyEvent, {
+    [x: string]: import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>> | import("xstate").ActorRefFromLogic<import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>> | undefined;
+}, {
+    src: "playbook";
+    logic: import("xstate").PromiseActorLogic<PlaybookOutput, PlaybookInput, import("xstate").EventObject>;
+    id: string | undefined;
+} | {
+    src: "captain";
+    logic: import("xstate").PromiseActorLogic<CaptainOutput, CaptainInput, import("xstate").EventObject>;
+    id: string | undefined;
+}, {
+    type: "startRoutingFromBoss";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "storeBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberInvalidBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setRoutingQuestion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "storeRoutingDelegation";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "appendSuccessfulChildResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "appendRejectedChildResult";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "storeFinalResponse";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setReassessQuestion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "storeContinuingCall";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberInvalidActorOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "isRoutingInterrupt";
+    params: unknown;
+} | {
+    type: "canResumeRouting";
+    params: unknown;
+} | {
+    type: "canResumeReassessing";
+    params: unknown;
+} | {
+    type: "hasBossIntent";
+    params: unknown;
+} | {
+    type: "isRoutingQuestion";
+    params: unknown;
+} | {
+    type: "isRoutingDelegation";
+    params: unknown;
+} | {
+    type: "isReassessFinal";
+    params: unknown;
+} | {
+    type: "isReassessQuestion";
+    params: unknown;
+} | {
+    type: "isReassessContinuing";
+    params: unknown;
+} | {
+    type: "isPlaybookSuccessOutput";
+    params: unknown;
+} | {
+    type: "isAuthoredChildError";
+    params: unknown;
+}, never, "done" | "failed" | "callPlaybook" | "routing" | "reassessing" | "ready" | "awaitBossReply", string, CaptainMachineInput, CaptainMachineOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "captain";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly routing: {
+            id: "routing";
+        };
+        readonly callPlaybook: {
+            id: "callPlaybook";
+        };
+        readonly reassessing: {
+            id: "reassessing";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly done: {
+            id: "done";
+        };
+    };
+}>;
+export {};