@juicesharp/rpiv-pi

Turn "build this feature" into a run of named stages — discover → research → design → plan → implement → validate → code-review → commit — each one writing a reviewable Markdown artifact under .rpiv/artifacts/ that the next stage consumes. rpiv-pi adds 27 skills, 15 specialist subagents, and three ready-made /wf pipelines to Pi Agent, and runs every stage in a detached child session you watch from a lane dock below your editor. It is for developers who want structured, reviewable multi-stage work instead of one very long chat turn.

Install

pi install npm:@juicesharp/rpiv-pi

Restart your Pi session.

Quick start

rpiv-pi registers no tools of its own — it drives the ones its sibling extensions provide. Install them in one step, then restart Pi again:

/rpiv-setup

The dialog previews every change and applies nothing until you confirm.

You also need a model configured in Pi. If /login already works you are set; otherwise see docs/models-config.md.

Now run a pipeline:

/wf build "add a --json flag to the export command"

build is the default — run /wf "<task>" and it resolves here. It captures your brief, slices it, designs each slice in parallel, gates the plan, then implements and validates; see docs/workflows.md for the full stage list and the other pipelines. The run detaches immediately: a lane appears in the dock under your editor with live progress while you keep typing. Press ctrl+q — or ↓ on an empty prompt, or /lanes — to step in, replay the transcript, answer a parked question with ⏎, or stop the run with x.

Prefer one stage at a time? Every skill also stands alone:

/skill:research "how does session state survive /reload"
/skill:blueprint .rpiv/artifacts/research/<latest>.md
/skill:implement .rpiv/artifacts/plans/<latest>.md

What you get

• Reviewable artifacts instead of one long turn — every skill declares a contract (produces / consumes) and writes timestamped Markdown into .rpiv/artifacts/<bucket>/, so you can read, edit, or reject a design before a line of code is written.
• Runs that don't hold your session hostage — each /wf stage executes in its own detached child session with bounded parallel fan-out; your interactive session stays a launcher and an observer.
• A dock that shows what is happening — one row per run with live progress, streaming thinking, per-unit fan-out sub-rows, token usage, and failure reasons. Step in for a faithful transcript replay with full tool rendering.
• Questions that never get lost — when a detached stage needs input it parks the question on its lane with a badge instead of hijacking your prompt; ⏎ on the flagged lane arms it inline.
• Three pipelines out of the box — build, vet, and polish, so you never have to author a workflow to get value.
• Cheap models for cheap stages — /rpiv-models sets model and reasoning-effort overrides per skill, per stage, per workflow, or per subagent, with a typo-catcher for keys that would otherwise silently never apply.
• Your architecture docs, injected where they matter — touch a file and the nearest AGENTS.md, CLAUDE.md, or .rpiv/guidance/<sub>/architecture.md at each depth is sent to the model, once per session, hidden from your transcript.

Configuration

/rpiv-models writes ~/.config/rpiv-pi/models.json (or $XDG_CONFIG_HOME/rpiv-pi/… when that is set to an absolute path, or a ~ / ~/… path, which is tilde-expanded first), with mode 0600. The file is optional — missing or malformed JSON degrades to no overrides.

Setting	What it does	Default
/rpiv-models	Pick model + reasoning effort for the global default, a subagent, a skill, a workflow stage, or a preset stage	no overrides
RPIV_LANES_HOTKEY	Rebind the lane-browser hotkey to any Pi key id, or set off to register none	ctrl+q
RPIV_BASH_TIMEOUT_MS	Per-command bash watchdog inside detached child sessions, clamped to 5 s–30 min	180000 (3 min)

Reference

• docs/skills.md — all 27 skills: what each consumes, what it writes, and which ones the model may pick on its own.
• docs/workflows.md — the three /wf pipelines stage by stage, plus hand-driven recipes for when you don't want a whole pipeline.
• docs/lanes.md — the dock, the lane browser's full key map, parked questions, and the lane environment variables.
• docs/models-config.md — giving Pi a provider, then the complete models.json schema, cascade, and worked examples.
• docs/agents.md — the 15 bundled subagents and how the on-disk sync decides what to overwrite.
• docs/architecture.md — what gets registered, guidance and git-context injection, sibling coupling, and uninstall.

Requirements

Requirement	Why
Pi Agent	The host. Install it globally so pi is on your PATH
A model provider	Pi's own /login or ~/.pi/agent/models.json — see docs/models-config.md
@tintinweb/pi-subagents	Supplies the Agent tool. Without it the parallel-analysis skills cannot dispatch. Installed by /rpiv-setup
@juicesharp/rpiv-workflow	Supplies /wf. Without it the three built-in workflows do not register. Installed by /rpiv-setup
git (optional)	Branch, commit, and user context. If it fails, injection is skipped and nothing else changes
Node.js 22+	Runtime for Pi and rpiv-pi's bundled scripts

You need no build step and no native dependency.

Troubleshooting

Symptom	Cause	Fix
Session-start banner: N sibling extension(s) missing	Sibling plugins not installed	Run /rpiv-setup, then restart Pi
Session-start banner: bundled agents need attention	A bundled agent changed upstream and your on-disk copy was edited	Run /rpiv-update-agents — it overwrites rpiv-managed files, and never touches agents you added yourself
/rpiv-setup or /rpiv-models says it requires interactive mode	Running headless	Install manually with pi install npm:<pkg>, or hand-edit models.json
/rpiv-setup fails on one package	Network or registry issue	Retry that package with pi install npm:<pkg>, then re-run /rpiv-setup
/lanes reports No in-flight runs (and ctrl+q does nothing)	Nothing is running	Expected — the browser only opens over live lanes
ctrl+q does nothing	RPIV_LANES_HOTKEY is set to off, empty, or an unrecognized key id	Unset it, or use /lanes
A stage stalls, then reports a per-command timeout	A bash command wedged past the watchdog	Raise RPIV_BASH_TIMEOUT_MS (max 1800000) before starting Pi
/rpiv-models reports No models available	Pi has no provider configured	Run /login, or add a provider to ~/.pi/agent/models.json

Related

/rpiv-setup installs the ones marked auto; the rest are standalone pi install npm:@juicesharp/rpiv-<name>.

Package	Role	Auto
@juicesharp/rpiv-workflow	/wf runner — chains skills into typed multi-stage pipelines	✓
@juicesharp/rpiv-args	$1 / $ARGUMENTS placeholders in skill bodies	✓
@juicesharp/rpiv-ask-user-question	Structured questionnaires back to you	✓
@juicesharp/rpiv-todo	Live task overlay surviving /reload	✓
@juicesharp/rpiv-advisor	Escalate to a stronger reviewer model	✓
@juicesharp/rpiv-web-tools	Web search + fetch with pluggable providers	✓
@juicesharp/rpiv-i18n	Localization SDK for the rpiv TUI strings	✓
@juicesharp/rpiv-warp	Warp Blocked badge on parked lane questions	—

License

MIT