Clarify project rules belong in AGENTS.md, harden Copilot review runbook - #174
Merged
Conversation
Two template-doc gaps surfaced while re-syncing ptr727/LanguageTags. #173: copilot-instructions.md was described as a narrow drop-in but never said where project-specific rules go instead, so a derived repo had parked its API contracts there - invisible to non-Copilot agents that only read AGENTS.md. State that project-specific conventions and API/behavioral contracts belong in AGENTS.md (every agent reads it); keep copilot-instructions.md to the Copilot runbook plus the inline commit/PR summary. Runbook: an agent twice reported "could not start a Copilot review - no bot id" when Copilot had in fact auto-reviewed with no comments. Spell out that a review with no inline comments is a completed clean pass (formal review, head commit.oid, body "...generated no comments"), that round 1 is normally auto-seeded and should be polled for before self-triggering, and that manual UI seeding is only for a genuinely missing review after polling.
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the template's agent-facing documentation to (1) explicitly direct derived repos to place project-specific conventions and public API/behavioral contracts in AGENTS.md (not .github/copilot-instructions.md), and (2) harden the GitHub Copilot review runbook to treat "no inline comments" as a valid clean-pass review outcome and to improve round-1 polling guidance.
Changes:
- Clarifies in
AGENTS.mdthat project-specific conventions and API/behavioral contracts belong inAGENTS.md, and that a no-findings review is a valid terminal state for a head SHA. - Narrows
.github/copilot-instructions.mdto the Copilot runbook + commit/PR-title summary, and adds guidance that reviews with no inline comments still count as completed coverage. - Adds "poll first" guidance for round 1 before attempting to re-request a Copilot review via
requestReviews.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
AGENTS.md | Documents where derived repos should put project rules (AGENTS.md) and clarifies that a no-findings review is a valid outcome in the review loop. |
.github/copilot-instructions.md | Strengthens the Copilot review runbook: clean-pass/no-inline-comments semantics and round-1 polling guidance before self-triggering. |
Uh oh!
There was an error while loading. Please reload this page.
A review comment on PR #174 caught that "no review of any kind - formal or issue comment" wrongly blocked manual seeding: step 1 reads the bot node id from formal reviews only, so an issue-comment-only situation has coverage but no bot id. Key the seed/bot-id decision on the formal review, and give the issue-comment-only case an explicit out (read the id from the comment author, or seed via the UI).
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Address Copilot review on PR #174: "never read"/"read only by" overstated and contradicted copilot-instructions.md's own intro ("any other AI agent reading this file") - reword to "not directed to it by default." Also correct the issue-comment bot-id lookup to query the PR's GraphQL `comments` connection rather than implying GraphQL reads the REST `issues/<N>/comments` path.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Addresses #173 and hardens the Copilot review runbook. Both gaps surfaced while re-syncing
ptr727/LanguageTagsagainst the template; both touch verbatim-carry files, so downstreams re-sync them.Project rules belong in AGENTS.md (#173)
.github/copilot-instructions.mdwas described as a narrow drop-in but never said where project-specific rules should live instead. A derived repo had parked its public-API contracts there - read only by GitHub Copilot / VS Code, so a non-Copilot agent reviewing a PR (Claude Code, Codex, Cursor) never saw them. Now stated in three places that project-specific conventions and API/behavioral contracts belong inAGENTS.md(the file every agent reads), withcopilot-instructions.mdkept to the Copilot runbook plus the inline commit/PR-title summary.Harden the Copilot review runbook
An agent twice told the maintainer it "could not start a Copilot review - no bot id" when Copilot had in fact auto-reviewed and produced no comments (e.g. LanguageTags#179). The runbook now states:
commit.oid, body ending "...generated no comments" - not a failure, and never a reason to re-request or escalate.Verification
markdownlint-cli2passes on both files; line endings remain CRLF per.editorconfig.state: COMMENTED,commit.oid== head, "generated no comments" body).