RGR

RGR

rgr is a no-dependency Red-Green-Refactor gate for coding agents. It gives agents a human-operator style CLI that records the failing test first, freezes that test with hashes and snapshots, and refuses to mark Green or Refactor if the Red test was edited.

Install

Clone the repo and run it with Bun:

git clone https://github.com/kingbootoshi/rgr.git
cd rgr
bun run rgr -- --help

Optional: link the CLI onto your PATH:

bun link
rgr --help

From this repo:

bun run rgr -- --help

From another repo:

bun run /path/to/rgr/src/cli/index.ts --root . --help

The workflow examples below assume rgr is on your PATH. If it is not, replace rgr with bun run /path/to/rgr/src/cli/index.ts.

Agent Plugins

RGR ships two skills as both Claude Code and Codex plugins, the two halves of trustless engineering:

• rgr — proves behavior and scope at one CI verdict (this tool).
• intent-contract — turns a request into a signed Locked Intent Boundary before any planning, so an agent cannot redefine the goal. It compiles to an IntentLock that rgr verify --intent-lock enforces. See skills/intent-contract/SKILL.md.

Together: intent-contract writes the law, rgr is the court that proves the work stayed inside it. See Trustless Enforcement.

Claude Code:

claude plugin marketplace add kingbootoshi/rgr
claude plugin install rgr@rgr

For local Claude Code testing from a clone:

claude --plugin-dir .

Codex:

• Plugin manifest: .codex-plugin/plugin.json
• Shared skill: skills/rgr/SKILL.md
• Codex UI metadata: skills/rgr/agents/openai.yaml

Install the repo root as the plugin directory in Codex, then invoke $rgr when a code change should use strict Red-Green-Refactor proof. The bundled intent-contract skill is discovered the same way (skills/intent-contract/).

Trustless Enforcement (intent-contract + rgr)

The endgame: accept an agent's work without trusting the agent, because a gate it cannot bribe has already proven the work stayed inside the human's intent and functions.

1. Lock intent. intent-contract produces a small, human-signed Locked Intent Boundary: required deltas, invariants, non-substitutions, and authorized-change rights (every diff op must map to a row). It compiles to a hash-pinned IntentLock.
2. Freeze it. rgr lock-intent --intent-lock <path> --expect-sha256 <H> verifies the lock's payload hash and stores a copy under .rgr/ as evidence.
3. Enforce one verdict. rgr verify --ci --replay --intent-lock <trusted> --expect-intent-sha256 <H> proves behavior (Red-Green-Replay) and scope (every git diff --no-renames --name-status <lockedBase>...HEAD op maps to an authorized row) in a single pass.

The load-bearing property: .rgr/ is evidence, not authority. CI reads the trusted lock from a path the agent does not control, hash/signature-verifies it, and audits the real diff against that. Tampering the in-tree copy changes nothing. A non-ancestor base or a dirty working tree fails closed. Deny rows (ops: []) fail on contact.

A signed boundary lives at docs/prds/intent-lock-scope-audit.intent-boundary.md — this feature was built under its own boundary and self-audited.

Core Workflow

# 1. Initialize a manifest for this goal.
rgr init --goal-id billing-scope

# 2. Write only the failing test, then capture Red.
rgr red --strict --goal-id billing-scope --test src/billing.test.ts -- bun test src/billing.test.ts

# Optional: explicitly freeze a helper, fixture, snapshot, or config file that defines the Red oracle.
rgr red --strict --goal-id billing-scope --test src/billing.test.ts --protect tests/fixtures/billing.ts -- bun test src/billing.test.ts

# 3. Implement production code, then prove Green.
rgr green

# 4. Refactor only while the Red test is still byte-for-byte unchanged.
rgr refactor -- bun test

# 5. Final gate for local CI or sandbox authority.
rgr verify --ci --replay -- bun test

Every run writes .rgr/manifest.json, .rgr/events.jsonl, snapshots, diffs, and command output logs.

When an older completed cycle has known replay-only environment noise, targeted replay can keep later cycles moving while still requiring Green receipts, protected heads, and the final verify command. Treat this as an exception path and report the replay scope.

# Replay only the latest active cycle.
rgr verify --ci --replay --cycle latest -- bun test

# Replay active cycles from a known cycle onward.
rgr verify --ci --replay --from-cycle 004 -- bun test

What It Enforces