npm - @maestro-ai/mcp-server - Versions diffs - 1.0.0 → 1.0.1 - Mend

@maestro-ai/mcp-server 1.0.0 → 1.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (440) hide show

package/dist/content/rules/RULES.md CHANGED Viewed

@@ -1,835 +1,835 @@
-# MCP Maestro Development Kit - AI Rules
-> Este arquivo define como a IA deve se comportar ao trabalhar com o sistema MCP Maestro.
----
-## CRITICAL: MCP MAESTRO PROTOCOL (START HERE)
-> **MANDATORY:** Você DEVE seguir o protocolo MCP Maestro para todos os projetos neste workspace.
-### 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
-### 2. Princípio Stateless (CRÍTICO)
-```
-❌ ERRADO: Assumir estado prévio em memória
-✅ CORRETO: Estado SEMPRE em .maestro/estado.json
-```
-**Protocolo obrigatório**:
-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
-4. NUNCA confiar em memória de conversação
-### 3. Filosofia: Qualidade Adaptativa
-**Princípio Central**: Qualidade não é negociável, formalidade é adaptável.
-| 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 |
-| Product | Base/Avançado | Estado da arte | SaaS, Fintech |
----
-## 📥 REQUEST CLASSIFIER (STEP 1)
-**Antes de QUALQUER ação, classificar o request:**
-| 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 |
----
-## 🤖 SPECIALIST AUTO-LOADING (STEP 2 - AUTO)
-**SEMPRE ATIVO: Carregar especialista correto para cada fase**
-### Protocol de Carregamento
-```
-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
-```
-### Mapeamento Fase → Especialista
-**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`
-**Fase Stitch (Opcional)** - Inserida após UX Design:
-- Prototipagem → `Prototipagem Rápida com Google Stitch`
-### Response Format (MANDATORY)
-Ao carregar especialista, informar:
-```markdown
-🎯 **Fase {número}: {nome}**
-🤖 **Especialista**: `{nome_especialista}`
-📋 **Entregável**: {entregavel_esperado}
-[Continuar com instruções do especialista]
-```
----
-## TIER 0: REGRAS UNIVERSAIS (Always Active)
-### 🌐 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)
-**ANTES de chamar qualquer tool MCP**:
-```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**:
-```
-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
-```
-**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
-### 🧠 Read → Understand → Apply
-```
-❌ ERRADO: Ler especialista → Gerar conteúdo genérico
-✅ CORRETO: Ler → Entender PRINCÍPIOS → Aplicar PERSONA → Gerar
-```
-**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?
----
-## TIER 1: FLUXO DE PROJETO
-### 📱 Classificação Automática
-**Quando**: Após Fase 1 (PRD) ser concluída
-**Critérios de Análise** (do PRD):
-| 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)
-**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
-```
-### 🎭 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**:
-```
-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**:
-```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";
-  }
-}
-```
-### 🔄 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
-```
-**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
-```
-**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
-```
----
-## TIER 2: ESPECIALISTAS
-### 🧠 Protocolo de Carregamento Automático
-**Sempre que mudar de fase**:
-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
-**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
-```markdown
-❌ ERRADO:
-"Vou criar o PRD..."
-[Gera texto genérico]
-✅ CORRETO:
-🤖 **Especialista**: Gestão de Produto
-Como Product Manager, vou aplicar o framework RICE para priorização...
-**Template PRD aplicado:**
-1. Problema
-2. Personas
-3. MVP
-4. North Star Metric
-...
-```
----
-## 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 |
-### 🔍 Validação Automática
-**Cada fase tem checklist específico por tier**:
-```typescript
-// Exemplo: Fase 1 (Produto)
-gate_checklist_essencial = [
-  "Problema claramente definido",
-  "MVP com funcionalidades listadas"
-]
-gate_checklist_base = [
-  ...gate_checklist_essencial,
-  "Personas identificadas",
-  "North Star Metric definida"
-]
-gate_checklist_avancado = [
-  ...gate_checklist_base,
-  "Análise de concorrentes",
-  "Business Model Canvas",
-  "Roadmap trimestral"
-]
-```
-**Cálculo de Score**:
-```typescript
-score = (itens_validados / total_itens) * 100
-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"
-}
-```
-### 🚦 Protocolo de Gate
-**1. Validação Automática (antes de avançar)**:
-```
-proximo(entregavel)
-  ↓
-validar_gate(fase_atual, entregavel)
-  ↓
-score >= 70?
-  ├─ SIM → Avança automaticamente
-  └─ NÃO → BLOQUEIA + mostra pendências
-```
-**2. Bloqueio (score < 70)**:
-```markdown
-🔴 **Gate Bloqueado** (Score: {score}/100)
-**Itens Validados** ✅:
-- [item 1]
-- [item 2]
-**Itens Pendentes** ❌:
-- [pendência 1]
-- [pendência 2]
-**Opções**:
-1. Corrigir pendências e validar novamente
-2. Solicitar aprovação manual (justificar)
-```
-**3. Aprovação Manual**:
-```
-Usuário: "aprovar mesmo assim porque [justificativa]"
-  ↓
-IA chama: aprovar_gate(acao: "aprovar", estado_json, diretorio)
-  ↓
-MCP registra aprovação forçada + motivo
-  ↓
-Avança para próxima fase
-```
----
-## TIER 4: TOOLS MCP
-### 🛠️ Tools Principais
-**Gerenciamento de Projeto**:
-```typescript
-// Iniciar novo projeto
-iniciar_projeto(nome, descricao?, diretorio?)
-→ Cria .maestro/, inicia Fase 1, carrega especialista
-// Confirmar criação (após análise)
-confirmar_projeto(nome, diretorio, tipo_artefato, nivel_complexidade)
-→ Efetiva projeto com classificação escolhida
-// Reclassificar (após PRD ou durante projeto)
-classificar(nivel?, prd?, estado_json, diretorio)
-→ Analisa e sugere nova classificação
-// Confirmar reclassificação
-confirmar_classificacao(nivel, tipo_artefato?, estado_json, diretorio)
-→ Aplica nova classificação e ajusta fluxo
-```
-**Avanço de Fases**:
-```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
-```
-**Consultas**:
-```typescript
-// Status completo
-status(estado_json, diretorio)
-→ Projeto, fase, gates, métricas
-// Contexto acumulado
-contexto(estado_json, diretorio)
-→ Resumo + stack + modelo + arquitetura
-// 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/
-```
-**Fluxos Alternativos**:
-```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
-```
-### 🎯 Uso Correto dos Tools
-**SEMPRE passar `estado_json` e `diretorio`**:
-```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()
-})
-```
----
-## 📁 QUICK REFERENCE
-### 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"
-### Estrutura de Arquivos
-```
-projeto/
-├── .maestro/
-│   ├── estado.json          # ⭐ FONTE DA VERDADE
-│   ├── resumo.json          # Cache
-│   └── rascunhos/           # Salvamentos temporários
-├── docs/
-│   ├── 01-produto/
-│   ├── 02-requisitos/
-│   └── ...
-└── src/
-```
-### Resources MCP
-```
-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
-```
-### 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 |
----
-## 🎓 EXAMPLES
-### Exemplo 1: Iniciar Projeto
-```markdown
-User: "Quero criar um sistema de gestão de pedidos para restaurante"
-AI:
-🎯 **Iniciando MCP Maestro**
-Vou iniciar o projeto. Qual o nome?
-User: "RestaurantePro"
-AI: [chama iniciar_projeto]
-🎯 **Projeto Iniciado**
-📁 Diretório: ./RestaurantePro
-📋 Fase 1: Produto
-🤖 Especialista: Gestão de Produto
-Vamos começar pelo PRD. 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?
-```
-### Exemplo 2: Avançar Fase
-```markdown
-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)]
-✅ **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)**
-Confirmar classificação?
-User: "Sim, está correto"
-AI: [chama confirmar_classificacao]
-✅ **Classificação Confirmada**
-🎯 **Fase 2: Requisitos**
-🤖 **Especialista**: Engenharia de Requisitos
-📋 **Entregável**: requisitos.md
-Como Engenheiro de Requisitos, vou elaborar...
-```
-### Exemplo 3: Gate Bloqueado
-```markdown
-User: "Próximo"
-AI: [chama validar_gate]
-🔴 **Gate Bloqueado** (Score: 60/100)
-**Itens Validados** ✅:
-- Requisitos funcionais com IDs únicos
-- Requisitos não-funcionais definidos
-**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
-Deseja corrigir ou aprovar mesmo assim?
-```
----
-## 🔧 TROUBLESHOOTING
-### Problema: "Tool retorna erro de estado"
-**Causa**: Não passou `estado_json`
-**Solução**:
-```typescript
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-// Passar em TODOS os tools
-```
-### Problema: "Especialista errado carregado"
-**Causa**: Não verificou `fase_atual` antes de carregar
-**Solução**:
-```typescript
-const estado = JSON.parse(estadoJson);
-const fase = estado.fase_atual; // Usar isso para mapear
-```
-### 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
+# MCP Maestro Development Kit - AI Rules
+> Este arquivo define como a IA deve se comportar ao trabalhar com o sistema MCP Maestro.
+---
+## CRITICAL: MCP MAESTRO PROTOCOL (START HERE)
+> **MANDATORY:** Você DEVE seguir o protocolo MCP Maestro para todos os projetos neste workspace.
+### 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
+### 2. Princípio Stateless (CRÍTICO)
+```
+❌ ERRADO: Assumir estado prévio em memória
+✅ CORRETO: Estado SEMPRE em .maestro/estado.json
+```
+**Protocolo obrigatório**:
+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
+4. NUNCA confiar em memória de conversação
+### 3. Filosofia: Qualidade Adaptativa
+**Princípio Central**: Qualidade não é negociável, formalidade é adaptável.
+| 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 |
+| Product | Base/Avançado | Estado da arte | SaaS, Fintech |
+---
+## 📥 REQUEST CLASSIFIER (STEP 1)
+**Antes de QUALQUER ação, classificar o request:**
+| 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 |
+---
+## 🤖 SPECIALIST AUTO-LOADING (STEP 2 - AUTO)
+**SEMPRE ATIVO: Carregar especialista correto para cada fase**
+### Protocol de Carregamento
+```
+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
+```
+### Mapeamento Fase → Especialista
+**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`
+**Fase Stitch (Opcional)** - Inserida após UX Design:
+- Prototipagem → `Prototipagem Rápida com Google Stitch`
+### Response Format (MANDATORY)
+Ao carregar especialista, informar:
+```markdown
+🎯 **Fase {número}: {nome}**
+🤖 **Especialista**: `{nome_especialista}`
+📋 **Entregável**: {entregavel_esperado}
+[Continuar com instruções do especialista]
+```
+---
+## TIER 0: REGRAS UNIVERSAIS (Always Active)
+### 🌐 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)
+**ANTES de chamar qualquer tool MCP**:
+```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**:
+```
+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
+```
+**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
+### 🧠 Read → Understand → Apply
+```
+❌ ERRADO: Ler especialista → Gerar conteúdo genérico
+✅ CORRETO: Ler → Entender PRINCÍPIOS → Aplicar PERSONA → Gerar
+```
+**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?
+---
+## TIER 1: FLUXO DE PROJETO
+### 📱 Classificação Automática
+**Quando**: Após Fase 1 (PRD) ser concluída
+**Critérios de Análise** (do PRD):
+| 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)
+**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
+```
+### 🎭 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**:
+```
+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**:
+```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";
+  }
+}
+```
+### 🔄 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
+```
+**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
+```
+**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
+```
+---
+## TIER 2: ESPECIALISTAS
+### 🧠 Protocolo de Carregamento Automático
+**Sempre que mudar de fase**:
+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
+**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
+```markdown
+❌ ERRADO:
+"Vou criar o PRD..."
+[Gera texto genérico]
+✅ CORRETO:
+🤖 **Especialista**: Gestão de Produto
+Como Product Manager, vou aplicar o framework RICE para priorização...
+**Template PRD aplicado:**
+1. Problema
+2. Personas
+3. MVP
+4. North Star Metric
+...
+```
+---
+## 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 |
+### 🔍 Validação Automática
+**Cada fase tem checklist específico por tier**:
+```typescript
+// Exemplo: Fase 1 (Produto)
+gate_checklist_essencial = [
+  "Problema claramente definido",
+  "MVP com funcionalidades listadas"
+]
+gate_checklist_base = [
+  ...gate_checklist_essencial,
+  "Personas identificadas",
+  "North Star Metric definida"
+]
+gate_checklist_avancado = [
+  ...gate_checklist_base,
+  "Análise de concorrentes",
+  "Business Model Canvas",
+  "Roadmap trimestral"
+]
+```
+**Cálculo de Score**:
+```typescript
+score = (itens_validados / total_itens) * 100
+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"
+}
+```
+### 🚦 Protocolo de Gate
+**1. Validação Automática (antes de avançar)**:
+```
+proximo(entregavel)
+  ↓
+validar_gate(fase_atual, entregavel)
+  ↓
+score >= 70?
+  ├─ SIM → Avança automaticamente
+  └─ NÃO → BLOQUEIA + mostra pendências
+```
+**2. Bloqueio (score < 70)**:
+```markdown
+🔴 **Gate Bloqueado** (Score: {score}/100)
+**Itens Validados** ✅:
+- [item 1]
+- [item 2]
+**Itens Pendentes** ❌:
+- [pendência 1]
+- [pendência 2]
+**Opções**:
+1. Corrigir pendências e validar novamente
+2. Solicitar aprovação manual (justificar)
+```
+**3. Aprovação Manual**:
+```
+Usuário: "aprovar mesmo assim porque [justificativa]"
+  ↓
+IA chama: aprovar_gate(acao: "aprovar", estado_json, diretorio)
+  ↓
+MCP registra aprovação forçada + motivo
+  ↓
+Avança para próxima fase
+```
+---
+## TIER 4: TOOLS MCP
+### 🛠️ Tools Principais
+**Gerenciamento de Projeto**:
+```typescript
+// Iniciar novo projeto
+iniciar_projeto(nome, descricao?, diretorio?)
+→ Cria .maestro/, inicia Fase 1, carrega especialista
+// Confirmar criação (após análise)
+confirmar_projeto(nome, diretorio, tipo_artefato, nivel_complexidade)
+→ Efetiva projeto com classificação escolhida
+// Reclassificar (após PRD ou durante projeto)
+classificar(nivel?, prd?, estado_json, diretorio)
+→ Analisa e sugere nova classificação
+// Confirmar reclassificação
+confirmar_classificacao(nivel, tipo_artefato?, estado_json, diretorio)
+→ Aplica nova classificação e ajusta fluxo
+```
+**Avanço de Fases**:
+```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
+```
+**Consultas**:
+```typescript
+// Status completo
+status(estado_json, diretorio)
+→ Projeto, fase, gates, métricas
+// Contexto acumulado
+contexto(estado_json, diretorio)
+→ Resumo + stack + modelo + arquitetura
+// 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/
+```
+**Fluxos Alternativos**:
+```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
+```
+### 🎯 Uso Correto dos Tools
+**SEMPRE passar `estado_json` e `diretorio`**:
+```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()
+})
+```
+---
+## 📁 QUICK REFERENCE
+### 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"
+### Estrutura de Arquivos
+```
+projeto/
+├── .maestro/
+│   ├── estado.json          # ⭐ FONTE DA VERDADE
+│   ├── resumo.json          # Cache
+│   └── rascunhos/           # Salvamentos temporários
+├── docs/
+│   ├── 01-produto/
+│   ├── 02-requisitos/
+│   └── ...
+└── src/
+```
+### Resources MCP
+```
+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
+```
+### 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 |
+---
+## 🎓 EXAMPLES
+### Exemplo 1: Iniciar Projeto
+```markdown
+User: "Quero criar um sistema de gestão de pedidos para restaurante"
+AI:
+🎯 **Iniciando MCP Maestro**
+Vou iniciar o projeto. Qual o nome?
+User: "RestaurantePro"
+AI: [chama iniciar_projeto]
+🎯 **Projeto Iniciado**
+📁 Diretório: ./RestaurantePro
+📋 Fase 1: Produto
+🤖 Especialista: Gestão de Produto
+Vamos começar pelo PRD. 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?
+```
+### Exemplo 2: Avançar Fase
+```markdown
+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)]
+✅ **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)**
+Confirmar classificação?
+User: "Sim, está correto"
+AI: [chama confirmar_classificacao]
+✅ **Classificação Confirmada**
+🎯 **Fase 2: Requisitos**
+🤖 **Especialista**: Engenharia de Requisitos
+📋 **Entregável**: requisitos.md
+Como Engenheiro de Requisitos, vou elaborar...
+```
+### Exemplo 3: Gate Bloqueado
+```markdown
+User: "Próximo"
+AI: [chama validar_gate]
+🔴 **Gate Bloqueado** (Score: 60/100)
+**Itens Validados** ✅:
+- Requisitos funcionais com IDs únicos
+- Requisitos não-funcionais definidos
+**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
+Deseja corrigir ou aprovar mesmo assim?
+```
+---
+## 🔧 TROUBLESHOOTING
+### Problema: "Tool retorna erro de estado"
+**Causa**: Não passou `estado_json`
+**Solução**:
+```typescript
+const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
+// Passar em TODOS os tools
+```
+### Problema: "Especialista errado carregado"
+**Causa**: Não verificou `fase_atual` antes de carregar
+**Solução**:
+```typescript
+const estado = JSON.parse(estadoJson);
+const fase = estado.fase_atual; // Usar isso para mapear
+```
+### 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