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 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 and terminates the chain. A ceremonial `Next:` on those three invited
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 `debug` exist twice: `<name>/SKILL.md` (interactive contract)
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` — four contracts plus the workflows
104
- template are the source of everything under `agents/`, `prompts/`, and the four dual-use
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.4.0` — installs the seven
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 four agent definitions into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses
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 `review` allow `context:files`: review stays low
126
- on purpose so it judges cold. `git-ops` allows none, on purpose. Each reason is in the
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. 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.
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
- **Seven skills for principal-level software engineering with the
4
- [pi coding agent](https://github.com/badlogic/pi-mono) — three inline skills and four
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/`, generated from the
8
- same contract as the skill). The files follow the [Agent Skills](https://agentskills.io/specification)
9
- standard, so other harnesses can consume the skills, but pi is the supported target. This
10
- is **4.x**: a thin orchestration layer over the seven skills, with the risk-adaptive
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 `debug` each serve as a loaded skill *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 ≤ 2000** —
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. Every ceiling has moved exactly once, each time buying a fix rather than more
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 | 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
+ | `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 the workflows delegate to
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.4.0
112
+ pi install git:github.com/mojomanyana/principal-pi-skills@v4.6.0
112
113
  ```
113
114
 
114
- The `pi` manifest registers the seven skills, the four `/principal-*` commands, and 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 four agent definitions:
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`, and
131
- `principal-debug` as **real files, not symlinks** — a symlink into a checkout breaks the
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: `plan` is read-only except for its own plan file; `build`,
137
- `review`, and `debug` add `bash` to run tests (and, for `build`, to write and edit).
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 seven authored frontmatter descriptions. Run
181
- `npm run check:routing-collisions` for all 42 directed description pairs and
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 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.
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. 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
@@ -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. 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
@@ -1,6 +1,6 @@
1
1
  # principal-pi-skills bootstrap
2
2
 
3
- Seven skills are installed. Route by what the input looks like; when none fits, answer
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 debug; strongest available for review and architect.
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. 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 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
- 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.
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.0",
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.",
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 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.