pi-skill-playbook 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 eiei114
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,90 @@
+# Pi Skill Playbook
+
+Pi Skill Playbook is a Pi extension that guides Agent Skill usage flows with visible, human-mediated playbooks.
+
+MVP scope:
+
+- `/playbook list`
+- `/playbook start <playbook-id> [--run <name>]`
+- `/playbook resume <run-id>`
+- `/playbook status [run-id]`
+- `/playbook done`
+- `/playbook choose <outcome>`
+- strict YAML validation
+- active run widget below the editor
+- marker-based auto advance for single-outcome steps
+- local run state in `.pi/playbook-runs/`
+
+Deferred after scaffold:
+
+- `/playbook import-web`
+- `/playbook record`
+
+## Install from npm
+
+```bash
+pi install npm:pi-skill-playbook
+```
+
+Package version: `0.1.0`
+
+## Install locally
+
+```bash
+cd C:/Users/Keisu/Projects/OSS/pi-skill-playbook
+npm install
+pi -e .
+```
+
+Or install as a local Pi package:
+
+```bash
+pi install C:/Users/Keisu/Projects/OSS/pi-skill-playbook
+```
+
+## Add a playbook to a project
+
+MVP uses manual sample copy:
+
+```bash
+mkdir -p .pi/playbooks
+cp C:/Users/Keisu/Projects/OSS/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/feature-development.yml
+```
+
+Add personal run state to the target repo's `.gitignore`:
+
+```gitignore
+.pi/playbook-runs/
+```
+
+## Use
+
+```text
+/playbook list
+/playbook start feature-development --run my-feature
+/playbook done
+/playbook choose pass
+/playbook status
+```
+
+The widget displays the current step, exact skill command, completion criteria, and outcome labels.
+
+## Auto advance
+
+Playbooks default to `autoAdvance: auto`.
+
+When a user explicitly runs the current step skill with `/skill:<name>`, Pi Skill Playbook injects a short prompt that asks the assistant to leave a visible completion marker:
+
+```text
+PLAYBOOK_OUTCOME: ready-for-prd
+```
+
+If the current step has exactly one outcome, a valid marker advances the run automatically. If the step has multiple outcomes, the marker is shown as a suggestion and the user must confirm with `/playbook choose <outcome>`.
+
+Optional playbook setting:
+
+```yaml
+autoAdvance: auto     # default: marker can advance single-outcome steps
+autoAdvance: suggest  # marker only suggests /playbook done or /playbook choose
+autoAdvance: off      # no prompt injection or completion detection
+```

package/extensions/index.ts

@@ -0,0 +1,500 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { lastAssistantText, parseOutcomeMarker, parseSkillInvocation, planCompletion, renderPlaybookPrompt } from "../src/auto-advance.js";
+import { clearActiveRun, createRunId, listRunIds, loadActiveRunId, loadRun, saveRun, setActiveRun } from "../src/state.js";
+import { findPlaybook, loadPlaybooks } from "../src/playbooks.js";
+import { getGitignoreAdvisory } from "../src/gitignore.js";
+import { renderStepCard, renderValidationErrors } from "../src/render.js";
+import { normalizeSkillCommandName, validatePlaybook, validateUniquePlaybookIds } from "../src/validation.js";
+import type { LoadedPlaybook, PlaybookRunState } from "../src/types.js";
+
+const WIDGET_ID = "pi-skill-playbook";
+
+export default function piSkillPlaybook(pi: ExtensionAPI) {
+  let completionCwd = process.cwd();
+  let pendingSkillInvocation: string | undefined;
+
+  pi.on("session_start", async (_event, ctx) => {
+    completionCwd = ctx.cwd;
+    if (!ctx.hasUI) return;
+    const activeRunId = await loadActiveRunId(ctx.cwd);
+    if (!activeRunId) {
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      return;
+    }
+    const run = await loadRun(ctx.cwd, activeRunId);
+    if (!run || run.status !== "active") {
+      await clearActiveRun(ctx.cwd);
+      ctx.ui.setWidget(WIDGET_ID, undefined);
+      return;
+    }
+    const playbook = await findPlaybook(ctx.cwd, run.playbookId);
+    if (!playbook) {
+      ctx.ui.setWidget(WIDGET_ID, [`Playbook run '${run.runId}' references missing playbook '${run.playbookId}'.`], {
+        placement: "belowEditor",
+      });
+      return;
+    }
+    ctx.ui.setWidget(WIDGET_ID, renderStepCard(playbook, run), { placement: "belowEditor" });
+  });
+
+  pi.on("input", (event) => {
+    if (event.source === "extension") return { action: "continue" };
+    pendingSkillInvocation = parseSkillInvocation(event.text);
+    return { action: "continue" };
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    const active = await loadActiveIfAvailable(ctx.cwd);
+    if (!active) return;
+    const prompt = renderPlaybookPrompt(active.playbook, active.run);
+    if (!prompt) return;
+    return { systemPrompt: `${event.systemPrompt}\n\n${prompt}` };
+  });
+
+  pi.on("agent_end", async (event, ctx) => {
+    try {
+      await processAgentCompletion(ctx.cwd, pendingSkillInvocation, lastAssistantText(event.messages), ctx.hasUI ? ctx.ui : undefined);
+    } finally {
+      pendingSkillInvocation = undefined;
+    }
+  });
+
+  pi.registerCommand("playbook", {
+    description: "Guide Agent Skill workflows with project-local playbooks",
+    getArgumentCompletions: (prefix) => getPlaybookArgumentCompletions(completionCwd, prefix),
+    handler: async (args, ctx) => {
+      const parsed = parseArgs(args);
+      const command = parsed.shift() ?? "status";
+
+      try {
+        switch (command) {
+          case "list":
+            await listPlaybooks(pi, ctx.cwd, ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "start":
+            await startPlaybook(pi, ctx.cwd, parsed, ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "resume":
+            await resumeRun(ctx.cwd, parsed, ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "status":
+            await showStatus(ctx.cwd, parsed[0], ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "done":
+            await completeCurrentStep(ctx.cwd, ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "choose":
+            await chooseOutcome(ctx.cwd, parsed[0], ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "cancel":
+          case "stop":
+          case "abort":
+            await cancelRun(ctx.cwd, parsed[0], ctx.hasUI ? ctx.ui : undefined);
+            return;
+          case "import-web":
+          case "record":
+            notify(ctx.hasUI ? ctx.ui : undefined, `/${command} is deferred after the Core 6 MVP scaffold.` , "warning");
+            return;
+          default:
+            notify(ctx.hasUI ? ctx.ui : undefined, usage(), "error");
+        }
+      } catch (error) {
+        notify(ctx.hasUI ? ctx.ui : undefined, error instanceof Error ? error.message : String(error), "error");
+      }
+    },
+  });
+}
+
+async function listPlaybooks(pi: ExtensionAPI, cwd: string, ui: UiLike | undefined): Promise<void> {
+  const playbooks = await loadPlaybooks(cwd);
+  if (playbooks.length === 0) {
+    notify(ui, "No playbooks found. Create .pi/playbooks/*.yml or copy samples/feature-development.yml.", "info");
+    return;
+  }
+
+  const availableSkills = getAvailableSkills(pi);
+  const duplicateResult = validateUniquePlaybookIds(playbooks);
+  const lines = playbooks.flatMap((playbook) => {
+    const result = validatePlaybook(playbook, availableSkills, { requireSkills: false });
+    const marker = result.valid ? "ok" : "invalid";
+    return [`${marker} ${playbook.definition.id} - ${playbook.definition.name}`, ...result.errors.map((error) => `  - ${error}`)];
+  });
+  if (!duplicateResult.valid) lines.push(...duplicateResult.errors.map((error) => `invalid ${error}`));
+  notify(ui, lines.join("\n"), duplicateResult.valid ? "info" : "error");
+}
+
+async function startPlaybook(pi: ExtensionAPI, cwd: string, args: string[], ui: UiLike | undefined): Promise<void> {
+  const playbookId = args[0];
+  if (!playbookId) throw new Error("Usage: /playbook start <playbook-id> [--run <name>]");
+
+  const playbook = await findPlaybook(cwd, playbookId);
+  if (!playbook) throw new Error(`Playbook '${playbookId}' not found in .pi/playbooks/.`);
+
+  const validation = validatePlaybook(playbook, getAvailableSkills(pi), { requireSkills: true });
+  if (!validation.valid) {
+    throw new Error(`Playbook validation failed:\n${renderValidationErrors(validation.errors)}`);
+  }
+
+  const runName = readFlagValue(args.slice(1), "--run");
+  const now = new Date().toISOString();
+  const run: PlaybookRunState = {
+    runId: createRunId(playbook.definition.id, runName),
+    playbookId: playbook.definition.id,
+    playbookPath: playbook.path,
+    currentStep: playbook.definition.entry,
+    status: "active",
+    createdAt: now,
+    updatedAt: now,
+    history: [],
+  };
+
+  await saveRun(cwd, run);
+  await setActiveRun(cwd, run.runId);
+  renderWidget(ui, playbook, run);
+  const advisory = await getGitignoreAdvisory(cwd);
+  notify(ui, [`Started ${run.runId}.`, ...(advisory ? ["", advisory] : [])].join("\n"), advisory ? "warning" : "info");
+}
+
+async function resumeRun(cwd: string, args: string[], ui: UiLike | undefined): Promise<void> {
+  const runId = args[0];
+  if (!runId) throw new Error("Usage: /playbook resume <run-id>");
+  const run = await loadRun(cwd, runId);
+  if (!run) throw new Error(`Run '${runId}' not found.`);
+  if (run.status !== "active") throw new Error(`Run '${runId}' is ${run.status}.`);
+  const playbook = await findPlaybook(cwd, run.playbookId);
+  if (!playbook) throw new Error(`Run '${runId}' references missing playbook '${run.playbookId}'.`);
+  await setActiveRun(cwd, run.runId);
+  renderWidget(ui, playbook, run);
+  notify(ui, `Resumed ${run.runId}.`, "info");
+}
+
+async function cancelRun(cwd: string, explicitRunId: string | undefined, ui: UiLike | undefined): Promise<void> {
+  const runId = explicitRunId ?? (await loadActiveRunId(cwd));
+  if (!runId) throw new Error("Usage: /playbook cancel [run-id]");
+  const run = await loadRun(cwd, runId);
+  if (!run) throw new Error(`Run '${runId}' not found.`);
+
+  if (run.status !== "active") {
+    if ((await loadActiveRunId(cwd)) === run.runId) await clearActiveRun(cwd);
+    clearWidget(ui);
+    notify(ui, `Run '${run.runId}' is already ${run.status}.`, "info");
+    return;
+  }
+
+  const now = new Date().toISOString();
+  run.status = "cancelled";
+  run.updatedAt = now;
+  run.history.push({ at: now, step: run.currentStep, outcome: "cancelled", to: "cancelled" });
+  await saveRun(cwd, run);
+  if ((await loadActiveRunId(cwd)) === run.runId) await clearActiveRun(cwd);
+  clearWidget(ui);
+  notify(ui, `Cancelled playbook run ${run.runId}.`, "info");
+}
+
+async function showStatus(cwd: string, explicitRunId: string | undefined, ui: UiLike | undefined): Promise<void> {
+  const runId = explicitRunId ?? (await loadActiveRunId(cwd));
+  if (!runId) {
+    notify(ui, "No active playbook run.", "info");
+    clearWidget(ui);
+    return;
+  }
+  const run = await loadRun(cwd, runId);
+  if (!run) throw new Error(`Run '${runId}' not found.`);
+  if (run.status !== "active") {
+    notify(ui, `Run '${run.runId}' is ${run.status}.`, "info");
+    if (!explicitRunId) clearWidget(ui);
+    return;
+  }
+  const playbook = await findPlaybook(cwd, run.playbookId);
+  if (!playbook) throw new Error(`Run '${runId}' references missing playbook '${run.playbookId}'.`);
+  const lines = renderStepCard(playbook, run);
+  renderWidget(ui, playbook, run);
+  const advisory = await getGitignoreAdvisory(cwd);
+  notify(ui, [...lines, ...(advisory ? ["", advisory] : [])].join("\n"), advisory ? "warning" : "info");
+}
+
+async function completeCurrentStep(cwd: string, ui: UiLike | undefined): Promise<void> {
+  const { run, playbook } = await loadActive(cwd);
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) throw new Error(`Current step '${run.currentStep}' is missing.`);
+
+  if (step.transitions.length === 0) {
+    await completeRun(cwd, playbook, run, "complete", "complete", ui);
+    return;
+  }
+  if (step.transitions.length > 1) {
+    notify(ui, `Step attested. Choose outcome: ${step.transitions.map((t) => t.outcome).join(", ")}`, "info");
+    renderWidget(ui, playbook, run);
+    return;
+  }
+  await advanceRun(cwd, playbook, run, step.transitions[0].outcome, ui);
+}
+
+async function chooseOutcome(cwd: string, outcome: string | undefined, ui: UiLike | undefined): Promise<void> {
+  if (!outcome) throw new Error("Usage: /playbook choose <outcome>");
+  const { run, playbook } = await loadActive(cwd);
+  await advanceRun(cwd, playbook, run, outcome, ui);
+}
+
+async function advanceRun(cwd: string, playbook: LoadedPlaybook, run: PlaybookRunState, outcome: string, ui: UiLike | undefined): Promise<void> {
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) throw new Error(`Current step '${run.currentStep}' is missing.`);
+  const transition = step.transitions.find((candidate) => candidate.outcome === outcome);
+  if (!transition) {
+    throw new Error(`Outcome '${outcome}' is not valid for step '${run.currentStep}'. Valid: ${step.transitions.map((t) => t.outcome).join(", ")}`);
+  }
+  await completeRun(cwd, playbook, run, transition.outcome, transition.to, ui);
+}
+
+async function completeRun(cwd: string, playbook: LoadedPlaybook, run: PlaybookRunState, outcome: string, to: string, ui: UiLike | undefined): Promise<void> {
+  const now = new Date().toISOString();
+  run.history.push({ at: now, step: run.currentStep, outcome, to });
+  run.updatedAt = now;
+
+  if (to === "complete") {
+    run.status = "completed";
+    await saveRun(cwd, run);
+    await clearActiveRun(cwd);
+    clearWidget(ui);
+    notify(ui, `Completed playbook run ${run.runId}.`, "info");
+    return;
+  }
+
+  run.currentStep = to;
+  await saveRun(cwd, run);
+  await setActiveRun(cwd, run.runId);
+  renderWidget(ui, playbook, run);
+  notify(ui, `Advanced to '${to}'.`, "info");
+}
+
+async function processAgentCompletion(cwd: string, invokedSkill: string | undefined, assistantText: string, ui: UiLike | undefined): Promise<void> {
+  const active = await loadActiveIfAvailable(cwd);
+  if (!active) return;
+
+  const marker = parseOutcomeMarker(assistantText);
+  const plan = planCompletion(active.playbook, active.run, invokedSkill, marker);
+  if (!plan) return;
+
+  if (plan.kind === "auto") {
+    await completeRun(cwd, active.playbook, active.run, plan.outcome ?? "complete", plan.to ?? "complete", ui);
+    return;
+  }
+
+  if (plan.kind === "suggest") {
+    renderWidget(ui, active.playbook, active.run, plan.message);
+    notify(ui, plan.message, "info");
+    return;
+  }
+
+  notify(ui, plan.message, plan.kind === "warning" ? "warning" : "info");
+}
+
+async function loadActiveIfAvailable(cwd: string): Promise<{ run: PlaybookRunState; playbook: LoadedPlaybook } | undefined> {
+  const runId = await loadActiveRunId(cwd);
+  if (!runId) return undefined;
+  const run = await loadRun(cwd, runId);
+  if (!run || run.status !== "active") return undefined;
+  const playbook = await findPlaybook(cwd, run.playbookId);
+  if (!playbook) return undefined;
+  return { run, playbook };
+}
+
+async function loadActive(cwd: string): Promise<{ run: PlaybookRunState; playbook: LoadedPlaybook }> {
+  const runId = await loadActiveRunId(cwd);
+  if (!runId) throw new Error("No active playbook run.");
+  const run = await loadRun(cwd, runId);
+  if (!run) throw new Error(`Active run '${runId}' not found.`);
+  if (run.status !== "active") throw new Error(`Active run '${runId}' is ${run.status}.`);
+  const playbook = await findPlaybook(cwd, run.playbookId);
+  if (!playbook) throw new Error(`Run '${run.runId}' references missing playbook '${run.playbookId}'.`);
+  return { run, playbook };
+}
+
+function getAvailableSkills(pi: ExtensionAPI): ReadonlySet<string> {
+  const skills = pi.getCommands()
+    .filter((command) => command.source === "skill")
+    .map((command) => normalizeSkillCommandName(command.name));
+  return new Set(skills);
+}
+
+function renderWidget(ui: UiLike | undefined, playbook: LoadedPlaybook, run: PlaybookRunState, notice?: string): void {
+  const lines = renderStepCard(playbook, run);
+  ui?.setWidget(WIDGET_ID, notice ? [...lines, "", notice] : lines, { placement: "belowEditor" });
+}
+
+function clearWidget(ui: UiLike | undefined): void {
+  ui?.setWidget(WIDGET_ID, undefined);
+}
+
+function notify(ui: UiLike | undefined, message: string, level: "info" | "warning" | "error"): void {
+  ui?.notify(message, level);
+}
+
+function usage(): string {
+  return [
+    "Usage:",
+    "/playbook list",
+    "/playbook start <playbook-id> [--run <name>]",
+    "/playbook resume <run-id>",
+    "/playbook status [run-id]",
+    "/playbook done",
+    "/playbook choose <outcome>",
+    "/playbook cancel [run-id]",
+  ].join("\n");
+}
+
+type CompletionItem = { value: string; label: string; description?: string };
+
+export async function getPlaybookArgumentCompletions(cwd: string, prefix: string): Promise<CompletionItem[] | null> {
+  try {
+    return await getPlaybookArgumentCompletionsUnsafe(cwd, prefix);
+  } catch {
+    return null;
+  }
+}
+
+async function getPlaybookArgumentCompletionsUnsafe(cwd: string, prefix: string): Promise<CompletionItem[] | null> {
+  const parsed = parseCompletionPrefix(prefix);
+  const command = parsed.command;
+  if (!command) {
+    return completeCommands(parsed.currentToken);
+  }
+
+  if (parsed.completedTokens.length === 0) {
+    return completeCommands(parsed.currentToken);
+  }
+
+  switch (command) {
+    case "start":
+      return completeStartArguments(cwd, parsed);
+    case "resume":
+      return completeRunArgument(cwd, parsed, command, { activeOnly: true });
+    case "status":
+      return completeRunArgument(cwd, parsed, command, { activeOnly: false, optional: true });
+    case "cancel":
+    case "stop":
+    case "abort":
+      return completeRunArgument(cwd, parsed, command, { activeOnly: true, optional: true });
+    case "choose":
+      return completeOutcomeArgument(cwd, parsed);
+    default:
+      return null;
+  }
+}
+
+function completeCommands(token: string): CompletionItem[] | null {
+  const commands = ["list", "start", "resume", "status", "done", "choose", "cancel"];
+  return toCompletionItems(commands, token, (command) => command, (command) => command);
+}
+
+async function completeStartArguments(cwd: string, parsed: CompletionPrefix): Promise<CompletionItem[] | null> {
+  const args = parsed.completedTokens.slice(1);
+  if (args.length === 0) {
+    const playbooks = await loadPlaybooks(cwd);
+    return toCompletionItems(
+      playbooks,
+      parsed.currentToken,
+      (playbook) => `start ${playbook.definition.id}`,
+      (playbook) => playbook.definition.id,
+      (playbook) => playbook.definition.name,
+    );
+  }
+
+  if (args.length >= 1 && !args.includes("--run")) {
+    return toCompletionItems(["--run"], parsed.currentToken, (flag) => `start ${args.join(" ")} ${flag} `, (flag) => flag);
+  }
+  return null;
+}
+
+async function completeRunArgument(
+  cwd: string,
+  parsed: CompletionPrefix,
+  command: string,
+  options: { activeOnly: boolean; optional?: boolean },
+): Promise<CompletionItem[] | null> {
+  const args = parsed.completedTokens.slice(1);
+  if (args.length > 0 || (options.optional && parsed.currentToken === "" && !parsed.trailingWhitespace)) return null;
+  const runs = await getRunCompletionCandidates(cwd, options.activeOnly);
+  return toCompletionItems(
+    runs,
+    parsed.currentToken,
+    (run) => `${command} ${run.runId}`,
+    (run) => run.runId,
+    (run) => `${run.playbookId} (${run.status})`,
+  );
+}
+
+async function completeOutcomeArgument(cwd: string, parsed: CompletionPrefix): Promise<CompletionItem[] | null> {
+  const args = parsed.completedTokens.slice(1);
+  if (args.length > 0) return null;
+  const { run, playbook } = await loadActive(cwd);
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) return null;
+  return toCompletionItems(
+    step.transitions,
+    parsed.currentToken,
+    (transition) => `choose ${transition.outcome}`,
+    (transition) => transition.outcome,
+    (transition) => `to ${transition.to}`,
+  );
+}
+
+async function getRunCompletionCandidates(cwd: string, activeOnly: boolean): Promise<PlaybookRunState[]> {
+  const ids = await listRunIds(cwd);
+  const runs = (await Promise.all(ids.map((id) => loadRun(cwd, id)))).filter((run): run is PlaybookRunState => Boolean(run));
+  const filtered = activeOnly ? runs.filter((run) => run.status === "active") : runs;
+  return filtered.sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+}
+
+function toCompletionItems<T>(
+  values: T[],
+  token: string,
+  valueFor: (item: T) => string,
+  labelFor: (item: T) => string,
+  descriptionFor?: (item: T) => string | undefined,
+): CompletionItem[] | null {
+  const normalizedToken = token.trim().toLowerCase();
+  const items = values
+    .filter((item) => matchesCompletion(labelFor(item), normalizedToken))
+    .map((item) => {
+      const description = descriptionFor?.(item);
+      return { value: valueFor(item), label: labelFor(item), ...(description ? { description } : {}) };
+    });
+  return items.length > 0 ? items : null;
+}
+
+function matchesCompletion(value: string, token: string): boolean {
+  if (token === "") return true;
+  return value.toLowerCase().includes(token);
+}
+
+type CompletionPrefix = {
+  completedTokens: string[];
+  currentToken: string;
+  command: string | undefined;
+  trailingWhitespace: boolean;
+};
+
+function parseCompletionPrefix(prefix: string): CompletionPrefix {
+  const trailingWhitespace = /\s$/.test(prefix);
+  const tokens = parseArgs(prefix);
+  const completedTokens = trailingWhitespace ? tokens : tokens.slice(0, -1);
+  const currentToken = trailingWhitespace ? "" : tokens.at(-1) ?? "";
+  return { completedTokens, currentToken, command: completedTokens[0] ?? (!trailingWhitespace && tokens.length > 1 ? tokens[0] : undefined), trailingWhitespace };
+}
+
+function parseArgs(args: string): string[] {
+  const matches = args.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  return matches.map((arg) => arg.replace(/^(["'])(.*)\1$/, "$2"));
+}
+
+function readFlagValue(args: string[], flag: string): string | undefined {
+  const index = args.indexOf(flag);
+  if (index === -1) return undefined;
+  return args[index + 1];
+}
+
+interface UiLike {
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  setWidget(id: string, content: string[] | undefined, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "pi-skill-playbook",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Pi extension for passive, human-mediated Agent Skill playbooks.",
+  "keywords": ["pi-package", "pi-extension", "agent-skills", "playbook"],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/eiei114/pi-skill-playbook.git"
+  },
+  "bugs": {
+    "url": "https://github.com/eiei114/pi-skill-playbook/issues"
+  },
+  "homepage": "https://github.com/eiei114/pi-skill-playbook#readme",
+  "license": "MIT",
+  "files": [
+    "extensions/",
+    "src/",
+    "samples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test --import tsx tests/*.test.ts",
+    "build": "npm run check"
+  },
+  "pi": {
+    "extensions": ["./extensions/index.ts"]
+  },
+  "dependencies": {
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.20.0",
+    "typescript": "^5.8.0"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  }
+}

package/samples/feature-development.yml

@@ -0,0 +1,67 @@
+version: 1
+id: feature-development
+name: Feature Development Playbook
+entry: grill
+autoAdvance: auto
+
+skills:
+  grill-with-docs:
+    role: entry
+  to-prd:
+    role: internal
+  to-issues:
+    role: internal
+  tdd:
+    role: internal
+  review:
+    role: internal
+
+steps:
+  grill:
+    primarySkill: grill-with-docs
+    commandHint: "/skill:grill-with-docs <feature idea>"
+    doneWhen:
+      - Problem boundary is clear.
+      - Key terminology is resolved.
+    transitions:
+      - outcome: ready-for-prd
+        to: prd
+
+  prd:
+    primarySkill: to-prd
+    commandHint: "/skill:to-prd create PRD from resolved design"
+    doneWhen:
+      - PRD exists.
+    transitions:
+      - outcome: ready-for-issues
+        to: issues
+
+  issues:
+    primarySkill: to-issues
+    commandHint: "/skill:to-issues break PRD into implementation issues"
+    doneWhen:
+      - Issues are independently grabbable.
+    transitions:
+      - outcome: ready-for-implementation
+        to: implement
+
+  implement:
+    primarySkill: tdd
+    commandHint: "/skill:tdd implement the next issue"
+    doneWhen:
+      - Tests pass.
+      - Implementation is complete.
+    transitions:
+      - outcome: ready-for-review
+        to: review
+
+  review:
+    primarySkill: review
+    commandHint: "/skill:review review this branch against the plan"
+    doneWhen:
+      - Review result is known.
+    transitions:
+      - outcome: pass
+        to: complete
+      - outcome: fail
+        to: implement

package/src/auto-advance.ts

@@ -0,0 +1,181 @@
+import type { AdvanceMode, LoadedPlaybook, PlaybookRunState, PlaybookStep } from "./types.js";
+
+export type OutcomeMarker =
+  | { kind: "outcome"; outcome: string }
+  | { kind: "done" };
+
+export interface CompletionPlan {
+  kind: "auto" | "suggest" | "ignore" | "warning";
+  outcome?: string;
+  to?: string;
+  message: string;
+}
+
+export function getAdvanceMode(playbook: LoadedPlaybook): AdvanceMode {
+  return playbook.definition.autoAdvance ?? "auto";
+}
+
+export function parseSkillInvocation(input: string): string | undefined {
+  const match = input.match(/^\s*\/skill:([a-z0-9][a-z0-9-]*)\b/i);
+  return match?.[1]?.toLowerCase();
+}
+
+export function parseOutcomeMarker(text: string): OutcomeMarker | undefined {
+  const outcomeMatch = text.match(/^\s*PLAYBOOK_OUTCOME:\s*([a-z0-9][a-z0-9-]*)\s*$/im);
+  if (outcomeMatch?.[1]) return { kind: "outcome", outcome: outcomeMatch[1].toLowerCase() };
+  if (/^\s*PLAYBOOK_DONE\s*$/im.test(text)) return { kind: "done" };
+  return undefined;
+}
+
+export function renderPlaybookPrompt(playbook: LoadedPlaybook, run: PlaybookRunState): string | undefined {
+  if (getAdvanceMode(playbook) === "off") return undefined;
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) return undefined;
+
+  const outcomes = step.transitions.map((transition) => transition.outcome);
+  const markerInstruction = outcomes.length === 0
+    ? "If you complete this final step, end your response with exactly: PLAYBOOK_DONE"
+    : outcomes.length === 1
+      ? `If you complete this step, end your response with exactly: PLAYBOOK_OUTCOME: ${outcomes[0]}`
+      : `If you complete this step, end your response with one recommended outcome marker such as: PLAYBOOK_OUTCOME: ${outcomes[0]}`;
+  const multiOutcomeNote = outcomes.length > 1
+    ? "This step has multiple outcomes; the marker will be shown to the user for explicit confirmation, not auto-applied."
+    : "Single-outcome completion markers may advance the active playbook automatically.";
+
+  return [
+    "Active Pi Skill Playbook run:",
+    `- Playbook: ${playbook.definition.name}`,
+    `- Run: ${run.runId}`,
+    `- Step: ${run.currentStep}`,
+    `- Primary skill: ${step.primarySkill}`,
+    `- Valid outcomes: ${outcomes.length > 0 ? outcomes.join(", ") : "complete"}`,
+    markerInstruction,
+    multiOutcomeNote,
+    "Do not emit a marker unless the active step is genuinely complete.",
+  ].join("\n");
+}
+
+export function planCompletion(
+  playbook: LoadedPlaybook,
+  run: PlaybookRunState,
+  invokedSkill: string | undefined,
+  marker: OutcomeMarker | undefined,
+): CompletionPlan | undefined {
+  const mode = getAdvanceMode(playbook);
+  if (mode === "off") return undefined;
+
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) return { kind: "warning", message: `Current step '${run.currentStep}' is missing.` };
+
+  const matchingInvocation = invokedSkill === step.primarySkill;
+  if (!matchingInvocation) {
+    if (marker) {
+      return {
+        kind: "warning",
+        message: "Ignored PLAYBOOK_OUTCOME because current step skill was not invoked.",
+      };
+    }
+    return undefined;
+  }
+
+  if (!marker) return suggestPlan(step, run.currentStep);
+
+  const resolved = resolveMarker(step, marker);
+  if (!resolved) {
+    const valid = validOutcomeText(step);
+    return { kind: "warning", message: `Ignored invalid playbook marker for step '${run.currentStep}'. Valid: ${valid}` };
+  }
+
+  if (step.transitions.length > 1) {
+    return {
+      kind: "suggest",
+      outcome: resolved.outcome,
+      to: resolved.to,
+      message: `Completion marked for step '${run.currentStep}'. Confirm outcome: /playbook choose ${resolved.outcome}`,
+    };
+  }
+
+  if (mode === "suggest") {
+    return {
+      kind: "suggest",
+      outcome: resolved.outcome,
+      to: resolved.to,
+      message: resolved.outcome === "complete"
+        ? `Completion marked for final step '${run.currentStep}'. Run /playbook done to complete.`
+        : `Completion marked for step '${run.currentStep}'. Run /playbook done to advance to '${resolved.to}'.`,
+    };
+  }
+
+  return {
+    kind: "auto",
+    outcome: resolved.outcome,
+    to: resolved.to,
+    message: resolved.to === "complete" ? `Auto-completing playbook run from step '${run.currentStep}'.` : `Auto-advancing to '${resolved.to}'.`,
+  };
+}
+
+export function textFromMessage(message: unknown): string {
+  if (!isRecord(message)) return "";
+  return textFromContent(message.content);
+}
+
+export function lastAssistantText(messages: unknown[]): string {
+  for (let index = messages.length - 1; index >= 0; index--) {
+    const message = messages[index];
+    if (isRecord(message) && message.role === "assistant") return textFromMessage(message);
+  }
+  return "";
+}
+
+function suggestPlan(step: PlaybookStep, stepId: string): CompletionPlan {
+  if (step.transitions.length === 0) {
+    return { kind: "suggest", outcome: "complete", to: "complete", message: `Completion suspected for final step '${stepId}'. Run /playbook done to complete.` };
+  }
+  if (step.transitions.length === 1) {
+    const transition = step.transitions[0]!;
+    return {
+      kind: "suggest",
+      outcome: transition.outcome,
+      to: transition.to,
+      message: `Completion suspected for step '${stepId}'. Run /playbook done to advance to '${transition.to}'.`,
+    };
+  }
+  return {
+    kind: "suggest",
+    message: `Completion suspected for step '${stepId}'. Choose outcome: ${step.transitions.map((transition) => `/playbook choose ${transition.outcome}`).join(" | ")}`,
+  };
+}
+
+function resolveMarker(step: PlaybookStep, marker: OutcomeMarker): { outcome: string; to: string } | undefined {
+  if (marker.kind === "done") {
+    if (step.transitions.length === 0) return { outcome: "complete", to: "complete" };
+    if (step.transitions.length === 1) {
+      const transition = step.transitions[0]!;
+      return { outcome: transition.outcome, to: transition.to };
+    }
+    return undefined;
+  }
+
+  const transition = step.transitions.find((candidate) => candidate.outcome === marker.outcome);
+  if (!transition) return undefined;
+  return { outcome: transition.outcome, to: transition.to };
+}
+
+function validOutcomeText(step: PlaybookStep): string {
+  if (step.transitions.length === 0) return "PLAYBOOK_DONE";
+  return step.transitions.map((transition) => transition.outcome).join(", ");
+}
+
+function textFromContent(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content.map((item) => {
+    if (typeof item === "string") return item;
+    if (isRecord(item) && item.type === "text" && typeof item.text === "string") return item.text;
+    return "";
+  }).filter(Boolean).join("\n");
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/gitignore.ts

@@ -0,0 +1,14 @@
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { RUNS_DIR } from "./state.js";
+
+export async function getGitignoreAdvisory(cwd: string): Promise<string | undefined> {
+  try {
+    const gitignore = await readFile(join(cwd, ".gitignore"), "utf8");
+    const lines = gitignore.split(/\r?\n/).map((line) => line.trim());
+    if (lines.includes(RUNS_DIR) || lines.includes(`${RUNS_DIR}/`)) return undefined;
+  } catch {
+    // Missing .gitignore still needs advisory.
+  }
+  return `Run state is personal. Add this to .gitignore:\n${RUNS_DIR}/`;
+}

package/src/playbooks.ts

@@ -0,0 +1,33 @@
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { parsePlaybookYaml } from "./validation.js";
+import type { LoadedPlaybook } from "./types.js";
+
+export const PLAYBOOK_DIR = ".pi/playbooks";
+
+export async function loadPlaybooks(cwd: string): Promise<LoadedPlaybook[]> {
+  const dir = join(cwd, PLAYBOOK_DIR);
+  let files: string[];
+  try {
+    files = await readdir(dir);
+  } catch (error) {
+    if (typeof error === "object" && error !== null && "code" in error && (error as { code?: string }).code === "ENOENT") {
+      return [];
+    }
+    throw error;
+  }
+
+  const yamlFiles = files.filter((file) => /\.ya?ml$/i.test(file));
+  const playbooks: LoadedPlaybook[] = [];
+  for (const file of yamlFiles) {
+    const fullPath = join(dir, file);
+    const source = await readFile(fullPath, "utf8");
+    playbooks.push(parsePlaybookYaml(source, fullPath));
+  }
+  return playbooks;
+}
+
+export async function findPlaybook(cwd: string, id: string): Promise<LoadedPlaybook | undefined> {
+  const playbooks = await loadPlaybooks(cwd);
+  return playbooks.find((playbook) => playbook.definition.id === id);
+}

package/src/render.ts

@@ -0,0 +1,38 @@
+import type { LoadedPlaybook, PlaybookRunState } from "./types.js";
+
+export function renderStepCard(playbook: LoadedPlaybook, run: PlaybookRunState): string[] {
+  if (run.status === "completed") {
+    return [
+      `Playbook complete: ${playbook.definition.name}`,
+      `Run: ${run.runId}`,
+    ];
+  }
+
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) {
+    return [
+      `Playbook error: ${playbook.definition.name}`,
+      `Run: ${run.runId}`,
+      `Missing step: ${run.currentStep}`,
+    ];
+  }
+
+  const doneWhen = step.doneWhen.map((item) => `  - ${item}`);
+  const outcomes = step.transitions.length > 0
+    ? step.transitions.map((transition) => `${transition.outcome} -> ${transition.to}`).join(", ")
+    : "complete";
+
+  return [
+    `Playbook: ${playbook.definition.name}`,
+    `Run: ${run.runId}`,
+    `Step: ${run.currentStep}`,
+    `Next: ${step.commandHint}`,
+    "Done when:",
+    ...doneWhen,
+    `Outcomes: ${outcomes}`,
+  ];
+}
+
+export function renderValidationErrors(errors: string[]): string {
+  return errors.map((error) => `- ${error}`).join("\n");
+}

package/src/state.ts

@@ -0,0 +1,85 @@
+import { mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { ActiveRunState, PlaybookRunState } from "./types.js";
+
+export const RUNS_DIR = ".pi/playbook-runs";
+const ACTIVE_FILE = "active.json";
+
+export function runsDir(cwd: string): string {
+  return join(cwd, RUNS_DIR);
+}
+
+export function runFile(cwd: string, runId: string): string {
+  return join(runsDir(cwd), `${runId}.json`);
+}
+
+export function activeFile(cwd: string): string {
+  return join(runsDir(cwd), ACTIVE_FILE);
+}
+
+export async function saveRun(cwd: string, run: PlaybookRunState): Promise<void> {
+  await mkdir(runsDir(cwd), { recursive: true });
+  await writeFile(runFile(cwd, run.runId), `${JSON.stringify(run, null, 2)}\n`, "utf8");
+}
+
+export async function loadRun(cwd: string, runId: string): Promise<PlaybookRunState | undefined> {
+  try {
+    return JSON.parse(await readFile(runFile(cwd, runId), "utf8")) as PlaybookRunState;
+  } catch (error) {
+    if (isNotFound(error)) return undefined;
+    throw error;
+  }
+}
+
+export async function listRunIds(cwd: string): Promise<string[]> {
+  let files: string[];
+  try {
+    files = await readdir(runsDir(cwd));
+  } catch (error) {
+    if (isNotFound(error)) return [];
+    throw error;
+  }
+  return files
+    .filter((file) => file.endsWith(".json") && file !== ACTIVE_FILE)
+    .map((file) => file.replace(/\.json$/, ""))
+    .sort();
+}
+
+export async function setActiveRun(cwd: string, runId: string): Promise<void> {
+  await mkdir(runsDir(cwd), { recursive: true });
+  const state: ActiveRunState = { runId };
+  await writeFile(activeFile(cwd), `${JSON.stringify(state, null, 2)}\n`, "utf8");
+}
+
+export async function loadActiveRunId(cwd: string): Promise<string | undefined> {
+  try {
+    const state = JSON.parse(await readFile(activeFile(cwd), "utf8")) as ActiveRunState;
+    return typeof state.runId === "string" ? state.runId : undefined;
+  } catch (error) {
+    if (isNotFound(error)) return undefined;
+    throw error;
+  }
+}
+
+export async function clearActiveRun(cwd: string): Promise<void> {
+  await rm(activeFile(cwd), { force: true });
+}
+
+export function createRunId(playbookId: string, runName?: string): string {
+  const base = slugify(runName ?? playbookId);
+  const stamp = new Date().toISOString().replace(/[-:.TZ]/g, "").slice(0, 14);
+  return `${base}-${stamp}`;
+}
+
+export function slugify(value: string): string {
+  const slug = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return slug || "playbook-run";
+}
+
+function isNotFound(error: unknown): boolean {
+  return typeof error === "object" && error !== null && "code" in error && (error as { code?: string }).code === "ENOENT";
+}

package/src/types.ts

@@ -0,0 +1,62 @@
+export type SkillRole = "entry" | "internal";
+export type AdvanceMode = "auto" | "suggest" | "off";
+
+export interface PlaybookSkillDefinition {
+  role: SkillRole;
+}
+
+export interface PlaybookTransition {
+  outcome: string;
+  to: string;
+}
+
+export interface PlaybookStep {
+  primarySkill: string;
+  commandHint: string;
+  doneWhen: string[];
+  transitions: PlaybookTransition[];
+}
+
+export interface PlaybookDefinition {
+  version: 1;
+  id: string;
+  name: string;
+  entry: string;
+  autoAdvance?: AdvanceMode;
+  skills: Record<string, PlaybookSkillDefinition>;
+  steps: Record<string, PlaybookStep>;
+  sources?: Array<{ url: string; title?: string; accessedAt: string }>;
+}
+
+export interface LoadedPlaybook {
+  path: string;
+  definition: PlaybookDefinition;
+}
+
+export interface PlaybookRunHistoryEntry {
+  at: string;
+  step: string;
+  outcome: string;
+  to: string;
+}
+
+export interface PlaybookRunState {
+  runId: string;
+  playbookId: string;
+  playbookPath: string;
+  currentStep: string;
+  status: "active" | "completed" | "cancelled";
+  createdAt: string;
+  updatedAt: string;
+  history: PlaybookRunHistoryEntry[];
+}
+
+export interface ActiveRunState {
+  runId: string;
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+  warnings: string[];
+}

package/src/validation.ts

@@ -0,0 +1,126 @@
+import { parse } from "yaml";
+import type { LoadedPlaybook, PlaybookDefinition, ValidationResult } from "./types.js";
+
+const ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+
+export function parsePlaybookYaml(source: string, path: string): LoadedPlaybook {
+  const parsed = parse(source) as unknown;
+  if (!isRecord(parsed)) {
+    throw new Error(`${path}: playbook must be a YAML object`);
+  }
+  return { path, definition: parsed as PlaybookDefinition };
+}
+
+export function validatePlaybook(
+  loaded: LoadedPlaybook,
+  availableSkills: ReadonlySet<string> = new Set(),
+  options: { requireSkills?: boolean } = {},
+): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const pb = loaded.definition as PlaybookDefinition;
+  const pathPrefix = loaded.path ? `${loaded.path}: ` : "";
+
+  if (pb.version !== 1) errors.push(`${pathPrefix}version must be 1`);
+  if (!isNonEmptyString(pb.id)) errors.push(`${pathPrefix}id is required`);
+  else if (!ID_PATTERN.test(pb.id)) errors.push(`${pathPrefix}id must be lower-kebab-case`);
+  if (!isNonEmptyString(pb.name)) errors.push(`${pathPrefix}name is required`);
+  if (!isNonEmptyString(pb.entry)) errors.push(`${pathPrefix}entry is required`);
+  if (pb.autoAdvance !== undefined && pb.autoAdvance !== "auto" && pb.autoAdvance !== "suggest" && pb.autoAdvance !== "off") {
+    errors.push(`${pathPrefix}autoAdvance must be 'auto', 'suggest', or 'off'`);
+  }
+  if (!isRecord(pb.skills)) errors.push(`${pathPrefix}skills map is required`);
+  if (!isRecord(pb.steps)) errors.push(`${pathPrefix}steps map is required`);
+
+  if (!isRecord(pb.steps)) return { valid: errors.length === 0, errors, warnings };
+
+  if (isNonEmptyString(pb.entry) && !(pb.entry in pb.steps)) {
+    errors.push(`${pathPrefix}entry step '${pb.entry}' is missing`);
+  }
+
+  for (const [skillName, skill] of Object.entries(pb.skills ?? {})) {
+    if (!ID_PATTERN.test(skillName)) warnings.push(`${pathPrefix}skill '${skillName}' is not lower-kebab-case`);
+    if (!isRecord(skill)) {
+      errors.push(`${pathPrefix}skills.${skillName} must be an object`);
+      continue;
+    }
+    if (skill.role !== "entry" && skill.role !== "internal") {
+      errors.push(`${pathPrefix}skills.${skillName}.role must be 'entry' or 'internal'`);
+    }
+  }
+
+  for (const [stepId, step] of Object.entries(pb.steps)) {
+    if (!ID_PATTERN.test(stepId)) errors.push(`${pathPrefix}step '${stepId}' must be lower-kebab-case`);
+    if (!isRecord(step)) {
+      errors.push(`${pathPrefix}steps.${stepId} must be an object`);
+      continue;
+    }
+
+    if (!isNonEmptyString(step.primarySkill)) {
+      errors.push(`${pathPrefix}steps.${stepId}.primarySkill is required`);
+    } else {
+      if (!isRecord(pb.skills) || !(step.primarySkill in pb.skills)) {
+        errors.push(`${pathPrefix}steps.${stepId}.primarySkill '${step.primarySkill}' is not declared in skills`);
+      }
+      if (options.requireSkills && !availableSkills.has(step.primarySkill)) {
+        errors.push(`${pathPrefix}steps.${stepId}.primarySkill '${step.primarySkill}' is not an available Agent Skill`);
+      }
+    }
+
+    if (!isNonEmptyString(step.commandHint)) errors.push(`${pathPrefix}steps.${stepId}.commandHint is required`);
+    if (!Array.isArray(step.doneWhen) || step.doneWhen.some((item) => !isNonEmptyString(item))) {
+      errors.push(`${pathPrefix}steps.${stepId}.doneWhen must be a non-empty string array`);
+    }
+    if (!Array.isArray(step.transitions)) {
+      errors.push(`${pathPrefix}steps.${stepId}.transitions must be an array`);
+    } else {
+      const outcomes = new Set<string>();
+      for (const transition of step.transitions) {
+        if (!isRecord(transition)) {
+          errors.push(`${pathPrefix}steps.${stepId}.transitions contains a non-object transition`);
+          continue;
+        }
+        if (!isNonEmptyString(transition.outcome)) {
+          errors.push(`${pathPrefix}steps.${stepId}.transition.outcome is required`);
+        } else if (outcomes.has(transition.outcome)) {
+          errors.push(`${pathPrefix}steps.${stepId}.transition outcome '${transition.outcome}' is duplicated`);
+        } else {
+          outcomes.add(transition.outcome);
+        }
+        if (!isNonEmptyString(transition.to)) {
+          errors.push(`${pathPrefix}steps.${stepId}.transition.to is required`);
+        } else if (transition.to !== "complete" && !(transition.to in pb.steps)) {
+          errors.push(`${pathPrefix}steps.${stepId}.transition '${transition.outcome}' targets missing step '${transition.to}'`);
+        }
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export function validateUniquePlaybookIds(playbooks: LoadedPlaybook[]): ValidationResult {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  const seen = new Map<string, string>();
+  for (const playbook of playbooks) {
+    const id = playbook.definition.id;
+    if (!isNonEmptyString(id)) continue;
+    const previous = seen.get(id);
+    if (previous) errors.push(`duplicate playbook id '${id}' in ${previous} and ${playbook.path}`);
+    else seen.set(id, playbook.path);
+  }
+  return { valid: errors.length === 0, errors, warnings };
+}
+
+export function normalizeSkillCommandName(name: string): string {
+  return name.replace(/^\//, "").replace(/^skill:/, "");
+}
+
+function isRecord(value: unknown): value is Record<string, any> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}