@polymorphism-tech/morph-spec 4.3.3 → 4.3.4

package/docs/next-generation/AGENTS.md

@@ -1,521 +0,0 @@
-# MORPH-SPEC v3.0 - Agent Ecosystem
-
-> New agents, enhancements, and standards for 100% domain coverage
-
-**Status:** Design Complete ✅
-**Last Updated:** 2026-02-18
-
----
-
-## Table of Contents
-
-- [Coverage Gaps](#coverage-gaps)
-- [New Agents (9)](#new-agents-9)
-- [Enhanced Agents (6)](#enhanced-agents-6)
-- [New Standards (23)](#new-standards-23)
-- [Impact Summary](#impact-summary)
-
----
-
-## Coverage Gaps
-
-### Current State ❌
-
-| Domain | Current Coverage | Gap |
-|--------|------------------|-----|
-| **Observability** | 0% | ❌ No observability-expert |
-| **Event-Driven** | 20% | ❌ No event-architect (only Hangfire) |
-| **NoSQL/Cache** | 30% | ❌ No nosql-cache-expert |
-| **API Design** | 40% | ❌ No api-designer (mixed in dotnet-senior) |
-| **DDD** | 50% | ❌ No ddd-expert (patterns scattered) |
-| **Vector Search** | 60% | ❌ No vector-search-expert (RAG ad-hoc) |
-| **Thread Management** | 0% | ❌ No thread-orchestrator (v3.0 feature) |
-| **Context Optimization** | 0% | ❌ No context-optimizer (v3.0 feature) |
-| **Performance** | 40% | ❌ No performance-expert |
-
-### Target State ✅
-
-**100% coverage** across all 9 domains:
-- Developer Experience
-- Application Layer (Frontend + Backend)
-- AI & Agent Orchestration
-- Data & Persistence
-- Security & Identity
-- Integration & Communication
-- Infrastructure & Platform
-- **Observability** (NEW domain)
-- Quality Assurance
-- Architecture & Patterns
-
----
-
-## New Agents (9)
-
-### 1. observability-expert ⭐⭐⭐⭐⭐ (CRITICAL)
-
-**Tier:** 3 (Specialist)
-**Domain:** Observability (NEW)
-**Priority:** CRITICAL (0% → 100% coverage)
-
-**Standards:**
-- observability/monitoring.md
-- observability/logging.md
-- observability/tracing.md
-- observability/metrics.md
-
-**Skills:**
-- Application Insights dashboards and queries (KQL)
-- Serilog structured logging configuration
-- OpenTelemetry instrumentation and tracing
-- Custom metrics and alerts setup
-- Azure Monitor workbooks
-- Log Analytics integration
-- Distributed tracing correlation IDs
-- Performance counters and profiling
-
-**Keywords:**
-- observability, monitoring, logging, tracing, metrics, telemetry
-- application insights, serilog, opentelemetry, azure monitor
-- dashboards, alerts, KQL, log analytics
-
-**Impact:**
-- Fills critical 0% coverage gap
-- Enables comprehensive production monitoring
-- Cross-cutting expertise across all domains
-
-**Reports To:** standards-architect
-**Coordinates:** All agents (cross-cutting concern)
-
----
-
-### 4. api-designer ⭐⭐⭐⭐ (HIGH)
-
-**Tier:** 3 (Specialist)
-**Domain:** Integration & Communication
-**Priority:** HIGH (dedicated API expertise)
-
-**Standards:**
-- integration/api/rest-design.md
-
-**Skills:**
-- REST API best practices and maturity levels
-- OpenAPI/Swagger documentation
-- Rate limiting and throttling
-- API security (OAuth2, JWT, API keys)
-- Pagination, filtering, sorting patterns
-
-**Keywords:**
-- api design, rest, graphql, grpc, openapi, swagger
-- api versioning, rate limiting, pagination, filtering
-
-**Impact:**
-- Dedicated API design expertise (vs. mixed in dotnet-senior)
-- Consistent API patterns across features
-- Modern API paradigms
-
-**Reports To:** dotnet-senior
-**Collaborates With:** event-architect
-
----
-
-### 5. ddd-expert ⭐⭐⭐ (MEDIUM)
-
-**Tier:** 3 (Specialist)
-**Domain:** Architecture & Patterns
-**Priority:** MEDIUM (systematic DDD patterns)
-
-**Standards:**
-- architecture/ddd/aggregates.md
-- architecture/ddd/entities.md
-- architecture/ddd/value-objects.md
-
-**Skills:**
-- Aggregate design and boundaries
-- Bounded contexts and context mapping
-- Domain events and event storming
-- Ubiquitous language development
-- Entity vs. Value Object design
-- Invariants and business rules
-- Anti-corruption layers
-- Strategic and tactical DDD
-
-**Keywords:**
-- ddd, domain-driven design, aggregates, entities, value objects
-- bounded context, ubiquitous language, domain events, invariants
-
-**Impact:**
-- Systematic DDD patterns (vs. ad-hoc currently)
-- Clean domain modeling
-- Better alignment with business language
-
-**Reports To:** standards-architect
-**Collaborates With:** event-architect, ef-modeler
-
----
-
-### 6. vector-search-expert ⭐⭐⭐ (MEDIUM)
-
-**Tier:** 3 (Specialist)
-**Domain:** Data & Persistence
-**Priority:** MEDIUM (dedicated RAG expertise)
-
-**Standards:**
-- data/vector-search/azure-ai-search.md
-- data/vector-search/rag-chunking.md
-
-**Skills:**
-- Azure AI Search setup and configuration
-- RAG (Retrieval-Augmented Generation) pipelines
-- Document chunking strategies
-- Embedding models (text-embedding-ada-002)
-- Vector search query optimization
-- Hybrid search (vector + keyword)
-- Semantic search configurations
-- Index design and maintenance
-
-**Keywords:**
-- vector search, rag, azure ai search, embeddings, semantic search
-- retrieval-augmented generation, chunking, hybrid search
-
-**Impact:**
-- Dedicated RAG expertise (vs. mixed in ms-agent-expert)
-- Specialized knowledge for AI search patterns
-- Better RAG pipeline design
-
-**Reports To:** ai-system-architect
-**Collaborates With:** ms-agent-expert
-
----
-
-### 7. thread-orchestrator (NEW for v3.0)
-
-**Tier:** 3 (Specialist)
-**Domain:** Developer Experience
-**Priority:** CRITICAL (enables v3.0 parallelization)
-
-**Standards:**
-- workflows/thread-management.md
-- workflows/parallel-execution.md
-
-**Skills:**
-- P-Thread (parallel) coordination
-- F-Thread (fusion) aggregation strategies
-- L-Thread (long-running) with stop hooks
-- Z-Thread (zero-touch) trust management
-- Thread dependency analysis
-- Parallel task scheduling
-- Thread analytics and monitoring
-- Deadlock detection and resolution
-
-**Keywords:**
-- thread management, parallel execution, fusion, orchestration
-- p-thread, f-thread, l-thread, z-thread, coordination
-
-**Impact:**
-- Enables 10-15 parallel threads (Boris Churnney's workflow)
-- Core component for v3.0 Scale pillar
-- Thread analytics and optimization
-
-**Reports To:** standards-architect
-**Collaborates With:** All domain leaders
-
----
-
-### 8. context-optimizer (NEW for v3.0)
-
-**Tier:** 3 (Specialist)
-**Domain:** Developer Experience
-**Priority:** CRITICAL (enables v3.0 optimization)
-
-**Standards:**
-- context/priming.md
-- context/bundles.md
-- context/analytics.md
-
-**Skills:**
-- MCP server hygiene and optimization
-- Context priming file generation
-- Micro-agent factory and specialization
-- Context bundle creation and compression
-- Token usage analytics and tracking
-- Context optimization recommendations
-- Real-time token monitoring
-- Session replay optimization
-
-**Keywords:**
-- context optimization, token reduction, mcp hygiene, priming
-- micro-agents, context bundles, analytics, token tracking
-
-**Impact:**
-- 30-40% token reduction (R&D framework)
-- Core component for v3.0 Optimize pillar
-- Context analytics dashboard
-
-**Reports To:** standards-architect
-**Collaborates With:** thread-orchestrator
-
----
-
-### 9. performance-expert ⭐⭐ (MEDIUM)
-
-**Tier:** 3 (Specialist)
-**Domain:** Quality Assurance
-**Priority:** MEDIUM (performance bottleneck identification)
-
-**Standards:**
-- performance/profiling.md
-- performance/optimization.md
-
-**Skills:**
-- .NET profiling (dotMemory, dotTrace, PerfView)
-- SQL query optimization and execution plans
-- Memory leak detection and analysis
-- CPU profiling and hot path optimization
-- Async/await performance patterns
-- Caching strategy recommendations
-- Database index optimization
-- Load testing and benchmarking
-
-**Keywords:**
-- performance, profiling, optimization, memory leak, cpu
-- dotMemory, dotTrace, query optimization, benchmarking
-
-**Impact:**
-- Performance bottleneck identification
-- Systematic optimization approach
-- Proactive performance monitoring
-
-**Reports To:** standards-architect
-**Collaborates With:** testing-specialist, ef-modeler
-
----
-
-## Enhanced Agents (6)
-
-### 1. nextjs-expert
-
-**Enhancements:**
-- **shadcn/ui:** Component library patterns and customization
-- **TanStack Query:** Data fetching, caching, and synchronization
-- **Server Actions:** Next.js 15 server-side mutations
-- **Middleware:** Authentication, authorization, request handling
-
-**New Skills:**
-- shadcn/ui component composition
-- React Server Components best practices
-- TanStack Query optimistic updates
-- Server Actions form handling
-- App Router patterns
-
----
-
-### 2. blazor-builder
-
-**Enhancements:**
-- **SignalR:** Real-time communication patterns
-- **FluentDataGrid:** Advanced grid usage and customization
-- **Blazor 10 features:** New lifecycle, rendering optimizations
-
-**New Skills:**
-- SignalR hub design and scaling
-- FluentDataGrid virtualization
-- Streaming rendering patterns
-- Enhanced navigation and forms
-
----
-
-### 3. ms-agent-expert
-
-**Enhancements:**
-- **MCP (Model Context Protocol):** Server implementation
-- **A2A (Agent-to-Agent):** Communication protocols
-- **Microsoft.Extensions.AI:** New abstractions
-
-**New Skills:**
-- MCP server development
-- A2A message patterns
-- Agent workflow orchestration with MAF
-- Tool integration best practices
-
----
-
-### 4. azure-architect
-
-**Enhancements:**
-- **Private Endpoints:** Secure Azure resource access
-- **Container Apps:** Best practices and optimization
-
-**New Skills:**
-- Private Endpoint networking
-- Zero-downtime deployments
-
----
-
-### 5. testing-specialist
-
-**Enhancements:**
-- **TestContainers:** Docker-based integration testing
-- **bUnit:** Blazor component testing
-- **Respawn:** Database reset between tests
-
-**New Skills:**
-- TestContainers.NET usage
-- bUnit component rendering tests
-- Respawn checkpoint strategy
-- Integration test isolation
-
----
-
-### 6. azure-identity
-
-**Enhancements:**
-- **WebAuthn/Passkeys:** Passwordless authentication
-- **FIDO2 integration:** Hardware key support
-
-**New Skills:**
-- Passkeys implementation
-- WebAuthn ceremony handling
-- Credential management
-- Fallback authentication flows
-
----
-
-## New Standards (23)
-
-### Observability (4 files)
-
-1. **observability/monitoring.md** - App Insights, dashboards, KQL queries
-2. **observability/logging.md** - Serilog, structured logging, correlation IDs
-3. **observability/tracing.md** - OpenTelemetry, distributed tracing, spans
-4. **observability/metrics.md** - Custom metrics, counters, gauges, alerts
-
-
-### API Design (3 files)
-
-11. **integration/api/rest-design.md** - REST best practices, versioning, HATEOAS
-
-### DDD (3 files)
-
-14. **architecture/ddd/aggregates.md** - Aggregate design, boundaries, invariants
-15. **architecture/ddd/entities.md** - Entity identity, lifecycle, persistence
-16. **architecture/ddd/value-objects.md** - Immutability, equality, validation
-
-### Vector Search (2 files)
-
-17. **data/vector-search/azure-ai-search.md** - Index design, vector config, hybrid search
-18. **data/vector-search/rag-chunking.md** - Chunking strategies, overlap, metadata
-
-### Context Optimization (3 files)
-
-19. **context/priming.md** - Context priming files, selective loading, token reduction
-20. **context/bundles.md** - Bundle compression, session replay, checkpoint storage
-21. **context/analytics.md** - Token tracking, optimization suggestions, Core Four
-
-### Thread Management (2 files)
-
-22. **workflows/thread-management.md** - Thread types, coordination, analytics
-23. **workflows/parallel-execution.md** - P-Thread patterns, dependencies, fusion
-
----
-
-## Impact Summary
-
-### Quantitative
-
-| Metric | Before | After | Change |
-|--------|--------|-------|--------|
-| **Total Agents** | 16 | 26 | **+62%** |
-| **Tier 3 Specialists** | 12 | 21 | **+75%** |
-| **Domain Coverage** | 90% | 100% | **+10%** |
-| **Total Standards** | 48 | 71 | **+48%** |
-| **Skill Enhancements** | 0 | 6 agents | **6 upgrades** |
-
-### Qualitative
-
-**Coverage:**
-- ✅ **Observability:** 0% → 100% (new domain)
-- ✅ **Event-Driven:** 20% → 100% (dedicated expert)
-- ✅ **NoSQL/Cache:** 30% → 100% (dedicated expert)
-- ✅ **API Design:** 40% → 100% (dedicated expert)
-- ✅ **DDD:** 50% → 100% (systematic patterns)
-- ✅ **Vector Search:** 60% → 100% (dedicated expert)
-
-**Specialization:**
-- Dedicated experts vs. generalists
-- Deeper knowledge in each domain
-- Better separation of concerns
-- Cross-cutting observability
-
-**v3.0 Enablement:**
-- thread-orchestrator enables parallelization (Scale pillar)
-- context-optimizer enables token reduction (Optimize pillar)
-- Both are critical for v3.0 success
-
----
-
-## agents.json Updates Required
-
-### Add New Agents Section
-
-```json
-{
-  "agents": {
-    "observability-expert": {
-      "tier": 3,
-      "role": "specialist",
-      "title": "Observability Expert",
-      "domains": ["observability"],
-      "keywords": ["observability", "monitoring", "logging", "tracing", "metrics", "telemetry"],
-      "always_active": false,
-      "validators": [],
-      "relationships": {
-        "reports_to": "standards-architect",
-        "coordinates": "all",
-        "team_role": "cross-cutting"
-      },
-      "standards": ["observability/monitoring.md", "observability/logging.md", "observability/tracing.md", "observability/metrics.md"]
-    }
-    // ... repeat for other 8 agents
-  }
-}
-```
-
-### Update squadConfigs
-
-```json
-{
-  "squadConfigs": {
-    "full-stack": {
-      "parallel": true,
-      "agents": [
-        "dotnet-senior",
-        "blazor-builder",
-        "bicep-architect",
-        "thread-orchestrator",
-        "context-optimizer",
-        "observability-expert"
-      ],
-      "waitForAll": true,
-      "coordination": "thread-orchestrator"
-    }
-  }
-}
-```
-
----
-
-## Summary
-
-MORPH-SPEC v3.0 agent ecosystem expansion delivers:
-
-- **9 new agents** (observability, event-driven, NoSQL, API, DDD, vector-search, thread, context, performance)
-- **6 enhanced agents** (nextjs, blazor, ms-agent, azure, testing, azure-identity)
-- **23 new standards** (4 observability, 3 event-driven, 3 NoSQL, 3 API, 3 DDD, 2 vector, 3 context, 2 thread)
-- **100% domain coverage** (fills all gaps)
-- **v3.0 enablement** (thread-orchestrator + context-optimizer)
-
-Next: See [ROADMAP.md](./ROADMAP.md) for 10-week implementation plan.
-
----
-
-*MORPH-SPEC v3.0 Agent Ecosystem - by Polymorphism Tech*