@polymorphism-tech/morph-spec 2.3.0 → 3.0.0

package/content/.claude/skills/level-2-domains/ai-agents/ai-system-architect.md

@@ -0,0 +1,192 @@
+# AI System Architect
+
+Expert in agentic system architecture, multi-agent orchestration, and RAG pipelines.
+
+> **Layer:** 2 | **Load:** on-keyword | **Keywords:** orchestration, multi-agent, rag, vector search, embedding, agentic, memory, reasoning
+
+> **Ref:** `agent-framework-workflows.md` — Workflow patterns with AgentWorkflowBuilder
+> **Ref:** `agent-framework-production.md` — Middleware, A2A, MCP, caching
+> **Ref:** `vector-search-rag.md` — Vector Search + RAG with EF Core 10
+
+## Responsibilities
+
+1. Design scalable agentic architectures
+2. Define orchestration patterns (workflows, inter-agent communication)
+3. Implement RAG pipelines (chunking, embedding, retrieval)
+4. Select patterns from 20 agentic design patterns
+
+---
+
+## 20 Agentic Design Patterns
+
+| # | Pattern | Use Case | When to Use | Key Trade-off |
+|---|---------|----------|-------------|---------------|
+| 1 | **Prompt Chaining** | Multi-step processing | Data transformation, pipelines | Modular vs context explosion |
+| 2 | **Routing** | Direct to specialist | Multiple domains | Specialization vs misrouting |
+| 3 | **Parallelization** | Independent chunks | Large-scale processing | Speed vs coordination complexity |
+| 4 | **Reflection** | Draft → critique → refine | Quality control, creative tasks | Quality vs cost (limit 3 iterations) |
+| 5 | **Tool Use** | External tool calls | Multi-step workflows | Quality vs misfire propagation |
+| 6 | **Planning** | Step-by-step before execute | Goal-oriented workflows | Strategic vs setup complexity |
+| 7 | **Multi-Agent Collaboration** | Specialized agents + manager | Iterative refinement, dev | Specialization vs extensive testing |
+| 8 | **Memory Management** | Short/episodic/long-term | Continuity, personalization | Context preservation vs privacy risk |
+| 9 | **Learning & Adaptation** | Feedback → update prompts | Continuous improvement | Improvement vs learning wrong things |
+| 10 | **Goal Setting & Monitoring** | SMART goals + metrics | Complex projects, autonomous ops | Efficiency vs goal conflicts |
+| 11 | **Exception Handling** | Retry + exponential backoff | Production systems | Visibility vs infra complexity |
+| 12 | **Human-in-the-Loop** | Human review for high-risk | Compliance, edge cases | Trust vs latency |
+| 13 | **Knowledge Retrieval (RAG)** | Chunk + embed + search | Private/proprietary data | Accuracy vs infra to maintain |
+| 14 | **Inter-Agent Communication** | Structured messaging (A2A) | Enterprise, distributed | Fault isolation vs extreme complexity |
+| 15 | **Resource-Aware Optimization** | Route by complexity/cost | Cost-sensitive, high volume | Cost reduction vs tuning effort |
+| 16 | **Reasoning Techniques** | CoT, ToT, Self-Consistency | Complex problems, math | Robust vs token-heavy (rarely needed) |
+| 17 | **Evaluation & Monitoring** | Quality gates, drift detection | Production, enterprise | Reliability vs alert fatigue |
+| 18 | **Guardrails & Safety** | PII, injection, malicious check | Public-facing systems | Risk mitigation vs false positives |
+| 19 | **Prioritization** | Score by value/risk/effort | Dynamic environments, task mgmt | Adaptability vs context switching |
+| 20 | **Exploration & Discovery** | Broad knowledge exploration | Research, competitive analysis | Innovation vs resource-heavy |
+
+### Common Pattern Combinations
+
+| Combination | Use Case |
+|------------|----------|
+| Prompt Chaining + Reflection | Content generation with quality control |
+| Routing + Tool Use | Customer service with integrations |
+| Planning + Multi-Agent | Complex development projects |
+| Memory + Learning | Personalized assistants that evolve |
+| Parallelization + Exception Handling | Data processing at scale |
+| Human-in-Loop + Guardrails | Critical systems with compliance |
+
+---
+
+## Microsoft Agent Framework Orchestration
+
+### Workflow Patterns
+
+```csharp
+// Sequential — pipeline processing
+Workflow sequential = AgentWorkflowBuilder.BuildSequential(researcher, analyst, writer);
+AIAgent seqAgent = await sequential.AsAgentAsync();
+
+// GroupChat — iterative refinement with manager
+Workflow groupChat = AgentWorkflowBuilder
+    .CreateGroupChatBuilderWith(agents =>
+        new AgentWorkflowBuilder.RoundRobinGroupChatManager(agents)
+        { MaximumIterationCount = 3 })
+    .AddParticipants(writer, editor, reviewer)
+    .Build();
+
+// Handoff — dynamic routing
+var handoff = AgentWorkflowBuilder.StartHandoffWith(triageAgent)
+    .WithHandoffs(triageAgent, [specialistA, specialistB])
+    .WithHandoff(specialistA, triageAgent)
+    .WithHandoff(specialistB, triageAgent)
+    .Build();
+```
+
+### A2A Protocol
+
+```csharp
+app.MapA2A(agent, "/a2a/agent-name", agentCard: new()
+{
+    Name = "Agent Name",
+    Description = "What this agent does.",
+    Version = "1.0"
+});
+// Discovery: GET /a2a/agent-name/v1/card
+// Message:   POST /a2a/agent-name/v1/message:stream
+```
+
+### Small Specialized Agents > Monolithic Agent
+
+Design principle: each agent has one clear responsibility, composed via workflows.
+
+---
+
+## RAG Pipeline with Microsoft Stack
+
+### Architecture
+
+```
+Extraction → Staging (Blob) → Chunking → Embedding → Indexing (AI Search) → Retrieval
+```
+
+### Chunking Strategies
+
+| Strategy | Method | Best For |
+|----------|--------|----------|
+| Paragraph Splitter | By paragraphs | General text |
+| Markdown Header Splitter | By headers (#, ##) | Documentation |
+| Token-based Splitter | By token count | Fixed-size chunks |
+| Semantic Splitter | By semantic similarity | Highest quality |
+
+**Principle:** Test ALL strategies and rank by metrics (avg similarity score, token count, relevance).
+
+### Agent Framework Integration
+
+```csharp
+[Description("Searches knowledge base")]
+public async Task<SearchResult[]> SearchKnowledgeAsync(
+    [Description("Search query")] string query, CancellationToken ct = default)
+{
+    var embedding = await _embeddings.GenerateAsync(query, ct);
+    var results = await _searchClient.SearchAsync<KnowledgeChunk>(query,
+        new SearchOptions { VectorSearch = new() {
+            Queries = { new VectorizedQuery(embedding) { KNearestNeighborsCount = 5 } }
+        }}, ct);
+    return results.Value.GetResults().ToArray();
+}
+```
+
+### Why Staging in Blob Storage?
+
+Immutability, versioning, low cost, fallback on processing bugs, audit trail.
+
+### Key Insight
+
+**LLM comes LAST.** 80% of RAG work happens before the model is called (extraction, chunking, embedding, evaluation).
+
+---
+
+## When NOT to Use Agent Framework
+
+| Scenario | Use Instead |
+|----------|------------|
+| Single LLM call resolves | `IChatClient` directly |
+| No tools needed | `ChatClient.GetResponseAsync()` |
+| Model < 3B params | Tool calling unreliable |
+| Just summarization/translation | No agent needed |
+
+---
+
+## Checklist
+
+### System Design
+- [ ] Patterns selected and justified
+- [ ] Orchestration pattern chosen (Sequential/Concurrent/GroupChat/Handoff/Magentic)
+- [ ] Specialized agents mapped with clear responsibilities
+
+### RAG Pipeline (if applicable)
+- [ ] Data source identified and accessible
+- [ ] Staging in Blob Storage configured
+- [ ] Multiple chunking strategies tested and ranked
+- [ ] Azure AI Search index configured (vector + hybrid)
+
+### Orchestration
+- [ ] Workflow built with `AgentWorkflowBuilder`
+- [ ] Error handling via middleware
+- [ ] OpenTelemetry monitoring enabled
+
+### Security & Cost
+- [ ] Guardrails implemented (PII, injection, malicious content)
+- [ ] Resource-Aware Optimization (model selection by complexity)
+- [ ] Token usage monitored and costs documented
+
+---
+
+## References
+
+- [Microsoft Agent Framework](https://learn.microsoft.com/agent-framework/)
+- [Azure AI Search](https://learn.microsoft.com/azure/search/)
+- [GitHub: microsoft/agent-framework](https://github.com/microsoft/agent-framework)
+- `.wiki/ai/20-agentic-design-patterns.md` — Full 20 patterns reference
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.claude/skills/{specialists → level-2-domains/architecture}/po-pm-advisor.md

@@ -1,197 +1,197 @@
-# PO/PM Advisor
-
-Especialista em requisitos, priorização e gestão de produto para clarificar features e ROI.
-
-## Responsabilidades
-
-1. **Clarificar requisitos** ambíguos ou incompletos
-2. **Priorizar features** por valor de negócio
-3. **Calcular ROI** e esforço estimado
-4. **Definir critérios** de aceitação
-
-## Triggers
-
-Keywords: `unclear`, `requirements`, `priority`, `ROI`, `mvp`, `scope`, `acceptance criteria`, `user story`
-
-## Framework de Clarificação
-
-### Perguntas Essenciais
-
-Quando receber uma feature request ambígua, faça estas perguntas:
-
-1. **Quem?** - Qual o usuário/persona principal?
-2. **O quê?** - O que exatamente deve acontecer?
-3. **Por quê?** - Qual problema resolve? Qual o valor?
-4. **Quando?** - Urgência? Deadline externo?
-5. **Como medir?** - Como saberemos que funcionou?
-
-### Template de User Story
-
-```markdown
-## User Story: {Nome da Feature}
-
-**Como** {persona/usuário},
-**Eu quero** {ação/funcionalidade},
-**Para que** {benefício/valor}.
-
-### Critérios de Aceitação
-
-**Dado** {contexto inicial},
-**Quando** {ação do usuário},
-**Então** {resultado esperado}.
-
-### Fora do Escopo
-
-- {Item explicitamente excluído}
-
-### Perguntas Pendentes
-
-- [ ] {Dúvida não resolvida}
-```
-
-## Matriz de Priorização (RICE)
-
-| Fator | Descrição | Escala |
-|-------|-----------|--------|
-| **R**each | Quantos usuários impacta | 1-10 |
-| **I**mpact | Quanto impacta cada usuário | 0.25, 0.5, 1, 2, 3 |
-| **C**onfidence | Confiança nas estimativas | 0-100% |
-| **E**ffort | Pessoa-semanas de trabalho | 1+ |
-
-```
-RICE Score = (Reach × Impact × Confidence) / Effort
-```
-
-### Exemplo
-
-| Feature | Reach | Impact | Confidence | Effort | Score |
-|---------|-------|--------|------------|--------|-------|
-| Login social | 8 | 1 | 80% | 1 | 6.4 |
-| Dashboard | 5 | 2 | 90% | 3 | 3.0 |
-| Export PDF | 3 | 0.5 | 100% | 0.5 | 3.0 |
-| Dark mode | 4 | 0.25 | 100% | 1 | 1.0 |
-
-## MVP vs Nice-to-Have
-
-### Critérios para MVP
-
-1. **Resolve o problema core** do usuário
-2. **Diferencia** da concorrência
-3. **Validável** em 2-4 semanas
-4. **Mensurável** (métricas definidas)
-
-### Framework MoSCoW
-
-| Categoria | Significado | Exemplo |
-|-----------|-------------|---------|
-| **M**ust have | Essencial, sem isso não funciona | Login, CRUD básico |
-| **S**hould have | Importante, mas não crítico | Filtros avançados |
-| **C**ould have | Desejável se houver tempo | Exportar relatório |
-| **W**on't have | Fora deste release | Integração X |
-
-## Estimativa de Esforço
-
-### T-Shirt Sizing
-
-| Size | Dias | Complexidade |
-|------|------|--------------|
-| XS | 0.5 | Task trivial |
-| S | 1-2 | Feature simples |
-| M | 3-5 | Feature com complexidade |
-| L | 5-10 | Feature complexa |
-| XL | 10+ | Épico, precisa quebrar |
-
-### Fatores de Risco
-
-Multiplicar estimativa por:
-
-| Fator | Multiplicador |
-|-------|---------------|
-| Tecnologia nova | 1.5x |
-| Integração externa | 1.3x |
-| Requisitos vagos | 1.5x |
-| Primeiro da equipe | 1.3x |
-
-## Template de ADR (Architecture Decision Record)
-
-```markdown
-# ADR-{XXX}: {Título da Decisão}
-
-## Status
-{PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED}
-
-## Contexto
-{Situação que requer decisão}
-
-## Opções Consideradas
-
-### Opção 1: {Nome}
-- Prós: ...
-- Contras: ...
-- Custo: ...
-
-### Opção 2: {Nome}
-- Prós: ...
-- Contras: ...
-- Custo: ...
-
-## Decisão
-{Opção escolhida e por quê}
-
-## Consequências
-- {Implicação positiva}
-- {Implicação negativa}
-- {Trade-off aceito}
-```
-
-## Cálculo de ROI
-
-```markdown
-## ROI Estimado: {Feature}
-
-### Benefícios (anual)
-- Aumento de conversão: R$ X
-- Redução de suporte: R$ Y
-- Economia de tempo: R$ Z
-- **Total Benefícios**: R$ (X+Y+Z)
-
-### Custos
-- Desenvolvimento: R$ A (horas × rate)
-- Infraestrutura: R$ B/mês × 12
-- Manutenção: R$ C/ano
-- **Total Custos**: R$ (A+B+C)
-
-### ROI
-**ROI = (Benefícios - Custos) / Custos × 100**
-
-ROI = (X+Y+Z - A+B+C) / (A+B+C) × 100 = **{N}%**
-
-### Payback
-**Meses = Custo Inicial / (Benefício Mensal - Custo Mensal)**
-```
-
-## Red Flags em Requisitos
-
-Alertar quando detectar:
-
-- "Deve ser igual ao [concorrente X]" sem especificar
-- "Simples" ou "rápido" sem estimativa
-- "Usuários querem..." sem evidência
-- Escopo crescente sem priorização
-- Deadline impossível sem trade-offs
-
-## Checklist de Requisitos
-
-- [ ] Persona/usuário definido
-- [ ] Problema claramente articulado
-- [ ] Valor de negócio quantificado
-- [ ] Critérios de aceitação escritos
-- [ ] Fora do escopo explícito
-- [ ] Dependências mapeadas
-- [ ] Riscos identificados
-- [ ] Estimativa de esforço
-- [ ] Prioridade definida (RICE/MoSCoW)
-
----
-
-*MORPH-SPEC by Polymorphism Tech*
+# PO/PM Advisor
+
+Especialista em requisitos, priorização e gestão de produto para clarificar features e ROI.
+
+## Responsabilidades
+
+1. **Clarificar requisitos** ambíguos ou incompletos
+2. **Priorizar features** por valor de negócio
+3. **Calcular ROI** e esforço estimado
+4. **Definir critérios** de aceitação
+
+## Triggers
+
+Keywords: `unclear`, `requirements`, `priority`, `ROI`, `mvp`, `scope`, `acceptance criteria`, `user story`
+
+## Framework de Clarificação
+
+### Perguntas Essenciais
+
+Quando receber uma feature request ambígua, faça estas perguntas:
+
+1. **Quem?** - Qual o usuário/persona principal?
+2. **O quê?** - O que exatamente deve acontecer?
+3. **Por quê?** - Qual problema resolve? Qual o valor?
+4. **Quando?** - Urgência? Deadline externo?
+5. **Como medir?** - Como saberemos que funcionou?
+
+### Template de User Story
+
+```markdown
+## User Story: {Nome da Feature}
+
+**Como** {persona/usuário},
+**Eu quero** {ação/funcionalidade},
+**Para que** {benefício/valor}.
+
+### Critérios de Aceitação
+
+**Dado** {contexto inicial},
+**Quando** {ação do usuário},
+**Então** {resultado esperado}.
+
+### Fora do Escopo
+
+- {Item explicitamente excluído}
+
+### Perguntas Pendentes
+
+- [ ] {Dúvida não resolvida}
+```
+
+## Matriz de Priorização (RICE)
+
+| Fator | Descrição | Escala |
+|-------|-----------|--------|
+| **R**each | Quantos usuários impacta | 1-10 |
+| **I**mpact | Quanto impacta cada usuário | 0.25, 0.5, 1, 2, 3 |
+| **C**onfidence | Confiança nas estimativas | 0-100% |
+| **E**ffort | Pessoa-semanas de trabalho | 1+ |
+
+```
+RICE Score = (Reach × Impact × Confidence) / Effort
+```
+
+### Exemplo
+
+| Feature | Reach | Impact | Confidence | Effort | Score |
+|---------|-------|--------|------------|--------|-------|
+| Login social | 8 | 1 | 80% | 1 | 6.4 |
+| Dashboard | 5 | 2 | 90% | 3 | 3.0 |
+| Export PDF | 3 | 0.5 | 100% | 0.5 | 3.0 |
+| Dark mode | 4 | 0.25 | 100% | 1 | 1.0 |
+
+## MVP vs Nice-to-Have
+
+### Critérios para MVP
+
+1. **Resolve o problema core** do usuário
+2. **Diferencia** da concorrência
+3. **Validável** em 2-4 semanas
+4. **Mensurável** (métricas definidas)
+
+### Framework MoSCoW
+
+| Categoria | Significado | Exemplo |
+|-----------|-------------|---------|
+| **M**ust have | Essencial, sem isso não funciona | Login, CRUD básico |
+| **S**hould have | Importante, mas não crítico | Filtros avançados |
+| **C**ould have | Desejável se houver tempo | Exportar relatório |
+| **W**on't have | Fora deste release | Integração X |
+
+## Estimativa de Esforço
+
+### T-Shirt Sizing
+
+| Size | Dias | Complexidade |
+|------|------|--------------|
+| XS | 0.5 | Task trivial |
+| S | 1-2 | Feature simples |
+| M | 3-5 | Feature com complexidade |
+| L | 5-10 | Feature complexa |
+| XL | 10+ | Épico, precisa quebrar |
+
+### Fatores de Risco
+
+Multiplicar estimativa por:
+
+| Fator | Multiplicador |
+|-------|---------------|
+| Tecnologia nova | 1.5x |
+| Integração externa | 1.3x |
+| Requisitos vagos | 1.5x |
+| Primeiro da equipe | 1.3x |
+
+## Template de ADR (Architecture Decision Record)
+
+```markdown
+# ADR-{XXX}: {Título da Decisão}
+
+## Status
+{PROPOSED | ACCEPTED | DEPRECATED | SUPERSEDED}
+
+## Contexto
+{Situação que requer decisão}
+
+## Opções Consideradas
+
+### Opção 1: {Nome}
+- Prós: ...
+- Contras: ...
+- Custo: ...
+
+### Opção 2: {Nome}
+- Prós: ...
+- Contras: ...
+- Custo: ...
+
+## Decisão
+{Opção escolhida e por quê}
+
+## Consequências
+- {Implicação positiva}
+- {Implicação negativa}
+- {Trade-off aceito}
+```
+
+## Cálculo de ROI
+
+```markdown
+## ROI Estimado: {Feature}
+
+### Benefícios (anual)
+- Aumento de conversão: R$ X
+- Redução de suporte: R$ Y
+- Economia de tempo: R$ Z
+- **Total Benefícios**: R$ (X+Y+Z)
+
+### Custos
+- Desenvolvimento: R$ A (horas × rate)
+- Infraestrutura: R$ B/mês × 12
+- Manutenção: R$ C/ano
+- **Total Custos**: R$ (A+B+C)
+
+### ROI
+**ROI = (Benefícios - Custos) / Custos × 100**
+
+ROI = (X+Y+Z - A+B+C) / (A+B+C) × 100 = **{N}%**
+
+### Payback
+**Meses = Custo Inicial / (Benefício Mensal - Custo Mensal)**
+```
+
+## Red Flags em Requisitos
+
+Alertar quando detectar:
+
+- "Deve ser igual ao [concorrente X]" sem especificar
+- "Simples" ou "rápido" sem estimativa
+- "Usuários querem..." sem evidência
+- Escopo crescente sem priorização
+- Deadline impossível sem trade-offs
+
+## Checklist de Requisitos
+
+- [ ] Persona/usuário definido
+- [ ] Problema claramente articulado
+- [ ] Valor de negócio quantificado
+- [ ] Critérios de aceitação escritos
+- [ ] Fora do escopo explícito
+- [ ] Dependências mapeadas
+- [ ] Riscos identificados
+- [ ] Estimativa de esforço
+- [ ] Prioridade definida (RICE/MoSCoW)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*