@maestro-ai/mcp-server 5.3.4 → 5.3.6

package/dist/content/rules/RULES.md

@@ -1,724 +1,449 @@
-# MCP Maestro Development Kit - AI Rules
+# MCP Maestro Development Kit v3 — AI Rules
 
-> Este arquivo define como a IA deve se comportar ao trabalhar com o sistema MCP Maestro.
+> Guia para a IA interagir com o sistema MCP Maestro.
+> Conteúdo universal para todas as IDEs (Cursor, Windsurf, Antigravity/Gemini, Copilot).
 
 ---
 
-## CRITICAL: MCP MAESTRO PROTOCOL (START HERE)
-
-> **MANDATORY:** Você DEVE seguir o protocolo MCP Maestro para todos os projetos neste workspace.
+## 🚨 PROTOCOLO OBRIGATÓRIO (START HERE)
 
 ### 1. Detectar Contexto MCP
 
-**Antes de QUALQUER ação, verificar**:
-- ✅ Existe `.maestro/estado.json` no diretório?
-- ✅ Se SIM → Ativar Modo MCP Maestro completo
-- ✅ Se NÃO → Seguir fluxo padrão
+**Antes de QUALQUER ação:**
+- ✅ Existe `.maestro/estado.json`? → **Modo MCP Maestro ativo**
+- ❌ Não existe? → Seguir fluxo padrão
 
-### 2. Princípio Stateless (CRÍTICO)
+### 2. Princípio Stateless
 
 ```
 ❌ ERRADO: Assumir estado prévio em memória
-✅ CORRETO: Estado SEMPRE em .maestro/estado.json
+✅ CORRETO: Estado SEMPRE lido de .maestro/estado.json
 ```
 
-**Protocolo obrigatório**:
+**Protocolo:**
 1. Ler `.maestro/estado.json` antes de qualquer tool MCP
-2. Parsear conteúdo para variável `estado_json`
-3. Passar `estado_json` como argumento em TODOS os tools MCP
+2. Passar `estado_json` como argumento em TODOS os tools
+3. Passar `diretorio` (caminho absoluto) em TODOS os tools
 4. NUNCA confiar em memória de conversação
 
-### 3. Filosofia: Qualidade Adaptativa
-
-**Princípio Central**: Qualidade não é negociável, formalidade é adaptável.
+### 3. Qualidade Adaptativa
 
 | Tipo Projeto | Gate Tier | Rigor | Exemplo |
 |--------------|-----------|-------|---------|
 | POC | Essencial | Funciona? | Spike técnico |
-| Script | Essencial | Funciona? | Automação backup |
-| Internal | Base | Padrão indústria | Dashboard admin |
+| Script | Essencial | Funciona? | Automação |
+| Internal | Base | Padrão indústria | Dashboard |
 | Product | Base/Avançado | Estado da arte | SaaS, Fintech |
 
 ---
 
-## 📥 REQUEST CLASSIFIER (STEP 1)
-
-**Antes de QUALQUER ação, classificar o request:**
+## ⚡ 5 TOOLS PÚBLICAS
 
-| Request Type | Trigger Keywords | MCP Tool | Resultado |
-|--------------|------------------|----------|-----------|
-| **NOVO PROJETO** | "criar projeto", "iniciar maestro", "novo sistema" | `iniciar_projeto` | Inicia Fase 1 (Produto) |
-| **AVANÇAR FASE** | "próximo", "terminei", "avançar", "continuar", "pronto" | `proximo` | Salva + Valida + Próxima Fase |
-| **VERIFICAR STATUS** | "status", "onde estou", "fase atual" | `status` | Estado completo do projeto |
-| **VALIDAR GATE** | "validar", "posso avançar?", "checklist" | `validar_gate` | Verifica checklist da fase |
-| **RECLASSIFICAR** | "mudar complexidade", "reclassificar" | `classificar` | Reanalisa complexidade |
-| **CONFIRMAR CLASSIFICAÇÃO** | "confirmar", "ok", "classificação correta" | `confirmar_classificacao` | Efetiva nova classificação |
-| **NOVA FEATURE** | "adicionar feature", "nova funcionalidade" | `nova_feature` | Fluxo de feature |
-| **BUG FIX** | "corrigir bug", "resolver erro", "debugging" | `corrigir_bug` | Fluxo de correção |
-| **REFATORAR** | "refatorar", "melhorar código", "reestruturar" | `refatorar` | Fluxo de refatoração |
-| **SALVAR** | "salvar rascunho", "salvar anexo" | `salvar` | Persiste sem avançar |
-| **CONTEXTO** | "contexto", "resumo", "o que temos até agora" | `contexto` | Contexto acumulado |
-
----
+> **IMPORTANTE**: Use APENAS estas 5 tools. Tools legadas (v4) ainda funcionam mas emitem deprecation warnings e serão removidas.
 
-## 🤖 SPECIALIST AUTO-LOADING (STEP 2 - AUTO)
+### 1. `maestro` — Entry Point Inteligente 🎯
 
-**SEMPRE ATIVO: Carregar especialista correto para cada fase**
+**Quando usar**: Iniciar projeto, ver status, criar projeto
 
-### Protocol de Carregamento
+```typescript
+// Ver status do projeto (sem ação = auto-detecta)
+maestro({ diretorio: "/path/to/project" })
+
+// Criar novo projeto
+maestro({
+  diretorio: "/path/to/project",
+  acao: "criar_projeto",
+  respostas: { nome: "MeuProjeto", descricao: "Sistema de..." }
+})
 
-```
-1. Ler estado.json → obter fase_atual
-2. Mapear fase → especialista (via fluxo)
-3. Carregar via resource maestro://especialista/{nome}
-4. Aplicar persona e instruções do especialista
-5. Usar template correto para a fase
+// Setup inicial (IDE, modo)
+maestro({
+  diretorio: "/path/to/project",
+  acao: "setup_inicial",
+  respostas: { ide: "vscode", modo: "balanced" }
+})
 ```
 
-### Mapeamento Fase → Especialista
+**Substitui**: `iniciar_projeto`, `confirmar_projeto`, `status`, `carregar_projeto`, `setup_inicial`
 
-**Fluxo Simples (7 fases)**:
-1. Produto → `Gestão de Produto`
-2. Requisitos → `Engenharia de Requisitos`
-3. UX Design → `UX Design`
-4. Arquitetura → `Arquitetura de Software`
-5. Backlog → `Plano de Execução`
-6. Frontend → `Desenvolvimento Frontend`
-7. Backend → `Desenvolvimento`
-
-**Fluxo Médio (13 fases)** adiciona:
-4. Modelo de Domínio → `Modelagem e Arquitetura de Domínio com IA`
-5. Banco de Dados → `Banco de Dados`
-7. Segurança → `Segurança da Informação`
-8. Testes → `Análise de Testes`
-10. Contrato API → `Contrato de API`
-13. Integração → `DevOps e Infraestrutura`
+---
 
-**Fluxo Complexo (17 fases)** adiciona:
-7. Arquitetura Avançada → `Arquitetura Avançada`
-9. Performance → `Performance e Escalabilidade`
-10. Observabilidade → `Observabilidade`
+### 2. `executar` — Ações no Projeto ⚡
 
-**Fase Stitch (Opcional)** - Inserida após UX Design:
-- Prototipagem → `Prototipagem Rápida com Google Stitch`
+**Quando usar**: Avançar fase, salvar, checkpoints
 
-### Response Format (MANDATORY)
+```typescript
+// Avançar fase com entregável
+executar({
+  diretorio: "/path/to/project",
+  acao: "avancar",        // padrão se omitido
+  entregavel: "<conteúdo completo do entregável>"
+})
 
-Ao carregar especialista, informar:
+// Avançar onboarding com respostas
+executar({
+  diretorio: "/path/to/project",
+  acao: "avancar",
+  respostas: { nome_produto: "MeuApp", problema: "..." }
+})
 
-```markdown
-🎯 **Fase {número}: {nome}**
-🤖 **Especialista**: `{nome_especialista}`
-📋 **Entregável**: {entregavel_esperado}
+// Salvar rascunho sem avançar
+executar({
+  diretorio: "/path/to/project",
+  acao: "salvar",
+  conteudo: "...",
+  tipo: "rascunho"        // "rascunho" | "anexo" | "entregavel"
+})
 
-[Continuar com instruções do especialista]
+// Checkpoint
+executar({
+  diretorio: "/path/to/project",
+  acao: "checkpoint",
+  checkpoint_acao: "criar",  // "criar" | "rollback" | "listar"
+  reason: "Antes de refatorar"
+})
 ```
 
----
-
-## TIER 0: REGRAS UNIVERSAIS (Always Active)
+**Substitui**: `proximo`, `avancar`, `salvar`, `checkpoint`
 
-### 🌐 Language Handling
-
-- **Responder**: Sempre em português do Brasil
-- **Código**: Variáveis, funções e comentários em inglês
-- **Documentação**: Português (PRD, requisitos) ou inglês (código)
+---
 
-### 🔄 Stateless Protocol (MANDATORY)
+### 3. `validar` — Validações ✅
 
-**ANTES de chamar qualquer tool MCP**:
+**Quando usar**: Validar gate, qualidade, compliance
 
 ```typescript
-// 1. Ler estado
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-
-// 2. Usar em TODOS os tools
-await mcp_maestro_proximo({
-  entregavel: "...",
-  estado_json: estadoJson,  // OBRIGATÓRIO
-  diretorio: process.cwd()
-});
-```
-
-**NUNCA**:
-- ❌ Assumir estado em memória
-- ❌ Cachear valores entre requests
-- ❌ Confiar em histórico de chat
-- ❌ Chamar tools MCP sem `estado_json`
-
-### 📁 File Structure Awareness
-
-**Estrutura Padrão MCP Maestro**:
+// Validar gate da fase atual (auto-detecta tipo)
+validar({ diretorio: "/path/to/project" })
+
+// Validar entregável específico
+validar({
+  diretorio: "/path/to/project",
+  tipo: "entregavel",
+  entregavel: "<conteúdo>"
+})
 
+// Verificar compliance
+validar({
+  diretorio: "/path/to/project",
+  tipo: "compliance",
+  standard: "LGPD",
+  code: "<código para verificar>"
+})
 ```
-projeto/
-├── .maestro/
-│   ├── estado.json       # ⭐ FONTE DA VERDADE
-│   └── resumo.json       # Cache de contexto
-├── docs/
-│   ├── 01-produto/
-│   │   └── PRD.md
-│   ├── 02-requisitos/
-│   │   └── requisitos.md
-│   ├── 03-ux/
-│   │   └── design-doc.md
-│   └── ...
-└── src/
-```
-
-**Antes de modificar arquivos**:
-1. Verificar se está seguindo estrutura MCP
-2. Criar diretórios por fase (`docs/{numero}-{nome}/`)
-3. Salvar entregáveis com nomes padronizados
-
-### 🛑 Gate Protection Protocol
-
-**Quando `validar_gate` retorna `valido: false`**:
 
-```
-1. 🛑 STOP: Não chamar proximo()
-2. 📊 MOSTRAR: Itens pendentes ao usuário
-3. 💡 SUGERIR: Correções baseadas em checklist
-4. ⏸️ AGUARDAR: Aprovação explícita do usuário
-```
+**Substitui**: `validar_gate`, `avaliar_entregavel`, `check_compliance`
 
-**Score de Qualidade**:
-- **100**: Todos itens do checklist validados ✅
-- **70-99**: Pode avançar com pendências menores ⚠️
-- **< 70**: **BLOQUEADO** - Requer correção ou aprovação manual 🔴
+---
 
-**NUNCA**:
-- ❌ Chamar `aprovar_gate` automaticamente
-- ❌ Usar `forcar: true` sem aprovação explícita
-- ❌ Ignorar gates ou pular validações
-- ❌ Avançar com score < 70 sem confirmação
+### 4. `analisar` — Análises de Código 🔍
 
-### 🧠 Read → Understand → Apply
+**Quando usar**: Segurança, qualidade, performance, relatórios
 
-```
-❌ ERRADO: Ler especialista → Gerar conteúdo genérico
-✅ CORRETO: Ler → Entender PRINCÍPIOS → Aplicar PERSONA → Gerar
+```typescript
+// Relatório completo (padrão)
+analisar({ diretorio: "/path/to/project" })
+
+// Análise específica
+analisar({
+  diretorio: "/path/to/project",
+  tipo: "seguranca",       // "seguranca" | "qualidade" | "performance" | "dependencias" | "completo"
+  code: "<código>"
+})
 ```
 
-**Antes de gerar qualquer entregável, responder**:
-1. Qual é o OBJETIVO desta fase?
-2. Que PRINCÍPIOS o especialista aplica?
-3. Como isso DIFERE de output genérico?
-4. Que TEMPLATE usar?
+**Substitui**: `analisar_seguranca`, `analisar_qualidade`, `analisar_performance`, `gerar_relatorio`
 
 ---
 
-## TIER 1: FLUXO DE PROJETO
+### 5. `contexto` — Contexto Acumulado 🧠
 
-### 📱 Classificação Automática
+**Quando usar**: Obter resumo do projeto, decisões, padrões
 
-**Quando**: Após Fase 1 (PRD) ser concluída
+```typescript
+contexto({ diretorio: "/path/to/project" })
+// → Retorna: Stack, modelo, arquitetura, ADRs, gates validados
+```
 
-**Critérios de Análise** (do PRD):
+**Substitui**: `get_context`
 
-| Critério | Como Detectar | Pontos |
-|----------|---------------|--------|
-| **Entidades** | Contar substantivos em Funcionalidades | 1-3 |
-| **Integrações** | Buscar "API", "integração", "serviço externo" | 1-3 |
-| **Segurança** | Palavras: "auth", "LGPD", "compliance", "criptografia" | 1-3 |
-| **Escala** | Números de usuários mencionados (>1k, >10k, >100k) | 1-3 |
-| **Tempo** | Cronograma (>3 meses = mais complexo) | 1-3 |
-| **Regras de Negócio** | Complexidade descrita (workflows, cálculos) | 1-3 |
+---
 
-**Resultado da Classificação**:
-- **8-12 pontos** → Simples (7 fases)
-- **13-18 pontos** → Médio (13 fases)
-- **19-24 pontos** → Complexo (17 fases)
+### Tools Exclusivas do Usuário
 
-**Fluxo**:
-```
-Usuário: "próximo" (após PRD)
-↓
-MCP analisa PRD automaticamente
-↓
-MCP sugere: "Detectei 14 pontos → Nível MÉDIO (13 fases)"
-↓
-IA pergunta: "Confirmar classificação ou ajustar?"
-↓
-Usuário confirma
-↓
-MCP confirma classificação e carrega Fase 2
+```typescript
+// ⚠️ NUNCA chame automaticamente — apenas quando o USUÁRIO solicitar
+aprovar_gate({ acao: "aprovar", estado_json: "...", diretorio: "..." })
 ```
 
-### 🎭 Stitch Protocol (Opcional)
-
-**Quando Usar**:
-- ✅ Projeto com UI/UX crítico
-- ✅ Validação de design com stakeholders necessária
-- ✅ Prototipagem rápida desejada
-
-**Quando Perguntar**:
-```markdown
-Projeto classificado. Deseja incluir fase de **Prototipagem com Google Stitch**?
-- ✅ Sim → Insere fase após UX Design
-- ❌ Não → Continua fluxo normal
-```
-
-**Fluxo com Stitch**:
-```
-Produto(1) → Requisitos(2) → UX Design(3) → Stitch(4) → Modelo(5) → ...
-```
-
-**Fase Stitch**:
-- **Especialista**: Prototipagem Rápida com Google Stitch
-- **Template**: `prototipo-stitch`
-- **Entregável**: `prototipos.md` + HTML/CSS exportados
-- **Checklist**:
-  - Design Doc aprovado como base
-  - Prompts para Stitch gerados
-  - Protótipos testados em stitch.withgoogle.com
-  - Código exportado e salvo
-
-### 🏗️ Frontend-First Protocol
-
-**Para features que envolvem Frontend + Backend**:
-
-**Regra oficial (obrigatória):**
-- **NUNCA** iniciar FE/BE sem **Contrato API validado + Mock server ativo**
-- **Frontend** só pode consumir **mocks gerados do contrato**
-- **Backend** deve **implementar exatamente o contrato**, sem alterações fora do versionamento
-- **Integração** só inicia após FE + BE concluídos
-
-```
-FEAT-001: Criar Pedido
-│
-├── 1. CONT-001 (Contrato API)
-│   ├── Gera: openapi.yaml
-│   ├── Gera: types para Frontend
-│   ├── Gera: types para Backend
-│   └── Gera: Mock Server
-│
-├── 2. US-001-FE (Frontend) ◄── Pode iniciar em paralelo
-│   ├── Dependência: CONT-001 ✅
-│   ├── Desenvolve contra mock
-│   ├── Componentes + hooks + pages
-│   └── Testes de componente
-│
-├── 3. US-001-BE (Backend) ◄── Pode iniciar em paralelo
-│   ├── Dependência: CONT-001 ✅
-│   ├── Implementa contrato
-│   ├── DTOs + entities + services
-│   └── Testes unitários
-│
-└── 4. INT-001 (Integração)
-    ├── Dependência: US-001-FE ✅
-    ├── Dependência: US-001-BE ✅
-    ├── Remove mocks
-    ├── Conecta FE com BE real
-    └── Testes E2E
-```
-
-**Validação de Dependências**:
+### Tools de Fluxos Alternativos
 
 ```typescript
-// Antes de iniciar história
-if (historia.tipo === 'frontend' || historia.tipo === 'backend') {
-  const contrato = buscarHistoria('contrato');
-  if (contrato.status !== 'concluido') {
-    return "⛔ BLOQUEADO: Contrato (CONT-XXX) precisa ser concluído primeiro";
-  }
-}
-
-if (historia.tipo === 'integracao') {
-  const fe = buscarHistoria('frontend');
-  const be = buscarHistoria('backend');
-  if (fe.status !== 'concluido' || be.status !== 'concluido') {
-    return "⛔ BLOQUEADO: Frontend e Backend precisam estar concluídos";
-  }
-}
+nova_feature({ descricao: "...", impacto_estimado: "medio" })
+corrigir_bug({ descricao: "...", severidade: "alta" })
+refatorar({ area: "...", motivo: "..." })
 ```
 
-### 🔄 Fluxos Alternativos
+---
 
-**Nova Feature**:
-```
-Tool: nova_feature(descricao, impacto_estimado)
-↓
-Fases:
-1. Análise de Impacto
-2. Refinamento de Requisitos
-3. Design/Arquitetura
-4. Implementação (Contrato → FE/BE → Integração)
-5. Testes
-6. Deploy
-```
+## 📥 REQUEST CLASSIFIER
 
-**Correção de Bug**:
-```
-Tool: corrigir_bug(descricao, severidade)
-↓
-Fases:
-1. Reprodução do Bug
-2. Análise de Causa Raiz
-3. Fix + Testes de Regressão
-4. Deploy
-```
+**Classificar o request do usuário ANTES de agir:**
 
-**Refatoração**:
-```
-Tool: refatorar(area, motivo)
-↓
-Fases:
-1. Análise de Código Atual
-2. Testes de Caracterização
-3. Refatoração Incremental
-4. Validação
-5. Deploy
-```
+| Request | Trigger Keywords | Tool | Ação |
+|---------|-----------------|------|------|
+| **Novo projeto** | "criar projeto", "iniciar", "novo sistema" | `maestro` | `acao: "criar_projeto"` |
+| **Avançar** | "próximo", "terminei", "avançar", "pronto" | `executar` | `acao: "avancar"` |
+| **Status** | "status", "onde estou", "fase atual" | `maestro` | sem ação |
+| **Validar** | "validar", "posso avançar?", "checklist" | `validar` | auto-detecta |
+| **Salvar** | "salvar rascunho", "salvar anexo" | `executar` | `acao: "salvar"` |
+| **Contexto** | "contexto", "resumo", "o que temos" | `contexto` | — |
+| **Nova feature** | "nova funcionalidade", "adicionar" | `nova_feature` | — |
+| **Bug fix** | "corrigir bug", "resolver erro" | `corrigir_bug` | — |
+| **Refatorar** | "refatorar", "reestruturar" | `refatorar` | — |
 
 ---
 
-## TIER 2: ESPECIALISTAS
+## 🤖 SKILLS E ESPECIALISTAS
 
-### 🧠 Protocolo de Carregamento Automático
+### Carregamento Automático
 
-**Sempre que mudar de fase**:
+**Ao iniciar cada fase**, o MCP carrega o especialista correto automaticamente.
+A IA DEVE **ler e aplicar** a skill correspondente.
 
-1. 🔍 Detectar `fase_atual` do `estado.json`
-2. 🗺️ Mapear fase → nome do especialista (via fluxo)
-3. 📥 Carregar `maestro://especialista/{nome}`
-4. 🎭 Aplicar persona completa do especialista
-5. 📋 Usar template correto
-6. ✅ Seguir gate checklist da fase
+**Protocolo:**
+```
+1. Ler estado.json → obter fase_atual + skill_name
+2. Localizar skill no diretório de skills da IDE (ver tabela abaixo)
+3. Ler SKILL.md para persona + instruções
+4. Consultar resources/templates/ para template do entregável
+5. Consultar resources/checklists/ para critérios de validação
+```
 
-**Exemplo**:
-```markdown
-// Estado atual
-fase_atual: 5
-nivel_complexidade: "medio"
-
-// Fluxo médio, fase 5 = Banco de Dados
-especialista: "Banco de Dados"
-template: "design-banco"
-
-// Carrega resource
-resource = await fetch('maestro://especialista/banco-de-dados')
-
-// Aplica
-- Persona do especialista
-- Instruções específicas
-- Checklist de validação
-```
-
-### 📚 Especialistas Disponíveis
-
-**Base (todos os fluxos)**:
-- Gestão de Produto
-- Engenharia de Requisitos
-- UX Design
-- Modelagem de Domínio (médio/complexo)
-- Banco de Dados (médio/complexo)
-- Arquitetura de Software
-- Segurança da Informação (médio/complexo)
-- Análise de Testes (médio/complexo)
-- Plano de Execução
-- Contrato de API (médio/complexo)
-- Desenvolvimento Frontend
-- Desenvolvimento Backend
-- DevOps e Infraestrutura (médio/complexo)
-
-**Avançados (apenas complexos)**:
-- Arquitetura Avançada (DDD, CQRS, Event Sourcing, Microserviços)
-- Performance e Escalabilidade (Load testing, caching, otimização)
-- Observabilidade (Logs, métricas, tracing distribuído, dashboards)
-
-**Complementares**:
-- Prototipagem com Google Stitch (opcional)
-- Dados e Analytics
-- Acessibilidade
-- Debugging e Troubleshooting
-- Documentação Técnica
-- Exploração de Codebase
-- Migração e Modernização
-
-### 🎯 Aplicação de Especialistas
-
-**Regra de Ouro**: Especialista = Persona + Princípios + Template
+### 📁 Diretórios por IDE
 
-```markdown
-❌ ERRADO:
-"Vou criar o PRD..."
-[Gera texto genérico]
+| IDE | Skills | Workflows | Rules File |
+|-----|--------|-----------|------------|
+| **Antigravity/Gemini** | `.agent/skills/` | `.agent/workflows/` | `.gemini/GEMINI.md` |
+| **Cursor** | `.cursor/skills/` | `.cursor/commands/` | `.cursorrules` |
+| **Windsurf** | `.windsurf/skills/` | `.windsurf/workflows/` | `.windsurfrules` |
+| **Copilot** | `.agent/skills/` | `.agent/workflows/` | `.github/copilot-instructions.md` |
 
-✅ CORRETO:
-🤖 **Especialista**: Gestão de Produto
+> 💡 Use o diretório correto da sua IDE ao referenciar skills e workflows.
 
-Como Product Manager, vou aplicar o framework RICE para priorização...
+### Estrutura de uma Skill
 
-**Template PRD aplicado:**
-1. Problema
-2. Personas
-3. MVP
-4. North Star Metric
-...
+```
+{skills_dir}/specialist-gestao-produto/
+├── SKILL.md                    # Persona + instruções (LER PRIMEIRO)
+├── README.md                   # Documentação completa
+├── MCP_INTEGRATION.md          # Funções MCP disponíveis
+└── resources/
+    ├── templates/PRD.md        # Template do entregável
+    ├── checklists/             # Critérios de validação
+    ├── examples/               # Exemplos reais
+    └── reference/              # Guias de referência
 ```
 
----
-
-## TIER 3: GATES ADAPTATIVOS
-
-### 🎚️ Tiers de Rigor
-
-| Tier | Quando | Foco | Exemplos de Validação |
-|------|--------|------|----------------------|
-| **Essencial** | POC, Script | Funciona? | Código executa, fim |
-| **Base** | Internal, Product simples | Padrão indústria | Testes, lint, segurança básica |
-| **Avançado** | Product complexo | Estado da arte | Arquitetura, observabilidade, compliance |
+### 🔧 Resources MCP (Consulta via API)
 
-### 🔍 Validação Automática
+> 💡 **Priorize skills locais** (diretório de skills da IDE). Use resources MCP como consulta complementar.
 
-**Cada fase tem checklist específico por tier**:
+```
+maestro://especialista/{nome}     # Persona do especialista
+maestro://template/{nome}         # Template de documento
+maestro://guia/{nome}             # Guia prático
+maestro://prompt/{area}/{nome}    # Prompts avançados
+maestro://system-prompt           # System prompt do Maestro
+```
 
-```typescript
-// Exemplo: Fase 1 (Produto)
-gate_checklist_essencial = [
-  "Problema claramente definido",
-  "MVP com funcionalidades listadas"
-]
+**Para consultar**: use `read_resource("maestro://especialista/gestao-produto")`
 
-gate_checklist_base = [
-  ...gate_checklist_essencial,
-  "Personas identificadas",
-  "North Star Metric definida"
-]
+### Mapeamento Fase → Skill
 
-gate_checklist_avancado = [
-  ...gate_checklist_base,
-  "Análise de concorrentes",
-  "Business Model Canvas",
-  "Roadmap trimestral"
-]
-```
+**Fluxo Simples (7 fases)**:
+1. Produto → `specialist-gestao-produto`
+2. Requisitos → `specialist-engenharia-requisitos-ia`
+3. UX Design → `specialist-ux-design`
+4. Arquitetura → `specialist-arquitetura-software`
+5. Backlog → `specialist-plano-execucao-ia`
+6. Frontend → `specialist-desenvolvimento-frontend`
+7. Backend → `specialist-desenvolvimento-backend`
+
+**Fluxo Médio (13 fases)** insere:
+- Modelo de Domínio → `specialist-modelagem-dominio`
+- Banco de Dados → `specialist-banco-dados`
+- Segurança → `specialist-seguranca-informacao`
+- Testes → `specialist-analise-testes`
+- Contrato API → `specialist-contrato-api`
+- Integração → `specialist-devops-infra`
 
-**Cálculo de Score**:
+**Fluxo Complexo (17 fases)** adiciona:
+- Arquitetura Avançada → `specialist-arquitetura-avancada`
+- Performance → `specialist-performance-escalabilidade`
+- Observabilidade → `specialist-observabilidade`
 
-```typescript
-score = (itens_validados / total_itens) * 100
+**Stitch (Opcional)** — Inserida após UX Design:
+- Prototipagem → `specialist-prototipagem-stitch`
 
-if (score === 100) {
-  return "✅ Gate aprovado - Todos itens validados"
-}
-else if (score >= 70) {
-  return "⚠️ Gate aprovado com pendências - Pode avançar"
-}
-else {
-  return "🔴 Gate bloqueado - Necessário corrigir ou aprovar manualmente"
-}
-```
+### Especialistas Complementares
 
-### 🚦 Protocolo de Gate
+Disponíveis sob demanda, fora do fluxo de fases:
+- `specialist-dados-analytics-ia` — Dados e Analytics
+- `specialist-acessibilidade` — Acessibilidade
+- `specialist-debugging-troubleshooting` — Debugging
+- `specialist-documentacao-tecnica` — Documentação
+- `specialist-exploracao-codebase` — Análise de código existente
+- `specialist-migracao-modernizacao` — Modernização de legado
 
-**1. Validação Automática (antes de avançar)**:
+### Regra de Ouro: Persona → Princípios → Template
 
 ```
-proximo(entregavel)
-  ↓
-validar_gate(fase_atual, entregavel)
-  ↓
-score >= 70?
-  ├─ SIM → Avança automaticamente
-  └─ NÃO → BLOQUEIA + mostra pendências
+❌ ERRADO: Ler especialista → Gerar conteúdo genérico
+✅ CORRETO: Ler SKILL.md → Entender PRINCÍPIOS → Aplicar PERSONA → Usar TEMPLATE → Gerar
 ```
 
-**2. Bloqueio (score < 70)**:
-
-```markdown
-🔴 **Gate Bloqueado** (Score: {score}/100)
-
-**Itens Validados** ✅:
-- [item 1]
-- [item 2]
+**Antes de gerar qualquer entregável, validar internamente:**
+1. Qual é o OBJETIVO desta fase?
+2. Que PRINCÍPIOS o especialista aplica?
+3. Que TEMPLATE usar?
+4. Como isso DIFERE de output genérico?
 
-**Itens Pendentes** ❌:
-- [pendência 1]
-- [pendência 2]
+---
 
-**Opções**:
-1. Corrigir pendências e validar novamente
-2. Solicitar aprovação manual (justificar)
-```
+## 🏗️ FLUXO DO PROJETO
 
-**3. Aprovação Manual**:
+### Classificação Automática (após PRD)
 
 ```
-Usuário: "aprovar mesmo assim porque [justificativa]"
+Usuário: "próximo" (após PRD)
+  ↓
+MCP analisa PRD automaticamente
   ↓
-IA chama: aprovar_gate(acao: "aprovar", estado_json, diretorio)
+MCP sugere: "Detectei 14 pontos → Nível MÉDIO (13 fases)"
   ↓
-MCP registra aprovação forçada + motivo
+IA pergunta: "Confirmar classificação ou ajustar?"
   ↓
-Avança para próxima fase
+Usuário confirma
+  ↓
+MCP confirma e carrega Fase 2
 ```
 
----
+| Nível | Fases | Quando |
+|-------|-------|--------|
+| Simples | 7 | POC, MVP, < 2 semanas |
+| Médio | 13 | SaaS simples, 1-3 meses |
+| Complexo | 17 | Multi-tenant, fintech, 3+ meses |
 
-## TIER 4: TOOLS MCP
+### Stitch (Opcional)
 
-### 🛠️ Tools Principais
+Quando o projeto tem UI/UX crítico:
+```
+Produto → Requisitos → UX Design → **Stitch** → Modelo → ...
+```
 
-**Gerenciamento de Projeto**:
+### Frontend-First Protocol
 
-```typescript
-// Iniciar novo projeto
-iniciar_projeto(nome, descricao?, diretorio?)
-→ Cria .maestro/, inicia Fase 1, carrega especialista
+**Regra obrigatória para features com Frontend + Backend:**
 
-// Confirmar criação (após análise)
-confirmar_projeto(nome, diretorio, tipo_artefato, nivel_complexidade)
-→ Efetiva projeto com classificação escolhida
+```
+1. CONT-001 (Contrato API) ← SEMPRE primeiro
+   ├── openapi.yaml
+   ├── types para FE/BE
+   └── Mock Server
 
-// Reclassificar (após PRD ou durante projeto)
-classificar(nivel?, prd?, estado_json, diretorio)
-→ Analisa e sugere nova classificação
+2. FE + BE em paralelo (contra mocks)
 
-// Confirmar reclassificação
-confirmar_classificacao(nivel, tipo_artefato?, estado_json, diretorio)
-→ Aplica nova classificação e ajusta fluxo
+3. INT-001 (Integração) ← DEPOIS de FE + BE prontos
 ```
 
-**Avanço de Fases**:
+- ❌ NUNCA iniciar FE/BE sem contrato API validado
+- ❌ NUNCA conectar FE com BE real sem ambos concluídos
 
-```typescript
-// Avançar fase (salva + valida + próxima)
-proximo(entregavel, estado_json, diretorio, forcar?, nome_arquivo?)
-→ Persiste, valida gate, carrega próxima fase
-
-// Validar gate antes de avançar
-validar_gate(estado_json, diretorio, fase?, entregavel?)
-→ Retorna score e checklist
+---
 
-// Aprovar gate manualmente (APENAS USUÁRIO)
-aprovar_gate(acao: "aprovar" | "rejeitar", estado_json, diretorio)
-→ Força avanço ou cancela
-```
+## 🛑 GATES ADAPTATIVOS
 
-**Consultas**:
+### Tiers de Rigor
 
-```typescript
-// Status completo
-status(estado_json, diretorio)
-→ Projeto, fase, gates, métricas
+| Tier | Quando | O que valida |
+|------|--------|-------------|
+| **Essencial** | POC, Script | Funciona? |
+| **Base** | Internal, Product | Padrão indústria |
+| **Avançado** | Product complexo | Estado da arte |
 
-// Contexto acumulado
-contexto(estado_json, diretorio)
-→ Resumo + stack + modelo + arquitetura
+### Protocolo de Gates
 
-// Carregar projeto existente
-carregar_projeto(estado_json, diretorio)
-→ Retoma sessão
 ```
-
-**Persistência**:
-
-```typescript
-// Salvar sem avançar
-salvar(conteudo, tipo: "rascunho" | "anexo" | "entregavel", estado_json, diretorio, nome_arquivo?)
-→ Persiste em docs/ ou .maestro/rascunhos/
+executar({ acao: "avancar", entregavel: "..." })
+  ↓
+Validação automática (score 0-100)
+  ↓
+≥ 70  → Avança ✅
+< 70  → BLOQUEADO 🔴 (mostra pendências)
 ```
 
-**Fluxos Alternativos**:
+**Quando bloqueado:**
+1. Mostrar itens pendentes ao usuário
+2. Sugerir correções baseadas no checklist
+3. **AGUARDAR** aprovação explícita
+4. ❌ NUNCA chamar `aprovar_gate` automaticamente
 
+**Aprovação manual** (apenas quando o USUÁRIO solicitar):
 ```typescript
-// Nova feature
-nova_feature(descricao, impacto_estimado?)
-→ Inicia fluxo de 6 fases
-
-// Corrigir bug
-corrigir_bug(descricao, severidade?)
-→ Inicia fluxo de debugging
-
-// Refatorar
-refatorar(area, motivo)
-→ Inicia fluxo de refatoração
+aprovar_gate({ acao: "aprovar", estado_json: "...", diretorio: "..." })
 ```
 
-### 🎯 Uso Correto dos Tools
-
-**SEMPRE passar `estado_json` e `diretorio`**:
+### Limite de Retries
 
-```typescript
-// ❌ ERRADO
-await mcp_maestro_proximo({
-  entregavel: "..."
-})
-
-// ✅ CORRETO
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-await mcp_maestro_proximo({
-  entregavel: "...",
-  estado_json: estadoJson,
-  diretorio: process.cwd()
-})
-```
+Após **3 tentativas** de validação sem atingir score mínimo:
+- Apresentar opções ao usuário (aprovar, editar, ou re-tentar)
+- ❌ NUNCA ficar em loop infinito de validação
 
 ---
 
-## 📁 QUICK REFERENCE
+## 🌐 REGRAS UNIVERSAIS
 
-### Gatilhos de Comando
-
-**Avanço**:
-- "próximo", "avançar", "continuar"
-- "terminei", "pronto", "finalizado"
-- "pode salvar", "está bom"
-
-**Validação**:
-- "validar", "posso avançar?", "checklist"
-- "gate", "verificar"
-
-**Consulta**:
-- "status", "onde estou", "fase atual"
-- "contexto", "resumo", "o que temos"
+### Idioma
+- **Respostas**: Sempre em português do Brasil
+- **Código**: Variáveis, funções e comentários em inglês
+- **Documentação**: Português (PRD, requisitos) ou inglês (código)
 
-### Estrutura de Arquivos
+### Estrutura de Arquivos do Projeto
 
 ```
 projeto/
 ├── .maestro/
-│   ├── estado.json          # ⭐ FONTE DA VERDADE
-│   ├── resumo.json          # Cache
-│   └── rascunhos/           # Salvamentos temporários
+│   ├── estado.json           # ⭐ FONTE DA VERDADE
+│   ├── resumo.json           # Cache de contexto
+│   ├── entregaveis/          # Drafts salvos
+│   └── rascunhos/            # Salvamentos temporários
+├── {skills_dir}/             # Skills locais (varia por IDE)
+│   ├── specialist-gestao-produto/
+│   ├── specialist-engenharia-requisitos-ia/
+│   └── ...
 ├── docs/
-│   ├── 01-produto/
-│   ├── 02-requisitos/
+│   ├── 01-produto/PRD.md
+│   ├── 02-requisitos/requisitos.md
+│   ├── 03-ux/design-doc.md
 │   └── ...
 └── src/
 ```
 
-### Resources MCP
+### Dados do Usuário
 
 ```
-maestro://especialista/{nome}   # Especialistas
-maestro://template/{nome}       # Templates de documentos
-maestro://guia/{nome}          # Guias práticos
-maestro://prompt/{area}/{nome} # Prompts avançados
-maestro://system-prompt        # System prompt completo
+❌ ERRADO: Inventar dados, métricas ou números
+✅ CORRETO: Perguntar ao usuário e usar respostas REAIS
 ```
 
-### Níveis de Complexidade
-
-| Nível | Fases | Quando Usar |
-|-------|-------|-------------|
-| Simples | 7 | POC, MVP, < 2 semanas |
-| Médio | 13 | SaaS simples, 1-3 meses |
-| Complexo | 17 | Multi-tenant, fintech, 3+ meses |
-
-### Tiers de Gates
-
-| Tier | Projeto | Rigor |
-|------|---------|-------|
-| Essencial | POC, Script | Funciona? |
-| Base | Internal, Product | Padrão indústria |
-| Avançado | Product complexo | Estado da arte |
+Se o usuário pedir "invente" ou "crie dados":
+→ Responder: "Preciso que VOCÊ me conte. Seus dados reais geram um resultado muito melhor."
+→ Oferecer exemplos para inspirar, mas NÃO usar como resposta
 
 ---
 
-## 🎓 EXAMPLES
+## 🎓 EXEMPLOS
 
 ### Exemplo 1: Iniciar Projeto
 
@@ -726,20 +451,16 @@ maestro://system-prompt        # System prompt completo
 User: "Quero criar um sistema de gestão de pedidos para restaurante"
 
 AI:
-🎯 **Iniciando MCP Maestro**
-
-Vou iniciar o projeto. Qual o nome?
+🎯 Vou iniciar o projeto MCP Maestro.
 
-User: "RestaurantePro"
-
-AI: [chama iniciar_projeto]
+[chama maestro({ acao: "criar_projeto", respostas: { nome: "RestaurantePro", descricao: "..." } })]
 
 🎯 **Projeto Iniciado**
 📁 Diretório: ./RestaurantePro
 📋 Fase 1: Produto
 🤖 Especialista: Gestão de Produto
 
-Vamos começar pelo PRD. Como Product Manager, preciso entender:
+Como Product Manager, preciso entender:
 1. Qual problema específico estamos resolvendo?
 2. Quem são os usuários principais?
 3. Quais funcionalidades do MVP?
@@ -751,33 +472,18 @@ Vamos começar pelo PRD. Como Product Manager, preciso entender:
 User: "Pronto, terminei o PRD"
 
 AI: [lê estado.json]
-
-Excelente! Vou salvar e validar o PRD.
-
-[chama proximo(entregavel: "conteúdo do PRD", estado_json, diretorio)]
+[chama executar({ acao: "avancar", entregavel: "<PRD completo>" })]
 
 ✅ **PRD Salvo**: docs/01-produto/PRD.md
 
-📊 **Classificação Automática**:
-- Entidades detectadas: 5 (Pedido, Mesa, Cliente, Produto, Pagamento)
-- Integrações: API Pagamento (1)
-- Segurança: Auth mencionada (1)
-- Escala: ~50 usuários (1)
-- **Total: 14 pontos → Nível MÉDIO (13 fases)**
-
+📊 **Classificação**: 14 pontos → Nível MÉDIO (13 fases)
 Confirmar classificação?
 
-User: "Sim, está correto"
-
-AI: [chama confirmar_classificacao]
-
-✅ **Classificação Confirmada**
+User: "Sim"
+[chama confirmar_classificacao(...)]
 
 🎯 **Fase 2: Requisitos**
-🤖 **Especialista**: Engenharia de Requisitos
-📋 **Entregável**: requisitos.md
-
-Como Engenheiro de Requisitos, vou elaborar...
+🤖 Especialista: Engenharia de Requisitos
 ```
 
 ### Exemplo 3: Gate Bloqueado
@@ -785,21 +491,15 @@ Como Engenheiro de Requisitos, vou elaborar...
 ```markdown
 User: "Próximo"
 
-AI: [chama validar_gate]
+AI: [chama executar({ acao: "avancar", entregavel: "..." })]
 
 🔴 **Gate Bloqueado** (Score: 60/100)
 
-**Itens Validados** ✅:
-- Requisitos funcionais com IDs únicos
-- Requisitos não-funcionais definidos
+✅ Requisitos funcionais com IDs
+✅ Requisitos não-funcionais
 
-**Itens Pendentes** ❌:
-- Critérios de aceite em Gherkin
-- Matriz de rastreabilidade iniciada
-
-**Sugestões**:
-1. Adicionar cenários Gherkin para cada RF
-2. Criar tabela RF → User Story
+❌ Critérios de aceite em Gherkin
+❌ Matriz de rastreabilidade
 
 Deseja corrigir ou aprovar mesmo assim?
 ```
@@ -808,34 +508,35 @@ Deseja corrigir ou aprovar mesmo assim?
 
 ## 🔧 TROUBLESHOOTING
 
-### Problema: "Tool retorna erro de estado"
+| Problema | Causa | Solução |
+|----------|-------|---------|
+| Tool retorna erro | Faltou `estado_json` | Ler `.maestro/estado.json` primeiro |
+| Especialista errado | Não verificou `fase_atual` | Checar estado.json antes de carregar |
+| Gate sempre falhando | Entregável vazio ou mal formatado | Salvar como arquivo + validar `docs/{fase}/` |
+| Score PRD 15/100 | Newlines escapados de JSON | MCP normaliza automaticamente |
+| Loop infinito | Retry sem limite | Limite de 3 retries |
 
-**Causa**: Não passou `estado_json`
+---
 
-**Solução**:
-```typescript
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-// Passar em TODOS os tools
-```
+## 📋 QUICK REFERENCE
+
+### Comando → Tool
 
-### Problema: "Especialista errado carregado"
+| Usuário diz | Tool | Args |
+|-------------|------|------|
+| "criar projeto" | `maestro` | `acao: "criar_projeto"` |
+| "próximo" / "avançar" | `executar` | `acao: "avancar"` |
+| "status" | `maestro` | — |
+| "validar" | `validar` | — |
+| "salvar" | `executar` | `acao: "salvar"` |
+| "contexto" | `contexto` | — |
+| "analisar" | `analisar` | — |
 
-**Causa**: Não verificou `fase_atual` antes de carregar
+### Parâmetro Obrigatório
 
-**Solução**:
 ```typescript
-const estado = JSON.parse(estadoJson);
-const fase = estado.fase_atual; // Usar isso para mapear
+// Em TODAS as tools, SEMPRE passar:
+{ diretorio: "/caminho/absoluto/do/projeto" }
 ```
 
-### Problema: "Gate sempre bloqueando"
-
-**Causa**: Checklist muito rigoroso para o tier
-
-**Solução**: Verificar `tier_gate` do projeto e ajustar critérios
-
----
-
-**Versão**: 1.0.0  
-**Última Atualização**: 2026-01-23  
-**Sistema**: MCP Maestro
+O `estado_json` é opcional (carrega automaticamente), mas recomendado para performance.