Skip to content

Propagate the Copilot review-loop contract + runbook to derived repos #117

Description

@ptr727

Summary

The Copilot review-loop contract (AGENTS.md → "Expected Review
Loop") and the provider mechanics (.github/copilot-instructions.md
→ "GitHub Copilot Review Runbook") live only in ProjectTemplate. Repos derived
from the template do not carry these files, and the "Quick Start for Derived
Projects" checklist doesn't tell you to copy or reference them. So an AI agent
working in a derived repo has no in-repo pointer to the reliable Copilot
interaction mechanics and falls back to ad-hoc behavior.

This is the same class of gap as #116 (the markdownlint config not propagating to
derived repos).

Evidence

In the derived repo ptr727/KiCadLibrary, AGENTS.md had no review-loop section
and there was no .github/copilot-instructions.md. Before being pointed at the
template, an agent there:

  • waited for the maintainer to manually re-request Copilot review instead of
    driving the loop;
  • tried the known-no-op POST /requested_reviewers (HTTP 422) rather than the
    requestReviews GraphQL mutation;
  • filtered REST comment queries by the GraphQL login form
    (copilot-pull-request-reviewer, no [bot]), which silently returned nothing,
    so it missed a whole review round.

Every one of these is already documented correctly in the template's runbook — the
agent just had no reason to look there from inside the derived repo.

Recommendation

The runbook content itself is clear; the fix is propagation + discoverability:

  1. Add to "Quick Start for Derived Projects" an explicit step: carry the AGENTS.md
    "PR Review Etiquette / Expected Review Loop" section and the
    .github/copilot-instructions.md runbook into the derived repo (adapt
    owner/repo, drop language-specific bits).
  2. Alternatively, factor the provider-agnostic loop contract + the Copilot runbook
    into a drop-in .github/copilot-instructions.md that derived repos copy
    verbatim (only owner/repo placeholders change), with AGENTS.md referencing
    it.
  3. State plainly that the review-loop contract is mandatory in every derived
    repo
    , so the reliable requestReviews mechanism is discoverable in-repo
    rather than only in the template.

A short note in AGENTS.md ("derived repos must inherit this section and the
runbook") would have prevented the failure above.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions