Core concepts

These are the terms the skills, the dashboard and the MCP tools use.

Orchestrator and reviewer

The orchestrator is the agent you talk to: Claude Code or Codex. It writes the plan or the code, runs the review skills and decides what to do with each finding.
The reviewer is a second model, the Codex CLI today. It runs in the background for each round. It reads the plan, the diff or the question, and it may run tests and commands to check a claim. Its prompts forbid changing project files, so the orchestrator makes every change.

The orchestrator drives a review with four MCP tools (review_begin, review_wait, review_reply and review_end), or with the runner’s command line when MCP is not available. See the MCP tools reference.

Session

A session is one review from start to end. It is a folder in the repository:

.cross-review/sessions/<skill>-<yyyymmdd>-<NNN>/

For example, review-impl-20261016-001 is the first review-impl session started on 16 October 2026. The folder keeps the rounds, the reviewer’s output and the final verdict. The .cross-review/ folder ignores itself in git. Session files lists what each file holds.

Round

A round is one reviewer turn. The first round starts with review_begin. Each reply the orchestrator sends, with review_reply, starts the next round. The reviewer resumes the same conversation, so it knows what it raised before and what changed.

review_wait reports where the session stands with a next value:

`next`	Meaning
`running`	The reviewer is still working. Wait again.
`respond`	The round has issues. The orchestrator fixes or disputes them and replies.
`cross_check`	Peer skills only. The orchestrator compares the reviewer’s view with its own analysis, then replies or ends.
`done`	The review reached its end. The orchestrator ends the session.
`ask_user`	The round has no verdict. The orchestrator asks you how to go on.
`stopped`	An error, a stall or a timeout ended the round. See Troubleshooting.

Issue

Each finding is an issue, written as an ISSUE-N block. The number stays the same in every later round, so the agent and the reviewer can refer to the same finding.

Every issue has these fields:

Field	Values
Category	A short label such as `bug`, `logic`, `spec-deviation`, `security` or `edge-case`. `plan-gap` and `scope-decision` mark issues that need a decision.
Severity	`low`, `medium`, `high` or `critical`
Location	A file path and line range, such as `src/export/markdown.js:18-22`
Problem	What is wrong
Evidence	A code excerpt or diff excerpt that shows it
Why it matters	The effect on the request, the plan, correctness, security or runtime
Suggested fix	One fix or a few options. Advisory: the orchestrator may fix it another way.

The orchestrator answers each issue in its reply, with FIXED_ITEMS (what changed, and where) and DISPUTED_ITEMS (the evidence against the issue).

Verdict

In a plan or implementation review (review-plan, review-impl), each round ends with a verdict:

APPROVE: no issues remain. The reviewer omits the issue blocks.
REVISE: at least one issue is open. The reviewer lists the issues.

The verdict decides the end of the review: an APPROVE ends it with done.

A peer review (review-think, review-pr) has no approval verdict. Each round ends with a status instead: CONTINUE (the debate goes on), CONSENSUS or STALEMATE. In review-think the reviewer calls it a suggested status, and it is advisory: the orchestrator compares it with its own analysis and decides the outcome. A review-pr round’s status is about the debate, not the pull request; the merge recommendation (approve or request changes) comes from the orchestrator’s final report.

Consensus and stalemate

A peer review (review-think, review-pr) ends in one of two outcomes that the orchestrator records with review_end:

Consensus: both sides agree. Their positions are in the last messages.
Stalemate: the same disagreements stay open with no new evidence. The orchestrator presents the open points and you decide.

For a plan or an implementation review, the runner reports a stalemate (done) when the same issues stay open across rounds without new evidence. In that case the orchestrator presents the deadlocked issues and you decide.

Fix or dispute

For each issue the orchestrator takes one of these actions:

Action	When
Accept and fix	The issue is a real defect or a real deviation from the approved target. The fix is verified, and the reply lists it.
Dispute	The issue is not a real problem. The reply gives concrete evidence from the request, the plan, the code or a test. Style preferences, optional polish and limits that protect nothing are common cases.
Plan gap	The approved plan itself causes a bug, a performance loss or a real risk. The orchestrator does not change the plan alone. It presents a plan change to you with its options.
User decision	A valid fix would change behavior you can see, scope, an API, a schema, stored data, compatibility, dependencies or the architecture. The orchestrator asks you one question at a time and waits.

Most issues raised after the first round come from the previous round’s fixes. Orchestrators check what each fix touches before they reply.

User authority

Your latest explicit instruction about a review overrides the skill, the protocol and the reviewer. You can tell the agent to continue, stop, skip a review, resume a stopped session, accept the current result as approved, or change the model or effort. An approval you give is recorded as yours, not the reviewer’s.

Your instructions do not authorize product, API, schema or compatibility changes you did not ask for.

Where sessions and settings live

Kind	Location
Sessions	`<repo>/.cross-review/sessions/`
Plans	`<repo>/.cross-review/plans/`
Workspace settings	`<repo>/.cross-review/config.json`
Global settings	`~/.cross-review/config.json`

Everything stays on your disk. The reviewer receives the prompts and the content it reads, as described in the FAQ.