@sublang/playbook 17.9.0 → 17.10.0

package/docs/configuration.md

@@ -17,7 +17,7 @@ file's directory with it when that leaves it empty, and leaves no compatibility
 alias, so running an older Spex host afterward could seed a second file at the
 path it still resolves.
 
-The current guard rejects relocation when a former relative `sessions` value
+The current guard rejects relocation when a former relative skill path, `sessions` value
 or relative filesystem `playbooks.<id>.from` would resolve differently below
 the new directory. It leaves the former file unchanged and names every
 target-preserving absolute replacement. Apply those replacements and retry;
@@ -277,6 +277,33 @@ 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.
 
+## Skills across agents
+
+Set a shared `skills` list to let working agents use the same native skill:
+
+```yaml
+skills:
+  - ../skills/project-conventions
+captain:
+  adapter: claude
+  skills: []
+players:
+  dev.coder: codex
+  dev.reviewer: claude
+```
+
+Entries name a skill directory or its `SKILL.md`. Relative entries resolve from
+whichever config or `--with` overlay file declares them. An agent's own list
+replaces the shared list; `[]` opts out. Playbook preserves absolute locators
+through interactive and headless launches, and Cligent stages them for the native
+agent without changing its permissions. Role bindings do not override skills.
+
+Reopening a settled session uses the current lists for the next turn. Recovery
+of an uncertain turn keeps its attempted lists. Skill sources remain external
+files, so keep their locations available for resumed runs. Ordinary Captain
+routing, judging and replies receive `skills: []`; bounded recovery preparation
+can use the Captain's configured skills.
+
 ## Browser capability
 
 A Captain or player agent block may set `browser: true` to make Cligent's managed
@@ -287,7 +314,7 @@ uses that attempt's recorded value. Agent permissions remain fixed and retain
 their native precedence.
 
 Ordinary Captain decisions, replies, question checks and judges always receive
-`browser: false` and an empty MCP configuration. Enabling Browser does not turn
+`browser: false`, `skills: []` and an empty MCP configuration. Enabling Browser does not turn
 them into working actors. A working player, or bounded recovery preparation when
 needed, can use the capability explicitly configured for its agent. An embedding
 application should use Cligent's capability and browser-preparation APIs before

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sublang/playbook",
-  "version": "17.9.0",
+  "version": "17.10.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",
@@ -280,7 +280,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@sublang/cligent": "^0.33.2",
+    "@sublang/cligent": "^0.34.0",
     "@sublang/spex": "^3.0.0",
     "p-queue": "^9.3.1",
     "xstate": "^5.19.4",

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

@@ -48,6 +48,7 @@ const PLAYBOOK_LAUNCHER_KEYS = ["from", "command", "roles"];
 const HOST_CAPABILITIES_OPTION_KEY = "hostCapabilities";
 const PLAYBOOK_TOP_LEVEL_KEYS = new Set([
   "captain",
+  "skills",
   "players",
   "playbooks",
   "layout",
@@ -419,9 +420,13 @@ export async function loadLaunchPlan({
     );
   }
   const currentPlaybookIds = addCurrentPlaybookIds(top);
+  if (selectedMembers !== undefined) top = projectSelectedLayer(top, validateSelectedMembers(selectedMembers), "config");
+  top = resolveSkillLocators(top, userConfigPath);
   for (const overlayPath of overlayPaths) {
-    const overlay = loadOverlayFragment(overlayPath);
+    let overlay = loadOverlayFragment(overlayPath);
     addCurrentPlaybookIds(overlay, currentPlaybookIds);
+    if (selectedMembers !== undefined) overlay = projectSelectedLayer(overlay, validateSelectedMembers(selectedMembers), "overlay");
+    overlay = resolveSkillLocators(overlay, overlayPath);
     top =
       selectedMembers === undefined
         ? mergeConfigs(top, overlay)
@@ -471,10 +476,12 @@ export async function loadSelectedLaunchPlanDataOnly({
     validateSelectedMembers(selectedMembers),
     "config",
   );
+  top = resolveSkillLocators(top, userConfigPath);
   for (const overlayPath of overlayPaths) {
-    const overlay = loadOverlayFragment(overlayPath);
+    let overlay = loadOverlayFragment(overlayPath);
     addCurrentPlaybookIds(overlay, currentPlaybookIds);
-    top = mergeSelectedConfigs(top, overlay, selectedMembers);
+    overlay = projectSelectedLayer(overlay, validateSelectedMembers(selectedMembers), "overlay");
+    top = mergeSelectedConfigs(top, resolveSkillLocators(overlay, overlayPath), selectedMembers);
   }
   return await normalizeSelectedLaunchPlanDataOnlyWith(
     top,
@@ -512,7 +519,7 @@ async function normalizeSelectedLaunchPlanDataOnlyWith(
     }
   }
   top = projectSelectedMembers(top, expectedMembers);
-  top = cloneJson(top, "config");
+  top = resolveSkillLocators(cloneJson(top, "config"), configPath);
   assertNoRetiredProfiles(top, configPath);
   if (hasOwn(top, "run")) {
     throw new Error(
@@ -663,6 +670,7 @@ async function normalizeSelectedLaunchPlanDataOnlyWith(
       ? expectedMembers.playerIds.slice(0, 1)
       : initialVisible;
   const provisional = {
+    ...(top.skills === undefined ? {} : { skills: top.skills }),
     captain: { ...captain, from: PLAYBOOK_CAPTAIN_MODULE, options: {} },
     players: [
       ...expectedMembers.playerIds.map((id) => ({
@@ -694,14 +702,14 @@ async function normalizeSelectedLaunchPlanDataOnlyWith(
     options: _captainOptions,
     ...normalizedCaptain
   } = normalizedHost.captain;
-  captain = sessionAgentFromHostAgent(normalizedCaptain, "captain");
+  captain = sessionAgentFromHostAgent(normalizedCaptain, "captain", normalizedHost.skills);
   const hostAgents = new Map(
     normalizedHost.players.map(({ id, ...agent }) => [id, agent]),
   );
   const normalizedPlayerAgents = new Map(
     expectedMembers.playerIds.map((id) => [
       id,
-      sessionAgentFromHostAgent(hostAgents.get(id), `players.${id}`),
+      sessionAgentFromHostAgent(hostAgents.get(id), `players.${id}`, normalizedHost.skills),
     ]),
   );
 
@@ -857,7 +865,7 @@ async function normalizeLaunchPlanWith(
 ) {
   const importModule = loadModule ?? ((specifier) => import(specifier));
   top = projectSelectedMembers(top, selectedMembers);
-  top = cloneJson(top, "config");
+  top = resolveSkillLocators(cloneJson(top, "config"), configPath);
   assertNoRetiredProfiles(top, configPath);
   if (hasOwn(top, "run")) {
     throw new Error(
@@ -1060,6 +1068,7 @@ async function normalizeLaunchPlanWith(
       ? allPlayerIds.slice(0, 1)
       : provisionalVisible;
   const provisional = {
+    ...(top.skills === undefined ? {} : { skills: top.skills }),
     captain: {
       ...captain,
       from: PLAYBOOK_CAPTAIN_MODULE,
@@ -1099,14 +1108,14 @@ async function normalizeLaunchPlanWith(
     options: _captainOptions,
     ...normalizedCaptain
   } = normalizedHost.captain;
-  captain = sessionAgentFromHostAgent(normalizedCaptain, "captain");
+  captain = sessionAgentFromHostAgent(normalizedCaptain, "captain", normalizedHost.skills);
   const hostAgents = new Map(
     normalizedHost.players.map(({ id, ...agent }) => [id, agent]),
   );
   const normalizedPlayerAgents = new Map(
     allPlayerIds.map((id) => [
       id,
-      sessionAgentFromHostAgent(hostAgents.get(id), `players.${id}`),
+      sessionAgentFromHostAgent(hostAgents.get(id), `players.${id}`, normalizedHost.skills),
     ]),
   );
 
@@ -1296,9 +1305,27 @@ async function normalizeLaunchPlanWith(
   );
 }
 
-// Run cligent's public explicit-config loader over an isolated projection so
-// generic launch planning tracks the installed host schema without importing
-// or duplicating cligent's private validators.
+// Resolve authored locators before the temporary host config changes their base.
+function resolveSkillLocators(top, configPath) {
+  if (!isObject(top)) return top;
+  const base = configPath === undefined ? process.cwd() : dirname(resolve(configPath));
+  const list = (value, path) => {
+    if (!Array.isArray(value) || value.some(item => typeof item !== "string" || item.trim().length === 0 || item.includes("\0"))) {
+      throw new Error(`${path} must be an array of nonblank skill paths`);
+    }
+    return value.map(item => resolve(base, item));
+  };
+  const agent = (value, path) => !isObject(value) || value.skills === undefined
+    ? value : { ...value, skills: list(value.skills, `${path}.skills`) };
+  return {
+    ...top,
+    ...(top.skills === undefined ? {} : { skills: list(top.skills, "skills") }),
+    ...(top.captain === undefined ? {} : { captain: agent(top.captain, "captain") }),
+    ...(isObject(top.players) ? { players: Object.fromEntries(Object.entries(top.players).map(([id, value]) => [id, agent(value, `players.${id}`)])) } : {}),
+  };
+}
+
+// Validate through the installed public loader before registry imports.
 export async function normalizeHostConfig(config) {
   const dir = mkdtempSync(join(tmpdir(), "playbook-host-config-"));
   const path = join(dir, "tmux-play.config.yaml");
@@ -1590,6 +1617,19 @@ function assertLegacyRelocationLocatorsSafe(
     }
   }
 
+  const skillLists = [["skills", top.skills], ["captain.skills", isObject(top.captain) ? top.captain.skills : undefined]];
+  if (isObject(top.players)) for (const [id, agent] of Object.entries(top.players)) {
+    if (isObject(agent)) skillLists.push([`players.${id}.skills`, agent.skills]);
+  }
+  for (const [path, entries] of skillLists) {
+    if (!Array.isArray(entries)) continue;
+    entries.forEach((entry, index) => {
+      if (typeof entry !== "string" || entry.trim().length === 0 || isAbsolute(entry)) return;
+      const formerTarget = resolve(legacyDir, entry);
+      if (formerTarget !== resolve(canonicalDir, entry)) affected.push({ path: `${path}[${index}]`, replacement: formerTarget });
+    });
+  }
+
   if (affected.length === 0) return;
   const replacements = affected
     .map(({ path, replacement }) => `${path} = ${JSON.stringify(replacement)}`)
@@ -2353,12 +2393,13 @@ function applyTuningOverrides(agent, binding) {
   return effective;
 }
 
-function sessionAgentFromHostAgent(agent, path) {
+function sessionAgentFromHostAgent(agent, path, defaultSkills) {
   if (!isObject(agent)) {
     throw new Error("installed cligent omitted a retained agent");
   }
   return {
     adapter: agent.adapter,
+    ...((agent.skills ?? defaultSkills) === undefined ? {} : { skills: [...(agent.skills ?? defaultSkills)] }),
     ...(agent.browser === undefined ? {} : { browser: fastModeSelection(agent.browser, `${path}.browser`) }),
     model: tuningSelection(agent.model, `${path}.model`),
     effort: tuningSelection(agent.effort, `${path}.effort`),
@@ -2397,6 +2438,7 @@ export function projectHostAgent(agent, path = "agent") {
   const normalized = cloneJson(agent, path);
   return {
     adapter: normalized.adapter,
+    ...(normalized.skills === undefined ? {} : { skills: normalized.skills }),
     ...(normalized.browser === undefined ? {} : { browser: fastModeSelection(normalized.browser, `${path}.browser`) }),
     ...(normalized.model?.kind === "value"
       ? { model: normalized.model.value }

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

@@ -5580,6 +5580,7 @@ function validateCaptainSessionProjection(
             'subagentModel',
             'subagentEffort',
             'browser',
+            'skills',
           ],
       playerPath,
     );
@@ -5751,6 +5752,7 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
   if (!structural) {
     validateProjectedFastMode(agent, `${path}.fastMode`);
     if (agent.browser !== undefined && typeof agent.browser !== 'boolean') throw new Error(`${path}.browser must be a boolean`);
+    if (agent.skills !== undefined && (!Array.isArray(agent.skills) || agent.skills.some(item => typeof item !== 'string' || item.includes('\0') || !isRecordedAbsolutePath(item)))) throw new Error(`${path}.skills must be an array of absolute skill paths`);
     validateProjectedSubagentTuning(agent, path);
   }
   if (!hasId) {
@@ -5766,6 +5768,7 @@ function validateProjectedAgent(value, path, { structural, hasId = false }) {
             'subagentModel',
             'subagentEffort',
             'browser',
+            'skills',
           ],
       path,
     );

package/reference/sdlc/code.playbook/playbook-captain.d.ts

@@ -8,6 +8,7 @@ import type { SessionAssetRef } from './session-assets.js';
 interface SessionAgent {
     /** Mutable next-turn execution capability; never structural identity. */
     readonly browser?: boolean;
+    readonly skills?: readonly string[];
     readonly adapter: string;
     readonly model: TuningSelection;
     readonly effort: TuningSelection<Effort>;
@@ -44,7 +45,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
     readonly rootPlaybookId: string;
     readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser'>>;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser' | 'skills'>>;
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 export interface ProgressChange {
     snapshot?: PlaybookCaptainShellSnapshot | null;

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

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 import { randomUUID } from 'node:crypto';
+import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
 import { isAgentCallSettingsError, } from '@sublang/cligent/tmux-play';
@@ -2310,6 +2311,12 @@ function snapshotNonblankTuning(value, path) {
     }
     return value;
 }
+function snapshotSkillLocators(value, path) {
+    if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.includes('\0') || !(posix.isAbsolute(item) || win32.isAbsolute(item)))) {
+        throw new Error(`${path} must be an array of absolute skill paths`);
+    }
+    return [...value];
+}
 function snapshotSessionAgent(value, path) {
     const agent = snapshotRecord(value, path);
     rejectSnapshotKeys(agent, [
@@ -2320,6 +2327,7 @@ function snapshotSessionAgent(value, path) {
         'subagentModel',
         'subagentEffort',
         'browser',
+        'skills',
         'instruction',
         'permissions',
     ], path);
@@ -2328,7 +2336,8 @@ function snapshotSessionAgent(value, path) {
         key !== 'fastMode' &&
         key !== 'subagentModel' &&
         key !== 'subagentEffort' &&
-        key !== 'browser')), path);
+        key !== 'browser' &&
+        key !== 'skills')), path);
     return {
         adapter: fixed.adapter,
         ...(fixed.instruction === undefined
@@ -2337,6 +2346,7 @@ function snapshotSessionAgent(value, path) {
         ...(fixed.permissions === undefined
             ? {}
             : { permissions: livePermissions(fixed.permissions) }),
+        ...(agent.skills === undefined ? {} : { skills: snapshotSkillLocators(agent.skills, `${path}.skills`) }),
         ...(agent.browser === undefined ? {} : { browser: snapshotFastMode(agent.browser, `${path}.browser`) }),
         model: snapshotTuningSelection(agent.model, `${path}.model`),
         effort: snapshotEffortSelection(agent.effort, `${path}.effort`),
@@ -2372,6 +2382,7 @@ function callSettings(agent, tuning = agent) {
         model: tuning.model,
         effort: tuning.effort,
         browser: agent.browser ?? false,
+        skills: agent.skills === undefined ? [] : [...agent.skills],
         ...(tuning.fastMode === undefined ? {} : { fastMode: tuning.fastMode }),
         ...(tuning.subagentModel === undefined
             ? {}
@@ -2384,7 +2395,7 @@ function callSettings(agent, tuning = agent) {
     };
 }
 function controlCallSettings(agent) {
-    return { ...callSettings(agent), browser: false, mcpServers: {} };
+    return { ...callSettings(agent), browser: false, skills: [], mcpServers: {} };
 }
 function promptIdentity(binding) {
     return binding.model.kind === 'value'

package/reference/sdlc/code.playbook/playbook-captain.ts

@@ -2,6 +2,7 @@
 // SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
 
 import { randomUUID } from 'node:crypto';
+import { posix, win32 } from 'node:path';
 import { isDeepStrictEqual } from 'node:util';
 import PQueue from 'p-queue';
 
@@ -69,6 +70,7 @@ import { QUOTED_EVIDENCE_LIMIT, workerReportExcerpt, workerReportBlock } from '.
 interface SessionAgent {
   /** Mutable next-turn execution capability; never structural identity. */
   readonly browser?: boolean;
+  readonly skills?: readonly string[];
   readonly adapter: string;
   readonly model: TuningSelection;
   readonly effort: TuningSelection<Effort>;
@@ -127,7 +129,7 @@ interface PlaybookCaptainUnresolvedEffectSettlementInput {
   readonly unresolvedEffects: readonly PlaybookCaptainUnresolvedEffect[];
 }
 
-type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser'>>;
+type SnapshotAgentEnvelope = DeepReadonly<Omit<SessionAgent, TuningKey | 'browser' | 'skills'>>;
 
 type PlayerLedgerSnapshotEntry = DeepReadonly<PlayerLedgerEntry>;
 
@@ -4059,6 +4061,13 @@ function snapshotNonblankTuning(
   return value;
 }
 
+function snapshotSkillLocators(value: JsonValue, path: string): readonly string[] {
+  if (!Array.isArray(value) || value.some(item => typeof item !== 'string' || item.includes('\0') || !(posix.isAbsolute(item) || win32.isAbsolute(item)))) {
+    throw new Error(`${path} must be an array of absolute skill paths`);
+  }
+  return [...value] as string[];
+}
+
 function snapshotSessionAgent(
   value: JsonValue | undefined,
   path: string,
@@ -4074,6 +4083,7 @@ function snapshotSessionAgent(
       'subagentModel',
       'subagentEffort',
       'browser',
+      'skills',
       'instruction',
       'permissions',
     ],
@@ -4088,7 +4098,8 @@ function snapshotSessionAgent(
           key !== 'fastMode' &&
           key !== 'subagentModel' &&
           key !== 'subagentEffort' &&
-          key !== 'browser',
+          key !== 'browser' &&
+          key !== 'skills',
       ),
     ) as JsonValue,
     path,
@@ -4101,6 +4112,7 @@ function snapshotSessionAgent(
     ...(fixed.permissions === undefined
       ? {}
       : { permissions: livePermissions(fixed.permissions) }),
+    ...(agent.skills === undefined ? {} : { skills: snapshotSkillLocators(agent.skills, `${path}.skills`) }),
     ...(agent.browser === undefined ? {} : { browser: snapshotFastMode(agent.browser, `${path}.browser`) }),
     model: snapshotTuningSelection(agent.model, `${path}.model`),
     effort: snapshotEffortSelection(agent.effort, `${path}.effort`),
@@ -4126,7 +4138,7 @@ function snapshotSessionAgent(
   };
 }
 
-function fixedAgent(agent: SessionAgent): Omit<SessionAgent, TuningKey | 'browser'> {
+function fixedAgent(agent: SessionAgent): Omit<SessionAgent, TuningKey | 'browser' | 'skills'> {
   return {
     adapter: agent.adapter,
     ...(agent.instruction === undefined ? {} : { instruction: agent.instruction }),
@@ -4147,6 +4159,7 @@ function callSettings(
     model: tuning.model,
     effort: tuning.effort,
     browser: agent.browser ?? false,
+    skills: agent.skills === undefined ? [] : [...agent.skills],
     ...(tuning.fastMode === undefined ? {} : { fastMode: tuning.fastMode }),
     ...(tuning.subagentModel === undefined
       ? {}
@@ -4160,7 +4173,7 @@ function callSettings(
 }
 
 function controlCallSettings(agent: SessionAgent): AgentCallSettings {
-  return { ...callSettings(agent), browser: false, mcpServers: {} };
+  return { ...callSettings(agent), browser: false, skills: [], mcpServers: {} };
 }
 
 function promptIdentity(binding: EffectivePlayerBinding): string {

package/src/xstate-playbook-runtime.js

@@ -995,14 +995,20 @@ export function renderGovernedOutcomeContract(guard, description, outcome, shape
     for (const [field, authority] of Object.entries(outcome?.fields ?? {})) {
         if (authority === 'semantic') {
             const entry = authored.get(field);
-            // DR-089: the value has the shape the compiled machine admits.
+            // DR-089: the value has the shape the compiled machine admits; a
+            // shape the probe did not reveal is the machine's to judge, so the
+            // example asserts none (DR-091).
             const shape = shapes !== undefined && Object.prototype.hasOwnProperty.call(shapes, field)
                 ? shapes[field]
-                : 'string';
-            const words = describePlaybookSemanticValueShape(shape);
+                : undefined;
+            const words = shape === undefined ? undefined : describePlaybookSemanticValueShape(shape);
             replyMembers.push(`${JSON.stringify(field)}: ${entry?.placeholder ??
-                (shape === 'string' ? '<string>' : `<${words.replace(/^a /, '')}>`)}`);
-            if (shape !== 'string')
+                (shape === undefined
+                    ? '<value>'
+                    : shape === 'string'
+                        ? '<string>'
+                        : `<${words.replace(/^a /, '')}>`)}`);
+            if (shape !== undefined && shape !== 'string')
                 valueShapes.push(`\`${field}\` is ${words}`);
             semanticAsAuthored.push(entry?.segment ?? `\`${field}\``);
         }

package/src/xstate-playbook-runtime.ts

@@ -1874,19 +1874,25 @@ export function renderGovernedOutcomeContract(
   for (const [field, authority] of Object.entries(outcome?.fields ?? {})) {
     if (authority === 'semantic') {
       const entry = authored.get(field);
-      // DR-089: the value has the shape the compiled machine admits.
+      // DR-089: the value has the shape the compiled machine admits; a
+      // shape the probe did not reveal is the machine's to judge, so the
+      // example asserts none (DR-091).
       const shape =
         shapes !== undefined && Object.prototype.hasOwnProperty.call(shapes, field)
           ? shapes[field]!
-          : 'string';
-      const words = describePlaybookSemanticValueShape(shape);
+          : undefined;
+      const words = shape === undefined ? undefined : describePlaybookSemanticValueShape(shape);
       replyMembers.push(
         `${JSON.stringify(field)}: ${
           entry?.placeholder ??
-          (shape === 'string' ? '<string>' : `<${words.replace(/^a /, '')}>`)
+          (shape === undefined
+            ? '<value>'
+            : shape === 'string'
+              ? '<string>'
+              : `<${words!.replace(/^a /, '')}>`)
         }`,
       );
-      if (shape !== 'string') valueShapes.push(`\`${field}\` is ${words}`);
+      if (shape !== undefined && shape !== 'string') valueShapes.push(`\`${field}\` is ${words}`);
       semanticAsAuthored.push(entry?.segment ?? `\`${field}\``);
     } else {
       runtimeSupplied.push(`\`${field}\` (${authority}-owned)`);