@maestro-ai/cli 1.0.0 → 1.2.0

package/content/rules/RULES.md

@@ -0,0 +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