@gonrocca/zero-pi 0.1.22 → 0.1.24

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.
Files changed (2) hide show
  1. package/README.md +223 -217
  2. package/package.json +4 -5
package/README.md CHANGED
@@ -7,290 +7,296 @@
7
7
  ╚══════╝ ╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝
8
8
  ```
9
9
 
10
+ <div align="center">
11
+
10
12
  # @gonrocca/zero-pi
11
13
 
12
- An installable layer for **[pi](https://pi.dev)** — it adds the zero
13
- spec-driven development workflow, skill auto-learning, and an animated `ZERO`
14
- startup banner **without modifying pi itself**.
14
+ **The zero spec-driven development workflow, packaged for [pi](https://pi.dev).**
15
+
16
+ [![npm](https://img.shields.io/npm/v/@gonrocca/zero-pi?color=af8aff&label=npm)](https://www.npmjs.com/package/@gonrocca/zero-pi)
17
+ [![license](https://img.shields.io/npm/l/@gonrocca/zero-pi?color=eebe5c)](./LICENSE)
18
+ [![node](https://img.shields.io/node/v/@gonrocca/zero-pi?color=4fddab&label=node)](https://nodejs.org)
19
+
20
+ </div>
21
+
22
+ ---
15
23
 
16
- Same idea as `gentle-pi`: pi stays untouched; zero-pi is a package pi loads.
24
+ zero-pi adds the **`/forge`** SDD pipeline, skill auto-learning, adaptive
25
+ per-phase models, a metered-billing guard, and an animated `ZERO` banner —
26
+ **without modifying pi itself**. Same idea as `gentle-pi`: pi stays untouched;
27
+ zero-pi is a package pi loads. Every prompt, skill, extension and theme below
28
+ ships inside this one package.
17
29
 
18
- ## Install
30
+ ## Contents
19
31
 
20
- ```bash
32
+ - [Install](#-install)
33
+ - [The SDD workflow](#-the-sdd-workflow)
34
+ - [Quality-of-life extensions](#-quality-of-life-extensions)
35
+ - [Commands](#-commands)
36
+ - [Environment variables](#-environment-variables)
37
+ - [Files it reads & writes](#-files-it-reads--writes)
38
+ - [Relationship to `zero`](#-relationship-to-zero)
39
+ - [Development](#-development)
40
+
41
+ ---
42
+
43
+ ## 📦 Install
44
+
45
+ ```
21
46
  pi install npm:@gonrocca/zero-pi
22
47
  ```
23
48
 
24
49
  That registers zero-pi in `~/.pi/agent/settings.json` and makes its prompts,
25
- skills, and the startup-banner extension available in every pi session.
50
+ skills, theme, and extensions available in every pi session.
26
51
 
27
- To remove it:
52
+ | Requirement | Detail |
53
+ | ----------- | ------ |
54
+ | `pi-subagents` | **Required** — the SDD pipeline delegates each phase to a sub-agent. Install with `pi install npm:pi-subagents`. |
55
+ | Node | ≥ 20.6 — pi loads the TypeScript extensions directly. |
56
+ | After upgrade | Restart pi for the new version to take effect. |
28
57
 
29
- ```bash
30
- pi remove npm:@gonrocca/zero-pi
31
- ```
58
+ Remove it with `pi remove npm:@gonrocca/zero-pi`.
59
+
60
+ ---
61
+
62
+ ## 🛠 The SDD workflow
63
+
64
+ ### `/forge` — the four-phase pipeline
65
+
66
+ A spec-driven development run, driven through four phases in order:
67
+
68
+ | Phase | Does |
69
+ | ----- | ---- |
70
+ | **explore** | Investigate the codebase read-only; produce findings. |
71
+ | **plan** | Write requirements, design, and an ordered task list. |
72
+ | **build** | Implement the plan. |
73
+ | **veredicto** | Review the build adversarially and record a verdict. |
74
+
75
+ Start it with `/forge <feature>`. The orchestrator drives phase order and
76
+ enforces a hard build/veredicto iteration cap — a `corregir` verdict re-runs
77
+ `build`, a `replantear` re-runs `plan`, and when the cap is reached without a
78
+ `pasa` the run stops and reports the result as **not verified**.
79
+ `/forge --continue [slug]` resumes an interrupted run from its `.sdd/<slug>/`
80
+ artifacts.
81
+
82
+ A run can also start from natural language: describe the work and signal SDD
83
+ intent — "hacelo con sdd", "usá el pipeline" — and the `sdd-routing` skill
84
+ routes it into `/forge`. It triggers only on a clear signal phrase; `/forge`
85
+ stays the primary, explicit entry point.
32
86
 
33
- ## What it adds
87
+ ### Language & output
34
88
 
35
- ### SDD workflow (`prompts/`)
89
+ A `/forge` run reads as a short, calm progress stream, in Spanish:
36
90
 
37
- A spec-driven development pipeline driven through four phases, in order:
91
+ - **Language Boundary** — every user-facing message is in Spanish (Rioplatense
92
+ voseo); sub-agent briefs stay in English for token efficiency; identifiers
93
+ (verdicts, slugs, paths, model ids, commands) are kept verbatim.
94
+ - **Output Contract** — each phase reports a bounded summary
95
+ (`Estado` / `Resumen` / `Artefactos` / `Siguiente`), never free-form prose.
96
+ No raw tool output, file dumps, sub-agent listings, or triple-backtick code
97
+ fences reach the chat. The phase-start line names the model and provider the
98
+ phase runs on plus a brief gloss of what it does — so a slow phase reads as
99
+ working, not frozen. The run ends stating `verificado` or `no verificado`.
38
100
 
39
- 1. **explore** — investigate the codebase read-only; produce findings.
40
- 2. **plan** — write requirements, design, and an ordered task list.
41
- 3. **build** — implement the plan.
42
- 4. **veredicto** — review the build adversarially and record a verdict
43
- (`pasa`, `corregir`, or `replantear`).
101
+ ### Review Workload Forecast
44
102
 
45
- Run it with the `/forge <feature>` prompt. The orchestrator drives phase order
46
- and enforces a hard build/veredicto iteration cap. Each phase has its own prompt
47
- under `prompts/phases/` so it can be delegated to a dedicated sub-agent.
103
+ The `plan` phase keeps tasks reviewable. Every planned task carries a
104
+ `review: ~N changed lines` estimate, and `tasks.md` gains a `## Review Workload`
105
+ section with a bold run total. Tasks are sized against a fixed budget of
106
+ **400 changed lines per task** (borrowed from gentle-ai). A task over budget is
107
+ split; one that genuinely cannot be split stays whole and is recorded as an
108
+ over-budget exception with a reason.
48
109
 
49
- Besides the explicit `/forge` command, an SDD run can also be started from
50
- natural language: describe the work and signal SDD intent — e.g. "hacelo con
51
- sdd" or "usá el pipeline" — and the `sdd-routing` skill routes the request into
52
- `/forge` for you. It triggers only on a clear signal phrase and stays out of the
53
- way for ordinary requests; `/forge` remains the primary, explicit entry point.
110
+ ### SDD sub-agents — `sdd-agents.ts`
54
111
 
55
- **Review Workload Forecast** — the plan phase keeps tasks reviewable. Every
56
- planned task carries a `review: ~N changed lines` estimate, and `tasks.md` gains
57
- a `## Review Workload` section with the per-task estimates and a bold run total.
58
- Tasks are sized against a fixed budget of **400 changed lines per task** — an
59
- internal, non-configurable default (borrowed from gentle-ai), so "small task"
60
- means the same number on every run. A task whose estimate exceeds the budget is
61
- split into smaller, individually verifiable tasks; one that genuinely cannot be
62
- split stays whole and is recorded as an over-budget exception with a reason. The
63
- orchestrator's plan-phase summary reports the run total and any exceptions.
112
+ `pi-subagents` discovers agents from `~/.pi/agent/agents/**/*.md`, but a
113
+ `pi install` ships only the phase *prompts*. This extension closes the gap: on
114
+ every load it generates the four `zero-<phase>` agent files under
115
+ `~/.pi/agent/agents/zero/` from the package's phase prompts and the per-phase
116
+ models in `~/.pi/zero.json`, so they stay in sync with the prompts and with
117
+ `/zero-models`.
64
118
 
65
- ### Per-phase models (`/zero-models`)
119
+ ### Per-phase models — `/zero-models`
66
120
 
67
- `/zero-models` is a real pi command — a code handler, not an LLM prompt — for
68
- the SDD models. Run it with no argument for the interactive picker, or set one
121
+ A real pi command — a code handler, not an LLM prompt — for the SDD models. Run
122
+ it with no argument for the **provider-aware** interactive picker
123
+ (**phase → provider → model**, sourced from pi's model registry), or set one
69
124
  directly:
70
125
 
71
126
  ```
72
- /zero-models # interactive picker
73
- /zero-models build=claude-opus-4-7 # set one phase
74
- /zero-models build=codex/gpt-5-codex # set one phase with an explicit provider
127
+ /zero-models interactive picker
128
+ /zero-models build=claude-opus-4-7 set one phase
129
+ /zero-models build=codex/gpt-5-codex set one phase with an explicit provider
75
130
  ```
76
131
 
77
- The interactive picker is **provider-aware**: it reads pi's model registry, so
78
- the flow is **phase → provider → model** and every provider you have configured
79
- (anthropic, codex, opencode, …) and its models are offered — not a hardcoded
80
- list. An `— otro provider —` / `— otro modelo —` entry still lets you type
81
- anything by hand.
132
+ It reads and writes `~/.pi/zero.json` — a `models` map and a parallel
133
+ `providers` map. The orchestrator picks the change up on the next `/forge` run.
82
134
 
83
- It reads and writes `~/.pi/zero.json` — `models` (the per-phase model id) plus a
84
- parallel `providers` map. The orchestrator picks the change up on the next
85
- `/forge` run. The `zero` CLI also writes this file when it installs the layer.
135
+ ### Run memory — Cortex
86
136
 
87
- **Run memory** — every SDD run reads from and writes to Cortex (the memory MCP
88
- server). Before exploring, the orchestrator recalls prior `zero-run/*` traces
89
- for the feature; when the run ends it saves a run-trace — the final verdict, the
90
- correction rounds, and the gotchas — under `topic_key: zero-run/<slug>`. The
91
- next run on related work starts from what the last one learned. With `--no-mcp`
92
- the loop degrades silently.
137
+ Every run reads from and writes to Cortex, the persistent-memory MCP server.
138
+ Before exploring, the orchestrator recalls prior `zero-run/*` traces; when the
139
+ run ends it saves a run-trace — verdict, correction rounds, gotchas — under
140
+ `topic_key: zero-run/<slug>`. The next run starts from what the last one
141
+ learned. With `--no-mcp`, or when Cortex is unreachable, the loop degrades
142
+ silently and never blocks a run.
93
143
 
94
144
  ### Canonical specs & `/zero-sync`
95
145
 
96
146
  zero keeps a **canonical, project-wide spec store** that accumulates accepted
97
- requirements across runs, so each `/forge` run builds on the last instead of
98
- starting from a blank spec.
99
-
100
- **The canonical store — `.sdd/specs/requirements.md`.** A single flat markdown
101
- file: a `# ` title followed by `### REQ: <stable-unique-name>` requirement
102
- blocks. It is the project's source of truth. The `plan` phase reads it as the
103
- baseline; a fresh project has no store yet, and that absence simply means an
104
- empty store.
105
-
106
- **The granular plan artifacts.** Every run's `plan` phase writes four files
107
- into `.sdd/<slug>/`:
108
-
109
- - `proposal.md` — the change intent: scope and rationale, in prose.
110
- - `spec.md` — the **delta** against the canonical store, never a full spec. Up
111
- to three `H2` sections — `## ADDED`, `## MODIFIED`, `## REMOVED` — each
112
- holding `### REQ:` blocks. `## MODIFIED` carries the complete updated text of
113
- an existing block (not a diff); `## REMOVED` needs only the name line.
114
- - `design.md` — how it is built.
115
- - `tasks.md` — the ordered task list with its `## Review Workload` section.
116
-
117
- **`/zero-sync` — folding the delta into the store.** `/zero-sync <slug>` is a
118
- real pi command — a deterministic, unit-tested merge, not an LLM prompt — that
119
- reads the store and the run's delta `spec.md`, applies the ADDED/MODIFIED/REMOVED
120
- changes, and writes the store atomically. Guardrails reject a bad delta before
121
- anything is written: a duplicate name, an ADDED collision with an existing
122
- block, a MODIFIED or REMOVED of a missing block, or malformed input. On a
123
- guardrail failure it writes nothing and reports the offending requirement; the
124
- store is never left half-merged. After a `pasa` verdict the SDD orchestrator
125
- invokes `/zero-sync <slug>` automatically — a `corregir`, `replantear`, or
126
- cap-reached run never syncs.
127
-
128
- **The archive — `.sdd/archive/`.** Each successful sync appends a dated,
129
- slug-named entry `.sdd/archive/<YYYY-MM-DD>-<slug>/` containing a copy of the
130
- run's `proposal.md` and `spec.md` plus a `sync.md` report listing every added,
131
- modified, and removed requirement. The archive is append-only — a new entry
132
- never rewrites a prior one — so it is a full audit trail of how the canonical
133
- store evolved.
134
-
135
- ### Adaptive model profiles
136
-
137
- zero learns which model fits each SDD phase from your own run history and can
138
- re-tune `~/.pi/zero.json` for you.
139
-
140
- **The metrics log — `~/.pi/zero-runs.jsonl`.** Every completed SDD run appends
141
- one JSON line to this file: the feature slug, the per-phase models the run used,
142
- the final verdict, the build/veredicto round count, and the ordered per-round
143
- verdict sequence. It is append-only and never rewritten. This local log is the
144
- only thing zero learns from — a run abandoned before it reaches a verdict adds
145
- no line.
146
-
147
- **Phase attribution (v2).** The per-round verdict sequence makes blame precise:
148
- a `corregir` round re-runs — and so blames — the `build` phase, and a
149
- `replantear` round blames the `plan` phase. Autotune aggregates that sequence
150
- per phase and upgrades **only the phase at fault**, one tier at a time — a
151
- `build` problem no longer drags `plan` up with it. The `explore` and `veredicto`
152
- phases are never tuned.
153
-
154
- **Autotune modes.** At each pi session start zero aggregates the log and, once a
155
- phase has accumulated enough run data to cross a confidence threshold, decides
156
- whether that phase's model should change. Until a phase has accumulated enough
157
- v2 runs of its own, autotune deliberately stays quiet — a one-time, silent
158
- cold-start after upgrading, not a regression. The `autotune` mode in
159
- `~/.pi/zero.json` controls what happens next:
147
+ requirements across runs, so each `/forge` run builds on the last.
148
+
149
+ - **The store** — `.sdd/specs/requirements.md`: a `# ` title followed by
150
+ `### REQ: <name>` blocks. The `plan` phase reads it as the baseline.
151
+ - **The plan artifacts** — every run's `plan` phase writes `proposal.md`,
152
+ `spec.md` (the **delta**: `## ADDED` / `## MODIFIED` / `## REMOVED`),
153
+ `design.md`, and `tasks.md` into `.sdd/<slug>/`.
154
+ - **`/zero-sync <slug>`** — a deterministic, unit-tested merge that folds the
155
+ delta into the store atomically. Guardrails reject a bad delta before
156
+ anything is written. The orchestrator invokes it automatically after a `pasa`
157
+ verdict — never on `corregir`, `replantear`, or a cap-reached run.
158
+ - **The archive** — `.sdd/archive/<YYYY-MM-DD>-<slug>/`: an append-only audit
159
+ trail of every sync.
160
+
161
+ ### Adaptive model profiles — autotune
162
+
163
+ zero learns which model fits each SDD phase from your own run history.
164
+
165
+ - **The metrics log** — `~/.pi/zero-runs.jsonl`: every completed run appends one
166
+ JSON line (slug, per-phase models, verdict, round count, per-round verdict
167
+ sequence). Append-only.
168
+ - **Phase attribution** — a `corregir` round blames `build`, a `replantear`
169
+ blames `plan`. Autotune upgrades **only the phase at fault**, one tier at a
170
+ time. `explore` and `veredicto` are never tuned.
171
+ - **Cross-machine sync** — each run pushes its metrics to Cortex; `/forge`
172
+ pulls the shared log back, so autotune sees runs from other machines too.
173
+
174
+ The `autotune` mode in `~/.pi/zero.json` controls what happens:
160
175
 
161
176
  | Mode | Behaviour |
162
177
  | ---- | --------- |
163
- | `auto` _(default)_ | zero applies the adjustment to `~/.pi/zero.json` and notifies you exactly what changed. |
164
- | `ask` | zero records the recommendation but changes nothing — you apply it from `/zero-models`. |
165
- | `off` | zero still records run metrics, but never changes or recommends anything. |
178
+ | `auto` _(default)_ | Applies the adjustment to `~/.pi/zero.json` and notifies you what changed. |
179
+ | `ask` | Records the recommendation; you apply it from `/zero-models`. |
180
+ | `off` | Records run metrics, but never changes or recommends anything. |
166
181
 
167
- A change always takes effect on the *next* `/forge` run, and every applied
168
- change is announced — autotune is never silent.
182
+ Set it with `/zero-models autotune=<auto\|ask\|off>`. In `ask` mode a waiting
183
+ recommendation shows as a leading `★ aplicar sugerencia` entry in `/zero-models`.
169
184
 
170
- **Setting the mode.** Set it directly, or pick it from the interactive
171
- `/zero-models` menu (which shows the current mode as its own entry):
185
+ ### Skill auto-learning — `skill-loop`
172
186
 
173
- ```
174
- /zero-models autotune=ask # auto | ask | off
175
- ```
187
+ Gives the agent a closed learning loop — distill a reusable skill from a
188
+ substantial task, store it, surface relevant skills on a new task, refine an
189
+ existing skill instead of duplicating it — so solutions are reused, not
190
+ re-derived.
176
191
 
177
- **Applying a pending suggestion.** In `ask` mode, when a recommendation is
178
- waiting, running `/zero-models` shows a leading `★ aplicar sugerencia` entry;
179
- selecting it applies the change and clears the pending suggestion. Note that a
180
- pending suggestion is *refreshed* — an unactioned suggestion is overwritten by
181
- the next `ask`-mode session with fresher data, so `/zero-models` always reflects
182
- the most recent recommendation.
192
+ ---
183
193
 
184
- ### Skill auto-learning (`skills/`)
194
+ ## ✨ Quality-of-life extensions
185
195
 
186
- `skill-loop.md` gives the agent a closed learning loop so solutions are reused
187
- instead of re-derived.
196
+ ### Provider guard — `provider-guard.ts`
188
197
 
189
- ### ZERO terminal theme (`themes/zero-sdd.json`)
198
+ pi reaches the same Claude models through two providers: `pi-claude-cli` (billed
199
+ against your subscription's plan limits) and `anthropic` (the direct API, billed
200
+ per token from your metered extra-usage pool). The guard watches model switches:
201
+ on a deliberate switch to a metered provider it offers — via a confirmation
202
+ dialog — to redirect you to the equivalent model on `pi-claude-cli`. Say no and
203
+ you stay put, no nagging. Switching to a subscription provider is a no-op.
190
204
 
191
- `zero-pi` ships a Pi theme named `zero-sdd`: a dark, high-contrast terminal
192
- palette with cyan, amber, mint, rose, and violet accents tuned for SDD work.
193
- Select it from `/settings`, or set `"theme": "zero-sdd"` in Pi settings.
205
+ ### Startup banner — `startup-banner.ts`
194
206
 
195
- ### Startup banner (`extensions/startup-banner.ts`)
207
+ Renders the `ZERO` wordmark as ASCII-safe Tetris cells in pure ANSI 24-bit
208
+ colour, no runtime dependencies. The cells assemble from the bottom up, settle,
209
+ then run a short **sparkle pass** — a few cells glint bright for about a second.
210
+ The render runs synchronously before pi draws its UI.
196
211
 
197
- Renders the `ZERO` wordmark as ASCII-safe Tetris cells. In the default animated
198
- mode, the cells assemble from the bottom up when a pi session starts, then
199
- settle into the completed ZERO banner. Pure ANSI 24-bit colour, no runtime
200
- dependencies.
212
+ | `ZERO_BANNER` | Effect |
213
+ | ------------- | ------ |
214
+ | _(unset)_ / `shimmer` | Animated assembly + sparkle, then settle (default) |
215
+ | `static` | Completed banner only, no animation |
216
+ | `off` | Render nothing |
201
217
 
202
- The render runs synchronously before pi draws its UI, so the animation never
203
- fights pi's renderer.
218
+ Colour is skipped automatically when `NO_COLOR` is set or output is not a TTY.
204
219
 
205
- ### Working-phrase ticker (`extensions/working-phrases.ts`)
220
+ ### Working-phrase ticker — `working-phrases.ts`
206
221
 
207
- Pi shows a single static `Working...` line while the agent is busy. This
208
- extension replaces it with a context-aware, rotating phrase:
222
+ Replaces pi's static `Working...` line with a context-aware, rotating Spanish
223
+ phrase — tool-specific while a tool runs (`Leyendo archivos…`), the SDD phase
224
+ while a sub-agent runs (`Planeando la solución…`), playful verbs while the model
225
+ thinks (`Maquinando…`) — plus a theme-tinted braille spinner.
209
226
 
210
- - **While a tool runs** — a tool-specific line: `Leyendo archivos…`,
211
- `Ejecutando comandos…`, `Buscando en el código…`. MCP tools are named by
212
- server (`Consultando un MCP…`).
213
- - **While a zero sub-agent runs** — the SDD phase it owns:
214
- `Explorando el código…`, `Planeando la solución…`,
215
- `Construyendo la implementación…`, `Revisando el veredicto…`.
216
- - **While the model thinks** — a rotation of playful verbs (`Maquinando…`,
217
- `Rumiando…`, `Cocinando…`). Once a `/forge` run is detected the rotation
218
- biases toward SDD vocabulary.
227
+ ### Conversation resume — `conversation-resume.ts`
219
228
 
220
- It also installs a theme-tinted braille spinner that gently breathes through
221
- the palette's `dim`/`muted`/`accent` colours. The extension uses only pi's
222
- public extension API, and every handler is defensive — the indicator can never
223
- break a session.
229
+ When pi exits normally, writes a local handoff note at `.pi/zero-resume.md` —
230
+ the exact restore command for the persisted session plus a concise conversation
231
+ tail. Generate it any time with `/zero-resume`. zero-pi creates `.pi/.gitignore`
232
+ so conversation context is never committed. Set `ZERO_RESUME=off` to disable the
233
+ automatic write.
224
234
 
225
- Control it with the `ZERO_BANNER` environment variable:
235
+ ### Windows process-tree kill — `win-tree-kill.ts`
226
236
 
227
- | `ZERO_BANNER` | Effect |
228
- | ------------- | ------ |
229
- | _(unset)_ / `shimmer` | Animated Tetris assembly, then settle (default) |
230
- | `static` | Completed Tetris banner only, no animation |
231
- | `off` | Render nothing |
237
+ On Windows, `kill()` terminates only the target process — so aborting a turn can
238
+ leave an orphaned `claude` process streaming (Esc appears to do nothing). This
239
+ extension patches `child_process.spawn` so every later subprocess tree-kills via
240
+ `taskkill /T /F`. No-op on non-Windows. **Keep it enabled on Windows.**
232
241
 
233
- Colour is skipped automatically when `NO_COLOR` is set or the output is not a
234
- TTY.
242
+ ### ZERO terminal theme — `themes/zero-sdd.json`
235
243
 
236
- ### Provider guard (`extensions/provider-guard.ts`)
244
+ A dark, high-contrast pi theme with cyan, amber, mint, rose, and violet accents
245
+ tuned for SDD work. Select it from `/settings`, or set `"theme": "zero-sdd"`.
237
246
 
238
- zero-pi watches model switches and steps in when you move to a metered
239
- provider. When you switch to a model on the `anthropic` provider — which bills
240
- per token and draws down your metered extra-usage pool — the guard offers to
241
- redirect you to the equivalent model on `pi-claude-cli`, the provider backed by
242
- your subscription's limits.
247
+ ---
243
248
 
244
- The redirect is offered through a confirmation dialog, and that dialog is your
245
- escape hatch: say "yes" and the guard switches you to the subscription-backed
246
- equivalent; say "no" (or cancel) and you stay on the metered `anthropic`
247
- provider with no further nagging. When there is no equivalent model on
248
- `pi-claude-cli`, and when a model is restored on session start rather than
249
- switched deliberately, the guard skips the modal and just shows a one-line
250
- warning. Switching to a subscription provider is a complete no-op — no dialog,
251
- no notification, no noise.
249
+ ## ⌨️ Commands
252
250
 
253
- ### Conversation resume (`extensions/conversation-resume.ts`)
251
+ | Command | What it does |
252
+ | ------- | ------------ |
253
+ | `/forge <feature>` | Run the four-phase SDD pipeline for a feature. |
254
+ | `/forge --continue [slug]` | Resume an interrupted SDD run. |
255
+ | `/zero-models [<phase>=[<provider>/]<model>]` | Show or set the per-phase SDD models. |
256
+ | `/zero-models autotune=<auto\|ask\|off>` | Set the autotune mode. |
257
+ | `/zero-sync <slug>` | Fold a run's delta `spec.md` into the canonical store. |
258
+ | `/zero-resume` | Write `.pi/zero-resume.md` now. |
254
259
 
255
- When pi exits normally, zero-pi writes a local handoff note:
260
+ ## 🔧 Environment variables
256
261
 
257
- ```
258
- .pi/zero-resume.md
259
- ```
262
+ | Variable | Effect |
263
+ | -------- | ------ |
264
+ | `ZERO_BANNER` | `shimmer` (default) · `static` · `off` — startup-banner mode. |
265
+ | `ZERO_RESUME` | `off` / `0` disables the automatic conversation-resume write. |
266
+ | `NO_COLOR` | Standard — disables banner colour. |
260
267
 
261
- The note includes the exact restore command for the persisted pi session:
268
+ ## 📂 Files it reads & writes
262
269
 
263
- ```bash
264
- pi --session '<session-file>'
265
- ```
270
+ | Path | Role |
271
+ | ---- | ---- |
272
+ | `~/.pi/zero.json` | Per-phase `models` / `providers` and the `autotune` mode. |
273
+ | `~/.pi/zero-runs.jsonl` | Append-only run-metrics log autotune learns from. |
274
+ | `~/.pi/agent/agents/zero/` | Generated `zero-<phase>` sub-agent files. |
275
+ | `.sdd/<slug>/` | Per-run plan artifacts. |
276
+ | `.sdd/specs/requirements.md` | The canonical, project-wide spec store. |
277
+ | `.sdd/archive/` | Append-only audit trail of every `/zero-sync`. |
278
+ | `.pi/zero-resume.md` | Local session handoff note. |
266
279
 
267
- When a session id is available it also writes the shorter form:
280
+ ## 🔗 Relationship to `zero`
268
281
 
269
- ```bash
270
- pi --session <session-id>
271
- ```
282
+ `zero-pi` is the pi-specific layer of the **zero** integrator. The `zero` CLI
283
+ installs this layer onto pi (bootstrapping pi.dev itself when missing) and
284
+ writes the per-phase model configuration. You can also install `zero-pi`
285
+ directly with `pi install npm:@gonrocca/zero-pi` if you only want the pi layer.
272
286
 
273
- `pi --resume` is listed too for the interactive session picker. The file also
274
- keeps a concise conversation tail, enough to remember the last user intent and
275
- assistant progress without replacing pi's real session history.
287
+ ## 🧪 Development
276
288
 
277
- Generate it manually at any time:
289
+ Dependency-free, no build step — pi loads the TypeScript extensions directly.
290
+ Run the test suite with:
278
291
 
279
- ```text
280
- /zero-resume
292
+ ```
293
+ npm test
281
294
  ```
282
295
 
283
- The resume lives under `.pi/`, and zero-pi creates `.pi/.gitignore` so local
284
- conversation context is not accidentally committed.
285
-
286
- ## Relationship to `zero`
287
-
288
- `zero-pi` is the pi-specific layer of the **[zero](https://github.com/gonzalonicolasr/zero)**
289
- integrator. The `zero` CLI installs this layer onto pi (bootstrapping pi.dev
290
- itself when it is missing) and writes the per-phase model configuration. You
291
- can also install `zero-pi` directly with `pi install npm:@gonrocca/zero-pi` if
292
- you only want the pi layer.
296
+ ---
293
297
 
294
- ## License
298
+ <div align="center">
295
299
 
296
300
  MIT © Gonzalo Rocca
301
+
302
+ </div>
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@gonrocca/zero-pi",
3
- "version": "0.1.22",
3
+ "version": "0.1.24",
4
4
  "description": "zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow, skill auto-learning, and an animated ZERO startup banner. Adds capability to pi without modifying pi.",
5
5
  "type": "module",
6
6
  "keywords": [
@@ -67,11 +67,10 @@
67
67
  },
68
68
  "repository": {
69
69
  "type": "git",
70
- "url": "git+https://github.com/gonzalonicolasr/zero.git",
71
- "directory": "packages/zero-pi"
70
+ "url": "git+https://github.com/gonzalonicolasr/zero-pi.git"
72
71
  },
73
- "homepage": "https://github.com/gonzalonicolasr/zero/tree/main/packages/zero-pi#readme",
72
+ "homepage": "https://github.com/gonzalonicolasr/zero-pi#readme",
74
73
  "bugs": {
75
- "url": "https://github.com/gonzalonicolasr/zero/issues"
74
+ "url": "https://github.com/gonzalonicolasr/zero-pi/issues"
76
75
  }
77
76
  }