pi-skill-playbook 0.1.5 → 1.0.0

package/README.md

@@ -22,7 +22,7 @@ Define ordered skill workflows as YAML playbooks in your project, then drive the
 - **Marker-based auto advance** — Single-outcome steps advance automatically when the assistant emits a visible `PLAYBOOK_OUTCOME:` marker. Multi-outcome steps always require explicit confirmation.
 - **Active run widget** — Displays current step, skill command, completion criteria, and outcome labels below the editor.
 - **Strict YAML validation** — Playbooks are validated on load for structure, transitions, and skill references.
-- **Tab completion** — Commands, playbook IDs, run IDs, outcomes, and flags all support tab completion.
+- **Selection UI** — Playbook, run, and outcome selection use the Pi TUI selector instead of memorized ids.
 - **Local run state** — Run state is stored in `.pi/playbook-runs/` inside the target project, never in git.
 
 ## Install
@@ -69,19 +69,21 @@ pi -e .
    .pi/playbook-runs/
    ```
 
-3. **Start a run**:
+3. **Start a run** from the Pi TUI:
 
    ```
    /playbook:list
-   /playbook:start feature-development --run my-feature
+   /playbook:start
    ```
 
+   When more than one playbook exists, Pi shows a selector with validation status for each playbook. The run id is generated automatically.
+
 4. **Drive the workflow**:
 
    ```
    /skill:grill-with-docs <feature idea>
    /playbook:done
-   /playbook:choose ready-for-prd
+   /playbook:choose
    /playbook:status
    ```
 
@@ -92,14 +94,14 @@ The widget displays the current step, exact skill command, completion criteria,
 | Command | Description |
 |---|---|
 | `/playbook:list` | List available playbooks with validation status |
-| `/playbook:start <id> [--run <name>]` | Start a new playbook run |
-| `/playbook:resume <run-id>` | Resume a paused active run |
-| `/playbook:status [run-id]` | Show current step and completion criteria |
+| `/playbook:start` | Select a playbook and start a new run |
+| `/playbook:resume` | Select an active run to resume |
+| `/playbook:status` | Show current step and completion criteria |
 | `/playbook:done` | Complete the current step (auto-advances if single outcome) |
-| `/playbook:choose <outcome>` | Choose an outcome for multi-branch steps |
-| `/playbook:cancel [run-id]` | Cancel an active run |
+| `/playbook:choose` | Select an outcome for multi-branch steps |
+| `/playbook:cancel` | Select and confirm an active run cancellation |
 
-Legacy space-separated forms (`/playbook start`) remain available for compatibility.
+All commands are argument-free. Use the Pi TUI selection UI to pick playbooks, runs, and outcomes.
 
 ### Auto advance
 

package/docs/adr/0001-marker-based-auto-advance.md

@@ -0,0 +1,15 @@
+# Marker-based auto advance
+
+Pi Skill Playbook defaults to marker-based **Auto Advance**: a run may advance automatically only when the active step's primary skill was explicitly invoked with `/skill:<name>` and the assistant emits a visible `PLAYBOOK_OUTCOME: <outcome>` marker. This keeps single-outcome workflows low-friction without turning playbooks into hidden skill automation; markerless completions only produce an advance suggestion, and multi-outcome steps still require explicit outcome choice.
+
+## Considered Options
+
+- Fully automatic advancement after any matching skill invocation: rejected because failed or partial skill runs could silently advance the run.
+- Suggest-only advancement: rejected as too close to the existing `/playbook:done` workflow.
+- Hidden structured metadata: rejected because visible markers make state changes auditable in conversation history.
+
+## Consequences
+
+- Playbook prompts must tell the assistant the valid outcomes and marker format for the active step.
+- `autoAdvance` defaults to `auto`, with `suggest` and `off` available per playbook.
+- Auto advance changes run state and widget state only; it never runs the next skill or writes commands into the editor.

package/docs/examples.md

@@ -0,0 +1,18 @@
+# Examples
+
+## Selection-first TUI flow
+
+Copy or create YAML playbooks in the target project under `.pi/playbooks/`, then use argument-free commands from the Pi TUI:
+
+```text
+/playbook:start
+/skill:grill-with-docs <feature idea>
+/playbook:done
+/playbook:choose
+/playbook:status
+```
+
+- `/playbook:start` opens a playbook selector when multiple playbooks exist and generates the run id automatically.
+- `/playbook:resume` opens an active-run selector.
+- `/playbook:choose` opens a selector for the current step's valid outcomes.
+- `/playbook:cancel` selects an active run when needed and asks for confirmation before marking it cancelled.

package/extensions/index.ts

@@ -19,26 +19,21 @@ const COMMANDS = [
   ["cancel", "cancel an active playbook run"],
 ] as const;
 
-const COLON_COMMAND_ALIASES = COMMANDS.map(([command, description]) => ({
-  name: `playbook:${command}`,
-  command,
-  description,
-}));
-
-const COLON_COMPLETION_COMMANDS = new Set(["start", "resume", "status", "cancel", "choose"]);
-
 type CommandContext = {
   cwd: string;
   hasUI: boolean;
   ui?: UiLike;
 };
 
+type SelectOption<T> = {
+  label: string;
+  value: T;
+};
+
 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) {
@@ -83,29 +78,12 @@ export default function piSkillPlaybook(pi: ExtensionAPI) {
     }
   });
 
-  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 {
-        await handlePlaybookCommand(pi, command, parsed, ctx);
-      } catch (error) {
-        notify(ctx.hasUI ? ctx.ui : undefined, error instanceof Error ? error.message : String(error), "error");
-      }
-    },
-  });
-
-  for (const alias of COLON_COMMAND_ALIASES) {
-    pi.registerCommand(alias.name, {
-      description: `Playbook: ${alias.description}. Alias for /playbook ${alias.command}.`,
-      ...(COLON_COMPLETION_COMMANDS.has(alias.command)
-        ? { getArgumentCompletions: (prefix) => getPlaybookColonArgumentCompletions(completionCwd, alias.command, prefix) }
-        : {}),
-      handler: async (args, ctx) => {
+  for (const [command, description] of COMMANDS) {
+    pi.registerCommand(`playbook:${command}`, {
+      description: `Playbook: ${description}.`,
+      handler: async (_args, ctx) => {
         try {
-          await handlePlaybookCommand(pi, alias.command, parseArgs(args), ctx);
+          await handlePlaybookCommand(pi, command, ctx);
         } catch (error) {
           notify(ctx.hasUI ? ctx.ui : undefined, error instanceof Error ? error.message : String(error), "error");
         }
@@ -114,10 +92,9 @@ export default function piSkillPlaybook(pi: ExtensionAPI) {
   }
 }
 
-async function handlePlaybookCommand(
+export async function handlePlaybookCommand(
   pi: ExtensionAPI,
   command: string,
-  args: string[],
   ctx: CommandContext,
 ): Promise<void> {
   const ui = ctx.hasUI ? ctx.ui : undefined;
@@ -127,24 +104,24 @@ async function handlePlaybookCommand(
       await listPlaybooks(pi, ctx.cwd, ui);
       return;
     case "start":
-      await startPlaybook(pi, ctx.cwd, args, ui);
+      await startPlaybook(pi, ctx.cwd, ui);
       return;
     case "resume":
-      await resumeRun(ctx.cwd, args, ui);
+      await resumeRun(ctx.cwd, ui);
       return;
     case "status":
-      await showStatus(ctx.cwd, args[0], ui);
+      await showStatus(ctx.cwd, ui);
       return;
     case "done":
       await completeCurrentStep(ctx.cwd, ui);
       return;
     case "choose":
-      await chooseOutcome(ctx.cwd, args[0], ui);
+      await chooseOutcome(ctx.cwd, ui);
       return;
     case "cancel":
     case "stop":
     case "abort":
-      await cancelRun(ctx.cwd, args[0], ui);
+      await cancelRun(ctx.cwd, ui);
       return;
     case "import-web":
     case "record":
@@ -173,19 +150,13 @@ async function listPlaybooks(pi: ExtensionAPI, cwd: string, ui: UiLike | undefin
   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)}`);
-  }
+async function startPlaybook(pi: ExtensionAPI, cwd: string, ui: UiLike | undefined): Promise<void> {
+  const playbook = await pickPlaybook(pi, cwd, ui);
+  if (!playbook) return;
+  await createAndActivateRun(cwd, playbook, undefined, ui);
+}
 
-  const runName = readFlagValue(args.slice(1), "--run");
+async function createAndActivateRun(cwd: string, playbook: LoadedPlaybook, runName: string | undefined, ui: UiLike | undefined): Promise<void> {
   const now = new Date().toISOString();
   const run: PlaybookRunState = {
     runId: createRunId(playbook.definition.id, runName),
@@ -205,24 +176,20 @@ async function startPlaybook(pi: ExtensionAPI, cwd: string, args: string[], ui:
   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}.`);
+async function resumeRun(cwd: string, ui: UiLike | undefined): Promise<void> {
+  const run = await pickActiveRun(cwd, ui, "Resume which playbook run?");
+  if (!run) return;
+
   const playbook = await findPlaybook(cwd, run.playbookId);
-  if (!playbook) throw new Error(`Run '${runId}' references missing playbook '${run.playbookId}'.`);
+  if (!playbook) throw new Error(`Run '${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.`);
+async function cancelRun(cwd: string, ui: UiLike | undefined): Promise<void> {
+  const run = await pickRunToCancel(cwd, ui);
+  if (!run) return;
 
   if (run.status !== "active") {
     if ((await loadActiveRunId(cwd)) === run.runId) await clearActiveRun(cwd);
@@ -241,8 +208,8 @@ async function cancelRun(cwd: string, explicitRunId: string | undefined, ui: UiL
   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));
+async function showStatus(cwd: string, ui: UiLike | undefined): Promise<void> {
+  const runId = await loadActiveRunId(cwd);
   if (!runId) {
     notify(ui, "No active playbook run.", "info");
     clearWidget(ui);
@@ -252,7 +219,7 @@ async function showStatus(cwd: string, explicitRunId: string | undefined, ui: Ui
   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);
+    clearWidget(ui);
     return;
   }
   const playbook = await findPlaybook(cwd, run.playbookId);
@@ -280,10 +247,161 @@ async function completeCurrentStep(cwd: string, ui: UiLike | undefined): Promise
   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>");
+async function chooseOutcome(cwd: string, ui: UiLike | undefined): Promise<void> {
   const { run, playbook } = await loadActive(cwd);
-  await advanceRun(cwd, playbook, run, outcome, ui);
+  const selected = await pickOutcome(playbook, run, ui);
+  if (!selected) return;
+  await advanceRun(cwd, playbook, run, selected.outcome, ui);
+}
+
+async function pickPlaybook(pi: ExtensionAPI, cwd: string, ui: UiLike | undefined): Promise<LoadedPlaybook | undefined> {
+  if (!hasSelectionUI(ui)) {
+    notify(ui, "Interactive playbook selection requires the Pi TUI. Run /playbook:start from the command palette.", "error");
+    return undefined;
+  }
+
+  const playbooks = await loadPlaybooks(cwd);
+  if (playbooks.length === 0) {
+    notify(ui, "No playbooks found. Create .pi/playbooks/*.yml or copy samples/feature-development.yml into .pi/playbooks/.", "info");
+    return undefined;
+  }
+
+  const availableSkills = getAvailableSkills(pi);
+  const duplicateErrors = duplicateIdErrors(playbooks);
+  const candidates = playbooks.map((playbook) => {
+    const validation = validatePlaybook(playbook, availableSkills, { requireSkills: true });
+    const errors = [...validation.errors, ...(duplicateErrors.get(playbook) ?? [])];
+    return { playbook, errors, valid: errors.length === 0 };
+  });
+
+  if (candidates.length === 1) {
+    const candidate = candidates[0];
+    if (!candidate.valid) {
+      notify(ui, `Playbook validation failed:\n${renderValidationErrors(candidate.errors)}`, "error");
+      return undefined;
+    }
+    return candidate.playbook;
+  }
+
+  const options = candidates.map((candidate) => ({
+    label: playbookSelectionLabel(candidate.playbook, candidate.errors),
+    value: candidate,
+  }));
+  const selected = await selectByLabel(ui, "Start which playbook?", options);
+  if (!selected) return undefined;
+  if (!selected.valid) {
+    notify(ui, `Playbook validation failed:\n${renderValidationErrors(selected.errors)}`, "error");
+    return undefined;
+  }
+  return selected.playbook;
+}
+
+function playbookSelectionLabel(playbook: LoadedPlaybook, errors: string[]): string {
+  const marker = errors.length === 0 ? "ok" : "invalid";
+  const suffix = errors.length === 0 ? "" : ` — ${errors.join("; ")}`;
+  return `${playbook.definition.id} — ${playbook.definition.name} (${marker})${suffix}`;
+}
+
+function duplicateIdErrors(playbooks: LoadedPlaybook[]): Map<LoadedPlaybook, string[]> {
+  const byId = new Map<string, LoadedPlaybook[]>();
+  for (const playbook of playbooks) {
+    const id = playbook.definition.id;
+    if (!id) continue;
+    byId.set(id, [...(byId.get(id) ?? []), playbook]);
+  }
+
+  const result = new Map<LoadedPlaybook, string[]>();
+  for (const [id, matches] of byId) {
+    if (matches.length < 2) continue;
+    const paths = matches.map((playbook) => playbook.path).join(", ");
+    for (const playbook of matches) result.set(playbook, [`duplicate playbook id '${id}' in ${paths}`]);
+  }
+  return result;
+}
+
+async function pickActiveRun(cwd: string, ui: UiLike | undefined, title: string): Promise<PlaybookRunState | undefined> {
+  if (!hasSelectionUI(ui)) {
+    notify(ui, "Interactive run selection requires the Pi TUI. Run /playbook:resume from the command palette.", "error");
+    return undefined;
+  }
+
+  const runs = await getActiveRuns(cwd);
+  if (runs.length === 0) {
+    clearWidget(ui);
+    notify(ui, "No active playbook runs. Start one with /playbook:start.", "info");
+    return undefined;
+  }
+
+  return selectByLabel(ui, title, runs.map((run) => ({ label: activeRunLabel(run), value: run })));
+}
+
+async function pickRunToCancel(cwd: string, ui: UiLike | undefined): Promise<PlaybookRunState | undefined> {
+  if (!hasConfirmUI(ui)) {
+    notify(ui, "Interactive cancellation requires the Pi TUI. Run /playbook:cancel from the command palette.", "error");
+    return undefined;
+  }
+
+  const runs = await getActiveRuns(cwd);
+  if (runs.length === 0) {
+    clearWidget(ui);
+    notify(ui, "No active playbook runs to cancel.", "info");
+    return undefined;
+  }
+
+  const run = runs.length === 1
+    ? runs[0]
+    : await selectByLabel(ui, "Cancel which playbook run?", runs.map((candidate) => ({ label: activeRunLabel(candidate), value: candidate })));
+  if (!run) return undefined;
+
+  const confirmed = await ui.confirm("Cancel playbook run?", `${run.runId} (${run.playbookId}) will be marked cancelled.`);
+  if (!confirmed) {
+    notify(ui, "Playbook cancellation skipped.", "info");
+    return undefined;
+  }
+  return run;
+}
+
+function activeRunLabel(run: PlaybookRunState): string {
+  return `${run.runId} — ${run.playbookId} (updated ${run.updatedAt})`;
+}
+
+async function pickOutcome(playbook: LoadedPlaybook, run: PlaybookRunState, ui: UiLike | undefined) {
+  if (!hasSelectionUI(ui)) {
+    notify(ui, "Interactive outcome selection requires the Pi TUI. Run /playbook:choose from the command palette.", "error");
+    return undefined;
+  }
+
+  const step = playbook.definition.steps[run.currentStep];
+  if (!step) throw new Error(`Current step '${run.currentStep}' is missing.`);
+  if (step.transitions.length === 0) {
+    notify(ui, "Current step has no branch outcomes. Run /playbook:done to complete it.", "info");
+    return undefined;
+  }
+
+  return selectByLabel(
+    ui,
+    `Choose outcome for ${run.currentStep}`,
+    step.transitions.map((transition) => ({ label: `${transition.outcome} → ${transition.to}`, value: transition })),
+  );
+}
+
+async function selectByLabel<T>(
+  ui: { select(title: string, options: string[]): Promise<string | undefined> },
+  title: string,
+  options: SelectOption<T>[],
+): Promise<T | undefined> {
+  const selected = await ui.select(title, options.map((option) => option.label));
+  return options.find((option) => option.label === selected)?.value;
+}
+
+function hasSelectionUI(ui: UiLike | undefined): ui is UiLike & { select: NonNullable<UiLike["select"]> } {
+  return typeof ui?.select === "function";
+}
+
+function hasConfirmUI(
+  ui: UiLike | undefined,
+): ui is UiLike & { select: NonNullable<UiLike["select"]>; confirm: NonNullable<UiLike["confirm"]> } {
+  return hasSelectionUI(ui) && typeof ui.confirm === "function";
 }
 
 async function advanceRun(cwd: string, playbook: LoadedPlaybook, run: PlaybookRunState, outcome: string, ui: UiLike | undefined): Promise<void> {
@@ -384,188 +502,24 @@ function usage(): string {
   return [
     "Usage:",
     "/playbook:list",
-    "/playbook:start <playbook-id> [--run <name>]",
-    "/playbook:resume <run-id>",
-    "/playbook:status [run-id]",
+    "/playbook:start",
+    "/playbook:resume",
+    "/playbook:status",
     "/playbook:done",
-    "/playbook:choose <outcome>",
-    "/playbook:cancel [run-id]",
-    "Legacy space-separated /playbook <subcommand> forms remain available for compatibility.",
+    "/playbook:choose",
+    "/playbook:cancel",
   ].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;
-  }
-}
-
-export async function getPlaybookColonArgumentCompletions(
-  cwd: string,
-  command: string,
-  prefix: string,
-): Promise<CompletionItem[] | null> {
-  try {
-    const normalizedPrefix = prefix.trimStart();
-    const legacyPrefix = normalizedPrefix ? `${command} ${normalizedPrefix}` : command;
-    const items = await getPlaybookArgumentCompletionsUnsafe(cwd, legacyPrefix);
-    if (!items) return null;
-    const legacyToken = `${command} `;
-    return items.map((item) => ({
-      ...item,
-      value: item.value.startsWith(legacyToken) ? item.value.slice(legacyToken.length) : item.value,
-    }));
-  } 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[]> {
+async function getActiveRuns(cwd: string): 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];
+  return runs.filter((run) => run.status === "active").sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
 }
 
 interface UiLike {
   notify(message: string, level: "info" | "warning" | "error"): void;
+  select?(title: string, options: string[]): Promise<string | undefined>;
+  confirm?(title: string, message: string): Promise<boolean>;
   setWidget(id: string, content: string[] | undefined, options?: { placement?: "aboveEditor" | "belowEditor" }): void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-playbook",
-  "version": "0.1.5",
+  "version": "1.0.0",
   "type": "module",
   "description": "Pi extension for passive, human-mediated Agent Skill playbooks.",
   "keywords": ["pi-package", "pi-extension", "agent-skills", "playbook"],
@@ -16,15 +16,18 @@
   "files": [
     "extensions/",
     "src/",
+    "docs/",
     "samples/",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
     "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
     "test": "node --test --import tsx tests/*.test.ts",
     "build": "npm run check",
-    "validate:package": "npm pack --dry-run"
+    "validate:package": "npm pack --dry-run",
+    "ci": "npm run typecheck && npm test && npm run validate:package"
   },
   "pi": {
     "extensions": ["./extensions/index.ts"]

package/src/auto-advance.ts

@@ -91,7 +91,7 @@ export function planCompletion(
       kind: "suggest",
       outcome: resolved.outcome,
       to: resolved.to,
-      message: `Completion marked for step '${run.currentStep}'. Confirm outcome: /playbook:choose ${resolved.outcome}`,
+      message: `Completion marked for step '${run.currentStep}'. Confirm outcome with /playbook:choose.`,
     };
   }
 
@@ -142,7 +142,7 @@ function suggestPlan(step: PlaybookStep, stepId: string): CompletionPlan {
   }
   return {
     kind: "suggest",
-    message: `Completion suspected for step '${stepId}'. Choose outcome: ${step.transitions.map((transition) => `/playbook:choose ${transition.outcome}`).join(" | ")}`,
+    message: `Completion suspected for step '${stepId}'. Run /playbook:choose to select an outcome.`,
   };
 }