@maestro-ai/cli 1.0.0 → 1.2.0

package/README.md

@@ -1,59 +1,191 @@
-# @maestro/cli
+# @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.
 
-## Instalação
+## 🚀 Uso Rápido
 
 ```bash
-npx @maestro init
+npx @maestro-ai/cli
 ```
 
-## Comandos
+Só isso! O comando injeta automaticamente todos os arquivos do Maestro na pasta atual.
 
-### `init`
+---
 
-Inicializa Maestro no projeto atual:
+## ⚙️ Opções
+
+| Opção | Descrição |
+|-------|-----------|
+| `--force` | Sobrescreve arquivos existentes |
+| `--minimal` | Instala apenas workflows + rules |
+| `--ide <ide>` | IDE alvo: `windsurf`, `cursor`, `antigravity`, `all` (default: `windsurf`) |
+
+### Exemplos
 
 ```bash
-npx @maestro init          # Instalação completa
-npx @maestro init --minimal # Apenas workflows + GEMINI.md
-npx @maestro init --force   # Sobrescreve arquivos existentes
+# Instalação completa (Windsurf - padrão)
+npx @maestro-ai/cli
+
+# Apenas para Cursor
+npx @maestro-ai/cli --ide cursor
+
+# Apenas para Antigravity/Gemini
+npx @maestro-ai/cli --ide antigravity
+
+# Sobrescrever arquivos existentes
+npx @maestro-ai/cli --force
+
+# Instalação mínima
+npx @maestro-ai/cli --minimal
+```
+
+---
+
+## 📁 Estrutura Criada
+
 ```
+projeto/
+├── .maestro/
+│   ├── config.json          # Configuração do projeto
+│   ├── history/             # Histórico de conversas
+│   └── content/             # Especialistas, templates, guides, prompts
+├── .windsurf/
+│   ├── skills/              # Skills especializadas
+│   └── workflows/           # Workflows inteligentes
+└── .windsurfrules           # Regras da IA para Windsurf
+```
+
+### Arquivos por IDE
+
+| IDE | Estrutura Gerada |
+|-----|------------------|
+| Windsurf | `.windsurf/workflows/` + `.windsurf/skills/` + `.windsurfrules` |
+| Cursor | `.cursor/commands/` + `.cursor/skills/` + `.cursorrules` |
+| Antigravity | `.agent/workflows/` + `.agent/skills/` + `.gemini/GEMINI.md` |
+
+---
+
+## 🎯 Fluxo de Trabalho
+
+O Maestro File System opera 100% localmente com workflows chat-first:
+
+```mermaid
+graph LR
+    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]
+```
+
+### 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 |
 
-**O que é criado:**
-- `.maestro/config.json` - Configuração do projeto
-- `content/` - Especialistas, templates, guides
-- `.agent/workflows/` - Workflows automatizados
-- `GEMINI.md` - Rules para a IA
+### 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 CLI
+
+### `init` (padrão)
+
+```bash
+npx @maestro-ai/cli init
+npx @maestro-ai/cli init --ide cursor
+npx @maestro-ai/cli init --force
+```
 
 ### `update`
 
 Atualiza content para a última versão:
 
 ```bash
-npx @maestro update
-npx @maestro update --force  # Sobrescreve arquivos modificados
+npx @maestro-ai/cli update
+npx @maestro-ai/cli update --force  # Sobrescreve arquivos modificados
 ```
 
-## Após Inicialização
+---
 
-Configure o MCP na sua IDE:
+## 🎨 Exemplo de Uso
 
-```json
-{
-  "mcpServers": {
-    "maestro": {
-      "serverUrl": "https://maestro.deluna.dev.br/mcp"
-    }
-  }
-}
+```bash
+# 1. Inicializar projeto
+npx @maestro-ai/cli
+
+# 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
 ```
 
-## Desenvolvimento
+---
+
+## 🛠️ Desenvolvimento
 
 ```bash
 cd packages/cli
 npm install
 npm run build
-npm run dev -- init  # Testar localmente
+npm run dev -- init --ide windsurf  # Testar localmente
+```
+
+---
+
+## 📦 Publicação
+
+```bash
+npm version patch  # ou minor/major
+npm publish
 ```
+
+---
+
+## 📄 Licença
+
+MIT

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).