principal-pi-skills 3.1.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 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
- This file is the **routing layer**. The framework deliberately has no routing skill —
7
- routing belongs to the orchestrator (you), and each file is self-contained: one file is
8
- the whole contract, there is no required reading beyond it.
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
- judgment, and noisy loops get delegated.
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`, `build`, `git-ops`.
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/`. Delegate to the
23
- `principal-*` names: agent names are a flat global registry, so a bare `plan` is a slot
24
- any package can claim and the last one loaded wins silently. The unprefixed names remain
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 — the main work, and the only phase that writes durably. Never fan parallel writers into one working tree: "parallel-safe" is a claim about which steps need each other's output |
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 rule-6 destructive ops require user consequence-acceptance no subagent can obtain |
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`, not
42
- `decide`; "how do I commit this" is `git-ops`, not `build`; "why is this test red" is
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 — the two drifting apart is how a spine ends
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 → build (inline) → review → git-ops
75
- finish (inline). Enter `architect`/`decide` first when the call is architectural or still
76
- contested.
77
- - Bug (`/principal-bugfix <symptom>`): debug → build (inline) → review → git-ops finish (inline).
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 three times: `<name>/SKILL.md` (interactive contract),
103
- `agents/principal-<name>.md` (the single-shot contract subagents get) and
104
- `agents/<name>.md` (its deprecated generic-name alias). They are different artifacts, not
105
- copies — but 74–84% of each pair is identical, and that shared majority is where they used
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
- All three are generated from `contracts/<name>.md.tmpl`. The two namespaced workflows are
109
- likewise generated from `contracts/workflows.md.tmpl`. Change shared behavior ONCE, there,
110
- then `npm run generate`. Editing a generated file directly is reverted by the next run and
111
- fails `npm run generate:check` in CI. Hand-mirroring used to be a reviewer's job and was
112
- never reliably done — which is how the D-scenarios once measured a contract no subagent had
113
- been handed.
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@v3.1.0` — the immutable install
123
- coordinate for source version `3.1.0`. Publication status is external to these package bytes:
124
- run `npm view principal-pi-skills version dist-tags --json` and check the
125
- [GitHub release](https://github.com/mojomanyana/principal-pi-skills/releases/tag/v3.1.0) before
126
- installing. Preparation evidence (2026-09-11): `v3.1.0` was pending and npm `latest` was `3.0.1`;
127
- this dated fact is not current registry guidance. `standard` is the default assurance
128
- profile, so a v2 invocation keeps working unchanged. It registers the
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".