Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (80 loc) · 5.4 KB

AGENTS.md

File metadata and controls

97 lines (80 loc) · 5.4 KB
Raw

AGENTS.md

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

  1. 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.

  2. Read Docs/README.md second. It is the table of contents for every concern in the repo.

  3. 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.

  4. 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.

  5. 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.