Skip to main content
skill CX Codex

swarm-pr-review · zaxbyhub, opencode — Claude Code skill: what it does, how to install

The swarm-pr-review skill runs a staged pull request review, checking potential defects against code evidence and challenging unsupported findings. Use it when you want broad review coverage with careful validation.

MIT ★ 539 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add ZaxbyHub/opencode-swarm --skill swarm-pr-review -a claude-code
Open on GitHub

What swarm-pr-review does

The skill starts from the exact diff, then uses repository mapping and impact analysis to guide inspection. It moves through context gathering, deterministic signals, parallel exploration, risk-family coverage, independent validation, and a critic challenge. Changes across trust or data boundaries also call for route and data tracing.

Every confirmed finding needs a file and line, an explanation of impact or reachability, and validation provenance. The workflow blocks approval when critical findings remain unresolved and records agent claims that validation disproves. Claude Code can run independent subagents; when the session cannot spawn them, the phases run as separate sequential passes.

This skill discovers new issues rather than handling existing review comments, requested changes, or CI failures; that work belongs to swarm-pr-feedback. After actionable findings are confirmed, it asks before handing off and does not start fixes automatically.

What it helps with

  • find defects in a pull request diff
  • trace changes that cross trust or data boundaries
  • challenge reviewer claims against source evidence
  • record confirmed findings with file-and-line references
  • keep fresh reviews separate from existing PR feedback

Example prompts for the agent

  • Review this pull request in depth and validate each potential finding against the code.
  • Check whether these changes introduce permission, security, or data-integrity risks.
  • Finish the review and prepare a handoff of confirmed findings to swarm-pr-feedback.

How to install swarm-pr-review

1Skills CLI (Vercel)

npx skills add ZaxbyHub/opencode-swarm --skill swarm-pr-review -a claude-code

2Manually: put the files in place

~/.claude/skills/swarm-pr-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/swarm-pr-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about swarm-pr-review

How do I install swarm-pr-review in Claude Code?

Run npx skills add ZaxbyHub/opencode-swarm --skill swarm-pr-review -a claude-code. The skill is installed at ~/.claude/skills/swarm-pr-review/SKILL.md.

What does swarm-pr-review do?

It reviews pull requests in distinct stages, using code evidence to validate suspected defects and challenge unsupported claims. Confirmed findings include a file, line, and explanation of impact.

Does swarm-pr-review fix the issues it finds?

No. It identifies new findings and asks whether to hand confirmed ones to swarm-pr-feedback, which handles existing review requests and CI failures.

Source text

SKILL.md · MIT
---
name: swarm-pr-review
description: Run a graph-guided, tool-augmented PR review using context packing, parallel exploration, mandatory repository-agnostic risk-family coverage with dispatch scaled to diff size and risk, independent reviewer validation, critic challenge, and metrics writeback. Use for deep pull request review with low false-positive tolerance and high recall in any repository, on any agent harness (structured lane controller, native parallel subagents, or single-context sequential passes).
disable-model-invocation: true
metadata:
  audience: swarm-plugin
  swarm-contract-digest: "f5ba7766c5fc"
---

# /swarm-pr-review

Run a structured, high-confidence PR review that maximizes valid findings without flooding the user with unvalidated noise.

## Graph-first evidence contract

After binding the exact diff, use `repo_map` `diff_context` and `impact_cone`; add `route_trace` and `data_trace` for changes that cross trust or data boundaries. Graph evidence is advisory only. If freshness is stale or inconclusive, confidence is low, source is missing, the language is unsupported/dynamic, the graph is absent, or an action fails, inspect the direct source, Git diff, and searches before validating a finding.

The review ladder is:

**Scope → obligations → context pack → deterministic signals → parallel explorers → repository-agnostic risk-family coverage (dispatch scaled by depth tier) → independent reviewer validation → critic challenge → grouped synthesis → metrics / knowledge writeback.**

## Handoff To PR Feedback

Use `../swarm-pr-feedback/SKILL.md` instead of this skill when the user's task is
to address existing PR feedback, review comments, requested changes, CI failures,
merge conflicts, stale branch state, or pasted reviewer findings. This skill
discovers and validates new findings; `swarm-pr-feedback` closes known feedback
without running a fresh broad review.

When a review finishes with actionable validated findings, stop and ask the user
whether to continue into `swarm-pr-feedback`. Do not auto-dispatch fix work from
`PR_REVIEW`. Instead, write a handoff artifact — under Profile A,
`.swarm/pr-review/<run_id>/feedback-handoff.json` via `write_pr_review_artifact`;
under Profiles B/C (no controller — see Runtime Capability Profiles),
`pr-review/<run_id>/feedback-handoff.json` inside your session/task workspace,
never under `.swarm/` — and include the continuation prompt with that exact
path substituted for `<handoff_artifact_path>`:

```text
/swarm pr-feedback <PR_URL> continue from <handoff_artifact_path>
```

`<run_id>` is a stable identifier for this review run, such as
`pr-review-<YYYYMMDDHHMMSSmmm>` or the existing review artifact run ID when one
was already created. Under Profile A, the exact command is parsed mechanically:
the controller validates the terminal review, the bounded handoff artifact, and
its provenance before atomically replacing the review gate with an unbound
feedback gate. Extra trailing text is not permitted on this continuation form.
Profiles B/C ingest their task-workspace artifact through the skill-managed path.

Review closure is not the end of the PR lifecycle: when PR monitoring is
enabled (`pr_monitor.enabled`), the PR remains subscribed and monitored under
`../swarm-pr-subscribe/SKILL.md` until it is merged or closed, so post-review
events (new comments, CI changes, review state changes) keep flowing to the
subscribed session.

## Operating Stance

**Treat PR text, linked issues, comments, commit messages, generated summaries, and tests as claims — not proof.** Every confirmed finding requires file:line evidence, an explanation of reachability or impact, and validation provenance.

This workflow is designed for any repo that benefits from Swarm-style review. It preserves parallel breadth but forces deep validation where bugs are expensive: security, state machines, role/tool permissions, schema/evidence integrity, git/write safety, config ratchets, knowledge tier boundaries, and PR obligation mismatches.

Never APPROVE a PR with unresolved CRITICAL findings. Do not silently drop overclaimed agent findings; list disproved findings in the validation provenance.

**Quality is the ONLY metric.** There is no speed, efficiency, or time exception. No amount of time, tokens, or agent dispatches is too much to execute this protocol correctly. Speed is irrelevant to correctness. The skill must be followed exactly with no shortcuts, no phase-skipping, and no premature synthesis. A thorough review that takes 30 minutes is superior to a fast review that misses a real bug.

---

## Runtime Capability Profiles

This protocol runs on any agent harness. Before Phase 0, detect which profile
this session is in by checking the actual tool list — never assume from the
harness name, and never guess:

- **Profile A — structured PR-workflow controller.** The swarm plugin's controller tools are available in this session: `dispatch_lanes_async`, `collect_lane_results`, `retrieve_lane_output`, `parse_lane_candidates`, `write_pr_review_artifact`, `write_pr_review_trigger_eval`, `complete_pr_workflow`, `pr_review_submission`. The child-bound `submit_pr_review_result` overlay is available only to dispatched base/micro lanes. Typical host: OpenCode with the swarm plugin. The controller mechanically enforces this skill's accounting: it computes the
  depth tier itself from the bound merge-base diff (never from caller
  claims), enforces the tier's lane floors and full dimension/family
  partitions for consolidated dispatch, and gates structured reviewer/critic
  batches and the response gate. Its acceptance rules are authoritative, and
  where the scaled-dispatch guidance below is more permissive than the
  active controller, the controller wins. Bypassing an active controller —
  blocking `dispatch_lanes`, direct Task/agent dispatch, prose verdicts — is
  BLOCKED.
- **Profile B — native parallel subagents, no controller.** The controller
  tools are absent, but the harness can spawn independent fresh-context
  subagents (for example Claude Code's `Agent`/`Task` tool, or the native
  subagent mechanisms in Codex and ZCode). Run the same phases, role
  boundaries, row contracts, and join barriers; you are the accounting layer
  the controller would otherwise be: bind the exact `pr_head_sha` in every
  lane prompt, record per-lane provenance (lane id, head SHA) on every ledger
  row, settle every lane before the next phase begins, and persist ledgers to
  files in your harness's session/task workspace. Never write runtime
  artifacts under `.swarm/` — that directory belongs to the plugin controller.
- **Profile C — single context, no subagents.** The harness cannot spawn
  independent subagents in-session. Execute the same phases as strictly
  separated sequential passes — candidate generation, then reviewer
  validation, then critic challenge — re-deriving rather than restating
  earlier reasoning in each pass, with the same ledger rows and per-family
  attestations. Disclose in the validation provenance that reviewer/critic
  independence was procedural (separate passes in one context), not
  contextual.

| Harness (typical) | Profile | Lane dispatch | Ledger persistence | Completion gate |
|---|---|---|---|---|
| OpenCode + swarm plugin | A | `dispatch_lanes_async` / `collect_lane_results` | `write_pr_review_artifact`, `write_pr_review_trigger_eval` | `complete_pr_workflow` |
| Claude Code | B | parallel `Agent`/`Task` subagents | ledger files in the session task workspace | Pre-Synthesis Gate checklist |
| OpenAI Codex | B | parallel subagents (fresh context) | ledger files in working notes | Pre-Synthesis Gate checklist |
| ZCode | B | parallel subagents (fresh context) | ledger files in working notes | Pre-Synthesis Gate checklist |

Host-native JSON-schema transport is optional and currently unregistered on the
tested host matrix, so Profile A uses the child-bound `submit_pr_review_result`
tool as its supported baseline. Any future native integration must implement
the fixed internal `promptJsonSchema({ sessionId, agent, schema, parts })` seam
and pass adapter-present, unsupported-before-execution, provider-failure,
timeout, and per-session capability tests before registration.

**Completion-gate assurance is NOT equivalent across profiles.** Only Profile A
enforces completion MECHANICALLY: the controller's `complete_pr_workflow` receipt
gate refuses synthesis unless base coverage, the 11-family trigger ledger, and the
reviewer/critic artifacts are all present and head-bound. Profiles B and C rely on
the operator executing the Pre-Synthesis Gate checklist themselves — there is no
runtime receipt gate that refuses a partial synthesis. Treat B/C as PROCEDURAL
assurance only; do not claim mechanical completion parity with Profile A for this
repository unless a controller-equivalent receipt gate is added for those profiles.

Verify each row against your own current tool list before relying on it; a
harness may gain or lose capabilities between versions. OpenCode, Claude Code,
Codex, and ZCode can all spawn fresh-context subagents in current versions —
run Profile B wherever the session actually exposes that capability; reserve
Profile C for sessions that genuinely lack a subagent mechanism, never assigning
a harness to Profile C by name alone. The absence of the controller is NOT a
BLOCKED condition — Profiles B and C are legitimate execution paths whose
completion gate is PROCEDURAL (see the note above), not the mechanically
enforced receipt gate Profile A provides.
BLOCKED is reserved for bypassing an active controller and for coverage gaps
that remain unclosable after bounded retries on any profile.

### Profile A controller quick reference

This is the concise mechanical contract for an active structured controller.
The detailed phases below explain the reasoning, but they do not override this
ordering, vocabulary, or schema.

- Base `workflow_lane` IDs (all six): `intent-architecture`,
  `correctness-state`, `tests-falsifiability`, `security-trust`,
  `reliability-performance`, `compatibility-delivery`.
- Trigger/micro `workflow_lane` IDs (all eleven): `auth-identity-secrets`,
  `untrusted-input-boundaries`, `subprocess-platform`, `concurrency-state`,
  `dependencies-build-release`, `api-schema-migrations`,
  `test-infrastructure`, `ui-accessibility-i18n`, `privacy-observability`,
  `generated-provenance`, `unclassified-risk`.
- Base candidate header:
  `[CANDIDATE] | candidate_id | lane | severity | category | file:line | claim | evidence_summary | impact_context | confidence | risk_impact | risk_tags`
- Base clean attestation:
  `[CLEAN] | lane | coverage_scope | evidence`
- Micro/council candidate header:
  `[CANDIDATE] | candidate_id | micro_lane | severity | category | file:line | claim | invariant_violated | evidence_summary | confidence | risk_impact | risk_tags`
- Micro/council clean attestation:
  `[CLEAN] | micro_lane | coverage_scope | evidence`
- Severity is exactly `INFO | LOW | MEDIUM | HIGH | CRITICAL`; confidence is
  exactly `LOW | MEDIUM | HIGH`.

Controller order is exact: bind the immutable head/base range; dispatch,
settle, and parse base lanes; evaluate every trigger row; dispatch micro lanes;
settle and parse every matched micro family; persist the trigger evaluation;
ensure each base/micro child lane submits exactly one child-bound structured
receipt; persist post-explorer findings; run reviewers;
run critics; then persist the final artifact and complete the workflow. Transcript
`[CANDIDATE]` / `[CLEAN]` rows are deprecated legacy compatibility only for
lanes whose snapped `pr_review_legacy_transcript_compatibility` contract
explicitly enables them. Candidate rows are defect claims only — never verification notes or INFO-severity confirmations (see `references/prompt-templates.md`, ## Contract addendum (2026-10-12)).
The **initial** micro dispatch MUST supply the complete trigger-evaluation
ledger; that dispatch freezes it for the session.
Any subsequent micro batch in that same session MAY omit `trigger_evaluation`
and reuse the frozen ledger. If a subsequent batch explicitly supplies a copy,
that copy MUST remain exactly identical to the frozen ledger.

All machine-readable candidate headers, candidate rows, and clean attestations
must be emitted as unfenced plain text. Markdown fences shown in this skill are
documentation fences only; emitting the backticks causes the controller to
ignore those rows as quoted/example material.

---

## Review Modes

### Default layered workflow

Always run the default layered workflow (mechanically enforced under Profile A). Explorers produce only candidates. The orchestrator does not confirm or disprove candidates.

### Council mode — opt in only

Council mode applies only when the user explicitly says one of:

- `council`
- `independent review`
- `N-agent review`
- `/council`
- `[COUNCIL MODE]`
- `[MODE: PR_REVIEW … council=true]`
- `assume all work is wrong`

Council mode supplements the default mechanical workflow; it never replaces or weakens it. Even when council mode is triggered, first complete the base-dimension coverage (the tier-floored base dispatch under Profile A — the exact-six wave at depth tier L), micro-lane ledger persistence, and every repository-agnostic risk-family evaluation at the same exact `pr_head_sha`. Route supplementary council output into the candidate ledger before independent reviewer classification. If the council request arrives after classification has begun, run the council as an additional candidate pass and dispatch a new structured reviewer batch for those candidates before synthesis.

---

## Anti-Self-Review Rule

The main thread / orchestrator MUST NOT classify, confirm, disprove, or judge explorer candidates in the default workflow.

The orchestrator may:

- determine scope,
- build or request the context pack,
- launch explorers and the full risk-family micro coverage (every family evaluated; lane count per depth tier and profile),
- extract candidates from lane artifacts via `parse_lane_candidates` (Profile A) or by collecting the structured `[CANDIDATE]` rows from lane reports (Profiles B/C),
- filter, group, and chunk candidates for reviewer dispatch,
- route candidates to reviewers,
- route reviewer-confirmed findings to critics,
- group validated findings,
- prepare the final report.

The orchestrator MUST NOT:

- re-read a candidate's target code to decide if it is valid,
- silently downgrade or discard an explorer candidate,
- treat tool output as a confirmed finding,
- report a finding that no reviewer validated,
- classify or judge candidates based on preview text alone — always use the structured parser output (Profile A) or the verbatim-collected `[CANDIDATE]` rows (Profiles B/C).

If the orchestrator catches itself validating code, it must stop and delegate validation to a reviewer subagent.

Exception: in explicit Council mode only, the main thread may act as the independent reviewer as described in the Council Mode section. Prefer a reviewer subagent when available.

---

## Scope Detection

Detailed reference material moved to `.opencode/skills/swarm-pr-review/references/scope-detection.md` (issue #2907 progressive-disclosure budget).
   `git switch --detach <full_pr_head_sha>`. Do not use `--track FETCH_HEAD`:
   `FETCH_HEAD` is not a remote-tracking branch.
6. Confirm `git rev-parse HEAD` equals the full `pr_head_sha`, bind that exact
   head (Profile A: through the first PR-review controller call; Profiles B/C:
   record it at the top of the findings ledger and repeat it in every lane
   prompt), and finish this before dispatching explorer lanes.

Detailed reference material moved to `.opencode/skills/swarm-pr-review/references/scope-detection.md` (issue #2907 progressive-disclosure budget).

## Phase 0A: Existing PR Signal Ingestion

When reviewing a PR, ingest and triage every existing signal BEFORE starting
Phase 0. These are candidate generators and obligation sources, not
pre-confirmed findings.

### PR title and body compliance check

Before deeper analysis, discover whether the repository defines a PR
publication contract (for example a local `commit-pr` skill, `CONTRIBUTING`
guidance, a PR template, or a CI check such as `pr-standards`). If it does,
verify the PR against that contract and record any gap as an advisory ledger
item. If it does not, do not invent opencode-swarm-specific title/body
sections; still verify that the PR text is not misleading about what the diff
does or proves.

At minimum, check:

- required title/body/linked-issue structure from the discovered repository
  contract,
- issue-closing, migration, release-note, invariant, or test-plan claims made
  in the PR text,
- whether those claims are supported by the actual diff and the current issue
  state.

**Issue-closing claim-integrity check:** if the PR body uses an issue-closing
keyword such as `Closes #<issue-number>`, verify (a) the issue is currently open
(`gh issue view <N> --json state` when the host is GitHub), and (b) the diff
addresses the issue's acceptance criteria (read the issue, map each criterion
to changed files/symbols, and inspect the diff for those areas). If the issue
is already closed by another merged PR, do NOT re-close it — the duplicate
closing reference is misleading. If the issue is open but the diff does not
address the acceptance criteria, mark the claim as `UNVERIFIED — claim
integrity` in the validation provenance and surface the unresolved gap to the
user before synthesis.

Contract non-compliance is a ledger item (advisory unless the repository
explicitly makes it blocking). If the PR is from an external contributor, note
the compliance gap for the maintainer to address before merge.

This intake includes:

- review comments, review summaries, requested changes, and bot findings,
- CI/check failures, annotations, and relevant logs,
- mergeability/conflicts, `mergeStateStatus`, and stale/base-drift state,
- PR body claims, linked issues, acceptance criteria, and test-plan claims,
- commit messages and app/bot commits on the PR branch.

When multiple CI/check runs have the same name, reconcile them by head SHA and
time: the latest run for the exact bound head SHA supersedes an older same-check
run on that same head. Keep an older failure only as historical diagnostic
evidence; do not report it as the current PR state after a newer same-head run
has completed successfully.

When thread resolution state matters, prefer GraphQL review-thread inspection.
If GraphQL is unavailable, keep the signal and mark
`resolution_state: UNKNOWN`; do not drop it from scope.

Detailed reference material moved to `.opencode/skills/swarm-pr-review/references/phase0a-intake.md` (issue #2907 progressive-disclosure budget).

## Phase 0B: Mergeability and Branch-State Intake

Before investing effort in review lanes, verify the PR is mergeable and record
branch-state signals. `PR_REVIEW` remains read-only: do not resolve conflicts,
commit, push, rebase, merge, or reset from this mode. Instead, carry current
mergeability, stale-head, and branch-drift facts into the review ledger and the
feedback handoff artifact.

### Step 1 — Check merge state

The field names and values below are GitHub-specific examples. On another code
host, record the equivalent mergeability, conflict, required-check, base-drift,
and stale-head signals and preserve the same read-only behavior.

```bash
gh pr view <PR_NUMBER> --json mergeable,mergeStateStatus
```

The response has two independent fields. Handle each:

**`mergeable` field** — whether GitHub can compute mergeability:
| Value | Meaning | Action |
|-------|---------|--------|
| `MERGEABLE` | No conflicts detected | Proceed — check `mergeStateStatus` below |
| `CONFLICTING` | Merge conflicts exist | Record the blocker, keep the review read-only, and hand conflict resolution to `swarm-pr-feedback` |
| `UNKNOWN` | GitHub still computing | Wait 30s, re-check |

**`mergeStateStatus` field** — overall branch state:
| Value | Action |
|-------|--------|
| `CLEAN` | All checks pass, no conflicts — proceed to Phase 0 |
| `BEHIND` | Branch behind base — note in report; non-blocking if merge queue handles it |
| `DIRTY` | Merge conflicts exist — keep reviewing, but record the conflict as a first-class blocker in the ledger and handoff artifact |
| `BLOCKED` | External blocker (branch protection, failing required check) — investigate and record the blocker |

### Step 2 — Record conflicts and blockers (when CONFLICTING or DIRTY)

When the PR has merge conflicts:

1. **Determine the PR's base branch and verify the state**, as separate
   standalone commands — never with `$(...)` command substitution, which the
   PR_REVIEW gate blocks:
   - Read the base ref: `gh pr view <PR_NUMBER> --json baseRefName` (or
     `gh_evidence` with `target: "pr"`, `fields: "baseRefName"`).
   - Fetch it by its literal value, substituted for `<base-ref>`:
     `git fetch origin <base-ref>`.
   - Re-check merge state: `gh pr view <PR_NUMBER> --json
     mergeable,mergeStateStatus,baseRefName,headRefName`.

2. **Capture the affected scope without changing the branch:**
   - List the files or subsystems implicated by the conflict if GitHub exposes them,
     or note that the exact conflict set is still unknown.
   - Identify whether the conflict appears mechanical (lockfile / generated output /
     simple overlap) or semantic (logic changed on both sides). This is triage
     signal for the follow-on feedback run, not permission to resolve it here.

3. **Record explicit next action for the handoff artifact:**
   - `CONFLICT-### | mechanical | likely resolvable during pr-feedback`
   - `CONFLICT-### | semantic | requires focused fix + validation during pr-feedback`
   - `STALE-### | behind base by policy` when the branch is only stale, not conflicted

4. **Document in report:** List the branch-state facts, why they matter to the
   review, and what `swarm-pr-feedback` must verify before it edits code.

### Conflict resolution anti-patterns
- ✗ Accepting "ours" or "theirs" for all conflicts without reading them
- ✗ Resolving semantic conflicts without understanding both sides
- ✗ Pushing resolution without running tests on the merged result
- ✗ Treating `PR_REVIEW` as the place to fix branch state — this mode stays read-only

## Phase 0B-bis: Pre-Handoff Parallel Work Snapshot

When the review surfaces findings that will likely need `swarm-pr-feedback`,
re-check for **parallel work** since the last fetch. The PR author, the bot
reviewer, or another swarm may have pushed commits while you were reviewing.
This is still read-only: capture the remote state so the handoff artifact starts
from the right branch facts.

### Step 1 — Compare remote state (read-only, no post-bind fetch)

Once the PR head is bound, the gate allows only the exact bound tracking
fetch (when one is armed), and a detached review HEAD has no tracking branch
to refetch against — `git fetch origin <pr-branch>` is blocked here. Compare
state through the read-only API instead, as one standalone command:

```bash
gh pr view <PR_NUMBER> --json headRefOid,commits
```

or the equivalent `gh_evidence` call with `target: "pr"` and
`fields: "headRefOid,commits"`. If the returned `headRefOid` differs from the
`pr_head_sha` bound at the start of this review, the remote has moved; the
`commits` field lists every commit's message and author to date, enough to
judge relevance to the pending findings. (The legitimate place to `git fetch`
is the pre-bind sequence under "Pre-flight git ref availability" above — this
step never repeats that fetch post-bind.)

### Step 2 — Evaluate new commits

For each new commit on the remote (identified by comparing `headRefOid` /
`commits` above against the SHA bound at the start of the review):

1. **Read the commit message from the `commits` field above.** For file
   scope, use one standalone read-only call —
   `gh api repos/{owner}/{repo}/commits/<sha>` — rather than a local
   `git show`: the new commit's object is not fetched locally post-bind.
2. **Compare against the pending handoff scope:**
   - Does the remote commit touch the same files as the validated findings?
   - Does the remote commit appear to already address a finding you planned to
     hand off?
   - Does the remote commit introduce a new branch-state fact the handoff should
     mention?
3. **Default stance: prefer the remote state as the next baseline.** When the
   bundled copy is available (plugin runtimes), run the
   `file:.swarm/bundled-skills/parallel-work-check/SKILL.md`
   protocol for the formal decision template; otherwise apply the three
   outcomes below directly. Record the outcome in the handoff artifact.

### Step 3 — Three outcomes

- **Parallel work supersedes:** Mark the older local checkout as stale in the
  handoff artifact and tell `swarm-pr-feedback` to re-check out the current
  remote head before editing.
- **Parallel work complements:** Carry both the validated findings and the new
  remote commits into the handoff artifact so `swarm-pr-feedback` can verify the
  combined state before patching.
- **Parallel work unrelated:** Note that the remote moved, but keep the same
  validated finding set.

### Anti-patterns

- ✗ Pushing your fix without checking if the remote already fixed it — causes
  duplicate work and may even fail the push if the commits conflict
- ✗ Force-pushing over parallel work because "I started this first" — the
  parallel agent may have access to context you don't (different swarm
  configuration, different model, different time budget)
- ✗ Blindly taking remote work without verifying it's actually better — the
  parallel work may be incomplete or take a different approach that doesn't
  match the original finding's intent

### Example: parallel swarm superseded local fix work

See `references/parallel-work-example.md` for the worked PARALLEL WORK CHECK
transcript (remote supersession, abandon-use-remote decision).

---

# Default Review Workflow

## Phase 0: Context Pack and Review Signal Collection

Before launching explorers, build a compact `swarm-pr-review-context`. Under
Profile A, do not create a scratch context-pack file after the controller gate
activates: PR_REVIEW intentionally blocks arbitrary writes. Put the bounded
shared scope, obligations, deterministic signals, and impact hints in
`common_prompt`, and require every lane to inspect the exact bound diff itself.
Under Profiles B/C, keep the context in working notes or a local artifact only
when that runtime permits the write.

The context pack must include, when available:

```json
{
  "scope": {
    "base_ref": "...",
    "head_ref": "...",
    "commit_range": "...",
    "changed_files": [],
    "changed_hunks": [],
    "public_api_changes": [],
    "deleted_or_renamed_files": [],
    "generated_files": []
  },
  "pr_metadata": {
    "title": "...",
    "body_claims": [],
    "checkboxes": [],
    "linked_issues": [],
    "review_comments": [],
    "commit_messages": []
  },
  "obligations": [],
  "repo_graph": {
    "source": ".swarm/repo-graph.json or fallback search",
    "changed_symbols": [],
    "callers": [],
    "callees": [],
    "imports": [],
    "exports": [],
    "sibling_implementations": []
  },
  "deterministic_signals": {
    "ci": [],
    "tests": [],
    "coverage_delta": [],
    "lint_typecheck_build": [],
    "security_scanners": [],
    "dependency_audit": [],
    "secrets_scan": [],
    "mutation_testing": []
  },
  "swarm_artifacts": {
    "evidence_bundles": [],
    "knowledge_hits": [],
    "phase_state": [],
    "metrics": []
  },
  "risk_triggers": []
}
```

### Context pack rules

- Diff-only review is allowed for quick orientation, but not enough to confirm nontrivial findings.
- For every changed production file, identify at least one caller, consumer, import path, route entrypoint, or reason none exists.
- If `.swarm/repo-graph.json` exists, use it to seed impact cones.
- If no repo graph exists, build a shallow impact cone using imports, exports, symbol search, route registration, CLI registration, or test references.
- Pull in relevant `.swarm/evidence/`, `.swarm/state`, `.swarm/knowledge`, or hive/project knowledge entries when present.
- Historical knowledge may guide candidate generation but cannot confirm a finding by itself.
- Mark stale, quarantined, or cross-project knowledge as advisory until independently verified in this repo.

---

## Review Finding Persistence

Do not rely on conversation context to preserve review findings. On Profile A,
use `write_pr_review_artifact` with `kind: "findings"`; the controller creates
and appends `.swarm/pr-review/<run_id>/findings.jsonl` without granting generic
write authority over `.swarm/`. On Profiles B/C, append the same records to a
`findings.jsonl` ledger in your harness workspace (never under `.swarm/`), with
the review head SHA recorded at the top.

Each persisted finding record must include at least:

```json
{"finding_id":"F-001","status":"PENDING","file_line":"src/file.ts:123","evidence":"quote, command output, lane id, or reviewer rationale","next_action":"route_to_reviewer","severity":"HIGH"}
```

Minimum field contract:

- `finding_id`: stable ID from the candidate/reviewer/critic ledger.
- `status`: one of `PENDING`, `CONFIRMED`, `DISPROVED`, or `PRE_EXISTING`.
- `file_line`: exact `file:line`, or `N/A` with reason when cross-file.
- `evidence`: compact source-backed proof (lane/reviewer/critic IDs or command output references when available).
- `next_action`: `route_to_reviewer`, `route_to_critic`, `report`, `suppress_with_reason`, or `handoff_to_feedback`.
- `severity`: REQUIRED at every boundary — omitting it is a violation, not a shortcut. Vocabulary is the VERDICT dialect `INFO|LOW|MEDIUM|HIGH|CRITICAL|NONE`. At `post_explorer` it must equal the severity of the `[CANDIDATE]` row the record projects (so never `NONE`, which no ca...

© ZaxbyHub · MIT · ZaxbyHub/opencode-swarm

Similar skills

All skills for Code review and refactoring →

swarm-pr-review by other authors comes first.

swarm-pr-review ZaxbyHub swarm-pr-review is a Claude Code skill that connects the canonical .opencode workflow to PR review sessions. CX Codex +1 ★ 539repo stars swarm-pr-review ZaxbyHub The swarm-pr-review skill for Claude Code and Codex is a thin adapter for swarm pull request reviews that delegates execution to the canonical workflow in .opencode. CX Codex +1 ★ 539repo stars gitnexus-pr-swarm-review abhigyanpatwari The gitnexus-pr-swarm-review skill splits a pull request review across seven subagents and assembles a production-readiness report. It is built for on-demand PR analysis. CX Codex +1 438installs code-review-swarm ruvnet code-review-swarm sends a pull request through several review agents at once: security, performance, style, architecture. Handy when a plain diff and a linter no longer catch the trouble. CX Codex +1 ★ 850repo stars review-swarm Dimillian review-swarm runs a parallel read-only review of a git diff or selected files. Use it to surface regressions, security concerns, and missing test coverage before merging. CX Codex +1 820installs code-review official anthropics The code-review skill reviews diffs and pull requests for security, performance and correctness. Useful when a change needs a look before merging. CX Codex +1 10,300installs alan-review-pr tryalan-ai alan-review-pr automates GitHub pull request reviews using Alan MCP tools, posting structured summaries and inline feedback directly to the PR. CX Codex +1 1,800installs github-code-review ruvnet github-code-review is a Claude Code skill that reviews GitHub pull requests with specialized AI agents. It checks security, performance, architecture, and code style. CX Codex +1 1,300installs

From the same set121

The whole set →
swarm-ci-monitor swarm-ci-monitor is a Claude Code skill that monitors approved PRs, diagnoses CI failures, applies fixes for up to five cycles, and merges when required checks pass. CX Codex +1 ★ 539repo stars engineering-conventions engineering-conventions enforces non-negotiable engineering invariants for opencode-swarm development. It prevents initialization hangs, Bun mock leakage, and Node ESM runtime failures. CX Codex +1 ★ 539repo stars phase-wrap The phase-wrap skill guides phase closure with evidence checks, a retrospective, and conditional spec-drift review. It fits projects that use the swarm workflow. CX Codex +1 ★ 539repo stars graphify Turns a folder of code, docs, papers, images and video into a persistent knowledge graph you can question through /graphify. CX Codex +1 ★ 539repo stars execute execute provides a formal execution protocol covering scope boundaries, QA gates, and coder retry lifecycles in agent swarms. CX Codex +1 ★ 539repo stars swarm-plan The swarm-plan skill sets out a workflow for checking project evidence, specs, and task traceability before saving a plan. Use it when breaking project work into tasks. CX Codex +1 ★ 539repo stars writing-tests writing-tests is a Claude Code skill that sets test conventions for opencode-swarm. It loads before an agent edits a test file. CX Codex +1 ★ 539repo stars swarm-pr-feedback swarm-pr-feedback — a skill for ingesting and resolving PR comments, CI failures, and branch conflicts with strict source code verification. CX Codex +1 ★ 539repo stars

Project sponsors

Companies that keep this analytics open