@maestro-ai/cli 1.1.0 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @maestro-ai/cli
 
-CLI para inicializar projetos com Maestro - Desenvolvimento assistido por IA.
+CLI para inicializar projetos **Maestro File System** - Orquestrador chat-first com workflows inteligentes.
 
 ## 🚀 Uso Rápido
 
@@ -8,7 +8,7 @@ CLI para inicializar projetos com Maestro - Desenvolvimento assistido por IA.
 npx @maestro-ai/cli
 ```
 
-Só isso! O comando injeta automaticamente todos os arquivos na pasta atual.
+Só isso! O comando injeta automaticamente todos os arquivos do Maestro na pasta atual.
 
 ---
 
@@ -18,25 +18,19 @@ Só isso! O comando injeta automaticamente todos os arquivos na pasta atual.
 |-------|-----------|
 | `--force` | Sobrescreve arquivos existentes |
 | `--minimal` | Instala apenas workflows + rules |
-| `--ide <ide>` | IDE alvo: `gemini`, `cursor`, `copilot`, `windsurf`, `all` (default: `all`) |
+| `--ide <ide>` | IDE alvo: `windsurf`, `cursor`, `antigravity`, `all` (default: `windsurf`) |
 
 ### Exemplos
 
 ```bash
-# Instalação completa (todas as IDEs)
+# Instalação completa (Windsurf - padrão)
 npx @maestro-ai/cli
 
-# Apenas para Gemini/Antigravity
-npx @maestro-ai/cli --ide gemini
-
 # Apenas para Cursor
 npx @maestro-ai/cli --ide cursor
 
-# Apenas para GitHub Copilot
-npx @maestro-ai/cli --ide copilot
-
-# Apenas para Windsurf
-npx @maestro-ai/cli --ide windsurf
+# Apenas para Antigravity/Gemini
+npx @maestro-ai/cli --ide antigravity
 
 # Sobrescrever arquivos existentes
 npx @maestro-ai/cli --force
@@ -55,45 +49,70 @@ projeto/
 │   ├── config.json          # Configuração do projeto
 │   ├── history/             # Histórico de conversas
 │   └── content/             # Especialistas, templates, guides, prompts
-├── .agent/
-│   ├── skills/              # Skills para a IA
-│   └── workflows/           # Workflows automatizados
-└── [Arquivos de regras por IDE]
+├── .windsurf/
+│   ├── skills/              # Skills especializadas
+│   └── workflows/           # Workflows inteligentes
+└── .windsurfrules           # Regras da IA para Windsurf
 ```
 
-### Arquivos de Regras por IDE
+### Arquivos por IDE
 
-| IDE | Arquivo Gerado |
-|-----|----------------|
-| Gemini/Antigravity | `.gemini/GEMINI.md` |
-| Cursor | `.cursorrules` |
-| GitHub Copilot | `.github/copilot-instructions.md` |
-| Windsurf | `.windsurfrules` |
+| IDE | Estrutura Gerada |
+|-----|------------------|
+| Windsurf | `.windsurf/workflows/` + `.windsurf/skills/` + `.windsurfrules` |
+| Cursor | `.cursor/commands/` + `.cursor/skills/` + `.cursorrules` |
+| Antigravity | `.agent/workflows/` + `.agent/skills/` + `.gemini/GEMINI.md` |
 
 ---
 
-## 🔄 Fluxo Esperado
+## 🎯 Fluxo de Trabalho
+
+O Maestro File System opera 100% localmente com workflows chat-first:
 
 ```mermaid
 graph LR
-    A[npx @maestro-ai/cli] --> B{Opção --ide?}
-    B -->|all| C[Gera todos]
-    B -->|específico| D[Gera um arquivo]
-    C --> E[.gemini/GEMINI.md]
-    C --> F[.cursorrules]
-    C --> G[.github/copilot-instructions.md]
-    C --> H[.windsurfrules]
-    D --> I[Arquivo da IDE escolhida]
+    A[/maestro] --> B{Estado do projeto}
+    B -->|Novo| C[/iniciar-projeto]
+    B -->|Em andamento| D[/continuar-fase]
+    B -->|Pronto| E[/avancar-fase]
+    C --> F[Fase 1: Produto]
+    D --> G[Retoma fase atual]
+    E --> H[Próxima fase]
 ```
 
-1. **Execute o CLI** no diretório do seu projeto
-2. **Escolha a IDE** (ou deixe `all` para suportar todas)
-3. **Configure o MCP** na sua IDE
-4. **Inicie um projeto Maestro** com `iniciar_projeto`
+### Comandos Principais
+
+| Comando | Descrição |
+|---------|-----------|
+| `/maestro` | Workflow universal inteligente que detecta estado |
+| `/iniciar-projeto` | Inicia novo projeto com classificação automática |
+| `/continuar-fase` | Retoma a fase atual do ponto exato |
+| `/avancar-fase` | Valida quality gates e avança para próxima fase |
+| `/status-projeto` | Mostra progresso completo e métricas |
+
+### Workflows de Desenvolvimento
+
+| Comando | Descrição |
+|---------|-----------|
+| `/nova-feature` | Adiciona funcionalidades (fluxo 6 fases) |
+| `/corrigir-bug` | Debugging estruturado (fluxo 4 fases) |
+| `/refatorar-codigo` | Refatoração segura com testes |
+| `/brainstorm` | Exploração estruturada de ideias |
+| `/deploy` | Deploy em produção com checklist |
+| `/testar` | Geração e execução de testes |
+
+---
+
+## 🔄 Como Funciona
+
+1. **Estado Centralizado**: `.maestro/estado.json` mantém toda a evolução do projeto
+2. **Workflows Inteligentes**: Cada workflow carrega especialistas, prompts e templates adequados
+3. **Quality Gates**: Validações automáticas entre fases com regras específicas
+4. **Multi-IDE**: Suporte nativo para Windsurf, Cursor e Antigravity
 
 ---
 
-## 📋 Comandos
+## 📋 Comandos CLI
 
 ### `init` (padrão)
 
@@ -114,24 +133,35 @@ npx @maestro-ai/cli update --force  # Sobrescreve arquivos modificados
 
 ---
 
-## ⚡ Após Inicialização
-
-Configure o MCP na sua IDE:
-
-```json
-{
-  "mcpServers": {
-    "maestro": {
-      "serverUrl": "https://maestro.deluna.dev.br/mcp"
-    }
-  }
-}
-```
+## 🎨 Exemplo de Uso
 
-Depois inicie um projeto:
+```bash
+# 1. Inicializar projeto
+npx @maestro-ai/cli
 
-```
-@mcp:maestro iniciar_projeto
+# 2. No Windsurf/Cursor, iniciar projeto
+/maestro
+# → Detecta projeto não inicializado
+# → Sugere /iniciar-projeto
+
+# 3. Iniciar projeto
+/iniciar-projeto
+# → Coleta informações
+# → Classifica complexidade
+# → Cria estado inicial
+# → Prepara Fase 1
+
+# 4. Desenvolver
+/continuar-fase
+# → Carrega especialista de Gestão de Produto
+# → Abre templates PRD.md
+# → Orienta preenchimento
+
+# 5. Avançar quando pronto
+/avancar-fase
+# → Valida quality gate
+# → Atualiza estado
+# → Prepara Fase 2
 ```
 
 ---
@@ -142,7 +172,7 @@ Depois inicie um projeto:
 cd packages/cli
 npm install
 npm run build
-npm run dev -- init --ide gemini  # Testar localmente
+npm run dev -- init --ide windsurf  # Testar localmente
 ```
 
 ---

package/content/guides/fases-mapeamento.md

@@ -0,0 +1,35 @@
+---
+description: Mapeamento fase ↔ especialista, prompts, templates e skills
+---
+
+# 📚 Mapa de Fases MCP → Recursos do Conteúdo
+
+| Fase | Especialista | Prompt principal | Template(s) | Skills/Notas |
+|------|--------------|------------------|-------------|--------------|
+| 1. Produto | specialists/Especialista em Gestão de Produto.md | prompts/produto.md | templates/PRD.md | Skills: Produto, Discovery; carregar PRD existente antes de iniciar. |
+| 2. Requisitos | specialists/Especialista em Engenharia de Requisitos com IA.md | prompts/requisitos.md | templates/requisitos.md, templates/matriz-rastreabilidade.md | Skills: Requirements, QA; referenciar MVP da fase 1. |
+| 3. UX Design | specialists/Especialista em UX Design.md | prompts/ux.md | templates/design-doc.md, templates/mapa-navegacao.md | Skills: UX, Acessibilidade. |
+| 4. Modelo de Domínio | specialists/Especialista em Modelagem e Arquitetura de Domínio com IA.md | prompts/modelo-dominio.md | templates/modelo-dominio.md | Skills: Architecture, Domain-driven. |
+| 5. Banco de Dados | specialists/Especialista em Banco de Dados.md | prompts/banco.md | templates/design-banco.md | Skills: Database, Performance. |
+| 6. Arquitetura | specialists/Especialista em Arquitetura de Software.md | prompts/arquitetura.md | templates/arquitetura.md, templates/adr.md | Skills: Architecture, Security. |
+| 7. Segurança | specialists/Especialista em Segurança da Informação.md | prompts/seguranca.md | templates/checklist-seguranca.md | Skills: Security. |
+| 8. Testes | specialists/Especialista em Análise de Testes.md | prompts/testes.md | templates/plano-testes.md, templates/criterios-aceite.md | Skills: Testing. |
+| 9. Backlog | specialists/Especialista em Plano de Execução com IA.md | prompts/backlog.md | templates/backlog.md, templates/historia-usuario.md | Skills: Agile/Execution. |
+| 10. Contrato API | specialists/Especialista em Contrato de API.md | prompts/api.md | templates/contrato-api.md | Skills: API, Integration. |
+| 11. Frontend | specialists/Especialista em Desenvolvimento Frontend.md | prompts/frontend.md | templates/historia-frontend.md | Skills: Frontend, UI. |
+| 12. Backend | specialists/Especialista em Desenvolvimento e Vibe Coding Estruturado.md | prompts/backend.md | templates/historia-backend.md | Skills: Backend, Clean Code. |
+| 13. Integração/Deploy | specialists/Especialista em DevOps e Infraestrutura.md | prompts/devops.md | templates/arquitetura.md, templates/slo-sli.md | Skills: DevOps, Observabilidade. |
+
+> Para fluxos simples (7 fases), considere apenas as linhas 1–7. Para fluxos complexos (17 fases), acrescente especialistas adicionais conforme `src/src/flows/types.ts` (Arquitetura Avançada, Performance, Observabilidade, etc.).
+
+## Como usar nos workflows
+
+1. **/continuar-fase**: após identificar a fase, abra o especialista e prompt correspondentes (ver tabela). Mencione explicitamente na resposta quais templates serão atualizados.
+2. **/avancar-fase**: use `entregavel_esperado` da tabela para verificar arquivos e validações antes de avançar.
+3. **/status-projeto**: liste os especialistas por fase concluída/parcial para ajudar o usuário a saber quem está ativo.
+
+## Manutenção
+
+- Sempre que um novo especialista ou template for adicionado, atualize esta tabela.
+- Se um prompt for renomeado, ajuste o nome aqui e nos workflows.
+- Skills podem ser expandidas mencionando diretórios específicos em `content/skills/`.

package/content/guides/multi-ide.md

@@ -0,0 +1,32 @@
+---
+description: Como usar o Maestro File System em Windsurf, Cursor e Antigravity
+---
+
+# 🌐 Guia Multi-IDE
+
+## Windsurf
+- Workflows: `.windsurf/workflows/*.md`
+- Skills: `.windsurf/skills/`
+- Regras: `.windsurfrules`
+- Comandos: usar `/maestro`, `/iniciar-projeto`, `/continuar-fase`, `/avancar-fase`, `/status-projeto` direto no chat.
+- Dica: Windsurf expande markdown automaticamente; cite caminhos completos (ex.: `content/guides/fases-mapeamento.md`).
+
+## Cursor
+- Comandos: `.cursor/commands/*.md` (mesmo nome dos workflows)
+- Skills: `.cursor/skills/`
+- Regras: `.cursorrules`
+- Para iniciar, digite `/maestro` no chat do Cursor; os demais comandos funcionam igual.
+- Dica: quando o comando pedir arquivos, use `cursor://` + caminho relativo para abrir.
+
+## Antigravity / Gemini
+- Workflows: `.agent/workflows/`
+- Skills: `.agent/skills/`
+- Regras: `.gemini/GEMINI.md` (contém header com trigger `always_on`)
+- Comandos: igual às outras IDEs; recomenda-se iniciar com `/maestro`.
+- Dica: especifique claramente quando precisar ler/escrever arquivos para evitar passos extras do agente.
+
+## Boas práticas gerais
+1. Sempre mantenha `.maestro/estado.json` versionado (ou com backup) para permitir retomada entre IDEs.
+2. Após atualizar conteúdo do CLI, rode novamente `npx @maestro-ai/cli --force --ide <alvo>` conforme necessidade, lembrando que cada IDE possui diretórios próprios.
+3. Ao criar novos workflows/rules, copie-os para cada IDE ou reexecute o CLI.
+4. Consulte este guia sempre que precisar lembrar onde vivem os arquivos instalados.

package/content/guides/playbook-orquestrador.md

@@ -0,0 +1,45 @@
+---
+description: Playbook de governança do orquestrador Maestro
+---
+
+# 📘 Playbook do Orquestrador Inteligente
+
+## 1. Fluxo padrão
+1. `/maestro` → Detecta estado, valida fluxos MCP e aponta próxima ação.
+2. `/iniciar-projeto` → Classifica, gera estado e prepara fase 1.
+3. `/continuar-fase` → Carrega especialista/prompt/templates e retoma do ponto exato.
+4. `/avancar-fase` → Executa quality gates e avança com registro em histórico.
+5. `/status-projeto` → Consolida progresso, scores, bloqueios e recomendações.
+
+## 2. Governança do estado (`.maestro/estado.json`)
+- Sempre ler antes de executar qualquer workflow.
+- Campos principais: `projeto`, `faseAtual`, `fases`, `qualityGates`, `historico`, `metrica`.
+- Atualizações recomendadas:
+  - `/continuar-fase`: atualizar `fases[N].artefatos`, notas, progresso, `metrica.ultimoComando`.
+  - `/avancar-fase`: marcar `fases[N].status = 'concluida'`, preencher `dataConclusao`, incrementar `faseAtual`, registrar `historico`.
+  - `/status-projeto`: apenas leitura; reporte divergências.
+
+## 3. Métricas e registro
+- `metrica.fasesConcluidas`: incrementado ao avançar.
+- `metrica.tempoPorFase`: registrar timestamps quando iniciar/concluir fase.
+- `metrica.scores`: manter média para relatórios (usado em `/status-projeto`).
+- `metrica.ultimoComando`: útil para retomar contexto entre sessões.
+
+## 4. Troubleshooting
+- **Estado ausente**: `/maestro` deve sugerir `/iniciar-projeto`.
+- **Divergência com fluxo MCP**: `/maestro` lista fases divergentes; ajustar manualmente ou reinicializar.
+- **Quality gate falhou**: `/avancar-fase` explica motivo e indica arquivos a revisar; refaça `/continuar-fase` com foco no ponto pendente.
+- **Mudança de IDE**: consultar `guides/multi-ide.md` para garantir que workflows/skills estejam no local correto.
+
+## 5. Checklist antes de concluir uma fase
+- Entregável existe e segue template.
+- Regras específicas cumpridas (`rules/validation-rules.md`).
+- Quality gate da transição validado (`rules/quality-gates.md`).
+- Estado atualizado (status, score, notas, timestamps).
+- Evento registrado em `historico` com resumo e próximos passos.
+
+## 6. Próximos passos sugeridos
+- Automatizar atualização do estado dentro dos workflows (scripts mentais).
+- Criar smoke tests para cada comando nas IDEs suportadas.
+- Estender métricas para dashboards ou relatórios automáticos.
+- Documentar casos de uso avançados (ex.: projetos multi-tier, Stitch opcional).

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