pi-skill-playbook 0.1.3 → 0.1.5

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,55 +54,141 @@ 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**:
 
-```gitignore
-.pi/playbook-runs/
-```
+   ```
+   /playbook:list
+   /playbook:start feature-development --run my-feature
+   ```
 
-## Use
+4. **Drive the workflow**:
 
-```text
-/playbook list
-/playbook start feature-development --run my-feature
-/playbook done
-/playbook choose pass
-/playbook status
-```
+   ```
+   /skill:grill-with-docs <feature idea>
+   /playbook:done
+   /playbook:choose ready-for-prd
+   /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 <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: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 |
+
+Legacy space-separated forms (`/playbook start`) remain available for compatibility.
 
-Playbooks default to `autoAdvance: auto`.
+### Auto advance
 
-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:
+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
+
+```
+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/extensions/index.ts

@@ -9,6 +9,30 @@ import type { LoadedPlaybook, PlaybookRunState } from "../src/types.js";
 
 const WIDGET_ID = "pi-skill-playbook";
 
+const COMMANDS = [
+  ["list", "list available playbooks"],
+  ["start", "start a playbook run"],
+  ["resume", "resume an active playbook run"],
+  ["status", "show playbook run status"],
+  ["done", "complete the current step"],
+  ["choose", "choose a step outcome"],
+  ["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;
+};
+
 export default function piSkillPlaybook(pi: ExtensionAPI) {
   let completionCwd = process.cwd();
   let pendingSkillInvocation: string | undefined;
@@ -65,44 +89,70 @@ export default function piSkillPlaybook(pi: ExtensionAPI) {
     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");
-        }
+        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) => {
+        try {
+          await handlePlaybookCommand(pi, alias.command, parseArgs(args), ctx);
+        } catch (error) {
+          notify(ctx.hasUI ? ctx.ui : undefined, error instanceof Error ? error.message : String(error), "error");
+        }
+      },
+    });
+  }
+}
+
+async function handlePlaybookCommand(
+  pi: ExtensionAPI,
+  command: string,
+  args: string[],
+  ctx: CommandContext,
+): Promise<void> {
+  const ui = ctx.hasUI ? ctx.ui : undefined;
+
+  switch (command) {
+    case "list":
+      await listPlaybooks(pi, ctx.cwd, ui);
+      return;
+    case "start":
+      await startPlaybook(pi, ctx.cwd, args, ui);
+      return;
+    case "resume":
+      await resumeRun(ctx.cwd, args, ui);
+      return;
+    case "status":
+      await showStatus(ctx.cwd, args[0], ui);
+      return;
+    case "done":
+      await completeCurrentStep(ctx.cwd, ui);
+      return;
+    case "choose":
+      await chooseOutcome(ctx.cwd, args[0], ui);
+      return;
+    case "cancel":
+    case "stop":
+    case "abort":
+      await cancelRun(ctx.cwd, args[0], ui);
+      return;
+    case "import-web":
+    case "record":
+      notify(ui, `/playbook:${command} is deferred after the Core 6 MVP scaffold.`, "warning");
+      return;
+    default:
+      notify(ui, usage(), "error");
+  }
 }
 
 async function listPlaybooks(pi: ExtensionAPI, cwd: string, ui: UiLike | undefined): Promise<void> {
@@ -125,7 +175,7 @@ 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) 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/.`);
@@ -157,7 +207,7 @@ 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) 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}.`);
@@ -170,7 +220,7 @@ 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]");
+  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.`);
 
@@ -231,7 +281,7 @@ 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>");
+  if (!outcome) throw new Error("Usage: /playbook:choose <outcome>");
   const { run, playbook } = await loadActive(cwd);
   await advanceRun(cwd, playbook, run, outcome, ui);
 }
@@ -333,13 +383,14 @@ function notify(ui: UiLike | undefined, message: string, level: "info" | "warnin
 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]",
+    "/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]",
+    "Legacy space-separated /playbook <subcommand> forms remain available for compatibility.",
   ].join("\n");
 }
 
@@ -353,6 +404,26 @@ export async function getPlaybookArgumentCompletions(cwd: string, prefix: string
   }
 }
 
+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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-playbook",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "type": "module",
   "description": "Pi extension for passive, human-mediated Agent Skill playbooks.",
   "keywords": ["pi-package", "pi-extension", "agent-skills", "playbook"],

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: /playbook:choose ${resolved.outcome}`,
     };
   }
 
@@ -101,8 +101,8 @@ export function planCompletion(
       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}'.`,
+        ? `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}'.`,
     };
   }
 
@@ -129,7 +129,7 @@ export function lastAssistantText(messages: unknown[]): string {
 
 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.` };
+    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]!;
@@ -137,12 +137,12 @@ function suggestPlan(step: PlaybookStep, stepId: string): CompletionPlan {
       kind: "suggest",
       outcome: transition.outcome,
       to: transition.to,
-      message: `Completion suspected for step '${stepId}'. Run /playbook done to advance 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(" | ")}`,
+    message: `Completion suspected for step '${stepId}'. Choose outcome: ${step.transitions.map((transition) => `/playbook:choose ${transition.outcome}`).join(" | ")}`,
   };
 }