pr-review: Instructions file for Claude Code

pr-review

Generic, plugin-based PR review tool for GitHub, Azure DevOps, and GitLab, packaged as a plugin for Copilot CLI or Claude Code. Orchestrates parallel review passes — each one a skill applied by a generic agent — in a single agent session via the task tool (Copilot) / Task tool (Claude Code), retains every deduplicated finding locally, and posts every publication-eligible finding as a resolvable inline review thread (all findings by default).

Build & test

npm run build          # tsc + esbuild → dist/cli.cjs
npm run test           # node scripts/test.mjs → node --test over tests/**/*.test.ts (990 tests, ~15s — on Windows run it from Git Bash: PowerShell resolves `bash` to WSL and fails `tests/command-finder.test.ts`)
npm run test:mod       # claude plugin test mods/live → the live mod's 35 kit tests, offline, ~8 s (needs Claude Code >= 2.1.287 on PATH)
npm run validate:mod   # claude plugin validate → the module's hooks:/calls: lines; the calls line is its read-only contract
npm run build:watch    # tsc watch (re-run `npm run bundle` for esbuild)

The bundle at dist/cli.cjs is the single-file distribution artifact. The slash command (commands/pr-review.md) finds it via $CLAUDE_PLUGIN_ROOT/dist/cli.cjs under Claude Code (falling back to ~/.copilot/installed-plugins/), locates the checkout whose git origin matches the PR URL (current dir, its subdirectories, then its siblings; a primary worktree beats a linked one), prints a project-skill count that approximates the loader's rule, and runs node "$CLI" review $ARGUMENTS.

Architecture

Two-layer model: slash command → Node CLI → single agent session (Copilot CLI or Claude Code) dispatching review passes as generic agents (subagent_type/agent_type general-purpose) via task() / Task().

• src/cli.ts — commander entry, subcommand routing
• src/commands/review.ts — gather → selection → planned delivery → complete-only dedupe/post. Schema-v1 --resume validates HMAC authority, PR identity, execution-mode transition, and hashes before targeted recovery (a live PR must still be open only to publish); legacy consolidated output keeps replay support, while legacy Phase 1 is diagnostic-only.
• src/commands/status.ts / src/commands/detach.ts — authenticated live/recoverable/terminal status plus detached execution. Exit 21 means targeted recovery is possible; exit 22 is terminal.
• src/dispatch/single-session.ts — materializes context/pass/companion files and an immutable plan, emits deterministic named dispatch-only task calls, adopts uniquely identified missing Copilot sidecars, promotes attempt outputs, performs one automatic selective recovery, assembles Phase 1/final output in Node, and runs a direct conditional verifier.
• src/dispatch/delivery.ts / src/dispatch/runtime-events.ts / src/util/atomic-json.ts / src/util/control-auth.ts / src/util/finalization-lease.ts — strict Finding[] delivery, bounded top-level Copilot JSONL parsing, missing-only create-once adoption, atomic create-only canonicals, authenticated started/completed/spawn-rejected attempt lifecycles, requested/resolved model and composed runtime-error evidence, attempt ceilings, digests, non-mutating control reads, Windows transaction-safe state, HMAC authority, and one recoverer/finalizer/poster per run.
• src/dispatch/runtime.ts — runtime selection (resolveRuntime, runtimeSpawnArgs, taskCall, normalizeModel); --runtime copilot|claude|auto (default auto: probes PATH, copilot first). Planned sessions add the materialized run dir while denying posting paths. Copilot removes shell aliases from the visible tool surface, requests non-streaming JSON output, and runs with COPILOT_PLUGIN_DIR_ONLY=true (1 is ignored by Copilot CLI 1.0.84-3); Claude keeps its explicit tool allowlist. MCP is denied at the PROCESS level, not only the tool level — denying the mcp__* tools alone still lets every server boot (a cmd.exe + conhost + npx + node each on win32, every console window leaking) only to be unreachable. MCP_PROCESS_DENIAL: Record<Runtime, string> holds the per-runtime switch, so a new runtime fails to compile until it declares one. The two are NOT symmetric: claude's --strict-mcp-config is categorical (every config source ignored, and no --mcp-config is passed, so the run-dir .mcp.json is inventory/provenance only — no runtime loads it); copilot's --disable-builtin-mcps covers built-ins and is completed one name at a time by --disable-mcp-server, so its reach is bounded by discoverMcpCapabilities.
• src/util/progress.ts / src/util/posted-marker.ts — the phase/heartbeat feed and posting idempotency guard. Schema-v1 decisions use authenticated authority; posted.marker in the run dir is diagnostic only.
• mods/live/hooks/register.js — the Claude Code mod (hooks module), declared by the hooks field of .claude-plugin/plugin.json and deliberately NOT a root hooks/ dir: claude plugin test <dir> takes the mod's folder and runs every *.test.ts beneath it, so the repo root would drag the node:test suite in (observed: 60+ the file did not load). Copilot's root plugin.json never names it, and Claude Code older than 2.1.287 ignores it. It is a READER of the run dir — progress.ndjson, reviewer-progress.ndjson (the per-reviewer timeline; the mod is its first reader in production), dispatch-plan.json, delivery-state.json, passes.json, error.txt — ticked once a second (the band redraws every tick) and re-read every second tick, each file only on a size/stamp change, never status (which reaps). A run that died without a terminal phase (error.txt, newer than the last progress line) settles as failed with the pr-review status <id> hint; a file that exists but cannot be read is named on the band, never mistaken for a --context-only preview. It attaches only to a validated id (one path segment: no separator, .., leading ./- or control character — an Azure DevOps id may hold a space) that exists under the runs root: the banner a --detach launch prints at the start of stdout (past the key: value lines the launch block prints first — the model composes that block from commands/pr-review.md, so their names, order and count vary: a live session added cli: …, and a preamble pinned to two names missed the launch), a --resume <id> typed into the Bash tool, a status <id> poll when nothing live is attached, or /pr-review-live — never a dir: line or anything inside a foreground summary, because finding bodies are model output about PR content (a forged dir: would have pointed $.fs.stat at a UNC path). The slash command sends node "$CLI" review … --detach with $CLI unexpanded, so the launch is keyed on the banner, not on the command text; mods/live/tests/live.test.ts runs that literal block, and tests/mod-surface.test.ts pins it to commands/pr-review.md and the banner to src/cli.ts. The run dir is written by the CLI under the user's own account and is writable by the reviewer session itself, so the mod shows what it finds there and decides nothing from it — status and the summary stay the authoritative readings. It draws the boxed band above the prompt (title and status, a bar with one stretch of cells per reviewer coloured by state, its legend, the counts, the sources — the PR label shortens below 96 and 64 columns, and under 7 rows of room the legend and the sources go), the pr-review-live pane (reviewers grouped under their source, one row each: state, time, short name, match kind) and the spinner suffix, registers /pr-review-live [run-id | off], strips control and Unicode format characters from every name and detail it shows, logs its own failures to the debug file only ($.ui.log … { to: 'debug' }), and stays inert when session.start says isInteractive: false, because pr-review's own claude -p reviewer sessions load the user's plugins (only Copilot is isolated, INV-CTX-06). Its surface is pinned read-only by tests/mod-surface.test.ts, which also refuses a rewritten or mutated Bash event in the observer, any $ alias, and a forbidden call on any receiver.
• src/dispatch/codex.ts — optional read-only Codex sibling; strict attempt-scoped Finding[] output and crash-safe attempt accounting (opt out: --no-codex)
• src/dispatch/line-snap.ts — snaps finding line numbers to the nearest valid diff line before posting
• src/dispatch/lockfile-digest.ts — the only code that knows the package-lock.json format: reduces the two sides gather read (via PrProvider.readFileAt) to a LockfileDigest and renders ## Lockfile Digest; pure, never fetches (INV-FETCH-04's exception)
• src/dispatch/call-sites.ts — the ## Call sites section: names the declarations a diff touches and finds their references with one read-only git grep at the PR head (else local HEAD, named as such), bounded, never fetching (INV-CTX-07)
• src/providers/github.ts / azuredevops.ts / gitlab.ts — PR data fetchers + comment posters (GitHub inline comments go out as one review batch — ONE attempt, runPost owns retry because only it can reconcile — with per-comment fallback; GitLab posts per-discussion via plain fetch). Each one delivers a COMPLETE file list or says so: GitHub carries the PR's changed_files as PrMetadata.changedFileCount (its pulls/:n/files stops at 3000 entries silently) and fetches no whole-PR text diff (pulls.get with the diff media type 406s above 300 files, so it is unusable exactly on the PRs that would need it); Azure DevOps pages iteration changes to completion ($top=2000, nextSkip, a cursor that does not advance throws), drops folder entries before they can count toward the file guard, and synthesizes each patch from two whole-file getItem calls — which is why it, alone of the three, honours the content-narrowing opts of fetchChangedFiles; GitLab maps changes_count ("N+" = changedFileListTruncated, because /diffs serves exactly the capped set)
• src/dispatch/parsers.ts — JSON / bracketed-markdown / section-header output parsers
• src/dedupe.ts — Jaccard token similarity, strict/loose/off modes
• src/config.ts — 5-level config merge (flags > env > repo yaml > global yaml > defaults)
• src/util/retry.ts — retry/backoff helper for transient posting errors
• src/packs/sync.ts / load.ts — skill packs: clone/pull configured git repos into ~/.pr-review/packs/<name>/ (fail-soft; >30 days without packs sync warns on every review) and load their skill files per include/exclude globs
• src/stack/linguist.ts / manifests.ts / detect.ts — stack detection: GitHub Linguist languages.yml (auto-downloaded to ~/.pr-review/cache/, refreshed on packs sync) tags changed files by language; dependency names parsed from manifests only when cwd's git origin is the PR's repo (identity via src/providers/identity.ts, so legacy *.visualstudio.com remotes match canonical dev.azure.com); beyond the shallow root scan, changed manifests and manifests beside/above changed files are read, so a deeply nested project contributes its own dependencies; evidence stays categorized (canonical Linguist languages, ecosystems, full dependency names, dependency tokens, dependency groups) rather than collapsing into one tag bag
• src/dispatch/pass-select.ts — pass selection: project skills (repo/configured/forced) become shared CONTEXT in every pass (skills-project.md, never pass slots) — every match injects, no numeric cap, bodies inlined whole (no byte truncation); passes are ranked by EVIDENCE TIER — specific path glob > manifest-backed dependency/framework token > language-consistent type/manifest glob > exact stack tag (cap MAX_STACK_PASSES=6) — plus EVERY baseline, which is contractual and rides on top of the total pass ceiling. A product guide cannot qualify from a bare language or a generic manifest alone, and product identity tokens must co-occur in ONE dependency group. Up to two installed-plugin passes may be admitted from repository/path/topic evidence. With no pack passes, project skills become the passes; overflow + unmatched + index-mode packs get materialized bodies referenced by digest-bound skills-index.md shards.
• src/commands/packs.ts — packs list / packs sync / packs add / packs suggest subcommands
• src/plugins/loader.ts — discovers skills from standard paths (.claude/skills, .claude/rules, .copilot/skills, .github/skills, .github/instructions, .agents/skills, plus the ~/ mirrors) and from configured dirs. Follows directory links (symlinks and NTFS junctions) ONE hop, in every discovery and configured dir: a link the PR added or changed (its path, or any parent of it, is in the diff) is refused BEFORE anything behind it is read and named as degraded coverage; a link met inside a linked directory is not followed. Under a skills root a subdirectory is a skill only through <dir>/SKILL.md — a SKILL.md-less subdirectory is skipped (stderr warning when it holds .md files), flat .md files at the root are still skills, a README.md directory entry is never a skill; rules/ and instructions/ roots recurse as before. Applies rule trust before same-name dedupe, and folds semantically identical mirrors silently while still warning on divergent same-name rules. It is the only walker for repo, personal and configured dirs (packs and installed plugins have their own): walkSkillDirs/loadFromDir in src/plugins/builtin.ts were removed because a second walker meant a second link policy
• src/plugins/trust.ts — a rule file added or modified by the PR under review is UNTRUSTED input: it is dropped from both authoritative context and the on-demand index, and named as degraded coverage. Checks lexical AND real paths, so a changed later mirror cannot evict its unchanged counterpart; comparisons fold letter case and Unicode (NFC) on EVERY platform — win32-only folding let a PR committing .Agents/skills bypass a macOS reviewer. Trust is by authorship, not location: content whose real path is outside the checkout is trusted when the PR did not author the link that reaches it AND the file is committed and clean in its home git repository (git ls-files + git status; a SKILL.md also needs its whole directory clean) — the same gate applies to every rule outside the checkout (linked, configured or personal), and a repository git cannot read is skipped, never trusted — on Windows git checkout of a PR branch writes THROUGH an NTFS junction into the shared directory, so a planted file would otherwise become a trusted rule for every sibling repo's review. Untracked or modified files there are skipped and named; a directory under no git repository at all is trusted as the reviewer's local configuration (one stderr note per directory reached through a link). Nothing depends on one company's layout: any link, any discovery root, any OS, git or not. In-repo --skill files stay scoped and must live inside the checkout; --force-skill is the explicit override
• src/plugins/installed.ts — host-agnostic discovery of installed plugins from their manifests, in BOTH runtimes: Copilot CLI (~/.copilot/installed-plugins/<marketplace>/<plugin>/) and Claude Code (~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/, whose generic discovery path is read from installed_plugins.json because several versions can sit side by side). It validates active roots selected by the runtime (Copilot's config.json is JSONC; Claude's plugin list --json supplies the enabled installPath, scoped to the reviewed directory by governsCwd in companions.ts, whose manifest identity must match — the version is recorded, never adjudicated). Skills are namespaced <plugin>/<skill>; declared paths and symlinks are constrained to the plugin root. Also builds the MCP capability inventory (capabilities.json) from trusted repo config, user config, and plugin manifests
• src/providers/identity.ts — canonical checkout/PR identity: canonicalPrAuthority normalizes legacy <org>.visualstudio.com, encoded HTTPS paths, and ssh.dev.azure.com:v3/<org>/<project>/<repo> onto one authority, including the ADO project so a same-name repo in another project can't supply manifests or rules
• src/util/git.ts — gitTopLevel(); the pipeline resolves the checkout root once so a run from a subdirectory still finds repo config and rules. gitOut() / gitZ() run read-only git and THROW on failure (a failed read is never an empty result); rule provenance and the gather's truncated-list completion both go through them
• src/plugins/companions.ts — detects installed companion plugins (pr-review-toolkit, code-review); copilot via copilot plugin list, claude via claude plugin list --json, which supplies each entry's enabled status, exact installPath, and scope. That list is not cwd-filtered — run from one checkout it still reports every project-scoped install on the machine — so governsCwd drops entries whose projectPath is not the directory under review (containment, foldPath-folded: pr-review may run from a subdirectory, and the same project appeared twice differing only by drive-letter case). Reading the list as already-scoped turned an unrelated project's installs into conflicting active installations and silently dropped all 7 dispatches — and so did two records of the SAME project on different versions (Claude Code writes one per spelling, C:\… and c:\…, and updates only one of them), for 36 reviews in a week (#54). There is no conflict gate any more: every enabled record governing the directory under review becomes a root, the version string is never compared, and agreedDefinition is the integrity check — it compares the whole definition FILE (frontmatter and CRLF normalized, before any criteria extraction), so identical files across roots dispatch and divergent files drop THAT companion only, naming every root with a digest. A record whose installPath has no manifest naming the plugin is named in the Degraded block and ignored while a sibling root dispatches. Each runtime has its own registry — installing under one leaves the other empty, and --runtime auto probes copilot first, so the machine that has them under Claude Code only still dispatches zero companions. Detection failure is unknown, never "not installed"; companionReviewerNames() is the single source of up to 7 planned identities. Supplied active roots are constrained to each plugin, every root must provide agreeing definitions, and an unterminated header or shell/network/acquisition/fan-out/posting directive fails closed. Frontmatter is stripped lexically because its metadata is not execution authority — and so is a ## When to invoke section, which addresses the HOST that dispatches the agent, not the agent: the official code-reviewer.md says "Spawn this agent on the freshly written files" there, and scanning it as criteria refused the companion over prose describing its own call sites. Removed, not exempted, so nothing inside it reaches the dispatched agent either. A companion that cannot be materialized is degraded coverage, never fatal — materializeCompanionBriefs returns failures instead of throwing, and runReview drops that id from installedCompanions BEFORE the planned roster is fixed (planning it and not dispatching it is what INV-DEL-01 reads as missing output, which would turn the degradation back into an exit 2). One bad plugin .md used to abort a run holding nine healthy passes and five working companions. One companion-brief-*.md per identity is hash-bound into the plan. Every companion runs as general-purpose; code-review keeps only its materialized-diff criteria, never its native gh/posting workflow — and those criteria have TWO marketplace wordings (CODE_REVIEW_SHAPES): the claude-code-plugins HIGH SIGNAL block, and the claude-plugins-official 0–100 rubric with its 80 cutoff, which is what Claude Code's default marketplace and a team enabledPlugins list install (all 14 cached official versions). Matching only the first refused every official install for a month; tests/fixtures/code-review-command/ holds both real files byte for byte, and a body matching neither is refused naming both. The Degraded line states the cost (0 of 7 companion reviewers dispatched, N reviewer(s) lost). formatWarning takes the runtime because the install command is not portable: slash commands under claude, copilot plugin … shell commands under copilot (it has no /plugin), from marketplace anthropics/claude-code — the larger anthropics/claude-plugins-official carries the same plugins but Copilot's marketplace.json schema rejects it