@gonrocca/zero-pi
zero-pi — an installable layer for pi (pi.dev): the zero spec-driven development workflow (clarify → explore → plan → analyze → build → veredicto) with automatic clarify/analyze gates, per-phase model autotune, and token-efficient batched builds. Adds cap
Package details
Install @gonrocca/zero-pi from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@gonrocca/zero-pi- Package
@gonrocca/zero-pi- Version
0.1.93- Published
- Nov 14, 2026
- Downloads
- 589/mo · 268/wk
- Author
- gonrocca
- License
- MIT
- Types
- extension, skill, theme, prompt
- Size
- 683.6 KB
- Dependencies
- 0 dependencies · 0 peers
Pi manifest JSON
{
"image": "https://raw.githubusercontent.com/gonzalonicolasr/zero-pi/main/assets/preview.png",
"skills": [
"./skills"
],
"themes": [
"./themes"
],
"prompts": [
"./prompts"
],
"extensions": [
"./extensions/zero-banner.ts",
"./extensions/zero-hud.ts",
"./extensions/zero-theme.ts",
"./extensions/zero-pretty-code-fences.ts",
"./extensions/zero-pretty-input-box.ts",
"./extensions/zero-pretty-tool-cards.ts",
"./extensions/zero-activity-panel.ts",
"./extensions/working-phrases.ts",
"./extensions/win-tree-kill.ts",
"./extensions/sdd-agents.ts",
"./extensions/conversation-resume.ts",
"./extensions/zero-models.ts",
"./extensions/autotune-extension.ts",
"./extensions/spec-merge-extension.ts",
"./extensions/zero-validate-extension.ts",
"./extensions/zero-status-extension.ts",
"./extensions/zero-doctor-extension.ts",
"./extensions/zero-cost-extension.ts",
"./extensions/zero-execution-extension.ts",
"./extensions/zero-checkpoint-extension.ts",
"./extensions/zero-rounds-extension.ts",
"./extensions/zero-pr-extension.ts",
"./extensions/zero-branch-extension.ts",
"./extensions/zero-git-validate-extension.ts",
"./extensions/zero-archive-extension.ts",
"./extensions/zero-issue-extension.ts",
"./extensions/zero-diff-extension.ts",
"./extensions/provider-guard-extension.ts",
"./extensions/scan-guard-extension.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
███████╗ ███████╗ ██████╗ ██████╗ ██████╗ ██╗
╚══███╔╝ ██╔════╝ ██╔══██╗ ██╔═══██╗ ██╔══██╗ ██║
███╔╝ █████╗ ██████╔╝ ██║ ██║ █████╗ ██████╔╝ ██║
███╔╝ ██╔══╝ ██╔══██╗ ██║ ██║ ╚════╝ ██╔═══╝ ██║
███████╗ ███████╗ ██║ ██║ ╚██████╔╝ ██║ ██║
╚══════╝ ╚══════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝
@gonrocca/zero-pi
The zero spec-driven development workflow, packaged for pi.
zero-pi is a package for pi that adds /forge: one command
that takes a feature through a spec-driven pipeline, one sub-agent per phase,
with a model and thinking level you choose for each phase. pi stays untouched.
clarify ─► explore ─► plan ─► analyze ─► build ─► veredicto ─► pasa (done)
▲ │ ▲ │
└─ replan ┘ └─corregir─┤
▲ │
└───────── replantear ──────────┘
pi install npm:@gonrocca/zero-pi
pi install npm:pi-subagents # required: every phase runs as a sub-agent
# restart pi, then inside pi:
/forge add a dark-mode toggle to the settings page
Install
Needs Node ≥ 20.6 and pi. Install both packages as above and restart pi so
it regenerates the zero-* phase agents (do it again after every upgrade).
Then run /zero-doctor. It checks pi-subagents, generated agents, model
config and gh auth before you spend tokens.
Quick use
/forge <feature>. It asks for interactive or automatic mode, then runs the phases. The run is in Spanish and prints one short summary per phase.- In interactive mode it pauses after each phase for your approval.
- At the end it prints a cost table and, if the verdict is
pasa, asks you to run/zero-archive <slug>. /forge --continue [slug]resumes an interrupted run.
You can also write "hacelo con sdd" in a normal message: the sdd-routing
skill sends it to /forge.
Phases
| Phase | Does |
|---|---|
| clarify | Records assumptions; stops only on blocking ambiguity. |
| explore | Reads the codebase (read-only) and writes findings. |
| plan | Writes requirements, design and an ordered task list. |
| analyze | Checks the plan after /zero-validate: continue or replan. |
| build | Implements the plan, test-first (strict TDD when a test runner exists). |
| veredicto | Reviews adversarially: pasa, corregir (back to build) or replantear (back to plan). |
Clarify and analyze run on their own. A run that reaches the round cap (3 by
default) without a pasa is reported as not verified. Everything lands in
.sdd/<slug>/ (clarifications.md, findings.md, spec.md, design.md,
tasks.md, checklist.md, ...). Details: docs/forge-pipeline.md.
Models and profiles
Each phase has its own model, provider and thinking level. Without config, the defaults are: Haiku 4.5 for clarify/explore, Opus 4.8 for plan/analyze/veredicto, Sonnet 4.6 for build. A profile is a named setup you can switch.
/zero-models # picker (the main screen is the profile list)
/zero-models build=anthropic/claude-sonnet-4-6 thinking=high
/zero-models profile new barato # snapshot current setup and activate it
/zero-models profile use premium # switch, then restart pi
| Profile command | Does |
|---|---|
profile list |
List profiles (* marks the active one). |
profile new <name> [from <other>] |
Create and activate (from the current setup, or a clone). |
profile use <name> |
Activate. Restart pi afterwards. |
profile save [<name>] |
Save the current setup under <name> (create or update) and activate it. No name: update the active profile, e.g. to keep autotune changes. |
profile delete <name> |
Delete. |
zero-pi ships no ready-made profiles; you create them. More: docs/models-and-profiles.md.
Commands
| Command | Does |
|---|---|
/forge <feature> |
Run the pipeline. --continue [slug] resumes. |
/zero-models ... |
Show or set models, thinking and profiles. |
/zero-doctor |
Preflight checks. |
/zero-status |
State of every run in .sdd/. |
/zero-validate <slug> |
Validate a run's plan artifacts. |
/zero-cost [<runId>|<slug>] |
Token and USD usage of a run's sub-agents. |
/zero-checkpoint [<slug>] |
Patch checkpoint before risky build batches. |
/zero-rounds [status|record|reset] |
Build/veredicto round ledger. |
/zero-branch, /zero-issue, /zero-pr, /zero-git-validate <slug> |
Git branch, GitHub issue and PR for a run. |
/zero-sync, /zero-diff, /zero-archive <slug> |
Merge a run's spec into .sdd/specs/ and archive it. |
/zero-hud, /zero-theme |
Footer preset and theme. |
/zero-resume |
Write the session handoff note now. |
All flags and arguments: docs/commands.md.
Configuration
| Where | What |
|---|---|
~/.pi/zero.json |
Per-phase models, providers, thinking, autotune, profiles. |
.sdd/config.json |
Per project: git, tdd.mode (strict or off), rounds.cap. |
ZERO_HUD_PRESET, ZERO_HEADER=off, ZERO_RESUME=off |
HUD preset, startup banner, resume note. |
Example .sdd/config.json to turn TDD off:
{ "tdd": { "mode": "off" } }
Full reference: docs/configuration.md.
Common problems
| Problem | Fix |
|---|---|
/forge does nothing useful or phases fail to launch |
Run /zero-doctor. The usual cause is a missing pi-subagents. |
| Model or profile change has no effect | Restart pi: the zero-* agents are regenerated when pi loads. |
/zero-models build=... is rejected |
The provider/model is unknown or ambiguous in pi's registry. Use provider/model. |
/zero-archive or /zero-branch says the worktree is dirty |
Commit first, or pass --allow-dirty. |
/zero-pr, /zero-issue fail |
Install gh and run gh auth login. |
/zero-pr refuses to run |
The run's latest verdict is not pasa. |
| Visuals look stale after an upgrade | /reload, or restart pi. |
| Run stopped as "not verified" | The round cap or the second analyze replan was hit. Read .sdd/<slug>/ and re-run /forge. |
More docs
- docs/forge-pipeline.md: gates, verdicts, caps, TDD, how phases launch.
- docs/models-and-profiles.md: defaults, thinking, profiles, autotune.
- docs/configuration.md: config files and environment variables.
- docs/commands.md: every command with its flags.
- docs/git-pr-issues.md: branch, issue, PR, archive, spec deltas.
- docs/features.md: everything else it adds, HUD, activity panel, themes.
- docs/token-efficiency.md: cost accounting and token limits.
- docs/forge-contract.md:
.sdd/<slug>/contract shared with the Claude Code forge mod. - docs/related-projects.md: zero or NODD, the
zeroCLI. - docs/development.md: tests and release checks.
- CHANGELOG.md and TOKEN-EFFICIENCY.md (historical audit).
License
MIT © Gonzalo Rocca · github.com/gonzalonicolasr/zero-pi
