@polymorphism-tech/morph-spec 2.2.0 → 2.4.0

package/content/.claude/skills/specialists/dotnet-senior.md

@@ -0,0 +1,287 @@
+# .NET Senior Engineer
+
+> **Layer:** 1 | **Load:** always | **Scope:** All .NET projects (Core Agent)
+
+Senior .NET engineer specialist. Writes production-quality C# following all framework standards. Includes **Ultrathink Mode** for complex architectural decisions.
+
+> **Ref:** `framework/standards/coding.md` — ALL code output MUST follow these conventions.
+> **Ref:** `framework/standards/architecture.md` — ALL code MUST respect layer boundaries.
+> **Ref:** `.claude/skills/checklists/code-review.md` — Self-check before delivering code.
+
+---
+
+## Two Modes
+
+### Standard Mode (default)
+
+Active for all C# code writing. Every file produced follows the coding standards and architecture patterns.
+
+**Trigger:** Any implementation task (always active as Core Agent).
+
+### Ultrathink Mode
+
+Extended deep-reasoning mode for complex decisions. Think step by step through trade-offs before recommending.
+
+**Trigger keywords:** `ultrathink`, `deep-think`, `think deeply`, `analyze deeply`, `complex decision`
+
+**Use for:**
+- Technology/library selection (MudBlazor vs Fluent UI, Hangfire vs Azure Functions)
+- Architecture pattern decisions (CQRS vs simple, Repository vs direct DbContext)
+- Performance optimization strategy
+- Migration planning (.NET version upgrades, library migrations)
+- Multi-system integration design
+- Database schema design for complex domains
+
+---
+
+## Code Writing Rules
+
+**MANDATORY for ALL C# code output.** No exceptions.
+
+### Naming (ref: coding.md)
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Classes | PascalCase + `sealed` | `public sealed class OrderService` |
+| Interfaces | `I` + PascalCase | `public interface IOrderService` |
+| Methods | PascalCase + `Async` | `public async Task<Result<Order>> GetByIdAsync(...)` |
+| Constants | PascalCase | `private const int MaxRetryCount = 3;` |
+| Private fields | `_camelCase` | `private readonly ILogger<OrderService> _logger;` |
+| Parameters | camelCase | `(int orderId, CancellationToken ct = default)` |
+
+### Structure
+
+```csharp
+// 1. File-scoped namespace
+namespace MyApp.Application.Services;
+
+// 2. Primary constructor for DI (preferred) or traditional constructor
+public sealed class OrderService(
+    IOrderRepository repository,
+    IPaymentGateway paymentGateway,
+    ILogger<OrderService> logger) : IOrderService
+{
+    // 3. Constants first (PascalCase)
+    private const int MaxRetryCount = 3;
+    private const string DefaultCurrency = "BRL";
+
+    // 4. Public methods (business operations)
+    public async Task<Result<OrderResponse>> CreateAsync(
+        CreateOrderRequest request,
+        CancellationToken ct = default)
+    {
+        // 5. Entry logging with correlation
+        logger.LogInformation("Creating order for customer {CustomerId}", request.CustomerId);
+
+        // 6. Validation (early return with Result)
+        if (request.Items.Count == 0)
+            return Result.Failure<OrderResponse>("Order must have at least one item");
+
+        // 7. Domain logic
+        var order = Order.Create(request.CustomerId, request.Items);
+
+        // 8. Persistence
+        await repository.AddAsync(order, ct);
+        await repository.SaveChangesAsync(ct);
+
+        // 9. Exit logging
+        logger.LogInformation("Order {OrderId} created successfully", order.Id);
+
+        // 10. Return mapped response
+        return Result.Success(order.ToResponse());
+    }
+}
+```
+
+### Mandatory Patterns
+
+| Pattern | Rule | Example |
+|---------|------|---------|
+| **CancellationToken** | Last parameter on ALL async methods | `CancellationToken ct = default` |
+| **Result pattern** | Business errors return Result, NOT exceptions | `Result.Failure<T>("message")` |
+| **Structured logging** | Entry + exit + error on every service method | `logger.LogInformation("...", correlationId)` |
+| **sealed** | All classes sealed unless designed for inheritance | `public sealed class OrderService` |
+| **Nullable types** | Always enabled, `?` only when truly optional | `string? middleName` (optional) vs `string name` (required) |
+| **Primary constructors** | For DI injection (C# 12+) | `class OrderService(IRepo repo)` |
+| **Expression body** | Single-line members | `public int Count => _items.Count;` |
+| **Pattern matching** | `is null` / `is not null` | `if (order is null) return ...` |
+| **Collection expressions** | Prefer `[..]` syntax | `List<int> ids = [1, 2, 3];` |
+
+### Entity Pattern
+
+```csharp
+namespace MyApp.Domain.Entities;
+
+public sealed class Order
+{
+    // Private constructor — force factory method
+    private Order() { }
+
+    public Guid Id { get; private set; }
+    public int CustomerId { get; private set; }
+    public OrderStatus Status { get; private set; }
+    public decimal Total { get; private set; }
+    public DateTime CreatedAt { get; private set; }
+
+    // Factory method with validation
+    public static Order Create(int customerId, List<OrderItem> items)
+    {
+        if (items.Count == 0)
+            throw new DomainException("Order must have at least one item");
+
+        return new Order
+        {
+            Id = Guid.NewGuid(),
+            CustomerId = customerId,
+            Status = OrderStatus.Created,
+            Total = items.Sum(i => i.Price * i.Quantity),
+            CreatedAt = DateTime.UtcNow
+        };
+    }
+
+    // Behavior methods (not anemic)
+    public void MarkAsPaid()
+    {
+        if (Status >= OrderStatus.Completed || Status == OrderStatus.Failed)
+            throw new DomainException($"Cannot mark order {Id} as paid in status {Status}");
+        Status = OrderStatus.PendingPayment;
+    }
+}
+```
+
+### DTO Pattern
+
+```csharp
+namespace MyApp.Application.DTOs;
+
+// Request: record with required properties
+public sealed record CreateOrderRequest(
+    int CustomerId,
+    List<OrderItemRequest> Items);
+
+// Response: record with computed properties
+public sealed record OrderResponse(
+    Guid Id,
+    int CustomerId,
+    string StatusDisplay,
+    decimal Total,
+    DateTime CreatedAt);
+
+// Enum: PascalCase members, error states at 100+
+public enum OrderStatus
+{
+    Created = 0,
+    PendingPayment = 1,
+    Processing = 2,
+    Shipped = 3,
+    Completed = 4,
+    // Error states (high values for comparison operators)
+    Failed = 100,
+    Cancelled = 101,
+    Refunded = 102
+}
+```
+
+---
+
+## Post-Implementation Pipeline
+
+After writing code, self-check before delivering:
+
+```
+1. NAMING CHECK     → Does every identifier follow coding.md?
+2. ARCHITECTURE     → Are files in the correct layer? No forbidden references?
+3. ASYNC            → CancellationToken on all async? No .Result/.Wait()?
+4. LOGGING          → Entry/exit/error logging? Message templates (not $"")?
+5. ERROR HANDLING   → Result pattern for business? No empty catch?
+6. SEALED           → All classes sealed?
+7. NULLABLE         → <Nullable>enable</Nullable>? ? only where optional?
+```
+
+Then trigger **Code Analyzer** for deeper review (automatic at checkpoints and FASE 5).
+
+---
+
+## Ultrathink Decision Template
+
+When in Ultrathink Mode, produce structured analysis:
+
+```markdown
+## Decision: {Title}
+
+### Context
+{Why this decision is needed now. What triggered it. Current state.}
+
+### Constraints
+- {Constraint 1: budget, timeline, team skill, existing tech}
+- {Constraint 2}
+
+### Options Analysis
+
+| Criterion | Option A: {Name} | Option B: {Name} | Option C: {Name} |
+|-----------|------------------|------------------|------------------|
+| **Performance** | {assessment} | {assessment} | {assessment} |
+| **Complexity** | {Low/Medium/High} | {Low/Medium/High} | {Low/Medium/High} |
+| **Maintainability** | {assessment} | {assessment} | {assessment} |
+| **Cost** | {assessment} | {assessment} | {assessment} |
+| **Risk** | {assessment} | {assessment} | {assessment} |
+| **Team familiarity** | {assessment} | {assessment} | {assessment} |
+
+### Option A: {Name}
+**Pros:** {list}
+**Cons:** {list}
+**Best when:** {scenario}
+
+### Option B: {Name}
+**Pros:** {list}
+**Cons:** {list}
+**Best when:** {scenario}
+
+### Recommendation
+**{Option X}** because {justification tied to constraints and criteria}.
+
+### Implementation Impact
+- **Files affected:** {count and key files}
+- **Migrations:** {yes/no, what changes}
+- **Breaking changes:** {yes/no, what breaks}
+- **Estimated effort:** {T-shirt size with rationale}
+- **Rollback plan:** {how to revert if needed}
+```
+
+---
+
+## .NET 10 / C# 14 Quick Patterns
+
+| Pattern | When | Example |
+|---------|------|---------|
+| Primary constructors | DI injection | `class Service(IRepo repo)` |
+| Collection expressions | Initialize collections | `List<int> ids = [1, 2, 3]` |
+| File-scoped namespaces | Always | `namespace MyApp.Services;` |
+| Raw string literals | Multi-line strings, SQL | `"""SELECT * FROM ..."""` |
+| Records | Immutable DTOs | `record OrderResponse(Guid Id, ...)` |
+| Pattern matching | Type checks, null checks | `if (x is Order { Status: > 0 } order)` |
+| `required` modifier | Non-nullable init props | `public required string Name { get; init; }` |
+| `sealed` classes | Default for all classes | `public sealed class OrderService` |
+| Extension methods | Add behavior to existing types | `public static class OrderExtensions` |
+| Global usings | Reduce repetitive imports | `global using MyApp.Domain.Entities;` |
+
+---
+
+## Anti-Patterns to NEVER Produce
+
+| Anti-Pattern | Why | Instead |
+|--------------|-----|---------|
+| `async void` | Exceptions lost, can't await | `async Task` (always) |
+| `.Result` / `.Wait()` | Deadlock in Blazor Server | `await` |
+| `new DbContext()` in service | Wrong lifetime, no DI | Constructor injection |
+| `catch (Exception) { }` | Swallowed exception | Log + rethrow or Result |
+| Public fields | Encapsulation broken | Properties with `{ get; private set; }` |
+| `string.Format` in logs | Defeats structured logging | Message templates |
+| `== null` | Not idiomatic C# | `is null` |
+| Unsealed classes | Unintended inheritance | `sealed` keyword |
+| Service Locator | Hidden dependencies | Constructor injection |
+| God class (500+ lines) | Unmaintainable | Split by responsibility |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/specialists/ef-modeler.md

@@ -1,200 +1,113 @@
-# EF Modeler
-
-Especialista em Entity Framework Core para modelagem de dados e banco de dados.
-
-## Responsabilidades
-
-1. **Modelar entidades** e relacionamentos
-2. **Criar migrations** seguras e reversíveis
-3. **Otimizar queries** para performance
-4. **Configurar DbContext** corretamente
-
-## Triggers
-
-Keywords: `entity`, `database`, `migration`, `ef core`, `dbcontext`, `table`, `column`, `relationship`, `query`
-
-## Estrutura de Entidades
-
-```csharp
-// Domain/Entities/Order.cs
-public class Order : BaseEntity
-{
-    public string OrderNumber { get; private set; } = null!;
-    public OrderStatus Status { get; private set; }
-    public decimal Total { get; private set; }
-    public DateTime CreatedAt { get; private set; }
-
-    // Navigation properties
-    public int CustomerId { get; private set; }
-    public Customer Customer { get; private set; } = null!;
-
-    public ICollection<OrderItem> Items { get; private set; } = new List<OrderItem>();
-
-    // Factory method
-    public static Order Create(int customerId, IEnumerable<OrderItem> items)
-    {
-        var order = new Order
-        {
-            OrderNumber = GenerateOrderNumber(),
-            Status = OrderStatus.Pending,
-            CustomerId = customerId,
-            CreatedAt = DateTime.UtcNow
-        };
-
-        foreach (var item in items)
-            order.Items.Add(item);
-
-        order.CalculateTotal();
-        return order;
-    }
-}
-```
-
-## Configuração do DbContext
-
-```csharp
-// Infrastructure/Data/AppDbContext.cs
-public class AppDbContext : DbContext
-{
-    public AppDbContext(DbContextOptions<AppDbContext> options)
-        : base(options) { }
-
-    public DbSet<Order> Orders => Set<Order>();
-    public DbSet<Customer> Customers => Set<Customer>();
-    public DbSet<OrderItem> OrderItems => Set<OrderItem>();
-
-    protected override void OnModelCreating(ModelBuilder modelBuilder)
-    {
-        modelBuilder.ApplyConfigurationsFromAssembly(
-            typeof(AppDbContext).Assembly);
-    }
-}
-
-// Infrastructure/Data/Configurations/OrderConfiguration.cs
-public class OrderConfiguration : IEntityTypeConfiguration<Order>
-{
-    public void Configure(EntityTypeBuilder<Order> builder)
-    {
-        builder.ToTable("Orders");
-
-        builder.HasKey(o => o.Id);
-
-        builder.Property(o => o.OrderNumber)
-            .IsRequired()
-            .HasMaxLength(20);
-
-        builder.Property(o => o.Total)
-            .HasPrecision(18, 2);
-
-        builder.HasIndex(o => o.OrderNumber)
-            .IsUnique();
-
-        builder.HasOne(o => o.Customer)
-            .WithMany(c => c.Orders)
-            .HasForeignKey(o => o.CustomerId)
-            .OnDelete(DeleteBehavior.Restrict);
-
-        builder.HasMany(o => o.Items)
-            .WithOne(i => i.Order)
-            .HasForeignKey(i => i.OrderId)
-            .OnDelete(DeleteBehavior.Cascade);
-    }
-}
-```
-
-## Migrations Seguras
-
-```powershell
-# Criar migration
-dotnet ef migrations add {MigrationName} --project src/Infrastructure --startup-project src/Web
-
-# Script SQL para revisão
-dotnet ef migrations script --idempotent --output migration.sql
-
-# Aplicar migration
-dotnet ef database update
-```
-
-### Convenções de Naming
-
-```
-{YYYYMMDD}_{Numero}_{Descricao}
-
-Exemplos:
-- 20240301_001_CreateOrdersTable
-- 20240301_002_AddCustomerIdToOrders
-- 20240302_001_CreateIndexOnOrderNumber
-```
-
-## Queries Otimizadas
-
-```csharp
-// RUIM: N+1 problem
-var orders = await _context.Orders.ToListAsync();
-foreach (var order in orders)
-{
-    var items = order.Items; // N queries adicionais!
-}
-
-// BOM: Include explicito
-var orders = await _context.Orders
-    .Include(o => o.Items)
-    .Include(o => o.Customer)
-    .ToListAsync();
-
-// MELHOR: Projection
-var orderDtos = await _context.Orders
-    .Select(o => new OrderDto
-    {
-        Id = o.Id,
-        OrderNumber = o.OrderNumber,
-        CustomerName = o.Customer.Name,
-        ItemCount = o.Items.Count,
-        Total = o.Total
-    })
-    .ToListAsync();
-
-// Paginação
-var pagedOrders = await _context.Orders
-    .OrderByDescending(o => o.CreatedAt)
-    .Skip((page - 1) * pageSize)
-    .Take(pageSize)
-    .ToListAsync();
-```
-
-## Padrões de Repository (Opcional)
-
-```csharp
-// Se usar repository pattern
-public interface IOrderRepository
-{
-    Task<Order?> GetByIdAsync(int id, CancellationToken ct = default);
-    Task<Order?> GetByOrderNumberAsync(string orderNumber, CancellationToken ct = default);
-    Task<IReadOnlyList<Order>> GetByCustomerIdAsync(int customerId, CancellationToken ct = default);
-    Task AddAsync(Order order, CancellationToken ct = default);
-    void Update(Order order);
-    void Remove(Order order);
-}
-```
-
-## Documentação de Referência
-
-- [EF Core Docs](https://learn.microsoft.com/en-us/ef/core/)
-- [Migrations](https://learn.microsoft.com/en-us/ef/core/managing-schemas/migrations/)
-- [Performance](https://learn.microsoft.com/en-us/ef/core/performance/)
-- [Relationships](https://learn.microsoft.com/en-us/ef/core/modeling/relationships/)
-
-## Checklist de Modelagem
-
-- [ ] Entidades com private setters
-- [ ] Factory methods para criação
-- [ ] Configuração separada (IEntityTypeConfiguration)
-- [ ] Índices em colunas de busca
-- [ ] Precision definida para decimais
-- [ ] Delete behavior explícito
-- [ ] Migration script gerado e revisado
-- [ ] Queries com Include ou Projection
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# EF Modeler
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** entity, database, migration, ef core, dbcontext, table, column, relationship, query
+
+Especialista em Entity Framework Core para modelagem de dados e banco de dados.
+
+## .NET 10 Compatibility
+- EF Core: **>= 10.0.0** | New: Vector search, primitive collections
+- **Ref:** `framework/standards/dotnet10-compatibility.md`
+
+---
+
+## Entity Structure
+
+```csharp
+public class Order : BaseEntity
+{
+    public string OrderNumber { get; private set; } = null!;
+    public OrderStatus Status { get; private set; }
+    public decimal Total { get; private set; }
+    public DateTime CreatedAt { get; private set; }
+
+    // Navigation
+    public int CustomerId { get; private set; }
+    public Customer Customer { get; private set; } = null!;
+    public ICollection<OrderItem> Items { get; private set; } = new List<OrderItem>();
+
+    // Factory method
+    public static Order Create(int customerId, IEnumerable<OrderItem> items) { ... }
+}
+```
+
+**Rules:** Private setters, factory methods, explicit navigation properties.
+
+## Configuration
+
+```csharp
+public class OrderConfiguration : IEntityTypeConfiguration<Order>
+{
+    public void Configure(EntityTypeBuilder<Order> builder)
+    {
+        builder.ToTable("Orders");
+        builder.HasKey(o => o.Id);
+        builder.Property(o => o.OrderNumber).IsRequired().HasMaxLength(20);
+        builder.Property(o => o.Total).HasPrecision(18, 2);
+        builder.HasIndex(o => o.OrderNumber).IsUnique();
+        builder.HasOne(o => o.Customer).WithMany(c => c.Orders)
+            .HasForeignKey(o => o.CustomerId).OnDelete(DeleteBehavior.Restrict);
+        builder.HasMany(o => o.Items).WithOne(i => i.Order)
+            .HasForeignKey(i => i.OrderId).OnDelete(DeleteBehavior.Cascade);
+    }
+}
+```
+
+## Migrations
+
+```powershell
+dotnet ef migrations add {Name} --project src/Infrastructure --startup-project src/Web
+dotnet ef migrations script --idempotent --output migration.sql
+dotnet ef database update
+```
+
+**Naming:** `{YYYYMMDD}_{Number}_{Description}` (e.g., `20240301_001_CreateOrdersTable`)
+
+## Query Optimization
+
+```csharp
+// ❌ N+1 problem
+var orders = await _context.Orders.ToListAsync();
+foreach (var o in orders) { var items = o.Items; } // N extra queries!
+
+// ✅ Include
+var orders = await _context.Orders.Include(o => o.Items).Include(o => o.Customer).ToListAsync();
+
+// ✅ Projection (best)
+var dtos = await _context.Orders.Select(o => new OrderDto {
+    Id = o.Id, CustomerName = o.Customer.Name, ItemCount = o.Items.Count
+}).ToListAsync();
+```
+
+---
+
+## Background Operations
+
+> **Ref:** `framework/standards/blazor-efcore.md` — Repository Factory pattern for background ops
+
+**Rule:** Separate thread = isolated DbContext via `IDbContextFactory`.
+Background tasks, `Task.Run`, SignalR, Hangfire jobs — all need `IDbContextFactory`.
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Invalid object name 'Table'` | Migration not applied | Run `database update` |
+| `PendingModelChangesWarning` | Model changed without migration | Create new migration |
+| `Include() doesn't load` | `HasMany<T>()` without navigation | Use `HasMany(x => x.Nav)` |
+| `A second operation was started` | Shared DbContext | Use `IDbContextFactory` |
+
+## Checklist
+- [ ] Entities with private setters + factory methods
+- [ ] Separate configuration (IEntityTypeConfiguration)
+- [ ] Indexes on search columns
+- [ ] Precision defined for decimals
+- [ ] Delete behavior explicit
+- [ ] Migration script generated and reviewed
+- [ ] Queries with Include or Projection (no N+1)
+- [ ] `IDbContextFactory` for background ops
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*