Closes Sub 3 of Epic #10214 (#10217). Adds the invitation layer that pairs with the existing cross-family review mandate (pull-request §6.1, codified per #10208). Sibling-shape to manage_issue_assignees per AGENTS.md §23.

Context

The cross-family PR review mandate (#10208) requires at least one Approved review from the opposite family before merge. This is the validation mechanism. Before this PR, no corresponding invitation mechanism existed — reviewers learned about PRs needing their review via passive notification polling or manual discovery. The 7-day-open fallback fires too late as the only recourse.

This PR closes the latency gap: an active MCP-tool primitive that surfaces GitHub's requested_reviewers API to the agent surface, paired with discipline guidance in pull-request §6.1.

The Architectural Reality

GitHub's native requested_reviewers API: POST /repos/{owner}/{repo}/pulls/{pull_number}/requested_reviewers. CLI equivalent: gh pr edit <pr-number> --add-reviewer <login>.

github-workflow MCP server pattern:

• Domain services in ai/mcp/server/github-workflow/services/ (each handles a domain — PullRequest, Issue, Discussion, Label, etc.)
• toolService.mjs maps tool names → service methods via serviceMapping registry
• openapi.yaml describes the wire shape for each tool

Sibling-pattern lift: IssueService.manageIssueAssignees is the analogous tool for issue assignees. I lifted its action-dispatch shape ('add'/'remove'), error-response taxonomy ('Bad Request' / 'GitHub CLI command failed'), and gh CLI invocation pattern (--add-X / --remove-X flags).

The Fix

4 files changed (147 insertions, 0 deletions):

1. ai/mcp/server/github-workflow/services/PullRequestService.mjs (+76) — new managePrReviewers({pr_number, reviewers, team_reviewers, action}) method. Validates action enum, requires at least one of reviewers or team_reviewers, auto-prepends aiConfig.owner/ for team-reviewer slugs (gh CLI requirement), surfaces gh-CLI exit codes as GH_CLI_ERROR structured errors. Anchor & Echo JSDoc references #10217 + Sub 3 + §6.1 cross-reference.
2. ai/mcp/server/github-workflow/services/toolService.mjs (+1) — adds manage_pr_reviewers: PullRequestService.managePrReviewers to the serviceMapping registry.
3. ai/mcp/server/github-workflow/openapi.yaml (+68) — schema entry at /pulls/{pr_number}/reviewers/manage. Required action enum, optional reviewers + team_reviewers arrays. Standard 200/400/500 responses (no 403 since gh-CLI surfaces permission errors via 500/GH_CLI_ERROR instead of a pre-flight 403).
4. .agent/skills/pull-request/references/pull-request-workflow.md (+2) — §6.1 "Invitation Layer" paragraph cross-references manage_pr_reviewers and articulates the invitation-vs-validation pairing. Authors SHOULD invoke manage_pr_reviewers({action: 'add', pr_number, reviewers: ['<opposite-family-login>']}) ~2 hours after PR open if no cross-family reviewer has engaged — natural escalation step BEFORE the existing 7-day-open fallback.

Design Decision: Skipping Pre-Flight Permission Check

IssueService.manageIssueAssignees calls hasWritePermission() pre-flight to return a structured 403 FORBIDDEN early. I deliberately did NOT replicate this pattern in PullRequestService.managePrReviewers — reasons:

1. Decoupling: PullRequestService doesn't currently depend on RepositoryService's permission cache. Adding the dependency for a defensive check creates coupling without functional benefit.
2. End-to-end visibility: when gh pr edit fails on permission, the error surface is identical to the pre-flight path's FORBIDDEN — the CLI error message is just as clear (often clearer with diagnostic stderr). Caught via the existing try/catch + GH_CLI_ERROR response.
3. Forward-compat: if RepositoryService's permission API evolves, only one service changes. The pre-flight pattern in IssueService is a candidate for inverse-refactor in a future cleanup PR (file-internal vs cross-service permission caching).

Trade-off: end-user error message is slightly less structured ('GitHub CLI command failed' vs 'Permission Denied'). Acceptable; raw stderr is included in the details field.

Acceptance Criteria

• Sub 3 AC1: manage_pr_reviewers MCP tool implemented in ai/mcp/server/github-workflow/services/ with add + remove actions
• Sub 3 AC2: OpenAPI spec registration for the new endpoint
• Sub 3 AC3: pull-request §6.1 cross-references the tool as the invitation mechanism
• Sub 3 AC4: Skill reference documents the tool's placement in the cross-family mandate workflow (via §6.1 Invitation Layer paragraph)

Out of Scope (per #10217)

• Automatic reviewer assignment based on CODEOWNERS — separate mechanism; GitHub already auto-requests CODEOWNERS
• Reviewer rotation / load balancing — YAGNI until swarm grows beyond Claude ↔ Gemini
• Integration with the 7-day-open fallback's verification logic — fallback still reads get_conversation independently; invitation is orthogonal

Avoided Traps

• Extending manage_issue_assignees with a target parameter rather than a sibling tool — rejected per #10217 body's "less preferred — orthogonal surface, distinct API path."
• Pre-flight permission check — rejected per the Design Decision above (decoupling + forward-compat trade-off, structured error UX is preserved via GH_CLI_ERROR.details).
• Hardcoding reviewer login conventions — supports both reviewers (logins) and team_reviewers (slugs) per the GitHub API contract.

Related

• Parent epic: #10214
• Validation-layer mandate: #10208 (merged) + pull-request §6.1
• Sibling tool pattern: manage_issue_assignees (existing; analogous shape lifted per AGENTS.md §23)
• Sibling sub-issues in same epic: #10215 (merged via #10413), #10216 (in #10415, awaiting cycle 2 review), #10218 (in #10416, awaiting cycle 2), #10219 (Gemini's, sandman stale-detector)
• Epic-review citation: my Greenlight at https://github.com/neomjs/neo/issues/10214#issuecomment-4326402152

Cross-Family Review

Per #10208 mandate — requesting review from @neo-gemini-pro.