@sublang/playbook 17.8.1 → 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.8.1",
+  "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/captain.md

@@ -96,7 +96,7 @@ When an acting turn's selection — parse-resolved or model-decided — settles
 > Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.
 > When mentioning progress detail, use only the aggregate counts the report supplies.
 > Append the supplied saved-counts line verbatim only when one is supplied; when none is supplied, append no saved-counts line.
-> Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.
+> Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Where the report states a step's commits, name each commit by its hash and the branch it landed on, exactly as the report gives them. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.
 > Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.
 > Omit routine status and routing updates. Do not add guarantees or conditions beyond the supplied facts.
 > Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.

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

@@ -53,7 +53,7 @@ const CLOSING_REPLY_PROMPT = [
     'Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.',
     'When mentioning progress detail, use only the aggregate counts the report supplies.',
     'Append the supplied saved-counts line verbatim only when one is supplied; when none is supplied, append no saved-counts line.',
-    "Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.",
+    "Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Where the report states a step's commits, name each commit by its hash and the branch it landed on, exactly as the report gives them. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.",
     'Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.',
     'Omit routine status and routing updates. Do not add guarantees or conditions beyond the supplied facts.',
     'Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.',

package/reference/sdlc/captain.playbook/captain.fsm.ts

@@ -267,7 +267,7 @@ const CLOSING_REPLY_PROMPT = [
   'Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.',
   'When mentioning progress detail, use only the aggregate counts the report supplies.',
   'Append the supplied saved-counts line verbatim only when one is supplied; when none is supplied, append no saved-counts line.',
-  "Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.",
+  "Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Where the report states a step's commits, name each commit by its hash and the branch it landed on, exactly as the report gives them. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.",
   'Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.',
   'Omit routine status and routing updates. Do not add guarantees or conditions beyond the supplied facts.',
   'Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.',

package/reference/sdlc/captain.playbook/captain.gears.md

@@ -65,7 +65,7 @@ Where this is the default generic session Captain playbook with no players beyon
 > Do not finish with a bare acknowledgement, a promise to act, or an announcement that the round is complete.
 > When mentioning progress detail, use only the aggregate counts the report supplies.
 > Append the supplied saved-counts line verbatim only when one is supplied; when none is supplied, append no saved-counts line.
-> Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.
+> Use familiar words and usually one to three short sentences, or a short list of choices. When a step's ending is supplied, give every fact that step reported — paths, record ids, commit hashes, names — as it gave them, before anything you say about them; leave none out and add none. Where the report states a step's commits, name each commit by its hash and the branch it landed on, exactly as the report gives them. Omit routine acknowledgements, unchanged-file reports, and other commit identifiers unless they explain a failure or a requested result. Never repeat other jargon, even in quotes: explain its meaning instead. Preserve every choice and material constraint without repeating background. Boss must understand and answer from your reply alone, without reading a player pane.
 > Keep the reply to 60 words unless extra words are essential to preserve choices, constraints, or result evidence.
 > Omit routine status and routing updates. Do not add guarantees or conditions beyond the supplied facts.
 > Write concise human chat prose with no guard names, result property names, control JSON, hidden control data, internal state ids, session ids, call ids, stack data, or private reasoning.

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/repository-effects.js

@@ -779,6 +779,23 @@ async function resolveHead(worktree, env) {
   }
 }
 
+// DR-090 §4: the branch HEAD names, or undefined when HEAD is detached:
+// `symbolic-ref --quiet` exits 1 without output for a detached HEAD, and
+// every other failure stays a failure.
+async function resolveBranch(worktree, env) {
+  try {
+    const branch = await runGitText(
+      worktree,
+      ['symbolic-ref', '--quiet', '--short', 'HEAD'],
+      { env },
+    );
+    return branch.length === 0 ? undefined : branch;
+  } catch (error) {
+    if (error?.code === 1 && error.stdout?.length === 0) return undefined;
+    throw error;
+  }
+}
+
 function gitFailureSays(error, exitCode, text) {
   return (
     typeof error === 'object' &&
@@ -862,20 +879,25 @@ export async function resolveCanonicalGitWorktree(cwd) {
 }
 
 async function sampleWorktree(worktree, env) {
-  const [headResult, visibilityResult, statusResult] = await Promise.allSettled([
+  // A directory that is not a repository yet names no branch: its scratch
+  // repository's HEAD is not the worktree's.
+  const [headResult, branchResult, visibilityResult, statusResult] = await Promise.allSettled([
     resolveHead(worktree, env),
+    env === undefined ? resolveBranch(worktree, env) : Promise.resolve(undefined),
     rawIndexVisibility(worktree, env),
     rawRepositoryStatus(worktree, env),
   ]);
   if (headResult.status === 'rejected') throw headResult.reason;
+  if (branchResult.status === 'rejected') throw branchResult.reason;
   if (visibilityResult.status === 'rejected') throw visibilityResult.reason;
   const head = headResult.value;
+  const branch = branchResult.value;
   const indexVisibility = visibilityResult.value;
   assertIndexVisibility(indexVisibility);
   if (statusResult.status === 'rejected') throw statusResult.reason;
   const status = statusResult.value;
   const projection = await projectionFromStatus(worktree, status);
-  return { head, indexVisibility, status, projection };
+  return { head, branch, indexVisibility, status, projection };
 }
 
 async function observeWorktreeSamples(identity, env, options) {
@@ -885,6 +907,7 @@ async function observeWorktreeSamples(identity, env, options) {
   const beforeText = projectionText(before.projection);
   if (
     before.head !== after.head ||
+    before.branch !== after.branch ||
     !before.indexVisibility.equals(after.indexVisibility) ||
     !before.status.equals(after.status) ||
     beforeText !== projectionText(after.projection)
@@ -895,6 +918,7 @@ async function observeWorktreeSamples(identity, env, options) {
     worktree: identity.worktree,
     gitDir: identity.gitDir,
     head: before.head,
+    ...(before.branch === undefined ? {} : { branch: before.branch }),
     projection: before.projection,
     projectionDigest: `sha256:${sha256(beforeText)}`,
   });

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/host-capabilities.d.ts

@@ -29,6 +29,7 @@ export interface RepositoryIdentity {
 }
 export interface PlaybookRepositoryObservation extends RepositoryIdentity {
   readonly head: string;
+  readonly branch?: string;
   readonly projection: Readonly<Record<string, JsonValue>>;
   readonly projectionDigest: string;
 }

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;