zaxbyhub/opencode-swarm/baseline

/swarm-pr-review

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

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>:

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

<run_id> is a stable identifier for this review run, such as pr-<number>-<YYYYMMDDHHMMSS> 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. 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.

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, and reserve Profile C for sessions that genuinely lack a subagent mechanism; never assign a harness to Profile C by name alone. The absence of the controller is NOT a BLOCKED condition — Profiles B and C are first-class execution paths, not degraded fallbacks. BLOCKED is reserved for bypassing an active controller and for coverage gaps that remain unclosable after bounded retries on any profile.

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

Determine review scope using this priority:

1. explicit user-provided PR URL, PR number, commit, branch, or file scope,
2. current feature branch diff vs the remote-tracking base ref (origin/main,

origin/master; a local main/master only as a last resort — it is only as fresh as the last fetch and yields a different merge base),

1. staged changes,
2. latest commit,
3. user-specified files or directories.

Record:

• base ref,
• head ref,
• commit range,
• changed files,
• deleted files,
• generated files,
• lockfiles,
• test files,
• docs/config/schema files,
• whether the working tree is dirty.

If scope cannot be determined, review the narrowest safe scope available and state the limitation.

Pre-flight git ref availability

Before launching explorers (Phase 3), perform this exact standalone sequence: