eslint-plugin-copilot 1.0.5

package/docs/rules/require-repository-hook-command-shell.md

@@ -0,0 +1,44 @@
+# require-repository-hook-command-shell
+
+Require repository `command` hook definitions to declare at least one shell command under `bash` or `powershell`.
+
+> **Rule catalog ID:** R061
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- `type: "command"` hook objects that omit both `bash` and `powershell`
+- `command` hook objects whose shell command fields are blank
+
+## Why this rule exists
+
+A command hook without an executable shell command cannot do anything useful. Requiring at least one non-empty shell command catches incomplete hook definitions before they reach runtime.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command" }]
+  }
+}
+```
+
+## ✅ 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)

package/docs/rules/require-repository-hooks-object.md

@@ -0,0 +1,34 @@
+# require-repository-hooks-object
+
+Require repository hook configuration files to declare a top-level `hooks` object.
+
+> **Rule catalog ID:** R057
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- hook configuration files with a missing top-level `hooks` object
+- hook configuration files whose `hooks` value is not a JSON object
+
+## Why this rule exists
+
+The hook schema centers on a top-level `hooks` object keyed by event name. Without that object, the file cannot declare event-specific hook arrays in the documented structure.
+
+## ❌ Incorrect
+
+```json
+{ "version": 1 }
+```
+
+## ✅ 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)

package/docs/rules/require-repository-instructions-file.md

@@ -0,0 +1,42 @@
+# require-repository-instructions-file
+
+Require repositories that define Copilot customization assets to also provide `.github/copilot-instructions.md`.
+
+> **Rule catalog ID:** R005
+
+## Targeted pattern scope
+
+- `.github/instructions/**/*.instructions.md`
+- `.github/prompts/**/*.prompt.md`
+- `.github/agents/**/*.agent.md`
+- `.github/chatmodes/**/*.chatmode.md`
+- `AGENTS.md`
+- `CLAUDE.md`
+- `GEMINI.md`
+
+## What this rule reports
+
+- Copilot customization assets in repositories that do not also include `.github/copilot-instructions.md`
+
+## Why this rule exists
+
+Repository-wide instructions provide the broadest Copilot customization surface and are widely supported. When a repository already defines prompts, custom agents, legacy chat modes, agent instructions, or path-specific instructions, a baseline repository instructions file keeps the overall guidance coherent.
+
+## ❌ Incorrect
+
+```text
+.github/prompts/review.prompt.md
+```
+
+with no `.github/copilot-instructions.md` in the repository.
+
+## ✅ Correct
+
+```text
+.github/copilot-instructions.md
+.github/prompts/review.prompt.md
+```
+
+## 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)

package/docs/rules/require-skill-file-location.md

@@ -0,0 +1,33 @@
+# require-skill-file-location
+
+Require project skill definition files to live at a documented `.github/skills/<skill>/SKILL.md` or `.claude/skills/<skill>/SKILL.md` path.
+
+> **Rule catalog ID:** R045
+
+## Targeted pattern scope
+
+- `**/SKILL.md`
+
+## What this rule reports
+
+- `SKILL.md` files that are not inside a documented project skill directory
+
+## Why this rule exists
+
+GitHub and compatible skill consumers expect project skills to live in a predictable directory structure. Keeping skill definitions in those documented locations makes discovery and portability much more reliable.
+
+## ❌ Incorrect
+
+```text
+docs/SKILL.md
+```
+
+## ✅ Correct
+
+```text
+.github/skills/review-checklist/SKILL.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-skill-file-metadata.md

@@ -0,0 +1,40 @@
+# require-skill-file-metadata
+
+Require Copilot skill definition files to declare `name` and `description` frontmatter.
+
+> **Rule catalog ID:** R046
+
+## Targeted pattern scope
+
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- skill files with no YAML frontmatter
+- missing or blank `name` values
+- missing or blank `description` values
+
+## Why this rule exists
+
+A skill definition without basic identifying metadata is hard for both humans and tools to understand. `name` and `description` provide the minimal contract that explains what the skill is and when it should be used.
+
+## ❌ Incorrect
+
+```md
+Review code carefully and use the security checklist.
+```
+
+## ✅ Correct
+
+```md
+---
+name: review-checklist
+description: Review code changes with the repository checklist.
+---
+Review code carefully and use the security checklist.
+```
+
+## 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-skill-md-filename.md

@@ -0,0 +1,43 @@
+# require-skill-md-filename
+
+Require markdown files that declare skill-definition frontmatter to use the documented `SKILL.md` filename.
+
+> **Rule catalog ID:** R055
+
+## Targeted pattern scope
+
+- `.github/skills/**/*.md`
+- `.claude/skills/**/*.md`
+
+## What this rule reports
+
+- markdown files inside skill directories that look like skill definitions but are not named `SKILL.md`
+
+## Why this rule exists
+
+Supplementary Markdown files are allowed inside a skill directory, but the actual skill definition file has a special documented filename. Enforcing that distinction keeps discovery predictable while still allowing supporting docs next to the skill.
+
+## ❌ Incorrect
+
+```text
+.github/skills/review/README.md
+```
+
+with frontmatter such as:
+
+```md
+---
+name: review
+description: Review code changes.
+---
+```
+
+## ✅ Correct
+
+```text
+.github/skills/review/SKILL.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-skill-name-match-directory.md

@@ -0,0 +1,46 @@
+# require-skill-name-match-directory
+
+Require Copilot skill `name` metadata to match the skill directory name.
+
+> **Rule catalog ID:** R050
+
+## Targeted pattern scope
+
+- `.github/skills/**/SKILL.md`
+- `.claude/skills/**/SKILL.md`
+
+## What this rule reports
+
+- explicit skill `name` values that do not match the parent skill directory name
+
+## Why this rule exists
+
+A mismatch between the skill directory and the declared skill name makes repositories harder to navigate and increases the chance that links, docs, or user expectations refer to the wrong identifier.
+
+## ❌ Incorrect
+
+```text
+.github/skills/review/SKILL.md
+```
+
+with frontmatter:
+
+```md
+---
+name: review-security
+description: Review code changes.
+---
+```
+
+## ✅ Correct
+
+```md
+---
+name: review
+description: Review code changes.
+---
+```
+
+## 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-string-repository-hook-env-values.md

@@ -0,0 +1,43 @@
+# require-string-repository-hook-env-values
+
+Require repository hook `env` objects to use string values.
+
+> **Rule catalog ID:** R066
+
+## Targeted pattern scope
+
+- `.github/hooks/**/*.json`
+
+## What this rule reports
+
+- `env` objects that contain non-string values such as numbers, arrays, or nested objects
+
+## Why this rule exists
+
+Environment variables are string-based in practice. Requiring string values avoids surprising serialization behavior and keeps hook environment configuration aligned with how shells consume variables.
+
+## ❌ Incorrect
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "env": { "RETRIES": 3 } }]
+  }
+}
+```
+
+## ✅ Correct
+
+```json
+{
+  "version": 1,
+  "hooks": {
+    "sessionStart": [{ "type": "command", "bash": "echo ready", "env": { "RETRIES": "3" } }]
+  }
+}
+```
+
+## 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-agent-argument-hint.md

@@ -0,0 +1,42 @@
+# require-valid-agent-argument-hint
+
+Require Copilot custom-agent `argument-hint` metadata to be a non-empty scalar when present.
+
+> **Rule catalog ID:** R043
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- blank custom-agent `argument-hint` values
+- malformed non-scalar `argument-hint` values in supported frontmatter
+
+## Why this rule exists
+
+A custom agent's `argument-hint` is supposed to help callers understand what to pass when invoking the agent. If that field is present, it should contain usable guidance rather than an empty placeholder.
+
+## ❌ Incorrect
+
+```md
+---
+description: Investigate a bug
+argument-hint:
+---
+Investigate the supplied issue.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Investigate a bug
+argument-hint: <issue-url-or-stack-trace>
+---
+Investigate the supplied issue.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

package/docs/rules/require-valid-agent-handoff-send.md

@@ -0,0 +1,49 @@
+# require-valid-agent-handoff-send
+
+Require Copilot custom-agent handoff `send` values to use documented boolean metadata when present.
+
+> **Rule catalog ID:** R021
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- custom-agent handoff entries whose `send` value is present but not `true` or `false`
+- empty `send` fields in handoff metadata
+
+## Why this rule exists
+
+VS Code documents `handoffs.send` as an optional boolean flag that controls whether the handoff prompt is auto-submitted. Restricting `send` to boolean values keeps guided handoff behavior explicit and aligned with the documented custom-agent frontmatter format.
+
+## ❌ Incorrect
+
+```md
+---
+description: Generate an implementation plan
+handoffs:
+  - label: Start Implementation
+    agent: implementation
+    send: later
+---
+Create a reviewable implementation plan.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Generate an implementation plan
+handoffs:
+  - label: Start Implementation
+    agent: implementation
+    prompt: Implement the approved plan.
+    send: true
+---
+Create a reviewable implementation plan.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)

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

@@ -0,0 +1,51 @@
+# require-valid-agent-handoffs
+
+Require Copilot custom-agent handoffs to define the metadata needed for usable guided transitions.
+
+> **Rule catalog ID:** R012
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- handoff entries that omit a non-empty `label`
+- handoff entries that omit a non-empty `agent`
+- handoff entries that set `send: true` without also defining a non-empty `prompt`
+
+## Why this rule exists
+
+VS Code custom-agent handoffs are meant to create guided transitions between agents. The documentation describes each handoff as specifying a button label and a target agent, with an optional prompt to send. If a repository defines incomplete handoff entries, the workflow becomes ambiguous or unusable.
+
+When `send: true` is set, the prompt is auto-submitted as the next step. Requiring a prompt in that case keeps the handoff explicit instead of auto-submitting an empty request.
+
+## ❌ Incorrect
+
+```md
+---
+description: Plan work carefully
+handoffs:
+  - label: Start Implementation
+    send: true
+---
+Plan the requested change before implementation.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Plan work carefully
+handoffs:
+  - label: Start Implementation
+    agent: Implementer
+    prompt: Implement the approved plan.
+    send: true
+---
+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-valid-agent-hook-events.md

@@ -0,0 +1,47 @@
+# require-valid-agent-hook-events
+
+Require Copilot custom-agent hooks to use supported VS Code hook event names.
+
+> **Rule catalog ID:** R015
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- agent-scoped hook event names that are not one of the supported VS Code lifecycle events
+
+## Why this rule exists
+
+VS Code agent hooks only support a defined set of lifecycle event names: `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PreCompact`, `SubagentStart`, `SubagentStop`, and `Stop`. Using a different event name makes the hook configuration drift away from the documented contract.
+
+## ❌ Incorrect
+
+```md
+---
+description: Format files after editing
+hooks:
+  AfterEdit:
+    - type: command
+      command: ./scripts/format.sh
+---
+Format edited files after tool usage.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      command: ./scripts/format.sh
+---
+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-valid-agent-hook-timeouts.md

@@ -0,0 +1,49 @@
+# require-valid-agent-hook-timeouts
+
+Require Copilot custom-agent hook `timeout` values to be numeric seconds when present.
+
+> **Rule catalog ID:** R016
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- agent-scoped hook entries whose `timeout` value is present but not numeric
+
+## Why this rule exists
+
+VS Code hook documentation defines `timeout` as a numeric value in seconds. Keeping hook timeout metadata numeric avoids ambiguous strings and keeps custom-agent hook frontmatter aligned with the documented hook command format.
+
+## ❌ Incorrect
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      command: ./scripts/format.sh
+      timeout: soon
+---
+Format edited files after tool usage.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      command: ./scripts/format.sh
+      timeout: 15
+---
+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-valid-agent-hooks.md

@@ -0,0 +1,49 @@
+# require-valid-agent-hooks
+
+Require Copilot custom-agent hooks to use `type: command` and define at least one command property.
+
+> **Rule catalog ID:** R014
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- hook entries whose `type` is missing or not `command`
+- hook entries that do not define any of `command`, `windows`, `linux`, or `osx`
+
+## Why this rule exists
+
+Agent-scoped hooks in VS Code use the same structure as hook configuration files. The hook documentation states that each hook entry must have `type: "command"` and at least one command property. This rule catches incomplete agent-scoped hook entries before they silently fail or miscommunicate behavior.
+
+## ❌ Incorrect
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      cwd: scripts
+---
+Format edited files after tool usage.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Format files after editing
+hooks:
+  PostToolUse:
+    - type: command
+      command: ./scripts/format.sh
+---
+Format edited files after tool usage.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+- [VS Code Docs: Agent hooks](https://code.visualstudio.com/docs/copilot/customization/hooks)

package/docs/rules/require-valid-agent-invocation-controls.md

@@ -0,0 +1,45 @@
+# require-valid-agent-invocation-controls
+
+Require Copilot custom-agent invocation-control flags to use documented boolean values when present.
+
+> **Rule catalog ID:** R020
+
+## Targeted pattern scope
+
+- `.github/agents/**/*.agent.md`
+
+## What this rule reports
+
+- invalid `user-invocable` values
+- invalid `disable-model-invocation` values
+- empty invocation-control fields when those fields are present
+
+## Why this rule exists
+
+VS Code documents `user-invocable` and `disable-model-invocation` as boolean control flags for how a custom agent appears in the agent picker and whether it can be invoked as a subagent. Restricting these fields to boolean values keeps custom-agent invocation behavior explicit and predictable.
+
+## ❌ Incorrect
+
+```md
+---
+description: Internal helper agent
+user-invocable: sometimes
+---
+Use this agent for internal helper work.
+```
+
+## ✅ Correct
+
+```md
+---
+description: Internal helper agent
+user-invocable: false
+disable-model-invocation: true
+---
+Use this agent for internal helper work.
+```
+
+## Further reading
+
+- [VS Code Docs: Custom agents](https://code.visualstudio.com/docs/copilot/customization/custom-agents)
+- [VS Code Docs: Subagents](https://code.visualstudio.com/docs/copilot/agents/subagents)