versão 1

global/workflows/aprimorar-IA.md

@@ -0,0 +1,263 @@
+---
+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.

global/workflows/documentar-regras-negocio.md

@@ -0,0 +1,105 @@
+---
+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

global/workflows/otimizar-codigos.md

@@ -0,0 +1,71 @@
+---
+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.