en-cross-review

Helper resolution. All references/X and bin/Y paths in this skill resolve relative to $ENSEMBLE_ROOT — the install root (skill at $ENSEMBLE_ROOT/skills/<name>/, shared helpers at $ENSEMBLE_ROOT/{references,bin}/). Compute once at start: $ENSEMBLE_ROOT env var if set; otherwise $(realpath "$(dirname <this-SKILL.md>)/../.."). Fail loudly if $ENSEMBLE_ROOT/references/host-detect.md does not resolve — that indicates a partial install (run /en-setup to repair).

/en-cross-review

Ad-hoc peer review. Wraps any artifact and ships it to the peer agent. The host parses findings JSON and surfaces them; the host applies the user-selected ones.

Process

1. Detect host. Source $ENSEMBLE_ROOT/references/host-detect.md. Resolve PEER, PEER_MODE, PEER_CMD, PEER_FORMAT, PEER_AVAILABLE.

2. Recursion guard. If ENSEMBLE_PEER_REVIEW=true, exit with note: "Already inside a peer subprocess — skipping cross-review to avoid recursion."

3. Resolve target.

   • No arg → current uncommitted diff (git diff + git diff --cached).
   • <path> → contents of the file.
   • <git-ref> (e.g., main..HEAD, HEAD~1) → diff between refs.
   • <branch-name> → diff between branch and the default branch.

4. Verify availability. If PEER_AVAILABLE=false, exit with the reason (peer_mode_override=off; cross-agent-only without other CLI installed; etc.).

5. Compose review prompt. Shell out to $ENSEMBLE_ROOT/bin/ensemble-build-peer-prompt — do not assemble the prompt by reasoning. Required args:

   • --artifact-type <code|plan|markdown artifact|mixed> — code for diffs/files of source, markdown artifact for docs/, plan only when reviewing a docs/plans/active/*.md (rare for ad-hoc cross-review), else mixed.
   • --project-context "<one-line>" — first paragraph of AGENTS.md or foundation §1.
   • --goal "<one-line>" — for diffs: the most-recent commit subject; for files: the user's stated reason for the cross-review.
   • --artifact-file <path> (or pipe via stdin with --artifact-stdin) — the resolved target body.
   • --peer-mode "$PEER_MODE" — from host-detect.

   The helper substitutes the conditional blocks (single-agent fallback note, plan-specific review dimensions) for you.

6. Apply --focus flag (if set). Append to the prompt: "Focus your review on ; deprioritize other concerns." Valid: security, performance, tests, correctness, maintainability, all (default).

7. Set ENSEMBLE_PEER_REVIEW=true in the subprocess env (recursion guard).

8. Invoke peer.

   ENSEMBLE_PEER_REVIEW=true \
     $PEER_CMD $PEER_FORMAT --max-turns 1 "$prompt" \
     > /tmp/peer-response.json 2>/tmp/peer-stderr.log
   

   Honor peer_timeout_seconds from ~/.ensemble/config.json (default 600).

9. Detect D30 violations (peer modified files). Per the protocol in $ENSEMBLE_ROOT/references/build-handoff.md:

   • git stash --include-untracked before; check git status after.
   • Any change → revert; log violation; do not trust this round.

10. Parse JSON response per $ENSEMBLE_ROOT/references/finding-schema.md. On malformed JSON: retry once with "respond with valid JSON only" suffix; if it fails again, surface and exit.

11. Present findings to the user grouped by severity (P0 → P3) and confidence:

    Cross-review verdict: revise (3 findings)
    Mode: cross-agent (peer: codex)
    Focus: all
    
    ### High (P1)
    
    1. **Refresh-token race in concurrent path** (correctness; conf 9)
       - src/auth/refresh.ts:42
       - Two requests can race during rotation; second invalidates the first.
       - Fix: serialize per-user via singleFlight cache.
       - Apply? (y/n/defer/disagree)
    
    [...]
    

12. User picks per finding (or --apply-all-safe-auto to auto-apply mechanical fixes).

13. Apply selections (per $ENSEMBLE_ROOT/references/severity.md). Re-verify with project test/lint after edits. On regression: revert; surface.

14. Capture-from-synthesis (D21) — soft prompt at the end if the cross-review surfaced a non-obvious lesson worth filing.

Flags

Flag	Effect
--focus security|performance|tests|correctness|maintainability|all	Bias the peer's attention
--apply-all-safe-auto	Auto-apply safe_auto findings without prompting
--no-apply	Show findings only; don't apply anything
--mode cross-agent|single-agent|auto	Override peer-mode resolution

Cross-review

This skill is the cross-review. No additional --peer flag.

When single-agent-fallback fires

When only one CLI is installed (or peer_mode_override: single-agent-only):

• PEER_CMD = host's own CLI (e.g., claude -p from Claude Code).
• The Outside Voice prompt includes the single-agent augmentation (be more aggressive, bias toward finding problems).
• Findings carry peer_mode: "single-agent-fallback" so the user knows which mode they're in.

The contract from D30 still holds — the fresh subprocess returns findings only.

No-write contract

The peer subprocess never modifies files. Detected violations (rare) are reverted automatically. The skill is fully read-only on the peer side; only the host applies user-selected findings.

Reference files

• $ENSEMBLE_ROOT/references/host-detect.md — host detection
• $ENSEMBLE_ROOT/references/outside-voice.md — prompt template + verdict handling
• $ENSEMBLE_ROOT/references/single-agent-fallback.md — same-CLI fallback contract
• $ENSEMBLE_ROOT/references/finding-schema.md — JSON shape
• $ENSEMBLE_ROOT/references/severity.md — apply / defer / disagree routing
• $ENSEMBLE_ROOT/references/recursion-guard.md — ENSEMBLE_PEER_REVIEW env var

Failure protocol

Failure	Behavior
PEER_AVAILABLE=false	Exit with reason; suggest install of other CLI or peer_mode_override change
Peer subprocess times out	Log to stderr; mark cross-review as skipped; exit
Peer returns malformed JSON	Retry once; on second failure, surface raw output and exit
Peer attempted to modify files	Revert; log violation; do not trust findings; surface
Target file/ref doesn't resolve	Surface; suggest a valid target
User declines all findings	No-op; the cross-review still ran (cost incurred); surface a summary
--no-apply set + findings present	Output report; don't ask user to pick

Cost characteristics

Artifact size	Approximate token cost
Small file or per-unit diff (< 100 lines)	5K–15K
Mid-size diff (~500 lines)	15K–40K
Large branch diff (1000+ lines)	40K–100K (consider splitting)

For genuinely large reviews, the user is better served by /en-review (multi-persona, parallel) than by /en-cross-review (single-pass peer). Use /en-cross-review when:

• The user wants a specifically different perspective (the other agent).
• The user wants a focused pass (--focus security).
• The user is operating from Codex and explicitly wants a Claude review (or vice versa).