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:
- 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).
- 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.
- 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.
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.mdhad no review-loop sectionand there was no
.github/copilot-instructions.md. Before being pointed at thetemplate, an agent there:
driving the loop;
POST /requested_reviewers(HTTP 422) rather than therequestReviewsGraphQL mutation;(
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:
"PR Review Etiquette / Expected Review Loop" section and the
.github/copilot-instructions.mdrunbook into the derived repo (adaptowner/repo, drop language-specific bits).into a drop-in
.github/copilot-instructions.mdthat derived repos copyverbatim (only
owner/repoplaceholders change), with AGENTS.md referencingit.
repo, so the reliable
requestReviewsmechanism is discoverable in-reporather 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.