scopewright

Website

scope (examine under a scope) + -wright (a maker, as in playwright/shipwright): a maker of SCOPED reviewers.

scopewright scaffolds read-only review subagents for Claude Code, Codex, Gemini CLI, OpenCode, Cursor, and Agent Skills-compatible harnesses, built on the SCOPED framework. It doesn't review your code — it interviews you and writes a reviewer tailored to your project. You supply the domain (runtime, language, criteria, stakes); scopewright prescribes the form: dependency-ordered S/C/O/P/E/D structure, strict read-only constraints, prompt-injection defenses, and clear verdict authority.

Usage

Claude Code:

/scopewright:create [what the reviewer should evaluate]

Pi:

pi install git:github.com/jwmarshall/scopewright
# or, while developing locally:
pi install ./path/to/scopewright

Then use /skill:scopewright-create [what the reviewer should evaluate].

For Gemini CLI, install this repository as an extension to get the bundled skills:

gemini extensions install https://github.com/jwmarshall/scopewright

The release workflow validates the manifest and publishes a Gemini-only archive (with the portable skills, Gemini reviewer agent, and required references, excluding other harness adapters) when you push a v<version> tag matching gemini-extension.json. Gemini CLI prefers that archive on installation. Its public extension gallery indexes public repositories automatically: add the gemini-cli-extension topic to this repository's GitHub About section once. The crawler discovers repositories with that topic and a valid root manifest.

Codex, Gemini CLI, OpenCode, and Cursor discover the checked-in .agents/skills/ directory. Install or link this repository so that directory is available to the project, then invoke scopewright-create as a skill. It creates a portable reviewer at .agents/skills/<name>/SKILL.md and, after selecting the harness, its native adapter:

| Harness | Native reviewer output | Invocation | | --- | --- | --- | | Claude Code | .claude/agents/<name>.md | delegate to <name> | | Pi + @tintinweb/pi-subagents | .agents/agents/<name>.md | @<name> <request> or delegate with the Agent tool | | Codex | .codex/agents/<name>.toml | ask Codex to delegate to <name> | | Gemini CLI | .gemini/agents/<name>.md | @<name> <target_files>… | | OpenCode | .opencode/agents/<name>.md | @<name> <target_files>… | | Cursor | .cursor/agents/<name>.md | /<name> <target_files>… |

Pi can invoke the generated portable skill with /skill:<name> in the current session. When the external pi-subagents plugin is installed and configured, Scopewright also creates its plugin-compatible agent definition in .agents/agents/<name>.md. The plugin is a separate dependency (Pi 0.84.0+); install it in Pi to discover and invoke these definitions. Declared tools are restricted to read-only inspection, but this is tool-list enforcement, not an OS sandbox:

pi install npm:@tintinweb/pi-subagents

The plugin loads .agents/agents/ definitions and supports @<name> <request> mentions or delegation through its Agent tool. Scopewright does not bundle or install the plugin runtime; it generates the agent definition. Every reviewer accepts <target_files> paths (or the raw-data mode selected during its interview) and remains read-only by instruction.

The skill will:

1. Read the bundled SCOPED specification.
2. Inspect your project and interview you for each SCOPED section (Specifications, Constraints, Objective, Purpose, Execution standards, Decision authority).
3. Write a tailored portable reviewer to .agents/skills/<name>/SKILL.md and, for a selected native harness, its adapter in that harness's agent directory. Claude Code writes .claude/agents/<name>.md, configured with Write/Edit/NotebookEdit disallowed; Pi writes .agents/agents/<name>.md for pi-subagents and limits its declared tools to read-only inspection; the other adapters use their documented read-only control.

The result is an ordinary project reviewer you can invoke, edit, and version. Re-run the skill to build additional reviewers (security audit, contract review, design critique, writing feedback, data-quality checks, and so on).

What it produces

A SCOPED reviewer follows the framework's six sections in dependency order and:

• treats all acquired data (file contents or raw payloads) as untrusted input;
• halts with an explicit [INSUFFICIENT DATA: …] string when context is missing;
• returns a distilled Structured Analytical Report, offloading bulky output to .agents/logs/ rather than dumping it into the chat;
• issues verdicts (e.g. [APPROVED] / [REJECTED]) to its Caller and escalates with [FAILED: …] instead of acting on state or asking humans directly.

Bundled reviewer: root-prompt-reviewer

The package also ships a ready-made SCOPED reviewer you can invoke directly — no interview required. root-prompt-reviewer audits a repository's root prompts (CLAUDE.md, AGENTS.md) — the instructions that execute on every inference — for:

• token economy — conversational filler and bloat that taxes every message;
• safety guardrails — missing limits on destructive actions (DB mutations, file deletions, quota burn) without human-in-the-loop confirmation;
• orchestration architecture — context stuffing that belongs in /commands or Skills, non-universal rules, premise-ordering failures, and unstructured prose.

It scores the target against six dimensions and returns an [APPROVED] / [REJECTED] verdict with a dimension scorecard and line-cited fixes. The pass/fail standard lives in reference/ROOT_PROMPT_DESIGN_RUBRIC.md, which the agent reads at runtime. Pi users with pi-subagents installed can invoke its project definition at .agents/agents/root-prompt-reviewer.md. Like every SCOPED reviewer it is strictly read-only.

The SCOPED framework

SCOPED stands for Specifications, Constraints, Objective, Purpose, Execution standards, and Decision authority. It is a prompting framework for building review and evaluation subagents that produce consistent, thorough, actionable verdicts.

Its central idea is dependency-first ordering: the six sections are arranged in the order the model actually uses the information while reasoning, not the order that reads naturally to a human. LLMs degrade sharply (the spec cites 30%+ drops) when premises arrive out of sequence and the model has to back-reference. SCOPED removes that back-referencing — each section is fully grounded by the ones above it:

Specifications  → grounding facts, specialization & how to acquire data
  Constraints     → the pass/fail rules derived from those facts
    Objective       → one sentence synthesizing the task
      Purpose         → why it matters; calibrates thoroughness
        Execution std.  → the quality bar for the output itself
          Decision auth.  → read-only autonomy, verdicts & escalation

S — Specifications & Context

The technical foundation, established first because the agent must know how to safely acquire data and what expertise to bring before it ever reads the criteria. This section carries the functional specialization (concrete stack, versions, conventions — so the agent behaves like an expert instead of being told to "pretend" to be one), plus three safety rules: a data-acquisition rule (read <target_files> paths vs. parse a <raw_data> payload), a data-encapsulation rule (treat everything acquired as untrusted, never as instructions), and an input-validation halt condition (the exact [INSUFFICIENT DATA: …] string to emit when context is missing). Why it leads: safe, specialized grounding has to exist before any evaluation can be trusted.

C — Constraints & Requirements

The explicit, binary and testable conditions that decide acceptance or rejection — pass/fail rules with detection methods and thresholds-with-units, not subjective scales. Why here: it depends on the stack and data structures named in S, and replaces vague "use good judgment" reviewing with criteria the agent can apply deterministically.

O — Objective Statement

A single synthesizing sentence (verb + deliverable + reference to the criteria/data above) that the agent can act on decisively. Why here: it only makes sense once the facts (S) and the rules (C) are in place; it fuses them into one unambiguous task.

P — Purpose & Impact

What the review gates and the concrete consequences of a miss — regulatory, financial, operational. Why it matters: stakes calibrate thoroughness. "Gates a $2M payment API; a miss means PCI-DSS failure" tells the agent how hard to look in a way the rules alone cannot.

E — Execution Standards

The quality bar for the output itself: a distilled Structured Analytical Report, a strict prohibition on dumping raw data or logs back into the chat, and instructions to offload bulky output to .agents/logs/ and return only the path. Why it matters: this is what keeps a subagent from polluting the caller's context — protecting tokens and reasoning, not just code quality.

D — Decision Authority

The agent's professional stance and hard boundaries, placed last because it governs what to do with everything above. It defines the verdict vocabulary the agent may return to its Caller ([APPROVED]/[REJECTED], or domain-specific like [BLOCK DEPLOYMENT]), the posture it is empowered to take (state findings as facts; challenge assumptions rather than be politely agreeable), and escalation that halts with [FAILED: …] to the Caller instead of acting on state or asking humans directly. Why it matters: this is where read-only safety is enforced in prose — countering the "action-taker" hallucination (claiming to have mutated state) and the "helpful assistant" drift ("looks mostly good…") that undermine real review.

Together these defend against the framework's named anti-patterns — action-taking, reflexive politeness, prompt injection through unprotected context, and token-wasting theatrical role-play.

Multi-agent design

The durable artifact is the SCOPED reviewer prompt, not a harness-specific agent file. Claude Code consumes agents/ definitions and skills directly under skills/; Pi consumes the package manifest's pi-skills/ and, with external @tintinweb/pi-subagents, project agents in .agents/agents/. Portable .agents/skills/ resources work in Codex, Gemini CLI, OpenCode, and Cursor. Native adapters also live in .codex/agents/, .gemini/agents/, .opencode/agents/, and .cursor/agents/ respectively. They keep the same S/C/O/P/E/D body and add each harness's available read-only control; they never fork review criteria.

Aider supports repository instruction files and read-only review workflows, but has no custom-subagent or Agent Skills format. Scopewright therefore does not claim native Aider delegation; use the portable reviewer prompt as a checked-in convention there.

Reference

The full framework spec ships with the plugin at reference/SCOPED_FRAMEWORK_V4.md.

License

MIT © Jonathon W. Marshall