---
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 e Configurar o Submódulo `.agent` na Branch Master

Na raiz do repositório do novo projeto:

```bash
# Adicionar rastreando explicitamente a branch master
git submodule add -b master https://git2.idz.one/publico/.agent.git .agent
git submodule update --init --recursive --remote
```

> 💡 **Repositórios existentes:** Caso o submódulo já esteja adicionado, garanta o rastreamento da branch `master`:
> ```bash
> git submodule set-branch --branch master .agent
> git submodule update --init --recursive --remote
> ```

---

## 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** | `<modulo-wiki>/<modulo-id>/index.md` | `DOCUMENTACAO/templates/modulo-dominio.md.template` |
| **Pilar 4: Wiki Dev** | `<modulo-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/`).