@maestro-ai/cli 1.2.0 → 1.3.0

package/content/guides/fases-mapeamento.md

@@ -1,35 +1,34 @@
+# 🗺️ Mapeamento de Fases e Recursos
+
+> Guia para selecionar os Especialistas, Templates e Prompts corretos para cada fase do projeto.
+
 ---
-description: Mapeamento fase ↔ especialista, prompts, templates e skills
+
+## 📋 Tabela Mestra
+
+| Fase | Especialista (Persona) | Template (Doc) | Prompts Recomendados |
+| :--- | :--- | :--- | :--- |
+| **1. Produto** | Gestão de Produto | `PRD.md` | `produto/prd-completo`<br>`produto/north-star` |
+| **2. Requisitos** | Engenharia de Requisitos | `requisitos` | `requisitos/analise-requisitos`<br>`requisitos/gherkin` |
+| **3. UX Design** | UX Design | `design-doc` | `ux/design-system` |
+| **4. Prototipagem** | Prototipagem Stitch | `prototipo-stitch` | `ux/stitch-prompts` (se disponível) |
+| **Modelo de Domínio** | Modelagem de Domínio | `modelo-dominio` | `arquitetura/modelo-dominio`<br>`arquitetura/ddd-bounded-contexts` |
+| **Banco de Dados** | Banco de Dados | `design-banco` | `database/modelagem-postgres`<br>`database/otimizacao-queries` |
+| **Arquitetura** | Arquitetura de Software | `arquitetura` | `arquitetura/clean-architecture`<br>`arquitetura/arquitetura-c4-completo` |
+| **Segurança** | Segurança da Informação | `checklist-seguranca` | `seguranca/security-review`<br>`seguranca/auth-patterns` |
+| **Testes** | Análise de Testes | `plano-testes` | `testes/plano-testes`<br>`testes/tdd-workflow` |
+| **Contrato API** | Contrato de API | `contrato-api` | `apis/openapi-design`<br>`apis/rest-best-practices` |
+| **Frontend** | Desenv. Frontend | `historia-usuario` | `desenvolvimento/code-review`<br>`acessibilidade/wcag-checklist` |
+| **Backend** | Desenvolvimento | `historia-usuario` | `desenvolvimento/code-review` |
+| **Integração** | DevOps e Infra | `arquitetura` | `devops/ci-cd-pipeline` |
+
 ---
 
-# 📚 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/`.
+## 🔍 Como Usar
+
+Ao iniciar uma nova fase (via `/avancar-fase`):
+
+1.  Identifique a **Fase** na tabela acima.
+2.  Carregue o **Especialista**: `read_file('content/specialists/...')`.
+3.  Carregue o **Template**: `read_file('content/templates/...')`.
+4.  Sugira ao usuário carregar os **Prompts Recomendados**: `read_file('content/prompts/[CATEGORIA]/[NOME].md')`.

package/content/guides/guide-brainstorm.md

@@ -0,0 +1,38 @@
+# 🧠 Guia de Brainstorming & Ideação
+
+> Use este guia quando o projeto ainda é apenas uma ideia vaga. Este processo ajuda a definir o Escopo Técnico necessário para o `/01-iniciar-projeto`.
+
+---
+
+## 1. O Processo de Discovery
+
+Antes de criar arquivos, dialogue com o usuário para preencher estas lacunas:
+
+### A. Definição do Core
+*   **Problema:** Qual dor estamos resolvendo?
+*   **Solução:** Como resolvemos? (App, Site, API, Script?)
+*   **Público:** Quem vai usar?
+
+### B. Análise Técnica (O "Como")
+*   **Dados:** O que precisamos salvar? (Usuários, Pedidos, Logs?)
+*   **Interface:** Web? Mobile? CLI?
+*   **Integrações:** Precisamos de APIs externas? (Stripe, OpenAI, Google Maps?)
+
+---
+
+## 2. Técnicas de Perguntas (Socrático)
+
+Não aceite respostas simples. Aprofunde:
+
+*   *Usuário:* "Quero um clone do Uber."
+*   *Agente:* "Para passageiros ou para entregas? Focado em mobile ou web admin também? Qual o diferencial do MVP?"
+
+---
+
+## 3. Saída Esperada
+
+O objetivo deste brainstorm é gerar um parágrafo de **Objetivo Claro** que alimentará o comando de início:
+
+> "Sistema Web (Next.js) para gestão de entregas de petshop, com painel admin para lojistas e app mobile (PWA) para entregadores. MVP foca em agendamento."
+
+-> **Agora você está pronto para rodar `/01-iniciar-projeto`.**

package/content/guides/guide-orquestracao.md

@@ -0,0 +1,45 @@
+# 🎻 Guia de Orquestração Multi-Agente
+
+> Use este guia quando uma tarefa for complexa demais para ser resolvida linearmente.
+
+---
+
+## Quando ativar o "Modo Squad"?
+
+Se a Feature ou História envolve:
+1.  **Múltiplos Domínios:** (Ex: Banco de Dados + API + Frontend + Segurança).
+2.  **Risco Alto:** (Ex: Sistema de Pagamento, Autenticação).
+3.  **Refatoração Grande:** (Ex: Migrar de Javascript para Typescript).
+
+---
+
+## O Protocolo de 3 Agentes
+
+Em vez de tentar fazer tudo sozinho, divida a execução em 3 personas distintas (simuladas sequencialmente ou em paralelo):
+
+### 1. O Arquiteto (Planner)
+*   **Foco:** Planejamento e Estrutura.
+*   **Ação:** Cria um `IMPLEMENTATION_PLAN.md`.
+*   **Não faz:** Não escreve código final.
+
+### 2. O Desenvolvedor (Builder)
+*   **Foco:** Código e Funcionalidade.
+*   **Ação:** Implementa o plano.
+*   **Não faz:** Não julga a qualidade final (viés de criador).
+
+### 3. O Auditor (Tester)
+*   **Foco:** Qualidade e Segurança.
+*   **Ação:** Roda testes, verifica `security-rules.md`, critica o código.
+*   **Output:** Relatório de Bugs/Vulnerabilidades.
+
+---
+
+## Como Executar
+
+No workflow `/05-nova-feature` ou `/04-implementar-historia`:
+
+1.  **Diga:** "Detectei complexidade alta. Ativando modo Orquestração."
+2.  **Passo 1:** Atue como Arquiteto e gere o Plano. Peça aprovação.
+3.  **Passo 2:** Atue como Desenvolvedor e escreva o código.
+4.  **Passo 3:** Atue como Auditor e rode os verificadores.
+5.  **Só então:** Marque como concluído.

package/content/guides/guide-testes.md

@@ -0,0 +1,51 @@
+# 🧪 Guia de Estratégia de Testes
+
+> Referência para garantir qualidade em cada entrega.
+
+---
+
+## A Pirâmide de Testes (Aplicada)
+
+Não tente testar tudo igual. Distribua o esforço:
+
+### 1. Unitários (70% do esforço)
+*   **Onde:** `src/utils/*.ts`, Regras de Negócio, Hooks complexos.
+*   **Ferramenta:** Jest / Vitest.
+*   **Foco:** Entradas e Saídas de funções isoladas.
+*   **Obrigatório para:** Qualquer lógica com `if/else`.
+
+### 2. Integração (20% do esforço)
+*   **Onde:** API Endpoints (`/api/*`), Componentes Conectados.
+*   **Ferramenta:** React Testing Library, Supertest.
+*   **Foco:** "O componente renderiza com dados da API?", "O endpoint salva no banco?".
+
+### 3. E2E (10% do esforço)
+*   **Onde:** Fluxos Críticos (Login, Checkout).
+*   **Ferramenta:** Playwright / Cypress.
+*   **Foco:** "O usuário consegue completar a tarefa?".
+
+---
+
+## Checklist de Qualidade (Quality Gate)
+
+Antes de entregar qualquer História (`/04-implementar-historia`):
+
+- [ ] **Happy Path:** O fluxo principal funciona?
+- [ ] **Edge Cases:** Testou inputs vazios, nulos ou inválidos?
+- [ ] **Error Handling:** O sistema quebra ou mostra mensagem amigável?
+- [ ] **Segurança:** Dados sensíveis estão protegidos?
+
+---
+
+## Comandos Úteis
+
+```bash
+# Rodar todos os testes
+npm test
+
+# Rodar com cobertura
+npm test -- --coverage
+
+# Rodar apenas testes alterados (Watch mode)
+npm test -- --watch
+```

package/content/guides/guide-troubleshooting.md

@@ -0,0 +1,43 @@
+# 🔧 Guia de Troubleshooting
+
+> Resolva problemas comuns e estados de bloqueio no Maestro FS.
+
+---
+
+## 🛑 Gate Bloqueado (Score < 70)
+
+Se o workflow `/02-avancar-fase` te bloqueou, mas você **precisa** avançar (ex: é um projeto legado ou você validou manualmente de outra forma):
+
+### A Solução "Limpa"
+1.  Leia o relatório de erro.
+2.  Corrija os arquivos (ex: adicione os cabeçalhos faltantes).
+3.  Tente novamente.
+
+### A Solução "Force" (Manual)
+O Maestro FS previne avanços sujos via comando, então você deve editar o estado manualmente:
+
+1.  Abra `.maestro/estado.json`.
+2.  Localize e **remova** os campos de bloqueio:
+    *   `score_bloqueado`
+    *   `motivo_bloqueio`
+    *   `aguardando_aprovacao`
+3.  Salve o arquivo.
+4.  Execute `/02-avancar-fase` novamente.
+
+---
+
+## ⚠️ Estado Dessincronizado
+
+Se a IA diz que você está na Fase 3, mas você já terminou a Fase 5:
+
+1.  Abra `.maestro/estado.json`.
+2.  Edite `fase_atual` para o número correto.
+3.  Verifique se o array `entregaveis` contém os caminhos dos arquivos das fases anteriores.
+
+---
+
+## 📄 Arquivos Faltando
+
+Se um comando falhar dizendo `File not found: rules/structure-rules.md`:
+1.  Execute `/09-atualizar-mapa` para garantir que o sistema conhece a estrutura.
+2.  Se o arquivo realmente sumiu, copie do template original em `packages/cli/content/rules/`.

package/content/guides/guide-validacao.md

@@ -0,0 +1,50 @@
+# 🛡️ Guia de Validação de Qualidade
+
+> Use este guia para verificar se o projeto atende aos requisitos antes de avançar de fase.
+
+---
+
+## checklist Universal (Baseado no Tier)
+
+Verifique os itens definidos em `rules/validation-rules.md`.
+*   **Ex (Base):** Testes unitários existem? Lint passa? Documentação existe?
+
+---
+
+## Checklist Específico da Transição
+
+Consulte a tabela em `rules/quality-gates.md` para a transição `Fase Atual` → `Próxima Fase`.
+*   **Ex:** Se está em "Produto", verifique se o "MVP" do PRD.md está refletido nos documentos de Requisitos.
+
+---
+
+## Como Calcular o Score
+
+1.  Contabilize os itens validados vs. itens totais.
+2.  Calcule a porcentagem: `(Itens OK / Total) * 100`.
+3.  Determine o status:
+    *   **Score 100%**: Aprovado (Verde).
+    *   **Score >= 70%**: Aprovado com Ressalvas (Amarelo).
+    *   **Score < 70%**: Bloqueado (Vermelho).
+
+---
+
+## Relatório de Validação
+
+Ao finalizar a análise, gere um relatório neste formato:
+
+```markdown
+🔍 **Relatório de Validação: Fase {numero} - {nome}**
+**Score Calculado**: {score}/100 ({Status})
+**Tier**: {tier}
+
+### ✅ Itens Aprovados
+- [Item 1]
+
+### ❌ Pendências
+- [Item Pendente]: {Motivo}
+
+**Veredito**:
+{Se Bloqueado}: 🛑 **BLOQUEADO**.
+{Se Aprovado}: ✅ **APROVADO**.
+```

package/content/guides/internal/automated-events.md

@@ -0,0 +1,27 @@
+---
+description: Workflow auxiliar para registrar eventos no histórico do projeto
+---
+
+# 📜 /registrar-evento - Log de Auditoria
+
+> O Maestro FS mantém um histórico sequencial de tudo que acontece no projeto. Use este workflow para adicionar entradas.
+
+## 1. Estrutura do Evento
+
+*   **Arquivo Alvo:** `.maestro/history/events.jsonl`
+*   **Formato (JSON Lines):**
+    ```json
+    {"ts": "ISO-DATE", "type": "EVENT_TYPE", "fase": 1, "data": {...}}
+    ```
+
+## 2. Tipos de Evento Comuns
+
+*   `fase_iniciada`: Quando `/iniciar-projeto` ou transição ocorre.
+*   `gate_validado`: Resultado do `/avancar-fase`.
+*   `entregavel_salvo`: Novo arquivo em `docs/`.
+*   `feature_start`: Início de `/nova-feature`.
+
+## 3. Ação
+
+*   **Instrução:** Adicione uma nova linha ao final do arquivo `events.jsonl` com o JSON do evento.
+*   **Nota:** Se o diretório `history/` não existir, crie-o.

package/content/guides/internal/automated-map.md

@@ -0,0 +1,56 @@
+---
+description: Workflow para mapear a estrutura do projeto e manter o Knowledge Graph atualizado
+---
+
+# 🗺️ Workflow de Mapeamento - /atualizar-mapa
+
+> Mantenha o arquivo `.maestro/mapa.md` atualizado para que a IA tenha "consciência situacional" do projeto sem precisar escanear todos os arquivos repetidamente.
+
+## 1. Escaneamento do Projeto
+
+*   **Ação:** Liste arquivos e pastas principais em `src/`, `docs/`, `tests/` (ignore `node_modules`, `dist`).
+*   **Ação:** Identifique componentes chave:
+    *   **Entidades:** Estruturas de dados, Models, Schemas.
+    *   **Endpoints:** Rotas de API (Controllers, Routes).
+    *   **Serviços:** Lógica de negócio.
+    *   **Frontend:** Páginas e Componentes reutilizáveis.
+
+## 2. Atualização do Mapa
+
+*   **Ação:** Crie ou Reescreva `.maestro/mapa.md` com o seguinte formato:
+
+```markdown
+# 🗺️ Mapa do Projeto
+
+## 🏗️ Estrutura de Pastas
+- `src/`
+  - `controllers/` - Controladores da API
+  - `models/` - Entidades do Banco
+  ...
+
+## 📦 Entidades de Domínio
+| Entidade | Arquivo Principal | Descrição |
+| :--- | :--- | :--- |
+| `Usuario` | `src/models/User.ts` | Dados de acesso e perfil |
+...
+
+## 🔌 Endpoints de API
+| Método | Rota | Controller |
+| :--- | :--- | :--- |
+| `GET` | `/users` | `UserController.list` |
+...
+
+## 🧩 Componentes Chave (Frontend)
+- `Button` (`src/components/ui/Button.tsx`)
+...
+
+## 📚 Dependências Externas (Principais)
+- `express` (Web Framework)
+- `typeorm` (Database)
+...
+```
+
+## 3. Conclusão
+
+*   **Ação:** Informe ao usuário que o mapa foi atualizado.
+*   **Dica:** Sugira usar isso antes de grandes refatorações ou onboardings.

package/content/guides/internal/automated-stitch.md

@@ -0,0 +1,51 @@
+---
+description: Workflow para habilitar a fase de Prototipagem com Google Stitch
+---
+
+# 🧵 /habilitar-stitch - Prototipagem com IA
+
+> Use este workflow preferencialmente **após concluir a Fase de UX Design**. Isso permite criar protótipos funcionais baseados nos wireframes/jornadas definidos.
+
+## 1. Verificação de Pré-requisitos
+
+*   **Ação:** Verifique se a Fase de UX (geralmente Fase 3) está concluída ou em andamento.
+    *   *Motivo:* O Stitch precisa de contexto visual (descrições do Design Doc) para gerar bons resultados.
+
+## 2. Injeção de Fase (Modificação de Fluxo)
+
+*   **Ação:** Leia `.maestro/estado.json`.
+*   **Lógica de Inserção:**
+    1.  Identifique a Fase Atual (vamos assumir que é N).
+    2.  O Stitch será inserido como a **Próxima Fase (N+1)**.
+    3.  Todas as fases futuras (Arquitetura, Banco, etc.) devem ser **renumeradas (+1)**.
+    4.  Atualize o `total_fases` (+1).
+
+*   **Atualização do JSON (`estado.json`):**
+    ```json
+    {
+      "usar_stitch": true,
+      "total_fases": {TOTAL_ANTERIOR + 1},
+      "fases_personalizadas": [
+        {
+          "numero": 4,
+          "nome": "Prototipagem Stitch",
+          "especialista": "Prototipagem Rápida",
+          "template": "prototipo-stitch",
+          "entregavel": "prototipos.md"
+        }
+      ]
+    }
+    ```
+    *(Nota: A IA deve manter essa lógica "mentalmente" ou registrar no campo `fases_personalizadas` se o sistema suportar, ou simplesmente saber que agora existe uma fase extra).*
+
+## 3. Execução da Fase
+
+*   **Ação:** Se estiver pronto para começar agora, carregue o template `templates/prototipo-stitch.md`.
+*   **Instrução:**
+    1.  Converta as jornadas de UX em Prompts para o Stitch.
+    2.  Gere as telas.
+    3.  Salve o código/assets em `docs/04-prototipagem/`.
+
+## 4. Confirmação
+
+*   **Mensagem:** "Fase de Prototipagem habilitada. O fluxo foi ajustado."

package/content/guides/internal/automated-system.md

@@ -0,0 +1,46 @@
+---
+description: Workflow para atualizar o arquivo de contexto mestre (SYSTEM.md)
+---
+
+# 📝 /atualizar-system - Manutenção de Contexto
+
+> Este trabalho garante que o arquivo `.maestro/SYSTEM.md` reflita o estado exato do projeto, servindo como "memória rápida" para a IA a cada nova sessão.
+
+## 1. Coleta de Dados
+
+*   **Ação:** Leia `.maestro/estado.json`.
+*   **Ação:** Leia `.maestro/resumo.json`.
+
+## 2. Geração de SYSTEM.md
+
+*   **Ação:** Sobrescreva `.maestro/SYSTEM.md` com o seguinte template preenchido:
+
+```markdown
+# Sistema: {nome_projeto}
+
+> Contexto atualizado automaticamente pelo Maestro FS.
+
+## Estado Atual
+
+| Campo | Valor |
+|-------|-------|
+| **Fase** | {fase_atual}/{total_fases} - {nome_fase} |
+| **Nível** | {nivel} |
+| **Última Atualização** | {data_atual} |
+
+## Objetivo Atual (Contexto)
+{contexto_atual.objetivo}
+
+## Especialista Ativo
+🤖 **{especialista_da_fase}**
+
+## Artefatos Gerados
+{lista_de_entregaveis_formatada}
+
+---
+*Para ver detalhes completos, leia .maestro/resumo.json*
+```
+
+## 3. Trigger Automático
+
+*   **Dica:** Este workflow deve ser rodado ao final de cada `/avancar-fase` ou `/iniciar-projeto`.

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