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-09-16 23:48:38 -03:00
commit 967f212be4
102 changed files with 3460 additions and 1939 deletions
Download patch file Download diff file Expand all files Collapse all files

2
agents/front/agent.json
View file

File diff suppressed because one or more lines are too long

26
agents/front/persona
View file

@ -45,7 +45,13 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
6. Extrair CSS para arquivos co-localizados quando necessário
7. Manter componentes dentro do limite de 250 linhas
8. Implementar fluxos de navegação e estados de interface
<<<<<<< HEAD
9. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`)** para acompanhamento do operador (ver `rules/testes-interface-agent-browser.md`)
=======
9. Criar e manter arquivo `{componente}.ajuda.md` co-localizado (para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`) sempre que houver ajuda contextual (ver `skills/adicionar-ajuda`)
10. Escrever comentários claros e coerentes quanto à aplicação prática em componentes e composables (ver `rules/jsdoc-padrao.md`)
11. Validar comportamento interativo e renderização visual de telas utilizando `agent-browser`, **sempre em modo visível (`--headed`)** para acompanhamento do operador (ver `rules/testes-interface-agent-browser.md`)
>>>>>>> master-xdd
## Restrições
@ -57,6 +63,8 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
- CSS extenso deve ser extraído para arquivo co-localizado (`.css`)
- Mensagens visíveis ao usuário devem estar em linguagem do domínio, sem jargões técnicos
- Schemas Zod importados de `*-comuns` — nunca redefinidos no front
- NUNCA usar strings literais quando existirem enums no `*-comuns` (usar obrigatoriamente os enums/zEnums da respectiva aplicação para status, filtros, tipos, categorias e opções de UI)
- Ajuda de interface deve ser **obrigatoriamente** no formato Markdown co-localizado (`modalX.ajuda.md`)
## Colaborações
@ -65,6 +73,7 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
- **Recebe diretrizes de UX de:** `@ux`
- **Entrega para validação:** `@testes`
- **Entrega build para:** `@deploy`
- **Alinha documentação com:** `@documentacao`
## Tom e Estilo
@ -81,17 +90,18 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
- [ ] Mensagens ao usuário sem termos técnicos?
- [ ] `defineComponent` com `setup()` real?
- [ ] Schemas importados de `*-comuns`?
- [ ] Filtros, selects, badges e condicionais de tela utilizam os enums/zEnums do `*-comuns` (sem magic strings)?
- [ ] Estados de loading, erro e vazio implementados?
- [ ] Modal ou tela com ajuda possui arquivo co-localizado `{componente}.ajuda.md` (ex: `modalX.ajuda.md`)?
- [ ] Comentários claros e coerentes quanto à aplicação prática inseridos no código?
- [ ] Build passa (`tsc --noEmit` + `biome check`)?
## Memória Persistente
## Memória Persistente & Identidade do Projeto
O ecossistema adota uma arquitetura de memória em duas camadas:
- **Memórias do Projeto ()**: Armazena decisões de negócio, contexto do produto, especificações funcionais e ADRs na raiz do projeto pai (versionado pelo repositório pai).
- **Evoluções da IA ()**: Armazena registros de sessões , otimizações dos agentes e melhorias da arquitetura multiagente (versionado pelo submódulo ).
O arquivo `<base_projeto>/memorias-ia/modulo.yml` é de **existência obrigatória em todos os projetos** e define a identidade do módulo (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`).
- Toda vez que precisar do ID do módulo (`modulo-id`), da rota/prefixo de URL (`modulo-caminho`), ou de informações de tipo/descrição (`modulo-tipo` / `modulo-descricao`), consulte obrigatoriamente `memorias-ia/modulo.yml`.
- Toda memória das ações, registros de sessões e decisões tomadas pela IA deve ser armazenada em `<base_projeto>/memorias-ia/` na raiz do projeto pai.
### Regras de Operação
- Gravar memórias de projeto em (na raiz do pai).
- Gravar evoluções da IA em (no submódulo).
- Toda memória deve ser um arquivo Markdown em com frontmatter (, , , , ).
- Gravar registros de ações, sessões e decisões da IA em `<base_projeto>/memorias-ia/`.
- Toda memória deve ser um arquivo Markdown com frontmatter (`type`, `name`, `description`, `session_date`, `updatedAt`).

155
agents/front/workflows/adicionar-ajuda.md
View file

@ -1,118 +1,109 @@
---
type: workflow
name: adicionar-ajuda
description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend)
scope: local
updatedAt: "2026-06-01"
description: Adicionar ou atualizar botão de ajuda e documentação contextual em telas e modais (Frontend)
scope: global
updatedAt: "2026-09-01"
---
# Workflow: Adicionar Ajuda em Telas
# Skill / Workflow: Adicionar Ajuda Contextual em Telas e Modais
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.
Este guia estabelece o padrão para criação e manutenção de arquivos de **ajuda contextual ao usuário** exibidos diretamente na interface da aplicação.
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.
O objetivo da ajuda em tela é **auxiliar o usuário final a compreender e operar a interface de forma autônoma**, explicando o funcionamento da tela/modal de forma clara, amigável 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.
## 1. Padrão Canônico de Nomenclatura e Co-Localização
## 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:
Sempre que uma tela ou modal possuir ajuda contextual, o arquivo Markdown de documentação **DEVE** ser co-localizado com o componente na mesma pasta, adotando o sufixo `.ajuda.md`:
```
TelaCadastroUsuario.tsx
TelaCadastroUsuario.ajuda.md
modalExportarPdf.vue → modalExportarPdf.ajuda.md
modalParametros.vue → modalParametros.ajuda.md
telaCadastroPonto.vue → telaCadastroPonto.ajuda.md
```
ou
> ⚠️ **Regra Estrita**: Para qualquer componente `modalX.vue`, o arquivo de ajuda contextual correspondente é obrigatoriamente `modalX.ajuda.md`.
```
---
TelaCadastroUsuario.vue
TelaCadastroUsuario.ajuda.md
## 2. Conteúdo Obrigatório do `.ajuda.md`
````
O conteúdo deve ser redigido **exclusivamente na linguagem do usuário e do domínio**, sem termos técnicos de desenvolvimento (como props, emits, SQL, endpoints, etc.).
### 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:
Estrutura recomendada:
```markdown
# Ajuda: [Nome da Tela]
# Ajuda: [Nome da Tela / Modal]
## Objetivo da Tela
## Objetivo
Explique resumidamente para que serve esta tela ou modal dentro do fluxo de trabalho do usuário.
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.
## Botões e Ações Principais
- **[Nome do Botão]**: O que acontece ao clicar (ex: *Salvar — grava as leituras informadas no sistema*).
- **[Nome do Botão]**: Ação de cancelamento ou descarte.
## Campos do Formulário
- **[Nome do Campo]**: Explicação do dado esperado, formato e obrigatoriedade.
- **[Nome do Campo]**: Regra de preenchimento ou limites aplicáveis.
- **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 Passo a Passo
1. Passo inicial do usuário.
2. Preenchimento e conferência.
3. Conclusão da ação.
## Fluxo de Uso
## Regras de Validação e Normas (quando aplicável)
Explique prazos, limites legais ou critérios ambientais relevantes para a operação.
```
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)
## 3. Posicionamento do Botão de Ajuda na UI
Explique regras técnicas, normas ou exigências legais relacionadas à funcionalidade da tela.
````
O botão de ajuda (ex: `BotaoAjuda`, ícone `HelpCircle` ou `v-icon`) deve ser posicionado de maneira consistente:
### 4. Posicionamento do Botão de Ajuda
### Em Modais (`modalX.vue`)
- Posicionado na **parte inferior esquerda** do modal (no footer / rodapé de ações).
- Nunca sobrepor botões principais de ação (como Salvar, Fechar, Excluir).
- Espaçamento adequado (`margin` / `padding`) garantindo contraste e acessibilidade.
O botão deve ser inserido de forma consistente e não pode interferir na interface da aplicação.
### Em Páginas / Telas (`telaX.vue`)
- Posicionado na **parte inferior esquerda** da página ou no cabeçalho ao lado do título da tela.
- Não sobrepor barras de navegação nem componentes flutuantes.
#### 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.
## 4. Integração Técnica no Vue 3
#### Modais e Diálogos
O componente de ajuda carrega dinamicamente o arquivo `.ajuda.md` co-localizado (via import raw `?raw` ou serviço de documentação local) e o renderiza em diálogo limpo:
* 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.
```vue
<!-- Exemplo no template do modal -->
<template>
<v-card>
<v-card-title>Configurar Parâmetros</v-card-title>
<v-card-text>...</v-card-text>
<v-card-actions class="d-flex justify-space-between">
<BotaoAjuda :conteudo-md="conteudoAjuda" />
<div>
<v-btn variant="text" @click="fechar">Cancelar</v-btn>
<v-btn color="primary" @click="salvar">Salvar</v-btn>
</div>
</v-card-actions>
</v-card>
</template>
<script setup lang="ts">
import conteudoAjuda from "./modalParametros.ajuda.md?raw"
</script>
```
---
## Checklist de Validação
- [ ] Arquivo nomeado exatamente como `modalX.ajuda.md` para `modalX.vue`?
- [ ] Arquivo co-localizado na mesma pasta do componente?
- [ ] Texto em português claro, sem jargões de TI?
- [ ] Botões, campos e fluxo passo a passo documentados?
- [ ] Botão de ajuda posicionado no canto inferior esquerdo sem sobrepor outros elementos?