From 68e58688f7086997396a9bda617f193c157e2aa7 Mon Sep 17 00:00:00 2001 From: Don Petry <36422719+don-petry@users.noreply.github.com> Date: Fri, 22 May 2026 07:56:26 -0500 Subject: [PATCH 1/6] feat(standards): require language instruction file links in Org Standards 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) --- .github/copilot-instructions.md | 12 +++++++++--- standards/copilot-instructions-standard.md | 21 ++++++++++++++++++++- 2 files changed, 29 insertions(+), 4 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index c963f0b6..90e21f67 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -21,9 +21,15 @@ Copilot-focused summary; AGENTS.md is authoritative when they conflict. Read the standard in [`standards/`](../standards/) before touching CI, repo settings, or agent configuration. -Language-specific rules are applied automatically via files in `.github/instructions/`: -`typescript`, `javascript`, `python`, `go`, `terraform`, and `shell` — see those files for -per-language guidance. +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): + +- [`typescript.instructions.md`](.github/instructions/typescript.instructions.md) — strict config, branded types, DDD/CQRS, pino, React, Electron IPC +- [`javascript.instructions.md`](.github/instructions/javascript.instructions.md) — style, JSDoc type annotations, error handling +- [`python.instructions.md`](.github/instructions/python.instructions.md) — black/ruff, type annotations, structlog, pytest, GAS companion code +- [`go.instructions.md`](.github/instructions/go.instructions.md) — naming, gofmt, slog, error wrapping, concurrency, HTTP, testing, security +- [`terraform.instructions.md`](.github/instructions/terraform.instructions.md) — fmt, tflint, tfsec, trivy, state management, security +- [`shell.instructions.md`](.github/instructions/shell.instructions.md) — safety flags, ShellCheck, quoting, error handling, Makefile standards ## Core Development Rules diff --git a/standards/copilot-instructions-standard.md b/standards/copilot-instructions-standard.md index a2df7080..f9dbf3aa 100644 --- a/standards/copilot-instructions-standard.md +++ b/standards/copilot-instructions-standard.md @@ -92,6 +92,10 @@ only document what differs or adds detail. A repo-level `copilot-instructions.md` MUST include the following sections. Keep the file to approximately two pages — concise, specific, and actionable. +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. + --- ```markdown @@ -147,7 +151,19 @@ apply.] ## Org Standards See [petry-projects/.github — AGENTS.md](https://github.com/petry-projects/.github/blob/main/AGENTS.md) -for full development standards. +for org-wide development standards. + +**Language-specific instructions** (applied automatically by Copilot when you open matching file types): + +- [TypeScript / TSX](.github/instructions/typescript.instructions.md) — [strict config, branded types, DDD/CQRS, pino, React/Electron as applicable] +- [JavaScript](.github/instructions/javascript.instructions.md) — [style, JSDoc, error handling] +- [Go](.github/instructions/go.instructions.md) — [naming, gofmt, slog, error wrapping, concurrency, testing] +- [Shell](.github/instructions/shell.instructions.md) — [safety flags, ShellCheck, quoting, error handling] +- [Python](.github/instructions/python.instructions.md) — [black/ruff, type annotations, structlog, pytest] +- [Terraform](.github/instructions/terraform.instructions.md) — [fmt, tflint, security scanning, state management] + +_List only the files actually deployed to `.github/instructions/` for this repo. +Omit this block entirely if no language instruction files were deployed._ ``` --- @@ -162,6 +178,7 @@ for full development standards. - Coverage thresholds and testing tools specific to this repo - Architecture patterns unique to this repo (e.g., Electron IPC conventions, GAS extraction pattern) - Any rule that overrides or refines the org-level defaults +- Links to every language-specific `.instructions.md` file deployed to `.github/instructions/`, each with a one-line scope description (list only files that are actually present) **Do NOT include in repo-level instructions:** @@ -169,6 +186,7 @@ for full development standards. - Rules already covered in language-specific `.instructions.md` files - Content already documented in `AGENTS.md` - Secrets, API keys, credentials, or example tokens with real values +- Links to language instruction files that were not deployed to this repo's `.github/instructions/` ## Content Quality Rules @@ -193,6 +211,7 @@ automatically. Two `warning`-severity checks run against every repository in the | `missing-copilot-instructions` | `.github/copilot-instructions.md` is absent | Copy the template below and fill in the repo-specific sections | | `copilot-instructions-missing-tech-stack` | File exists but `## Tech Stack` section is absent | Add the section — list runtimes, frameworks, and major library versions | | `copilot-instructions-missing-local-dev-commands` | File exists but `## Local Dev Commands` section is absent | Add the section — include exact install, dev-run, test, lint, and typecheck commands | +| `copilot-instructions-missing-language-links` | `.github/instructions/` contains files not listed in `## Org Standards` | Add links to each deployed language instruction file with a one-line scope description | Findings are reported as `warning` (not `error`) because the org-level baseline in `petry-projects/.github` ensures minimum Copilot guidance even without a repo-level file. From 47938ae49010cee32a53b42a5637f985c54219b2 Mon Sep 17 00:00:00 2001 From: donpetry-bot <281750570+donpetry-bot@users.noreply.github.com> Date: Tue, 26 May 2026 17:05:26 +0000 Subject: [PATCH 2/6] chore: apply manual instructions [skip ci-relay] --- .github/copilot-instructions.md | 12 ++++++------ .gitignore | 1 + standards/copilot-instructions-standard.md | 13 ++++++------- 3 files changed, 13 insertions(+), 13 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 90e21f67..1d4ec81d 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -24,12 +24,12 @@ configuration. 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): -- [`typescript.instructions.md`](.github/instructions/typescript.instructions.md) — strict config, branded types, DDD/CQRS, pino, React, Electron IPC -- [`javascript.instructions.md`](.github/instructions/javascript.instructions.md) — style, JSDoc type annotations, error handling -- [`python.instructions.md`](.github/instructions/python.instructions.md) — black/ruff, type annotations, structlog, pytest, GAS companion code -- [`go.instructions.md`](.github/instructions/go.instructions.md) — naming, gofmt, slog, error wrapping, concurrency, HTTP, testing, security -- [`terraform.instructions.md`](.github/instructions/terraform.instructions.md) — fmt, tflint, tfsec, trivy, state management, security -- [`shell.instructions.md`](.github/instructions/shell.instructions.md) — safety flags, ShellCheck, quoting, error handling, Makefile standards +- [`typescript.instructions.md`](instructions/typescript.instructions.md) — strict config, branded types, DDD/CQRS, pino, React, Electron IPC +- [`javascript.instructions.md`](instructions/javascript.instructions.md) — style, JSDoc type annotations, error handling +- [`python.instructions.md`](instructions/python.instructions.md) — black/ruff, type annotations, structlog, pytest, GAS companion code +- [`go.instructions.md`](instructions/go.instructions.md) — naming, gofmt, slog, error wrapping, concurrency, HTTP, testing, security +- [`terraform.instructions.md`](instructions/terraform.instructions.md) — fmt, tflint, tfsec, trivy, state management, security +- [`shell.instructions.md`](instructions/shell.instructions.md) — safety flags, ShellCheck, quoting, error handling, Makefile standards ## Core Development Rules diff --git a/.gitignore b/.gitignore index 38463791..af6a1c5b 100644 --- a/.gitignore +++ b/.gitignore @@ -390,3 +390,4 @@ private.yml # End of petry-projects secrets baseline # ============================================================================ .dev-lead/ +.dev-lead/ diff --git a/standards/copilot-instructions-standard.md b/standards/copilot-instructions-standard.md index f9dbf3aa..39f3ec82 100644 --- a/standards/copilot-instructions-standard.md +++ b/standards/copilot-instructions-standard.md @@ -155,12 +155,12 @@ for org-wide development standards. **Language-specific instructions** (applied automatically by Copilot when you open matching file types): -- [TypeScript / TSX](.github/instructions/typescript.instructions.md) — [strict config, branded types, DDD/CQRS, pino, React/Electron as applicable] -- [JavaScript](.github/instructions/javascript.instructions.md) — [style, JSDoc, error handling] -- [Go](.github/instructions/go.instructions.md) — [naming, gofmt, slog, error wrapping, concurrency, testing] -- [Shell](.github/instructions/shell.instructions.md) — [safety flags, ShellCheck, quoting, error handling] -- [Python](.github/instructions/python.instructions.md) — [black/ruff, type annotations, structlog, pytest] -- [Terraform](.github/instructions/terraform.instructions.md) — [fmt, tflint, security scanning, state management] +- [TypeScript / TSX](instructions/typescript.instructions.md) — [strict config, branded types, DDD/CQRS, pino, React/Electron as applicable] +- [JavaScript](instructions/javascript.instructions.md) — [style, JSDoc, error handling] +- [Go](instructions/go.instructions.md) — [naming, gofmt, slog, error wrapping, concurrency, testing] +- [Shell](instructions/shell.instructions.md) — [safety flags, ShellCheck, quoting, error handling] +- [Python](instructions/python.instructions.md) — [black/ruff, type annotations, structlog, pytest] +- [Terraform](instructions/terraform.instructions.md) — [fmt, tflint, security scanning, state management] _List only the files actually deployed to `.github/instructions/` for this repo. Omit this block entirely if no language instruction files were deployed._ @@ -211,7 +211,6 @@ automatically. Two `warning`-severity checks run against every repository in the | `missing-copilot-instructions` | `.github/copilot-instructions.md` is absent | Copy the template below and fill in the repo-specific sections | | `copilot-instructions-missing-tech-stack` | File exists but `## Tech Stack` section is absent | Add the section — list runtimes, frameworks, and major library versions | | `copilot-instructions-missing-local-dev-commands` | File exists but `## Local Dev Commands` section is absent | Add the section — include exact install, dev-run, test, lint, and typecheck commands | -| `copilot-instructions-missing-language-links` | `.github/instructions/` contains files not listed in `## Org Standards` | Add links to each deployed language instruction file with a one-line scope description | Findings are reported as `warning` (not `error`) because the org-level baseline in `petry-projects/.github` ensures minimum Copilot guidance even without a repo-level file. From e0061a4a782bb3ed96a0855165db08a50d7c5c15 Mon Sep 17 00:00:00 2001 From: donpetry-bot <281750570+donpetry-bot@users.noreply.github.com> Date: Tue, 26 May 2026 17:08:03 +0000 Subject: [PATCH 3/6] chore: apply manual instructions [skip ci-relay] --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index af6a1c5b..e49aaf1e 100644 --- a/.gitignore +++ b/.gitignore @@ -391,3 +391,4 @@ private.yml # ============================================================================ .dev-lead/ .dev-lead/ +.dev-lead/ From b869d425ec7b5cb3efdabbc3e0486bf9a1ec0b4a Mon Sep 17 00:00:00 2001 From: donpetry-bot <281750570+donpetry-bot@users.noreply.github.com> Date: Tue, 26 May 2026 17:10:18 +0000 Subject: [PATCH 4/6] chore: apply manual instructions [skip ci-relay] --- .gitignore | 1 + standards/copilot-instructions-standard.md | 1 + 2 files changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index e49aaf1e..9061774d 100644 --- a/.gitignore +++ b/.gitignore @@ -392,3 +392,4 @@ private.yml .dev-lead/ .dev-lead/ .dev-lead/ +.dev-lead/ diff --git a/standards/copilot-instructions-standard.md b/standards/copilot-instructions-standard.md index 39f3ec82..f24ebac7 100644 --- a/standards/copilot-instructions-standard.md +++ b/standards/copilot-instructions-standard.md @@ -211,6 +211,7 @@ automatically. Two `warning`-severity checks run against every repository in the | `missing-copilot-instructions` | `.github/copilot-instructions.md` is absent | Copy the template below and fill in the repo-specific sections | | `copilot-instructions-missing-tech-stack` | File exists but `## Tech Stack` section is absent | Add the section — list runtimes, frameworks, and major library versions | | `copilot-instructions-missing-local-dev-commands` | File exists but `## Local Dev Commands` section is absent | Add the section — include exact install, dev-run, test, lint, and typecheck commands | +| `copilot-instructions-missing-language-links` | `.github/instructions/` contains files not listed in `## Org Standards`, or `## Org Standards` lists links that do not resolve to an existing file in `.github/instructions/` (broken links) | Ensure files in `.github/instructions/` are listed in `## Org Standards` and that each listed link resolves to the correct relative path (no broken links) | Findings are reported as `warning` (not `error`) because the org-level baseline in `petry-projects/.github` ensures minimum Copilot guidance even without a repo-level file. From cba203e615d4e6ce4a51610111bdf8a783567c29 Mon Sep 17 00:00:00 2001 From: donpetry-bot <281750570+donpetry-bot@users.noreply.github.com> Date: Tue, 26 May 2026 17:13:08 +0000 Subject: [PATCH 5/6] chore: apply manual instructions [skip ci-relay] --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 9061774d..e2a21eab 100644 --- a/.gitignore +++ b/.gitignore @@ -393,3 +393,4 @@ private.yml .dev-lead/ .dev-lead/ .dev-lead/ +.dev-lead/ From a11fc5748f61961530a874552fc0c2a2133bd8f9 Mon Sep 17 00:00:00 2001 From: donpetry-bot <281750570+donpetry-bot@users.noreply.github.com> Date: Tue, 26 May 2026 17:22:49 +0000 Subject: [PATCH 6/6] chore: apply manual instructions [skip ci-relay] --- .gitignore | 1 + standards/copilot-instructions-standard.md | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitignore b/.gitignore index e2a21eab..b5a94cd1 100644 --- a/.gitignore +++ b/.gitignore @@ -394,3 +394,4 @@ private.yml .dev-lead/ .dev-lead/ .dev-lead/ +.dev-lead/ diff --git a/standards/copilot-instructions-standard.md b/standards/copilot-instructions-standard.md index f24ebac7..39f3ec82 100644 --- a/standards/copilot-instructions-standard.md +++ b/standards/copilot-instructions-standard.md @@ -211,7 +211,6 @@ automatically. Two `warning`-severity checks run against every repository in the | `missing-copilot-instructions` | `.github/copilot-instructions.md` is absent | Copy the template below and fill in the repo-specific sections | | `copilot-instructions-missing-tech-stack` | File exists but `## Tech Stack` section is absent | Add the section — list runtimes, frameworks, and major library versions | | `copilot-instructions-missing-local-dev-commands` | File exists but `## Local Dev Commands` section is absent | Add the section — include exact install, dev-run, test, lint, and typecheck commands | -| `copilot-instructions-missing-language-links` | `.github/instructions/` contains files not listed in `## Org Standards`, or `## Org Standards` lists links that do not resolve to an existing file in `.github/instructions/` (broken links) | Ensure files in `.github/instructions/` are listed in `## Org Standards` and that each listed link resolves to the correct relative path (no broken links) | Findings are reported as `warning` (not `error`) because the org-level baseline in `petry-projects/.github` ensures minimum Copilot guidance even without a repo-level file.