AGENTS.md

July 10, 2026 · View on GitHub

Cross-tool agent guidance for Sentinel-As-Code. Recognised by GitHub Copilot, Claude, Gemini, Cursor, and other agentic coding tools that look for AGENTS.md at the repo root.

This file is a thin pointer — every agent / tool should follow the canonical instructions in .github/copilot-instructions.md.

TL;DR for agents

Read .github/copilot-instructions.md first. It carries the conventions (en-GB spelling, no em-dashes, commit-message format, no AI co-author trailers, etc.) that the rest of the docs assume.
Read Docs/README.md second. It is the table of contents for every concern in the repo.
Path-scoped instructions under .github/instructions/ carry per-folder schema rules and conventions. Copilot loads them automatically based on the file you're editing; other agents should read the matching <area>.instructions.md before editing files in that area.
Reusable prompts under .github/prompts/ are slash commands for repeatable tasks (new rule, new test, review-a-rule, regenerate-deps). Copilot exposes them in chat; other agents can read them as task templates.
Custom agents under .github/agents/ are persona configurations recognised by GitHub Copilot Chat (github.com), Copilot cloud agent, Copilot CLI, VS Code, JetBrains, Eclipse, and Xcode. Thirteen agents in two tiers:

Persona-broad (5) — repo-explorer, rule-author, content-editor, rule-tuner, code-explainer. Pick one based on the kind of help you want.

Engineering specialists (8) — pipeline-engineer, powershell-engineer, bicep-engineer, kql-engineer, test-engineer, security-reviewer, drift-engineer, dependencies-engineer. Pick one when the task is firmly in one engineering specialism.

Other agentic tools can treat the .agent.md files as role definitions.

Hard rules

Never push to main directly. All changes via PR.
Never push to auto/* branches. Bot-managed.
Never hand-edit dependencies.json. Auto-derived. Run ./Tools/Build-DependencyManifest.ps1 -Mode Generate instead.
Never include AI / LLM references in commit messages or Co-Authored-By trailers. This includes Claude, Anthropic, ChatGPT, Copilot, etc.
Never use em-dashes (—) in new prose. Use hyphens or parenthetical phrasing.
Always run Pester locally before pushing: ./Tools/Invoke-PRValidation.ps1.

What to do for common tasks

You want to...	Read	Use
Add a Sentinel analytical rule	Docs/Content/Analytical-Rules.md	Agent `rule-author` (works on github.com + VS Code) or prompt `/new-analytical-rule` (VS Code)
Add a hunting query	Docs/Content/Hunting-Queries.md	Agent `rule-author` or prompt `/new-hunting-query`
Add a Defender XDR detection	Docs/Content/Defender-Custom-Detections.md	Agent `rule-author` or prompt `/new-defender-detection`
Add a Pester test	Docs/Tests/Pester-Tests.md	Prompt `/new-pester-test` (VS Code)
Tune an existing rule's threshold / severity	The rule file itself	Agent `rule-tuner`
Understand how a piece of the repo works	Docs/README.md	Agent `repo-explorer`
Explain a rule's KQL	The rule file	Agent `code-explainer`
Edit a workflow / pipeline, port an ADO change to GH, or diagnose a CI/CD failure	Docs/Pipelines/README.md	Agent `pipeline-engineer`
Add a function to `Sentinel.Common` or refactor a script	Docs/Deploy/Scripts.md	Agent `powershell-engineer`
Edit a Bicep template	Docs/Infra/Bicep.md	Agent `bicep-engineer`
Optimise a KQL query (performance, parser extraction, watchlist promotion)	`.github/instructions/kql-queries.instructions.md`	Agent `kql-engineer`
Add coverage / refactor a Pester suite	Docs/Tests/Pester-Tests.md	Agent `test-engineer`
Security-review a playbook / script / workflow	The file in question	Agent `security-reviewer`
Triage a drift auto-PR or fix the drift detector	Docs/Tools/Sentinel-Drift-Detection.md	Agent `drift-engineer`
Fix wrong output in `dependencies.json` or extend the KQL discovery extractor	Docs/Tools/Dependency-Manifest.md	Agent `dependencies-engineer`
Refresh `dependencies.json` (routine regeneration)	Docs/Tools/Dependency-Manifest.md	Prompt `/regenerate-deps`

Test before you ship

Always run the Pester suite locally before opening a PR:

./Tools/Invoke-PRValidation.ps1 -RepoPath .

Five-job CI gate on every PR to main:

validate — Pester suites
bicep-build — az bicep build
arm-validate — Test-AzResourceGroupDeployment template validation (OIDC)
kql-validate — Microsoft.Azure.Kusto.Language parser
dependency-manifest — dependencies.json drift gate

A failing gate blocks merge. See Docs/Tests/Pester-Tests.md.