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

aplimoramento de agent

Browse source
This commit is contained in:
Luiz Silva 2026-09-02 10:23:53 -03:00
parent b361f25955
commit f597436be3
83 changed files with 1312 additions and 574 deletions
Download patch file Download diff file Expand all files Collapse all files

7
global/rules/autonomia-agente.md
View file

@ -18,10 +18,12 @@ O agente existe para **ampliar a capacidade humana**, não para substituir decis
O agente pode executar sem perguntar:
- Consultar `memorias-ia/modulo.yml` para obter identificador (`modulo-id`), rotas (`modulo-caminho`), descrição (`modulo-descricao`) e tipo (`modulo-tipo`)
- Criar `memorias-ia/modulo.yml` a partir do template quando inexistente em novo projeto
- Corrigir erros de tipagem em arquivos que já está modificando
- Aplicar formatação (`biome check --write`)
- Atualizar referências quebradas entre artefatos
- Criar ou atualizar documentação de regras de negócio em `../../wiki/dev/<modulo>/`
- Criar ou atualizar documentação de regras de negócio em `<base_projeto>/../wiki/dev/<modulo-id>/`
- Gerar JSDoc em funções compartilhadas
- Extrair CSS para arquivo co-localizado
- Aplicar padrões de nomenclatura já definidos em rules
@ -42,7 +44,8 @@ O agente deve **propor e aguardar aprovação**:
O agente **nunca** deve:
- Deletar memória/ADRs sem instrução explícita do operador
- Deletar ou corromper `memorias-ia/modulo.yml` ou memórias/ADRs sem instrução explícita do operador
- Assumir ou inventar IDs de módulos ou rotas sem consultar `memorias-ia/modulo.yml`
- Alterar artefatos globais (sufixo `.global`) sem justificativa
- Inventar regras de negócio não documentadas
- Assumir comportamento de API sem verificar o código-fonte

31
global/rules/ddd-documentacao-primeiro.md
View file

@ -26,20 +26,21 @@ Todo desenvolvimento e manutenção no ecossistema deve obrigatoriamente respeit
| :--- | :--- | :--- | :--- |
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | Comentários claros e coerentes quanto à sua aplicação prática, contexto e raciocínio de negócio (JSDoc no topo de funções, serviços e rotas). |
| **2. Ajuda na Tela (UI)** | `*-front/src/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue`, o arquivo de ajuda **DEVE** ser `modalX.ajuda.md`. Detalha objetivo, botões, campos e instruções de uso. |
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo-id>/` | Usuários / Operadores | Aplicação VitePress com acesso dos usuários. Manuais de operação completos, tutoriais de uso, conceitos de negócio e fluxos da aplicação. |
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo-id>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno exclusivo da equipe de desenvolvimento. Arquitetura técnica detalhada, modelos de banco, regras de negócio (`{modulo}.regras-negocio.md`), fluxos de filas (BullMQ), CRONs e ADRs. |
| **5. Integração de IA** | Rota de Backend `/llm.md` | Agentes de IA / LLMs | Documentação gerada/servida dinamicamente contendo schemas Zod, enums canônicos, endpoints e contratos para consumo por LLMs. |
| **6. Memória das Ações da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões da IA, otimizações executadas, histórico de decisões arquiteturais e relatórios de aprimoramento contínuo. |
| **6. Memória das Ações da IA e Identidade** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Arquivo mandatório `modulo.yml` (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`), registros de sessões, histórico de decisões e relatórios de aprimoramento. |
> ℹ️ **Estrutura da Wiki VitePress (`../../wiki`)**:
> - `../../wiki/<modulo>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes**.
> - `../../wiki/dev/<modulo>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
> ℹ️ **Estrutura da Wiki VitePress (`<base_projeto>/../wiki`)**:
> - `<base_projeto>/../wiki/<modulo-id>/` $\rightarrow$ Aplicação VitePress voltada ao **acesso dos usuários e clientes** (onde `<modulo-id>` é o ID do módulo em `memorias-ia/modulo.yml`).
> - `<base_projeto>/../wiki/dev/<modulo-id>/` $\rightarrow$ Seção VitePress de **acesso interno da equipe de desenvolvimento e arquitetura**.
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização de cada projeto reside em:
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
> - `../../wiki/<modulo>/`: Documentação do módulo com acesso dos usuários (VitePress).
> - `../../wiki/dev/<modulo>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
> 🧩 **Polimorfismo do `.agent` e Identidade do Projeto**:
> O repositório `.agent` é **polimórfico e genérico**, sendo compartilhado entre múltiplos projetos do ecossistema. Toda personalização e identidade de cada projeto reside em:
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): **Identificador mandatório** (`modulo-id`, `modulo-caminho`, `modulo-descricao`, `modulo-tipo`). Sempre consultado quando precisar de IDs, rotas base ou stack.
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação do módulo com acesso dos usuários (VitePress).
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica do módulo com acesso interno dev (VitePress).
---
@ -50,8 +51,8 @@ Para toda nova demanda, módulo ou funcionalidade, execute os passos abaixo:
1. **Identificar os Pilares Impactados**:
- É alteração de código? $\rightarrow$ Planejar comentários contextuais claros (Pilar 1).
- É tela/modal com ajuda ao usuário? $\rightarrow$ Criar/atualizar `modalX.ajuda.md` co-localizado (Pilar 2).
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `../../wiki/<modulo>/` (Pilar 3).
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `../../wiki/dev/<modulo>/` (Pilar 4).
- É funcionalidade com impacto no usuário final? $\rightarrow$ Criar/atualizar documentação em `<base_projeto>/../wiki/<modulo>/` (Pilar 3).
- É componente técnico, arquitetura, serviço ou fila? $\rightarrow$ Criar/atualizar documentação em `<base_projeto>/../wiki/dev/<modulo>/` (Pilar 4).
- É endpoint, schema ou contrato de API? $\rightarrow$ Assegurar reflexão na rota `/llm.md` (Pilar 5).
- É ação estruturante ou otimização de IA? $\rightarrow$ Registrar memória em `<base_projeto>/memorias-ia/` (Pilar 6).
@ -82,14 +83,14 @@ A etapa de documentação prévia pode ser simplificada apenas para:
✅ **Correto**:
- Criou um novo modal `ModalParametros.vue` $\rightarrow$ criou `ModalParametros.ajuda.md` na mesma pasta explicando campos e botões para o usuário.
- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `../../wiki/dev/e-licencie.sigma/` e o guia de uso em `../../wiki/e-licencie.sigma/`.
- Criou um serviço de cálculo de efluentes $\rightarrow$ inseriu JSDoc claro quanto à sua aplicação prática, documentou a regra técnica em `<base_projeto>/../wiki/dev/e-licencie.sigma/` e o guia de uso em `<base_projeto>/../wiki/e-licencie.sigma/`.
- Criou endpoints novos no backend $\rightarrow$ rota `/llm.md` atualizada automaticamente via gerador de contratos.
- Realizou otimização no ecossistema de agentes $\rightarrow$ registrou relatório em `<base_projeto>/memorias-ia/`.
❌ **Incorreto**:
- Criou `modalX.vue` e colocou ajuda em formato desconhecido ou fora da pasta do componente.
- Implementou código sem comentários ou com JSDoc que apenas repete os tipos sem explicar a aplicação real no sistema.
- Criou regras técnicas complexas sem atualizar `../../wiki/dev/<modulo>/`.
- Criou regras técnicas complexas sem atualizar `<base_projeto>/../wiki/dev/<modulo>/`.
- Gravou registros de ações da IA em pastas despadronizadas fora de `<base_projeto>/memorias-ia/`.
---

77
global/rules/identidade-modulo.md Normal file
View file

@ -0,0 +1,77 @@
---
type: rule
name: identidade-modulo
description: Identificação obrigatória do projeto/módulo via memorias-ia/modulo.yml (modulo-id, modulo-caminho, modulo-descricao, modulo-tipo).
scope: global
trigger: always_on
priority: critica
updatedAt: "2026-09-02"
---
# Regra: Identidade do Projeto via `memorias-ia/modulo.yml`
## Contexto
O framework `.agent` é polimórfico e genérico, sendo compartilhado como submódulo Git entre múltiplos projetos do ecossistema. Para que qualquer agente saiba com precisão e sem ambiguidades qual é o projeto hospedeiro, seu identificador canônico, suas rotas de URL, sua descrição e sua stack técnica, a identidade do módulo é centralizada em um arquivo padronizado.
---
## Regra de Existência Obrigatória
Todo projeto que utiliza o `.agent` **DEVE conter obrigatoriamente** na raiz do projeto pai o arquivo:
```
<base_projeto>/memorias-ia/modulo.yml
```
Caso o arquivo não exista ou esteja incompleto ao iniciar uma interação em um novo projeto, a prioridade máxima do agente é diagnosticá-lo e criá-lo/solicitá-lo com base no template antes de executar qualquer implementação.
---
## Estrutura Canônica de `memorias-ia/modulo.yml`
O arquivo deve conter estritamente as 4 chaves abaixo:
```yaml
modulo-id: <identificador-do-modulo>
modulo-caminho: <rota-na-url>
modulo-descricao: <texto-descritivo>
modulo-tipo: <texto-tipo-arquitetura>
```
### Definição dos Campos
| Campo | Tipo | Descrição | Exemplo |
| :--- | :--- | :--- | :--- |
| **`modulo-id`** | `string` | Identificador único do módulo no ecossistema. Utilizado para compor nomes de pacotes, pastas de wiki e referências de regras de negócio. | `e-licencie.sigma` |
| **`modulo-caminho`** | `string` | Rota / prefixo utilizado na URL e navegação do módulo (base route para front, proxy e endpoints). | `/sigma/` |
| **`modulo-descricao`** | `string` | Descrição textual do propósito funcional e escopo de negócio do módulo. | `Módulo para gestão de monitoramentos ambientais` |
| **`modulo-tipo`** | `string` | Descrição textual da arquitetura e tecnologias empregadas no módulo. | `aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres` |
---
## Regra Universal de Consulta
Sempre que qualquer agente, persona, workflow ou skill necessitar de:
1. **Nome ou ID do módulo (`modulo-id`)**: para criar ou referenciar documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`), Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`), regras de negócio (`{modulo}.regras-negocio.md`), ADRs (`<base_projeto>/../wiki/dev/<modulo-id>/adrs/`) ou relatórios;
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
---
## Proibições
- **NUNCA** assumir, deduzir ou "chutar" o ID ou a rota do módulo via heurísticas incertas quando o arquivo existir.
- **NUNCA** codificar IDs ou rotas de módulos hardcoded em regras e artefatos globais do `.agent`.
- **NUNCA** deletar ou corromper o arquivo `memorias-ia/modulo.yml`.
---
## Referências
- Rule: `global/rules/ddd-documentacao-primeiro.md`
- Rule: `global/rules/regras-negocio-md.md`
- Template: `.agent/DOCUMENTACAO/templates/modulo.yml.template`
- Hub: `.agent/DOCUMENTACAO/README`

20
global/rules/regras-negocio-md.md
View file

@ -1,21 +1,23 @@
---
type: rule
name: regras-negocio-md
description: O conteúdo de regras de negócio deve ficar em ../../wiki/dev/<modulo>/.
description: O conteúdo de regras de negócio deve ficar em <base_projeto>/../wiki/dev/<modulo>/.
scope: global
trigger: always_on
updatedAt: "2026-09-01"
---
# Regra: Conteúdo de Regras de Negócio em `../../wiki/dev/<modulo>/`
# Regra: Conteúdo de Regras de Negócio em `<base_projeto>/../wiki/dev/<modulo>/`
> **Escopo global** — aplica-se a todos os projetos do ecossistema Azteca.
## Contexto
Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
Toda lógica de negócio não-trivial — regras de decisão, critérios de bloqueio, estratégias de processamento, priorizações e fluxos de dados — deve ter seu conteúdo documentado em linguagem natural na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
> 💡 **Aplicação VitePress (`../../wiki`)**: O diretório `../../wiki` é uma aplicação VitePress na qual `../../wiki/<modulo>/` é voltado ao acesso dos **usuários**, e `../../wiki/dev/<modulo>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
> 💡 **Aplicação VitePress (`<base_projeto>/../wiki`) e Resolução do Módulo**:
> - O diretório `<base_projeto>/../wiki` é uma aplicação VitePress na qual `<base_projeto>/../wiki/<modulo-id>/` é voltado ao acesso dos **usuários**, e `<base_projeto>/../wiki/dev/<modulo-id>/` é reservado ao **acesso interno exclusivo da equipe de desenvolvimento**.
> - O identificador `<modulo-id>` (ou `<modulo>`) **DEVE** ser obtido obrigatoriamente do campo `modulo-id` em `memorias-ia/modulo.yml` na raiz do projeto (ex: `e-licencie.sigma`).
Isso garante centralização, governança técnica e facilidade de consulta por desenvolvedores, arquitetos e agentes de IA.
@ -23,7 +25,7 @@ Isso garante centralização, governança técnica e facilidade de consulta por
## Regra
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `../../wiki/dev/<modulo>/`.**
**Todo o conteúdo detalhado de regras de negócio DEVE ficar em `<base_projeto>/../wiki/dev/<modulo>/`.**
Considera-se lógica não-trivial qualquer módulo que:
- Possui 3 ou mais critérios de decisão distintos
@ -35,7 +37,7 @@ Considera-se lógica não-trivial qualquer módulo que:
O módulo TypeScript deve conter, na primeira linha útil do arquivo, a referência:
```typescript
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
```
A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógica operacional**. Os comentários JSDoc no código explicam a aplicação prática da função e apontam para a wiki para o detalhamento dos critérios.
@ -44,7 +46,7 @@ A documentação na **Wiki de Desenvolvimento** é a **fonte de verdade da lógi
## Estrutura do Documento de Regras na Wiki de Desenvolvimento
**Localização:** `../../wiki/dev/<modulo>/` (ex.: `../../wiki/dev/e-licencie.sigma/regras-negocio/` ou `../../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
**Localização:** `<base_projeto>/../wiki/dev/<modulo>/` (ex.: `<base_projeto>/../wiki/dev/e-licencie.sigma/regras-negocio/` ou `<base_projeto>/../wiki/dev/e-licencie.sigma/{modulo}.regras-negocio.md`)
```markdown
# Regras de Negócio — [Nome do Módulo / Serviço]
@ -79,7 +81,7 @@ Tabelas, filas BullMQ, rotas e serviços externos tocados pelo módulo.
✅ **Correto** — referência no topo do módulo apontando para a Wiki de Desenvolvimento:
```typescript
// Regras de negócio: ver ../../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
// Regras de negócio: ver <base_projeto>/../wiki/dev/e-licencie.sigma/juntar_execucoes.regras-negocio.md
import { ... } from "..."
@ -117,4 +119,4 @@ export const compilarJuntarExecucoes = async (...) => {
- Rule: `rules/jsdoc-padrao.md`
- Skill: `skills/documentar-regras-negocio/SKILL.md`
- Workflow: `global/workflows/documentar-regras-negocio.md`
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/`
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo>/`

4
global/skills/doc/SKILL.md
View file

@ -13,8 +13,8 @@ Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pila
- `1. Código-Fonte` $\rightarrow$ JSDoc de aplicação prática (`rules/jsdoc-padrao.md`)
- `2. Ajuda UI` $\rightarrow$ `modalX.ajuda.md` co-localizado com `modalX.vue`
- `3. Wiki Usuário` $\rightarrow$ `../../wiki/<modulo>/` (VitePress com acesso dos usuários)
- `4. Wiki Dev` $\rightarrow$ `../../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
- `3. Wiki Usuário` $\rightarrow$ `<base_projeto>/../wiki/<modulo>/` (VitePress com acesso dos usuários)
- `4. Wiki Dev` $\rightarrow$ `<base_projeto>/../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
- `5. Rota IA` $\rightarrow$ Rota do backend `/llm.md`
- `6. Memória IA` $\rightarrow$ `<base_projeto>/memorias-ia/`

10
global/skills/documentacao/SKILL.md
View file

@ -17,8 +17,8 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
1. **Pilar 1 (Código-Fonte):** Insere comentários JSDoc de aplicação prática nos arquivos alterados (`rules/jsdoc-padrao.md`).
2. **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `../../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `../../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
3. **Pilar 3 (Wiki do Usuário):** Atualiza tutoriais e manuais em `<base_projeto>/../wiki/<modulo>/` (aplicação VitePress com acesso dos usuários).
4. **Pilar 4 (Wiki de Desenvolvimento):** Documenta regras de negócio (`{modulo}.regras-negocio.md`), modelos e ADRs em `<base_projeto>/../wiki/dev/<modulo>/` (aplicação VitePress com acesso interno dev).
5. **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
6. **Pilar 6 (Memória IA):** Registra o relatório completo da sessão em `<base_projeto>/memorias-ia/`.
@ -30,8 +30,8 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
| :--- | :--- | :--- | :--- |
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | Desenvolvedores / IA | JSDoc e comentários claros quanto à aplicação prática e contexto de negócio. |
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Usuários da UI | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo>/` | Usuários / Clientes | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo>/` | Desenvolvedores / Arquitetos | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), arquitetura e ADRs (`adrs/`). |
| **5. Integração de IA** | Rota Backend `/llm.md` | Agentes de IA / LLMs | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | Agentes de IA / Auditoria | Registros de sessões, otimizações executadas e decisões históricas. |
@ -66,4 +66,4 @@ Esta skill aciona o **Agente de Documentação & Memória** para gerar, atualiza
1. **Nunca inventar regras:** Documentar estritamente o que foi implementado no código ou declarado na conversa.
2. **Linguagem acessível no usuário:** Sem termos técnicos de TI na Wiki do Usuário ou em `.ajuda.md`.
3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos.
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `../../wiki/`.
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.

10
global/skills/documentar-decisao-tecnica/SKILL
View file

@ -3,7 +3,7 @@ name: documentar-decisao-tecnica
scope: global
updatedAt: "2026-09-01"
description: >
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/adrs/).
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo>/adrs/).
---
# Skill: Documentar Decisão Técnica (ADR)
@ -28,10 +28,10 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi
## PASSO 1 — Localizar o Diretório de ADRs
Convenção de diretório: `../../wiki/dev/<modulo>/adrs/` (na Wiki de Desenvolvimento) ou `.agent/DOCUMENTACAO/arquitetura/`.
Convenção de diretório: `<base_projeto>/../wiki/dev/<modulo>/adrs/` (na Wiki de Desenvolvimento) ou `.agent/DOCUMENTACAO/arquitetura/`.
```bash
mkdir -p ../../wiki/dev/<modulo>/adrs
mkdir -p <base_projeto>/../wiki/dev/<modulo>/adrs
```
---
@ -152,7 +152,7 @@ Antes de considerar completo:
- [ ] As consequências (positivas e negativas) estão claras?
- [ ] Os pacotes impactados estão listados?
- [ ] O status está definido (proposto/aceito)?
- [ ] O ADR foi salvo em `../../wiki/dev/<modulo>/adrs/` ou `.agent/DOCUMENTACAO/arquitetura/`?
- [ ] O ADR foi salvo em `<base_projeto>/../wiki/dev/<modulo>/adrs/` ou `.agent/DOCUMENTACAO/arquitetura/`?
- [ ] A decisão foi registrada na memória em `<base_projeto>/memorias-ia/`?
- [ ] Alguém de fora do contexto entenderia este ADR?
@ -162,4 +162,4 @@ Antes de considerar completo:
- Rule: `rules/ddd-documentacao-primeiro.md`
- Workflow: `global/workflows/aprimora-ia.md`
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/adrs/`
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo>/adrs/`

13
global/skills/documentar-decisao-tecnica/SKILL.md
View file

@ -3,7 +3,7 @@ name: documentar-decisao-tecnica
scope: global
updatedAt: "2026-09-01"
description: >
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/adrs/).
Guia operacional para registrar decisões técnicas e arquiteturais como ADRs (Architecture Decision Records) na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/adrs/).
---
# Skill: Documentar Decisão Técnica (ADR)
@ -26,12 +26,13 @@ O objetivo é garantir que **nenhuma decisão fique apenas na cabeça** ou perdi
---
## PASSO 1 — Localizar o Diretório de ADRs
## PASSO 1 — Obter Identidade do Módulo e Localizar o Diretório de ADRs
Convenção de diretório: `../../wiki/dev/<modulo>/adrs/` (na Wiki de Desenvolvimento) ou `.agent/DOCUMENTACAO/arquitetura/`.
1. Ler `modulo-id` em `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
2. Convenção de diretório: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/` (na Wiki de Desenvolvimento).
```bash
mkdir -p ../../wiki/dev/<modulo>/adrs
mkdir -p <base_projeto>/../wiki/dev/<modulo-id>/adrs
```
---
@ -152,7 +153,7 @@ Antes de considerar completo:
- [ ] As consequências (positivas e negativas) estão claras?
- [ ] Os pacotes impactados estão listados?
- [ ] O status está definido (proposto/aceito)?
- [ ] O ADR foi salvo em `../../wiki/dev/<modulo>/adrs/` ou `.agent/DOCUMENTACAO/arquitetura/`?
- [ ] O ADR foi salvo em `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`?
- [ ] A decisão foi registrada na memória em `<base_projeto>/memorias-ia/`?
- [ ] Alguém de fora do contexto entenderia este ADR?
@ -162,4 +163,4 @@ Antes de considerar completo:
- Rule: `rules/ddd-documentacao-primeiro.md`
- Workflow: `global/workflows/aprimora-ia.md`
- Wiki de Desenvolvimento: `../../wiki/dev/<modulo>/adrs/`
- Wiki de Desenvolvimento: `<base_projeto>/../wiki/dev/<modulo-id>/adrs/`

24
global/skills/documentar-dominio-modulo/SKILL
View file

@ -4,16 +4,16 @@ scope: global
updatedAt: "2026-09-01"
description: >
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
de usuário (../../wiki/<modulo>/) e de desenvolvimento (../../wiki/dev/<modulo>/).
de usuário (<base_projeto>/../wiki/<modulo>/) e de desenvolvimento (<base_projeto>/../wiki/dev/<modulo>/).
---
# Skill: Documentar Domínio de um Módulo
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `../../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
1. **Wiki do Usuário (`../../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
2. **Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `<base_projeto>/../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
1. **Wiki do Usuário (`<base_projeto>/../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
2. **Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
---
@ -23,14 +23,14 @@ Determinar qual área da ciência/gestão o módulo aborda:
| Exemplo de módulo | Domínio | Destino Usuário | Destino Dev |
|---|---|---|---|
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `../../wiki/e-licencie.sigma/` | `../../wiki/dev/e-licencie.sigma/` |
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `../../wiki/e-licencie/` | `../../wiki/dev/e-licencie/` |
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `../../wiki/e-licencie.residuos/` | `../../wiki/dev/e-licencie.residuos/` |
| Qualificação | Qualificação e conformidade de fornecedores | `../../wiki/e-licencie.qualifica/` | `../../wiki/dev/e-licencie.qualifica/` |
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `<base_projeto>/../wiki/e-licencie.sigma/` | `<base_projeto>/../wiki/dev/e-licencie.sigma/` |
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `<base_projeto>/../wiki/e-licencie/` | `<base_projeto>/../wiki/dev/e-licencie/` |
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `<base_projeto>/../wiki/e-licencie.residuos/` | `<base_projeto>/../wiki/dev/e-licencie.residuos/` |
| Qualificação | Qualificação e conformidade de fornecedores | `<base_projeto>/../wiki/e-licencie.qualifica/` | `<base_projeto>/../wiki/dev/e-licencie.qualifica/` |
---
## PASSO 2 — Criar Documentação na Wiki do Usuário (`../../wiki/<modulo>/`)
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo>/`)
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
@ -54,7 +54,7 @@ Breve descrição do propósito do módulo para o gestor e operador.
---
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`)
Estruturar a especificação técnica, modelos de banco e arquitetura:
@ -85,8 +85,8 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
## Checklist Final
- [ ] Documentação de usuário criada/atualizada em `../../wiki/<modulo>/`?
- [ ] Documentação técnica criada/atualizada em `../../wiki/dev/<modulo>/`?
- [ ] Documentação de usuário criada/atualizada em `<base_projeto>/../wiki/<modulo>/`?
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../wiki/dev/<modulo>/`?
- [ ] Glossário com os termos centrais do domínio documentado?
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
- [ ] Rota `/llm.md` no backend reflete o módulo?

33
global/skills/documentar-dominio-modulo/SKILL.md
View file

@ -4,33 +4,34 @@ scope: global
updatedAt: "2026-09-01"
description: >
Guia para documentar o domínio científico/técnico de cada módulo nas wikis
de usuário (../../wiki/<modulo>/) e de desenvolvimento (../../wiki/dev/<modulo>/).
de usuário (<base_projeto>/../wiki/<modulo-id>/) e de desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/).
---
# Skill: Documentar Domínio de um Módulo
Use esta skill ao iniciar um novo módulo SaaS ou ao perceber que o agente não conhece o vocabulário e as regras do domínio que o módulo aborda.
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `../../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
1. **Wiki do Usuário (`../../wiki/<modulo>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
2. **Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
Cada módulo opera em uma disciplina diferente da ciência/gestão ambiental (licenciamento, efluentes, bombeamento, resíduos, projetos, etc.). O repositório `<base_projeto>/../wiki` é uma **aplicação VitePress**, onde a base factual do domínio é estruturada em dois níveis de acesso:
1. **Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`):** Aplicação VitePress com **acesso dos usuários e clientes** (linguagem funcional, conceitos, glossário, fluxos e manuais operacionais).
2. **Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo-id>/`):** Aplicação VitePress com **acesso interno exclusivo da equipe de desenvolvimento e arquitetura** (arquitetura técnica, diagramas, modelos de banco, regras de negócio e ADRs).
---
## PASSO 1 — Identificar o Domínio do Módulo
## PASSO 1 — Identificar a Identidade e Domínio do Módulo via `memorias-ia/modulo.yml`
Determinar qual área da ciência/gestão o módulo aborda:
Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` na raiz do projeto pai:
- `modulo-id`: identificador do módulo (ex: `e-licencie.sigma`)
- `modulo-caminho`: rota base na URL (ex: `/sigma/`)
- `modulo-descricao`: escopo funcional e propósito do módulo
- `modulo-tipo`: stack tecnológica e arquitetura
| Exemplo de módulo | Domínio | Destino Usuário | Destino Dev |
|---|---|---|---|
| SIGMA | Monitoramento ambiental (efluentes, piezometria, bombeamento) | `../../wiki/e-licencie.sigma/` | `../../wiki/dev/e-licencie.sigma/` |
| Licenciamento | Gestão de licenças (LP, LI, LO, condicionantes) | `../../wiki/e-licencie/` | `../../wiki/dev/e-licencie/` |
| Resíduos | Gestão de resíduos sólidos (PGRS, MTR, MTR-e) | `../../wiki/e-licencie.residuos/` | `../../wiki/dev/e-licencie.residuos/` |
| Qualificação | Qualificação e conformidade de fornecedores | `../../wiki/e-licencie.qualifica/` | `../../wiki/dev/e-licencie.qualifica/` |
Os destinos canônicos da documentação na aplicação VitePress (`<base_projeto>/../wiki`) são:
- **Wiki do Usuário:** `<base_projeto>/../wiki/<modulo-id>/`
- **Wiki de Desenvolvimento:** `<base_projeto>/../wiki/dev/<modulo-id>/`
---
## PASSO 2 — Criar Documentação na Wiki do Usuário (`../../wiki/<modulo>/`)
## PASSO 2 — Criar Documentação na Wiki do Usuário (`<base_projeto>/../wiki/<modulo-id>/`)
Estruturar o guia do usuário e conceitos de negócio em linguagem clara e acessível:
@ -54,7 +55,7 @@ Breve descrição do propósito do módulo para o gestor e operador.
---
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
## PASSO 3 — Criar Documentação na Wiki de Desenvolvimento (`<base_projeto>/../wiki/dev/<modulo>/`)
Estruturar a especificação técnica, modelos de banco e arquitetura:
@ -85,8 +86,8 @@ Estruturar a especificação técnica, modelos de banco e arquitetura:
## Checklist Final
- [ ] Documentação de usuário criada/atualizada em `../../wiki/<modulo>/`?
- [ ] Documentação técnica criada/atualizada em `../../wiki/dev/<modulo>/`?
- [ ] Documentação de usuário criada/atualizada em `<base_projeto>/../wiki/<modulo>/`?
- [ ] Documentação técnica criada/atualizada em `<base_projeto>/../wiki/dev/<modulo>/`?
- [ ] Glossário com os termos centrais do domínio documentado?
- [ ] Regras e entidades técnicas alinhadas com os schemas Zod do `*-comuns`?
- [ ] Rota `/llm.md` no backend reflete o módulo?

14
global/skills/documentar-regras-negocio/SKILL
View file

@ -1,13 +1,13 @@
---
name: documentar-regras-negocio
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
scope: global
updatedAt: "2026-09-01"
---
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
---
@ -28,7 +28,7 @@ Identificar e anotar:
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
```bash
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
ls <base_projeto>/../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
```
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
@ -38,7 +38,7 @@ ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
**Localização:** `<base_projeto>/../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo>/regras-negocio/`).
Preencher com a estrutura padrão:
- Contexto operacional
@ -55,7 +55,7 @@ Preencher com a estrutura padrão:
Garantir que a primeira linha útil do arquivo TypeScript seja:
```typescript
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
```
Se já existia e está correto → sem mudança necessária.
@ -100,6 +100,6 @@ Zero erros = concluído.
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
- Criar ou atualizar ADR em `../../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
- Criar ou atualizar ADR em `<base_projeto>/../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.

22
global/skills/documentar-regras-negocio/SKILL.md
View file

@ -1,20 +1,20 @@
---
name: documentar-regras-negocio
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
scope: global
updatedAt: "2026-09-01"
updatedAt: "2026-09-02"
---
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo-id>/`.
---
[1] Ler o módulo TypeScript completamente
Identificar e anotar:
[1] Obter a identidade do módulo e ler o código TypeScript
1. Ler `modulo-id` em `<base_projeto>/memorias-ia/modulo.yml` (ex: `e-licencie.sigma`).
2. Identificar e anotar no código:
- Nome do arquivo e localização exata no código
- Funções exportadas e suas responsabilidades
- Todos os `if` que representam critérios de decisão
@ -28,7 +28,7 @@ Identificar e anotar:
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
```bash
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
ls <base_projeto>/../wiki/dev/<modulo-id>/*regras-negocio*.md 2>/dev/null
```
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
@ -38,7 +38,7 @@ ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
**Localização:** `<base_projeto>/../wiki/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo-id>/regras-negocio/`).
Preencher com a estrutura padrão:
- Contexto operacional
@ -55,7 +55,7 @@ Preencher com a estrutura padrão:
Garantir que a primeira linha útil do arquivo TypeScript seja:
```typescript
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
```
Se já existia e está correto → sem mudança necessária.
@ -100,6 +100,6 @@ Zero erros = concluído.
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
- Criar ou atualizar ADR em `../../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
- Criar ou atualizar ADR em `<base_projeto>/../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.

11
global/skills/mapear-codigo-fonte/SKILL.md
View file

@ -12,9 +12,15 @@ Use esta skill ao iniciar trabalho em um monorepo desconhecido, ao onboardar em
---
## PASSO 1 — Identificar a Raiz e o Gerenciador de Pacotes
## PASSO 1 — Identificar a Identidade do Módulo e o Gerenciador de Pacotes
Localize os arquivos que definem a estratégia de monorepo:
1. Consultar obrigatoriamente `<base_projeto>/memorias-ia/modulo.yml` para obter:
- `modulo-id`: identificador canônico do módulo
- `modulo-caminho`: rota/prefixo de URL base
- `modulo-descricao`: escopo funcional e propósito de negócio
- `modulo-tipo`: arquitetura e stack técnica
2. Localize os arquivos que definem a estratégia de monorepo:
```bash
# Identificar o gerenciador e workspace config
@ -23,6 +29,7 @@ ls -la package.json pnpm-workspace.yaml lerna.json turbo.json nx.json tsconfig.b
Elementos a extrair:
- **Identidade do Módulo**: `modulo-id` e `modulo-caminho` em `memorias-ia/modulo.yml`
- **Gerenciador**: `pnpm` (workspaces em `pnpm-workspace.yaml`), `npm/yarn` (workspaces em `package.json`), ou `nx`/`turbo`
- **Pacotes compartilhados**: diretórios listados em `packages:` ou `workspaces:`
- **Apps/serviços**: diretórios de aplicações deployáveis

86
global/skills/onboarding-projeto/SKILL.md Normal file
View file

@ -0,0 +1,86 @@
---
name: onboarding-projeto
description: Guia operacional para inicializar o framework .agent em qualquer novo repositório ou módulo do ecossistema.
scope: global
updatedAt: "2026-09-02"
---
# Skill: Onboarding de Novo Projeto com `.agent`
Use esta skill sempre que for criar um novo projeto, inicializar um módulo SaaS ou integrar o framework `.agent` como submódulo Git em um repositório existente.
---
## 🚀 Fluxo de Onboarding em 4 Passos
```mermaid
flowchart LR
A[1. Adicionar Submódulo] --> B[2. Configurar modulo.yml]
B --> C[3. Auditar com validar-setup.sh]
C --> D[4. Instanciar os 6 Pilares DDD]
```
---
## PASSO 1 — Adicionar o Submódulo `.agent`
Na raiz do repositório do novo projeto:
```bash
git submodule add git@github.com:azteca-sistemas/agent-ia.git .agent
```
---
## PASSO 2 — Configurar a Identidade do Módulo (`memorias-ia/modulo.yml`)
1. Criar a pasta de memórias e copiar o template oficial:
```bash
mkdir -p memorias-ia
cp .agent/DOCUMENTACAO/templates/modulo.yml.template memorias-ia/modulo.yml
```
2. Editar `memorias-ia/modulo.yml` preenchendo os 4 campos obrigatórios:
```yaml
modulo-id: nome-do-modulo.submodulo # ex: e-licencie.qualifica
modulo-caminho: /qualifica/ # rota base na URL
modulo-descricao: Módulo para gestão de conformidade de fornecedores
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
```
---
## PASSO 3 — Validar a Conformidade com o Script de Setup
Execute o script de auditoria para certificar que os parâmetros foram preenchidos corretamente:
```bash
bash .agent/validar-setup.sh
```
---
## PASSO 4 — Instanciar os 6 Pilares de Documentação (Templates)
Utilize os modelos canônicos disponíveis em `.agent/DOCUMENTACAO/templates/`:
| Pilar DDD | Destino no Projeto | Template Canônico |
| :--- | :--- | :--- |
| **Pilar 1: Código** | `.ts`, `.vue`, `.js` | JSDoc no topo das funções |
| **Pilar 2: Ajuda UI** | `*-front/src/.../{componente}.ajuda.md` | `DOCUMENTACAO/templates/ajuda-tela.md.template` |
| **Pilar 3: Wiki Usuário** | `<base_projeto>/../wiki/<modulo-id>/index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` |
| **Pilar 4: Wiki Dev** | `<base_projeto>/../wiki/dev/<modulo-id>/` | `DOCUMENTACAO/templates/regra-negocio.md.template` e `adr.md.template` |
| **Pilar 5: IA (/llm.md)** | `GET <modulo-caminho>llm.md` | `DOCUMENTACAO/templates/contrato-api.md.template` |
| **Pilar 6: Memórias IA** | `memorias-ia/sessao-*.md` | Frontmatter `type: session_memory` |
---
## 🧩 Extensibilidade Local (`.agent-local/`) — Opcional
Se o novo projeto possuir regras de negócio, bibliotecas ou rotinas exclusivas que **não devem** ser enviadas ao submódulo global `.agent`:
```bash
mkdir -p .agent-local/rules .agent-local/skills .agent-local/workflows
```
> ℹ️ **Hierarquia:** Qualquer arquivo em `.agent-local/` sobrescreve automaticamente o arquivo correspondente do submódulo `.agent/` (`.agent-local/ > .agent/`).

11
global/workflows/aprimora-ia.md
View file

@ -27,11 +27,12 @@ O conhecimento do agente está organizado em **três tipos de artefatos**, cada
| **Skills** | `.agent/skills/` | `.agent/skills/` | Guias operacionais completos e reutilizáveis para tarefas complexas recorrentes |
| **Memória das Ações da IA** | — | `<base_projeto>/memorias-ia/` | Registros de sessões, otimizações dos agentes, decisões e relatórios da IA (raiz do pai) |
> 🧩 **Polimorfismo do `.agent` e Personalização por Projeto**:
> O `.agent` é polimórfico e genérico. A personalização de cada projeto específico é mantida fora do `.agent`:
> - `./memorias-ia/` (na raiz do projeto pai): Registros de ações, sessões e decisões da IA.
> - `../../wiki/<modulo>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
> - `../../wiki/dev/<modulo>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
> 🧩 **Polimorfismo do `.agent` e Identidade por Projeto**:
> O `.agent` é polimórfico e genérico. A personalização e identidade de cada projeto específico é mantida fora do `.agent`:
> - `./memorias-ia/modulo.yml` (na raiz do projeto pai): Arquivo mandatório com `modulo-id`, `modulo-caminho`, `modulo-descricao` e `modulo-tipo`.
> - `./memorias-ia/`: Registros de ações, sessões e decisões da IA.
> - `<base_projeto>/../wiki/<modulo-id>/`: Documentação funcional com acesso dos usuários na aplicação VitePress.
> - `<base_projeto>/../wiki/dev/<modulo-id>/`: Documentação técnica com acesso interno dev na aplicação VitePress.
### Diferenças entre os artefatos

4
global/workflows/doc.md
View file

@ -14,8 +14,8 @@ Atalho rápido para o **Agente de Documentação & Memória** cobrindo os 6 pila
- `1. Código-Fonte` $\rightarrow$ JSDoc de aplicação prática (`rules/jsdoc-padrao.md`)
- `2. Ajuda UI` $\rightarrow$ `modalX.ajuda.md` co-localizado com `modalX.vue`
- `3. Wiki Usuário` $\rightarrow$ `../../wiki/<modulo>/` (VitePress com acesso dos usuários)
- `4. Wiki Dev` $\rightarrow$ `../../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
- `3. Wiki Usuário` $\rightarrow$ `<base_projeto>/../wiki/<modulo>/` (VitePress com acesso dos usuários)
- `4. Wiki Dev` $\rightarrow$ `<base_projeto>/../wiki/dev/<modulo>/` (VitePress com acesso interno dev e regras `{modulo}.regras-negocio.md`)
- `5. Rota IA` $\rightarrow$ Rota do backend `/llm.md`
- `6. Memória IA` $\rightarrow$ `<base_projeto>/memorias-ia/`

10
global/workflows/documentacao.md
View file

@ -21,8 +21,8 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
2. **Distribuição e Geração nos 6 Pilares:**
- **Pilar 1 (Código-Fonte):** Insere JSDoc de aplicação prática nos arquivos alterados na sessão (`rules/jsdoc-padrao.md`).
- **Pilar 2 (Ajuda UI):** Gera `{componente}.ajuda.md` para modais e telas criados/modificados (`skills/adicionar-ajuda`).
- **Pilar 3 (Wiki Usuário):** Atualiza manuais em `../../wiki/<modulo>/` se houver mudanças com impacto no usuário final.
- **Pilar 4 (Wiki Dev):** Documenta regras técnicas (`{modulo}.regras-negocio.md`) e ADRs em `../../wiki/dev/<modulo>/`.
- **Pilar 3 (Wiki Usuário):** Atualiza manuais em `<base_projeto>/../wiki/<modulo>/` se houver mudanças com impacto no usuário final.
- **Pilar 4 (Wiki Dev):** Documenta regras técnicas (`{modulo}.regras-negocio.md`) e ADRs em `<base_projeto>/../wiki/dev/<modulo>/`.
- **Pilar 5 (Rota IA):** Assegura que novos schemas e rotas estejam refletidos na rota `/llm.md`.
- **Pilar 6 (Memória IA):** Registra o relatório completo da sessão em `<base_projeto>/memorias-ia/`.
3. **Entrega de Relatório:**
@ -36,8 +36,8 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
| :--- | :--- | :--- |
| **1. Código-Fonte** | `.ts`, `.vue`, `.js` | JSDoc e comentários claros quanto à aplicação prática (ver `rules/jsdoc-padrao.md`). |
| **2. Ajuda na Tela** | `*-front/.../{componente}.ajuda.md` | Ajuda contextual co-localizada: para `modalX.vue` $\rightarrow$ `modalX.ajuda.md`. |
| **3. Wiki do Usuário** | `../../wiki/<modulo>/` | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
| **4. Wiki de Desenvolvimento** | `../../wiki/dev/<modulo>/` | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), modelos de banco, arquitetura e ADRs (`adrs/`). |
| **3. Wiki do Usuário** | `<base_projeto>/../wiki/<modulo>/` | Aplicação VitePress com acesso dos usuários (manuais, tutoriais e fluxos). |
| **4. Wiki de Desenvolvimento** | `<base_projeto>/../wiki/dev/<modulo>/` | Aplicação VitePress com acesso interno dev: regras de negócio (`{modulo}.regras-negocio.md`), modelos de banco, arquitetura e ADRs (`adrs/`). |
| **5. Integração de IA** | Rota Backend `/llm.md` | Catálogo de schemas Zod, enums e contratos para consumo por LLMs. |
| **6. Memória da IA** | `<base_projeto>/memorias-ia/` | Registros de sessões, otimizações executadas e decisões históricas. |
@ -72,4 +72,4 @@ Este workflow aciona o **Agente de Documentação** para gerar, atualizar ou aud
1. **Nunca inventar regras:** Documentar estritamente o que foi implementado no código ou declarado na conversa.
2. **Linguagem acessível no usuário:** Sem termos técnicos de TI na Wiki do Usuário ou em `.ajuda.md`.
3. **JSDoc de Aplicação:** Explicar a utilidade prática no sistema, não apenas repetir tipos.
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `../../wiki/`.
4. **Polimorfismo:** O `.agent` é genérico; personalizações ficam em `./memorias-ia/` e `<base_projeto>/../wiki/`.

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

@ -1,13 +1,13 @@
---
name: documentar-regras-negocio
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
scope: global
updatedAt: "2026-09-01"
---
# Workflow / Skill: Documentar Regras de Negócio de um Módulo
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
---
@ -28,7 +28,7 @@ Identificar e anotar:
[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
```bash
ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
ls <base_projeto>/../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
```
- **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
@ -38,7 +38,7 @@ ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
[3] Criar o arquivo de regras na Wiki de Desenvolvimento
**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
**Localização:** `<base_projeto>/../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `<base_projeto>/../wiki/dev/<modulo>/regras-negocio/`).
Preencher com a estrutura padrão:
- Contexto operacional
@ -55,7 +55,7 @@ Preencher com a estrutura padrão:
Garantir que a primeira linha útil do arquivo TypeScript seja:
```typescript
// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
// Regras de negócio: ver <base_projeto>/../wiki/dev/<modulo>/{modulo}.regras-negocio.md
```
Se já existia e está correto → sem mudança necessária.
@ -100,6 +100,6 @@ Zero erros = concluído.
Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
- Criar ou atualizar ADR em `../../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `<base_projeto>/../wiki/dev/<modulo>/`.
- Criar ou atualizar ADR em `<base_projeto>/../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.