rpiv-pi v2.3.1
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 cut your forks your design gate /wf capture ↺ slice design review ↺ plan ↺ code land
↺ gates grade & repair on their own asks only when the code can’t decide always pauses · your design gate

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 2.3.1

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 pipeline: what each one chains, shortest to deepest.

  2. /wf build

    inspect the graph before committing to it: 30 stages, three gates, one design review.

  3. /wf build “describe your change”

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

what happens on go

  1. 01

    capture ▢ your answers

    your brief goes to disk byte-for-byte. No LLM touches it. Research then grounds it in your codebase, asking on ambiguity and confirming with you before it writes. Every gate downstream grades against your exact words.

  2. 02

    slice ▢ your cut gate · 0 LLM calls

    the brief is cut into independent vertical slices, each small enough for one design pass. You confirm the cut once. That freezes the coverage units a script then conserves: cycle-free, no piece of your ask dropped.

  3. 03

    design ▢ your forks

    one fresh session per slice, dependency-ordered, all running at once. Every lane is live in the console. A genuine design fork reaches you without halting the others.

  4. 04

    review ■ your design gate

    your design gate, the pause that carries real judgment: every slice's design in one summary. Accept, or adjust interfaces and data types; the edit cascades to dependents before synthesis.

  5. 05

    plan gate ×5 · ↺ fix

    per-cluster sub-plans merge into one plan. A five-dimension panel grades it before any code exists; completeness and correctness are judged against your verbatim brief.

  6. 06

    code gate · ↺ fix

    implement-ready code elaborated per phase in parallel, spliced into the plan by a script, and the code-bearing plan re-graded.

  7. 07

    land

    phases implemented in order, the result validated against your brief. You confirm the commit plan; your name goes on the diff.

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

§ the pipelines · pick one

Three pipelines. One command.

Each pipeline is a fixed, code-defined graph of contract-carrying skills: validatable, auditable, resumable. build ships a brief; vet reviews a diff you already have; polish works a big architecture review, phase by phase.

/wf build 30 stages · 3 gates · 1 design review

A feature from a brief. Sliced, designed in parallel, gated before any code.

capture slice design review ◉ plan code land

  • verbatim brief
  • 3 quality gates
  • design review · yours
  • parallel design
/wf vet 8 stages

A diff already exists, yours or a teammate's. Review it, loop a fix cycle until zero blockers remain.

goal code-review blueprint implement implement-scope-check reconcile 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

  • phase fanout
  • architecture review
  • review loop

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

→ small change in a big codebase? /skill:discover → /skill:research slices the search space. Then finish in chat, or with /skill:blueprint when you want a plan first.

§ inside build · 30 stages · 3 gates · 1 design review

Every stage answers a failure you’ve met.

Build's thirty stages, drawn as seven acts: three fix loops, one seal. Machinery like this would be overhead in sequence. Here, everything between gates runs in parallel.

capture goal script · your brief, byte-for-byte research ▢ grounds the brief in your code · asks you on ambiguity slice slice ▢ independent vertical slices · you confirm the cut slice-check script gate · cycle-free, coverage conserved · 0 LLM calls slice-fix slice-grade design-readiness · one fresh-context judgment design design-slice ×N ▢ fresh session per slice, dependency-ordered · forks reach you review design-review ◉ every slice's design, one pause · adjustments cascade plan subplan ×clusters per-cluster merge · no pass holds every design plan one merged plan plan-fix plan-grade panel ×5 · graded against your verbatim brief code elaborate ×phases implement-ready code per phase code-splice script · deterministic splice into the plan code-fix code-grade panel ×5 · re-grades the code-bearing plan land implement phases in order · a patch series, not a race validate against your brief · --goal commit your name on the diff
▢ asks only when the code can’t decide ◉ always pauses · your design gate

§ 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 pipelines are composition, not a cage.

3

pipelines

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

→ the pipelines

27

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 · v2.3.1 · 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 v2.3.1

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

rpiv-btw

side question v2.3.1

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

§ 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.2Kimi 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 pipeline stage, and into every fanout unit: each grade dimension and each slice design resolves its own model. Run the chain on an affordable model and escalate just the grade panels to a frontier one. The expensive tokens go 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
  • bounded context by construction: every fanned-out session carries one slice, one dimension, or one phase. The anatomy is why small models hold up

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 pipelines
  • per-stage model control
  • workflow engine
  • unified loop driver
  • parallel fan-out + live lane console
  • judges + verify
  • panel() + match() routing
  • mid-loop resume
  • skill contracts
  • the sibling family

what's next

  • first-class fan-in / synthesize affordance
  • 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
  • worktree isolation for shared-tree stages

→ 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.