agentic-team-templates 0.13.2 → 0.15.0

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

@@ -0,0 +1,254 @@
+# C# Tooling and Ecosystem
+
+The .NET toolchain, project configuration, and CI/CD patterns.
+
+## Essential CLI Commands
+
+```bash
+# Project management
+dotnet new webapi -n MyApp.Api        # Create new project
+dotnet new sln -n MyApp               # Create solution
+dotnet sln add src/MyApp.Api          # Add project to solution
+dotnet add reference ../MyApp.Domain  # Add project reference
+dotnet add package Serilog            # Add NuGet package
+
+# Build and run
+dotnet build --warnaserror            # Build with warnings as errors
+dotnet run --project src/MyApp.Api    # Run specific project
+dotnet watch --project src/MyApp.Api  # Hot reload
+
+# Testing
+dotnet test                           # Run all tests
+dotnet test --filter "Category=Unit"  # Filter tests
+dotnet test --collect:"XPlat Code Coverage"  # With coverage
+dotnet test --logger "console;verbosity=detailed"
+
+# Analysis
+dotnet format                         # Apply code style
+dotnet format --verify-no-changes     # CI check
+```
+
+## Project Configuration
+
+### Directory.Build.props
+
+Shared settings across all projects in the solution:
+
+```xml
+<Project>
+  <PropertyGroup>
+    <TargetFramework>net9.0</TargetFramework>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+    <EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
+    <AnalysisLevel>latest-recommended</AnalysisLevel>
+  </PropertyGroup>
+
+  <!-- Central package management -->
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
+</Project>
+```
+
+### Directory.Packages.props
+
+Central package version management (single source of truth):
+
+```xml
+<Project>
+  <ItemGroup>
+    <!-- Core -->
+    <PackageVersion Include="Microsoft.EntityFrameworkCore" Version="9.0.0" />
+    <PackageVersion Include="Npgsql.EntityFrameworkCore.PostgreSQL" Version="9.0.0" />
+
+    <!-- Testing -->
+    <PackageVersion Include="xunit" Version="2.9.0" />
+    <PackageVersion Include="FluentAssertions" Version="7.0.0" />
+    <PackageVersion Include="NSubstitute" Version="5.3.0" />
+    <PackageVersion Include="Testcontainers.PostgreSql" Version="4.0.0" />
+
+    <!-- Analysis -->
+    <PackageVersion Include="SonarAnalyzer.CSharp" Version="10.0.0" />
+    <PackageVersion Include="Roslynator.Analyzers" Version="4.12.0" />
+  </ItemGroup>
+</Project>
+```
+
+## .editorconfig
+
+```ini
+root = true
+
+[*.cs]
+# Naming conventions
+dotnet_naming_rule.private_fields_should_be_camel_case.severity = error
+dotnet_naming_rule.private_fields_should_be_camel_case.symbols = private_fields
+dotnet_naming_rule.private_fields_should_be_camel_case.style = underscore_camel_case
+
+dotnet_naming_symbols.private_fields.applicable_kinds = field
+dotnet_naming_symbols.private_fields.applicable_accessibilities = private
+
+dotnet_naming_style.underscore_camel_case.required_prefix = _
+dotnet_naming_style.underscore_camel_case.capitalization = camel_case
+
+# Code style
+csharp_style_var_for_built_in_types = false:warning
+csharp_style_var_when_type_is_apparent = true:suggestion
+csharp_style_var_elsewhere = false:suggestion
+
+csharp_prefer_simple_using_statement = true:warning
+csharp_style_namespace_declarations = file_scoped:warning
+csharp_style_prefer_primary_constructors = true:suggestion
+
+# Formatting
+dotnet_sort_system_directives_first = true
+csharp_new_line_before_open_brace = all
+```
+
+## Analyzers
+
+```xml
+<!-- In .csproj or Directory.Build.props -->
+<ItemGroup>
+  <!-- Roslyn analyzers -->
+  <PackageReference Include="SonarAnalyzer.CSharp" PrivateAssets="all" />
+  <PackageReference Include="Roslynator.Analyzers" PrivateAssets="all" />
+  <PackageReference Include="Microsoft.CodeAnalysis.NetAnalyzers" PrivateAssets="all" />
+
+  <!-- Security analyzers -->
+  <PackageReference Include="SecurityCodeScan.VS2019" PrivateAssets="all" />
+</ItemGroup>
+```
+
+## Docker
+
+```dockerfile
+# Multi-stage build for minimal image
+FROM mcr.microsoft.com/dotnet/sdk:9.0 AS build
+WORKDIR /src
+COPY Directory.Build.props Directory.Packages.props ./
+COPY **/*.csproj ./
+RUN dotnet restore
+
+COPY . .
+RUN dotnet publish src/MyApp.Api -c Release -o /app --no-restore
+
+# Runtime image — minimal, non-root
+FROM mcr.microsoft.com/dotnet/aspnet:9.0-alpine AS runtime
+RUN addgroup -S appgroup && adduser -S appuser -G appgroup
+USER appuser
+WORKDIR /app
+COPY --from=build /app .
+EXPOSE 8080
+ENV ASPNETCORE_URLS=http://+:8080
+ENTRYPOINT ["dotnet", "MyApp.Api.dll"]
+```
+
+## CI/CD (GitHub Actions)
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16-alpine
+        env:
+          POSTGRES_PASSWORD: test
+          POSTGRES_DB: testdb
+        ports:
+          - 5432:5432
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-dotnet@v4
+        with:
+          dotnet-version: '9.0.x'
+
+      - name: Restore
+        run: dotnet restore
+
+      - name: Build
+        run: dotnet build --no-restore --warnaserror
+
+      - name: Format check
+        run: dotnet format --verify-no-changes --no-restore
+
+      - name: Test
+        run: dotnet test --no-build --collect:"XPlat Code Coverage" --logger trx
+        env:
+          ConnectionStrings__TestDb: "Host=localhost;Database=testdb;Username=postgres;Password=test"
+
+      - name: Upload coverage
+        uses: codecov/codecov-action@v4
+```
+
+## NuGet Package Publishing
+
+```xml
+<!-- For library projects -->
+<PropertyGroup>
+  <PackageId>MyCompany.MyLibrary</PackageId>
+  <Version>1.0.0</Version>
+  <Description>A useful library</Description>
+  <Authors>Your Name</Authors>
+  <PackageLicenseExpression>MIT</PackageLicenseExpression>
+  <PackageReadmeFile>README.md</PackageReadmeFile>
+  <GenerateDocumentationFile>true</GenerateDocumentationFile>
+  <PublishRepositoryUrl>true</PublishRepositoryUrl>
+  <EmbedUntrackedSources>true</EmbedUntrackedSources>
+  <IncludeSymbols>true</IncludeSymbols>
+  <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+</PropertyGroup>
+```
+
+```bash
+dotnet pack -c Release
+dotnet nuget push bin/Release/*.nupkg --source https://api.nuget.org/v3/index.json --api-key $NUGET_KEY
+```
+
+## Logging with Serilog
+
+```csharp
+// Program.cs
+builder.Host.UseSerilog((context, config) =>
+    config.ReadFrom.Configuration(context.Configuration)
+        .Enrich.FromLogContext()
+        .Enrich.WithMachineName()
+        .Enrich.WithEnvironmentName()
+        .WriteTo.Console(new CompactJsonFormatter())
+        .WriteTo.Seq(context.Configuration["Seq:Url"]!));
+
+// Structured logging — always use templates, never interpolation
+logger.LogInformation("Processing order {OrderId} for {CustomerId}", order.Id, order.CustomerId);
+// NOT: logger.LogInformation($"Processing order {order.Id}"); // Defeats structured logging
+```
+
+## Anti-Patterns
+
+```csharp
+// Never: hardcoded connection strings
+var conn = "Host=localhost;Database=mydb;Password=secret";
+// Use configuration and user-secrets for development
+
+// Never: version conflicts across projects
+// Use Directory.Packages.props for central version management
+
+// Never: shipping debug builds
+// Always build Release for production: dotnet publish -c Release
+
+// Never: skipping dotnet format in CI
+// Code style drift makes reviews harder and diffs noisier
+```

package/templates/csharp-expert/CLAUDE.md

@@ -0,0 +1,360 @@
+# C# Expert Development Guide
+
+Principal-level guidelines for C# engineering. Deep .NET runtime knowledge, modern language features, and production-grade patterns.
+
+---
+
+## Overview
+
+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
+│   │   ├── Endpoints/
+│   │   └── Middleware/
+│   ├── MyApp.Application/      # Use cases (no framework deps)
+│   │   ├── Commands/
+│   │   ├── Queries/
+│   │   └── Interfaces/
+│   ├── MyApp.Domain/           # Core domain (zero dependencies)
+│   │   ├── Entities/
+│   │   ├── ValueObjects/
+│   │   └── Events/
+│   └── MyApp.Infrastructure/   # External concerns (DB, HTTP)
+│       ├── Persistence/
+│       └── Services/
+├── tests/
+│   ├── MyApp.UnitTests/
+│   ├── MyApp.IntegrationTests/
+│   └── MyApp.ArchitectureTests/
+├── Directory.Build.props
+├── .editorconfig
+└── MyApp.sln
+```
+
+---
+
+## Language Features
+
+### Nullable Reference Types
+
+```csharp
+public async Task<User?> FindByEmailAsync(string email)
+{
+    ArgumentException.ThrowIfNullOrWhiteSpace(email);
+    return await _repository.FindByEmailAsync(email);
+}
+```
+
+- Never disable nullable warnings project-wide
+- `string` means non-null. `string?` means nullable
+- Use `ArgumentNullException.ThrowIfNull()` at public API boundaries
+
+### Records
+
+```csharp
+// Immutable data with value semantics
+public record CreateUserRequest(string Name, string Email);
+public readonly record struct Coordinate(double Latitude, double Longitude);
+
+// Non-destructive mutation
+var updated = original with { Email = "new@example.com" };
+```
+
+### Pattern Matching
+
+```csharp
+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
+};
+```
+
+### Spans and Memory
+
+```csharp
+public static bool StartsWithDigit(ReadOnlySpan<char> input)
+    => !input.IsEmpty && char.IsDigit(input[0]);
+```
+
+---
+
+## Async Patterns
+
+### The Golden Rules
+
+1. Async all the way down — never mix sync and async
+2. Never block on async — no `.Result`, `.Wait()`, `.GetAwaiter().GetResult()`
+3. Always pass `CancellationToken`
+4. `ConfigureAwait(false)` in library code only
+5. Return `Task`, not `void` — `async void` is only for event handlers
+
+### CancellationToken
+
+```csharp
+public async Task<OrderResult> ProcessOrderAsync(
+    CreateOrderRequest request, CancellationToken cancellationToken)
+{
+    var user = await _userService.GetByIdAsync(request.UserId, cancellationToken);
+    cancellationToken.ThrowIfCancellationRequested();
+    var order = Order.Create(user, request.Items);
+    await _repository.SaveAsync(order, cancellationToken);
+    return new OrderResult(order.Id);
+}
+```
+
+### Concurrent Operations
+
+```csharp
+var userTask = _userService.GetByIdAsync(userId, ct);
+var ordersTask = _orderService.GetRecentAsync(userId, ct);
+await Task.WhenAll(userTask, ordersTask);
+```
+
+### Channels
+
+```csharp
+private readonly Channel<DomainEvent> _channel =
+    Channel.CreateBounded<DomainEvent>(new BoundedChannelOptions(1000)
+    {
+        FullMode = BoundedChannelFullMode.Wait,
+        SingleReader = true
+    });
+```
+
+---
+
+## Dependency Injection
+
+### Service Lifetimes
+
+- **Transient**: New instance every time. Lightweight, stateless services.
+- **Scoped**: One per request. DbContext, Unit of Work.
+- **Singleton**: One for app lifetime. Caches, config, HTTP clients.
+
+### The Captive Dependency Problem
+
+A singleton must NEVER depend on a scoped or transient service.
+
+```csharp
+// WRONG: singleton captures scoped DbContext
+// RIGHT: use IServiceScopeFactory to create scopes on demand
+```
+
+### Options Pattern
+
+```csharp
+builder.Services
+    .AddOptions<SmtpOptions>()
+    .BindConfiguration(SmtpOptions.SectionName)
+    .ValidateDataAnnotations()
+    .ValidateOnStart();
+```
+
+---
+
+## Error Handling
+
+### Two Categories
+
+1. **Exceptions** — Programming errors, infrastructure failures
+2. **Result patterns** — Validation failures, business rule violations
+
+### Guard Clauses
+
+```csharp
+ArgumentNullException.ThrowIfNull(request);
+ArgumentException.ThrowIfNullOrWhiteSpace(request.Email);
+ArgumentOutOfRangeException.ThrowIfNegativeOrZero(request.Quantity);
+```
+
+### Result Pattern
+
+```csharp
+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)
+    });
+```
+
+---
+
+## Testing
+
+### Framework Stack
+
+| Tool | Purpose |
+|------|---------|
+| xUnit | Test framework |
+| NSubstitute | Mocking |
+| FluentAssertions | Readable assertions |
+| Bogus | Test data generation |
+| Testcontainers | Real databases in tests |
+| ArchUnitNET | Architecture tests |
+
+### Unit Test Structure
+
+```csharp
+[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");
+}
+```
+
+### Integration Tests
+
+```csharp
+public class OrderEndpointTests : IClassFixture<WebApplicationFactory<Program>>
+{
+    [Fact]
+    public async Task POST_orders_returns_created_for_valid_request()
+    {
+        var response = await _client.PostAsJsonAsync("/orders", request);
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+    }
+}
+```
+
+---
+
+## Performance
+
+### Profile First
+
+```bash
+dotnet-counters monitor --process-id <pid>
+dotnet-trace collect --process-id <pid>
+```
+
+### Key Patterns
+
+- `AsNoTracking()` for read-only EF Core queries
+- `ArrayPool<T>.Shared` for buffer reuse
+- `FrozenDictionary` for read-heavy, write-once lookups
+- `ObjectPool<T>` for expensive-to-create objects
+- Compiled EF Core queries for hot paths
+- Project to DTOs in LINQ — don't load full entities
+- Use `struct` for small, immutable value types (< 16 bytes guideline)
+
+---
+
+## ASP.NET Core
+
+### Minimal APIs
+
+```csharp
+var group = app.MapGroup("/orders").RequireAuthorization();
+group.MapGet("/{id:int}", GetOrderById);
+group.MapPost("/", CreateOrder);
+```
+
+### Health Checks
+
+```csharp
+builder.Services.AddHealthChecks()
+    .AddDbContextCheck<AppDbContext>("database")
+    .AddRedis(connectionString, "redis");
+
+app.MapHealthChecks("/healthz");
+```
+
+### Rate Limiting
+
+```csharp
+builder.Services.AddRateLimiter(options =>
+    options.AddFixedWindowLimiter("api", config =>
+    {
+        config.PermitLimit = 100;
+        config.Window = TimeSpan.FromMinutes(1);
+    }));
+```
+
+---
+
+## Tooling
+
+### Essential Stack
+
+| Tool | Purpose |
+|------|---------|
+| dotnet CLI | Build, test, publish |
+| dotnet format | Code style enforcement |
+| Roslyn analyzers | Static analysis |
+| BenchmarkDotNet | Performance benchmarks |
+| Serilog | Structured logging |
+| Central Package Management | Version consistency |
+
+### CI Essentials
+
+```bash
+dotnet restore
+dotnet build --warnaserror
+dotnet format --verify-no-changes
+dotnet test --collect:"XPlat Code Coverage"
+```
+
+---
+
+## 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