eslint-plugin-copilot 1.0.5

package/docs/rules/require-existing-relative-instructions-links.md

@@ -0,0 +1,43 @@
+# require-existing-relative-instructions-links
+
+Require relative Markdown links in path-specific Copilot instructions files to resolve to existing workspace targets.
+
+> **Rule catalog ID:** R032
+
+## Targeted pattern scope
+
+- `.github/instructions/**/*.instructions.md`
+
+## What this rule reports
+
+- relative instructions links whose resolved workspace target does not exist
+
+## Why this rule exists
+
+Path-specific instructions commonly link to package-specific conventions or local examples. Broken links weaken those instructions by pointing reviewers and coding agents at context that is no longer there.
+
+## ❌ Incorrect
+
+```md
+---
+description: Frontend guidance
+applyTo: src/**/*.ts
+---
+See [frontend standards](../../docs/frontend.md).
+```
+
+when `../../docs/frontend.md` does not exist from the instructions file.
+
+## ✅ Correct
+
+```md
+---
+description: Frontend guidance
+applyTo: src/**/*.ts
+---
+See [frontend standards](../../docs/standards/frontend.md).
+```
+
+## Further reading
+
+- [VS Code Docs: Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)

package/docs/rules/require-existing-relative-prompt-links.md

@@ -0,0 +1,41 @@
+# require-existing-relative-prompt-links
+
+Require relative Markdown links in Copilot prompt files to resolve to existing workspace targets.
+
+> **Rule catalog ID:** R030
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- relative links whose resolved workspace target does not exist
+
+## Why this rule exists
+
+Relative links are only useful when they actually resolve. Broken prompt links can hide important context, examples, or runbooks from the people and tools invoking the prompt.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review a pull request
+---
+See [review guide](../docs/review-guide.md).
+```
+
+when `../docs/review-guide.md` does not exist from the prompt file.
+
+## ✅ Correct
+
+```md
+---
+description: Review a pull request
+---
+See [review guide](../../docs/review-guide.md).
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-existing-relative-skill-links.md

@@ -0,0 +1,44 @@
+# require-existing-relative-skill-links
+
+Require relative Markdown links in Copilot skill definition files to resolve to existing workspace resources.
+
+> **Rule catalog ID:** R053
+
+## Targeted pattern scope
+
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- relative skill links whose resolved workspace target does not exist
+
+## Why this rule exists
+
+Skills often depend on linked guides, examples, and scripts stored alongside the definition. Broken relative links make the skill incomplete even though its frontmatter and body appear structurally valid.
+
+## ❌ Incorrect
+
+```md
+---
+name: review
+description: Review code changes.
+---
+See [guide](guide.md).
+```
+
+when `guide.md` does not exist next to the skill definition.
+
+## ✅ Correct
+
+```md
+---
+name: review
+description: Review code changes.
+---
+See [guide](reference/guide.md).
+```
+
+## Further reading
+
+- [GitHub Docs: Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills)

package/docs/rules/require-existing-repository-hook-cwd.md

@@ -0,0 +1,45 @@
+# require-existing-repository-hook-cwd
+
+Require repository hook `cwd` values to resolve to existing repository paths.
+
+> **Rule catalog ID:** R063
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- relative hook `cwd` values that do not exist in the repository
+
+## Why this rule exists
+
+A repository-relative working directory still needs to point somewhere real. Validating the path on disk catches stale or misspelled hook working directories before the hook runs.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "cwd": "scripts/hooks" }]
+  }
+}
+```
+
+when `scripts/hooks` does not exist in the repository.
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "cwd": "scripts" }]
+  }
+}
+```
+
+## Further reading
+
+- [GitHub Docs: Using hooks with GitHub Copilot agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)

package/docs/rules/require-github-copilot-target-for-mcp-servers.md

@@ -0,0 +1,46 @@
+# require-github-copilot-target-for-mcp-servers
+
+Require Copilot custom agents that declare `mcp-servers` to set `target: github-copilot`.
+
+> **Rule catalog ID:** R010
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- custom agent files that declare `mcp-servers` without any `target`
+- custom agent files that declare `mcp-servers` with an empty `target`
+- custom agent files that declare `mcp-servers` with a non-`github-copilot` target
+
+## Why this rule exists
+
+The `mcp-servers` frontmatter is specific to GitHub Copilot-targeted custom agents. If a custom agent opts into `mcp-servers` but omits `target: github-copilot`, the file drifts away from the current VS Code contract and can miscommunicate how that agent is meant to run.
+
+## ❌ Incorrect
+
+```md
+---
+description: Coordinate release automation through MCP servers
+target: vscode
+mcp-servers: [release-coordinator.json]
+---
+Coordinate release automation tasks.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Coordinate release automation through MCP servers
+target: github-copilot
+mcp-servers: [release-coordinator.json]
+---
+Coordinate release automation tasks.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+- [VS Code January 2026 update notes: Agent extensibility](https://code.visualstudio.com/updates/v1_109)

package/docs/rules/require-instructions-apply-to.md

@@ -0,0 +1,40 @@
+# require-instructions-apply-to
+
+Require path-specific Copilot instructions files to define a non-empty `applyTo` frontmatter glob.
+
+> **Rule catalog ID:** R001
+
+## Targeted pattern scope
+
+- `.github/instructions/**/*.instructions.md`
+
+## What this rule reports
+
+- instructions files with missing or blank `applyTo` frontmatter
+
+## Why this rule exists
+
+Path-specific instructions are only useful when Copilot can tell which files they target. Without `applyTo`, the instructions file cannot participate in automatic attachment for matching files.
+
+## ❌ Incorrect
+
+```md
+---
+description: TypeScript style guidance
+---
+Use `satisfies` for stable object literals.
+```
+
+## ✅ Correct
+
+```md
+---
+description: TypeScript style guidance
+applyTo: "src/**/*.ts"
+---
+Use `satisfies` for stable object literals.
+```
+
+## Further reading
+
+- [VS Code Docs: Reusable instruction files](https://code.visualstudio.com/docs/copilot/copilot-customization#_reusable-instruction-files)

package/docs/rules/require-json-agent-mcp-servers.md

@@ -0,0 +1,41 @@
+# require-json-agent-mcp-servers
+
+Require Copilot custom-agent `mcp-servers` entries to reference JSON config files.
+
+> **Rule catalog ID:** R034
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- `mcp-servers` entries that do not end in `.json`
+
+## Why this rule exists
+
+In practice, custom-agent `mcp-servers` entries are repository file references to MCP server configuration documents. Requiring `.json` targets makes those references more explicit and catches obvious misconfigurations early.
+
+## ❌ Incorrect
+
+```md
+---
+description: Release coordinator
+mcp-servers: ['release-server']
+---
+Coordinate the release.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Release coordinator
+mcp-servers: ['release-server.json']
+---
+Coordinate the release.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-prompt-file-metadata.md

@@ -0,0 +1,45 @@
+# require-prompt-file-metadata
+
+Require reusable Copilot prompt files to declare `description`, `agent`, and built-in agent-mode `tools` metadata.
+
+> **Rule catalog ID:** R002
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- prompt files with missing or blank `description`
+- prompt files with missing or blank `agent`
+- prompt files that still use deprecated `mode`
+- built-in `agent` prompt files without `tools`
+
+## Why this rule exists
+
+Prompt files are reusable requests. Explicit metadata makes them easier to understand, safer to run, and more consistent across repositories. Current VS Code prompt files use `agent` instead of the older `mode` key.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review this repository
+agent: agent
+---
+Audit the repository for stale branding and broken docs links.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review this repository
+agent: agent
+tools: [search/file_search, search/read_file]
+---
+Audit the repository for stale branding and broken docs links.
+```
+
+## Further reading
+
+- [VS Code Docs: Reusable prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-qualified-agent-handoff-models.md

@@ -0,0 +1,47 @@
+# require-qualified-agent-handoff-models
+
+Require Copilot custom-agent handoff models to use qualified `Model Name (vendor)` names.
+
+> **Rule catalog ID:** R013
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- handoff entries whose `model` value is present but not written in a qualified format such as `GPT-5 (copilot)`
+
+## Why this rule exists
+
+VS Code custom-agent docs specify that `handoffs.model` should use a qualified model name in the format `Model Name (vendor)`. That keeps handoff execution explicit and avoids ambiguous shorthand model names in multi-vendor Copilot environments.
+
+## ❌ Incorrect
+
+```md
+---
+description: Plan work carefully
+handoffs:
+  - label: Start Implementation
+    agent: Implementer
+    model: GPT-5
+---
+Plan the requested change before implementation.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Plan work carefully
+handoffs:
+  - label: Start Implementation
+    agent: Implementer
+    model: GPT-5 (copilot)
+---
+Plan the requested change before implementation.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-relative-agent-hook-cwd.md

@@ -0,0 +1,50 @@
+# require-relative-agent-hook-cwd
+
+Require Copilot custom-agent hook `cwd` values to stay relative to the repository root.
+
+> **Rule catalog ID:** R018
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- agent-scoped hook entries whose `cwd` value is empty
+- agent-scoped hook entries whose `cwd` value is absolute, home-relative, or otherwise not repository-relative
+
+## Why this rule exists
+
+VS Code documents hook `cwd` as a working directory path relative to the repository root. Absolute paths and empty values make hook execution less portable across developers and environments, and they drift away from the documented hook configuration format.
+
+## ❌ Incorrect
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      command: ./scripts/format.sh
+      cwd: C:\hooks
+---
+Format edited files after tool usage.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      command: ./scripts/format.sh
+      cwd: scripts/hooks
+---
+Format edited files after tool usage.
+```
+
+## Further reading
+
+- [VS Code Docs: Agent hooks](https://code.visualstudio.com/docs/copilot/customization/hooks)

package/docs/rules/require-relative-agent-links.md

@@ -0,0 +1,40 @@
+# require-relative-agent-links
+
+Require Copilot custom agents to use relative Markdown links for workspace files.
+
+> **Rule catalog ID:** R028
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- root-relative links such as `/docs/runbook.md`
+- file links that use other non-relative workspace-style paths instead of paths relative to the current agent file
+
+## Why this rule exists
+
+Relative links make custom-agent instructions portable across forks, local clones, and different workspace roots. They also match how Copilot customization content typically references repository resources.
+
+## ❌ Incorrect
+
+```md
+---
+description: Release coordinator
+---
+See [runbook](/docs/release-runbook.md).
+```
+
+## ✅ Correct
+
+```md
+---
+description: Release coordinator
+---
+See [runbook](../../docs/release-runbook.md).
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-relative-instructions-links.md

@@ -0,0 +1,42 @@
+# require-relative-instructions-links
+
+Require path-specific Copilot instructions files to use relative Markdown links for workspace files.
+
+> **Rule catalog ID:** R029
+
+## Targeted pattern scope
+
+- `.github/instructions/**/*.instructions.md`
+
+## What this rule reports
+
+- root-relative links such as `/docs/frontend.md`
+- file links that use other non-relative workspace-style paths instead of paths relative to the current instructions file
+
+## Why this rule exists
+
+Path-specific instructions often link to coding standards, examples, or package documentation in the repository. Relative links keep those references portable and make it clearer how the linked resource relates to the current instructions file.
+
+## ❌ Incorrect
+
+```md
+---
+description: Frontend guidance
+applyTo: src/**/*.ts
+---
+See [frontend standards](/docs/frontend.md).
+```
+
+## ✅ Correct
+
+```md
+---
+description: Frontend guidance
+applyTo: src/**/*.ts
+---
+See [frontend standards](../../docs/frontend.md).
+```
+
+## Further reading
+
+- [VS Code Docs: Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)

package/docs/rules/require-relative-prompt-links.md

@@ -0,0 +1,43 @@
+# require-relative-prompt-links
+
+Require Copilot prompt files to use relative Markdown links for workspace files.
+
+> **Rule catalog ID:** R024
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- root-relative Markdown links to workspace files inside prompt bodies
+- filesystem-style absolute paths in prompt Markdown links
+- `file:` links used instead of repository-relative workspace links
+
+## Why this rule exists
+
+VS Code prompt-file documentation says to reference workspace files with Markdown links that use relative paths based on the prompt file location. Enforcing relative workspace links keeps prompt files portable across machines, folders, and repositories.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review changes with repository guidance
+agent: agent
+---
+Review the proposed changes using [security guidance](/.github/instructions/security.instructions.md).
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review changes with repository guidance
+agent: agent
+---
+Review the proposed changes using [security guidance](../instructions/security.instructions.md).
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-relative-repository-hook-cwd.md

@@ -0,0 +1,43 @@
+# require-relative-repository-hook-cwd
+
+Require repository hook `cwd` values to use repository-relative paths.
+
+> **Rule catalog ID:** R062
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- absolute or otherwise non-relative `cwd` values in hook definitions
+
+## Why this rule exists
+
+Repository hooks are meant to run against the checked-out repository. Repository-relative working directories are more portable than absolute paths and avoid machine-specific configuration.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "cwd": "/tmp" }]
+  }
+}
+```
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "cwd": "scripts" }]
+  }
+}
+```
+
+## Further reading
+
+- [GitHub Docs: Using hooks with GitHub Copilot agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)

package/docs/rules/require-relative-skill-links.md

@@ -0,0 +1,42 @@
+# require-relative-skill-links
+
+Require Copilot skill definition files to use relative Markdown links for workspace resources.
+
+> **Rule catalog ID:** R052
+
+## Targeted pattern scope
+
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- root-relative or otherwise non-relative workspace file links in a skill body
+
+## Why this rule exists
+
+Skills frequently reference supplementary Markdown files, scripts, and local resources. Relative links keep those references portable and aligned with the repository-local nature of project skills.
+
+## ❌ Incorrect
+
+```md
+---
+name: review
+description: Review code changes.
+---
+See [guide](/docs/review.md).
+```
+
+## ✅ Correct
+
+```md
+---
+name: review
+description: Review code changes.
+---
+See [guide](guide.md).
+```
+
+## Further reading
+
+- [GitHub Docs: Creating agent skills for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/create-skills)

package/docs/rules/require-repository-hook-arrays.md

@@ -0,0 +1,33 @@
+# require-repository-hook-arrays
+
+Require each repository hook event entry in `hooks` to be an array.
+
+> **Rule catalog ID:** R058
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- hook event values that are objects, strings, numbers, or other non-array JSON values
+
+## Why this rule exists
+
+Each hook event is documented as an array of hook definitions. Enforcing that array shape keeps the JSON structure consistent and makes it possible to reason about multiple hooks on the same event.
+
+## ❌ Incorrect
+
+```json
+{ "version": 1, "hooks": { "sessionStart": {} } }
+```
+
+## ✅ Correct
+
+```json
+{ "version": 1, "hooks": { "sessionStart": [] } }
+```
+
+## Further reading
+
+- [GitHub Docs: Using hooks with GitHub Copilot agents](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)