> ## Documentation Index
> Fetch the complete documentation index at: https://panopticon-cli.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Convoys

> The review convoy, four parallel reviewers and one synthesis parent

export const ThemedImage = ({light, dark, alt = ""}) => {
  const [darkMode, setDarkMode] = useState(null);
  useEffect(() => {
    const root = document.documentElement;
    const syncTheme = () => setDarkMode(root.classList.contains("dark"));
    const observer = new MutationObserver(syncTheme);
    syncTheme();
    observer.observe(root, {
      attributes: true,
      attributeFilter: ["class"]
    });
    return () => observer.disconnect();
  }, []);
  if (darkMode === null) return null;
  return <img src={darkMode ? dark ?? light : light} alt={alt} loading="lazy" />;
};

# Convoys: Parallel Code Review

A review convoy is how Overdeck runs a **full** code review. Four reviewers
each check one concern in parallel, and a review parent combines their
findings into one verdict that it posts on the pull request.

There is no separate convoy command and no convoy state. A convoy is a set of
agents that the review pipeline starts for an issue. Its result is the PR
review itself.

## Why Convoys?

When reviewing code, a single AI agent must context-switch between:

* Checking for logic errors
* Looking for security vulnerabilities
* Analyzing performance issues
* Checking the change against the issue's acceptance criteria

This leads to:

* **Shallow reviews**: it can't go deep on everything
* **Missed issues**: focus on one area, miss others
* **Long sequential execution**: nothing runs in parallel

Convoys solve this by **specialization + parallelization**:

* Four focused reviewers run at the same time
* Each one goes deep in its own domain
* The review parent combines their findings and decides the verdict

## Quick Start

A review starts automatically when the work agent runs `pan done`. You can
also start or manage one by hand:

```bash theme={null}
# Request a (re-)review after fixing feedback
pan review request PAN-123 -m "Fixed the null check"

# See where the issue is: derived state plus recent pipeline journal entries
pan show PAN-123

# Stop every running reviewer for the issue
pan review abort PAN-123

# Restart the review, re-running any reviewer that has no report yet
pan review restart PAN-123
```

Whether a review runs as a convoy depends on the review mode. See
[Review modes](#review-modes).

## How the Review Convoy Works

```
pan done PAN-123   (or pan review request, the dashboard, or a PR webhook)
    │
    ├─→ Phase 1 (Parallel): four reviewers run simultaneously
    │     ├─→ agent-pan-123-review-security     → security.md
    │     ├─→ agent-pan-123-review-correctness  → correctness.md
    │     ├─→ agent-pan-123-review-performance  → performance.md
    │     └─→ agent-pan-123-review-requirements → requirements.md
    │
    └─→ Phase 2: the review parent (agent-pan-123-review) waits for all four
          ├─→ reads the reports → synthesis.md
          └─→ posts one PR review: approve or request changes
```

Every review request goes through one entry point, whether it comes from
`pan done`, `pan review request`, the dashboard or the PR webhook. The parent
and all four lanes start together against the PR's current head commit.

### Phase 1: Specialized Reviews (Parallel)

Four reviewers run at the same time, each focused on one concern:

| Agent | Focus Areas |
| - | - |
| `agent-<issue>-review-security` | OWASP Top 10, injection, XSS, auth issues |
| `agent-<issue>-review-correctness` | Logic errors, edge cases, type safety, null handling |
| `agent-<issue>-review-performance` | N+1 queries, blocking operations, memory leaks, algorithm complexity |
| `agent-<issue>-review-requirements` | Acceptance criteria and xBRIEF coverage |

`<issue>` is the lowercase issue id, for example `agent-pan-123-review-security`.
Each reviewer's model comes from `roles.review.sub.<lane>.model`, set in the
dashboard's Roles panel or in `~/.overdeck/config.yaml`.

Each reviewer:

* Reviews the PR's diff independently
* Writes its report to `.pan/review/<runId>/<lane>.md` in the issue's workspace
* Goes deep without worrying about the other concerns
* Runs in parallel, so total time is the slowest reviewer, not the sum

The lane instructions live in `roles/review-security.md`,
`roles/review-correctness.md`, `roles/review-performance.md` and
`roles/review-requirements.md`.

### Phase 2: Synthesis

The review parent, `agent-<issue>-review`, waits for the four reports. Then it:

1. **Reads all four reports**
2. **Removes duplicates**: the same issue found by more than one reviewer
3. **Weighs the findings**: severity, code citations, tests and requirement coverage
4. **Writes** `.pan/review/<runId>/synthesis.md`
5. **Posts one PR review**: approve, or request changes with the findings as PR comments

The PR review is the verdict. Overdeck stores no review status of its own.
When GitHub refuses a review on your own PR (a single-account install), the
verdict is posted as a PR comment that starts with
`<!-- overdeck-verdict: APPROVED sha=<head> -->` or `<!-- overdeck-verdict: CHANGES_REQUESTED sha=<head> -->`,
naming the commit it reviewed when that commit is still the head.
See [docs/REVIEW-AGENT-ARCHITECTURE.md](https://github.com/eltmon/overdeck/blob/main/docs/REVIEW-AGENT-ARCHITECTURE.md).

## What is Synthesis?

Synthesis combines the findings from the parallel reviewers into a single,
prioritized verdict.

**Without synthesis**, after four parallel reviews you get:

* Four separate reports to read
* Duplicate findings (the same issue reported differently)
* No prioritization (which to fix first?)
* The work of merging them yourself

**With synthesis**, you get:

* One PR review with one decision
* Deduplicated findings
* Blockers separated from everything else
* Clear action items for the work agent

The reports are evidence, not votes. The parent decides the verdict. The
synthesis report has this shape:

```markdown theme={null}
# Verdict: APPROVED | CHANGES_REQUESTED | FAILED

## Summary

## Blockers

## Evidence

## Convoy Notes
```

## Review modes

The review mode decides whether a review runs as a convoy. Set it in the
dashboard's Roles settings panel, or with `roles.review.mode` in
`~/.overdeck/config.yaml`. It applies to every review.

| Mode | What runs |
| - | - |
| `quick` (default) | One review agent, `agent-<issue>-review`, does a combined pass and writes `review.md` |
| `full` | The convoy: the review parent plus the four lanes |
| `none` | No AI review. The verification quality gates still apply. |

## Review Commands

```bash theme={null}
# Request a re-review after fixing feedback
pan review request <id> [-m <message>]

# Stop every running reviewer session for the issue.
# The work agent is left idle and is not messaged.
pan review abort <id>

# Restart the review parent and re-run any lane that has no report yet
pan review restart <id>
  --role <lane>     # Re-run only this lane (security/correctness/performance/requirements)
  --model <model>   # Use this model for the restarted reviewers

# Derived issue state and the last pipeline journal entries
pan show <id>
pan show <id> --json   # includes pr.reviewState
```

## Review Lifecycle

```
1. Review requested (pan done, pan review request, dashboard, or PR webhook)
        │   journal: review.requested
        ▼
2. Parent and four lanes start against the PR head
        │   journal: review.dispatched
        ├─→ agent-<issue>-review-security
        ├─→ agent-<issue>-review-correctness
        ├─→ agent-<issue>-review-performance
        └─→ agent-<issue>-review-requirements
        │
        ▼
3. Each lane writes .pan/review/<runId>/<lane>.md and exits
        │
        ▼
4. Parent writes synthesis.md and posts the PR review
        │   journal: review.verdict
        ▼
5a. Approved: the PR is mergeable once its checks are green
5b. Changes requested: the work agent gets the PR comments and a pan tell,
    fixes, pushes, and the next full review starts again at step 1
```

The journal entries are appended to the issue's pipeline journal
(`<workspace>/.overdeck/pipeline.jsonl`), and `pan show` prints the latest
ones. Merge readiness is computed live from the PR's approvals against its
current head, so a push after an approval leaves the new head unreviewed until
the next review runs.

## Monitoring Convoys

**Dashboard:**

Reviewers appear in the issue view next to the work agent they review, with
their status, model, cost and verdict. The Pipeline page groups every issue
and its agents by phase (Ship, Review, Verifying), with a metric strip across
the top (Active issues, Work running, Review queue, Ship, Spend) and a live
activity feed on the right.

<ThemedImage light="/images/dashboard/pipeline-light.png" dark="/images/dashboard/pipeline-dark.png" alt="Pipeline page: a metric strip showing Active issues, Work running, Review queue, Ship, and Spend over phase-grouped issue rows, with a live activity feed on the right." />

**CLI:**

```bash theme={null}
# Where the issue is, and the last pipeline journal entries
pan show PAN-123

# Recent terminal output of one reviewer
curl -s "http://localhost:3011/api/agents/agent-pan-123-review-security/output?lines=100"

# The reports for a run
ls -lh <workspace>/.pan/review/<runId>/
```

To open a reviewer's terminal, use the attach command for your terminal
backend. See [Reaching an agent from a shell](/configuration/terminal-backend#reaching-an-agent-from-a-shell).

## Use Cases

* Pre-merge quality checks on every PR
* Security audits of sensitive changes
* Performance reviews of hot paths
* Checking a change against its acceptance criteria

When reviews run across several projects at once, the God View gives an
aggregate cross-project picture of every agent's activity in one place. Review
convoys orbit their issue, so a convoy whose reviewers have stalled or are
burning more than expected is easy to spot.

<ThemedImage light="/images/dashboard/god-view-light.png" dark="/images/dashboard/god-view-dark.png" alt="God View: an aggregate cross-project view of all agent activity across every Overdeck-monitored project." />

## Best Practices

**When to use `full` mode:**

* Changes where security, performance and correctness all matter
* You want complete coverage, not a surface-level pass
* The cost of four extra reviewers is worth it

**When `quick` is enough:**

* Small, focused changes
* Documentation or style-only changes

Every full review runs all four lanes against the current head. A prior
report is never reused for a new commit.

## Troubleshooting

**Review stuck with no verdict:**

```bash theme={null}
# What the pipeline last did for the issue
pan show PAN-123

# Which reviewers are alive (either terminal backend)
pan status --json   # read each agent's `alive`

# Recent output of a reviewer
curl -s "http://localhost:3011/api/agents/agent-pan-123-review-security/output?lines=100"

# Re-run the lanes that have no report, keeping completed ones
pan review restart PAN-123

# Or stop every reviewer
pan review abort PAN-123
```

Overdeck also recovers some stalls on its own. When an issue's last journal
entry is `review.requested`, `review.dispatched` or `review.redispatched`, it
is at least 15 minutes old, and no `agent-<issue>-review-*` reviewer is alive,
the deacon re-dispatches the full review, at most once an hour per issue. If
the parent dies after the lanes finish, the completed reports are still used
to post the PR review.

**Review parent fails:**

* Check that each lane wrote its report in `.pan/review/<runId>/`
* Read the parent's output in the dashboard or via `GET /api/agents/agent-<issue>-review/output`
* Run `pan review restart <id>`

**Reviewers finish too quickly:**

* Check the lane report for permission or access errors
* Check that the PR has a diff against its base branch

## Related Guides

* [Terminal backend](/configuration/terminal-backend) - Reaching an agent from a shell
* [Skills](/features/skills) - Subagents and skill system
* [Specialists](/features/specialists) - Long-running specialist agents
* [Cloister](/features/cloister) - AI lifecycle management


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.