QRSPI

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. qrspi@0.5.0); 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>.

/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

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.

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.

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