QRSPI QRSPI
QRSPI Claude Code plugin · v0.3.0

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

Install Source npm
  1. 00 Questions ~15k burned 00-questions.md ~1k
  2. 01 Research 150-250k 01-research.md ~5k
  3. 02 Design starts at 6k 02-design.md ~4k
  4. 03 Structure starts at 9k 03-structure.md ~3k
  5. 04 Plan starts at 12k 04-plan.md ~6k
  6. 05 Implement starts at 7k code + PR

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 and /qrspi:next.

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

Pin a version with npx qrspi@0.1.0 install; 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

/qrspi:next refuses to advance when the upstream artifact is not ready — unresolved placeholders, 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, and the seven phase templates 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
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.

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.

Read the skills

Straight from the repository. Each SKILL.md is an index of about a hundred lines; the references below it load only when a question needs them.

handoff

Write a handoff — the note a fresh session with zero context reads to continue this work — when asked to summarise a session before context runs out, compress research or a long investigation into a file, hand work to another agent or a …

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