principal-pi-skills 4.2.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,22 @@ 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
+
9
25
  ## [4.2.0] — 2026-09-21
10
26
 
11
27
  **Cheaper loops, borrowed from superpowers' subagent-driven development.** A delegated
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`, 1457) or inline | 1236 |
48
- | `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1239) or inline | 1111 |
49
- | `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1393) or inline | 1293 |
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
@@ -108,7 +108,7 @@ CHANGELOG.md release history
108
108
  1. **Skills + prompts** — install an immutable tag, not a branch:
109
109
 
110
110
  ```
111
- pi install git:github.com/mojomanyana/principal-pi-skills@v4.1.0
111
+ pi install git:github.com/mojomanyana/principal-pi-skills@v4.3.0
112
112
  ```
113
113
 
114
114
  The `pi` manifest registers the seven skills, the four `/principal-*` commands, and the
@@ -133,7 +133,7 @@ CHANGELOG.md release history
133
133
  agent. It refuses to overwrite anything it did not install, and `uninstall` removes only
134
134
  its own unmodified files.
135
135
 
136
- 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`,
137
137
  `review`, and `debug` add `bash` to run tests (and, for `build`, to write and edit).
138
138
 
139
139
  One trap worth knowing if you run subagents on a non-default provider: a delegated agent
@@ -148,6 +148,30 @@ CHANGELOG.md release history
148
148
  still reaches the session because the bootstrap extension injects it — installing the
149
149
  package is enough for that part; only delegation itself needs step 2.
150
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
+
151
175
  ## Validation
152
176
 
153
177
  4.0 ships with no model score. The skill-harness specifications and the v2.4 DeepSeek/GLM
@@ -6,7 +6,7 @@ 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
@@ -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
@@ -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
@@ -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.2.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
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