@sublang/playbook 0.2.0 → 0.4.0

package/README.md

@@ -43,33 +43,95 @@ the slc pipeline's `<basename>.<pipeline>/` output directory.
 
 ### Install (users)
 
-Install the package globally. The bundled production config wires
-Anthropic (Captain + Coder) and OpenAI Codex (Reviewer); `@sublang/
-cligent`, the two adapter SDKs, and `xstate` are all direct
-dependencies, so a single install pulls in everything:
+Install the package globally. `@sublang/cligent`, the Claude and
+Codex adapter SDKs, and `xstate` are direct dependencies, so a single
+install pulls in the reference CODE playbook and its host:
 
 ```sh
 npm install -g @sublang/playbook
 ```
 
-Each adapter reads its own auth: the Claude SDK uses your local
-Claude Code auth (or `ANTHROPIC_API_KEY`); the Codex SDK uses your
-local codex CLI auth (or `OPENAI_API_KEY`).
+Then launch the reference playbook in a `tmux-play` session:
+
+```sh
+playbook-code
+```
+
+For a one-shot run without a global install, use the same command
+through npx:
+
+```sh
+npx playbook-code
+```
+
+On first run, `playbook-code` creates a commented user config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml`
+from the bundled template, prints that path to stderr, then checks the
+declared adapters before launching. Later runs reuse that file and do
+not overwrite it.
+
+Known adapter readiness is intentionally light: `claude` is ready when
+local Claude Code auth exists or `ANTHROPIC_API_KEY` is set; `codex` is
+ready when local Codex CLI auth exists or `OPENAI_API_KEY` is set. If a
+known adapter is not ready, `playbook-code` prints its own help text
+with the config path, auth pointers, and agent-swap recipe, then exits
+without launching. You can view the same recovery text at any time:
 
-The bundled configs run each agent in cligent's protected auto mode
+```sh
+playbook-code --help
+```
+
+The seed template runs each agent in cligent's protected auto mode
 (`permissions.mode: auto`), suppressing routine approval prompts.
 
-Then launch the reference playbook in a `tmux-play` session:
+### Configure agents
+
+Edit the seeded user config when you want different coding agents:
 
 ```sh
-playbook-code
+$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml"
 ```
 
-The `playbook-code` bin resolves the bundled
-`tmux-play.production.config.yaml` and execs the bundled `tmux-play`
-CLI (from playbook's own `node_modules/@sublang/cligent`) against it;
-any extra flags pass through (`playbook-code --help` lists
-`tmux-play`'s).
+Both CODE players can use `claude` or `codex`; other adapter ids are
+passed through to `tmux-play` with a warning because `playbook-code`
+does not know how to preflight their auth. The safe tuning points are
+`captain.adapter`, `captain.model`, and each player's `adapter`. Keep
+`captain.from` and the `players[].id` values fixed; the runtime binds
+to those host-configuration invariants per
+[PBRT-4](specs/user/playbook-runtime.md#pbrt-4) and derives the
+`<coder-llm>` / `<reviewer-llm>` substitution strings from each
+player entry's `adapter`.
+
+For example, this swaps the Coder to Codex and the Reviewer to Claude:
+
+```yaml
+captain:
+  from: "@sublang/playbook/code/tmux-play"
+  adapter: claude
+  model: claude-opus-4-7
+  permissions:
+    mode: auto
+
+players:
+  - id: coder      # must stay `coder` — see PBRT-4
+    adapter: codex
+    permissions:
+      mode: auto
+  - id: reviewer   # must stay `reviewer` — see PBRT-4
+    adapter: claude
+    permissions:
+      mode: auto
+```
+
+Normal `playbook-code` runs use the seeded path above. If you need a
+separate config file for a one-off run, pass it explicitly; this bypasses
+the seed and readiness gate and forwards the arguments to `tmux-play`
+verbatim, as pinned in
+[PBCODE-1](specs/user/playbook-code.md#pbcode-1):
+
+```sh
+playbook-code --config ./playbook-code.config.yaml
+```
 
 ### Install (contributors / from source)
 
@@ -83,7 +145,7 @@ pnpm build
 pnpm test
 ```
 
-`pnpm install` resolves `@sublang/cligent` (^0.4.0) from the registry;
+`pnpm install` resolves `@sublang/cligent` (^0.6.0) from the registry;
 no local link required. To point pnpm at a local `cligent` checkout
 instead, copy
 [`pnpm-workspace.yaml.example`](pnpm-workspace.yaml.example)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and tmux-play adapter for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
@@ -40,6 +40,7 @@
     "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"
   ],
   "bin": {
@@ -66,7 +67,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.130.0",
-    "@sublang/cligent": "^0.4.0",
+    "@sublang/cligent": "^0.6.0",
     "xstate": "^5.19.4"
   },
   "devDependencies": {

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

@@ -2,42 +2,277 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
-// Thin shim that resolves the bundled tmux-play.production.config.yaml
-// relative to this script's own location and execs cligent's tmux-play
-// CLI from inside @sublang/playbook's own node_modules tree. We resolve
-// the CLI through cligent's `./tmux-play` subpath export instead of
-// relying on `tmux-play` being on PATH — npm global installs only link
-// bins from top-level packages, so a transitive cligent's bin won't
-// reach the user's PATH but its files are still resolvable here.
-
 import { spawn } from 'node:child_process';
+import {
+  constants,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const here = dirname(fileURLToPath(import.meta.url));
-const configPath = resolve(here, '..', 'tmux-play.production.config.yaml');
-
-// cligent's `./tmux-play` subpath export only declares "import"
-// (no "require"/"default"), so createRequire(...).resolve trips
-// ERR_PACKAGE_PATH_NOT_EXPORTED. import.meta.resolve uses ESM rules
-// and follows the "import" condition — works from Node 20.6+.
-const tmuxPlayIndexUrl = import.meta.resolve('@sublang/cligent/tmux-play');
-const tmuxPlayBin = join(dirname(fileURLToPath(tmuxPlayIndexUrl)), 'cli.js');
-
-const child = spawn(
-  process.execPath,
-  [tmuxPlayBin, '--config', configPath, ...process.argv.slice(2)],
-  { stdio: 'inherit' },
-);
-
-child.on('error', (err) => {
-  process.stderr.write(
-    `playbook-code: failed to launch tmux-play (${tmuxPlayBin}): ${err.message}\n`,
-  );
-  process.exit(127);
-});
-
-child.on('exit', (code, signal) => {
-  if (signal) process.kill(process.pid, signal);
-  else process.exit(code ?? 0);
-});
+const templatePath = resolve(here, '..', 'playbook-code.config.template.yaml');
+const READINESS_FAILURE_EXIT_CODE = 2;
+
+export async function runPlaybookCodeCli(options = {}) {
+  const argv = [...(options.argv ?? process.argv.slice(2))];
+  const env = options.env ?? process.env;
+  const stdout = options.stdout ?? process.stdout;
+  const stderr = options.stderr ?? process.stderr;
+  const spawnFn = options.spawn ?? spawn;
+  const tmuxPlayBin = options.tmuxPlayBin ?? resolveTmuxPlayBin();
+  const home = options.homeDir ?? env.HOME ?? homedir();
+  const userConfigPath = resolveUserConfigPath(env, home);
+
+  if (argv.includes('--help') || argv.includes('-h')) {
+    stdout.write(helpText({ userConfigPath }));
+    return { code: 0 };
+  }
+
+  const explicitConfig = hasExplicitConfig(argv);
+  const configPath = explicitConfig ? undefined : userConfigPath;
+
+  if (!explicitConfig) {
+    seedUserConfigIfMissing(userConfigPath, stderr);
+    const readiness = checkReadiness(userConfigPath, env, home);
+    for (const adapter of readiness.unknownAdapters) {
+      stderr.write(
+        `playbook-code: warning: no readiness check for adapter "${adapter}"\n`,
+      );
+    }
+    if (readiness.failingAdapters.length > 0) {
+      stderr.write(
+        helpText({
+          userConfigPath,
+          failingAdapters: readiness.failingAdapters,
+        }),
+      );
+      return { code: READINESS_FAILURE_EXIT_CODE };
+    }
+  }
+
+  const childArgs = explicitConfig
+    ? [tmuxPlayBin, ...argv]
+    : [tmuxPlayBin, '--config', configPath, ...argv];
+  return await launchTmuxPlay(spawnFn, childArgs, stderr);
+}
+
+export function resolveUserConfigPath(env = process.env, home = homedir()) {
+  const configHome = env.XDG_CONFIG_HOME || join(home, '.config');
+  return join(configHome, 'playbook', 'playbook-code.config.yaml');
+}
+
+export function collectAdaptersFromConfig(source) {
+  const adapters = new Set();
+  let section = '';
+  let captainChildIndent;
+  let playerItemIndent;
+  let playerChildIndent;
+
+  for (const line of source.split(/\r?\n/)) {
+    const uncommented = stripYamlComment(line);
+    if (uncommented.trim() === '') continue;
+
+    const indent = leadingSpaceCount(uncommented);
+    const trimmed = uncommented.trim();
+
+    if (indent === 0) {
+      if (trimmed === 'captain:') section = 'captain';
+      else if (trimmed === 'players:') section = 'players';
+      else section = '';
+      captainChildIndent = undefined;
+      playerItemIndent = undefined;
+      playerChildIndent = undefined;
+      continue;
+    }
+
+    if (section === 'captain') {
+      captainChildIndent ??= indent;
+      if (indent === captainChildIndent) {
+        collectAdapterValue(trimmed, adapters);
+      }
+      continue;
+    }
+
+    if (section === 'players') {
+      if (trimmed.startsWith('- ')) {
+        playerItemIndent = indent;
+        playerChildIndent = undefined;
+        collectAdapterValue(trimmed.slice(2).trim(), adapters);
+        continue;
+      }
+      if (playerItemIndent !== undefined && indent > playerItemIndent) {
+        playerChildIndent ??= indent;
+        if (indent === playerChildIndent) {
+          collectAdapterValue(trimmed, adapters);
+        }
+      }
+    }
+  }
+  return [...adapters];
+}
+
+export function checkReadiness(configPath, env = process.env, home = homedir()) {
+  const config = readFileSync(configPath, 'utf8');
+  const adapters = collectAdaptersFromConfig(config);
+  const failingAdapters = [];
+  const unknownAdapters = [];
+
+  for (const adapter of adapters) {
+    if (adapter === 'claude') {
+      if (!env.ANTHROPIC_API_KEY && !existsSync(join(home, '.claude'))) {
+        failingAdapters.push(adapter);
+      }
+      continue;
+    }
+    if (adapter === 'codex') {
+      if (!env.OPENAI_API_KEY && !existsSync(join(home, '.codex'))) {
+        failingAdapters.push(adapter);
+      }
+      continue;
+    }
+    unknownAdapters.push(adapter);
+  }
+
+  return { failingAdapters, unknownAdapters };
+}
+
+function seedUserConfigIfMissing(userConfigPath, stderr) {
+  if (existsSync(userConfigPath)) return;
+  mkdirSync(dirname(userConfigPath), { recursive: true });
+  copyFileSync(templatePath, userConfigPath, constants.COPYFILE_EXCL);
+  stderr.write(`playbook-code: created config at ${userConfigPath}\n`);
+}
+
+function hasExplicitConfig(argv) {
+  return argv.some((arg) => arg === '--config' || arg.startsWith('--config='));
+}
+
+function helpText({ userConfigPath, failingAdapters = [] }) {
+  const failures =
+    failingAdapters.length > 0
+      ? [
+          `Adapters not ready: ${failingAdapters.join(', ')}`,
+          '',
+        ]
+      : [];
+  return [
+    ...failures,
+    'Usage:',
+    '  playbook-code [--config <path>] [tmux-play options]',
+    '  playbook-code --help',
+    '',
+    `Default config: ${userConfigPath}`,
+    '',
+    'Adapter setup:',
+    '  claude: run Claude Code once or set ANTHROPIC_API_KEY.',
+    '  codex: run Codex CLI once or set OPENAI_API_KEY.',
+    '',
+    'Agent swap recipe:',
+    '  - change captain.adapter and captain.model for the Captain/Judge',
+    '  - change each player adapter for the Coder and Reviewer',
+    '  - keep captain.from and players[].id fixed',
+    '',
+  ].join('\n');
+}
+
+async function launchTmuxPlay(spawnFn, childArgs, stderr) {
+  return await new Promise((resolveResult) => {
+    let child;
+    try {
+      child = spawnFn(process.execPath, childArgs, { stdio: 'inherit' });
+    } catch (error) {
+      stderr.write(`playbook-code: failed to launch tmux-play: ${errorMessage(error)}\n`);
+      resolveResult({ code: 127 });
+      return;
+    }
+
+    let settled = false;
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      resolveResult(result);
+    };
+
+    child.on('error', (err) => {
+      stderr.write(
+        `playbook-code: failed to launch tmux-play: ${errorMessage(err)}\n`,
+      );
+      settle({ code: 127 });
+    });
+
+    child.on('exit', (code, signal) => {
+      if (signal) settle({ signal });
+      else settle({ code: code ?? 0 });
+    });
+  });
+}
+
+function resolveTmuxPlayBin() {
+  const tmuxPlayIndexUrl = import.meta.resolve('@sublang/cligent/tmux-play');
+  return join(dirname(fileURLToPath(tmuxPlayIndexUrl)), 'cli.js');
+}
+
+function stripYamlComment(line) {
+  let quote = '';
+  for (let index = 0; index < line.length; index += 1) {
+    const char = line[index];
+    if ((char === '"' || char === "'") && line[index - 1] !== '\\') {
+      quote = quote === char ? '' : quote || char;
+      continue;
+    }
+    if (char === '#' && !quote) {
+      return line.slice(0, index);
+    }
+  }
+  return line;
+}
+
+function unquoteYamlScalar(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1).trim();
+  }
+  return trimmed;
+}
+
+function collectAdapterValue(trimmedLine, adapters) {
+  const match = trimmedLine.match(/^adapter\s*:\s*(.+?)\s*$/);
+  if (!match) return;
+  const value = unquoteYamlScalar(match[1].trim());
+  if (value) adapters.add(value);
+}
+
+function leadingSpaceCount(line) {
+  return line.length - line.trimStart().length;
+}
+
+function errorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isCliEntry(
+  argv1 = process.argv[1],
+  moduleUrl = import.meta.url,
+) {
+  if (!argv1) return false;
+  try {
+    return realpathSync(argv1) === realpathSync(fileURLToPath(moduleUrl));
+  } catch {
+    return false;
+  }
+}
+
+if (isCliEntry()) {
+  const result = await runPlaybookCodeCli();
+  if (result.signal) process.kill(process.pid, result.signal);
+  else process.exit(result.code ?? 0);
+}

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

@@ -113,7 +113,7 @@ const planAndImplementInput = (context) => ({
     prompt: [
         'Assess whether this can be completed in a single commit, following best practices.',
         'If yes, implement and test, updating both code and specs; otherwise, decompose into tasks as a new IR under @specs/iterations.',
-        'Consult @specs/map.md for relevant context if needed; ensure it reflects the changes.',
+        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; ensure @specs/map.md reflects the changes.',
         'Do not commit.',
     ].join('\n'),
     result: withNeedsBossReply({
@@ -501,7 +501,7 @@ export const codingMachine = setup({
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -538,7 +538,7 @@ export const codingMachine = setup({
                         'Refer to the commit message.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -582,7 +582,7 @@ export const codingMachine = setup({
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -625,7 +625,7 @@ export const codingMachine = setup({
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -663,7 +663,7 @@ export const codingMachine = setup({
                         'Refer to the commit message.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -708,7 +708,7 @@ export const codingMachine = setup({
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -749,7 +749,7 @@ export const codingMachine = setup({
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -787,7 +787,7 @@ export const codingMachine = setup({
                         'Understand the intent.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -832,7 +832,7 @@ export const codingMachine = setup({
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                     ].join('\n'),
                     result: {
@@ -877,7 +877,7 @@ export const codingMachine = setup({
                         '- Minimal: essential and concise; every item earns its place; also check with other items.',
                         '',
                         'Flag anything missing, redundant, over-specified, or under-specified.',
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                         'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
                     ].join('\n'),
@@ -918,7 +918,7 @@ export const codingMachine = setup({
                         'Understand the intent.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                         'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
                     ].join('\n'),
@@ -966,7 +966,7 @@ export const codingMachine = setup({
                         'Flag anything missing, redundant, over-specified, or under-specified.',
                         'Flag any issues or improvements (numbered; no duplication).',
                         "Think thoroughly — don't just approve or reject.",
-                        'Consult @specs/map.md for relevant context if needed; verify it reflects the changes.',
+                        'Consult @specs/map.md or @specs/meta.md for relevant context if needed; verify @specs/map.md reflects the changes.',
                         "If the change is ready to commit or push, don't raise nitpicks.",
                         'For each rebuttal below, challenge or accept it, with strong reasoning, solid evidence, and comprehensive thinking.',
                     ].join('\n'),