agentic-team-templates 0.13.1 → 0.14.0

package/templates/csharp-expert/.cursorrules/overview.md

@@ -0,0 +1,92 @@
+# C# Expert Overview
+
+Principal-level C# engineering. Deep .NET runtime knowledge, modern language features, and production-grade patterns.
+
+## Scope
+
+This guide applies to:
+- Web APIs and services (ASP.NET Core, Minimal APIs)
+- Desktop and cross-platform applications (WPF, MAUI, Avalonia)
+- Cloud-native services (Azure Functions, Worker Services)
+- Libraries and NuGet packages
+- Real-time systems (SignalR, gRPC)
+- Background processing (Hosted Services, message consumers)
+
+## Core Philosophy
+
+C# is a language of deliberate design. Every feature exists for a reason — use the right tool for the job.
+
+- **Type safety is your first line of defense.** Nullable reference types enabled, warnings as errors.
+- **Composition over inheritance.** Interfaces, extension methods, and dependency injection — not deep class hierarchies.
+- **Async all the way down.** Never block on async code. Never use `.Result` or `.Wait()` in application code.
+- **The framework does the heavy lifting.** ASP.NET Core's middleware pipeline, DI container, and configuration system are battle-tested — use them.
+- **Measure before you optimize.** BenchmarkDotNet and dotnet-counters before rewriting anything.
+- **If you don't know, say so.** Admitting uncertainty is professional. Guessing at runtime behavior you haven't verified is not.
+
+## Key Principles
+
+1. **Nullable Reference Types Are Non-Negotiable** — `<Nullable>enable</Nullable>` in every project
+2. **Prefer Records for Data** — Immutable by default, value semantics, concise syntax
+3. **Dependency Injection Is the Architecture** — Constructor injection, interface segregation, composition root
+4. **Errors Are Explicit** — Result patterns for expected failures, exceptions for exceptional conditions
+5. **Tests Describe Behavior** — Not implementation details
+
+## Project Structure
+
+```
+Solution/
+├── src/
+│   ├── MyApp.Api/              # ASP.NET Core host (thin — wiring only)
+│   │   ├── Program.cs          # Composition root
+│   │   ├── Endpoints/          # Minimal API endpoint definitions
+│   │   └── Middleware/         # Custom middleware
+│   ├── MyApp.Application/      # Use cases, commands, queries (no framework deps)
+│   │   ├── Commands/
+│   │   ├── Queries/
+│   │   └── Interfaces/
+│   ├── MyApp.Domain/           # Core domain (zero dependencies)
+│   │   ├── Entities/
+│   │   ├── ValueObjects/
+│   │   └── Events/
+│   └── MyApp.Infrastructure/   # External concerns (DB, HTTP, messaging)
+│       ├── Persistence/
+│       ├── Services/
+│       └── Configuration/
+├── tests/
+│   ├── MyApp.UnitTests/
+│   ├── MyApp.IntegrationTests/
+│   └── MyApp.ArchitectureTests/
+├── Directory.Build.props       # Shared project settings
+├── .editorconfig               # Code style enforcement
+└── MyApp.sln
+```
+
+## Directory.Build.props
+
+```xml
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <AnalysisLevel>latest-recommended</AnalysisLevel>
+  </PropertyGroup>
+</Project>
+```
+
+## Definition of Done
+
+A C# feature is complete when:
+
+- [ ] `dotnet build --warnaserror` passes with zero warnings
+- [ ] `dotnet test` passes with no failures
+- [ ] Nullable reference types produce no warnings
+- [ ] No `#pragma warning disable` without inline justification
+- [ ] Async methods don't block (no `.Result`, `.Wait()`, `.GetAwaiter().GetResult()`)
+- [ ] All public APIs have XML documentation comments
+- [ ] Error paths are tested
+- [ ] DI registrations verified (no missing services at runtime)
+- [ ] No `TODO` without an associated issue
+- [ ] Code reviewed and approved

package/templates/csharp-expert/.cursorrules/performance.md

@@ -0,0 +1,251 @@
+# C# Performance
+
+Measure first. Optimize second. BenchmarkDotNet is your truth.
+
+## Profile Before Optimizing
+
+```csharp
+// BenchmarkDotNet for micro-benchmarks
+[MemoryDiagnoser]
+[SimpleJob(RuntimeMoniker.Net90)]
+public class StringConcatBenchmark
+{
+    private readonly string[] _items = Enumerable.Range(0, 1000)
+        .Select(i => i.ToString()).ToArray();
+
+    [Benchmark(Baseline = true)]
+    public string Concatenation()
+    {
+        var result = "";
+        foreach (var item in _items)
+            result += item;
+        return result;
+    }
+
+    [Benchmark]
+    public string StringBuilder()
+    {
+        var sb = new StringBuilder();
+        foreach (var item in _items)
+            sb.Append(item);
+        return sb.ToString();
+    }
+
+    [Benchmark]
+    public string StringJoin()
+        => string.Join("", _items);
+}
+```
+
+### Diagnostic Tools
+
+| Tool | Purpose |
+|------|---------|
+| `dotnet-counters` | Live runtime metrics (GC, thread pool, exceptions) |
+| `dotnet-trace` | Performance tracing |
+| `dotnet-dump` | Memory dump analysis |
+| `dotnet-gcdump` | GC heap analysis |
+| BenchmarkDotNet | Micro-benchmarks with statistical rigor |
+
+## Allocation Patterns
+
+### Reduce Allocations
+
+```csharp
+// Bad: allocates on every call
+public string FormatName(string first, string last)
+    => $"{first} {last}"; // Allocates interpolated string
+
+// Good: use string.Create or Span for hot paths
+public string FormatName(ReadOnlySpan<char> first, ReadOnlySpan<char> last)
+    => string.Create(first.Length + 1 + last.Length, (first.ToString(), last.ToString()),
+        (span, state) =>
+        {
+            state.Item1.AsSpan().CopyTo(span);
+            span[state.Item1.Length] = ' ';
+            state.Item2.AsSpan().CopyTo(span[(state.Item1.Length + 1)..]);
+        });
+
+// Better for most cases: just use StringBuilder
+// Premature optimization with Span is worse than readable code
+```
+
+### ArrayPool and MemoryPool
+
+```csharp
+// Rent buffers instead of allocating
+public async Task<byte[]> CompressAsync(Stream input, CancellationToken ct)
+{
+    var buffer = ArrayPool<byte>.Shared.Rent(8192);
+    try
+    {
+        using var output = new MemoryStream();
+        using var compressor = new GZipStream(output, CompressionLevel.Optimal);
+
+        int bytesRead;
+        while ((bytesRead = await input.ReadAsync(buffer, ct)) > 0)
+        {
+            await compressor.WriteAsync(buffer.AsMemory(0, bytesRead), ct);
+        }
+
+        await compressor.FlushAsync(ct);
+        return output.ToArray();
+    }
+    finally
+    {
+        ArrayPool<byte>.Shared.Return(buffer);
+    }
+}
+```
+
+### Object Pooling
+
+```csharp
+// ObjectPool for expensive-to-create objects
+builder.Services.AddSingleton<ObjectPool<StringBuilder>>(
+    new DefaultObjectPoolProvider().CreateStringBuilderPool());
+
+public class ReportGenerator(ObjectPool<StringBuilder> pool)
+{
+    public string Generate(ReportData data)
+    {
+        var sb = pool.Get();
+        try
+        {
+            sb.AppendLine($"Report: {data.Title}");
+            foreach (var item in data.Items)
+                sb.AppendLine($"- {item.Name}: {item.Value}");
+            return sb.ToString();
+        }
+        finally
+        {
+            pool.Return(sb);
+        }
+    }
+}
+```
+
+## struct vs class
+
+```csharp
+// Use struct when:
+// - Logically represents a single value
+// - Instance size < 16 bytes (guideline, not rule)
+// - Immutable
+// - Won't be boxed frequently
+public readonly record struct Coordinate(double Lat, double Lon);
+
+// Use class when:
+// - Reference semantics needed
+// - Will be used polymorphically
+// - Large (copying structs is expensive)
+// - Needs to be nullable (struct? has overhead)
+```
+
+## Collection Performance
+
+```csharp
+// FrozenDictionary/FrozenSet for read-heavy, write-once scenarios (.NET 8+)
+private static readonly FrozenDictionary<string, Handler> _handlers =
+    new Dictionary<string, Handler>
+    {
+        ["GET"] = new GetHandler(),
+        ["POST"] = new PostHandler(),
+    }.ToFrozenDictionary();
+
+// Use CollectionsMarshal for high-performance dictionary access
+ref var value = ref CollectionsMarshal.GetValueRefOrAddDefault(
+    dictionary, key, out bool exists);
+if (!exists) value = ComputeExpensiveValue(key);
+
+// Correct collection type for the job
+// List<T>: random access, append
+// HashSet<T>: uniqueness, O(1) Contains
+// Dictionary<K,V>: O(1) lookup by key
+// Queue<T>/Stack<T>: FIFO/LIFO
+// LinkedList<T>: frequent insert/remove in middle (rare in practice)
+// SortedSet<T>: ordered unique elements
+```
+
+## EF Core Performance
+
+```csharp
+// Always use AsNoTracking for read-only queries
+var users = await _db.Users
+    .AsNoTracking()
+    .Where(u => u.IsActive)
+    .Select(u => new UserDto(u.Id, u.Name, u.Email)) // Project to DTO
+    .ToListAsync(ct);
+
+// Avoid N+1 queries — use Include or projection
+// Bad:
+var orders = await _db.Orders.ToListAsync(ct);
+foreach (var order in orders)
+{
+    var items = order.Items; // Lazy load = N+1 queries!
+}
+
+// Good:
+var orders = await _db.Orders
+    .Include(o => o.Items)
+    .ToListAsync(ct);
+
+// Even better: project to exactly what you need
+var orderSummaries = await _db.Orders
+    .Select(o => new OrderSummary(o.Id, o.Total, o.Items.Count))
+    .ToListAsync(ct);
+
+// Use compiled queries for hot paths
+private static readonly Func<AppDbContext, int, Task<User?>> GetUserById =
+    EF.CompileAsyncQuery((AppDbContext db, int id) =>
+        db.Users.FirstOrDefault(u => u.Id == id));
+```
+
+## Caching
+
+```csharp
+// IMemoryCache for single-instance caching
+public async Task<User?> GetUserAsync(int id, CancellationToken ct)
+{
+    return await _cache.GetOrCreateAsync($"user:{id}", async entry =>
+    {
+        entry.SetSlidingExpiration(TimeSpan.FromMinutes(5));
+        entry.SetAbsoluteExpiration(TimeSpan.FromHours(1));
+        entry.SetSize(1); // For bounded caches
+        return await _repository.GetByIdAsync(id, ct);
+    });
+}
+
+// IDistributedCache for multi-instance (Redis, SQL Server)
+// HybridCache (.NET 9+) for stampede protection
+public async Task<User?> GetUserAsync(int id, CancellationToken ct)
+{
+    return await _hybridCache.GetOrCreateAsync(
+        $"user:{id}",
+        async token => await _repository.GetByIdAsync(id, token),
+        cancellationToken: ct);
+}
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: premature optimization without measurement
+// "I think StringBuilder is faster" — prove it with a benchmark
+
+// Never: LINQ in hot loops when a simple for loop suffices
+for (int i = 0; i < items.Length; i++) // Fine for hot paths
+    Process(items[i]);
+
+// Never: multiple enumeration of IEnumerable
+var count = query.Count();    // Executes query
+var list = query.ToList();    // Executes query AGAIN
+// Materialize once: var list = query.ToList(); var count = list.Count;
+
+// Never: blocking async in constructors
+public MyService()
+{
+    _data = LoadDataAsync().Result; // Deadlock risk
+}
+// Use async factory method or lazy initialization
+```

package/templates/csharp-expert/.cursorrules/testing.md

@@ -0,0 +1,282 @@
+# C# Testing
+
+Test behavior, not implementation. Every test should answer: "what does this code do?"
+
+## Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| xUnit | Test framework (preferred for .NET) |
+| NSubstitute | Mocking (clean syntax, less ceremony than Moq) |
+| FluentAssertions | Readable assertions |
+| Bogus | Test data generation |
+| Testcontainers | Real databases/services in integration tests |
+| Verify | Snapshot testing |
+| ArchUnitNET | Architecture tests |
+
+## Unit Test Structure
+
+```csharp
+public class OrderServiceTests
+{
+    private readonly IOrderRepository _repository = Substitute.For<IOrderRepository>();
+    private readonly IInventoryService _inventory = Substitute.For<IInventoryService>();
+    private readonly OrderService _sut;
+
+    public OrderServiceTests()
+    {
+        _sut = new OrderService(_repository, _inventory);
+    }
+
+    [Fact]
+    public async Task CreateOrder_WithValidItems_ReturnsOrder()
+    {
+        // Arrange
+        var request = new CreateOrderRequest("customer-1", [new("sku-1", 2)]);
+        _inventory.CheckAvailabilityAsync("sku-1", 2, Arg.Any<CancellationToken>())
+            .Returns(true);
+
+        // Act
+        var result = await _sut.CreateAsync(request, CancellationToken.None);
+
+        // Assert
+        result.IsSuccess.Should().BeTrue();
+        result.Value!.CustomerId.Should().Be("customer-1");
+        result.Value.Items.Should().HaveCount(1);
+    }
+
+    [Fact]
+    public async Task CreateOrder_WithInsufficientInventory_ReturnsError()
+    {
+        // Arrange
+        var request = new CreateOrderRequest("customer-1", [new("sku-1", 100)]);
+        _inventory.CheckAvailabilityAsync("sku-1", 100, Arg.Any<CancellationToken>())
+            .Returns(false);
+
+        // Act
+        var result = await _sut.CreateAsync(request, CancellationToken.None);
+
+        // Assert
+        result.IsSuccess.Should().BeFalse();
+        result.Error!.Code.Should().Be("INSUFFICIENT_INVENTORY");
+    }
+}
+```
+
+## Test Naming
+
+```csharp
+// Pattern: Method_Scenario_ExpectedBehavior
+[Fact]
+public async Task GetByEmail_WhenUserExists_ReturnsUser() { }
+
+[Fact]
+public async Task GetByEmail_WhenUserNotFound_ReturnsNull() { }
+
+[Fact]
+public async Task Register_WithDuplicateEmail_ReturnsConflictError() { }
+
+// Or descriptive phrases
+[Fact]
+public async Task Newly_created_order_has_pending_status() { }
+```
+
+## Theory (Parameterized Tests)
+
+```csharp
+[Theory]
+[InlineData("", false)]
+[InlineData("a", false)]
+[InlineData("ab", false)]
+[InlineData("abc", true)]
+[InlineData("valid@email.com", true)]
+public void Validate_Password_MinLength(string input, bool expectedValid)
+{
+    var result = PasswordValidator.IsValid(input);
+    result.Should().Be(expectedValid);
+}
+
+// Complex data with MemberData
+[Theory]
+[MemberData(nameof(InvalidOrderTestCases))]
+public async Task CreateOrder_WithInvalidData_ReturnsValidationError(
+    CreateOrderRequest request, string expectedErrorCode)
+{
+    var result = await _sut.CreateAsync(request, CancellationToken.None);
+
+    result.IsSuccess.Should().BeFalse();
+    result.Error!.Code.Should().Be(expectedErrorCode);
+}
+
+public static IEnumerable<object[]> InvalidOrderTestCases()
+{
+    yield return [new CreateOrderRequest("", []), "VALIDATION"];
+    yield return [new CreateOrderRequest("c1", []), "VALIDATION"];
+}
+```
+
+## Integration Tests with WebApplicationFactory
+
+```csharp
+public class OrderEndpointTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client;
+
+    public OrderEndpointTests(WebApplicationFactory<Program> factory)
+    {
+        _client = factory.WithWebHostBuilder(builder =>
+        {
+            builder.ConfigureServices(services =>
+            {
+                // Replace real services with test doubles
+                services.RemoveAll<IOrderRepository>();
+                services.AddScoped<IOrderRepository, InMemoryOrderRepository>();
+            });
+        }).CreateClient();
+    }
+
+    [Fact]
+    public async Task POST_orders_returns_created_for_valid_request()
+    {
+        // Arrange
+        var request = new CreateOrderRequest("customer-1", [new("sku-1", 1)]);
+
+        // Act
+        var response = await _client.PostAsJsonAsync("/orders", request);
+
+        // Assert
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+        var order = await response.Content.ReadFromJsonAsync<OrderResponse>();
+        order!.CustomerId.Should().Be("customer-1");
+    }
+
+    [Fact]
+    public async Task GET_orders_id_returns_not_found_for_missing_order()
+    {
+        var response = await _client.GetAsync("/orders/nonexistent");
+        response.StatusCode.Should().Be(HttpStatusCode.NotFound);
+    }
+}
+```
+
+## Integration Tests with Testcontainers
+
+```csharp
+public class PostgresOrderRepositoryTests : IAsyncLifetime
+{
+    private readonly PostgreSqlContainer _postgres = new PostgreSqlBuilder()
+        .WithImage("postgres:16-alpine")
+        .Build();
+
+    private AppDbContext _dbContext = null!;
+
+    public async Task InitializeAsync()
+    {
+        await _postgres.StartAsync();
+        var options = new DbContextOptionsBuilder<AppDbContext>()
+            .UseNpgsql(_postgres.GetConnectionString())
+            .Options;
+        _dbContext = new AppDbContext(options);
+        await _dbContext.Database.MigrateAsync();
+    }
+
+    public async Task DisposeAsync()
+    {
+        await _dbContext.DisposeAsync();
+        await _postgres.DisposeAsync();
+    }
+
+    [Fact]
+    public async Task SaveAndRetrieve_RoundTrips_Correctly()
+    {
+        var repo = new OrderRepository(_dbContext);
+        var order = Order.Create("customer-1", [new OrderItem("sku-1", 2, 9.99m)]);
+
+        await repo.SaveAsync(order, CancellationToken.None);
+        var retrieved = await repo.GetByIdAsync(order.Id, CancellationToken.None);
+
+        retrieved.Should().NotBeNull();
+        retrieved!.CustomerId.Should().Be("customer-1");
+        retrieved.Items.Should().HaveCount(1);
+    }
+}
+```
+
+## Architecture Tests
+
+```csharp
+public class ArchitectureTests
+{
+    private static readonly Architecture Architecture =
+        new ArchLoader().LoadAssemblies(
+            typeof(Order).Assembly,       // Domain
+            typeof(OrderService).Assembly, // Application
+            typeof(OrderRepository).Assembly // Infrastructure
+        ).Build();
+
+    [Fact]
+    public void Domain_should_not_depend_on_infrastructure()
+    {
+        Types().That().ResideInNamespace("MyApp.Domain")
+            .Should().NotDependOnAny("MyApp.Infrastructure")
+            .Check(Architecture);
+    }
+
+    [Fact]
+    public void Application_should_not_depend_on_aspnetcore()
+    {
+        Types().That().ResideInNamespace("MyApp.Application")
+            .Should().NotDependOnAny("Microsoft.AspNetCore")
+            .Check(Architecture);
+    }
+}
+```
+
+## Test Data Builders
+
+```csharp
+// Bogus for realistic fake data
+public static class TestData
+{
+    private static readonly Faker<CreateOrderRequest> OrderFaker = new Faker<CreateOrderRequest>()
+        .CustomInstantiator(f => new CreateOrderRequest(
+            CustomerId: f.Random.Guid().ToString(),
+            Items: f.Make(f.Random.Int(1, 5), () =>
+                new OrderItemRequest(f.Commerce.Ean13(), f.Random.Int(1, 10)))));
+
+    public static CreateOrderRequest ValidOrder() => OrderFaker.Generate();
+
+    // Builder pattern for specific scenarios
+    public static CreateOrderRequest OrderWithItems(int count) =>
+        OrderFaker.Generate() with
+        {
+            Items = Enumerable.Range(0, count)
+                .Select(i => new OrderItemRequest($"sku-{i}", 1))
+                .ToList()
+        };
+}
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: testing implementation details
+_repository.Received(1).SaveAsync(Arg.Any<Order>(), Arg.Any<CancellationToken>());
+// Test the outcome instead: verify the order was actually persisted
+
+// Never: shared mutable state between tests
+private static List<Order> _orders = []; // Tests pollute each other
+// Use fresh state in constructor or Setup
+
+// Never: Thread.Sleep in tests
+await Task.Delay(5000); // Flaky and slow
+// Use polling with timeout, or Polly retry, or proper async synchronization
+
+// Never: testing trivial code
+[Fact]
+public void Name_getter_returns_name() // Waste of time
+{
+    var user = new User { Name = "Alice" };
+    user.Name.Should().Be("Alice");
+}
+```