100 lines
3.4 KiB
Markdown
100 lines
3.4 KiB
Markdown
---
|
||
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 os templates oficiais:
|
||
```bash
|
||
mkdir -p memorias-ia
|
||
cp .agent/DOCUMENTACAO/templates/modulo.yml.template memorias-ia/modulo.yml
|
||
cp .agent/DOCUMENTACAO/templates/historico-acoes.md.template memorias-ia/historico-acoes.md
|
||
```
|
||
|
||
2. Editar `memorias-ia/modulo.yml` preenchendo os campos canônicos:
|
||
```yaml
|
||
modulo-id: nome-do-modulo
|
||
modulo-caminho: /modulo/
|
||
modulo-descricao: Descrição funcional e escopo de negócio do módulo
|
||
modulo-tipo: aplicação web com back e front nas tecnologias bun e vue 3 com banco postgres
|
||
modulo-acesso:
|
||
usuario: usuario@exemplo.com.br
|
||
senha: "123"
|
||
modulo-wiki: ../wiki
|
||
```
|
||
|
||
---
|
||
|
||
## 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/`).
|