.agent/EXTEND.md

Como usar o AGENT-IA como submodulo git

O AGENT-IA é adicionado como git submodule em cada projeto filho. Isso garante controle de versão, rollback seguro e atualizações rastreáveis.

---

Estrutura em um projeto filho

meu-modulo/
├── .agent/
│   ├── base/              ← git submodule (AGENT-IA repo — nunca editar)
│   │   └── .agent/
│   │       ├── global/
│   │       ├── agents/
│   │       ├── adaptadores/
│   │       └── ...
│   ├── local/             ← suas extensões (commitar no projeto)
│   │   ├── rules/
│   │   ├── workflows/
│   │   ├── skills/
│   │   └── agents/
│   ├── inherited/         ← cópia sincronizada do base (git-ignored)
│   ├── manifesto-local.json
│   └── atualizar-agente.sh
└── .gitmodules            ← gerado pelo git ao adicionar submodulo

---

Configuração inicial (uma vez por projeto)

1. Adicionar o AGENT-IA como submodulo

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

2. Criar a estrutura local

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

cp .agent/base/.agent/manifesto-local.template.json .agent/manifesto-local.json

Editar o arquivo:

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

4. Copiar e executar o script de sincronização

cp .agent/base/.agent/atualizar-agente.sh .agent/atualizar-agente.sh
chmod +x .agent/atualizar-agente.sh
sh .agent/atualizar-agente.sh

Isso popula .agent/inherited/ com os artefatos do base, sem tocar em local/.

5. Configurar .gitignore

# Artefatos sincronizados do submodulo — regenerados automaticamente
.agent/inherited/

---

Como atualizar o base no futuro

# Atualiza o submodulo para o commit mais recente e sincroniza
sh .agent/atualizar-agente.sh

# Só atualiza o git sem sincronizar (verificar antes)
sh .agent/atualizar-agente.sh --no-pull --dry-run

# Atualiza sem fazer pull (usar conteúdo atual do submodulo)
sh .agent/atualizar-agente.sh --no-pull

---

Como fazer override de um agente

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

---
name: ag-back
extends: inherited/agents/ag-back/persona.md
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 local/rules/:

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

"local": {
  "rules": ["local/rules/dominio-ambiental.md"]
}

---

Precedência de artefatos

local/ > inherited/ (base)

Situação	Resultado
Artefato só em inherited/	Usa o base
Artefato só em local/	Usa o local
Artefato em ambos	local/ tem prioridade

---

Pinagem de versão (segurança)

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

cd .agent/base
git checkout v2.1.0           # travar em tag
# ou
git checkout main             # usar sempre o mais recente

cd ../..
git add .agent/base
git commit -m "chore: atualizar agent-ia para v2.1.0"

---

O que commitar no projeto filho

✅ Commitar:
  .agent/manifesto-local.json
  .agent/atualizar-agente.sh
  .agent/local/           (todas as extensões locais)
  .gitmodules             (referência ao submodulo)

❌ Não commitar (adicionar ao .gitignore):
  .agent/inherited/       (sincronizado automaticamente)

---

Compatibilidade com múltiplas LLMs

O modelo de herança funciona com qualquer LLM:

• local/ e inherited/ são Markdown puro
• manifesto-local.json é JSON genérico
• Para gerar config nativa de uma LLM: use inherited/adaptadores/{llm}/