melhorias em compoenentes de numero

2026-04-30 12:19:36 -03:00 · 2026-04-30 12:19:36 -03:00 · 303eda1b99
commit 303eda1b99
parent 5124844773
27 changed files with 3056 additions and 55 deletions
--- a/.agent/workflows/adicionar-ajuda.global.md
+++ b/.agent/workflows/adicionar-ajuda.global.md
@ -0,0 +1,114 @@
+---
+description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
+---
+
+# Workflow: Adicionar Ajuda em Telas
+
+Este workflow automatiza a inserção do botão de ajuda e a criação do arquivo de documentação correspondente sempre que uma tela é criada ou modificada de forma significativa.
+
+O objetivo da ajuda é **auxiliar o usuário final a compreender e utilizar corretamente a aplicação**, explicando o funcionamento da tela de forma clara e objetiva.
+
+## Pré-requisitos
+
+- O arquivo alvo deve ser um componente de interface (`.tsx` para React ou `.vue` para Vue).
+- O projeto deve possuir um componente de ajuda (ex: `BotaoAjuda`, `HelpButton` ou equivalente) disponível para uso na interface.
+- Caso não exista, criar um componente reutilizável que exiba o conteúdo do `.ajuda.md` em modal ou drawer.
+
+## Passos
+
+### 1. Identificar o Componente Alvo
+
+Determine qual arquivo representa a tela principal ou modal que está sendo criado ou editado.
+
+- React → `.tsx`
+- Vue → `.vue`
+
+### 2. Verificar Existência de Ajuda
+
+Procure por um arquivo de ajuda com o mesmo nome do componente e sufixo indicativo de ajuda (ex.: `.ajuda.md`) localizado na mesma pasta.
+
+Exemplo:
+
+```
+
+TelaCadastroUsuario.tsx
+TelaCadastroUsuario.ajuda.md
+
+```
+
+ou
+
+```
+
+TelaCadastroUsuario.vue
+TelaCadastroUsuario.ajuda.md
+
+````
+
+### 3. Criar ou Atualizar o Arquivo Markdown
+
+Se o arquivo `.ajuda.md` não existir, crie-o utilizando o template básico abaixo.
+
+O conteúdo deve ser escrito **pensando no usuário final**, explicando de forma simples como utilizar a tela.
+
+A documentação deve incluir, quando aplicável:
+
+- **Objetivo da tela**
+- **Descrição dos botões**
+- **Descrição dos campos de formulário**
+- **Regras de preenchimento e validações**
+- **Fluxo esperado de uso**
+- **Contexto técnico ou legal**, quando relevante para o entendimento da funcionalidade
+
+Template inicial:
+
+```markdown
+# Ajuda: [Nome da Tela]
+
+## Objetivo da Tela
+
+Explique de forma simples para que serve esta tela dentro do sistema.
+
+## Botões
+
+- **Salvar**: grava as informações preenchidas.
+- **Cancelar**: descarta as alterações realizadas.
+- **Excluir**: remove o registro atual do sistema.
+
+## Campos do Formulário
+
+- **Nome**: informe o nome completo do responsável.
+- **Data de Vistoria**: data em que a vistoria foi realizada.
+- **Observações**: campo livre para registrar informações adicionais.
+
+## Fluxo de Uso
+
+1. Preencha os campos obrigatórios.
+2. Revise as informações inseridas.
+3. Clique em **Salvar** para registrar os dados no sistema.
+
+## Informações Técnicas ou Legais (quando aplicável)
+
+Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
+````
+
+### 4. Posicionamento do Botão de Ajuda
+
+O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.
+
+#### Telas / Páginas
+
+* O botão deve ficar na **parte inferior esquerda da página**.
+* Deve respeitar espaçamento suficiente das bordas da interface.
+* **Não pode sobrepor nenhum componente da tela.**
+* **Não pode ficar oculto ou sobreposto pela barra de módulos da aplicação.**
+* Ajustar `margin`, `padding` ou `z-index` quando necessário para garantir visibilidade adequada.
+
+#### Modais e Diálogos
+
+* O botão deve ficar na **parte inferior esquerda do modal**.
+* Preferencialmente no rodapé do modal ou em um container equivalente.
+* **Não pode sobrepor botões ou ações do modal.**
+* Garantir espaçamento adequado para não interferir na usabilidade.
+
+
--- a/.agent/workflows/aprimorar-IA.global.md
+++ b/.agent/workflows/aprimorar-IA.global.md
@ -0,0 +1,300 @@
+---
+description: Consolidar aprendizados da conversa atual e evoluir continuamente as regras, skills e fluxos da aplicação
+---
+
+# Workflow: Aprimorar Conhecimento da Aplicação
+
+## 🎯 Objetivo
+
+Garantir que **toda decisão tomada** seja imediatamente incorporada ao conhecimento estruturado da aplicação, mantendo o sistema de rules, workflows e skills **coerente, atualizado, não redundante e sem contradições**.
+
+Este workflow é **obrigatório** e deve ser executado sempre que houver qualquer definição nova.
+
+---
+
+## Artefatos de Conhecimento
+
+O conhecimento do agente está organizado em **três tipos de artefatos**, cada um com responsabilidade distinta:
+
+| Artefato | Diretório | Responsabilidade |
+|----------|-----------|------------------|
+| **Rules** | `.agent/rules/` | Restrições e convenções que o agente **deve respeitar sempre** |
+| **Workflows** | `.agent/workflows/` | Processos sequenciais com passos numerados para tarefas bem definidas |
+| **Skills** | `.agent/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
+| **Memória** | `.agent/memoria/` | Registros históricos, contexto do projeto, fatos e decisões importantes |
+
+### Diferenças entre os artefatos
+
+| Critério | Rule | Workflow | Skill | Memória |
+|----------|------|----------|-------|---------|
+| **Formato** | Regra declarativa | Passos sequenciais | Guia prático com templates | Diários, ADRs, documentação de contexto puro |
+| **Quando usar** | Aplicada **automaticamente** em todo contexto | Acionado por **comando** (`/workflow`) | Consultado **sob demanda** ao iniciar tarefa complexa | Consultado **para restaurar contexto** e entender escopo |
+| **Exemplos** | "Nunca usar `any`" | "/migracao_banco" | "Criar função api2 end-to-end" | "ADR de transição para Nuxt 4", "Dicionário de dados" |
+| **Escopo** | Restrição transversal | Processo pontual | Padrão operacional completo | Registro histórico e base factual |
+
+### Regra de escolha
+
+- Se é uma **restrição** que vale sempre → **Rule**
+- Se é um **processo com etapas** que o usuário aciona → **Workflow**
+- Se é um **guia operacional** com templates e checklist para tarefas complexas → **Skill**
+- Se o conteúdo serve como **referência cruzada** durante tarefas → **Skill**
+- Se é um **registro de estado, decisão técnica importante ou compreensão do domínio temporal** → **Memória**
+
+---
+
+## 1️⃣ Análise do Contexto Atual (Obrigatória)
+
+É obrigatório:
+
+- Revisar integralmente a conversa atual.
+- Identificar:
+  - Regras de negócio novas ou alteradas.
+  - Padrões técnicos definidos.
+  - Convenções estabelecidas.
+  - Decisões arquiteturais.
+  - Ajustes de comportamento do sistema ou do agente.
+
+Para cada item identificado, classificar obrigatoriamente:
+
+- Já existe artefato correspondente (rule, workflow ou skill) → **ATUALIZAR**
+- Existe parcialmente → **REFATORAR**
+- Não existe → **CRIAR**
+- Impacta múltiplas áreas → **PROPAGAR**
+
+---
+
+## 2️⃣ Atualização das Rules (Obrigatória)
+
+### Regras inegociáveis:
+
+- Toda nova regra **DEVE** ser registrada.
+- Nenhuma regra pode existir apenas na conversa.
+- É **PROIBIDO** deixar conhecimento implícito.
+
+### Estrutura obrigatória:
+
+- Um arquivo = um único assunto.
+- Nome claro em `snake_case`.
+- Limite máximo: ~10.000 caracteres.
+
+### É obrigatório:
+
+- Evitar duplicação de conteúdo.
+- Atualizar regras antigas quando substituídas.
+- Remover ou ajustar regras conflitantes.
+- Garantir consistência semântica entre arquivos.
+
+### Estrutura obrigatória da rule:
+
+```md
+# Nome da Regra
+
+## Contexto
+Quando se aplica.
+
+## Regra
+Definição objetiva e obrigatória.
+
+## Exemplos
+✅ Correto
+❌ Incorreto
+
+## Impacto
+Problema que evita.
+```
+
+---
+
+## 3️⃣ Atualização dos Workflows (Obrigatória quando aplicável)
+
+Sempre que houver processo repetível identificado:
+
+* Criar ou atualizar workflow em `.agent/workflows/`.
+
+### Obrigatório:
+
+* Frontmatter com `description`.
+* Passos numerados.
+* Clareza operacional (sem ambiguidade).
+* Comandos executáveis quando possível.
+* Uso de `// turbo` para comandos seguros.
+
+---
+
+## 4️⃣ Atualização das Skills (Obrigatória quando aplicável)
+
+Sempre que um padrão operacional complexo for definido, refinado ou corrigido:
+
+* Criar ou atualizar skill em `.agent/skills/<nome-da-skill>/SKILL.md`.
+
+### Quando atualizar uma skill:
+
+- Nova regra afeta o padrão operacional descrito na skill (ex: nova convenção de tipagem afeta `criar-funcao-api2`)
+- Novo workflow introduz etapas que complementam ou substituem uma skill
+- Um erro recorrente revela que a skill está incompleta ou desatualizada
+- Uma decisão arquitetural muda o fluxo descrito na skill
+
+### Estrutura obrigatória da skill:
+
+```md
+---
+name: nome-da-skill
+description: >
+  Descrição em uma linha do que a skill faz.
+---
+
+# Skill: Nome Descritivo
+
+Parágrafo de contexto explicando quando usar.
+
+## PASSO N — Título do Passo
+Instruções com código, regras e padrões.
+
+## Checklist Final
+- [ ] Item de verificação
+
+## Referências
+- Regras: `.agent/rules/xxx.md`
+- Workflow: `.agent/workflows/xxx.md`
+```
+
+### Regras de organização:
+
+- Uma skill por diretório: `.agent/skills/<nome>/SKILL.md`
+- Skills globais são identificadas pelo campo `scope: global` no frontmatter
+- Nome do diretório em `kebab-case`
+- A skill **não deve duplicar** conteúdo de rules — referencia-as via seção `Referências`
+- A skill **pode consolidar** conhecimento de múltiplas rules e workflows em um guia unificado
+- Templates de código devem estar na própria skill (não em arquivos separados, a menos que sejam muito grandes)
+
+### Skills globais (distribuídas via `atualizar-agente.global.sh`):
+
+| Skill | Escopo |
+|-------|--------|
+| `mapear-codigo-fonte` | Mapear e navegar a estrutura de qualquer monorepo TS |
+| `diagnosticar-erros-build` | Diagnosticar erros de build em cascata entre pacotes |
+| `documentar-decisao-tecnica` | Registrar decisões técnicas como ADRs |
+
+### Skills de projeto (criadas localmente em cada monorepo):
+
+Cada projeto pode criar skills adicionais específicas em `.agent/skills/<nome>/SKILL.md`.
+Essas skills focam nos padrões e domínios exclusivos daquele projeto.
+
+Exemplos de skills de projeto:
+
+| Skill | Escopo |
+|-------|--------|
+| `criar-funcao-api` | Função de API end-to-end (comuns → back → front) |
+| `criar-componente-vue3` | Componente Vue 3 com padrões obrigatórios do projeto |
+| `consultar-banco-knex` | Queries Knex com padrões de leitura/escrita/JSONB |
+| `implementar-permissoes` | Controle de acesso específico do domínio |
+
+---
+
+## 5️⃣ Atualização da Memória (Obrigatória quando aplicável)
+
+Sempre que decisões críticas sobre a arquitetura da aplicação ou o contexto do domínio precisarem ser arquivadas temporária ou permanentemente de maneira descritiva (e não diretamente injetável em código ou regra de lint):
+
+* Registre o novo documento no formato adequado mantendo a pasta limpa em `.agent/memoria/`.
+* Exemplo: Manter diário de pendências (`diario_pendencias_modulo_x.md`) ou Arquivo de Registro de Decisão Arquitetural (`adr-001-migracao-nuxt-4.md`).
+* Atenção! Tudo que puder ser abstraído para um formato técnico estrito/guiado, deve virar **Skill** ou **Rule**. Use a Memória apenas como extensão de base factual.
+
+---
+
+## 6️⃣ Revisão Global de TODO o Sistema de Conhecimento (OBRIGATÓRIA E INEGOCIÁVEL)
+
+Esta é a etapa mais crítica.
+
+Sempre que qualquer alteração ocorrer, é **OBRIGATÓRIO revisar TODO o sistema de conhecimento**, incluindo:
+
+* **TODOS os arquivos em `.agent/rules/`**
+* **TODOS os arquivos em `.agent/workflows/`**
+* **TODOS os arquivos em `.agent/skills/`**
+* **TODOS os arquivos em `.agent/memoria/`**
+
+### É PROIBIDO:
+
+* Atualizar apenas um arquivo isolado.
+* Assumir que o impacto é local.
+* Ignorar arquivos existentes.
+* Criar artefatos sem validar o restante do sistema.
+
+---
+
+### A revisão DEVE obrigatoriamente verificar:
+
+#### Consistência
+
+* Não existem regras conflitantes.
+* Não existem interpretações ambíguas.
+* Skills refletem fielmente as rules e workflows atuais.
+
+#### Atualização
+
+* Nenhuma rule está desatualizada.
+* Nenhum workflow usa regra antiga.
+* Nenhuma skill contém padrões obsoletos.
+
+#### Não duplicação
+
+* Não existem regras repetidas em arquivos diferentes.
+* Conteúdos redundantes foram consolidados.
+* Skills referenciam rules (não copiam o conteúdo).
+
+#### Propagação de impacto
+
+* Toda mudança foi refletida em:
+
+  * Rules relacionadas
+  * Workflows relacionados
+  * Skills relacionadas
+  * Memória afetada pela mudança (ADRs, Diários)
+
+#### Coerência estrutural
+
+* Nomes de arquivos continuam válidos.
+* Assuntos estão bem separados.
+* Arquivos grandes foram divididos.
+* Skills estão organizadas em diretórios individuais.
+
+---
+
+### Regras obrigatórias desta etapa:
+
+* **Toda alteração é considerada global até prova contrária.**
+* **Se uma rule muda, todos os workflows e skills relacionados DEVEM ser revisados.**
+* **Se um workflow muda, todas as rules e skills relacionadas DEVEM ser revisadas.**
+* **Se uma skill muda, as rules e workflows que ela referencia DEVEM ser verificados.**
+* **Atualizações de contexto devem garantir que toda a memória conflitante seja suprimida ou tagueada.**
+* **Nenhuma inconsistência pode permanecer.**
+* **Nenhuma duplicação é aceitável.**
+
+---
+
+## 7️⃣ Verificação Final (Checklist obrigatório)
+
+Só é permitido encerrar se TODOS forem verdadeiros:
+
+* [ ] Todas as rules foram revisadas
+* [ ] Todos os workflows foram revisados
+* [ ] Todas as skills foram revisadas
+* [ ] Não existe conflito entre artefatos
+* [ ] Não existe duplicação de conteúdo
+* [ ] Nenhuma regra ficou implícita
+* [ ] Todas as mudanças foram propagadas (rules ↔ workflows ↔ skills)
+* [ ] Estrutura está organizada por assunto
+* [ ] Nenhum arquivo excede ~10k caracteres
+* [ ] Workflows refletem fielmente as rules atuais
+* [ ] Skills referenciam (não duplicam) rules
+* [ ] O sistema está consistente como um todo
+
+---
+
+## ⚠️ Regra Suprema
+
+> Se existir qualquer dúvida, conflito, duplicação ou inconsistência,
+> o trabalho é considerado **INCOMPLETO**.
+
+Não existe atualização parcial.
+Não existe impacto local.
+Não existe exceção.
--- a/.agent/workflows/atualizar-agente.global.md
+++ b/.agent/workflows/atualizar-agente.global.md
@ -0,0 +1,42 @@
+---
+description: Aplica atualizações globais para o agente de IA
+---
+
+# Workflow: Atualizar Agente Global
+
+## Objetivo
+
+Baixar e aplicar a versão mais recente das rules, workflows e tools globais a partir do servidor central (`paiol.idz.one`).
+
+## Passos
+
+### 1. Baixar o script de atualização (se ainda não existir)
+
+```bash
+curl -fL# "https://paiol.idz.one/desenvolvimento/agent-ia/atualizar-agente-global.sh" -o .agent/atualizar-agente.global.sh
+chmod +x .agent/atualizar-agente.global.sh
+```
+
+### 2. Executar o script
+
+// turbo
+
+```bash
+sh .agent/atualizar-agente.global.sh
+```
+
+O script possui auto-atualização: na primeira execução, ele baixa sua própria versão mais recente e re-executa automaticamente.
+
+### 3. Verificar resultado
+
+Confirmar que os arquivos foram atualizados sem duplicações:
+
+```bash
+find .agent/ -name "*.md" -o -name "*.sh" | sort
+```
+
+Resultado esperado: todos os arquivos `.md` devem ter o sufixo `.global` (exceto `tools.md`).
+
+### 4. Revisar mudanças (quando aplicável)
+
+Se houve alterações significativas nas rules ou workflows, executar `/aprimorar-IA` para validar consistência do sistema de conhecimento.
--- a/.agent/workflows/comercial.global.md
+++ b/.agent/workflows/comercial.global.md
@ -0,0 +1,140 @@
+---
+description: Criar uma descrição comercial das funcionalidades e do sistema
+---
+
+# Workflow: Criar Descrição Comercial
+
+Este workflow gera uma descrição comercial de funcionalidades ou do sistema completo, escrita na pasta `./COMERCIAL/`. Cada módulo ou funcionalidade gera um arquivo separado com o padrão `./COMERCIAL/<nome-do-modulo>.md`.
+
+É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
+
+---
+
+## Passos
+
+### 1. Identificar as funcionalidades solicitadas
+
+Perguntar ao usuário quais módulos ou funcionalidades devem ser descritos. Se o pedido for genérico ("descreva o sistema"), listar os módulos principais do projeto e confirmar o escopo antes de redigir.
+
+### 2. Levantar contexto real de cada funcionalidade
+
+Antes de escrever, ler o código-fonte e os componentes relacionados para entender:
+
+- Qual **problema real** a funcionalidade resolve?
+- Quem são os **usuários diretos**? (consultor ambiental, gestor ambiental, gestor público, técnico de campo)
+- Qual é o **fluxo de uso** no dia a dia?
+- Quais **dificuldades operacionais** existiam antes da solução?
+
+### 3. Redigir a descrição comercial
+
+Para cada funcionalidade, produzir **dois blocos de texto** no arquivo `./COMERCIAL/<nome-do-modulo>.md`:
+
+#### Bloco A — Descrição Resumida (2 a 4 linhas)
+
+Texto curto que pode ser usado em páginas de divulgação, apresentações rápidas ou materiais institucionais.
+
+Estrutura obrigatória:
+- **Linha 1**: o problema/dificuldade que existe sem a solução
+- **Linha 2-3**: como funciona na prática (ação do usuário, sem termos técnicos de TI)
+- **Linha 4**: o impacto concreto (ganho mensurável)
+
+*Exemplo:*
+> Sem controle digital, registros de campo ficam em cadernos e planilhas isoladas — sujeitos a perda e erro de transcrição.
+> Com a solução, o técnico registra os dados direto no celular, mesmo sem internet, com validação automática.
+> Isso elimina falhas de preenchimento e garante rastreabilidade completa para auditorias.
+
+#### Bloco B — Descrição Detalhada
+
+Texto mais completo (5 a 15 linhas) que aprofunda o funcionamento e os diferenciais. Deve incluir:
+
+- Cenário de uso realista (quem faz o quê, quando e onde)
+- Recursos técnicos relevantes explicados de forma acessível (offline, sincronização, alertas automáticos)
+- Benefícios encadeados (causa → efeito)
+- **Implicações legais ou normativas** (quando aplicável): se a funcionalidade tem relação com legislação, normas regulatórias ou resoluções de órgãos competentes, **citar expressamente** a norma ou obrigação legal. Isso fortalece o argumento comercial e demonstra que a solução atende requisitos reais de conformidade.
+
+> **Regra de siglas**: toda sigla usada pela primeira vez no texto deve vir acompanhada do nome por extenso. Exemplo: "ANA (Agência Nacional de Águas e Saneamento Básico)". Nas ocorrências seguintes, pode-se usar apenas a sigla.
+
+### 4. Revisar contra o checklist de qualidade
+
+Antes de entregar, validar **cada bloco** contra as restrições abaixo:
+
+- [ ] O texto do Resumo começa pelo problema, não pela funcionalidade?
+- [ ] Há pelo menos um cenário de uso prático (quem, onde, como)?
+- [ ] Os parágrafos são curtos (2 a 4 linhas) com uma ideia principal cada?
+- [ ] A linguagem soa como alguém que vive o problema, não como manual de software?
+- [ ] Está **LIVRE** de jargões de TI e termos em inglês sem tradução?
+- [ ] Toda **sigla** está acompanhada do nome por extenso na primeira ocorrência?
+- [ ] Está **LIVRE** de termos vazios ("Inovador", "Eficiente", "Solução completa", "O presente projeto")?
+- [ ] Está **LIVRE** do padrão repetitivo "O sistema permite / A funcionalidade permite / A ferramenta permite"?
+- [ ] As frases variam de estrutura? (alternando "Na prática...", "Com isso...", "Isso reduz...", "Como resultado...")
+- [ ] Quando há implicação legal ou normativa, a norma/lei/resolução está **citada e destacada** no texto?
+- [ ] O texto é compreensível pelo **público-alvo do produto** sem conhecimento de TI?
+
+---
+
+## Público-Alvo
+
+Todo texto produzido por este workflow deve ser compreensível pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
+
+Regra geral: nenhum dos perfis-alvo tem obrigação de conhecer termos de tecnologia. A linguagem deve ser **acessível, direta e sem jargões de TI**.
+
+---
+
+## Regras de Tom e Vocabulário
+
+| ✅ Usar | ❌ Evitar |
+|---|---|
+| "Na prática, o técnico..." | "O sistema permite..." |
+| "Com isso, a equipe..." | "A solução inovadora..." |
+| "Isso elimina..." | "O presente projeto visa..." |
+| "Como resultado..." | "Dessa forma..." |
+| "Sem a solução, o gestor precisa..." | "A ferramenta oferece..." |
+| "Entregamos controle sobre..." | "Nossa solução oferece..." |
+| "O gestor ganha visibilidade de..." | "A plataforma disponibiliza..." |
+| "página de divulgação" | "landing page" |
+| "frase de abertura" | "hook" |
+| "chamada para ação" | "CTA" (isolado, sem explicação) |
+| "texto persuasivo" | "copywriting" |
+| "linha do tempo, publicações" | "feed" |
+
+**Tom geral**: profissional, direto, sem burocracia institucional. O texto deve parecer escrito por quem constrói a solução e entende a operação do dia a dia do cliente.
+
+---
+
+## Formato de Saída
+
+Cada módulo ou funcionalidade deve gerar **um arquivo próprio** dentro da pasta `./COMERCIAL/`.
+
+**Regra de nomeação do arquivo:**
+- Usar o nome do módulo em **kebab-case** (minúsculo, separado por hifens)
+
+O arquivo `./COMERCIAL/<nome-do-modulo>.md` deve seguir esta estrutura:
+
+```markdown
+# [Nome do Módulo]
+
+## [Nome da Sub-funcionalidade]
+
+### Resumo
+
+[Bloco A — 2 a 4 linhas: problema → solução → impacto]
+
+### Detalhamento
+
+[Bloco B — 5 a 15 linhas: cenário real + técnico acessível + legal]
+
+---
+
+## [Próxima Sub-funcionalidade]
+
+...
+```
+
+---
+
+## Referências
+
+- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
+- Workflow: `.agent/workflows/orcamento.global.md` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades)
+- Workflow: `.agent/workflows/marketing.global.md` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail)
+- Workflow: `.agent/workflows/documentar-codigo.global.md` (para documentação técnica, não comercial)
--- a/.agent/workflows/criar-fluxograma.global.md
+++ b/.agent/workflows/criar-fluxograma.global.md
@ -0,0 +1,185 @@
+---
+description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema
+---
+
+# Workflow: Criar Fluxograma de Decisões
+
+Este workflow cria uma **página interativa de fluxograma** em qualquer aplicação web, usando Mermaid.js instalado como dependência do projeto.
+
+## Princípio
+
+O fluxograma é um artefato vivo. Ele documenta visualmente:
+- Os **pontos de entrada** do processo
+- As **decisões** tomadas em cada etapa
+- Os **registros gerados** (banco, fila, log, e-mail, etc.)
+- As **proteções e regras** que governam os estados
+
+Deve ser mantido sempre sincronizado com o código real.
+
+---
+
+## Passos
+
+### 1. Levantar o processo a ser documentado
+
+Ler os arquivos de código relevantes para entender:
+
+- Quais são os **pontos de entrada**? (funções de API, eventos, webhooks, ações do usuário)
+- Quais são as **decisões**? (condições `if/else`, guards, validações)
+- Quais são os **efeitos colaterais**? (gravações em banco, envios de e-mail, filas, logs)
+- Quais são os **estados possíveis**? (status, notas, flags, etapas)
+- Existe **hierarquia ou prioridade** entre estados?
+
+### 2. Organizar os diagramas
+
+Dividir o processo em **um diagrama por ponto de entrada**.
+
+Cada diagrama deve mostrar:
+- Todos os caminhos possíveis, inclusive early returns e casos de erro
+- Registros gerados com ícone indicativo (ex: 🗄️ banco, 📧 e-mail, 🚫 bloqueio)
+- Decisões claramente separadas por ramificações
+
+Definir a orientação de cada diagrama:
+- `flowchart TD` → vertical (melhor para fluxos sequenciais com poucas ramificações)
+- `flowchart LR` → horizontal (melhor para pipelines e fluxos com muitas etapas em linha)
+
+### 3. Instalar o Mermaid
+
+Instalar como dependência do projeto antes de qualquer implementação:
+
+```bash
+# npm
+npm install mermaid
+
+# pnpm
+pnpm add mermaid
+```
+
+### 4. Criar a página com Mermaid
+
+Adaptar à plataforma do projeto (Vue, React, HTML puro, etc.), mas garantir:
+
+#### Importação
+
+```js
+import mermaid from 'mermaid';
+```
+
+#### Inicialização com tema institucional
+
+Adaptar as cores para a identidade visual do projeto:
+
+```js
+mermaid.initialize({
+  startOnLoad: false,
+  theme: 'base',
+  themeVariables: {
+    primaryColor: '#4F46E5',       // cor primária do projeto
+    primaryTextColor: '#1F2933',
+    primaryBorderColor: '#3730A3', // variação mais escura da primária
+    lineColor: '#6B7280',
+    secondaryColor: '#E0E7FF',     // variação clara da primária
+    tertiaryColor: '#F3F4F6',
+    fontFamily: "'Inter', 'Segoe UI', sans-serif",
+    fontSize: '13px',
+  },
+});
+```
+
+#### Renderização de cada diagrama
+
+```js
+// Para cada diagrama:
+const { svg } = await mermaid.render(`id-unico-${idx}`, codigoMermaid);
+container.innerHTML = svg;
+
+// Tornar o SVG responsivo:
+const svgEl = container.querySelector('svg');
+if (svgEl) {
+  svgEl.style.width = '100%';
+  svgEl.style.height = 'auto';
+  svgEl.removeAttribute('width');
+}
+```
+
+### 5. Registrar a rota e adicionar acesso
+
+- Registrar a rota `/fluxograma` (ou equivalente) no sistema de rotas do projeto
+- Adicionar botão de navegação na tela de administração ou dashboard
+
+---
+
+## Padrão de sintaxe Mermaid
+
+### Tipos de nó por semântica
+
+| Situação | Sintaxe | Exemplo |
+|---|---|---|
+| Início / Fim | `A(["Texto"])` | `A(["Início"])` |
+| Decisão | `B{"Condição?"}` | `B{"Nota é ativa?"}` |
+| Ação / Processo | `C["Texto"]` | `C["Consulta banco"]` |
+| Registro em banco | `D[("🗄️ Grava dado")]` | `D[("🗄️ Grava 203_neutro")]` |
+| E-mail / notificação | `E["📧 Envia e-mail"]` | `E["📧 Agenda na fila"]` |
+| Bloqueio / guard | `F["🚫 Retorna sem ação"]` | `F["🚫 Nota ativa, ignora"]` |
+| Proteção / regra | `G["🛡️ Regra aplicada"]` | `G["🛡️ SQL CASE protege"]` |
+
+### Regras para evitar erros de parsing
+
+```
+✅ Nós com parênteses → usar aspas:
+   A["Texto (com parênteses)"]
+
+✅ Labels de arestas com texto especial → usar aspas:
+   A -- "Label aqui" --> B
+
+✅ Emojis → sempre dentro de aspas:
+   A["🗄️ Grava registro"]
+
+❌ Não usar < > dentro de labels sem aspas
+❌ Não usar & diretamente — usar texto alternativo
+```
+
+### Cores de destaque para nós
+
+```
+style NomeNo fill:#22C55E,color:#fff    → verde sucesso
+style NomeNo fill:#DC2626,color:#fff    → vermelho erro
+style NomeNo fill:#F59E0B,color:#000    → amarelo alerta
+style NomeNo fill:#4F46E5,color:#fff    → cor institucional (adaptar ao projeto)
+style NomeNo fill:#6B7280,color:#fff    → cinza neutro
+```
+
+---
+
+## Validação antes de finalizar
+
+- [ ] Cada ponto de entrada tem seu próprio diagrama?
+- [ ] Todos os registros gerados estão mapeados?
+- [ ] Os caminhos de bloqueio e early return estão visíveis?
+- [ ] A hierarquia de estados (se existir) está documentada?
+- [ ] A data de atualização está registrada na página?
+- [ ] A sintaxe Mermaid está correta (sem erros de parsing)?
+- [ ] O SVG está responsivo (largura 100%, sem width fixo)?
+
+---
+
+## Manutenção
+
+Sempre que o processo mudar:
+
+1. Identificar qual diagrama é afetado
+2. Atualizar o código Mermaid correspondente
+3. Atualizar a data de atualização na página
+4. Se houver novo estado ou proteção, documentar na legenda
+
+---
+
+## Referência de implementação
+
+Se o projeto já possuir um fluxograma implementado, usar como referência.
+Caso contrário, seguir os passos acima para criar a primeira implementação.
+
+## Referências
+
+- Workflow: `.agent/workflows/documentar-codigo.global.md`
+- Skill: `.agent/skills/documentar-decisao-tecnica/SKILL.md` (para decisões que geram fluxogramas)
--- a/.agent/workflows/documentar-codigo.global.md
+++ b/.agent/workflows/documentar-codigo.global.md
@ -0,0 +1,58 @@
+---
+description: Workflow para criação e padronização de documentação em código (JSDoc, comentários e tipagem)
+---
+
+# Workflow: Documentar Código
+
+## 🎯 Objetivo
+Estabelecer um padrão global e unificado para a redação de documentação em código (comentários, `JSDoc` e explicações arquiteturais) em todas as aplicações, garantindo clareza sem prolixidade e respeitando a política de tipagem explícita.
+
+---
+
+## 1️⃣ Princípios Básicos de Documentação
+- **Por que, não o Quê**: Documente o raciocínio por trás da decisão arquitetural ou a regra de negócio que forçou a estratégia, não o mecanismo óbvio que o TypeScript nativamente expressaria.
+- **Nomenclatura Limpa**: Confie na auto-documentação de nomes de variáveis expressivos baseados no domínio antes de escrever um comentário de texto livre.
+
+## 2️⃣ Funções Compartilhadas e JSDoc (Obrigatória)
+Toda função central ou de uso compartilhado, independente da aplicação (frontend, backend, mobile ou bibliotecas comuns), deve portar cabeçalho em `JSDoc`.
+
+### Padrão para JSDoc
+```typescript
+/**
+ * Busca os detalhes de uma entidade baseando-se no ID fornecido e calcula privilégios aplicáveis.
+ * Não utilizar em fluxos de processamento em lote para evitar sobrecarga de requisições ou banco.
+ *
+ * @param tenantId  - Identificador único do cliente/tenant no sistema
+ * @param entityId  - ID exclusivo identificando o registro na base de dados
+ * @returns Retorna o objeto consolidado com dados ou `null` caso não seja encontrado
+ */
+export const obterDetalhesEntidade = async (tenantId: string, entityId: string) => { ... }
+```
+
+## 3️⃣ Tratamento de Exceções e Casts Temporários
+Devido à política `TypeScript sem any`, não utilizamos conversores obscuros imperativamente.
+Porém, se uma coerção agressiva (`as unknown as X`) demonstrar-se temporariamente necessária por divergência ou limitação de SDK terceiro, **o comentário justificando a anomalia é obrigatório**.
+
+```typescript
+// Necessário cast duplo pois a biblioteca externa não provê tipagem genérica adequada na versão atual
+const dados = payload.raw as unknown as RespostaFormatada
+```
+
+## 4️⃣ Atribuição de TODOs
+Toda refatoração, debito técnico visualizado ou dúvida de negócio deixada aberta em código de longo prazo **não prescreve** e deve ser acompanhada do formato `// TODO`:
+- **Tipagem**: `// TODO de tipagem: Criar interface estrita para o retorno da API de listagem (Removendo Partial)`
+- **Negócio**: `// TODO de regra: Validar com a equipe de Produto se a nova taxa adicional será inserida para clientes antigos.`
+
+## 5️⃣ Validação do Fluxo
+Sempre ao propor documentação de um arquivo novo ou refatorado, valide via checklist:
+* [ ] A documentação está aderente sem estar redundante à tipagem TS?
+* [ ] A formatação de parágrafos/espaçamento quebra alguma regra no formatador?
+* [ ] A sintaxe suporta autocompletion na sua camada dependente (`@params` estão exatos)?
+
+---
+
+## Referências
+
+- Rules: `.agent/rules/typescript-sem-any.global.md` (política de tipagem que influencia a documentação)
+- Skill: `.agent/skills/documentar-decisao-tecnica/SKILL.md` (para decisões arquiteturais que exigem ADR além de JSDoc)
+
--- a/.agent/workflows/documentar-regras-negocio.global.md
+++ b/.agent/workflows/documentar-regras-negocio.global.md
@ -0,0 +1,101 @@
+---
+description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md co-localizado com um módulo TypeScript e garantir consistência entre código e documentação
+---
+
+# Workflow: Documentar Regras de Negócio de um Módulo
+
+Use este workflow com `/documentar-regras-negocio.global` para criar ou atualizar o arquivo
+`{modulo}.regras-negocio.md` de qualquer módulo TypeScript com lógica de negócio não-trivial.
+
+---
+
+[1] Ler o módulo TypeScript completamente
+
+Identificar e anotar:
+
+- Nome do arquivo e localização exata
+- Funções exportadas e suas responsabilidades
+- Todos os `if` que representam critérios de decisão
+- Campos lidos e gravados (especialmente JSONB e campos de status)
+- Queries de banco: tabelas acessadas, filtros aplicados, joins
+- Caminhos alternativos (revisão manual, erros, skips)
+- Dependências externas (filas, e-mails, serviços)
+
+---
+
+[2] Verificar se já existe um `.regras-negocio.md`
+
+```bash
+ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
+```
+
+- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
+- **Não existe** → ir para o passo [3]
+
+---
+
+[3] Criar o arquivo `.regras-negocio.md`
+
+Nomenclatura: `{nome-sem-_inicial}.regras-negocio.md` na mesma pasta do módulo.
+
+Preencher com o template da skill `documentar-regras-negocio.global`:
+- Contexto
+- Critérios de Entrada
+- Regras de Processamento (numeradas)
+- Casos de Revisão Manual
+- Estratégia de Saída / Fusão de Campos
+- Dependências Externas
+
+---
+
+[4] Adicionar ou verificar a referência no `.ts`
+
+Garantir que a primeira linha útil do arquivo TypeScript seja:
+
+```typescript
+// Regras de negócio: ver {modulo}.regras-negocio.md
+```
+
+Se já existia e está correto → sem mudança necessária.
+
+---
+
+[5] Simplificar JSDoc que duplicam as regras
+
+Percorrer cada função do módulo:
+
+- JSDoc com lista de regras de negócio → substituir por referência ao `.md`
+- Manter apenas `@param` e `@returns` com informação técnica precisa
+- Comentários inline (`//`) explicando lógica pontual são aceitos → manter
+
+---
+
+[6] Verificar consistência — código ↔ `.md`
+
+Para cada regra listada no `.md`:
+
+- [ ] Existe `if` correspondente no código
+- [ ] A ordem de avaliação bate entre `.md` e código
+- [ ] Campos com separador de concatenação batem entre `.md` e código
+- [ ] `null` como neutro está implementado corretamente (`!= null`)
+- [ ] Queries têm `orderBy` quando a posição dos resultados importa
+
+---
+
+[7] Validar tipagem
+
+// turbo
+```bash
+cd e-licencie-back && node_modules/.bin/tsc --noEmit
+```
+
+Zero erros = concluído.
+
+---
+
+[8] Registrar no sistema de conhecimento (se regras novas)
+
+Se o workflow revelou novos padrões de negócio relevantes ao projeto:
+
+- Criar ou atualizar ADR em `.agent/memoria/` via skill `documentar-decisao-tecnica`
+- Verificar se alguma rule precisa ser atualizada
--- a/.agent/workflows/marketing.global.md
+++ b/.agent/workflows/marketing.global.md
@ -0,0 +1,205 @@
+---
+description: Criar peças de marketing digital para funcionalidades e módulos do sistema
+---
+
+# Workflow: Criar Peças de Marketing
+
+Este workflow gera peças de marketing digital prontas para uso em canais como LinkedIn, Instagram, WhatsApp e E-mail. O resultado é salvo na pasta `./COMERCIAL/` junto ao arquivo comercial do módulo correspondente, ou em arquivo separado `./COMERCIAL/<nome-do-modulo>-marketing.md`.
+
+É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
+
+O agente deve atuar como **especialista em marketing digital voltado para o setor do produto (venda entre empresas)**, aplicando técnicas comprovadas de texto persuasivo e engajamento.
+
+## Público-Alvo das Peças
+
+As peças serão lidas pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
+
+Regra geral: nenhum dos perfis-alvo tem obrigação de conhecer termos de tecnologia. A linguagem deve ser **acessível, direta e sem jargões de TI**. Siglas devem vir acompanhadas do nome por extenso na primeira ocorrência.
+
+---
+
+## Pré-requisitos
+
+Antes de gerar peças de marketing, o arquivo comercial do módulo (`./COMERCIAL/<nome-do-modulo>.md`) já deve existir com os blocos A (Resumo) e B (Detalhamento). Se não existir, aplicar primeiro o workflow `/comercial.global`.
+
+---
+
+## Passos
+
+### 1. Identificar o módulo e o canal
+
+Perguntar ao usuário:
+- Qual módulo ou funcionalidade será divulgado?
+- Quais canais deseja? (LinkedIn, Instagram, WhatsApp, E-mail, ou todos)
+
+### 2. Ler o contexto comercial
+
+Ler o arquivo `./COMERCIAL/<nome-do-modulo>.md` para extrair:
+- O problema e impacto (Bloco A)
+- Os cenários de uso e referências legais (Bloco B)
+
+### 3. Redigir as peças de marketing
+
+---
+
+## Princípios de Engajamento
+
+1. **Abrir com uma provocação ou dado concreto** — nunca com o nome do produto. A primeira frase deve fazer o leitor parar de rolar as publicações.
+2. **Falar a língua do decisor** — usar o vocabulário do público-alvo do produto, não termos de tecnologia.
+3. **Criar urgência sem desespero** — mostrar o custo da inação (multa, retrabalho, perda de prazo) sem tom alarmista.
+4. **Fechar com uma chamada para ação clara** — sempre direcionar para o próximo passo: demonstração, contato, link ou agendamento.
+5. **Adaptar ao canal** — o mesmo conteúdo não funciona igual no LinkedIn, Instagram, WhatsApp e e-mail. Cada peça deve respeitar o formato e tom do canal.
+
+---
+
+## Técnicas Obrigatórias
+
+| Técnica | Como aplicar |
+|---|---|
+| **Frase de abertura impactante** | Pergunta retórica, dado alarmante ou afirmação provocativa nas primeiras 10 palavras |
+| **Prova social** | Mencionar o tipo de cliente que já usa (prefeituras, indústrias, consultorias), sem inventar números |
+| **Contraste antes/depois** | Mostrar o cenário ruim (planilha, papel, multa) ao lado do cenário com a solução |
+| **Especificidade** | Trocar "economiza tempo" por "reduz 4 horas semanais de consolidação manual" |
+| **Chamada para ação conectada ao problema** | A frase final deve se conectar ao problema apresentado, não ser genérica |
+
+---
+
+## Formatos por Canal
+
+### LinkedIn (Carrossel ou Post)
+
+- 3 a 5 parágrafos curtos (1-2 linhas cada)
+- Abrir com frase de abertura forte na primeira linha (antes do "ver mais")
+- Usar quebras de linha para facilitar a leitura
+- Emojis como marcadores (⚠️, ✅, 📊), no máximo 1 por parágrafo
+- Fechar com chamada para ação + hashtags relevantes (no máximo 5)
+
+*Exemplo de LinkedIn:*
+
+```
+⚠️ Sua equipe ainda controla [processo crítico] em planilha?
+
+A maioria das operações só descobre o problema 
+quando o órgão regulador notifica.
+Nessa hora, a multa já está lavrada.
+
+Com [nome do produto], cada registro é feito digitalmente 
+com cálculo automático. Se o valor ultrapassar 
+o limite autorizado, um alerta dispara na hora.
+
+✅ Controle em tempo real
+✅ Alertas automáticos de limite
+✅ Relatórios prontos para auditoria
+
+Quer ver funcionando? Fale com a gente.
+
+#Hashtag1 #Hashtag2 #Hashtag3
+```
+
+### Instagram (Stories / Reels / Carrossel)
+
+- Frases de impacto (no máximo 15 palavras por slide)
+- Visual > texto — cada slide deve ter uma ideia única
+- Usar contrastes visuais (❌ antes / ✅ depois)
+- Chamada para ação no último slide: "Link na bio" ou "Fale com nosso time"
+
+*Exemplo de Instagram:*
+
+```
+Slide 1: "Sua operação está em conformidade?"
+Slide 2: ❌ "Planilhas manuais. Registros esquecidos. Consolidação no fim do mês."
+Slide 3: ⚠️ "[Citação legal relevante]"
+Slide 4: ✅ "Registro digital com cálculo automático."
+Slide 5: ✅ "Alerta em tempo real quando o limite é atingido."
+Slide 6: "Conheça [nome do produto]. Link na bio."
+```
+
+### WhatsApp (Mensagem de prospecção)
+
+- No máximo 4 linhas + 1 chamada para ação
+- Tom pessoal, sem parecer mensagem em massa
+- Mencionar o contexto do destinatário (setor, dificuldade conhecida)
+
+*Exemplo de WhatsApp:*
+
+```
+Oi [Nome], tudo bem?
+
+Vi que vocês trabalham com [contexto do destinatário]. 
+Queria mostrar como estamos ajudando operações como a de vocês 
+a [benefício principal da solução].
+
+Posso te mandar um vídeo rápido de 2 min mostrando como funciona?
+```
+
+### E-mail (Prospecção ou Nutrição)
+
+- Assunto: direto, com gancho de dificuldade real (no máximo 60 caracteres)
+- Corpo: 3 parágrafos curtos — problema → solução → chamada para ação
+- Evitar formatação visual pesada — preferir texto limpo e direto
+
+*Exemplo de E-mail:*
+
+```
+Assunto: [Pergunta sobre dificuldade real do destinatário]
+
+Olá [Nome],
+
+[Parágrafo 1: descrever a dificuldade que o destinatário provavelmente enfrenta]
+
+[Parágrafo 2: como a solução resolve, com dados concretos]
+
+Se fizer sentido, posso agendar 15 minutos para mostrar como funciona 
+na prática. Qual o melhor horário para você?
+
+[Assinatura]
+```
+
+---
+
+## Checklist de Qualidade
+
+Antes de finalizar qualquer peça, validar:
+
+- [ ] A primeira frase **provoca, questiona ou surpreende**?
+- [ ] O texto fala a **língua do decisor** (público-alvo do produto), não de desenvolvedor?
+- [ ] Existe **contraste claro** entre o cenário sem e com a solução?
+- [ ] Os benefícios são **específicos** (números, tempo, ações concretas)?
+- [ ] Tem **chamada para ação clara** e conectada ao problema apresentado?
+- [ ] O tom está **adaptado ao canal** (LinkedIn ≠ WhatsApp ≠ E-mail)?
+- [ ] Está **LIVRE** de jargões de TI e termos em inglês sem tradução?
+- [ ] Toda **sigla** está acompanhada do nome por extenso na primeira ocorrência?
+- [ ] Menções legais são usadas como **argumento de urgência**, não como decoração?
+
+---
+
+## Formato de Saída
+
+O resultado deve ser salvo em `./COMERCIAL/<nome-do-modulo>-marketing.md` ou adicionado ao final do arquivo comercial existente, conforme preferência do usuário.
+
+```markdown
+# Marketing — [Nome do Módulo]
+
+## LinkedIn
+
+[Post pronto para publicação]
+
+## Instagram
+
+[Roteiro de slides para carrossel ou legenda para post]
+
+## WhatsApp
+
+[Mensagem de prospecção]
+
+## E-mail
+
+[Template de prospecção ou nutrição]
+```
+
+---
+
+## Referências
+
+- Workflow: `.agent/workflows/comercial.global.md` (gera os blocos A e B que alimentam o marketing)
+- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
--- a/.agent/workflows/orcamento.global.md
+++ b/.agent/workflows/orcamento.global.md
@ -0,0 +1,130 @@
+---
+description: Criar texto de orçamento pronto para copiar e colar em peças de orçamento/proposta
+---
+
+# Workflow: Criar Texto de Orçamento
+
+Este workflow gera textos prontos para **copiar e colar dentro de documentos de orçamento e propostas comerciais**. O resultado é salvo na pasta `./COMERCIAL/` com o sufixo `-orcamento` (ex: `./COMERCIAL/<nome-do-modulo>-orcamento.md`).
+
+É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
+
+---
+
+## Público-Alvo
+
+O documento de orçamento será lido pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
+
+A linguagem deve ser **acessível, direta e sem jargões de TI**. Siglas devem vir acompanhadas do nome por extenso na primeira ocorrência.
+
+---
+
+## Pré-requisitos
+
+Antes de gerar o texto de orçamento, o agente deve ler o código-fonte do módulo para entender quais funcionalidades existem de fato. Se já existir o arquivo comercial (`./COMERCIAL/<nome-do-modulo>.md`), usá-lo como base para extrair contexto.
+
+---
+
+## Passos
+
+### 1. Identificar o módulo
+
+Perguntar ao usuário qual módulo ou funcionalidade será orçado.
+
+### 2. Levantar contexto
+
+Ler o código-fonte e os componentes relacionados para mapear:
+- Quais **funcionalidades** o módulo oferece de fato?
+- Existe **legislação ou norma** relevante que o módulo atende?
+- Quem são os **usuários diretos**? (consultor, gestor, técnico de campo)
+
+### 3. Redigir o texto de orçamento
+
+O texto deve ser **autocontido** — pronto para colar diretamente dentro de um documento de orçamento sem necessidade de edição. Estrutura obrigatória:
+
+#### Apresentação do Módulo (2 a 4 linhas)
+
+Texto que descreve o módulo de forma direta, mostrando **o que ele faz** e **qual problema resolve**. Se houver legislação ou norma relevante, **citar aqui** para demonstrar conformidade regulatória e fortalecer o argumento.
+
+Regras:
+- Começar pelo que o módulo entrega, não pelo problema
+- Se houver lei/norma relevante, citar com nome por extenso e artigo
+- Tom confiante e profissional — adequado para documento formal
+- Não usar termos de tecnologia
+
+#### Lista de Funcionalidades
+
+Após a apresentação, listar as funcionalidades do módulo em formato de **itens curtos** (1 a 2 linhas cada). Cada item deve:
+
+- Descrever **o que a funcionalidade faz na prática** (ação concreta, não conceito abstrato)
+- Ser compreensível por alguém que **nunca viu o sistema**
+- Ser suficientemente específico para justificar o valor cobrado
+
+Regras para cada item:
+- Começar com o **nome da funcionalidade** em negrito
+- Seguir com uma descrição curta do que ela faz
+- Opcionalmente, incluir o benefício direto entre parênteses ou traço
+
+### 4. Revisar contra o checklist de qualidade
+
+Antes de entregar, validar:
+
+- [ ] A apresentação do módulo é autocontida e compreensível isoladamente?
+- [ ] Cada funcionalidade está descrita de forma concreta (o que faz, não o que é)?
+- [ ] O texto está **pronto para copiar e colar** sem edição?
+- [ ] Está **LIVRE** de jargões de TI e termos em inglês sem tradução?
+- [ ] Toda **sigla** está acompanhada do nome por extenso na primeira ocorrência?
+- [ ] Legislação/norma relevante está **citada na apresentação** com nome por extenso?
+- [ ] O tom é profissional e adequado para um documento formal de orçamento?
+- [ ] É compreensível pelo **público-alvo do produto** sem conhecimento de TI?
+
+---
+
+## Regras de Redação
+
+- **Sem jargões de TI**: trocar termos técnicos por equivalentes acessíveis (ex: "painel" em vez de "dashboard", "código QR" em vez de "QR Code")
+- **Siglas por extenso**: toda sigla deve vir acompanhada do nome por extenso na primeira ocorrência
+- **Tom formal mas acessível**: adequado para um documento de orçamento/proposta enviado a um diretor ou secretário
+- **Funcionalidades concretas**: "Registro de leituras com cálculo automático de volume", não "Módulo de coleta de dados parametrizável"
+
+---
+
+## Formato de Saída
+
+O arquivo `./COMERCIAL/<nome-do-modulo>-orcamento.md` deve seguir esta estrutura:
+
+```markdown
+# [Nome do Módulo]
+
+[Apresentação do módulo — 2 a 4 linhas com legislação relevante, se aplicável]
+
+## Funcionalidades incluídas
+
+- **[Nome da funcionalidade 1]**: [descrição curta do que faz na prática]
+- **[Nome da funcionalidade 2]**: [descrição curta do que faz na prática]
+- **[Nome da funcionalidade 3]**: [descrição curta do que faz na prática]
+- ...
+```
+
+*Exemplo:*
+
+```markdown
+# [Nome do Módulo]
+
+[Apresentação do módulo com descrição direta do que faz, qual problema resolve e,
+se aplicável, legislação ou norma relevante citada por extenso.]
+
+## Funcionalidades incluídas
+
+- **[Funcionalidade 1]**: [descrição curta do que faz]
+- **[Funcionalidade 2]**: [descrição curta do que faz]
+- **[Funcionalidade 3]**: [descrição curta do que faz]
+- ...
+```
+
+---
+
+## Referências
+
+- Workflow: `.agent/workflows/comercial.global.md` (descrição comercial detalhada — Resumo e Detalhamento)
+- Workflow: `.agent/workflows/marketing.global.md` (peças de marketing digital)
+- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)
--- a/.agent/workflows/reels.global.md
+++ b/.agent/workflows/reels.global.md
@ -0,0 +1,200 @@
+---
+description: Criar cadeia de roteiros de Reels para divulgação de funcionalidades e módulos
+---
+
+# Workflow: Criar Roteiros de Reels
+
+Este workflow gera **cadeias de roteiros de Reels** (vídeos curtos de 30 a 60 segundos) organizados por tema. Os roteiros são escritos em tom provocativo, informal e direto — prontos para gravar falando para a câmera ou com narração em off. O resultado é salvo em `./COMERCIAL/<nome-do-modulo>-reels.md`.
+
+É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow.
+
+---
+
+## Público-Alvo dos Reels
+
+Os vídeos serão assistidos pelo **público-alvo do produto**. O agente deve identificar quem são os usuários e decisores com base no contexto do projeto.
+
+Regra geral: a linguagem deve ser **coloquial, direta e sem jargões de TI**. Siglas devem vir acompanhadas do nome por extenso quando citadas pela primeira vez.
+
+---
+
+## Pré-requisitos
+
+Antes de gerar roteiros, o agente deve entender as funcionalidades reais do módulo. Se já existir o arquivo comercial (`./COMERCIAL/<nome-do-modulo>.md`), usá-lo como base. Caso contrário, ler o código-fonte para mapear o que o módulo entrega de fato.
+
+---
+
+## Passos
+
+### 1. Identificar o tema
+
+Perguntar ao usuário:
+- Qual módulo ou funcionalidade será o tema dos reels?
+- Quantos roteiros deseja na cadeia? (padrão: 6)
+- Algum tom específico? (provocativo, educativo, humorístico)
+
+### 2. Levantar contexto
+
+Mapear:
+- Quais **funcionalidades** do módulo geram mais impacto visual e prático?
+- Quais **dores reais** o público-alvo enfrenta sem a solução?
+- Existe **legislação ou norma** que possa ser usada como argumento de urgência?
+- Quais **comparações do dia a dia** fazem sentido para o público?
+
+### 3. Redigir a cadeia de roteiros
+
+Cada cadeia deve conter **4 a 8 roteiros**, todos conectados pelo mesmo tema mas com abordagens diferentes. Cada roteiro segue a estrutura abaixo.
+
+---
+
+## Estrutura de um Roteiro
+
+Cada roteiro deve ter entre **6 e 12 frases curtas**, organizadas em 4 blocos:
+
+### Bloco 1 — Abertura (1-2 frases)
+
+A primeira frase é a mais importante. Ela decide se o espectador para ou rola.
+
+Técnicas obrigatórias (usar pelo menos uma por roteiro):
+
+| Técnica | Exemplo |
+|---|---|
+| **Provocação direta** | "Se você ainda faz isso manual… tá perdendo dinheiro." |
+| **Referência pop** | "Tá mais perdido que timeline de fofoca da Virgínia?" |
+| **Formato "Plot twist"** | "Plot twist: você perde cliente não é pelo preço…" |
+| **Convocação** | "Se sua proposta fosse convocada hoje… ela jogaria?" |
+| **Contraste chocante** | "Expectativa: vou organizar meus processos. Realidade: caos." |
+| **Pergunta retórica** | "Quantas horas você perdeu esse mês montando relatório?" |
+| **Afirmação polêmica** | "A maioria dos consultores está jogando dinheiro fora." |
+
+### Bloco 2 — Dor / Cenário ruim (2-3 frases)
+
+Descrever o cenário do público-alvo SEM a solução. Usar linguagem do dia a dia — como se estivesse conversando com um colega.
+
+Regras:
+- Frases curtas e ritmadas (máximo 12 palavras por frase)
+- Usar repetição para ritmo ("proposta pra um lado, orçamento pra outro…")
+- Descrever ações reais, não conceitos ("anota no papel, perde foto, esquece detalhe")
+- Pode usar humor leve e ironia
+
+### Bloco 3 — Virada / Solução (2-3 frases)
+
+Apresentar o produto como a virada. O nome do produto aparece aqui — naturalmente, sem parecer propaganda.
+
+Regras:
+- O produto é mencionado **uma única vez**, pelo nome
+- Descrever o que o produto faz em **ações concretas**, não em conceitos
+- Usar verbos de ação: "monta", "registra", "envia", "centraliza"
+- Mostrar resultado imediato: "menos retrabalho", "mais fechamento"
+
+### Bloco 4 — Fechamento / Desafio (1-2 frases)
+
+Fechar com uma pergunta ou desafio que provoque o espectador a agir.
+
+Técnicas:
+- **Desafio direto**: "Quer ser titular ou continuar no banco?"
+- **Escolha binária**: "Você decide em qual nível quer jogar."
+- **Pergunta provocativa**: "Você tá otimizando ou só se ocupando?"
+- **Chamada para ação suave**: "Começa a jogar no nível profissional."
+
+---
+
+## Estilos de Roteiro
+
+Cada cadeia deve variar os estilos para manter o conteúdo diverso. O agente deve usar **pelo menos 4 estilos diferentes** numa cadeia de 6 roteiros.
+
+| Estilo | Descrição | Ritmo |
+|---|---|---|
+| **Plot twist** | Começa com uma crença comum e inverte | Surpreendente |
+| **Mais perdido que...** | Analogia cômica + caos do dia a dia | Humorístico |
+| **Convocação** | Metáfora de seleção/time/jogo | Competitivo |
+| **Raiz vs Smart** | Dois perfis contrastados | Comparativo |
+| **Tempo é dinheiro** | Foco em produtividade e custo de oportunidade | Urgência |
+| **Expectativa vs Realidade** | Contraste entre o plano e o caos | Identificação |
+| **Se eu te contasse** | Narrativa de revelação progressiva | Curiosidade |
+| **Checklist do fracasso** | Lista irônica do que NÃO fazer | Irônico |
+
+---
+
+## Regras de Entonação
+
+O roteiro deve indicar **como falar** cada trecho. Usar marcações simples:
+
+| Marcação | Significado |
+|---|---|
+| Texto normal | Tom de conversa, olhando pra câmera |
+| *Texto em itálico* | Tom irônico ou de provocação |
+| **Texto em negrito** | Ênfase, falar mais forte |
+| `[pausa]` | Pausa dramática de 1-2 segundos |
+| `[rápido]` | Falar em ritmo acelerado |
+| `[sussurrando]` | Tom baixo, como se contasse um segredo |
+
+---
+
+## Regras de Redação
+
+- **Frases curtas**: máximo 15 palavras por frase. Idealmente 8-12
+- **Sem jargões de TI**: trocar termos técnicos por equivalentes do dia a dia
+- **Tom coloquial**: "tá", "pra", "gente", "bobo" são permitidos e desejáveis
+- **Referências culturais**: usar quando fizerem sentido para o público (futebol, reality, memes do momento). Marcar como `[ref: atualizar]` se a referência puder ficar datada
+- **Uma ideia por frase**: cada frase deve ser compreensível isoladamente
+- **Sem "Olá pessoal"**: nunca abrir com saudação genérica
+- **Produto natural**: o nome do produto aparece no máximo 1 vez por roteiro, no bloco de solução
+- **Siglas**: toda sigla usada pela primeira vez deve vir acompanhada do nome por extenso
+
+---
+
+## Checklist de Qualidade
+
+Antes de entregar, validar **cada roteiro**:
+
+- [ ] A primeira frase **para o scroll**? (provocação, surpresa ou identificação)
+- [ ] O cenário da dor é **real e reconhecível** pelo público-alvo?
+- [ ] O produto aparece **naturalmente**, sem parecer propaganda forçada?
+- [ ] O fechamento **provoca ação** (pergunta, desafio ou escolha)?
+- [ ] O roteiro tem entre **6 e 12 frases**?
+- [ ] Cada frase tem no **máximo 15 palavras**?
+- [ ] O tom é **coloquial e direto** (não institucional)?
+- [ ] A cadeia usa **pelo menos 4 estilos diferentes**?
+- [ ] Está **LIVRE** de jargões de TI?
+- [ ] O roteiro funciona sendo **falado em voz alta**? (ler em voz alta para validar)
+
+---
+
+## Formato de Saída
+
+O arquivo `./COMERCIAL/<nome-do-modulo>-reels.md` deve seguir esta estrutura:
+
+```markdown
+# Reels — [Nome do Módulo]
+
+> Cadeia de [N] roteiros sobre [tema]
+> Tom: [provocativo / educativo / humorístico]
+> Duração média: 30-60 segundos por reel
+
+---
+
+## 🎥 Roteiro 1 – "[Título criativo]"
+
+"[Primeira frase — abertura impactante]
+
+[Bloco de dor — 2-3 frases curtas]
+
+[Bloco de solução — 2-3 frases com o produto]
+
+[Fechamento — pergunta ou desafio]"
+
+---
+
+## 🎥 Roteiro 2 – "[Título criativo]"
+
+...
+```
+
+---
+
+## Referências
+
+- Workflow: `.agent/workflows/comercial.global.md` (descrição comercial detalhada — base de contexto)
+- Workflow: `.agent/workflows/marketing.global.md` (peças de marketing por canal)
+- Regra global: `.agent/rules/escrita-natural.global.md` (padrão obrigatório de redação)