pr-swarm-review/orchestration.md
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.
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.
Pick the mode your runtime supports. The output contract is identical in both modes.
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.
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.
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.
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.
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.
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
The final review must include all of these sections, in order:
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.
If no issues are found, say exactly:
No production-readiness issues found against the current DoD bar.