rpiv-pi v1.20.0
github docs blog
install

§ rpiv-pi · keep the driver in the loop

correct ≠ aligned

A driver-in-the-loop pipeline for the Pi coding agent. One /wf command from brief to reviewed commit.

LLMs produce correct code: it compiles, it passes tests. Aligned code, the kind that fits your patterns and your unwritten conventions, still takes a driver. rpiv-pi keeps that driver in the loop at LLM speed.

your brief your answers your checkpoints /wf research blueprint implement validate code-review commit

start in three steps ↓ pi install npm:@juicesharp/rpiv-pi

§ the gap · correct → aligned

Correct code isn't aligned code.

Output that compiles and passes tests can still be wrong for your codebase. Misaligned code isn’t zero-value. It’s negative-value: it ships, then it taxes every engineer who reads that file afterward.

correct

It compiles. The tests pass. The diff looks fine in PR review. Every capable model produces this reliably today, at any price point. This bar is no longer the hard part.

aligned

It fits the codebase’s existing patterns. It respects conventions that aren’t written down anywhere. It makes the boring choices mature systems rely on, and it stays reviewable and extensible by the next person who touches it.

without a driver

  • locally-correct, globally-misaligned diffs that pass review
  • near-duplicates that cost the next refactor half a day
  • architectural coherence eroding quietly, untraceable to any one diff
  • alignment debt is paid later, by someone else

with the driver in the loop

  • the pipeline asks the right questions at the right moments
  • architectural decisions surface where they actually matter
  • involvement is participation, not rubber-stamp approval
  • review loops on hard data until the blockers read zero

§ install · 3 steps

Three steps. One restart.

  1. 01 
    pi install npm:@juicesharp/rpiv-pi
  2. 02 
    /rpiv-setup

    Reads ~/.pi/agent/settings.json. Previews missing siblings and any legacy entries to prune. One confirm to apply.

  3. 03

    Restart your Pi Agent session.

Requires Pi pi-coding-agent ^0.70.5  ·  rpiv-pi 1.20.0

Bring your own key (z.ai, OpenAI, Anthropic, and others). See README → Prerequisites .

§ first run · one command

Your first run, end to end.

Three commands of escalating commitment: look, inspect, go. The runner drives the chain; you decide at the moments that shape the outcome.

look · inspect · go

  1. /wf

    preview every flow: what each one chains, shortest to deepest.

  2. /wf build

    inspect the graph before committing to it: stages, gate, loop.

  3. /wf build “describe your change”

    run the whole chain. Your brief is the only required input.

what happens on go

  1. 01

    research ■ you

    subagents fan out under fresh context; grounded questions come back to you before the doc is written.

  2. 02

    blueprint ■ you

    the plan pauses at micro-checkpoints. Your call before any code is written.

  3. 03

    implement

    fans out across the plan's phases, each verified against its success criteria.

  4. 04

    validate

    the finished work re-checked phase by phase against the plan.

  5. 05

    code-review ↺ ≤ 3 passes

    gates on a contract-validated blockers_count and loops back until it reads zero.

  6. 06

    commit

    grouped logically, message written, your name on the diff.

one JSONL ledger per run · .rpiv/workflows/runs/<id>.jsonl · resume any run with /wf @<run-id>

§ the six flows · pick one

Six ways to ship.

Two questions choose your flow: how big is the change, and do you already have a diff? They run shortest to deepest, left to right.

Starting fresh

from a one-line brief
/wf ship 4 stages

Small change, obvious approach. No research, no review.

blueprint implement validate commit

  • phase fanout
/wf build 7 stages

Medium change you want reviewed before it lands.

research blueprint implement validate code-review commit

  • research-backed
  • phase fanout
  • review loop
/wf arch 7 stages

Complex change across many files or layers.

research design plan implement validate code-review commit

  • research-backed
  • design-led
  • phase fanout
  • review loop

You already have a diff

yours, a teammate's, or an incoming PR
/wf vet 5 stages

A diff already exists. Review it, optionally repair.

code-review blueprint implement validate commit

  • phase fanout
  • review loop
/wf polish 6 stages

A large architecture review, planned phase by phase.

architecture-review blueprint implement validate code-review commit

  • architecture review
  • phase fanout
  • review loop
/wf pr-triage 2 stages

An incoming PR. Decide if it earns a review: read-only, halts on a security BLOCK.

pr-triage security-gate

  • security gate

→ run /wf to preview every flow, /wf <name> for one’s graph, /wf <name> “your task” to go.

§ the surface · what one install pulls in

Small command, deep surface.

Everything below ships behind pi install npm:@juicesharp/rpiv-pi and one /rpiv-setup. Every piece is documented, and every piece is yours to run directly. The workflows are composition, not a cage.

6

workflows

one /wf command each, from a brief to a reviewed commit.

→ the flows

20

skills

contract-carrying, /skill:-runnable on their own, chainable by /wf.

→ skills reference

6

siblings

every tool surface is its own extension; rpiv-pi registers zero tools.

→ the family

MIT · v1.20.0 · ships raw TypeScript · no build step, Pi loads it directly

§ siblings · 6 packages

Tools, not infrastructure.

rpiv-pi registers zero tools. Every tool surface lives in a sibling extension, detected by a regex over ~/.pi/agent/settings.json. /rpiv-setup installs the missing ones in a single confirm.

rpiv-advisor

advisor model v1.20.0

Pi extension. A second opinion the model can request from a stronger reviewer model before it acts.

 pi install npm:@juicesharp/rpiv-advisor

peers pi-ai · pi-coding-agent · pi-tui · typebox

rpiv-btw

side question v1.20.0

Pi extension. The /btw slash command, for putting a one-off side question to the same primary model without polluting the main conversation.

 pi install npm:@juicesharp/rpiv-btw

peers pi-ai · pi-coding-agent · pi-tui

rpiv-web-tools

web search v1.20.0

Pi extension. Web search and fetch for the model with pluggable providers (Brave, Tavily, Serper, Exa, You.com, Jina, Firecrawl, Perplexity, SearXNG, Ollama).

 pi install npm:@juicesharp/rpiv-web-tools

peers pi-coding-agent · pi-tui · typebox

§ models · no frontier budget required

Built to run on affordable models.

The pipeline produces genuinely good results on open-weight models at a fraction of frontier token prices, and it is honest about the residual gap.

GLM-5.1Kimi K2.5MiMo-V2-Pro … or Claude, GPT, Gemini: bring your own key. 

/rpiv-models

Per-skill and per-stage model + reasoning-effort overrides, cascading from defaults down to a single workflow stage. Run the chain on an affordable model and escalate just the review and judge stages to a frontier one, spending the expensive tokens only where they earn their keep.

gain

  • runs end to end on open-weight models, at roughly a third of frontier output pricing
  • same pipeline, same contracts, same audit at any price point
  • per-stage escalation: frontier judgement without frontier-priced drafting

cost

  • not yet at parity with frontier on the same task: more mistakes, longer runs
  • closing that gap is the active roadmap: fresh-context verification first, frontier escalation only where it pays

§ roadmap · done → next → possible

Where this is going.

No dates, no version targets. Items move down the list as they ship. The direction is the promise: keep an experienced driver in the loop while the work moves at LLM speed.

shipped · the product you just scrolled

  • the skill pipeline
  • named subagents
  • built-in /wf flows
  • per-stage model control
  • workflow engine
  • unified loop driver
  • judges + verify
  • mid-loop resume
  • skill contracts
  • the sibling family

what's next

  • panel(): N judges + vote fold for adversarial verification
  • first-class fan-in / synthesize affordance
  • match() enum gate
  • automatic flow generation via agent
  • headless Pi / out-of-process execution
  • verification under affordable models: fresh-context isolation + frontier escalation
  • delegation strategy optimization

what's possible

  • telemetry public release
  • non-Pi host embedding
  • third-party skill contracts + user workflow packs
  • tournament bracket ranking
  • true parallelism with worktree isolation

→ the structured list lives in roadmap.md; the README keeps the philosophy.

§ setup · /rpiv-setup

Scan, confirm, install. One prompt.

  1. Runs only when it's safe

    In a headless or automated session it notifies and exits: nothing is read, nothing is installed.

  2. Works out what's needed

    Reads your Pi settings and figures out which sibling extensions are missing and which stale entries should go. If settings can't be read, it backs off instead of guessing.

  3. Stops if there's nothing to do

    Already installed and clean? It says so and returns: no prompt, no changes.

  4. Asks once

    Shows a single preview of exactly what it will install and what it will remove, then asks to proceed. Cancel leaves everything untouched.

  5. Prunes the stale entries

    Removes the outdated entries from your settings. A write error is reported, never fatal.

  6. Installs one at a time

    Each missing sibling installs on its own, with a time limit so one slow or stuck install can't stall the rest.

  7. Tells you what changed

    Lists what installed and what failed, and asks you to restart your Pi session only when something actually changed.