principal-pi-skills 4.4.0 → 4.5.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 +1 -1
- package/CHANGELOG.md +22 -3
- package/README.md +13 -13
- package/agents/principal-build.md +4 -2
- package/agents/principal-review.md +3 -2
- package/architect/SKILL.md +4 -5
- package/build/SKILL.md +4 -2
- package/debug/SKILL.md +4 -4
- package/decide/SKILL.md +4 -6
- package/git-ops/SKILL.md +17 -9
- package/package.json +1 -1
- package/plan/SKILL.md +5 -4
- package/review/SKILL.md +3 -2
package/AGENTS.md
CHANGED
|
@@ -113,7 +113,7 @@ to every output.
|
|
|
113
113
|
|
|
114
114
|
## Setup (pi)
|
|
115
115
|
|
|
116
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.
|
|
116
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.5.0` — installs the seven
|
|
117
117
|
skills, the four `/principal-*` commands, and the bootstrap
|
|
118
118
|
extension, which loads automatically with the package. Install a tag, not a branch.
|
|
119
119
|
2. Subagents (optional): `npx -p principal-pi-skills principal-pi-agents install` copies
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,25 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [4.5.0] — 2026-09-29
|
|
10
|
+
|
|
11
|
+
**Routing by output, with stable evidence (#51, #52, #53, #54).** PR #51 moved the routing
|
|
12
|
+
model to `glm-5p3-flash` because `glm-5p2` is no longer deployed, and separated `debug` from
|
|
13
|
+
`git-ops` by what each produces. PR #52 made the collision check report STABLE (collided in
|
|
14
|
+
every run) and ANY (collided in any run) over three runs, and fail only on STABLE. PR #53
|
|
15
|
+
expanded the decide/architect/plan boundary corpus. PR #54 separated those three descriptions
|
|
16
|
+
by output — a choice with rationale, a system structure, or an ordered sequence of work — and
|
|
17
|
+
narrowed `decide`. The adversarial corpus grew from 34 to 54 records, and every label now
|
|
18
|
+
follows the rule that a skill is chosen by what it produces.
|
|
19
|
+
|
|
20
|
+
**Stronger delivery evidence and attribution.** `git-ops` stamps `Pi-Episode`,
|
|
21
|
+
`Pi-Definition`, and `Pi-Execution` trailers on commits when pi-daddy exports them. `build`
|
|
22
|
+
and `review` require the repository's full test command as evidence, rather than treating
|
|
23
|
+
focused checks as sufficient.
|
|
24
|
+
|
|
25
|
+
**Changed defaults.** None for users. Routing evaluations require `FIREWORKS_API_KEY` and now
|
|
26
|
+
default to `glm-5p3-flash`.
|
|
27
|
+
|
|
9
28
|
## [4.4.0] — 2026-09-23
|
|
10
29
|
|
|
11
30
|
**Added — local routing evaluation for the seven skill descriptions.** A shared loader reads
|
|
@@ -13,9 +32,9 @@ only authored `SKILL.md` frontmatter descriptions. Opt-in checks cover all 42 di
|
|
|
13
32
|
pairwise collisions and a three-run trigger corpus with per-skill precision and recall,
|
|
14
33
|
collision-boundary cases, explicit `AMBIGUOUS` labels, and `NO_SKILL` hard negatives. Model
|
|
15
34
|
payloads use opaque case IDs and omit expected labels. CI can run both checks manually with
|
|
16
|
-
a Fireworks key.
|
|
17
|
-
trigger run
|
|
18
|
-
corpus because Fireworks was unavailable for that rerun.
|
|
35
|
+
a Fireworks key. At the 4.4.0 release, the committed collision baseline recorded three
|
|
36
|
+
overlaps and the original trigger run was retained as pre-expansion evidence, not claimed
|
|
37
|
+
as a score for the expanded corpus because Fireworks was unavailable for that rerun.
|
|
19
38
|
|
|
20
39
|
## [4.3.0] — 2026-09-22
|
|
21
40
|
|
package/README.md
CHANGED
|
@@ -42,13 +42,13 @@ around.
|
|
|
42
42
|
|
|
43
43
|
| Skill | What it does | How it runs | Words |
|
|
44
44
|
|---|---|---|---|
|
|
45
|
-
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline |
|
|
46
|
-
| `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 |
|
|
47
|
-
| `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`, 1458) or inline |
|
|
48
|
-
| `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`,
|
|
49
|
-
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`,
|
|
50
|
-
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1456) or inline |
|
|
51
|
-
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated |
|
|
45
|
+
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 1056 |
|
|
46
|
+
| `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 | 1161 |
|
|
47
|
+
| `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`, 1458) or inline | 1241 |
|
|
48
|
+
| `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1277) or inline | 1149 |
|
|
49
|
+
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1415) or inline | 1315 |
|
|
50
|
+
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1456) or inline | 1320 |
|
|
51
|
+
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 2000 |
|
|
52
52
|
|
|
53
53
|
Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
|
|
54
54
|
routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is the
|
|
@@ -108,7 +108,7 @@ CHANGELOG.md release history
|
|
|
108
108
|
1. **Skills + prompts** — install an immutable tag, not a branch:
|
|
109
109
|
|
|
110
110
|
```
|
|
111
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v4.
|
|
111
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v4.5.0
|
|
112
112
|
```
|
|
113
113
|
|
|
114
114
|
The `pi` manifest registers the seven skills, the four `/principal-*` commands, and the
|
|
@@ -181,11 +181,11 @@ Two opt-in routing checks use only the seven authored frontmatter descriptions.
|
|
|
181
181
|
`npm run check:routing-collisions` for all 42 directed description pairs and
|
|
182
182
|
`npm run check:routing-triggers` for the three-run synthetic trigger suite. Both require
|
|
183
183
|
`FIREWORKS_API_KEY`; `ROUTING_MODEL` and `ROUTING_API_URL` override the defaults. The suite
|
|
184
|
-
starts with 12 positives and 8 near-miss negatives per skill
|
|
185
|
-
and no-skill probes, and reports per-skill precision and recall
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
184
|
+
starts with 12 positives and 8 near-miss negatives per skill (14 positives for git-ops), then
|
|
185
|
+
adds authored collision-boundary and no-skill probes, and reports per-skill precision and recall
|
|
186
|
+
at a 0.5 vote threshold. `evals/baseline/triggers.json` records the expanded three-run corpus;
|
|
187
|
+
the obsolete pre-expansion record was removed. Regenerate the baseline after any corpus or
|
|
188
|
+
routing-description change.
|
|
189
189
|
|
|
190
190
|
## Why 4.0
|
|
191
191
|
|
|
@@ -62,8 +62,10 @@ plan is a statement about dependencies, not a licence for concurrent edits.
|
|
|
62
62
|
as if it were valid-but-empty is suppression with extra steps.
|
|
63
63
|
6. **Self-review the diff before declaring done**: leftover print statements, dead code,
|
|
64
64
|
swallowed errors, hardcoded secrets, tests that assert nothing.
|
|
65
|
-
7. **Report honestly.** Run the full suite and report actual results verbatim.
|
|
66
|
-
|
|
65
|
+
7. **Report honestly.** Run the full suite and report actual results verbatim. Use the
|
|
66
|
+
repository's declared full test command verbatim — `package.json` `test`, the Makefile
|
|
67
|
+
target, or whatever its CI runs — and report the exact passing and total counts from
|
|
68
|
+
its output; a narrower command is not evidence. Name anything hacky, guessed, or skipped. If the user insisted on skipping tests, deliver
|
|
67
69
|
the code marked `UNTESTED (per request)` with the risk named — never a silent skip.
|
|
68
70
|
|
|
69
71
|
## Repair mode
|
|
@@ -68,8 +68,9 @@ ships is a failed review.
|
|
|
68
68
|
change: read it once and do not re-derive it. The build report's `Full evidence:` line,
|
|
69
69
|
when it names the exact command and a verbatim result, is test evidence — do not re-run
|
|
70
70
|
the suite to confirm it; run one targeted test only when reading the code raises a
|
|
71
|
-
specific doubt, and say which doubt.
|
|
72
|
-
|
|
71
|
+
specific doubt, and say which doubt. If CI ran for the same commit, compare the build's
|
|
72
|
+
reported total with CI's test count; a mismatch is a finding. Destructive probes (revert
|
|
73
|
+
the fix, break an input) and any run against a dirty tree belong in a disposable copy, never the caller checkout:
|
|
73
74
|
`npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree
|
|
74
75
|
holding the exact working state. Work there, then `remove` it. If creation fails, only
|
|
75
76
|
read or run a read-only check and return UNVERIFIED; never mutate the caller checkout.
|
package/architect/SKILL.md
CHANGED
|
@@ -1,11 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: architect
|
|
3
3
|
description: >
|
|
4
|
-
Use
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
design (decide), or code-level planning of one change (plan).
|
|
4
|
+
Use when the user needs a system structure — components, boundaries, data, and their
|
|
5
|
+
relationships — from measurable drivers: "how should I structure", "design a system",
|
|
6
|
+
"review our architecture", or "write an ADR". The output is that structure. Not for
|
|
7
|
+
choosing whether or which option to take (decide), or ordering implementation work (plan).
|
|
9
8
|
# context:summary (pi-daddy 0.33.0+; also permits pruned, files): delegated, architect cannot ask,
|
|
10
9
|
# and its drivers are the constraints the user stated in the parent's dialogue.
|
|
11
10
|
allowed-tools: read, grep, find, ls, context:summary
|
package/build/SKILL.md
CHANGED
|
@@ -49,8 +49,10 @@ plan is a statement about dependencies, not a licence for concurrent edits.
|
|
|
49
49
|
as if it were valid-but-empty is suppression with extra steps.
|
|
50
50
|
6. **Self-review the diff before declaring done**: leftover print statements, dead code,
|
|
51
51
|
swallowed errors, hardcoded secrets, tests that assert nothing.
|
|
52
|
-
7. **Report honestly.** Run the full suite and report actual results verbatim.
|
|
53
|
-
|
|
52
|
+
7. **Report honestly.** Run the full suite and report actual results verbatim. Use the
|
|
53
|
+
repository's declared full test command verbatim — `package.json` `test`, the Makefile
|
|
54
|
+
target, or whatever its CI runs — and report the exact passing and total counts from
|
|
55
|
+
its output; a narrower command is not evidence. Name anything hacky, guessed, or skipped. If the user insisted on skipping tests, deliver
|
|
54
56
|
the code marked `UNTESTED (per request)` with the risk named — never a silent skip.
|
|
55
57
|
|
|
56
58
|
## Repair mode
|
package/debug/SKILL.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: debug
|
|
3
3
|
description: >
|
|
4
|
-
Use when
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
Use when the user wants the cause of a code, test, lint, runtime, or CI failure — including
|
|
5
|
+
one that began after a Git operation. The output is a diagnosis. Not for a Git command
|
|
6
|
+
failure, acting on Git/GitHub, or answering a repository-state question (git-ops), or
|
|
7
|
+
implementing a known fix (build).
|
|
8
8
|
allowed-tools: read, grep, find, ls, bash, context:files
|
|
9
9
|
---
|
|
10
10
|
|
package/decide/SKILL.md
CHANGED
|
@@ -1,12 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: decide
|
|
3
3
|
description: >
|
|
4
|
-
Use when the user
|
|
5
|
-
"
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
designing how a system is structured (architect), planning implementation (plan), or
|
|
9
|
-
writing code (build).
|
|
4
|
+
Use when the user needs a choice with a rationale — "should I", "what are my options",
|
|
5
|
+
"is this a good idea", or an unsettled build-vs-buy, vendor, or delivery decision. The
|
|
6
|
+
output is one choice and why. Not for defining components, boundaries, or data
|
|
7
|
+
(architect), or ordering implementation work (plan).
|
|
10
8
|
# context:summary (pi-daddy 0.33.0+; also permits pruned, files): delegated, decide cannot ask,
|
|
11
9
|
# and the options already weighed and rejected live only in the parent's dialogue.
|
|
12
10
|
allowed-tools: read, grep, find, ls, context:summary
|
package/git-ops/SKILL.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: git-ops
|
|
3
3
|
description: >
|
|
4
|
-
Use
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
Use when the user wants Git/GitHub work or a repository-state answer — commits, branches,
|
|
5
|
+
pull requests, rebases, merges, tags, history, conflicts, missing commits, command or
|
|
6
|
+
checkout errors, and leaked secrets. The output is a safe repository result. Not for
|
|
7
|
+
diagnosing why code, tests, lint, runtime, or CI failed, even after a Git operation (debug).
|
|
8
8
|
# No context: capability, deliberately. Repo state, not conversation; destructive-op consent
|
|
9
9
|
# comes from the user, never from forwarded turns.
|
|
10
10
|
allowed-tools: read, bash
|
|
@@ -135,11 +135,19 @@ the rewrite IS the operation, and their version is not the primary or the fallba
|
|
|
135
135
|
| Find the breaking commit | `git bisect run <test-command>` |
|
|
136
136
|
|
|
137
137
|
## Finish mode
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
138
|
+
On a reviewed branch, rerun the full suite on the integration tree and quote the result.
|
|
139
|
+
Then offer exactly three choices and wait: **merge locally**, **push and open a PR**, or
|
|
140
|
+
**keep the branch**. Discard only on explicit request after naming the branch,
|
|
141
|
+
commits, and worktree.
|
|
142
|
+
|
|
143
|
+
When `PI_DADDY_EPISODE` is set, append these trailers. Missing companion variables use
|
|
144
|
+
empty values; never fail the commit:
|
|
145
|
+
```
|
|
146
|
+
Pi-Episode: $PI_DADDY_EPISODE
|
|
147
|
+
Pi-Definition: $PI_DADDY_DEFINITION
|
|
148
|
+
Pi-Execution: $PI_DADDY_EXECUTION
|
|
149
|
+
```
|
|
150
|
+
When it is unset, append nothing.
|
|
143
151
|
|
|
144
152
|
## Right-sizing
|
|
145
153
|
A one-word docs fix gets a clean commit with a good message — not a branch-and-PR dance
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "principal-pi-skills",
|
|
3
|
-
"version": "4.
|
|
3
|
+
"version": "4.5.0",
|
|
4
4
|
"description": "Skill framework for principal-level software engineering: seven dual-use skills (decide, architect, plan, build, review, debug, git-ops), a pi bootstrap, and two approval-gated workflows.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Nemanja Alavanja",
|
package/plan/SKILL.md
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: plan
|
|
3
3
|
description: >
|
|
4
|
-
Use when
|
|
5
|
-
"
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
Use when the user needs an ordered sequence of implementation work — "break this down",
|
|
5
|
+
"where do I start", "what's the order of work", "scope this refactor", or "plan the fix".
|
|
6
|
+
The output is that executable sequence with per-step specs. Not for choosing the direction
|
|
7
|
+
(decide), defining components, boundaries, or data (architect), diagnosing failures
|
|
8
|
+
(debug), or writing code (build).
|
|
8
9
|
allowed-tools: read, grep, find, ls, write, context:summary
|
|
9
10
|
---
|
|
10
11
|
|
package/review/SKILL.md
CHANGED
|
@@ -61,8 +61,9 @@ ships is a failed review.
|
|
|
61
61
|
change: read it once and do not re-derive it. The build report's `Full evidence:` line,
|
|
62
62
|
when it names the exact command and a verbatim result, is test evidence — do not re-run
|
|
63
63
|
the suite to confirm it; run one targeted test only when reading the code raises a
|
|
64
|
-
specific doubt, and say which doubt.
|
|
65
|
-
|
|
64
|
+
specific doubt, and say which doubt. If CI ran for the same commit, compare the build's
|
|
65
|
+
reported total with CI's test count; a mismatch is a finding. Destructive probes (revert
|
|
66
|
+
the fix, break an input) and any run against a dirty tree belong in a disposable copy, never the caller checkout:
|
|
66
67
|
`npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree
|
|
67
68
|
holding the exact working state. Work there, then `remove` it. If creation fails, only
|
|
68
69
|
read or run a read-only check and return UNVERIFIED; never mutate the caller checkout.
|