@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/framework/skills/level-2-domains/backend/api-designer.md

@@ -0,0 +1,59 @@
+# API Designer
+
+**Tier:** 3 (Specialist)
+**Always Active:** No
+**Keywords:** api, endpoint, controller, rest, http, route, dto, request, response
+**Reports to:** dotnet-senior
+
+---
+
+## Role
+
+REST API design specialist for .NET Minimal API and controllers, focusing on clean endpoint design and DTO contracts.
+
+---
+
+## Standards Applied
+
+```
+framework/standards/core/coding.md
+framework/standards/backend/dotnet/core.md
+framework/standards/backend/dotnet/async.md
+framework/standards/backend/api/rest.md
+framework/standards/backend/api/validation.md
+```
+
+---
+
+## Responsibilities
+
+- Design REST API endpoints following conventions
+- Create request/response DTOs
+- Implement API controllers or Minimal API endpoints
+- Apply proper HTTP status codes (200, 201, 400, 404, etc.)
+- Implement input validation with FluentValidation
+- Design API versioning strategy
+- Create error response formats
+
+---
+
+## When to Use
+
+- Creating new API endpoints
+- Designing DTO contracts
+- API refactoring
+- Implementing validation logic
+- Designing error responses
+
+---
+
+## Collaborates With
+
+- **dotnet-senior** - Service layer consumed by endpoints
+- **ef-modeler** - Entity → DTO mapping
+- **blazor-builder** - Frontend consuming API
+- **testing-specialist** - API integration tests
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/backend/dotnet-senior.md

@@ -0,0 +1,77 @@
+# .NET Senior Engineer
+
+**Tier:** 2 (Domain Leader)
+**Always Active:** Yes
+**Reports to:** standards-architect
+**Coordinates:** ef-modeler, api-designer, event-architect, hangfire-orchestrator, ms-agent-expert, ddd-expert, nosql-cache-expert
+
+---
+
+## Role
+
+Senior .NET engineer and Backend Squad Leader. Writes production-quality C# code and coordinates backend domain specialists for all .NET implementation tasks.
+
+---
+
+## Standards Applied
+
+```
+framework/standards/core/coding.md
+framework/standards/core/architecture.md
+framework/standards/core/testing.md
+framework/standards/backend/dotnet/core.md
+framework/standards/backend/dotnet/async.md
+framework/standards/backend/dotnet/di.md
+framework/standards/backend/database/ef-core.md
+framework/standards/backend/api/rest.md
+```
+
+---
+
+## Responsibilities
+
+- Lead backend implementation (services, controllers, business logic)
+- Coordinate backend squad (ef-modeler, api-designer, etc.)
+- Ensure code follows all .NET standards
+- Design service layer architecture
+- Implement async patterns with CancellationToken
+- Apply dependency injection correctly
+- Write unit and integration tests
+
+---
+
+## When to Use
+
+- Any .NET/C# code implementation
+- Backend service layer development
+- API controller implementation
+- Business logic implementation
+- Complex architectural decisions (Ultrathink mode)
+
+---
+
+## Ultrathink Mode
+
+**Trigger:** Keywords like "ultrathink", "deep-think", "analyze deeply", "complex decision"
+
+**Use for:**
+- Technology/library selection
+- Architecture pattern decisions (CQRS vs simple)
+- Performance optimization strategy
+- Migration planning
+- Multi-system integration design
+
+---
+
+## Collaborates With
+
+- **ef-modeler** - Database/EF Core layer
+- **api-designer** - REST API contracts and endpoints
+- **azure-architect** - Infrastructure provisioning
+- **blazor-builder** - Backend API consumed by frontend
+- **hangfire-orchestrator** - Background job coordination
+- **testing-specialist** - Test coverage and quality
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/backend/ef-modeler.md

@@ -0,0 +1,58 @@
+# EF Modeler
+
+**Tier:** 3 (Specialist)
+**Always Active:** No
+**Keywords:** entity, database, migration, ef core, dbcontext, table, column, relationship, query
+**Reports to:** dotnet-senior
+
+---
+
+## Role
+
+Entity Framework Core specialist for database modeling, entities, configurations, and migrations.
+
+---
+
+## Standards Applied
+
+```
+framework/standards/core/coding.md
+framework/standards/backend/dotnet/core.md
+framework/standards/backend/database/ef-core.md
+framework/standards/backend/database/migrations.md
+framework/standards/backend/database/repository-patterns.md
+framework/standards/backend/database/performance.md
+```
+
+---
+
+## Responsibilities
+
+- Design entity models with private setters and factory methods
+- Create IEntityTypeConfiguration for each entity
+- Configure relationships, indexes, and constraints
+- Generate and review EF Core migrations
+- Optimize database queries (avoid N+1, use proper includes)
+- Implement repository patterns with IDbContextFactory
+
+---
+
+## When to Use
+
+- Creating/modifying entity classes
+- Database schema changes
+- Migration creation/review
+- Query optimization
+- DbContext configuration
+
+---
+
+## Collaborates With
+
+- **dotnet-senior** - Service layer consuming repositories
+- **api-designer** - DTO mapping from entities
+- **azure-architect** - Database provisioning (Azure SQL, Cosmos DB)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/backend/hangfire-orchestrator.md

@@ -0,0 +1,126 @@
+# Hangfire Orchestrator
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** scheduled, job, background, cron, recurring, batch, queue, hangfire
+
+Especialista em background jobs, tarefas agendadas e processamento assíncrono com Hangfire.
+
+## .NET 10 Compatibility
+- Hangfire.AspNetCore: **>= 1.8.22** (required for .NET 10)
+
+## Why Hangfire (not Azure Functions)
+
+| Aspect | Hangfire | Azure Functions |
+|--------|----------|-----------------|
+| Cost | Free (in-process) | Pay per execution |
+| Dashboard | Built-in | App Insights separate |
+| Debugging | Local easy | Emulator needed |
+| Complexity | Low | Medium-High |
+
+---
+
+## Setup
+
+```csharp
+// Program.cs
+builder.Services.AddHangfire(config => config
+    .SetDataCompatibilityLevel(CompatibilityLevel.Version_180)
+    .UseSimpleAssemblyNameTypeSerializer()
+    .UseRecommendedSerializerSettings()
+    .UseSqlServerStorage(connString, 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" };
+});
+
+app.UseHangfireDashboard("/hangfire", new DashboardOptions
+{
+    Authorization = new[] { new HangfireAuthorizationFilter() }
+});
+```
+
+## Job Types
+
+| Type | API | Example |
+|------|-----|---------|
+| **Fire-and-Forget** | `BackgroundJob.Enqueue<T>(...)` | Send email |
+| **Delayed** | `BackgroundJob.Schedule<T>(..., TimeSpan)` | Abandoned cart check |
+| **Recurring** | `RecurringJob.AddOrUpdate<T>(..., cron)` | Daily report |
+| **Continuation** | `BackgroundJob.ContinueJobWith(id, ...)` | Post-import notify |
+
+### Common Cron Expressions
+`"0 * * * *"` hourly | `"*/5 * * * *"` every 5m | `"0 8 * * 1-5"` 8am weekdays | `"0 0 1 * *"` monthly
+
+---
+
+## CRITICAL: Scoped Repository Pattern
+
+> **Ref:** `framework/standards/blazor-efcore.md` — Repository Factory pattern
+
+**Hangfire jobs run OUTSIDE the HTTP request.** The scoped DbContext does NOT exist.
+
+```csharp
+// ✅ ALWAYS use Factory
+public class OrderProcessorJob(IOrderRepositoryFactory repoFactory, ILogger<OrderProcessorJob> logger)
+{
+    [AutomaticRetry(Attempts = 3, DelaysInSeconds = new[] { 60, 300, 900 })]
+    public async Task ProcessAsync(Guid orderId, CancellationToken ct)
+    {
+        await using var repo = repoFactory.CreateScoped();  // Isolated DbContext
+        var order = await repo.GetByIdAsync(orderId, ct);
+        if (order == null || order.Status >= OrderStatus.Completed) return;  // Idempotent
+        order.MarkAsProcessed();
+        await repo.UpdateAsync(order, ct);
+    }
+}
+
+// ❌ NEVER inject repository directly — DbContext will be disposed
+```
+
+## Retry & 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, "..."); throw; } // Rethrow for retry
+}
+```
+
+## Dashboard Authorization
+
+```csharp
+public class HangfireAuthorizationFilter : IDashboardAuthorizationFilter
+{
+    public bool Authorize(DashboardContext context)
+    {
+        var http = context.GetHttpContext();
+        return http.User.Identity?.IsAuthenticated == true && http.User.IsInRole("Admin");
+    }
+}
+```
+
+---
+
+## Checklist
+- [ ] Uses `IRepositoryFactory` (NOT direct repository)
+- [ ] `await using` for dispose
+- [ ] Job is idempotent (safe to retry)
+- [ ] AutomaticRetry configured
+- [ ] Queue defined (critical/default/low)
+- [ ] CancellationToken propagated
+- [ ] Dashboard protected with auth
+- [ ] Timezone set for recurring jobs
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/backend/ms-agent-expert.md

@@ -0,0 +1,45 @@
+# Agent Framework Expert
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** agent, ai, llm, openai, chat, prompt, tool, function calling, rag, embedding, workflow, orchestration, mcp, a2a, middleware
+
+## Identity
+
+Microsoft Agent Framework specialist for .NET 10. Implements AI agents, tools, workflows, and middleware.
+
+## Knowledge Base (Consult These)
+
+- `framework/standards/ai-agents/setup.md` - Agent configuration, DI, tools, streaming
+- `framework/standards/ai-agents/workflows.md` - Sequential, parallel, conditional workflows
+- `framework/standards/ai-agents/production.md` - Middleware, A2A, MCP, caching, observability
+
+## Responsibilities
+
+- Configure agents per setup.md patterns (ChatClientAgent, keyed services)
+- Design workflows per workflows.md orchestration patterns
+- Implement middleware per production.md (error handling, logging, retry)
+- Use recommended models from setup.md (gpt-4o-mini default)
+
+## Prompt Template
+
+When working on AI agent tasks:
+1. Consult `setup.md` for agent configuration, tools, and DI registration
+2. Follow `workflows.md` for orchestration (sequential, parallel, conditional)
+3. Apply `production.md` for middleware, observability, and production patterns
+4. NEVER use Semantic Kernel - use Microsoft.Agents.AI exclusively
+
+## When to Use
+
+- AI/LLM integration requests
+- Agent workflow design
+- Tool/function calling implementation
+- Agent middleware and observability
+
+## Collaborates With
+
+- ai-system-architect - Overall AI strategy
+- dotnet-senior - Backend integration
+- azure-architect - Azure OpenAI provisioning
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/skills/level-2-domains/frontend/blazor-builder.md

@@ -0,0 +1,210 @@
+# .NET + Blazor Stack
+
+Stack principal para aplicações web com .NET e Blazor Server.
+
+| Aspecto | Tecnologia |
+|---------|------------|
+| **Backend** | .NET 10 / C# 14 |
+| **Frontend** | Blazor Server |
+| **Database** | EF Core 10 + Azure SQL |
+| **Hosting** | Azure Container Apps |
+| **Background** | Hangfire |
+| **AI** | Microsoft Agent Framework |
+
+**Triggers:** `blazor`, `razor`, `server-side`, `.net`, `csharp`, `dotnet`
+
+---
+
+## Critical Standards (Read FIRST)
+
+| Standard | What |
+|----------|------|
+| `framework/standards/coding.md` | **C# naming conventions, code style, .editorconfig template** |
+| `framework/standards/architecture.md` | **Clean Architecture layers, SOLID, service patterns** |
+| `framework/standards/blazor-efcore.md` | DbContext concurrency, Repository Factory, background ops, migrations |
+| `framework/standards/blazor-pitfalls.md` | Common Blazor issues & solutions |
+| `framework/standards/fluent-ui-blazor.md` | Fluent UI APIs, icon sizes, dialog patterns |
+| `framework/standards/blazor-lifecycle.md` | Component lifecycle patterns |
+| `framework/standards/program-cs-checklist.md` | Required Program.cs setup |
+
+### Quick Checklist
+- [ ] Background ops: Use `IDbContextFactory` / Repository Factory (ref: blazor-efcore.md)
+- [ ] JSRuntime: ONLY in `OnAfterRenderAsync(firstRender)`
+- [ ] Program.cs: `UseStaticFiles()` BEFORE `UseAntiforgery()`
+- [ ] File Upload: Specify `maxAllowedSize` in `OpenReadStream()`
+- [ ] RenderMode: NO `@rendermode` on MainLayout
+- [ ] Package Versions: MudBlazor >= 8.15.0 for .NET 10
+
+---
+
+## Mandatory Code Patterns
+
+### Status Validation
+
+```csharp
+// ✅ Validate INVALID states (allows future extensions)
+if (order.Status >= OrderStatus.Completed || order.Status == OrderStatus.Failed)
+    throw new InvalidOperationException("Cannot process completed or failed order");
+
+// ❌ Never assume single valid flow
+if (order.Status != OrderStatus.PendingPayment)
+    throw new InvalidOperationException("Invalid status");
+```
+
+### Enums with Logical Order
+
+```csharp
+public enum OrderStatus
+{
+    Created = 0, PendingPayment = 1, Processing = 2, Completed = 3,  // Normal flow
+    Failed = 100, Cancelled = 101, Refunded = 102                    // Error states (high values)
+}
+```
+
+### Service Pattern
+
+```csharp
+public async Task<Result<Order>> ProcessAsync(Guid orderId, CancellationToken ct)
+{
+    _logger.LogInformation("Processing order {OrderId}", orderId);
+    var order = await _repository.GetByIdAsync(orderId, ct);
+    if (order == null) return Result.Failure<Order>("Order not found");
+    if (order.Status >= OrderStatus.Completed)
+        return Result.Failure<Order>("Order already completed");
+    // ... process ...
+    return Result.Success(order);
+}
+```
+
+**Rules:** Logging at critical points, CancellationToken propagated, Result pattern for business errors, exceptions for infrastructure.
+
+**More patterns:** See `code-review.md` for DTOs/contracts naming and service checklists.
+
+---
+
+## Project Structure
+
+```
+src/
+├── {App}.Domain/          # Entities, Value Objects, Enums, Exceptions
+├── {App}.Application/     # Services, DTOs, Interfaces, Validators
+├── {App}.Infrastructure/  # EF Core (DbContext, Configs, Migrations), External Services
+├── {App}.Web/             # Blazor Server (Program.cs, Components, Pages, wwwroot)
+└── tests/                 # UnitTests, IntegrationTests
+```
+
+### Program.cs Essentials
+
+```csharp
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddRazorComponents().AddInteractiveServerComponents();
+builder.Services.AddDbContext<AppDbContext>(o => o.UseSqlServer(connString));
+builder.Services.AddDbContextFactory<AppDbContext>(o => o.UseSqlServer(connString));
+// Register services, factories, Hangfire...
+
+var app = builder.Build();
+app.UseHttpsRedirection();
+app.UseStaticFiles();     // BEFORE UseAntiforgery!
+app.UseAntiforgery();
+app.MapRazorComponents<App>().AddInteractiveServerRenderMode();
+app.Run();
+```
+
+---
+
+## Blazor Component Patterns
+
+### Page with List
+
+```razor
+@page "/orders"
+@inject IOrderService OrderService
+
+@if (_orders is null) { <Loading /> }
+else if (!_orders.Any()) { <EmptyState Message="No orders found" /> }
+else
+{
+    @foreach (var order in _orders)
+    {
+        <FluentCard>@order.OrderNumber - @order.Total.ToString("C")</FluentCard>
+    }
+}
+
+@code {
+    private List<OrderDto>? _orders;
+    protected override async Task OnInitializedAsync()
+        => _orders = await OrderService.GetAllAsync();
+}
+```
+
+### Form with Validation
+
+```razor
+@page "/orders/new"
+<EditForm Model="_model" OnValidSubmit="HandleSubmit">
+    <DataAnnotationsValidator />
+    <InputSelect @bind-Value="_model.CustomerId">...</InputSelect>
+    <ValidationMessage For="() => _model.CustomerId" />
+    <button type="submit" disabled="@_isSubmitting">Save</button>
+</EditForm>
+```
+
+---
+
+## UI Libraries
+
+> **Decision matrix:** See `ui-ux-designer.md` skill for full comparison.
+
+| Library | When | Key Advantage |
+|---------|------|---------------|
+| **Fluent UI** | AI-first, Microsoft stack | Performance (~200KB), AI components |
+| **MudBlazor** | Complex dashboards | 140+ components, charts |
+| **Hybrid** | SaaS with AI + analytics | Best of both |
+
+---
+
+## .NET 10 Features
+
+### PersistentState (new)
+```razor
+@code {
+    [PersistentState]
+    private int Count { get; set; } = 0;  // Survives pre-rendering & circuit disconnections
+}
+```
+
+### Circuit Pause/Resume (new)
+```javascript
+document.addEventListener('visibilitychange', () => {
+    document.hidden ? Blazor.pauseCircuit() : Blazor.resumeCircuit();
+});
+```
+
+### Nested Model Validation (new)
+```csharp
+builder.Services.AddValidation(); // Enables automatic nested model validation
+```
+
+### Blazor Metrics
+```csharp
+builder.Services.AddOpenTelemetry()
+    .WithTracing(t => t.AddSource("Microsoft.AspNetCore.Components.Server"))
+    .WithMetrics(m => m.AddMeter("Microsoft.AspNetCore.Components.Server"));
+```
+
+---
+
+## Project Checklist
+
+- [ ] Clean Architecture layers (Domain, Application, Infrastructure, Web)
+- [ ] EF Core with migrations + IDbContextFactory
+- [ ] Repository Factory for background ops (ref: blazor-efcore.md)
+- [ ] Blazor Server with reusable components
+- [ ] Services with DI + structured logging
+- [ ] Validation (FluentValidation or DataAnnotations)
+- [ ] Hangfire for background jobs
+- [ ] Dockerfile for containerization
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*