@polymorphism-tech/morph-spec 1.0.0

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

@@ -0,0 +1,200 @@
+# 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*

package/content/.claude/skills/specialists/hangfire-orchestrator.md

@@ -0,0 +1,245 @@
+# Hangfire Orchestrator
+
+Especialista em background jobs, tarefas agendadas e processamento assíncrono com Hangfire.
+
+## Responsabilidades
+
+1. **Criar jobs** de background para processamento assíncrono
+2. **Configurar schedules** com expressões cron
+3. **Gerenciar filas** e prioridades
+4. **Monitorar** execução via dashboard
+
+## Triggers
+
+Keywords: `scheduled`, `job`, `background`, `cron`, `recurring`, `batch`, `queue`, `hangfire`, `task`
+
+## Por que Hangfire (não Azure Functions)
+
+| Aspecto | Hangfire | Azure Functions |
+|---------|----------|-----------------|
+| Custo | Free (in-process) | Pay per execution |
+| Dashboard | Built-in | App Insights separado |
+| Debugging | Local fácil | Emulator necessário |
+| Estado | Persistido SQL | Storage Account |
+| Complexidade | Baixa | Média-Alta |
+
+## Configuração Básica
+
+```csharp
+// Program.cs
+builder.Services.AddHangfire(config => config
+    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
+    .UseSimpleAssemblyNameTypeSerializer()
+    .UseRecommendedSerializerSettings()
+    .UseSqlServerStorage(
+        builder.Configuration.GetConnectionString("HangfireConnection"),
+        new SqlServerStorageOptions
+        {
+            CommandBatchMaxTimeout = TimeSpan.FromMinutes(5),
+            QueuePollInterval = TimeSpan.Zero,
+            UseRecommendedIsolationLevel = true,
+            DisableGlobalLocks = true
+        }));
+
+builder.Services.AddHangfireServer(options =>
+{
+    options.WorkerCount = Environment.ProcessorCount * 2;
+    options.Queues = new[] { "critical", "default", "low" };
+});
+
+// Middleware
+app.UseHangfireDashboard("/hangfire", new DashboardOptions
+{
+    Authorization = new[] { new HangfireAuthorizationFilter() }
+});
+```
+
+## Tipos de Jobs
+
+### Fire-and-Forget (Uma vez)
+
+```csharp
+// Executa imediatamente em background
+BackgroundJob.Enqueue(() => _emailService.SendWelcomeEmailAsync(userId));
+
+// Com injeção de dependência
+BackgroundJob.Enqueue<IEmailService>(service =>
+    service.SendWelcomeEmailAsync(userId));
+```
+
+### Delayed (Atrasado)
+
+```csharp
+// Executa após delay
+BackgroundJob.Schedule(() =>
+    _orderService.CheckAbandonedCartAsync(cartId),
+    TimeSpan.FromHours(24));
+
+// Em data específica
+BackgroundJob.Schedule(() =>
+    _reminderService.SendReminderAsync(appointmentId),
+    appointmentDate.AddHours(-1));
+```
+
+### Recurring (Recorrente)
+
+```csharp
+// Cron expression
+RecurringJob.AddOrUpdate<IReportService>(
+    "daily-sales-report",
+    service => service.GenerateDailySalesReportAsync(),
+    "0 8 * * *",  // Todo dia às 8h
+    new RecurringJobOptions
+    {
+        TimeZone = TimeZoneInfo.FindSystemTimeZoneById("E. South America Standard Time")
+    });
+
+// Expressões comuns
+// "0 * * * *"     - A cada hora
+// "*/5 * * * *"   - A cada 5 minutos
+// "0 8 * * 1-5"   - 8h em dias úteis
+// "0 0 1 * *"     - Primeiro dia do mês
+```
+
+### Continuations (Encadeamento)
+
+```csharp
+var jobId = BackgroundJob.Enqueue(() => _importService.ImportDataAsync(fileId));
+
+BackgroundJob.ContinueJobWith(jobId, () =>
+    _notificationService.NotifyImportCompleteAsync(fileId));
+```
+
+### Batch (Lote)
+
+```csharp
+// Requer Hangfire.Pro ou implementação custom
+var batchId = BatchJob.StartNew(batch =>
+{
+    foreach (var orderId in orderIds)
+    {
+        batch.Enqueue(() => _orderService.ProcessOrderAsync(orderId));
+    }
+});
+
+BatchJob.ContinueBatchWith(batchId, batch =>
+{
+    batch.Enqueue(() => _reportService.GenerateBatchReportAsync(batchId));
+});
+```
+
+## Estrutura de Job Service
+
+```csharp
+// Jobs/DailySalesReportJob.cs
+public interface IDailySalesReportJob
+{
+    Task ExecuteAsync(CancellationToken ct = default);
+}
+
+public class DailySalesReportJob : IDailySalesReportJob
+{
+    private readonly IOrderRepository _orderRepository;
+    private readonly IReportGenerator _reportGenerator;
+    private readonly IEmailService _emailService;
+    private readonly ILogger<DailySalesReportJob> _logger;
+
+    public DailySalesReportJob(
+        IOrderRepository orderRepository,
+        IReportGenerator reportGenerator,
+        IEmailService emailService,
+        ILogger<DailySalesReportJob> logger)
+    {
+        _orderRepository = orderRepository;
+        _reportGenerator = reportGenerator;
+        _emailService = emailService;
+        _logger = logger;
+    }
+
+    [AutomaticRetry(Attempts = 3)]
+    [Queue("default")]
+    public async Task ExecuteAsync(CancellationToken ct = default)
+    {
+        _logger.LogInformation("Starting daily sales report generation");
+
+        var yesterday = DateTime.Today.AddDays(-1);
+        var orders = await _orderRepository.GetByDateRangeAsync(
+            yesterday, yesterday.AddDays(1), ct);
+
+        var report = await _reportGenerator.GenerateAsync(orders, ct);
+
+        await _emailService.SendReportAsync(report, ct);
+
+        _logger.LogInformation("Daily sales report completed. Orders: {Count}", orders.Count);
+    }
+}
+
+// Registro
+RecurringJob.AddOrUpdate<IDailySalesReportJob>(
+    "daily-sales-report",
+    job => job.ExecuteAsync(default),
+    "0 8 * * *");
+```
+
+## Retry e Error Handling
+
+```csharp
+[AutomaticRetry(Attempts = 5, DelaysInSeconds = new[] { 60, 300, 900, 3600, 7200 })]
+[Queue("critical")]
+public async Task ProcessPaymentAsync(int orderId)
+{
+    try
+    {
+        await _paymentService.ProcessAsync(orderId);
+    }
+    catch (PaymentGatewayException ex)
+    {
+        _logger.LogWarning(ex, "Payment failed for order {OrderId}, will retry", orderId);
+        throw; // Rethrow para Hangfire retry
+    }
+    catch (Exception ex)
+    {
+        _logger.LogError(ex, "Unexpected error processing order {OrderId}", orderId);
+        throw;
+    }
+}
+```
+
+## Dashboard Authorization
+
+```csharp
+public class HangfireAuthorizationFilter : IDashboardAuthorizationFilter
+{
+    public bool Authorize(DashboardContext context)
+    {
+        var httpContext = context.GetHttpContext();
+
+        // Em produção, verificar autenticação/autorização
+        if (!httpContext.User.Identity?.IsAuthenticated ?? true)
+            return false;
+
+        return httpContext.User.IsInRole("Admin");
+    }
+}
+```
+
+## Documentação de Referência
+
+- [Hangfire Documentation](https://docs.hangfire.io/en/latest/)
+- [Cron Expressions](https://crontab.guru/)
+- [SQL Server Storage](https://docs.hangfire.io/en/latest/configuration/using-sql-server.html)
+
+## Checklist de Jobs
+
+- [ ] Job service com interface
+- [ ] Injeção de dependência correta
+- [ ] AutomaticRetry configurado
+- [ ] Queue definida (critical/default/low)
+- [ ] Logging estruturado
+- [ ] CancellationToken propagado
+- [ ] Dashboard protegido
+- [ ] Timezone configurado para recorrentes
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/specialists/ms-agent-expert.md

@@ -0,0 +1,209 @@
+# MS Agent Expert
+
+Especialista em Microsoft Agent Framework, Semantic Kernel e integração de IA em aplicações .NET.
+
+## Responsabilidades
+
+1. **Integrar Microsoft Agent Framework** em projetos
+2. **Configurar Semantic Kernel** para orquestração
+3. **Otimizar prompts** e gerenciar tokens
+4. **Criar agentes** com plugins e functions
+
+## Triggers
+
+Keywords: `agent`, `ai`, `semantic kernel`, `llm`, `openai`, `chat`, `prompt`, `plugin`, `function calling`
+
+## Microsoft Agent Framework
+
+> Novo framework oficial da Microsoft que unifica Semantic Kernel e AutoGen.
+
+### Estrutura Básica
+
+```csharp
+// Agent com Semantic Kernel
+using Microsoft.SemanticKernel;
+using Microsoft.SemanticKernel.Agents;
+
+public class OrderAnalysisAgent
+{
+    private readonly Kernel _kernel;
+
+    public OrderAnalysisAgent(Kernel kernel)
+    {
+        _kernel = kernel;
+    }
+
+    public async Task<string> AnalyzeOrderAsync(Order order)
+    {
+        var prompt = """
+            Analise o pedido abaixo e forneça insights:
+
+            Número: {{$orderNumber}}
+            Total: {{$total}}
+            Itens: {{$itemCount}}
+            Cliente: {{$customerName}}
+
+            Forneça:
+            1. Resumo do pedido
+            2. Sugestões de upsell
+            3. Risco de cancelamento (baixo/médio/alto)
+            """;
+
+        var function = _kernel.CreateFunctionFromPrompt(prompt);
+
+        var result = await _kernel.InvokeAsync(function, new()
+        {
+            ["orderNumber"] = order.OrderNumber,
+            ["total"] = order.Total.ToString("C"),
+            ["itemCount"] = order.Items.Count,
+            ["customerName"] = order.Customer.Name
+        });
+
+        return result.GetValue<string>() ?? "";
+    }
+}
+```
+
+### Configuração do Kernel
+
+```csharp
+// Program.cs
+builder.Services.AddKernel()
+    .AddAzureOpenAIChatCompletion(
+        deploymentName: "gpt-4o-mini",
+        endpoint: builder.Configuration["AzureOpenAI:Endpoint"]!,
+        apiKey: builder.Configuration["AzureOpenAI:ApiKey"]!);
+
+// Ou OpenAI direto
+builder.Services.AddKernel()
+    .AddOpenAIChatCompletion(
+        modelId: "gpt-4o-mini",
+        apiKey: builder.Configuration["OpenAI:ApiKey"]!);
+```
+
+### Plugins e Functions
+
+```csharp
+// Plugins/OrderPlugin.cs
+public class OrderPlugin
+{
+    private readonly IOrderService _orderService;
+
+    public OrderPlugin(IOrderService orderService)
+    {
+        _orderService = orderService;
+    }
+
+    [KernelFunction("get_order")]
+    [Description("Busca um pedido pelo número")]
+    public async Task<Order?> GetOrderAsync(
+        [Description("Número do pedido")] string orderNumber)
+    {
+        return await _orderService.GetByNumberAsync(orderNumber);
+    }
+
+    [KernelFunction("calculate_discount")]
+    [Description("Calcula desconto baseado no histórico do cliente")]
+    public decimal CalculateDiscount(
+        [Description("ID do cliente")] int customerId,
+        [Description("Valor do pedido")] decimal orderTotal)
+    {
+        // Lógica de desconto
+        return orderTotal * 0.1m;
+    }
+}
+
+// Registrar plugin
+kernel.Plugins.AddFromObject(new OrderPlugin(orderService));
+```
+
+### Agent Framework (Preview)
+
+```csharp
+// Usando Microsoft.SemanticKernel.Agents
+var agent = new ChatCompletionAgent
+{
+    Name = "OrderAssistant",
+    Instructions = """
+        Você é um assistente de pedidos. Ajude os usuários a:
+        - Consultar status de pedidos
+        - Calcular descontos
+        - Sugerir produtos relacionados
+
+        Seja conciso e profissional.
+        """,
+    Kernel = kernel
+};
+
+// Conversa
+var history = new ChatHistory();
+history.AddUserMessage("Qual o status do pedido #12345?");
+
+await foreach (var message in agent.InvokeAsync(history))
+{
+    Console.WriteLine(message.Content);
+}
+```
+
+## Padrões de Prompt
+
+### System Prompt Estruturado
+
+```csharp
+var systemPrompt = """
+    # Identidade
+    Você é {AgentName}, especialista em {Domain}.
+
+    # Contexto
+    {ContextDescription}
+
+    # Regras
+    - {Rule1}
+    - {Rule2}
+
+    # Formato de Resposta
+    {ResponseFormat}
+
+    # Exemplos
+    Input: {ExampleInput}
+    Output: {ExampleOutput}
+    """;
+```
+
+### Otimização de Tokens
+
+1. **Use gpt-4o-mini** como padrão (mais barato)
+2. **Limite contexto** a informações relevantes
+3. **Cache prompts** fixos quando possível
+4. **Meça tokens** com TikToken
+
+## Modelo Padrão
+
+| Uso | Modelo | Custo |
+|-----|--------|-------|
+| Tarefas simples | gpt-4o-mini | $0.15/1M input |
+| Análise complexa | gpt-4o | $2.50/1M input |
+| Embedding | text-embedding-3-small | $0.02/1M |
+
+## Documentação de Referência
+
+- [Microsoft Agent Framework](https://learn.microsoft.com/en-us/agent-framework/overview/agent-framework-overview)
+- [Agent Framework GitHub](https://github.com/microsoft/agent-framework)
+- [Semantic Kernel](https://learn.microsoft.com/en-us/semantic-kernel/overview/)
+- [Semantic Kernel GitHub](https://github.com/microsoft/semantic-kernel)
+- [Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/)
+
+## Checklist de Integração AI
+
+- [ ] Kernel configurado com DI
+- [ ] Modelo gpt-4o-mini como padrão
+- [ ] API keys no Key Vault (não hardcoded)
+- [ ] Plugins registrados
+- [ ] System prompt estruturado
+- [ ] Error handling para rate limits
+- [ ] Logging de prompts/responses (dev only)
+- [ ] Custos estimados por operação
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*