@polymorphism-tech/morph-spec 4.5.0 → 4.7.0

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

@@ -1,354 +0,0 @@
-# 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

@@ -1,120 +0,0 @@
-# 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/entities.md

@@ -1,99 +0,0 @@
-# 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/.morph/framework/standards/architecture/ddd/value-objects.md

@@ -1,124 +0,0 @@
-# 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