sdg-agents 1.0.5

package/src/assets/instructions/idioms/csharp/patterns.md

@@ -0,0 +1,367 @@
+# C# — Project Conventions
+
+> Universal principles (naming, composition, DRY, performance, security) are in `../../core/staff-dna.md`.
+> This file contains only decisions specific to this language and stack.
+
+<ruleset name="CSharpConventions">
+
+## Error Handling
+
+- **Strategy**: Result Pattern in the domain (`Result<T>` via sealed record); exceptions only for unexpected failures (infra/runtime)
+- **Propagation**: Result is explicitly returned in business flows; exceptions bubble up to the global middleware
+- **Domain errors**: `sealed record ApiError(string Message, string Code)`; pattern matching for mapping
+- **Never**: `throw` for business rules; `.Result` / `.Wait()` in async code; leak internal details
+
+### Result Pattern
+
+> <rule name="ResultPatternCSharp">
+
+```csharp
+public sealed record ApiError(string Message, string Code);
+
+public record Result<T>(bool IsSuccess, bool IsFailure, T? Value, ApiError? Error)
+{
+    public static Result<T> Success(T value) => new(true, false, value, null);
+    public static Result<T> Fail(string msg, string code) => new(false, true, default, new ApiError(msg, code));
+}
+
+// Pattern matching
+public IActionResult GetOrder(Result<Order> result) => result switch
+{
+    { IsSuccess: true, Value: var o } => Ok(o),
+    { IsFailure: true, Error: var e } => MapError(e),
+    _ => Problem()
+};
+```
+
+> </rule>
+
+---
+
+## HTTP & API
+
+- **Framework**: ASP.NET Core — Minimal APIs (preferred) or Controllers when necessary
+- **Style**: API First + BFF
+- **Route organization**: Vertical slice per feature (`Features/Orders/OrderEndpoints.cs`)
+- **Middleware/hooks**: Auth in the pipeline; validation at the boundary; centralized logging/tracing
+- **DI**: Constructor injection via primary constructors; registration in `Program.cs`; never service locator
+
+### Minimal API per Feature
+
+> <rule name="MinimalAPI">
+
+```csharp
+public static class OrderEndpoints
+{
+    public static void MapOrderEndpoints(this WebApplication app)
+    {
+        var group = app.MapGroup("/api/orders").WithTags("Orders");
+        group.MapPost("/", CreateOrder);
+        group.MapGet("/{id:guid}", GetOrder);
+    }
+
+    private static async Task<IResult> CreateOrder(
+        CreateOrderRequest request,
+        OrderService service,
+        CancellationToken ct)
+    {
+        var result = await service.CreateOrderAsync(request, ct);
+        var httpResponse = ToEnvelope(result);
+        return httpResponse;
+    }
+
+    // Adapter — only layer that knows both Result<T> and HTTP envelope
+    private static IResult ToEnvelope<T>(Result<T> result) => result switch
+    {
+        { IsSuccess: true, Value: var value } =>
+            Results.Ok(new { success = true, error = (object?)null, data = value }),
+        { IsFailure: true, Error: var error } =>
+            Results.Json(
+                new { success = false, error = new { code = error!.Code, message = error.Message }, data = (object?)null },
+                statusCode: MapStatusCode(error.Code)
+            ),
+        _ => Results.Problem()
+    };
+
+    private static int MapStatusCode(string code) => code switch
+    {
+        "NOT_FOUND" => 404,
+        "UNAUTHORIZED" => 401,
+        "FORBIDDEN" => 403,
+        "CONFLICT" => 409,
+        "INVALID_INPUT" => 400,
+        _ => 422
+    };
+}
+```
+
+> </rule>
+
+### Dependency Injection
+
+> <rule name="CSharpDI">
+
+```csharp
+public class OrderService(IOrderRepository repo, INotifier notifier)
+{
+    public async Task<Result<Order>> CreateOrderAsync(CreateOrderRequest request, CancellationToken ct = default)
+    {
+        var order = await repo.SaveAsync(Order.From(request), ct);
+        await notifier.SendAsync(order, ct);
+        return Result<Order>.Success(order);
+    }
+}
+
+// Program.cs
+builder.Services.AddScoped<IOrderRepository, PostgresOrderRepository>();
+builder.Services.AddScoped<OrderService>();
+```
+
+> </rule>
+
+---
+
+## Testing
+
+- **Framework**: xUnit + FluentAssertions + NSubstitute
+- **Style**: Flat, behavior-oriented
+- **Naming**: `MethodName_ShouldDoX_WhenY`
+- **Mocks**: NSubstitute for external dependencies; never mock the domain
+- **What to test**: Business rules, error cases (Result), API contracts
+
+### Unit Testing
+
+> <rule name="CSharpTesting">
+
+```csharp
+public class OrderServiceTests
+{
+    private readonly IOrderRepository _repo = Substitute.For<IOrderRepository>();
+    private readonly INotifier _notifier = Substitute.For<INotifier>();
+    private readonly OrderService _sut;
+
+    public OrderServiceTests() => _sut = new OrderService(_repo, _notifier);
+
+    [Fact]
+    public async Task CreateOrder_ShouldReturnSuccess()
+    {
+        _repo.SaveAsync(Arg.Any<Order>(), Arg.Any<CancellationToken>())
+             .Returns(new Order(Guid.NewGuid(), "prod-1", 2));
+
+        var result = await _sut.CreateOrderAsync(new CreateOrderRequest("prod-1", 2));
+
+        result.IsSuccess.Should().BeTrue();
+        result.Value!.ProductId.Should().Be("prod-1");
+        await _notifier.Received(1).SendAsync(Arg.Any<Order>(), Arg.Any<CancellationToken>());
+    }
+}
+```
+
+> </rule>
+
+### Integration Testing
+
+> <rule name="CSharpIntegration">
+
+```csharp
+public class OrdersApiTests(WebApplicationFactory<Program> factory)
+    : IClassFixture<WebApplicationFactory<Program>>
+{
+    private readonly HttpClient _client = factory.CreateClient();
+
+    [Fact]
+    public async Task CreateOrder_ReturnsCreated()
+    {
+        var response = await _client.PostAsJsonAsync("/api/orders", new { ProductId = "abc", Quantity = 2 });
+        response.StatusCode.Should().Be(HttpStatusCode.Created);
+    }
+}
+```
+
+> </rule>
+
+---
+
+## Types & Contracts
+
+- **DTOs**: `record` for Request/Response; each layer has its own type; never expose EF entities
+- **Validation**: Validation at the boundary — factory method with Result, FluentValidation when rules are complex
+- **Async**: All I/O methods are `async Task<T>`; `Async` suffix; `CancellationToken` in public APIs; never `.Result` / `.Wait()`
+- **Naming**: PascalCase for public members; `_camelCase` for private fields; `I` prefix for interfaces; `Async` suffix for async methods
+
+### Records as Data Carriers
+
+> <rule name="CSharpRecords">
+
+```csharp
+public record CreateUserRequest(string Email, string Password);
+public record UserResponse(Guid Id, string Email);
+
+// Factory method with validation
+public record CreateOrderRequest(string ProductId, int Quantity)
+{
+    public static Result<CreateOrderRequest> Create(string productId, int quantity)
+    {
+        if (string.IsNullOrWhiteSpace(productId))
+            return Result<CreateOrderRequest>.Fail("Product ID is required.", "INVALID_PRODUCT_ID");
+        if (quantity < 1)
+            return Result<CreateOrderRequest>.Fail("Quantity must be at least 1.", "INVALID_QUANTITY");
+        return Result<CreateOrderRequest>.Success(new(productId, quantity));
+    }
+}
+```
+
+> </rule>
+
+### Async Pattern
+
+> <rule name="CSharpAsync">
+
+```csharp
+public async Task<Result<Dashboard>> GetDashboardAsync(string userId, CancellationToken ct = default)
+{
+    var profileTask = _users.FindByIdAsync(userId, ct);
+    var ordersTask = _orders.GetRecentAsync(userId, ct);
+    var notificationsTask = _notifications.GetUnreadAsync(userId, ct);
+
+    await Task.WhenAll(profileTask, ordersTask, notificationsTask);
+
+    return Result<Dashboard>.Success(new Dashboard(
+        Profile: await profileTask,
+        Orders: await ordersTask,
+        Notifications: await notificationsTask
+    ));
+}
+```
+
+> </rule>
+
+---
+
+## LINQ & Collections
+
+> Use LINQ for clarity, not cleverness. Prefer readability over chaining.
+
+### Core Principles
+
+- Prefer **readability over conciseness**
+- Keep queries **simple and predictable**
+- Avoid complex chaining ("magic LINQ")
+- LINQ is for **data transformation**, not business logic
+- Use `foreach` for complex logic or accumulation (sum, total)
+
+### Code Flow Alignment
+
+Keep LINQ inside the **execution step** — never mix orchestration with complex queries.
+
+> <rule name="CSharpLINQ">
+
+````carousel
+```csharp
+// ❌ BAD: Chained LINQ magic — logic buried, untestable, hard to extend
+var result = orders
+    .Where(o => o.Status == "CONFIRMED" && o.CreatedAt > DateTime.UtcNow.AddDays(-30))
+    .GroupBy(o => o.CustomerId)
+    .Select(g => new { CustomerId = g.Key, Total = g.Sum(o => o.Items.Sum(i => i.Price * i.Qty)) })
+    .OrderByDescending(x => x.Total)
+    .ToList();
+```
+<!-- slide -->
+```csharp
+// ✅ GOOD: LINQ for 1-to-1 transform; foreach for accumulation — each step is readable
+var recentOrders = orders
+    .Where(o => o.Status == "CONFIRMED" && o.CreatedAt > DateTime.UtcNow.AddDays(-30))
+    .ToList();
+
+var summaries = recentOrders
+    .GroupBy(o => o.CustomerId)
+    .Select(group => BuildCustomerSummary(group))
+    .OrderByDescending(summary => summary.Total)
+    .ToList();
+
+return summaries;
+
+static CustomerSummary BuildCustomerSummary(IGrouping<Guid, Order> group)
+{
+    decimal total = 0;
+    foreach (var order in group)
+    foreach (var item in order.Items)
+    {
+        var lineAmount = item.Price * item.Qty;
+        total += lineAmount;
+    }
+
+    var customerSummary = new CustomerSummary(group.Key, total);
+    return customerSummary;
+}
+```
+````
+
+> </rule>
+
+### Materialization (ToList / ToArray)
+
+Materialize only when needed: multiple iterations, snapshot of data, or returning a concrete collection.
+
+- Default → `IEnumerable<T>`
+- Use `.ToList()` at boundaries (return, serialization, EF Core terminal calls)
+- Never materialize prematurely inside a pipeline
+
+### Side Effects
+
+LINQ must be **pure** — no side effects inside queries. Never use `.Select(u => { Log(u); return u; })`.
+
+---
+
+## Data Access — EF Core
+
+> Data access rules in [Universal Data Access Principles](../../core/data-access.md).
+
+### DbContext & Tracking
+
+> <rule name="EFContextLifetime">
+> `DbContext` Scoped (one per request). `AsNoTracking()` in read-only queries. Never Singleton.
+
+```csharp
+public async Task<IReadOnlyList<OrderSummary>> GetRecentOrdersAsync(CancellationToken ct) =>
+    await _context.Orders
+        .AsNoTracking()
+        .Where(o => o.CreatedAt > DateTime.UtcNow.AddDays(-30))
+        .Select(o => new OrderSummary(o.Id, o.Total, o.CreatedAt))
+        .ToListAsync(ct);
+```
+
+> </rule>
+
+### Projection — Select over Full Entities
+
+> <rule name="EFProjection">
+> Always project to DTOs via `.Select()`. Never expose EF entities to the API layer.
+
+```csharp
+public async Task<ProductDetail?> GetProductDetailAsync(Guid id, CancellationToken ct) =>
+    await _context.Products
+        .Where(p => p.Id == id)
+        .Select(p => new ProductDetail(p.Id, p.Name, p.Price, p.Category.Name, p.Reviews.Count))
+        .FirstOrDefaultAsync(ct);
+```
+
+> </rule>
+
+### N+1 Prevention
+
+> <rule name="EFNPlusOne">
+> Lazy loading disabled. `.Include()` for known graphs. `AsSplitQuery()` for multiple collections.
+
+```csharp
+var orders = await _context.Orders
+    .Include(o => o.Items)
+    .Include(o => o.Payments)
+    .AsSplitQuery()
+    .Where(o => o.CustomerId == customerId)
+    .ToListAsync(ct);
+```
+
+> </rule>
+
+</ruleset>

package/src/assets/instructions/idioms/flutter/patterns.md

@@ -0,0 +1,97 @@
+# Flutter (Dart) — Project Conventions
+
+> Universal principles (naming, composition, DRY, performance, security) are in `../../core/staff-dna.md`.
+> This file contains only decisions specific to this language and stack.
+
+<ruleset name="FlutterConventions">
+
+## Error Handling
+
+- **Strategy**: Result Pattern (`Result<T>`) in the domain; `throw` only for unexpected failures
+- **Propagation**: Explicit Result between layers; exceptions handled at the boundary (ViewModel/Controller)
+- **Domain errors**: Sealed classes via `freezed` for union types; standard structure (`code`, `message`)
+- **Never**: Exception for business rules; swallow errors; expose technical errors in the UI
+
+### Result Pattern (Sealed Class / Freezed)
+
+> <rule name="ResultPatternFlutter">
+
+```dart
+@freezed
+class Result<T> with _$Result<T> {
+  const factory Result.success(T data) = Success<T>;
+  const factory Result.failure(String message, String code) = Failure<T>;
+}
+
+// Usage in ViewModel
+final result = await _useCase.execute(request);
+state = result.when(
+  success: (data) => state.copyWith(data: data, isLoading: false),
+  failure: (msg, code) => state.copyWith(errorMessage: msg, isLoading: false),
+);
+```
+
+> </rule>
+
+---
+
+## HTTP & API
+
+- **Style**: API First + BFF
+- **Client**: Dio (preferred) or `http`; centralized and typed API client
+- **Serialization**: `json_serializable` or `freezed`
+- **Never**: Call API directly from the widget; mix parsing with UI
+
+---
+
+## Testing
+
+- **Framework**: `flutter_test` / `mocktail`
+- **Style**: Behavior-oriented
+- **Naming**: `shouldDoXWhenY`
+- **Mocks**: Mock only external I/O; domain is always real
+
+---
+
+## Types & Contracts
+
+- **Classes**: Immutable by default (`const`, `final`)
+- **Union types**: `freezed` for complex DTOs and states
+- **Null safety**: Mandatory; avoid `!`
+- **DTOs**: Separated from the domain; never expose internal structure
+- **Validation**: At the boundary (input/API)
+
+---
+
+## Flutter-Specific Delta
+
+- Widget = rendering only; no business logic in `build()`
+- Logic outside the widget (Controller/ViewModel)
+- State management with Riverpod or BLoC — no uncontrolled global state
+- Strong componentization — small and focused widgets
+- Organization by feature
+- Naming: `camelCase` for variables/functions; `PascalCase` for classes; `snake_case` for files
+- `map` is valid for pure 1-to-1 collection transforms; `for` loops are preferred for accumulation or complex logic
+
+### Collections & UI Lists
+
+> <rule name="FlutterCollections">
+
+```dart
+// ✅ map — valid for 1-to-1 transform (e.g. data to widget)
+final userWidgets = users
+    .where((u) => u.isActive)
+    .map((u) => UserCard(user: u))
+    .toList();
+
+// ✅ for loop — preferred for accumulation
+double total = 0;
+for (final item in order.items) {
+    final lineAmount = item.qty * item.price;
+    total += lineAmount;
+}
+```
+
+> </rule>
+
+</ruleset>

package/src/assets/instructions/idioms/go/patterns.md

@@ -0,0 +1,193 @@
+# Go — Project Conventions
+
+> Universal principles (naming, composition, DRY, performance, security) are in `../../core/staff-dna.md`.
+> This file contains only decisions specific to this language and stack.
+
+<ruleset name="GoConventions">
+
+## Error Handling
+
+- **Strategy**: Explicit `(T, error)`; no exceptions, no `panic` for business logic
+- **Propagation**: Errors are explicitly returned; wrapping with `fmt.Errorf("ctx: %w", err)` for traceability
+- **Domain errors**: Sentinel `var` for simple cases; custom `type` with `Error()` when necessary; `errors.Is` / `errors.As` for comparison
+- **Never**: Ignore errors (`_`); `panic` for business rules; swallow errors
+- **Global Handling**: HTTP handler converts `error` → response; structured logging (`slog`)
+
+### Result Pattern (Go Style)
+
+> <rule name="ResultPatternGo">
+
+```go
+type AppError struct {
+    Message string
+    Code    string
+}
+
+func (e *AppError) Error() string {
+    return fmt.Sprintf("[%s] %s", e.Code, e.Message)
+}
+
+func FindUser(ctx context.Context, id string) (*User, error) {
+    if id == "" {
+        return nil, &AppError{Message: "id is required", Code: "INVALID_ID"}
+    }
+    user, err := db.QueryUser(ctx, id)
+    if err != nil {
+        return nil, fmt.Errorf("FindUser: %w", err)
+    }
+    return user, nil
+}
+```
+
+> </rule>
+
+---
+
+## HTTP & API
+
+- **Framework**: `net/http` (preferred) or Echo/Fiber when necessary
+- **Style**: API First + BFF
+- **Route organization**: Vertical slice per feature/package; avoid generic packages (`utils`, `common`)
+- **Middleware/hooks**: Auth via middleware; validation at the boundary; logging/tracing in the pipeline
+- **DI**: Manual — explicit dependency passing via structs; constructor functions (`New...`); avoid containers
+
+### Interface Design
+
+> <rule name="InterfaceDesign">
+> Interfaces defined by the consumer, not the provider. Small interfaces (1-2 methods). `-er` suffix for single-method.
+
+```go
+type UserFinder interface {
+    FindByID(ctx context.Context, id string) (*User, error)
+}
+
+type OrderService struct {
+    users UserFinder
+}
+
+func NewOrderService(users UserFinder) *OrderService {
+    return &OrderService{users: users}
+}
+```
+
+> </rule>
+
+### Context Propagation
+
+> <rule name="ContextPropagation">
+> `context.Context` is the first parameter of every function that performs I/O or can be canceled.
+
+```go
+func (s *Service) CreateOrder(ctx context.Context, input CreateOrderRequest) (*Order, error) {
+    user, err := s.users.FindByID(ctx, input.UserID)
+    if err != nil {
+        return nil, fmt.Errorf("CreateOrder: %w", err)
+    }
+    return s.orders.Save(ctx, newOrder(user, input))
+}
+```
+
+> </rule>
+
+---
+
+## Testing
+
+- **Framework**: built-in (`testing`)
+- **Style**: Table-driven tests (preferred)
+- **Naming**: `TestShouldDoXWhenY`
+- **Mocks**: Small interfaces for abstraction; mock only external I/O; avoid heavy frameworks
+
+### Table-Driven Tests
+
+> <rule name="TableTests">
+
+```go
+func TestParseVersion(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   string
+        want    float64
+        wantErr bool
+    }{
+        {name: "simple", input: "10", want: 10},
+        {name: "decimal", input: "3.14", want: 3.14},
+        {name: "empty", input: "", wantErr: true},
+    }
+
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got, err := ParseVersion(tt.input)
+            if (err != nil) != tt.wantErr {
+                t.Errorf("error = %v, wantErr %v", err, tt.wantErr)
+            }
+            if got != tt.want {
+                t.Errorf("got %v, want %v", got, tt.want)
+            }
+        })
+    }
+}
+```
+
+> </rule>
+
+---
+
+## Types & Contracts
+
+- **struct** for data; small interfaces defined by the consumer
+- No nulls — use zero values carefully; pointers only when strictly necessary
+- Well-defined JSON tags; never expose internal structs directly
+- Manual validation or lightweight library (`go-playground/validator`); simple and explicit
+
+---
+
+## Go-Specific Delta
+
+- Idiomatic > "beautiful architecture" — simplicity is the standard, not the exception
+- Short and clear names; exported = PascalCase; unexported = camelCase; acronyms in caps (`ID`, `HTTP`)
+- Early return for error flow — no `else` after `return err`
+- Avoid "god structs" and "god packages" — focused packages by responsibility
+- `context.Context` always applicable — cancellation and timeout propagated
+- Managed lifecycle goroutines (`errgroup`, `WaitGroup`); never fire-and-forget
+- `defer` immediately after resource acquisition
+- Structured logging (`slog`)
+- Package names: lowercase, single word, no underscores
+- `for` loops are the standard for all collection operations; mapping and transformations follow the imperative pattern
+
+### Goroutines & Concurrency
+
+> <rule name="GoroutinesChannels">
+
+```go
+func ProcessBatch(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    for _, item := range items {
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+    return g.Wait()
+}
+```
+
+> </rule>
+
+### Defer for Cleanup
+
+> <rule name="DeferCleanup">
+
+```go
+func ReadConfig(path string) ([]byte, error) {
+    f, err := os.Open(path)
+    if err != nil {
+        return nil, fmt.Errorf("ReadConfig: %w", err)
+    }
+    defer f.Close()
+    return io.ReadAll(f)
+}
+```
+
+> </rule>
+
+</ruleset>