principal-pi-skills 2.3.1 → 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 CHANGED
@@ -110,9 +110,14 @@ to every output.
110
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`) and the
114
- agent definitions installed once: `npx -p principal-pi-skills principal-pi-agents install`. It copies real
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,58 @@ 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
+
9
61
  ## [2.3.1] — 2026-08-10
10
62
 
11
63
  A defect-fix release. 2.3.0 shipped three defects that a second independent review found,
@@ -43,10 +95,14 @@ add, so it could not fail. Both restored. The corruption reached git through a b
43
95
  two `node_modules/.vite` caches that churn the fixture source hash. Those are untracked and
44
96
  `node_modules/` is now ignored.
45
97
 
46
- **Changed** — `debug` and `review` scorecard cells are **withdrawn** pending a re-run.
98
+ **Changed** — `debug` and `review` scorecard cells were **withdrawn** pending a re-run.
47
99
  debug's were measured against the corrupted fixtures; review's contract changed in this
48
100
  release. A withdrawn cell publishes nothing rather than a number that measured something
49
- else.
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.
50
106
 
51
107
  **Note on verification.** 2.3.0's bins were reported as "verified working from the published
52
108
  artifact". That check invoked `./node_modules/.bin/<name>`, which is a different resolution
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 | 847 |
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 | 1088 |
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`, 1360) or inline | 1150 |
52
- | `build` | Test-first implementation — code proven by a test you watched fail | inline | 968 |
53
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1317) or inline | 1289 |
54
- | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1335) or inline | 1208 |
55
- | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1895 |
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,17 +86,31 @@ 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.0
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.0` only if
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).** Install pi-mono's subagent extension
96
- (`packages/coding-agent/examples/extensions/subagent` — symlink its `index.ts` and
97
- `agents.ts` into `~/.pi/agent/extensions/subagent/`), then install the agent definitions:
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
116
  npx -p principal-pi-skills principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
@@ -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.80.2** and pi-mono
115
- [`008c76f`](https://github.com/badlogic/pi-mono/commit/008c76f955ae) — the newest commit
116
- touching that extension path, so the layout has been stable since 2026-06-18. Upstream is
117
- someone else's repo: if the file names move, check out that commit.
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,18 +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 ✗ | — *(withdrawn)* | — *(withdrawn)* | — *(deferred)* |
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 ✗ | — *(withdrawn)* | — *(withdrawn)* | — *(deferred)* |
201
-
202
- ✗ `debug`'s cells are **withdrawn**: a review found its D1 and A5 fixtures shipped
203
- already-fixed code, so a critical scenario could not reproduce its own failure and another
204
- could not fail. The fixtures are restored and a re-run is pending; the previous 9/11 and
205
- 10/11 were measured against them and should not be quoted.
222
+ | review | **21/21 · 100% SHIP** | **21/21 · 100% SHIP** | — *(deferred)* |
206
223
 
207
- **Four of the six remaining skills ship on at least one model.** `decide` is new to that list — it
224
+ **All seven skills ship on at least one model.** `decide` is new to that list — it
208
225
  previously held at 92% on every model, failing exactly one boundary scenario each, and shipped
209
226
  nowhere; it is now 12/12 on both. `build` went 7/9 → 9/9 on DeepSeek.
210
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
package/agents/plan.md CHANGED
@@ -7,6 +7,7 @@ description: >
7
7
  the plan and per-step specs; writes no code. Not for system-level design (architect)
8
8
  or diagnosing failures (debug).
9
9
  tools: read, grep, find, ls
10
+ allowed-tools: read, grep, find, ls
10
11
  ---
11
12
 
12
13
  # Plan — Slices and Specs
@@ -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
@@ -7,6 +7,7 @@ description: >
7
7
  the plan and per-step specs; writes no code. Not for system-level design (architect)
8
8
  or diagnosing failures (debug).
9
9
  tools: read, grep, find, ls
10
+ allowed-tools: read, grep, find, ls
10
11
  ---
11
12
 
12
13
  # Plan — Slices and Specs
@@ -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
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
@@ -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
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.1",
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
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