caspar-code-review

name	caspar-code_review
description	Run an independent adversarial code review of completed work using a pinned high-effort opposing runtime, with a same-contract native fallback. Finds bugs, correctness and security failures, regressions, performance landmines, overengineering, and missing behavioral tests. Review only; never edits code.
user-invocable	true

code_review

Adversarial review of what was just built. A clean-context reviewer tries to falsify correctness and production readiness, then returns only evidence-backed, severity-ranked findings. Review only; never edit code.

Inputs

• $ARGUMENTS - optional focus guidance, explicit diff/base range, target OUT_DIR, and optional --orchestrated when another workflow will consume the report.
• Review scope = completed work plus modified/created/deleted files, their direct dependencies/importers, and relevant tests. Pull requirements and acceptance criteria from the matching tasks.json parent slices when present, else plan.md, else the user's request and actual diff. Use execute.md only to locate tasks.json.
• If the work scope is genuinely ambiguous after inspecting artifacts and git state, ask what to review before dispatching.

Working Set

• branch = git rev-parse --abbrev-ref HEAD (fallback unknown).
• OUT_DIR = target_dir || docs/tasks/{branch}; report under {OUT_DIR}/reviews/.
• REVIEW_REPORT = {OUT_DIR}/reviews/comprehensive_code_review.md; if it exists, use comprehensive_code_review_{YYYY-MM-DD_HHMMSS}.md and never overwrite prior evidence.
• Build a late-bound review manifest: diff/base range, changed-file summary, in-scope requirement/AC paths, relevant tasks.json parent ids, direct dependencies/importers, relevant tests, and explicit exclusions. Do not inline an entire large diff or task graph; the reviewer reads them directly.

Method / guardrails

External-first selection

1. If current runtime is Codex and command -v claude succeeds, run Claude Code.
2. If current runtime is Claude Code and command -v codex succeeds, run Codex.
3. If the opposite CLI is missing, exits non-zero, cannot write REVIEW_REPORT, or produces an invalid report after one repair attempt, record the reason and fall back to one native @caspar:reviewer; unavailable opposing runtimes never block completion.
4. Primary-agent self-review is prohibited except validating the saved report and persisting an explicit native fallback return.
5. Do not probe for startup commands. Use exactly the applicable recipe below from repo root.

Opposite-runtime initiation recipe

From Codex primary:

claude -p --model fable --effort high --permission-mode dontAsk --allowedTools "Read,Grep,Glob,LS,Bash(mkdir -p *),Bash(git diff *),Bash(git show *),Bash(git status *),Bash(git rev-parse *),Write" --output-format text "$REVIEW_PROMPT"

From Claude Code primary:

codex exec -C "$PWD" -m gpt-5.6-sol -c 'model_reasoning_effort="high"' -s workspace-write "$REVIEW_PROMPT"

External report metadata is fixed by route: Codex -> Claude Code records Reviewer Runtime: Claude Code, Reviewer Model: fable, Reviewer Effort: high, Invocation Route: Codex -> Claude Code; Claude Code -> Codex records Reviewer Runtime: Codex, Reviewer Model: gpt-5.6-sol, Reviewer Effort: high, Invocation Route: Claude Code -> Codex.

The external reviewer may write only REVIEW_REPORT; it may not edit code, tests, plans, tasks, scope docs, or other artifacts. Allow at least 20 minutes before treating the run as hung.

REVIEW_PROMPT includes: "Act as an adversarial code reviewer. Try to prove the completed work is wrong, unsafe, unnecessarily complex, or unable to meet its stated requirements. Do not defend the implementation and do not invent out-of-scope requirements." It also includes the review manifest, report path, scope boundary, lenses, severity/evidence rules, required sections, write restriction, and required metadata (Reviewer Runtime, Reviewer Model, Reviewer Effort, Invocation Route).

Adversarial lenses

Lens	Attack surface
Correctness	wrong outputs, broken invariants, edge cases, state/ordering/concurrency failures, error-path behavior
Regression / integration	broken callers, unreachable wiring, stale active paths, contract mismatches, incomplete migrations
Security	trust boundaries, auth/permissions, injection, secret/data exposure, unsafe input or destructive behavior
Performance / reliability	hot-path complexity, N+1 work, blocking I/O, leaks, unbounded memory/work, retry or failure amplification
Overengineering	speculative abstractions, duplicate paths, needless indirection, generality not required by scope; flag only when a materially simpler in-scope shape is evident
Test adequacy	changed behavior with no executable regression signal, untested failure/security paths, assertions that cannot catch the defect

Severity and evidence

• CRITICAL - exploitable security failure, data loss/corruption, privilege bypass, or core execution failure.
• HIGH - concrete user-facing correctness/regression, serious security weakness, or demonstrated hot-path/reliability failure.
• MEDIUM - localized defect, meaningful maintainability/overengineering cost, non-critical performance issue, or material test gap with a concrete failure risk.
• LOW - small but actionable issue. Do not report style, naming, formatting, praise, or speculative future concerns.
• Every finding needs file:line, the violated behavior/requirement, concrete evidence, impact, and the smallest scope-safe fix.
• Every CRITICAL/HIGH also needs a reproducible failure, exploit, or performance path with observable behavior. No evidence chain means downgrade or omit; "could potentially" is not evidence.
• Stay within the completed work and its direct blast radius. Missing features from another scope and subjective architecture preferences are not findings.

Native fallback

• Dispatch one clean-context @caspar:reviewer with the same manifest, adversarial role, lenses, severity rules, evidence requirements, exclusions, and report schema from REVIEW_PROMPT.
• Replace only the persistence instruction: return the complete report in-thread so the primary can save it unchanged to REVIEW_REPORT.
• Record Reviewer Runtime: native-subagent, Reviewer Model: runtime-native, Reviewer Effort: inherited, Invocation Route: native-fallback, and Fallback Reason: ....

After either route, verify the report exists, contains every required section, names the reviewed scope, and includes all runtime/model metadata. Repair an invalid external report once with the same CLI; otherwise use the native fallback. Never fix findings inside this skill.

Outputs + DONE

Required report sections:

1. Scope Boundary - completed work, diff/base, requirements, in-scope files/dependencies/tests, and explicit exclusions.
2. Verdict - BLOCKED for CRITICAL/HIGH, PASS WITH FINDINGS for MEDIUM/LOW only, or CLEAN.
3. Findings - table # | Severity | Lens | Location | Evidence / Reproduction | Impact | Smallest Fix, ordered CRITICAL to LOW. Say No findings when clean; do not pad.
4. Coverage Record - files/paths and tests inspected, plus material areas not verified and why.
5. Prioritized Actions - minimal ordered remediation list, or None when clean.
6. Review Metadata - ISO8601 timestamp, Reviewer Runtime:, Reviewer Model:, Reviewer Effort:, Invocation Route:, and Fallback Reason: when applicable.

DONE when the report exists with all six sections; scope is explicit; runtime/model/effort/route metadata is present; any native fallback reason is recorded; findings satisfy evidence rules; no code or non-report artifact was modified.

Handoff

• Standalone: return only CRITICAL/HIGH findings numbered for selection, the verdict, reviewer runtime/model, fallback reason if any, and Review report saved: {path}. Suggest /caspar:fix for blockers or /caspar:clean / /caspar:test when unblocked.
• --orchestrated: return the verdict, CRITICAL/HIGH findings with their evidence chains, reviewer metadata, and report path to the calling workflow without pausing or suggesting a separate command.

Escalate-If

• Diff/work scope remains ambiguous after reading available task/plan artifacts and git state -> ask what to review before dispatching.
• A proposed finding changes requirements rather than identifying a defect -> label it Scope Change Required; do not include it in the blocking verdict.