@maestro-ai/cli 1.0.0 → 1.2.0

package/content/rules/adapters/copilot.md

@@ -0,0 +1,10 @@
+---
+description: Adapter for GitHub Copilot
+target_path: .github/copilot-instructions.md
+---
+
+# GitHub Copilot Adapter
+
+Este adaptador formata as regras para o GitHub Copilot.
+
+O conteúdo de `RULES.md` será inserido automaticamente pelo CLI.

package/content/rules/adapters/cursor.md

@@ -0,0 +1,10 @@
+---
+description: Adapter for Cursor IDE
+target_path: .cursorrules
+---
+
+# Cursor Adapter
+
+Este adaptador formata as regras para o Cursor IDE.
+
+O conteúdo de `RULES.md` será inserido automaticamente pelo CLI.

package/content/rules/adapters/gemini.md

@@ -0,0 +1,13 @@
+---
+trigger: always_on
+system: maestro
+version: 1.0.0
+description: Adapter for Gemini/Antigravity IDE
+target_path: .gemini/GEMINI.md
+---
+
+# Gemini Adapter
+
+Este adaptador adiciona o frontmatter específico para Gemini/Antigravity.
+
+O conteúdo de `RULES.md` será inserido automaticamente pelo CLI.

package/content/rules/adapters/windsurf.md

@@ -0,0 +1,10 @@
+---
+description: Adapter for Windsurf IDE
+target_path: .windsurfrules
+---
+
+# Windsurf Adapter
+
+Este adaptador formata as regras para o Windsurf IDE.
+
+O conteúdo de `RULES.md` será inserido automaticamente pelo CLI.

package/content/rules/quality-gates.md

@@ -0,0 +1,43 @@
+# 🔐 Quality Gates por Transição
+
+| De → Para | Checklist Obrigatória | Validadores sugeridos |
+|-----------|----------------------|------------------------|
+| Produto → Requisitos | MVP 100% coberto nos requisitos; personas refletidas | `validarCoberturaMVP(PRD, requisitos)` |
+| Requisitos → UX Design | Fluxos/jornadas definidos; critérios de aceite aprovados | `analisarFluxosUsuarios(requisitos)` |
+| UX Design → Prototipagem (Stitch) | Wireframes completos; estilo aprovado | `validarWireframes(designDoc)` |
+| Prototipagem → Arquitetura | Feedback aplicado; requisitos atualizados | `verificarConsistencia(designDoc, requisitos)` |
+| Arquitetura → Modelo de Domínio | Stack confirmada; contexto alinhado | `compararModelagem(arquitetura, modeloDominio)` |
+| Modelo de Domínio → Banco de Dados | Entidades → tabelas; regras documentadas | `validarModeloDominio(modeloDominio, designBanco)` |
+| Banco → Segurança | Dados sensíveis catalogados; políticas definidas | `analisarSensibilidade(designBanco)` |
+| Segurança → Testes | Controles críticos definidos; riscos registrados | `validarChecklistSeguranca(checklist)` |
+| Testes → Backlog | Estratégia de testes aprovada; cobertura planejada | `verificarPlanoTestes(plano)` |
+| Backlog → Contrato API | Stories/radar de integrações aprovados | `compararBacklogContrato(backlog, openapi)` |
+| Contrato API → Frontend | OpenAPI completo; mocks disponíveis | `validarContrato(openapi)` |
+| Frontend → Backend | Componentes integrados a mocks; testes passando | `executarSuite('frontend-tests')` |
+| Backend → Integração/Deploy | Testes unitários/integração/contrato passando | `executarSuite('backend-tests')` |
+| Integração → Observabilidade (fluxo complexo) | Pipelines verdes; monitoração básica configurada | `validarPipeline(ciCdConfig)` |
+| Observabilidade → Performance | Dashboards + alertas definidos | `validarObservabilidade(config)` |
+| Performance → Deploy Final | Testes de carga concluídos; tuning aplicado | `executarLoadTest(plan)` |
+
+## Exemplo de validação cruzada (Produto → Requisitos)
+
+```javascript
+function validarCoberturaMVP(prdPath, requisitosPath) {
+  const prd = lerArquivo(prdPath);
+  const requisitos = lerArquivo(requisitosPath);
+  const mvpItems = extrairItens('MVP', prd);
+  const faltantes = mvpItems.filter(item => !requisitos.includes(item));
+
+  return {
+    percentual: ((mvpItems.length - faltantes.length) / mvpItems.length) * 100,
+    faltantes
+  };
+}
+```
+
+## Uso no /avancar-fase
+
+1. Determine a transição atual (fase `N` → `N+1`).
+2. Carregue o checklist correspondente na tabela acima.
+3. Execute as funções auxiliares indicadas (ou use lógica equivalente).
+4. Só permita avanço quando **todos** os itens estiverem `true` e o score da fase atingir o mínimo definido em `validation-rules.md`.

package/content/rules/validation-rules.md

@@ -0,0 +1,97 @@
+# 🛡️ Regras de Validação por Fase
+
+## Fase 1 - Produto
+- Problema central definido
+- Público-alvo/personas
+- MVP listado e priorizado
+- Métricas de sucesso (North Star + KPIs)
+- Score mínimo: **75/100**
+
+## Fase 2 - Requisitos
+- Cobertura 100% do MVP
+- Requisitos funcionais em formato testável
+- Requisitos não funcionais (performance, segurança)
+- Critérios de aceite (Given-When-Then)
+- Score mínimo: **70/100**
+
+## Fase 3 - UX Design
+- Wireframes para todas as telas principais
+- Jornadas/fluxos de usuário descritos
+- Navegação coerente
+- Consistência visual e de componentes
+- Score mínimo: **70/100**
+
+## Fase 4 - Prototipagem / Stitch (quando aplicável)
+- Protótipo navegável validado com stakeholders
+- Feedback registrado e aplicado
+- Export pronto para handoff ou Stitch output salvo
+- Score mínimo: **75/100**
+
+## Fase 5 - Arquitetura
+- Stack definida
+- Diagrama C4 nível 2 ou 3
+- ADRs para decisões críticas
+- Requisitos não funcionais endereçados
+- Score mínimo: **80/100**
+
+## Fase 6 - Modelo de Domínio
+- Entidades e relacionamentos definidos
+- Regras de negócio documentadas
+- Eventos e agregados identificados (quando necessário)
+- Score mínimo: **75/100**
+
+## Fase 7 - Banco de Dados
+- Modelo relacional ou NoSQL definido
+- Índices/partições planejados
+- Estratégia de migração descrita
+- Score mínimo: **75/100**
+
+## Fase 8 - Segurança
+- OWASP Top 10 avaliado
+- Autenticação/autorização descritas
+- Dados sensíveis mapeados e protegidos
+- Score mínimo: **80/100**
+
+## Fase 9 - Testes
+- Estratégia (pirâmide) definida
+- Casos de teste críticos descritos
+- Ferramentas e ambientes definidos
+- Score mínimo: **75/100**
+
+## Fase 10 - Backlog
+- Épicos e features priorizados
+- Histórias com critérios de aceite claros
+- Dependências mapeadas
+- Score mínimo: **75/100**
+
+## Fase 11 - Contrato de API
+- Esquema OpenAPI completo
+- Versionamento/documentação definidas
+- Mocks ou client SDK disponíveis
+- Score mínimo: **80/100**
+
+## Fase 12 - Frontend
+- Componentes implementados conforme design
+- Testes de componente ou integração passando
+- Responsividade e acessibilidade verificadas
+- Score mínimo: **80/100**
+
+## Fase 13 - Backend
+- Endpoints implementados conforme contrato
+- Testes unitários e de integração passando
+- Migrações e jobs documentados
+- Score mínimo: **80/100**
+
+## Fase 14 - Performance / Observabilidade (fluxo complexo)
+- Métricas e alertas configurados
+- Estratégia de cache/performance definida
+- Testes de carga planejados
+- Score mínimo: **80/100**
+
+## Fase 15 - Integração / Deploy
+- Pipeline CI/CD verde
+- Testes E2E executados
+- Plano de rollback/documentação de release
+- Score mínimo: **85/100**
+
+> Use essas regras para preencher `fase.validacoes` e justificar o `score` atribuído no estado.

package/content/templates/estado-template.json

@@ -0,0 +1,73 @@
+{
+  "projeto": {
+    "nome": "[Nome do Projeto]",
+    "descricao": "[Resumo do projeto]",
+    "tipo": "[poc|script|internal|product]",
+    "complexidade": "[simples|medio|complexo]",
+    "tier": "[essencial|base|avancado]",
+    "usarStitch": false,
+    "criadoEm": "[ISO datetime]",
+    "atualizadoEm": "[ISO datetime]"
+  },
+  "faseAtual": {
+    "numero": 1,
+    "nome": "Produto",
+    "status": "in_progress",
+    "especialista": "Gestão de Produto",
+    "score": null,
+    "scoreMinimo": 75,
+    "iniciadoEm": "[ISO datetime]",
+    "ultimoUpdate": "[ISO datetime]"
+  },
+  "fases": {
+    "1": {
+      "numero": 1,
+      "nome": "Produto",
+      "especialista": "Gestão de Produto",
+      "status": "pending",
+      "score": null,
+      "scoreMinimo": 75,
+      "artefatos": ["docs/01-produto/PRD.md"],
+      "validacoes": {
+        "problema_definido": false,
+        "personas": false,
+        "mvp_listado": false,
+        "metricas": false
+      }
+    },
+    "2": {
+      "numero": 2,
+      "nome": "Requisitos",
+      "especialista": "Engenharia de Requisitos",
+      "status": "pending",
+      "score": null,
+      "scoreMinimo": 70,
+      "artefatos": ["docs/02-requisitos/requisitos.md"],
+      "validacoes": {
+        "requisitos_funcionais": false,
+        "requisitos_nao_funcionais": false,
+        "criterios_aceite": false,
+        "cobertura_mvp": false
+      }
+    }
+  },
+  "qualityGates": {
+    "1_para_2": {
+      "validado": false,
+      "score": null,
+      "checks": ["mvp_100_coberto"]
+    }
+  },
+  "historico": [
+    {
+      "acao": "projeto_iniciado",
+      "detalhes": "Projeto criado a partir do template",
+      "timestamp": "[ISO datetime]"
+    }
+  ],
+  "metrica": {
+    "fasesConcluidas": 0,
+    "ultimoComando": null,
+    "tempoPorFase": {}
+  }
+}

package/content/workflows/avancar-fase.md

@@ -0,0 +1,84 @@
+---
+description: Valida fase atual com quality gates e prepara a próxima fase
+---
+
+# 🔄 Workflow de Avanço - /avancar-fase
+
+## 1. Ler estado e fase atual
+
+```javascript
+const estado = lerJson('.maestro/estado.json');
+const faseAtual = estado.fases[estado.faseAtual];
+if (!faseAtual) throw new Error('Fase atual não existe');
+
+function salvarEstado(state) {
+  escreverJson('.maestro/estado.json', state, { spaces: 2 });
+}
+```
+
+## 2. Checklist obrigatório
+
+- `faseAtual.status` deve ser `concluida`.
+- `faseAtual.score >= faseAtual.scoreMinimo`.
+- Todos os itens de `faseAtual.validacoes` precisam estar `true`.
+- Verificar bloqueios pendentes.
+
+Se algum critério falhar, listar o motivo e encerrar sem avançar.
+
+## 3. Validação cruzada
+
+Use regras específicas da transição (ver `content/rules/quality-gates.md`). Exemplo:
+
+```javascript
+if (estado.faseAtual === 1) {
+  const prd = lerArquivo('docs/01-produto/PRD.md');
+  const requisitos = lerArquivo('docs/02-requisitos/requisitos.md');
+  const cobertura = validarCoberturaMVP(prd, requisitos);
+  if (cobertura.percentual < 100) throw new Error('MVP não está 100% coberto nos requisitos');
+}
+```
+
+## 4. Determinar próxima fase
+
+```javascript
+const PROGRESSAO = {
+  1: { numero: 2, nome: 'Requisitos', especialista: 'Engenharia de Requisitos', entregavel: 'docs/02-requisitos/requisitos.md' },
+  2: { numero: 3, nome: 'UX Design', especialista: 'UX Designer', entregavel: 'docs/03-ux/design-doc.md' },
+  // ... completar até o tier máximo
+};
+
+const proxima = PROGRESSAO[estado.faseAtual];
+if (!proxima) return 'Projeto já está na última fase';
+```
+
+Depois de obter `proxima`, consulte `content/guides/fases-mapeamento.md` para descobrir:
+
+- **Especialista** em `content/specialists/` que atuará na próxima fase
+- **Prompt principal** em `content/prompts/`
+- **Templates** que devem ser carregados/atualizados
+- **Skills** sugeridas em `content/skills/`
+
+Inclua essas referências na resposta final para orientar o usuário sobre o contexto que será carregado quando `/continuar-fase` for executado.
+
+## 5. Atualizar estado
+
+- Marcar `faseAtual.dataConclusao`.
+- Incrementar `estado.faseAtual` para `proxima.numero`.
+- Preparar entrada vazia para a próxima fase (`status: 'in_progress'`).
+- Registrar evento no histórico (`fase_avancada`).
+- Atualizar `estado.metrica.fasesConcluidas` e `estado.metrica.ultimoComando = '/avancar-fase'`.
+- Chamar `salvarEstado(estado)` após todas as alterações.
+
+## 6. Mensagem de saída
+
+```
+✅ **Fase {faseAtual.numero} - {faseAtual.nome} concluída!**
+📊 Score: {faseAtual.score}/{faseAtual.scoreMinimo}
+🔍 Validações: {lista de validações confirmadas}
+
+🎯 **Próxima fase:** {proxima.nome}
+👤 Especialista: {proxima.especialista}
+📁 Arquivo inicial: {proxima.entregavel}
+
+Execute `/continuar-fase` para começar imediatamente.
+```

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.
+```