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 +118 -0
- package/CHANGELOG.md +400 -0
- package/LICENSE +21 -0
- package/README.md +247 -0
- package/agents/debug.md +124 -0
- package/agents/plan.md +130 -0
- package/agents/principal-debug.md +124 -0
- package/agents/principal-plan.md +130 -0
- package/agents/principal-review.md +126 -0
- package/agents/review.md +126 -0
- package/architect/SKILL.md +107 -0
- package/build/SKILL.md +94 -0
- package/debug/SKILL.md +117 -0
- package/decide/SKILL.md +88 -0
- package/git-ops/SKILL.md +152 -0
- package/package.json +65 -0
- package/plan/SKILL.md +111 -0
- package/prompts/bugfix.md +15 -0
- package/prompts/feature.md +15 -0
- package/prompts/principal-bugfix.md +47 -0
- package/prompts/principal-feature.md +49 -0
- package/review/SKILL.md +123 -0
- package/scripts/install-agents.mjs +219 -0
- package/scripts/snapshot-workspace.mjs +186 -0
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.
|