# @gonrocca/zero-pi
**The zero spec-driven development workflow, packaged for [pi](https://pi.dev).**
[](https://www.npmjs.com/package/@gonrocca/zero-pi) [](https://github.com/gonzalonicolasr/zero-pi) [](https://discord.gg/aNFCZBZVT3) [](./LICENSE) [](https://nodejs.org)
### 💬 Join the community
Questions, ideas, or want to debate workflow design? Come hang out:
[](https://discord.gg/aNFCZBZVT3)
---
zero-pi is an installable **[pi](https://pi.dev)** package that adds a
disciplined spec-driven development pipeline — plus a handful of quality-of-life
extensions — **without modifying pi**. Same idea as `gentle-pi`: pi stays
untouched; zero-pi is a package it loads.
## 📦 Install
```
pi install npm:@gonrocca/zero-pi
pi install npm:pi-subagents # required — the pipeline delegates to sub-agents
```
Needs Node ≥ 20.6. Restart pi after an install or upgrade so pi regenerates
the `zero-*` phase agents.
### Quick start
1. Run `/zero-doctor` to catch missing `pi-subagents`, stale generated agents,
invalid model config, or GitHub CLI auth before spending tokens.
2. Run `/zero-models` (or set direct assignments) when you want a different
model/thinking profile per phase; otherwise the package defaults are used.
3. Run `/forge ` and let the automatic gates drive the flow.
4. Read the final cost table: `/forge` invokes `/zero-cost ` automatically
at the end. Re-run `/zero-cost [slug]` manually only when you want to inspect
an older run or debug missing metadata.
## 🛠 `/forge` — the SDD pipeline
The core of zero-pi. Run **`/forge `** and the orchestrator drives the
work through six phases — the automatic
**clarify → explore → plan → analyze → build → veredicto** flow — each delegated
to its own sub-agent:
| Phase | Does |
| ----- | ---- |
| **clarify** | Record de-risking assumptions before exploration; stop only on blocking ambiguity. |
| **explore** | Investigate the codebase read-only; produce findings. |
| **plan** | Write requirements, design, and an ordered task list. |
| **analyze** | Review plan readiness after `/zero-validate`; decide continue or replan. |
| **build** | Implement the plan. |
| **veredicto** | Review it adversarially and record a verdict. |
Each run keeps its paper trail under `.sdd//`: `clarifications.md`,
`findings.md`, `proposal.md`, `spec.md`, `design.md`, `tasks.md`,
`checklist.md`, and (when Strict TDD engages) `tdd-evidence.md`.
The **clarify** and **analyze** gates are automatic inside `/forge` — no extra
slash command in the normal flow. `clarify` writes `.sdd//clarifications.md`
and asks only when proceeding would risk the wrong product; `analyze` writes
`.sdd//checklist.md` after the structural `/zero-validate` gate and returns
`continue` (build) or `replan` (re-run plan with concrete defects). Neither gate
counts as a build/veredicto round.
The verdict is `pasa` (done), `corregir` (re-run build), or `replantear`
(re-run plan). A hard iteration cap bounds the build↔veredicto loop — reached
without a `pasa`, the run stops and is reported as **not verified**.
`/forge --continue [slug]` resumes an interrupted run.
**Build runs test-first.** By default the build phase follows a strict TDD
cycle — RED → GREEN → TRIANGULATE → REFACTOR — and records a **TDD Cycle
Evidence** table; veredicto audits that evidence (tests exist, are really green,
assertions verify real behavior) and returns `corregir` if the discipline
slipped. It engages only when a test runner exists and the change touches code,
so docs/config-only work degrades gracefully. Opt a project out with
`tdd.mode: "off"` in `.sdd/config.json` (see *Configuration*).
The run speaks **Spanish**, in a bounded, low-noise format — one short summary
per phase, naming the model that phase runs on, no raw tool output. Or just
describe the work and say "hacelo con sdd": the `sdd-routing` skill routes it
into `/forge` for you.
## ✨ What else it adds
| Feature | What it does |
| ------- | ------------ |
| **Strict TDD** | The build phase drives RED → GREEN → TRIANGULATE → REFACTOR with a TDD Cycle Evidence table; veredicto audits it. On by default, runtime-gated on a test runner; `tdd.mode: "off"` disables it. |
| **`/zero-models`** | Pick the model + provider + thinking level for each of the six SDD phases — a boxed-window picker, or set one directly. Direct assignments are validated against pi's model registry when available. |
| **Phase tool gating** | Generated `zero-*` sub-agents get phase-specific tool allowlists: explore/veredicto are read-only, clarify/analyze/plan write only `.sdd` artifacts, build edits code. |
| **Dependency-aware tasks** | `tasks.md` is validated as a task graph with mandatory `depends:` edges, topological ordering, and review workload totals. |
| **Autotune** | Learns which model fits each phase from your run history and re-tunes itself; optional `autotuneBudget.maxPhaseCostUsd` suppresses costly step-ups. |
| **`/zero-doctor`** | Preflight diagnostics for zero-pi: package install, Node version, pi-subagents, generated phase agents, model config, `.sdd/config`, run history, git, and `gh` auth. |
| **`/zero-cost`** | Aggregates a run's sub-agent `meta.json` files into a per-phase token/cost/duration report — `/forge` invokes it automatically at the end; manual re-run stays available for older runs/debug. |
| **`/zero-checkpoint`** | Writes patch-based worktree checkpoints under `.sdd//checkpoints/` before risky build batches. |
| **`/zero-sync` / `/zero-archive`** | Folds each run's spec delta into a canonical, project-wide spec store and archives approved runs. |
| **Git / PR / Issues** | `/zero-branch`, `/zero-git-validate`, `/zero-pr`, and `/zero-issue` keep branches and GitHub links audit-ready. |
| **Run memory** | Every run recalls and saves traces to Cortex, so runs learn from each other. |
| **Provider guard** | Warns when the `anthropic` provider runs on a metered API key instead of your subscription. |
| **Startup banner** | The sunset ANSI-Shadow `ZERO` wordmark, drawn once at pi startup — `ZERO_HEADER=off` to disable. |
| **ZERO HUD** | OMP-inspired segmented footer for SDD work: phase, model, tokens, cache, cost, diff, context %, and branch. Switch presets with `/zero-hud compact\|minimal\|full\|ascii\|off` or `ZERO_HUD_PRESET`. |
| **Pretty input box** | OMP-style prompt chrome with rounded corners, side borders, ZERO chips, and compact keyboard hints. |
| **Pretty code fences** | Markdown code blocks render as bordered panels with language badges instead of raw ```txt / ```json fence lines. |
| **Live activity panel** | Shows `/forge` phase progress and recent tool cards above the prompt while work is running. |
| **Working-phrase ticker** | Swaps pi's static `Working...` / `Procesando...` for a large pool of context-aware Spanish/ZERO/SDD phrases + spinner. |
| **Conversation resume** | Writes `.pi/zero-resume.md` on exit — the restore command + a conversation tail. |
| **Windows tree-kill** | Aborting a turn kills the whole process tree — no orphaned `claude`. |
| **SDD routing skill** | Natural-language requests that say "hacelo con sdd" route into `/forge` without remembering the slash command. |
| **`zero-sdd` theme** | A dark, high-contrast pi theme tuned for SDD work. |
| **`zero-sunset` theme** | A warm sunset variant — gold/coral/magenta accents over warm-dark panels, with one cool tone kept for syntax legibility. Activate with `/theme zero-sunset`. |
| **`zero-omp-neon` theme** | A high-contrast OMP-inspired neon theme with separated colour roles: cyan links/paths, gold titles, mint code/success, violet borders, and navy tool cards. Activate with `/theme zero-omp-neon`. |
| **ZERO theme pack** | Extra visual variants: `zero-sith`, `zero-saiyan`, `zero-matrix`, and `zero-cyberpunk`. Switch quickly with `/zero-theme sith|saiyan|matrix|cyberpunk`. |
## ⌨️ Commands
| Command | Does |
| ------- | ---- |
| `/forge ` | Run the SDD pipeline — `--continue [slug]` resumes. |
| `/zero-models [=[/] [thinking=]]` | Show or set per-phase models, providers, and thinking — `thinking=` (`off\|minimal\|low\|medium\|high\|xhigh`); `autotune=auto\|ask\|off`. Direct assignments fail fast when pi's registry says the provider/model is unknown or ambiguous. |
| `/zero-doctor` | Run zero-pi preflight diagnostics: package, Node, pi-subagents, generated agents/support modules, model config, `.sdd/config`, run history, git, and `gh`. |
| `/zero-sync ` | Fold a run's spec delta into the canonical spec store; a first all-`## ADDED` delta creates the store lazily. |
| `/zero-archive ` | Merge an approved run into `.sdd/specs/`, move it to `.sdd/archive/YYYY-MM-DD-/`, and persist `archivePath`. |
| `/zero-validate ` | Validate proposal/spec/design/tasks artifacts, including task schema and per-domain specs. |
| `/zero-status` | Show each `.sdd/` run's artifact, sync, latest-verdict, and GitHub-link status. |
| `/zero-hud [compact\|minimal\|full\|ascii\|off\|on\|preview]` | Preview or switch the segmented ZERO footer for this pi session. Default preset: `compact`. |
| `/zero-theme [neon\|sunset\|sdd\|sith\|saiyan\|matrix\|cyberpunk]` | Switch between packaged ZERO theme variants without remembering full `zero-*` names. |
| `/zero-cost []` | Report tokens (in/out/cache), USD cost, duration, and tool-count per SDD phase for a run — reads native pi session metas and project-local `.pi-subagents/artifacts`; `` for a specific run, no argument for the most recent. |
| `/zero-checkpoint [] [--json]` | Save `diff.patch`, `status.txt`, `head.txt`, `meta.json`, and a review-before-running `restore.sh` under `.sdd//checkpoints//`. |
| `/zero-branch ` | Create/reuse the configured SDD Git branch and persist `branch`/`baseBranch`. |
| `/zero-git-validate ` | Check worktree, branch, remote, `gh auth`, and verdict gating before PR/archive. |
| `/zero-pr ` | Create an audit-ready GitHub PR from a run that already has verdict `pasa`. |
| `/zero-issue ` | Create or reuse a GitHub issue for a run and persist the link. |
| `/zero-diff ` | Preview the logical spec-store merge without writing files. |
| `/zero-resume` | Write the session handoff note now. |
## 🎛️ Visual chrome: HUD, activity panel, prompt box
zero-pi ships several visual extensions. They are related, but each one owns a different part of pi's TUI:
| Surface | File | Where it appears | Purpose |
| ------- | ---- | ---------------- | ------- |
| **ZERO HUD** | `extensions/zero-hud.ts` | Footer/status line at the bottom | Persistent model/tokens/cost/diff/context/branch telemetry. |
| **Activity panel** | `extensions/zero-activity-panel.ts` | Widget above the prompt while work is running | Live `/forge` phase progress plus recent tool cards. |
| **Tool cards** | `extensions/zero-pretty-tool-cards.ts` | Each tool execution/result in chat | ZERO-styled bordered cards with status glyphs, title metadata, and padded content. |
| **Prompt box** | `extensions/zero-pretty-input-box.ts` | The input/editor box | OMP-like rounded box with ZERO chips and key hints. |
| **Code fences** | `extensions/zero-pretty-code-fences.ts` | Markdown code blocks in chat | Bordered panels with language badges instead of raw ```txt / ```json lines. |
| **Working phrases** | `extensions/working-phrases.ts` | Tiny loading row (`Procesando… (esc)`) | Rotating ZERO/SDD/Star Wars/DBZ phrases and themed spinner. |
### ZERO HUD presets
The HUD is the **bottom footer**. It is not the activity panel. Control it with:
```txt
/zero-hud preview
/zero-hud compact
/zero-hud minimal
/zero-hud full
/zero-hud ascii
/zero-hud off
/zero-hud on
```
Example compact HUD:
```txt
ZERO ▸ gpt-5.5 ▸ tok ↑1.1M ↓42K ▸ cost $16.22 ▸ diff +0/-0 ▸ ctx 11%
```
Startup preset can be set with:
```bash
ZERO_HUD_PRESET=full pi
```
Supported presets: `compact` (default), `minimal`, `full`, `ascii`, `off`.
### Activity panel vs HUD
During `/forge`, the activity panel appears **above the prompt** and summarizes the live run:
```txt
╭─ ZERO activity ───────────────────────────────────────────────────────╮
│ SDD ✓ clarify › ✓ explore › ⠋ plan › · analyze › · build › · veredicto
│ Tools ⠋ subagent · ✓ read zero-hud.ts · ✓ bash npm test
╰────────────────────────────────────────────────────────────────────────╯
```
The activity panel is transient: it clears after the agent finishes. The HUD stays in the footer across normal work.
### Applying visual changes after install
After `pi install npm:@gonrocca/zero-pi@`, reload the active session:
```txt
/reload
```
If a visual monkeypatch was already loaded in the current process, restarting pi is the safest way to force all visual extensions to reinitialize.
### Git / PR / Issues
Recommended flow: `/zero-branch ` → `/zero-issue ` → `/forge ` (the orchestrator validates plan artifacts and can create `/zero-checkpoint` before build) → `/zero-git-validate --for=pr` → `/zero-pr ` → `/zero-archive `.
`links.json` is forward-compatible and may contain:
```json
{
"issueNumber": 12,
"issueUrl": "https://github.com/org/repo/issues/12",
"branch": "sdd/my-feature",
"baseBranch": "main",
"prNumber": 34,
"prUrl": "https://github.com/org/repo/pull/34",
"archivePath": ".sdd/archive/2026-05-24-my-feature"
}
```
`/zero-branch ` uses `.sdd/config.json` when present:
```json
{ "git": { "branchPrefix": "sdd/", "numbering": false, "autoCommit": false, "commitStyle": "conventional", "baseBranch": "main" } }
```
`/zero-pr ` builds a PR title/body from `.sdd//proposal.md`,
`spec.md`, `design.md`, and `tasks.md`, then saves the returned `prNumber` and
`prUrl` into `.sdd//links.json`. It only runs after the run's latest
recorded verdict is `pasa`; if an issue was already linked, the PR body includes
`Closes #N`.
`/zero-issue ` searches open GitHub issues for the exact normalized title
before creating a new one, then saves `issueNumber` and `issueUrl` in the same
`links.json`. Both commands require the `gh` CLI to be installed and
authenticated (`gh auth login`). `--type=