@sublang/playbook 13.0.0 → 13.2.0

package/README.md

@@ -29,13 +29,14 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 
 ## Quick start
 
-Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, and **DECIDE** for independently proposed and reviewed specification decisions.
-CODE and DECIDE call REVIEW as a nested playbook.
+Out of the box, Playbook includes **CODE** for implementation, **REVIEW** for commit-based review and fixes, **DECIDE** for independently proposed and reviewed specification decisions, **DEV** for repository-aware planning of a development request, **BRANCH** for checking out a new branch for a GitHub issue, and **PR** for publishing, checking, and merging that branch through a pull request.
+CODE and DECIDE call REVIEW as a nested playbook; DEV calls CODE, or DECIDE and then CODE, and wraps them in BRANCH and PR when the request names a GitHub issue or asks for a pull request.
 
 The shared starter config uses Claude as both Captain and the `dev.coder`
-player, and Codex as `dev.reviewer`. CODE, REVIEW, and DECIDE bind their local
-roles explicitly to those two stable players, so nested and later engagements
-share a conversation only where their bindings name the same player ID.
+player, and Codex as `dev.reviewer`. CODE, REVIEW, DECIDE, BRANCH, and PR bind
+their local roles explicitly to those two stable players, so nested and later
+engagements share a conversation only where their bindings name the same
+player ID; DEV's Analyst binds a distinct `dev.analyst` player.
 
 ```sh
 npm install -g @sublang/playbook
@@ -50,6 +51,7 @@ Prerequisites:
 - Node.js >= 20.6.0
 - Authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY`
 - Authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY`
+- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated for the repository's GitHub remote, for `/branch`, `/pr`, and `/dev` requests that name an issue or ask for a pull request
 
 Interactive `playbook` additionally needs tmux 3.3 or newer and [`glow`](https://github.com/charmbracelet/glow#installation) on `PATH`; headless `playbook run` does not.
 

package/docs/cli.md

@@ -105,8 +105,8 @@ its exit status or signal and exit `127` when it cannot be spawned
 
 The Boss pane starts at the Playbook Captain shell, where the session
 Captain runs for the whole session and sees every turn. Use `/code`,
-`/review`, `/decide`, or `/dev` followed by a task to select one of the
-bundled playbooks explicitly. A registered command resolves deterministically,
+`/review`, `/decide`, `/dev`, `/branch`, or `/pr` followed by a task to
+select one of the bundled playbooks explicitly. A registered command resolves deterministically,
 with no model call parsing it: at idle it starts that playbook, at its
 own leaf it delivers the rest of the line, an enabled command absent
 from the active path switches to it, and a bare command answers with
@@ -121,11 +121,25 @@ untouched
 ([[playbook-captain-1](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-1)],
 [[playbook-captain-2](https://github.com/sublang-ai/playbook/blob/main/specs/packages/playbook-captain.md#playbook-captain-2)]).
 
-The current CODE, REVIEW, DECIDE, and DEV workflows take their deterministic
-initial event from the selecting Boss turn. CODE and DECIDE then call REVIEW
-as a nested playbook, while DEV — the repository-aware planner behind
-`/dev` — analyzes a development request and itself calls CODE, or DECIDE and
-then CODE, as nested playbooks. Local role names do not imply continuity: each frame
+The current CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows take their
+deterministic initial event from the selecting Boss turn. CODE and DECIDE then
+call REVIEW as a nested playbook, while DEV — the repository-aware planner
+behind `/dev` — analyzes a development request and itself calls CODE, or
+DECIDE and then CODE, as nested playbooks. When the request names a GitHub
+issue or asks for pull-request delivery, DEV reads the issue and its comments
+while planning, calls BRANCH before that path and PR after CODE succeeds, and
+ends with a merged pull request and a closed issue — or with a named failure
+that leaves the pull request open for a later `/pr`. Both are usable on their
+own: `/branch <issue or request>` creates and checks out `issue-N-slug` (or a
+request slug) at the current commit, changing nothing else; `/pr` pushes the
+checked-out branch, opens or reuses its pull request against the default
+branch, waits for the checks, fixes red checks through one nested CODE call,
+merges with a merge commit, and fast-forwards the local default branch. A
+repository without checks merges on CODE's nested review alone. BRANCH, PR,
+and issue-aware DEV planning require the GitHub CLI `gh`, authenticated for
+the repository's GitHub remote
+([DR-050](https://github.com/sublang-ai/playbook/blob/main/specs/decisions/050-pull-request-delivery.md)).
+Local role names do not imply continuity: each frame
 uses the exact stable player IDs configured under its `roles` map. Equal IDs
 share one pane and provider conversation across nested and later root
 engagements; distinct IDs remain isolated even when their agent settings are
@@ -333,8 +347,13 @@ For each governed player call, Playbook records a Git baseline before the call
 and a durable receipt afterward. CODE and DECIDE commit arms, and REVIEW's
 Coder commit arm, accept a commit only when the receipt proves exactly one
 descendant commit with no residual repository change; REVIEW's Reviewer calls,
-DECIDE's proposal calls, and every DEV Analyst planning call require the
-repository to remain exact. The
+DECIDE's proposal calls, every DEV Analyst planning call, BRANCH's Coder call,
+and PR's Coder call require the repository to remain exact — a new branch at
+the current commit, a push, and an opened pull request change neither HEAD's
+commit nor the working tree, and BRANCH takes its base revision from that
+receipt rather than from the Coder. PR's check waits, fix publication, merge,
+and fast-forward are agent-free script steps outside governance; the merge is
+the one step that moves HEAD, onto the default branch. The
 player's prose, including any `Commit:` line, is presentation rather than
 proof.
 

package/docs/configuration.md

@@ -113,6 +113,20 @@ playbooks:
     from: '@sublang/playbook/dev/registry'
     roles:
       analyst: dev.analyst
+
+  # Pull-request delivery for DEV. BRANCH and PR bind Coder to the same
+  # dev.coder player as CODE and REVIEW on purpose: the Coder that read the
+  # issue and named the branch makes the commits and then describes them in
+  # the pull request. Change an id to isolate its conversation.
+  branch:
+    from: '@sublang/playbook/branch/registry'
+    roles:
+      coder: dev.coder
+
+  pr:
+    from: '@sublang/playbook/pr/registry'
+    roles:
+      coder: dev.coder
 ```
 
 The current bundled workflows accept no workflow-specific options.
@@ -156,11 +170,13 @@ those define the stable player envelope.
 
 Two bindings that name the same player ID deliberately share one sequential
 provider conversation throughout the logical Captain session — across nested
-calls, returns, and later root engagements. CODE's and REVIEW's `coder` roles
-therefore share `dev.coder` in the starter, and DECIDE and its nested REVIEW
-share both starter players. DEV's `analyst` instead binds the distinct
-`dev.analyst` player, so planning context does not bleed into the shared
-review conversation. Disposal of one playbook frame does not clear that
+calls, returns, and later root engagements. CODE's, REVIEW's, BRANCH's, and
+PR's `coder` roles therefore share `dev.coder` in the starter — so on a `/dev`
+pull-request path the Coder that read the issue and named the branch makes the
+commits and then describes them in the pull request — and DECIDE and its
+nested REVIEW share both starter players. DEV's `analyst` instead binds the
+distinct `dev.analyst` player, so planning context does not bleed into the
+shared review conversation. Disposal of one playbook frame does not clear that
 session ledger.
 
 Two distinct player IDs stay isolated even when their agent blocks are

package/docs/embedding.md

@@ -20,7 +20,7 @@ semver-stable surface (`PlayerResult`, `PlaybookPorts`,
 `PlayerCallOptions`, `PlayerSessionStore`, `CaptainCallOptions`, `CaptainResult`,
 `PlaybookTraceEvent`, and `PlaybookRuntimeFactory`) that imports no CODE
 or FSM types, so a host satisfies it once and inherits every playbook.
-The generated CODE, REVIEW, and DECIDE modules re-export their shared
+The generated CODE, REVIEW, DECIDE, DEV, BRANCH, and PR modules re-export their shared
 runtime contract types from their public `playbook` subpaths;
 `PlaybookRuntimeFactory` is available from `@sublang/playbook/runtime`.
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@sublang/playbook",
-  "version": "13.0.0",
+  "version": "13.2.0",
   "type": "module",
-  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, and DEV workflows driven by GEARS specs.",
+  "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, and PR workflows driven by GEARS specs.",
   "license": "Apache-2.0",
   "homepage": "https://github.com/sublang-ai/playbook#readme",
   "repository": {
@@ -46,6 +46,8 @@
     "reference/sdlc/review.md",
     "reference/sdlc/decide.md",
     "reference/sdlc/dev.md",
+    "reference/sdlc/branch.md",
+    "reference/sdlc/pr.md",
     "reference/sdlc/captain.playbook/captain.gears.md",
     "reference/sdlc/captain.playbook/captain.fsm.ts",
     "reference/sdlc/captain.playbook/captain.fsm.js",
@@ -113,6 +115,26 @@
     "reference/sdlc/dev.playbook/dev.registry.ts",
     "reference/sdlc/dev.playbook/dev.registry.js",
     "reference/sdlc/dev.playbook/dev.registry.d.ts",
+    "reference/sdlc/branch.playbook/branch.gears.md",
+    "reference/sdlc/branch.playbook/branch.fsm.ts",
+    "reference/sdlc/branch.playbook/branch.fsm.js",
+    "reference/sdlc/branch.playbook/branch.fsm.d.ts",
+    "reference/sdlc/branch.playbook/branch.playbook.ts",
+    "reference/sdlc/branch.playbook/branch.playbook.js",
+    "reference/sdlc/branch.playbook/branch.playbook.d.ts",
+    "reference/sdlc/branch.playbook/branch.registry.ts",
+    "reference/sdlc/branch.playbook/branch.registry.js",
+    "reference/sdlc/branch.playbook/branch.registry.d.ts",
+    "reference/sdlc/pr.playbook/pr.gears.md",
+    "reference/sdlc/pr.playbook/pr.fsm.ts",
+    "reference/sdlc/pr.playbook/pr.fsm.js",
+    "reference/sdlc/pr.playbook/pr.fsm.d.ts",
+    "reference/sdlc/pr.playbook/pr.playbook.ts",
+    "reference/sdlc/pr.playbook/pr.playbook.js",
+    "reference/sdlc/pr.playbook/pr.playbook.d.ts",
+    "reference/sdlc/pr.playbook/pr.registry.ts",
+    "reference/sdlc/pr.playbook/pr.registry.js",
+    "reference/sdlc/pr.playbook/pr.registry.d.ts",
     "docs",
     "reference/sdlc/code.playbook/session-host.js",
     "reference/sdlc/code.playbook/session-host.d.ts",
@@ -180,6 +202,22 @@
       "types": "./reference/sdlc/dev.playbook/dev.registry.d.ts",
       "default": "./reference/sdlc/dev.playbook/dev.registry.js"
     },
+    "./branch/playbook": {
+      "types": "./reference/sdlc/branch.playbook/branch.playbook.d.ts",
+      "default": "./reference/sdlc/branch.playbook/branch.playbook.js"
+    },
+    "./branch/registry": {
+      "types": "./reference/sdlc/branch.playbook/branch.registry.d.ts",
+      "default": "./reference/sdlc/branch.playbook/branch.registry.js"
+    },
+    "./pr/playbook": {
+      "types": "./reference/sdlc/pr.playbook/pr.playbook.d.ts",
+      "default": "./reference/sdlc/pr.playbook/pr.playbook.js"
+    },
+    "./pr/registry": {
+      "types": "./reference/sdlc/pr.playbook/pr.registry.d.ts",
+      "default": "./reference/sdlc/pr.playbook/pr.registry.js"
+    },
     "./session-host": {
       "types": "./reference/sdlc/code.playbook/session-host.d.ts",
       "default": "./reference/sdlc/code.playbook/session-host.js"
@@ -198,7 +236,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.25.0",
+    "@sublang/cligent": "^0.26.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

package/reference/sdlc/branch.md

@@ -0,0 +1,37 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+<!-- AI agents: do not edit this file without human approval. -->
+
+# Branch
+
+Roles:
+
+- Coder
+
+The caller supplies a development request that names a GitHub issue (number or URL) or, when no issue is named, describes the work, together with any relevant context.
+
+`branch` prepares pull-request delivery of one development request: it creates and checks out a new branch at the current commit.
+It changes no files and owns no repository commit.
+
+When the caller gives the request, Captain shall relay the complete caller input in quotes (`>`) to Coder, along with the following instruction:
+
+> Original request: <caller-input>
+
+```markdown
+Prepare a new branch for this work without changing any file or making any commit.
+Identify the GitHub issue the request names, if any, and read it with its comments (`gh issue view --comments` with the issue number).
+If the request could refer to more than one issue, or does not say which work to branch for, ask Boss before creating anything.
+Confirm that the working tree is clean and that `gh` is authenticated for the repository's GitHub remote.
+Name the branch `issue-N-short-kebab-slug` for issue number N, otherwise a short kebab-case slug of the request.
+Create the branch from the current commit and check it out; do not pull, reset, stash, or move HEAD to another commit.
+Report the exact branch name, the commit it was created from, and a concise summary of the issue and its comments, or of the request when no issue is named.
+If the working tree is not clean, `gh` is not authenticated, the named issue does not exist or cannot be read, or a branch with that name already exists locally or on the remote, create nothing and report the failure with its reason.
+```
+
+The result has two semantic outcomes: branched and refused, plus the Boss question when the request is ambiguous about the issue or work it means.
+Each outcome requires affirmative support in Coder's result; the absence of a reported obstacle is not support for branched, and no outcome depends on a fixed presentation format of Coder's reply.
+Every outcome keeps the repository exact: a new branch at the current commit changes neither HEAD's commit nor the working tree.
+Captain shall take the base revision from repository authority, not from Coder's prose.
+
+For branched, `branch` is complete and returns the exact branch name, the exact base revision, and the issue summary to its caller.
+For refused, `branch` fails and reports Coder's complete result with its reason to its caller; no branch was created.

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

@@ -0,0 +1,169 @@
+export type BranchStateId = 'createBranch';
+export type BranchSourceItem = 'BRANCH-1';
+export type PendingBossQuestion = {
+    readonly questionId: 'createBranch';
+    readonly resumeStateId: 'createBranch';
+    readonly sourceItem: 'BRANCH-1';
+    readonly asker: {
+        readonly kind: 'role';
+        readonly roleId: 'coder';
+    };
+    readonly question: string;
+};
+export type PlayerInput = {
+    readonly stateId: 'createBranch';
+    readonly role: 'coder';
+    readonly sourceItem: 'BRANCH-1';
+    readonly prompt: string;
+    readonly result: Readonly<Record<string, string>>;
+    readonly callerInput: string;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type PlayerOutput = {
+    readonly guard: 'branched';
+    readonly branch: string;
+    /**
+     * Receipt-owned effect evidence (DR-045): the branching call's
+     * `unchanged` receipt observes the commit the branch was created from
+     * as HEAD, so the linked runtime injects it and never takes it from
+     * Coder's prose.
+     */
+    readonly baseRevision: string;
+    readonly issueSummary: string;
+} | {
+    readonly guard: 'refused';
+    readonly coderOutput: string;
+} | {
+    readonly guard: 'needsBossReply';
+    readonly question: string;
+};
+export type BranchPlaybookOutput = {
+    readonly status: 'branched';
+    /** Exact name of the new branch now checked out. */
+    readonly branch: string;
+    /** Exact receipt-observed revision the branch was created from. */
+    readonly baseRevision: string;
+    /** Coder's concise summary of the issue and its comments, or of the request. */
+    readonly issueSummary: string;
+} | {
+    readonly status: 'refused';
+    /** Coder's complete report carrying the reason no branch was created. */
+    readonly coderOutput: string;
+};
+export type BranchInput = Readonly<Record<string, never>>;
+export type BranchContext = {
+    readonly callerInput?: string;
+    readonly branch?: string;
+    /** Observed HEAD of the branching call's unchanged receipt (DR-045). */
+    readonly baseRevision?: string;
+    readonly issueSummary?: string;
+    readonly coderOutput?: string;
+    readonly completion?: 'branched' | 'refused';
+    readonly lastError?: unknown;
+    readonly pendingBossQuestion?: PendingBossQuestion;
+    readonly bossReply?: string;
+};
+export type BranchEvent = {
+    readonly type: 'START_BRANCH';
+    readonly callerInput: string;
+} | {
+    readonly type: 'BOSS_REPLY';
+    readonly answer: string;
+    readonly questionId?: 'createBranch';
+};
+export declare const branchMachine: import("xstate").StateMachine<BranchContext, {
+    readonly type: "START_BRANCH";
+    readonly callerInput: string;
+} | {
+    readonly type: "BOSS_REPLY";
+    readonly answer: string;
+    readonly questionId?: "createBranch";
+}, {
+    [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: "playbook.acceptedOutcome";
+    params: {
+        readonly source: string;
+        readonly target: string;
+        readonly acceptedOutcome: string;
+    };
+} | {
+    type: "rememberActorError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberPendingQuestion";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBossReply";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberEmptyBossReplyError";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberMalformedPlayerOutput";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "startBranch";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberBranched";
+    params: import("xstate").NonReducibleUnknown;
+} | {
+    type: "rememberRefused";
+    params: import("xstate").NonReducibleUnknown;
+}, {
+    type: "needsBossReply";
+    params: unknown;
+} | {
+    type: "emptyBossReply";
+    params: unknown;
+} | {
+    type: "isBranched";
+    params: unknown;
+} | {
+    type: "isRefused";
+    params: unknown;
+} | {
+    type: "resumesCreateBranch";
+    params: unknown;
+}, never, "failed" | "awaitBossReply" | "ready" | "refused" | "createBranch" | "branched", string, Readonly<Record<string, never>>, {
+    readonly status: "branched";
+    /** Exact name of the new branch now checked out. */
+    readonly branch: string;
+    /** Exact receipt-observed revision the branch was created from. */
+    readonly baseRevision: string;
+    /** Coder's concise summary of the issue and its comments, or of the request. */
+    readonly issueSummary: string;
+} | {
+    readonly status: "refused";
+    /** Coder's complete report carrying the reason no branch was created. */
+    readonly coderOutput: string;
+}, import("xstate").EventObject, import("xstate").MetaObject, {
+    id: "branch";
+    states: {
+        readonly ready: {
+            id: "ready";
+        };
+        readonly createBranch: {
+            id: "createBranch";
+        };
+        readonly awaitBossReply: {
+            id: "awaitBossReply";
+        };
+        readonly failed: {
+            id: "failed";
+        };
+        readonly branched: {
+            id: "branched";
+        };
+        readonly refused: {
+            id: "refused";
+        };
+    };
+}>;
+export default branchMachine;