pi-skill-playbook 0.1.4 → 0.2.0

package/README.md

@@ -1,33 +1,39 @@
 # Pi Skill Playbook
 
-Pi Skill Playbook is a Pi extension that guides Agent Skill usage flows with visible, human-mediated playbooks.
+[![CI](https://github.com/eiei114/pi-skill-playbook/actions/workflows/auto-release.yml/badge.svg)](https://github.com/eiei114/pi-skill-playbook/actions/workflows/auto-release.yml)
+[![Publish](https://github.com/eiei114/pi-skill-playbook/actions/workflows/publish.yml/badge.svg)](https://github.com/eiei114/pi-skill-playbook/actions/workflows/publish.yml)
+[![npm version](https://img.shields.io/npm/v/pi-skill-playbook.svg)](https://www.npmjs.com/package/pi-skill-playbook)
+[![npm downloads](https://img.shields.io/npm/dt/pi-skill-playbook.svg)](https://www.npmjs.com/package/pi-skill-playbook)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Pi package](https://img.shields.io/badge/Pi-package-blue)](https://github.com/eiei114/pi-skill-playbook)
 
-MVP scope:
+Human-mediated Agent Skill playbooks for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
 
-- `/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/`
+## What this is
 
-Deferred after scaffold:
+Pi Skill Playbook is a Pi extension that guides Agent Skill usage flows with **visible, human-controlled playbooks**. It shows the current workflow step, next recommended skill command, and completion criteria — but never runs skills automatically.
 
-- `/playbook:import-web`
-- `/playbook:record`
+Define ordered skill workflows as YAML playbooks in your project, then drive them step by step from the Pi command palette.
 
-## Install from npm
+## Features
+
+- **Playbook-driven workflows** — Define multi-step skill sequences with named outcomes and transitions in YAML.
+- **Human-mediated** — Every step requires an explicit user action. No hidden automation.
+- **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.
+- **Local run state** — Run state is stored in `.pi/playbook-runs/` inside the target project, never in git.
+
+## Install
+
+### From npm
 
 ```bash
 pi install npm:pi-skill-playbook
 ```
 
-
-## Install from GitHub
+### From GitHub
 
 ```bash
 pi install git:github.com/eiei114/pi-skill-playbook
@@ -39,9 +45,7 @@ Or with a full Git URL:
 pi install git+https://github.com/eiei114/pi-skill-playbook.git
 ```
 
-## Install locally
-
-Clone the repository first, then run Pi from the checkout:
+### Locally (for development)
 
 ```bash
 git clone https://github.com/eiei114/pi-skill-playbook.git
@@ -50,57 +54,143 @@ npm install
 pi -e .
 ```
 
-Or install as a local Pi package:
+## Quick start
 
-```bash
-pi install /path/to/pi-skill-playbook
-```
+1. **Copy a sample playbook** into your project:
 
-## Add a playbook to a project
+   ```bash
+   mkdir -p .pi/playbooks
+   cp node_modules/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/
+   ```
 
-MVP uses manual sample copy:
+2. **Add run state to `.gitignore`** in the target project:
 
-```bash
-mkdir -p .pi/playbooks
-cp /path/to/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/feature-development.yml
-```
+   ```gitignore
+   .pi/playbook-runs/
+   ```
 
-Add personal run state to the target repo's `.gitignore`:
+3. **Start a run** from the Pi TUI:
 
-```gitignore
-.pi/playbook-runs/
-```
+   ```
+   /playbook:list
+   /playbook:start
+   ```
 
-## Use
+   When more than one playbook exists, Pi shows a selector with validation status for each playbook. The run id is generated automatically.
 
-```text
-/playbook:list
-/playbook:start feature-development --run my-feature
-/playbook:done
-/playbook:choose pass
-/playbook:status
-```
+4. **Drive the workflow**:
+
+   ```
+   /skill:grill-with-docs <feature idea>
+   /playbook:done
+   /playbook:choose
+   /playbook:status
+   ```
 
 The widget displays the current step, exact skill command, completion criteria, and outcome labels.
 
-## Auto advance
+## Usage summary
+
+| Command | Description |
+|---|---|
+| `/playbook:list` | List available playbooks with validation status |
+| `/playbook:start` | Select a playbook and start a new run |
+| `/playbook:resume` | Select an active run to resume |
+| `/playbook:status [run-id]` | Show current step and completion criteria |
+| `/playbook:done` | Complete the current step (auto-advances if single outcome) |
+| `/playbook:choose` | Select an outcome for multi-branch steps |
+| `/playbook:cancel` | Select and confirm an active run cancellation |
 
-Playbooks default to `autoAdvance: auto`.
+Legacy explicit-argument forms (`/playbook:start <id>`, `/playbook:resume <run-id>`, `/playbook:choose <outcome>`, `/playbook:cancel <run-id>`, and space-separated `/playbook start`) remain available for scripts and non-interactive use.
 
-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:
+### Auto advance
+
+Playbooks default to `autoAdvance: auto`. When a user explicitly runs the current step's skill with `/skill:<name>`, Pi Skill Playbook injects a short prompt asking the assistant to emit 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>`.
+| Mode | Behavior |
+|---|---|
+| `auto` (default) | Marker can advance single-outcome steps automatically |
+| `suggest` | Marker only suggests `/playbook:done` or `/playbook:choose` |
+| `off` | No prompt injection or completion detection |
+
+## Package contents
 
-Legacy space-separated forms such as `/playbook start` remain available for one release.
+```
+pi-skill-playbook/
+├── extensions/     Pi extension entry point
+├── src/            Domain logic: validation, state, rendering, auto-advance
+├── samples/        Example playbooks (feature-development.yml)
+├── tests/          Node.js test suite
+├── docs/adr/       Architecture decision records
+├── LICENSE         MIT
+└── README.md
+```
 
-Optional playbook setting:
+### Playbook YAML structure
 
 ```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
+version: 1
+id: my-playbook
+name: My Playbook
+entry: first-step
+autoAdvance: auto        # auto | suggest | off
+
+skills:
+  my-skill:
+    role: entry
+
+steps:
+  first-step:
+    primarySkill: my-skill
+    commandHint: "/skill:my-skill <arg>"
+    doneWhen:
+      - Criterion one.
+      - Criterion two.
+    transitions:
+      - outcome: done
+        to: complete        # "complete" ends the run
 ```
+
+See [`samples/feature-development.yml`](samples/feature-development.yml) for a full example.
+
+## Development
+
+```bash
+npm install
+npm run check     # TypeScript type check
+npm test          # Run tests (Node.js built-in test runner + tsx)
+```
+
+Requires Node.js ≥ 24, TypeScript 5.8+, and tsx 4.20+.
+
+## Release
+
+Releases are automated via GitHub Actions:
+
+1. Bump `version` in `package.json` and merge to `main`.
+2. `auto-release.yml` detects the new version, creates a git tag and GitHub Release.
+3. `publish.yml` publishes to npm with provenance.
+
+Manual dispatch is also available from the Actions tab.
+
+## Security
+
+- Run state is local-only (`.pi/playbook-runs/`). No data leaves the machine.
+- The extension does **not** inject system prompts for skill execution. It only adds a short playbook prompt describing the current step, valid outcomes, and expected marker format.
+- No automatic file edits — the extension warns with a `.gitignore` snippet instead of modifying files.
+- Report vulnerabilities via [GitHub Security Advisories](https://github.com/eiei114/pi-skill-playbook/security/advisories/new).
+
+## Links
+
+- [npm package](https://www.npmjs.com/package/pi-skill-playbook)
+- [GitHub repository](https://github.com/eiei114/pi-skill-playbook)
+- [Pi coding agent](https://github.com/earendil-works/pi-coding-agent)
+- [Architecture decisions](docs/adr/)
+
+## License
+
+[MIT](LICENSE)

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,29 @@
+# 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.
+
+## Script-compatible explicit args
+
+Non-interactive scripts can still pass ids explicitly:
+
+```text
+/playbook:start feature-development --run scripted-feature
+/playbook:resume feature-development-20260608120000
+/playbook:choose ready-for-prd
+/playbook:cancel feature-development-20260608120000
+```

package/extensions/index.ts

@@ -33,6 +33,11 @@ type CommandContext = {
   ui?: UiLike;
 };
 
+type SelectOption<T> = {
+  label: string;
+  value: T;
+};
+
 export default function piSkillPlaybook(pi: ExtensionAPI) {
   let completionCwd = process.cwd();
   let pendingSkillInvocation: string | undefined;
@@ -114,7 +119,7 @@ export default function piSkillPlaybook(pi: ExtensionAPI) {
   }
 }
 
-async function handlePlaybookCommand(
+export async function handlePlaybookCommand(
   pi: ExtensionAPI,
   command: string,
   args: string[],
@@ -175,7 +180,12 @@ async function listPlaybooks(pi: ExtensionAPI, cwd: string, ui: UiLike | undefin
 
 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>]");
+  if (!playbookId) {
+    const playbook = await pickPlaybook(pi, cwd, ui);
+    if (!playbook) return;
+    await createAndActivateRun(cwd, playbook, undefined, ui);
+    return;
+  }
 
   const playbook = await findPlaybook(cwd, playbookId);
   if (!playbook) throw new Error(`Playbook '${playbookId}' not found in .pi/playbooks/.`);
@@ -186,6 +196,10 @@ async function startPlaybook(pi: ExtensionAPI, cwd: string, args: string[], ui:
   }
 
   const runName = readFlagValue(args.slice(1), "--run");
+  await createAndActivateRun(cwd, playbook, runName, ui);
+}
+
+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),
@@ -207,7 +221,12 @@ async function startPlaybook(pi: ExtensionAPI, cwd: string, args: string[], ui:
 
 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>");
+  if (!runId) {
+    const run = await pickActiveRun(cwd, ui, "Resume which playbook run?");
+    if (!run) return;
+    await resumeRun(cwd, [run.runId], ui);
+    return;
+  }
   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}.`);
@@ -219,8 +238,12 @@ async function resumeRun(cwd: string, args: string[], ui: UiLike | undefined): P
 }
 
 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]");
+  let runId = explicitRunId;
+  if (!runId) {
+    const run = await pickRunToCancel(cwd, ui);
+    if (!run) return;
+    runId = run.runId;
+  }
   const run = await loadRun(cwd, runId);
   if (!run) throw new Error(`Run '${runId}' not found.`);
 
@@ -281,11 +304,165 @@ async function completeCurrentStep(cwd: string, ui: UiLike | undefined): Promise
 }
 
 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);
+  if (!outcome) {
+    const selected = await pickOutcome(playbook, run, ui);
+    if (!selected) return;
+    outcome = selected.outcome;
+  }
   await advanceRun(cwd, playbook, run, 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. For scripts, use /playbook:start <playbook-id> [--run <name>].", "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. For scripts, pass the run id explicitly.", "error");
+    return undefined;
+  }
+
+  const runs = await getRunCompletionCandidates(cwd, true);
+  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. For scripts, use /playbook:cancel <run-id>.", "error");
+    return undefined;
+  }
+
+  const runs = await getRunCompletionCandidates(cwd, true);
+  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. For scripts, use /playbook:choose <outcome>.", "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> {
   const step = playbook.definition.steps[run.currentStep];
   if (!step) throw new Error(`Current step '${run.currentStep}' is missing.`);
@@ -384,13 +561,13 @@ function usage(): string {
   return [
     "Usage:",
     "/playbook:list",
-    "/playbook:start <playbook-id> [--run <name>]",
-    "/playbook:resume <run-id>",
+    "/playbook:start",
+    "/playbook:resume",
     "/playbook:status [run-id]",
     "/playbook:done",
-    "/playbook:choose <outcome>",
-    "/playbook:cancel [run-id]",
-    "Legacy space-separated /playbook <subcommand> forms remain available for compatibility.",
+    "/playbook:choose",
+    "/playbook:cancel",
+    "Legacy explicit args remain available for scripts: start <playbook-id> [--run <name>], resume <run-id>, choose <outcome>, cancel <run-id>.",
   ].join("\n");
 }
 
@@ -567,5 +744,7 @@ function readFlagValue(args: string[], flag: string): string | undefined {
 
 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.4",
+  "version": "0.2.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"]