add ai assist rules

.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
+* [IdentityModel Guidelines](identityModel-guidelines.md) - Guidelines for working with IdentityModel 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
+- IdentityModel-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 xUnit SDK v2 for tests
+* Emit "Act", "Arrange" or "Assert" comments
+* Use Moq 4.14.x 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/identityModel-guidelines.md

@@ -0,0 +1,95 @@
+# IdentityModel Guidelines
+
+## Overview
+
+IdentityModel Extensions for .NET is a foundational authentication and authorization library that provides the core building blocks for implementing token-based security in .NET applications. The library specializes in:
+
+- JSON Web Token (JWT) creation, validation, and management
+- OpenID Connect (OIDC) and OAuth 2.0 protocol implementations
+- Token validation and security key management
+- High-performance token handling
+- SAML token support
+- WS-Federation protocol support
+
+Through its robust architecture and battle-tested components, IdentityModel provides the security foundation used by numerous authentication libraries and frameworks, including Microsoft.Identity.Web and ASP.NET core authentication.
+
+## Repository Structure
+
+### Core Directories
+- `/src` - Contains all source code for the Microsoft.IdentityModel packages
+  - JsonWebTokens - Core JWT functionality
+  - Protocols - Protocol implementations (OIDC, OAuth, WS-Fed)
+  - Tokens - Token handling and validation
+  - Xml - XML security functionality
+  - Validators - Token validation components
+- `/tests` - Unit tests, integration tests, and test utilities
+- `/benchmark` - Performance benchmarking infrastructure
+- `/build` - Build configuration and scripts
+
+## Shipped Packages
+
+### Core Token Handling
+- Microsoft.IdentityModel.JsonWebTokens - JWT processing and validation
+- Microsoft.IdentityModel.Tokens - Security token handling and validation
+- System.IdentityModel.Tokens.Jwt - JWT framework for creating and validating JSON Web Tokens
+
+### Protocol Support
+- Microsoft.IdentityModel.Protocols - Base protocol handling infrastructure
+- Microsoft.IdentityModel.Protocols.OpenIdConnect - OpenID Connect protocol implementation
+- Microsoft.IdentityModel.Protocols.WsFederation - WS-Federation protocol support
+- Microsoft.IdentityModel.Protocols.SignedHttpRequest - Signed HTTP request handling
+
+### Security and Integration
+- Microsoft.IdentityModel.Tokens.Saml - SAML token support
+- Microsoft.IdentityModel.Xml - XML security functionality
+- Microsoft.IdentityModel.Validators - Token validation utilities
+
+## Development Guidelines
+
+### Core Development Principles
+- Follow .editorconfig rules strictly
+- Prioritize performance in token handling operations
+- Maintain backward compatibility due to widespread usage
+- Implement thorough security validation
+- Keep dependencies minimal and well-justified
+
+### Performance Requirements
+- Design for high-throughput token validation
+- Optimize memory allocation patterns
+- Consider token caching strategies
+- Profile performance-critical paths
+- Benchmark changes that affect token processing
+
+### Security Guidelines
+- Follow security best practices for cryptographic operations
+- Validate all token parameters thoroughly
+- Handle security keys with appropriate precautions
+- Implement proper error handling for security operations
+- Document security considerations for public APIs
+
+### Testing Requirements
+- Maintain comprehensive test coverage
+- Include security validation tests
+- Add performance benchmarks for critical paths
+- Test with different key types and sizes
+- Verify protocol compliance
+
+### Public API Changes
+- The project uses Microsoft.CodeAnalysis.PublicApiAnalyzers (version 3.3.4)
+- For any public API changes:
+  1. Update PublicAPI.Unshipped.txt in the relevant package directory
+  2. Include complete API signatures
+  3. Consider backward compatibility impacts
+  4. Document breaking changes clearly
+
+Example format:
+```diff
+// Adding new API
++Microsoft.IdentityModel.Tokens.TokenValidationResult.Clone() -> Microsoft.IdentityModel.Tokens.TokenValidationResult
++Microsoft.IdentityModel.Tokens.SecurityKey.KeySize.get -> int
+
+// Removing API (requires careful consideration)
+-Microsoft.IdentityModel.Tokens.ObsoleteTokenValidationMethod() -> 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.