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 71 commits into
Conversation
|
Warning Review limit reached
More reviews will be available in 23 minutes and 31 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 (7)
📝 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.
* chore: replace claude-code-reusable references with dev-lead * chore: remove claude-code-reusable.yml (replaced by dev-lead framework) * fix: remove trailing space in org-scorecard.yml (yamllint) Line 93 had a trailing space that caused the YAML lint CI check to fail. Co-Authored-By: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Sonnet 4.6 (1M context) <noreply@anthropic.com>
Bypassing automated review bot as requested by user. All feedback has been addressed and CI is passing.
* docs: document fine-grained token scopes for ORG_SCORECARD_TOKEN * Apply suggestion from @gemini-code-assist[bot] Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com> * fix(docs): wrap long line to fix markdownlint error --------- Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
…anch not found Race condition: gh pr list may include a PR whose branch has been deleted between the list fetch and the compare call (or a newly-created Dependabot PR whose branch is not yet fully initialised). Previously the script exited with code 1 because set -e propagated the 404 through the unguarded BEHIND=$(gh api …) assignment. Fix: wrap the compare call in if ! …; then … continue; fi so that a failed lookup logs a warning and skips to the next PR instead of aborting the step. Fixes: petry-projects/ContentTwin#232 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
…issions) (#405) Adds check_dev_lead_stub() validating each consumer's dev-lead.yml against the centralized contract (standards/ci-standards.md#dev-lead-agent), catching the three drift modes behind #402: 1. Pin: must be petry-projects/.github-private/.../dev-lead-reusable.yml@main. 2. Concurrency: must NOT carry a per-stub concurrency block (owned by the reusable; a local block drifts and cancels issue pickups). 3. Permissions: must grant `statuses: read` (reusable requests it since #435; missing it => every run startup_failures). Also removes the stale `dev-lead.yml:dev-lead-reusable:v1` entry from check_centralized_workflow_stubs — dev-lead lives in the private repo at @main and never fit that check's `.github/@version` model (it was mis-flagging every adopter). dev-lead is now covered solely by the dedicated check. Verified against live repos: ContentTwin compliant; TalkTerm flags all three; bmad flags only the missing statuses:read — matching their current state. Refs #402 Co-authored-by: Claude Code Bot <noreply@anthropic.com>
…le (#152) * fix(ci): downgrade pnpm/action-setup to v5 in dependency-audit reusable The SHA 08c4be7e (mislabeled # v4) is actually pnpm/action-setup@v6.0.0, which bootstraps with pnpm v11.0.0-rc.0. pnpm v11-rc cannot parse lockfiles generated by pnpm v9 (lockfileVersion '9.0'), causing ERR_PNPM_BROKEN_LOCKFILE in all repos still on pnpm v9. Pinning to action-setup@v5.0.0 (fc06bc1), which installs pnpm via npm directly with no v11 bootstrap, restoring compatibility with pnpm v9. * fix(bot): address bot feedback [skip ci-relay] --------- Co-authored-by: DJ <dj@Rachels-Air.localdomain> Co-authored-by: donpetry-bot <281750570+donpetry-bot@users.noreply.github.com>
…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>
don-petry
force-pushed
the
feat/copilot-instructions-standard-language-links
branch
from
3bf8de7 to
a53452d
Compare
Dev-Lead — rebase (no-changes)Agent reasoning |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a53452dcbb
ℹ️ 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".
|
|
||
| --- | ||
|
|
||
| ## Multi-Agent Isolation — Git Worktrees |
There was a problem hiding this comment.
This new block duplicates the existing ## Multi-Agent Isolation — Git Worktrees section already present earlier in AGENTS.md (starting at line 560), including the stacked-PR guidance that follows it. Because this file is the authoritative org-wide agent standard, maintaining two copies of the same rules means future edits can update one copy while leaving the other stale or contradictory.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in AGENTS.md: removed the duplicate ## Multi-Agent Isolation — Git Worktrees block (and the ## Stacked PRs for Epic/Feature Development section that followed it) that had been appended starting at line 1023. The original sections at lines 560 and 759 are retained as the single source of truth.
| # | ||
| # Array format: "workflow-filename:expected-reusable-basename:version-tag" | ||
| # --------------------------------------------------------------------------- | ||
| check_centralized_workflow_stubs() { |
There was a problem hiding this comment.
This redefines check_centralized_workflow_stubs even though the same function is already defined earlier in the script (starting at line 731), and Bash silently keeps only the later definition. Any future fix made to the first copy would not affect the audit at runtime, so the script now has two sources of truth for the same compliance check.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in scripts/compliance-audit.sh: removed the duplicate check_centralized_workflow_stubs function definition that started at line 993 (including its comment block). Only the original definition at line 731 remains, which contains the additional NOTE about dev-lead.yml being excluded from this check.
| for the template. | ||
|
|
||
| In addition, BMAD Method-enabled repositories MUST also include the conditional | ||
| [Feature Ideation workflow](#8-feature-ideation-feature-ideationyml--bmad-method-repos) |
There was a problem hiding this comment.
This added paragraph duplicates the preceding Feature Ideation requirement but changes the anchor to #8-feature-ideation-feature-ideationyml--bmad-method-repos; the actual section headings in this file are numbered ### 9. Feature Ideation, so readers following this new link land on a non-existent anchor while the existing link just above is correct.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in standards/ci-standards.md: removed the duplicate paragraph that referenced the non-existent anchor #8-feature-ideation-feature-ideationyml--bmad-method-repos. The preceding paragraph with the correct anchor #9-feature-ideation-feature-ideationyml--bmad-method-repos is retained.
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
|
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