@maestro-ai/cli 1.1.0 → 1.2.0

package/content/workflows/mcp-next.md

@@ -1,388 +0,0 @@
----
-description: Avançar fase MCP com validação de gates e salvamento de entregável
----
-
-# /mcp-next - Avançar Fase MCP
-
-$ARGUMENTS
-
----
-
-## Objetivo
-
-Salvar entregável da fase atual, validar gates de qualidade, e avançar para próxima fase do fluxo MCP Maestro.
-
----
-
-## Protocolo Stateless MCP (CRÍTICO)
-
-> [!IMPORTANT]
-> **OBRIGATÓRIO antes de QUALQUER tool MCP:**
-> ```typescript
-> const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-> // Passar estadoJson em TODOS os tools
-> ```
-
----
-
-## Fluxo de Execução
-
-### Passo 1: Verificar Contexto MCP
-
-```typescript
-// Verificar se existe projeto MCP
-if (!fs.existsSync('.maestro/estado.json')) {
-  return "❌ Nenhum projeto MCP ativo. Use /mcp-start para iniciar.";
-}
-
-// Ler estado
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-const estado = JSON.parse(estadoJson);
-
-// Mostrar contexto
-console.log(`
-📋 **Fase Atual:** ${estado.fase_atual} - ${estado.fases[estado.fase_atual - 1].nome}
-📄 **Entregável Esperado:** ${estado.fases[estado.fase_atual - 1].template}
-`);
-```
-
----
-
-### Passo 2: Coletar Entregável
-
-**Se usuário forneceu arquivo como argumento:**
-
-```bash
-/mcp-next docs/01-produto/PRD.md
-```
-
-**Ler arquivo:**
-
-```typescript
-const entregavel = await fs.readFile(argumentoArquivo, 'utf-8');
-```
-
-**Se NÃO forneceu argumento:**
-
-```markdown
-📝 **Entregável da Fase [numero]**
-
-Como deseja fornecer o entregável?
-
-1. Colar conteúdo diretamente
-2. Informar caminho do arquivo
-
-Escolha (1/2):
-```
-
-**Se opção 1:**
-```
-Cole o conteúdo do entregável abaixo:
-```
-
-**Se opção 2:**
-```
-Qual o caminho do arquivo?
-Exemplo: docs/01-produto/PRD.md
-```
-
----
-
-### Passo 3: Validar Gate
-
-```typescript
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-
-const resultado = await mcp_maestro_validar_gate({
-  entregavel: entregavel,
-  estado_json: estadoJson,
-  diretorio: process.cwd()
-});
-```
-
-**MCP retorna:**
-- `valido`: boolean
-- `score`: 0-100
-- `checklist`: array de itens
-- `pendencias`: array de strings
-
----
-
-### Passo 4: Apresentar Resultado da Validação
-
-#### Cenário A: Score >= 70 (Aprovado ✅)
-
-```markdown
-✅ **Gate Aprovado** (Score: ${score}/100)
-
-**Checklist da Fase:**
-${checklist.map(item => `${item.validado ? '✅' : '⚠️'} ${item.nome}`).join('\n')}
-
-${pendencias.length > 0 ? `
-**Pendências Menores:**
-${pendencias.map(p => `- ${p}`).join('\n')}
-
-(Pode avançar, mas considere corrigir depois)
-` : ''}
-
-Avançando para próxima fase...
-```
-
-**Chamar proximo automaticamente:**
-
-```typescript
-await mcp_maestro_proximo({
-  entregavel: entregavel,
-  estado_json: estadoJson,
-  diretorio: process.cwd()
-});
-```
-
-#### Cenário B: Score < 70 (Bloqueado 🔴)
-
-```markdown
-🔴 **Gate Bloqueado** (Score: ${score}/100)
-
-**Itens Validados** ✅:
-${checklist.filter(i => i.validado).map(i => `- ${i.nome}`).join('\n')}
-
-**Itens Pendentes** ❌:
-${checklist.filter(i => !i.validado).map(i => `- ${i.nome}`).join('\n')}
-
-**Sugestões de Correção:**
-${pendencias.map(p => `- ${p}`).join('\n')}
-
----
-
-**Opções:**
-
-1. **Corrigir pendências** → Atualize o entregável e execute `/mcp-next [arquivo]` novamente
-2. **Aprovar manualmente** → Se tiver motivo justificado, posso informar como forçar
-
-Qual opção? (1/2)
-```
-
-**Se usuário escolher opção 2:**
-
-> [!CAUTION]
-> **NUNCA** chamar `aprovar_gate` automaticamente!
-> 
-> Apenas **INFORMAR** ao usuário:
-
-```markdown
-⚠️ **Aprovação Manual de Gate**
-
-Para aprovar este gate manualmente, você (usuário) precisa:
-
-1. Entender os riscos de avançar com pendências
-2. Ter justificativa documentada
-3. Executar: `/mcp-gate approve [justificativa]`
-
-**Exemplo:**
-/mcp-gate approve "MVP inicial, vamos refinar depois"
-
-❌ **Eu (IA) NÃO posso aprovar gates automaticamente.**
-```
-
----
-
-### Passo 5: Apresentar Próxima Fase
-
-**Após avançar com sucesso:**
-
-```typescript
-// Recarregar estado atualizado
-const novoEstadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-const novoEstado = JSON.parse(novoEstadoJson);
-
-// Carregar especialista da próxima fase
-const proximaFase = novoEstado.fases[novoEstado.fase_atual - 1];
-const especialista = await fetch(`maestro://especialista/${proximaFase.especialista}`);
-```
-
-**Apresentar:**
-
-```markdown
-✅ **Entregável Salvo:** docs/${faseConcluida.numero}-${faseConcluida.slug}/${arquivo}
-
----
-
-🎯 **Fase ${proximaFase.numero}/${totalFases}: ${proximaFase.nome}**
-🤖 **Especialista:** ${proximaFase.especialista}
-📄 **Entregável Esperado:** ${proximaFase.template}
-
----
-
-## 🎯 ${proximaFase.nome}
-
-${especialista.introducao}
-
-${especialista.perguntas_iniciais}
-```
-
----
-
-## Comandos
-
-```
-/mcp-next                    → Wizard (pede entregável)
-/mcp-next [arquivo]          → Usa arquivo como entregável
-/mcp-next --force [arquivo]  → ❌ NÃO SUPORTADO (usar /mcp-gate approve)
-```
-
----
-
-## Exemplos de Uso
-
-### Exemplo 1: Gate Aprovado Automaticamente
-
-```
-User: /mcp-next docs/01-produto/PRD.md
-
-AI: Validando gate da Fase 1...
-
-    ✅ Gate Aprovado (Score: 95/100)
-    
-    Checklist:
-    ✅ Problema claramente definido
-    ✅ Personas identificadas
-    ✅ MVP com funcionalidades listadas
-    ✅ North Star Metric definida
-    
-    Avançando para próxima fase...
-    
-    ✅ PRD Salvo: docs/01-produto/PRD.md
-    
-    🎯 Fase 2/13: Requisitos
-    🤖 Especialista: Engenharia de Requisitos
-    
-    Vamos elaborar os requisitos funcionais e não-funcionais...
-```
-
-### Exemplo 2: Gate Bloqueado
-
-```
-User: /mcp-next docs/02-requisitos/requisitos.md
-
-AI: Validando gate da Fase 2...
-
-    🔴 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:
-    - Adicione cenários Gherkin para cada RF (Dado/Quando/Então)
-    - Crie tabela mapeando RF → User Story
-    
-    ---
-    
-    Opções:
-    1. Corrigir pendências
-    2. Aprovar manualmente
-    
-    Qual? (1/2)
-
-User: 1
-
-AI: Certo! Atualize o arquivo `docs/02-requisitos/requisitos.md` 
-    e execute `/mcp-next` novamente quando estiver pronto.
-```
-
-### Exemplo 3: Wizard Interativo
-
-```
-User: /mcp-next
-
-AI: 📋 Fase Atual: 3 - UX Design
-    📄 Entregável Esperado: design-doc.md
-    
-    Como deseja fornecer o entregável?
-    1. Colar conteúdo
-    2. Informar arquivo
-    
-    Escolha: 
-
-User: 2
-
-AI: Qual o caminho do arquivo?
-
-User: docs/03-ux/design-doc.md
-
-AI: Validando gate...
-    [continua validação]
-```
-
----
-
-## Regras Críticas
-
-### ✅ SEMPRE Fazer:
-
-1. Ler `.maestro/estado.json` ANTES de qualquer tool MCP
-2. Passar `estado_json` em TODOS os tools
-3. Validar gate ANTES de chamar `proximo`
-4. Apresentar resultado de validação ao usuário
-5. Carregar especialista da próxima fase
-
-### ❌ NUNCA Fazer:
-
-1. Chamar `proximo` sem validar gate antes
-2. Chamar `aprovar_gate` automaticamente
-3. Usar `forcar: true` sem aprovação explícita do usuário
-4. Avançar com score < 70 sem mostrar pendências
-5. Assumir que arquivo existe sem verificar
-
----
-
-## Gate Protection Protocol
-
-> [!CAUTION]
-> **Quando `validar_gate` retorna `valido: false`:**
-> 
-> 1. 🛑 **PARAR** - Não chamar `proximo()`
-> 2. 📊 **MOSTRAR** - Itens pendentes ao usuário
-> 3. 💡 **SUGERIR** - Correções baseadas em checklist
-> 4. ⏸️ **AGUARDAR** - Decisão do usuário
-> 
-> **NUNCA:**
-> - ❌ Chamar `aprovar_gate` automaticamente
-> - ❌ Usar `forcar: true` sem aprovação explícita
-> - ❌ Ignorar gates ou pular validações
-
----
-
-## Troubleshooting
-
-### Erro: "estado.json not found"
-
-```
-❌ Nenhum projeto MCP ativo.
-
-Use `/mcp-start` para iniciar um novo projeto.
-```
-
-### Erro: "Fase já concluída"
-
-```
-⚠️ Esta fase já foi concluída.
-
-Use `/mcp-status` para ver a fase atual.
-```
-
-### Score Sempre < 70
-
-**Causa:** Tier de gate muito rigoroso para o tipo de projeto.
-
-**Solução:** Reclassificar projeto:
-
-```
-/mcp-start reclassificar
-```
-
-Ou aprovar manualmente com justificativa.

package/content/workflows/mcp-start.md

@@ -1,304 +0,0 @@
----
-description: Iniciar projeto MCP com classificação automática e wizard interativo
----
-
-# /mcp-start - Iniciar Projeto MCP Maestro
-
-$ARGUMENTS
-
----
-
-## Objetivo
-
-Iniciar novo projeto usando o sistema MCP Maestro com classificação automática de complexidade, seleção de tier de gates, e opção de prototipagem com Stitch.
-
----
-
-## Protocolo Stateless MCP (CRÍTICO)
-
-> [!IMPORTANT]
-> **ANTES de chamar QUALQUER tool MCP:**
-> 1. Ler `.maestro/estado.json` (se existir)
-> 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
-
----
-
-## Fluxo de Execução
-
-### Passo 1: Coleta de Informações
-
-**Perguntar ao usuário:**
-
-```
-🎯 **Iniciando Projeto MCP Maestro**
-
-1. Qual o nome do projeto?
-2. Descreva brevemente o projeto (problema, solução, público-alvo):
-```
-
-**Se usuário forneceu argumentos:**
-- `/mcp-start NomeProjeto` → Usar nome, pedir descrição
-- `/mcp-start` → Pedir nome e descrição
-
----
-
-### Passo 2: Análise e Classificação Automática
-
-**Chamar MCP tool:**
-
-```typescript
-await mcp_maestro_iniciar_projeto({
-  nome: "[nome fornecido]",
-  descricao: "[descrição fornecida]",
-  diretorio: process.cwd()
-});
-```
-
-**MCP retorna:**
-- Classificação sugerida: `tipo_artefato` (poc/script/internal/product)
-- Nível de complexidade: `nivel_complexidade` (simples/medio/complexo)
-- Tier de gates: `tier_gate` (essencial/base/avancado)
-- Número de fases resultante
-- Justificativa da classificação
-
----
-
-### Passo 3: Apresentar Classificação ao Usuário
-
-```markdown
-📊 **Classificação Automática**
-
-Analisei sua descrição e sugiro:
-
-- **Tipo de Artefato:** [POC/Script/Internal/Product]
-- **Complexidade:** [Simples/Médio/Complexo]
-- **Número de Fases:** [7/13/17]
-- **Tier de Gates:** [Essencial/Base/Avançado]
-
-**Justificativa:**
-- [motivo 1]
-- [motivo 2]
-- [motivo 3]
-
-**Isso significa:**
-- [O que o tier de gate valida]
-- [Quais especialistas serão usados]
-
-Confirmar classificação? (Y/N)
-Se quiser ajustar, responda: "reclassificar para [simples/medio/complexo]"
-```
-
----
-
-### Passo 4: Confirmação ou Reclassificação
-
-**Se usuário confirmar (Y):**
-
-```typescript
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-
-await mcp_maestro_confirmar_projeto({
-  nome: "[nome]",
-  diretorio: process.cwd(),
-  tipo_artefato: "[tipo sugerido]",
-  nivel_complexidade: "[nivel sugerido]"
-});
-```
-
-**Se usuário quiser reclassificar:**
-
-```typescript
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-
-await mcp_maestro_classificar({
-  nivel: "[simples/medio/complexo]",
-  estado_json: estadoJson,
-  diretorio: process.cwd()
-});
-
-// Após reclassificação, confirmar:
-await mcp_maestro_confirmar_classificacao({
-  nivel: "[novo nivel]",
-  tipo_artefato: "[tipo]",
-  estado_json: estadoJson,
-  diretorio: process.cwd()
-});
-```
-
----
-
-### Passo 5: Opção de Prototipagem com Stitch (Opcional)
-
-```markdown
-🎨 **Prototipagem com Google Stitch**
-
-Deseja incluir uma fase de **Prototipagem Rápida com Google Stitch**?
-
-Isso adiciona uma fase após UX Design para:
-- Gerar prompts otimizados para Stitch
-- Criar protótipos HTML/CSS validados
-- Exportar código para produção
-
-Usar Stitch? (Y/N)
-```
-
-**Se Y:**
-
-```typescript
-const estadoJson = await fs.readFile('.maestro/estado.json', 'utf-8');
-
-await mcp_maestro_confirmar_stitch({
-  usar_stitch: true,
-  estado_json: estadoJson,
-  diretorio: process.cwd()
-});
-```
-
----
-
-### Passo 6: Apresentar Fase Inicial
-
-```markdown
-✅ **Projeto Iniciado com Sucesso**
-
-📁 **Diretório:** [diretorio]
-📋 **Fase 1/[total]:** Produto
-🤖 **Especialista:** Gestão de Produto
-📄 **Entregável Esperado:** PRD.md
-
----
-
-## 🎯 Fase 1: Visão de Produto
-
-Como **Especialista em Gestão de Produto**, vou ajudá-lo a definir:
-
-1. **Problema** - Que dor estamos resolvendo?
-2. **Solução** - Como vamos resolver?
-3. **Público-alvo** - Quem são os usuários?
-4. **MVP** - O que entra na primeira versão?
-5. **Métricas** - Como medir sucesso (North Star Metric)?
-
-Vamos começar. Qual o **principal problema** que este produto resolve?
-```
-
-**Carregar especialista:**
-
-```typescript
-const especialista = await fetch('maestro://especialista/gestao-de-produto');
-// Aplicar persona e instruções do especialista
-```
-
----
-
-## Estrutura Criada
-
-Após execução bem-sucedida, o projeto terá:
-
-```
-[nome-projeto]/
-├── .maestro/
-│   ├── estado.json       # ⭐ Fonte da verdade (STATE)
-│   └── resumo.json       # Cache de contexto
-└── docs/
-    └── 01-produto/       # Criado quando salvar PRD
-```
-
----
-
-## Comandos Relacionados
-
-```
-/mcp-start              → Wizard completo (recomendado)
-/mcp-start MeuProjeto   → Inicia com nome, pede descrição
-/mcp-status             → Ver status após criação
-/mcp-next               → Avançar para próxima fase
-```
-
----
-
-## Exemplos de Uso
-
-### Exemplo 1: SaaS Simples
-
-```
-User: /mcp-start
-
-AI: Qual o nome do projeto?
-User: TaskFlow
-
-AI: Descreva brevemente o projeto:
-User: Gerenciador de tarefas para times pequenos, até 10 usuários
-
-AI: 📊 Classificação Automática
-    - Tipo: Internal
-    - Complexidade: Simples (7 fases)
-    - Tier: Base
-    - Justificativa: Escala pequena, sem integrações complexas
-
-User: Y
-
-AI: Usar Stitch?
-User: N
-
-AI: ✅ Projeto iniciado! Fase 1: Produto...
-```
-
-### Exemplo 2: Fintech Complexo
-
-```
-User: /mcp-start
-
-AI: Qual o nome do projeto?
-User: PaySecure
-
-AI: Descreva brevemente o projeto:
-User: Plataforma de pagamentos com multi-tenancy, compliance PCI-DSS, 100k+ usuários
-
-AI: 📊 Classificação Automática
-    - Tipo: Product
-    - Complexidade: Complexo (17 fases)
-    - Tier: Avançado
-    - Justificativa: 
-      - Multi-tenancy detectado
-      - Compliance rigoroso (PCI-DSS)
-      - Alta escala (100k+ usuários)
-
-User: Y
-
-AI: Usar Stitch?
-User: Y
-
-AI: ✅ Projeto iniciado! Fase Stitch incluída após UX...
-```
-
----
-
-## Regras Críticas
-
-1. ✅ **SEMPRE** ler `estado.json` antes de chamar tools MCP
-2. ✅ **SEMPRE** passar `estado_json` como argumento
-3. ✅ **AGUARDAR** confirmação do usuário antes de `confirmar_projeto`
-4. ❌ **NUNCA** assumir classificação sem mostrar ao usuário
-5. ❌ **NUNCA** pular wizard, sempre fazer perguntas
-6. ❌ **NUNCA** avançar automaticamente para Fase 2 (usar `/mcp-next`)
-
----
-
-## Troubleshooting
-
-### Erro: "estado.json not found"
-
-**Causa:** Tool MCP esperava estado mas projeto não foi criado ainda.
-
-**Solução:** Normal no primeiro `iniciar_projeto`. Ignorar e continuar.
-
-### Classificação Parece Errada
-
-**Solução:** Perguntar ao usuário se quer reclassificar:
-
-```
-A classificação parece adequada? Se quiser ajustar, diga:
-"reclassificar para [simples/medio/complexo]"
-```