docs(pr-review): orchestrator split — ADR, PRD, and issues

apps/claude-code/pr-review/CONTEXT.md

@@ -77,6 +77,34 @@ _Avoid_: merger, aggregator, deduplicator
 A self-contained plugin agent that orchestrates the entire Doc Context gathering phase — fetching work item details, running the Confluence credential check once, spawning Work Item Summarizer and Confluence Fetcher agents in parallel, and delegating final synthesis to the Doc Context Synthesizer. Returns the Synthesizer's output verbatim as a plain markdown string.
 _Avoid_: context orchestrator, doc orchestrator, gathering agent
 
+### Operating modes
+
+**Pre-PR mode**:
+A Review run without a PR URL, targeting a local branch diff. No ADO write-back occurs; findings are presented in the Claude interface only.
+_Avoid_: local review, offline review, draft review
+
+**First-review mode**:
+A Review run against an ADO PR where no prior Bot Signature is found. Produces a full set of Inline Comments and a Review Summary posted to ADO.
+_Avoid_: initial review, fresh review
+
+**Re-review mode**:
+A Review run against an ADO PR where a prior **Bot Signature** is found in the PR's threads. Focuses on commits since the last Review, performs Thread Classification, and replies to or resolves existing Review Threads rather than duplicating them.
+_Avoid_: incremental review, follow-up review, second pass
+
+### Orchestration agents
+
+**ADO Fetcher**:
+A plugin agent that retrieves PR metadata, iterations, changed files, and the raw diff from Azure DevOps. Used by first-review and re-review modes; not invoked in pre-PR mode.
+_Avoid_: fetcher, data agent, ADO client
+
+**Re-review Coordinator**:
+A plugin agent that owns the full re-review state machine — prior thread detection, partial-run check, Thread Classification, finding matching, and reply posting to classified threads. Invoked only in re-review mode.
+_Avoid_: re-review agent, rereview handler
+
+**ADO Writer**:
+A plugin agent responsible for all ADO write-back operations — posting Inline Comments, patching thread status, and posting the Review Summary or delta reply. Used by first-review and re-review modes.
+_Avoid_: writer agent, comment poster, ADO publisher
+
 ### Re-review classification
 
 **Thread Classification**:
@@ -106,6 +134,9 @@ A Thread Classification state. The relevant code was deleted or moved; the comme
 - A **Doc Context** is assembled via a three-tier pipeline: the **Doc Context Orchestrator** spawns **Work Item Summarizer** and **Confluence Fetcher** agents (Doc Context Sub-agents) in parallel, then delegates their outputs to the **Doc Context Synthesizer**, which produces the final `DOC_CONTEXT` narrative injected into every Review Aspect agent
 - A **Doc Context Sub-agent** operates on a single source (work item or Confluence page) and receives the changed files list and the local diff when available
 - The **Doc Context Orchestrator** returns the **Doc Context Synthesizer**'s output verbatim; it does not rewrite or reformat the narrative
+- The **ADO Fetcher** is invoked by first-review and re-review modes; **Pre-PR mode** skips it entirely and goes directly to Review Aspect agents
+- The **Re-review Coordinator** is invoked only when the mode is re-review; first-review and pre-PR modes never load it
+- The **ADO Writer** is invoked by first-review and re-review modes; **Pre-PR mode** does not write back to ADO
 
 ## Example dialogue
 

apps/claude-code/pr-review/docs/adr/0013-orchestrator-split-for-review-pr.md

@@ -0,0 +1,57 @@
+# 0013. Split review-pr.md into a thin orchestrator and focused agents
+
+**Status:** Accepted (2026-05)
+
+## Context
+
+`review-pr.md` has grown to ~1000 lines as the re-review state machine, ADO write-back logic, and doc-context orchestration were added. This creates two compounding problems:
+
+1. **Token budget pressure.** The full command file is loaded into the parent context on every invocation. Combined with tool-call results flowing back from parallel review agents, average PR reviews reach +100 K tokens — unsustainable as the command grows further.
+
+2. **Growth risk.** A pre-PR mode (review without opening a PR) is an emerging user request. Adding a third operating mode to the current monolith would push the file toward ~1300 lines and worsen the token problem.
+
+The root cause is architectural: `review-pr.md` conflates orchestration (which mode are we in? what agents to launch?) with platform integration (fetch ADO threads, post inline comments) and re-review state management (classify threads, match findings, reply).
+
+The GitHub PR review workflow (`.claude/prompts/pr-review-workflow.prompt.md`) solves the same orchestration problem in ~80 lines by staying a thin coordinator and delegating everything else to focused agents. That pattern is the right model for `review-pr.md`.
+
+## Decision
+
+Refactor `review-pr.md` into a **thin orchestrator** of ~200 lines that:
+
+1. Validates prerequisites and parses the PR URL (or detects absence of URL for pre-PR mode).
+2. Detects the operating mode: **pre-PR**, **first-review**, or **re-review**.
+3. Delegates immediately to a focused agent per mode.
+
+Three focused agents live in the plugin's `.agents/` directory (not in `pr-review-toolkit`, which is a read-only dependency):
+
+- **`pr-review:ado-fetcher`** — fetches PR metadata, iterations, changed files, and raw diff from ADO. Used by first-review and re-review modes.
+- **`pr-review:re-review-coordinator`** — owns Steps 3.5–10-Path-B: prior thread detection, partial-run check, thread classification, finding matching, and reply posting to classified threads. Used only in re-review mode.
+- **`pr-review:ado-writer`** — owns the ADO write-back pipeline: posting inline threads, patching thread status, and posting the summary comment. Used by first-review and re-review modes.
+
+Pre-PR mode skips the ADO fetcher and writer entirely; it goes straight from the orchestrator to the `pr-review-toolkit` review agents and presents findings locally.
+
+**Compact sub-agent output.** Review agents (`pr-review-toolkit:code-reviewer`, etc.) are asked via the Step 8 prompt in `review-pr.md` to return structured findings (`severity`, `filePath`, `startLine`, `endLine`, `title`, `body`) rather than prose with embedded code quotes. This keeps what flows back into the parent context small. This guidance stays in `review-pr.md`'s prompt, not in the toolkit agent definitions, because `pr-review-toolkit` is not owned by this plugin.
+
+**Re-review logic ownership.** The four Node.js modules in `scripts/re-review/` are already algorithmically platform-agnostic; only their input shapes are ADO-specific. When a second write-back platform (GitHub) is built, normalising to a canonical thread shape and lifting these modules to `pr-review-toolkit` is the correct move. That work is deferred until a second platform consumer exists.
+
+**Alternatives considered:**
+
+_Keep the monolith_ — continue adding to `review-pr.md`. Rejected because the token budget problem compounds with each new feature, and the pre-PR mode would require significant branching inside an already large file.
+
+_Lift re-review modules to pr-review-toolkit now_ — move the four Node.js modules to the toolkit as shared library code. Rejected because there is no second platform consumer yet; any canonical thread schema designed now would be speculative and likely wrong.
+
+_Option B: re-review coordinator as a procedural agent_ — keep re-review logic in a dedicated agent that reasons about edge cases rather than pure procedural code. Accepted in part: the `pr-review:re-review-coordinator` agent replaces the procedural inline steps, but the four Node.js modules remain as pure functions called from it.
+
+## Consequences
+
+- The parent context for a first-review or pre-PR run no longer loads re-review logic.
+- Each focused agent only receives the context it needs; intermediate state (prior threads JSON, classification results, diff hunks) does not accumulate in the orchestrator context.
+- Adding a fourth operating mode (e.g. post-merge audit) requires only a new agent plus a new branch in the ~200-line orchestrator.
+- The three new agents must be documented in the plugin's `CONTEXT.md` under the appropriate relationship entries.
+
+**See also:**
+
+- `docs/issues/pr-review-orchestrator-split/PRD.md` for the feature PRD and implementation issues that deliver this split
+- ADR 0008 (soft dependency on `pr-review-toolkit`)
+- `.claude/prompts/pr-review-workflow.prompt.md` (the GitHub orchestrator pattern this
+  mirrors)

docs/issues/pr-review-orchestrator-split/01-create-ado-fetcher-agent.md

@@ -0,0 +1,65 @@
+# Create ADO Fetcher agent
+
+**Status:** ready-for-agent
+**Category:** enhancement
+
+## Parent
+
+`docs/issues/pr-review-orchestrator-split/PRD.md`
+
+## What to build
+
+Create a new plugin agent (`pr-review:ado-fetcher`) that encapsulates all Azure DevOps read operations required for a PR review. The agent receives a PR URL (org, project, PR ID) and returns a structured context block containing: PR metadata (title, description, source/target branches, repo ID), latest iteration ID and its commit SHA, prior commit SHA (passed in for re-review, empty for first-review), changed files list, raw diff, and work-item IDs linked to the PR.
+
+This agent replaces the inline ADO shell commands currently scattered across Steps 2–5 of the `review-pr` command. It is invoked by first-review and re-review modes; pre-PR mode never calls it.
+
+The ADO Fetcher and the Doc Context Orchestrator agent must be invocable concurrently — the ADO Fetcher provides the work-item IDs that the Doc Context Orchestrator needs, so the Fetcher runs first, but the Fetcher and Doc Context Orchestrator may overlap in wall-clock time.
+
+## Acceptance criteria
+
+- [ ] The agent accepts PR URL components (org URL, project, PR ID) and returns a structured context block
+- [ ] The context block includes PR metadata, latest iteration ID, latest commit SHA, changed files list, and raw diff
+- [ ] The context block includes the work-item IDs linked to the PR (empty list if none)
+- [ ] The agent handles the case where no iterations are returned (defaults gracefully)
+- [ ] The agent handles PRs that are already merged (continues without error)
+- [ ] The agent contains no write operations — it is purely a read agent
+
+## Blocked by
+
+None — can start immediately.
+
+---
+
+## Agent Brief
+
+> _This was generated by AI during triage._
+
+**Category:** enhancement
+**Summary:** Create the `pr-review:ado-fetcher` agent that encapsulates all ADO read operations for a PR review.
+
+**Current behavior:**
+ADO read operations (PR metadata, iterations, changed files, diff, work-item IDs) are scattered as inline `az devops invoke` shell commands across multiple steps of the `review-pr` command. There is no dedicated agent for this concern.
+
+**Desired behavior:**
+A new plugin agent (`pr-review:ado-fetcher`) accepts PR URL components and returns a single structured context block. All other agents and the orchestrator consume this block rather than making their own ADO calls. The agent is purely read-only — it performs no write operations.
+
+**Key interfaces:**
+
+- Input: org URL, project, PR ID, optional prior commit SHA (passed in for re-review)
+- Output: structured context block — PR metadata, latest iteration ID, latest commit SHA, changed files list, raw diff, work-item IDs list
+- The agent must handle zero-iteration PRs and already-merged PRs gracefully
+
+**Acceptance criteria:**
+
+- [ ] The agent accepts PR URL components and returns a structured context block
+- [ ] The context block includes PR metadata, latest iteration ID, latest commit SHA, changed files list, and raw diff
+- [ ] The context block includes the work-item IDs linked to the PR (empty list if none)
+- [ ] The agent handles the case where no iterations are returned (defaults gracefully)
+- [ ] The agent handles PRs that are already merged (continues without error)
+- [ ] The agent contains no write operations — it is purely a read agent
+
+**Out of scope:**
+
+- Any ADO write operations
+- Doc Context fetching (that stays with the Doc Context Orchestrator)
+- GitHub or GitLab platform support

docs/issues/pr-review-orchestrator-split/02-create-ado-writer-agent.md

@@ -0,0 +1,72 @@
+# Create ADO Writer agent
+
+**Status:** ready-for-agent
+**Category:** enhancement
+
+## Parent
+
+`docs/issues/pr-review-orchestrator-split/PRD.md`
+
+## What to build
+
+Create a new plugin agent (`pr-review:ado-writer`) that encapsulates all Azure DevOps write-back operations for a PR review. The agent receives: PR context (org URL, project, repo ID, PR ID, latest iteration ID, summary thread ID), a list of compact findings, and a mode flag (first-review or re-review).
+
+For each finding it posts a new Inline Comment thread to ADO. After all findings are posted it posts the Review Summary on first-review, or a delta reply to the existing summary thread on re-review. As its final action it posts the completion marker reply to the summary thread.
+
+The compact finding schema the agent accepts: `{ severity, filePath, startLine, endLine, title, body }`. Every comment posted must end with the canonical Bot Signature trailer `---\n🤖 *Reviewed by Claude Code* — Iteration N`.
+
+This agent is used by both first-review and re-review modes. It is not invoked in pre-PR mode.
+
+## Acceptance criteria
+
+- [ ] The agent posts one Inline Comment thread per finding at the correct file path and line range
+- [ ] Each posted comment ends with the canonical Bot Signature including the iteration number
+- [ ] On first-review, the agent posts a full Review Summary as a new general thread
+- [ ] On re-review with at least one new finding, the agent posts a delta reply to the existing summary thread
+- [ ] On re-review with zero new findings, the agent skips the summary reply
+- [ ] The agent posts a completion marker reply (`✅ Review complete — Iteration N`) to the summary thread as its final action
+- [ ] If `threadContext` is rejected by ADO (file not in diff), the agent retries without `threadContext` (general comment fallback)
+- [ ] The agent returns the final `SUMMARY_THREAD_ID` and `FINDINGS_POSTED` count to the caller
+
+## Blocked by
+
+None — can start immediately.
+
+---
+
+## Agent Brief
+
+> _This was generated by AI during triage._
+
+**Category:** enhancement
+**Summary:** Create the `pr-review:ado-writer` agent that encapsulates all ADO write-back operations for a PR review.
+
+**Current behavior:**
+ADO write operations (posting Inline Comment threads, patching thread status, posting the Review Summary, posting the completion marker) are inline shell commands in `review-pr.md`. There is no dedicated agent for write-back.
+
+**Desired behavior:**
+A new plugin agent (`pr-review:ado-writer`) receives a PR context block, a compact findings list, a mode flag, and an optional existing summary thread ID. It posts all Inline Comments, the Review Summary (or delta reply on re-review), and the completion marker. Every comment ends with the canonical Bot Signature.
+
+**Key interfaces:**
+
+- Input: PR context (org URL, project, repo ID, PR ID, latest iteration ID, summary thread ID), findings list as `{ severity, filePath, startLine, endLine, title, body }[]`, mode (`first-review` | `re-review`)
+- Output: `{ summaryThreadId, findingsPosted }` returned to the caller
+- Bot Signature constant: `🤖 *Reviewed by Claude Code*` prefix — must not change
+- On `threadContext` rejection by ADO, retries without `threadContext` (general comment fallback)
+
+**Acceptance criteria:**
+
+- [ ] The agent posts one Inline Comment thread per finding at the correct file path and line range
+- [ ] Each posted comment ends with the canonical Bot Signature including the iteration number
+- [ ] On first-review, the agent posts a full Review Summary as a new general thread
+- [ ] On re-review with at least one new finding, the agent posts a delta reply to the existing summary thread
+- [ ] On re-review with zero new findings, the agent skips the summary reply
+- [ ] The agent posts a completion marker reply to the summary thread as its final action
+- [ ] If `threadContext` is rejected by ADO, the agent retries without `threadContext`
+- [ ] The agent returns the final `summaryThreadId` and `findingsPosted` count
+
+**Out of scope:**
+
+- Reply posting for re-review classified threads (that is the Re-review Coordinator's responsibility)
+- Pre-PR mode (no ADO calls in that mode)
+- Reading or fetching any ADO data