[pr-review-doc-context-spawn-reliability] Doc Context Orchestrator agent

[orioltf]

Type: AFK

Parent

docs/issues/pr-review-doc-context-spawn-reliability/PRD.md

What to build

Create the Doc Context Orchestrator agent — a new self-contained plugin agent that handles the entire Doc Context gathering phase in its own context window. It receives: ORG_URL, PR_ID, a list of work item IDs, the full diff, the changed files list, and the absolute path to confluence-client.mjs (pre-expanded by the caller — agents do not inherit env vars).

The agent must:

1. Fetch each work item via az boards work-item show. Skip and warn on failure.
2. Branch on work item type: Bug → extract Microsoft.VSTS.TCM.ReproSteps + Microsoft.VSTS.TCM.SystemInfo; all other types (including unrecognised) → System.Description.
3. Spawn one Work Item Summarizer agent per work item in parallel. Each summarizer receives the work item content, changed files, and diff; returns a plain-text summary and a list of Confluence URLs found in the description.
4. Run node {CONFLUENCE_CLIENT_PATH} --check-creds exactly once. If creds are absent and Confluence URLs were found: emit the standard warning to console and skip all Confluence fetching.
5. If creds are available: collect all unique Confluence URLs across all summarizer outputs and spawn one Confluence Fetcher agent per unique URL in parallel. Each fetcher runs node {CONFLUENCE_CLIENT_PATH} {URL} and returns a plain-text summary or emits a warning and returns nothing on failure.
6. Pass all summarizer and fetcher outputs to the Doc Context Synthesizer agent.
7. Return the synthesizer's output verbatim as plain markdown — no JSON wrapper.

Acceptance criteria

• .agents/doc-context-orchestrator.md exists as a plugin agent file.
• The agent prompt references pr-review:doc-context-synthesizer for the final synthesis step.
• Bug work items: prompt instructs extraction of ReproSteps + SystemInfo, not System.Description.
• Unrecognised work item types: prompt instructs fallback to System.Description.
• Credential check runs exactly once (not per fetcher, not per work item).
• All paths to confluence-client.mjs in the prompt are described as absolute literal strings passed in by the caller — no relative paths, no env-var references inside the agent.
• Console warnings (failed work item fetch, missing creds, failed Confluence fetch) are printed as side effects; none appear in the agent's return value.
• The agent returns plain markdown (the synthesizer's output verbatim), consistent with ADR-0012.

Blocked by

#70 — synthesizer interface must be settled before this agent references it.

---

Agent Brief

This was generated by AI during triage.

Category: enhancement
Summary: Create the Doc Context Orchestrator agent — self-contained gathering phase in its own context window

Current behavior:

The agent file does not exist. Step 4a currently satisfies doc-context intent inline with no Agent() spawn call, so no orchestrator runs and no business context is gathered.

Desired behavior:

.agents/doc-context-orchestrator.md exists as a plugin agent. When invoked, it receives ORG_URL, PR_ID, a list of work item IDs, the full diff, the changed files list, and CONFLUENCE_CLIENT_PATH (absolute path, pre-expanded by the caller). It orchestrates the entire Doc Context gathering phase and returns the Doc Context Synthesizer's output verbatim as plain markdown.

Key behavioural contracts:

• Per work item: fetch via az boards work-item show; branch on type (Bug → ReproSteps + SystemInfo, all others → System.Description); skip + warn on failure
• Spawn one Work Item Summarizer agent per work item in parallel
• Run --check-creds exactly once; if creds absent and Confluence URLs found, emit the standard warning and skip all fetching
• If creds present: deduplicate Confluence URLs across all summarizer outputs, spawn one Confluence Fetcher agent per unique URL in parallel
• Delegate all outputs to pr-review:doc-context-synthesizer; return its output verbatim
• All confluence-client.mjs paths are the absolute literal string received as input — no env-var references inside the agent prompt

Key interfaces:

• doc-context-orchestrator plugin agent — inputs: ORG_URL, PR_ID, work item ID list, diff, changed files, CONFLUENCE_CLIENT_PATH (absolute string); output: plain markdown block or empty string
• pr-review:doc-context-synthesizer — called as the final step; must be implemented first (issue 01)
• Work Item Summarizer agents — spawned inline (anonymous), not as named plugin agent types

Acceptance criteria:

• .agents/doc-context-orchestrator.md exists as a plugin agent file
• Prompt references pr-review:doc-context-synthesizer for the final step
• Bug work items use ReproSteps + SystemInfo; all other types use System.Description
• Credential check runs exactly once — not per fetcher, not per work item
• All confluence-client.mjs paths in the prompt are absolute literal strings from the caller — no relative paths
• Warnings are printed as side effects; none appear in the return value
• Agent returns plain markdown consistent with ADR-0012

Out of scope:

• Changes to commands/review-pr.md (issue 03)
• Changes to confluence-client.mjs or its tests
• GitHub PR support, caching, or Jira sources

---

PRD: docs/issues/pr-review-doc-context-spawn-reliability/PRD.md
Migrated from: docs/issues/pr-review-doc-context-spawn-reliability/02-orchestrator-agent.md (source removed after migration)
Touched by PRs: #23, #25