@sublang/playbook 18.0.1 → 18.1.0

package/README.md

@@ -32,8 +32,9 @@ Run `playbook` for an interactive tmux UI powered by [cligent](https://github.co
 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, **PR** for publishing, checking, and merging that branch through a pull request, and **INSPECT** for explaining supplied material or a running interface without changing the repository.
 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 selects one adapter for the Captain and all players
-from locally visible credentials: Claude first, then Codex. If neither is
+The shared starter config selects the Captain's and players' adapter from
+locally visible credentials: Claude first, then Codex, and where both are
+configured only `dev.reviewer` seeds on Codex. If neither is
 configured, it seeds Claude and prints a notice. CODE, REVIEW, DECIDE, BRANCH, and PR bind
 their local roles explicitly to `dev.coder` and `dev.reviewer`, so nested and later
 engagements share a conversation only where their bindings name the same
@@ -51,7 +52,7 @@ If an SDK is missing or older than cligent supports, Playbook prints the pinned
 Prerequisites:
 
 - Node.js >= 20.6.0
-- Credentials for the configured adapter: authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY` for Claude; authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY` for Codex
+- Credentials for the configured adapter: authenticated [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview) or `ANTHROPIC_API_KEY` / `CLAUDE_CODE_OAUTH_TOKEN` for Claude; authenticated [Codex CLI](https://github.com/openai/codex) or `OPENAI_API_KEY` / `CODEX_ACCESS_TOKEN` for Codex
 - [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/configuration.md

@@ -64,16 +64,23 @@ one; see [Modules supplied at launch](#modules-supplied-at-launch). Every
 manifest role must be present exactly once. The launcher injects the rest — you do not write host wiring by
 hand.
 
-The launcher seeds one adapter for the Captain and all stable players from
-locally visible credentials: Claude first, then Codex. It uses Claude Opus 5.5
-for Claude or GPT-6 Sol for Codex, with Captain and Coder at `high` effort
-and Reviewer and Analyst at `xhigh`. If neither adapter is configured, it
-seeds Claude and prints a notice. Credentials do not prove SDK availability
-or remaining quota; launch still checks the configured adapter. Existing
-configs are left unchanged.
+The launcher seeds the Captain and all stable players from locally visible
+credentials (an API key in the environment, or `~/.claude` / `~/.codex`):
 
-The Claude default is shown below. A Codex seed also adds
-`permissions.writablePaths: ['.git']` to each agent:
+| Credentials | Seeded agents |
+| --- | --- |
+| Claude only, or neither | every agent on Claude Opus 5.5 (with a notice when neither is configured) |
+| Codex only | every agent on GPT-6 Sol |
+| both | `dev.reviewer` on GPT-6 Sol, every other agent on Claude Opus 5.5 |
+
+Captain, Coder, and Inspector run at `high` effort and Reviewer and Analyst at
+`xhigh`. Credentials do not prove SDK availability or remaining quota; launch
+still checks the configured adapter. Existing configs are left unchanged.
+Embedding hosts seed the same agent settings through
+`seedConfigText({ env, homeDir })` from `@sublang/playbook/seed-config`.
+
+The Claude default is shown below. Each Codex agent also carries
+`permissions.writablePaths: ['.git']`:
 
 ```yaml
 captain:
@@ -273,9 +280,12 @@ It may not finish the specialist’s task or invent a decision; discarding work
 Preparation has a 150-second limit.
 
 Adapter readiness is intentionally light: `claude` is ready with local
-Claude Code auth or `ANTHROPIC_API_KEY`; `codex` with local Codex CLI
-auth or `OPENAI_API_KEY`. A known adapter that is not ready blocks the
-launch and prints the help text.
+Claude Code auth, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, or
+`CLAUDE_CODE_OAUTH_TOKEN`; `codex` with local Codex CLI auth,
+`OPENAI_API_KEY`, `CODEX_API_KEY`, or `CODEX_ACCESS_TOKEN`. Only presence
+counts; no token is checked. A known adapter that is not ready blocks the
+launch and prints the help text. The same check picks the starter config's
+lineup.
 
 ## Skills across agents
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "18.0.1",
+  "version": "18.1.0",
   "type": "module",
   "description": "Composable XState v5 playbook runtime with compiled Captain, CODE, REVIEW, DECIDE, DEV, BRANCH, PR, and INSPECT workflows driven by GEARS specs.",
   "license": "Apache-2.0",
@@ -83,6 +83,8 @@
     "reference/sdlc/code.playbook/host-capabilities.d.ts",
     "reference/sdlc/code.playbook/machine-identity.js",
     "reference/sdlc/code.playbook/machine-identity.d.ts",
+    "reference/sdlc/code.playbook/seed-config.js",
+    "reference/sdlc/code.playbook/seed-config.d.ts",
     "reference/sdlc/code.playbook/code.gears.md",
     "reference/sdlc/code.playbook/playbook.config.template.yaml",
     "reference/sdlc/code.playbook/bin/playbook.js",
@@ -212,6 +214,10 @@
       "types": "./reference/sdlc/code.playbook/machine-identity.d.ts",
       "default": "./reference/sdlc/code.playbook/machine-identity.js"
     },
+    "./seed-config": {
+      "types": "./reference/sdlc/code.playbook/seed-config.d.ts",
+      "default": "./reference/sdlc/code.playbook/seed-config.js"
+    },
     "./slc/*": "./slc/*",
     "./review/playbook": {
       "types": "./reference/sdlc/review.playbook/review.playbook.d.ts",

package/reference/sdlc/code.playbook/bin/launch-config.js

@@ -1438,23 +1438,36 @@ export function adaptersFromComposedConfig(config) {
   return [...adapters];
 }
 
+// DR-097: each agent's documented environment forms, any one of which, or the
+// agent's sign-in folder, counts it as ready. No value is read.
+const CREDENTIAL_FORMS = {
+  claude: {
+    names: ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN"],
+    folder: ".claude",
+  },
+  codex: {
+    names: ["OPENAI_API_KEY", "CODEX_API_KEY", "CODEX_ACCESS_TOKEN"],
+    folder: ".codex",
+  },
+};
+
 export function checkReadiness(adapters, env = process.env, home = homedir()) {
   const failingAdapters = [];
   const unknownAdapters = [];
   for (const adapter of adapters) {
-    if (adapter === "claude") {
-      if (!env.ANTHROPIC_API_KEY && !existsSync(join(home, ".claude"))) {
-        failingAdapters.push(adapter);
-      }
+    const forms = Object.hasOwn(CREDENTIAL_FORMS, adapter)
+      ? CREDENTIAL_FORMS[adapter]
+      : undefined;
+    if (!forms) {
+      unknownAdapters.push(adapter);
       continue;
     }
-    if (adapter === "codex") {
-      if (!env.OPENAI_API_KEY && !existsSync(join(home, ".codex"))) {
-        failingAdapters.push(adapter);
-      }
-      continue;
+    if (
+      !forms.names.some((name) => env[name]) &&
+      !existsSync(join(home, forms.folder))
+    ) {
+      failingAdapters.push(adapter);
     }
-    unknownAdapters.push(adapter);
   }
   return { failingAdapters, unknownAdapters };
 }
@@ -1651,9 +1664,14 @@ const SEED_LINEUP = Object.freeze([
   Object.freeze({ adapter: "codex", model: "gpt-6-sol" }),
 ]);
 
+// DR-096: where both adapters are ready, this player alone takes the
+// second row, so review comes from a different provider than the work.
+const SECOND_ADAPTER_PLAYER = "dev.reviewer";
+
 /**
  * PBCLI-11: the lineup a seed would write here, and whether anything
- * actually probed ready.
+ * actually probed ready. `reviewer` is the row `dev.reviewer` takes;
+ * every other agent takes `lineup`.
  *
  * Only the credential check participates. The SDK probe constructs an
  * adapter and awaits `isAvailable()`, which reads whatever happens to
@@ -1666,7 +1684,12 @@ export function selectSeedLineup(env = process.env, home = homedir()) {
     (entry) =>
       checkReadiness([entry.adapter], env, home).failingAdapters.length === 0,
   );
-  return { lineup: ready[0] ?? SEED_LINEUP[0], anyReady: ready.length > 0 };
+  const lineup = ready[0] ?? SEED_LINEUP[0];
+  return {
+    lineup,
+    reviewer: ready.length > 1 ? ready[1] : lineup,
+    anyReady: ready.length > 0,
+  };
 }
 
 /**
@@ -1675,9 +1698,7 @@ export function selectSeedLineup(env = process.env, home = homedir()) {
  * byte copy it always was. A different adapter rewrites the agent
  * scalars in place, which the Document API carries comments through.
  */
-function seedTextForLineup(templatePath, lineup) {
-  const template = readFileSync(templatePath, "utf8");
-  if (lineup.adapter === SEED_LINEUP[0].adapter) return template;
+function seedTextForLineup(template, { lineup, reviewer }) {
   const doc = parseYamlDocument(template);
   const players = doc.getIn(["players"]);
   const agentPaths = [
@@ -1687,18 +1708,35 @@ function seedTextForLineup(templatePath, lineup) {
       String(pair.key),
     ]),
   ];
+  let changed = false;
   for (const path of agentPaths) {
-    doc.setIn([...path, "adapter"], lineup.adapter);
-    doc.setIn([...path, "model"], lineup.model);
+    const entry = path[1] === SECOND_ADAPTER_PLAYER ? reviewer : lineup;
+    if (entry.adapter === SEED_LINEUP[0].adapter) continue;
+    changed = true;
+    doc.setIn([...path, "adapter"], entry.adapter);
+    doc.setIn([...path, "model"], entry.model);
     // A codex agent writes git metadata under its sandbox; claude's
     // auto mode needs no grant, so the key exists for one adapter only.
-    if (lineup.adapter === "codex") {
-      doc.setIn([...path, "permissions", "writablePaths"], [".git"]);
-    } else {
-      doc.deleteIn([...path, "permissions", "writablePaths"]);
-    }
+    doc.setIn([...path, "permissions", "writablePaths"], [".git"]);
   }
-  return String(doc);
+  return changed ? String(doc) : template;
+}
+
+/**
+ * PBCLI-100: the starter text a seed writes under this environment and
+ * home. The public `seed-config` facade and the launcher both call it,
+ * so every host seeding through it selects the same agent settings.
+ */
+export function seedConfigText(
+  templatePath,
+  env = process.env,
+  homeDir = env.HOME ?? homedir(),
+) {
+  const selection = selectSeedLineup(env, homeDir);
+  return {
+    text: seedTextForLineup(readFileSync(templatePath, "utf8"), selection),
+    anyReady: selection.anyReady,
+  };
 }
 
 function seedUserConfigIfMissing(
@@ -1710,21 +1748,13 @@ function seedUserConfigIfMissing(
 ) {
   if (existsSync(userConfigPath)) return;
   mkdirSync(dirname(userConfigPath), { recursive: true });
-  const { lineup, anyReady } = selectSeedLineup(env, homeDir);
-  if (lineup.adapter === SEED_LINEUP[0].adapter && anyReady) {
-    // Unchanged default path: one exclusive create of the template bytes.
-    copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
-  } else {
-    // Still one exclusive create, so two seeding calls cannot disagree.
-    writeFileSync(userConfigPath, seedTextForLineup(templatePath, lineup), {
-      encoding: "utf8",
-      flag: "wx",
-    });
-  }
+  const { text, anyReady } = seedConfigText(templatePath, env, homeDir);
+  // One exclusive create, so two seeding calls cannot disagree.
+  writeFileSync(userConfigPath, text, { encoding: "utf8", flag: "wx" });
   onNotice(`playbook: created config at ${userConfigPath}\n`);
   if (!anyReady) {
     onNotice(
-      `playbook: no adapter probed ready; seeded ${lineup.adapter}\n`,
+      `playbook: no adapter probed ready; seeded ${SEED_LINEUP[0].adapter}\n`,
     );
   }
 }

package/reference/sdlc/code.playbook/bin/playbook.js

@@ -993,9 +993,9 @@ function helpText({
     "",
     "Adapter setup:",
     "  claude: npm install -g @anthropic-ai/claude-agent-sdk, then run",
-    "    Claude Code once or set ANTHROPIC_API_KEY.",
+    "    Claude Code once or set ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN).",
     "  codex: npm install -g @openai/codex-sdk, then run Codex CLI once",
-    "    or set OPENAI_API_KEY.",
+    "    or set OPENAI_API_KEY (or CODEX_API_KEY, CODEX_ACCESS_TOKEN).",
     "  Each SDK is an optional peer dependency, so you install only the",
     "  vendors your config actually names.",
     "",

package/reference/sdlc/code.playbook/seed-config.d.ts

@@ -0,0 +1,12 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+export interface SeedConfigOptions {
+  readonly env?: NodeJS.ProcessEnv;
+  readonly homeDir?: string;
+}
+export interface SeedConfigText {
+  readonly text: string;
+  readonly anyReady: boolean;
+}
+export declare function seedConfigText(options?: SeedConfigOptions): SeedConfigText;

package/reference/sdlc/code.playbook/seed-config.js

@@ -0,0 +1,22 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+
+// DR-096: the public `@sublang/playbook/seed-config` facade. The text is
+// the launcher's own seed (playbook-cli-11); this module only fixes the
+// bundled template and narrows the accepted options (playbook-cli-100).
+
+import { fileURLToPath } from 'node:url';
+import { seedConfigText as seedText } from './bin/launch-config.js';
+
+const TEMPLATE_PATH = fileURLToPath(
+  new URL('./playbook.config.template.yaml', import.meta.url),
+);
+
+export function seedConfigText(options = {}) {
+  const env = options.env ?? process.env;
+  return seedText(
+    TEMPLATE_PATH,
+    env,
+    ...(options.homeDir !== undefined ? [options.homeDir] : []),
+  );
+}