@polymorphism-tech/morph-spec 4.7.0 → 4.7.2

package/.morph/framework/standards/ai-agents/workflows.md

@@ -0,0 +1,354 @@
+# Microsoft Agent Framework - Workflow Orchestration Patterns
+
+> **Scope:** universal
+> **Layer:** 0 (always load)
+> **Keywords:** workflow, orchestration, sequential, parallel, conditional
+> **Load When:** always
+
+**Ref:** `setup.md` — Core setup guide (packages, ChatClientAgent, tools)
+
+Workflows compose multiple agents and executors into coordinated pipelines using `AgentWorkflowBuilder`.
+
+---
+
+## Core Concepts
+
+| Concept | Description |
+|---------|-------------|
+| **Executor** | Base processing unit. Implements `IMessageHandler<T>`. Agents are executors. |
+| **Edge** | Typed connection between executors defining message flow |
+| **Workflow** | Composition of executors + edges forming a processing graph |
+| **AIAgent** | Chat-based executor (most common type) |
+
+### Packages
+
+```xml
+<PackageReference Include="Microsoft.Agents.AI" Version="1.0.0-preview.*" />
+<PackageReference Include="Microsoft.Agents.AI.Workflows" Version="1.0.0-preview.*" />
+```
+
+---
+
+## 5 Orchestration Patterns
+
+| Pattern | Topology | Use Case | Coordination |
+|---------|----------|----------|--------------|
+| **Sequential** | Linear chain | Pipelines, multi-stage processing | Ordered, dependent |
+| **Concurrent** | Broadcast | Parallel analysis, ensemble | Independent, aggregated |
+| **GroupChat** | Star (manager hub) | Iterative refinement, review | Manager-controlled |
+| **Handoff** | Mesh | Dynamic routing, escalation | Agent-decided |
+| **Magentic** | Star (planner) | Complex generalist collaboration | Planner-based |
+
+---
+
+## 1. Sequential Workflow
+
+Agents execute in order — each agent receives the output of the previous one.
+
+```
+[Writer] → [Editor] → [Output]
+```
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Workflows;
+
+AIAgent writer = new ChatClientAgent(chatClient, new ChatClientAgentOptions
+{
+    Name = "Writer",
+    Instructions = "Write stories that are engaging and creative."
+});
+
+AIAgent editor = new ChatClientAgent(chatClient, new ChatClientAgentOptions
+{
+    Name = "Editor",
+    Instructions = "Make the story more engaging, fix grammar, and enhance plot."
+});
+
+Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
+
+AIAgent workflowAgent = await workflow.AsAgentAsync();
+AgentRunResponse response = await workflowAgent.RunAsync(
+    "Write a short story about a haunted house.");
+
+Console.WriteLine(response.Text);
+```
+
+---
+
+## 2. Concurrent Workflow (Fan-Out / Fan-In)
+
+Same input sent to multiple agents in parallel, results aggregated.
+
+```
+           ┌→ [Agent B1] →┐
+[Input] → Fan-Out → [Agent B2] → Fan-In → [Aggregator]
+           └→ [Agent B3] →┘
+```
+
+```csharp
+// Create specialized analysis agents
+AIAgent securityAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for security vulnerabilities.",
+    name: "SecurityAnalyst");
+
+AIAgent performanceAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for performance issues.",
+    name: "PerformanceAnalyst");
+
+AIAgent readabilityAnalyst = chatClient.AsAIAgent(
+    instructions: "Analyze code for readability and maintainability.",
+    name: "ReadabilityAnalyst");
+
+// Fan-out to all analysts, fan-in results
+// Use AddFanOutEdge / AddFanInEdge for custom executors
+```
+
+**Note:** All executors in the same superstep must complete before downstream executors begin.
+
+---
+
+## 3. GroupChat Workflow
+
+Manager-controlled round-robin conversation between agents.
+
+```csharp
+Workflow workflow = AgentWorkflowBuilder
+    .CreateGroupChatBuilderWith(agents =>
+        new AgentWorkflowBuilder.RoundRobinGroupChatManager(agents)
+        {
+            MaximumIterationCount = 2  // Max rounds
+        })
+    .AddParticipants(writer, editor)
+    .Build();
+
+AIAgent workflowAgent = await workflow.AsAgentAsync();
+AgentRunResponse response = await workflowAgent.RunAsync(prompt);
+```
+
+---
+
+## 4. Handoff Workflow
+
+Agents dynamically pass control based on routing rules. Mesh topology — no central orchestrator.
+
+```
+[Triage] ──┬→ [Math Tutor] ──→ [Triage]
+           └→ [History Tutor] → [Triage]
+```
+
+```csharp
+// Define specialized agents
+ChatClientAgent historyTutor = new(chatClient,
+    "You provide help with historical queries. Only respond about history.",
+    "history_tutor",
+    "Specialist agent for historical questions");
+
+ChatClientAgent mathTutor = new(chatClient,
+    "You provide help with math problems. Only respond about math.",
+    "math_tutor",
+    "Specialist agent for math questions");
+
+ChatClientAgent triageAgent = new(chatClient,
+    "You determine which agent to use. ALWAYS handoff to another agent.",
+    "triage_agent",
+    "Routes messages to the appropriate specialist");
+
+// Build handoff workflow
+var workflow = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
+    .WithHandoffs(triageAgent, [mathTutor, historyTutor])
+    .WithHandoff(mathTutor, triageAgent)
+    .WithHandoff(historyTutor, triageAgent)
+    .Build();
+```
+
+### Running Handoff with Streaming Events
+
+```csharp
+List<ChatMessage> messages = new();
+messages.Add(new(ChatRole.User, "What is the derivative of x^2?"));
+
+StreamingRun run = await InProcessExecution.StreamAsync(workflow, messages);
+await run.TrySendMessageAsync(new TurnToken(emitEvents: true));
+
+await foreach (WorkflowEvent evt in run.WatchStreamAsync())
+{
+    if (evt is AgentResponseUpdateEvent e)
+        Console.WriteLine($"{e.ExecutorId}: {e.Data}");
+    else if (evt is WorkflowOutputEvent outputEvt)
+    {
+        messages.AddRange(((List<ChatMessage>)outputEvt.Data!).Skip(messages.Count));
+        break;
+    }
+}
+```
+
+**Handoff characteristics:**
+- Receiving agent takes full task ownership
+- Full conversation history passed to receiving agent
+- Only supports `ChatAgent` with local tool execution
+
+---
+
+## 5. Magentic Workflow
+
+Planner-based variant of GroupChat. A manager agent dynamically selects which agent acts next based on planning.
+
+| Aspect | GroupChat | Magentic |
+|--------|-----------|----------|
+| Turn order | Fixed (round-robin) | Dynamic (planner decides) |
+| Manager | Simple rotation | LLM-based planner |
+| Best for | Predictable workflows | Complex, adaptive tasks |
+
+---
+
+## Workflow-as-Agent
+
+Any workflow can be encapsulated as a single agent for composition:
+
+```csharp
+Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
+AIAgent workflowAgent = await workflow.AsAgentAsync();
+
+// Use like any other agent
+var response = await workflowAgent.RunAsync("Write a report.");
+
+// Can be composed into larger workflows
+Workflow outerWorkflow = AgentWorkflowBuilder.BuildSequential(workflowAgent, reviewer);
+```
+
+---
+
+## Web API Integration
+
+```csharp
+// Program.cs
+builder.AddAIAgent("Writer", (sp, key) =>
+{
+    var chatClient = sp.GetRequiredService<IChatClient>();
+    return new ChatClientAgent(chatClient, name: key,
+        instructions: "You are a creative writing assistant.");
+});
+
+builder.AddAIAgent("Editor",
+    instructions: "You improve a writer's draft.");
+
+app.MapGet("/agent/chat", async (
+    [FromKeyedServices("Writer")] AIAgent writer,
+    [FromKeyedServices("Editor")] AIAgent editor,
+    string prompt) =>
+{
+    Workflow workflow = AgentWorkflowBuilder.BuildSequential(writer, editor);
+    AIAgent workflowAgent = await workflow.AsAgentAsync();
+    var response = await workflowAgent.RunAsync(prompt);
+    return Results.Ok(response.Text);
+});
+```
+
+---
+
+## Custom Executors
+
+For non-agent processing steps (data transformation, external API calls):
+
+```csharp
+public class PhotoCritiqueExecutor : BaseExecutor, IMessageHandler<WorkflowMessage>
+{
+    public async Task HandleAsync(
+        WorkflowMessage message,
+        WorkflowContext context,
+        CancellationToken cancellationToken)
+    {
+        var client = GetVisionClient();
+        var prompt = await GetPromptAsync("critique-prompt.md");
+
+        var dataContent = new DataContent(
+            await File.ReadAllBytesAsync(message.ImagePath),
+            "image/jpeg");
+
+        var fullPrompt = new PromptBuilder()
+            .AddText(prompt)
+            .AddImage(dataContent)
+            .Build();
+
+        var response = await client.GetResponseAsync(fullPrompt);
+        await context.SendAsync(new CritiqueResult(response));
+    }
+}
+```
+
+---
+
+## Client Types
+
+| Type | Method | Input / Output | Use Case |
+|------|--------|---------------|----------|
+| Conversational | `GetConversationalClient()` | Text → Text | Chat, analysis, generation |
+| Vision | `GetVisionClient()` | Image → Text | Image analysis, OCR |
+| Image Generation | `GetImageClient()` | Text → Image | Mockups, visualizations |
+
+---
+
+## Prompt Engineering for Workflows
+
+Store prompts in external markdown files for:
+- Versioning without recompilation
+- Independent iteration and testing
+- Reuse across agents
+
+```csharp
+var prompt = await File.ReadAllTextAsync("prompts/analysis.md");
+var agent = chatClient.AsAIAgent(instructions: prompt, name: "Analyst");
+```
+
+---
+
+## When to Use Which Pattern
+
+| Scenario | Pattern | Why |
+|----------|---------|-----|
+| ETL / data pipeline | Sequential | Each step depends on previous |
+| Code review (security + perf + style) | Concurrent | Independent analyses |
+| Content creation + editing | GroupChat | Iterative refinement |
+| Customer support routing | Handoff | Dynamic expert selection |
+| Complex research tasks | Magentic | Adaptive planning |
+| Composing sub-workflows | Workflow-as-Agent | Abstraction |
+
+---
+
+## Development Tools
+
+| Tool | Purpose |
+|------|---------|
+| Mermaid diagrams | Auto-generated workflow visualization |
+| Aspire Dashboard | Trace inter-agent calls and performance |
+| `dotnet new webapi-ai` | Template: Web API with Agent Framework |
+| `dotnet new mcp-server` | Template: MCP Server |
+
+---
+
+## Checklist
+
+- [ ] `Microsoft.Agents.AI.Workflows` package installed
+- [ ] Orchestration pattern selected and justified
+- [ ] Agents have clear, single responsibilities
+- [ ] Workflow built with `AgentWorkflowBuilder`
+- [ ] Streaming events handled for real-time UI
+- [ ] OpenTelemetry enabled for workflow tracing
+- [ ] Prompts stored externally (markdown files)
+- [ ] Error handling defined per executor
+
+---
+
+## References
+
+- [Workflow Orchestrations Overview](https://learn.microsoft.com/agent-framework/user-guide/workflows/orchestrations/overview)
+- [Handoff Pattern](https://learn.microsoft.com/agent-framework/user-guide/workflows/orchestrations/handoff)
+- [Agents in Workflows](https://learn.microsoft.com/agent-framework/tutorials/workflows/agents-in-workflows)
+- [GitHub Samples: Workflows](https://github.com/microsoft/agent-framework/tree/main/dotnet/samples/GettingStarted/Workflows)
+- `setup.md` — Core setup
+- `production.md` — Middleware, A2A, MCP
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/architecture/ddd/aggregates.md

@@ -0,0 +1,120 @@
+# Architecture Standard: DDD Aggregates
+
+## Overview
+Aggregates are the primary unit of consistency in DDD. An aggregate root is the only entry point.
+
+## Design Rules
+1. **Small aggregates**: Keep aggregates small (3-5 entities max)
+2. **Reference by ID**: Aggregates reference each other by ID only (not navigation properties across aggregate boundaries)
+3. **Consistency boundary**: All invariants within an aggregate must hold after every command
+4. **Single repository**: One repository per aggregate root
+
+## Aggregate Root Pattern
+```csharp
+public abstract class AggregateRoot : Entity
+{
+    private readonly List<DomainEvent> _domainEvents = [];
+
+    public IReadOnlyList<DomainEvent> DomainEvents => _domainEvents.AsReadOnly();
+
+    protected void RaiseDomainEvent(DomainEvent @event)
+    {
+        @event = @event with { Version = _domainEvents.Count + 1 };
+        _domainEvents.Add(@event);
+    }
+
+    public void ClearDomainEvents() => _domainEvents.Clear();
+}
+
+public abstract class Entity
+{
+    public Guid Id { get; protected set; } = Guid.NewGuid();
+    public DateTime CreatedAt { get; protected set; } = DateTime.UtcNow;
+    public DateTime? UpdatedAt { get; protected set; }
+}
+```
+
+## Order Aggregate Example
+```csharp
+public class Order : AggregateRoot
+{
+    private readonly List<OrderItem> _items = [];
+
+    // Private constructor — use factory method
+    private Order(Guid userId) { UserId = userId; Status = OrderStatus.Draft; }
+
+    public Guid UserId { get; private set; }
+    public OrderStatus Status { get; private set; }
+    public IReadOnlyList<OrderItem> Items => _items.AsReadOnly();
+    public decimal Total => _items.Sum(i => i.Subtotal);
+
+    // Factory method — validates invariants before creating
+    public static Order Create(Guid userId, IEnumerable<OrderItem> items)
+    {
+        if (userId == Guid.Empty) throw new DomainException("UserId required");
+        var order = new Order(userId);
+        foreach (var item in items) order.AddItem(item);
+        order.RaiseDomainEvent(new OrderCreatedEvent(order.Id, userId));
+        return order;
+    }
+
+    public void AddItem(OrderItem item)
+    {
+        if (Status != OrderStatus.Draft)
+            throw new DomainException($"Cannot add items to order in {Status} status");
+
+        var existing = _items.FirstOrDefault(i => i.ProductId == item.ProductId);
+        if (existing != null)
+            existing.IncreaseQuantity(item.Quantity);
+        else
+            _items.Add(item);
+
+        UpdatedAt = DateTime.UtcNow;
+    }
+
+    public void Confirm()
+    {
+        if (Status != OrderStatus.Draft)
+            throw new DomainException("Can only confirm draft orders");
+        if (!_items.Any())
+            throw new DomainException("Order must have at least one item");
+
+        Status = OrderStatus.Confirmed;
+        UpdatedAt = DateTime.UtcNow;
+        RaiseDomainEvent(new OrderConfirmedEvent(Id));
+    }
+}
+```
+
+## Repository Interface (per aggregate root)
+```csharp
+public interface IOrderRepository
+{
+    Task<Order?> GetAsync(Guid id, CancellationToken ct = default);
+    Task AddAsync(Order order, CancellationToken ct = default);
+    Task UpdateAsync(Order order, CancellationToken ct = default);
+}
+```
+
+## EF Core Configuration
+```csharp
+public class OrderConfiguration : IEntityTypeConfiguration<Order>
+{
+    public void Configure(EntityTypeBuilder<Order> builder)
+    {
+        builder.HasKey(o => o.Id);
+        builder.OwnsMany(o => o.Items, items =>
+        {
+            items.ToTable("OrderItems");
+            items.WithOwner().HasForeignKey("OrderId");
+        });
+        builder.Ignore(o => o.DomainEvents); // Not persisted
+    }
+}
+```
+
+## Anti-Patterns
+- Never expose mutable collections: use `IReadOnlyList<>`, never `List<>`
+- Never set state directly from outside: all mutations through aggregate methods
+- Never cross aggregate boundaries in a single transaction
+- Never put query logic in aggregates — use separate read models

package/.morph/framework/standards/architecture/ddd/bounded-contexts.md

@@ -0,0 +1,105 @@
+# DDD Bounded Contexts
+
+> **Scope:** universal
+> **Layer:** 2
+> **Keywords:** bounded-context, ddd, domain, context-map, modular-monolith, integration-events
+
+Bounded Context (BC) é a fronteira onde um modelo de domínio tem significado único.
+Use apenas em sistemas com múltiplos domínios distintos (Nível 3 de complexidade).
+
+---
+
+## Estrutura de Pastas (Nível 3)
+
+```
+src/{App}.Domain/
+  Billing/
+    Aggregates/
+      Subscription.cs
+      Invoice.cs
+    ValueObjects/
+      PlanTier.cs
+      BillingCycle.cs
+    Events/
+      SubscriptionCreatedEvent.cs
+    Exceptions/
+      SubscriptionNotFoundException.cs
+
+  Orders/
+    Aggregates/
+      Order.cs
+    ValueObjects/
+      Money.cs
+    Events/
+      OrderConfirmedEvent.cs
+
+src/{App}.Application/
+  Billing/
+    Commands/
+      CreateSubscriptionCommand.cs
+    Queries/
+      GetActiveSubscriptionQuery.cs
+    Handlers/
+      CreateSubscriptionHandler.cs
+
+src/{App}.Infrastructure/
+  Billing/
+    Repositories/
+      SubscriptionRepository.cs
+    Configurations/
+      SubscriptionConfiguration.cs
+```
+
+---
+
+## Regras de Comunicação Cross-BC
+
+```csharp
+// ✅ CORRETO: referenciar outro BC por ID
+public class Order : AggregateRoot
+{
+    public Guid CustomerId { get; private set; }  // ID, não navigation property
+}
+
+// ✅ CORRETO: comunicação via Integration Events
+public class OrderConfirmedHandler : INotificationHandler<OrderConfirmedIntegrationEvent>
+{
+    public async Task Handle(OrderConfirmedIntegrationEvent notification, CancellationToken ct)
+    {
+        await _billingService.ChargeForOrderAsync(notification.OrderId, ct);
+    }
+}
+
+// ❌ ERRADO: acesso direto ao repositório de outro BC
+public class OrderService
+{
+    private readonly ICustomerRepository _customerRepo; // cross-BC — PROIBIDO
+}
+```
+
+---
+
+## Linguagem Ubíqua por BC
+
+O mesmo termo pode ter significados diferentes em BCs distintos:
+
+| Termo | BC: Orders | BC: Support |
+|-------|-----------|-------------|
+| `Customer` | Quem fez pedido, tem `Orders[]` | Quem abriu ticket, tem `SLA` |
+| `Status` | `Draft/Confirmed/Shipped` | `Open/InProgress/Resolved` |
+
+Documente em `1-design/ubiquitous-language.md` por feature.
+
+---
+
+## Quando NÃO usar Bounded Contexts
+
+- App single-domain (ex: sistema de agendamentos)
+- MVP ou projeto com um único time
+- Quando os "domínios" compartilham o mesmo modelo sem conflito
+
+Em todos esses casos: use Nível 2 (Aggregates sem BC isolation).
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/.morph/framework/standards/architecture/ddd/complexity-levels.md

@@ -0,0 +1,108 @@
+# DDD Complexity Levels
+
+> **Scope:** universal
+> **Layer:** 2
+> **Keywords:** ddd, complexity, aggregate, crud, bounded-context, domain, level
+
+Define o nível de complexidade de domínio para cada feature. O nível determina qual
+template de contracts.cs será usado e quais padrões DDD são mandatórios.
+
+---
+
+## Os 3 Níveis
+
+### Nível 1 — CRUD
+
+**Quando usar:**
+- Feature é essencialmente Create/Read/Update/Delete
+- Entidade não tem regras de negócio (apenas validações de campos)
+- Nenhum outro domínio precisa reagir às mudanças desta entidade
+- Exemplos: `Category`, `Tag`, `UserProfile`, `Notification`
+
+**O que gerar:**
+- `Entity` simples (sem AggregateRoot)
+- Service interface CRUD
+- DTOs (record)
+- Repository interface básica
+- **SEM** Domain Events, **SEM** Value Objects obrigatórios, **SEM** CQRS
+
+---
+
+### Nível 2 — Business Logic
+
+**Quando usar:**
+- Entidade tem estados com transições controladas por regras (ex: Draft → Confirmed → Shipped)
+- Invariants existem: "só pode cancelar se estiver Ativo"
+- Cálculos derivados (Total, Saldo, Desconto)
+- Outros módulos precisam reagir a mudanças desta entidade
+- Exemplos: `Order`, `Subscription`, `Invoice`, `Project`, `Ticket`
+
+**O que gerar:**
+- `AggregateRoot` com factory method estático
+- Value Objects para tipos com regras (Money, Email, PhoneNumber)
+- Domain Events para mudanças de estado relevantes
+- Commands + Queries (CQRS com MediatR)
+- Repository interface por aggregate root
+- **SEM** Bounded Context isolation (módulos se comunicam diretamente)
+
+---
+
+### Nível 3 — Bounded Context
+
+**Quando usar (opt-in explícito apenas):**
+- Sistema tem 3+ domínios distintos onde o mesmo conceito tem modelos diferentes
+  - Exemplo: "Customer" em Billing ≠ "Customer" em Support
+- Times distintos trabalharão em cada domínio
+- Domínios precisam evoluir independentemente
+- Exemplos: plataforma multi-produto, marketplace, ERP
+
+**O que gerar:**
+- Tudo do Nível 2 +
+- Pasta `{BoundedContext}/` em Domain + Application
+- Integration Events para comunicação cross-BC (via MediatR/Service Bus)
+- Referências cross-BC por ID (nunca navigation properties)
+- Glossário de Linguagem Ubíqua por BC
+
+**⚠️ Não use Nível 3 por default.** Declare explicitamente na proposta.
+
+---
+
+## Como Detectar o Nível
+
+O `domain-architect` analisa a proposta e responde:
+
+```
+1. A entidade principal tem estados com transições? → Sim = Nível 2+
+2. Existem invariants de negócio? → Sim = Nível 2+
+3. Cálculos derivados existem? → Sim = Nível 2+
+4. Outros domínios precisam reagir a mudanças? → Sim = Nível 2+
+5. Diferentes contextos usam modelos diferentes do mesmo conceito? → Sim = Nível 3
+6. O usuário declarou explicitamente Bounded Context? → Sim = Nível 3
+Se nenhuma das anteriores: Nível 1
+```
+
+---
+
+## Template por Nível
+
+| Nível | Template |
+|-------|----------|
+| 1 | `code/dotnet/contracts/contracts-level1.cs` |
+| 2 | `code/dotnet/contracts/contracts-level2.cs` |
+| 3 | `code/dotnet/contracts/contracts-level3.cs` |
+
+---
+
+## Anti-Patterns
+
+| Anti-Pattern | Nível Afetado | Correção |
+|---|---|---|
+| AggregateRoot para CRUD simples | Nível 1 desnecessário | Use Entity simples |
+| Domain Events sem consumidores | Nível 2 excessivo | Remova ou use Nível 1 |
+| Bounded Context para app single-domain | Nível 3 prematuro | Use Nível 2 |
+| Entidade anêmica com regras no Service | Todos | Mova regras para o Aggregate |
+| Value Objects para todo primitivo | Nível 2 excessivo | Só quando há regras/validação |
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*