principal-pi-skills 3.2.0 → 4.0.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 +40 -66
- package/CHANGELOG.md +31 -497
- package/README.md +95 -233
- package/agents/principal-build.md +114 -0
- package/agents/principal-debug.md +6 -0
- package/agents/principal-plan.md +17 -60
- package/agents/principal-review.md +8 -29
- package/architect/SKILL.md +5 -5
- package/bootstrap/BOOTSTRAP.md +25 -0
- package/build/SKILL.md +16 -19
- package/debug/SKILL.md +6 -0
- package/decide/SKILL.md +6 -6
- package/extensions/bootstrap.ts +45 -0
- package/git-ops/SKILL.md +5 -8
- package/package.json +9 -10
- package/plan/SKILL.md +13 -57
- package/prompts/principal-bugfix.md +50 -137
- package/prompts/principal-feature.md +48 -137
- package/review/SKILL.md +8 -29
- package/scripts/install-agents.mjs +12 -17
- package/agents/debug.md +0 -130
- package/agents/plan.md +0 -184
- package/agents/review.md +0 -139
- package/prompts/bugfix.md +0 -146
- package/prompts/feature.md +0 -146
- package/schemas/assurance-evidence-receipt-v1.schema.json +0 -48
- package/schemas/assurance-run-state-v1.schema.json +0 -307
- package/schemas/assurance-task-packet-v1.schema.json +0 -91
- package/scripts/assurance-state.mjs +0 -2203
package/AGENTS.md
CHANGED
|
@@ -3,44 +3,44 @@
|
|
|
3
3
|
Instructions for the [pi coding agent](https://github.com/badlogic/pi-mono) operating
|
|
4
4
|
with this set installed. Read this once at session start.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
6
|
+
The bootstrap extension (`extensions/bootstrap.ts`) injects this file's routing table,
|
|
7
|
+
compressed, from `bootstrap/BOOTSTRAP.md` at session start and after compaction — you do
|
|
8
|
+
not need to read this file for the framework to route. This file is the long-form
|
|
9
|
+
**routing layer**: full rationale per row, the complete `Next:` set, and the maintenance
|
|
10
|
+
rule. The framework deliberately has no routing skill — routing belongs to the
|
|
11
|
+
orchestrator (you), and each other file is self-contained: no required reading beyond it.
|
|
9
12
|
|
|
10
13
|
## Two forms, one rule
|
|
11
14
|
|
|
12
15
|
A **skill** runs inline in this session: it shares your context, can dialogue with the
|
|
13
16
|
user, and its work stays in your window. A **subagent** (via the subagent tool) runs in
|
|
14
17
|
its own context with its own tools, cannot ask questions, and returns only its output
|
|
15
|
-
template. The rule: dialogue and session state stay inline; heavy reading, cold
|
|
16
|
-
|
|
18
|
+
template. The rule: dialogue and session state stay inline; heavy reading, cold judgment,
|
|
19
|
+
and noisy loops get delegated.
|
|
17
20
|
|
|
18
21
|
The set:
|
|
19
22
|
|
|
20
|
-
- Skills (inline only): `decide`, `architect`, `
|
|
23
|
+
- Skills (inline only): `decide`, `architect`, `git-ops`.
|
|
21
24
|
- Agents (delegate when the subagent tool is available): `principal-plan`,
|
|
22
|
-
`principal-review`, `principal-debug` — defined in `agents/`.
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
as deprecated aliases. Each contract also has a SKILL.md for interactive use when
|
|
26
|
-
delegation is unavailable or the user wants to work through it conversationally.
|
|
25
|
+
`principal-build`, `principal-review`, `principal-debug` — defined in `agents/`. Each
|
|
26
|
+
contract also has a SKILL.md for interactive use when delegation is unavailable or the
|
|
27
|
+
user wants to work through it conversationally.
|
|
27
28
|
|
|
28
29
|
## Routing — pick by what the input looks like
|
|
29
30
|
|
|
30
31
|
| Input shape | Route to | How |
|
|
31
32
|
|---|---|---|
|
|
32
33
|
| Exploring a decision, not executing one ("should I…", "what are my options", "I'm stuck") | `decide` | inline — the dialogue is the value |
|
|
33
|
-
| A system to design or a significant/irreversible choice ("design X", "Postgres or DynamoDB") | `architect` | inline — drivers come from asking |
|
|
34
|
+
| A system to design or a significant/irreversible choice ("design X", "Postgres or DynamoDB", "review our architecture") | `architect` | inline — drivers come from asking |
|
|
34
35
|
| 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 |
|
|
35
|
-
| Code to write ("implement", "fix this", "make the test pass") | `build` | inline
|
|
36
|
+
| Code to write ("implement", "fix this known bug", "make the test pass") | `build` | inline, or `principal-build` per approved plan step when the subagent tool exists — never fan parallel writers into one working tree |
|
|
36
37
|
| A change to judge before landing ("review this", "ready to merge?") | `review` | **subagent, always when available** — a fresh context judging the diff cold beats self-review; inline review of code you just wrote is anchored on its own reasoning |
|
|
37
38
|
| An unknown failure to diagnose ("why is this failing", "find the bug") | `debug` | **subagent** when reproduction is noisy (flaky loops, bisects); inline when the user is driving |
|
|
38
|
-
| A git or GitHub operation ("commit", "push", "open a PR", "I leaked a secret") | `git-ops` | inline, never delegated — needs this session's working-tree state, and
|
|
39
|
+
| A git or GitHub operation ("commit", "push", "open a PR", "I leaked a secret") | `git-ops` | inline, never delegated — needs this session's working-tree state, and destructive ops require user consequence-acceptance no subagent can obtain |
|
|
39
40
|
|
|
40
41
|
**When more than one applies**, route by altitude: the highest-altitude match for the
|
|
41
|
-
*actual* request, not the surface phrasing. "Redis or Memcached?" is `architect
|
|
42
|
-
|
|
43
|
-
`debug` (unknown cause), not `build` (known fix).
|
|
42
|
+
*actual* request, not the surface phrasing. "Redis or Memcached?" is `architect`; "how do
|
|
43
|
+
I commit this" is `git-ops`, not `build`; "why is this test red" is `debug`, not `build`.
|
|
44
44
|
|
|
45
45
|
**When no skill fits**, don't force one. Everyday Q&A doesn't need the framework.
|
|
46
46
|
|
|
@@ -66,16 +66,15 @@ an interpretation. The complete set:
|
|
|
66
66
|
`git-ops` runs inline and terminates the chain. A ceremonial `Next:` on those three invited
|
|
67
67
|
a workflow to route somewhere nobody asked to go. Every value above is consumed by both
|
|
68
68
|
workflow prompts, and a unit test fails if a contract declares a value no workflow handles
|
|
69
|
-
or a workflow handles one no contract can emit
|
|
70
|
-
up with a transition that silently does nothing.
|
|
69
|
+
or a workflow handles one no contract can emit.
|
|
71
70
|
|
|
72
71
|
Typical spines (available as prompt templates):
|
|
73
72
|
|
|
74
|
-
- Feature (`/principal-feature <task>`): plan →
|
|
75
|
-
finish
|
|
76
|
-
contested.
|
|
77
|
-
- Bug (`/principal-bugfix <symptom>`): debug →
|
|
78
|
-
If debug's note says design flaw, stop and surface it.
|
|
73
|
+
- Feature (`/principal-feature <task>`): plan → approval stop → build (inline or
|
|
74
|
+
delegated) → review → git-ops finish. Enter `architect`/`decide` first when the call is
|
|
75
|
+
architectural or still contested.
|
|
76
|
+
- Bug (`/principal-bugfix <symptom>`): debug → approval stop → build → review → git-ops
|
|
77
|
+
finish. If debug's note says design flaw, stop and surface it.
|
|
79
78
|
- Either spine, when the subagent tool is missing or reports an unknown agent: run that
|
|
80
79
|
phase's skill inline instead and say so in the digest. Fall back on *absence* only —
|
|
81
80
|
any other agent failure stops the workflow. Build↔review repair loops stop after two
|
|
@@ -83,34 +82,22 @@ Typical spines (available as prompt templates):
|
|
|
83
82
|
- Tiny change: build → git-ops, both inline — every contract carries a Right-sizing
|
|
84
83
|
rule; don't add ceremony the file itself would refuse.
|
|
85
84
|
|
|
86
|
-
### Workflow assurance (v3)
|
|
87
|
-
|
|
88
|
-
Both namespaced prompts parse and persist `lean|standard|critical`; standard is the default,
|
|
89
|
-
and omitted flags preserve v2 invocation. Routing still belongs here/the prompt, never a new
|
|
90
|
-
skill. The shared controller contract is generated from `contracts/workflows.md.tmpl`; the
|
|
91
|
-
hash-chained state and gates live in `scripts/assurance-state.mjs`, outside the product tree.
|
|
92
|
-
Lean/standard retain the complete inline baseline. Critical requires owned isolation and
|
|
93
|
-
fresh plan/review contexts; absence returns `BLOCKED_CRITICAL_ASSURANCE`, never inline
|
|
94
|
-
self-review presented as independent. Build remains the sole source writer and Git-Ops offers
|
|
95
|
-
merge locally, push/open PR, or keep the branch after fresh evidence.
|
|
96
|
-
|
|
97
85
|
A delegated step returning `BLOCKED` stops the chain: surface its one question to the
|
|
98
86
|
user; don't answer it yourself and keep going.
|
|
99
87
|
|
|
100
88
|
## Maintenance rule — the contracts are generated
|
|
101
89
|
|
|
102
|
-
`plan`, `review` and `debug` exist
|
|
103
|
-
`agents/principal-<name>.md` (the single-shot contract subagents get)
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
to drift.
|
|
90
|
+
`plan`, `build`, `review` and `debug` exist twice: `<name>/SKILL.md` (interactive contract)
|
|
91
|
+
and `agents/principal-<name>.md` (the single-shot contract subagents get) — different
|
|
92
|
+
artifacts, not copies, but most of each pair is identical, and that shared majority is
|
|
93
|
+
where they used to drift.
|
|
107
94
|
|
|
108
|
-
|
|
109
|
-
likewise generated from `contracts/workflows.md.tmpl
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
95
|
+
Both are generated from `contracts/<name>.md.tmpl`. The two namespaced workflows are
|
|
96
|
+
likewise generated from `contracts/workflows.md.tmpl` — four contracts plus the workflows
|
|
97
|
+
template are the source of everything under `agents/`, `prompts/`, and the four dual-use
|
|
98
|
+
`SKILL.md` files. Change shared behavior ONCE, there, then `npm run generate`. Editing a
|
|
99
|
+
generated file directly is reverted by the next run and fails `npm run generate:check` in
|
|
100
|
+
CI.
|
|
114
101
|
|
|
115
102
|
Deliberate divergences are marked in the template: `{{#skill}}` for interactive-dialogue
|
|
116
103
|
rules, `{{#agent}}` for single-shot mechanics — the BLOCKED form, the
|
|
@@ -119,23 +106,10 @@ to every output.
|
|
|
119
106
|
|
|
120
107
|
## Setup (pi)
|
|
121
108
|
|
|
122
|
-
1. `pi install git:github.com/mojomanyana/principal-pi-skills@
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
skills and the `/principal-feature` + `/principal-bugfix` commands via the `pi`
|
|
130
|
-
manifest. Install a tag, not a branch.
|
|
131
|
-
2. Subagents need pi-mono's subagent extension (`examples/extensions/subagent`, which ships
|
|
132
|
-
inside pi itself — nothing to vendor) and the agent definitions installed once:
|
|
133
|
-
`npx -p principal-pi-skills principal-pi-agents install`. It copies real
|
|
134
|
-
files into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses to overwrite
|
|
135
|
-
anything it did not install.
|
|
136
|
-
A delegated agent runs on the pi config's `defaultProvider`/`defaultModel`, **not** the
|
|
137
|
-
`--provider`/`--model` you gave the parent: the extension forwards `--model` only when an
|
|
138
|
-
agent's frontmatter names one, and these deliberately do not. If delegations fail to
|
|
139
|
-
authenticate while the parent session is fine, that mismatch is the reason.
|
|
140
|
-
3. Without the extension, everything runs inline via the skills; the How column above
|
|
141
|
-
simply collapses to "inline".
|
|
109
|
+
1. `pi install git:github.com/mojomanyana/principal-pi-skills@v4.0.0` — installs the seven
|
|
110
|
+
skills, the `/principal-feature` and `/principal-bugfix` commands, and the bootstrap
|
|
111
|
+
extension, which loads automatically with the package. Install a tag, not a branch.
|
|
112
|
+
2. Subagents (optional): `npx -p principal-pi-skills principal-pi-agents install` copies
|
|
113
|
+
the four agent definitions into `${PI_CODING_AGENT_DIR:-~/.pi/agent}/agents` and refuses
|
|
114
|
+
to overwrite anything it did not install. Without it, everything in the routing table
|
|
115
|
+
above still runs; the How column just collapses to "inline".
|