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:

# 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.

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:

Reads all four reports
Removes duplicates: the same issue found by more than one reviewer
Weighs the findings: severity, code citations, tests and requirement coverage
Writes .pan/review/<runId>/synthesis.md
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  or , naming the commit it reviewed when that commit is still the head. See 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:

# 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

# 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. CLI:

# 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.

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.

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:

# 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

Terminal backend - Reaching an agent from a shell
Skills - Subagents and skill system
Specialists - Long-running specialist agents
Cloister - AI lifecycle management

​Convoys: Parallel Code Review

​Why Convoys?

​Quick Start

​How the Review Convoy Works

​Phase 1: Specialized Reviews (Parallel)

​Phase 2: Synthesis

​What is Synthesis?

​Review modes

​Review Commands

​Review Lifecycle

​Monitoring Convoys

​Use Cases

​Best Practices

​Troubleshooting

​Related Guides