.agent/skills/onboarding-projeto/SKILL.md

name	description	scope	updatedAt
onboarding-projeto	Guia operacional para inicializar o framework .agent em qualquer novo repositório ou módulo do ecossistema.	global	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

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:

# 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:

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:

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:

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

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