Pi Skill Playbook

Human-mediated Agent Skill playbooks for the Pi coding agent.

What this is

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.

Define ordered skill workflows as YAML playbooks in your project, then drive them step by step from the Pi command palette.

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.
• Selection UI — Playbook, run, and outcome selection use the Pi TUI selector instead of memorized ids.
• Record command — Capture explicit skill usage with /playbook:record:* marks and convert the flow into a validated playbook draft.
• Local run state — Run state is stored in .pi/playbook-runs/ inside the target project, never in git.

Install

From npm

pi install npm:pi-skill-playbook

From GitHub

pi install git:github.com/eiei114/pi-skill-playbook

Or with a full Git URL:

pi install git+https://github.com/eiei114/pi-skill-playbook.git

Locally (for development)

git clone https://github.com/eiei114/pi-skill-playbook.git
cd pi-skill-playbook
npm install
pi -e .

Quick start

1. Copy a sample playbook into your project:

   mkdir -p .pi/playbooks
   cp node_modules/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/

2. Add run state to .gitignore in the target project:

   .pi/playbook-runs/
   .pi/playbook-records/

3. Start a run from the Pi TUI:

   /playbook:list
   /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
   /playbook:status

The widget displays the current step, exact skill command, completion criteria, and outcome labels.

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 | 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 | | /playbook:history | Browse completed runs (read-only; active runs use /playbook:resume) | | /playbook:rundiff | Compare recent completed runs with a compact diff summary | | /playbook:record:start <id> [--name <name>] | Start recording an explicit skill flow | | /playbook:record:mark [<skill>] | Mark explicit skill usage (selection UI when omitted) | | /playbook:record:branch <outcome> | Record a branch outcome label before the next skill mark | | /playbook:record:stop | Preview, validate, confirm, and save a recorded playbook draft | | /playbook:record:status | Show the active recording session | | /playbook:import-web [<query>] [--url <url> ...] [--id <id>] | Import an external web workflow into a validated draft |

Core run commands are argument-free. Record and import-web accept optional args as shown above.

Run lifecycle

| State | Stored in | Resume? | Browse with | | --- | --- | --- | --- | | Active | .pi/playbook-runs/<run-id>.json + active.json | Yes — /playbook:resume | /playbook:status while active | | Completed | .pi/playbook-runs/<run-id>.json (history kept) | No — read-only | /playbook:history | | Cancelled | same file, status: cancelled | No | not listed in history |

Finished runs stay on disk for reference; /playbook:history lists compact metadata (playbook name, run id, finished time, final outcome).

Record vs import-web

| Command | Source | When to use | |---|---|---| | /playbook:record:* | Your own explicit skill usage during day-to-day work | Grow playbooks from internal flows you already run | | /playbook:import-web | Web search + URLs | Import external workflow articles with Required Source Trace |

Record never scrapes session logs or infers skills automatically. Import-web complements recording for external sources.

Import-web configuration

/playbook:import-web needs:

• Brave Search for query-based discovery. Set BRAVE_SEARCH_API_KEY (preferred) or BRAVE_API_KEY in the environment before starting Pi.
• An active Pi model provider for model-assisted drafting. The command shows the draft prompt and asks for confirmation before any model request is sent.
• Pi TUI confirmation UI for model drafting and save confirmation.

Happy path: run /playbook:import-web without args, enter a query, pick a search result, confirm the model draft request, then confirm save. You can also pass explicit URLs with --url and optionally pin the playbook id with --id.

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:

PLAYBOOK_OUTCOME: ready-for-prd

| 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 |

Sample playbooks

| Playbook | File | When to use | |---|---|---| | Feature Development | feature-development.yml | Generic product work with standard to-prd / to-issues skills. Good default for non-OSS projects. | | Pi OSS New Extension Delivery | pi-oss-new.yml | Full Pi OSS lane from idea through PR verify and release post. Uses -for-oss skills and vault maintenance skills. | | Pi OSS Bootstrap Only | pi-oss-bootstrap-only.yml | Repo + vault bootstrap, then PRD and issue slicing only. Stops before implementation. | | OSS Maintenance Onboarding | oss-maintenance-onboard.yml | Add a new OSS target to the Multica maintenance operating model. |

Copy one or more files from samples/ into .pi/playbooks/ in the target project. See docs/examples.md for copy-and-start steps.

Package contents

pi-skill-playbook/
├── extensions/     Pi extension entry point
├── src/            Domain logic: validation, state, rendering, auto-advance
├── samples/        Example playbooks (generic + Pi OSS lane)
├── tests/          Node.js test suite
├── docs/           Examples and architecture decision records
├── LICENSE         MIT
└── README.md

Playbook YAML structure

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 for a generic example and samples/pi-oss-new.yml for the Pi OSS delivery lane.

Development

npm install
npm run ci        # Full CI validation (typecheck, tests, package manifest, actions pin check)
npm run check     # TypeScript type check only
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.
• For vulnerability reporting, see SECURITY.md.

Links

• npm package
• GitHub repository
• Pi coding agent
• Roadmap
• Architecture decisions

License

MIT