add ai assist rules (#5312)

* add ai assist rules

* updates

* Update .clinerules/csharp-guidelines.md

* Update .clinerules/csharp-guidelines.md

---------

Co-authored-by: Bogdan Gavril <[email protected]>

Author: jennyf19

.clinerules/ai-guidelines.md

@@ -0,0 +1,12 @@
+# Development Guidelines
+
+This directory contains guidelines for AI assistants:
+
+* [Cline AI Assistant Guidelines](cline-instructions.md) - Guidelines specific to using Cline AI assistant
+* [C# Development Guidelines](csharp-guidelines.md) - C# coding standards and best practices
+* [MSAL.NET Guidelines](msal-guidelines.md) - Guidelines for working with MSAL.NET components and ecosystem
+
+The guidelines are split into separate files to organize different concerns:
+- Cline-specific capabilities and workflows
+- C# language-specific standards and practices
+- MSAL.NET -specific development guidelines and best practices

.clinerules/cline-instructions.md

@@ -0,0 +1,70 @@
+# Cline AI Assistant Guidelines
+
+## Core Principles
+
+* Make changes incrementally and verify each step
+* Always analyze existing code patterns before making changes
+* Prioritize built-in tools over shell commands
+* Follow existing project patterns and conventions
+* Maintain comprehensive test coverage
+
+## Tool Usage
+
+### File Operations
+* Use `read_file` for examining file contents instead of shell commands like `cat`
+* Use `replace_in_file` for targeted, specific changes to existing files
+* Use `write_to_file` only for new files or complete file rewrites
+* Use `list_files` to explore directory structures
+* Use `search_files` with precise regex patterns to find code patterns
+* Use `list_code_definition_names` to understand code structure before modifications
+
+### Command Execution
+* Use `execute_command` sparingly, preferring built-in file operation tools when possible
+* Always provide clear explanations for any executed commands
+* Set `requires_approval` to true for potentially impactful operations
+
+## Development Workflow
+
+### Planning Phase (PLAN MODE)
+* Begin complex tasks in PLAN mode to discuss approach
+* Analyze existing codebase patterns using search tools
+* Review related test files to understand testing patterns
+* Present clear implementation steps for approval
+* Ask clarifying questions early to avoid rework
+
+### Implementation Phase (ACT MODE)
+* Make changes incrementally, one file at a time
+* Verify each change before proceeding
+* Follow patterns discovered during planning phase
+* Focus on maintaining test coverage
+* Use error messages and linter feedback to guide fixes
+
+## Code Modifications
+
+### General Guidelines
+* Follow .editorconfig rules strictly
+* Preserve file headers and license information
+* Maintain consistent XML documentation
+* Respect existing error handling patterns
+* Keep line endings consistent with existing files
+
+### Quality Checks
+* Verify changes match existing code style
+* Ensure test coverage for new code
+* Validate changes against project conventions
+* Check for proper error handling
+* Maintain nullable reference type annotations
+
+## MCP Server Integration
+
+* Use appropriate MCP tools when available for specialized tasks
+* Access MCP resources efficiently using proper URIs
+* Handle MCP operation results appropriately
+* Follow server-specific authentication and usage patterns
+
+## Error Handling
+
+* Provide clear error messages and suggestions
+* Handle tool operation failures gracefully
+* Suggest alternative approaches when primary approach fails
+* Roll back changes if necessary to maintain stability

.clinerules/csharp-guidelines.md

@@ -0,0 +1,35 @@
+# C# Development Guidelines
+
+## General
+
+* Always use the latest version C#, currently C# 13 features
+* Never change global.json unless explicitly asked to
+* Never change package.json or package-lock.json files unless explicitly asked to
+* Never change NuGet.config files unless explicitly asked to
+
+## Formatting
+
+* Apply code-formatting style defined in `.editorconfig`
+* Prefer file-scoped namespace declarations and single-line using directives
+* Insert a newline before the opening curly brace of any code block (e.g., after `if`, `for`, `while`, `foreach`, `using`, `try`, etc.)
+* Ensure that the final return statement of a method is on its own line
+* Use pattern matching and switch expressions wherever possible
+* Use `nameof` instead of string literals when referring to member names
+* Ensure that XML doc comments are created for any public APIs. When applicable, include `<example>` and `<code>` documentation in the comments
+
+### Nullable Reference Types
+
+* Declare variables non-nullable, and check for `null` at entry points
+* Always use `is null` or `is not null` instead of `== null` or `!= null`
+* Trust the C# null annotations and don't add null checks when the type system says a value cannot be null
+
+### Testing
+
+* We use mstest SDK v3 for tests
+* Emit "Act", "Arrange" or "Assert" comments
+* Use NSubstitute for mocking in tests
+* Copy existing style in nearby files for test method names and capitalization
+
+## Running tests
+
+* To build and run tests in the repo, run `dotnet test`, you need one solution open, or specify the solution

.clinerules/msal-guidelines.md

@@ -0,0 +1,96 @@
+# MSAL.NET Guidelines
+
+## Overview
+
+Microsoft Authentication Library (MSAL) for .NET is a highly scalable authentication library that enables applications to authenticate with the Microsoft identity platform. For confidential client scenarios (server-side applications), the library provides:
+
+- Token acquisition for service-to-service calls
+- Flexible token caching with distributed cache support
+- Managed identity integration for Azure workloads
+- On-behalf-of flow for service-to-service delegated access
+
+Through its comprehensive feature set and proven reliability, MSAL.NET simplifies the implementation of secure authentication in server-side applications while maintaining optimal performance and security.
+
+## Repository Structure
+
+### Core Directories
+- `/src/client/Microsoft.Identity.Client` - Core MSAL functionality
+  - `ConfidentialClientApplication.cs` - Primary confidential client implementation
+  - `ApiConfig/` - API configuration and builders
+  - `Cache/` - Token cache implementations
+  - `ManagedIdentity/` - Azure managed identity support 
+  - `OAuth2/` - OAuth protocol implementations
+  - `Internal/` - Internal components and utilities
+- `/tests` - Unit tests and integration tests
+- `/benchmark` - Performance benchmarking infrastructure
+- `/tools` - Development and configuration tools
+
+## Core Components
+
+### Confidential Client Features
+- Microsoft.Identity.Client - Main MSAL library with confidential client support
+- Token cache implementations with extensible serialization
+- Managed identity integration for Azure environments
+
+### Authentication Components
+- IConfidentialClientApplication - Primary interface for confidential clients
+- Token cache providers and serialization extensibility
+- Client credential builders and configurations
+- Custom assertion providers (certificates, managed identity)
+
+## Development Guidelines
+
+### Core Development Principles
+- Follow .editorconfig rules strictly
+- Maintain backward compatibility due to widespread usage
+- Implement proper error handling and retry logic
+- Keep dependencies minimal and well-justified
+- Document security considerations thoroughly
+
+### Authentication Best Practices
+- Use certificate-based authentication over client secrets when possible
+- Implement token caching for optimal performance
+- Handle token expiration and refresh scenarios
+- Configure appropriate token lifetimes
+- Use managed identities in Azure environments when available
+
+### Performance Requirements
+- Implement distributed token caching for scale-out scenarios
+- Optimize token acquisition patterns
+- Use asynchronous APIs consistently
+- Configure appropriate retry policies
+- Benchmark token operations in high-throughput scenarios
+
+### Security Guidelines
+- Secure storage of client secrets and certificates
+- Implement proper token validation
+- Follow least-privilege principle for scopes
+- Handle sensitive data appropriately
+- Implement proper logging (avoiding sensitive data)
+
+### Testing Requirements
+- Maintain comprehensive test coverage
+- Include integration tests with actual identity endpoints
+- Test token cache implementations thoroughly
+- Verify managed identity scenarios
+- Include performance benchmarks for token operations
+
+### Public API Changes
+- The project uses Microsoft.CodeAnalysis.PublicApiAnalyzers
+- For any public API changes:
+  1. Update PublicAPI.Unshipped.txt in the package directory
+  2. Include complete API signatures
+  3. Consider backward compatibility impacts
+  4. Document breaking changes clearly
+
+Example format:
+```diff
+// Adding new API
++Microsoft.Identity.Client.ConfidentialClientApplication.AcquireTokenForClient() -> Task<AuthenticationResult>
++Microsoft.Identity.Client.IConfidentialClientApplication.GetAccounts() -> Task<IEnumerable<IAccount>>
+
+// Removing API (requires careful consideration)
+-Microsoft.Identity.Client.ConfidentialClientApplication.ObsoleteMethod() -> void
+```
+
+The analyzer enforces documentation of all public API changes in PublicAPI.Unshipped.txt and will fail the build if changes are not properly reflected.

.github/copilot-instructions.md

@@ -0,0 +1 @@
+Carefully review all markdown documents in the ../.clinerules folder. Those are your custom instructions.