@maestro-ai/mcp-server 1.2.0 → 2.1.0

package/dist/content/skills/specialist-performance-escalabilidade/SKILL.md

@@ -0,0 +1,329 @@
+---
+name: specialist-performance-escalabilidade
+description: Perfis de carga, caching, tuning e auto-scaling para alto volume.
+allowed-tools: Read, Write, Edit, Glob, Grep
+---
+
+# Performance e Escalabilidade · Skill do Especialista
+
+## Missão
+Garantir que o sistema suporte milhões de requisições com desempenho, aplicando perfis de carga, caching, tuning e auto-scaling para alto volume.
+
+## Quando ativar
+- Fase: Especialista Avançado
+- Workflows recomendados: /corrigir-bug, /maestro
+- Use quando precisar em projetos com SLOs agressivos ou problemas de performance.
+
+## Inputs obrigatórios
+- Requisitos de performance
+- Métricas atuais
+- Cenários de pico
+- Arquitetura existente
+- CONTEXTO.md do projeto
+
+## Outputs gerados
+- Planos de teste de carga
+- Estratégias de caching e tuning
+- Configuração de auto-scaling
+- Relatórios de performance
+- Recomendações de otimização
+
+## Quality Gate
+- SLOs definidos e medidos
+- Testes de carga executados
+- Otimizações implementadas
+- Auto-scaling configurado
+- Monitoramento ativo
+
+## Performance Engineering
+
+### SLOs e SLIs
+```text
+Defina métricas claras:
+- Latency: p95 < 100ms, p99 < 500ms
+- Throughput: > 1000 RPS
+- Error Rate: < 0.1%
+- Availability: 99.9%
+- Resource Utilization: < 80%
+```
+
+### Performance Testing
+```bash
+# Load testing com k6
+k6 run --vus 100 --duration 5m script.js
+
+# Stress testing
+k6 run --vus 1000 --duration 10m stress-test.js
+
+# Soak testing
+k6 run --vus 50 --duration 24h soak-test.js
+```
+
+## Caching Strategies
+
+### Multi-Level Caching
+```text
+Implemente cache hierarchy:
+1. Browser Cache (Client-side)
+2. CDN Cache (Edge)
+3. Application Cache (Redis/Memcached)
+4. Database Cache (Query cache)
+5. Static Cache (CDN + CloudFront)
+```
+
+### Cache Patterns
+- **Cache-Aside:** Application manages cache
+- **Read-Through:** Cache manages misses
+- **Write-Through:** Write to cache and DB
+- **Write-Behind:** Async write to DB
+- **Refresh-Ahead:** Proactive cache refresh
+
+## Optimization Techniques
+
+### Database Optimization
+```sql
+-- Indexes estratégicos
+CREATE INDEX CONCURRENTLY idx_user_email_active 
+ON users(email) WHERE active = true;
+
+-- Query optimization
+EXPLAIN ANALYZE SELECT * FROM orders 
+WHERE user_id = $1 AND created_at > $2;
+```
+
+### Application Optimization
+```javascript
+// Connection pooling
+const pool = new Pool({
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+// Async processing
+await Promise.all([
+  fetchUser(id),
+  fetchOrders(id),
+  fetchProfile(id)
+]);
+```
+
+## Auto-Scaling Strategies
+
+### Horizontal Scaling
+```yaml
+# Kubernetes HPA
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: app-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: app
+  minReplicas: 2
+  maxReplicas: 100
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: 70
+```
+
+### Vertical Scaling
+```yaml
+# Kubernetes VPA
+apiVersion: autoscaling.k8s.io/v1
+kind: VerticalPodAutoscaler
+metadata:
+  name: app-vpa
+spec:
+  targetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: app
+  updatePolicy:
+    updateMode: Auto
+```
+
+## Processo de Performance Engineering
+
+### 1. Baseline Establishment
+```text
+Meça performance atual:
+- Latency por endpoint
+- Throughput por serviço
+- Resource utilization
+- Error rates
+- Database query times
+```
+
+### 2. Bottleneck Identification
+```text
+Identifique gargalos:
+- CPU-bound vs I/O-bound
+- Database queries lentas
+- Network latency
+- Memory leaks
+- Contention points
+```
+
+### 3. Optimization Implementation
+```text
+Aplique otimizações:
+- Database indexing
+- Caching strategies
+- Code optimization
+- Resource allocation
+- Architecture changes
+```
+
+### 4. Validation
+```text
+Valide melhorias:
+- Load testing pós-otimização
+- Compare baseline vs optimized
+- Monitor production metrics
+- Validate SLO achievement
+```
+
+## Guardrails Críticos
+
+### NUNCA Faça
+- **NUNCA** otimize sem medição
+- **NUNCA** ignore SLOs em produção
+- **NUNCA** cache dados sensíveis sem TTL
+- **NUNCA** scale sem monitoramento
+
+### SEMPRE Faça
+- **SEMPRE** meça antes de otimizar
+- **SEMPRE** defina SLOs claros
+- **SEMPRE** monitore em produção
+- **SEMPRE** teste load antes de deploy
+
+## Context Flow
+
+### Artefatos Obrigatórios para Iniciar
+Cole no início:
+1. Requisitos de performance
+2. Métricas atuais do sistema
+3. Cenários de pico esperados
+4. Arquitetura existente
+5. CONTEXTO.md com restrições
+
+### Prompt de Continuação
+```
+Atue como Performance Engineer Sênior.
+
+Contexto do projeto:
+[COLE docs/CONTEXTO.md]
+
+Requisitos de performance:
+[COLE REQUISITOS DE PERFORMANCE]
+
+Métricas atuais:
+[COLE MÉTRICAS ATUAIS]
+
+Preciso garantir que o sistema suporte [NÚMERO] requisições com performance adequada.
+```
+
+### Ao Concluir Esta Fase
+1. **Defina** SLOs e SLIs
+2. **Implemente** caching strategies
+3. **Configure** auto-scaling
+4. **Otimize** bottlenecks
+5. **Teste** load scenarios
+6. **Monitore** production
+
+## Métricas de Performance
+
+### Indicadores Obrigatórios
+- **Latency:** p95 < 100ms, p99 < 500ms
+- **Throughput:** > 1000 RPS
+- **Error Rate:** < 0.1%
+- **Availability:** 99.9%
+- **Resource Utilization:** < 80%
+- **Cache Hit Rate:** > 90%
+
+### Metas de Excelência
+- Latency: p95 < 50ms, p99 < 200ms
+- Throughput: > 5000 RPS
+- Error Rate: < 0.01%
+- Availability: 99.99%
+- Cache Hit Rate: > 95%
+
+## Templates Prontos
+
+### Load Testing Script (k6)
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+
+export let options = {
+  stages: [
+    { duration: '2m', target: 100 },
+    { duration: '5m', target: 100 },
+    { duration: '2m', target: 200 },
+    { duration: '5m', target: 200 },
+    { duration: '2m', target: 0 },
+  ],
+};
+
+export default function () {
+  let response = http.get('https://api.example.com/users');
+  check(response, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 200ms': (r) => r.timings.duration < 200,
+  });
+  sleep(1);
+}
+```
+
+### Performance Report
+```markdown
+# Performance Test Report
+
+## Test Configuration
+- **Tool:** k6
+- **Duration:** 14 minutes
+- **Peak Load:** 200 VUs
+- **Target:** https://api.example.com
+
+## Results Summary
+- **Total Requests:** 12,000
+- **Average Response Time:** 145ms
+- **95th Percentile:** 280ms
+- **99th Percentile:** 450ms
+- **Error Rate:** 0.2%
+- **Throughput:** 14.3 RPS
+
+## Bottlenecks Identified
+1. **Database:** Slow queries on user profile
+2. **Memory:** High memory usage at peak load
+3. **Network:** Latency spikes at 150+ VUs
+
+## Recommendations
+1. Add database indexes for profile queries
+2. Implement connection pooling
+3. Add CDN for static assets
+4. Optimize memory usage
+```
+
+## Skills complementares
+- `performance-profiling`
+- `systematic-debugging`
+- `database-design`
+- `deployment-procedures`
+- `monitoring-setup`
+
+## Referências essenciais
+- **Especialista original:** `content/specialists/Especialista em Performance e Escalabilidade.md`
+- **Artefatos alvo:**
+  - Planos de teste de carga
+  - Estratégias de caching e tuning
+  - Configuração de auto-scaling
+  - Relatórios de performance
+  - Recomendações de otimização

package/dist/content/skills/specialist-plano-execucao-ia/MCP_INTEGRATION.md

@@ -0,0 +1,371 @@
+# Integração MCP - Plano de Execução
+
+**Versão:** 2.0  
+**Última Atualização:** 31/01/2026  
+**Especialista:** Plano de Execução com IA
+
+---
+
+## 🎯 Visão Geral da Integração MCP
+
+Este documento descreve como o MCP (Maestro Command Processor) automatiza o processo de planejamento de execução, desde a inicialização da estrutura de backlog até a validação de qualidade e preparação para a próxima fase.
+
+### **Princípios de Integração**
+
+- **Skill Descritiva:** Este especialista contém apenas informações e processos
+- **Automação Externa:** Toda lógica de execução está no MCP
+- **Quality Gates:** Validação automatizada com score mínimo de 75/100
+- **Context Flow:** Dados fluem automaticamente entre fases
+
+---
+
+## 🤖 Funções MCP Disponíveis
+
+### **1. init_backlog_structure**
+
+**Propósito:** Inicializar estrutura de backlog a partir de documentos de entrada
+
+**Input:**
+```typescript
+{
+  prd: string;              // Conteúdo do PRD.md
+  requisitos: string;       // Conteúdo do requisitos.md
+  designDoc: string;        // Conteúdo do design-doc.md
+  arquitetura: string;      // Conteúdo do arquitetura.md
+  contexto: string;         // Conteúdo do CONTEXTO.md
+  capacidadeTime?: {        // Opcional
+    desenvolvedores: number;
+    duracaoSprint: number;  // em semanas
+    deadlines?: string[];
+  }
+}
+```
+
+**Output:**
+```typescript
+{
+  backlog: {
+    epicos: Epico[];
+    features: Feature[];
+    timeline: Timeline;
+    metricas: Metricas;
+  };
+  estruturaArquivos: {
+    backlogMd: string;      // Conteúdo do backlog.md
+    features: FeatureFile[]; // Arquivos de features
+    contratos: ContratoFile[]; // Arquivos de contratos API
+  };
+  proximaFase: string;      // Nome da próxima fase
+}
+```
+
+**Processo:**
+1. Analisa todos os documentos de entrada
+2. Identifica épicos principais do PRD
+3. Mapeia requisitos funcionais para features
+4. Separa features por tipo (CONT, FE, BE, INT)
+5. Define dependências entre features
+6. Calcula timeline com buffer de 20%
+7. Gera estrutura de arquivos
+
+**Exemplo de Uso:**
+```typescript
+const resultado = await mcp.initBacklogStructure({
+  prd: await readFile('docs/01-produto/PRD.md'),
+  requisitos: await readFile('docs/02-requisitos/requisitos.md'),
+  designDoc: await readFile('docs/03-ux/design-doc.md'),
+  arquitetura: await readFile('docs/06-arquitetura/arquitetura.md'),
+  contexto: await readFile('docs/CONTEXTO.md'),
+  capacidadeTime: {
+    desenvolvedores: 2,
+    duracaoSprint: 2,
+    deadlines: ['2026-03-15']
+  }
+});
+
+// Salvar arquivos gerados
+await writeFile('docs/08-backlog/backlog.md', resultado.estruturaArquivos.backlogMd);
+```
+
+---
+
+### **2. validate_backlog_quality**
+
+**Propósito:** Validar qualidade do backlog gerado com checklist automatizado
+
+**Input:**
+```typescript
+{
+  backlogMd: string;        // Conteúdo do backlog.md
+  features: FeatureFile[];  // Arquivos de features
+  contratos: ContratoFile[]; // Arquivos de contratos
+  strictMode?: boolean;     // Modo rigoroso (default: false)
+}
+```
+
+**Output:**
+```typescript
+{
+  score: number;            // 0-100
+  aprovado: boolean;        // true se score >= 75
+  detalhes: {
+    estruturaBacklog: {
+      score: number;        // 0-25
+      itens: ChecklistItem[];
+    };
+    qualidadeHistorias: {
+      score: number;        // 0-30
+      itens: ChecklistItem[];
+    };
+    rastreabilidade: {
+      score: number;        // 0-20
+      itens: ChecklistItem[];
+    };
+    planejamento: {
+      score: number;        // 0-25
+      itens: ChecklistItem[];
+    };
+  };
+  recomendacoes: string[];  // Sugestões de melhoria
+}
+```
+
+**Checklist Automatizado:**
+
+**1. Estrutura do Backlog (25 pontos):**
+- ✅ Épicos claramente definidos (5 pts)
+- ✅ Features mapeadas para épicos (5 pts)
+- ✅ Histórias mapeadas para features (5 pts)
+- ✅ Priorização RICE aplicada (5 pts)
+- ✅ Dependências identificadas (5 pts)
+
+**2. Qualidade das Histórias (30 pontos):**
+- ✅ Formato "Como [persona], quero [ação], para [benefício]" (8 pts)
+- ✅ Critérios de aceite em Gherkin (8 pts)
+- ✅ Estimativas de esforço (7 pts)
+- ✅ Dependências técnicas (7 pts)
+
+**3. Rastreabilidade (20 pontos):**
+- ✅ Histórias → Requisitos (7 pts)
+- ✅ Histórias → Design (7 pts)
+- ✅ Matriz de rastreabilidade (6 pts)
+
+**4. Planejamento (25 pontos):**
+- ✅ Sprints definidos (7 pts)
+- ✅ Releases planejados (6 pts)
+- ✅ Riscos identificados (6 pts)
+- ✅ Buffer de 20% (6 pts)
+
+**Exemplo de Uso:**
+```typescript
+const validacao = await mcp.validateBacklogQuality({
+  backlogMd: await readFile('docs/08-backlog/backlog.md'),
+  features: await readFeatures('docs/08-backlog/features/'),
+  contratos: await readContratos('docs/08-backlog/contratos/'),
+  strictMode: false
+});
+
+if (!validacao.aprovado) {
+  console.log(`Score: ${validacao.score}/100 - BLOQUEADO`);
+  console.log('Recomendações:', validacao.recomendacoes);
+} else {
+  console.log(`Score: ${validacao.score}/100 - APROVADO`);
+}
+```
+
+---
+
+### **3. process_backlog_to_next_phase**
+
+**Propósito:** Preparar backlog para desenvolvimento e avançar para próxima fase
+
+**Input:**
+```typescript
+{
+  backlogMd: string;
+  features: FeatureFile[];
+  contratos: ContratoFile[];
+  validacao: ValidationResult; // Resultado de validate_backlog_quality
+}
+```
+
+**Output:**
+```typescript
+{
+  proximaFase: {
+    nome: string;           // "Contrato de API" ou "Desenvolvimento"
+    especialista: string;   // Nome do próximo especialista
+    artefatosEntrada: string[]; // Arquivos necessários
+  };
+  historiasProximas: Historia[]; // Histórias prioritárias
+  contextoPrepared: {
+    backlogResumo: string;
+    epicosAtivos: Epico[];
+    dependenciasCriticas: Dependencia[];
+  };
+  atualizacoes: {
+    contextoMd: string;     // Atualização do CONTEXTO.md
+    statusMd: string;       // Atualização do STATUS.md
+  };
+}
+```
+
+**Processo:**
+1. Valida que score >= 75 (ou aprovação manual)
+2. Identifica próxima fase (Contrato API ou Desenvolvimento)
+3. Prepara histórias prioritárias para sprint 1
+4. Atualiza CONTEXTO.md com resumo do planejamento
+5. Registra métricas de planejamento
+6. Retorna dados para próximo especialista
+
+**Exemplo de Uso:**
+```typescript
+const proximaFase = await mcp.processBacklogToNextPhase({
+  backlogMd: await readFile('docs/08-backlog/backlog.md'),
+  features: await readFeatures('docs/08-backlog/features/'),
+  contratos: await readContratos('docs/08-backlog/contratos/'),
+  validacao: resultadoValidacao
+});
+
+// Atualizar arquivos
+await writeFile('docs/CONTEXTO.md', proximaFase.atualizacoes.contextoMd);
+await writeFile('docs/STATUS.md', proximaFase.atualizacoes.statusMd);
+
+console.log(`Próxima fase: ${proximaFase.proximaFase.nome}`);
+console.log(`Especialista: ${proximaFase.proximaFase.especialista}`);
+```
+
+---
+
+## 🔄 Fluxo de Integração Completo
+
+### **Sequência de Chamadas MCP**
+
+```typescript
+// 1. Inicializar backlog
+const backlog = await mcp.initBacklogStructure({
+  prd, requisitos, designDoc, arquitetura, contexto
+});
+
+// 2. Salvar arquivos gerados
+await saveBacklogFiles(backlog.estruturaArquivos);
+
+// 3. Validar qualidade
+const validacao = await mcp.validateBacklogQuality({
+  backlogMd: backlog.estruturaArquivos.backlogMd,
+  features: backlog.estruturaArquivos.features,
+  contratos: backlog.estruturaArquivos.contratos
+});
+
+// 4. Se aprovado, processar para próxima fase
+if (validacao.aprovado) {
+  const proximaFase = await mcp.processBacklogToNextPhase({
+    backlogMd: backlog.estruturaArquivos.backlogMd,
+    features: backlog.estruturaArquivos.features,
+    contratos: backlog.estruturaArquivos.contratos,
+    validacao
+  });
+  
+  // 5. Avançar para próximo especialista
+  await loadNextSpecialist(proximaFase.proximaFase.especialista);
+}
+```
+
+---
+
+## 📊 Quality Gates e Thresholds
+
+### **Score Mínimo**
+- **Padrão:** 75/100 pontos
+- **Modo Rigoroso:** 85/100 pontos
+- **Aprovação Manual:** Permitida com justificativa
+
+### **Critérios de Bloqueio**
+
+**Bloqueio Automático (Score < 70):**
+- Histórias sem critérios de aceite
+- Épicos sem features
+- Timeline sem buffer
+- Dependências não mapeadas
+
+**Aviso (Score 70-74):**
+- Estimativas incompletas
+- Rastreabilidade parcial
+- Riscos não documentados
+
+**Aprovado (Score >= 75):**
+- Todos os critérios obrigatórios atendidos
+- Pode avançar automaticamente
+
+---
+
+## 🎯 Context Flow
+
+### **Dados Recebidos de Fases Anteriores**
+
+| Fase | Artefato | Uso |
+|------|----------|-----|
+| Gestão de Produto | PRD.md | Identificar épicos e MVP |
+| Engenharia de Requisitos | requisitos.md | Mapear RFs para histórias |
+| UX Design | design-doc.md | Rastrear histórias para wireframes |
+| Arquitetura de Software | arquitetura.md | Definir stack e separação FE/BE |
+
+### **Dados Enviados para Próximas Fases**
+
+| Fase | Artefato | Conteúdo |
+|------|----------|----------|
+| Contrato de API | contratos/*.yaml | Especificações OpenAPI |
+| Desenvolvimento Frontend | features/FE-*.md | Histórias frontend |
+| Desenvolvimento Backend | features/BE-*.md | Histórias backend |
+| Integração | features/INT-*.md | Histórias de integração |
+
+---
+
+## 📝 Implementação de Referência
+
+As funções MCP descritas acima são **referências** para implementação no servidor MCP. O diretório `mcp_functions/` contém:
+
+- `init_backlog_structure.py` - Implementação de referência da função 1
+- `validate_backlog_quality.py` - Implementação de referência da função 2
+- `process_backlog_to_next_phase.py` - Implementação de referência da função 3
+- `README.md` - Documentação das funções
+
+**Nota:** Estas são funções de **referência** e devem ser implementadas no servidor MCP, não executadas localmente.
+
+---
+
+## 🔧 Troubleshooting
+
+### **Problema: Score baixo na validação**
+
+**Causa:** Histórias incompletas ou sem critérios de aceite
+
+**Solução:**
+1. Revisar checklist de validação
+2. Completar campos obrigatórios
+3. Adicionar critérios de aceite em Gherkin
+4. Re-executar validação
+
+### **Problema: Dependências circulares**
+
+**Causa:** Features dependem umas das outras em loop
+
+**Solução:**
+1. Revisar mapeamento de dependências
+2. Quebrar features em partes menores
+3. Definir ordem de execução clara
+
+### **Problema: Timeline irrealista**
+
+**Causa:** Estimativas muito otimistas ou sem buffer
+
+**Solução:**
+1. Adicionar buffer de 20% mínimo
+2. Revisar estimativas com time
+3. Considerar riscos e impedimentos
+
+---
+
+**Versão:** 2.0  
+**Framework:** Skills Modernas com Progressive Disclosure  
+**Arquitetura:** Skill Descritiva + Automação MCP