A multi-host plugin (Claude Code + Codex) that packages a 3-round / 6-step cross-agent spec/plan review pipeline as a single state-driven skill. One slash command — /cr — advances the pipeline based on a project-local state file (.cross-agent-reviews/<slug>/), so operators no longer paste round JSON between rounds on a single host. Reviewer rounds audit the artifact in fresh sessions; author rounds settle findings without requiring a fresh session, with a strict final round preserving cross-agent diversity by construction. Reviews scale to artifact risk: an operator-locked review_profile sets the minimum review breadth and an optional fast mode enables deterministic shortcuts — auto-settling clean rounds and impact-routing verification — without weakening the final independent blocker review (see Review profiles and modes). v0.1.x ships local-only; install via the host's /plugin slash-commands (see Install below).
| Round | Procedure | Role | Input | Output |
|---|---|---|---|---|
| 1a | rounds/1a-audit.md |
Reviewer (5-agent parallel review) | spec/plan path | round-1a.json |
| 1b | rounds/1b-settle.md |
Author (settle + edit) | round-1a.json |
round-1b.json |
| 2a | rounds/2a-audit.md |
Reviewer (verify corrections) | round-1b.json |
round-2a.json |
| 2b | rounds/2b-settle.md |
Author (settle + edit) | round-2a.json |
round-2b.json |
| 3a | rounds/3a-audit.md |
Reviewer (strict final check) | round-2b.json |
round-3a.json |
| 3b | rounds/3b-settle.md |
Author (final adjudication) | round-3a.json |
final_status (READY_FOR_IMPLEMENTATION or CORRECTED_PENDING_VERIFICATION) |
| 3c | rounds/3c-verify.md |
Independent verifier (conditional) | round-3b.json |
round-3c.json / round-3c-attempt-NNN.json |
Round 3b runs only when Round 3a found blockers. A clean 3a — every reviewer agent ship_ready with zero findings — terminates the pipeline directly (see Terminal status below). Round 3c (final verification) runs only when Round 3b accepted and corrected blockers; a Round 3b that rejected every blocker terminates directly.
In fast mode, a clean 1a/2a audit auto-settles — the empty 1b/2b is generated and persisted with no manual settle round — and 2a/3a verification is impact-routed to the slices touched by accepted findings plus mandatory global and cross-artifact coverage. Any ambiguity, blocker, spec drift, cross-artifact mismatch, or incomplete finding lineage falls back to broad review. Final 3a always keeps full parallel independent reviewer coverage for every slice in its selected scope.
Fresh session per audit round. The router applies a fresh-session preflight before audit rounds (1a, 2a, 3a) and before the verification round (3c) — cross-agent diversity demands the reviewer/verifier come to the artifact without prior interpretive frame. Settle rounds (1b, 2b, 3b) may continue in the same session or a fresh one (operator choice).
Terminal status. The pipeline terminates one of three ways:
- Clean 3a — every Round 3a agent is
ship_readywith zero findings. Terminates at Round 3a; Rounds 3b and 3c do not run.final_status: READY_FOR_IMPLEMENTATION. - Via Round 3b — Round 3a found blockers, Round 3b rejected all of them.
final_status: READY_FOR_IMPLEMENTATION; artifact ships unchanged. - Via Round 3c — Round 3b accepted and corrected blockers, then Round 3c independently verified the corrections.
final_status: CORRECTED_AND_READY.
Between Round 3b and a CORRECTED_AND_READY terminal the pipeline holds two non-terminal states: final_verification_pending (3c not yet run) and final_verification_failed (a 3c attempt found unresolved blockers or regressions — fix the artifact and rerun /cr).
review_profile and mode are locked once at artifact-block init and cannot change mid-pipeline. Pass them as order-independent tokens alongside the artifact path:
/cr docs/specs/foo-design.md patch fast
| Token | Values | Controls |
|---|---|---|
review_profile |
patch · feature · greenfield |
Minimum review breadth (slice count, mandatory coverage). |
mode |
thorough (default) · fast |
Whether the deterministic shortcuts the profile allows fire. |
patch— targeted fix, small refactor, or doc correction: most aggressive deterministic reduction.feature— new behavior in an existing codebase: moderate reduction; final3astays broad until narrower routing is proven safe.greenfield— new subsystem or broad architecture: conservative; broad review stays mandatory.
Legacy or absent values preserve the original thorough behavior unchanged.
/cr suggest <artifact-path> prints a deterministic, explainable profile/mode recommendation with rule-ID evidence and writes no state. It never auto-selects — routing always follows the operator's locked values. Init records the suggestion beside the locked values for audit, and /cr status shows it, flagging any divergence from the locked profile or mode. Ambiguous or conflicting signals yield the safer (broader) profile, and a suggested fast is never silently selected.
The plugin is a single skill with a router and six round procedures, backed by a project-local state directory:
plugin/skills/cr/
├── SKILL.md # router: parse intent, read state, dispatch
├── rounds/
│ ├── 1a-audit.md
│ ├── 1b-settle.md
│ ├── 2a-audit.md
│ ├── 2b-settle.md
│ ├── 3a-audit.md
│ ├── 3b-settle.md
│ └── 3c-verify.md
└── _shared/
├── preflight.md
├── dispatch-template.md
├── status-protocol.md
├── self-review.md
├── status-report.md
├── attribution.md
├── model-tier-rubric.md
├── cross-artifact-slice.md
└── schema/ # JSON Schema (Draft 2020-12) files
State directory layout (resolved via git rev-parse --show-toplevel from the artifact's directory; falls back to cwd if no git root):
<project-root>/.cross-agent-reviews/
└── <slug>/
├── state.json
├── spec/
│ ├── round-1a.json
│ ├── round-1b.json
│ └── …
└── plan/
├── round-1a.json
└── …
The router parses operator intent, reads state, disambiguates the active slug, determines the next round, applies the fresh-session check (audit rounds only), executes the round procedure, calls cr_state_write.py to persist the round JSON + update state.json, and prints the next-step message.
Design rationale lives in docs/superpowers/specs/2026-05-07-issue-1-state-file-redesign-design.md.
This plugin's pipeline shape adapts patterns from the Superpowers plugin family (reference version 5.0.7):
superpowers:dispatching-parallel-agents— parallel-dispatch decision pattern for slice planning.superpowers:subagent-driven-development— model-tier rubric, status protocol, and dispatch-template structure.
Full attribution at plugin/skills/cr/_shared/attribution.md.
sudo apt install python3 python3-pip ripgrep jq diffutils bats
curl -LsSf https://astral.sh/uv/install.sh | sh # or: pipx install uv
uv syncbrew install python@3.11 ripgrep jq uv bats-core
uv syncwsl --install -d Ubuntu-24.04
# Then inside Ubuntu, follow the Linux pathuv sync reads pyproject.toml + uv.lock and creates .venv/. Operators preferring vanilla pip can use pip install . instead — pyproject.toml is the standard format.
After uv sync, run the one-time hook install:
uv sync && uv run pre-commit install --hook-type pre-commit --hook-type pre-pushIn any Claude Code session:
/plugin marketplace add /path/to/cross-agent-reviews
/plugin install cross-agent-reviews@cross-agent-reviews
/cr appears in autocomplete. Restart the session if it doesn't surface immediately.
To uninstall: /plugin uninstall cross-agent-reviews@cross-agent-reviews. The marketplace registration stays; remove separately with /plugin marketplace remove cross-agent-reviews if desired.
In Codex (CLI v0.128+):
codex plugin marketplace add /path/to/cross-agent-reviews
Then in the Codex TUI, open /plugin, navigate to the cross-agent-reviews marketplace, and install the cross-agent-reviews plugin. $cr appears in autocomplete. Restart the TUI once after install to refresh the skill index.
To uninstall, use /plugin in the TUI to uninstall the plugin, or run codex plugin marketplace remove cross-agent-reviews to drop the marketplace registration.
Once the repo is published at https://github.com/j7an/cross-agent-reviews, the same slash-command flow is expected to accept a GitHub URL as the marketplace source:
/plugin marketplace add https://github.com/j7an/cross-agent-reviews
/plugin install cross-agent-reviews@cross-agent-reviews
v0.1.x is local-only — the URL is reserved but not yet published.
- Linux: Ubuntu 24.04 LTS native.
- macOS: any modern release with current Homebrew.
- Windows: Ubuntu 24.04 LTS inside WSL2.
- Native Windows (cmd/PowerShell with Git Bash, MSYS2, Cygwin): best-effort, not in v0.1.x test matrix.
State file does all handoff. Per the §5.4 fresh-session policy, fresh sessions are mandatory only before audit rounds (1a, 2a, 3a); settle rounds (1b, 2b, 3b) may continue in the same session or a fresh one — operator's choice (design §9.1, §10.1).
[fresh session 1] /cr <spec-path> [<profile>] [fast] → cr_state_init locks mode/profile, runs round 1a
[same or fresh] /cr → state says next is 1b; runs round 1b
[fresh session] /cr → state says next is 2a (audit); fresh required
[same or fresh] /cr → state says next is 2b; runs round 2b
[fresh session] /cr → state says next is 3a (audit); fresh required
clean 3a → pipeline terminates here (3b, 3c skipped)
non-clean 3a → state says next is 3b
[same or fresh] /cr → (non-clean 3a only) runs round 3b
3b rejects all blockers → pipeline terminates
3b accepts blockers → state says next is 3c
[fresh session] /cr → (3b accepted only) runs round 3c; fresh required
3c passes → pipeline terminates (CORRECTED_AND_READY)
3c fails → fix artifact, run /cr to re-verify
[fresh session] /cr <plan-path> → state has spec finished; plan starts at round 1a (audit, fresh required)
… [plan rounds with the same audit/settle alternation] …
Operator never pastes JSON. /cr status reports the locked mode/profile, the recorded suggestion (and any divergence), auto-settled rounds, impact-routed rounds, and any fallback reasons.
The state directory is gitignored, so it does not sync across hosts. At every host transition the operator gives an explicit natural-language cue ("review on a different host", "I just ran round 1a on the other host; here is its output"). The router routes such cues into paste-import mode instead of running the next round locally (design §10.2).
On the initiating host, the cue must be combined with the artifact path on the same /cr invocation — the router uses the presence of a path to disambiguate the outbound bootstrap branch (Host A: init locally and emit state.json for paste) from the inbound paste-import branch (Host B: receive the paste). A bare cue with no artifact path always routes to inbound paste-import.
[Host A, fresh] /cr <spec-path> review on a different host
→ outbound bootstrap branch: cr_state_init writes state on A
→ skill prints state.json (bootstrap payload) and STOPS
(round 1a does NOT run on A)
[Host B, fresh] /cr → no local state; skill asks operator to paste state.json
operator pastes → cr_state_read.py --paste validates state.json (bootstrap path)
→ writes state.json locally
→ runs round 1a; emits round-1a.json (file + stdout)
[Host A, fresh] /cr → operator says "import round 1a from the other host"
operator pastes → cr_state_read.py --paste validates round-1a.json
→ writes round-1a.json locally; updates state.json
→ runs round 1b
… [continues] …
The operator pastes JSON twice per round-pair (one transit per host hop). Same UX as v0.1.0 paste-into-prompt; the state file makes single-host operation file-driven without regressing cross-host.
Failed round-3c-attempt-NNN.json files are host-local and are never paste-imported; the passing round-3c.json is the cross-host handoff record. The operator must carry the verified artifact bytes to the receiving host — a 3c paste is rejected if the receiving host's local artifact does not match the pasted verified_content_hash.
Common mistakes:
- Forgetting the artifact path on first
/cr— the skill will ask; supply absolute or relative path. - Pasting the wrong round's JSON across hosts — the skill detects round-order mismatch (pasted
stage≠ next expected) and asks you to repaste. - Editing the artifact between an author round (1b/2b) and the next reviewer round (2a/3a) — manual edits in between break the contract; the reviewer round verifies the same artifact the previous author edited.
uv run pytest tests/ # run Python tests
uv run pytest --cov=plugin/skills/cr/_helpers tests/ # with coverage
uv run ruff check . # lint
uv run ruff format . # format
bats tests/bats/ # bash tests
bash scripts/verify-prompt-contract.sh # static prompt-content verifierThe verifier runs prompt-content checks across the v0.1.x layout. Required tools: bash, rg (ripgrep), jq, diff, bats-core.
See CONTRIBUTING.md for the TDD discipline, coverage floor, and conventional-commit conventions.
This plugin's pipeline shape was iterated locally in a sibling repo (superpowers-cross-agent-reviews) over three commits before being extracted as a publishable plugin. The design directly adopts patterns from the Superpowers skill collection by Jesse Vincent and contributors. See plugin/skills/cr/_shared/attribution.md for the full attribution.
MIT. See LICENSE.