@maestro-ai/cli 1.1.0 → 1.2.0

package/content/workflows/brainstorm.md

@@ -1,16 +1,29 @@
 ---
-description: Structured brainstorming for projects and features. Explores multiple options before implementation.
+description: Exploração estruturada de ideias, integrada ao estado do Maestro.
 ---
 
-# /brainstorm - Structured Idea Exploration
+# /brainstorm - Exploração Estruturada de Ideias
 
 $ARGUMENTS
 
 ---
 
+## Pré-requisitos e conexão com o Maestro
+
+1. Execute `/maestro` para validar o estado atual e detectar fase/artefatos focos.
+2. Carregue `.maestro/estado.json` para contextualizar o brainstorming com o problema/fase em andamento:
+   ```javascript
+   const estado = lerJson('.maestro/estado.json');
+   const faseAtual = estado.fases?.[estado.faseAtual];
+   ```
+3. Registre no histórico (`estado.historico`) o evento `brainstorm_executado`, indicando o tópico e os caminhos escolhidos. Chame `salvarEstado(estado)` após concluir.
+4. Use `content/guides/fases-mapeamento.md` para puxar especialistas/prompts relacionados (ex.: fase 1 → Gestão de Produto, fase 3 → UX).
+
+---
+
 ## Purpose
 
-This command activates BRAINSTORM mode for structured idea exploration. Use when you need to explore options before committing to an implementation.
+This command activates BRAINSTORM mode for structured idea exploration. Use when you need to explore options before committing to an implementation and quer salvar as conclusões no estado do Maestro.
 
 ---
 
@@ -22,6 +35,7 @@ When `/brainstorm` is triggered:
    - What problem are we solving?
    - Who is the user?
    - What constraints exist?
+   - Relacione com `faseAtual.nome` e `faseAtual.especialista` para manter alinhamento.
 
 2. **Generate options**
    - Provide at least 3 different approaches
@@ -34,7 +48,7 @@ When `/brainstorm` is triggered:
 
 ---
 
-## Output Format
+## Output Format (registrar em `docs/brainstorm/<slug>.md` e anexar ao estado)
 
 ```markdown
 ## 🧠 Brainstorm: [Topic]
@@ -97,10 +111,10 @@ What direction would you like to explore?
 ## Examples
 
 ```
-/brainstorm authentication system
-/brainstorm state management for complex form
-/brainstorm database schema for social app
-/brainstorm caching strategy
+/brainstorm authentication system (fase 2 – requisitos)
+/brainstorm redesign para dashboard (fase 3 – UX)
+/brainstorm integrações com ERP (fase 6 – Integração)
+/brainstorm caching strategy para escala
 ```
 
 ---

package/content/workflows/continuar-fase.md

@@ -0,0 +1,64 @@
+---
+description: Retoma a fase atual exatamente do ponto onde foi interrompida
+---
+
+# 🔄 Workflow de Continuação - /continuar-fase
+
+## 1. Ler estado atual
+
+```javascript
+const estado = lerJson('.maestro/estado.json');
+const faseAtual = estado.fases[estado.faseAtual];
+if (!faseAtual) throw new Error('Fase atual não encontrada');
+
+function salvarEstado(state) {
+  escreverJson('.maestro/estado.json', state, { spaces: 2 });
+}
+```
+
+## 2. Identificar último artefato
+
+- Use `faseAtual.artefatos` para encontrar o arquivo principal.
+- Se vazio, referencie o template padrão da fase (ex.: `docs/01-produto/PRD.md`).
+
+```javascript
+const arquivo = faseAtual.artefatos?.slice(-1)[0] || faseAtual.entregavel;
+const analise = analisarArquivo(arquivo);
+/* analise = {
+   secoesPreenchidas,
+   secoesFaltantes,
+   percentualCompleto,
+   proximaSecao
+} */
+```
+
+## 3. Mensagem de retomada
+
+```
+📋 **Retomando Fase {estado.faseAtual}/{estado.totalFases} - {faseAtual.nome}**
+- Especialista: {faseAtual.especialista}
+- Artefato: {arquivo}
+- Progresso: {analise.percentualCompleto}%
+- Última ação: {analise.ultimaSecao}
+- Próxima tarefa: {analise.proximaSecao}
+```
+
+## 4. Carregar contexto
+
+1. Consulte `content/guides/fases-mapeamento.md` para mapear fase → especialista/prompt/template/skills.
+2. Abra o especialista e prompt correspondentes. Ex.: fase 2 → `specialists/Especialista em Engenharia de Requisitos com IA.md` + `prompts/requisitos.md`.
+3. Carregue os templates associados (ver tabela) e compare com o artefato atual para detectar seções faltantes.
+4. Liste explicitamente na resposta quais arquivos serão atualizados (ex.: `docs/02-requisitos/requisitos.md`, `templates/matriz-rastreabilidade.md`).
+
+## 5. Retomar execução
+
+- Perguntar ao usuário se deseja continuar exatamente da próxima seção, revisar algo ou mudar o foco.
+- Ao continuar, seguir checklist da fase (regras em `content/rules/validation-rules.md`).
+
+## 6. Atualização de estado (manual)
+
+Quando terminar a sessão:
+- Atualizar `faseAtual.progresso` e `faseAtual.artefatos`.
+- Registrar nota no histórico, se necessário.
+- Atualizar `estado.metrica.ultimoComando = '/continuar-fase'`.
+- Chamar `salvarEstado(estado)` para persistir.

package/content/workflows/{mcp-debug.md → corrigir-bug.md}

@@ -2,12 +2,27 @@
 description: Correção de bugs com fluxo estruturado (Reprodução → Análise → Fix → Regressão)
 ---
 
-# /mcp-debug - Correção de Bug MCP
+# /corrigir-bug - Correção de Bug Maestro
 
 $ARGUMENTS
 
 ---
 
+## Integração com o Maestro
+
+1. Execute `/maestro` antes para garantir que o estado está sincronizado e detectar bloqueios ativos.
+2. Crie helpers mentais para ler e salvar estado:
+   ```javascript
+   const estado = lerJson('.maestro/estado.json');
+   function salvarEstado(next) {
+     escreverJson('.maestro/estado.json', next, { spaces: 2 });
+   }
+   ```
+3. Sempre passe `estado_json` para qualquer tool MCP que for invocado e registre eventos no `estado.historico` (`acao: "bug_iniciado"`, `bug_id`, `severidade`).
+4. Use `content/guides/fases-mapeamento.md` para carregar especialistas, prompts e templates de apoio (Debugging, DevOps, Testes, etc.).
+
+---
+
 ## Objetivo
 
 Corrigir bugs de forma estruturada usando fluxo de 4 fases do MCP Maestro, com análise de causa raiz e testes de regressão.
@@ -21,8 +36,8 @@ Corrigir bugs de forma estruturada usando fluxo de 4 fases do MCP Maestro, com a
 - Erro que requer análise sistemática
 
 **NÃO usar para:**
-- Nova funcionalidade → Use `/mcp-feature`
-- Refatoração de código → Use `/mcp-refactor`
+- Nova funcionalidade → Use `/nova-feature`
+- Refatoração de código → Use `/refatorar-codigo`
 
 ---
 
@@ -71,12 +86,21 @@ Corrigir bugs de forma estruturada usando fluxo de 4 fases do MCP Maestro, com a
 
 ### Passo 2: Iniciar Fluxo de Debugging
 
+> [!IMPORTANT]
+> **Protocolo stateless:** carregar `.maestro/estado.json` do disco antes de qualquer chamada.
+
 ```typescript
+const estadoJson = lerArquivo('.maestro/estado.json');
+
 await mcp_maestro_corrigir_bug({
   descricao: "[descrição fornecida]",
   severidade: "[critica/alta/media/baixa]",
-  ticket_id: "[opcional: JIRA-123]"
+  ticket_id: "[opcional: JIRA-123]",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
+
+salvarEstado(registrarHistorico(estado, { acao: 'bug_iniciado', severidade }));
 ```
 
 **MCP cria contexto de bug e retorna:**
@@ -315,7 +339,7 @@ Executar deploy? Use `/deploy [ambiente]`
 ### Exemplo 1: Bug Crítico (Duplicação de Pedido)
 
 ```
-User: /mcp-debug
+User: /corrigir-bug
 
 AI: Descreva o bug:
 
@@ -382,7 +406,7 @@ AI: ✅ Fluxo iniciado (BUG-001) - Severidade CRÍTICA
 ### Exemplo 2: Bug de UI (Baixa Severidade)
 
 ```
-User: /mcp-debug Botão de logout desalinhado no mobile
+User: /corrigir-bug Botão de logout desalinhado no mobile
 
 AI: Severidade?
 

package/content/workflows/iniciar-projeto.md

@@ -0,0 +1,59 @@
+---
+description: Inicia novo projeto Maestro com classificação automática e setup inteligente
+---
+
+# 🚀 Workflow de Iniciação - /iniciar-projeto
+
+## 1. Coleta de informações
+
+Pergunte ao usuário (ou utilize argumentos) para obter:
+- Nome do projeto
+- Descrição curta (problema, público, solução)
+
+## 2. Classificação automática
+
+1. Carregue o template em `templates/estado-template.json` e os fluxos definidos em `src/src/flows/types.ts` (funções `getFluxo`, `getFluxoComStitch`).
+2. Use a função mental abaixo para sugerir configuração:
+
+```javascript
+const analise = classificarProjeto({ nome, descricao });
+const fluxo = getFluxoComStitch(analise.complexidade, analise.usarStitch);
+/* Retorna:
+ * - complexidade (simples/medio/complexo)
+ * - tier (7/13/17 fases)
+ * - especialistaInicial (fase 1 do fluxo escolhido)
+ */
+```
+
+Mostre a classificação e peça confirmação. Permita ajustes manuais caso o usuário solicite (ex.: "reclassificar para médio").
+
+## 3. Geração do estado inicial
+
+- Copie o template de estado e popule as fases com base em `fluxo.fases`.
+- Garanta que cada fase traga `especialista`, `entregavel_esperado`, `scoreMinimo` e `gate_checklist` do fluxo MCP.
+- Registre em `historico` o evento `projeto_iniciado` com justificativa da classificação.
+- Defina helpers mentais para leitura/escrita:
+  ```javascript
+  const estado = preencherTemplate(...);
+  function salvarEstado(state) {
+    escreverJson('.maestro/estado.json', state, { spaces: 2 });
+  }
+  salvarEstado(estado);
+  ```
+
+## 4. Setup do contexto
+
+- Copiar templates necessários para `docs/<fase>/...`
+- Registrar especialista inicial (`Gestão de Produto` para fase 1)
+- Preparar prompts e skills relevantes
+
+## 5. Mensagem de saída
+
+```
+✅ Projeto iniciado!
+- Fase 1/ {totalFases}: Produto
+- Especialista: Gestão de Produto
+- Entregável: docs/01-produto/PRD.md
+
+Próximo passo: responda às perguntas do especialista para preencher o PRD.
+```

package/content/workflows/maestro.md

@@ -0,0 +1,77 @@
+---
+description: Workflow universal inteligente que detecta estado e toma a próxima ação
+---
+
+# 🤖 Workflow Universal - /maestro
+
+## Objetivo
+
+Detectar automaticamente o estado do projeto Maestro, validar se o estado reflete os fluxos MCP (7/13/17 fases + Stitch) e decidir a ação adequada, respondendo no chat com contexto completo.
+
+## Sincronização com os fluxos MCP
+
+Antes de qualquer decisão:
+
+1. Ler `.maestro/estado.json` **e** o template original em `packages/cli/content/templates/estado-template.json` para entender a estrutura completa.
+2. Ler `src/src/flows/types.ts` para conhecer `FLUXO_SIMPLES`, `FLUXO_MEDIO`, `FLUXO_COMPLEXO` e a inserção opcional de Stitch (`getFluxoComStitch`).
+3. Verificar se `estado.fases` segue a mesma ordem e quantidade de fases do fluxo correspondente. Se detectar divergências (fase faltando, numeração diferente), listar no resumo e sugerir ao usuário rodar `/iniciar-projeto` ou ajustar manualmente.
+
+## Como funciona
+
+1. **Ler estado** em `.maestro/estado.json` (se não existir, classificar como `novo_projeto`).
+2. **Validar consistência** comparando `estado.fases` com o fluxo MCP adequado.
+3. **Classificar estado** usando a função mental abaixo.
+4. **Mapear ação** (`/iniciar-projeto`, `/continuar-fase`, `/avancar-fase`).
+5. **Responder** com resumo e próxima ação sugerida.
+
+```javascript
+const estado = lerJson('.maestro/estado.json');
+const fluxo = estado?.projeto
+  ? getFluxoComStitch(estado.projeto.complexidade, estado.projeto.usarStitch)
+  : null;
+
+if (!estado || !estado.projeto?.nome) {
+  return { status: 'novo_projeto', proximaAcao: '/iniciar-projeto' };
+}
+
+const faseAtual = estado.fases[estado.faseAtual];
+if (!faseAtual || faseAtual.status !== 'concluida') {
+  return {
+    status: 'fase_incompleta',
+    proximaAcao: '/continuar-fase',
+    fase: estado.faseAtual,
+    arquivoFoco: faseAtual?.artefatos?.slice(-1)[0] || fluxo?.fases?.find(f => f.numero === estado.faseAtual)?.entregavel_esperado,
+    divergenciasFluxo: compararComFluxo(estado.fases, fluxo?.fases)
+  };
+}
+
+return {
+  status: 'pronto_para_avancar',
+  proximaAcao: '/avancar-fase',
+  fase: estado.faseAtual,
+  proximaFase: estado.faseAtual + 1,
+  divergenciasFluxo: compararComFluxo(estado.fases, fluxo?.fases)
+};
+```
+
+## Template de resposta
+
+```
+📋 **Status Detectado:** {status}
+- Projeto: {estado.projeto.nome}
+- Fase atual: {estado.faseAtual}/{totalFases} - {faseAtual.nome}
+- Especialista: {faseAtual.especialista}
+- Arquivo foco: {arquivoFoco}
+
+🎯 **Próxima ação sugerida:** {proximaAcao}
+➡️ Execute o comando correspondente ou peça um ajuste específico.
+
+{divergenciasFluxo?.length ? `⚠️ Divergências detectadas entre estado e fluxo MCP:
+- ${divergenciasFluxo.join('\n- ')}` : ''}
+```
+
+## Regras rápidas
+
+- Sempre verificar se há bloqueios (`faseAtual.status === 'bloqueado'`) e destacar no resumo.
+- Se detectar `novo_projeto`, **não** tentar gerar estado: apenas orientar o usuário a rodar `/iniciar-projeto`.
+- Se o usuário preferir outra ação, respeitar e registrar no histórico (se aplicável).

package/content/workflows/{mcp-feature.md → nova-feature.md}

@@ -2,12 +2,27 @@
 description: Adicionar nova feature com fluxo estruturado (Análise → Implementação → Deploy)
 ---
 
-# /mcp-feature - Nova Feature MCP
+# /nova-feature - Nova Feature Maestro
 
 $ARGUMENTS
 
 ---
 
+## Pré-requisitos e integração com o Maestro
+
+1. Execute `/maestro` para garantir que o estado esteja sincronizado com os fluxos MCP (7/13/17 + Stitch).
+2. Carregue o estado antes de qualquer tool:
+   ```javascript
+   const estado = lerJson('.maestro/estado.json');
+   function salvarEstado(novoEstado) {
+     escreverJson('.maestro/estado.json', novoEstado, { spaces: 2 });
+   }
+   ```
+3. Use `content/guides/fases-mapeamento.md` para alinhar especialistas, prompts e templates de suporte a features.
+4. Todos os artefatos criados devem ficar dentro de `docs/features/FEATURE-ID/` e ser registrados em `estado.historico`.
+
+---
+
 ## Objetivo
 
 Adicionar nova funcionalidade em projeto existente usando fluxo estruturado de 6 fases do MCP Maestro.
@@ -21,9 +36,9 @@ Adicionar nova funcionalidade em projeto existente usando fluxo estruturado de 6
 - Feature que precisa de análise de impacto
 
 **NÃO usar para:**
-- Correção de bugs → Use `/mcp-debug`
-- Melhorias de código → Use `/mcp-refactor`
-- Novo projeto → Use `/mcp-start`
+- Correção de bugs → Use `/corrigir-bug`
+- Melhorias de código → Use `/refatorar-codigo`
+- Novo projeto → Use `/iniciar-projeto`
 
 ---
 
@@ -68,7 +83,7 @@ Adicionar nova funcionalidade em projeto existente usando fluxo estruturado de 6
 **Se forneceu argumentos:**
 
 ```bash
-/mcp-feature Sistema de notificações push
+/nova-feature Sistema de notificações push
 ```
 
 → Usar como descrição, pedir apenas impacto
@@ -77,13 +92,22 @@ Adicionar nova funcionalidade em projeto existente usando fluxo estruturado de 6
 
 ### Passo 2: Iniciar Fluxo de Feature
 
+> [!IMPORTANT]
+> **Protocolo stateless:** sempre envie `estado_json` carregado do disco para os tools MCP.
+
 ```typescript
+const estadoJson = lerArquivo('.maestro/estado.json');
+
 await mcp_maestro_nova_feature({
   descricao: "[descrição fornecida]",
-  impacto_estimado: "[baixo/médio/alto]"
+  impacto_estimado: "[baixo/médio/alto]",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
 ```
 
+Após a resposta, atualize `estado.historico` com `acao: "feature_iniciada"`, registrando `feature_id` e impacto.
+
 **MCP cria contexto separado para a feature e retorna:**
 
 ```json
@@ -146,25 +170,42 @@ Vamos começar. Que **entidades** ou **tabelas** serão afetadas?
 
 ### Passo 4: Avançar Entre Fases (Frontend-First)
 
-**Usar `/mcp-next` para cada fase:**
+**Usar `/avancar-fase` (via `/maestro`) para conectar com o fluxo principal**
+
+Quando estiver trabalhando dentro da feature, o acompanhamento das fases internas segue o mesmo padrão do Maestro. Utilize:
 
 ```
 Fase 1: Análise ✅
-  ↓ /mcp-next
+  ↓ /avancar-fase (passando o artefato docs/features/FEATURE-ID/01-impacto.md)
 Fase 2: Requisitos ✅
-  ↓ /mcp-next
-Fase 3: Design ✅
-  ✓ Gera: Contrato de API (OpenAPI)
-  ↓ /mcp-next
+  ↓ /avancar-fase
+...
+```
+
+Caso precise apenas retomar o trabalho da feature antes de avançar, use `/continuar-fase` com o arquivo da subfase correspondente.
+
+---
+
+### Passo 4: Avançar Entre Fases (Frontend-First)
+
+**Mapeie especialistas e templates** usando `guides/fases-mapeamento.md` para cada etapa abaixo e carregue os prompts adequados (ex.: Contrato API → especialista "Contrato de API").
+
+```
+Fase 1: Análise ✅
+  ↓ /avancar-fase (ou `/maestro` → sugere avanço)
+Fase 2: Requisitos ✅
+  ↓ /avancar-fase
+Fase 3: Design ✅ (gera contrato OpenAPI)
+  ↓ /avancar-fase
 Fase 4: Implementação
   ├─ US-001-CONT (Contrato) ✅
   ├─ US-001-FE (Frontend) 🔄 ← Paralelo
-  ├─ US-001-BE (Backend) 🔄  ← Paralelo
+  ├─ US-001-BE (Backend) 🔄 ← Paralelo
   └─ INT-001 (Integração) ⏳ ← Após FE+BE
-  ↓ /mcp-next
+  ↓ /avancar-fase
 Fase 5: Testes ✅
-  ↓ /mcp-next
-Fase 6: Deploy ✅
+  ↓ /avancar-fase
+Fase 6: Deploy ✅ (encerra feature e atualiza estado)
 ```
 
 **Protocolo Frontend-First:**
@@ -191,29 +232,41 @@ Fase 6: Deploy ✅
 **Na Fase 4 (Implementação):**
 
 ```typescript
+const estadoJson = lerArquivo('.maestro/estado.json');
+
 // Contrato
 await mcp_maestro_implementar_historia({
   historia_id: "US-001-CONT",
-  modo: "iniciar"
+  modo: "iniciar",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
 
 // Frontend (pode iniciar em paralelo após contrato)
 await mcp_maestro_implementar_historia({
   historia_id: "US-001-FE",
-  modo: "iniciar"
+  modo: "iniciar",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
 
 // Backend (pode iniciar em paralelo após contrato)
 await mcp_maestro_implementar_historia({
   historia_id: "US-001-BE",
-  modo: "iniciar"
+  modo: "iniciar",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
 
 // Integração (somente após FE e BE finalizados)
 await mcp_maestro_implementar_historia({
   historia_id: "INT-001",
-  modo: "iniciar"
+  modo: "iniciar",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
+
+salvarEstado(atualizarHistorico(estado, { acao: 'feature_historia_iniciada', historia: 'INT-001' }));
 ```
 
 ---
@@ -223,7 +276,7 @@ await mcp_maestro_implementar_historia({
 ### Exemplo 1: Feature Simples (Impacto Baixo)
 
 ```
-User: /mcp-feature Adicionar filtro de data na listagem de pedidos
+User: /nova-feature Adicionar filtro de data na listagem de pedidos
 
 AI: Qual o impacto estimado? (baixo/médio/alto)
 
@@ -244,13 +297,13 @@ AI: ✅ Fluxo de Feature Iniciado (FEAT-001)
 
 User: Sim
 
-AI: [Avança para Fase 2 com /mcp-next]
+AI: [Avança para Fase 2 executando `/maestro` → `/avancar-fase`]
 ```
 
 ### Exemplo 2: Feature Complexa (Impacto Alto)
 
 ```
-User: /mcp-feature Sistema de notificações push em tempo real
+User: /nova-feature Sistema de notificações push em tempo real
 
 AI: Qual o impacto estimado?
 
@@ -290,10 +343,10 @@ AI: ✅ Fluxo de Feature Iniciado (FEAT-002)
 ## Comandos Relacionados
 
 ```
-/mcp-feature [descrição]    → Inicia fluxo de feature
-/mcp-next                   → Avança entre fases
-/mcp-status                 → Ver status da feature
-/mcp-debug                  → Se bug aparecer durante feature
+/nova-feature [descrição] → Inicia fluxo de feature alinhado ao estado
+/continuar-fase          → Retoma etapa corrente da feature
+/avancar-fase            → Valida gate e registra próxima fase
+/corrigir-bug            → Se surgir bug durante a feature
 ```
 
 ---
@@ -369,7 +422,7 @@ FEAT-001: Sistema de Notificações (Épico)
 ├─ FEAT-001-B: Frontend (UI)
 └─ FEAT-001-C: Integração (Push)
 
-Implementar um por vez com /mcp-feature
+Implementar um por vez com `/nova-feature`
 ```
 
 ### Conflito com Feature em Andamento

package/content/workflows/{mcp-refactor.md → refatorar-codigo.md}

@@ -2,12 +2,28 @@
 description: Refatoração estruturada de código (Análise → Testes → Refactor → Validação)
 ---
 
-# /mcp-refactor - Refatoração MCP
+# /refatorar-codigo - Refatoração Maestro
 
 $ARGUMENTS
 
 ---
 
+## Integração obrigatória com o Maestro
+
+1. **Sincronize o estado** executando `/maestro` antes de começar. Garanta que não há gates bloqueados.
+2. **Carregue o estado e defina helpers**:
+   ```javascript
+   const estado = lerJson('.maestro/estado.json');
+   function salvarEstado(novoEstado) {
+     escreverJson('.maestro/estado.json', novoEstado, { spaces: 2 });
+   }
+   ```
+3. Sempre passe `estado_json` ao chamar qualquer tool MCP (`mcp_maestro_refatorar`, `mcp_maestro_avancar_refatoracao`, etc.).
+4. Atualize `estado.historico` com eventos como `refatoracao_iniciada`, `refatoracao_passo_concluido` e `refatoracao_finalizada`, armazenando `refactor_id` e arquivos afetados.
+5. Use `content/guides/fases-mapeamento.md` para escolher especialistas de apoio (Arquitetura, Performance, Testes) conforme o foco da refatoração.
+
+---
+
 ## Objetivo
 
 Refatorar código de forma segura e estruturada usando fluxo de 5 fases do MCP Maestro, com testes de caracterização e validação contínua.
@@ -22,8 +38,8 @@ Refatorar código de forma segura e estruturada usando fluxo de 5 fases do MCP M
 - Migrar para novo padrão ou arquitetura
 
 **NÃO usar para:**
-- Adicionar funcionalidade → Use `/mcp-feature`
-- Corrigir bugs → Use `/mcp-debug`
+- Adicionar funcionalidade → Use `/nova-feature`
+- Corrigir bugs → Use `/corrigir-bug`
 
 ---
 
@@ -75,10 +91,16 @@ Refatorar código de forma segura e estruturada usando fluxo de 5 fases do MCP M
 ### Passo 2: Iniciar Fluxo de Refatoração
 
 ```typescript
+const estadoJson = lerArquivo('.maestro/estado.json');
+
 await mcp_maestro_refatorar({
   area: "[área fornecida]",
-  motivo: "[motivo]"
+  motivo: "[motivo]",
+  estado_json: estadoJson,
+  diretorio: process.cwd()
 });
+
+salvarEstado(registrarHistorico(estado, { acao: 'refatoracao_iniciada', area, motivo }));
 ```
 
 **MCP cria contexto e retorna:**
@@ -397,7 +419,7 @@ Use: `/deploy production`
 ### Exemplo 1: Refatorar Serviço Complexo
 
 ```
-User: /mcp-refactor
+User: /refatorar-codigo
 
 AI: Qual área deseja refatorar?
 
@@ -435,7 +457,7 @@ AI: [Fase 2: Cria testes de caracterização]
     
     Todos passando. Pronto para refatorar!
 
-User: /mcp-next
+User: /avancar-fase (ou `/maestro` para validar e avançar)
 
 AI: [Fase 3: Refatoração]
     
@@ -463,7 +485,7 @@ AI: [Fase 3: Refatoração]
 ### Exemplo 2: Migração de Padrão
 
 ```
-User: /mcp-refactor Migrar de callback para async/await
+User: /refatorar-codigo Migrar de callback para async/await
 
 AI: Motivo?
 
@@ -496,9 +518,10 @@ AI: ✅ Refactor initiated
 ## Comandos Relacionados
 
 ```
-/mcp-refactor [área]        → Inicia refatoração
-/mcp-next                   → Avança entre fases/passos
-/mcp-status                 → Ver progresso da refatoração
+/refatorar-codigo [área]  → Inicia refatoração integrada ao estado
+/continuar-fase          → Retoma passo atual (usa análise do artefato)
+/avancar-fase            → Valida gate pós-refatoração
+/status-projeto          → Ver progresso e métricas
 ```
 
 ---