principal-pi-skills 4.0.1 → 4.2.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 +8 -3
- package/CHANGELOG.md +25 -0
- package/README.md +17 -9
- package/agents/principal-build.md +6 -2
- package/agents/principal-plan.md +3 -1
- package/agents/principal-review.md +16 -3
- package/bootstrap/BOOTSTRAP.md +3 -1
- package/package.json +1 -1
- package/plan/SKILL.md +3 -1
- package/prompts/principal-bugfix.md +18 -9
- package/prompts/principal-feature.md +18 -9
- package/prompts/principal-refactor.md +68 -0
- package/prompts/principal-review-branch.md +22 -0
- package/review/SKILL.md +9 -3
package/AGENTS.md
CHANGED
|
@@ -75,7 +75,12 @@ Typical spines (available as prompt templates):
|
|
|
75
75
|
architectural or still contested.
|
|
76
76
|
- Bug (`/principal-bugfix <symptom>`): debug → approval stop → build → review → git-ops
|
|
77
77
|
finish. If debug's note says design flaw, stop and surface it.
|
|
78
|
-
-
|
|
78
|
+
- Refactor (`/principal-refactor <scope>`): the feature spine with a no-behavior-change
|
|
79
|
+
frame — existing tests pass unchanged, uncovered behavior gets a characterization test first.
|
|
80
|
+
- Review a branch (`/principal-review-branch [base]`): cold `principal-review` of
|
|
81
|
+
`merge-base <base> HEAD..HEAD`, then git-ops finish mode on APPROVE; findings stop for the
|
|
82
|
+
user otherwise. No plan, no build.
|
|
83
|
+
- Any spine, when the subagent tool is missing or reports an unknown agent: run that
|
|
79
84
|
phase's skill inline instead and say so in the digest. Fall back on *absence* only —
|
|
80
85
|
any other agent failure stops the workflow. Build↔review repair loops stop after two
|
|
81
86
|
rounds; a third means the plan or the diagnosis was wrong, not the code.
|
|
@@ -108,8 +113,8 @@ to every output.
|
|
|
108
113
|
|
|
109
114
|
## Setup (pi)
|
|
110
115
|
|
|
111
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.0
|
|
112
|
-
skills, the
|
|
116
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.1.0` — installs the seven
|
|
117
|
+
skills, the four `/principal-*` commands, and the bootstrap
|
|
113
118
|
extension, which loads automatically with the package. Install a tag, not a branch.
|
|
114
119
|
2. Subagents (optional): `npx -p principal-pi-skills principal-pi-agents install` copies
|
|
115
120
|
the four agent definitions into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses
|
package/CHANGELOG.md
CHANGED
|
@@ -6,6 +6,31 @@ Where review revealed a prior claim or design decision didn't hold up under clos
|
|
|
6
6
|
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
+
## [4.2.0] — 2026-09-21
|
|
10
|
+
|
|
11
|
+
**Cheaper loops, borrowed from superpowers' subagent-driven development.** A delegated
|
|
12
|
+
`principal-build` now writes its full report to `.principal/reports/<step>-build.md` and
|
|
13
|
+
returns five status lines, so reports stop accumulating in the steering context. Review is
|
|
14
|
+
handed a diff package (`git diff --stat` + full diff, one file) and the build reports; it
|
|
15
|
+
treats a verbatim `Full evidence:` line as test evidence and runs a test only for a named
|
|
16
|
+
doubt, instead of rebuilding a worktree and re-running the suite on every call. Repair rounds
|
|
17
|
+
resume the build agent when the tool allows and get a **scoped re-review** (agent form only):
|
|
18
|
+
each open finding ID is verdicted ADDRESSED or NOT ADDRESSED, new breakage is checked in the
|
|
19
|
+
fix diff alone. Plan batches same-shape edits across files into one step. The spines name
|
|
20
|
+
the model tier per review: strongest for the whole-change review, mid-tier for scoped
|
|
21
|
+
re-reviews. Skill forms of build and review are unchanged except review's evidence rule.
|
|
22
|
+
|
|
23
|
+
## [4.1.0] — 2026-09-21
|
|
24
|
+
|
|
25
|
+
**Added.** Two prompt templates. `/principal-refactor <scope>` is the feature spine with a
|
|
26
|
+
no-behavior-change frame: plan steps keep existing tests passing unchanged, uncovered behavior
|
|
27
|
+
gets a characterization test first, and review treats any observable behavior change as a
|
|
28
|
+
`[BLOCKER]`. `/principal-review-branch [base]` cold-reviews the current branch against `base`
|
|
29
|
+
(default `main`) with `principal-review`, runs git-ops finish mode on APPROVE, and stops with
|
|
30
|
+
findings otherwise; it has no plan or build phase and is hand-written rather than generated.
|
|
31
|
+
All four prompts now carry an `argument-hint` for pi's autocomplete. The bootstrap and
|
|
32
|
+
AGENTS.md name the two new commands. No skill or agent text changed.
|
|
33
|
+
|
|
9
34
|
## [4.0.1] — 2026-09-21
|
|
10
35
|
|
|
11
36
|
Removed the seeded `<skill>/tests/fixtures/` trees (build, debug, git-ops) and the
|
package/README.md
CHANGED
|
@@ -44,9 +44,9 @@ around.
|
|
|
44
44
|
|---|---|---|---|
|
|
45
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
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`,
|
|
48
|
-
| `build` | Test-first implementation — code proven by a test you watched fail | subagent (`agents/principal-build.md`,
|
|
49
|
-
| `review` | One pass, two axes — correctness and simplicity — ending in one severity-ranked verdict | subagent (`agents/principal-review.md`,
|
|
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
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
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 |
|
|
52
52
|
|
|
@@ -58,19 +58,27 @@ automatically at session start, so nothing needs to point pi at it by hand.
|
|
|
58
58
|
## Bootstrap and workflows
|
|
59
59
|
|
|
60
60
|
A pi extension (`extensions/bootstrap.ts`) injects `bootstrap/BOOTSTRAP.md` — about 250
|
|
61
|
-
words — as a
|
|
61
|
+
words — as a leading message at session start and again after compaction, so the routing
|
|
62
62
|
context survives a context reset instead of depending on someone re-reading a file. It
|
|
63
63
|
carries the routing table compressed to input shape → skill → inline/subagent, the closed
|
|
64
64
|
`Next:` vocabulary the phases hand off with, and model tiering: the cheapest model for a
|
|
65
65
|
build agent working a complete step spec, the session default for plan and debug, the
|
|
66
66
|
strongest available for review and architect.
|
|
67
67
|
|
|
68
|
-
|
|
69
|
-
after the planning phase
|
|
68
|
+
The three spines (`/principal-feature <task>`, `/principal-bugfix <symptom>`,
|
|
69
|
+
`/principal-refactor <scope>`) stop for your approval after the planning phase or the debug
|
|
70
|
+
note and wait for an explicit go
|
|
70
71
|
before building — presenting the artifact and starting to build in the same turn is the
|
|
71
72
|
failure the rule exists to catch. The artifact scales with the change (three lines for a
|
|
72
73
|
config tweak, full slices for a feature); the stop does not.
|
|
73
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
|
+
|
|
74
82
|
When plan's output is the multi-step template, it writes the plan to
|
|
75
83
|
`.principal/plans/<slug>.md` and prints the path; `.principal/.gitignore` is created
|
|
76
84
|
alongside it on first use, so the directory is git-ignored and self-ignoring. Delegated
|
|
@@ -100,11 +108,11 @@ CHANGELOG.md release history
|
|
|
100
108
|
1. **Skills + prompts** — install an immutable tag, not a branch:
|
|
101
109
|
|
|
102
110
|
```
|
|
103
|
-
pi install git:github.com/mojomanyana/principal-pi-skills@v4.0
|
|
111
|
+
pi install git:github.com/mojomanyana/principal-pi-skills@v4.1.0
|
|
104
112
|
```
|
|
105
113
|
|
|
106
|
-
The `pi` manifest registers the seven skills, the `/principal
|
|
107
|
-
|
|
114
|
+
The `pi` manifest registers the seven skills, the four `/principal-*` commands, and the
|
|
115
|
+
bootstrap extension — it loads automatically with
|
|
108
116
|
the package; there is no separate extension-install step. Unpinned `main` moves under
|
|
109
117
|
you, so install a tag if you want a fixed, nameable behavior.
|
|
110
118
|
|
|
@@ -12,8 +12,12 @@ allowed-tools: read, grep, find, ls, edit, write, bash
|
|
|
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
|
|
16
|
-
|
|
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
|
package/agents/principal-plan.md
CHANGED
|
@@ -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.
|
|
@@ -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
|
|
67
|
-
(
|
|
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
|
|
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. |
|
package/bootstrap/BOOTSTRAP.md
CHANGED
|
@@ -18,7 +18,9 @@ delegated. A subagent never invokes another agent — you read its `Next:` line
|
|
|
18
18
|
plan → `build`; debug → `build` `plan` `done` `blocked`; build → `review` `debug` `blocked`;
|
|
19
19
|
review → `build` `git-ops`. `decide`, `architect`, `git-ops` end without a `Next:`.
|
|
20
20
|
|
|
21
|
-
Multi-step work goes through `/principal-feature <task
|
|
21
|
+
Multi-step work goes through `/principal-feature <task>`, `/principal-bugfix <symptom>`, or
|
|
22
|
+
`/principal-refactor <scope>`; `/principal-review-branch [base]` cold-reviews and finishes a
|
|
23
|
+
branch built outside them. The spines
|
|
22
24
|
which stop for your approval after planning and can resume from `.principal/plans/`.
|
|
23
25
|
|
|
24
26
|
Model choice when you dispatch: cheapest model for a build agent working from a complete
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "principal-pi-skills",
|
|
3
|
-
"version": "4.0
|
|
3
|
+
"version": "4.2.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
|
@@ -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.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Bugfix spine — debug, approval, build, review, git-ops.
|
|
3
|
+
argument-hint: "<symptom>"
|
|
3
4
|
---
|
|
4
5
|
Execute this workflow for: $@
|
|
5
6
|
|
|
@@ -20,17 +21,25 @@ build until the user says go. Presenting the artifact and starting to build in t
|
|
|
20
21
|
is the failure. The artifact scales — three lines for a config change, full slices for a
|
|
21
22
|
feature — the stop does not. A re-plan needs a new approval.
|
|
22
23
|
|
|
23
|
-
**Build.** One writer at a time, on a branch the user can see. Inline when there is no
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
the
|
|
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.
|
|
28
31
|
|
|
29
32
|
**Review.** Always delegate to `principal-review` when the tool exists — a cold read beats
|
|
30
|
-
self-review.
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
`
|
|
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.
|
|
34
43
|
|
|
35
44
|
**Blocked.** A phase returning `BLOCKED` stops the chain: surface its one question and
|
|
36
45
|
wait. Do not answer it yourself.
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
description: Feature spine — plan, approval, build, review, git-ops.
|
|
3
|
+
argument-hint: "<task>"
|
|
3
4
|
---
|
|
4
5
|
Execute this workflow for: $@
|
|
5
6
|
|
|
@@ -20,17 +21,25 @@ build until the user says go. Presenting the artifact and starting to build in t
|
|
|
20
21
|
is the failure. The artifact scales — three lines for a config change, full slices for a
|
|
21
22
|
feature — the stop does not. A re-plan needs a new approval.
|
|
22
23
|
|
|
23
|
-
**Build.** One writer at a time, on a branch the user can see. Inline when there is no
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
the
|
|
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.
|
|
28
31
|
|
|
29
32
|
**Review.** Always delegate to `principal-review` when the tool exists — a cold read beats
|
|
30
|
-
self-review.
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
`
|
|
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.
|
|
34
43
|
|
|
35
44
|
**Blocked.** A phase returning `BLOCKED` stops the chain: surface its one question and
|
|
36
45
|
wait. Do not answer it yourself.
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Refactor spine — the feature spine with a no-behavior-change frame.
|
|
3
|
+
argument-hint: "<scope>"
|
|
4
|
+
---
|
|
5
|
+
Execute this workflow for: refactor $@ without changing behavior.
|
|
6
|
+
|
|
7
|
+
<!-- shared:start -->
|
|
8
|
+
## How this chain runs
|
|
9
|
+
|
|
10
|
+
You are the orchestrator. Each phase is a skill or a `principal-*` agent; you route on the
|
|
11
|
+
`Next:` line it returns and never let a phase invoke another. When a step names an agent,
|
|
12
|
+
try it once; if the subagent tool is missing or reports an unknown agent, run that phase's
|
|
13
|
+
skill inline and say so in the Digest. Any other agent failure stops the chain.
|
|
14
|
+
|
|
15
|
+
**Resume.** Before the first phase, list `.principal/plans/`. If exactly one file's `## Plan:` line
|
|
16
|
+
describes this request's task, read it and `git log` first: a step whose commit exists is
|
|
17
|
+
done. If several could match, name them and ask the user which one; if none does, start the chain at step 1. Resume at the first step without one. Never re-plan a plan the user already approved.
|
|
18
|
+
|
|
19
|
+
**Approval.** After the planning or diagnosing phase returns, present its artifact and stop. Do not
|
|
20
|
+
build until the user says go. Presenting the artifact and starting to build in the same turn
|
|
21
|
+
is the failure. The artifact scales — three lines for a config change, full slices for a
|
|
22
|
+
feature — the stop does not. A re-plan needs a new approval.
|
|
23
|
+
|
|
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.
|
|
31
|
+
|
|
32
|
+
**Review.** Always delegate to `principal-review` when the tool exists — a cold read beats
|
|
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.
|
|
43
|
+
|
|
44
|
+
**Blocked.** A phase returning `BLOCKED` stops the chain: surface its one question and
|
|
45
|
+
wait. Do not answer it yourself.
|
|
46
|
+
|
|
47
|
+
**Finish.** Git-Ops runs inline in finish mode: fresh full suite on the final tree, then
|
|
48
|
+
exactly merge locally / push and open a PR / keep the branch. Never auto-push, tag,
|
|
49
|
+
force-push, or clean up. End with `Digest:` followed by one line per label, in this order:
|
|
50
|
+
`Ref:` (full final commit SHA or branch), `Plan file:` (path or none), `Assumptions:`,
|
|
51
|
+
`Follow-ups:`, `Evidence gaps:`, `Execution contexts:` (inline / delegated per phase).
|
|
52
|
+
No transcript narration after it.
|
|
53
|
+
<!-- shared:end -->
|
|
54
|
+
|
|
55
|
+
## Refactor path
|
|
56
|
+
|
|
57
|
+
The request is a refactor of `$@`: structure changes, behavior does not.
|
|
58
|
+
|
|
59
|
+
1. Invoke `principal-plan` (or Plan inline) with this frame: every step keeps the existing
|
|
60
|
+
tests passing unchanged — a test needing new assertions means behavior changed, so it is
|
|
61
|
+
a finding, not a step. Behavior the refactor touches that has no test gets a
|
|
62
|
+
characterization test pinning it first, as its own step. A `[ONE-WAY]` step (public API,
|
|
63
|
+
schema, data) must carry its rollback note.
|
|
64
|
+
2. Approval stop. Then Build, step by step, as above.
|
|
65
|
+
3. Review, with one extra question: does the diff change any observable behavior? If yes,
|
|
66
|
+
that is a `[BLOCKER]` finding regardless of quality. Repair loop as above. `Next: debug`
|
|
67
|
+
→ `principal-debug` (or Debug inline); `Next: blocked` → stop.
|
|
68
|
+
4. Git-Ops finish mode and the Digest.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Cold review of the current branch against a base, then finish mode.
|
|
3
|
+
argument-hint: "[base]"
|
|
4
|
+
---
|
|
5
|
+
Review this branch against `${1:-main}` and finish it.
|
|
6
|
+
|
|
7
|
+
You are the orchestrator; this chain has no planning phase and no plan file. Work that was
|
|
8
|
+
built outside the workflows gets the same cold review the workflows give.
|
|
9
|
+
|
|
10
|
+
1. Find the range: `git merge-base ${1:-main} HEAD` is the base; `HEAD` is the head. If
|
|
11
|
+
the working tree is dirty, say so and stop — review judges committed work.
|
|
12
|
+
2. Delegate to `principal-review` when the subagent tool exists (otherwise run Review
|
|
13
|
+
inline and say so in the Digest). Hand it the base and head SHAs and the commit list;
|
|
14
|
+
it computes the diff itself in a disposable workspace.
|
|
15
|
+
3. Route on the verdict. `APPROVE` or `APPROVE-WITH-NITS` → Git-Ops finish mode: fresh
|
|
16
|
+
full suite on this tree, then exactly merge locally / push and open a PR / keep the
|
|
17
|
+
branch. `CHANGES-REQUESTED` → present the findings with their `[REV-…]` IDs and stop;
|
|
18
|
+
there is no plan to repair against, so the user decides which to accept, and a repair
|
|
19
|
+
is a new request. `UNVERIFIED` → say what blocked verification and stop.
|
|
20
|
+
4. End with `Digest:` followed by one line per label: `Ref:` (base..head), `Verdict:`,
|
|
21
|
+
`Findings:` (count by severity, or none), `Follow-ups:`, `Execution contexts:`
|
|
22
|
+
(inline / delegated). No transcript narration after it.
|
package/review/SKILL.md
CHANGED
|
@@ -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
|
|
60
|
-
(
|
|
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
|
|
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. |
|