aplimoramento de agent

skills/onboarding-projeto/SKILL.md

@@ -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/`).