@sublang/playbook 0.7.0 → 0.9.0

package/README.md

@@ -55,79 +55,93 @@ npm install -g @sublang/playbook
 Then launch the reference playbook in a `tmux-play` session:
 
 ```sh
-playbook-code
+playbook
 ```
 
-For a one-shot run without a global install, use the same command
-through npx:
+For a one-shot run without a global install, invoke the scoped
+package through npx (it runs the package's `playbook` bin):
 
 ```sh
-npx playbook-code
+npx @sublang/playbook
 ```
 
-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.
+On first run, `playbook` creates a commented user config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`
+from the bundled starter, prints that path to stderr, then composes a
+`tmux-play` config and 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:
+known adapter is not ready, `playbook` 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:
 
 ```sh
-playbook-code --help
+playbook --help
 ```
 
-The seed template runs each agent in cligent's protected auto mode
-(`permissions.mode: auto`), suppressing routine approval prompts. Its
-Codex Coder also grants `permissions.writablePaths: [.git]` so git
-metadata writes stay available under auto mode without switching to
-bypass permissions.
+`playbook --list` prints the configured playbooks with their slash
+commands and intents. Every seeded agent — the Captain and both roles —
+runs in cligent's protected auto mode (`permissions.mode: auto`), so
+routine in-session approval prompts are suppressed without switching to
+bypass permissions. The seeded Codex Reviewer additionally grants
+`permissions.writablePaths: [.git]` so git metadata writes stay
+available under the Codex sandbox; the Claude agents need no such grant
+under their auto mode.
 
 ### Configure agents
 
 Edit the seeded user config when you want different coding agents:
 
 ```sh
-$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook-code.config.yaml"
+$EDITOR "${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml"
 ```
 
-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 role's `adapter` and
-`model` under `players.coder` / `players.reviewer`. The composer owns
-`captain.from` and points it at the Playbook Captain shell adapter, and
-it owns the `coder` / `reviewer` role keys, so leave those keys as-is;
-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 role's
-`model` when pinned and `adapter` otherwise — so the Committer's
+The config is top-level (no `config:` wrapper): a `profiles` map of
+reusable agent settings, a `captain` Judge agent, optional `layout` /
+`notifications` / `theme`, and a `playbooks` map of enabled playbooks. Each
+`captain` or `players.<role>` value is a profile id or an adapter
+shorthand (`claude`, `codex`); other adapter ids are passed through to
+`tmux-play` with a warning because `playbook` cannot preflight their
+auth. Name profiles by their underlying agent/model (e.g. `claude-opus`,
+`codex-gpt`) so the profile ids read distinctly from the `coder` /
+`reviewer` player roles that reference them. Within a `playbooks.<id>` block, `from` (the registry module),
+`command` (an optional slash-command override), and `players` are
+launcher-owned; every other key (e.g. CODE's `committer`) is that
+playbook's option slice. The launcher injects `captain.from` and the
+namespaced `<id>-<role>` host players, so you do not write those by
+hand.
+
+CODE's per-run `<coder-llm>` / `<reviewer-llm>` prompt strings come from
+each role's pinned `model`, else its `adapter`
+([PBRT-4](specs/user/playbook-runtime.md#pbrt-4)) — so the Committer's
 commit-message trailers can name the concrete model
-(e.g. `claude-opus-4-8`) rather than the adapter family (`claude`).
-
-`players.committer` is an optional alias naming which role — `coder`
-or `reviewer` — runs the commit turn; the seeded overlay points it at
-the Reviewer. Absent the alias the Committer falls back to the Coder
+(e.g. `claude-opus-4-8[1m]`) rather than the adapter family (`claude`).
+`committer` is an optional CODE alias naming which role — `coder` or
+`reviewer` — runs the commit turn; the seeded config points it at the
+Coder, and absent the alias the Committer falls back to the Coder
 ([PBRT-8](specs/user/playbook-runtime.md#pbrt-8)).
 
-For example, the seeded overlay runs the Coder on Codex and the
-Reviewer on Claude, with the Committer aliased to the Reviewer:
+For example, the seeded config runs the Coder on Claude Opus 4.8 1m and
+the Reviewer on GPT-5.5, with the Committer aliased to the Coder:
 
 ```yaml
-captain:
-  adapter: claude
-  model: claude-sonnet-4-6
-  reasoningEffort: high
-  permissions:
-    mode: auto
-
-players:
-  coder:              # role key must stay `coder` — see PBRT-4
+profiles:
+  claude-opus:
+    adapter: claude
+    model: claude-opus-4-8
+    reasoningEffort: high
+    permissions:
+      mode: auto        # protected auto mode for the Claude Captain
+  claude-opus-1m:
+    adapter: claude
+    model: claude-opus-4-8[1m]
+    reasoningEffort: xhigh
+    permissions:
+      mode: auto        # protected auto mode for the Claude Coder
+  codex-gpt:
     adapter: codex
     model: gpt-5.5
     reasoningEffort: xhigh
@@ -135,23 +149,25 @@ players:
       mode: auto
       writablePaths:
         - .git          # allow git metadata writes under Codex auto mode
-  reviewer:           # role key must stay `reviewer` — see PBRT-4
-    adapter: claude
-    model: claude-opus-4-8
-    reasoningEffort: xhigh
-    permissions:
-      mode: auto
-  committer: reviewer   # which role commits — `coder` or `reviewer`
+
+captain: claude-opus
+
+playbooks:
+  code:
+    from: "@sublang/playbook/code/registry"
+    players:
+      coder: claude-opus-1m
+      reviewer: codex-gpt
+    committer: coder      # which role commits — `coder` or `reviewer`
 ```
 
-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):
+If you need a separate config file for a one-off run, pass a raw
+`tmux-play` config explicitly; this bypasses the seed, composition, and
+readiness gate and forwards the arguments to `tmux-play` verbatim
+([PBCLI-1](specs/user/playbook-cli.md#pbcli-1)):
 
 ```sh
-playbook-code --config ./playbook-code.config.yaml
+playbook --config ./tmux-play.config.yaml
 ```
 
 ### Install (contributors / from source)
@@ -170,8 +186,8 @@ pnpm test
 in the checked-in `pnpm-lock.yaml` — the same version CI installs
 via `--frozen-lockfile`, so contributor checkouts and CI agree.
 The published `package.json` declares `@sublang/cligent` as
-`^0.12.0`, so an end-user install with no lockfile (e.g., `npm
-install -g @sublang/playbook`) resolves a compatible cligent 0.12.x
+`^0.13.0`, so an end-user install with no lockfile (e.g., `npm
+install -g @sublang/playbook`) resolves a compatible cligent 0.13.x
 release (see [RELEASE-14](specs/dev/release.md#release-14)). To
 refresh the contributor pin within that range, run
 `pnpm update @sublang/cligent` and commit the resulting
@@ -184,17 +200,19 @@ instead, copy
 into place; the override is gitignored so it never leaks into a
 production install.
 
-Drive a Boss turn against the source tree (uses the developer
-[`tmux-play.config.yaml`](reference/sdlc/code.playbook/tmux-play.config.yaml)
-that imports the compiled Playbook Captain shell via relative path):
+Drive a Boss turn against the source tree with the launcher, which
+resolves `tmux-play`, the Playbook Captain shell, and the CODE registry
+from the local package:
 
 ```sh
-pnpm exec tmux-play --config reference/sdlc/code.playbook/tmux-play.config.yaml
+pnpm playbook
 ```
 
-`pnpm exec` resolves `tmux-play` from the package's local
-`node_modules/.bin/`, so this works whether or not `@sublang/cligent` is
-installed globally.
+On first run this seeds the generic config at
+`${XDG_CONFIG_HOME:-$HOME/.config}/playbook/playbook.config.yaml`
+(see [Configure agents](#configure-agents)) and launches the composed
+session, so this works whether or not `@sublang/cligent` is installed
+globally.
 
 ### Running a Boss turn
 
@@ -214,11 +232,12 @@ and streams the CODE state machine with the four-glyph vocabulary `◆ ▸ ⮕
 [PBRT-3](specs/user/playbook-runtime.md#pbrt-3), while player prompts
 ride their own panes.
 
-Published configs should import the shell adapter from
-`@sublang/playbook/playbook-captain`. Existing explicit configs that
-still import `@sublang/playbook/code/tmux-play` keep resolving through
-a compatibility shim that delegates to the same shell with CODE
-registered.
+Published configs import the shell adapter from
+`@sublang/playbook/playbook-captain` and enable CODE through a
+`captain.options.playbooks.code` block whose `from` is
+`@sublang/playbook/code/registry`. The generic `playbook` launcher
+composes this for you from the top-level `profiles` / `playbooks`
+config above.
 
 ### Embedding the runtime in your own host
 
@@ -307,7 +326,7 @@ package.
 
 ## Requirements
 
-- Node.js ≥ 20.6.0 (the `playbook-code` shim uses
+- Node.js ≥ 20.6.0 (the `playbook` launcher uses
   `import.meta.resolve`, unflagged since this release)
 - pnpm 9 (for the reference package)
 - A configured `tmux-play` host (for live Boss turns) — requires

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Reference CODE playbook — XState v5 FSM, host-agnostic runtime, and Playbook Captain shell for a coder/reviewer/committer loop driven by GEARS spec items.",
   "license": "Apache-2.0",
@@ -46,17 +46,12 @@
     "reference/sdlc/code.playbook/playbook-captain.ts",
     "reference/sdlc/code.playbook/playbook-captain.js",
     "reference/sdlc/code.playbook/playbook-captain.d.ts",
-    "reference/sdlc/code.playbook/code.tmux-play.ts",
-    "reference/sdlc/code.playbook/code.tmux-play.js",
-    "reference/sdlc/code.playbook/code.tmux-play.d.ts",
     "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/playbook-code.js"
+    "reference/sdlc/code.playbook/playbook.config.template.yaml",
+    "reference/sdlc/code.playbook/bin/playbook.js"
   ],
   "bin": {
-    "playbook-code": "reference/sdlc/code.playbook/bin/playbook-code.js"
+    "playbook": "reference/sdlc/code.playbook/bin/playbook.js"
   },
   "exports": {
     "./runtime": {
@@ -67,20 +62,20 @@
       "types": "./reference/sdlc/code.playbook/code.playbook.d.ts",
       "default": "./reference/sdlc/code.playbook/code.playbook.js"
     },
+    "./code/registry": {
+      "types": "./reference/sdlc/code.playbook/code.registry.d.ts",
+      "default": "./reference/sdlc/code.playbook/code.registry.js"
+    },
     "./playbook-captain": {
       "types": "./reference/sdlc/code.playbook/playbook-captain.d.ts",
       "default": "./reference/sdlc/code.playbook/playbook-captain.js"
     },
-    "./code/tmux-play": {
-      "types": "./reference/sdlc/code.playbook/code.tmux-play.d.ts",
-      "default": "./reference/sdlc/code.playbook/code.tmux-play.js"
-    },
     "./slc/*": "./slc/*"
   },
   "scripts": {
     "build": "tsc",
     "test": "vitest run",
-    "playbook-code": "node reference/sdlc/code.playbook/bin/playbook-code.js"
+    "playbook": "node reference/sdlc/code.playbook/bin/playbook.js"
   },
   "publishConfig": {
     "access": "public",
@@ -89,7 +84,7 @@
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "^0.3.143",
     "@openai/codex-sdk": "^0.139.0",
-    "@sublang/cligent": "^0.12.0",
+    "@sublang/cligent": "^0.13.0",
     "xstate": "^5.19.4",
     "yaml": "^2.9.0"
   },