@maestro-ai/cli 1.1.0 → 1.3.0

package/content/guides/mapa-sistema.md

@@ -0,0 +1,86 @@
+# 🗺️ Mapa do Sistema Maestro FS
+
+> Este documento detalha a arquitetura final e como os workflows interagem com as regras e guias.
+
+---
+
+## 🔄 Visão Geral do Fluxo
+
+```mermaid
+graph TD
+    Start((Início)) --> W01[01-iniciar-projeto]
+    W01 --> State[estado.json]
+    
+    State --> W00{00-maestro}
+    W00 -->|Status: Em Andamento| W02[02-avancar-fase]
+    W00 -->|Status: Fase Incompleta| W03[03-continuar-fase]
+    
+    W02 --> Rules{GATES}
+    Rules -->|Aprovado| Next[Próxima Fase]
+    Rules -->|Reprovado| Fix[Correção]
+    
+    Next --> AutoSystem[Auto: system.md]
+    AutoSystem --> AutoEvents[Auto: Log Evento]
+    
+    subgraph "Fluxos Paralelos"
+    W04[04-implementar-historia]
+    W05[05-nova-feature]
+    W06[06-corrigir-bug]
+    W07[07-refatorar-codigo]
+    end
+    
+    W04 --> AutoMap[Auto: mapa.md]
+    W07 --> AutoMap
+    
+    Next --> End((Fim - 08-deploy))
+```
+
+---
+
+## 📂 Arquitetura do Knowledge Base
+
+### 1. Workflows (Ação) - `content/workflows/`
+
+Comandos sequenciais que a IA executa para transformar o projeto.
+
+| Comando | Objetivo | Automações Inclusas |
+| :--- | :--- | :--- |
+| **`/00-maestro`** | Router Inteligente (Status) | Leitura de Estado |
+| **`/01-iniciar-projeto`** | Setup Inicial | `guide-brainstorm.md` (Opcional) |
+| **`/02-avancar-fase`** | Transição de Fase | `automated-system`, `automated-events`, `automated-stitch` |
+| **`/03-continuar-fase`** | Retomada de Trabalho | - |
+| **`/04-implementar-historia`** | Código Frontend-First | `automated-map`, `automated-events`, `guide-testes` |
+| **`/05-nova-feature`** | Grandes Funcionalidades | `guide-orquestracao` (Opcional) |
+| **`/06-corrigir-bug`** | Fix Crítico | `guide-orquestracao` (Opcional) |
+| **`/07-refatorar-codigo`** | Melhoria Técnica | `automated-map` |
+| **`/08-deploy-projeto`** | Produção | Checklist de Release |
+
+### 2. Automações Internas (Invisíveis) - `content/guides/internal/`
+
+Scripts "mentais" que os workflows chamam obrigatoriamente.
+
+*   `automated-map.md`: Escaneia `src/` e atualiza `.maestro/mapa.md`.
+*   `automated-system.md`: Atualiza `.maestro/SYSTEM.md` (Memória de Curto Prazo).
+*   `automated-events.md`: Registra logs em `.maestro/history/events.jsonl`.
+*   `automated-stitch.md`: Injeta fase de prototipagem se necessário.
+
+### 3. Guias de Referência (Consulta) - `content/guides/`
+
+ manuais que a IA consulta sob demanda ou quando instruída.
+
+*   `guide-brainstorm.md`: Ideação de escopo.
+*   `guide-orquestracao.md`: Como operar em modo Squad (Planner/Dev/Reviewer).
+*   `guide-testes.md`: Estratégia de testes por camada.
+*   `guide-validacao.md`: Como validar um gate manualmente.
+*   `guide-troubleshooting.md`: Como resolver bloqueios e erros de estado.
+
+---
+
+## 🧠 Ciclo de Vida do Estado
+
+1.  **Início (`01`)**: Cria `estado.json` (Fonte da Verdade).
+2.  **Durante (`04-07`)**: Atualiza `mapa.md` e `events.jsonl`.
+3.  **Transição (`02`)**: Atualiza `SYSTEM.md` e `resumo.json`.
+4.  **Fim (`08`)**: Consolida a versão.
+
+O sistema é **autônomo** (sabe o que rodar) e **resiliente** (se perder contexto, lê `SYSTEM.md` ou roda `/00-maestro`).

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/guides/workflows-avancados.md

@@ -0,0 +1,62 @@
+# 🚀 Workflows Avançados e Seus Benefícios
+
+> Entenda por que promovemos estes workflows para o "Primeiro Escalão" do Maestro FS.
+
+---
+
+## 1. `/08-deploy-projeto` (Antigo `deploy.md`)
+
+**O Problema Anterior:**
+O sistema original parava na fase de "Coding". O desenvolvedor ficava com o código pronto na máquina, mas sem um guia claro de como levar para produção com segurança.
+
+**O Benefício:**
+Este workflow introduz a disciplina de **DevOps**:
+*   ✅ **Checklist Pré-Voo (Pre-flight)**: Garante que segredos não estão hardcoded, testes passaram e versão foi bumpada.
+*   🔄 **Rollback Strategy**: Obriga a pensar em "como voltar atrás" se der errado.
+*   📦 **Multi-Cloud**: Dá dicas para Vercel, Railway, Docker, etc.
+
+---
+
+## 2. `/80-orchestrate-agents` (Antigo `orchestrate.md`)
+
+**O Problema Anterior:**
+O Maestro atuava muito como um "Lobo Solitário". Para tarefas complexas (ex: "Refazer todo o módulo de Auth"), uma única passada linear não é suficiente.
+
+**O Benefício:**
+Este workflow ativa o **Modo Squad**:
+*   🤖 **Multi-Agente**: Simula uma equipe onde um "Planner" quebra a tarefa, um "Dev" executa e um "Tester" valida.
+*   🧠 **Pensamento Paralelo**: Permite atacar Frontend e Backend simultaneamente (conceitualmente).
+*   🛡️ **Orquestração**: Garante que as peças se encaixem no final.
+
+---
+
+## 3. `/81-brainstorm` (Antigo `brainstorm.md`)
+
+**O Problema Anterior:**
+O comando `/01-iniciar-projeto` exige que você já saiba o que quer ("Nome", "Escopo"). E se você só tiver uma ideia vaga?
+
+**O Benefício:**
+Este workflow é a fase **Zero**:
+*   💡 **Ideação Guiada**: Ajuda a transformar "Quero um Uber para Pets" em um escopo técnico viável.
+*   🔍 **Exploração de Viabilidade**: Analisa concorrentes e desafios técnicos antes de escrever uma linha de código.
+
+---
+
+## 4. `/82-testar-lib` (Antigo `testar.md`)
+
+**O Problema Anterior:**
+Os workflows padrão dizem "Rode os testes", mas não ensinam *como* estruturar uma estratégia de testes complexa.
+
+**O Benefício:**
+Este workflow é o **Manual de Qualidade Especializado**:
+*   🧪 **Estratégia Pyramid**: Ensina a balancear Unitários vs Integração vs E2E.
+*   🛠️ **Tooling**: Sugere ferramentas específicas (Jest, Vitest, Playwright) para cada cenário.
+
+---
+
+## 📋 Resumo da Organização
+
+Ao adotar essa numeração, cobrimos o ciclo completo:
+
+*   **01-08**: Ciclo de Vida Padrão (Do início ao Deploy).
+*   **Guides**: Ferramentas de "Super Poderes" (Orquestração, Ideação, Testes Profundos).