.

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

agents/ag-documentacao/rules/escrita-natural.md

@@ -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.

agents/ag-documentacao/rules/jsdoc-padrao.md

@@ -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`