principal-pi-skills 4.4.0 → 4.6.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 +13 -10
- package/CHANGELOG.md +40 -3
- package/README.md +37 -34
- package/agents/principal-build.md +4 -2
- package/agents/principal-investigate.md +51 -0
- package/agents/principal-review.md +3 -2
- package/architect/SKILL.md +4 -5
- package/bootstrap/BOOTSTRAP.md +4 -3
- package/build/SKILL.md +4 -2
- package/debug/SKILL.md +4 -4
- package/decide/SKILL.md +4 -6
- package/git-ops/SKILL.md +29 -9
- package/investigate/SKILL.md +49 -0
- package/package.json +4 -2
- package/plan/SKILL.md +5 -4
- package/review/SKILL.md +3 -2
package/AGENTS.md
CHANGED
|
@@ -22,7 +22,7 @@ The set:
|
|
|
22
22
|
|
|
23
23
|
- Skills (inline only): `decide`, `architect`, `git-ops`.
|
|
24
24
|
- Agents (delegate when the subagent tool is available): `principal-plan`,
|
|
25
|
-
`principal-build`, `principal-review`, `principal-debug` — defined in `agents/`. Each
|
|
25
|
+
`principal-build`, `principal-review`, `principal-debug`, `principal-investigate` — defined in `agents/`. Each
|
|
26
26
|
contract also has a SKILL.md for interactive use when delegation is unavailable or the
|
|
27
27
|
user wants to work through it conversationally.
|
|
28
28
|
|
|
@@ -36,6 +36,7 @@ The set:
|
|
|
36
36
|
| Code to write ("implement", "fix this known bug", "make the test pass") | `build` | inline, or `principal-build` per approved plan step when the subagent tool exists — never fan parallel writers into one working tree |
|
|
37
37
|
| 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 |
|
|
38
38
|
| 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 |
|
|
39
|
+
| Facts about current code, data, runtime, or history ("how does", "where is", "map", "what changed between") | `investigate` | **subagent** for heavy reading; inline when dialogue is needed |
|
|
39
40
|
| 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 destructive ops require user consequence-acceptance no subagent can obtain |
|
|
40
41
|
|
|
41
42
|
**When more than one applies**, route by altitude: the highest-altitude match for the
|
|
@@ -60,10 +61,11 @@ an interpretation. The complete set:
|
|
|
60
61
|
| debug | `build` · `plan` · `done` · `blocked` |
|
|
61
62
|
| build | `review` · `debug` · `blocked` |
|
|
62
63
|
| review | `build` · `git-ops` |
|
|
63
|
-
| decide · architect · git-ops | *(none — they terminate)* |
|
|
64
|
+
| decide · architect · investigate · git-ops | *(none — they terminate)* |
|
|
64
65
|
|
|
65
66
|
`decide` and `architect` end in a judgment the user acts on, not a handoff a workflow routes;
|
|
66
|
-
`git-ops` runs inline
|
|
67
|
+
`investigate` ends in a factual report and `git-ops` runs inline. A ceremonial `Next:` on
|
|
68
|
+
those four invited
|
|
67
69
|
a workflow to route somewhere nobody asked to go. Every value above is consumed by both
|
|
68
70
|
workflow prompts, and a unit test fails if a contract declares a value no workflow handles
|
|
69
71
|
or a workflow handles one no contract can emit.
|
|
@@ -94,14 +96,14 @@ user; don't answer it yourself and keep going.
|
|
|
94
96
|
|
|
95
97
|
## Maintenance rule — the contracts are generated
|
|
96
98
|
|
|
97
|
-
`plan`, `build`, `review` and `
|
|
99
|
+
`plan`, `build`, `review`, `debug` and `investigate` exist twice: `<name>/SKILL.md` (interactive contract)
|
|
98
100
|
and `agents/principal-<name>.md` (the single-shot contract subagents get) — different
|
|
99
101
|
artifacts, not copies, but most of each pair is identical, and that shared majority is
|
|
100
102
|
where they used to drift.
|
|
101
103
|
|
|
102
104
|
Both are generated from `contracts/<name>.md.tmpl`. The two namespaced workflows are
|
|
103
|
-
likewise generated from `contracts/workflows.md.tmpl` —
|
|
104
|
-
template are the source of everything under `agents/`, `prompts/`, and the
|
|
105
|
+
likewise generated from `contracts/workflows.md.tmpl` — five contracts plus the workflows
|
|
106
|
+
template are the source of everything under `agents/`, `prompts/`, and the five dual-use
|
|
105
107
|
`SKILL.md` files. Change shared behavior ONCE, there, then `npm run generate`. Editing a
|
|
106
108
|
generated file directly is reverted by the next run and fails `npm run generate:check` in
|
|
107
109
|
CI.
|
|
@@ -113,16 +115,17 @@ to every output.
|
|
|
113
115
|
|
|
114
116
|
## Setup (pi)
|
|
115
117
|
|
|
116
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.
|
|
118
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.6.0` installs the eight
|
|
117
119
|
skills, the four `/principal-*` commands, and the bootstrap
|
|
118
120
|
extension, which loads automatically with the package. Install a tag, not a branch.
|
|
119
121
|
2. Subagents (optional): `npx -p principal-pi-skills principal-pi-agents install` copies
|
|
120
|
-
the
|
|
122
|
+
the five agent definitions into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses
|
|
121
123
|
to overwrite anything it did not install. Without it, everything in the routing table
|
|
122
124
|
above still runs; the How column just collapses to "inline".
|
|
123
125
|
3. Context handoff (pi-daddy 0.33.0+): each skill's `allowed-tools` sets how much of this
|
|
124
126
|
session a delegated child may receive. `architect`, `decide` and `plan` allow
|
|
125
|
-
`context:summary`. `build`, `debug` and `
|
|
126
|
-
|
|
127
|
+
`context:summary`. `build`, `debug`, `review` and `investigate` allow `context:files`: review
|
|
128
|
+
stays low so it judges cold; investigate receives named evidence, not reasoning.
|
|
129
|
+
`git-ops` allows none, on purpose. Each reason is in the
|
|
127
130
|
skill's frontmatter and the README install section, along with the egress note. Don't
|
|
128
131
|
ask a child for more than its ceiling, and don't raise a ceiling to make a refusal go away.
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,43 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [4.6.0] — 2026-09-29
|
|
10
|
+
|
|
11
|
+
**Added — read-only investigation with cited facts (#56).** `investigate` reports how code,
|
|
12
|
+
data, runtime, or history currently behaves without changing, fixing, choosing, or giving a
|
|
13
|
+
merge verdict. PR #56 registered the eighth skill and its read-only agent at every install,
|
|
14
|
+
routing, packaging, and verification point; added a 25-record boundary corpus; narrowed
|
|
15
|
+
`git-ops` to repository actions; and recorded eight-skill routing baselines.
|
|
16
|
+
|
|
17
|
+
**Added — repository-native release mode (#57).** `git-ops` now reads the prior release and
|
|
18
|
+
replicates its branch, PR, commit, and annotated-tag shape; bumps every version occurrence;
|
|
19
|
+
writes the changelog in repository style; runs the full suite; and stops before publishing
|
|
20
|
+
with the repository's next publish command. PR #57 added the release boundary records and
|
|
21
|
+
refreshed both routing baselines.
|
|
22
|
+
|
|
23
|
+
**Changed defaults.** The installed set now includes `investigate`; previously factual
|
|
24
|
+
questions about the current repository had no skill. `git-ops` now handles “cut a release”
|
|
25
|
+
as a release mode; previously it had no explicit release workflow.
|
|
26
|
+
|
|
27
|
+
## [4.5.0] — 2026-09-29
|
|
28
|
+
|
|
29
|
+
**Routing by output, with stable evidence (#51, #52, #53, #54).** PR #51 moved the routing
|
|
30
|
+
model to `glm-5p3-flash` because `glm-5p2` is no longer deployed, and separated `debug` from
|
|
31
|
+
`git-ops` by what each produces. PR #52 made the collision check report STABLE (collided in
|
|
32
|
+
every run) and ANY (collided in any run) over three runs, and fail only on STABLE. PR #53
|
|
33
|
+
expanded the decide/architect/plan boundary corpus. PR #54 separated those three descriptions
|
|
34
|
+
by output — a choice with rationale, a system structure, or an ordered sequence of work — and
|
|
35
|
+
narrowed `decide`. The adversarial corpus grew from 34 to 54 records, and every label now
|
|
36
|
+
follows the rule that a skill is chosen by what it produces.
|
|
37
|
+
|
|
38
|
+
**Stronger delivery evidence and attribution.** `git-ops` stamps `Pi-Episode`,
|
|
39
|
+
`Pi-Definition`, and `Pi-Execution` trailers on commits when pi-daddy exports them. `build`
|
|
40
|
+
and `review` require the repository's full test command as evidence, rather than treating
|
|
41
|
+
focused checks as sufficient.
|
|
42
|
+
|
|
43
|
+
**Changed defaults.** None for users. Routing evaluations require `FIREWORKS_API_KEY` and now
|
|
44
|
+
default to `glm-5p3-flash`.
|
|
45
|
+
|
|
9
46
|
## [4.4.0] — 2026-09-23
|
|
10
47
|
|
|
11
48
|
**Added — local routing evaluation for the seven skill descriptions.** A shared loader reads
|
|
@@ -13,9 +50,9 @@ only authored `SKILL.md` frontmatter descriptions. Opt-in checks cover all 42 di
|
|
|
13
50
|
pairwise collisions and a three-run trigger corpus with per-skill precision and recall,
|
|
14
51
|
collision-boundary cases, explicit `AMBIGUOUS` labels, and `NO_SKILL` hard negatives. Model
|
|
15
52
|
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.
|
|
53
|
+
a Fireworks key. At the 4.4.0 release, the committed collision baseline recorded three
|
|
54
|
+
overlaps and the original trigger run was retained as pre-expansion evidence, not claimed
|
|
55
|
+
as a score for the expanded corpus because Fireworks was unavailable for that rerun.
|
|
19
56
|
|
|
20
57
|
## [4.3.0] — 2026-09-22
|
|
21
58
|
|
package/README.md
CHANGED
|
@@ -1,13 +1,14 @@
|
|
|
1
1
|
# principal-pi-skills
|
|
2
2
|
|
|
3
|
-
**
|
|
4
|
-
[pi coding agent](https://github.com/badlogic/pi-mono) — three inline skills and
|
|
3
|
+
**Eight skills for principal-level software engineering with the
|
|
4
|
+
[pi coding agent](https://github.com/badlogic/pi-mono) — three inline skills and five
|
|
5
5
|
that double as subagents.** Dialogue and session state run inline (`decide`, `architect`,
|
|
6
6
|
`git-ops`); heavy reading, cold judgment, and noisy loops delegate to isolated contexts
|
|
7
|
-
(`plan`, `build`, `review`, `debug` — single-shot variants in `agents/`,
|
|
8
|
-
same contract as the skill). The files follow the
|
|
9
|
-
standard, so other harnesses can
|
|
10
|
-
is **4.x**: a thin orchestration
|
|
7
|
+
(`plan`, `build`, `review`, `debug`, `investigate` — single-shot variants in `agents/`,
|
|
8
|
+
generated from the same contract as the skill). The files follow the
|
|
9
|
+
[Agent Skills](https://agentskills.io/specification) standard, so other harnesses can
|
|
10
|
+
consume the skills, but pi is the supported target. This is **4.x**: a thin orchestration
|
|
11
|
+
layer over the eight skills, with the risk-adaptive
|
|
11
12
|
assurance controller and model measurement removed to a separate track (see
|
|
12
13
|
[Validation](#validation)).
|
|
13
14
|
|
|
@@ -19,7 +20,7 @@ around.
|
|
|
19
20
|
|
|
20
21
|
## Three constraints
|
|
21
22
|
|
|
22
|
-
1. **Dual-use.** `plan`, `build`, `review`, and `
|
|
23
|
+
1. **Dual-use.** `plan`, `build`, `review`, `debug`, and `investigate` each serve as a loaded skill *and*
|
|
23
24
|
as a subagent system prompt. Both forms are rendered from one contract, so the shared
|
|
24
25
|
behavior cannot drift between them, and the differences — single-shot mechanics, the
|
|
25
26
|
BLOCKED form, no-dialogue rules — are marked rather than remembered. That constraint is
|
|
@@ -29,10 +30,9 @@ around.
|
|
|
29
30
|
plain-text tags (`[ONE-WAY]`, `[BLOCKER]`) instead of an emoji schema, no aphorisms
|
|
30
31
|
doing load-bearing work, no personas, no required reading in reference files.
|
|
31
32
|
3. **Token economics.** Budgets stated as decisions rather than aspirations: **skills
|
|
32
|
-
≤ 1400 words**, **agents ≤ 1500**, and **`git-ops` an accepted exception at ≤
|
|
33
|
+
≤ 1400 words**, **agents ≤ 1500**, and **`git-ops` an accepted exception at ≤ 2150** —
|
|
33
34
|
the safety-critical operator carries the most arming, and validated behavior outweighs
|
|
34
|
-
a budget.
|
|
35
|
-
prose: an absolute is cheap to write and wrong in real cases, and a rule plus the cases
|
|
35
|
+
a budget. Ceilings move only to buy a fix rather than more prose: an absolute is cheap to write and wrong in real cases, and a rule plus the cases
|
|
36
36
|
it must not eat costs more words than the absolute it replaced. **When a fix and the
|
|
37
37
|
ceiling conflict, the ceiling moves.** Every count in the table below is checkable with
|
|
38
38
|
`wc -w`. Nothing loads anything else — a subagent reads one file and has the whole
|
|
@@ -42,13 +42,14 @@ 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
|
-
| `
|
|
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
|
+
| `investigate` | A factual report of how code, data, runtime, or history currently behaves, with file-and-line citations | subagent (`agents/principal-investigate.md`, 395) or inline | 396 |
|
|
52
|
+
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 2145 |
|
|
52
53
|
|
|
53
54
|
Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
|
|
54
55
|
routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is the
|
|
@@ -91,8 +92,8 @@ being asked.
|
|
|
91
92
|
|
|
92
93
|
```
|
|
93
94
|
<skill>/SKILL.md the interactive contract — nothing else is required reading
|
|
94
|
-
agents/principal-{plan,build,review,debug}.md subagent definitions
|
|
95
|
-
contracts/{plan,build,review,debug}.md.tmpl source for dual-use contracts — edit here, run `npm run generate`
|
|
95
|
+
agents/principal-{plan,build,review,debug,investigate}.md subagent definitions available for delegation
|
|
96
|
+
contracts/{plan,build,review,debug,investigate}.md.tmpl source for dual-use contracts — edit here, run `npm run generate`
|
|
96
97
|
contracts/workflows.md.tmpl source for the two namespaced spines
|
|
97
98
|
prompts/principal-{feature,bugfix}.md generated workflows
|
|
98
99
|
bootstrap/BOOTSTRAP.md routing table + Next: vocabulary + model tiering, injected by the extension
|
|
@@ -108,11 +109,11 @@ CHANGELOG.md release history
|
|
|
108
109
|
1. **Skills + prompts** — install an immutable tag, not a branch:
|
|
109
110
|
|
|
110
111
|
```
|
|
111
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v4.
|
|
112
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v4.6.0
|
|
112
113
|
```
|
|
113
114
|
|
|
114
|
-
The `pi` manifest registers the
|
|
115
|
-
bootstrap extension — it loads automatically with
|
|
115
|
+
The v4.6.0 `pi` manifest registers the eight skills, the four `/principal-*` commands,
|
|
116
|
+
and the bootstrap extension — it loads automatically with
|
|
116
117
|
the package; there is no separate extension-install step. Unpinned `main` moves under
|
|
117
118
|
you, so install a tag if you want a fixed, nameable behavior.
|
|
118
119
|
|
|
@@ -120,21 +121,22 @@ CHANGELOG.md release history
|
|
|
120
121
|
`principal-pi-workspace remove` deletes any path handed to it, including your checkout,
|
|
121
122
|
and reports success. `2.3.1` is the lowest safe version.
|
|
122
123
|
|
|
123
|
-
2. **Subagents (optional).** Install the
|
|
124
|
+
2. **Subagents (optional).** Install the five agent definitions:
|
|
124
125
|
|
|
125
126
|
```
|
|
126
127
|
npx -p principal-pi-skills principal-pi-agents install # → ${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents
|
|
127
128
|
npx -p principal-pi-skills principal-pi-agents check # verify they are present and current
|
|
128
129
|
```
|
|
129
130
|
|
|
130
|
-
It installs `principal-plan`, `principal-build`, `principal-review`,
|
|
131
|
-
`principal-
|
|
131
|
+
It installs `principal-plan`, `principal-build`, `principal-review`, `principal-debug`,
|
|
132
|
+
and `principal-investigate` as **real files, not symlinks** — a symlink into a checkout breaks the
|
|
132
133
|
moment that directory moves, and breaks silently, since pi just reports an unknown
|
|
133
134
|
agent. It refuses to overwrite anything it did not install, and `uninstall` removes only
|
|
134
135
|
its own unmodified files.
|
|
135
136
|
|
|
136
|
-
Tool restriction is structural, in the agents' frontmatter: `
|
|
137
|
-
`
|
|
137
|
+
Tool restriction is structural, in the agents' frontmatter: `investigate` is read-only;
|
|
138
|
+
`plan` is read-only except for its own plan file; `build`, `review`, and `debug` add
|
|
139
|
+
`bash` to run tests (and, for `build`, to write and edit).
|
|
138
140
|
|
|
139
141
|
One trap worth knowing if you run subagents on a non-default provider: a delegated agent
|
|
140
142
|
runs on the pi config's `defaultProvider`/`defaultModel`, **not** the
|
|
@@ -159,6 +161,7 @@ CHANGELOG.md release history
|
|
|
159
161
|
| `plan` | `context:summary` | a plan must honour what the user ruled out, which a task line flattens; no `bash` |
|
|
160
162
|
| `review` | `context:files` | **deliberately low.** Review is cold by design, and the author's reasoning is what it must not be anchored on; the diff package and build report are files |
|
|
161
163
|
| `build`, `debug` | `context:files` | they act on a stated target (a plan file or a symptom); logs travel verbatim as files; with `bash`, anything a child receives can leave the machine |
|
|
164
|
+
| `investigate` | `context:files` | receives only named evidence and has no shell or write tools; the caller's reasoning is not evidence |
|
|
162
165
|
| `git-ops` | none | acts on the working tree, not the conversation; consent to a destructive op must come from the user, not from forwarded turns |
|
|
163
166
|
|
|
164
167
|
Nothing declares `context:fork`. Write the prefix in lowercase: `Context:summary` turns
|
|
@@ -177,15 +180,15 @@ CHANGELOG.md release history
|
|
|
177
180
|
`npm test` remains the free gate: generated-contract drift, word budgets, frontmatter lint,
|
|
178
181
|
installer and tarball behavior, and `Next:` transition parity.
|
|
179
182
|
|
|
180
|
-
Two opt-in routing checks use only the
|
|
181
|
-
`npm run check:routing-collisions` for all
|
|
183
|
+
Two opt-in routing checks use only the eight authored frontmatter descriptions. Run
|
|
184
|
+
`npm run check:routing-collisions` for all 56 directed description pairs and
|
|
182
185
|
`npm run check:routing-triggers` for the three-run synthetic trigger suite. Both require
|
|
183
186
|
`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
|
|
185
|
-
and no-skill probes, and reports per-skill precision and recall
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
|
|
187
|
+
starts with 12 positives and 8 near-miss negatives per skill, then
|
|
188
|
+
adds authored collision-boundary and no-skill probes, and reports per-skill precision and recall
|
|
189
|
+
at a 0.5 vote threshold. `evals/baseline/triggers.json` records the expanded three-run corpus;
|
|
190
|
+
the obsolete pre-expansion record was removed. Regenerate the baseline after any corpus or
|
|
191
|
+
routing-description change.
|
|
189
192
|
|
|
190
193
|
## Why 4.0
|
|
191
194
|
|
|
@@ -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
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: principal-investigate
|
|
3
|
+
description: >
|
|
4
|
+
Delegate to this agent to report how code, data, runtime, or history currently behaves or
|
|
5
|
+
is laid out. Returns facts with file and line citations. Changes nothing, fixes nothing,
|
|
6
|
+
and makes no choice or verdict. Not for diagnosing failures, reviewing diffs, repository
|
|
7
|
+
actions, decisions, or target designs.
|
|
8
|
+
tools: read, grep, find, ls
|
|
9
|
+
allowed-tools: read, grep, find, ls, context:files
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Investigate — Facts About What Is
|
|
13
|
+
|
|
14
|
+
Report the current state of code, data, runtime, or history. Establish facts; do not turn
|
|
15
|
+
those facts into a fix, recommendation, design, merge verdict, or repository action.
|
|
16
|
+
|
|
17
|
+
You run in an isolated context and cannot ask questions. **The caller receives ONLY your
|
|
18
|
+
final message.** Make that message the complete report in the format below.
|
|
19
|
+
|
|
20
|
+
## Method
|
|
21
|
+
1. **State the question.** Restate the factual question narrowly enough that the report has
|
|
22
|
+
a clear boundary. Preserve qualifiers such as environment, version, time range, and
|
|
23
|
+
subsystem.
|
|
24
|
+
2. **Read the evidence.** Trace definitions to callers and data to consumers. Prefer the
|
|
25
|
+
implementation and observed artifacts over names, comments, or architecture documents.
|
|
26
|
+
Do not infer runtime behavior from source when configuration or state can change it;
|
|
27
|
+
label what the available evidence cannot establish.
|
|
28
|
+
3. **Cite every finding.** Attach a `path:line` or `path:start-end` citation to each code or
|
|
29
|
+
data claim. For history, identify the revision and cite the affected file and lines.
|
|
30
|
+
Separate observation from inference, and say when sources disagree.
|
|
31
|
+
4. **Stay read-only.** Do not edit files, run mutating commands, create commits, fix a
|
|
32
|
+
discovered defect, choose among options, propose a target design, or judge whether a
|
|
33
|
+
diff should land. A factual answer may expose a problem; naming the problem is not
|
|
34
|
+
permission to solve or review it.
|
|
35
|
+
5. **Stop at scope creep.** A request that expands into a cause, fix, choice, verdict,
|
|
36
|
+
design, or action belongs to another skill. Stop at the original factual boundary and
|
|
37
|
+
put the additional work under `What was not checked`; do not cross the boundary by
|
|
38
|
+
appending advice.
|
|
39
|
+
|
|
40
|
+
## Output — investigation report
|
|
41
|
+
```
|
|
42
|
+
## Investigation: <question, one line>
|
|
43
|
+
Question: <the factual scope, including version/environment/time range>
|
|
44
|
+
Findings:
|
|
45
|
+
- <fact> — <path:line or path:start-end>
|
|
46
|
+
- <fact> — <path:line or path:start-end>
|
|
47
|
+
What was not checked: <unavailable evidence and out-of-scope follow-ons> | none
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
A report with no supported finding says so. Never fill the gap with a likely explanation,
|
|
51
|
+
a proposed fix, or a verdict.
|
|
@@ -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/bootstrap/BOOTSTRAP.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# principal-pi-skills bootstrap
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Eight skills are installed. Route by what the input looks like; when none fits, answer
|
|
4
4
|
normally — everyday Q&A does not need the framework.
|
|
5
5
|
|
|
6
6
|
| Input shape | Route to | How |
|
|
@@ -11,12 +11,13 @@ normally — everyday Q&A does not need the framework.
|
|
|
11
11
|
| "implement", "fix this known bug", "make the test pass" | `build` | inline, or `principal-build` per approved plan step |
|
|
12
12
|
| "review this", "ready to merge?" | `review` | `principal-review` agent, always when available |
|
|
13
13
|
| "why is this failing", "find the bug" | `debug` | `principal-debug` agent when reproduction is noisy |
|
|
14
|
+
| "how does", "where is", "map", "what changed between" | `investigate` | `principal-investigate` agent for heavy reading |
|
|
14
15
|
| "commit", "push", "open a PR", "I leaked a secret" | `git-ops` | inline, never delegated |
|
|
15
16
|
|
|
16
17
|
Dialogue and session state stay inline; heavy reading, cold judgment, and noisy loops are
|
|
17
18
|
delegated. A subagent never invokes another agent — you read its `Next:` line and route:
|
|
18
19
|
plan → `build`; debug → `build` `plan` `done` `blocked`; build → `review` `debug` `blocked`;
|
|
19
|
-
review → `build` `git-ops`. `decide`, `architect`, `git-ops` end without a `Next:`.
|
|
20
|
+
review → `build` `git-ops`. `decide`, `architect`, `investigate`, `git-ops` end without a `Next:`.
|
|
20
21
|
|
|
21
22
|
Multi-step work goes through `/principal-feature <task>`, `/principal-bugfix <symptom>`, or
|
|
22
23
|
`/principal-refactor <scope>`; `/principal-review-branch [base]` cold-reviews and finishes a
|
|
@@ -24,4 +25,4 @@ branch built outside them. The spines
|
|
|
24
25
|
which stop for your approval after planning and can resume from `.principal/plans/`.
|
|
25
26
|
|
|
26
27
|
Model choice when you dispatch: cheapest model for a build agent working from a complete
|
|
27
|
-
step spec; session default for plan and
|
|
28
|
+
step spec; session default for plan, debug, and investigate; strongest available for review and architect.
|
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 for
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
4
|
+
Use for Git/GitHub actions — commit, branch, open a PR, rebase, merge,
|
|
5
|
+
tag, resolve a conflict, recover a lost commit, repair a broken checkout, cut a release,
|
|
6
|
+
or remove a leaked secret. The output is a safe repository result. Not for diagnosing why code,
|
|
7
|
+
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
|
|
@@ -134,12 +134,32 @@ the rewrite IS the operation, and their version is not the primary or the fallba
|
|
|
134
134
|
| Undo a pushed commit (shared) | `git revert <sha>` |
|
|
135
135
|
| Find the breaking commit | `git bisect run <test-command>` |
|
|
136
136
|
|
|
137
|
+
## Release mode
|
|
138
|
+
Read the previous release before changing anything: find the last release commit or release
|
|
139
|
+
PR and its tag, then replicate that exact branch/PR/commit/tag shape. Bump every version
|
|
140
|
+
occurrence, including `package.json`, locks, workspace packages, test assertions, and README
|
|
141
|
+
badges. Write the CHANGELOG entry in its existing style; name every PR since the last tag,
|
|
142
|
+
and state each changed default as “X now does Y; previously Z”. Run the repository's full
|
|
143
|
+
test command. Commit. For a PR-shaped release, push the branch, open the PR, and after merge
|
|
144
|
+
identify its integration commit; otherwise commit to main. Create the annotated `vX.Y.Z` tag
|
|
145
|
+
on that final release commit, then push the commit and tag. **STOP before
|
|
146
|
+
publishing.** Report the exact publish command the repository's own release flow would run
|
|
147
|
+
next. If a package has a release guard, never bypass it with a raw `npm publish`.
|
|
148
|
+
|
|
137
149
|
## Finish mode
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
150
|
+
On a reviewed branch, rerun the full suite on the integration tree and quote the result.
|
|
151
|
+
Then offer exactly three choices and wait: **merge locally**, **push and open a PR**, or
|
|
152
|
+
**keep the branch**. Discard only on explicit request after naming the branch,
|
|
153
|
+
commits, and worktree.
|
|
154
|
+
|
|
155
|
+
When `PI_DADDY_EPISODE` is set, append these trailers. Missing companion variables use
|
|
156
|
+
empty values; never fail the commit:
|
|
157
|
+
```
|
|
158
|
+
Pi-Episode: $PI_DADDY_EPISODE
|
|
159
|
+
Pi-Definition: $PI_DADDY_DEFINITION
|
|
160
|
+
Pi-Execution: $PI_DADDY_EXECUTION
|
|
161
|
+
```
|
|
162
|
+
When it is unset, append nothing.
|
|
143
163
|
|
|
144
164
|
## Right-sizing
|
|
145
165
|
A one-word docs fix gets a clean commit with a good message — not a branch-and-PR dance
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: investigate
|
|
3
|
+
description: >
|
|
4
|
+
Use when the user wants to know what is — how code, data, runtime, or history currently
|
|
5
|
+
behaves or is laid out: "how does", "where is", "which", "map", "inventory", "what changed
|
|
6
|
+
between", "which commit", "when did". The output is a factual report with file and line citations. Nothing is changed,
|
|
7
|
+
fixed, or chosen. Not for the cause of a failure (debug), a choice (decide), a verdict on a
|
|
8
|
+
diff (review), acting on the repository (git-ops), or a target design (architect).
|
|
9
|
+
allowed-tools: read, grep, find, ls, context:files
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Investigate — Facts About What Is
|
|
13
|
+
|
|
14
|
+
Report the current state of code, data, runtime, or history. Establish facts; do not turn
|
|
15
|
+
those facts into a fix, recommendation, design, merge verdict, or repository action.
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
## Method
|
|
19
|
+
1. **State the question.** Restate the factual question narrowly enough that the report has
|
|
20
|
+
a clear boundary. Preserve qualifiers such as environment, version, time range, and
|
|
21
|
+
subsystem.
|
|
22
|
+
2. **Read the evidence.** Trace definitions to callers and data to consumers. Prefer the
|
|
23
|
+
implementation and observed artifacts over names, comments, or architecture documents.
|
|
24
|
+
Do not infer runtime behavior from source when configuration or state can change it;
|
|
25
|
+
label what the available evidence cannot establish.
|
|
26
|
+
3. **Cite every finding.** Attach a `path:line` or `path:start-end` citation to each code or
|
|
27
|
+
data claim. For history, identify the revision and cite the affected file and lines.
|
|
28
|
+
Separate observation from inference, and say when sources disagree.
|
|
29
|
+
4. **Stay read-only.** Do not edit files, run mutating commands, create commits, fix a
|
|
30
|
+
discovered defect, choose among options, propose a target design, or judge whether a
|
|
31
|
+
diff should land. A factual answer may expose a problem; naming the problem is not
|
|
32
|
+
permission to solve or review it.
|
|
33
|
+
5. **Stop at scope creep.** A request that expands into a cause, fix, choice, verdict,
|
|
34
|
+
design, or action belongs to another skill. Stop at the original factual boundary and
|
|
35
|
+
put the additional work under `What was not checked`; do not cross the boundary by
|
|
36
|
+
appending advice.
|
|
37
|
+
|
|
38
|
+
## Output — investigation report
|
|
39
|
+
```
|
|
40
|
+
## Investigation: <question, one line>
|
|
41
|
+
Question: <the factual scope, including version/environment/time range>
|
|
42
|
+
Findings:
|
|
43
|
+
- <fact> — <path:line or path:start-end>
|
|
44
|
+
- <fact> — <path:line or path:start-end>
|
|
45
|
+
What was not checked: <unavailable evidence and out-of-scope follow-ons> | none
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
A report with no supported finding says so. Never fill the gap with a likely explanation,
|
|
49
|
+
a proposed fix, or a verdict.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "principal-pi-skills",
|
|
3
|
-
"version": "4.
|
|
4
|
-
"description": "Skill framework for principal-level software engineering:
|
|
3
|
+
"version": "4.6.0",
|
|
4
|
+
"description": "Skill framework for principal-level software engineering: eight skills (decide, architect, plan, build, review, debug, investigate, git-ops), a pi bootstrap, and two approval-gated workflows.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"author": "Nemanja Alavanja",
|
|
7
7
|
"repository": {
|
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
"./build",
|
|
40
40
|
"./review",
|
|
41
41
|
"./debug",
|
|
42
|
+
"./investigate",
|
|
42
43
|
"./git-ops"
|
|
43
44
|
],
|
|
44
45
|
"prompts": [
|
|
@@ -61,6 +62,7 @@
|
|
|
61
62
|
"build/SKILL.md",
|
|
62
63
|
"review/SKILL.md",
|
|
63
64
|
"debug/SKILL.md",
|
|
65
|
+
"investigate/SKILL.md",
|
|
64
66
|
"git-ops/SKILL.md",
|
|
65
67
|
"prompts/*.md",
|
|
66
68
|
"agents/*.md",
|
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.
|