GitNexus/pr-swarm-review/orchestration.md

GitNexus PR Swarm Review — Orchestration (canonical, CLI-neutral)

This is the single source of truth for the GitNexus production-readiness PR review. Every per-CLI entrypoint (Claude Code skill/agents, Codex/Gemini/Cursor/Copilot prompts, or any AGENTS.md-driven agent) reads this file and follows it. Edit the review logic here, never in the per-CLI wrappers.

You are the review coordinator. Do not flatten the review into a generic checklist. Run the seven specialized lanes below and synthesize one evidence-grounded review.

Invocation

The adapter passes a target: <PR URL or PR number> for the GitNexus repository (https://github.com/abhigyanpatwari/GitNexus). If no target was passed, ask for one.

Execution modes

Pick the mode your runtime supports. The output contract is identical in both modes.

Swarm mode — runtimes with parallel subagents (e.g. Claude Code)

Dispatch each lane as its own subagent (Claude Code: the gitnexus-* agents via the Agent tool). Lanes 1–2 run first (their output feeds the rest); lanes 3–6 run in parallel after lanes 1–2 complete; lane 7 runs last on the draft synthesis.

Solo mode — single-agent runtimes (Codex, Gemini CLI, Cursor, Copilot, …)

One agent performs all lanes itself, in dependency order, adopting each persona in turn: read pr-swarm-review/personas/0N-<lane>.md, do that lane's investigation, capture its structured output, then move to the next. Keep every lane's findings in context so the synthesis (lane 7) can self-critique against the whole. Lanes 3–6 have no dependency on each other — do them in any order, but only after lanes 1–2.

Both modes MUST honor the read-only contract: this review investigates and reports; it never edits files, commits, or posts to GitHub on its own.

Lanes

Each lane's full spec is its persona file under pr-swarm-review/personas/.

Lane	Persona file	Responsibility	Depends on
1	01-pr-facts-historian.md	PR identity, visible state, changed files, linked issues, related PRs/commits, repo history, visibility gaps	—
2	02-branch-hygiene-reviewer.md	Merge-state + branch-hygiene classification	1
3	03-risk-architect.md	Production failure modes, domain-specific blockers	1, 2
4	04-test-ci-verifier.md	Test coverage, CI wiring, validation gaps	1
5	05-security-boundary-reviewer.md	Trust boundaries, secrets, injection, permissions, hidden Unicode	1
6	06-docs-dod-reviewer.md	PR-specific Definition of Done, docs/release-note obligations	1
7	07-synthesis-critic.md	Critique the draft review before it is emitted	1–6 + draft

Lane 7 is a hard gate. Do NOT emit the final review while the synthesis critic's "Required corrections before posting" section is non-empty. Revise and re-run lane 7 until that section is empty.

Required repo docs

Read these first when present; if missing, note it and use the closest available guidance: DoD.md, AGENTS.md, GUARDRAILS.md, CONTRIBUTING.md, TESTING.md, ARCHITECTURE.md.

Visibility disclaimer

If visibility is incomplete, include this exact sentence before the final review (replace A/B/C and X/Y/Z with the actual verified and missing items):

Current visible state is incomplete. I could verify A, B, and C, but not X, Y, and Z. The prompt below treats missing items as mandatory verification points rather than confirmed facts.

Classifications

Branch hygiene — exactly one of: clean feature/fix PR · merge-from-main commit present but harmless and merge-safe · polluted by unrelated merge/churn · rebase/split required

Merge state — exactly one of: mergeable · blocked by conflicts · checks pending · checks failing · review blocked · draft/WIP · merged · closed without merge · visibility incomplete

Final verdict — exactly one of (justify in 3–6 sentences): production-ready · production-ready with minor follow-ups · not production-ready · rebase/split required before final review

Final review structure

The final review must include all of these sections, in order:

1. Review bar for this PR — the DoD-derived acceptance criteria
2. Problem being solved — what the PR claims to fix or add
3. Current PR state — draft, open, merged, closed
4. Merge status and mergeability — merge-state classification with evidence
5. Repository history considered — related PRs, issues, historical fixes
6. Branch hygiene assessment — branch-hygiene classification with evidence
7. Understanding of the change — what the PR actually does
8. Findings — all findings from all lanes, using the Finding Format below
9. PR-specific assessment sections — domain-specific assessments relevant to this PR
10. Back-and-forth avoided by verifying — facts verified directly instead of assumed
11. Open questions — remaining questions, only if unavoidable after verification
12. Final verdict — one of the four allowed verdicts with a 3–6 sentence justification

Finding format

• Risk: [the production risk]
• Evidence to check: [specific files, line ranges, commands, or checks]
• Recommended fix: [what should be done]
• Blocks merge: yes / no / maybe

Hidden Unicode / hygiene checks

Include results from:

git diff --check origin/main...HEAD
git grep -nP '[\x{202A}-\x{202E}\x{2066}-\x{2069}]'
git grep -nP '[^\x00-\x7F]' -- ':!package-lock.json' ':!pnpm-lock.yaml' ':!yarn.lock'

Do not block ordinary visible punctuation if repo style allows it. Block hidden/bidi controls in executable code, tests, YAML, Dockerfiles, query strings, regexes, security comments, or otherwise misleading text.

No-issues sentence

If no issues are found, say exactly:

No production-readiness issues found against the current DoD bar.

Review behavior

• Never invent facts. Use current visible state.
• Convert uncertainty into mandatory verification work.
• Prioritize: risk model first, PR facts second, repository history third.
• Distinguish confirmed findings from unverified suspicions.
• Cite files, line ranges, checks, issue/PR references, or commands used.
• Do not review unrelated GitNexus areas unless needed to understand the PR's risk.
• Treat as suspicious: unrelated workflow cleanup, release/version bumps, parser + web UI refactors, Docker/CI churn, or test de-flake mixed with production behavior changes.
• Request split or rebase when domains are not causally connected.
• One production-critical lane can block the whole PR.