@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

package/framework/{skills/level-2-domains → agents}/README.md

@@ -1,14 +1,14 @@
-# Level 2: Domains
-
-Domain expertise skills organized by squad.
-
-**Purpose:** Skills that provide deep domain knowledge (backend, frontend, infra, quality, ai-agents, integrations).
-
-**Squads:**
-- backend/ - Backend Squad (led by dotnet-senior)
-- frontend/ - Frontend Squad (led by ui-designer)
-- infrastructure/ - Infrastructure Squad (led by azure-architect)
-- quality/ - Quality Squad (coordinated by standards-architect)
-- ai-agents/ - AI/Agent specialists
-- integrations/ - External integration specialists
-- architecture/ - Architecture and planning
+# Level 2: Domains
+
+Domain expertise skills organized by squad.
+
+**Purpose:** Skills that provide deep domain knowledge (backend, frontend, infra, quality, ai-agents, integrations).
+
+**Squads:**
+- backend/ - Backend Squad (led by dotnet-senior)
+- frontend/ - Frontend Squad (led by ui-designer)
+- infrastructure/ - Infrastructure Squad (led by infra-architect)
+- quality/ - Quality Squad (coordinated by standards-architect)
+- ai-agents/ - AI/Agent specialists
+- integrations/ - External integration specialists
+- architecture/ - Architecture and planning

package/framework/{skills/level-2-domains → agents}/ai-agents/ai-system-architect.md

@@ -1,7 +1,6 @@
 ---
 name: ai-system-architect
-description: >
-  AI System Architect specialist for agent systems, LLM orchestration, and AI pipeline design. Activates for keywords: semantic kernel, microsoft agents, ai pipeline, llm, embeddings.
+description: AI System Architect specialist for designing multi-agent systems, LLM orchestration, RAG pipelines, and Semantic Kernel patterns. Use when designing AI agent architectures, implementing LLM-powered features, building RAG pipelines, or integrating Microsoft Agent Framework.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
@@ -9,8 +8,6 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 
 Expert in agentic system architecture, multi-agent orchestration, and RAG pipelines.
 
-> **Layer:** 2 | **Load:** on-keyword | **Keywords:** orchestration, multi-agent, rag, vector search, embedding, agentic, memory, reasoning
-
 > **Ref:** `framework/standards/ai-agents/workflows.md` — Workflow patterns with AgentWorkflowBuilder
 > **Ref:** `framework/standards/ai-agents/production.md` — Middleware, A2A, MCP, caching
 > **Ref:** `framework/standards/backend/database/vector-search-rag.md` — Vector Search + RAG with EF Core 10

package/framework/{skills/level-2-domains → agents}/architecture/po-pm-advisor.md

@@ -1,7 +1,6 @@
 ---
 name: po-pm-advisor
-description: >
-  PO/PM Advisor specialist for product requirements, roadmaps, and user stories. Activates for keywords: product, roadmap, requirements, user stories, acceptance criteria.
+description: PO/PM Advisor specialist for clarifying product requirements, defining acceptance criteria, writing user stories, and evaluating feature ROI. Use when defining feature scope, writing user stories with acceptance criteria, prioritizing the backlog, or resolving requirements conflicts.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 

package/framework/{skills/level-2-domains → agents}/architecture/prompt-engineer.md

@@ -1,7 +1,6 @@
 ---
 name: prompt-engineer
-description: >
-  Prompt Engineer specialist for designing system prompts, few-shot examples, and LLM interaction patterns. Activates for keywords: prompts, system prompts, llm, few-shot, chain-of-thought.
+description: Prompt Engineer specialist for designing system prompts, few-shot examples, chain-of-thought patterns, and LLM interaction optimization. Use when building AI features, writing or improving system prompts, designing LLM agent instructions, or optimizing prompt performance.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 

package/framework/{skills/level-2-domains → agents}/architecture/seo-growth-hacker.md

@@ -1,7 +1,6 @@
 ---
 name: seo-growth-hacker
-description: >
-  SEO and Growth specialist for performance optimization, analytics, and search engine ranking. Activates for keywords: seo, performance, analytics, lighthouse, core web vitals.
+description: SEO and Growth specialist for technical SEO, Core Web Vitals optimization, content strategy, and organic growth for SaaS and landing pages. Use when optimizing for search engine ranking, improving Lighthouse scores, implementing SEO for Next.js/Blazor pages, or planning content-driven growth.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 

package/framework/{skills/level-2-domains → agents}/architecture/standards-architect.md

@@ -1,163 +1,160 @@
----
-name: standards-architect
-description: >
-  Standards Architect (Tier 1 Orchestrator). Always active. Enforces naming conventions, coding standards, cross-cutting concerns, and reviews all outputs for compliance.
-allowed-tools: Read, Write, Edit, Bash, Glob, Grep
----
-
-# Standards Architect
-
-> **Layer:** 0 | **Load:** always | **Scope:** All .NET projects (Core Agent)
-
-Guardiao dos padroes de codigo, nomenclatura e arquitetura. Valida aderencia aos standards antes de aprovar merges.
-
-> **Ref:** `framework/standards/core/coding.md` for complete C# naming conventions and .editorconfig template.
-> **Ref:** `framework/standards/core/architecture.md` for Clean Architecture layers, SOLID, service patterns.
-
-## Responsabilidades
-
-1. **Garantir aderencia aos padroes** definidos em `framework/standards/` e `.morph/context/`
-2. **Validar nomenclatura** contra `coding.md` (PascalCase, _camelCase, etc.)
-3. **Revisar codigo** antes de aprovar merges
-4. **Definir convencoes** de projeto
-5. **Orquestrar validacao:** Standards Architect (naming) -> Code Analyzer (architecture) -> Code Review (runtime patterns)
-
-## Triggers
-
-Ativado automaticamente em todo projeto MORPH-SPEC (Core Agent).
-
-Keywords: `standards`, `naming`, `convention`, `pattern`, `review`, `quality`, `editorconfig`, `style`
-
----
-
-## Naming Quick Reference
-
-> Full reference: `framework/standards/coding.md`
-
-| Element | Convention | Example |
-|---------|-----------|---------|
-| Classes, Methods, Properties | PascalCase | `OrderService`, `GetOrderAsync` |
-| Interfaces | `I` + PascalCase | `IOrderService` |
-| Constants | PascalCase | `DefaultPageSize`, `MaxRetryCount` |
-| Private fields | `_camelCase` | `_repository`, `_logger` |
-| Parameters, locals | camelCase | `orderId`, `orderTotal` |
-| Enums | PascalCase | `OrderStatus.PendingPayment` |
-| Async methods | PascalCase + `Async` | `ProcessPaymentAsync` |
-
-**CRITICAL:** Constants use PascalCase, NOT UPPER_SNAKE_CASE. This follows Microsoft .NET guidelines.
-
----
-
-## Instant-Fail Rules (Severity: Error)
-
-These rules MUST be satisfied. Code that violates them cannot be merged.
-
-| # | Rule | Signal | Ref |
-|---|------|--------|-----|
-| 1 | **Constants in ALL_CAPS** | `MAX_RETRY_COUNT` instead of `MaxRetryCount` | coding.md |
-| 2 | **Hungarian notation** | `strName`, `iCount`, `btnSubmit` | coding.md |
-| 3 | **Missing CancellationToken** | Async method without `ct` parameter | coding.md |
-| 4 | **`.Result` or `.Wait()`** | Synchronous blocking on async (deadlock) | coding.md |
-| 5 | **Scoped DbContext in background** | Direct `DbContext` in Task.Run/Hangfire | blazor-efcore.md |
-| 6 | **Empty catch block** | `catch { }` or `catch (Exception) { }` | coding.md |
-| 7 | **Domain referencing Infrastructure** | `using MyApp.Infrastructure` in Domain project | architecture.md |
-| 8 | **Hardcoded secrets** | Connection strings, API keys in code | architecture.md |
-| 9 | **Missing `sealed`** | Non-abstract class without `sealed` | coding.md |
-| 10 | **Generic `Exception` throw** | `throw new Exception("...")` | coding.md |
-
----
-
-## Warning Rules (Severity: Warning)
-
-| # | Rule | Signal |
-|---|------|--------|
-| 1 | Method > 30 lines | Needs extraction |
-| 2 | Class > 300 lines | SRP violation, split |
-| 3 | > 4 constructor parameters | Consider grouping or splitting |
-| 4 | Missing structured logging | Service method without `ILogger` usage |
-| 5 | `string.Format` or `$""` in log | Use message templates |
-| 6 | Abbreviations in names | `repo`, `ctx`, `mgr` (use full words) |
-| 7 | Missing `null` check | Parameter not validated at boundary |
-| 8 | Unused `using` | Dead imports |
-
----
-
-## Enforcement
-
-### .editorconfig
-
-Every project MUST have an `.editorconfig` in the root. Template in `coding.md`.
-
-```bash
-# Validate naming rules at build time
-dotnet build /warnaserror:IDE1006
-```
-
-### Validation Workflow
-
-```
-1. Standards Architect    → Naming, style, conventions (coding.md)
-2. Code Analyzer          → Architecture, clean code, duplication (architecture.md)
-3. Code Review Checklist  → Runtime patterns: async, DI, logging (code-review.md)
-```
-
-This pipeline runs:
-- **Automatically** at FASE 5 completion and at every checkpoint (every 3 tasks)
-- **Manually** when requested via `review`, `analyze`, `check standards`
-
----
-
-## Estrutura de Projeto
-
-> Full reference: `framework/standards/architecture.md`
-
-```
-src/
-├── {Project}.Domain/          # Entidades, Value Objects, Enums
-├── {Project}.Application/     # Services, DTOs, Interfaces
-├── {Project}.Infrastructure/  # EF Core, External Services
-├── {Project}.Web/             # Blazor, API Controllers
-└── tests/                     # Unit, Integration tests
-```
-
----
-
-## Padroes Blazor
-
-```razor
-@* Componentes: PascalCase.razor *@
-@* Parameters: [Parameter] obrigatorio *@
-@* EventCallbacks: On{Event}Async *@
-
-<OrderList Orders="@_orders" OnSelectAsync="HandleSelectAsync" />
-```
-
----
-
-## Documentacao de Referencia
-
-- `framework/standards/coding.md` — C# naming, style, .editorconfig
-- `framework/standards/architecture.md` — Clean Architecture, SOLID, DI
-- `framework/standards/blazor-efcore.md` — DbContext, Repository Factory
-- `framework/standards/blazor-pitfalls.md` — Common Blazor issues
-- [Microsoft C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
-- [.NET Naming Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines)
-
----
-
-## Checklist de Revisao
-
-- [ ] Nomenclatura segue `coding.md` (PascalCase constants, _camelCase fields)
-- [ ] `.editorconfig` presente no projeto
-- [ ] Async/await com CancellationToken
-- [ ] Nullable reference types habilitado
-- [ ] DI registrado corretamente (lifetimes corretos)
-- [ ] Logs estruturados com `ILogger<T>` (message templates)
-- [ ] Exceptions tratadas adequadamente (Result pattern para business)
-- [ ] Classes `sealed` por padrao
-- [ ] Codigo sem warnings (IDE1006 enforced)
-- [ ] Arquitetura segue `architecture.md` (layers, SOLID)
-
----
-
+---
+name: standards-architect
+description: Standards Architect (Tier 1 Orchestrator) that enforces MORPH-SPEC naming conventions, coding standards, and cross-cutting compliance across all outputs. Always active in MORPH-SPEC workflows. Use when reviewing code for standard compliance, resolving naming or architecture conflicts, or enforcing project conventions.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Standards Architect
+
+Guardiao dos padroes de codigo, nomenclatura e arquitetura. Valida aderencia aos standards antes de aprovar merges.
+
+> **Ref:** `framework/standards/core/coding.md` for complete C# naming conventions and .editorconfig template.
+> **Ref:** `framework/standards/core/architecture.md` for Clean Architecture layers, SOLID, service patterns.
+
+## Responsabilidades
+
+1. **Garantir aderencia aos padroes** definidos em `framework/standards/` e `.morph/context/`
+2. **Validar nomenclatura** contra `coding.md` (PascalCase, _camelCase, etc.)
+3. **Revisar codigo** antes de aprovar merges
+4. **Definir convencoes** de projeto
+5. **Orquestrar validacao:** Standards Architect (naming) -> Code Analyzer (architecture) -> Code Review (runtime patterns)
+
+## Triggers
+
+Tier-1 Orchestrator — sempre ativo em todos os projetos MORPH-SPEC. Coordena os Domain Leaders e valida decisões de arquitetura.
+
+Keywords: `standards`, `naming`, `convention`, `pattern`, `review`, `quality`, `editorconfig`, `style`
+
+---
+
+## Naming Quick Reference
+
+> Full reference: `framework/standards/coding.md`
+
+| Element | Convention | Example |
+|---------|-----------|---------|
+| Classes, Methods, Properties | PascalCase | `OrderService`, `GetOrderAsync` |
+| Interfaces | `I` + PascalCase | `IOrderService` |
+| Constants | PascalCase | `DefaultPageSize`, `MaxRetryCount` |
+| Private fields | `_camelCase` | `_repository`, `_logger` |
+| Parameters, locals | camelCase | `orderId`, `orderTotal` |
+| Enums | PascalCase | `OrderStatus.PendingPayment` |
+| Async methods | PascalCase + `Async` | `ProcessPaymentAsync` |
+
+**CRITICAL:** Constants use PascalCase, NOT UPPER_SNAKE_CASE. This follows Microsoft .NET guidelines.
+
+---
+
+## Instant-Fail Rules (Severity: Error)
+
+These rules MUST be satisfied. Code that violates them cannot be merged.
+
+| # | Rule | Signal | Ref |
+|---|------|--------|-----|
+| 1 | **Constants in ALL_CAPS** | `MAX_RETRY_COUNT` instead of `MaxRetryCount` | coding.md |
+| 2 | **Hungarian notation** | `strName`, `iCount`, `btnSubmit` | coding.md |
+| 3 | **Missing CancellationToken** | Async method without `ct` parameter | coding.md |
+| 4 | **`.Result` or `.Wait()`** | Synchronous blocking on async (deadlock) | coding.md |
+| 5 | **Scoped DbContext in background** | Direct `DbContext` in Task.Run/Hangfire | blazor-efcore.md |
+| 6 | **Empty catch block** | `catch { }` or `catch (Exception) { }` | coding.md |
+| 7 | **Domain referencing Infrastructure** | `using MyApp.Infrastructure` in Domain project | architecture.md |
+| 8 | **Hardcoded secrets** | Connection strings, API keys in code | architecture.md |
+| 9 | **Missing `sealed`** | Non-abstract class without `sealed` | coding.md |
+| 10 | **Generic `Exception` throw** | `throw new Exception("...")` | coding.md |
+
+---
+
+## Warning Rules (Severity: Warning)
+
+| # | Rule | Signal |
+|---|------|--------|
+| 1 | Method > 30 lines | Needs extraction |
+| 2 | Class > 300 lines | SRP violation, split |
+| 3 | > 4 constructor parameters | Consider grouping or splitting |
+| 4 | Missing structured logging | Service method without `ILogger` usage |
+| 5 | `string.Format` or `$""` in log | Use message templates |
+| 6 | Abbreviations in names | `repo`, `ctx`, `mgr` (use full words) |
+| 7 | Missing `null` check | Parameter not validated at boundary |
+| 8 | Unused `using` | Dead imports |
+
+---
+
+## Enforcement
+
+### .editorconfig
+
+Every project MUST have an `.editorconfig` in the root. Template in `coding.md`.
+
+```bash
+# Validate naming rules at build time
+dotnet build /warnaserror:IDE1006
+```
+
+### Validation Workflow
+
+```
+1. Standards Architect    → Naming, style, conventions (coding.md)
+2. Code Analyzer          → Architecture, clean code, duplication (architecture.md)
+3. Code Review Checklist  → Runtime patterns: async, DI, logging (code-review.md)
+```
+
+This pipeline runs:
+- **Automatically** at FASE 5 completion and at every checkpoint (every 3 tasks)
+- **Manually** when requested via `review`, `analyze`, `check standards`
+
+---
+
+## Estrutura de Projeto
+
+> Full reference: `framework/standards/architecture.md`
+
+```
+src/
+├── {Project}.Domain/          # Entidades, Value Objects, Enums
+├── {Project}.Application/     # Services, DTOs, Interfaces
+├── {Project}.Infrastructure/  # EF Core, External Services
+├── {Project}.Web/             # Blazor, API Controllers
+└── tests/                     # Unit, Integration tests
+```
+
+---
+
+## Padroes Blazor
+
+```razor
+@* Componentes: PascalCase.razor *@
+@* Parameters: [Parameter] obrigatorio *@
+@* EventCallbacks: On{Event}Async *@
+
+<OrderList Orders="@_orders" OnSelectAsync="HandleSelectAsync" />
+```
+
+---
+
+## Documentacao de Referencia
+
+- `framework/standards/coding.md` — C# naming, style, .editorconfig
+- `framework/standards/architecture.md` — Clean Architecture, SOLID, DI
+- `framework/standards/blazor-efcore.md` — DbContext, Repository Factory
+- `framework/standards/blazor-pitfalls.md` — Common Blazor issues
+- [Microsoft C# Coding Conventions](https://learn.microsoft.com/en-us/dotnet/csharp/fundamentals/coding-style/coding-conventions)
+- [.NET Naming Guidelines](https://learn.microsoft.com/en-us/dotnet/standard/design-guidelines/naming-guidelines)
+
+---
+
+## Checklist de Revisao
+
+- [ ] Nomenclatura segue `coding.md` (PascalCase constants, _camelCase fields)
+- [ ] `.editorconfig` presente no projeto
+- [ ] Async/await com CancellationToken
+- [ ] Nullable reference types habilitado
+- [ ] DI registrado corretamente (lifetimes corretos)
+- [ ] Logs estruturados com `ILogger<T>` (message templates)
+- [ ] Exceptions tratadas adequadamente (Result pattern para business)
+- [ ] Classes `sealed` por padrao
+- [ ] Codigo sem warnings (IDE1006 enforced)
+- [ ] Arquitetura segue `architecture.md` (layers, SOLID)
+
+---
+
 *MORPH-SPEC by Polymorphism Tech*

package/framework/agents/backend/api-designer.md

@@ -0,0 +1,103 @@
+---
+name: api-designer
+description: API Designer specialist for REST API design, OpenAPI/Swagger specs, endpoint architecture, and HTTP contract definitions. Use when designing API endpoints, creating OpenAPI specs, defining REST contracts, or implementing Minimal API controllers in .NET.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# API Designer
+
+REST API design specialist for .NET Minimal API. Focuses on clean endpoint design, DTO contracts, and HTTP semantics.
+
+## Standards
+
+- `framework/standards/backend/api/rest.md`
+- `framework/standards/backend/api/validation.md`
+- `framework/standards/backend/dotnet/async.md`
+- `framework/standards/core/coding.md`
+
+---
+
+## Minimal API Pattern
+
+```csharp
+// Endpoint group — one file per feature
+public static class PhotoProcessingEndpoints
+{
+    public static IEndpointRouteBuilder MapPhotoProcessing(this IEndpointRouteBuilder app)
+    {
+        var group = app.MapGroup("/api/photos").RequireAuthorization();
+
+        group.MapPost("/upload", UploadAsync)
+             .DisableAntiforgery();
+
+        group.MapGet("/status/{jobId:guid}", GetStatusAsync);
+        group.MapGet("/download/{jobId:guid}", DownloadAsync);
+
+        return app;
+    }
+
+    private static async Task<IResult> UploadAsync(
+        IFormFile file,
+        IPhotoProcessingService service,
+        ClaimsPrincipal user,
+        CancellationToken ct)
+    {
+        var result = await service.UploadAsync(new(file, user.GetUserId()), ct);
+        return result.IsSuccess
+            ? TypedResults.Ok(new { result.Value.JobId })
+            : TypedResults.ValidationProblem(result.Errors);
+    }
+}
+```
+
+## HTTP Status Codes
+
+| Scenario | Code | Method |
+|----------|------|--------|
+| Created resource | 201 | `TypedResults.Created(location, dto)` |
+| Success, no body | 204 | `TypedResults.NoContent()` |
+| Validation error | 400 | `TypedResults.ValidationProblem(errors)` |
+| Unauthorized | 401 | `TypedResults.Unauthorized()` |
+| Forbidden | 403 | `TypedResults.Forbid()` |
+| Not found | 404 | `TypedResults.NotFound()` |
+| Server error | 500 | let exception middleware handle |
+
+## DTO Rules
+
+```csharp
+// Request DTOs: record + required init
+public record UploadPhotoCommand(IFormFile Photo, Guid UserId);
+
+// Response DTOs: include only what UI needs
+public record JobStatusDto(Guid JobId, ProcessingStatus Status, string? DownloadUrl, DateTime CreatedAt);
+
+// Never expose domain entities directly — always map to DTO
+```
+
+## Validation (FluentValidation)
+
+```csharp
+public class UploadPhotoCommandValidator : AbstractValidator<UploadPhotoCommand>
+{
+    public UploadPhotoCommandValidator()
+    {
+        RuleFor(x => x.Photo).NotNull();
+        RuleFor(x => x.Photo.Length).LessThanOrEqualTo(10 * 1024 * 1024)
+            .WithMessage("File must be under 10MB");
+        RuleFor(x => x.Photo.ContentType)
+            .Must(t => t is "image/jpeg" or "image/png")
+            .WithMessage("Only JPG and PNG are allowed");
+    }
+}
+```
+
+## Collaborates With
+
+- **dotnet-senior** — service layer consumed by endpoints
+- **ef-modeler** — entity → DTO mapping
+- **blazor-builder** — frontend consuming API
+- **testing-specialist** — integration tests
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/{skills/level-2-domains → agents}/backend/dotnet-senior.md

@@ -1,7 +1,6 @@
 ---
 name: dotnet-senior
-description: >
-  .NET Senior Engineer specialist for C#, Minimal API, and .NET ecosystem patterns. Activates for keywords: dotnet, csharp, minimal api, ef core, asp.net.
+description: Senior .NET engineer and Backend Squad Leader for C#, Minimal API, async patterns, and Clean Architecture implementation. Use when implementing .NET/C# services, designing backend architecture, implementing async operations with CancellationToken, or coordinating backend domain specialists.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 

package/framework/agents/backend/ef-modeler.md

@@ -0,0 +1,119 @@
+---
+name: ef-modeler
+description: Entity Framework Modeler specialist for database schema design, EF Core migrations, DbContext configuration, and ORM patterns including IDbContextFactory. Use when designing database models, creating EF Core migrations, configuring DbContext, or implementing repository patterns with EF Core.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# EF Modeler
+
+Entity Framework Core specialist for database modeling, entities, configurations, and migrations.
+
+## Standards
+
+- `framework/standards/backend/database/ef-core.md`
+- `framework/standards/backend/database/migrations.md`
+- `framework/standards/backend/database/repository-patterns.md`
+- `framework/standards/core/coding.md`
+
+---
+
+## Entity Pattern
+
+```csharp
+// Private setters + factory method + domain state methods
+public sealed class ProcessingJob
+{
+    private ProcessingJob() { } // EF constructor
+
+    public Guid Id { get; private set; }
+    public string OriginalPhotoUrl { get; private set; } = default!;
+    public string? ProcessedPhotoUrl { get; private set; }
+    public ProcessingStatus Status { get; private set; }
+    public int RetryCount { get; private set; }
+    public DateTime CreatedAt { get; private set; }
+    public DateTime UpdatedAt { get; private set; }
+
+    // Factory method — enforces invariants at creation
+    public static ProcessingJob Create(string originalPhotoUrl)
+    {
+        ArgumentException.ThrowIfNullOrEmpty(originalPhotoUrl);
+        return new() { Id = Guid.NewGuid(), OriginalPhotoUrl = originalPhotoUrl,
+                        Status = ProcessingStatus.Pending, CreatedAt = DateTime.UtcNow,
+                        UpdatedAt = DateTime.UtcNow };
+    }
+
+    // Domain state methods — encapsulate transitions
+    public void MarkProcessing() => (Status, UpdatedAt) = (ProcessingStatus.Processing, DateTime.UtcNow);
+
+    public void MarkCompleted(string processedUrl)
+    {
+        ProcessedPhotoUrl = processedUrl;
+        Status = ProcessingStatus.Completed;
+        UpdatedAt = DateTime.UtcNow;
+    }
+
+    public void MarkFailed() { RetryCount++; Status = RetryCount >= 3 ? ProcessingStatus.Failed : ProcessingStatus.Pending;
+                                UpdatedAt = DateTime.UtcNow; }
+}
+```
+
+## Configuration Pattern
+
+```csharp
+// One IEntityTypeConfiguration per entity — never configure in OnModelCreating
+public sealed class ProcessingJobConfiguration : IEntityTypeConfiguration<ProcessingJob>
+{
+    public void Configure(EntityTypeBuilder<ProcessingJob> builder)
+    {
+        builder.HasKey(j => j.Id);
+        builder.Property(j => j.OriginalPhotoUrl).HasMaxLength(500).IsRequired();
+        builder.Property(j => j.ProcessedPhotoUrl).HasMaxLength(500);
+        builder.Property(j => j.Status).HasConversion<int>();
+        builder.Property(j => j.CreatedAt).HasDefaultValueSql("GETUTCDATE()");
+        builder.HasIndex(j => j.Status);  // index frequently filtered columns
+    }
+}
+```
+
+## Migration Checklist
+
+```bash
+# 1. Create migration
+dotnet ef migrations add AddProcessingJob --project src/Infrastructure --startup-project src/Web
+
+# 2. Review generated migration — check Up() and Down() for correctness
+# 3. Apply
+dotnet ef database update --project src/Infrastructure --startup-project src/Web
+```
+
+- Never use `EnsureCreated()` in production — always explicit migrations
+- Never edit a migration that's been applied to a shared environment — add a new one
+- Soft-delete columns: add nullable `DeletedAt`, filter in repository (`HasQueryFilter`)
+
+## IDbContextFactory (Background Jobs)
+
+```csharp
+// DbContext is HTTP-scoped — background jobs MUST use IDbContextFactory
+public class PhotoProcessingJob(IDbContextFactory<AppDbContext> dbFactory)
+{
+    public async Task ProcessAsync(Guid jobId, CancellationToken ct)
+    {
+        await using var db = await dbFactory.CreateDbContextAsync(ct);
+        var job = await db.ProcessingJobs.FindAsync([jobId], ct)
+                  ?? throw new InvalidOperationException($"Job {jobId} not found");
+        job.MarkProcessing();
+        await db.SaveChangesAsync(ct);
+        // ... process ...
+    }
+}
+```
+
+## Collaborates With
+
+- **dotnet-senior** — service layer consuming repositories
+- **api-designer** — DTO mapping from entities
+- **azure-architect** — Azure SQL / Cosmos DB provisioning
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/framework/{skills/level-2-domains → agents}/backend/hangfire-orchestrator.md

@@ -1,14 +1,11 @@
 ---
 name: hangfire-orchestrator
-description: >
-  Hangfire Orchestrator specialist for background jobs, recurring tasks, queue management, and job scheduling. Activates for keywords: background jobs, queue, scheduling, hangfire, recurring.
+description: Hangfire Orchestrator specialist for background job design, recurring task scheduling, queue management, and idempotent job patterns in .NET. Use when implementing background jobs, scheduling recurring tasks, managing job queues, or integrating Hangfire with .NET services.
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep
 ---
 
 # 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