eslint-plugin-copilot 1.0.5

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

@@ -0,0 +1,45 @@
+# require-valid-agent-mcp-servers
+
+Require Copilot custom-agent `mcp-servers` metadata to be a non-empty list when present.
+
+> **Rule catalog ID:** R023
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- empty `mcp-servers` values in custom-agent frontmatter
+- empty `mcp-servers` lists such as `[]`
+- scalar `mcp-servers` values instead of the documented list form
+
+## Why this rule exists
+
+VS Code documents `mcp-servers` as an optional list of MCP server config JSON entries for GitHub Copilot-targeted custom agents. Keeping that metadata in the documented list form helps avoid ambiguous or no-op custom-agent configuration.
+
+## ❌ Incorrect
+
+```md
+---
+description: Coordinate release automation
+target: github-copilot
+mcp-servers: release-coordinator.json
+---
+Coordinate release tasks through MCP servers.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Coordinate release automation
+target: github-copilot
+mcp-servers: ['release-coordinator.json', 'observability.json']
+---
+Coordinate release tasks through MCP servers.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-valid-agent-model.md

@@ -0,0 +1,43 @@
+# require-valid-agent-model
+
+Require Copilot custom-agent `model` metadata to be a non-empty model name or non-empty prioritized list of model names when present.
+
+> **Rule catalog ID:** R022
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- empty custom-agent `model` values
+- empty custom-agent model lists such as `[]`
+- malformed model list literals that collapse to an empty list
+
+## Why this rule exists
+
+VS Code documents custom-agent `model` as either a single model name string or a prioritized array of model names. Keeping `model` metadata in one of those documented shapes helps ensure model overrides are intentional and usable.
+
+## ❌ Incorrect
+
+```md
+---
+description: Implement approved changes
+model: []
+---
+Implement the requested changes.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Implement approved changes
+model: ['Claude Haiku 4.5 (copilot)', 'GPT-5 (copilot)']
+---
+Implement the requested changes.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-valid-agent-name.md

@@ -0,0 +1,42 @@
+# require-valid-agent-name
+
+Require Copilot custom-agent `name` metadata to be a non-empty scalar when present.
+
+> **Rule catalog ID:** R042
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- blank custom-agent `name` values
+- malformed non-scalar `name` values in supported frontmatter
+
+## Why this rule exists
+
+Custom agents can declare a friendly `name` in frontmatter. When present, that field should be an actual scalar string so the agent has a stable human-facing identity instead of an empty placeholder.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review implementation quality
+name:
+---
+Review the implementation carefully.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review implementation quality
+name: reviewer
+---
+Review the implementation carefully.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-valid-agent-subagents.md

@@ -0,0 +1,52 @@
+# require-valid-agent-subagents
+
+Require Copilot custom-agent `agents` metadata to be `*`, `[]`, or a non-empty list of explicit agent names.
+
+> **Rule catalog ID:** R017
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- scalar `agents` values other than `*`
+- malformed `agents` metadata that is neither `*`, `[]`, nor a list of explicit agent names
+- wildcard list entries such as `['*', 'Planner']`
+
+## Why this rule exists
+
+VS Code documents the `agents` field as accepting one of three shapes: a list of allowed agent names, `*` to allow all available subagents, or `[]` to disable subagent use. Keeping that metadata in one of the documented forms makes subagent orchestration predictable and avoids accidental misconfiguration.
+
+## ❌ Incorrect
+
+```md
+---
+description: Coordinate feature work
+agents: Planner
+---
+Use subagents when helpful.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Coordinate feature work
+agents: ['Planner', 'Reviewer']
+---
+Use subagents when helpful.
+```
+
+```md
+---
+description: Stay in the current agent only
+agents: []
+---
+Do not use subagents for this workflow.
+```
+
+## Further reading
+
+- [VS Code Docs: Subagents](https://code.visualstudio.com/docs/copilot/agents/subagents)
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-valid-agent-target.md

@@ -0,0 +1,44 @@
+# require-valid-agent-target
+
+Require Copilot custom-agent `target` metadata to use a documented target value when present.
+
+> **Rule catalog ID:** R019
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- empty `target` values in custom-agent frontmatter
+- custom-agent `target` values other than `vscode` or `github-copilot`
+
+## Why this rule exists
+
+VS Code documents `target` as the target environment or context for a custom agent and currently supports `vscode` and `github-copilot`. Using other target values drifts away from the documented custom-agent contract and can make the agent configuration ambiguous.
+
+This rule intentionally defers to the more specific `require-github-copilot-target-for-mcp-servers` rule when `mcp-servers` metadata is present.
+
+## ❌ Incorrect
+
+```md
+---
+description: Plan work inside VS Code
+target: github
+---
+Plan work before implementation starts.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Plan work inside VS Code
+target: vscode
+---
+Plan work before implementation starts.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-valid-agent-tools.md

@@ -0,0 +1,43 @@
+# require-valid-agent-tools
+
+Require Copilot custom-agent `tools` metadata to be a non-empty list of tool or tool-set names when present.
+
+> **Rule catalog ID:** R025
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- empty custom-agent `tools` values
+- scalar custom-agent `tools` values instead of the documented list form
+- empty custom-agent `tools` lists such as `[]`
+
+## Why this rule exists
+
+VS Code documents custom-agent `tools` as a list of tool or tool set names. Keeping that metadata in the documented list shape helps ensure a custom agent's allowed tool surface is explicit and machine-usable.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review implementation quality
+tools: search/codebase
+---
+Review the implementation carefully.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review implementation quality
+tools: ['search/codebase', 'fetch/web']
+---
+Review the implementation carefully.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

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

@@ -0,0 +1,45 @@
+# require-valid-instructions-apply-to-globs
+
+Require path-specific Copilot instructions `applyTo` metadata to use repository-relative glob patterns.
+
+> **Rule catalog ID:** R044
+
+## Targeted pattern scope
+
+- `.github/instructions/**/*.instructions.md`
+
+## What this rule reports
+
+- `applyTo` entries that start with `./` or `../`
+- absolute paths such as `/src/**` or `C:\repo\src\**`
+- path-like values that use URI schemes or backslashes
+- empty or otherwise non-portable `applyTo` patterns
+
+## Why this rule exists
+
+Path-specific instructions are meant to target files relative to the repository layout. Repository-relative globs are more portable across machines and clients than absolute paths, URI-like references, or current-directory-relative shortcuts.
+
+## ❌ Incorrect
+
+```md
+---
+description: Frontend guidance
+applyTo: ./src/**/*.ts
+---
+Use explicit return types.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Frontend guidance
+applyTo: src/**/*.ts
+---
+Use explicit return types.
+```
+
+## Further reading
+
+- [GitHub Docs: Add repository custom instructions for GitHub Copilot](https://docs.github.com/en/copilot/how-tos/configure-custom-instructions/add-repository-instructions)
+- [VS Code Docs: Custom instructions](https://code.visualstudio.com/docs/copilot/customization/custom-instructions)

package/docs/rules/require-valid-prompt-argument-hint.md

@@ -0,0 +1,42 @@
+# require-valid-prompt-argument-hint
+
+Require Copilot prompt-file `argument-hint` metadata to be a non-empty scalar when present.
+
+> **Rule catalog ID:** R041
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- blank `argument-hint` values
+- non-scalar `argument-hint` values that do not parse as one string
+
+## Why this rule exists
+
+`argument-hint` is meant to describe the argument shape a prompt expects. If you include it, it should give users and clients a concrete hint rather than an empty or malformed placeholder.
+
+## ❌ Incorrect
+
+```md
+---
+description: Summarize a change
+argument-hint:
+---
+Summarize the supplied change.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Summarize a change
+argument-hint: <pull-request-number>
+---
+Summarize the supplied change.
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-valid-prompt-model.md

@@ -0,0 +1,45 @@
+# require-valid-prompt-model
+
+Require Copilot prompt-file `model` metadata to be a non-empty single model name when present.
+
+> **Rule catalog ID:** R026
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- empty prompt-file `model` values
+- prompt-file `model` lists where the docs only describe a single model field
+- malformed list literals such as `model: []`
+
+## Why this rule exists
+
+VS Code documents prompt-file `model` as the language model used when running the prompt. Unlike custom agents, the prompt-file docs do not describe a prioritized model array shape, so keeping prompt `model` metadata to a single non-empty model name keeps prompt configuration aligned with the documented contract.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review changes
+agent: plan
+model: ['Claude Haiku 4.5 (copilot)', 'GPT-5 (copilot)']
+---
+Review the requested changes.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review changes
+agent: plan
+model: GPT-5 (copilot)
+---
+Review the requested changes.
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-valid-prompt-name.md

@@ -0,0 +1,42 @@
+# require-valid-prompt-name
+
+Require Copilot prompt-file `name` metadata to be a non-empty scalar when present.
+
+> **Rule catalog ID:** R040
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- blank `name` values
+- non-scalar `name` values that do not parse as a single string in supported frontmatter
+
+## Why this rule exists
+
+Prompt files can expose a slash-command name through frontmatter. When `name` is present, it should be a real string value instead of an empty placeholder so the prompt has a stable, intentional command name.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review a pull request
+name:
+---
+Review the proposed changes.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review a pull request
+name: review-pr
+---
+Review the proposed changes.
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-valid-prompt-tools.md

@@ -0,0 +1,43 @@
+# require-valid-prompt-tools
+
+Require Copilot prompt-file `tools` metadata to be a non-empty list of tool or tool-set names when present.
+
+> **Rule catalog ID:** R027
+
+## Targeted pattern scope
+
+- `.github/prompts/**/*.prompt.md`
+
+## What this rule reports
+
+- scalar `tools` values such as `tools: fetch`
+- empty `tools` values
+- empty prompt tool lists such as `tools: []`
+
+## Why this rule exists
+
+VS Code documents reusable prompt-file `tools` metadata as a list. Keeping prompt tool declarations in that documented list form makes the allowed tool surface explicit and easier for Copilot clients to interpret consistently.
+
+## ❌ Incorrect
+
+```md
+---
+description: Review a pull request
+tools: fetch
+---
+Review the proposed changes.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Review a pull request
+tools: ['search/codebase', 'fetch/web']
+---
+Review the proposed changes.
+```
+
+## Further reading
+
+- [VS Code Docs: Prompt files](https://code.visualstudio.com/docs/copilot/customization/prompt-files)

package/docs/rules/require-valid-repository-hook-command-type.md

@@ -0,0 +1,45 @@
+# require-valid-repository-hook-command-type
+
+Require repository hook definitions to declare a supported `type` value such as `command` or `prompt`.
+
+> **Rule catalog ID:** R060
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- hook objects with a missing `type`
+- hook objects whose `type` is not a supported string
+
+## Why this rule exists
+
+Each hook definition needs an explicit type so Copilot knows how to interpret it. Requiring a supported `type` catches incomplete hook entries and obvious schema mismatches.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "bash": "echo ready" }]
+  }
+}
+```
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready" }]
+  }
+}
+```
+
+## 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)
+- [GitHub Docs: GitHub Copilot CLI command reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference)

package/docs/rules/require-valid-repository-hook-env.md

@@ -0,0 +1,43 @@
+# require-valid-repository-hook-env
+
+Require repository hook `env` values to be JSON objects when present.
+
+> **Rule catalog ID:** R065
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- `env` values that are arrays, numbers, strings, or other non-object JSON values
+
+## Why this rule exists
+
+Hook environment variables are documented as key/value mappings. Requiring an object shape keeps that contract explicit and prevents malformed environment configuration.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "env": ["LOG_LEVEL"] }]
+  }
+}
+```
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "env": { "LOG_LEVEL": "info" } }]
+  }
+}
+```
+
+## 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-valid-repository-hook-events.md

@@ -0,0 +1,34 @@
+# require-valid-repository-hook-events
+
+Require repository hook configuration files to use supported hook event names.
+
+> **Rule catalog ID:** R059
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- unsupported hook event names inside the top-level `hooks` object
+
+## Why this rule exists
+
+Repository hooks only run for a fixed set of documented lifecycle events. Rejecting unknown event names helps catch typos and prevents configuration from silently doing nothing.
+
+## ❌ Incorrect
+
+```json
+{ "version": 1, "hooks": { "beforeAnything": [] } }
+```
+
+## ✅ 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)
+- [GitHub Docs: GitHub Copilot CLI command reference](https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-command-reference)

package/docs/rules/require-valid-repository-hook-timeouts.md

@@ -0,0 +1,43 @@
+# require-valid-repository-hook-timeouts
+
+Require repository hook `timeoutSec` values to be positive integers when present.
+
+> **Rule catalog ID:** R064
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- zero, negative, fractional, or non-numeric `timeoutSec` values
+
+## Why this rule exists
+
+Hook timeouts are numeric execution budgets. Requiring a positive integer keeps the hook configuration aligned with the documented schema and avoids values that are ambiguous or unusable at runtime.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "timeoutSec": 0 }]
+  }
+}
+```
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "timeoutSec": 10 }]
+  }
+}
+```
+
+## 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-valid-repository-hook-version.md

@@ -0,0 +1,34 @@
+# require-valid-repository-hook-version
+
+Require repository hook configuration files to declare `version: 1`.
+
+> **Rule catalog ID:** R056
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- hook configuration files with a missing `version`
+- hook configuration files whose `version` is not exactly `1`
+
+## Why this rule exists
+
+Repository hook files use an explicit versioned JSON schema. Requiring the documented `version: 1` value catches incompatible or incomplete hook files early.
+
+## ❌ Incorrect
+
+```json
+{ "version": 2, "hooks": {} }
+```
+
+## ✅ Correct
+
+```json
+{ "version": 1, "hooks": {} }
+```
+
+## 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)