agentic-team-templates 0.13.1 → 0.14.0

package/templates/csharp-expert/.cursorrules/aspnet-core.md

@@ -0,0 +1,311 @@
+# ASP.NET Core Patterns
+
+Modern ASP.NET Core web development. Minimal APIs, middleware, and production-grade service patterns.
+
+## Minimal APIs
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+
+// Service registration
+builder.Services.AddOrderServices();
+builder.Services.AddOpenApi();
+
+var app = builder.Build();
+
+// Middleware pipeline — order matters
+app.UseExceptionHandler();
+app.UseStatusCodePages();
+app.UseAuthentication();
+app.UseAuthorization();
+
+// Endpoint mapping
+app.MapOrderEndpoints();
+app.MapOpenApi();
+
+app.Run();
+```
+
+### Endpoint Organization
+
+```csharp
+public static class OrderEndpoints
+{
+    public static void MapOrderEndpoints(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/orders")
+            .WithTags("Orders")
+            .RequireAuthorization();
+
+        group.MapGet("/", GetAllOrders)
+            .WithName("GetOrders")
+            .Produces<IReadOnlyList<OrderResponse>>();
+
+        group.MapGet("/{id:int}", GetOrderById)
+            .WithName("GetOrder")
+            .Produces<OrderResponse>()
+            .ProducesProblem(StatusCodes.Status404NotFound);
+
+        group.MapPost("/", CreateOrder)
+            .WithName("CreateOrder")
+            .Produces<OrderResponse>(StatusCodes.Status201Created)
+            .ProducesValidationProblem();
+
+        group.MapDelete("/{id:int}", DeleteOrder)
+            .RequireAuthorization("AdminOnly");
+    }
+
+    private static async Task<IResult> GetOrderById(
+        int id, IOrderService service, CancellationToken ct)
+    {
+        var order = await service.GetByIdAsync(id, ct);
+        return order is not null
+            ? Results.Ok(order)
+            : Results.Problem(statusCode: 404, title: "Order not found");
+    }
+
+    private static async Task<IResult> CreateOrder(
+        CreateOrderRequest request,
+        IValidator<CreateOrderRequest> validator,
+        IOrderService service,
+        CancellationToken ct)
+    {
+        var validation = await validator.ValidateAsync(request, ct);
+        if (!validation.IsValid)
+            return Results.ValidationProblem(validation.ToDictionary());
+
+        var result = await service.CreateAsync(request, ct);
+        return result.Match(
+            order => Results.Created($"/orders/{order.Id}", order),
+            error => Results.Problem(error.Message, statusCode: 400));
+    }
+}
+```
+
+## Middleware
+
+```csharp
+// Request timing middleware
+public class RequestTimingMiddleware(RequestDelegate next, ILogger<RequestTimingMiddleware> logger)
+{
+    public async Task InvokeAsync(HttpContext context)
+    {
+        var stopwatch = Stopwatch.StartNew();
+        try
+        {
+            await next(context);
+        }
+        finally
+        {
+            stopwatch.Stop();
+            logger.LogInformation(
+                "HTTP {Method} {Path} responded {StatusCode} in {ElapsedMs}ms",
+                context.Request.Method,
+                context.Request.Path,
+                context.Response.StatusCode,
+                stopwatch.ElapsedMilliseconds);
+        }
+    }
+}
+
+// Registration
+app.UseMiddleware<RequestTimingMiddleware>();
+```
+
+## Configuration
+
+```csharp
+// Strongly typed with validation
+public class DatabaseOptions
+{
+    public const string SectionName = "Database";
+
+    [Required]
+    public required string ConnectionString { get; init; }
+
+    [Range(1, 100)]
+    public int MaxPoolSize { get; init; } = 20;
+
+    [Range(1, 300)]
+    public int CommandTimeoutSeconds { get; init; } = 30;
+}
+
+// Registration with validation at startup
+builder.Services
+    .AddOptions<DatabaseOptions>()
+    .BindConfiguration(DatabaseOptions.SectionName)
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+## Health Checks
+
+```csharp
+builder.Services.AddHealthChecks()
+    .AddDbContextCheck<AppDbContext>("database")
+    .AddRedis(connectionString, "redis")
+    .AddCheck<ExternalApiHealthCheck>("external-api");
+
+app.MapHealthChecks("/healthz", new HealthCheckOptions
+{
+    ResponseWriter = UIResponseWriter.WriteHealthCheckUIResponse
+});
+
+// Liveness vs readiness
+app.MapHealthChecks("/healthz/live", new HealthCheckOptions
+{
+    Predicate = _ => false // Just checks if the app is running
+});
+
+app.MapHealthChecks("/healthz/ready", new HealthCheckOptions
+{
+    Predicate = check => check.Tags.Contains("ready")
+});
+```
+
+## Authentication & Authorization
+
+```csharp
+// JWT Bearer
+builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+    .AddJwtBearer(options =>
+    {
+        options.Authority = builder.Configuration["Auth:Authority"];
+        options.Audience = builder.Configuration["Auth:Audience"];
+        options.TokenValidationParameters = new TokenValidationParameters
+        {
+            ValidateIssuer = true,
+            ValidateAudience = true,
+            ValidateLifetime = true,
+            ClockSkew = TimeSpan.FromSeconds(30)
+        };
+    });
+
+// Policy-based authorization
+builder.Services.AddAuthorization(options =>
+{
+    options.AddPolicy("AdminOnly", policy =>
+        policy.RequireClaim("role", "admin"));
+
+    options.AddPolicy("CanManageOrders", policy =>
+        policy.Requirements.Add(new OrderManagementRequirement()));
+});
+```
+
+## Output Caching (.NET 7+)
+
+```csharp
+builder.Services.AddOutputCache(options =>
+{
+    options.AddBasePolicy(builder => builder.Expire(TimeSpan.FromMinutes(5)));
+    options.AddPolicy("Products", builder =>
+        builder.Tag("products").Expire(TimeSpan.FromMinutes(30)));
+});
+
+app.MapGet("/products", GetProducts)
+    .CacheOutput("Products");
+
+// Invalidation
+app.MapPost("/products", async (
+    CreateProductRequest request,
+    IOutputCacheStore store,
+    CancellationToken ct) =>
+{
+    // ... create product ...
+    await store.EvictByTagAsync("products", ct);
+});
+```
+
+## Rate Limiting
+
+```csharp
+builder.Services.AddRateLimiter(options =>
+{
+    options.AddFixedWindowLimiter("api", config =>
+    {
+        config.PermitLimit = 100;
+        config.Window = TimeSpan.FromMinutes(1);
+        config.QueueLimit = 0;
+    });
+
+    options.AddTokenBucketLimiter("uploads", config =>
+    {
+        config.TokenLimit = 10;
+        config.ReplenishmentPeriod = TimeSpan.FromSeconds(10);
+        config.TokensPerPeriod = 2;
+    });
+
+    options.OnRejected = async (context, ct) =>
+    {
+        context.HttpContext.Response.StatusCode = StatusCodes.Status429TooManyRequests;
+        await context.HttpContext.Response.WriteAsJsonAsync(
+            new ProblemDetails { Title = "Too many requests" }, ct);
+    };
+});
+
+app.UseRateLimiter();
+app.MapGet("/api/data", GetData).RequireRateLimiting("api");
+```
+
+## Background Services
+
+```csharp
+public class OrderProcessorService(
+    IServiceScopeFactory scopeFactory,
+    ILogger<OrderProcessorService> logger) : BackgroundService
+{
+    protected override async Task ExecuteAsync(CancellationToken stoppingToken)
+    {
+        logger.LogInformation("Order processor starting");
+
+        while (!stoppingToken.IsCancellationRequested)
+        {
+            try
+            {
+                using var scope = scopeFactory.CreateScope();
+                var processor = scope.ServiceProvider
+                    .GetRequiredService<IOrderProcessor>();
+
+                await processor.ProcessPendingOrdersAsync(stoppingToken);
+            }
+            catch (Exception ex) when (ex is not OperationCanceledException)
+            {
+                logger.LogError(ex, "Error processing orders");
+            }
+
+            await Task.Delay(TimeSpan.FromSeconds(30), stoppingToken);
+        }
+    }
+}
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: business logic in endpoints
+app.MapPost("/orders", async (CreateOrderRequest req, AppDbContext db) =>
+{
+    // Validation, business rules, persistence all in one place
+    if (req.Items.Count == 0) return Results.BadRequest();
+    var order = new Order { /* ... */ };
+    db.Orders.Add(order);
+    await db.SaveChangesAsync();
+    return Results.Ok(order);
+});
+// Use services, keep endpoints thin
+
+// Never: exposing entities directly
+app.MapGet("/users/{id}", async (int id, AppDbContext db) =>
+    await db.Users.FindAsync(id)); // Exposes internal schema, password hashes, etc.
+// Map to DTOs/response records
+
+// Never: synchronous I/O in middleware
+public void Configure(IApplicationBuilder app)
+{
+    app.Use((context, next) =>
+    {
+        var data = File.ReadAllText("config.json"); // Blocks thread pool thread!
+        return next();
+    });
+}
+```

package/templates/csharp-expert/.cursorrules/async-patterns.md

@@ -0,0 +1,206 @@
+# C# Async Patterns
+
+async/await done right. Every pitfall known. Every pattern battle-tested.
+
+## The Golden Rules
+
+1. **Async all the way down.** Never mix sync and async.
+2. **Never block on async.** No `.Result`, `.Wait()`, `.GetAwaiter().GetResult()` in application code.
+3. **Always pass CancellationToken.** Every async method that does I/O should accept and honor one.
+4. **ConfigureAwait(false) in library code.** Not needed in ASP.NET Core app code (no SynchronizationContext).
+5. **Return Task, not void.** `async void` is only for event handlers.
+
+## Proper Async Methods
+
+```csharp
+// Good: accepts CancellationToken, returns Task<T>
+public async Task<User?> GetUserAsync(int id, CancellationToken cancellationToken = default)
+{
+    return await _dbContext.Users
+        .AsNoTracking()
+        .FirstOrDefaultAsync(u => u.Id == id, cancellationToken);
+}
+
+// Good: elide async/await when just forwarding
+public Task<User?> GetUserAsync(int id, CancellationToken ct = default)
+    => _dbContext.Users.AsNoTracking().FirstOrDefaultAsync(u => u.Id == id, ct);
+// But: don't elide if there's a using/try-catch — the await ensures proper lifetime
+
+// Bad: blocking on async
+public User GetUser(int id)
+{
+    return GetUserAsync(id).Result; // DEADLOCK RISK
+}
+```
+
+## CancellationToken
+
+```csharp
+// Thread it through every layer
+public async Task<OrderResult> ProcessOrderAsync(
+    CreateOrderRequest request,
+    CancellationToken cancellationToken)
+{
+    var user = await _userService.GetByIdAsync(request.UserId, cancellationToken);
+    var inventory = await _inventoryService.CheckAsync(request.Items, cancellationToken);
+
+    // Check cancellation before expensive operations
+    cancellationToken.ThrowIfCancellationRequested();
+
+    var order = Order.Create(user, inventory);
+    await _repository.SaveAsync(order, cancellationToken);
+
+    return new OrderResult(order.Id);
+}
+
+// Link cancellation tokens
+using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
+    cancellationToken,
+    _applicationLifetime.ApplicationStopping);
+
+// Timeout with cancellation
+using var timeoutCts = new CancellationTokenSource(TimeSpan.FromSeconds(30));
+using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
+    cancellationToken, timeoutCts.Token);
+```
+
+## Concurrent Operations
+
+```csharp
+// Good: parallel independent operations with Task.WhenAll
+public async Task<DashboardData> GetDashboardAsync(int userId, CancellationToken ct)
+{
+    var userTask = _userService.GetByIdAsync(userId, ct);
+    var ordersTask = _orderService.GetRecentAsync(userId, ct);
+    var notificationsTask = _notificationService.GetUnreadAsync(userId, ct);
+
+    await Task.WhenAll(userTask, ordersTask, notificationsTask);
+
+    return new DashboardData(
+        User: await userTask,
+        Orders: await ordersTask,
+        Notifications: await notificationsTask);
+}
+
+// Good: bounded concurrency with SemaphoreSlim
+public async Task ProcessBatchAsync(
+    IReadOnlyList<Item> items, CancellationToken ct)
+{
+    using var semaphore = new SemaphoreSlim(maxConcurrency: 10);
+    var tasks = items.Select(async item =>
+    {
+        await semaphore.WaitAsync(ct);
+        try
+        {
+            await ProcessItemAsync(item, ct);
+        }
+        finally
+        {
+            semaphore.Release();
+        }
+    });
+
+    await Task.WhenAll(tasks);
+}
+```
+
+## Channels
+
+```csharp
+// Producer-consumer with bounded channels
+public class EventProcessor
+{
+    private readonly Channel<DomainEvent> _channel =
+        Channel.CreateBounded<DomainEvent>(new BoundedChannelOptions(1000)
+        {
+            FullMode = BoundedChannelFullMode.Wait,
+            SingleReader = true,
+            SingleWriter = false
+        });
+
+    public async ValueTask PublishAsync(DomainEvent @event, CancellationToken ct)
+    {
+        await _channel.Writer.WriteAsync(@event, ct);
+    }
+
+    public async Task ProcessAsync(CancellationToken ct)
+    {
+        await foreach (var @event in _channel.Reader.ReadAllAsync(ct))
+        {
+            await HandleEventAsync(@event, ct);
+        }
+    }
+}
+```
+
+## ValueTask
+
+```csharp
+// Use ValueTask when the result is often synchronous (cached, pooled)
+public ValueTask<User?> GetCachedUserAsync(int id, CancellationToken ct)
+{
+    if (_cache.TryGetValue(id, out var user))
+        return ValueTask.FromResult<User?>(user); // No allocation
+
+    return GetAndCacheUserAsync(id, ct); // Async path
+}
+
+private async ValueTask<User?> GetAndCacheUserAsync(int id, CancellationToken ct)
+{
+    var user = await _repository.GetByIdAsync(id, ct);
+    if (user is not null) _cache.Set(id, user);
+    return user;
+}
+
+// Rules for ValueTask:
+// - Never await a ValueTask more than once
+// - Never use .Result or .GetAwaiter().GetResult() on an incomplete ValueTask
+// - Never use Task.WhenAll with ValueTask (convert with .AsTask() first)
+```
+
+## IAsyncEnumerable
+
+```csharp
+// Streaming results without buffering
+public async IAsyncEnumerable<LogEntry> StreamLogsAsync(
+    string filter,
+    [EnumeratorCancellation] CancellationToken ct = default)
+{
+    await foreach (var line in _logSource.ReadLinesAsync(ct))
+    {
+        if (line.Contains(filter, StringComparison.OrdinalIgnoreCase))
+        {
+            yield return ParseLogEntry(line);
+        }
+    }
+}
+
+// Consuming
+await foreach (var entry in StreamLogsAsync("ERROR", ct))
+{
+    await ProcessEntryAsync(entry, ct);
+}
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: async void (unobservable exceptions)
+async void OnButtonClick() { await DoWorkAsync(); }
+// Use: async Task OnButtonClickAsync() { ... }
+
+// Never: fire-and-forget without error handling
+_ = DoWorkAsync(); // Exception silently swallowed
+// Use: _ = Task.Run(async () => { try { ... } catch { _logger.LogError(...); } });
+
+// Never: unnecessary async/await wrapper
+async Task<int> GetValueAsync() { return await Task.FromResult(42); }
+// Just: Task<int> GetValueAsync() => Task.FromResult(42);
+
+// Never: Task.Run for I/O-bound work
+await Task.Run(() => httpClient.GetAsync(url)); // Wastes a thread pool thread
+// Just: await httpClient.GetAsync(url);
+
+// Never: capturing loop variable in pre-C#5 style (modern C# handles this, but be aware)
+// Never: using async lambdas with void-returning delegates (Action)
+```