@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

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

@@ -0,0 +1,109 @@
+# 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
+
+Microsoft Agent Framework for .NET 10. **Replaces Semantic Kernel.** Packages: `Microsoft.Agents.AI`, `Microsoft.Agents.AI.OpenAI`, `Microsoft.Agents.AI.Hosting`.
+
+> **Ref:** `agent-framework-setup.md` — Full setup guide
+> **Ref:** `agent-framework-workflows.md` — Orchestration patterns
+> **Ref:** `agent-framework-production.md` — Middleware, A2A, MCP, caching
+
+## Quick Start
+
+```csharp
+AIAgent agent = new AzureOpenAIClient(
+    new Uri(endpoint), new AzureCliCredential())
+  .GetChatClient("gpt-4o-mini")
+  .AsAIAgent(instructions: "You are a helpful assistant.");
+
+Console.WriteLine(await agent.RunAsync("Analyze this."));
+```
+
+## Agent with Tools
+
+```csharp
+public class OrderFunctions
+{
+    private readonly IOrderService _orderService;
+
+    public OrderFunctions(IOrderService orderService) => _orderService = orderService;
+
+    [Description("Get order by number")]
+    public async Task<Order?> GetOrderAsync(
+        [Description("Order number")] string orderNumber, CancellationToken ct = default)
+        => await _orderService.GetByNumberAsync(orderNumber, ct);
+
+    [Description("Calculate customer discount")]
+    public decimal CalculateDiscount(
+        [Description("Customer ID")] int customerId,
+        [Description("Order total")] decimal orderTotal) => orderTotal * 0.1m;
+}
+
+// Register agent with tools via DI
+builder.AddAIAgent("OrderAgent", (sp, key) =>
+{
+    var chatClient = sp.GetRequiredService<IChatClient>();
+    var orderFunctions = sp.GetRequiredService<OrderFunctions>();
+
+    return new ChatClientAgent(chatClient, name: key,
+        instructions: "You are an order assistant. Use tools to help users.",
+        tools: [
+            AIFunctionFactory.Create(orderFunctions.GetOrderAsync),
+            AIFunctionFactory.Create(orderFunctions.CalculateDiscount)]);
+});
+```
+
+## Workflow (Sequential)
+
+```csharp
+Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
+AIAgent workflowAgent = await workflow.AsAgentAsync();
+var response = await workflowAgent.RunAsync("Write a report.");
+```
+
+## Middleware (Error Handling)
+
+```csharp
+var agent = originalAgent.AsBuilder()
+    .Use(async (agent, context, next, ct) =>
+    {
+        try { return await next(context, ct); }
+        catch (Exception ex) { return $"Error: {ex.Message}"; }
+    })
+    .Build();
+```
+
+## Prompt Template
+
+```
+# Identity: You are {AgentName}, expert in {Domain}.
+# Context: {ContextDescription}
+# Rules: {BulletList}
+# Response Format: {Format}
+# Examples: Input: {In} → Output: {Out}
+```
+
+## Model Selection
+
+| Use Case | Model | Cost |
+|----------|-------|------|
+| Simple tasks (default) | gpt-4o-mini | $0.15/1M input |
+| Complex analysis | gpt-4o | $2.50/1M input |
+| Embeddings | text-embedding-3-small | $0.02/1M |
+
+## Checklist
+
+- [ ] `Microsoft.Agents.AI` + `Microsoft.Agents.AI.OpenAI` installed
+- [ ] `IChatClient` configured via DI (singleton)
+- [ ] Agents use `ChatClientAgent` or `.AsAIAgent()`
+- [ ] Agents registered with `builder.AddAIAgent()` (keyed services)
+- [ ] Tools use `AIFunctionFactory.Create()` + `[Description]`
+- [ ] Middleware for error handling and logging
+- [ ] gpt-4o-mini as default model
+- [ ] API keys in Key Vault
+- [ ] OpenTelemetry enabled: `agent.WithOpenTelemetry()`
+- [ ] **Do NOT use Semantic Kernel** (`Kernel`, `KernelFunction`, `InvokePromptAsync`)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/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*

package/content/.claude/skills/level-2-domains/frontend/nextjs-expert.md

@@ -0,0 +1,154 @@
+# .NET + Next.js Stack
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** nextjs, next.js, react, api, frontend, spa, typescript
+
+| Aspect | Technology |
+|--------|------------|
+| **Backend** | .NET 10 Web API / C# 14 |
+| **Frontend** | Next.js 15+ / React 19 |
+| **Database** | EF Core 10 + Azure SQL |
+| **API** | REST + OpenAPI |
+| **Hosting** | Azure Container Apps |
+
+## Project Structure
+
+```
+/
+├── backend/
+│   ├── src/{Api,Application,Domain,Infrastructure}/
+│   ├── tests/
+│   └── Backend.sln
+├── frontend/
+│   ├── src/{app,components,lib,hooks}/
+│   ├── package.json
+│   └── next.config.js
+├── docker-compose.yml
+└── infra/main.bicep
+```
+
+---
+
+## Backend (.NET Minimal API)
+
+```csharp
+// Program.cs
+var builder = WebApplication.CreateBuilder(args);
+builder.Services.AddEndpointsApiExplorer();
+builder.Services.AddSwaggerGen();
+builder.Services.AddCors(o => o.AddPolicy("Frontend", p =>
+    p.WithOrigins(builder.Configuration["Frontend:Url"]!)
+     .AllowAnyHeader().AllowAnyMethod().AllowCredentials()));
+builder.Services.AddDbContext<AppDbContext>(o => o.UseSqlServer(connString));
+
+var app = builder.Build();
+if (app.Environment.IsDevelopment()) { app.UseSwagger(); app.UseSwaggerUI(); }
+app.UseCors("Frontend");
+app.UseAuthentication();
+app.UseAuthorization();
+app.MapOrderEndpoints();
+app.Run();
+```
+
+### Minimal API Endpoints
+
+```csharp
+public static class OrderEndpoints
+{
+    public static void MapOrderEndpoints(this WebApplication app)
+    {
+        var group = app.MapGroup("/api/orders").WithTags("Orders").RequireAuthorization();
+        group.MapGet("/", GetAll);
+        group.MapGet("/{id:int}", GetById);
+        group.MapPost("/", Create);
+        group.MapPut("/{id:int}", Update);
+        group.MapDelete("/{id:int}", Delete);
+    }
+    // Each handler: inject IService + params → return Results.Ok/NotFound/Created/NoContent
+}
+```
+
+---
+
+## Frontend (Next.js)
+
+### API Client
+
+```typescript
+const API_URL = process.env.NEXT_PUBLIC_API_URL!;
+
+async function fetchApi<T>(endpoint: string, options?: RequestInit): Promise<T> {
+  const res = await fetch(`${API_URL}${endpoint}`, {
+    ...options,
+    headers: { 'Content-Type': 'application/json', ...options?.headers },
+    credentials: 'include',
+  });
+  if (!res.ok) throw new Error(`API error: ${res.status}`);
+  return res.json();
+}
+
+export const api = {
+  orders: {
+    getAll: (params?) => fetchApi<PaginatedResult<Order>>(`/api/orders?${new URLSearchParams(params)}`),
+    getById: (id: number) => fetchApi<Order>(`/api/orders/${id}`),
+    create: (data) => fetchApi<Order>('/api/orders', { method: 'POST', body: JSON.stringify(data) }),
+  },
+};
+```
+
+### Types (generated from OpenAPI)
+
+```typescript
+export interface Order { id: number; orderNumber: string; total: number; status: OrderStatus; }
+export type OrderStatus = 'Pending' | 'Processing' | 'Completed' | 'Cancelled';
+export interface PaginatedResult<T> { items: T[]; totalCount: number; page: number; totalPages: number; }
+```
+
+### Server Component (App Router)
+```tsx
+export default async function OrdersPage() {
+  const orders = await api.orders.getAll();
+  return <OrderList initialOrders={orders} />;
+}
+```
+
+### Client Component
+```tsx
+'use client';
+// Use useState + api calls for client-side pagination/interaction
+```
+
+---
+
+## Docker Compose
+
+```yaml
+services:
+  backend:
+    build: { context: ./backend }
+    ports: ["5000:8080"]
+    environment:
+      - ConnectionStrings__Default=Server=db;Database=App;User=sa;Password=Pass!;TrustServerCertificate=true
+      - Frontend__Url=http://localhost:3000
+  frontend:
+    build: { context: ./frontend }
+    ports: ["3000:3000"]
+    environment: [NEXT_PUBLIC_API_URL=http://localhost:5000]
+  db:
+    image: mcr.microsoft.com/mssql/server:2022-latest
+    environment: [ACCEPT_EULA=Y, SA_PASSWORD=YourStrong!Passw0rd]
+    ports: ["1433:1433"]
+```
+
+## Checklist
+- [ ] Backend with Minimal APIs
+- [ ] OpenAPI/Swagger configured
+- [ ] CORS configured for frontend
+- [ ] Frontend with App Router (Next.js 15+)
+- [ ] API client typed
+- [ ] Types generated from OpenAPI
+- [ ] Docker Compose for dev
+- [ ] Environment variables configured
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/level-2-domains/frontend/ui-ux-designer.md

@@ -0,0 +1,191 @@
+# UI/UX Designer
+
+Especialista em design de interfaces, UX e componentes Blazor. Domina **Fluent UI Blazor** e **MudBlazor**.
+
+> **FASE 1.5: UI/UX DESIGN** - Obrigatória para features com front-end.
+> Gera wireframes, specs de componentes e fluxos ANTES do design técnico.
+> **Ref:** `framework/standards/fluent-ui-blazor.md` para API details e armadilhas.
+
+## Triggers
+
+Keywords: `blazor`, `component`, `page`, `ui`, `ux`, `design`, `layout`, `wizard`, `dashboard`, `form`, `chart`, `table`, `dialog`, `modal`, `tela`, `interface`, `formulário`
+
+---
+
+## Design Moderno (2025+)
+
+### Visual Trends
+- **Glassmorphism**: `backdrop-filter: blur(10px)`, semi-transparent backgrounds
+- **Gradients**: Purple (#667eea → #764ba2), Blue-Purple (#4facfe → #00f2fe)
+- **Soft Shadows**: `box-shadow: 0 4px 6px rgba(0,0,0,0.1)`
+- **Rounded Corners**: `border-radius: 12px-16px`
+- **Micro-interactions**: Hover effects, transitions (transform, scale, opacity)
+
+### Component Patterns
+- Cards with elevation + hover lift
+- Skeleton loaders (not just spinners)
+- Toast notifications (bottom-right, auto-dismiss)
+- Empty states with illustration + CTA
+- Dark mode support (always design for both)
+
+### Layout Principles
+- Whitespace: 32px-48px container padding
+- Grid: 12-column, gap 24px-32px
+- Typography: xs:12, sm:14, base:16, lg:18, xl:20, 2xl:24
+- Contrast: WCAG AA (4.5:1 text, 3:1 UI)
+
+### Design References
+Linear (linear.app), Vercel (vercel.com), Stripe (stripe.com), Dribbble dashboards
+
+---
+
+## FASE 1.5 Workflow
+
+### Step 1: Collect User Input (ALWAYS ask first)
+
+1. Layout ideas or reference sites?
+2. Visual references (screenshots, mockups)?
+3. User flow expectations?
+4. Design system defined (colors, fonts, spacing)?
+5. Image examples to analyze?
+
+If user provides screenshots → Read tool → extract patterns (layout, components, colors).
+If HTML prototype exists → extract patterns automatically, skip wireframes, map HTML → Blazor.
+
+### Step 2: Generate Deliverables
+
+| File | Content |
+|------|---------|
+| `ui-design-system.md` | Colors, typography, spacing |
+| `ui-mockups.md` | ASCII wireframes + descriptions per screen |
+| `ui-components.md` | Component specs (library-agnostic first, library choice in FASE 2) |
+| `ui-flows.md` | User flow diagrams + edge cases |
+
+**Important:** Generate specs AGNOSTIC of UI library. Use generic names ("primary button", "card", "table"). Library choice happens in FASE 2: DESIGN.
+
+### Step 3: Present for Approval
+
+Show deliverable summary → **⛔ PAUSE** with 3 options (approve / adjust wireframes / add flows).
+
+---
+
+## Fluent UI vs MudBlazor Decision Matrix
+
+| Criterion | Fluent UI Blazor | MudBlazor |
+|-----------|------------------|-----------|
+| AI-first projects | Ideal (native components) | Requires customization |
+| Performance | ~200KB | ~500KB |
+| Microsoft Stack | Perfect integration | Works well |
+| Complex components | Limited | Very complete |
+| Community | Smaller (newer) | Larger |
+| Maturity | v4.0 (recent) | v6.x (stable) |
+
+**Use Fluent UI if:** AI-first, Microsoft stack, modern M365 design, performance critical.
+**Use MudBlazor if:** Complex dashboards, Material Design, need TreeView/advanced DataGrid, larger community.
+**Hybrid:** Fluent UI (base) + MudBlazor (specific complex components).
+
+---
+
+## Fluent UI Quick Reference
+
+> **Full details:** `framework/standards/fluent-ui-blazor.md`
+
+### Common Pitfalls
+
+| Issue | Wrong | Correct |
+|-------|-------|---------|
+| Icon sizes | `Size16`, `Size14` | `Size20`, `Size24`, `Size28`, `Size32`, `Size48` |
+| Icon namespace | `@using ...Icons` | `@using Icons = Microsoft.FluentUI.AspNetCore.Components.Icons` |
+| Toast methods | `await ShowSuccessAsync()` | `ToastService.ShowSuccess()` (sync!) |
+| Dialog show | `await _dialog.ShowAsync()` | `_dialog.Show()` (sync!) |
+| Dialog close | `_dialog.Hide()` | `await _dialog.CloseAsync()` (async!) |
+| Dialog init | `<FluentDialog>` | `<FluentDialog Hidden="true">` (must hide initially!) |
+
+### Key Components
+
+| Component | Use Case |
+|-----------|----------|
+| `FluentCard` + `FluentStack` | Containers, dashboards |
+| `FluentDataGrid` | Data tables with sorting |
+| `FluentWizard` | Multi-step flows |
+| `FluentDialog` | Modals, confirmations |
+| `FluentMessageBar` | Chat, notifications |
+| `FluentProgress` | Loading, streaming |
+| `FluentTextField` | Text inputs |
+| `FluentToast` | System feedback |
+
+---
+
+## MudBlazor Key Components
+
+| Component | Advantage over Fluent |
+|-----------|----------------------|
+| `MudDataGrid` | Grouping, advanced filtering |
+| `MudTreeView` | More complete hierarchies |
+| `MudChart` | Native charts (Fluent has none) |
+| `MudFileUpload` | More upload features |
+| `MudAutocomplete` | Better performance |
+
+---
+
+## Design System Defaults
+
+```css
+/* Colors */
+--primary: #3b82f6; --secondary: #6b7280;
+--success: #10b981; --warning: #f59e0b;
+--danger: #ef4444;  --info: #06b6d4;
+
+/* Spacing (4px system) */
+--space-1: 0.25rem; --space-2: 0.5rem; --space-4: 1rem;
+--space-6: 1.5rem;  --space-8: 2rem;
+```
+
+---
+
+## Generating Deliverables
+
+### ui-mockups.md Structure
+
+Per screen: ASCII wireframe + description (purpose, components, interactions, states) + responsiveness (desktop/mobile).
+
+### ui-components.md Structure
+
+Per component: Library, component name, main props, events, states (default/loading/error/empty), accessibility (ARIA, keyboard).
+
+### ui-flows.md Structure
+
+Per flow: Trigger, steps, happy path, edge cases, ASCII flowchart diagram.
+
+---
+
+## Accessibility (A11y)
+
+- Contrast: 4.5:1 text minimum (WCAG AA)
+- Focus visible: Outline on focusable elements
+- Labels: Every input with associated label
+- ARIA: Roles and labels where needed
+- Keyboard nav: Logical tab order
+
+---
+
+## Checklist
+
+### FASE 1.5 Deliverables
+- [ ] `ui-mockups.md`: Wireframes for ALL screens + states (loading, error, empty) + responsiveness
+- [ ] `ui-components.md`: Library justified + all components mapped with props/events/states
+- [ ] `ui-flows.md`: Happy paths + edge cases + ASCII diagrams
+- [ ] `decisions.md`: Updated with UI library ADR
+
+### UI Quality
+- [ ] Visual hierarchy clear
+- [ ] Consistent spacing (4px multiples)
+- [ ] Responsive (mobile-first)
+- [ ] States: hover, focus, disabled, error
+- [ ] Loading states (skeleton/spinner)
+- [ ] Empty states with CTA
+- [ ] WCAG AA accessibility
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*