@polymorphism-tech/morph-spec 1.0.0

package/content/.morph/examples/multi-agent/spec.md

@@ -0,0 +1,479 @@
+# Multi-Agent System - Especificação
+
+## 1. Visão Geral
+
+Sistema de agentes de IA cooperativos usando Microsoft Semantic Kernel para resolver tarefas complexas através de decomposição e especialização.
+
+### 1.1 Objetivos
+
+- Criar sistema escalável de agentes cooperativos
+- Implementar orquestração inteligente de tarefas
+- Fornecer extensibilidade para novos agentes e plugins
+- Manter custos controlados com uso eficiente de tokens
+
+### 1.2 Use Cases
+
+| Use Case | Agentes Envolvidos |
+|----------|-------------------|
+| Pesquisa de mercado | Orchestrator → Research → Analysis → Writing |
+| Análise de documentos | Orchestrator → Research → Analysis |
+| Geração de relatórios | Orchestrator → Research → Writing |
+| Q&A com base de conhecimento | Orchestrator → Research |
+
+## 2. Arquitetura
+
+### 2.1 Componentes Principais
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        API Layer                                 │
+│  ┌─────────────────┐  ┌─────────────────┐                       │
+│  │  ChatEndpoints  │  │  AgentEndpoints │                       │
+│  └─────────────────┘  └─────────────────┘                       │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Orchestration Layer                           │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+│  │ TaskDecomposer  │  │  AgentRouter    │  │ ResultAggregator│ │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Agent Layer                                 │
+│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
+│  │ Research     │  │ Analysis     │  │ Writing              │  │
+│  │ Agent        │  │ Agent        │  │ Agent                │  │
+│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                      Plugin Layer                                │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │ WebSearch   │  │ Document    │  │ DataAnalysis│             │
+│  │ Plugin      │  │ Plugin      │  │ Plugin      │             │
+│  └─────────────┘  └─────────────┘  └─────────────┘             │
+└─────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Infrastructure Layer                          │
+│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
+│  │  Azure OpenAI   │  │  Vector Store   │  │  Memory Store   │ │
+│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 2.2 Fluxo de Dados
+
+```
+User Request
+    │
+    ▼
+┌─────────────────────────────────────────┐
+│           Task Decomposition            │
+│  "Compare cloud providers" →            │
+│  [Research AWS, Research Azure,         │
+│   Research GCP, Compare, Write Report]  │
+└─────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────┐
+│           Agent Execution               │
+│  Research Agent → findings[]            │
+│  Analysis Agent → insights              │
+│  Writing Agent → report                 │
+└─────────────────────────────────────────┘
+    │
+    ▼
+┌─────────────────────────────────────────┐
+│         Result Aggregation              │
+│  Combine outputs, format, validate      │
+└─────────────────────────────────────────┘
+    │
+    ▼
+Final Response
+```
+
+## 3. Requisitos Funcionais
+
+### 3.1 API
+
+| ID | Requisito |
+|----|-----------|
+| API-001 | Endpoint de chat para interação com usuário |
+| API-002 | Endpoint para consultar status de processamento |
+| API-003 | Endpoint para listar agentes disponíveis |
+| API-004 | Streaming de respostas (SSE) |
+| API-005 | Autenticação via API Key |
+
+### 3.2 Orchestrator
+
+| ID | Requisito |
+|----|-----------|
+| ORCH-001 | Análise de intenção do usuário |
+| ORCH-002 | Decomposição de tarefas complexas |
+| ORCH-003 | Roteamento para agentes especialistas |
+| ORCH-004 | Agregação de resultados |
+| ORCH-005 | Retry automático em falhas |
+| ORCH-006 | Timeout por subtarefa |
+
+### 3.3 Agentes
+
+| ID | Requisito |
+|----|-----------|
+| AGT-001 | Research Agent com acesso a web search |
+| AGT-002 | Research Agent com RAG (vector search) |
+| AGT-003 | Analysis Agent para comparações |
+| AGT-004 | Analysis Agent para insights |
+| AGT-005 | Writing Agent para relatórios |
+| AGT-006 | Writing Agent para sumários |
+
+### 3.4 Plugins
+
+| ID | Requisito |
+|----|-----------|
+| PLG-001 | WebSearch via Bing API |
+| PLG-002 | Document retrieval via vector store |
+| PLG-003 | Calculator para análises numéricas |
+| PLG-004 | Date/Time utilities |
+
+### 3.5 Memória
+
+| ID | Requisito |
+|----|-----------|
+| MEM-001 | Conversation memory por sessão |
+| MEM-002 | Semantic memory para contexto relevante |
+| MEM-003 | Persistência opcional em Cosmos DB |
+
+## 4. Requisitos Não-Funcionais
+
+### 4.1 Performance
+
+| ID | Requisito |
+|----|-----------|
+| PERF-001 | Response streaming para UX fluida |
+| PERF-002 | Timeout máximo de 60s por request |
+| PERF-003 | Execução paralela de subtarefas independentes |
+
+### 4.2 Custo
+
+| ID | Requisito |
+|----|-----------|
+| COST-001 | Limite de tokens por request configurável |
+| COST-002 | Uso de modelos menores para subtarefas simples |
+| COST-003 | Cache de resultados de pesquisa |
+| COST-004 | Tracking de uso de tokens |
+
+### 4.3 Segurança
+
+| ID | Requisito |
+|----|-----------|
+| SEC-001 | API Key authentication |
+| SEC-002 | Rate limiting por API key |
+| SEC-003 | Input sanitization |
+| SEC-004 | Output filtering (PII, harmful content) |
+
+## 5. Agentes em Detalhe
+
+### 5.1 Orchestrator Agent
+
+**System Prompt**:
+```
+You are an orchestrator agent responsible for coordinating other specialized agents.
+
+When you receive a user request:
+1. Analyze the intent and complexity
+2. Decompose into subtasks if needed
+3. Delegate to appropriate specialist agents
+4. Aggregate and format the final response
+
+Available agents:
+- research: For information gathering, web search, document retrieval
+- analysis: For data analysis, comparisons, insight generation
+- writing: For text generation, summaries, reports
+
+Respond with a plan in JSON format:
+{
+  "understanding": "Brief summary of user's request",
+  "subtasks": [
+    {"agent": "research", "task": "specific task description"},
+    {"agent": "analysis", "task": "specific task description"},
+    {"agent": "writing", "task": "specific task description"}
+  ]
+}
+```
+
+### 5.2 Research Agent
+
+**System Prompt**:
+```
+You are a research specialist agent. Your capabilities include:
+- Searching the web for current information
+- Retrieving relevant documents from the knowledge base
+- Summarizing and extracting key information
+
+When researching:
+1. Use web_search for current/recent information
+2. Use document_search for internal knowledge
+3. Synthesize findings into structured data
+
+Always cite your sources and indicate confidence level.
+```
+
+**Plugins**:
+- `web_search(query, max_results)`
+- `document_search(query, limit)`
+
+### 5.3 Analysis Agent
+
+**System Prompt**:
+```
+You are an analysis specialist agent. Your capabilities include:
+- Analyzing data and identifying patterns
+- Comparing options and alternatives
+- Generating insights and recommendations
+
+When analyzing:
+1. Structure the data clearly
+2. Apply appropriate analytical frameworks
+3. Provide evidence-based conclusions
+
+Be objective and highlight trade-offs.
+```
+
+**Plugins**:
+- `calculate(expression)`
+- `compare(items, criteria)`
+
+### 5.4 Writing Agent
+
+**System Prompt**:
+```
+You are a writing specialist agent. Your capabilities include:
+- Generating clear, well-structured text
+- Creating summaries and reports
+- Adapting tone and style for the audience
+
+When writing:
+1. Start with a clear structure
+2. Use appropriate formatting
+3. Be concise but comprehensive
+
+Match the requested format (report, summary, email, etc.).
+```
+
+## 6. Plugins em Detalhe
+
+### 6.1 WebSearchPlugin
+
+```csharp
+public class WebSearchPlugin
+{
+    private readonly BingSearchService _searchService;
+
+    [KernelFunction("web_search")]
+    [Description("Search the web for information on a topic")]
+    public async Task<SearchResults> SearchAsync(
+        [Description("The search query")] string query,
+        [Description("Maximum results to return")] int maxResults = 5)
+    {
+        var results = await _searchService.SearchAsync(query, maxResults);
+        return new SearchResults
+        {
+            Query = query,
+            Items = results.Select(r => new SearchResult
+            {
+                Title = r.Title,
+                Snippet = r.Snippet,
+                Url = r.Url
+            }).ToList()
+        };
+    }
+}
+```
+
+### 6.2 DocumentPlugin
+
+```csharp
+public class DocumentPlugin
+{
+    private readonly IVectorStore _vectorStore;
+    private readonly IEmbeddingService _embeddingService;
+
+    [KernelFunction("document_search")]
+    [Description("Search internal documents using semantic similarity")]
+    public async Task<IEnumerable<DocumentResult>> SearchDocumentsAsync(
+        [Description("The search query")] string query,
+        [Description("Maximum documents")] int limit = 3)
+    {
+        var embedding = await _embeddingService.GetEmbeddingAsync(query);
+        var documents = await _vectorStore.SearchAsync(embedding, limit);
+
+        return documents.Select(d => new DocumentResult
+        {
+            Title = d.Title,
+            Content = d.Content,
+            Score = d.Score,
+            Source = d.Source
+        });
+    }
+}
+```
+
+## 7. APIs
+
+### 7.1 Chat Endpoint
+
+```
+POST /api/chat
+Content-Type: application/json
+
+{
+  "message": "Compare AWS, Azure and GCP for a SaaS startup",
+  "sessionId": "optional-session-id",
+  "stream": true
+}
+
+Response (streaming):
+data: {"type": "thinking", "content": "Analyzing request..."}
+data: {"type": "agent", "agent": "research", "status": "started"}
+data: {"type": "agent", "agent": "research", "status": "completed"}
+data: {"type": "content", "content": "Based on my analysis..."}
+data: {"type": "done", "usage": {"tokens": 1234}}
+```
+
+### 7.2 Agents Endpoint
+
+```
+GET /api/agents
+
+Response:
+{
+  "agents": [
+    {
+      "id": "orchestrator",
+      "name": "Orchestrator Agent",
+      "description": "Coordinates other agents",
+      "capabilities": ["task_decomposition", "routing", "aggregation"]
+    },
+    {
+      "id": "research",
+      "name": "Research Agent",
+      "description": "Information gathering specialist",
+      "capabilities": ["web_search", "document_retrieval", "summarization"]
+    }
+  ]
+}
+```
+
+## 8. Modelo de Dados
+
+### 8.1 Conversation
+
+```csharp
+public class Conversation
+{
+    public string Id { get; set; }
+    public string UserId { get; set; }
+    public List<Message> Messages { get; set; }
+    public DateTime CreatedAt { get; set; }
+    public DateTime UpdatedAt { get; set; }
+}
+
+public class Message
+{
+    public string Id { get; set; }
+    public MessageRole Role { get; set; } // User, Assistant, System
+    public string Content { get; set; }
+    public AgentMetadata? AgentMetadata { get; set; }
+    public TokenUsage? Usage { get; set; }
+    public DateTime Timestamp { get; set; }
+}
+
+public class AgentMetadata
+{
+    public string AgentId { get; set; }
+    public List<string> PluginsUsed { get; set; }
+    public Dictionary<string, object> Metadata { get; set; }
+}
+```
+
+### 8.2 Agent Task
+
+```csharp
+public class AgentTask
+{
+    public string Id { get; set; }
+    public string AgentId { get; set; }
+    public string Description { get; set; }
+    public TaskStatus Status { get; set; }
+    public string? Input { get; set; }
+    public string? Output { get; set; }
+    public string? Error { get; set; }
+    public TimeSpan Duration { get; set; }
+    public TokenUsage Usage { get; set; }
+}
+
+public enum TaskStatus
+{
+    Pending,
+    Running,
+    Completed,
+    Failed
+}
+```
+
+## 9. Configuração
+
+### 9.1 Azure OpenAI
+
+```json
+{
+  "AzureOpenAI": {
+    "Endpoint": "https://{resource}.openai.azure.com/",
+    "ApiKey": "{key}",
+    "Deployments": {
+      "Chat": "gpt-4",
+      "ChatFast": "gpt-35-turbo",
+      "Embedding": "text-embedding-ada-002"
+    }
+  }
+}
+```
+
+### 9.2 Agent Configuration
+
+```json
+{
+  "Agents": {
+    "Orchestrator": {
+      "Model": "gpt-4",
+      "MaxTokens": 2000,
+      "Temperature": 0.3
+    },
+    "Research": {
+      "Model": "gpt-35-turbo",
+      "MaxTokens": 1500,
+      "Temperature": 0.5
+    },
+    "Analysis": {
+      "Model": "gpt-35-turbo",
+      "MaxTokens": 1500,
+      "Temperature": 0.3
+    },
+    "Writing": {
+      "Model": "gpt-4",
+      "MaxTokens": 3000,
+      "Temperature": 0.7
+    }
+  }
+}
+```
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.morph/examples/multi-agent/tasks.md

@@ -0,0 +1,185 @@
+# Multi-Agent System - Tasks
+
+## Fase 1: Setup do Projeto
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T001 | Criar solution e projetos | - | S |
+| T002 | Configurar packages (Semantic Kernel, etc) | T001 | S |
+| T003 | Configurar appsettings.json | T001 | S |
+| T004 | Criar estrutura de pastas | T001 | S |
+
+## Fase 2: Infrastructure Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T005 | Implementar AzureOpenAIService | T002 | M |
+| T006 | Implementar EmbeddingService | T005 | M |
+| T007 | Implementar InMemoryVectorStore | T006 | M |
+| T008 | Implementar ConversationStore (in-memory) | T002 | M |
+
+## Fase 3: Plugin Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T009 | Criar WebSearchPlugin | T005 | M |
+| T010 | Configurar Bing Search API | T009 | S |
+| T011 | Criar DocumentPlugin | T007 | M |
+| T012 | Criar CalculatorPlugin | T005 | S |
+| T013 | Criar DateTimePlugin | T005 | S |
+
+## Fase 4: Agent Layer - Base
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T014 | Criar BaseAgent abstract class | T005 | M |
+| T015 | Implementar AgentFactory | T014 | M |
+| T016 | Criar AgentContext (DI scope) | T015 | M |
+
+## Fase 5: Agent Layer - Agents
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T017 | Implementar ResearchAgent | T014, T009, T011 | L |
+| T018 | Implementar AnalysisAgent | T014, T012 | M |
+| T019 | Implementar WritingAgent | T014 | M |
+| T020 | Implementar OrchestratorAgent | T017-T019 | L |
+
+## Fase 6: Orchestration Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T021 | Implementar TaskDecomposer | T020 | M |
+| T022 | Implementar AgentRouter | T015, T021 | M |
+| T023 | Implementar ResultAggregator | T020 | M |
+| T024 | Implementar Orchestrator | T021-T023 | L |
+
+## Fase 7: Memory Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T025 | Implementar ConversationMemory | T008 | M |
+| T026 | Implementar SemanticMemory | T007 | M |
+| T027 | Integrar memória com Orchestrator | T024-T026 | M |
+
+## Fase 8: API Layer
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T028 | Configurar Program.cs base | T001 | M |
+| T029 | Criar ChatEndpoints | T024, T027 | M |
+| T030 | Implementar streaming (SSE) | T029 | M |
+| T031 | Criar AgentEndpoints | T015 | S |
+| T032 | Criar HealthEndpoints | T028 | S |
+| T033 | Configurar API Key auth | T028 | S |
+
+## Fase 9: Error Handling & Resilience
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T034 | Implementar retry policies | T024 | M |
+| T035 | Implementar circuit breaker | T034 | M |
+| T036 | Implementar timeout handling | T024 | M |
+| T037 | Criar error logging middleware | T028 | S |
+
+## Fase 10: Monitoring & Metrics
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T038 | Implementar token tracking | T005 | M |
+| T039 | Implementar usage metrics | T038 | M |
+| T040 | Criar cost estimation | T039 | S |
+| T041 | Integrar com App Insights | T028 | M |
+
+## Fase 11: Infrastructure (IaC)
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T042 | Criar main.bicep | - | M |
+| T043 | Configurar Container App | T042 | M |
+| T044 | Configurar Azure OpenAI (manual) | - | M |
+| T045 | Configurar Key Vault | T042 | S |
+| T046 | Configurar App Insights | T042 | S |
+
+## Fase 12: Testes
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T047 | Criar testes unitários - Plugins | T009-T013 | M |
+| T048 | Criar testes unitários - Agents | T017-T020 | M |
+| T049 | Criar testes integração - Orchestrator | T024 | L |
+| T050 | Criar testes E2E - API | T029-T032 | L |
+
+## Fase 13: Documentação
+
+| ID | Task | Dependências | Estimativa |
+|----|------|--------------|------------|
+| T051 | Documentar APIs (OpenAPI) | T029-T032 | M |
+| T052 | Criar guia de extensibilidade | T014-T020 | M |
+| T053 | Criar exemplos de uso | T029 | M |
+
+## Checkpoints
+
+| Checkpoint | Após Tasks | Validação |
+|------------|------------|-----------|
+| CP1 | T004 | Projeto compila |
+| CP2 | T008 | Infrastructure funcionando |
+| CP3 | T013 | Plugins funcionando |
+| CP4 | T020 | Agents funcionando |
+| CP5 | T024 | Orchestrator funcionando |
+| CP6 | T027 | Memória integrada |
+| CP7 | T033 | API completa |
+| CP8 | T037 | Error handling completo |
+| CP9 | T041 | Monitoring ativo |
+| CP10 | T046 | IaC pronto |
+| CP11 | T053 | Projeto completo |
+
+## Legenda
+
+- **S** = Small (< 1h)
+- **M** = Medium (1-3h)
+- **L** = Large (3-8h)
+
+## Dependências Críticas
+
+```
+Azure OpenAI Setup (T044) - BLOQUEANTE para todos os testes reais
+
+T005 (LLM Service) → T014 (BaseAgent) → T017-T020 (Agents) → T024 (Orchestrator)
+           ↓
+       T006 (Embedding) → T007 (VectorStore) → T011 (DocumentPlugin)
+           ↓
+       T009 (WebSearch) → T017 (ResearchAgent)
+```
+
+## Ordem de Execução Recomendada
+
+### Fase Paralela 1 (Setup)
+- T001-T004 (Setup)
+- T042 (IaC base)
+
+### Fase Paralela 2 (Foundation)
+- T005-T008 (Infrastructure)
+- T044 (Azure OpenAI manual)
+
+### Fase Paralela 3 (Building Blocks)
+- T009-T013 (Plugins)
+- T014-T016 (Agent base)
+
+### Fase Sequencial 4 (Core)
+- T017-T020 (Agents)
+- T021-T024 (Orchestration)
+- T025-T027 (Memory)
+
+### Fase Paralela 5 (API + Supporting)
+- T028-T033 (API)
+- T034-T037 (Resilience)
+- T038-T041 (Monitoring)
+
+### Fase Final
+- T043-T046 (IaC complete)
+- T047-T053 (Tests + Docs)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech*

package/content/.morph/features/.gitkeep

@@ -0,0 +1,25 @@
+# Features em Desenvolvimento
+
+Esta pasta contém as features ATIVAS em desenvolvimento.
+
+## Estrutura
+
+```
+features/
+└── {feature-name}/
+    ├── proposal.md    # Proposta (por que e o quê)
+    ├── spec.md        # Especificação técnica
+    ├── tasks.md       # Checklist de implementação
+    ├── contracts.cs   # Interfaces e DTOs
+    ├── decisions.md   # ADRs
+    └── recap.md       # Resumo pós-implementação
+```
+
+## Workflow
+
+1. `/morph-proposal {feature}` - Criar nova feature
+2. Revisar e aprovar proposal
+3. `/morph-apply {feature}` - Implementar
+4. `/morph-archive {feature}` - Arquivar quando concluída
+
+*Gerado pelo MORPH Framework*