agentic-team-templates 0.13.2 → 0.14.0

package/templates/csharp-expert/.cursorrules/dependency-injection.md

@@ -0,0 +1,206 @@
+# C# Dependency Injection
+
+The built-in Microsoft.Extensions.DependencyInjection container is the standard. Use it correctly.
+
+## Service Lifetimes
+
+```csharp
+// Transient: new instance every time. Use for lightweight, stateless services.
+builder.Services.AddTransient<IEmailSender, SmtpEmailSender>();
+
+// Scoped: one instance per request/scope. Use for DbContext, Unit of Work.
+builder.Services.AddScoped<IOrderRepository, OrderRepository>();
+builder.Services.AddDbContext<AppDbContext>();
+
+// Singleton: one instance for app lifetime. Use for caches, config, HTTP clients.
+builder.Services.AddSingleton<IConnectionMultiplexer>(sp =>
+    ConnectionMultiplexer.Connect(configuration.GetConnectionString("Redis")!));
+```
+
+### The Captive Dependency Problem
+
+A singleton must NEVER depend on a scoped or transient service — it captures a stale instance.
+
+```csharp
+// WRONG: singleton captures scoped DbContext
+public class CachedUserService  // Registered as Singleton
+{
+    private readonly AppDbContext _db; // Scoped! This instance lives forever now.
+    public CachedUserService(AppDbContext db) => _db = db;
+}
+
+// RIGHT: use IServiceScopeFactory to create scopes
+public class CachedUserService
+{
+    private readonly IServiceScopeFactory _scopeFactory;
+
+    public CachedUserService(IServiceScopeFactory scopeFactory)
+        => _scopeFactory = scopeFactory;
+
+    public async Task<User?> GetUserAsync(int id)
+    {
+        using var scope = _scopeFactory.CreateScope();
+        var db = scope.ServiceProvider.GetRequiredService<AppDbContext>();
+        return await db.Users.FindAsync(id);
+    }
+}
+```
+
+## Registration Patterns
+
+```csharp
+// Extension methods for clean composition root
+public static class OrderServiceExtensions
+{
+    public static IServiceCollection AddOrderServices(this IServiceCollection services)
+    {
+        services.AddScoped<IOrderRepository, OrderRepository>();
+        services.AddScoped<IOrderService, OrderService>();
+        services.AddScoped<IInventoryChecker, InventoryChecker>();
+        return services;
+    }
+}
+
+// Program.cs stays clean
+builder.Services.AddOrderServices();
+builder.Services.AddNotificationServices();
+builder.Services.AddAuthenticationServices(builder.Configuration);
+```
+
+## Options Pattern
+
+```csharp
+// Strongly typed configuration
+public class SmtpOptions
+{
+    public const string SectionName = "Smtp";
+
+    public required string Host { get; init; }
+    public int Port { get; init; } = 587;
+    public required string Username { get; init; }
+    public required string Password { get; init; }
+    public bool UseSsl { get; init; } = true;
+}
+
+// Registration with validation
+builder.Services
+    .AddOptions<SmtpOptions>()
+    .BindConfiguration(SmtpOptions.SectionName)
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+
+// Injection — use IOptions<T> for static config, IOptionsMonitor<T> for reloadable
+public class EmailSender(IOptions<SmtpOptions> options)
+{
+    private readonly SmtpOptions _smtp = options.Value;
+}
+```
+
+## Keyed Services (.NET 8+)
+
+```csharp
+// Register multiple implementations of the same interface
+builder.Services.AddKeyedSingleton<INotifier, EmailNotifier>("email");
+builder.Services.AddKeyedSingleton<INotifier, SmsNotifier>("sms");
+builder.Services.AddKeyedSingleton<INotifier, SlackNotifier>("slack");
+
+// Inject by key
+public class NotificationService([FromKeyedServices("email")] INotifier emailNotifier)
+{
+    public Task NotifyAsync(string message)
+        => emailNotifier.SendAsync(message);
+}
+```
+
+## Interface Segregation
+
+```csharp
+// Bad: fat interface
+public interface IUserRepository
+{
+    Task<User?> GetByIdAsync(int id, CancellationToken ct);
+    Task<User?> GetByEmailAsync(string email, CancellationToken ct);
+    Task<IReadOnlyList<User>> GetAllAsync(CancellationToken ct);
+    Task CreateAsync(User user, CancellationToken ct);
+    Task UpdateAsync(User user, CancellationToken ct);
+    Task DeleteAsync(int id, CancellationToken ct);
+    Task<int> GetCountAsync(CancellationToken ct);
+    Task<bool> ExistsAsync(string email, CancellationToken ct);
+}
+
+// Good: segregated interfaces
+public interface IUserReader
+{
+    Task<User?> GetByIdAsync(int id, CancellationToken ct);
+    Task<User?> GetByEmailAsync(string email, CancellationToken ct);
+}
+
+public interface IUserWriter
+{
+    Task CreateAsync(User user, CancellationToken ct);
+    Task UpdateAsync(User user, CancellationToken ct);
+}
+
+// Consumers only depend on what they use
+public class LoginService(IUserReader users) { }
+public class RegistrationService(IUserReader users, IUserWriter writer) { }
+```
+
+## Decorator Pattern
+
+```csharp
+// Scrutor or manual registration for decorators
+public class CachedUserRepository : IUserReader
+{
+    private readonly IUserReader _inner;
+    private readonly IMemoryCache _cache;
+
+    public CachedUserRepository(IUserReader inner, IMemoryCache cache)
+    {
+        _inner = inner;
+        _cache = cache;
+    }
+
+    public async Task<User?> GetByIdAsync(int id, CancellationToken ct)
+    {
+        return await _cache.GetOrCreateAsync($"user:{id}", async entry =>
+        {
+            entry.AbsoluteExpirationRelativeToNow = TimeSpan.FromMinutes(5);
+            return await _inner.GetByIdAsync(id, ct);
+        });
+    }
+}
+
+// Registration
+builder.Services.AddScoped<UserRepository>();
+builder.Services.AddScoped<IUserReader>(sp =>
+    new CachedUserRepository(
+        sp.GetRequiredService<UserRepository>(),
+        sp.GetRequiredService<IMemoryCache>()));
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: service locator pattern
+public class OrderService
+{
+    private readonly IServiceProvider _sp;
+    public OrderService(IServiceProvider sp) => _sp = sp;
+    public void Process()
+    {
+        var repo = _sp.GetRequiredService<IOrderRepository>(); // Hidden dependency
+    }
+}
+// Use constructor injection instead
+
+// Never: registering concrete types without interfaces (for testability)
+builder.Services.AddScoped<OrderService>(); // Can't mock in tests
+// Register with interface: AddScoped<IOrderService, OrderService>();
+
+// Never: static service accessors
+public static class ServiceLocator
+{
+    public static IServiceProvider Provider { get; set; } = null!; // Global mutable state
+}
+```

package/templates/csharp-expert/.cursorrules/error-handling.md

@@ -0,0 +1,235 @@
+# C# Error Handling
+
+Exceptions for exceptional conditions. Result types for expected failures. Never swallow errors.
+
+## The Two Categories
+
+1. **Exceptions** — Programming errors, infrastructure failures, genuinely unexpected conditions
+2. **Result patterns** — Validation failures, business rule violations, "not found" scenarios
+
+## Exception Best Practices
+
+```csharp
+// Catch specific exceptions, never bare catch
+try
+{
+    await _httpClient.PostAsync(url, content, ct);
+}
+catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.TooManyRequests)
+{
+    _logger.LogWarning(ex, "Rate limited by {Url}", url);
+    await Task.Delay(retryDelay, ct);
+}
+catch (TaskCanceledException) when (ct.IsCancellationRequested)
+{
+    _logger.LogInformation("Request cancelled");
+    throw; // Let cancellation propagate
+}
+catch (HttpRequestException ex)
+{
+    _logger.LogError(ex, "HTTP request to {Url} failed", url);
+    throw; // Re-throw — don't swallow
+}
+
+// Exception filters (when clause) — use them for conditional catch
+catch (SqlException ex) when (ex.Number == 2627) // Unique constraint violation
+{
+    throw new DuplicateEntityException("User with this email already exists", ex);
+}
+```
+
+### Guard Clauses
+
+```csharp
+public class OrderService
+{
+    public async Task<Order> CreateAsync(CreateOrderRequest request, CancellationToken ct)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentException.ThrowIfNullOrWhiteSpace(request.CustomerId);
+        ArgumentOutOfRangeException.ThrowIfNegativeOrZero(request.Items.Count);
+
+        // Business logic follows clean preconditions
+        var customer = await _customers.GetByIdAsync(request.CustomerId, ct)
+            ?? throw new NotFoundException($"Customer '{request.CustomerId}' not found");
+
+        return Order.Create(customer, request.Items);
+    }
+}
+```
+
+## Result Pattern
+
+```csharp
+// A generic Result type for operations that can fail predictably
+public readonly record struct Result<T>
+{
+    public T? Value { get; }
+    public Error? Error { get; }
+    public bool IsSuccess => Error is null;
+
+    private Result(T value) { Value = value; Error = null; }
+    private Result(Error error) { Value = default; Error = error; }
+
+    public static Result<T> Success(T value) => new(value);
+    public static Result<T> Failure(Error error) => new(error);
+
+    public TResult Match<TResult>(
+        Func<T, TResult> onSuccess,
+        Func<Error, TResult> onFailure)
+        => IsSuccess ? onSuccess(Value!) : onFailure(Error!);
+}
+
+public record Error(string Code, string Message)
+{
+    public static Error NotFound(string entity, object id)
+        => new("NOT_FOUND", $"{entity} with id '{id}' was not found");
+
+    public static Error Validation(string message)
+        => new("VALIDATION", message);
+
+    public static Error Conflict(string message)
+        => new("CONFLICT", message);
+}
+```
+
+### Using the Result Pattern
+
+```csharp
+public class UserService
+{
+    public async Task<Result<User>> RegisterAsync(
+        RegisterRequest request, CancellationToken ct)
+    {
+        // Validation
+        if (!EmailValidator.IsValid(request.Email))
+            return Result<User>.Failure(Error.Validation("Invalid email format"));
+
+        // Business rule check
+        var existing = await _users.GetByEmailAsync(request.Email, ct);
+        if (existing is not null)
+            return Result<User>.Failure(Error.Conflict("Email already registered"));
+
+        // Happy path
+        var user = User.Create(request.Name, request.Email);
+        await _users.CreateAsync(user, ct);
+        return Result<User>.Success(user);
+    }
+}
+
+// In the endpoint
+app.MapPost("/users", async (RegisterRequest request, UserService service, CancellationToken ct) =>
+{
+    var result = await service.RegisterAsync(request, ct);
+    return result.Match(
+        user => Results.Created($"/users/{user.Id}", user),
+        error => error.Code switch
+        {
+            "VALIDATION" => Results.BadRequest(error),
+            "CONFLICT" => Results.Conflict(error),
+            _ => Results.Problem(error.Message)
+        });
+});
+```
+
+## Problem Details (RFC 9457)
+
+```csharp
+// ASP.NET Core's built-in Problem Details support
+builder.Services.AddProblemDetails(options =>
+{
+    options.CustomizeProblemDetails = context =>
+    {
+        context.ProblemDetails.Extensions["traceId"] =
+            context.HttpContext.TraceIdentifier;
+    };
+});
+
+// Global exception handler middleware
+app.UseExceptionHandler(exceptionApp =>
+{
+    exceptionApp.Run(async context =>
+    {
+        var exception = context.Features.Get<IExceptionHandlerFeature>()?.Error;
+        var problemDetails = exception switch
+        {
+            NotFoundException ex => new ProblemDetails
+            {
+                Status = 404,
+                Title = "Not Found",
+                Detail = ex.Message
+            },
+            ValidationException ex => new ProblemDetails
+            {
+                Status = 400,
+                Title = "Validation Error",
+                Detail = ex.Message
+            },
+            _ => new ProblemDetails
+            {
+                Status = 500,
+                Title = "Internal Server Error",
+                Detail = "An unexpected error occurred"
+            }
+        };
+
+        context.Response.StatusCode = problemDetails.Status ?? 500;
+        await context.Response.WriteAsJsonAsync(problemDetails);
+    });
+});
+```
+
+## FluentValidation
+
+```csharp
+public class CreateOrderValidator : AbstractValidator<CreateOrderRequest>
+{
+    public CreateOrderValidator()
+    {
+        RuleFor(x => x.CustomerId)
+            .NotEmpty()
+            .WithMessage("Customer ID is required");
+
+        RuleFor(x => x.Items)
+            .NotEmpty()
+            .WithMessage("Order must contain at least one item");
+
+        RuleForEach(x => x.Items).ChildRules(item =>
+        {
+            item.RuleFor(i => i.Quantity)
+                .GreaterThan(0)
+                .WithMessage("Quantity must be positive");
+
+            item.RuleFor(i => i.Price)
+                .GreaterThan(0)
+                .WithMessage("Price must be positive");
+        });
+    }
+}
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: catch-all that swallows exceptions
+try { DoWork(); }
+catch (Exception) { } // Silent failure — a bug hiding a bug
+
+// Never: catch and throw new (loses stack trace)
+catch (Exception ex) { throw new Exception("Failed", ex); }
+// Use: throw; (preserves stack trace)
+// Or: throw new SpecificException("context", ex); (wraps with context)
+
+// Never: exceptions for control flow
+try { return dict[key]; }
+catch (KeyNotFoundException) { return default; }
+// Use: dict.TryGetValue(key, out var value)
+
+// Never: log and throw (produces duplicate log entries)
+catch (Exception ex)
+{
+    _logger.LogError(ex, "Failed");
+    throw; // Now it's logged twice — here and in global handler
+}
+// Choose one: log OR throw, not both
+```

package/templates/csharp-expert/.cursorrules/language-features.md

@@ -0,0 +1,204 @@
+# Modern C# Language Features
+
+Deep knowledge of C# language evolution. Use modern features deliberately, not just because they exist.
+
+## Nullable Reference Types
+
+The single most impactful feature for code correctness. Non-negotiable.
+
+```csharp
+// The compiler is your partner — listen to it
+public class UserService
+{
+    // Non-nullable: guaranteed to have a value
+    private readonly IUserRepository _repository;
+
+    // Nullable: explicitly communicates "might not exist"
+    public async Task<User?> FindByEmailAsync(string email)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(email);
+        return await _repository.FindByEmailAsync(email);
+    }
+
+    // Null-forgiving operator (!) — document WHY
+    // Only when you genuinely know better than the compiler
+    var user = users.FirstOrDefault(u => u.Id == id)!; // Validated above
+}
+```
+
+### Rules
+
+- Never disable nullable warnings project-wide
+- `string` means non-null. `string?` means nullable. Respect the distinction
+- Use `ArgumentNullException.ThrowIfNull()` at public API boundaries
+- Avoid the null-forgiving operator (`!`) — if you need it, the design may be wrong
+
+## Records
+
+```csharp
+// Immutable data with value semantics — the default for DTOs and value objects
+public record CreateUserRequest(string Name, string Email);
+
+// Record structs for high-performance value types
+public readonly record struct Coordinate(double Latitude, double Longitude);
+
+// Records with validation
+public record Money
+{
+    public decimal Amount { get; }
+    public string Currency { get; }
+
+    public Money(decimal amount, string currency)
+    {
+        ArgumentOutOfRangeException.ThrowIfNegative(amount);
+        ArgumentException.ThrowIfNullOrWhiteSpace(currency);
+        Amount = amount;
+        Currency = currency.ToUpperInvariant();
+    }
+}
+
+// Non-destructive mutation
+var updated = original with { Email = "new@example.com" };
+```
+
+## Pattern Matching
+
+```csharp
+// Switch expressions — exhaustive, concise
+public static string FormatStatus(OrderStatus status) => status switch
+{
+    OrderStatus.Pending => "Awaiting processing",
+    OrderStatus.Shipped => "On its way",
+    OrderStatus.Delivered => "Delivered",
+    OrderStatus.Cancelled => "Cancelled",
+    _ => throw new ArgumentOutOfRangeException(nameof(status))
+};
+
+// Property patterns
+public static decimal CalculateDiscount(Order order) => order switch
+{
+    { Total: > 1000, Customer.IsPremium: true } => order.Total * 0.15m,
+    { Total: > 500 } => order.Total * 0.10m,
+    { Customer.IsPremium: true } => order.Total * 0.05m,
+    _ => 0m
+};
+
+// Type patterns with guards
+public static string Describe(object value) => value switch
+{
+    int n when n < 0 => "negative integer",
+    int n => $"positive integer: {n}",
+    string { Length: 0 } => "empty string",
+    string s => $"string: {s}",
+    null => "null",
+    _ => $"unknown: {value.GetType().Name}"
+};
+
+// List patterns (C# 11+)
+public static bool IsValidSequence(int[] values) => values switch
+{
+    [1, 2, 3] => true,
+    [1, .., 3] => true,  // Starts with 1, ends with 3
+    [_, _, ..] => true,   // At least 2 elements
+    _ => false
+};
+```
+
+## LINQ — Use It Well
+
+```csharp
+// Good: clear, composable, declarative
+var activeUsers = users
+    .Where(u => u.IsActive)
+    .OrderBy(u => u.LastLogin)
+    .Select(u => new UserSummary(u.Id, u.Name, u.Email))
+    .ToList();
+
+// Bad: LINQ for side effects
+users.ForEach(u => u.Deactivate()); // Use a foreach loop instead
+
+// Bad: multiple enumerations of IEnumerable
+var count = users.Count();        // Enumerates
+var first = users.FirstOrDefault(); // Enumerates again!
+// Fix: materialize first with .ToList()
+
+// Performance: use the right method
+users.Any(u => u.IsAdmin)         // Good: short-circuits
+users.Count(u => u.IsAdmin) > 0   // Bad: counts everything
+users.Where(u => u.IsAdmin).Any() // Acceptable but unnecessary
+```
+
+## Spans and Memory
+
+```csharp
+// Span<T> for zero-allocation slicing
+public static bool StartsWithDigit(ReadOnlySpan<char> input)
+    => !input.IsEmpty && char.IsDigit(input[0]);
+
+// String parsing without allocation
+public static (string Key, string Value) ParseHeader(ReadOnlySpan<char> header)
+{
+    var separatorIndex = header.IndexOf(':');
+    if (separatorIndex < 0)
+        throw new FormatException("Invalid header format");
+
+    var key = header[..separatorIndex].Trim().ToString();
+    var value = header[(separatorIndex + 1)..].Trim().ToString();
+    return (key, value);
+}
+
+// stackalloc for small buffers
+Span<byte> buffer = stackalloc byte[256];
+var bytesWritten = Encoding.UTF8.GetBytes(input, buffer);
+```
+
+## Collection Expressions (C# 12+)
+
+```csharp
+// Concise collection initialization
+int[] numbers = [1, 2, 3, 4, 5];
+List<string> names = ["Alice", "Bob"];
+Dictionary<string, int> scores = new() { ["Alice"] = 95, ["Bob"] = 87 };
+
+// Spread operator
+int[] combined = [..firstHalf, ..secondHalf];
+```
+
+## Primary Constructors (C# 12+)
+
+```csharp
+// For services — captures parameters as fields
+public class OrderService(IOrderRepository repository, ILogger<OrderService> logger)
+{
+    public async Task<Order> GetByIdAsync(int id)
+    {
+        logger.LogInformation("Fetching order {OrderId}", id);
+        return await repository.GetByIdAsync(id)
+            ?? throw new NotFoundException($"Order {id} not found");
+    }
+}
+
+// Caution: primary constructor parameters are mutable and capturable
+// For DTOs, prefer records instead
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: stringly-typed code
+void Process(string type, string data) { } // What types? What format?
+// Use enums, records, or discriminated unions
+
+// Never: throwing exceptions for control flow
+try { return users.First(u => u.Id == id); }
+catch (InvalidOperationException) { return null; }
+// Use FirstOrDefault or TryGetValue patterns
+
+// Never: mutable static state
+static List<User> _cache = new(); // Thread-unsafe, untestable
+// Use IMemoryCache or a proper caching abstraction
+
+// Never: deep inheritance hierarchies
+class SpecialPremiumInternationalCustomerOrder : PremiumCustomerOrder { }
+// Use composition and interfaces
+```