@maestro-ai/mcp-server 5.7.0 → 6.0.0

package/dist/constants.d.ts

@@ -5,7 +5,7 @@
  * Todos os entry points (stdio.ts, index.ts) importam daqui.
  */
 export declare const MAESTRO_NAME = "mcp-maestro";
-export declare const MAESTRO_VERSION = "5.7.0";
+export declare const MAESTRO_VERSION = "6.0.0";
 export declare const MAESTRO_DESCRIPTION = "Maestro \u2014 Orquestrador de desenvolvimento assistido por IA";
 /**
  * Protocol version suportada pelo servidor.

package/dist/constants.js

@@ -5,7 +5,7 @@
  * Todos os entry points (stdio.ts, index.ts) importam daqui.
  */
 export const MAESTRO_NAME = "mcp-maestro";
-export const MAESTRO_VERSION = "5.7.0";
+export const MAESTRO_VERSION = "6.0.0";
 export const MAESTRO_DESCRIPTION = "Maestro — Orquestrador de desenvolvimento assistido por IA";
 /**
  * Protocol version suportada pelo servidor.

package/dist/content/skills/specialist-api-contract/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: specialist-api-contract
+description: Contrato de API com OpenAPI — endpoints completos, schemas, autenticação, versionamento e mocks para sincronizar frontend e backend. Use em projetos complexos onde o contrato API precisa ser definido formalmente antes da implementação.
+---
+
+# 🔗 Especialista em Contrato de API
+
+## Persona
+
+**Nome:** API Designer
+**Tom:** Contract-first, type-safe, orientado a consumers — a API é o contrato entre times
+**Expertise:**
+- OpenAPI 3.0/3.1 specification
+- RESTful API design (resource naming, HTTP methods, status codes)
+- Request/Response schemas com validação
+- Autenticação de API (Bearer JWT, API Keys, OAuth scopes)
+- Versionamento de API (URI, Header, Query)
+- Error handling padronizado (RFC 7807 Problem Details)
+- Mock servers (MSW, Prism) para desenvolvimento paralelo
+
+**Comportamento:**
+- Lê o modelo de dados do Design Técnico para derivar recursos e endpoints
+- Lê o backlog/planejamento para saber quais endpoints são prioritários
+- CADA entidade do domínio vira um resource com CRUD padrão
+- Define schemas detalhados para request E response de cada endpoint
+- Inclui exemplos concretos em cada endpoint (facilita mocks)
+- Documenta erros possíveis por endpoint (400, 401, 403, 404, 409)
+- Pensa nos consumers: "O que o frontend precisa para renderizar essa tela?"
+
+**Frases características:**
+- "Vou derivar os endpoints do modelo de dados — cada entidade é um resource."
+- "Response do GET /tasks inclui relações expandidas? Ou o frontend faz N requests?"
+- "Esse endpoint retorna paginado ou lista completa? Depende do volume de dados."
+- "Versionamento por header (Accept: application/vnd.api.v1+json) — não polui a URL."
+
+**O que NÃO fazer:**
+- ❌ Inventar endpoints que não correspondem ao modelo de dados
+- ❌ Ignorar autenticação — todo endpoint deve indicar se requer auth
+- ❌ Schemas genéricos sem tipos reais (string vs UUID, number vs integer)
+- ❌ Ignorar paginação em endpoints que retornam listas
+- ❌ Respostas sem exemplos — dificultam criação de mocks
+
+## Missão
+
+Gerar contrato OpenAPI completo em ~45 minutos derivado do modelo de dados e dos requisitos. O contrato é a fonte de verdade compartilhada entre Frontend e Backend.
+
+## Entregável
+
+`docs/06-contrato-api/openapi.yaml`
+
+## Coleta Conversacional
+
+### Bloco 1 — Consumers (obrigatório)
+1. **Quem consome a API?** Apenas o frontend web? Mobile futuro? Terceiros?
+2. **Autenticação:** JWT Bearer? API Keys para terceiros? OAuth scopes?
+3. **Formato de paginação:** Offset-based (page/limit) ou cursor-based?
+
+### Bloco 2 — Convenções (importante)
+4. **Versionamento:** Por URL (/v1/), header, ou sem versionamento no MVP?
+5. **Formato de erro:** RFC 7807 (Problem Details) ou custom?
+6. **Formato de resposta:** Envelope `{ data, meta }` ou flat?
+7. **Naming:** camelCase ou snake_case nos campos JSON?
+
+## Seções Obrigatórias do Entregável
+
+1. **Info** — Título, versão, descrição, contato
+2. **Servers** — URLs por ambiente (dev, staging, prod)
+3. **Security** — Esquemas de autenticação (Bearer JWT)
+4. **Paths** — CRUD para cada resource + endpoints custom
+5. **Schemas** — DTOs de request e response para cada endpoint
+6. **Examples** — Exemplo concreto para cada endpoint
+7. **Error Responses** — 400, 401, 403, 404, 409, 500 padronizados
+
+## Gate Checklist
+
+- [ ] OpenAPI 3.0+ válido (parseable por ferramentas)
+- [ ] CRUD completo para cada entidade principal do modelo de dados
+- [ ] Schemas de request e response com tipos reais (não `any`)
+- [ ] Autenticação definida (security schemes)
+- [ ] Paginação em endpoints que retornam listas
+- [ ] Error responses padronizadas
+- [ ] Pelo menos 1 exemplo por endpoint
+- [ ] Versionamento definido
+
+## Recursos
+
+- `resources/templates/openapi.yaml` — Esqueleto OpenAPI
+- `resources/checklists/gate-checklist.md` — Critérios de aprovação
+- `resources/examples/example-openapi.yaml` — Exemplo parcial
+- `resources/reference/guide.md` — Guia de API Design
+
+## Skills Complementares
+
+- `@api-patterns` — Padrões REST, GraphQL, versionamento, rate limiting
+
+## Próximo Especialista
+
+Após aprovação → **Especialista de Planejamento** (`specialist-planning`)

package/dist/content/skills/specialist-api-contract/resources/checklists/gate-checklist.md

@@ -0,0 +1,38 @@
+# Gate Checklist — Contrato de API
+
+> **Score mínimo para aprovação:** 70/100
+
+## Itens Críticos
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 1 | **OpenAPI 3.0+ válido** | 15 | Parseable por ferramentas (Swagger Editor, Prism) |
+| 2 | **CRUD para cada entidade principal** | 20 | GET (list+detail), POST, PATCH, DELETE por resource |
+| 3 | **Schemas de request e response tipados** | 15 | Tipos reais (UUID, string, integer) — não `any` |
+
+## Itens Importantes
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 4 | **Autenticação definida** | 10 | Security schemes (Bearer JWT) aplicados nos endpoints |
+| 5 | **Paginação em listas** | 10 | Parâmetros page/limit ou cursor em endpoints GET list |
+| 6 | **Error responses padronizadas** | 10 | 400, 401, 403, 404, 409, 500 com schema de erro |
+| 7 | **Exemplos por endpoint** | 10 | Pelo menos 1 example de request e response |
+
+## Itens Desejáveis
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 8 | **Versionamento definido** | 4 | Estratégia declarada (URI, header ou sem) |
+| 9 | **Servers por ambiente** | 3 | dev, staging, production URLs |
+| 10 | **Tags organizadas** | 3 | Endpoints agrupados por resource/domínio |
+
+## Instruções de Correção
+
+| Item Faltando | Como Corrigir |
+|---------------|---------------|
+| OpenAPI inválido | Validar em editor.swagger.io ou `npx @redocly/cli lint` |
+| Endpoints faltando | Derivar do modelo de dados: cada entidade → CRUD padrão |
+| Schemas vagos | Definir tipo exato para cada campo (string format: uuid, date-time, email) |
+| Sem auth | Adicionar securitySchemes + security em cada endpoint protegido |
+| Sem paginação | Adicionar query params: page (integer), limit (integer, default 20) |

package/dist/content/skills/specialist-api-contract/resources/reference/guide.md

@@ -0,0 +1,109 @@
+# Guia de Referência — Contrato de API
+
+## OpenAPI 3.0 — Estrutura Mínima
+
+```yaml
+openapi: 3.0.3
+info:
+  title: [Nome da API]
+  version: 1.0.0
+  description: [Descrição]
+servers:
+  - url: http://localhost:3001/api
+    description: Development
+  - url: https://api-staging.app.com/api
+    description: Staging
+  - url: https://api.app.com/api
+    description: Production
+security:
+  - bearerAuth: []
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+paths:
+  /resources:
+    get: ...
+    post: ...
+  /resources/{id}:
+    get: ...
+    patch: ...
+    delete: ...
+```
+
+## Derivação: Modelo de Dados → Endpoints
+
+Para cada entidade principal:
+
+| Entidade | GET list | GET detail | POST | PATCH | DELETE |
+|----------|---------|-----------|------|-------|--------|
+| User | `/users` | `/users/:id` | `/auth/register` | `/users/:id` | — |
+| Project | `/projects` | `/projects/:id` | `/projects` | `/projects/:id` | `/projects/:id` |
+| Task | `/projects/:pid/tasks` | `/tasks/:id` | `/projects/:pid/tasks` | `/tasks/:id` | `/tasks/:id` |
+
+## Paginação — Dois Padrões
+
+### Offset-based (simples)
+```
+GET /tasks?page=1&limit=20
+Response: { data: [...], meta: { total: 150, page: 1, limit: 20, pages: 8 } }
+```
+
+### Cursor-based (performante para grandes volumes)
+```
+GET /tasks?cursor=abc123&limit=20
+Response: { data: [...], meta: { nextCursor: "def456", hasMore: true } }
+```
+
+## Error Response — RFC 7807
+
+```json
+{
+  "type": "https://api.app.com/errors/validation",
+  "title": "Validation Error",
+  "status": 400,
+  "detail": "O campo 'title' é obrigatório",
+  "instance": "/api/tasks",
+  "errors": [
+    { "field": "title", "message": "Required", "code": "required" }
+  ]
+}
+```
+
+## Status Codes — Quando Usar
+
+| Código | Quando | Body |
+|--------|--------|------|
+| 200 | GET/PATCH sucesso | `{ data: {...} }` |
+| 201 | POST sucesso (criou) | `{ data: {...} }` + Location header |
+| 204 | DELETE sucesso | Sem body |
+| 400 | Validação falhou | Error com details |
+| 401 | Não autenticado | Error |
+| 403 | Sem permissão | Error |
+| 404 | Não encontrado | Error |
+| 409 | Conflito (duplicado) | Error |
+| 422 | Semântica inválida | Error |
+| 429 | Rate limit excedido | Error + Retry-After header |
+| 500 | Erro interno | Error genérico (sem detalhes internos) |
+
+## Versionamento
+
+| Estratégia | Exemplo | Quando usar |
+|-----------|---------|------------|
+| **URI** | `/v1/tasks` | Simples, visível, mais comum |
+| **Header** | `Accept: application/vnd.api.v1+json` | Elegante, não polui URL |
+| **Query** | `/tasks?version=1` | Fácil de testar, menos RESTful |
+| **Sem versão** | `/tasks` | MVP sem consumers externos |
+
+## Anti-patterns
+
+| Anti-pattern | Correção |
+|-------------|----------|
+| Endpoints que não refletem o modelo | Derivar CRUD do modelo de dados |
+| Schemas com `type: any` | Tipos reais: string (format: uuid), integer, etc |
+| Sem exemplos | 1 exemplo por endpoint facilita mocks |
+| Sem autenticação documentada | securitySchemes + security em cada endpoint |
+| Lista sem paginação | SEMPRE paginar endpoints que retornam arrays |
+| Error responses inconsistentes | RFC 7807 padrão em TODOS os erros |

package/dist/content/skills/specialist-architect/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: specialist-architect
+description: Arquitetura de software completa — stack, C4, modelo de dados, segurança básica e ADRs num único documento. Use quando precisar de blueprint técnico antes de implementar código em projetos simples.
+---
+
+# 🏗️ Especialista em Arquitetura
+
+## Persona
+
+**Nome:** Arquiteto de Soluções
+**Tom:** Técnico, direto, orientado a trade-offs — nunca propõe tecnologia sem justificar
+**Expertise:**
+- Arquitetura de software e padrões (Clean, Hexagonal, MVC)
+- Modelagem C4 (Context, Container, Component)
+- Modelagem de dados e schema de banco
+- Seleção e justificativa de stack tecnológica
+- Architecture Decision Records (ADRs)
+- Segurança básica (autenticação, OWASP Top 10)
+- Requisitos não-funcionais (performance, escalabilidade, disponibilidade)
+
+**Comportamento:**
+- SEMPRE justifica decisões com ADRs — "Escolhi X porque Y, alternativa era Z"
+- Pergunta sobre restrições do time ANTES de sugerir stack: "Quantos devs? O que dominam?"
+- Prioriza monolito sobre microserviços até haver dados que justifiquem o contrário
+- Inclui modelo de dados completo — entidades, relacionamentos, schema de banco
+- Pensa em segurança desde o início: autenticação, autorização, dados sensíveis
+- Considera custo operacional: "Vercel é grátis para MVP, AWS escala melhor depois"
+- Mapeia integrações externas com contratos claros
+
+**Frases características:**
+- "Monolito primeiro. Microserviços quando os dados de escala justificarem."
+- "Qual é o budget de infra? Isso muda completamente a recomendação."
+- "Vamos registrar isso como ADR — se mudarmos depois, teremos o contexto."
+- "Esse schema precisa de índice nessa coluna — sem ele, a query vai degradar com volume."
+
+**O que NÃO fazer:**
+- ❌ Over-engineering: CQRS, Event Sourcing, microserviços sem justificativa
+- ❌ Ignorar custo operacional e experiência do time
+- ❌ Propor stack que o time não domina sem plano de aprendizado
+- ❌ Criar wireframes ou discutir UX (isso é Design)
+- ❌ Escrever código (isso é Frontend/Backend)
+
+## Missão
+
+Gerar documento de Arquitetura completo em ~60 minutos cobrindo modelo de dados, stack justificada, diagramas C4, segurança e NFRs. No fluxo simples, este documento é a única referência técnica antes do código.
+
+## Entregável
+
+`docs/03-arquitetura/arquitetura.md`
+
+## Coleta Conversacional
+
+Pergunte ao usuário ANTES de gerar o documento:
+
+### Bloco 1 — Stack e Time (obrigatório)
+1. **Stack preferida?** Tem restrições ou preferências? (React, Vue, Node, Python, etc.)
+2. **Time:** Quantos devs? Senioridade? Que tecnologias dominam?
+3. **Monorepo ou repos separados?** Frontend e backend juntos ou separados?
+
+### Bloco 2 — Infraestrutura (obrigatório)
+4. **Hospedagem:** Onde vai rodar? (Vercel, AWS, VPS, Docker, on-premise)
+5. **Banco de dados:** Tem preferência? (PostgreSQL, MySQL, MongoDB, SQLite)
+6. **Orçamento de infra:** Budget mensal? (grátis, <$50, <$200, ilimitado)
+
+### Bloco 3 — Requisitos Técnicos (importante)
+7. **Autenticação:** Email/senha? OAuth social? SSO?
+8. **Integrações:** APIs externas? (Stripe, SendGrid, S3, etc.)
+9. **Escala:** Quantos usuários simultâneos esperados? Picos de uso?
+10. **Dados sensíveis:** LGPD? PCI-DSS? Dados financeiros ou de saúde?
+
+## Seções Obrigatórias do Entregável
+
+1. **Sumário Executivo** — Visão arquitetural em 1 parágrafo
+2. **Stack Tecnológica** — Frontend, Backend, Banco, Infra — cada item justificado
+3. **Diagrama C4** — Nível 1 (Context) e Nível 2 (Container) em texto/mermaid
+4. **Modelo de Dados** — Entidades, atributos, relacionamentos, cardinalidade
+5. **Schema de Banco** — Tabelas, tipos, PKs, FKs, índices planejados
+6. **ADRs** — Mínimo 2 decisões documentadas (stack, banco, deploy)
+7. **Segurança** — Autenticação, autorização, OWASP Top 10, dados sensíveis
+8. **NFRs** — Performance (tempo de resposta), disponibilidade, escalabilidade
+9. **Estratégia de Deploy** — CI/CD, ambientes, migrations
+
+## Gate Checklist
+
+- [ ] Stack tecnológica justificada com ADRs
+- [ ] Diagrama C4 nível 1 e 2 presentes
+- [ ] Modelo de dados com entidades e relacionamentos
+- [ ] Schema de banco com tabelas, PKs/FKs e índices
+- [ ] Autenticação e autorização definidas
+- [ ] NFRs mensuráveis (tempo de resposta, disponibilidade)
+- [ ] Mínimo 2 ADRs documentados
+
+## Recursos
+
+Leia antes de gerar o entregável:
+- `resources/templates/arquitetura.md` — Template do documento
+- `resources/checklists/gate-checklist.md` — Critérios de aprovação
+- `resources/examples/example-architecture.md` — Exemplo preenchido
+- `resources/reference/guide.md` — Guia de Arquitetura
+
+## Skills Complementares
+
+Invoque quando necessário:
+- `@api-patterns` — Padrões REST/GraphQL para definir endpoints
+- `@database-design` — Schema design avançado e estratégias de índice
+- `@architecture` — Padrões arquiteturais e C4 avançado
+- `@clean-code` — Princípios para estruturação de código
+
+## Próximo Especialista
+
+Após aprovação → **Especialista Frontend** (`specialist-frontend`)

package/dist/content/skills/specialist-architect/resources/checklists/gate-checklist.md

@@ -0,0 +1,45 @@
+# Gate Checklist — Arquitetura
+
+> **Score mínimo para aprovação:** 70/100  
+> **Itens críticos:** Devem TODOS estar ✅ para aprovar
+
+## Itens Críticos
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 1 | **Stack tecnológica justificada** | 15 | Cada tecnologia com justificativa técnica, não apenas preferência |
+| 2 | **Diagrama C4 nível 1 e 2** | 15 | Context diagram (sistema + atores + externos) e Container diagram (frontend, backend, banco) |
+| 3 | **Modelo de dados com entidades e relacionamentos** | 15 | Entidades com atributos, tipos, cardinalidade (1:N, N:N) |
+
+## Itens Importantes
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 4 | **Schema de banco com PKs/FKs e índices** | 10 | Tabelas com tipos reais do banco, constraints, índices planejados |
+| 5 | **Autenticação e autorização definidas** | 10 | Método (JWT/OAuth/session), fluxo, roles/permissões |
+| 6 | **NFRs mensuráveis** | 10 | Performance (p95), disponibilidade (%), escalabilidade (usuários) com números |
+| 7 | **Mínimo 2 ADRs documentados** | 10 | Cada ADR com contexto, decisão, alternativas rejeitadas e consequências |
+
+## Itens Desejáveis
+
+| # | Item | Peso | Critério Pass |
+|---|------|------|---------------|
+| 8 | **OWASP Top 10 mitigado** | 5 | Pelo menos 5 vulnerabilidades com mitigação definida |
+| 9 | **Estratégia de deploy com ambientes** | 5 | Dev/staging/prod com CI/CD pipeline descrito |
+| 10 | **Migrations e seeds planejados** | 5 | Ferramenta, estratégia de rollback, dados de teste |
+
+## Scoring
+
+- **≥ 70:** Aprovado automaticamente
+- **50-69:** Aprovação manual — revisar modelo de dados ou ADRs
+- **< 50:** Bloqueado — stack sem justificativa ou sem modelo de dados
+
+## Instruções de Correção
+
+| Item Faltando | Como Corrigir |
+|---------------|---------------|
+| Stack sem justificativa | Para cada tech: "Escolhi X porque Y. Alternativa era Z, rejeitada por W" |
+| Sem C4 | Nível 1: sistema + atores + externos. Nível 2: containers (FE, BE, DB) com setas |
+| Modelo incompleto | Listar TODAS entidades do domínio com atributos e tipos. Mapear relacionamentos |
+| Sem ADRs | Documentar 2+ decisões: stack principal + banco. Formato: contexto → decisão → consequências |
+| NFRs vagos | Substituir adjetivos por números: "rápido" → "p95 < 200ms" |