1<!--
2SPDX-FileCopyrightText: Amolith <amolith@secluded.site>
3
4SPDX-License-Identifier: CC0-1.0
5-->
6
7# Crosscheck
8
9Crosscheck is an [OpenProse 14][OpenProse]\* workflow that has a main LLM agent
10orchestrate parallel subagents to review code, come up with findings, validate
11those findings, and provide a report.
12
13[OpenProse]: https://github.com/openprose/prose/tree/v0.14.0
14
15I hate that there's terminology, but I think there has to be 😭 Maybe I'll come
16up with clearer terms for the non-OpenProse things that won't require
17explanation.
18
19For Prose:
20
21- OpenProse: Markdown files ("contracts") that turn the LLM agent you're
22 interacting with into a sort of "virtual machine" that executes those Markdown
23 contracts.
24- Prose Complete: describes any LLM harness, like Crush, Claude Code, etc., with
25 the required tools to execute OpenProse.
26- Prose VM: the main, front-and-center conversation/session/thread with an LLM
27 agent in a Prose Complete harness.
28
29For Crosscheck:
30
31- Runner: either a subagent in your Prose VM or a standalone Prose Complete
32 harness invoked by your Prose VM through its shell tool.
33
34\*Specifically OpenProse 14 because later versions change drastically, adding a
35whole "reactor" thing that replaces Prose Complete harnesses, and OpenProse's
36harness agnosticism is a huge reason I like it. So we're sticking with when it
37was good :)
38
39## Execution ownership
40
41The Prose VM is the coordinator/runtime. If you type `prose run ...` into Amp,
42then that thread in Amp is the Prose VM. If you run `crush run "prose run ..."`,
43then that session in Crush is the Prose VM.
44
45The VM owns Crosscheck's sequencing and run state: resolving the subject,
46discovering runners and model availability, planning the reviewers and
47validators, preparing workspaces, indexing candidates, merging findings, and
48writing the final packet.
49
50Runners are workers. A reviewer runner gets one lane prompt and returns one lane
51report. A validator runner gets neutralized candidate briefs and returns
52verdicts.
53
54## Usage
55
56Run Crosscheck from the repository or worktree being reviewed:
57
58<!-- rumdl-disable MD013 -->
59
60```bash
61# simple use
62prose run ~/where/you/cloned/crosscheck/src -- subject: "current diff"
63# with preferences
64prose run ~/where/you/cloned/crosscheck/src -- subject: "git diff main" preferences: "crush run --yolo with minimax, kimi, qwen, and deepseek reviewers, no mimo"
65```
66
67<!-- rumdl-enable MD013 -->
68
69- `subject`: current diff, ref range, branch, paths, PR description, or a
70 natural-language review target
71- `preferences`: optional runner/model/focus/exclusion/local-testing guidance
72
73## Setup
74
75You'll need [OpenProse 14][OpenProse]'s agent skill and standard-library
76dependency cache. This installs both from the `v0.14.0` zip archive, replacing
77any existing copies at those two paths.
78
79<!-- rumdl-disable MD013 -->
80
81```bash
82set -euo pipefail
83
84OPENPROSE_TAG=v0.14.0
85tmpdir="$(mktemp -d)"
86
87curl -fsSL \
88 "https://github.com/openprose/prose/archive/refs/tags/${OPENPROSE_TAG}.zip" \
89 -o "${tmpdir}/openprose.zip"
90
91unzip -q "${tmpdir}/openprose.zip" -d "${tmpdir}"
92srcdir="$(find "${tmpdir}" -mindepth 1 -maxdepth 1 -type d -name 'prose-*' | head -n 1)"
93test -n "${srcdir}"
94
95mkdir -p \
96 "${HOME}/.agents/skills" \
97 "${HOME}/.agents/prose/deps/github.com/openprose"
98
99rm -rf \
100 "${HOME}/.agents/skills/open-prose" \
101 "${HOME}/.agents/prose/deps/github.com/openprose/prose"
102
103cp -R "${srcdir}/skills/open-prose" \
104 "${HOME}/.agents/skills/open-prose"
105
106cp -R "${srcdir}" \
107 "${HOME}/.agents/prose/deps/github.com/openprose/prose"
108
109rm -rf "${tmpdir}"
110```
111
112<!-- rumdl-enable MD013 -->
113
114The first `cp` installs the `open-prose` skill. OpenProse has a global
115dependency cache of Markdown (seems crazy, but I guess it makes sense?) and the
116second copy puts the `std/...` and `co/...` deps in the right place.
117
118Other dependencies:
119
120- `bash`, `curl`, `unzip`, and ordinary shell utilities such as `mktemp`,
121 `find`, `head`, `mkdir`, `rm`, and `cp` for the setup command above.
122- At least one Prose Complete harness like [Crush][Crush], [Pi][Pi], [Amp][Amp],
123 [Claude Code][Claude Code], or [Codex][Codex] on your PATH that can load the
124 `open-prose` skill and give the LLM filesystem and shell access.
125 - You'll interact with the Prose VM and it must either use built-in subagents
126 or invoke itself/another Prose Complete harness through the shell tool. If
127 you want a read-only review, the Prose Complete harness should have an
128 effective read-only mode.
129- Model/provider credentials configured for the runner. Local models _can_ work
130 well for this, but unless you have stellar hardware, the quantisations you'll
131 be limited to might yield very poor results.
132- The VCS CLI needed by your `subject`. The examples above use `git`, if your
133 repo is `jj`, you'll need that.
134
135Microsandbox is not required yet, but it will be for the escalation path where
136reviewers and validators can build and execute adversarial probes inside
137isolated environments.
138
139[Crush]: https://github.com/charmbracelet/crush
140[Pi]: https://github.com/earendil-works/pi/tree/main/packages/coding-agent
141[Amp]: https://ampcode.com
142[Claude Code]: https://claude.com/product/claude-code
143[Codex]: https://github.com/openai/codex