principal-pi-skills 4.1.0 → 4.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -113,10 +113,16 @@ to every output.
113
113
 
114
114
  ## Setup (pi)
115
115
 
116
- 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.1.0` — installs the seven
116
+ 1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.3.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
120
120
  the four agent definitions into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses
121
121
  to overwrite anything it did not install. Without it, everything in the routing table
122
122
  above still runs; the How column just collapses to "inline".
123
+ 3. Context handoff (pi-daddy 0.33.0+): each skill's `allowed-tools` sets how much of this
124
+ 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
+ skill's frontmatter and the README install section, along with the egress note. Don't
128
+ 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,36 @@ Where review revealed a prior claim or design decision didn't hold up under clos
6
6
 
7
7
  ---
8
8
 
9
+ ## [4.3.0] — 2026-09-22
10
+
11
+ **Context-handoff ceilings for pi-daddy 0.33.0+.** pi-daddy made the context a delegated
12
+ child receives a capability the child's own `allowed-tools` must declare. None of the seven
13
+ skills declared one, so every delegation that asked for context was refused. Now:
14
+ `architect`, `decide` and `plan` declare `context:summary`; `build`, `debug` and `review`
15
+ declare `context:files`; `git-ops` declares none, deliberately. Review sits below the
16
+ "reasons about done work" level on purpose: a cold reviewer must not get the author's
17
+ reasoning. No skill body promised session context. Every input a contract names is task
18
+ text or a file the child reads. The README install section records each reason and the
19
+ egress consequence: with `pruned` allowed and an advisor on, operator turns go to a third
20
+ party. Verified against pi-daddy 0.38.0. Also: the install docs now name `v4.3.0` (they still said
21
+ `v4.1.0`), the README no longer calls `plan` read-only (it writes its plan file), and the
22
+ template comments point to the capability-ceilings decision on the `v3.2.0` tag, where it
23
+ still lives.
24
+
25
+ ## [4.2.0] — 2026-09-21
26
+
27
+ **Cheaper loops, borrowed from superpowers' subagent-driven development.** A delegated
28
+ `principal-build` now writes its full report to `.principal/reports/<step>-build.md` and
29
+ returns five status lines, so reports stop accumulating in the steering context. Review is
30
+ handed a diff package (`git diff --stat` + full diff, one file) and the build reports; it
31
+ treats a verbatim `Full evidence:` line as test evidence and runs a test only for a named
32
+ doubt, instead of rebuilding a worktree and re-running the suite on every call. Repair rounds
33
+ resume the build agent when the tool allows and get a **scoped re-review** (agent form only):
34
+ each open finding ID is verdicted ADDRESSED or NOT ADDRESSED, new breakage is checked in the
35
+ fix diff alone. Plan batches same-shape edits across files into one step. The spines name
36
+ the model tier per review: strongest for the whole-change review, mid-tier for scoped
37
+ re-reviews. Skill forms of build and review are unchanged except review's evidence rule.
38
+
9
39
  ## [4.1.0] — 2026-09-21
10
40
 
11
41
  **Added.** Two prompt templates. `/principal-refactor <scope>` is the feature spine with a
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 | 1053 |
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 | 1145 |
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`, 1425) or inline | 1204 |
48
- | `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1195) or inline | 1111 |
49
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1202) or inline | 1174 |
50
- | `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1455) or inline | 1321 |
51
- | `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 1976 |
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 |
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
@@ -72,6 +72,13 @@ before building — presenting the artifact and starting to build in the same tu
72
72
  failure the rule exists to catch. The artifact scales with the change (three lines for a
73
73
  config tweak, full slices for a feature); the stop does not.
74
74
 
75
+ Delegated phases hand artifacts to each other as files, not pasted text. A `principal-build`
76
+ writes its full report to `.principal/reports/<step>-build.md` and returns five status lines;
77
+ review is handed one diff package for the whole change plus those reports, treats a verbatim
78
+ test-result line as evidence, and runs a test only for a named doubt. A repair round resumes
79
+ the build agent where the tool allows and gets a scoped re-review of the fix diff against the
80
+ open finding IDs. The `.principal/` directory ignores itself, so none of this reaches git.
81
+
75
82
  When plan's output is the multi-step template, it writes the plan to
76
83
  `.principal/plans/<slug>.md` and prints the path; `.principal/.gitignore` is created
77
84
  alongside it on first use, so the directory is git-ignored and self-ignoring. Delegated
@@ -101,7 +108,7 @@ CHANGELOG.md release history
101
108
  1. **Skills + prompts** — install an immutable tag, not a branch:
102
109
 
103
110
  ```
104
- pi install git:github.com/mojomanyana/principal-pi-skills@v4.1.0
111
+ pi install git:github.com/mojomanyana/principal-pi-skills@v4.3.0
105
112
  ```
106
113
 
107
114
  The `pi` manifest registers the seven skills, the four `/principal-*` commands, and the
@@ -126,7 +133,7 @@ CHANGELOG.md release history
126
133
  agent. It refuses to overwrite anything it did not install, and `uninstall` removes only
127
134
  its own unmodified files.
128
135
 
129
- Tool restriction is structural, in the agents' frontmatter: `plan` is read-only; `build`,
136
+ Tool restriction is structural, in the agents' frontmatter: `plan` is read-only except for its own plan file; `build`,
130
137
  `review`, and `debug` add `bash` to run tests (and, for `build`, to write and edit).
131
138
 
132
139
  One trap worth knowing if you run subagents on a non-default provider: a delegated agent
@@ -141,6 +148,30 @@ CHANGELOG.md release history
141
148
  still reaches the session because the bootstrap extension injects it — installing the
142
149
  package is enough for that part; only delegation itself needs step 2.
143
150
 
151
+ 4. **Under pi-daddy (0.33.0+), each skill declares how much of the caller's session it may
152
+ receive.** A child gets only the `context:` mode its own `allowed-tools` names (or a
153
+ weaker one: `none < files < pruned < summary < fork`). Asking for more is refused, not
154
+ downgraded. The ceilings are decisions, and each one is explained in its frontmatter:
155
+
156
+ | skill | ceiling | why |
157
+ |---|---|---|
158
+ | `architect`, `decide` | `context:summary` | delegated, they cannot ask; the drivers and the rejected options live in the parent's dialogue |
159
+ | `plan` | `context:summary` | a plan must honour what the user ruled out, which a task line flattens; no `bash` |
160
+ | `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
+ | `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 |
162
+ | `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
+
164
+ Nothing declares `context:fork`. Write the prefix in lowercase: `Context:summary` turns
165
+ into `tool:context:summary`, which grants no context mode.
166
+
167
+ **Egress: know what `summary` enables.** `context:summary` also permits `pruned`. That
168
+ mode carries the operator's own session turns (the last 20 by default, up to 32 KiB),
169
+ not just the task. With a pi-daddy advisor enabled (`PI_DADDY_ADVISOR` plus
170
+ `PI_DADDY_ADVISOR_KEY`), a `pruned` handoff sends those turns to that third party so it
171
+ can choose which ones to keep. For `architect`, `decide` and `plan`, that is what you
172
+ switch on by delegating with `pruned` while an advisor is on. Raising any other skill's
173
+ ceiling extends that exposure to it.
174
+
144
175
  ## Validation
145
176
 
146
177
  4.0 ships with no model score. The skill-harness specifications and the v2.4 DeepSeek/GLM
@@ -6,14 +6,18 @@ description: >
6
6
  implementation report. Not for diagnosing an unknown failure (debug) or deciding what to
7
7
  build (plan).
8
8
  tools: read, grep, find, ls, edit, write, bash
9
- allowed-tools: read, grep, find, ls, edit, write, bash
9
+ allowed-tools: read, grep, find, ls, edit, write, bash, context:files
10
10
  ---
11
11
 
12
12
  # Build — Test-First Implementation
13
13
 
14
14
  You run in an isolated context and cannot ask questions. **The caller receives ONLY your
15
- final message**, so your last message must be the complete implementation report below. You
16
- receive a plan file path and a step number: read that step and implement exactly it. When no
15
+ final message.** Write the complete implementation report below to the report path the
16
+ caller names (default `.principal/reports/<step>-build.md`; create the directory), then make
17
+ your final message exactly five lines: `Next:`, `Changed paths:`, `Findings applied:`,
18
+ `Tests:` (the verbatim result line), `Report:` (the path). The caller reads the file only
19
+ when routing needs more; everything else you print is lost. You receive a plan file path and
20
+ a step number: read that step and implement exactly it. When no
17
21
  plan file is given, the task in your prompt — a fix with a known cause, or a list of
18
22
  accepted `[REV-…]` findings to repair — is the whole spec; implement exactly that. If the
19
23
  step contradicts the codebase, implement nothing on the contested point and report it under
@@ -6,7 +6,7 @@ description: >
6
6
  crashes when", "works on my machine". Not for writing new features or fixing a bug
7
7
  whose cause is already known (build).
8
8
  tools: read, grep, find, ls, bash
9
- allowed-tools: read, grep, find, ls, bash
9
+ allowed-tools: read, grep, find, ls, bash, context:files
10
10
  ---
11
11
 
12
12
  # Debug — Hypothesis Before Fix
@@ -7,7 +7,7 @@ description: >
7
7
  the plan and per-step specs; writes no code. Not for system-level design (architect)
8
8
  or diagnosing failures (debug).
9
9
  tools: read, grep, find, ls, write
10
- allowed-tools: read, grep, find, ls, write
10
+ allowed-tools: read, grep, find, ls, write, context:summary
11
11
  ---
12
12
 
13
13
  # Plan — Slices and Specs
@@ -56,7 +56,9 @@ behavior, and the test that proves it.
56
56
  done-signal. Never plan horizontal layers ("all models, then all services") — that saves
57
57
  integration risk for last, where it is most expensive.
58
58
  5. **Slice vertically.** Each later step is a small end-to-end increment, independently
59
- testable, roughly a day or less of work.
59
+ testable, roughly a day or less of work. Small edits of the same shape repeated across files
60
+ (one rename, constant, or field, N places) are ONE step listing every file, not N steps —
61
+ each step costs a fresh builder.
60
62
  6. **Spec each step concretely**: files to touch, signatures, exact behavior, the test
61
63
  that proves it, and ripples (callers of changed signatures, config, migrations). If
62
64
  the builder would have to make a design decision you skipped, the spec isn't done.
@@ -7,7 +7,7 @@ description: >
7
7
  test quality, security) and simplicity (dead code, needless abstraction, unneeded
8
8
  dependencies).
9
9
  tools: read, grep, find, ls, bash
10
- allowed-tools: read, grep, find, ls, bash
10
+ allowed-tools: read, grep, find, ls, bash, context:files
11
11
  ---
12
12
 
13
13
  # Review — Correctness and Simplicity, One Pass
@@ -63,8 +63,13 @@ ships is a failed review.
63
63
  still contain the original's guards — code you present as "cleaner" that drops a
64
64
  validation or weakens a security compare is a bug you just authored. If the only way
65
65
  smaller is through a safeguard, the verdict is KEEP; say so.
66
- 4. **Verify in a workspace you own.** Run tests and the riskiest path. Destructive probes
67
- (revert the fix, break an input) belong in a disposable copy, never the caller checkout:
66
+ 4. **Verify with the cheapest evidence that settles it.** A diff package the caller hands you
67
+ (`git diff --stat` plus the full base..head diff in one file) is your view of a committed
68
+ change: read it once and do not re-derive it. The build report's `Full evidence:` line,
69
+ when it names the exact command and a verbatim result, is test evidence — do not re-run
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:
68
73
  `npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree
69
74
  holding the exact working state. Work there, then `remove` it. If creation fails, only
70
75
  read or run a read-only check and return UNVERIFIED; never mutate the caller checkout.
@@ -72,6 +77,13 @@ ships is a failed review.
72
77
  (show smaller code for simplifications). Order by severity; Top concern is the highest.
73
78
  Clean code gets “verified, no blockers” — never manufacture findings.
74
79
 
80
+ ## Scoped re-review
81
+ When the caller supplies open finding IDs and a fix diff, you are judging the fix, not the
82
+ change: for each ID return `ADDRESSED` or `NOT ADDRESSED` with `file:line` evidence, flag new
83
+ breakage inside the fix diff only, and leave untouched code alone — an observation outside
84
+ the fix diff goes under Follow-ups, never into Findings. The verdict is APPROVE when every ID
85
+ is addressed and nothing new broke.
86
+
75
87
  ## Right-sizing
76
88
  Depth scales with blast radius. A described one-character/typo-level fix with no behavior
77
89
  change gets one line — "fine, ship it" — from the description alone: don't demand the
@@ -110,9 +122,10 @@ partial verdict.
110
122
  ## Checks
111
123
  | If you are about to… | Instead |
112
124
  |---|---|
113
- | Approve without running the tests or seeing it work | Verify first, or mark UNVERIFIED. |
125
+ | Approve without evidence — neither a verbatim test result in the report nor a run of your own | Get one, or mark UNVERIFIED. |
114
126
  | Flag a fallback that logs, counts, or returns real data as a swallow | It is observable. Review the DEGRADATION, not its existence. |
115
127
  | Return BLOCKED because the workspace is empty | A described change is reviewable. BLOCKED needs no code AND no description. |
128
+ | Re-run the whole suite that the build report already shows green | The report line is the evidence; run one targeted test only for a named doubt. |
116
129
  | Write "LGTM" with no findings on a non-trivial change | Name what you checked, even if the result is "checked X, Y, Z — clean". |
117
130
  | Flag style while a real bug sits unmentioned | Correctness findings first; taste is the last 5%. |
118
131
  | Delete a safeguard to shrink the diff | The floor holds. Verdict on that code is KEEP. |
@@ -6,7 +6,9 @@ description: >
6
6
  architecture", "plan the migration", "write an ADR". The output is a design note with
7
7
  measurable drivers. Not for a yes/no or which-vendor decision without a structure to
8
8
  design (decide), or code-level planning of one change (plan).
9
- allowed-tools: read, grep, find, ls
9
+ # context:summary (pi-daddy 0.33.0+; also permits pruned, files): delegated, architect cannot ask,
10
+ # and its drivers are the constraints the user stated in the parent's dialogue.
11
+ allowed-tools: read, grep, find, ls, context:summary
10
12
  ---
11
13
 
12
14
  # Architect — Design from Measurable Drivers
package/build/SKILL.md CHANGED
@@ -5,7 +5,7 @@ description: >
5
5
  refactor — "fix this", "write the function", "implement the spec", "make the test pass",
6
6
  "code this up", "build it". Not for diagnosing an unknown failure (debug) or deciding
7
7
  what to build (plan).
8
- allowed-tools: read, grep, find, ls, edit, write, bash
8
+ allowed-tools: read, grep, find, ls, edit, write, bash, context:files
9
9
  ---
10
10
 
11
11
  # Build — Test-First Implementation
package/debug/SKILL.md CHANGED
@@ -5,7 +5,7 @@ description: >
5
5
  lint error — "why is this failing", "find the bug", "debug this", "it crashes when",
6
6
  "works on my machine". Not for writing new features or fixing a bug whose cause is
7
7
  already known (build).
8
- allowed-tools: read, grep, find, ls, bash
8
+ allowed-tools: read, grep, find, ls, bash, context:files
9
9
  ---
10
10
 
11
11
  # Debug — Hypothesis Before Fix
package/decide/SKILL.md CHANGED
@@ -7,7 +7,9 @@ description: >
7
7
  whether to migrate, scope and sequencing, process. The output is a decision brief. Not for
8
8
  designing how a system is structured (architect), planning implementation (plan), or
9
9
  writing code (build).
10
- allowed-tools: read, grep, find, ls
10
+ # context:summary (pi-daddy 0.33.0+; also permits pruned, files): delegated, decide cannot ask,
11
+ # and the options already weighed and rejected live only in the parent's dialogue.
12
+ allowed-tools: read, grep, find, ls, context:summary
11
13
  ---
12
14
 
13
15
  # Decide — Options and Stress-Tests
package/git-ops/SKILL.md CHANGED
@@ -5,6 +5,8 @@ description: >
5
5
  "rebase", "merge", "tag a release", "who wrote this", "when did this break", "undo
6
6
  this", "wrong branch", "lost commits", "I leaked a secret", CI failures. Safe operator:
7
7
  refuses history rewrites on shared branches, scans for secrets before committing.
8
+ # No context: capability, deliberately. Repo state, not conversation; destructive-op consent
9
+ # comes from the user, never from forwarded turns.
8
10
  allowed-tools: read, bash
9
11
  ---
10
12
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "principal-pi-skills",
3
- "version": "4.1.0",
3
+ "version": "4.3.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
@@ -5,7 +5,7 @@ description: >
5
5
  "break this down", "how should I implement this", "where do I start", "what's the order
6
6
  of work", "scope this refactor", "plan the fix". Produces the plan and per-step specs;
7
7
  writes no code. Not for system-level design (architect) or diagnosing failures (debug).
8
- allowed-tools: read, grep, find, ls, write
8
+ allowed-tools: read, grep, find, ls, write, context:summary
9
9
  ---
10
10
 
11
11
  # Plan — Slices and Specs
@@ -39,7 +39,9 @@ behavior, and the test that proves it.
39
39
  done-signal. Never plan horizontal layers ("all models, then all services") — that saves
40
40
  integration risk for last, where it is most expensive.
41
41
  5. **Slice vertically.** Each later step is a small end-to-end increment, independently
42
- testable, roughly a day or less of work.
42
+ testable, roughly a day or less of work. Small edits of the same shape repeated across files
43
+ (one rename, constant, or field, N places) are ONE step listing every file, not N steps —
44
+ each step costs a fresh builder.
43
45
  6. **Spec each step concretely**: files to touch, signatures, exact behavior, the test
44
46
  that proves it, and ripples (callers of changed signatures, config, migrations). If
45
47
  the builder would have to make a design decision you skipped, the spec isn't done.
@@ -21,17 +21,25 @@ build until the user says go. Presenting the artifact and starting to build in t
21
21
  is the failure. The artifact scales — three lines for a config change, full slices for a
22
22
  feature — the stop does not. A re-plan needs a new approval.
23
23
 
24
- **Build.** One writer at a time, on a branch the user can see. Inline when there is no multi-step plan file (a three-line plan, or a bugfix) or the subagent tool is absent. Otherwise dispatch one fresh `principal-build`
25
- per step with the plan file path and the step number; record its report's Changed paths,
26
- Tests, and Follow-ups; then the next step.
27
- Choose the cheapest model that can transcribe a complete step spec; the build report carries
28
- the evidence.
24
+ **Build.** One writer at a time, on a branch the user can see. Inline when there is no
25
+ multi-step plan file (a three-line plan, or a bugfix) or the subagent tool is absent.
26
+ Otherwise dispatch one fresh `principal-build` per step — a batched step is one dispatch —
27
+ with the plan file path, the step number, and a report path
28
+ `.principal/reports/<step>-build.md`. It returns five status lines; read the report file only
29
+ when routing needs more, and never paste a report into a later dispatch. Choose the cheapest
30
+ model that can transcribe a complete step spec.
29
31
 
30
32
  **Review.** Always delegate to `principal-review` when the tool exists — a cold read beats
31
- self-review. `CHANGES-REQUESTED` → decide which findings are accepted, then Build in repair
32
- mode with exactly those IDs, then review again; at most two repair rounds, a third means
33
- the plan or diagnosis was wrong. `UNVERIFIED` is not approval: fix whatever blocked verification, then review again; it counts as a repair round. `APPROVE` or
34
- `APPROVE-WITH-NITS` → git-ops.
33
+ self-review. Hand it files, not prose: write `git diff --stat` and `git diff -U6 <base>..<head>`
34
+ for the whole change to `.principal/reports/review-diff.txt` and pass that path plus the build
35
+ report paths; review judges from them and runs a test only for a named doubt. Use the
36
+ strongest available model for this review. `CHANGES-REQUESTED` → decide which findings are
37
+ accepted; then repair with exactly those IDs — resume the build agent that made the change
38
+ when your tool can, otherwise a fresh dispatch — then a scoped re-review: the open IDs and the
39
+ fix diff only, on a mid-tier model, verdicting each ID. At most two repair rounds; a third means
40
+ the plan or diagnosis was wrong. `UNVERIFIED` is not approval: fix whatever blocked
41
+ verification, then review again; it counts as a repair round. `APPROVE` or `APPROVE-WITH-NITS`
42
+ → git-ops.
35
43
 
36
44
  **Blocked.** A phase returning `BLOCKED` stops the chain: surface its one question and
37
45
  wait. Do not answer it yourself.
@@ -21,17 +21,25 @@ build until the user says go. Presenting the artifact and starting to build in t
21
21
  is the failure. The artifact scales — three lines for a config change, full slices for a
22
22
  feature — the stop does not. A re-plan needs a new approval.
23
23
 
24
- **Build.** One writer at a time, on a branch the user can see. Inline when there is no multi-step plan file (a three-line plan, or a bugfix) or the subagent tool is absent. Otherwise dispatch one fresh `principal-build`
25
- per step with the plan file path and the step number; record its report's Changed paths,
26
- Tests, and Follow-ups; then the next step.
27
- Choose the cheapest model that can transcribe a complete step spec; the build report carries
28
- the evidence.
24
+ **Build.** One writer at a time, on a branch the user can see. Inline when there is no
25
+ multi-step plan file (a three-line plan, or a bugfix) or the subagent tool is absent.
26
+ Otherwise dispatch one fresh `principal-build` per step — a batched step is one dispatch —
27
+ with the plan file path, the step number, and a report path
28
+ `.principal/reports/<step>-build.md`. It returns five status lines; read the report file only
29
+ when routing needs more, and never paste a report into a later dispatch. Choose the cheapest
30
+ model that can transcribe a complete step spec.
29
31
 
30
32
  **Review.** Always delegate to `principal-review` when the tool exists — a cold read beats
31
- self-review. `CHANGES-REQUESTED` → decide which findings are accepted, then Build in repair
32
- mode with exactly those IDs, then review again; at most two repair rounds, a third means
33
- the plan or diagnosis was wrong. `UNVERIFIED` is not approval: fix whatever blocked verification, then review again; it counts as a repair round. `APPROVE` or
34
- `APPROVE-WITH-NITS` → git-ops.
33
+ self-review. Hand it files, not prose: write `git diff --stat` and `git diff -U6 <base>..<head>`
34
+ for the whole change to `.principal/reports/review-diff.txt` and pass that path plus the build
35
+ report paths; review judges from them and runs a test only for a named doubt. Use the
36
+ strongest available model for this review. `CHANGES-REQUESTED` → decide which findings are
37
+ accepted; then repair with exactly those IDs — resume the build agent that made the change
38
+ when your tool can, otherwise a fresh dispatch — then a scoped re-review: the open IDs and the
39
+ fix diff only, on a mid-tier model, verdicting each ID. At most two repair rounds; a third means
40
+ the plan or diagnosis was wrong. `UNVERIFIED` is not approval: fix whatever blocked
41
+ verification, then review again; it counts as a repair round. `APPROVE` or `APPROVE-WITH-NITS`
42
+ → git-ops.
35
43
 
36
44
  **Blocked.** A phase returning `BLOCKED` stops the chain: surface its one question and
37
45
  wait. Do not answer it yourself.
@@ -21,17 +21,25 @@ build until the user says go. Presenting the artifact and starting to build in t
21
21
  is the failure. The artifact scales — three lines for a config change, full slices for a
22
22
  feature — the stop does not. A re-plan needs a new approval.
23
23
 
24
- **Build.** One writer at a time, on a branch the user can see. Inline when there is no multi-step plan file (a three-line plan, or a bugfix) or the subagent tool is absent. Otherwise dispatch one fresh `principal-build`
25
- per step with the plan file path and the step number; record its report's Changed paths,
26
- Tests, and Follow-ups; then the next step.
27
- Choose the cheapest model that can transcribe a complete step spec; the build report carries
28
- the evidence.
24
+ **Build.** One writer at a time, on a branch the user can see. Inline when there is no
25
+ multi-step plan file (a three-line plan, or a bugfix) or the subagent tool is absent.
26
+ Otherwise dispatch one fresh `principal-build` per step — a batched step is one dispatch —
27
+ with the plan file path, the step number, and a report path
28
+ `.principal/reports/<step>-build.md`. It returns five status lines; read the report file only
29
+ when routing needs more, and never paste a report into a later dispatch. Choose the cheapest
30
+ model that can transcribe a complete step spec.
29
31
 
30
32
  **Review.** Always delegate to `principal-review` when the tool exists — a cold read beats
31
- self-review. `CHANGES-REQUESTED` → decide which findings are accepted, then Build in repair
32
- mode with exactly those IDs, then review again; at most two repair rounds, a third means
33
- the plan or diagnosis was wrong. `UNVERIFIED` is not approval: fix whatever blocked verification, then review again; it counts as a repair round. `APPROVE` or
34
- `APPROVE-WITH-NITS` → git-ops.
33
+ self-review. Hand it files, not prose: write `git diff --stat` and `git diff -U6 <base>..<head>`
34
+ for the whole change to `.principal/reports/review-diff.txt` and pass that path plus the build
35
+ report paths; review judges from them and runs a test only for a named doubt. Use the
36
+ strongest available model for this review. `CHANGES-REQUESTED` → decide which findings are
37
+ accepted; then repair with exactly those IDs — resume the build agent that made the change
38
+ when your tool can, otherwise a fresh dispatch — then a scoped re-review: the open IDs and the
39
+ fix diff only, on a mid-tier model, verdicting each ID. At most two repair rounds; a third means
40
+ the plan or diagnosis was wrong. `UNVERIFIED` is not approval: fix whatever blocked
41
+ verification, then review again; it counts as a repair round. `APPROVE` or `APPROVE-WITH-NITS`
42
+ → git-ops.
35
43
 
36
44
  **Blocked.** A phase returning `BLOCKED` stops the chain: surface its one question and
37
45
  wait. Do not answer it yourself.
package/review/SKILL.md CHANGED
@@ -5,7 +5,7 @@ description: >
5
5
  this diff", "simplify this", "is this over-engineered", or after any non-trivial
6
6
  implementation. Covers both correctness (bugs, edge cases, error handling, test quality,
7
7
  security) and simplicity (dead code, needless abstraction, unneeded dependencies).
8
- allowed-tools: read, grep, find, ls, bash
8
+ allowed-tools: read, grep, find, ls, bash, context:files
9
9
  ---
10
10
 
11
11
  # Review — Correctness and Simplicity, One Pass
@@ -56,8 +56,13 @@ ships is a failed review.
56
56
  still contain the original's guards — code you present as "cleaner" that drops a
57
57
  validation or weakens a security compare is a bug you just authored. If the only way
58
58
  smaller is through a safeguard, the verdict is KEEP; say so.
59
- 4. **Verify in a workspace you own.** Run tests and the riskiest path. Destructive probes
60
- (revert the fix, break an input) belong in a disposable copy, never the caller checkout:
59
+ 4. **Verify with the cheapest evidence that settles it.** A diff package the caller hands you
60
+ (`git diff --stat` plus the full base..head diff in one file) is your view of a committed
61
+ change: read it once and do not re-derive it. The build report's `Full evidence:` line,
62
+ when it names the exact command and a verbatim result, is test evidence — do not re-run
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:
61
66
  `npx -p principal-pi-skills principal-pi-workspace create` prints a throwaway worktree
62
67
  holding the exact working state. Work there, then `remove` it. If creation fails, only
63
68
  read or run a read-only check and return UNVERIFIED; never mutate the caller checkout.
@@ -107,9 +112,10 @@ partial verdict.
107
112
  ## Checks
108
113
  | If you are about to… | Instead |
109
114
  |---|---|
110
- | Approve without running the tests or seeing it work | Verify first, or mark UNVERIFIED. |
115
+ | Approve without evidence — neither a verbatim test result in the report nor a run of your own | Get one, or mark UNVERIFIED. |
111
116
  | Flag a fallback that logs, counts, or returns real data as a swallow | It is observable. Review the DEGRADATION, not its existence. |
112
117
  | Return BLOCKED because the workspace is empty | A described change is reviewable. BLOCKED needs no code AND no description. |
118
+ | Re-run the whole suite that the build report already shows green | The report line is the evidence; run one targeted test only for a named doubt. |
113
119
  | Write "LGTM" with no findings on a non-trivial change | Name what you checked, even if the result is "checked X, Y, Z — clean". |
114
120
  | Flag style while a real bug sits unmentioned | Correctness findings first; taste is the last 5%. |
115
121
  | Delete a safeguard to shrink the diff | The floor holds. Verdict on that code is KEEP. |