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 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.4.0` — installs the seven
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. The committed collision baseline records three overlaps; the original
17
- trigger run is retained as pre-expansion evidence, not claimed as a score for the expanded
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 | 1080 |
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 | 1172 |
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 | 1237 |
48
- | `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1240) or inline | 1112 |
49
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1394) or inline | 1294 |
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 | 1322 |
51
- | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1996 |
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.4.0
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, then adds authored collision-boundary
185
- and no-skill probes, and reports per-skill precision and recall at a 0.5 vote threshold. The
186
- original 140-case record is retained as `evals/baseline/triggers.pre-expansion.json`; it is
187
- not evidence for the expanded corpus. Regenerate `evals/baseline/triggers.json` after any
188
- corpus change.
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. Name
66
- anything hacky, guessed, or skipped. If the user insisted on skipping tests, deliver
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. Destructive probes (revert the fix, break an input)
72
- and any run against a dirty tree belong in a disposable copy, never the caller checkout:
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.
@@ -1,11 +1,10 @@
1
1
  ---
2
2
  name: architect
3
3
  description: >
4
- Use for how a system should be structured — "how should I structure", "design a system
5
- that", "SQL vs NoSQL for this workload", "monolith vs services", "review our
6
- architecture", "plan the migration", "write an ADR". The output is a design note with
7
- measurable drivers. Not for a yes/no or which-vendor decision without a structure to
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. Name
53
- anything hacky, guessed, or skipped. If the user insisted on skipping tests, deliver
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 diagnosing a failure — a failing or flaky test, a stack trace, a crash, a CI or
5
- lint error — "why is this failing", "find the bug", "debug this", "it crashes when",
6
- "works on my machine". Not for writing new features or fixing a bug whose cause is
7
- already known (build).
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 is choosing rather than executing — "should I", "what are my options",
5
- "which approach", "is this a good idea", "what could go wrong", "I'm stuck" — on any
6
- engineering, delivery, or team decision that isn't settled: build vs buy, which vendor,
7
- whether to migrate, scope and sequencing, process. The output is a decision brief. Not for
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 for any git or GitHub operation — "commit", "push", "open a PR", "new branch",
5
- "rebase", "merge", "tag a release", "who wrote this", "when did this break", "undo
6
- this", "wrong branch", "lost commits", "I leaked a secret", CI failures. Safe operator:
7
- refuses history rewrites on shared branches, scans for secrets before committing.
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
- When a workflow hands you a reviewed branch: run the full suite on the tree you are about
139
- to integrate and quote the result line — a green run earlier in the session proves nothing
140
- about this tree. Then offer exactly three choices and wait: **merge locally**, **push and
141
- open a PR**, or **keep the branch**. Discarding work happens only on an explicit request,
142
- with the branch, commits, and worktree named before the user confirms.
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.4.0",
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 turning a decision, feature, or multi-step task into an executable plan —
5
- "break this down", "how should I implement this", "where do I start", "what's the order
6
- of work", "scope this refactor", "plan the fix". Produces the plan and per-step specs;
7
- writes no code. Not for system-level design (architect) or diagnosing failures (debug).
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. Destructive probes (revert the fix, break an input)
65
- and any run against a dirty tree belong in a disposable copy, never the caller checkout:
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.