pi-skill-playbook 0.1.4 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +140 -52
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,33 +1,39 @@
1
1
  # Pi Skill Playbook
2
2
 
3
- Pi Skill Playbook is a Pi extension that guides Agent Skill usage flows with visible, human-mediated playbooks.
3
+ [![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)
4
+ [![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)
5
+ [![npm version](https://img.shields.io/npm/v/pi-skill-playbook.svg)](https://www.npmjs.com/package/pi-skill-playbook)
6
+ [![npm downloads](https://img.shields.io/npm/dt/pi-skill-playbook.svg)](https://www.npmjs.com/package/pi-skill-playbook)
7
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
8
+ [![Pi package](https://img.shields.io/badge/Pi-package-blue)](https://github.com/eiei114/pi-skill-playbook)
4
9
 
5
- MVP scope:
10
+ Human-mediated Agent Skill playbooks for the [Pi coding agent](https://github.com/earendil-works/pi-coding-agent).
6
11
 
7
- - `/playbook:list`
8
- - `/playbook:start <playbook-id> [--run <name>]`
9
- - `/playbook:resume <run-id>`
10
- - `/playbook:status [run-id]`
11
- - `/playbook:done`
12
- - `/playbook:choose <outcome>`
13
- - strict YAML validation
14
- - active run widget below the editor
15
- - marker-based auto advance for single-outcome steps
16
- - local run state in `.pi/playbook-runs/`
12
+ ## What this is
17
13
 
18
- Deferred after scaffold:
14
+ 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.
19
15
 
20
- - `/playbook:import-web`
21
- - `/playbook:record`
16
+ Define ordered skill workflows as YAML playbooks in your project, then drive them step by step from the Pi command palette.
22
17
 
23
- ## Install from npm
18
+ ## Features
19
+
20
+ - **Playbook-driven workflows** — Define multi-step skill sequences with named outcomes and transitions in YAML.
21
+ - **Human-mediated** — Every step requires an explicit user action. No hidden automation.
22
+ - **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.
23
+ - **Active run widget** — Displays current step, skill command, completion criteria, and outcome labels below the editor.
24
+ - **Strict YAML validation** — Playbooks are validated on load for structure, transitions, and skill references.
25
+ - **Tab completion** — Commands, playbook IDs, run IDs, outcomes, and flags all support tab completion.
26
+ - **Local run state** — Run state is stored in `.pi/playbook-runs/` inside the target project, never in git.
27
+
28
+ ## Install
29
+
30
+ ### From npm
24
31
 
25
32
  ```bash
26
33
  pi install npm:pi-skill-playbook
27
34
  ```
28
35
 
29
-
30
- ## Install from GitHub
36
+ ### From GitHub
31
37
 
32
38
  ```bash
33
39
  pi install git:github.com/eiei114/pi-skill-playbook
@@ -39,9 +45,7 @@ Or with a full Git URL:
39
45
  pi install git+https://github.com/eiei114/pi-skill-playbook.git
40
46
  ```
41
47
 
42
- ## Install locally
43
-
44
- Clone the repository first, then run Pi from the checkout:
48
+ ### Locally (for development)
45
49
 
46
50
  ```bash
47
51
  git clone https://github.com/eiei114/pi-skill-playbook.git
@@ -50,57 +54,141 @@ npm install
50
54
  pi -e .
51
55
  ```
52
56
 
53
- Or install as a local Pi package:
57
+ ## Quick start
54
58
 
55
- ```bash
56
- pi install /path/to/pi-skill-playbook
57
- ```
59
+ 1. **Copy a sample playbook** into your project:
58
60
 
59
- ## Add a playbook to a project
61
+ ```bash
62
+ mkdir -p .pi/playbooks
63
+ cp node_modules/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/
64
+ ```
60
65
 
61
- MVP uses manual sample copy:
66
+ 2. **Add run state to `.gitignore`** in the target project:
62
67
 
63
- ```bash
64
- mkdir -p .pi/playbooks
65
- cp /path/to/pi-skill-playbook/samples/feature-development.yml .pi/playbooks/feature-development.yml
66
- ```
68
+ ```gitignore
69
+ .pi/playbook-runs/
70
+ ```
67
71
 
68
- Add personal run state to the target repo's `.gitignore`:
72
+ 3. **Start a run**:
69
73
 
70
- ```gitignore
71
- .pi/playbook-runs/
72
- ```
74
+ ```
75
+ /playbook:list
76
+ /playbook:start feature-development --run my-feature
77
+ ```
73
78
 
74
- ## Use
79
+ 4. **Drive the workflow**:
75
80
 
76
- ```text
77
- /playbook:list
78
- /playbook:start feature-development --run my-feature
79
- /playbook:done
80
- /playbook:choose pass
81
- /playbook:status
82
- ```
81
+ ```
82
+ /skill:grill-with-docs <feature idea>
83
+ /playbook:done
84
+ /playbook:choose ready-for-prd
85
+ /playbook:status
86
+ ```
83
87
 
84
88
  The widget displays the current step, exact skill command, completion criteria, and outcome labels.
85
89
 
86
- ## Auto advance
90
+ ## Usage summary
91
+
92
+ | Command | Description |
93
+ |---|---|
94
+ | `/playbook:list` | List available playbooks with validation status |
95
+ | `/playbook:start <id> [--run <name>]` | Start a new playbook run |
96
+ | `/playbook:resume <run-id>` | Resume a paused active run |
97
+ | `/playbook:status [run-id]` | Show current step and completion criteria |
98
+ | `/playbook:done` | Complete the current step (auto-advances if single outcome) |
99
+ | `/playbook:choose <outcome>` | Choose an outcome for multi-branch steps |
100
+ | `/playbook:cancel [run-id]` | Cancel an active run |
87
101
 
88
- Playbooks default to `autoAdvance: auto`.
102
+ Legacy space-separated forms (`/playbook start`) remain available for compatibility.
89
103
 
90
- 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:
104
+ ### Auto advance
105
+
106
+ 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:
91
107
 
92
108
  ```text
93
109
  PLAYBOOK_OUTCOME: ready-for-prd
94
110
  ```
95
111
 
96
- 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>`.
112
+ | Mode | Behavior |
113
+ |---|---|
114
+ | `auto` (default) | Marker can advance single-outcome steps automatically |
115
+ | `suggest` | Marker only suggests `/playbook:done` or `/playbook:choose` |
116
+ | `off` | No prompt injection or completion detection |
117
+
118
+ ## Package contents
97
119
 
98
- Legacy space-separated forms such as `/playbook start` remain available for one release.
120
+ ```
121
+ pi-skill-playbook/
122
+ ├── extensions/ Pi extension entry point
123
+ ├── src/ Domain logic: validation, state, rendering, auto-advance
124
+ ├── samples/ Example playbooks (feature-development.yml)
125
+ ├── tests/ Node.js test suite
126
+ ├── docs/adr/ Architecture decision records
127
+ ├── LICENSE MIT
128
+ └── README.md
129
+ ```
99
130
 
100
- Optional playbook setting:
131
+ ### Playbook YAML structure
101
132
 
102
133
  ```yaml
103
- autoAdvance: auto # default: marker can advance single-outcome steps
104
- autoAdvance: suggest # marker only suggests /playbook:done or /playbook:choose
105
- autoAdvance: off # no prompt injection or completion detection
134
+ version: 1
135
+ id: my-playbook
136
+ name: My Playbook
137
+ entry: first-step
138
+ autoAdvance: auto # auto | suggest | off
139
+
140
+ skills:
141
+ my-skill:
142
+ role: entry
143
+
144
+ steps:
145
+ first-step:
146
+ primarySkill: my-skill
147
+ commandHint: "/skill:my-skill <arg>"
148
+ doneWhen:
149
+ - Criterion one.
150
+ - Criterion two.
151
+ transitions:
152
+ - outcome: done
153
+ to: complete # "complete" ends the run
106
154
  ```
155
+
156
+ See [`samples/feature-development.yml`](samples/feature-development.yml) for a full example.
157
+
158
+ ## Development
159
+
160
+ ```bash
161
+ npm install
162
+ npm run check # TypeScript type check
163
+ npm test # Run tests (Node.js built-in test runner + tsx)
164
+ ```
165
+
166
+ Requires Node.js ≥ 24, TypeScript 5.8+, and tsx 4.20+.
167
+
168
+ ## Release
169
+
170
+ Releases are automated via GitHub Actions:
171
+
172
+ 1. Bump `version` in `package.json` and merge to `main`.
173
+ 2. `auto-release.yml` detects the new version, creates a git tag and GitHub Release.
174
+ 3. `publish.yml` publishes to npm with provenance.
175
+
176
+ Manual dispatch is also available from the Actions tab.
177
+
178
+ ## Security
179
+
180
+ - Run state is local-only (`.pi/playbook-runs/`). No data leaves the machine.
181
+ - 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.
182
+ - No automatic file edits — the extension warns with a `.gitignore` snippet instead of modifying files.
183
+ - Report vulnerabilities via [GitHub Security Advisories](https://github.com/eiei114/pi-skill-playbook/security/advisories/new).
184
+
185
+ ## Links
186
+
187
+ - [npm package](https://www.npmjs.com/package/pi-skill-playbook)
188
+ - [GitHub repository](https://github.com/eiei114/pi-skill-playbook)
189
+ - [Pi coding agent](https://github.com/earendil-works/pi-coding-agent)
190
+ - [Architecture decisions](docs/adr/)
191
+
192
+ ## License
193
+
194
+ [MIT](LICENSE)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-skill-playbook",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "type": "module",
5
5
  "description": "Pi extension for passive, human-mediated Agent Skill playbooks.",
6
6
  "keywords": ["pi-package", "pi-extension", "agent-skills", "playbook"],