principal-pi-skills 4.7.3 → 4.8.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 +60 -29
- package/CHANGELOG.md +50 -0
- package/README.md +169 -76
- package/agents/principal-build.md +24 -11
- package/agents/principal-debug.md +13 -7
- package/agents/principal-investigate.md +2 -0
- package/agents/principal-plan.md +11 -2
- package/agents/principal-review.md +14 -0
- package/architect/SKILL.md +19 -14
- package/bootstrap/BOOTSTRAP.md +27 -22
- package/build/SKILL.md +26 -10
- package/debug/SKILL.md +13 -7
- package/decide/SKILL.md +27 -39
- package/extensions/bootstrap.ts +66 -37
- package/git-ops/SKILL.md +38 -2
- package/investigate/SKILL.md +2 -0
- package/package.json +5 -2
- package/plan/SKILL.md +11 -2
- package/principal-agents.json +36 -0
- package/prompts/principal-bugfix.md +76 -23
- package/prompts/principal-feature.md +73 -21
- package/prompts/principal-refactor.md +75 -23
- package/prompts/principal-review-branch.md +12 -3
- package/review/SKILL.md +14 -0
- package/scripts/install-agents.mjs +293 -138
- package/scripts/progress-artifacts.mjs +198 -0
package/AGENTS.md
CHANGED
|
@@ -4,7 +4,7 @@ Instructions for the [pi coding agent](https://github.com/badlogic/pi-mono) oper
|
|
|
4
4
|
with this set installed. Read this once at session start.
|
|
5
5
|
|
|
6
6
|
The bootstrap extension (`extensions/bootstrap.ts`) injects this file's routing table,
|
|
7
|
-
compressed, from `bootstrap/BOOTSTRAP.md`
|
|
7
|
+
compressed, from `bootstrap/BOOTSTRAP.md` into each applicable converted request — you do
|
|
8
8
|
not need to read this file for the framework to route. This file is the long-form
|
|
9
9
|
**routing layer**: full rationale per row, the complete `Next:` set, and the maintenance
|
|
10
10
|
rule. The framework deliberately has no routing skill — routing belongs to the
|
|
@@ -13,7 +13,7 @@ orchestrator (you), and each other file is self-contained: no required reading b
|
|
|
13
13
|
## Two forms, one rule
|
|
14
14
|
|
|
15
15
|
A **skill** runs inline in this session: it shares your context, can dialogue with the
|
|
16
|
-
user, and its work stays in your window. A **subagent** (via the
|
|
16
|
+
user, and its work stays in your window. A **subagent** (via native delegation or the configured legacy runner) runs in
|
|
17
17
|
its own context with its own tools, cannot ask questions, and returns only its output
|
|
18
18
|
template. The rule: dialogue and session state stay inline; heavy reading, cold judgment,
|
|
19
19
|
and noisy loops get delegated.
|
|
@@ -21,10 +21,26 @@ and noisy loops get delegated.
|
|
|
21
21
|
The set:
|
|
22
22
|
|
|
23
23
|
- Skills (inline only): `decide`, `architect`, `git-ops`.
|
|
24
|
-
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
24
|
+
- Delegated phases: `plan`, `build`, `review`, `debug`, `investigate`, bound to their
|
|
25
|
+
generated `agents/principal-*.md` contract through `principal-agents.json`. Each also has
|
|
26
|
+
a SKILL.md for deliberately chosen inline work. Legacy principal-* names are only for an
|
|
27
|
+
explicitly configured runner when native tools are genuinely absent.
|
|
28
|
+
|
|
29
|
+
For native delegation, call `delegate_describe({agent:"phase"})`, require binding package
|
|
30
|
+
`principal-pi-skills` and exact phase. Native names are `plan`, `build`, `review`, `debug`,
|
|
31
|
+
`investigate`. Pass the corresponding captured `definitionId` to every `delegate` call,
|
|
32
|
+
`delegate_all` child and `delegate_chain` step. The runtime verifies enabled selected source and
|
|
33
|
+
both generated file hashes. Missing/wrong/disabled bindings, stale reload, unqualified backend,
|
|
34
|
+
permission/context refusal, timeout, report gap or uncertain cleanup stops dependent work;
|
|
35
|
+
never substitute legacy, foreign or inline execution after failure. Follow authored model/effort
|
|
36
|
+
policy without phase-tier overrides. Inline is a workflow choice, not a fallback.
|
|
37
|
+
|
|
38
|
+
For approved independent batches, use one `delegate_all({children:[...]})` call; every child
|
|
39
|
+
carries its native phase name and described `definitionId`. Do not overlap single `delegate`
|
|
40
|
+
calls: each conservatively reserves available subtree capacity. Writers need distinct
|
|
41
|
+
precreated registered Git worktrees, declared scopes/dependencies and unused full-report paths.
|
|
42
|
+
Read every result, retain completed siblings after failures, review candidates and integrate
|
|
43
|
+
serially with merged checks. A refusal stops dependent work, never triggers a runner switch.
|
|
28
44
|
|
|
29
45
|
## Routing — pick by what the input looks like
|
|
30
46
|
|
|
@@ -33,7 +49,7 @@ The set:
|
|
|
33
49
|
| Choice and rationale ("should I…", "Postgres or DynamoDB", "what are my options") | `decide` | inline — the dialogue is the value |
|
|
34
50
|
| System structure, components, boundaries or data ("design X", "review our architecture") | `architect` | inline — drivers come from asking |
|
|
35
51
|
| A task needing order of work and code-level specs ("plan this", "break this down") | `plan` | **subagent** — it opens every file it names; keep that out of this context |
|
|
36
|
-
| Code to write ("implement", "fix this known bug", "make the test pass") | `build` | inline, or `
|
|
52
|
+
| Code to write ("implement", "fix this known bug", "make the test pass") | `build` | inline, or native `build` with its captured `definitionId` per approved plan step — never fan parallel writers into one working tree |
|
|
37
53
|
| 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
54
|
| 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
55
|
| 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 |
|
|
@@ -82,18 +98,26 @@ Typical spines (available as prompt templates):
|
|
|
82
98
|
- Bug (`/principal-bugfix <symptom>`): debug → approval stop → build → review → git-ops
|
|
83
99
|
finish. If debug's note says design flaw, stop and surface it.
|
|
84
100
|
- Refactor (`/principal-refactor <scope>`): the feature spine with a no-behavior-change
|
|
85
|
-
frame —
|
|
86
|
-
|
|
101
|
+
frame — behavior and coverage stay equivalent; test maintenance is allowed, and uncovered
|
|
102
|
+
behavior gets a characterization test first.
|
|
103
|
+
- Review a branch (`/principal-review-branch [base]`): cold native `review` with its captured `definitionId` of
|
|
87
104
|
`merge-base <base> HEAD..HEAD`, then git-ops finish mode on APPROVE; findings stop for the
|
|
88
105
|
user otherwise. No plan, no build.
|
|
89
|
-
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
rounds; a third means the plan or the diagnosis was wrong, not the code.
|
|
106
|
+
- Every spine uses the bound native or explicitly configured legacy interface above.
|
|
107
|
+
Build↔review repair loops stop after two rounds; a third means the plan or diagnosis was
|
|
108
|
+
wrong. A missing full report blocks dependent review; preserve independent completed work.
|
|
93
109
|
- Multi-step plans are written to `.principal/plans/<slug>.md` (git-ignored) so a delegated
|
|
94
110
|
build reads its step from the file and a compacted or fresh session resumes from it.
|
|
95
|
-
- Tiny change: build → git-ops
|
|
96
|
-
|
|
111
|
+
- Tiny change: build → git-ops only when finish is requested. Clear, reversible, localized
|
|
112
|
+
low-risk direct work may finish inline with actual checks and caveats, without `Next:`.
|
|
113
|
+
Honor requested review and existing approvals; a tiny security or normative edit is
|
|
114
|
+
consequential. Delegated status/report protocols and explicit spine approval stops remain.
|
|
115
|
+
- Review scope is task, integrated or scoped repair. Task approval covers only its candidate
|
|
116
|
+
and interfaces; only final integrated approval supports Git-Ops finish. Keep original
|
|
117
|
+
whole-change obligations and gates through repairs.
|
|
118
|
+
- Progress records are optional coordinator evidence indexes, never approval or execution.
|
|
119
|
+
Reconcile actual authority, work and current report/candidate references; commit, review,
|
|
120
|
+
integration and verification are separate facts. Incomplete/stale records stay unresolved.
|
|
97
121
|
|
|
98
122
|
Before any orchestrator artifact write (including planless Review, inline Build or optional
|
|
99
123
|
Investigate persistence), create an absent `.principal/.gitignore` containing `*`, never
|
|
@@ -121,7 +145,9 @@ where they used to drift.
|
|
|
121
145
|
|
|
122
146
|
Both are generated from `contracts/<name>.md.tmpl`. The three spine workflows are
|
|
123
147
|
likewise generated from `contracts/workflows.md.tmpl` — five contracts plus one workflows
|
|
124
|
-
template produce five agents, five dual-use `SKILL.md` files and three prompts
|
|
148
|
+
template produce five agents, five dual-use `SKILL.md` files and three prompts, plus the
|
|
149
|
+
root `principal-agents.json` binding manifest (14 outputs). The manifest hashes full generated
|
|
150
|
+
UTF-8 skill/agent bytes in the same pass; never hand-edit its identities.
|
|
125
151
|
`prompts/principal-review-branch.md` is handwritten. Change shared behavior ONCE, there, then `npm run generate`. Editing a
|
|
126
152
|
generated file directly is reverted by the next run and fails `npm run generate:check` in
|
|
127
153
|
CI.
|
|
@@ -137,24 +163,29 @@ Behavioural measurement—including the fidelity corpus and skill-harness eviden
|
|
|
137
163
|
|
|
138
164
|
## Setup (pi)
|
|
139
165
|
|
|
140
|
-
1.
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
166
|
+
1. Install the stable tag:
|
|
167
|
+
`pi install git:github.com/mojomanyana/principal-pi-skills@v4.8.0` installs the eight
|
|
168
|
+
skills, the four `/principal-*` commands, and the bootstrap extension, which loads
|
|
169
|
+
automatically with the package. This release is stable 4.8.0. Native delegation
|
|
170
|
+
requires companion pi-daddy 0.44.0 and exactly the qualified Pi 1.0.4 setup; generated
|
|
171
|
+
skill/agent bindings and captured definition IDs must match the selected package.
|
|
172
|
+
2. Legacy subagents (optional): native delegation does not need this separate installation.
|
|
173
|
+
A configured legacy runner is available only when native tools are genuinely absent;
|
|
174
|
+
native refusal or failure cannot fall back to it. Npm publication is separate from this
|
|
175
|
+
prerelease. Use the installed tagged package's `scripts/install-agents.mjs` with Node
|
|
145
176
|
(`install`, then `check`), locating its actual path rather than assuming a universal Pi
|
|
146
177
|
install directory. Alternatively follow the concrete verified-tag disposable checkout
|
|
147
|
-
recipe in [README Install](README.md#install-pi).
|
|
148
|
-
`npx -p principal-pi-skills@4.
|
|
149
|
-
`npx -p principal-pi-skills@4.
|
|
178
|
+
recipe in [README Install](README.md#install-pi). Pin both npm commands:
|
|
179
|
+
`npx -p principal-pi-skills@4.8.0 principal-pi-agents install` and
|
|
180
|
+
`npx -p principal-pi-skills@4.8.0 principal-pi-agents check`.
|
|
150
181
|
The five definitions go to `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents`; foreign files
|
|
151
|
-
are refused.
|
|
152
|
-
Version 4.
|
|
153
|
-
|
|
154
|
-
checks remain here.
|
|
182
|
+
are refused. These files serve a configured legacy runner; they do not override native selection.
|
|
183
|
+
Version 4.8.0 adds native bindings, request-local routing, workflow and installer
|
|
184
|
+
safety changes, and manual progress records. Behavioral measurement remains in
|
|
185
|
+
`principal-pi-skills-evals` while routing checks remain here. To validate the tagged release,
|
|
155
186
|
validate the actual candidate's skills and installer
|
|
156
187
|
in isolation. Recorded model/evidence limitations remain; a release tag does not erase them.
|
|
157
|
-
3. Context handoff (pi-daddy
|
|
188
|
+
3. Context handoff (matching pi-daddy candidate): each skill's `allowed-tools` sets how much of this
|
|
158
189
|
session a delegated child may receive. `architect`, `decide` and `plan` allow
|
|
159
190
|
`context:summary`. `build`, `debug`, `review` and `investigate` allow `context:files`: review
|
|
160
191
|
stays low so it judges cold; investigate receives named evidence, not reasoning.
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,56 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [4.8.0] — 2026-10-07
|
|
10
|
+
|
|
11
|
+
**Fixed — installer compatibility without ownership bypass.** Symlinked directory ancestors
|
|
12
|
+
resolve to canonical anchors before ownership checks; agent/manifest leaf links still refuse.
|
|
13
|
+
Installed agents use `0644` and ownership metadata uses `0600`. Explicit `adopt` recovers a
|
|
14
|
+
missing manifest only for a complete byte-identical current agent set. `install` never
|
|
15
|
+
silently adopts; deprecated `--force` now explains that it cannot bypass ownership.
|
|
16
|
+
|
|
17
|
+
**Fixed — selected routing and parallel dispatch.** A stale foreign skill path cannot latch
|
|
18
|
+
all Principal routing off. Native workflows name `build`/`review`/other phases with captured
|
|
19
|
+
`definitionId` values and dispatch independent batches through `delegate_all`, with isolated
|
|
20
|
+
writer worktrees and serial integration. Compatibility is qualified for exactly Pi 1.0.4
|
|
21
|
+
and the companion pi-daddy 0.44.0 release, not unknown runtime versions.
|
|
22
|
+
|
|
23
|
+
## [4.8.0-rc.1] — 2026-10-07
|
|
24
|
+
|
|
25
|
+
**Added — native phase identity and request-local routing.** Generated
|
|
26
|
+
`principal-agents.json` binds all five delegated phases to their skill and agent hashes.
|
|
27
|
+
The bootstrap keeps Principal package identity, uses the selected native definition ID,
|
|
28
|
+
and refreshes routing after resource discovery, reloads and compaction. It deduplicates
|
|
29
|
+
its own request-local messages without treating quoted markers as routing state, and
|
|
30
|
+
retains read failures rather than silently selecting a different contract.
|
|
31
|
+
|
|
32
|
+
**Changed — concrete workflow contracts.** Planning records interfaces and checks where
|
|
33
|
+
needed; Decide and Architect avoid invented options or patterns. Build preserves behavior
|
|
34
|
+
and coverage during refactors, Review supports scoped review and repair, and diagnosis
|
|
35
|
+
hands implementation and verification back to Build. Eligible small changes can stay inline.
|
|
36
|
+
|
|
37
|
+
**Added — manual progress and complete reports.** `principal-pi-progress` stores ignored,
|
|
38
|
+
candidate-bound full reports and a strict evidence index. Exact metadata validation prevents
|
|
39
|
+
report redirection. Stale or incomplete records remain explicit; the helper neither grants
|
|
40
|
+
approval nor resumes work automatically.
|
|
41
|
+
|
|
42
|
+
**Fixed — installer ownership and recovery.** The installer validates the entire ownership
|
|
43
|
+
manifest before mutation and refuses malformed, foreign, edited or symlink targets, including
|
|
44
|
+
with `--force`. Git recovery instructions preserve staged, unstaged, untracked and ignored
|
|
45
|
+
content rather than assuming a patch alone captures the working state.
|
|
46
|
+
|
|
47
|
+
**Compatibility.** This prerelease targets stable 4.8.0. Native delegation requires the
|
|
48
|
+
companion pi-daddy 0.44.0-rc.1 candidate's `delegate_describe`/`definitionId` protocol and the
|
|
49
|
+
qualified Pi 1.0.4 setup. A configured legacy runner is available only when native tools are
|
|
50
|
+
genuinely absent; native failure cannot silently fall back. Existing installs require explicit
|
|
51
|
+
activation. Tag creation and npm publication are separate; this entry does not assert either.
|
|
52
|
+
|
|
53
|
+
**Validation.** `npm test` covers 168 unit and 33 install tests, generated outputs, word
|
|
54
|
+
budgets, package contents and skill lint. Companion runtime qualification exercises the
|
|
55
|
+
actual Pi 1.0.4 SDK/bootstrap and all five native phases with a local scripted provider.
|
|
56
|
+
These checks establish behavior and wiring, not model quality; behavioral measurement
|
|
57
|
+
remains in `principal-pi-skills-evals`.
|
|
58
|
+
|
|
9
59
|
## [4.7.3] — 2026-10-06
|
|
10
60
|
|
|
11
61
|
**Changed — current release and measurement documentation.** Installation examples and
|
package/README.md
CHANGED
|
@@ -30,7 +30,7 @@ around.
|
|
|
30
30
|
plain-text tags (`[ONE-WAY]`, `[BLOCKER]`) instead of an emoji schema, no aphorisms
|
|
31
31
|
doing load-bearing work, no personas, no required reading in reference files.
|
|
32
32
|
3. **Token economics.** Budgets stated as decisions rather than aspirations: **skills
|
|
33
|
-
≤ 1400 words**, **agents ≤ 1500**, and **`git-ops` an accepted exception at ≤
|
|
33
|
+
≤ 1400 words**, **agents ≤ 1500**, and **`git-ops` an accepted exception at ≤ 2550** (including operation-specific preservation and verified restoration) —
|
|
34
34
|
the safety-critical operator carries the most arming, and validated behavior outweighs
|
|
35
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
|
|
@@ -38,46 +38,62 @@ around.
|
|
|
38
38
|
`wc -w`. Nothing loads anything else — a subagent reads one file and has the whole
|
|
39
39
|
contract.
|
|
40
40
|
|
|
41
|
-
Individual
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
without removing existing guards;
|
|
50
|
-
Debug's agent ceiling is 1550 for honest sandbox/applied states. Common ceilings and Git-Ops
|
|
51
|
-
stay unchanged. These budgets preserve safeguards for lower-cost models, not a claim of
|
|
52
|
-
measured robustness on those models.
|
|
41
|
+
Individual contract exceptions (skill/agent words): Plan 2000/2050 preserves complete
|
|
42
|
+
source/requirement maps and adds exact connected interfaces and shared-resource checks.
|
|
43
|
+
Build 2000/2000 retains authority, full evidence and immutable repair provenance while adding
|
|
44
|
+
meaningful test maintenance and a guarded inline path. Review 1800/1850 retains candidate-bound
|
|
45
|
+
gates and distinguishes task, integrated and repair scope. Debug 1450/1600 preserves honest
|
|
46
|
+
disposable/applied states while making diagnosis sufficient for handoff and protecting
|
|
47
|
+
boundary evidence. These narrow increases retain the existing safeguards; they are not
|
|
48
|
+
claims of measured model compliance. Common ceilings remain unchanged.
|
|
53
49
|
|
|
54
50
|
## The set
|
|
55
51
|
|
|
56
52
|
| Skill | What it does | How it runs | Words |
|
|
57
53
|
|---|---|---|---|
|
|
58
|
-
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline |
|
|
59
|
-
| `architect` | System structure from measurable drivers; components, boundaries and data. The decision record is a section of the output, not a separate artifact | inline |
|
|
60
|
-
| `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`,
|
|
61
|
-
| `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`,
|
|
62
|
-
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`,
|
|
63
|
-
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`,
|
|
64
|
-
| `investigate` | A factual report of how code, data, runtime, or history currently behaves, with file-and-line citations | subagent (`agents/principal-investigate.md`,
|
|
65
|
-
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated |
|
|
54
|
+
| `decide` | Options and stress-tests for a decision that isn't settled — "should I", "what are my options", "I'm stuck" | inline | 975 |
|
|
55
|
+
| `architect` | System structure from measurable drivers; components, boundaries and data. The decision record is a section of the output, not a separate artifact | inline | 1270 |
|
|
56
|
+
| `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`, 2024) or inline | 1963 |
|
|
57
|
+
| `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`, 1970) or inline | 1960 |
|
|
58
|
+
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`, 1841) or inline | 1777 |
|
|
59
|
+
| `debug` | Hypothesis before fix: a diagnosis loop ending in a note with root cause and a regression test | subagent (`agents/principal-debug.md`, 1587) or inline | 1451 |
|
|
60
|
+
| `investigate` | A factual report of how code, data, runtime, or history currently behaves, with file-and-line citations | subagent (`agents/principal-investigate.md`, 494) or inline | 495 |
|
|
61
|
+
| `git-ops` | Safe version-control operator — reads state before writing it, keeps published history immutable, scans for secrets before committing | inline, never delegated | 2507 |
|
|
66
62
|
|
|
67
63
|
Routing between them belongs to the orchestrator, not to a skill — there is deliberately no
|
|
68
64
|
routing skill spending context to say "pick a skill". [AGENTS.md](./AGENTS.md) is the
|
|
69
65
|
long-form routing reference, and the bootstrap extension below injects its routing table
|
|
70
|
-
|
|
66
|
+
into applicable requests, so nothing needs to point pi at it by hand.
|
|
71
67
|
|
|
72
68
|
## Bootstrap and workflows
|
|
73
69
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
70
|
+
The extension (`extensions/bootstrap.ts`) discovers this package's enabled selected skills
|
|
71
|
+
through public `pi.getCommands()` at `before_agent_start`, after resource discovery. It
|
|
72
|
+
adds the under-300-word `bootstrap/BOOTSTRAP.md` once to each converted request, preserving
|
|
73
|
+
leading compaction/system/tool state and durable history. Tool iterations and later ordinary
|
|
74
|
+
requests receive routing too. Only extension-owned inserted objects are replaced; a quoted
|
|
75
|
+
marker cannot suppress injection. Disabled or shadowed package resources stay inactive.
|
|
76
|
+
Principal read/discovery failure is visible and latched until deliberate `/reload` reinstantiates the
|
|
77
|
+
extension; stale foreign command paths are ignored independently without disabling valid Principal skills; each registration owns its content cache and selected-resource state.
|
|
78
|
+
|
|
79
|
+
Native handoffs use `delegate_describe({agent:"phase"})`, require binding package
|
|
80
|
+
`principal-pi-skills` and exact phase. Native names are `plan`, `build`, `review`, `debug`,
|
|
81
|
+
`investigate`; pass the corresponding captured `definitionId` to every `delegate` call,
|
|
82
|
+
`delegate_all` child and `delegate_chain` step. The root `principal-agents.json` manifest binds exactly five phases to generated
|
|
83
|
+
inline/delegated paths and full-file SHA-256 hashes from the same generation pass. The
|
|
84
|
+
runtime must verify enabled selected source, package identity and both hashes. Missing,
|
|
85
|
+
wrong or disabled bindings and operational failures stop dependent work; they never trigger
|
|
86
|
+
legacy/foreign/inline substitution. Only genuinely absent native tools permit an explicitly
|
|
87
|
+
configured legacy principal-* runner. Inline is a workflow choice. Authored model/effort
|
|
88
|
+
policy governs; phase labels do not silently override it. This contract alone does not qualify
|
|
89
|
+
live native execution; the actual installed runtime/candidate still needs integration evidence.
|
|
90
|
+
|
|
91
|
+
Use one `delegate_all({children:[...]})` call for an approved independent parallel batch,
|
|
92
|
+
with the exact native phase name and captured `definitionId` on each child. Single `delegate`
|
|
93
|
+
calls conservatively reserve the available subtree capacity; overlapping single calls can
|
|
94
|
+
be refused. Writers need distinct precreated registered Git worktrees and declared scopes,
|
|
95
|
+
dependencies, shared resources and full-report destinations. Read every outcome, preserve
|
|
96
|
+
completed siblings after failure, review candidates, integrate serially and check the merged whole.
|
|
81
97
|
|
|
82
98
|
The three spines (`/principal-feature <task>`, `/principal-bugfix <symptom>`,
|
|
83
99
|
`/principal-refactor <scope>`) stop for your approval after the planning phase or the debug
|
|
@@ -86,7 +102,7 @@ before building — presenting the artifact and starting to build in the same tu
|
|
|
86
102
|
failure the rule exists to catch. The artifact scales with the change (three lines for a
|
|
87
103
|
config tweak, full slices for a feature); the stop does not.
|
|
88
104
|
|
|
89
|
-
Delegated phases hand artifacts to each other as files, not pasted text. A `
|
|
105
|
+
Delegated phases hand artifacts to each other as files, not pasted text. A native `build` child
|
|
90
106
|
writes its full report to an unused task/run/candidate-scoped path under `.principal/reports/`
|
|
91
107
|
(or a valid unused caller-chosen path) and returns five status lines;
|
|
92
108
|
review receives governing source/definition references, the complete plan/map when present,
|
|
@@ -107,10 +123,10 @@ alongside it only if absent, never overwritten. The complete executable artifact
|
|
|
107
123
|
stay in the file; chat gives a short summary and approval cue. Without persistence, the full
|
|
108
124
|
artifact is returned in chat, explicitly not saved. Tiny normative changes retain source/ID,
|
|
109
125
|
step and test without full machinery. Delegated
|
|
110
|
-
`
|
|
111
|
-
session
|
|
112
|
-
|
|
113
|
-
|
|
126
|
+
`build` children read their assigned step from that file, and a fresh or compacted
|
|
127
|
+
session locates matching plans, then reconciles actual approval, current work and candidate-bound
|
|
128
|
+
reports. A commit does not establish review, integration or verification. Resume manually at
|
|
129
|
+
what the evidence shows remains; do not repeat completed work or infer approval from a title.
|
|
114
130
|
|
|
115
131
|
## Layout
|
|
116
132
|
|
|
@@ -122,7 +138,7 @@ contracts/workflows.md.tmpl source for the three namespaced spines
|
|
|
122
138
|
prompts/principal-{feature,bugfix,refactor}.md generated workflows
|
|
123
139
|
prompts/principal-review-branch.md handwritten planless/buildless review entry
|
|
124
140
|
bootstrap/BOOTSTRAP.md routing table + Next: vocabulary + model tiering, injected by the extension
|
|
125
|
-
extensions/bootstrap.ts pi extension:
|
|
141
|
+
extensions/bootstrap.ts pi extension: request-local routing after selected-resource discovery
|
|
126
142
|
scripts/ generator, installers, and checks behind `npm test`
|
|
127
143
|
tests/{unit,install}/ current product/contract + clean-home install tests (node:test)
|
|
128
144
|
evals/{triggers.json,adversarial-triggers.json,baseline/} routing checks and baselines
|
|
@@ -132,13 +148,14 @@ CHANGELOG.md release history
|
|
|
132
148
|
|
|
133
149
|
## Install (pi)
|
|
134
150
|
|
|
135
|
-
1. **Skills + prompts** —
|
|
151
|
+
1. **Skills + prompts** — this prerelease targets stable 4.8.0. Once the immutable tag
|
|
152
|
+
exists, install it rather than a branch:
|
|
136
153
|
|
|
137
154
|
```
|
|
138
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v4.
|
|
155
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v4.8.0
|
|
139
156
|
```
|
|
140
157
|
|
|
141
|
-
The v4.
|
|
158
|
+
The v4.8.0 `pi` manifest registers the eight skills, the four `/principal-*` commands,
|
|
142
159
|
and the bootstrap extension — it loads automatically with
|
|
143
160
|
the package; there is no separate extension-install step. Unpinned `main` moves under
|
|
144
161
|
you, so install a tag if you want a fixed, nameable behavior.
|
|
@@ -147,37 +164,45 @@ CHANGELOG.md release history
|
|
|
147
164
|
`principal-pi-workspace remove` deletes any path handed to it, including your checkout,
|
|
148
165
|
and reports success. `2.3.1` is the lowest safe version.
|
|
149
166
|
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
167
|
+
Native delegation requires the companion pi-daddy 0.44.0 release and **exactly
|
|
168
|
+
Pi 1.0.4**, the qualified version. This is not a claim of compatibility with every Pi 1.x
|
|
169
|
+
release; other or unknown versions require separate qualification before use. The selected package's generated `principal-agents.json`
|
|
170
|
+
binds each delegated phase to its skill and agent bytes. Native routing uses
|
|
171
|
+
`delegate_describe` and a captured `definitionId`; a native refusal or failure does
|
|
172
|
+
not fall back to a legacy runner or inline execution.
|
|
173
|
+
|
|
174
|
+
2. **Legacy subagents (optional).** A configured legacy runner can use the five agent
|
|
175
|
+
definitions when native tools are genuinely absent. Native delegation does not need
|
|
176
|
+
this separate agent installation. Use the **same source** as the installed skills:
|
|
177
|
+
locate the actual installed tagged package (its path varies by Pi configuration) and
|
|
178
|
+
run its `scripts/install-agents.mjs` with Node, or use this matching-tag disposable
|
|
179
|
+
checkout recipe after the tag exists. This prerelease does not imply npm publication.
|
|
155
180
|
|
|
156
181
|
```sh
|
|
157
182
|
(
|
|
158
183
|
set -eu
|
|
159
184
|
source_dir=$(mktemp -d)
|
|
160
185
|
trap 'rm -rf -- "$source_dir"' EXIT
|
|
161
|
-
git clone --depth 1 --branch v4.
|
|
162
|
-
test "$(git -C "$source_dir/package" rev-parse HEAD)" = "$(git -C "$source_dir/package" rev-parse 'v4.
|
|
186
|
+
git clone --depth 1 --branch v4.8.0 https://github.com/mojomanyana/principal-pi-skills.git "$source_dir/package"
|
|
187
|
+
test "$(git -C "$source_dir/package" rev-parse HEAD)" = "$(git -C "$source_dir/package" rev-parse 'v4.8.0^{commit}')"
|
|
163
188
|
git -C "$source_dir/package" rev-parse HEAD # retain the resolved source identity
|
|
164
189
|
node "$source_dir/package/scripts/install-agents.mjs" install
|
|
165
190
|
node "$source_dir/package/scripts/install-agents.mjs" check
|
|
166
191
|
)
|
|
167
192
|
```
|
|
168
193
|
|
|
169
|
-
|
|
194
|
+
Pin both npm commands:
|
|
170
195
|
|
|
171
196
|
```sh
|
|
172
|
-
npx -p principal-pi-skills@4.
|
|
173
|
-
npx -p principal-pi-skills@4.
|
|
197
|
+
npx -p principal-pi-skills@4.8.0 principal-pi-agents install
|
|
198
|
+
npx -p principal-pi-skills@4.8.0 principal-pi-agents check
|
|
174
199
|
```
|
|
175
200
|
|
|
176
|
-
Version 4.
|
|
177
|
-
|
|
178
|
-
`principal-pi-skills-evals` repository, while routing
|
|
179
|
-
|
|
180
|
-
tag/HEAD consistency, not independent tag trust;
|
|
201
|
+
Version 4.8.0 adds native phase bindings, request-local bootstrap routing, stricter
|
|
202
|
+
workflow contracts, manual progress records, and installer ownership checks. Behavioral
|
|
203
|
+
measurement remains in the separate `principal-pi-skills-evals` repository, while routing
|
|
204
|
+
checks remain here. The checkout check
|
|
205
|
+
verifies tag/HEAD consistency, not independent tag trust;
|
|
181
206
|
compare the recorded SHA with the release identity when provenance matters. Before tagging,
|
|
182
207
|
validate the actual candidate's skills and installer in an isolated `PI_CODING_AGENT_DIR`.
|
|
183
208
|
Known behavioral qualification limits remain documented; combining the release does not waive them.
|
|
@@ -186,26 +211,36 @@ CHANGELOG.md release history
|
|
|
186
211
|
and `principal-investigate` as **real files, not symlinks** — a symlink into a checkout breaks the
|
|
187
212
|
moment that directory moves, and breaks silently, since pi just reports an unknown
|
|
188
213
|
agent. It refuses to overwrite anything it did not install, and `uninstall` removes only
|
|
189
|
-
its own unmodified files.
|
|
214
|
+
its own unmodified files. Symlinked home/config ancestors resolve once to a canonical
|
|
215
|
+
directory; agent and manifest leaf symlinks (including dangling links) still refuse.
|
|
216
|
+
Installed agent files are `0644`; the ownership manifest is `0600`. Re-running `install`
|
|
217
|
+
repairs the earlier `0600` agent mode only for unchanged owned files.
|
|
218
|
+
|
|
219
|
+
**Ownership migration/recovery:** `install` no longer silently adopts byte-identical
|
|
220
|
+
unowned files, and deprecated `--force` never bypasses validation or ownership. If only
|
|
221
|
+
the manifest was lost and all five agents exactly match this package version, explicitly
|
|
222
|
+
run `node <installed-package>/scripts/install-agents.mjs adopt`, then `install` (to repair
|
|
223
|
+
unchanged owned file modes), then `check`. `adopt`
|
|
224
|
+
creates only the absent manifest and leaves agent bytes/modes untouched; it refuses an
|
|
225
|
+
existing manifest, partial sets, modified/older content and leaf symlinks. Unrelated files
|
|
226
|
+
remain unclaimed. Keep any edited or older files and restore known-good metadata from
|
|
227
|
+
your own backup; do not delete them merely to make installation pass.
|
|
190
228
|
|
|
191
229
|
Tool restriction is structural, in the agents' frontmatter: `investigate` is read-only;
|
|
192
230
|
`plan` is read-only except for its plan and creation of an absent `.principal/.gitignore`; `build`, `review`, and `debug` add
|
|
193
231
|
`bash` to run tests (and, for `build`, to write and edit).
|
|
194
232
|
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
delegations fail to authenticate while the parent session is fine, that mismatch is the
|
|
200
|
-
reason.
|
|
233
|
+
Legacy runners differ in model forwarding. If a runner does not forward the parent's
|
|
234
|
+
provider/model, check that runner's defaults and agent-frontmatter rules when a child
|
|
235
|
+
cannot authenticate. Native delegation uses the matching pi-daddy runtime's resolved
|
|
236
|
+
model and effort policy.
|
|
201
237
|
|
|
202
|
-
3. **
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
package is enough for that part; only delegation itself needs step 2.
|
|
238
|
+
3. **Inline execution remains available when the workflow selects it.** The bootstrap
|
|
239
|
+
supplies routing with the installed skills. Skipping the legacy agent installation does
|
|
240
|
+
not disable native delegation, and a failed native handoff cannot silently become inline.
|
|
206
241
|
|
|
207
|
-
4. **
|
|
208
|
-
receive.** A child gets only the `context:` mode its own `allowed-tools` names (or a
|
|
242
|
+
4. **With the matching pi-daddy candidate, each skill declares how much of the caller's
|
|
243
|
+
session it may receive.** A child gets only the `context:` mode its own `allowed-tools` names (or a
|
|
209
244
|
weaker one: `none < files < pruned < summary < fork`). Asking for more is refused, not
|
|
210
245
|
downgraded. The ceilings are decisions, and each one is explained in its frontmatter:
|
|
211
246
|
|
|
@@ -221,13 +256,69 @@ CHANGELOG.md release history
|
|
|
221
256
|
Nothing declares `context:fork`. Write the prefix in lowercase: `Context:summary` turns
|
|
222
257
|
into `tool:context:summary`, which grants no context mode.
|
|
223
258
|
|
|
224
|
-
**Egress: know what `summary` enables.** `context:summary` also permits `pruned
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
228
|
-
|
|
229
|
-
|
|
230
|
-
|
|
259
|
+
**Egress: know what `summary` enables.** `context:summary` also permits `pruned`,
|
|
260
|
+
which can carry selected turns from the active parent branch to the delegated child's
|
|
261
|
+
provider. The matching pi-daddy candidate no longer uses an external advisor to choose
|
|
262
|
+
those turns. Forwarded context still reaches the child and its provider; raising another
|
|
263
|
+
skill's ceiling extends that exposure to it.
|
|
264
|
+
|
|
265
|
+
## Reports and manual progress
|
|
266
|
+
|
|
267
|
+
Use the installed `principal-pi-progress` helper when a coordinator needs repeated report
|
|
268
|
+
allocation/persistence. It creates private unused candidate directories beneath ignored
|
|
269
|
+
`.principal/reports/`, writes complete `.md` reports exclusively, and appends a small
|
|
270
|
+
`progress.jsonl` index. It preserves an existing ignore policy and refuses an exposed path.
|
|
271
|
+
The helper is optional; Plan's write ceiling and Investigate's read-only ceiling do not grow.
|
|
272
|
+
Do not fetch/install it solely to write a report.
|
|
273
|
+
|
|
274
|
+
```sh
|
|
275
|
+
principal-pi-progress create /path/to/repo task-name '<actual candidate identity>'
|
|
276
|
+
# Set RUN to the decoded returned path; use the same caller-established identity below.
|
|
277
|
+
principal-pi-progress report "$RUN" step-1-build.md < complete-report.md
|
|
278
|
+
principal-pi-progress reference /absolute/path/to/plan.md
|
|
279
|
+
principal-pi-progress append "$RUN" < record.json
|
|
280
|
+
principal-pi-progress read "$RUN" '<actual current candidate identity>'
|
|
281
|
+
```
|
|
282
|
+
|
|
283
|
+
`report` and `reference` return `{ "path": "/absolute/path", "sha256": "<64 hex>" }`.
|
|
284
|
+
A version 1 record has exactly these fields (replace `REPORT_REF` with that returned object):
|
|
285
|
+
|
|
286
|
+
```json
|
|
287
|
+
{
|
|
288
|
+
"version": 1,
|
|
289
|
+
"plan": null,
|
|
290
|
+
"step": "impl:S1",
|
|
291
|
+
"candidate": "<actual candidate identity>",
|
|
292
|
+
"facts": {
|
|
293
|
+
"planned": { "state": "unknown", "evidence": [], "note": "No separate plan" },
|
|
294
|
+
"implemented": { "state": "complete", "evidence": ["REPORT_REF"], "note": "Implementation saved; review pending" },
|
|
295
|
+
"reviewed": { "state": "unknown", "evidence": [], "note": "Not reviewed" },
|
|
296
|
+
"integrated": { "state": "unknown", "evidence": [], "note": "Not integrated" },
|
|
297
|
+
"verified": { "state": "unknown", "evidence": [], "note": "Qualification not run" }
|
|
298
|
+
},
|
|
299
|
+
"findings": [],
|
|
300
|
+
"nextAction": "Request task review"
|
|
301
|
+
}
|
|
302
|
+
```
|
|
303
|
+
|
|
304
|
+
`plan` is null or a file reference. Every fact has `unknown`, `incomplete` or `complete`
|
|
305
|
+
state, evidence references and an honest note; complete needs evidence. A completed review
|
|
306
|
+
means the review occurred, and its note must retain the verdict, including CHANGES-REQUESTED.
|
|
307
|
+
Each finding has `id`, `source` reference and `status` (`open`, `addressed`, `verified`,
|
|
308
|
+
`accepted`, `disputed`, `duplicate`, `stale`); a duplicate also names `duplicateOf`. Preserve original
|
|
309
|
+
review baseline/definitions and PR comment URLs/IDs in the referenced complete reports.
|
|
310
|
+
|
|
311
|
+
The coordinator is the single writer. Save the report before appending progress; an append
|
|
312
|
+
failure preserves that report and leaves progress incomplete. Never force-clear a writer
|
|
313
|
+
lock. Reads return the original records plus independently assessed facts/issues: changed or
|
|
314
|
+
missing files, changed/unconfirmed candidates and malformed/incomplete records remain
|
|
315
|
+
unresolved. An incomplete final JSONL line is ignored/reported, never promoted to complete;
|
|
316
|
+
preserve its bytes and start a new run if needed. Reconcile records by step, not just the
|
|
317
|
+
last line. No helper claim proves its evidence's meaning, model judgment, approval or broad
|
|
318
|
+
candidate equivalence. It neither computes candidate identity nor resumes/runs tasks. Check
|
|
319
|
+
actual user authority/current work before choosing the next action; a title, role, commit or
|
|
320
|
+
self-authored boolean cannot grant approval. This is a trusted-coordinator filesystem helper,
|
|
321
|
+
not hostile-process containment or an atomic multi-file transaction.
|
|
231
322
|
|
|
232
323
|
## Validation
|
|
233
324
|
|
|
@@ -276,9 +367,9 @@ Decisions taken for 4.0, all closed:
|
|
|
276
367
|
| Target harness | pi only |
|
|
277
368
|
| Assurance ledger and profiles | removed; per-skill right-sizing is the mechanism; the tool lives on the `v3.2.0` tag for porting to pi-daddy |
|
|
278
369
|
| Human approval | always, after plan (feature) or after the debug note (bugfix); the artifact scales, the stop does not |
|
|
279
|
-
| Routing delivery |
|
|
280
|
-
| Build delegation |
|
|
281
|
-
| Plan persistence | multi-step plans to git-ignored `.principal/plans/<slug>.md`;
|
|
370
|
+
| Routing delivery | request-local bootstrap after selected-resource discovery; quoted markers do not suppress it |
|
|
371
|
+
| Build delegation | bound native phase, or explicitly configured legacy runner when native tools are absent; inline is a workflow choice |
|
|
372
|
+
| Plan persistence | multi-step plans to git-ignored `.principal/plans/<slug>.md`; titles locate candidates, while manual resume checks actual authority, current work and evidence |
|
|
282
373
|
| Decide vs architect | both kept; decide answers "should we / which", architect answers "how is it structured" |
|
|
283
374
|
| Measurement | behavioural measurement lives in [principal-pi-skills-evals](https://github.com/mojomanyana/principal-pi-skills-evals); routing checks stay here |
|
|
284
375
|
|
|
@@ -317,3 +408,5 @@ Why the files look the way they do. Each of these was learned by measuring the a
|
|
|
317
408
|
## License
|
|
318
409
|
|
|
319
410
|
MIT © 2026 Nemanja Alavanja. See [LICENSE](./LICENSE).
|
|
411
|
+
|
|
412
|
+
The Debug inline budget includes three generated frontmatter words that mark Principal package identity; missing or replaced package metadata must refuse native binding rather than downgrade to inline instructions.
|