principal-pi-skills 2.3.0 → 2.4.0
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/AGENTS.md +8 -3
- package/CHANGELOG.md +106 -3
- package/README.md +43 -21
- package/agents/debug.md +3 -1
- package/agents/plan.md +1 -0
- package/agents/principal-debug.md +3 -1
- package/agents/principal-plan.md +1 -0
- package/agents/principal-review.md +2 -1
- package/agents/review.md +2 -1
- package/architect/SKILL.md +1 -0
- package/build/SKILL.md +1 -0
- package/debug/SKILL.md +2 -1
- package/decide/SKILL.md +1 -0
- package/git-ops/SKILL.md +1 -0
- package/package.json +1 -1
- package/plan/SKILL.md +1 -0
- package/prompts/principal-bugfix.md +1 -1
- package/prompts/principal-feature.md +1 -1
- package/review/SKILL.md +2 -1
- package/scripts/install-agents.mjs +13 -2
- package/scripts/snapshot-workspace.mjs +32 -5
package/AGENTS.md
CHANGED
|
@@ -107,12 +107,17 @@ to every output.
|
|
|
107
107
|
|
|
108
108
|
## Setup (pi)
|
|
109
109
|
|
|
110
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.
|
|
110
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.1` — registers the
|
|
111
111
|
skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
|
|
112
112
|
manifest. Install a tag, not a branch.
|
|
113
|
-
2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent
|
|
114
|
-
|
|
113
|
+
2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
|
|
114
|
+
inside pi itself — nothing to vendor) and the agent definitions installed once:
|
|
115
|
+
`npx -p principal-pi-skills principal-pi-agents install`. It copies real
|
|
115
116
|
files into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses to overwrite
|
|
116
117
|
anything it did not install.
|
|
118
|
+
A delegated agent runs on the pi config's `defaultProvider`/`defaultModel`, **not** the
|
|
119
|
+
`--provider`/`--model` you gave the parent: the extension forwards `--model` only when an
|
|
120
|
+
agent's frontmatter names one, and these deliberately do not. If delegations fail to
|
|
121
|
+
authenticate while the parent session is fine, that mismatch is the reason.
|
|
117
122
|
3. Without the extension, everything runs inline via the skills; the How column above
|
|
118
123
|
simply collapses to "inline".
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,109 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [2.4.0] — 2026-08-17
|
|
10
|
+
|
|
11
|
+
**Added** — every skill now declares an `allowed-tools` capability ceiling, which
|
|
12
|
+
[pi-daddy](https://github.com/mojomanyana/pi-daddy) enforces as a real `--tools` allowlist in a
|
|
13
|
+
separate OS process. Four are read-only (`decide`, `architect`, `plan`, plus nothing else that can
|
|
14
|
+
modify anything); three hold `bash` (`review`, `debug`, `git-ops`); `build` alone holds `edit` and
|
|
15
|
+
`write`. Reasoning and the rejected alternative: [docs/DECISION-capability-ceilings.md](docs/DECISION-capability-ceilings.md).
|
|
16
|
+
|
|
17
|
+
**Decided** — `decide`, `architect` and `plan` return their document as text rather than writing a
|
|
18
|
+
file. pi-daddy governs tools and never paths, so `Write(docs/**)` is not expressible — verified in
|
|
19
|
+
its source, where a path-scoped entry yields *zero* capabilities plus a refusal flag rather than a
|
|
20
|
+
broad write. Granting these three a real `write` would have meant unrestricted filesystem access in
|
|
21
|
+
order to produce a document their own bodies already define as a message, and would have emptied the
|
|
22
|
+
read-only tier entirely. `build/SKILL.md` already said this: *"You are the only phase that writes
|
|
23
|
+
durably. Plan reads."*
|
|
24
|
+
|
|
25
|
+
**Fixed** — `agents/debug.md` declared no `tools:` key, and in pi-subagents an absent `tools:` means
|
|
26
|
+
the *full default toolset*. The debug twin was silently the most powerful of the three while `plan`
|
|
27
|
+
and `review` declared theirs. It now declares `read, grep, find, ls, bash` in both spellings.
|
|
28
|
+
|
|
29
|
+
**Corrected** — the integration handoff proposed `Read, Grep, Glob` for `review` on the grounds that
|
|
30
|
+
its description says *"Reports findings; never edits"*. That string appears nowhere in this
|
|
31
|
+
repository, and `review/SKILL.md:58-68` requires the opposite: it creates a disposable worktree and
|
|
32
|
+
runs the tests in it. Denying `bash` would have made every review return `UNVERIFIED` — which
|
|
33
|
+
review's own body calls "not a soft approve". The handoff's `Glob` is also unknown to pi, whose
|
|
34
|
+
built-ins are `bash, edit, edit-diff, find, grep, ls, parallel, read, write`; six of the seven
|
|
35
|
+
proposed ceilings carried it, and would have been refused as written.
|
|
36
|
+
|
|
37
|
+
**Fixed upstream** — declaring `allowed-tools` initially took `npm run lint:skills` from 2 stale
|
|
38
|
+
findings to 22, because skill-harness hashed the whole `SKILL.md` and so charged a paid re-wave for
|
|
39
|
+
a frontmatter key no graded run can observe. Reported and fixed in skill-harness 0.8.0, which
|
|
40
|
+
digests a prompt document as body plus model-visible frontmatter. `restamp` then upgraded the
|
|
41
|
+
committed runs — 202 examined, 18 upgraded, 122 correctly unprovable — bringing this branch back to
|
|
42
|
+
the pre-change baseline of 57 findings, 2 stale.
|
|
43
|
+
|
|
44
|
+
**Added** — a fourth severity in `scripts/lint-skills.mjs`, declared in
|
|
45
|
+
`docs/validation/record-artifacts.txt`: a staleness finding whose *record* cannot be proven but
|
|
46
|
+
whose *stimulus* is vouched for by a checkable assertion. It covers the two remaining `debug/A6`
|
|
47
|
+
findings, which predate this work and fail on `main` today: a `vitest` cache left by a hand
|
|
48
|
+
authoring run was hashed into the 2026-08-10 fixture digests and no longer exists, so no digest of
|
|
49
|
+
those runs can be proven — while `git diff` shows the tracked stimulus byte-identical and `rescore`
|
|
50
|
+
reproduces the published grades exactly, 0 verdicts moved.
|
|
51
|
+
|
|
52
|
+
Deliberately not folded into `unpublished-cells.txt`: that file covers cells with no claim to
|
|
53
|
+
protect, and these publish. Entries here match on three tokens (cell, model, and the source vouched
|
|
54
|
+
for) rather than two, so one cannot swallow a different kind of drift on the same cell — verified: a
|
|
55
|
+
one-word body edit to `debug/SKILL.md` still blocks. Dead entries fail the build, so a re-run
|
|
56
|
+
retires the exemption rather than quietly extending it. It is the weakest of the four severities and
|
|
57
|
+
says so: a human standing where a measurement used to.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## [2.3.1] — 2026-08-10
|
|
62
|
+
|
|
63
|
+
A defect-fix release. 2.3.0 shipped three defects that a second independent review found,
|
|
64
|
+
all of which made a documented command either do nothing or do damage. **If you installed
|
|
65
|
+
2.3.0, upgrade** — its `principal-pi-workspace remove` can delete a directory you hand it.
|
|
66
|
+
|
|
67
|
+
**Fixed** — `principal-pi-workspace remove` deleted any path it was given. `git worktree
|
|
68
|
+
remove` fails for anything that is not a linked worktree — including your main checkout —
|
|
69
|
+
and the fallback was an unguarded recursive delete that printed `removed` and exited 0.
|
|
70
|
+
Verified destroying a directory of uncommitted work. The path comes from an LLM following a
|
|
71
|
+
contract, so "the caller passes a sane argument" was never a safe assumption. It now refuses
|
|
72
|
+
anything that is neither a worktree of the repository nor a `ppw-*` snapshot under the temp
|
|
73
|
+
directory.
|
|
74
|
+
|
|
75
|
+
**Fixed** — both documented `npx` invocations resolved to nonexistent packages.
|
|
76
|
+
`npx principal-pi-agents install` and `npx principal-pi-workspace create` ask npm for a
|
|
77
|
+
*package* of that name; the bins belong to `principal-pi-skills`. Both returned E404. The
|
|
78
|
+
consequence was silent rather than loud: the agent install wrote nothing, so workflows
|
|
79
|
+
degraded to inline self-review with no attributable error, and every review/debug agent got
|
|
80
|
+
E404 where a disposable workspace should have been — leaving the workspace-isolation feature
|
|
81
|
+
inert for every installed user while the contracts forbade verifying in the caller's tree.
|
|
82
|
+
The correct form is `npx -p principal-pi-skills <bin>`, now used in all 14 files that carried
|
|
83
|
+
it.
|
|
84
|
+
|
|
85
|
+
**Fixed** — the agent installer's ownership record. Files that were already byte-identical
|
|
86
|
+
were skipped without being recorded in the manifest, so `uninstall` was a permanent no-op for
|
|
87
|
+
them. `check` also verified only what the current invocation would install, reporting green
|
|
88
|
+
while previously-installed generic aliases rotted.
|
|
89
|
+
|
|
90
|
+
**Fixed** — two `debug` fixtures shipped already-fixed code. D1's `reduce` had gained an
|
|
91
|
+
initial value and an empty-cart test, so the **critical** D1 scenario could not reproduce the
|
|
92
|
+
failure its checklist grades; A5's parser had gained the guard its scenario asks the model to
|
|
93
|
+
add, so it could not fail. Both restored. The corruption reached git through a blanket
|
|
94
|
+
`git add -A` that swept up fixtures a local `vitest` run had rewritten — which also tracked
|
|
95
|
+
two `node_modules/.vite` caches that churn the fixture source hash. Those are untracked and
|
|
96
|
+
`node_modules/` is now ignored.
|
|
97
|
+
|
|
98
|
+
**Changed** — `debug` and `review` scorecard cells were **withdrawn** pending a re-run.
|
|
99
|
+
debug's were measured against the corrupted fixtures; review's contract changed in this
|
|
100
|
+
release. A withdrawn cell publishes nothing rather than a number that measured something
|
|
101
|
+
else. **That re-run has since landed** (`release-3c`, after this version was published):
|
|
102
|
+
`debug` 9/11 on DeepSeek and 11/11 · SHIP on GLM, `review` 21/21 · SHIP on both. Both cells
|
|
103
|
+
are published again, which takes the board to all seven skills shipping on at least one
|
|
104
|
+
model — see `docs/validation/VALIDATION.md` for the current numbers, which this entry does
|
|
105
|
+
not restate.
|
|
106
|
+
|
|
107
|
+
**Note on verification.** 2.3.0's bins were reported as "verified working from the published
|
|
108
|
+
artifact". That check invoked `./node_modules/.bin/<name>`, which is a different resolution
|
|
109
|
+
path from the documented command — the same class of error as testing a CLI by importing its
|
|
110
|
+
module. The install tests now exercise the documented invocation.
|
|
111
|
+
|
|
9
112
|
## [2.3.0] — 2026-08-09
|
|
10
113
|
|
|
11
114
|
The release that made the installed product real: namespaced commands and agents, generated
|
|
@@ -59,8 +162,8 @@ documented command silently do nothing or do damage:
|
|
|
59
162
|
|
|
60
163
|
- **Both CLIs were no-ops when installed.** The main-module guard compared
|
|
61
164
|
`import.meta.url` against an unresolved `process.argv[1]`. npm links bins as symlinks, so
|
|
62
|
-
for every real user the comparison was false: `npx principal-pi-agents install` printed
|
|
63
|
-
nothing and exited 0, and so did `npx principal-pi-workspace create`. Exit 0 with no output
|
|
165
|
+
for every real user the comparison was false: `npx -p principal-pi-skills principal-pi-agents install` printed
|
|
166
|
+
nothing and exited 0, and so did `npx -p principal-pi-skills principal-pi-workspace create`. Exit 0 with no output
|
|
64
167
|
reads as success, so the agents never installed and debug/review got an empty path where a
|
|
65
168
|
worktree should be — silently losing the isolation this release is built around.
|
|
66
169
|
- **`snapshot-workspace` dropped its own subcommand** whenever `--repo` was absent: the
|
|
@@ -89,7 +192,7 @@ in every developer test and broken for every user.
|
|
|
89
192
|
**Fixed** — the workspace helper is reachable from an installed package. The contracts said
|
|
90
193
|
`node scripts/snapshot-workspace.mjs`, a relative path that resolves in this checkout and
|
|
91
194
|
nowhere else; debug and review would have found no helper and fallen back to a read-only
|
|
92
|
-
diagnosis for the wrong reason. It is now a bin entry, `npx principal-pi-workspace`. The
|
|
195
|
+
diagnosis for the wrong reason. It is now a bin entry, `npx -p principal-pi-skills principal-pi-workspace`. The
|
|
93
196
|
packaging step is what surfaced it.
|
|
94
197
|
|
|
95
198
|
**Removed** — `docs/superpowers/` (a completed cleanup plan and its design spec, referenced
|
package/README.md
CHANGED
|
@@ -46,13 +46,13 @@ around.
|
|
|
46
46
|
|
|
47
47
|
| Skill | What it does | How it runs | Words |
|
|
48
48
|
|---|---|---|---|
|
|
49
|
-
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline |
|
|
50
|
-
| `architect` | System design from measurable drivers; significant or irreversible technical choices. The decision record is a section of the output, not a separate artifact | inline |
|
|
51
|
-
| `plan` | A task turned into ordered steps and per-step specs a builder can execute without making load-bearing decisions. Writes no code | subagent (`agents/principal-plan.md`,
|
|
52
|
-
| `build` | Test-first implementation — code proven by a test you watched fail | inline |
|
|
53
|
-
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`,
|
|
54
|
-
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`,
|
|
55
|
-
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated |
|
|
49
|
+
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 852 |
|
|
50
|
+
| `architect` | System design from measurable drivers; significant or irreversible technical choices. The decision record is a section of the output, not a separate artifact | inline | 1093 |
|
|
51
|
+
| `plan` | A task turned into ordered steps and per-step specs a builder can execute without making load-bearing decisions. Writes no code | subagent (`agents/principal-plan.md`, 1365) or inline | 1155 |
|
|
52
|
+
| `build` | Test-first implementation — code proven by a test you watched fail | inline | 976 |
|
|
53
|
+
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1323) or inline | 1295 |
|
|
54
|
+
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1347) or inline | 1214 |
|
|
55
|
+
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1898 |
|
|
56
56
|
|
|
57
57
|
Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
|
|
58
58
|
routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is that
|
|
@@ -69,11 +69,13 @@ contracts/{plan,review,debug}.md.tmpl the SOURCE for all of the above — edit h
|
|
|
69
69
|
prompts/principal-{feature,bugfix}.md the two workflow spines (/feature, /bugfix are aliases)
|
|
70
70
|
scripts/ generator, agent installer, and the checks behind `npm test`
|
|
71
71
|
tests/{unit,install}/ unit + clean-home install tests (node:test, no dependencies)
|
|
72
|
+
tests/e2e/run-e2e.sh live workflow cells: both spines, with and without subagents
|
|
72
73
|
<skill>/tests/specification.yaml skill-harness scenarios (ship bar, critical gates)
|
|
73
74
|
<skill>/tests/fixtures/<ID>/ seeded repo for one scenario (git-ops, build, debug)
|
|
74
75
|
<skill>/tests/results/…/results.yaml committed run evidence (Opus-judged)
|
|
75
76
|
AGENTS.md routing + dispatch reference (ships, but pi does not auto-load it)
|
|
76
77
|
CHANGELOG.md release history
|
|
78
|
+
docs/HANDOFF.md current state, what is open, standing hazards — read first
|
|
77
79
|
docs/validation/ how the skills are measured — scorecard, run manifest
|
|
78
80
|
docs/evidence/ per-judgment and per-rep records behind the scorecard
|
|
79
81
|
docs/demos/ the chains running end to end, repo-verified
|
|
@@ -84,21 +86,35 @@ docs/demos/ the chains running end to end, repo-verifi
|
|
|
84
86
|
1. **Skills + prompts** — install an immutable tag, not a branch:
|
|
85
87
|
|
|
86
88
|
```
|
|
87
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.
|
|
89
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.1
|
|
88
90
|
```
|
|
89
91
|
|
|
92
|
+
**Do not install `2.3.0`** — it is deprecated on npm for a destructive defect: its
|
|
93
|
+
`principal-pi-workspace remove` deletes any path handed to it, including your checkout,
|
|
94
|
+
and reports success. `2.3.1` is the lowest safe version.
|
|
95
|
+
|
|
90
96
|
The `pi` manifest registers the seven skills and the `/principal-feature` and
|
|
91
97
|
`/principal-bugfix` commands (plus the deprecated `/feature` and `/bugfix` aliases).
|
|
92
98
|
Unpinned `main` moves under you: the skills' behavior is what the committed scorecard
|
|
93
|
-
measured, and a tag is what keeps those two the same thing. Drop the `@v2.3.
|
|
99
|
+
measured, and a tag is what keeps those two the same thing. Drop the `@v2.3.1` only if
|
|
94
100
|
you want whatever `main` currently holds, measured or not.
|
|
95
|
-
2. **Subagents (optional).**
|
|
96
|
-
|
|
97
|
-
|
|
101
|
+
2. **Subagents (optional).** The extension ships **inside pi itself**, so there is nothing
|
|
102
|
+
to clone. Copy its `index.ts` and `agents.ts` into `~/.pi/agent/extensions/subagent/`
|
|
103
|
+
from wherever your pi lives:
|
|
104
|
+
|
|
105
|
+
```
|
|
106
|
+
# installed from npm — the path that applies to most people:
|
|
107
|
+
EXT="$(dirname "$(readlink -f "$(command -v pi)")")/../examples/extensions/subagent"
|
|
108
|
+
mkdir -p ~/.pi/agent/extensions/subagent
|
|
109
|
+
cp "$EXT/index.ts" "$EXT/agents.ts" ~/.pi/agent/extensions/subagent/
|
|
110
|
+
```
|
|
111
|
+
|
|
112
|
+
In a pi-mono *source* checkout the same files are at
|
|
113
|
+
`packages/coding-agent/examples/extensions/subagent`. Then install the agent definitions:
|
|
98
114
|
|
|
99
115
|
```
|
|
100
|
-
npx principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
|
|
101
|
-
npx principal-pi-agents check # verify they are present and current
|
|
116
|
+
npx -p principal-pi-skills principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
|
|
117
|
+
npx -p principal-pi-skills principal-pi-agents check # verify they are present and current
|
|
102
118
|
```
|
|
103
119
|
|
|
104
120
|
It installs `principal-plan`, `principal-review` and `principal-debug` as **real files,
|
|
@@ -111,10 +127,16 @@ docs/demos/ the chains running end to end, repo-verifi
|
|
|
111
127
|
Tool restriction is structural, in the agents' frontmatter: `plan` is read-only;
|
|
112
128
|
`review` adds `bash` only to run tests; `debug` gets the full toolset.
|
|
113
129
|
|
|
114
|
-
The extension steps were last run end to end against **pi 0.
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
someone else's repo
|
|
130
|
+
The extension steps were last run end to end against **pi 0.83.0** (2026-08-11), by the
|
|
131
|
+
live workflow E2E cells in `tests/e2e/run-e2e.sh` — both `× subagents present` cells
|
|
132
|
+
delegate to `principal-plan`/`principal-review`/`principal-debug` and pass. Upstream is
|
|
133
|
+
someone else's repo, so if the file names move, that copy step is the thing to re-check.
|
|
134
|
+
|
|
135
|
+
One trap worth knowing if you run subagents on a non-default provider: the extension
|
|
136
|
+
passes `--model` to the child `pi` only when an agent's frontmatter names one. Ours
|
|
137
|
+
deliberately do not, so a delegated agent uses your pi config's `defaultProvider` /
|
|
138
|
+
`defaultModel` — **not** whatever `--provider`/`--model` you passed the parent. If
|
|
139
|
+
delegations fail to authenticate while the parent is fine, that mismatch is why.
|
|
118
140
|
3. **Without the extension everything still works.** The workflows detect that delegation is
|
|
119
141
|
unavailable and run each phase inline instead. That is a supported configuration, not a
|
|
120
142
|
degraded one — with one honest caveat: inline review is *self-review*. It sees the
|
|
@@ -193,13 +215,13 @@ follow-up rather than a published column in the current round.
|
|
|
193
215
|
|---|---|---|---|
|
|
194
216
|
| architect | 13/14 · 93% | **14/14 · 100% SHIP** | — *(deferred)* |
|
|
195
217
|
| build | **9/9 · 100% SHIP** | **9/9 · 100% SHIP** | — *(deferred)* |
|
|
196
|
-
| debug | 9/11 · 82% |
|
|
218
|
+
| debug | 9/11 · 82% | **11/11 · 100% SHIP** | — *(deferred)* |
|
|
197
219
|
| decide | **12/12 · 100% SHIP** | **12/12 · 100% SHIP** | — *(deferred)* |
|
|
198
220
|
| git-ops | 18/19 · 95% | **19/19 · 100% SHIP** | — *(deferred)* |
|
|
199
221
|
| plan | 8/12 · 67% | **12/12 · 100% SHIP** | — *(deferred)* |
|
|
200
|
-
| review |
|
|
222
|
+
| review | **21/21 · 100% SHIP** | **21/21 · 100% SHIP** | — *(deferred)* |
|
|
201
223
|
|
|
202
|
-
**
|
|
224
|
+
**All seven skills ship on at least one model.** `decide` is new to that list — it
|
|
203
225
|
previously held at 92% on every model, failing exactly one boundary scenario each, and shipped
|
|
204
226
|
nowhere; it is now 12/12 on both. `build` went 7/9 → 9/9 on DeepSeek.
|
|
205
227
|
|
package/agents/debug.md
CHANGED
|
@@ -5,6 +5,8 @@ description: >
|
|
|
5
5
|
a crash, a CI or lint error — "why is this failing", "find the bug", "debug this", "it
|
|
6
6
|
crashes when", "works on my machine". Not for writing new features or fixing a bug
|
|
7
7
|
whose cause is already known (build).
|
|
8
|
+
tools: read, grep, find, ls, bash
|
|
9
|
+
allowed-tools: read, grep, find, ls, bash
|
|
8
10
|
---
|
|
9
11
|
|
|
10
12
|
# Debug — Hypothesis Before Fix
|
|
@@ -32,7 +34,7 @@ unknown one; the harder the bug, the stricter the loop.
|
|
|
32
34
|
file:line because <observed evidence> implies <cause>"; test the cheapest first.
|
|
33
35
|
4. **Probe — in a workspace you own.** One smallest experiment per hypothesis: a log line,
|
|
34
36
|
an assertion, a narrowed test. One change at a time. Probing edits code, so do it in a
|
|
35
|
-
disposable copy, never the caller's checkout: `npx principal-pi-workspace create`
|
|
37
|
+
disposable copy, never the caller's checkout: `npx -p principal-pi-skills principal-pi-workspace create`
|
|
36
38
|
prints a throwaway worktree holding their exact working state (minus anything git
|
|
37
39
|
ignores). Work there, then `remove` it. That keeps "probes are temporary" structurally,
|
|
38
40
|
which nobody manages by hand under a failing build.
|
package/agents/plan.md
CHANGED
|
@@ -5,6 +5,8 @@ description: >
|
|
|
5
5
|
a crash, a CI or lint error — "why is this failing", "find the bug", "debug this", "it
|
|
6
6
|
crashes when", "works on my machine". Not for writing new features or fixing a bug
|
|
7
7
|
whose cause is already known (build).
|
|
8
|
+
tools: read, grep, find, ls, bash
|
|
9
|
+
allowed-tools: read, grep, find, ls, bash
|
|
8
10
|
---
|
|
9
11
|
|
|
10
12
|
# Debug — Hypothesis Before Fix
|
|
@@ -32,7 +34,7 @@ unknown one; the harder the bug, the stricter the loop.
|
|
|
32
34
|
file:line because <observed evidence> implies <cause>"; test the cheapest first.
|
|
33
35
|
4. **Probe — in a workspace you own.** One smallest experiment per hypothesis: a log line,
|
|
34
36
|
an assertion, a narrowed test. One change at a time. Probing edits code, so do it in a
|
|
35
|
-
disposable copy, never the caller's checkout: `npx principal-pi-workspace create`
|
|
37
|
+
disposable copy, never the caller's checkout: `npx -p principal-pi-skills principal-pi-workspace create`
|
|
36
38
|
prints a throwaway worktree holding their exact working state (minus anything git
|
|
37
39
|
ignores). Work there, then `remove` it. That keeps "probes are temporary" structurally,
|
|
38
40
|
which nobody manages by hand under a failing build.
|
package/agents/principal-plan.md
CHANGED
|
@@ -7,6 +7,7 @@ description: >
|
|
|
7
7
|
test quality, security) and simplicity (dead code, needless abstraction, unneeded
|
|
8
8
|
dependencies).
|
|
9
9
|
tools: read, grep, find, ls, bash
|
|
10
|
+
allowed-tools: read, grep, find, ls, bash
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Review — Correctness and Simplicity, One Pass
|
|
@@ -66,7 +67,7 @@ ships is a failed review.
|
|
|
66
67
|
path. The strongest check is often destructive — revert the fix and confirm the
|
|
67
68
|
regression test goes red, break an input and watch the guard fire — so do all of it in a
|
|
68
69
|
disposable copy, never in the caller's checkout:
|
|
69
|
-
`npx principal-pi-workspace create` prints a throwaway worktree carrying their
|
|
70
|
+
`npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree carrying their
|
|
70
71
|
exact working state (staged, unstaged, untracked, minus anything git ignores). Work
|
|
71
72
|
there, then `remove` it. The caller must find their tree byte-for-byte as they left it —
|
|
72
73
|
they are still working in it, and a file you "just" reverted is one they may be editing.
|
package/agents/review.md
CHANGED
|
@@ -7,6 +7,7 @@ description: >
|
|
|
7
7
|
test quality, security) and simplicity (dead code, needless abstraction, unneeded
|
|
8
8
|
dependencies).
|
|
9
9
|
tools: read, grep, find, ls, bash
|
|
10
|
+
allowed-tools: read, grep, find, ls, bash
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Review — Correctness and Simplicity, One Pass
|
|
@@ -66,7 +67,7 @@ ships is a failed review.
|
|
|
66
67
|
path. The strongest check is often destructive — revert the fix and confirm the
|
|
67
68
|
regression test goes red, break an input and watch the guard fire — so do all of it in a
|
|
68
69
|
disposable copy, never in the caller's checkout:
|
|
69
|
-
`npx principal-pi-workspace create` prints a throwaway worktree carrying their
|
|
70
|
+
`npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree carrying their
|
|
70
71
|
exact working state (staged, unstaged, untracked, minus anything git ignores). Work
|
|
71
72
|
there, then `remove` it. The caller must find their tree byte-for-byte as they left it —
|
|
72
73
|
they are still working in it, and a file you "just" reverted is one they may be editing.
|
package/architect/SKILL.md
CHANGED
|
@@ -6,6 +6,7 @@ description: >
|
|
|
6
6
|
or recording an architecture decision — "how should I structure", "design a system that",
|
|
7
7
|
"should we adopt X", "plan the migration", "review our architecture", "write an ADR".
|
|
8
8
|
Not for code-level planning of a single change.
|
|
9
|
+
allowed-tools: read, grep, find, ls
|
|
9
10
|
---
|
|
10
11
|
|
|
11
12
|
# Architect — Design from Measurable Drivers
|
package/build/SKILL.md
CHANGED
|
@@ -5,6 +5,7 @@ description: >
|
|
|
5
5
|
refactor — "fix this", "write the function", "implement the spec", "make the test pass",
|
|
6
6
|
"code this up", "build it". Not for diagnosing an unknown failure (debug) or deciding
|
|
7
7
|
what to build (plan).
|
|
8
|
+
allowed-tools: read, grep, find, ls, edit, write, bash
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
# Build — Test-First Implementation
|
package/debug/SKILL.md
CHANGED
|
@@ -5,6 +5,7 @@ description: >
|
|
|
5
5
|
lint error — "why is this failing", "find the bug", "debug this", "it crashes when",
|
|
6
6
|
"works on my machine". Not for writing new features or fixing a bug whose cause is
|
|
7
7
|
already known (build).
|
|
8
|
+
allowed-tools: read, grep, find, ls, bash
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
# Debug — Hypothesis Before Fix
|
|
@@ -23,7 +24,7 @@ unknown one; the harder the bug, the stricter the loop.
|
|
|
23
24
|
file:line because <observed evidence> implies <cause>"; test the cheapest first.
|
|
24
25
|
4. **Probe — in a workspace you own.** One smallest experiment per hypothesis: a log line,
|
|
25
26
|
an assertion, a narrowed test. One change at a time. Probing edits code, so do it in a
|
|
26
|
-
disposable copy, never the caller's checkout: `npx principal-pi-workspace create`
|
|
27
|
+
disposable copy, never the caller's checkout: `npx -p principal-pi-skills principal-pi-workspace create`
|
|
27
28
|
prints a throwaway worktree holding their exact working state (minus anything git
|
|
28
29
|
ignores). Work there, then `remove` it. That keeps "probes are temporary" structurally,
|
|
29
30
|
which nobody manages by hand under a failing build.
|
package/decide/SKILL.md
CHANGED
|
@@ -7,6 +7,7 @@ description: >
|
|
|
7
7
|
delivery, and how a technical team works — build vs buy, which vendor, whether to migrate,
|
|
8
8
|
scope and sequencing, team process. Not for building code, designing system architecture,
|
|
9
9
|
planning implementation, or personal-life decisions.
|
|
10
|
+
allowed-tools: read, grep, find, ls
|
|
10
11
|
---
|
|
11
12
|
|
|
12
13
|
# Decide — Options and Stress-Tests
|
package/git-ops/SKILL.md
CHANGED
|
@@ -5,6 +5,7 @@ description: >
|
|
|
5
5
|
"rebase", "merge", "tag a release", "who wrote this", "when did this break", "undo
|
|
6
6
|
this", "wrong branch", "lost commits", "I leaked a secret", CI failures. Safe operator:
|
|
7
7
|
refuses history rewrites on shared branches, scans for secrets before committing.
|
|
8
|
+
allowed-tools: read, bash
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
# Git-Ops — Safe Version-Control Operator
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "principal-pi-skills",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.4.0",
|
|
4
4
|
"description": "Skill framework for principal-level software engineering: seven dual-use skills (decide, architect, plan, build, review, debug, git-ops) that work unedited as loaded skills or as subagent system prompts.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Nemanja Alavanja",
|
package/plan/SKILL.md
CHANGED
|
@@ -5,6 +5,7 @@ description: >
|
|
|
5
5
|
"break this down", "how should I implement this", "where do I start", "what's the order
|
|
6
6
|
of work", "scope this refactor", "plan the fix". Produces the plan and per-step specs;
|
|
7
7
|
writes no code. Not for system-level design (architect) or diagnosing failures (debug).
|
|
8
|
+
allowed-tools: read, grep, find, ls
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
# Plan — Slices and Specs
|
|
@@ -30,7 +30,7 @@ reasoning, so it cannot be surprised by it. When review runs inline, say so in t
|
|
|
30
30
|
confident the diagnosis was.
|
|
31
31
|
4. **Review** — `principal-review` agent, or the `review` skill inline. It verifies the
|
|
32
32
|
regression test fails before the fix and passes after — a destructive check, so it
|
|
33
|
-
belongs in a disposable workspace (`npx principal-pi-workspace`), never in this
|
|
33
|
+
belongs in a disposable workspace (`npx -p principal-pi-skills principal-pi-workspace`), never in this
|
|
34
34
|
checkout. A verdict without that check is UNVERIFIED, and UNVERIFIED is not an approval;
|
|
35
35
|
when review reports `Workspace: none`, treat it as a gap to close rather than a verdict
|
|
36
36
|
to accept.
|
|
@@ -27,7 +27,7 @@ reasoning, so it cannot be surprised by it. When review runs inline, say so in t
|
|
|
27
27
|
4. **Review** — `principal-review` agent, or the `review` skill inline. Pass the
|
|
28
28
|
implementation report. Review runs the tests before any verdict; a verdict without a test
|
|
29
29
|
run is UNVERIFIED, and UNVERIFIED is not an approval. Review's destructive checks belong
|
|
30
|
-
in a disposable workspace (`npx principal-pi-workspace`), never in this checkout —
|
|
30
|
+
in a disposable workspace (`npx -p principal-pi-skills principal-pi-workspace`), never in this checkout —
|
|
31
31
|
when it reports `Workspace: none`, expect UNVERIFIED and treat that as a gap to close,
|
|
32
32
|
not a verdict to accept.
|
|
33
33
|
5. **Repair loop** — if the verdict is CHANGES-REQUESTED, return to Build with the findings,
|
package/review/SKILL.md
CHANGED
|
@@ -5,6 +5,7 @@ description: >
|
|
|
5
5
|
this diff", "simplify this", "is this over-engineered", or after any non-trivial
|
|
6
6
|
implementation. Covers both correctness (bugs, edge cases, error handling, test quality,
|
|
7
7
|
security) and simplicity (dead code, needless abstraction, unneeded dependencies).
|
|
8
|
+
allowed-tools: read, grep, find, ls, bash
|
|
8
9
|
---
|
|
9
10
|
|
|
10
11
|
# Review — Correctness and Simplicity, One Pass
|
|
@@ -59,7 +60,7 @@ ships is a failed review.
|
|
|
59
60
|
path. The strongest check is often destructive — revert the fix and confirm the
|
|
60
61
|
regression test goes red, break an input and watch the guard fire — so do all of it in a
|
|
61
62
|
disposable copy, never in the caller's checkout:
|
|
62
|
-
`npx principal-pi-workspace create` prints a throwaway worktree carrying their
|
|
63
|
+
`npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree carrying their
|
|
63
64
|
exact working state (staged, unstaged, untracked, minus anything git ignores). Work
|
|
64
65
|
there, then `remove` it. The caller must find their tree byte-for-byte as they left it —
|
|
65
66
|
they are still working in it, and a file you "just" reverted is one they may be editing.
|
|
@@ -108,7 +108,13 @@ function install({ dir, wanted, force }) {
|
|
|
108
108
|
|
|
109
109
|
let wrote = 0;
|
|
110
110
|
for (const a of actions) {
|
|
111
|
-
if (a.kind === "current")
|
|
111
|
+
if (a.kind === "current") {
|
|
112
|
+
// Record it anyway. Ownership is what `uninstall` removes by, and a file that was
|
|
113
|
+
// already byte-identical (a re-install, or a user who copied it in by hand) would
|
|
114
|
+
// otherwise never enter the manifest — making uninstall a permanent no-op for it.
|
|
115
|
+
manifest.files[a.file] ??= sha(readFileSync(join(dir, a.file), "utf8"));
|
|
116
|
+
continue;
|
|
117
|
+
}
|
|
112
118
|
if (a.kind === "refuse" && !force) continue;
|
|
113
119
|
// Remove first. Writing to a path that is a symlink writes THROUGH it, editing whatever
|
|
114
120
|
// it points at — which is why plan() refuses links at all. --force means "replace the
|
|
@@ -131,7 +137,12 @@ function check({ dir, wanted }) {
|
|
|
131
137
|
console.error(`✗ ${dir} does not exist — run \`principal-pi-agents install\``);
|
|
132
138
|
return 1;
|
|
133
139
|
}
|
|
134
|
-
|
|
140
|
+
// Check everything we own, not just what this invocation would install. Otherwise a
|
|
141
|
+
// `check` without --with-generic-aliases reports green while previously-installed generic
|
|
142
|
+
// aliases sit stale — the drift check missing exactly the files it is responsible for.
|
|
143
|
+
const owned = Object.keys(readManifest(dir).files);
|
|
144
|
+
const all = [...new Set([...wanted, ...owned])].filter((f) => existsSync(join(ROOT, "agents", f)));
|
|
145
|
+
const { actions } = plan(dir, all);
|
|
135
146
|
const bad = actions.filter((a) => a.kind !== "current");
|
|
136
147
|
for (const a of bad) {
|
|
137
148
|
console.error(`✗ ${a.file}: ${a.kind === "install" ? "not installed" : a.kind === "update" ? "out of date" : a.why}`);
|
|
@@ -39,12 +39,14 @@
|
|
|
39
39
|
import { execFileSync } from "node:child_process";
|
|
40
40
|
import { mkdtempSync, mkdirSync, copyFileSync, symlinkSync, readlinkSync, lstatSync, existsSync, rmSync, writeFileSync, realpathSync } from "node:fs";
|
|
41
41
|
import { tmpdir } from "node:os";
|
|
42
|
-
import { join, dirname, resolve } from "node:path";
|
|
42
|
+
import { join, dirname, resolve, basename } from "node:path";
|
|
43
43
|
import { fileURLToPath } from "node:url";
|
|
44
44
|
|
|
45
45
|
const git = (args, cwd, opts = {}) =>
|
|
46
46
|
execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 64 * 1024 * 1024, ...opts });
|
|
47
47
|
|
|
48
|
+
export const SNAPSHOT_PREFIX = "ppw-";
|
|
49
|
+
|
|
48
50
|
export class SnapshotError extends Error {}
|
|
49
51
|
|
|
50
52
|
/**
|
|
@@ -70,7 +72,7 @@ export function createSnapshot(repo = process.cwd()) {
|
|
|
70
72
|
throw new SnapshotError("repository has no commits yet — nothing to snapshot");
|
|
71
73
|
}
|
|
72
74
|
|
|
73
|
-
const path = mkdtempSync(join(tmpdir(),
|
|
75
|
+
const path = mkdtempSync(join(tmpdir(), SNAPSHOT_PREFIX));
|
|
74
76
|
rmSync(path, { recursive: true, force: true }); // git worktree add wants a non-existent path
|
|
75
77
|
|
|
76
78
|
const cleanup = () => {
|
|
@@ -147,13 +149,38 @@ function main(argv) {
|
|
|
147
149
|
return 2;
|
|
148
150
|
}
|
|
149
151
|
const root = git(["rev-parse", "--show-toplevel"], repo).trim();
|
|
152
|
+
const target = resolve(arg);
|
|
153
|
+
|
|
154
|
+
// Refuse anything this tool did not create. The previous version fell back to an
|
|
155
|
+
// unguarded recursive delete whenever `git worktree remove` failed — and it fails for
|
|
156
|
+
// ANY path that is not a linked worktree, including the user's main checkout. A stale
|
|
157
|
+
// or mistyped path therefore destroyed uncommitted work and printed "removed".
|
|
158
|
+
// An LLM following a contract supplies these paths, so "the caller passes a sane
|
|
159
|
+
// argument" is not an assumption this can make.
|
|
160
|
+
const isOurs = basename(target).startsWith(SNAPSHOT_PREFIX) && target.startsWith(realpathSync(tmpdir()));
|
|
161
|
+
let registered = false;
|
|
162
|
+
try {
|
|
163
|
+
registered = git(["worktree", "list", "--porcelain"], root)
|
|
164
|
+
.split("\n")
|
|
165
|
+
.some((l) => l.startsWith("worktree ") && resolve(l.slice(9)) === target);
|
|
166
|
+
} catch {
|
|
167
|
+
/* not a repo we can query; fall through to the ownership check */
|
|
168
|
+
}
|
|
169
|
+
if (!registered && !isOurs) {
|
|
170
|
+
console.error(`✗ refusing to remove ${target}`);
|
|
171
|
+
console.error(` It is neither a worktree of this repository nor a snapshot this tool created`);
|
|
172
|
+
console.error(` (${SNAPSHOT_PREFIX}* under ${tmpdir()}). Delete it yourself if that is what you meant.`);
|
|
173
|
+
return 1;
|
|
174
|
+
}
|
|
175
|
+
|
|
150
176
|
try {
|
|
151
|
-
git(["worktree", "remove", "--force",
|
|
177
|
+
git(["worktree", "remove", "--force", target], root, { stdio: "ignore" });
|
|
152
178
|
} catch {
|
|
153
|
-
|
|
179
|
+
// Only reachable for a path we have already proven we own.
|
|
180
|
+
if (existsSync(target)) rmSync(target, { recursive: true, force: true });
|
|
154
181
|
}
|
|
155
182
|
git(["worktree", "prune"], root, { stdio: "ignore" });
|
|
156
|
-
console.log(`removed ${
|
|
183
|
+
console.log(`removed ${target}`);
|
|
157
184
|
return 0;
|
|
158
185
|
}
|
|
159
186
|
if (cmd === "prune") {
|