pr-review AGENTS.md

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), and posts every finding back to the PR as a resolvable inline review thread.

Build & test

npm run build          # tsc + esbuild → dist/cli.cjs
npm run test           # node scripts/test.mjs → node --test over tests/**/*.test.ts (566 tests, ~15s)
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 files and an immutable plan, emits description-bearing dispatch-only task calls, 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/util/atomic-json.ts / src/util/control-auth.ts / src/util/finalization-lease.ts — strict Finding[] delivery, atomic create-only canonicals, 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). runtimeSpawnArgs adds the materialized run dir and checkout root as readable directories while denying shell and posting paths.
• 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.
• 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/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)
• 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 authoritative installPath is read from installed_plugins.json because several versions can sit side by side). 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
• src/plugins/companions.ts — detects installed companion plugins (pr-review-toolkit, code-review); copilot via copilot plugin list, claude via ~/.claude/plugins/installed_plugins.json. Detection failure is unknown, never "not installed"; companionReviewerNames() is the single source of the 7 planned dispatch names (6 toolkit agents + 1 code-review slash command), reconciled against delivered outputs in companions.json