QRSPI

A Claude Code plugin for running coding tasks through phase-gated intentional compaction: every phase writes one self-contained artifact to disk, the next phase starts from a fresh session and reads only that artifact.

Questions → Research → Spec (Design + Structure) → Plan → Implement

Questions   ~20k burned    →  00-questions.md   (~3k)
Research    150-250k       →  01-research.md    (~7k)
Design      starts at 10k  →  02-design.md      (~4k)
Structure   starts at 4k   →  03-structure.md   (~3k)
Plan        starts at 7k   →  04-plan.md        (~13k)
Implement   starts at 7k   →  code + PR

These are the phase's own context. The harness adds a floor on top of every phase — system prompt, tools, CLAUDE.md, installed skills and MCP servers — measured at ~56k on the one run behind these figures (WB-1 in whipbench, #91); it depends on your setup.

The point is not only cost. Implement runs steadily under 20% context — the zone where models actually perform — instead of inheriting 250k tokens of Research residue. And the artifacts are diffable, reviewable, and become the record of the decision.

Install

From inside Claude Code:

/plugin marketplace add Allan-Nava/qrspi
/plugin install qrspi

Or from a shell, with npm:

npx qrspi install

Claude Code has no npm plugin source, so npx qrspi install is a wrapper: it ships the plugin files in the package and registers them for you — through claude plugin marketplace add when the claude CLI is on PATH, otherwise by copying the skills and commands into ~/.claude/ (--copy forces that mode). Either way you end up with the same /qrspi:new, /qrspi:next and /qrspi:review.

npx qrspi install --dry-run   # show what it would do, change nothing
npx qrspi install --copy      # skip the plugin system, copy into ~/.claude
npx qrspi uninstall           # remove what copy mode installed
npx qrspi path                # print the plugin root
npx qrspi check               # validate the package

Codex CLI reads the same repository as a plugin — its marketplace file is the Claude Code one, which Codex accepts as a legacy marketplace, and the manifest is .codex-plugin/plugin.json beside .claude-plugin/plugin.json:

codex plugin marketplace add Allan-Nava/qrspi
codex plugin add qrspi@allan-nava

Codex prefixes plugin skills with the plugin name: the three skills arrive as $qrspi:qrspi, $qrspi:handoff, $qrspi:token-efficiency; the three commands, which Codex has no slash-command form for, arrive as skills too — $qrspi:qrspi-new, $qrspi:qrspi-next, $qrspi:qrspi-review — whose descriptions tell Codex to run them only when named. Verified on Codex CLI 0.155.1, 2026-09-23. Two differences: Codex skills carry no tool allowlist, so Codex's own approval mode and sandbox govern what a phase may run; and rule 1 means a new codex session per phase — codex exec is one-shot by nature, the TUI needs a fresh start, and codex resume is the thing not to do.

Pin a version with npx qrspi@<version> install (e.g. [email protected]); npm i -g qrspi then qrspi install works too. Which route updates itself: the plugin route does, through /plugin — npx registers the marketplace from GitHub, because the npx cache it runs from is pruned; npm i -g registers the installed package directory, which is not. Copy mode is a snapshot — re-run npx qrspi install to update.

Use

/qrspi:new ENG-1234 <ticket text or URL>   # bootstrap thoughts/ + run the Questions phase
/qrspi:next thoughts/ENG-1234-refund-flow  # detect the phase, emit the next prompt, gate on quality

In Codex CLI the same two are $qrspi:qrspi-new ENG-1234 <ticket> and $qrspi:qrspi-next thoughts/ENG-1234-refund-flow, and /qrspi:review <file> is $qrspi:qrspi-review <file>.

When several Implement steps can run in parallel, /qrspi:next prints an execution plan instead of one prompt: a worktree and a prompt per step, the merge order with a rebase between merges, the files more than one step touches, and who keeps 99-progress.md. It still runs nothing — you, or the sessions you start, do.

A pane, optionally. qrspi-pane is a second plugin in the same marketplace: a Claude Code mod that draws each task in thoughts/ as a pane — the phases done, the current one and the Status boxes still open in it (an Approved waiting on you, say), the Implement steps from 99-progress.md, and the /qrspi:next line to run. It only reads, refreshes after every turn, and is opened with /qrspi-status (or /qrspi-status <project path>). Install it with /plugin install qrspi-pane@allan-nava; it needs a Claude Code with function hooks, and the Markdown plugin works the same without it.

/qrspi:next refuses to advance when the upstream artifact is not ready — unresolved placeholders, an Approved box nobody has ticked (every phase ends on one only a person signs), a design with open review comments, a structure step with no verification command, a plan that fails the zero-context test. That gate is the feature: the whole workflow is worthless if you rubber-stamp your way through it.

What's in it

| | | |---|---| | skills/qrspi/ | the workflow: six rules, per-phase context budgets, the six artifact templates and the Implement prompt, and three guides — re-entering a phase, reviewing an artifact, landing the PR — as on-demand references | | skills/token-efficiency/ | the reference behind it: measurement, compaction, subagent firewalls, effort allocation, prompt-caching invalidation, tool definitions and output, KPIs | | skills/handoff/ | the craft the other two assume: what survives a context reset, the load-bearing-fact test, compressing research without losing its evidence trail, writing a step a zero-context agent can execute | | commands/new.md | bootstrap a task and run phase 0 | | commands/next.md | advance a task across a phase boundary | | commands/review.md | review one artifact for what the gates cannot see — finished, plausible, and wrong | | plugins/qrspi-pane/ | an optional second plugin: the QRSPI pane, a Claude Code mod (function hooks); not in the npm package | | skills/qrspi-{new,next,review}/ | the three commands in Codex CLI form ($qrspi:qrspi-new …) — Codex has no slash commands; hidden from Claude Code | | .codex-plugin/plugin.json | the Codex CLI plugin manifest, beside .claude-plugin/ | | bin/qrspi.mjs | the npx qrspi installer — zero dependencies, no build |

Six non-negotiable rules

1. Fresh session at every phase boundary. Never continue.
2. The artifact is the only channel. If it is not written there, it does not exist for the next phase.
3. Artifacts are self-contained. Repo-root paths, explicit symbols, line numbers.
4. The ticket does not enter Research. Handing the agent the ticket makes it hunt for evidence supporting a solution it already assumed. The ticket returns in Design.
5. The 40% rule. Past the threshold, stop and compact — do not push through.
6. Do not outsource the thinking. Every phase is a checkpoint where you correct.

Two design notes

Three skills, not eight. One skill per phase would be the obvious shape and the wrong one: every installed skill's description sits in context permanently, and six near-identical descriptions both burn that budget and compete to trigger. The phases are sequential and user-driven, so they are slash commands. A skill has to earn its permanent line by triggering outside QRSPI: token-efficiency does, on any question about cost; handoff does, on "summarise this session before I lose it" from anyone running any agent. Knowledge that only matters mid-workflow is a reference, loaded on demand. Codex is the one exception, and a bounded one: it has no slash commands, so it lists the three commands' skill forms too — three more descriptions, each saying to run it only when named, and none of them in Claude Code's context.

The skills practise what they document. Each SKILL.md is an index of ~100 lines; the detail lives in references/ and is loaded only when the question needs it. A 700-line skill that documents context economy while spending 9k tokens on every trigger would be an argument against itself.

Prior art

HumanLayer has not open-sourced its own QRSPI. This is a reconstruction based on Dexter Horthy's talks (Advanced Context Engineering for Coding Agents) and the public product documentation. Its predecessor, RPI, is open source.

Other public reconstructions worth reading: matanshavit/qrspi · dfrysinger/qrspi-plus (parallel worktrees) · From RPI to QRSPI

License

MIT. Working on the plugin itself? See CONTRIBUTING.md.