feat(standards): require language instruction file links in Org Standards section#343
feat(standards): require language instruction file links in Org Standards section#343don-petry wants to merge 13 commits into
Conversation
…ards section Adds an explicit requirement that every repo-level copilot-instructions.md MUST list the language-specific .instructions.md files deployed to .github/instructions/, each with a one-line scope description, in the ## Org Standards section. Makes path-specific files discoverable without requiring contributors to browse the directory. Changes: - standards/copilot-instructions-standard.md: update ## Org Standards template to show the language-link pattern, add to Required Sections intro, add to What to Include list, add copilot-instructions-missing- language-links compliance check row - .github/copilot-instructions.md: convert prose language-file mention to linked list matching the new pattern (serves as the canonical example) Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
|
Warning Review limit reached
More reviews will be available in 55 minutes and 32 seconds. Learn how PR review limits work. Your organization has run out of usage credits. Purchase more in the billing tab. ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (3)
📝 WalkthroughWalkthroughThis PR updates Copilot instructions governance by expanding the standard template to require explicit listing of deployed language-specific instruction files in ChangesCopilot Instructions Standard and Language File Listing
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request updates the Copilot instructions and standards to improve the discoverability of language-specific instruction files. It mandates listing these files in the ## Org Standards section and introduces a new linting rule to verify their presence. Review feedback correctly identified that the relative links used in both the instructions file and the template were broken, as they incorrectly included the .github/ prefix while already residing within that directory.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
Updates the Copilot instruction-file standard to require that repositories explicitly link to any deployed language-specific instruction files from the ## Org Standards section, improving discoverability for contributors.
Changes:
- Adds a MUST requirement to list each deployed
.github/instructions/*.instructions.mdfile (with a one-line scope description) in repo-levelcopilot-instructions.md. - Updates the
standards/copilot-instructions-standard.mdtemplate to demonstrate the linked-list pattern for all six language instruction files. - Adds a new (future) compliance check row:
copilot-instructions-missing-language-links, and updates this repo’s.github/copilot-instructions.mdto use the linked-list pattern.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| standards/copilot-instructions-standard.md | Adds a normative requirement + template example for listing language instruction files; adds a compliance table row for missing links. |
| .github/copilot-instructions.md | Converts the language-instruction prose reference into an explicit linked list intended as the canonical example. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68e58688f7
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1fc01cf7db
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Superseded by automated re-review at
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 17f8932b48
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/copilot-instructions.md:
- Around line 27-32: The canonical example (.github/copilot-instructions.md)
contains broken relative links that point to .github/.github/instructions/...;
update each referenced path (e.g., typescript.instructions.md,
javascript.instructions.md, python.instructions.md, go.instructions.md,
terraform.instructions.md, shell.instructions.md) so they use the correct
relative path from .github/copilot-instructions.md (i.e.,
.github/instructions/<file>.instructions.md should be replaced with
instructions/<file>.instructions.md or ./instructions/<file>.instructions.md)
ensuring the links resolve correctly when copied to downstream repos.
In `@standards/copilot-instructions-standard.md`:
- Line 214: Update the rule description for
`copilot-instructions-missing-language-links` to indicate a bidirectional check:
not only must `.github/instructions/` contain files listed in the `## Org
Standards` section, but each listed link must also resolve to an existing file
at the specified relative path; change the table cell text to something like
"Ensure files in `.github/instructions/` are listed in `## Org Standards` and
that each listed link resolves to the correct relative path (no broken links)."
Reference the `copilot-instructions-missing-language-links` rule, the
`.github/instructions/` directory, and the `## Org Standards` section when
making the edit.
- Around line 158-163: The relative links in the list (e.g.,
".github/instructions/typescript.instructions.md",
".github/instructions/javascript.instructions.md", etc.) are incorrect when this
file lives at .github/copilot-instructions.md and resolve to
".github/.github/..."; change those links to the correct relative path (for
example "./instructions/typescript.instructions.md" or
"instructions/typescript.instructions.md") for each entry ("TypeScript / TSX",
"JavaScript", "Go", "Shell", "Python", "Terraform") so they point to the real
files under .github/instructions/.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: d3684388-6824-41e9-9742-2196d69f76df
📒 Files selected for processing (2)
.github/copilot-instructions.mdstandards/copilot-instructions-standard.md
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 47442f7fec
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e023f383a1
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
|
@coderabbitai resolve |
Dev-Lead — review-changes (applied)Changes committed and pushed. |
|
@coderabbitai resolve |
Dev-Lead — review-changes (applied)Changes committed and pushed. |
✅ Actions performedComments resolved and changes approved. |
1 similar comment
✅ Actions performedComments resolved and changes approved. |
Dev-Lead — review-changes (applied)Changes committed and pushed. |
Dev-Lead — review-changes (applied)Changes committed and pushed. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: cba203e615
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Dev-Lead — review-changes (applied)Changes committed and pushed. |
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: a11fc5748f61961530a874552fc0c2a2133bd8f9
Cascade: triage → deep (triage: haiku 4.5 → deep: sonnet 4.6 + duck: o4-mini → audit: opus 4.7)
Summary
Documentation-only PR that adds a discoverability requirement for language instruction files in Copilot standards. The broken relative-link issue flagged in the prior review cycle has been fixed (links now correctly use instructions/<file> rather than .github/instructions/<file>). The only remaining defect is five duplicate .dev-lead/ entries in .gitignore, which is a cosmetic artifact of repeated automated fix application and has zero functional impact. All CI checks pass, no security concerns.
Findings
- MINOR:
.gitignorecontains 5 duplicate.dev-lead/entries (lines 394-398) in addition to the pre-existing entry at line 393. Git silently ignores duplicate rules so there is no functional impact, but it is messy and appears to be an artifact of a bot applying the same fix multiple times. Worth cleaning up in a follow-up or squash before merge. - INFO: Relative links in
.github/copilot-instructions.mdnow correctly useinstructions/<file>.instructions.md(resolves to.github/instructions/on GitHub). The template block instandards/copilot-instructions-standard.mduses the same relative form inside a code fence — correct for downstream copy-paste use. The broken-link issue raised in the prior deep review and by gemini-code-assist, copilot-pull-request-reviewer, and coderabbitai has been resolved. - INFO: PR is blocked on
org-leadsteam review (REVIEW_REQUIRED). This is a human-gating requirement; the automated review approves the change but cannot fulfill the team-review gate. - INFO: New
copilot-instructions-missing-language-linkscompliance row added to the check table. Current description only checks for presence (files in.github/instructions/not listed in## Org Standards). A future enhancement could also validate that listed links resolve to files that actually exist — this would have caught the original broken-link bug automatically.
Reviewed by the PR-review cascade (triage: haiku 4.5 → deep: sonnet 4.6 + duck: o4-mini → audit: opus 4.7). Reply if you need a human review.
donpetry-bot
left a comment
donpetry-bot
left a comment
There was a problem hiding this comment.
Automated review — APPROVED ✓
Risk: LOW
Reviewed commit: a11fc5748f61961530a874552fc0c2a2133bd8f9
Review mode: triage-approved (single reviewer confirmation)
Summary
Confirming the triage-tier approval. This is a documentation-only change that (a) adds a requirement to standards/copilot-instructions-standard.md that the ## Org Standards section list every deployed language .instructions.md file with a one-line scope description, (b) updates the template block to demonstrate the pattern, (c) adds a new copilot-instructions-missing-language-links row to the compliance check table, and (d) converts the prose language-file mention in the org-level copilot-instructions.md to the linked-list pattern as a live example. The intent matches the PR description and motivation.
Linked issue analysis
No linked issue. PR body cites CodeRabbit feedback across rollout PRs (#203, #241, #204, #181, #199, #357) as motivation; that context is documented in the PR description rather than a tracked issue, which is acceptable for a small standards-doc change.
Findings
- MINOR (carried forward from prior review, still unresolved):
.gitignorecontains six.dev-lead/entries at the tail of the file (one pre-existing plus five duplicates added in this PR). Git deduplicates ignore rules so there is no functional impact, but the duplication appears to be an artifact of repeated automated fix-application and is unrelated to this PR's stated scope. Worth cleaning up in a follow-up commit or a squash-merge. - INFO: Relative links in both the org-level
.github/copilot-instructions.mdand the template insidestandards/copilot-instructions-standard.mduse theinstructions/<file>.instructions.mdform. For the org file this resolves correctly to.github/instructions/<file>on GitHub; for the template (inside a fenced code block, copied verbatim into target repos) the same form is also correct because target repos place the file at.github/copilot-instructions.md. Earlier broken-link concerns from gemini-code-assist, copilot-pull-request-reviewer, and coderabbitai are resolved. - INFO: The new
copilot-instructions-missing-language-linkscompliance row only checks for presence (files in.github/instructions/not listed in## Org Standards). A future enhancement could additionally validate that listed links resolve to files that actually exist — that would have caught the original broken-link defect automatically. Not blocking.
CI status
All required checks green: Lint, CodeQL, Analyze, SonarCloud (×3), CodeRabbit, ShellCheck, Secret scan (gitleaks), Agent Security Scan, agent-shield/AgentShield, pr-auto-review, dev-lead/dispatch. Language-specific audit jobs (npm/pnpm/pip/cargo/govulncheck) skipped as expected for a docs-only change. Mergeable: CLEAN.
Reviewed automatically by the PR-review agent (single-reviewer mode). Reply if you need a human review.
donpetry-bot
dismissed
their stale review
Superseded by automated re-review at a11fc57.
Automated review — human attention neededThis PR has been through 3 automated review cycles (cap: 3) without converging on an approval-and-merge state. Further automated review has been paused to avoid infinite loops. Please take a look manually, or close this PR if it's no longer needed. Once a human review resolves the situation, remove the Posted by the donpetry-bot PR-review cascade. |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 205aba96d3
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| The `## Org Standards` section MUST list every language-specific `.instructions.md` file deployed | ||
| to `.github/instructions/` in that repo, each with a one-line scope description. This makes the | ||
| path-specific files discoverable without requiring contributors to browse the directory. |
There was a problem hiding this comment.
In the current patch, this new MUST makes language links a required section, but the weekly audit still only checks for Tech Stack and Local Dev Commands in scripts/compliance-audit.sh (required_sections at lines 1101-1111) while this same document says the audit enforces the standard automatically. Repos can therefore omit every language-instruction link and still pass the compliance audit, creating a false compliance signal for the discoverability requirement introduced here.
Useful? React with 👍 / 👎.
| Language-specific rules are applied automatically via files in `.github/instructions/` when you | ||
| open a matching file type. Canonical files in this repo (deployed verbatim to each target repo): |
There was a problem hiding this comment.
This file is still advertised below as the starting point to copy into each repo, but the new language-instruction list is added under ## Standards Reference and this file has no ## Org Standards heading. Repos that follow this canonical file can therefore include the links yet still fail the new standard's requirement that they be listed in ## Org Standards, so the live example should either add that section or move the list there.
Useful? React with 👍 / 👎.
|
Summary
copilot-instructions.mdfiles MUST list each deployed language instruction file in## Org Standardswith a one-line scope descriptioncopilot-instructions-standard.mdto show the pattern with all six language files as examplescopilot-instructions-missing-language-linksto the compliance check table (for future audit enforcement)copilot-instructions.mdto the linked-list pattern, serving as the canonical exampleMotivation
CodeRabbit flagged across the rollout PRs (#203, #241, #204, #181, #199, #357) that the
## Org Standardssection didn't surface the language instruction files that were deployed alongsidecopilot-instructions.md. Contributors had no way to discovertypescript.instructions.mdetc. without browsing.github/instructions/. This change makes discoverability a standard requirement and closes the gap that caused those review comments.Files changed
standards/copilot-instructions-standard.md— template updated, requirement added to intro + What to Include, compliance row added.github/copilot-instructions.md— prose → linked list; serves as the live example of the pattern🤖 Generated with Claude Code
Summary by CodeRabbit