@sublang/playbook 5.0.0 → 7.0.0

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

@@ -0,0 +1,41 @@
+import { type PlaybookRuntime, type PlaybookRuntimeOptions } from './decide.playbook.js';
+export interface PlaybookSummaryPolicy {
+    stateCountLabels: Readonly<Record<string, string>>;
+    copyPasteGuardNames: readonly string[];
+    savedCountsLine(counts: {
+        interruptions: number;
+        copyPastes: number;
+    }, rounds: number): string;
+}
+export interface RegistryPlayer {
+    id: string;
+    adapter?: string;
+    model?: string;
+}
+export interface CreateDecideRuntimeOptions {
+    captainOptions: unknown;
+    players: readonly RegistryPlayer[];
+}
+export type DecideOptions = Readonly<Record<string, never>>;
+export interface DecidePlaybookRegistryEntry {
+    id: 'decide';
+    command: 'decide';
+    intent: string;
+    requiredRoleIds: readonly ['coder', 'reviewer'];
+    summaryPolicy: PlaybookSummaryPolicy;
+    validateOptions(captainOptions: unknown): DecideOptions;
+    createRuntime(options: CreateDecideRuntimeOptions): PlaybookRuntime;
+}
+export declare const decideStateCountLabels: {
+    readonly independentProposals: "proposal round";
+};
+export declare const decideCopyPasteGuardNames: readonly ["proposed"];
+export declare function decideSavedCountsLine(counts: {
+    interruptions: number;
+    copyPastes: number;
+}, rounds: number): string;
+export declare const decideSummaryPolicy: PlaybookSummaryPolicy;
+export declare function validateDecideOptions(optionSlice: unknown): DecideOptions;
+export declare function createDecideRuntimeOptions({ captainOptions, players, }: CreateDecideRuntimeOptions): PlaybookRuntimeOptions;
+export declare const decidePlaybookRegistryEntry: DecidePlaybookRegistryEntry;
+export default decidePlaybookRegistryEntry;

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

@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+import createPlaybookRuntime from './decide.playbook.js';
+export const decideStateCountLabels = {
+    independentProposals: 'proposal round',
+};
+export const decideCopyPasteGuardNames = ['proposed'];
+function countNoun(count, singular, plural = `${singular}s`) {
+    return `${count} ${count === 1 ? singular : plural}`;
+}
+export function decideSavedCountsLine(counts, rounds) {
+    return [
+        'Saved you',
+        countNoun(counts.interruptions, 'interruption'),
+        'and',
+        countNoun(counts.copyPastes, 'copy-paste'),
+        'across',
+        countNoun(rounds, 'round'),
+        'of proposals/reviews.',
+    ].join(' ');
+}
+export const decideSummaryPolicy = {
+    stateCountLabels: decideStateCountLabels,
+    copyPasteGuardNames: decideCopyPasteGuardNames,
+    savedCountsLine: decideSavedCountsLine,
+};
+export function validateDecideOptions(optionSlice) {
+    if (optionSlice === undefined)
+        return Object.freeze({});
+    if (optionSlice === null ||
+        typeof optionSlice !== 'object' ||
+        Array.isArray(optionSlice)) {
+        throw new Error('captain.options.playbooks.decide.options must be an object');
+    }
+    const keys = Object.keys(optionSlice);
+    if (keys.length > 0) {
+        throw new Error(`Unknown config field captain.options.playbooks.decide.options.${keys[0]}`);
+    }
+    return Object.freeze({});
+}
+function playerIdentity(players, id) {
+    const player = players.find((entry) => entry.id === id);
+    return player?.model ?? player?.adapter ?? id;
+}
+export function createDecideRuntimeOptions({ captainOptions, players, }) {
+    validateDecideOptions(captainOptions);
+    return { coderLlm: playerIdentity(players, 'coder') };
+}
+export const decidePlaybookRegistryEntry = {
+    id: 'decide',
+    command: 'decide',
+    intent: 'turn independent Coder and Reviewer proposals into an approved spec-design commit',
+    requiredRoleIds: ['coder', 'reviewer'],
+    summaryPolicy: decideSummaryPolicy,
+    validateOptions: validateDecideOptions,
+    createRuntime(options) {
+        return createPlaybookRuntime(createDecideRuntimeOptions(options));
+    },
+};
+export default decidePlaybookRegistryEntry;

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

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+import createPlaybookRuntime, {
+  type PlaybookRuntime,
+  type PlaybookRuntimeOptions,
+} from './decide.playbook.js';
+
+export interface PlaybookSummaryPolicy {
+  stateCountLabels: Readonly<Record<string, string>>;
+  copyPasteGuardNames: readonly string[];
+  savedCountsLine(
+    counts: { interruptions: number; copyPastes: number },
+    rounds: number,
+  ): string;
+}
+
+export interface RegistryPlayer {
+  id: string;
+  adapter?: string;
+  model?: string;
+}
+
+export interface CreateDecideRuntimeOptions {
+  captainOptions: unknown;
+  players: readonly RegistryPlayer[];
+}
+
+export type DecideOptions = Readonly<Record<string, never>>;
+
+export interface DecidePlaybookRegistryEntry {
+  id: 'decide';
+  command: 'decide';
+  intent: string;
+  requiredRoleIds: readonly ['coder', 'reviewer'];
+  summaryPolicy: PlaybookSummaryPolicy;
+  validateOptions(captainOptions: unknown): DecideOptions;
+  createRuntime(options: CreateDecideRuntimeOptions): PlaybookRuntime;
+}
+
+export const decideStateCountLabels = {
+  independentProposals: 'proposal round',
+} as const;
+
+export const decideCopyPasteGuardNames = ['proposed'] as const;
+
+function countNoun(
+  count: number,
+  singular: string,
+  plural = `${singular}s`,
+): string {
+  return `${count} ${count === 1 ? singular : plural}`;
+}
+
+export function decideSavedCountsLine(
+  counts: { interruptions: number; copyPastes: number },
+  rounds: number,
+): string {
+  return [
+    'Saved you',
+    countNoun(counts.interruptions, 'interruption'),
+    'and',
+    countNoun(counts.copyPastes, 'copy-paste'),
+    'across',
+    countNoun(rounds, 'round'),
+    'of proposals/reviews.',
+  ].join(' ');
+}
+
+export const decideSummaryPolicy: PlaybookSummaryPolicy = {
+  stateCountLabels: decideStateCountLabels,
+  copyPasteGuardNames: decideCopyPasteGuardNames,
+  savedCountsLine: decideSavedCountsLine,
+};
+
+export function validateDecideOptions(optionSlice: unknown): DecideOptions {
+  if (optionSlice === undefined) return Object.freeze({});
+  if (
+    optionSlice === null ||
+    typeof optionSlice !== 'object' ||
+    Array.isArray(optionSlice)
+  ) {
+    throw new Error(
+      'captain.options.playbooks.decide.options must be an object',
+    );
+  }
+  const keys = Object.keys(optionSlice);
+  if (keys.length > 0) {
+    throw new Error(
+      `Unknown config field captain.options.playbooks.decide.options.${keys[0]}`,
+    );
+  }
+  return Object.freeze({});
+}
+
+function playerIdentity(
+  players: readonly RegistryPlayer[],
+  id: string,
+): string {
+  const player = players.find((entry) => entry.id === id);
+  return player?.model ?? player?.adapter ?? id;
+}
+
+export function createDecideRuntimeOptions({
+  captainOptions,
+  players,
+}: CreateDecideRuntimeOptions): PlaybookRuntimeOptions {
+  validateDecideOptions(captainOptions);
+  return { coderLlm: playerIdentity(players, 'coder') };
+}
+
+export const decidePlaybookRegistryEntry: DecidePlaybookRegistryEntry = {
+  id: 'decide',
+  command: 'decide',
+  intent:
+    'turn independent Coder and Reviewer proposals into an approved spec-design commit',
+  requiredRoleIds: ['coder', 'reviewer'],
+  summaryPolicy: decideSummaryPolicy,
+  validateOptions: validateDecideOptions,
+  createRuntime(options) {
+    return createPlaybookRuntime(createDecideRuntimeOptions(options));
+  },
+};
+
+export default decidePlaybookRegistryEntry;

package/reference/sdlc/review.md

@@ -0,0 +1,81 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# Review
+
+Players:
+
+- Coder
+- Reviewer
+
+The caller supplies the initial intent or any specific context and relevant run results.
+
+`review` examines committed work only.
+Every review round begins with a new or existing commit.
+
+At the first review round, Captain shall relay to Reviewer the complete initial review request in quotes (`>`).
+
+At the first review round, Captain shall give Reviewer the following instruction:
+
+```markdown
+A new review begins on the latest commit.
+Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.
+```
+
+After every review-fix commit, Captain shall give Reviewer the following instruction:
+
+```markdown
+Review the latest commit and resulting repository state; read the commit message first for its intent and rationale.
+```
+
+When Coder rejects every finding and makes no commit, Captain shall give Reviewer the following instruction:
+
+```markdown
+No new commit was made because Coder rejected every finding.
+For any rebuttal, accept or challenge it.
+State which findings, if any, remain.
+```
+
+At the start of *every* review round, Captain shall relay to Reviewer any Coder feedback from the preceding round and any relevant run results, in quotes (`>`) after the instruction.
+
+At the start of *every* review round, Captain shall append the following instruction to the end of the prompt:
+
+```markdown
+Understand the full picture and think systematically about the underlying design.
+Continue to identify issues or improvements, if any (numbered; no duplication).
+Treat as settled, and do not raise again, any finding in this review rejected twice with reasoning.
+Flag only what materially affects correctness, behavior, or spec quality — not style, equally valid alternatives, or theoretical threats.
+For specs, flag stale, missing, over-specified, or under-specified ones.
+Avoid unnecessary complexity in code or tests, but flag any fundamental design flaw when leaving it would cost more in later patches than fixing it now.
+
+Do not re-run tests or builds whose inputs have not changed since any previous reported run.
+Do not edit files or commit; report findings only.
+
+Consult @specs/map.md for context if needed; verify it remains accurate.
+Consult @specs/meta.md for spec requirements if needed; verify affected specs follow it.
+```
+
+When Reviewer raises or keeps any finding, Captain shall relay the Reviewer's findings and any relevant run results to Coder, in quotes (`>`), along with the following prompt:
+
+```markdown
+For each review item, accept or reject it.
+Before deciding, understand the full picture and think systematically about the underlying design.
+Reject anything that is not essential or is not worth fixing now.
+If you accept an item, fix its root cause, including any fundamental design flaw - do not patch around it.
+If you reject an item, give the reasoning and cite code or test output that supports it.
+Do not re-run tests or builds whose inputs have not changed since any previous reported run.
+
+If you accept any item, make minimal changes and commit them as one new commit; never amend the reviewed commit.
+Follow @specs/packages/git.md.
+Make the commit message explain concisely what changed and why, including relevant verification.
+Coder is <coder-llm>; Reviewer is <reviewer-llm>; format model tokens in conventional human form.
+
+If you reject every item, change nothing and make no commit.
+Report every disposition, all relevant run results, and every rebuttal.
+```
+
+When Coder makes a new commit or decides to reject all findings, Captain shall relay the above required context to Reviewer and begin the next review round.
+Reviewer shall read the context information and follow the corresponding instructions.
+Rounds continue until Reviewer raises no unsettled findings.
+`review` then returns the approved latest commit and the fact that no findings remain to its caller.

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

@@ -0,0 +1,183 @@
+type Player = 'Coder' | 'Reviewer';
+type JumpableStateId = 'reviewInitial';
+export type ResumableStateId = 'reviewInitial' | 'addressFindings' | 'reviewAfterCommit' | 'reviewAfterRebuttal';
+export interface PendingBossQuestion {
+    questionId: ResumableStateId;
+    resumeStateId: ResumableStateId;
+    sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
+    player: Player;
+    question: string;
+}
+export interface ReviewOutput {
+    approvedCommit: 'latest';
+    noUnsettledFindings: true;
+}
+export interface ReviewInput {
+    coderLlm: string;
+    reviewerLlm: string;
+}
+export interface ReviewContext extends ReviewInput {
+    callerInput?: string;
+    reviewerOutput?: string;
+    coderOutput?: string;
+    lastError?: unknown;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
+}
+export type ReviewEvent = {
+    type: 'START_REVIEW';
+    callerInput: string;
+} | {
+    type: 'BOSS_INTERRUPT';
+    targetId: JumpableStateId;
+    bossIntent: string;
+} | {
+    type: 'BOSS_REPLY';
+    questionId?: ResumableStateId;
+    answer: string;
+};
+export interface PlayerInput {
+    stateId: ResumableStateId;
+    sourceItem: `REVIEW-${1 | 2 | 3 | 4}`;
+    player: Player;
+    prompt: string;
+    result: Readonly<Record<string, string>>;
+    callerInput?: string;
+    reviewerOutput?: string;
+    coderOutput?: string;
+    coderLlm?: string;
+    reviewerLlm?: string;
+    pendingBossQuestion?: PendingBossQuestion;
+    bossReply?: string;
+}
+export type PlayerOutput = {
+    guard: 'hasFindings';
+    reviewerOutput: string;
+} | {
+    guard: 'noFindings';
+} | {
+    guard: 'committed';
+    coderOutput: string;
+} | {
+    guard: 'rejectedAll';
+    coderOutput: string;
+} | {
+    guard: 'needsBossReply';
+    question: string;
+};
+export declare const reviewMachine: import("xstate").StateMachine<ReviewContext, {
+    type: "START_REVIEW";
+    callerInput: string;
+} | {
+    type: "BOSS_INTERRUPT";
+    targetId: JumpableStateId;
+    bossIntent: string;
+} | {
+    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: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberEmptyBossReplyError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyStartInput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "copyInterruptedInput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberReviewerOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberCoderOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "clearBossReplyContext";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingReviewInitial";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingAddressFindings";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingReviewAfterCommit";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "setPendingReviewAfterRebuttal";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "needsBossReply";
+    params: unknown;
+} | {
+    type: "emptyBossReply";
+    params: unknown;
+} | {
+    type: "hasFindings";
+    params: unknown;
+} | {
+    type: "noFindings";
+    params: unknown;
+} | {
+    type: "committed";
+    params: unknown;
+} | {
+    type: "rejectedAll";
+    params: unknown;
+} | {
+    type: "resumeReviewInitial";
+    params: unknown;
+} | {
+    type: "resumeAddressFindings";
+    params: unknown;
+} | {
+    type: "resumeReviewAfterCommit";
+    params: unknown;
+} | {
+    type: "resumeReviewAfterRebuttal";
+    params: unknown;
+} | {
+    type: "restartInitialReview";
+    params: unknown;
+}, never, "done" | "failed" | "awaitBossReply" | "ready" | "reviewInitial" | "addressFindings" | "reviewAfterCommit" | "reviewAfterRebuttal", string, ReviewInput, ReviewOutput, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "review";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly reviewInitial: {
+            id: "reviewInitial";
+        };
+        readonly addressFindings: {
+            id: "addressFindings";
+        };
+        readonly reviewAfterCommit: {
+            id: "reviewAfterCommit";
+        };
+        readonly reviewAfterRebuttal: {
+            id: "reviewAfterRebuttal";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly done: {
+            id: "done";
+        };
+    };
+}>;
+export {};