# Como usar o .agent como submodulo git

O repositório `.agent` é adicionado como **git submodule** em cada projeto.
Isso garante controle de versão, rollback seguro e atualizações rastreáveis.

---

## Estrutura em um projeto filho

```
meu-modulo/
├── .agent/                ← git submodule (este repo — nunca editar diretamente)
│   ├── global/
│   ├── agents/
│   ├── adaptadores/
│   ├── AGENTS
│   ├── EXTEND
│   └── ...
├── .agent-local/          ← suas extensões (commitar no projeto)
│   ├── rules/
│   ├── workflows/
│   ├── skills/
│   ├── agents/
│   └── manifesto-local.json
└── .gitmodules            ← gerado pelo git ao adicionar submodulo
```

---

## Configuração inicial (uma vez por projeto)

### 1. Adicionar o .agent como submodulo

```sh
# Na raiz do projeto
git submodule add https://git2.idz.one/publico/.agent.git .agent
git submodule update --init --recursive
```

### 2. Criar a estrutura local

```sh
mkdir -p .agent-local/rules
mkdir -p .agent-local/workflows
mkdir -p .agent-local/skills
mkdir -p .agent-local/agents
```

### 3. Criar o `manifesto-local.json`

```sh
cp .agent/manifesto-local.template.json .agent-local/manifesto-local.json
```

Editar o arquivo:

```json
{
  "submodulo": ".agent",
  "projeto": "sigma2026",
  "descricao": "Módulo de monitoramento ambiental",
  "versao": "1.0.0",
  "local": {
    "rules": [
      "rules/dominio-ambiental"
    ],
    "workflows": [],
    "skills": [
      "skills/criar-funcao-api/SKILL"
    ],
    "agents": {
      "ag-back": {
        "persona-local": "agents/ag-back/persona-local",
        "rules": [
          "agents/ag-back/rules/knex-padrao"
        ]
      }
    }
  }
}
```

### 4. Configurar `.gitignore`

```gitignore
# O .agent/ é submodulo — gerenciado pelo git automaticamente
# Nada a ignorar; .agent-local/ é commitado normalmente
```

---

## Como atualizar o .agent no futuro

```sh
cd .agent
git pull origin main
cd ..
git add .agent
git commit -m "chore: atualizar .agent para versão mais recente"
```

---

## Como fazer override de um agente

Crie `persona-local` em `.agent-local/agents/{agente}/`:

```markdown
---
name: ag-back
extends: .agent/agents/ag-back/persona
project: sigma2026
---

# Extensão: @ag-back para sigma2026

## Contexto adicional do projeto

- PostgreSQL com PostGIS (coordenadas geográficas)
- JSONB para características variáveis por tipo de monitoramento
- Padrão `zBaseTabelaPadrao` do sigma-comuns

## Regras adicionais

- Toda query de coordenadas usa funções PostGIS
- O campo `info` é cache descartável — não é fonte primária
```

---

## Como adicionar uma rule local

Crie em `.agent-local/rules/`:

```markdown
---
name: dominio-ambiental
description: Vocabulário e padrões do domínio ambiental para o sigma2026
scope: local
---

# Regra: Domínio Ambiental (sigma2026)

## Contexto
...

## Regra
...
```

Declare no `manifesto-local.json`:
```json
"local": {
  "rules": ["rules/dominio-ambiental"]
}
```

---

## Precedência de artefatos

```
.agent-local/ > .agent/ (base)
```

| Situação | Resultado |
|----------|-----------|
| Artefato só em `.agent/` | Usa o base |
| Artefato só em `.agent-local/` | Usa o local |
| Artefato em ambos | `.agent-local/` tem prioridade |

---

## Pinagem de versão (segurança)

O submodulo fica travado em um commit específico do .agent.
Para atualizar para uma versão específica:

```sh
cd .agent
git checkout v3.0.0           # travar em tag
# ou
git checkout main             # usar sempre o mais recente

cd ..
git add .agent
git commit -m "chore: atualizar .agent para v3.0.0"
```

---

## O que commitar no projeto filho

```
✅ Commitar:
  .agent-local/         (todas as extensões locais)
  .gitmodules           (referência ao submodulo)

❌ Não commitar (gerenciado pelo git submodule):
  .agent/               (é submodulo — referência automática)
```

---

## Compatibilidade com múltiplas LLMs

O modelo de herança funciona com qualquer LLM:
- `.agent-local/` e `.agent/` são **Markdown puro** (sem extensão)
- `manifesto-local.json` é **JSON genérico**
- Para gerar config nativa de uma LLM: use `.agent/adaptadores/{llm}/`