pi-dev 0.1.3 → 0.1.4
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.
- package/README.md +86 -53
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,30 +1,51 @@
|
|
|
1
1
|
# pi-dev
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> **Three slash commands. One finished outcome. Zero ceremony.**
|
|
4
4
|
>
|
|
5
|
-
>
|
|
5
|
+
> An autonomous engineering skill framework for the [pi](https://github.com/badlogic/pi) runtime — built on [Matt Pocock's skills](https://github.com/mattpocock/skills), wrapped in a single entry point, a strict migration gate, and three-layer preferences so the agent runs end-to-end without interrupting you.
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
```bash
|
|
8
|
+
npx pi-dev@latest install
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
That is the whole setup. From here on you talk to the agent, not to a tool palette.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## The pitch
|
|
16
|
+
|
|
17
|
+
Most AI engineering setups give you a drawer full of commands and ask you to remember which one to use, when, and in what order. After a week you stop opening the drawer.
|
|
8
18
|
|
|
9
|
-
|
|
19
|
+
`pi-dev` collapses the drawer into **three commands** and lets the agent decide the rest:
|
|
10
20
|
|
|
11
21
|
```
|
|
12
|
-
/do
|
|
13
|
-
/taste
|
|
14
|
-
/where
|
|
22
|
+
/do — do the engineering work end-to-end
|
|
23
|
+
/taste — view or update your engineering preferences
|
|
24
|
+
/where — recall prior pi sessions for this cwd
|
|
15
25
|
```
|
|
16
26
|
|
|
17
|
-
|
|
27
|
+
Behind `/do` sit eleven specialist skills — `diagnose`, `tdd`, `to-prd`, `to-issues`, `triage`, `grill-with-docs`, `improve-codebase-architecture`, `zoom-out`, `recon-with-vision`, `migrate`, `setup` — chained automatically based on intent (`feature` / `bug` / `perf` / `refactor` / `recon` / `docs` / `triage`) and scope (`nano` / `small` / `medium` / `large`).
|
|
28
|
+
|
|
29
|
+
You ask. It classifies. It executes. It reports.
|
|
30
|
+
|
|
31
|
+
## What you actually get
|
|
32
|
+
|
|
33
|
+
- **One request → one finished outcome.** `/do` runs the right chain to completion: write the PRD, file the slice issues with proper labels, drive TDD per slice, boot the app locally to verify, commit, open the PR.
|
|
34
|
+
- **Preferences as decisions, not prompts.** Anything answered in your global / project / package `preferences.md` is settled. The agent never re-asks. Set `auto-pr=true` once and pushes happen; set `interrupt-on-ambiguity=low` and the agent picks a sensible default and reports it instead of stopping.
|
|
35
|
+
- **A migration gate that won't let you cheat.** `/do` refuses to touch an un-migrated repo. `/migrate` audits `AGENTS.md`, `CLAUDE.md`, scoped agent dirs, handoff systems, and ADR layouts; archives the noise; stamps a marker; and on every re-entry runs drift probes so banned conventions can't sneak back in.
|
|
36
|
+
- **No handoff files. Ever.** State of work lives in three places only — code (git), the issue tracker, and merged preferences. No `docs/handoff/`, no `.scratch/flow/`, no SESSION_*.md littering your repo.
|
|
37
|
+
- **Local-live verification the agent owns.** A one-time playbook captures how to boot your stack. From then on the agent boots it, drives it, and quotes the evidence in the summary. You are not the test runner.
|
|
38
|
+
- **Vertical-slice issues with AI disclaimers baked in.** `/to-issues` produces independently-grabbable tickets — each with acceptance criteria, allowed-touch-set, and out-of-scope — and the disclaimer required by `/triage` lands on every one.
|
|
18
39
|
|
|
19
40
|
## Install
|
|
20
41
|
|
|
21
|
-
Requires Node ≥ 20 and the pi runtime.
|
|
42
|
+
Requires Node ≥ 20 and the [pi runtime](https://github.com/badlogic/pi).
|
|
22
43
|
|
|
23
44
|
```bash
|
|
24
45
|
# Install the skills + seed your global preferences
|
|
25
46
|
npx pi-dev@latest install
|
|
26
47
|
|
|
27
|
-
#
|
|
48
|
+
# Refresh skills only (keeps your preferences as-is)
|
|
28
49
|
npx pi-dev@latest update
|
|
29
50
|
|
|
30
51
|
# See what's installed
|
|
@@ -34,47 +55,65 @@ npx pi-dev list
|
|
|
34
55
|
npx pi-dev doctor
|
|
35
56
|
```
|
|
36
57
|
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
- Copies the skill folders to `~/.pi/agent/skills/` (the directory the pi runtime reads).
|
|
40
|
-
- Seeds `~/.pi/agent/preferences.md` with sensible global defaults — only if you do not already have one.
|
|
58
|
+
`install` copies the skill folders to `~/.pi/agent/skills/` (where the pi runtime looks) and seeds `~/.pi/agent/preferences.md` only if you don't already have one.
|
|
59
|
+
`update` refreshes skill folders but leaves your preferences alone unless you pass `--include-prefs`.
|
|
41
60
|
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
- Refreshes the skill folders.
|
|
45
|
-
- **Does not** overwrite your global preferences. Pass `--include-prefs` if you want to re-seed.
|
|
46
|
-
|
|
47
|
-
## How it works
|
|
61
|
+
## How `/do` actually flows
|
|
48
62
|
|
|
49
63
|
```
|
|
50
|
-
[ /do ]
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
64
|
+
[ /do <your request> ]
|
|
65
|
+
│
|
|
66
|
+
▼
|
|
67
|
+
bootstrap
|
|
68
|
+
├─ load merged preferences (global → project → package)
|
|
69
|
+
├─ check migration marker ──► if missing, hand off to /migrate
|
|
70
|
+
├─ taboo lint (handoff drift, banned labels)
|
|
71
|
+
▼
|
|
72
|
+
classify intent + scope
|
|
73
|
+
▼
|
|
74
|
+
execute the matching chain
|
|
75
|
+
├─ feature × small → (zoom-out?) → tdd → (improve-codebase-architecture?)
|
|
76
|
+
├─ feature × large → zoom-out → grill-with-docs → to-prd → to-issues → triage → tdd per slice → improve-codebase-architecture
|
|
77
|
+
├─ bug × any → diagnose → tdd (regression) → improve-codebase-architecture
|
|
78
|
+
├─ recon × any → recon-with-vision → (to-prd / to-issues)
|
|
79
|
+
└─ … (full table in skills/do/SKILL.md)
|
|
80
|
+
▼
|
|
81
|
+
live-verify locally (agent boots and drives the stack)
|
|
82
|
+
▼
|
|
83
|
+
side effects per prefs (commit, push, open PR, file issues, label)
|
|
84
|
+
▼
|
|
85
|
+
one-screen final summary
|
|
55
86
|
```
|
|
56
87
|
|
|
57
|
-
The first time you run `/do` in a new repo, the gate
|
|
88
|
+
The first time you run `/do` in a new repo, the migration gate fires:
|
|
58
89
|
|
|
59
|
-
1. **`/migrate`**
|
|
60
|
-
2. **`/setup`**
|
|
61
|
-
3. **`/taste`**
|
|
90
|
+
1. **`/migrate`** normalises `AGENTS.md`, archives handoff systems, locks them out via `.gitignore`, stamps the marker.
|
|
91
|
+
2. **`/setup`** scaffolds `docs/agents/{issue-tracker,triage-labels,domain}.md`.
|
|
92
|
+
3. **`/taste`** auto-detects project signals, asks only where the project diverges from your global preferences, writes `docs/agents/preferences.md`.
|
|
62
93
|
|
|
63
|
-
After that
|
|
94
|
+
After that, `/do` runs uninterrupted.
|
|
64
95
|
|
|
65
|
-
## Preferences
|
|
96
|
+
## Preferences: three layers, last write wins
|
|
66
97
|
|
|
67
98
|
```
|
|
68
|
-
~/.pi/agent/preferences.md # global
|
|
69
|
-
docs/agents/preferences.md # project
|
|
70
|
-
packages/<pkg>/preferences.md # package
|
|
99
|
+
~/.pi/agent/preferences.md # global — your engineering taste
|
|
100
|
+
docs/agents/preferences.md # project — overrides for this repo
|
|
101
|
+
packages/<pkg>/preferences.md # package — overrides for this subtree (optional)
|
|
71
102
|
```
|
|
72
103
|
|
|
73
|
-
Skills merge
|
|
104
|
+
Skills merge in that order. Edit any layer directly, or use `/taste` for a guided pass. The keys that move the needle most:
|
|
105
|
+
|
|
106
|
+
| key | what it controls |
|
|
107
|
+
| --- | --- |
|
|
108
|
+
| `interrupt-on-ambiguity` | how willing the agent is to ask vs. pick a default and report it |
|
|
109
|
+
| `change-budget` | how big a chunk a single `/do` run is allowed to swallow |
|
|
110
|
+
| `auto-create-issues` / `auto-apply-labels` | whether tracker side-effects happen automatically |
|
|
111
|
+
| `auto-commit-per-slice` / `auto-pr` | how aggressively work lands on `main` |
|
|
112
|
+
| `local-live-policy` / `ops-live-policy` | when the agent boots locally vs. probes prod |
|
|
74
113
|
|
|
75
114
|
## What's a skill?
|
|
76
115
|
|
|
77
|
-
|
|
116
|
+
A directory with a `SKILL.md`. That's the whole format. The pi runtime reads the directory name and the markdown frontmatter and exposes the skill as `/<name>`. No code, no plugin API — just instructions for the agent, version-controlled like any other prose.
|
|
78
117
|
|
|
79
118
|
## Credits
|
|
80
119
|
|
|
@@ -82,12 +121,12 @@ The engineering discipline encoded here — `tdd`, `diagnose`, `to-prd`, `to-iss
|
|
|
82
121
|
|
|
83
122
|
This package adds:
|
|
84
123
|
|
|
85
|
-
-
|
|
86
|
-
-
|
|
87
|
-
-
|
|
88
|
-
-
|
|
124
|
+
- **`do`** — a one-shot orchestrator that picks the right chain
|
|
125
|
+
- **`migrate`** — a strict gate that normalises any repo into the canonical shape and probes for drift on every re-entry
|
|
126
|
+
- **`taste`** — three-layer preferences with project-aware onboarding
|
|
127
|
+
- **`where`** — pi-session recall for multi-session work
|
|
89
128
|
|
|
90
|
-
If
|
|
129
|
+
If these skills earn their keep for you, please support the upstream:
|
|
91
130
|
|
|
92
131
|
- Matt Pocock — https://www.mattpocock.com
|
|
93
132
|
- pi runtime — https://github.com/badlogic/pi
|
|
@@ -96,21 +135,15 @@ If you find these skills useful, support the upstream:
|
|
|
96
135
|
|
|
97
136
|
Versioning, changelog, tagging, and npm publishing are fully automated:
|
|
98
137
|
|
|
99
|
-
1. Land changes on `main` using **Conventional Commits** (`feat:`, `fix:`,
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
3. Merge the Release PR. release-please tags the commit and creates a GitHub
|
|
104
|
-
Release.
|
|
105
|
-
4. The `Release` workflow rebuilds, retests, and runs `npm publish --access
|
|
106
|
-
public` automatically.
|
|
138
|
+
1. Land changes on `main` using **Conventional Commits** (`feat:`, `fix:`, `perf:`, `refactor:`, `docs:`, `chore:`).
|
|
139
|
+
2. [release-please](https://github.com/googleapis/release-please) opens or updates a **Release PR** that bumps the version and writes `CHANGELOG.md`.
|
|
140
|
+
3. Merge the Release PR. release-please tags the commit and creates a GitHub Release.
|
|
141
|
+
4. The `Release` workflow rebuilds, retests, and runs `npm publish --access public` automatically.
|
|
107
142
|
|
|
108
143
|
Required one-time setup (maintainer):
|
|
109
144
|
|
|
110
|
-
- Add an `NPM_TOKEN` repository secret with a granular publish token from
|
|
111
|
-
|
|
112
|
-
- If you flip the repo to public later, add `--provenance` to the publish
|
|
113
|
-
command in `.github/workflows/release.yml` for sigstore attestation.
|
|
145
|
+
- Add an `NPM_TOKEN` repository secret with a granular publish token from npmjs.com (read + write, 2FA bypass enabled).
|
|
146
|
+
- If the repo becomes public, add `--provenance` to the publish command in `.github/workflows/release.yml` for sigstore attestation.
|
|
114
147
|
|
|
115
148
|
## License
|
|
116
149
|
|