@polymorphism-tech/morph-spec 4.3.1 → 4.3.3

package/stacks/nextjs-supabase/.morph/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/stacks/nextjs-supabase/.morph/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/stacks/nextjs-supabase/.morph/standards/architecture/ddd/entities.md

@@ -0,0 +1,99 @@
+# Architecture Standard: DDD Entities
+
+## Overview
+Entities have identity — two entities with the same ID are the same, regardless of their attribute values.
+
+## Entity Base Class
+```csharp
+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; }
+    public bool IsDeleted { get; private set; }
+    public DateTime? DeletedAt { get; private set; }
+
+    // Identity equality (not attribute equality)
+    public override bool Equals(object? obj)
+        => obj is Entity other && Id == other.Id;
+
+    public override int GetHashCode() => Id.GetHashCode();
+    public static bool operator ==(Entity? a, Entity? b) => a?.Equals(b) ?? b is null;
+    public static bool operator !=(Entity? a, Entity? b) => !(a == b);
+
+    // Soft delete support
+    public void SoftDelete()
+    {
+        IsDeleted = true;
+        DeletedAt = DateTime.UtcNow;
+    }
+}
+```
+
+## Entity Lifecycle
+```csharp
+// Entities are created through factory methods (never bare constructors from outside the aggregate)
+public class OrderItem : Entity
+{
+    private OrderItem() { } // Private for EF Core
+
+    internal static OrderItem Create(Guid productId, string productName, decimal price, int quantity)
+    {
+        if (price <= 0) throw new DomainException("Price must be positive");
+        if (quantity <= 0) throw new DomainException("Quantity must be positive");
+
+        return new OrderItem
+        {
+            ProductId = productId,
+            ProductName = productName,
+            UnitPrice = price,
+            Quantity = quantity
+        };
+    }
+
+    public Guid ProductId { get; private set; }
+    public string ProductName { get; private set; } = string.Empty;
+    public decimal UnitPrice { get; private set; }
+    public int Quantity { get; private set; }
+    public decimal Subtotal => UnitPrice * Quantity;
+
+    internal void IncreaseQuantity(int additionalQuantity)
+    {
+        if (additionalQuantity <= 0) throw new DomainException("Quantity must be positive");
+        Quantity += additionalQuantity;
+        UpdatedAt = DateTime.UtcNow;
+    }
+}
+```
+
+## EF Core Mapping
+
+### Required Conventions
+```csharp
+builder.HasKey(e => e.Id);
+builder.Property(e => e.CreatedAt).IsRequired();
+
+// Soft delete filter (apply globally)
+builder.HasQueryFilter(e => !e.IsDeleted);
+
+// All string properties: max length
+builder.Property(e => e.Name)
+    .IsRequired()
+    .HasMaxLength(200);
+```
+
+### Inheritance (TPH by default)
+```csharp
+// Table Per Hierarchy (single table with discriminator)
+builder.HasDiscriminator<string>("Type")
+    .HasValue<ProductOrder>("product")
+    .HasValue<ServiceOrder>("service");
+```
+
+## Entity vs Value Object Decision
+| Use Entity When | Use Value Object When |
+|----------------|----------------------|
+| Has lifecycle (created, updated, deleted) | Immutable by definition |
+| Identity matters (two objects with same data are different) | Equality by value |
+| Needs to be tracked in a repository | Owned by an entity (no separate table) |
+| Examples: User, Order, Product | Examples: Money, Address, DateRange |

package/stacks/nextjs-supabase/.morph/standards/architecture/ddd/value-objects.md

@@ -0,0 +1,124 @@
+# Architecture Standard: DDD Value Objects
+
+## Overview
+Value objects have no identity — equality is based on their attribute values. They are immutable.
+
+## Value Object Base Class
+```csharp
+public abstract class ValueObject
+{
+    protected abstract IEnumerable<object?> GetEqualityComponents();
+
+    public override bool Equals(object? obj)
+    {
+        if (obj is null || obj.GetType() != GetType()) return false;
+        return GetEqualityComponents().SequenceEqual(((ValueObject)obj).GetEqualityComponents());
+    }
+
+    public override int GetHashCode()
+        => GetEqualityComponents().Aggregate(0, (hash, c) => HashCode.Combine(hash, c?.GetHashCode() ?? 0));
+
+    public static bool operator ==(ValueObject? a, ValueObject? b) => a?.Equals(b) ?? b is null;
+    public static bool operator !=(ValueObject? a, ValueObject? b) => !(a == b);
+}
+```
+
+## Money Value Object
+```csharp
+public sealed class Money : ValueObject
+{
+    public decimal Amount { get; }
+    public string Currency { get; }
+
+    private Money(decimal amount, string currency)
+    {
+        Amount = amount;
+        Currency = currency.ToUpper();
+    }
+
+    public static Money Of(decimal amount, string currency = "BRL")
+    {
+        if (amount < 0) throw new DomainException("Money amount cannot be negative");
+        if (string.IsNullOrWhiteSpace(currency)) throw new DomainException("Currency required");
+        return new Money(amount, currency);
+    }
+
+    public Money Add(Money other)
+    {
+        if (Currency != other.Currency)
+            throw new DomainException($"Cannot add {Currency} and {other.Currency}");
+        return new Money(Amount + other.Amount, Currency);
+    }
+
+    public Money Multiply(decimal factor)
+        => new(Amount * factor, Currency);
+
+    public override string ToString() => $"{Amount:F2} {Currency}";
+
+    protected override IEnumerable<object?> GetEqualityComponents()
+    {
+        yield return Amount;
+        yield return Currency;
+    }
+}
+```
+
+## Address Value Object
+```csharp
+public sealed class Address : ValueObject
+{
+    public string Street { get; }
+    public string City { get; }
+    public string State { get; }
+    public string ZipCode { get; }
+    public string Country { get; }
+
+    public Address(string street, string city, string state, string zipCode, string country)
+    {
+        Street = street ?? throw new DomainException("Street required");
+        City = city ?? throw new DomainException("City required");
+        State = state ?? throw new DomainException("State required");
+        ZipCode = zipCode ?? throw new DomainException("ZipCode required");
+        Country = country ?? throw new DomainException("Country required");
+    }
+
+    protected override IEnumerable<object?> GetEqualityComponents()
+    {
+        yield return Street;
+        yield return City;
+        yield return State;
+        yield return ZipCode;
+        yield return Country;
+    }
+}
+```
+
+## EF Core Configuration (Owned Types)
+```csharp
+public class OrderConfiguration : IEntityTypeConfiguration<Order>
+{
+    public void Configure(EntityTypeBuilder<Order> builder)
+    {
+        // Embedded in same table (no separate table)
+        builder.OwnsOne(o => o.ShippingAddress, addr =>
+        {
+            addr.Property(a => a.Street).HasMaxLength(200).IsRequired();
+            addr.Property(a => a.City).HasMaxLength(100).IsRequired();
+            addr.Property(a => a.ZipCode).HasMaxLength(20).IsRequired();
+        });
+
+        // Money: stored as separate Amount + Currency columns
+        builder.OwnsOne(o => o.Total, money =>
+        {
+            money.Property(m => m.Amount).HasColumnType("decimal(18,2)").IsRequired();
+            money.Property(m => m.Currency).HasMaxLength(3).IsRequired();
+        });
+    }
+}
+```
+
+## Rules
+- Value objects are always immutable — no setters, return new instance from methods
+- Use `record` types only when they don't need to inherit from `ValueObject` base class
+- Never use value objects as EF Core entity (no `Id` column)
+- Never create value objects with invalid state — validate in constructor/factory