publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

.

Browse source
This commit is contained in:
Luiz Silva 2026-06-18 16:50:03 -03:00
parent 1adf19b92d
commit 1388a121bc
65 changed files with 157 additions and 5166 deletions
Download patch file Download diff file Expand all files Collapse all files

118
workflows/adicionar-ajuda.global.md
View file

@ -1,118 +0,0 @@
---
type: workflow
name: adicionar-ajuda
description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
scope: global
updatedAt: "2026-06-01"
---
# 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.

263
workflows/aprimorar-IA.global.md
View file

@ -1,263 +0,0 @@
---
type: workflow
name: aprimorar-IA
description: Consolidar aprendizados da conversa atual e evoluir continuamente as regras, skills e fluxos da aplicação
scope: global
updatedAt: "2026-06-01"
---
# 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 `kebab-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 ADR (`adr-001-migracao-nuxt-4.md`).
* Atenção! Tudo que puder ser abstraído para formato técnico estrito deve virar **Skill** ou **Rule**. Use a Memória apenas como extensão de base factual.
---
## 6️⃣ Revisão de Impacto (Dirigida por Grafo)
Quando um artefato é alterado, a revisão deve ser **dirigida**, não exaustiva.
### Processo:
1. Identificar o artefato alterado
2. Consultar a seção `Referências` do artefato para encontrar dependentes diretos
3. Verificar consistência APENAS entre o artefato alterado e seus dependentes
4. Se uma inconsistência for encontrada, propagar para o próximo nível
### Regras de escopo:
| Se alterou... | Revisar... |
|---|---|
| Uma **Rule** | Workflows e skills que a **referenciam** |
| Um **Workflow** | Skills que o **referenciam** |
| Uma **Skill** | Rules e workflows na seção Referências |
| **Memória/ADR** | Nada — memória é registro, não dependência |
### É PROIBIDO:
* Revisar artefatos **sem relação** com a mudança
* Afirmar que "tudo foi revisado" sem listar quais artefatos foram verificados
* Criar artefatos sem verificar se já existe um com o mesmo escopo
### A revisão DEVE verificar:
* Não existem regras conflitantes entre o artefato alterado e seus dependentes
* Referências cruzadas continuam válidas (arquivos existem, nomes corretos)
* Skills refletem fielmente as rules que referenciam
* Não há duplicação de conteúdo entre artefatos
---
## 7⃣ Verificação Final (Checklist obrigatório)
Só é permitido encerrar se TODOS forem verdadeiros:
* [ ] Artefatos dependentes do alterado foram revisados
* [ ] Não existe conflito entre artefatos revisados
* [ ] Não existe duplicação de conteúdo
* [ ] Nenhuma regra ficou implícita
* [ ] Referências cruzadas estão válidas
* [ ] Estrutura está organizada por assunto
* [ ] Skills referenciam (não duplicam) rules
---
## ⚠️ Regra Suprema
> Se existir qualquer dúvida, conflito ou inconsistência
> entre o artefato alterado e seus dependentes,
> o trabalho é considerado **INCOMPLETO**.
A revisão é dirigida, não opcional.

46
workflows/atualizar-agente.global.md
View file

@ -1,46 +0,0 @@
---
type: workflow
name: atualizar-agente
description: Aplica atualizações globais para o agente de IA
scope: global
updatedAt: "2026-06-01"
---
# 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.

144
workflows/comercial.global.md
View file

@ -1,144 +0,0 @@
---
type: workflow
name: comercial
description: Criar uma descrição comercial das funcionalidades e do sistema
scope: global
updatedAt: "2026-06-01"
---
# 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/otimizar-codigos.global.md` (para documentação técnica, não comercial)

189
workflows/criar-fluxograma.global.md
View file

@ -1,189 +0,0 @@
---
type: workflow
name: criar-fluxograma
description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema
scope: global
updatedAt: "2026-06-01"
---
# 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/otimizar-codigos.global.md`
- Skill: `.agent/skills/documentar-decisao-tecnica.global/SKILL.md` (para decisões que geram fluxogramas)

105
workflows/documentar-regras-negocio.global.md
View file

@ -1,105 +0,0 @@
---
type: workflow
name: documentar-regras-negocio
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
scope: global
updatedAt: "2026-06-01"
---
# 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
npx 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

209
workflows/marketing.global.md
View file

@ -1,209 +0,0 @@
---
type: workflow
name: marketing
description: Criar peças de marketing digital para funcionalidades e módulos do sistema
scope: global
updatedAt: "2026-06-01"
---
# 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)

134
workflows/orcamento.global.md
View file

@ -1,134 +0,0 @@
---
type: workflow
name: orcamento
description: Criar texto de orçamento pronto para copiar e colar em peças de orçamento/proposta
scope: global
updatedAt: "2026-06-01"
---
# 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)

71
workflows/otimizar-codigos.global.md
View file

@ -1,71 +0,0 @@
---
type: workflow
name: otimizar-codigos
description: Agente especialista em limpeza e refatoração de código
scope: global
updatedAt: "2026-06-03"
---
Você é um agente especialista em limpeza e refatoração de código para projetos TypeScript, Vue 3, TSX e JSX.
Sua missão é melhorar a legibilidade, organização e manutenção do código, sem alterar o comportamento funcional.
## Regras principais
1. Não altere regras de negócio.
2. Não mude nomes públicos de props, emits, funções exportadas ou contratos de API.
3. Não remova validações existentes.
4. Não altere layout visual sem necessidade.
5. Nenhum arquivo `.vue`, `.ts`, `.tsx` ou `.jsx` deve ultrapassar 250 linhas.
6. Se o arquivo estiver grande, proponha separação em:
- composables
- helpers
- constants
- dispatch tables
- arquivos `.css` separados
7. O `setup()` de componentes Vue não deve ser separado do componente.
8. CSS pode ser separado em:
- `NomeDoArquivo.vue`
- `NomeDoArquivo.css`
9. Quando houver separação de arquivos, melhore a estrutura de pastas (ex: convertendo o arquivo principal em uma pasta dedicada contendo `index.vue` ou `index.ts` junto com seus arquivos auxiliares e subcomponentes).
## O que limpar
- imports não utilizados
- variáveis não utilizadas
- funções duplicadas
- nomes confusos
- blocos muito grandes
- condicionais repetidas
- código morto
- comentários óbvios
- funções inline complexas
- tipagens fracas ou `any` desnecessário
- componentes com responsabilidade demais
## Padrões desejados
- Preferir funções pequenas e nomeadas.
- Usar `computed`, `ref` e `reactive` de forma clara.
- Usar `PropType<T>` quando a prop tiver tipo complexo.
- Sempre usar **Dispatch Table** fortemente tipada para substituir múltiplos blocos de `if`, `else` ou `switch`.
- Sempre dar prioridade para uso de enums.
- Manter tipagens existentes sempre que possível.
- Criar nomes claros e objetivos.
- Preservar compatibilidade com Vue 3 e TypeScript.
## Saída esperada
Para cada arquivo analisado, retorne:
1. Problemas encontrados
2. Melhorias aplicadas
3. Código final refatorado
4. Arquivos sugeridos caso seja necessário dividir
## Formato da resposta
- Seja direto.
- Não explique conceitos básicos.
- Entregue o código pronto.
- Quando separar arquivos, mostrar o conteúdo completo de cada arquivo.

204
workflows/reels.global.md
View file

@ -1,204 +0,0 @@
---
type: workflow
name: reels
description: Criar cadeia de roteiros de Reels para divulgação de funcionalidades e módulos
scope: global
updatedAt: "2026-06-01"
---
# 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)

257
workflows/ux.global.md
View file

@ -1,257 +0,0 @@
---
type: workflow
name: ux
description: Revisar e otimizar UX de componentes e telas Vue (Frontend)
scope: global
updatedAt: "2026-06-01"
---
# Workflow: Revisão de UX
Guia de revisão e otimização de interfaces Vue 3 + Vuetify 3 no ecossistema Azteca — para usuários corporativos com baixa familiaridade tecnológica.
---
## Perfil do Usuário
O público-alvo das interfaces é corporativo e diversificado em experiência técnica:
- Gestores públicos e ambientais
- Técnicos de campo
- Consultores ambientais
- Operadores administrativos
**Premissa central**: o usuário não tem familiaridade avançada com tecnologia. A interface precisa ser autoexplicativa, sem dependência de treinamento prévio.
---
## Paleta de Cores Institucional
Cor base: `#688C00` (verde floresta). Três escalas derivadas: **Verde floresta** (primária), **Âmbar terroso** (apoio/aviso), **Cinza musgo** (neutros). Semânticas independentes para garantir reconhecimento universal.
### Escala primária — Verde floresta
| Token | Hex | Stop | Uso |
|---|---|---|---|
| `--cor-eli-primaria-bg` | `#EEF3D0` | 50 | Fundo de cards destacados, linhas ativas, hover suave |
| `--cor-eli-primaria-zebra` | `#F6F9E8` | 30 | Linha zebrada de tabelas (quase branco esverdeado) |
| `--cor-eli-primaria-suave` | `#BFC99C` | — | **Cabeçalho de tabela** — sage/olive mudo, sem limão, texto escuro |
| `--cor-eli-primaria-clara` | `#D4E290` | 100 | Badges, chips, seleção, fundo de hover em listas |
| `--cor-eli-primaria-media` | `#ADCC44` | 200 | Tags, indicadores secundários |
| `--cor-eli-primaria-acao` | `#8AAF00` | 400 | Ação secundária, ícones ativos |
| `--cor-eli-primaria` | `#688C00` | 600 | **Botões principais, links ativos, destaques — CTA principal** |
| `--cor-eli-primaria-escura` | `#4A6500` | 800 | Hover em botões, bordas ativas, títulos com ênfase |
| `--cor-eli-primaria-texto` | `#2E3F00` | 900 | Texto escuro sobre fundos claros da paleta primária |
### Escala de apoio — Âmbar terroso
| Token | Hex | Stop | Uso |
|---|---|---|---|
| `--cor-eli-alerta-bg` | `#FAF3DF` | 50 | Fundo de banners de aviso |
| `--cor-eli-alerta-clara` | `#F5DC8A` | 100 | Badges de atenção, chips de alerta |
| `--cor-eli-alerta` | `#DDB847` | 200 | Ícones de aviso, bordas de alerta |
| `--cor-eli-alerta-forte` | `#8C6A00` | 600 | Texto sobre fundo de alerta, status pendente |
### Escala neutra — Cinza musgo
| Token | Hex | Stop | Uso |
|---|---|---|---|
| `--cor-eli-fundo` | `#F2F3EE` | 50 | Background geral de páginas |
| `--cor-eli-borda` | `#D5D8CC` | 100 | Bordas padrão de containers |
| `--cor-eli-borda-forte` | `#B5BAA8` | 200 | Bordas de foco, divisores |
| `--cor-eli-neutro` | `#5E6553` | 600 | Textos secundários, ícones inativos |
| `--cor-eli-neutro-escuro` | `#3E4436` | 800 | Texto de label, cabeçalhos de tabela |
| `--cor-eli-superficie` | `#FFFFFF` | — | Cards, modais, popovers |
### Cores semânticas
| Token | Hex | Uso |
|---|---|---|
| `--cor-eli-sucesso` | `#2e7d32` | Confirmações, status positivo |
| `--cor-eli-sucesso-bg` | `#E8F5E9` | Fundo de mensagens de sucesso |
| `--cor-eli-erro` | `#c62828` | Erros, ações destrutivas |
| `--cor-eli-erro-bg` | `#FFEBEE` | Fundo de mensagens de erro |
| `--cor-eli-info` | `#1565c0` | Informações auxiliares |
| `--cor-eli-info-bg` | `#E3F2FD` | Fundo de banners informativos |
### Regras de contraste
- Texto sobre `--cor-eli-primaria` (`#688C00`) deve ser **branco** (`#ffffff`) — contraste 4.6:1 ✓
- Texto sobre `--cor-eli-primaria-bg` (`#EEF3D0`) deve ser `--cor-eli-primaria-texto` (`#2E3F00`) — contraste 12:1 ✓
- Texto sobre `--cor-eli-primaria-escura` (`#4A6500`) deve ser **branco** (`#ffffff`) — contraste 7.1:1 ✓
- Texto sobre `--cor-eli-alerta-bg` (`#FAF3DF`) deve ser `--cor-eli-alerta-forte` (`#8C6A00`) — contraste 5.2:1 ✓
- Texto sobre `--cor-eli-primaria-suave` (`#BFC99C`) deve ser `--cor-eli-neutro-escuro` (`#3E4436`) — contraste ~12:1 ✓
- **⚠️ Efeito limão**: `--cor-eli-media` (`#ADCC44`) e `--cor-eli-acao` (`#8AAF00`) têm saturação 100% no hue amarelo-verde — **nunca usar como fundo de cabeçalho**. Para fundo verde mudo, usar `--cor-eli-primaria-suave`.
- Sempre validar contraste mínimo de **4.5:1** (WCAG AA) para texto normal e **3:1** para texto grande (18px+ ou 14px bold).
---
## Passos
### 1. Identificar o escopo da revisão
Determinar qual componente, tela ou modal será revisado. Pode ser:
- Um componente isolado (ex: `EliTabela`, `EliCartao`)
- Uma página completa (ex: `PaginaCadastro.vue`)
- Um modal ou drawer (ex: `EliTabelaModalFiltroAvancado.vue`)
- Uma interação específica (ex: fluxo de filtro, paginação, menu de ações)
### 2. Mapear o estado atual
Antes de alterar, entender o que já existe:
- Ler o template (`<template>`) para entender a estrutura visual
- Ler o CSS/SCSS associado para mapear os tokens de design em uso
- Identificar quais componentes Vuetify estão sendo utilizados (ex: `v-btn`, `v-dialog`, `v-select`)
- Verificar se existem estilos inline que deveriam migrar para classes CSS
### 3. Avaliar contra os critérios de UX
Para cada elemento da interface, avaliar:
#### Clareza
- [ ] O propósito de cada elemento é óbvio sem instrução?
- [ ] Labels e placeholders são descritivos? (ex: "Buscar por nome ou CPF" vs "Buscar")
- [ ] Ícones acompanham texto quando a ação não é universalmente reconhecível?
- [ ] O estado vazio (empty state) orienta o usuário sobre o próximo passo?
#### Hierarquia visual
- [ ] O olho do usuário é guiado para a ação principal primeiro?
- [ ] Ações primárias usam `--cor-eli-primaria` (`#688C00`) com destaque?
- [ ] Ações secundárias são visuais mas não competem com a primária?
- [ ] Ações destrutivas (Excluir, Limpar) usam `--cor-eli-erro` com variante `text` ou `outlined`?
#### Feedback e estados
- [ ] Botões têm estados claros de hover (`--cor-eli-primaria-escura`), focus e disabled (`--cor-eli-borda-forte`)?
- [ ] Carregamentos exibem indicador visual (spinner, skeleton, barra de progresso)?
- [ ] Erros de formulário aparecem próximos ao campo com mensagem descritiva, usando `--cor-eli-erro` + `--cor-eli-erro-bg`?
- [ ] Sucesso de operações tem confirmação visual (snackbar, toast, badge) com `--cor-eli-sucesso`?
#### Densidade e espaçamento
- [ ] O espaçamento segue múltiplos de 4px (4, 8, 12, 16, 24, 32)?
- [ ] Em desktop, o espaço horizontal é bem aproveitado? (ex: grids de 2+ colunas para formulários largos)
- [ ] Em mobile, os elementos empilham verticalmente sem quebra visual?
- [ ] Modais têm largura proporcional ao conteúdo?
#### Tipografia
- [ ] Tamanhos de fonte seguem a escala: 12px (caption), 14px (body), 16px (subtitle), 20px (title), 24px (heading)?
- [ ] Textos longos usam `line-height: 1.5` para legibilidade?
- [ ] Labels de formulário são visualmente distintos do conteúdo preenchido?
#### Acessibilidade básica
- [ ] Elementos interativos têm `aria-label` quando o texto visual não é suficiente?
- [ ] Foco via teclado (`Tab`) segue uma ordem lógica?
- [ ] Cores não são o único meio de comunicar estado (ex: ícone + cor para erro)?
- [ ] Todo texto sobre cor primária ou escura usa branco (`#FFFFFF`)?
- [ ] Todo texto sobre `--cor-eli-primaria-bg` usa `--cor-eli-primaria-texto` (`#2E3F00`)?
### 4. Aplicar padrões Vue/Vuetify do projeto
Ao implementar melhorias, seguir os padrões do ecossistema:
#### Componentes Vuetify
- Usar `v-btn` com variantes do tema (`color="primary"`) em vez de classes CSS manuais para botões
- Usar `v-dialog` para modais, `v-menu` para popovers contextuais
- Usar `v-text-field`, `v-select` etc. para inputs sempre que possível
- Aproveitar props de Vuetify: `density`, `variant`, `rounded`, `elevation`
#### Iconografia — Lucide (obrigatório)
Todos os ícones do projeto devem vir exclusivamente da biblioteca **`@lucide/vue`** (dependência já instalada no `package.json`).
**Proibido**:
- SVG inline manual (hardcoded no template)
- Ícones de `@mdi/font` ou Material Design Icons em componentes do projeto
- Bibliotecas alternativas (Font Awesome, Heroicons, etc.)
**Como usar**:
```vue
<script lang="ts">
import { Filter, Plus, X, Trash2, Eye } from "@lucide/vue"
</script>
<template>
<!-- Uso direto como componente -->
<Filter :size="18" :stroke-width="2" />
<!-- Dentro de botão -->
<button>
<Plus :size="15" :stroke-width="2.5" />
Adicionar
</button>
</template>
```
**Props úteis**: `:size` (número em px), `:stroke-width` (espessura do traço, padrão 2), `:color` (cor do ícone).
**Catálogo de referência**: https://lucide.dev/icons — buscar pelo nome do ícone em inglês.
> Os tokens CSS estão documentados nas tabelas da seção **Paleta de Cores Institucional** acima.
> No código, usar `var(--token, #fallback)` — sempre com fallback hardcoded em componentes de biblioteca.
- Classes devem seguir BEM: `eli-componente__elemento--modificador`
- Evitar `!important` — resolver especificidade via seletor mais específico
- Usar `var(--cor-eli-primaria)` em vez de valores hex hardcoded no CSS dos componentes
- Transições padrão: `transition: all 0.2s ease` para hover/focus
#### Composição de componentes
- Componentes filhos devem receber dados via `props` e emitir eventos via `$emit`
- Evitar acessar o DOM diretamente; preferir `ref` do Vue
- Não duplicar CSS entre componentes — extrair para classe utilitária ou CSS do componente pai
### 5. Implementar melhorias prioritárias
Ordenar as melhorias por impacto no usuário:
1. **Crítico**: elementos que causam confusão ou impedem o uso (falta de feedback, botão invisível, estado vazio sem orientação)
2. **Alto**: melhorias que reduzem atrito (espaçamento, hierarquia de botões, responsividade)
3. **Médio**: refinamentos visuais (transições, micro-animações, consistência de cores)
4. **Baixo**: polish (sombras sutis, arredondamentos, tipografia refinada)
### 6. Validar resultado
Após implementar:
- [ ] A tela renderiza sem erros no console?
- [ ] Os estados (vazio, carregando, erro, com dados) estão todos cobertos?
- [ ] A paleta de cores está coerente com a base `#688C00`?
- [ ] Todos os tokens usados estão definidos na escala primária, de apoio ou neutra?
- [ ] Nenhuma cor está hardcoded no CSS do componente (usar `var(--token, #fallback)`)?
- [ ] Tokens novos têm fallback hardcoded? (ex: `var(--cor-eli-primaria-suave, #BFC99C)`)?
- [ ] Contraste de texto validado: branco sobre `--cor-eli-primaria` e `--cor-eli-primaria-escura`; `--cor-eli-neutro-escuro` sobre `--cor-eli-primaria-suave`?
- [ ] Nenhuma ação ficou sem feedback visual?
- [ ] O layout não quebra em larguras menores que 1024px?
- [ ] Componentes Vuetify recebem props de tema (`color`, `variant`) em vez de override CSS?
- [ ] Efeito zebra de tabelas tem fundo branco explícito nas linhas normais (para funcionar sobre qualquer fundo de página)?
---
## Anti-padrões a evitar
| ❌ Anti-padrão | ✅ Alternativa |
|---|---|
| Botão sem label de texto | Botão com ícone + texto, ou `aria-label` descritivo |
| Cor vermelha para ação primária | Vermelho apenas para destrutivas; primária usa `--cor-eli-primaria` |
| Modal com scroll interno extenso | Dividir em etapas ou usar drawer lateral |
| Tabela com 15+ colunas visíveis | Usar o modal de colunas para esconder as menos usadas |
| Placeholder como único label | Label fixo acima do campo + placeholder como exemplo |
| Ações alinhadas à esquerda em linha de tabela | Ações à direita, próximas ao fim da linha visual |
| Toast/snackbar sem ação de fechar | Sempre incluir botão de fechar ou auto-dismiss com tempo suficiente (5s+) |
| Estilos inline em `<template>` | Migrar para `<style scoped>` com classe BEM |
| Cor hex hardcoded no componente | Usar `var(--cor-eli-primaria)` e demais tokens com fallback |
| Texto escuro (`#333`) sobre `--cor-eli-primaria` | Usar branco (`#FFFFFF`) para garantir contraste WCAG AA |
| Amarelo/âmbar para sucesso | Âmbar é reservado para **aviso**; sucesso usa `--cor-eli-sucesso` (`#2E7D32`) |
| Misturar stops da paleta fora dos tokens | Usar apenas os tokens definidos; nunca interpolar valores avulsos |
| Usar `--cor-eli-media` ou `--cor-eli-acao` como fundo de cabeçalho | Usar `--cor-eli-primaria-suave` (`#BFC99C`) — verde mudo sem efeito limão |
| `var(--token)` sem fallback em componente de biblioteca | Sempre declarar `var(--token, #valor)` — o projeto destino pode não ter o token atualizado |
| Zebra de tabela sem fundo branco explícito nas linhas normais | Declarar `.eli-tabela__tr .eli-tabela__td { background: var(--cor-eli-superficie, #fff) }` antes da regra zebra |