principal-pi-skills 2.3.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 ADDED
@@ -0,0 +1,118 @@
1
+ # AGENTS.md
2
+
3
+ Instructions for the [pi coding agent](https://github.com/badlogic/pi-mono) operating
4
+ with this set installed. Read this once at session start.
5
+
6
+ This file is the **routing layer**. The framework deliberately has no routing skill —
7
+ routing belongs to the orchestrator (you), and each file is self-contained: one file is
8
+ the whole contract, there is no required reading beyond it.
9
+
10
+ ## Two forms, one rule
11
+
12
+ A **skill** runs inline in this session: it shares your context, can dialogue with the
13
+ user, and its work stays in your window. A **subagent** (via the subagent tool) runs in
14
+ its own context with its own tools, cannot ask questions, and returns only its output
15
+ template. The rule: dialogue and session state stay inline; heavy reading, cold
16
+ judgment, and noisy loops get delegated.
17
+
18
+ The set:
19
+
20
+ - Skills (inline only): `decide`, `architect`, `build`, `git-ops`.
21
+ - Agents (delegate when the subagent tool is available): `principal-plan`,
22
+ `principal-review`, `principal-debug` — defined in `agents/`. Delegate to the
23
+ `principal-*` names: agent names are a flat global registry, so a bare `plan` is a slot
24
+ any package can claim and the last one loaded wins silently. The unprefixed names remain
25
+ as deprecated aliases. Each contract also has a SKILL.md for interactive use when
26
+ delegation is unavailable or the user wants to work through it conversationally.
27
+
28
+ ## Routing — pick by what the input looks like
29
+
30
+ | Input shape | Route to | How |
31
+ |---|---|---|
32
+ | Exploring a decision, not executing one ("should I…", "what are my options", "I'm stuck") | `decide` | inline — the dialogue is the value |
33
+ | A system to design or a significant/irreversible choice ("design X", "Postgres or DynamoDB") | `architect` | inline — drivers come from asking |
34
+ | A task needing order of work and code-level specs ("plan this", "break this down") | `plan` | **subagent** — it opens every file it names; keep that out of this context |
35
+ | Code to write ("implement", "fix this", "make the test pass") | `build` | inline — the main work, and the only phase that writes durably. Never fan parallel writers into one working tree: "parallel-safe" is a claim about which steps need each other's output |
36
+ | A change to judge before landing ("review this", "ready to merge?") | `review` | **subagent, always when available** — a fresh context judging the diff cold beats self-review; inline review of code you just wrote is anchored on its own reasoning |
37
+ | An unknown failure to diagnose ("why is this failing", "find the bug") | `debug` | **subagent** when reproduction is noisy (flaky loops, bisects); inline when the user is driving |
38
+ | A git or GitHub operation ("commit", "push", "open a PR", "I leaked a secret") | `git-ops` | inline, never delegated — needs this session's working-tree state, and rule-6 destructive ops require user consequence-acceptance no subagent can obtain |
39
+
40
+ **When more than one applies**, route by altitude: the highest-altitude match for the
41
+ *actual* request, not the surface phrasing. "Redis or Memcached?" is `architect`, not
42
+ `decide`; "how do I commit this" is `git-ops`, not `build`; "why is this test red" is
43
+ `debug` (unknown cause), not `build` (known fix).
44
+
45
+ **When no skill fits**, don't force one. Everyday Q&A doesn't need the framework.
46
+
47
+ ## The handoff contract
48
+
49
+ The phases that hand off end with a `Next:` line naming the follow-on. That plus the fixed
50
+ template fields *is* the handoff. You read the `Next:` line and route — a subagent never
51
+ invokes another agent; inline, continuing into the named skill in this same context is
52
+ orchestration, not a skill invoking another.
53
+
54
+ `Next:` carries exactly one bare word from a closed set, so routing is a lookup rather than
55
+ an interpretation. The complete set:
56
+
57
+ | Phase | Allowed `Next:` values |
58
+ |---|---|
59
+ | plan | `build` |
60
+ | debug | `build` · `plan` · `done` · `blocked` |
61
+ | build | `review` · `debug` · `blocked` |
62
+ | review | `build` · `git-ops` |
63
+ | decide · architect · git-ops | *(none — they terminate)* |
64
+
65
+ `decide` and `architect` end in a judgment the user acts on, not a handoff a workflow routes;
66
+ `git-ops` runs inline and terminates the chain. A ceremonial `Next:` on those three invited
67
+ a workflow to route somewhere nobody asked to go. Every value above is consumed by both
68
+ workflow prompts, and a unit test fails if a contract declares a value no workflow handles
69
+ or a workflow handles one no contract can emit — the two drifting apart is how a spine ends
70
+ up with a transition that silently does nothing.
71
+
72
+ Typical spines (available as prompt templates):
73
+
74
+ - Feature (`/principal-feature <task>`): plan → build (inline) → review → git-ops
75
+ (inline). Enter `architect`/`decide` first when the call is architectural or still
76
+ contested.
77
+ - Bug (`/principal-bugfix <symptom>`): debug → build (inline) → review → git-ops (inline).
78
+ If debug's note says design flaw, stop and surface it.
79
+ - Either spine, when the subagent tool is missing or reports an unknown agent: run that
80
+ phase's skill inline instead and say so in the digest. Fall back on *absence* only —
81
+ any other agent failure stops the workflow. Build↔review repair loops stop after two
82
+ rounds; a third means the plan or the diagnosis was wrong, not the code.
83
+ - Tiny change: build → git-ops, both inline — every contract carries a Right-sizing
84
+ rule; don't add ceremony the file itself would refuse.
85
+
86
+ A delegated step returning `BLOCKED` stops the chain: surface its one question to the
87
+ user; don't answer it yourself and keep going.
88
+
89
+ ## Maintenance rule — the contracts are generated
90
+
91
+ `plan`, `review` and `debug` exist three times: `<name>/SKILL.md` (interactive contract),
92
+ `agents/principal-<name>.md` (the single-shot contract subagents get) and
93
+ `agents/<name>.md` (its deprecated generic-name alias). They are different artifacts, not
94
+ copies — but 74–84% of each pair is identical, and that shared majority is where they used
95
+ to drift.
96
+
97
+ All three are generated from `contracts/<name>.md.tmpl`. Change shared behavior ONCE, there,
98
+ then `npm run generate`. Editing a generated file directly is reverted by the next run and
99
+ fails `npm run generate:check` in CI. Hand-mirroring used to be a reviewer's job and was
100
+ never reliably done — which is how the D-scenarios once measured a contract no subagent had
101
+ been handed.
102
+
103
+ Deliberate divergences are marked in the template: `{{#skill}}` for interactive-dialogue
104
+ rules, `{{#agent}}` for single-shot mechanics — the BLOCKED form, the
105
+ assumptions-not-questions rule, the final-message-only rule. Anything outside a block goes
106
+ to every output.
107
+
108
+ ## Setup (pi)
109
+
110
+ 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v2.3.0` — registers the
111
+ skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
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 principal-pi-agents install`. It copies real
115
+ files into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses to overwrite
116
+ anything it did not install.
117
+ 3. Without the extension, everything runs inline via the skills; the How column above
118
+ simply collapses to "inline".
package/CHANGELOG.md ADDED
@@ -0,0 +1,400 @@
1
+ # Changelog
2
+
3
+ All notable changes to this framework are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/).
4
+
5
+ Where review revealed a prior claim or design decision didn't hold up under closer inspection, this changelog says so explicitly. The history of the framework's own thinking is part of the framework.
6
+
7
+ ---
8
+
9
+ ## [2.3.0] — 2026-08-09
10
+
11
+ The release that made the installed product real: namespaced commands and agents, generated
12
+ contracts, filesystem isolation between phases, and a contract cleanup that replaced
13
+ absolutes with governed rules.
14
+
15
+ **Measured, not asserted.** Every skill's text changed in this release, so the whole board was
16
+ re-run: 98 scenarios × 3 reps × DeepSeek and GLM, `--mode force`, reps pinned in the spec.
17
+ Five of seven skills ship on at least one model.
18
+
19
+ | | DeepSeek | GLM |
20
+ |---|---|---|
21
+ | architect | 13/14 | **14/14 SHIP** |
22
+ | build | **9/9 SHIP** | **9/9 SHIP** |
23
+ | debug | 9/11 | 10/11 |
24
+ | decide | **12/12 SHIP** | **12/12 SHIP** |
25
+ | git-ops | 18/19 | **19/19 SHIP** |
26
+ | plan | 8/12 | **12/12 SHIP** |
27
+ | review | 20/21 | 19/21 |
28
+
29
+ `decide` shipped on no model before this and is now perfect on both. `build` went 7/9 → 9/9
30
+ on DeepSeek. `plan` is 12/12 on GLM against 8/12 on DeepSeek — the same text, so the weakness
31
+ is model-specific rather than inherent, and its boundary cells move between runs.
32
+
33
+ **kimi-k3 is deferred**, so there is no evidence yet about generalization beyond the two
34
+ models these skills were tuned against.
35
+
36
+ **Added** — the steering digest, dogfooded. `/feature` and `/bugfix` both driven end to end
37
+ against a repo carrying a planted out-of-scope bug; the closing digest surfaced it as a
38
+ Follow-up in both flows without either touching it, and caught one defect nobody planted.
39
+ Recorded in `docs/demos/steering-digest-2026-08-06.md`. The `[ONE-WAY]` pause remains
40
+ unexercised — no task in the run warranted a one-way step.
41
+
42
+ **Added** — red baselines and lift. Every scenario re-run with no skill at all (477
43
+ rep-executions, three models, three reps) to measure what the skills *add* rather than how
44
+ well they score: aggregate +15 / +11 / +13 scenarios of 35. Lift concentrates where models
45
+ are weakest, and some disciplines — characterization tests before refactoring,
46
+ decision-record honesty — appear only under the skill, on every model.
47
+
48
+ **Changed** — documentation restructured for public use. The README leads with the skills
49
+ (646 lines to under 200); everything about measuring them consolidated into
50
+ `docs/validation/VALIDATION.md` with the run manifest beside it. **Removed**
51
+ `REVIEW-FINDINGS.md` (every item fixed, SHAs recorded in the file's own history) and
52
+ `docs/revalidation-2026-08-05.md` (dated working notes). Both survive in git history.
53
+
54
+ **Fixed** — CI's lint-summary guard tolerates additive format growth in the harness output,
55
+ so tracking the harness's moving `latest` tag stops turning its releases into red trees.
56
+
57
+ **Fixed** — four defects found by an independent review of this branch, all of which made a
58
+ documented command silently do nothing or do damage:
59
+
60
+ - **Both CLIs were no-ops when installed.** The main-module guard compared
61
+ `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
64
+ reads as success, so the agents never installed and debug/review got an empty path where a
65
+ worktree should be — silently losing the isolation this release is built around.
66
+ - **`snapshot-workspace` dropped its own subcommand** whenever `--repo` was absent: the
67
+ argument filter used `repoFlag + 1`, which is index 0 when the flag is missing. The
68
+ documented invocation could not work by either route.
69
+ - **`install --force` wrote *through* a symlink**, overwriting whatever it pointed at
70
+ anywhere on the filesystem, leaving the link in place and recording it in the manifest — so
71
+ a later `uninstall` would delete the link and leave the damaged file behind. The refusal
72
+ path had always guarded this; the force path did not.
73
+ - **Both workflow spines branched on `REQUEST-CHANGES`** while review emits
74
+ `CHANGES-REQUESTED`, so a review asking for changes routed nowhere and the spine fell
75
+ through to the commit step. The transition test accepted either spelling and waved through
76
+ the exact drift it existed to catch.
77
+
78
+ Each now has a regression test, including one that runs both bins through `node_modules/.bin`
79
+ after a real install rather than importing them.
80
+
81
+ **Changed** — the package ships 24 files and 166 kB instead of 287 files and ~1 MB. A `files`
82
+ allowlist replaces npm's default sweep, which was shipping every fixture, every committed
83
+ `results.yaml`, the evidence directory, CI config and the contract templates — none of which
84
+ runs at install time, all of which stays in git. `npm run check:pack` enforces it in both
85
+ directions: a required runtime file missing from the tarball fails just as loudly as an
86
+ excluded one leaking in, because an allowlist that silently drops a new SKILL.md is invisible
87
+ in every developer test and broken for every user.
88
+
89
+ **Fixed** — the workspace helper is reachable from an installed package. The contracts said
90
+ `node scripts/snapshot-workspace.mjs`, a relative path that resolves in this checkout and
91
+ 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
93
+ packaging step is what surfaced it.
94
+
95
+ **Removed** — `docs/superpowers/` (a completed cleanup plan and its design spec, referenced
96
+ by nothing). Benchmark evidence, demos and the run manifest stay: they are the record behind
97
+ the numbers, and the plan is explicit that they are kept in git even as they leave the
98
+ package.
99
+
100
+ **Changed** — README states plainly what a clean install gives you: the seven skills and
101
+ both workflows running **inline**, which is the complete baseline product; subagents only if
102
+ you separately install the extension; `/feature` and `/bugfix` as deprecated aliases; and
103
+ that **`AGENTS.md` is not loaded as routing context** — pi registers skills and prompts, not
104
+ a routing file, so implying otherwise would have described a layer that is not wired up.
105
+ Inline review is named as self-review and weaker evidence than a cold delegated read.
106
+
107
+ **Changed** — contract cleanup: absolutes replaced with governed rules, because every one of
108
+ these absolutes was wrong in a real case and the wrongness only showed as over-refusal.
109
+
110
+ - **`debug`'s error rule.** "Every catch logs AND changes observable state" is right at a
111
+ service boundary and wrong elsewhere. It now states four requirements — preserve the
112
+ failure semantics, keep state consistent *where state was changed*, log once at the owning
113
+ boundary, sanitize what is logged — plus the three shapes it used to eat: pure/library code
114
+ returning a typed error without logging, a transaction that rolls back and rethrows, and
115
+ operations with no durable record, where inventing a status field is ceremony. Three new
116
+ counter-scenarios pin each.
117
+ - **`review`'s simplicity hunt.** One implementation or one caller is now a signal to look,
118
+ not a verdict: a boundary earns its place when it centralizes policy, pins a public API,
119
+ isolates a provider, or makes tests deterministic. Dependency decisions weigh what the
120
+ dependency carries — for crypto, untrusted parsing or date arithmetic a maintained library
121
+ is the *safer* choice and hand-rolling is the finding — rather than counting lines. An
122
+ observable, documented fallback is a design decision; only *silent* success is a blocker.
123
+ Three counter-scenarios, including a hand-rolled JWT verifier that the old rule would have
124
+ praised for removing a dependency.
125
+ - **`plan`.** The walking skeleton must be primitive *and real* at every seam — the rubric
126
+ that graded a skeleton as passing "with stub/trivial logic" contradicted the contract it
127
+ was testing. No-codebase plans state assumptions instead of trailing open questions, which
128
+ the skill-mode text had explicitly invited.
129
+ - **`decide`.** Scope narrowed to engineering, product delivery and technical-team decisions
130
+ (personal-life routing removed). The brief is produced *when concluding*, not always: a
131
+ fuzzy or high-stakes first turn asks the one load-bearing question, because a brief built
132
+ on guessed constraints is confident and wrong, and the confidence is the damage.
133
+
134
+ **Changed** — `Next:` is now a closed set of bare words per phase (plan → `build`; debug →
135
+ `build|plan|done|blocked`; build → `review|debug|blocked`; review → `build|git-ops`), so
136
+ routing is a lookup rather than an interpretation — `build (fix is nontrivial)` matched
137
+ nothing. `decide`, `architect` and `git-ops` carry no `Next:` at all: they terminate, and a
138
+ ceremonial token invited a workflow to route where nobody asked. A unit test fails if a
139
+ contract emits a value no workflow handles or a workflow branches on one no contract emits;
140
+ it immediately caught a real hole — `build` could return `Next: debug` with the feature spine
141
+ having no route for it.
142
+
143
+ **Changed** — the skill word budget, 1100 → 1250, deliberately and with a reason: *every
144
+ arming needs its governor in the same breath*. An absolute is cheap to write and wrong in
145
+ real cases; a rule plus the cases it must not eat costs more words. The alternative was
146
+ keeping the cheaper text and the defects.
147
+
148
+ **Added** — filesystem isolation and phase ownership. `scripts/snapshot-workspace.mjs`
149
+ creates a disposable detached worktree carrying the caller's exact working state — committed
150
+ HEAD, staged and unstaged changes, deletions, untracked files, symlinks — and never anything
151
+ git ignores. Debug probes hypotheses and proves candidate fixes there; review runs its
152
+ destructive checks there (reverting a fix to confirm the regression test goes red is the
153
+ strongest verification available and the most damaging place to do it in someone's live
154
+ tree). Build is named as the only phase that writes durably, and it writes where the user can
155
+ see it.
156
+
157
+ The exclusion of `.env`, credentials and caches is structural rather than a denylist: the
158
+ snapshot is built from `git diff HEAD` and `git ls-files --others --exclude-standard`,
159
+ neither of which can see an ignored file. A denylist would have to anticipate every name a
160
+ secret might have; this cannot miss one because it never looks at them.
161
+
162
+ When no workspace can be created, debug returns a read-only diagnosis with the fix marked
163
+ unproven (or `BLOCKED`), and review returns `UNVERIFIED`. Neither falls back to mutating the
164
+ caller's checkout — the fallback for "I cannot verify safely" is to say so, not to verify
165
+ unsafely. Both contracts gained a `Workspace:` output field so the caller can see which
166
+ happened.
167
+
168
+ **Removed** — permission to fan parallel writers into one working tree. "Parallel-safe" in a
169
+ plan is a claim about which steps need each other's output; it was being read as a licence
170
+ for concurrent writers sharing a checkout. Parallel *analysis* remains fine.
171
+
172
+ **Added** — namespaced workflows and agents. `/principal-feature` and `/principal-bugfix`
173
+ are the supported commands, and the spines delegate to `principal-plan`,
174
+ `principal-review` and `principal-debug`. Agent and command names are a flat global
175
+ registry: a bare `plan` or `feature` is a slot any installed package can claim, and the last
176
+ one loaded wins silently. `/feature`, `/bugfix` and the unprefixed agents remain as
177
+ deprecated aliases; the generic agents install only under `--with-generic-aliases`.
178
+
179
+ **Added** — both spines now state their fallback explicitly. If the subagent tool is absent
180
+ or reports an unknown agent, that phase runs its skill inline and the digest says so —
181
+ a supported configuration, not a degradation, with the honest caveat that inline review is
182
+ self-review and cannot be surprised by reasoning it produced. Fallback happens on *absence*
183
+ only; any other agent failure stops the workflow. Build↔review repair loops are capped at
184
+ two rounds.
185
+
186
+ **Added** — `principal-pi-agents install | check | uninstall`. It copies real files into
187
+ `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents`, replacing the documented
188
+ `ln -sf "$(pwd)"/agents/*.md` — a symlink that broke the moment the checkout moved, and
189
+ broke silently, since pi then reports an unknown agent and the workflow quietly falls back
190
+ to inline. It refuses to overwrite files it does not own, refuses to write through a
191
+ symlink, and on uninstall removes only its own unmodified files; anything you edited is
192
+ yours and is kept.
193
+
194
+ **Added** — `tests/install/`, 20 tests including a clean-home run that packs the tarball,
195
+ installs it into a throwaway HOME, runs the shipped installer, verifies pi resolves and
196
+ materializes every declared resource, and asserts the developer's real home was untouched.
197
+ Also covers the collision case: preseeded foreign `plan`/`review`/`feature` files are left
198
+ alone while the namespaced agents install regardless.
199
+
200
+ **Added** — `plan`, `review` and `debug` are generated from `contracts/<skill>.md.tmpl`.
201
+ Each existed twice, as a loaded skill and as a subagent system prompt, 74–84% identical. That
202
+ shared majority now lives in one file, with the deliberate divergences marked `{{#skill}}` /
203
+ `{{#agent}}`, and `npm run generate:check` fails if either output stops matching. Changing a
204
+ shared rule in one representation and not the other is no longer mergeable — a divergence
205
+ that once left the D-scenarios measuring a contract no subagent had been handed.
206
+
207
+ The first generator commit renders all six files **byte-identical** to what was committed,
208
+ verified by checksum: this change moves no text and alters no behavior. The generated files
209
+ deliberately carry no "generated by" banner, which the design called for — they are prompts,
210
+ every byte is measured, and a banner would have staled nine published scorecard cells to
211
+ state something the drift check enforces properly.
212
+
213
+ **Removed** — the agents-lockstep CI rule, superseded. It asked whether both files changed,
214
+ which can be true while they disagree; and once the contracts became generated it would have
215
+ failed correct skill-only edits, the sort of false positive that gets routed around with an
216
+ exempt label until the gate stops being read.
217
+
218
+ ## [2.2.1] — never released separately
219
+
220
+ The git-ops safety patch. It was version-bumped and fully measured (19/19 · SHIP on
221
+ DeepSeek) but never published or tagged before the rest of this milestone landed, so it
222
+ ships **inside 2.3.0**. Kept as its own section because the work is a coherent unit and the
223
+ changelog is the record of the framework's thinking, not only of its tags — but there is no
224
+ `v2.2.1` to install.
225
+
226
+ A safety patch. `git-ops` carried rules that contradicted each other or leaked the thing
227
+ they existed to protect, and none of it was visible in a passing 15/15 board — because no
228
+ scenario asked.
229
+
230
+ **Fixed** — four safety defects in `git-ops`, repaired together because they interlock:
231
+
232
+ - The pre-flight ran `git fetch @{u}` unconditionally, so a branch with no upstream failed a
233
+ check that should never have run on it. Divergence is now conditional and `upstream: none`
234
+ is a reported fact that blocks nothing. Detached HEAD becomes the one pre-flight result
235
+ that *does* block writes.
236
+ - Rule 2's protected-branch absolute and rule 4's leaked-secret playbook contradicted each
237
+ other outright: one forbade rewriting `main`, the other required it. Reconciled as a
238
+ **named credential-incident exception** whose preconditions must be stated back before any
239
+ command is given. Deletion stays absolute and sits outside the exception — it is a rewrite
240
+ exception only.
241
+ - A secret match was reported *by showing it*, copying the leak into the transcript, the
242
+ scrollback and every log that captures them. Findings are now reported by path, line,
243
+ detector and non-reversible fingerprint. Conflict markers and oversized files are
244
+ explicitly carved out: those name their files outright, having nothing to redact.
245
+ - Wrong-branch recovery recommended `reset` regardless of whether the commit was published.
246
+ It is now publication-aware, and unknown publication is treated as published.
247
+
248
+ **Removed** — `git-ops`'s delegated-output block and its ceremonial `next:` field. The skill
249
+ is inline-only and nothing consumed them.
250
+
251
+ **Added** — four adversarial scenarios, taking the board from 15 to 19: **A13** secret
252
+ redaction (critical, seeded on a staged synthetic credential, audited by grepping transcripts
253
+ for a canary embedded in the credential body), **A14** published wrong branch, **A15** its
254
+ unpublished-commit governor, **A16** the credential-purge over-refusal governor. A2 and C2
255
+ gained checklist items for the same boundaries.
256
+
257
+ **Changed** — `git-ops` re-measured at **19/19 · 100% · SHIP** on DeepSeek (force, three
258
+ reps, flakiness 0.00 across all 57 rep-executions, zero misfires). The three previous
259
+ 15/15 cells measured text that no longer exists and are relabelled **historical**. GLM and
260
+ kimi-k3 publish no `git-ops` cell: one model verifies a patch, it does not make a scorecard.
261
+
262
+ **Changed** — the skill grew 1320 → 1895 words, breaking its own stated budget. The exception
263
+ is re-declared at ~1900 rather than quietly ignored, and is now machine-checked.
264
+
265
+ **Added** — `npm test`, a real zero-model entry point that passes from a fresh checkout:
266
+ word-budget verification against the README table, plus spec lint under this repo's severity
267
+ policy. Both CI and a contributor run the identical command.
268
+
269
+ **Changed** — staleness now blocks a **pull request**, not just `main`, but only for cells the
270
+ scorecard actually publishes. Cells that publish no number are declared in
271
+ `docs/validation/unpublished-cells.txt`, and an entry there that matches no finding fails the
272
+ build — an exemption has to die when its reason does.
273
+
274
+ **Changed** — GitHub Actions pinned to immutable commit SHAs. The harness deliberately keeps
275
+ tracking its moving `latest` tag: that ordering guarantee is what lets the staleness rule
276
+ compare hashes at all, and the contradictory "pinned to an exact release" comment that had
277
+ sat above `ref: latest` is gone.
278
+
279
+ **Note on method.** Five defects surfaced only under measurement, and three of them were
280
+ regressions introduced while fixing the earlier ones — including one that broke two
281
+ scenarios at once by arming a rule without its governor, the exact failure mode
282
+ `VALIDATION.md` already warns about in writing. The run-by-run trajectory is kept in the
283
+ manifest for that reason.
284
+
285
+ ## [2.2.0] — 2026-08-06
286
+
287
+ The release that learned to distrust its own instruments.
288
+
289
+ **Added** — a third subject model across the whole board. kimi-k3, never tuned against, run
290
+ on all 88 scenarios (264 rep-executions) as the control for overfitting. It ties or beats
291
+ both tuned models, which re-partitions the failure list: several published "universal"
292
+ limits turn out to be two-model artifacts.
293
+
294
+ **Added** — the judge-variance audit. Every non-unanimous cell re-judged from saved
295
+ transcripts, then disputed reps escalated: over 170 judge calls, no model spend. Two cells
296
+ were misreported as failures and corrected; a third correction was later **retracted** when
297
+ nine judgments of the same transcript split 4–5. The finding that outlasted the numbers:
298
+ some transcripts are coin flips, and no amount of voting fixes one — read the margin, not
299
+ the majority.
300
+
301
+ **Changed** — three checklists rewritten to decide their own transcripts (`architect` C2,
302
+ `build` B1, `review` S6), each validated by re-judging saved transcripts several times per
303
+ rep and reading the margin rather than the majority. Decidability cut both ways: the same
304
+ rewrite moved `architect` C2 to PASS on one model and to a decisive FAIL on another,
305
+ exposing a consistent failure the old count-based checklist had never named.
306
+
307
+ **Changed** — seeded scenarios are graded from the diff, not the model's prose. skill-harness
308
+ 0.3.0 puts the staged diff in front of the judge; `build` and `debug` were fully re-measured
309
+ against it. `debug` held at 8/8 on both models. `build` fell to 44%, which is the honest
310
+ number: three distinct causes, one of them a needle that scored word choice rather than
311
+ behavior.
312
+
313
+ **Fixed** — scenario bugs, the fourth and fifth instances of the law that they present as
314
+ model failures: `git-ops` A9 asked a model to point at conflict markers in an empty
315
+ directory (reseeded; both models now 15/15 SHIP), and `build` A2's out-of-scope item was
316
+ already annotated as known in its own fixture.
317
+
318
+ **Added** — the release-2 bundle: `/feature` and `/bugfix` gain a `[ONE-WAY]` pause and a
319
+ closing six-line digest; `build` A1 gets an objective overdraft gate and B1 a Checks row;
320
+ `architect` gains a middle mode so a sound-check returns a verdict instead of the full
321
+ artifact; `plan`'s walking skeleton teaches primitive-but-real instead of stubbed, and its
322
+ right-sizing hatch survives system-prompt placement.
323
+
324
+ **Changed** — the measured deployment is now skill-as-system-prompt (`--mode force`). pi
325
+ 0.83 switched `--skill` to progressive disclosure and accepts a nonexistent skill path
326
+ silently, so a day of runs measured naked models while producing plausible results. Those
327
+ runs are marked INVALID and kept as the incident's evidence. Green-epoch and force-epoch
328
+ cells are **not comparable**: on identical text, force placement took `build` A1 from 0/3 to
329
+ 3/3 on DeepSeek and 1/3 to 3/3 on GLM, and dropped `plan` C2 on GLM from 3/3 to 0/3.
330
+
331
+ **Added** — CI guards, all free: spec and results lint on every PR (staleness warns on a
332
+ branch, blocks on `main`), plus an agents-lockstep check that fails a PR touching
333
+ `plan|review|debug/SKILL.md` without its `agents/` twin.
334
+
335
+ ## [2.1.0] — 2026-08-04
336
+
337
+ The v2 redesign, promoted and measured.
338
+
339
+ **Changed** — the seven v2 skills moved from `proposals/` to the repository root and are now
340
+ the framework. **Removed** the ten v1 skill directories, `BATON.md`, and the v1-era README
341
+ and AGENTS.md. The v1 stack — specs, fixtures and Opus-judged baseline results — survives in
342
+ git history at the commit before the promotion.
343
+
344
+ **Added** — the seven dual-use skills (`decide`, `architect`, `plan`, `build`, `review`,
345
+ `debug`, `git-ops`), each working unedited as a loaded skill or a subagent system prompt;
346
+ three hand-written single-shot variants in `agents/`; the `/feature` and `/bugfix` prompt
347
+ templates; and `RESULTS-MANIFEST.md` mapping every committed run to its round and status.
348
+
349
+ **Fixed** — the delegation contract, measured for the first time and then repaired. `BLOCKED`
350
+ appeared in AGENTS.md, both prompt templates and six checklist items — and in none of the
351
+ three agent definitions. The agents now carry the contract themselves; the starved-input
352
+ scenario — which `plan` failed on both models and `debug` failed on GLM — now passes at
353
+ majority or better in every agent × model cell.
354
+
355
+ **Fixed** — coverage debt: `debug` D1 redesigned around a coherent single-cause bug (its old
356
+ premise was false under its own bug), two over-refusal guards added to `git-ops` so the
357
+ safety absolutes are shown not to overshoot, and a characterization-test scenario added to
358
+ `build`.
359
+
360
+ **Added** — release-1: 88 scenarios × two models × three reps, 528 rep-executions, judged by
361
+ `claude-code:opus`, with the first live end-to-end runs of both chains against real repos
362
+ (`docs/demos/`).
363
+
364
+ ## Pre-2.1.0
365
+
366
+ The v1 ten-skill stack and its iteration — the baton schema, the brownfield architect modes,
367
+ the tech-lead ↔ coder boundary, the orchestrator model, reversibility notation, frontmatter
368
+ trimming — was removed when v2 was promoted. Those items described artifacts that no longer
369
+ exist; the reasoning behind them is in git history and in the `[0.2.0]` entry below, which
370
+ records the restructure that produced the stack v2 replaced.
371
+
372
+ ## [0.2.0] — 2026-06-25
373
+
374
+ Model-agnostic framework redesign. The six-skill stack became a ten-skill stack, every `SKILL.md` was rewritten to drop model-specific assumptions, and the per-skill bash benchmark was replaced by one declarative spec per skill.
375
+
376
+ **Changed — model-agnostic rewrite of every skill.** Compressed `SKILL.md` bodies to one-line tenets, replaced prose guidance with armed red-flag / STOP tables plus over-correction governors (so a skill can't be pushed past its own remit), narrowed frontmatter `description`s to trigger-only text, and inlined the few load-bearing `AGENTS.md` facts directly into the skills — removing the `§N` cross-references that coupled skills to a specific repo layout.
377
+
378
+ **Changed — `tech-lead` merged into `implementation-planner`.** The planner now produces both the implementation plan and the per-slice coding spec; the standalone `tech-lead/` skill is gone. Its assets moved under `implementation-planner/assets/` (`coding-spec.md`, `bugfix-spec.md`, `refactor-spec.md`, `risk-register.md`, `exploration-notes.md`).
379
+
380
+ **Added — new skills.**
381
+ - `ponytail` — simplicity sidekick / critic.
382
+ - `code-review` — correctness gate.
383
+ - `using-principal-pi-skills` — posture + routing index for the stack.
384
+ - `adr` — split out of `software-architect` into its own skill.
385
+
386
+ **Changed — the skill set is now ten:** `using-principal-pi-skills`, `brainstorming`, `software-architect`, `adr`, `implementation-planner`, `coder`, `ponytail`, `code-review`, `debugging`, `project-git`. Primary flow: brainstorming → implementation-planner → coder → [ponytail · code-review] → project-git, with software-architect (+adr) as design depth and debugging as the repair loop.
387
+
388
+ **Changed — test harness consolidated.** Each skill now carries one declarative `tests/specification.yaml` (scenarios + checklist + ship bar), replacing the old per-skill bash harness (`run-pi` / `run-claude` / `bench` / `grade` / `cases` / `scenarios.md`). Seeded `coder` and `debugging` fixtures are TypeScript + Vitest. A separate, portable `skill-check` tool runs the specs.
389
+
390
+ **Changed** `package.json` `pi.skills` manifest synced to the ten-skill stack.
391
+
392
+ #### Design notes
393
+
394
+ `package.json` `version` stays `0.1.0`; skills now version independently in their own frontmatter (`implementation-planner` 0.3.0, `coder` 0.3.0, `brainstorming` 2.2.0, others 0.1–0.2). The `0.2.0` tag here marks the framework-level restructure, not the package version.
395
+
396
+ Nine of the ten skills ship a `specification.yaml`; `using-principal-pi-skills` is a routing index with no behavior of its own to spec, so it has no test directory.
397
+
398
+ ## [0.1.0] — 2026-05-12
399
+
400
+ Initial commit. Six skills (`brainstorming`, `software-architect`, `tech-lead`, `implementation-planner`, `coder`, `project-git`), each with `SKILL.md` + `assets/` + `references/`. MIT license.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Nemanja Alavanja
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.