diff --git a/agents/ag-comercial/workflows/comercial.md b/agents/ag-comercial/workflows/comercial.md index 4e33b7c..6a67cd0 100644 --- a/agents/ag-comercial/workflows/comercial.md +++ b/agents/ag-comercial/workflows/comercial.md @@ -2,7 +2,7 @@ type: workflow name: comercial description: Criar uma descrição comercial das funcionalidades e do sistema -scope: global +scope: local updatedAt: "2026-06-01" --- @@ -10,7 +10,7 @@ updatedAt: "2026-06-01" 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/.md`. -É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow. +É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow. --- @@ -138,7 +138,7 @@ O arquivo `./COMERCIAL/.md` deve seguir esta estrutura: ## 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) +- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação) +- Workflow: `agents/ag-comercial/workflows/orcamento.md` (texto para documentos de orçamento e proposta — apresentação + lista de funcionalidades) +- Workflow: `agents/ag-comercial/workflows/marketing.md` (peças de marketing digital — LinkedIn, Instagram, WhatsApp, E-mail) +- Workflow: `global/workflows/otimizar-codigos.md` (para documentação técnica, não comercial) diff --git a/agents/ag-comercial/workflows/marketing.md b/agents/ag-comercial/workflows/marketing.md index 6b6c3fb..ce8ce37 100644 --- a/agents/ag-comercial/workflows/marketing.md +++ b/agents/ag-comercial/workflows/marketing.md @@ -2,7 +2,7 @@ type: workflow name: marketing description: Criar peças de marketing digital para funcionalidades e módulos do sistema -scope: global +scope: local updatedAt: "2026-06-01" --- @@ -10,7 +10,7 @@ updatedAt: "2026-06-01" 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/-marketing.md`. -É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow. +É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.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. @@ -205,5 +205,5 @@ O resultado deve ser salvo em `./COMERCIAL/-marketing.md` ou adi ## 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) +- Workflow: `agents/ag-comercial/workflows/comercial.md` (gera os blocos A e B que alimentam o marketing) +- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação) diff --git a/agents/ag-comercial/workflows/orcamento.md b/agents/ag-comercial/workflows/orcamento.md index 9d46b27..9c3b395 100644 --- a/agents/ag-comercial/workflows/orcamento.md +++ b/agents/ag-comercial/workflows/orcamento.md @@ -2,7 +2,7 @@ type: workflow name: orcamento description: Criar texto de orçamento pronto para copiar e colar em peças de orçamento/proposta -scope: global +scope: local updatedAt: "2026-06-01" --- @@ -10,7 +10,7 @@ updatedAt: "2026-06-01" 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/-orcamento.md`). -É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow. +É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow. --- @@ -129,6 +129,6 @@ se aplicável, legislação ou norma relevante citada por extenso.] ## 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) +- Workflow: `agents/ag-comercial/workflows/comercial.md` (descrição comercial detalhada — Resumo e Detalhamento) +- Workflow: `agents/ag-comercial/workflows/marketing.md` (peças de marketing digital) +- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação) diff --git a/agents/ag-comercial/workflows/reels.md b/agents/ag-comercial/workflows/reels.md index 6276b65..64e40df 100644 --- a/agents/ag-comercial/workflows/reels.md +++ b/agents/ag-comercial/workflows/reels.md @@ -2,7 +2,7 @@ type: workflow name: reels description: Criar cadeia de roteiros de Reels para divulgação de funcionalidades e módulos -scope: global +scope: local updatedAt: "2026-06-01" --- @@ -10,7 +10,7 @@ updatedAt: "2026-06-01" 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/-reels.md`. -É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.global.md`) em toda produção textual deste workflow. +É **OBRIGATÓRIO** seguir a regra global de Escrita Natural (`escrita-natural.md`) em toda produção textual deste workflow. --- @@ -199,6 +199,6 @@ O arquivo `./COMERCIAL/-reels.md` deve seguir esta estrutura: ## 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) +- Workflow: `agents/ag-comercial/workflows/comercial.md` (descrição comercial detalhada — base de contexto) +- Workflow: `agents/ag-comercial/workflows/marketing.md` (peças de marketing por canal) +- Rule: `global/rules/escrita-natural.md` (padrão obrigatório de redação) diff --git a/agents/ag-deploy/persona.md b/agents/ag-deploy/persona.md index 1e9e809..86c57e4 100644 --- a/agents/ag-deploy/persona.md +++ b/agents/ag-deploy/persona.md @@ -30,7 +30,7 @@ Você é o agente responsável pela infraestrutura, pipelines e ambientes do eco - Dockerfiles e `docker-compose.yml` - Scripts de CI/CD - Variáveis de ambiente e secrets -- Scripts de distribuição do `.agent/` +- Scripts de sincronização do `.agent/` (submodule + inherited) - Automações e tarefas agendadas de infraestrutura ## Responsabilidades diff --git a/agents/ag-deploy/workflows/atualizar-agente.md b/agents/ag-deploy/workflows/atualizar-agente.md index b91cc26..3b1c1a4 100644 --- a/agents/ag-deploy/workflows/atualizar-agente.md +++ b/agents/ag-deploy/workflows/atualizar-agente.md @@ -1,46 +1,54 @@ --- type: workflow name: atualizar-agente -description: Aplica atualizações globais para o agente de IA -scope: global -updatedAt: "2026-06-01" +description: Atualiza o submodule AGENT-IA e sincroniza artefatos herdados +scope: local +updatedAt: "2026-06-18" --- -# Workflow: Atualizar Agente Global +# Workflow: Atualizar Agente (Submodule) ## Objetivo -Baixar e aplicar a versão mais recente das rules, workflows e tools globais a partir do servidor central (`paiol.idz.one`). +Atualizar o submodule `.agent/base/` para a versão mais recente do AGENT-IA e sincronizar os artefatos herdados no projeto. ## Passos -### 1. Baixar o script de atualização (se ainda não existir) +### 1. Atualizar o submodule ```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 +cd .agent/base +git pull origin main +cd ../.. +git add .agent/base ``` -### 2. Executar o script +### 2. Executar o script de sincronização // turbo ```bash -sh .agent/atualizar-agente.global.sh +sh .agent/atualizar-agente.sh ``` -O script possui auto-atualização: na primeira execução, ele baixa sua própria versão mais recente e re-executa automaticamente. +O script sincroniza `.agent/inherited/` com os artefatos do `base/`, sem tocar em `local/`. ### 3. Verificar resultado -Confirmar que os arquivos foram atualizados sem duplicações: +Confirmar que a estrutura está íntegra: ```bash -find .agent/ -name "*.md" -o -name "*.sh" | sort +echo "=== Herdados ===" && find .agent/inherited/ -name "*.md" | sort +echo "=== Locais ===" && find .agent/local/ -name "*.md" | sort 2>/dev/null || echo "(vazio)" ``` -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. \ No newline at end of file +Se houve alterações significativas nas rules ou workflows herdados, executar `/aprimorar-IA` para validar consistência do sistema de conhecimento. + +### 5. Commitar a atualização + +```bash +git add .agent/base +git commit -m "chore: atualizar agent-ia para versão mais recente" +``` \ No newline at end of file diff --git a/agents/ag-documentacao/persona.md b/agents/ag-documentacao/persona.md index 2f1c337..d145af3 100644 --- a/agents/ag-documentacao/persona.md +++ b/agents/ag-documentacao/persona.md @@ -26,7 +26,7 @@ Você é o agente responsável por tornar o conhecimento do ecossistema Azteca a ## Escopo de Atuação - Todos os pacotes: `*-back`, `*-front`, `*-comuns` -- Diretório `.agent/` (regras, workflows, skills, memória) +- Diretório `.agent/` (base/ herdado + local/ extensões + memoria/) - Arquivos `.regras-negocio.md` co-localizados - JSDoc em funções compartilhadas - Guias de usuário e ajuda contextual nas telas diff --git a/agents/ag-documentacao/rules/escrita-natural.md b/agents/ag-documentacao/rules/escrita-natural.md deleted file mode 100644 index 2c92584..0000000 --- a/agents/ag-documentacao/rules/escrita-natural.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -type: rule -name: escrita-natural -trigger: context_match -description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica. -scope: global -updatedAt: "2026-06-01" -ativacao: > - Aplicar quando o agente estiver produzindo textos comerciais, de marketing, - orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo. - NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio). ---- - -# Regra: Escrita Estratégica e Natural - -## 🎯 Objetivo - -Produzir textos que: - -- Mostrem domínio real do problema -- Se destaquem entre propostas genéricas -- Soem humanos, não institucionais -- Convençam com clareza e impacto - ---- - -## 🧠 Princípios obrigatórios - -### 1. Começar pelo problema real - -Evitar introduções genéricas. - -❌ -"O presente projeto tem como objetivo..." - -✅ -"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios." - ---- - -### 2. Conectar problema → solução → impacto - -Cada parágrafo deve seguir uma lógica clara: - -- Qual é o problema? -- Como a solução resolve? -- O que muda na prática? - -✅ Exemplo: -"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho." - ---- - -### 3. Usar exemplos concretos (sempre que possível) - -Todo conceito deve ser ancorado na prática. - -❌ -"A solução permite coleta de dados estruturados." - -✅ -"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet." - ---- - -### 4. Escrever como quem vive o problema - -O texto deve ter contexto real: - -- campo -- operação -- prefeitura -- equipe técnica - -✅ -"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos." - ---- - -### 5. Persuasão baseada em impacto real - -Evitar adjetivos vazios. - -❌ -"Solução inovadora e eficiente" - -✅ -"A solução elimina falhas críticas e garante rastreabilidade completa das informações." - ---- - -### 6. Linguagem natural (sem burocracia) - -Preferir: - -- "Com a solução..." -- "Na prática..." -- "Isso permite..." -- "Como resultado..." - -Evitar: - -- "Dessa forma" -- "Destarte" -- "O presente projeto" - ---- - -### 7. Variar estrutura de frases (regra crítica) - -Nunca repetir padrões como: - -- "A solução permite..." -- "O sistema permite..." - -Alternar com: - -- "Na prática, o técnico..." -- "Com isso..." -- "Isso reduz..." -- "Como resultado..." - ---- - -### 8. Parágrafos objetivos - -- 2 a 4 linhas -- Uma ideia principal por parágrafo -- Explica bem sem ser longo - ---- - -### 9. Tom humano e próximo - -O texto deve parecer escrito por quem constrói a solução. - -✅ -"A solução resolve um problema real que impacta o dia a dia das equipes." - ---- - -## 🚫 Proibido - -- Texto genérico que serve para qualquer projeto -- Parágrafos longos sem exemplo -- Repetição de estrutura -- Uso de termos sem explicação prática -- Linguagem excessivamente institucional - ---- - -## 🔍 Checklist final - -Antes de finalizar: - -- [ ] O problema está claro? -- [ ] Existe exemplo prático? -- [ ] O impacto está explícito? -- [ ] O texto soa humano? -- [ ] Há repetição de estrutura? -- [ ] Parece algo real ou genérico? - ---- - -## 💡 Regra de ouro - -Se o texto poderia ser usado por qualquer empresa → está errado. - -Se parece que vem de quem vive o problema → está certo. \ No newline at end of file diff --git a/agents/ag-documentacao/rules/jsdoc-padrao.md b/agents/ag-documentacao/rules/jsdoc-padrao.md deleted file mode 100644 index d1833d3..0000000 --- a/agents/ag-documentacao/rules/jsdoc-padrao.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -type: rule -name: jsdoc-padrao -description: Padrões de documentação em código (JSDoc, casts temporários e TODOs estruturados) -scope: global -trigger: file_match -globs: - - "**/*.ts" - - "**/*.tsx" - - "**/*.vue" -updatedAt: "2026-06-01" ---- - -# Regra: Documentação em Código - -## 1. JSDoc — Princípios - -- **Por que, não o Quê**: documente o raciocínio, não o mecanismo que o TypeScript já expressa. -- **Nomenclatura limpa**: confie em nomes expressivos antes de comentários. - -## 2. JSDoc obrigatório em funções compartilhadas - -Toda função central ou de uso compartilhado deve ter cabeçalho JSDoc: - -```typescript -/** - * Busca detalhes da entidade e calcula privilégios aplicáveis. - * Não utilizar em processamento em lote para evitar sobrecarga. - * - * @param tenantId - Identificador do tenant no sistema - * @param entityId - ID do registro na base de dados - * @returns Objeto consolidado ou `null` se não encontrado - */ -export const obterDetalhes = async (tenantId: string, entityId: string) => { ... } -``` - -## 3. Casts temporários — justificativa obrigatória - -Coerções agressivas requerem comentário explicando o porquê: - -```typescript -// Necessário: biblioteca externa não provê tipagem genérica na versão atual -const dados = payload.raw as unknown as RespostaFormatada -``` - -## 4. TODOs estruturados - -Dívida técnica ou dúvida de negócio deve seguir formato padronizado: - -- **Tipagem**: `// TODO de tipagem: Criar interface para o retorno da API` -- **Negócio**: `// TODO de regra: Validar com Produto se taxa se aplica a clientes antigos` - -## Impacto - -Sem este padrão, funções compartilhadas ficam sem documentação, casts aparecem sem justificativa, e TODOs são inconsistentes e difíceis de buscar. - -## Referências - -- Rule: `.agent/rules/typescript-sem-any.global.md` diff --git a/agents/ag-front/rules/escrita-natural.md b/agents/ag-front/rules/escrita-natural.md deleted file mode 100644 index 2c92584..0000000 --- a/agents/ag-front/rules/escrita-natural.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -type: rule -name: escrita-natural -trigger: context_match -description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica. -scope: global -updatedAt: "2026-06-01" -ativacao: > - Aplicar quando o agente estiver produzindo textos comerciais, de marketing, - orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo. - NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio). ---- - -# Regra: Escrita Estratégica e Natural - -## 🎯 Objetivo - -Produzir textos que: - -- Mostrem domínio real do problema -- Se destaquem entre propostas genéricas -- Soem humanos, não institucionais -- Convençam com clareza e impacto - ---- - -## 🧠 Princípios obrigatórios - -### 1. Começar pelo problema real - -Evitar introduções genéricas. - -❌ -"O presente projeto tem como objetivo..." - -✅ -"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios." - ---- - -### 2. Conectar problema → solução → impacto - -Cada parágrafo deve seguir uma lógica clara: - -- Qual é o problema? -- Como a solução resolve? -- O que muda na prática? - -✅ Exemplo: -"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho." - ---- - -### 3. Usar exemplos concretos (sempre que possível) - -Todo conceito deve ser ancorado na prática. - -❌ -"A solução permite coleta de dados estruturados." - -✅ -"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet." - ---- - -### 4. Escrever como quem vive o problema - -O texto deve ter contexto real: - -- campo -- operação -- prefeitura -- equipe técnica - -✅ -"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos." - ---- - -### 5. Persuasão baseada em impacto real - -Evitar adjetivos vazios. - -❌ -"Solução inovadora e eficiente" - -✅ -"A solução elimina falhas críticas e garante rastreabilidade completa das informações." - ---- - -### 6. Linguagem natural (sem burocracia) - -Preferir: - -- "Com a solução..." -- "Na prática..." -- "Isso permite..." -- "Como resultado..." - -Evitar: - -- "Dessa forma" -- "Destarte" -- "O presente projeto" - ---- - -### 7. Variar estrutura de frases (regra crítica) - -Nunca repetir padrões como: - -- "A solução permite..." -- "O sistema permite..." - -Alternar com: - -- "Na prática, o técnico..." -- "Com isso..." -- "Isso reduz..." -- "Como resultado..." - ---- - -### 8. Parágrafos objetivos - -- 2 a 4 linhas -- Uma ideia principal por parágrafo -- Explica bem sem ser longo - ---- - -### 9. Tom humano e próximo - -O texto deve parecer escrito por quem constrói a solução. - -✅ -"A solução resolve um problema real que impacta o dia a dia das equipes." - ---- - -## 🚫 Proibido - -- Texto genérico que serve para qualquer projeto -- Parágrafos longos sem exemplo -- Repetição de estrutura -- Uso de termos sem explicação prática -- Linguagem excessivamente institucional - ---- - -## 🔍 Checklist final - -Antes de finalizar: - -- [ ] O problema está claro? -- [ ] Existe exemplo prático? -- [ ] O impacto está explícito? -- [ ] O texto soa humano? -- [ ] Há repetição de estrutura? -- [ ] Parece algo real ou genérico? - ---- - -## 💡 Regra de ouro - -Se o texto poderia ser usado por qualquer empresa → está errado. - -Se parece que vem de quem vive o problema → está certo. \ No newline at end of file diff --git a/agents/ag-front/rules/estrutura-vue.md b/agents/ag-front/rules/estrutura-vue.md index de0a4cf..417889a 100644 --- a/agents/ag-front/rules/estrutura-vue.md +++ b/agents/ag-front/rules/estrutura-vue.md @@ -2,7 +2,7 @@ type: rule name: estrutura-vue description: Padrões obrigatórios de estrutura para componentes Vue 3 (defineComponent, setup, CSS, dispatch) -scope: global +scope: local trigger: file_match globs: - "**/*.vue" @@ -82,5 +82,5 @@ Sem estes padrões, componentes perdem inferência de tipos, lógica fica inaudi ## Referências -- Rule: `.agent/rules/limite-linhas.global.md` -- Rule: `.agent/rules/typescript-sem-any.global.md` +- Rule: `global/rules/limite-linhas.md` +- Rule: `global/rules/typescript-sem-any.md` diff --git a/agents/ag-front/workflows/adicionar-ajuda.md b/agents/ag-front/workflows/adicionar-ajuda.md index 2dff1e9..adf862c 100644 --- a/agents/ag-front/workflows/adicionar-ajuda.md +++ b/agents/ag-front/workflows/adicionar-ajuda.md @@ -2,7 +2,7 @@ type: workflow name: adicionar-ajuda description: Adicionar ou atualizar botão de ajuda e documentação em telas (Frontend) -scope: global +scope: local updatedAt: "2026-06-01" --- diff --git a/agents/ag-front/workflows/criar-fluxograma.md b/agents/ag-front/workflows/criar-fluxograma.md index d7651d2..231fee1 100644 --- a/agents/ag-front/workflows/criar-fluxograma.md +++ b/agents/ag-front/workflows/criar-fluxograma.md @@ -2,7 +2,7 @@ type: workflow name: criar-fluxograma description: Criar ou atualizar uma página de fluxograma interativo em qualquer sistema -scope: global +scope: local updatedAt: "2026-06-01" --- @@ -185,5 +185,5 @@ 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) +- Workflow: `global/workflows/otimizar-codigos.md` +- Skill: `global/skills/documentar-decisao-tecnica/SKILL.md` (para decisões que geram fluxogramas) diff --git a/agents/ag-testes/persona.md b/agents/ag-testes/persona.md index cd1f0bf..9783f73 100644 --- a/agents/ag-testes/persona.md +++ b/agents/ag-testes/persona.md @@ -61,6 +61,41 @@ Você é o agente responsável por garantir a qualidade e confiabilidade do ecos - Cenários escritos em linguagem do domínio (Gherkin-style quando aplicável) - Documenta o "o que" e o "por que" de cada cenário +## Contexto de Referência + +Este repositório é consumido como **git submodule** em `.agent/base/` dentro de cada projeto filho. Os artefatos seguem a hierarquia: + +``` +.agent/ +├── base/ ← submodule AGENT-IA (read-only, nunca editar) +│ ├── global/ ← rules, workflows e skills herdados +│ └── agents/ ← personas e artefatos de cada agente +├── local/ ← extensões do projeto (rules, workflows, skills) +├── inherited/ ← cópia sincronizada do base (git-ignored) +└── memoria/ ← ADRs, diários, contexto do projeto +``` + +### Onde encontrar artefatos + +| Tipo | Caminho | +|------|---------| +| Rules globais (herdadas) | `.agent/base/global/rules/` | +| Workflows globais (herdados) | `.agent/base/global/workflows/` | +| Skills globais (herdadas) | `.agent/base/global/skills/` | +| Personas dos agentes | `.agent/base/agents/*/persona.md` | +| Rules locais do projeto | `.agent/local/rules/` | +| Workflows locais do projeto | `.agent/local/workflows/` | +| Skills locais do projeto | `.agent/local/skills/` | +| Memória e ADRs | `.agent/memoria/` | + +### Precedência + +``` +local/ > inherited/ (base) +``` + +Artefatos em `local/` sempre têm prioridade sobre os herdados de `base/`. + ## Checklist de cobertura mínima - [ ] Happy path (fluxo principal) coberto? diff --git a/agents/ag-ux/rules/escrita-natural.md b/agents/ag-ux/rules/escrita-natural.md deleted file mode 100644 index 2c92584..0000000 --- a/agents/ag-ux/rules/escrita-natural.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -type: rule -name: escrita-natural -trigger: context_match -description: Garantir escrita natural, fluida e humana em textos comerciais e de comunicação, evitando linguagem robótica ou excessivamente genérica. -scope: global -updatedAt: "2026-06-01" -ativacao: > - Aplicar quando o agente estiver produzindo textos comerciais, de marketing, - orçamentos, propostas, reels ou qualquer comunicação voltada ao público externo. - NÃO aplicar em documentação técnica (ADRs, rules, JSDoc, regras de negócio). ---- - -# Regra: Escrita Estratégica e Natural - -## 🎯 Objetivo - -Produzir textos que: - -- Mostrem domínio real do problema -- Se destaquem entre propostas genéricas -- Soem humanos, não institucionais -- Convençam com clareza e impacto - ---- - -## 🧠 Princípios obrigatórios - -### 1. Começar pelo problema real - -Evitar introduções genéricas. - -❌ -"O presente projeto tem como objetivo..." - -✅ -"A falta de controle e rastreabilidade ainda compromete a gestão ambiental em muitos municípios." - ---- - -### 2. Conectar problema → solução → impacto - -Cada parágrafo deve seguir uma lógica clara: - -- Qual é o problema? -- Como a solução resolve? -- O que muda na prática? - -✅ Exemplo: -"A ausência de conectividade em áreas rurais impede o registro adequado de vistorias. A solução permite coleta offline diretamente no celular. Como resultado, elimina perda de informação e reduz retrabalho." - ---- - -### 3. Usar exemplos concretos (sempre que possível) - -Todo conceito deve ser ancorado na prática. - -❌ -"A solução permite coleta de dados estruturados." - -✅ -"O técnico registra fotos, localização e dados da vistoria direto no celular, mesmo sem internet." - ---- - -### 4. Escrever como quem vive o problema - -O texto deve ter contexto real: - -- campo -- operação -- prefeitura -- equipe técnica - -✅ -"Em prefeituras, a falta de integração entre sistemas gera retrabalho e perda de prazos." - ---- - -### 5. Persuasão baseada em impacto real - -Evitar adjetivos vazios. - -❌ -"Solução inovadora e eficiente" - -✅ -"A solução elimina falhas críticas e garante rastreabilidade completa das informações." - ---- - -### 6. Linguagem natural (sem burocracia) - -Preferir: - -- "Com a solução..." -- "Na prática..." -- "Isso permite..." -- "Como resultado..." - -Evitar: - -- "Dessa forma" -- "Destarte" -- "O presente projeto" - ---- - -### 7. Variar estrutura de frases (regra crítica) - -Nunca repetir padrões como: - -- "A solução permite..." -- "O sistema permite..." - -Alternar com: - -- "Na prática, o técnico..." -- "Com isso..." -- "Isso reduz..." -- "Como resultado..." - ---- - -### 8. Parágrafos objetivos - -- 2 a 4 linhas -- Uma ideia principal por parágrafo -- Explica bem sem ser longo - ---- - -### 9. Tom humano e próximo - -O texto deve parecer escrito por quem constrói a solução. - -✅ -"A solução resolve um problema real que impacta o dia a dia das equipes." - ---- - -## 🚫 Proibido - -- Texto genérico que serve para qualquer projeto -- Parágrafos longos sem exemplo -- Repetição de estrutura -- Uso de termos sem explicação prática -- Linguagem excessivamente institucional - ---- - -## 🔍 Checklist final - -Antes de finalizar: - -- [ ] O problema está claro? -- [ ] Existe exemplo prático? -- [ ] O impacto está explícito? -- [ ] O texto soa humano? -- [ ] Há repetição de estrutura? -- [ ] Parece algo real ou genérico? - ---- - -## 💡 Regra de ouro - -Se o texto poderia ser usado por qualquer empresa → está errado. - -Se parece que vem de quem vive o problema → está certo. \ No newline at end of file diff --git a/agents/ag-ux/rules/mensagens-usuario.md b/agents/ag-ux/rules/mensagens-usuario.md deleted file mode 100644 index 2085e92..0000000 --- a/agents/ag-ux/rules/mensagens-usuario.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -type: rule -name: mensagens-usuario -description: Toda mensagem visível ao usuário final deve ser escrita em linguagem do domínio, sem termos técnicos de TI -scope: global -trigger: file_match -globs: - - "**/*.vue" - - "**/*.ts" - - "**/*.tsx" -updatedAt: "2026-06-01" ---- - -# Regra: Mensagens Orientadas ao Domínio - -## Contexto - -O usuário final dos módulos SaaS é profissional de **engenharia, ciência ou gestão ambiental**. Ele entende de legislação, processos técnicos e ciência aplicada — mas **não tem obrigação de entender tecnologia**. - -Toda mensagem visível na interface — erro, validação, confirmação, tooltip, empty state, ajuda — deve ser escrita na linguagem do domínio do módulo. - -## Regra - -### 1. Erros de validação devem indicar O QUE preencher, não O QUE falhou - -```typescript -// ❌ ERRADO — linguagem técnica -"Campo obrigatório" -"Erro de validação" -"Formato inválido" -"Payload inválido" - -// ✅ CORRETO — linguagem do domínio -"Informe a Área do Empreendimento (em hectares)" -"Selecione o Tipo de Licença: LP, LI ou LO" -"A Data da Vistoria deve ser anterior à data atual" -"Informe o CNPJ no formato 00.000.000/0000-00" -``` - -### 2. Erros de sistema devem ser traduzidos para o usuário - -```typescript -// ❌ ERRADO — erro técnico exposto -"Erro 500: Internal Server Error" -"Timeout na requisição" -"Network Error" -"ECONNREFUSED" - -// ✅ CORRETO — mensagem humanizada -"Não foi possível salvar. Tente novamente em instantes." -"A operação demorou mais que o esperado. Tente novamente." -"Sem conexão com o servidor. Verifique sua internet." -``` - -### 3. Estados vazios devem explicar o contexto - -Quando uma lista ou tabela está vazia, a mensagem deve orientar o usuário: - -```typescript -// ❌ ERRADO — genérico -"Nenhum registro encontrado" -"Lista vazia" - -// ✅ CORRETO — explica o domínio e orienta -"Nenhuma condicionante cadastrada para esta licença." -"Nenhum relatório de monitoramento registrado neste período." -"Nenhum empreendimento encontrado com os filtros aplicados. Tente ampliar a busca." -``` - -### 4. Confirmações devem descrever a consequência - -```typescript -// ❌ ERRADO — genérico -"Tem certeza que deseja excluir?" -"Confirmar operação?" - -// ✅ CORRETO — descreve o impacto -"Excluir esta condicionante? O prazo de cumprimento e os documentos vinculados serão removidos." -"Arquivar esta licença? Ela não aparecerá mais nas listagens ativas." -``` - -### 5. Labels e placeholders devem usar vocabulário do domínio - -```typescript -// ❌ ERRADO — genérico -label: "Nome" -placeholder: "Digite aqui" - -// ✅ CORRETO — específico do domínio -label: "Razão Social do Empreendedor" -placeholder: "Ex: Mineração Vale Verde Ltda." - -label: "Área Total do Empreendimento" -placeholder: "Em hectares (ex: 150,5)" -``` - -### 6. Schemas Zod devem ter mensagens de domínio - -```typescript -// ❌ ERRADO — mensagens padrão do Zod -const zEmpreendimento = z.object({ - nome: z.string().min(1), // "String must contain at least 1 character(s)" - area: z.number().positive(), // "Number must be greater than 0" -}) - -// ✅ CORRETO — mensagens customizadas -const zEmpreendimento = z.object({ - nome: z.string().min(1, "Informe o nome do empreendimento"), - area: z.number({ invalid_type_error: "A área deve ser um número" }) - .positive("A área deve ser maior que zero"), - cnpj: z.string().regex(/^\d{2}\.\d{3}\.\d{3}\/\d{4}-\d{2}$/, - "CNPJ inválido. Use o formato 00.000.000/0000-00"), -}) -``` - -## Impacto - -Sem esta regra, o agente gera mensagens técnicas que confundem gestores ambientais, consultores e técnicos de campo — forçando a equipe de suporte a traduzir erros de sistema para o vocabulário do cliente. - -## Referências - -- Rule: `.agent/rules/zod-validacao-padrao.global.md` (schemas com mensagens customizadas) -- Workflow: `.agent/workflows/ux.global.md` (design de interface) diff --git a/agents/ag-ux/workflows/ux.md b/agents/ag-ux/workflows/ux.md deleted file mode 100644 index f7d8357..0000000 --- a/agents/ag-ux/workflows/ux.md +++ /dev/null @@ -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 (`