Add repository guidance for AI agents

[Bogdan Gavril (bgavrilMS)]

Summary

• add a root AGENTS.md with MSAL.NET repository structure, build/test commands, coding requirements, API compatibility guidance, and testing expectations
• document multi-targeting and mobile considerations for production source reviews
• document the preferred unit-test strategy and restricted use of integration tests
• add mandatory PR and Azure DevOps work-item telemetry tagging instructions

assistance: agentic-mixed
type: docs
agent-tool: copilot-cli
agent-model: gpt-5.6-sol
work-item: AB#n/a

[Copilot]

Pull request overview

Adds a new repository-level AGENTS.md document intended to guide AI coding agents contributing to MSAL.NET by pointing them at authoritative repo guidance and summarizing repo structure, build/testing context, and core coding requirements.

Changes:

• Introduces AGENTS.md with high-level MSAL.NET overview and “authoritative guidance” links.
• Documents repository layout (src/tests/docs/build/tools) and notes on multi-targeting/test framework expectations.
• Summarizes key coding requirements (no drive-by refactors, async consistency, input validation, no secrets/PII).

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (7)

.github/instructions/src.instructions.md:9

• This sentence has a typo ("multi-targetting") and uses numeric "2" in prose; please correct to "multi-targeting" and "two".

To support multi-targetting, 2 approaches are used:

.github/instructions/tests.instructions.md:30

• Typo in "sceanrios" (should be "scenarios"). While here, rewording slightly avoids "etc." and makes the guidance more precise.

- Prefer unit tests that mock the HTTP layer. A good unit test uses the public API and uses minimal mocking to verify behavior. Ideally you only mock the HTTP layer, but sometimes it isn't possible, for example for MSI sceanrios env variables need to be mocked etc.

AGENTS.md:56

• The PR description says AGENTS.md includes build/test commands, but this section currently describes tooling without providing any concrete commands. Either add example dotnet commands here or adjust the PR description to match.

## Building and Testing

This is a standard .net project and standard dotnet tooling applies. The only complexity is that this is a multi-target SDK which explicitly targets: 

- .NET Framework and .NET
- Netstandard 2.0
- mobile target frameworks 

Note that the regular build ignores the mobile target frameworks. The CI builds those. 

.github/instructions/src.instructions.md:7

• The heading contains a typo: "Multi-targetting" should be "Multi-targeting".

This issue also appears on line 9 of the same file.

## Multi-targetting support

.github/instructions/src.instructions.md:12

• There is a typo in "compilaton"; also consider formatting code tokens/paths with backticks to avoid ambiguity.

- #if directives to conditionally compile code for different target frameworks
- conditional compilaton of entire files in src/client/Microsoft.Identity.Client/Platforms

.github/instructions/src.instructions.md:14

• ".NET FWK" is unclear/abbreviated for repo guidance; spelling out ".NET Framework" and formatting #if as code improves readability.

Since most development happens in .NET and .NET FWK, which have similar capabilities, we generally prefer #if directives, as they are easier to understand. 

.github/instructions/tests.instructions.md:29

• Typo in "sceanrios" (should be "scenarios").

This issue also appears on line 30 of the same file.

- Integration tests are slow and should only be used for mainline sceanrios.

[Gladwin Johnson VR (gladjohn)]

I see even IdWeb reporting the agents.md is missing. This is good.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (5)

.github/instructions/src.instructions.md:12

• Typo: “compilaton” should be “compilation” (and the path is clearer if formatted as code).

- conditional compilaton of entire files in src/client/Microsoft.Identity.Client/Platforms

AGENTS.md:54

• Minor terminology/casing: “.net” should be “.NET”, and “Netstandard 2.0” should match the actual TFM name (netstandard2.0).

This is a standard .net project and standard dotnet tooling applies. The only complexity is that this is a multi-target SDK which explicitly targets: 

- .NET Framework and .NET
- Netstandard 2.0
- mobile target frameworks 

.github/instructions/tests.instructions.md:30

• Typo in “scenarios” and the second bullet is hard to read/has additional typos (“sceanrios”). Consider tightening the wording so the guidance is clear.

- Integration tests are slow and should only be used for mainline sceanrios.
- Prefer unit tests that mock the HTTP layer. A good unit test uses the public API and uses minimal mocking to verify behavior. Ideally you only mock the HTTP layer, but sometimes it isn't possible, for example for MSI sceanrios env variables need to be mocked etc.

.github/instructions/src.instructions.md:10

• Spelling/wording: “multi-targetting” should be “multi-targeting”, and “2” is better written as “two” in prose.

This issue also appears on line 12 of the same file.

## Multi-targetting support

To support multi-targetting, 2 approaches are used:

AGENTS.md:34

• Inconsistent capitalization: elsewhere this doc uses “mTLS Proof-of-Possession” / “PoP”, but this line says “POP”. Use “PoP” for consistency.

- `src/client/Microsoft.Identity.Client.KeyAttestation/`: key attestation
  support, for mTLS POP support

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated no new comments.

Suppressed comments (5)

.github/instructions/src.instructions.md:12

• Spelling: “compilaton” should be “compilation”.

- conditional compilaton of entire files in src/client/Microsoft.Identity.Client/Platforms

AGENTS.md:54

• Casing/spelling: “.net” should be “.NET”, and “Netstandard” should be “netstandard” (framework name casing).

This is a standard .net project and standard dotnet tooling applies. The only complexity is that this is a multi-target SDK which explicitly targets: 

- .NET Framework and .NET
- Netstandard 2.0
- mobile target frameworks 

AGENTS.md:34

• Inconsistent casing/abbreviation: this line uses “mTLS POP”, but elsewhere the doc uses “Proof-of-Possession” (PoP). For clarity and consistency, use “PoP” here as well (and avoid repeating “support”).

- `src/client/Microsoft.Identity.Client.KeyAttestation/`: key attestation
  support, for mTLS POP support

.github/instructions/tests.instructions.md:30

• Spelling: “sceanrios” appears twice; should be “scenarios”.

- Integration tests are slow and should only be used for mainline sceanrios.
- Prefer unit tests that mock the HTTP layer. A good unit test uses the public API and uses minimal mocking to verify behavior. Ideally you only mock the HTTP layer, but sometimes it isn't possible, for example for MSI sceanrios env variables need to be mocked etc.

.github/instructions/src.instructions.md:9

• Spelling: “Multi-targetting” / “multi-targetting” should be “Multi-targeting” / “multi-targeting”.

This issue also appears on line 12 of the same file.

## Multi-targetting support

To support multi-targetting, 2 approaches are used: