@sublang/playbook 5.0.0 → 7.0.0

package/reference/sdlc/discuss.md

@@ -1,93 +0,0 @@
-<!-- SPDX-License-Identifier: Apache-2.0 -->
-<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
-
-# Discuss
-
-Players:
-
-- Host
-- Participant
-- Committer = Host | Participant
-
-When Boss gives a topic, Captain shall relay it to both players concurrently and independently, without waiting for either proposal before asking the other, along with the following prompt:
-
-> Assess whether Boss's topic above is better expressed as a few spec items (per @specs/meta.md) or requires one or more DRs added to @specs/decisions/.
-> Consult @specs/map.md, if necessary, to find relevant context.
-> Each DR should be coherent and focused.
-> Propose your design in reply.
-> DRs, if any, need not include full detail here — describe the key points at a high level.
-> Don't change any code.
-
-The initial discussion shall go round by round.
-In each round, Captain shall prompt both players concurrently.
-Both players each shall make a new proposal using only the completed proposals from the previous round; neither shall see the other's current-round result before replying.
-Captain shall join both results before beginning the next round, using the following prompt:
-
-> Consider the other agent's proposal below.
-> (1) If there are essentially different points (including creation or division of DRs), list them, accept any reasonable ones, and challenge the rest with strong reasoning, solid evidence, and comprehensive thinking — make your argument.
-> (2) Only if your proposal of the previous round is equivalent to the other's, with nothing to reconcile, state the end of initial discussion.
-> Don't change any code.
-
-A Boss interrupt into parallel discussion shall restart the whole initial-proposal or reconciliation round so both independent branches receive one coherent prior-round input. An individual branch that asks Boss a question may still resume on its own; branch working states are not Boss-interrupt destinations.
-
-When both players state the end of initial discussion, Captain shall ask Host to write spec items or DRs according to the agreement, along with the following prompt:
-
-> Update @specs/map.md to reflect your changes (if any) when done.
-
-When Committer commits at the end of the initial discussion, or when Host addresses findings with changes, Captain shall ask Participant to review the spec changes in a round, without waiting for Boss.
-In the first step of each round, Participant shall review the latest changes, address any rebuttals, and raise any findings.
-In the second step of each round, Host shall address any findings.
-Rounds continue until Participant raises no findings.
-
-Spec item files are the files under @specs/ that hold spec items — @specs/packages/ and @specs/compositions/ in the current layout, or @specs/user/, @specs/dev/, and @specs/test/ in the legacy one; decision and intent records (iteration records in older scaffolds), @specs/map.md, and @specs/meta.md are not spec item files.
-
-While any new or updated spec item (in spec item files) is under review, Captain shall include the following prompt for Participant:
-
-> Verify any new or updated spec items are:
->
-> - Complete & coherent: sufficient for you to reimplement code.
-> - Right level: external behavior users rely on or internal system behavior (organized per @specs/meta.md), not implementation specifics; integration/system testing, not unit testing.
-> - Minimal: essential and concise; every item earns its place; also check with other items.
-> - Well organized: spec packages are finely scoped, with high cohesion and low coupling.
->
-> Flag anything missing, redundant, over-specified, or under-specified.
-
-While any new or updated DR is under review, Captain shall include the following prompt for Participant:
-
-> Review any new/updated decision following @specs/meta.md (reread if necessary).
-> Flag any issues or propose any design suggestions (numbered; no duplication), with strong reasoning and evidence.
-> Key statements must be backed by references unless they are common sense or widely acknowledged best practices.
->
-> If the decision is well-thought-out and well-written, don't raise nitpicks.
-> Remember to keep the DR simple and minimal.
-
-When Participant begins any review, Captain shall include the following prompt:
-
-> Think thoroughly — don't just approve or reject.
-> For context discovery, consult @specs/map.md; @specs/meta.md describes the spec format.
-> Verify @specs/map.md reflects the changes.
-> If the change is ready to commit or push, don't raise nitpicks.
-> Do not edit files or commit; report findings only.
-
-When Participant raises any findings, Captain shall relay them to Host along with the following prompt:
-
-> For each review item below for the above changes, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
-> Stage all current changes that belong in the repo before making any edits, and leave your edits unstaged/untracked.
-
-When Host raises any rebuttals, Captain shall relay them to Participant along with the following prompt:
-
-> For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.
-
-When the spec items or DRs are written at the end of the initial discussion, or Participant raises no findings on uncommitted changes, Captain shall ask Committer to commit with the following prompt:
-
-> Then make a commit of the changes that belong in the repo, following @specs/packages/git.md (reread if necessary).
-> If that spec is absent, follow the legacy @specs/dev/git.md; if neither exists, follow the repository's existing commit conventions and do not search elsewhere.
-> Write the commit message concisely.
-> Host is \<host-llm\>.
-> Participant is \<participant-llm\>.
-
-`<*-llm>` shall be the conventional human form of the substituted ID (e.g., `claude-opus-4-7` → `Claude-Opus-4.7`, `gpt-5.5` → `GPT-5.5`).
-
-For the initial-discussion commit outcome, any adjudicated `reviewScope`
-payload shall be exactly `specItems`, `decisionRecords`, or `mixed`; a prose
-summary is not a review scope.

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

@@ -1,396 +0,0 @@
-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" | "awaitBossReply" | "ready" | "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;