@gonrocca/zero-pi 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gonzalo Rocca
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# @gonrocca/zero-pi
+
+An installable layer for **[pi](https://pi.dev)** — it adds the zero
+spec-driven development workflow, skill auto-learning, and an animated `ZERO`
+startup banner **without modifying pi itself**.
+
+Same idea as `gentle-pi`: pi stays untouched; zero-pi is a package pi loads.
+
+## Install
+
+```bash
+pi install npm:@gonrocca/zero-pi
+```
+
+That registers zero-pi in `~/.pi/agent/settings.json` and makes its prompts,
+skills, and the startup-banner extension available in every pi session.
+
+To remove it:
+
+```bash
+pi remove npm:@gonrocca/zero-pi
+```
+
+## What it adds
+
+### SDD workflow (`prompts/`)
+
+A spec-driven development pipeline driven through four phases, in order:
+
+1. **explore** — investigate the codebase read-only; produce findings.
+2. **plan** — write requirements, design, and an ordered task list.
+3. **build** — implement the plan.
+4. **veredicto** — review the build adversarially and record a verdict
+   (`pasa`, `corregir`, or `replantear`).
+
+Run it with the `/forge` prompt. The orchestrator drives phase order and
+enforces a hard build/veredicto iteration cap. Each phase has its own prompt
+under `prompts/phases/` so it can be delegated to a dedicated sub-agent.
+
+Per-phase model assignments are read from `~/.pi/zero.json`, which the `zero`
+CLI writes when it installs this layer.
+
+### Skill auto-learning (`skills/`)
+
+`skill-loop.md` gives the agent a closed learning loop so solutions are reused
+instead of re-derived.
+
+### Startup banner (`extensions/startup-banner.ts`)
+
+Renders the `ZERO` wordmark in ANSI Shadow figlet style with a purple → amber
+shimmer sweep the moment a pi session starts, then settles into a static
+gradient glow. Pure ANSI 24-bit colour, no runtime dependencies.
+
+The render runs synchronously before pi draws its UI, so the animation never
+fights pi's renderer.
+
+Control it with the `ZERO_BANNER` environment variable:
+
+| `ZERO_BANNER` | Effect |
+| ------------- | ------ |
+| _(unset)_ / `shimmer` | Animated shimmer sweep, then settle (default) |
+| `static` | Settled gradient only, no animation |
+| `off` | Render nothing |
+
+Colour is skipped automatically when `NO_COLOR` is set or the output is not a
+TTY.
+
+## Relationship to `zero`
+
+`zero-pi` is the pi-specific layer of the **[zero](https://github.com/gonzalonicolasr/zero)**
+integrator. The `zero` CLI installs this layer onto pi (bootstrapping pi.dev
+itself when it is missing) and writes the per-phase model configuration. You
+can also install `zero-pi` directly with `pi install npm:@gonrocca/zero-pi` if
+you only want the pi layer.
+
+## License
+
+MIT © Gonzalo Rocca

package/extensions/startup-banner.ts

@@ -0,0 +1,268 @@
+// zero-pi — animated startup banner.
+//
+// A pi extension that renders the "ZERO" wordmark in ANSI Shadow figlet style
+// — heavy block glyphs with box-drawing trim for a chunky pixel-art feel — the
+// instant a pi session starts. A purple -> amber shimmer sweeps left -> right
+// once, then the glyphs settle into a static gradient glow.
+//
+// The render runs synchronously inside the extension's register() call, before
+// pi draws its interactive UI, so the animation never fights pi's renderer and
+// no extra dependency is needed. A banner failure is swallowed: it must never
+// break a pi session.
+//
+// Behaviour is controlled by the ZERO_BANNER environment variable:
+//   ZERO_BANNER=off        render nothing
+//   ZERO_BANNER=static     render the settled gradient, no animation
+//   (unset) / shimmer      render the animated shimmer sweep (default)
+//
+// Pure ANSI 24-bit colour, zero runtime dependencies.
+
+type RGB = [number, number, number];
+
+const COLORS: Record<string, RGB> = {
+  purpleDim: [82, 70, 124],
+  purpleMid: [157, 124, 216],
+  amber: [255, 180, 84],
+  peak: [255, 240, 210],
+};
+
+/** Number of rows in every glyph of the ANSI Shadow font. */
+const ROWS = 6;
+
+// The ANSI Shadow font, one entry per supported character. Each glyph is six
+// rows tall; widths vary per letter and the layout adds one space between
+// glyphs for breathing room.
+const FONT: Record<string, string[]> = {
+  Z: [
+    "███████╗",
+    "╚══███╔╝",
+    "  ███╔╝ ",
+    " ███╔╝  ",
+    "███████╗",
+    "╚══════╝",
+  ],
+  E: [
+    "███████╗",
+    "██╔════╝",
+    "█████╗  ",
+    "██╔══╝  ",
+    "███████╗",
+    "╚══════╝",
+  ],
+  R: [
+    "██████╗ ",
+    "██╔══██╗",
+    "██████╔╝",
+    "██╔══██╗",
+    "██║  ██║",
+    "╚═╝  ╚═╝",
+  ],
+  O: [
+    " ██████╗ ",
+    "██╔═══██╗",
+    "██║   ██║",
+    "██║   ██║",
+    "╚██████╔╝",
+    " ╚═════╝ ",
+  ],
+  P: [
+    "██████╗ ",
+    "██╔══██╗",
+    "██████╔╝",
+    "██╔═══╝ ",
+    "██║     ",
+    "╚═╝     ",
+  ],
+  I: [
+    "██╗",
+    "██║",
+    "██║",
+    "██║",
+    "██║",
+    "╚═╝",
+  ],
+  "-": [
+    "        ",
+    "        ",
+    " █████╗ ",
+    " ╚════╝ ",
+    "        ",
+    "        ",
+  ],
+  " ": ["  ", "  ", "  ", "  ", "  ", "  "],
+};
+
+/** Lay a word out as six text rows of ANSI Shadow glyphs. */
+export function bannerLines(text = "ZERO"): string[] {
+  const lines: string[] = Array.from({ length: ROWS }, () => "");
+  for (const ch of text) {
+    const glyph = FONT[ch.toUpperCase()] ?? FONT[" "];
+    for (let r = 0; r < ROWS; r++) {
+      lines[r] += glyph[r] + " ";
+    }
+  }
+  return lines;
+}
+
+function lerp(a: number, b: number, t: number): number {
+  return a + (b - a) * t;
+}
+
+function lerpColor(c1: RGB, c2: RGB, t: number): RGB {
+  const k = Math.max(0, Math.min(1, t));
+  return [
+    Math.round(lerp(c1[0], c2[0], k)),
+    Math.round(lerp(c1[1], c2[1], k)),
+    Math.round(lerp(c1[2], c2[2], k)),
+  ];
+}
+
+/**
+ * The colour of one glyph cell.
+ *
+ * When `spotlight` is null the banner is in its settled state: a subtle
+ * horizontal purple -> amber gradient with a top-to-bottom warmth bias so the
+ * lower rows glow like embers. Otherwise the cell's colour depends on its
+ * distance from the moving spotlight column.
+ */
+function colorAt(col: number, row: number, spotlight: number | null, width: number): RGB {
+  if (spotlight === null) {
+    const horizontal = col / Math.max(1, width - 1);
+    const vertical = row / (ROWS - 1);
+    const base = lerpColor(COLORS.purpleMid, COLORS.amber, horizontal * 0.55);
+    return lerpColor(base, COLORS.amber, vertical * 0.25);
+  }
+  const dx = Math.abs(col - spotlight);
+  if (dx < 1.5) return COLORS.peak;
+  if (dx < 4) return lerpColor(COLORS.peak, COLORS.amber, (dx - 1.5) / 2.5);
+  if (dx < 9) return lerpColor(COLORS.amber, COLORS.purpleMid, (dx - 4) / 5);
+  if (dx < 16) return lerpColor(COLORS.purpleMid, COLORS.purpleDim, (dx - 9) / 7);
+  return COLORS.purpleDim;
+}
+
+/** Paint one banner row with 24-bit ANSI colour, leaving spaces uncoloured. */
+function paintLine(line: string, row: number, spotlight: number | null, width: number): string {
+  let out = "";
+  let colored = false;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    if (ch === " ") {
+      if (colored) {
+        out += "\x1b[0m";
+        colored = false;
+      }
+      out += " ";
+      continue;
+    }
+    const [r, g, b] = colorAt(i, row, spotlight, width);
+    out += `\x1b[38;2;${r};${g};${b}m${ch}`;
+    colored = true;
+  }
+  if (colored) out += "\x1b[0m";
+  return out;
+}
+
+interface OutStream {
+  write(chunk: string): unknown;
+  isTTY?: boolean;
+}
+
+/** Whether colour output is appropriate for the given stream. */
+function shouldColor(stream: OutStream): boolean {
+  if (process.env.NO_COLOR) return false;
+  if (process.env.FORCE_COLOR) return true;
+  return Boolean(stream && stream.isTTY);
+}
+
+/** The three banner modes, resolved from the ZERO_BANNER environment variable. */
+export type BannerMode = "off" | "static" | "shimmer";
+
+/** Resolve the banner mode from an environment-variable value. */
+export function resolveBannerMode(raw: string | undefined): BannerMode {
+  const value = (raw ?? "").trim().toLowerCase();
+  if (value === "off" || value === "0" || value === "false" || value === "none") return "off";
+  if (value === "static" || value === "plain" || value === "no-animate") return "static";
+  return "shimmer";
+}
+
+// A synchronous millisecond sleep — Atomics.wait blocks the thread until the
+// timeout elapses (the value never changes). Used to pace animation frames
+// without making register() async, so the whole banner is drawn before pi's
+// UI takes over.
+const SLEEP_SLOT = new Int32Array(new SharedArrayBuffer(4));
+function sleepSync(ms: number): void {
+  if (ms > 0) Atomics.wait(SLEEP_SLOT, 0, 0, ms);
+}
+
+/** Options for {@link renderBanner}. */
+export interface RenderOptions {
+  mode?: BannerMode;
+  text?: string;
+  frames?: number;
+  frameMs?: number;
+  stream?: OutStream;
+}
+
+/**
+ * Render the ZERO banner synchronously.
+ *
+ * On a non-colour stream the banner is printed plain. Otherwise the shimmer
+ * sweep is animated frame by frame (mode `shimmer`) or skipped (mode `static`),
+ * settling on the static gradient either way.
+ */
+export function renderBanner(options: RenderOptions = {}): void {
+  const mode = options.mode ?? resolveBannerMode(process.env.ZERO_BANNER);
+  if (mode === "off") return;
+
+  const stream: OutStream = options.stream ?? process.stdout;
+  const lines = bannerLines(options.text ?? "ZERO");
+  const width = lines[0].length;
+
+  if (!shouldColor(stream)) {
+    stream.write("\n" + lines.join("\n") + "\n\n");
+    return;
+  }
+
+  // Reserve the vertical space the banner will occupy, then redraw in place.
+  stream.write("\n" + lines.map(() => "").join("\n") + "\n");
+
+  if (mode === "shimmer") {
+    const frames = Math.max(2, options.frames ?? 28);
+    const frameMs = Math.max(1, options.frameMs ?? 24);
+    const startCol = -10;
+    const endCol = width + 10;
+    for (let f = 0; f < frames; f++) {
+      const t = f / (frames - 1);
+      // ease-in-out so the sweep slows at the edges
+      const eased = t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+      const spotlight = startCol + (endCol - startCol) * eased;
+      stream.write(`\x1b[${ROWS}A\r`);
+      for (let r = 0; r < ROWS; r++) {
+        stream.write("\x1b[2K" + paintLine(lines[r], r, spotlight, width) + "\n");
+      }
+      sleepSync(frameMs);
+    }
+  }
+
+  // Settle on the static gradient.
+  stream.write(`\x1b[${ROWS}A\r`);
+  for (let r = 0; r < ROWS; r++) {
+    stream.write("\x1b[2K" + paintLine(lines[r], r, null, width) + "\n");
+  }
+  stream.write("\n");
+}
+
+/**
+ * The pi extension entry point.
+ *
+ * pi calls this once when the extension loads, before the interactive UI
+ * starts — exactly when the banner should be drawn. The `pi` argument is
+ * accepted for API compatibility but not needed: the banner is self-contained.
+ */
+export default function register(_pi?: unknown): void {
+  try {
+    renderBanner();
+  } catch {
+    // A banner failure must never break a pi session.
+  }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@gonrocca/zero-pi",
+  "version": "0.1.0",
+  "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.",
+  "type": "module",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "pi-extension",
+    "zero",
+    "sdd",
+    "spec-driven-development",
+    "ai-coding-agent"
+  ],
+  "pi": {
+    "prompts": [
+      "./prompts"
+    ],
+    "skills": [
+      "./skills"
+    ],
+    "extensions": [
+      "./extensions/startup-banner.ts"
+    ]
+  },
+  "files": [
+    "prompts",
+    "skills",
+    "extensions/startup-banner.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test --experimental-strip-types",
+    "prepublishOnly": "node --test --experimental-strip-types"
+  },
+  "engines": {
+    "node": ">=20.6.0"
+  },
+  "author": "Gonzalo Rocca",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gonzalonicolasr/zero.git",
+    "directory": "packages/zero-pi"
+  },
+  "homepage": "https://github.com/gonzalonicolasr/zero/tree/main/packages/zero-pi#readme",
+  "bugs": {
+    "url": "https://github.com/gonzalonicolasr/zero/issues"
+  }
+}

package/prompts/forge.md

@@ -0,0 +1,20 @@
+---
+description: Run an automatic spec-driven development pipeline for a feature request
+---
+
+Run the zero SDD pipeline for the feature request in the arguments.
+
+Follow the zero SDD orchestrator instructions: drive the run through the
+explore → plan → build → veredicto phases, honour the build/veredicto iteration
+cap, and use the execution mode (interactive or automatic) the user chose.
+
+Delegate each phase to its dedicated sub-agent so the phase runs on the model
+it is configured for: `zero-explore`, `zero-plan`, `zero-build`, and
+`zero-veredicto`. You stay the orchestrator — you decide phase order and count
+the rounds; the sub-agents only execute their phase.
+
+In interactive mode, pause after each phase with a summary and ask before
+continuing. Never report success unless the veredicto phase returned a `pasa`
+verdict; if the cap is reached first, report that the result is not verified.
+
+Feature request: $ARGUMENTS

package/prompts/orchestrator.md

@@ -0,0 +1,58 @@
+# zero — SDD Orchestrator
+
+You are the orchestrator of a spec-driven development (SDD) run. You COORDINATE
+the work; you decide what runs next — never let the loop drift on the model's
+whim. Drive the run through four phases, in order:
+
+1. **explore** — investigate the codebase read-only; produce findings.
+2. **plan** — write a plan: requirements, design, and an ordered task list.
+3. **build** — implement the plan.
+4. **veredicto** — review the build adversarially with a fresh perspective and
+   record a verdict: `pasa`, `corregir`, or `replantear`.
+
+## Phase order and the iteration cap
+
+- A `pasa` verdict finishes the run successfully.
+- A `corregir` verdict re-runs **build**.
+- A `replantear` verdict re-runs **plan**, then **build**.
+- Count every build/veredicto round. There is a hard **cap** on rounds. When
+  the cap is reached without a `pasa` verdict, STOP. Report that the result is
+  **not verified** — do **not** claim success.
+
+The orchestrator code controls phase order and the round count. The cap is not
+optional and the model does not get to extend it.
+
+## Sub-agent delegation
+
+Each phase runs as its own sub-agent — `zero-explore`, `zero-plan`,
+`zero-build`, `zero-veredicto` — so every phase executes on the model it is
+configured for: a cheaper model for exploration, a stronger model for planning
+and the adversarial veredicto. Delegate each phase to its sub-agent and wait
+for its result. The orchestrator keeps control of phase order and the round
+count — the sub-agents only carry out their own phase.
+
+## Model configuration
+
+The per-phase model assignments live in `~/.pi/zero.json` under `models`
+(keys: `explore`, `plan`, `build`, `veredicto`). Read that file at the start of
+a run and delegate each phase's sub-agent to the model listed there. When the
+file is absent or a phase is missing, fall back to the session's default model.
+
+## Execution mode
+
+At the start of a run, ask the user which mode they want:
+
+- **interactive** (default): after each phase, show a concise summary of what
+  the phase produced and what the next phase will do, then ask
+  "¿Continuamos? / Continue?" before proceeding. Accept continue, stop, or
+  feedback to adjust.
+- **automatic**: run all phases back to back without pausing; show the final
+  result only.
+
+Cache the mode for the run.
+
+## Visibility
+
+While a phase runs, keep the user informed of progress — never run silently for
+a long stretch. The user must always be able to tell which phase and round the
+run is in.

package/prompts/phases/build.md

@@ -0,0 +1,11 @@
+---
+description: SDD build phase — implement the planned tasks, test-first, and make the suite pass
+---
+
+You run the **build** phase of a zero SDD pipeline.
+
+Implement the planned tasks in order, test-first where practical. Keep every
+change within the plan's scope — do not expand it on your own initiative.
+
+Run the test suite and make it pass before reporting the phase complete. Report
+what you changed so the veredicto phase has something concrete to review.

package/prompts/phases/explore.md

@@ -0,0 +1,12 @@
+---
+description: SDD explore phase — investigate the codebase read-only and produce findings
+---
+
+You run the **explore** phase of a zero SDD pipeline.
+
+Investigate the codebase and the feature request read-only. Do not modify any
+files. Map the relevant modules, the existing patterns and conventions, the
+integration points, and the constraints. Identify the risks and the unknowns.
+
+Produce a concise findings report the **plan** phase can build on: what exists,
+what is relevant to the request, and what to watch out for.

package/prompts/phases/plan.md

@@ -0,0 +1,13 @@
+---
+description: SDD plan phase — turn findings into requirements, design, and an ordered task list
+---
+
+You run the **plan** phase of a zero SDD pipeline.
+
+Using the explore findings, write the plan: the requirements (what must be
+true), the design (how it will be built), and an ordered list of small,
+independently verifiable tasks.
+
+Do not write implementation code in this phase — only the plan. Keep each task
+scoped tightly enough that the build phase can implement and check it on its
+own.

package/prompts/phases/veredicto.md

@@ -0,0 +1,17 @@
+---
+description: SDD veredicto phase — adversarially review the build and record a verdict
+---
+
+You run the **veredicto** phase of a zero SDD pipeline.
+
+Review the build adversarially, with a fresh perspective. Check it against the
+plan's requirements, run the tests yourself, and look for gaps, regressions,
+and unmet acceptance criteria.
+
+Record exactly one verdict:
+
+- `pasa` — the build meets the plan; the run finishes successfully.
+- `corregir` — fixable defects remain; the build phase must re-run.
+- `replantear` — the plan itself is wrong; the plan phase must re-run.
+
+Never return `pasa` unless the evidence supports it.

package/skills/skill-loop.md

@@ -0,0 +1,28 @@
+# zero — Skill Auto-Learning
+
+zero gives the agent a closed learning loop so solutions are reused, not
+re-derived.
+
+## Distill
+
+When a substantial task completes, **distill** a reusable skill from it: capture
+the solution pattern, the ordered steps, and the non-obvious gotchas into a
+single skill document. If the task did only routine or one-off work with no
+reusable pattern, do not create a skill.
+
+## Store
+
+Store each learned skill in the per-user skill library so it persists across
+sessions and is available to every agent zero has configured.
+
+## Surface
+
+When a new task begins, surface the stored skills relevant to it — match by the
+skill's subject and description — so the agent consults a known solution before
+re-deriving one. Surface nothing when no stored skill is relevant.
+
+## Refine
+
+When a run re-applies an existing skill, **refine** that skill rather than
+create a duplicate: merge new gotchas and steps without repeating what is
+already there, and prefer the newer learning when it contradicts the old.