@polymorphism-tech/morph-spec 3.1.0 → 4.2.0

package/docs/v3.0/AGENTS.md

@@ -0,0 +1,521 @@
+# 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-v3": {
+      "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*