opus-rail

4.8 drives. 5 works.

Claude Code orchestration where Opus 4.8 is the main-loop orchestrator and Opus 5 runs only inside tightly scoped subagents.

---

Why

Measured in real use: Opus 4.8 as the orchestrator follows project doctrine, keeps a leaner context window, and produces a better working flow — while Opus 5 is at its best inside single-objective, fully scoped tasks. opus-rail wires that split into Claude Code instead of hoping the model remembers it:

Lane	Model	Job
orchestrator	Opus 4.8 (main loop)	frame tasks, dispatch, adjudicate, verify, commit
executor	Opus 5	implementation, debugging, tests, focused review — per task
redteam	Opus 5	adversarial review of ideas/plans before they're presented
worker	Sonnet	mechanical bulk, read-heavy search

sequenceDiagram
    participant U as You
    participant O as Opus 4.8 (orchestrator)
    participant R as redteam (Opus 5)
    participant E as executor (Opus 5)
    U->>O: implementation-shaped prompt
    Note over O: ROUTING CHECK injected<br/>at the moment of decision
    O->>R: proposal + context (plans/designs)
    R-->>O: advisory findings, evidence-ranked
    O->>E: scoped dispatch: objective, paths,<br/>constraints, command that must pass
    E-->>O: files changed + verification result
    O->>U: adjudicated, verified result

Loading

Does it actually change behavior?

The core mechanism exists because prose alone measurably failed. Same class of 2-file task, same session setup, live A/B:

	rails as prose only	with point-of-decision routing check
subagent dispatches	0	1 (scoped, 2.6k-char brief)
direct edits by orchestrator	2	0

The system was then reviewed adversarially three ways — by a Claude redteam agent, by GPT via Codex, and by Kimi K3 — and every surviving finding was fixed (see the commit history, which documents what each review caught).

The strongest observed benefits are interactive-session properties — doctrine adherence over long sessions and a lean orchestrator context (delegated churn never enters the 4.8 window). Those resist honest measurement in one-shot harnesses; an earlier benchmark attempt is preserved on the bench-archive branch for anyone who wants to build a multi-turn version.

Install

Two variants — run one, not both:

Full system (hook-enforced)

Model-conditional hooks inject the rules only into Opus sessions, re-inject after compaction, fire a routing check on implementation-shaped prompts, and log telemetry (opus-rails.py stats). → full/INSTALL.md

Skill only (zero-footprint)

No hooks, no settings surgery. Copy one folder, run /opus-rail per session (/opus-rail plus to add the dispatched redteam lane):

mkdir -p ~/.claude/skills && cp -R skill/opus-rail ~/.claude/skills/

The trade: instructions instead of hook enforcement, and it assumes an unpinned opus alias (= Opus 5) for its subagent lanes. → skill/opus-rail/SKILL.md

Known boundaries (measured)

• Hooks do not fire inside subagents — verified live (a pip install inside a subagent ran uninterception). Guards you care about must live in the agent definitions; the ones shipped here do.
• Headless --print sessions have no statusline, so first-prompt model resolution needs a pre-written session flag (--session-id + flag file) or falls back to transcript scan from the second exchange.
• The rails text is opinionated, derived from audited failure sessions; edit the words, keep the mechanism.
• The full system's env pin re-points the opus alias machine-wide to 4.8; /model claude-opus-5 bypasses it.

Repo layout

full/    hook, agents, settings snippet, install guide
skill/   the /opus-rail session skill
assets/  logos

License

MIT © 2026 TigerGTC