npm - @polymorphism-tech/morph-spec - Versions diffs - 4.3.3 → 4.3.4 - Mend

@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (401) hide show

package/stacks/nextjs-supabase/.morph/standards/ai-agents/workflows.md DELETED Viewed

@@ -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/stacks/nextjs-supabase/.morph/standards/architecture/ddd/aggregates.md DELETED Viewed

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

@@ -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/stacks/nextjs-supabase/.morph/standards/architecture/ddd/value-objects.md DELETED Viewed

@@ -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