publico/.agent
4
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(submodule): atualizar submodulo .agent na branch master ao iniciar sessao

Browse source
This commit is contained in:
Luiz Silva 2026-10-08 11:15:14 -03:00
parent b1c4c5c42e
commit 29e5bc979e
14 changed files with 306 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

6
README
View file

@ -110,9 +110,9 @@ PLANOS/ ← fila de planos técnicos de implementaç
## Usar em um novo projeto (Onboarding em 4 passos)
```sh
# 1. Adicionar o submódulo
git submodule add https://git2.idz.one/publico/.agent.git.agent
git submodule update --init --recursive
# 1. Adicionar e sincronizar o submódulo na branch master
git submodule add -b master https://git2.idz.one/publico/.agent.git .agent
git submodule update --init --recursive --remote
# 2. Criar obrigatoriamente a identidade do módulo
mkdir -p memorias-ia

6
README.md
View file

@ -110,9 +110,9 @@ PLANOS/ ← fila de planos técnicos de implementaç
## Usar em um novo projeto (Onboarding em 4 passos)
```sh
# 1. Adicionar o submódulo
git submodule add https://git2.idz.one/publico/.agent.git.agent
git submodule update --init --recursive
# 1. Adicionar e sincronizar o submódulo na branch master
git submodule add -b master https://git2.idz.one/publico/.agent.git .agent
git submodule update --init --recursive --remote
# 2. Criar obrigatoriamente a identidade do módulo
mkdir -p memorias-ia

80
global/rules/atualizacao-submodulo-sessao.md Normal file
View file

@ -0,0 +1,80 @@
# Regra: Atualização Obrigatória do Submódulo `.agent` na Branch Master ao Iniciar Sessão
## Contexto
O ecossistema Azteca adota o framework `.agent` como um **git submodule** compartilhado entre múltiplos repositórios e produtos (`quipo`, `e-licencie`, `sigma`, etc.). Novas regras, personas, correções de ferramentas (como isolamento de sessão do `agent-browser` e upload MinIO Paiol), workflows e skills são continuamente aprimorados e versionados diretamente na branch `master` do repositório remoto:
```
https://git2.idz.one/publico/.agent.git
```
Trabalhar com uma versão defasada do submódulo `.agent` faz com que o agente tome decisões baseadas em regras antigas, falhe em auditorias de setup ou use padrões depreciados. Por isso, a sincronização do submódulo na branch `master` é mandatória ao iniciar qualquer sessão.
---
## Regra Mandatória de Inicialização
Ao iniciar uma nova sessão de trabalho ou interação no projeto hospedeiro, a sincronização do submódulo `.agent` **DEVE OBRIGATORIAMENTE ser executada** na branch `master`:
```bash
git submodule update --init --recursive --remote
```
Esta operação é classificada como uma **ação autônoma** (conforme `rules/autonomia-agente.md`) e não requer autorização prévia do operador humano.
---
## 1. Rastreamento Obrigatório de Branch no `.gitmodules`
Para que o parâmetro `--remote` do Git saiba qual branch do submódulo deve ser consultada e atualizada, o arquivo `.gitmodules` na raiz do projeto pai deve conter explicitamente a declaração `branch = master`:
```ini
[submodule ".agent"]
path = .agent
url = https://git2.idz.one/publico/.agent.git
branch = master
```
Caso o atributo `branch` esteja ausente no `.gitmodules`, o script de governança ou o próprio agente deve configurá-lo executando:
```bash
git submodule set-branch --branch master .agent
```
---
## 2. Protocolo de Automação via Lifecycle Hook
O framework `.agent` disponibiliza um hook nativo do Antigravity em `.agent/hooks.json` vinculado ao evento `PreInvocation`:
1. No início da conversa, o hook aciona o script `.agent/scripts/atualizar-submodulo.sh`.
2. O script detecta a raiz do projeto pai (superprojeto) e verifica a existência de uma trava temporária da sessão (`/tmp/.antigravity_agent_updated_${conversationId}`).
3. **Idempotência:** A sincronização remota é executada apenas no primeiro turno da sessão. Turnos subsequentes retornam imediatamente (`{}`), garantindo zero latência adicional durante o diálogo.
4. Ao concluir com sucesso, o script emite uma notificação efêmera informando a IA sobre a sincronização na branch `master`.
---
## 3. Resiliência e Fallback Offline
A atualização do submódulo nunca deve interromper ou impedir o atendimento ao operador:
- Se o ambiente estiver sem acesso à internet, com DNS indisponível ou falha temporária de rede, o script captura o erro graciosamente.
- O agente emite um aviso no log/contexto informando que a sincronização remota não pôde ser completada e prossegue normalmente a execução com a versão local já presente no submódulo.
---
## Proibições
- **NUNCA** travar o submódulo `.agent` em branches experimentais ou desatualizadas sem autorização explícita do operador.
- **NUNCA** abortar a sessão ou falhar com crash caso a rede esteja indisponível para atualização remota.
- **NUNCA** executar `git submodule update --remote` descartando alterações locais em desenvolvimento sem verificação prévia.
---
## Referências
- Rule: `rules/autonomia-agente.md`
- Rule: `rules/identidade-modulo.md`
- Script: `.agent/scripts/atualizar-submodulo.sh`
- Hook: `.agent/hooks.json`
- Script: `.agent/validar-setup.sh`

1
global/rules/autonomia-agente.md
View file

@ -29,6 +29,7 @@ O agente pode executar sem perguntar:
- Aplicar padrões de nomenclatura já definidos em rules
- Executar `git add`, `git commit`, `git push` e resolver conflitos diretamente na branch `master` no repositório da Wiki (`<base_projeto>/../wiki` ou `wiki/`) ao criar ou atualizar documentações
- Executar `git commit` na aplicação principal em branches de trabalho (criando compulsoriamente uma nova branch caso o repositório esteja na `master`)
- Atualizar o submódulo `.agent` ao iniciar uma sessão executando `git submodule update --init --recursive --remote` na branch `master`
## Ações que Requerem Confirmação

4
global/rules/identidade-modulo.md
View file

@ -67,7 +67,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia.
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
@ -83,6 +84,7 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
## Referências
- Rule: `global/rules/atualizacao-submodulo-sessao.md`
- Rule: `global/rules/ddd-documentacao-primeiro.md`
- Rule: `global/rules/regras-negocio-md.md`
- Rule: `global/rules/testes-interface-agent-browser.md`

12
global/skills/onboarding-projeto/SKILL.md
View file

@ -22,14 +22,22 @@ flowchart LR
---
## PASSO 1 — Adicionar o Submódulo `.agent`
## PASSO 1 — Adicionar e Configurar o Submódulo `.agent` na Branch Master
Na raiz do repositório do novo projeto:
```bash
git submodule add https://git2.idz.one/publico/.agent.git.agent
# 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`)

11
hooks.json Normal file
View file

@ -0,0 +1,11 @@
{
"atualizar-submodulo-agent": {
"PreInvocation": [
{
"type": "command",
"command": "[ -f .agent/scripts/atualizar-submodulo.sh ] && bash .agent/scripts/atualizar-submodulo.sh || bash scripts/atualizar-submodulo.sh",
"timeout": 20
}
]
}
}

3
manifesto.json
View file

@ -1,10 +1,11 @@
{
"versao": "3.2.0",
"atualizadoEm": "2026-10-01",
"atualizadoEm": "2026-10-08",
"projeto": "e-licencie",
"artefatos": {
"global": {
"rules": [
"global/rules/atualizacao-submodulo-sessao.md",
"global/rules/autonomia-agente.md",
"global/rules/carta-principios-agente-azteca.md",
"global/rules/copywriting-landing.md",

80
rules/atualizacao-submodulo-sessao.md Normal file
View file

@ -0,0 +1,80 @@
# Regra: Atualização Obrigatória do Submódulo `.agent` na Branch Master ao Iniciar Sessão
## Contexto
O ecossistema Azteca adota o framework `.agent` como um **git submodule** compartilhado entre múltiplos repositórios e produtos (`quipo`, `e-licencie`, `sigma`, etc.). Novas regras, personas, correções de ferramentas (como isolamento de sessão do `agent-browser` e upload MinIO Paiol), workflows e skills são continuamente aprimorados e versionados diretamente na branch `master` do repositório remoto:
```
https://git2.idz.one/publico/.agent.git
```
Trabalhar com uma versão defasada do submódulo `.agent` faz com que o agente tome decisões baseadas em regras antigas, falhe em auditorias de setup ou use padrões depreciados. Por isso, a sincronização do submódulo na branch `master` é mandatória ao iniciar qualquer sessão.
---
## Regra Mandatória de Inicialização
Ao iniciar uma nova sessão de trabalho ou interação no projeto hospedeiro, a sincronização do submódulo `.agent` **DEVE OBRIGATORIAMENTE ser executada** na branch `master`:
```bash
git submodule update --init --recursive --remote
```
Esta operação é classificada como uma **ação autônoma** (conforme `rules/autonomia-agente.md`) e não requer autorização prévia do operador humano.
---
## 1. Rastreamento Obrigatório de Branch no `.gitmodules`
Para que o parâmetro `--remote` do Git saiba qual branch do submódulo deve ser consultada e atualizada, o arquivo `.gitmodules` na raiz do projeto pai deve conter explicitamente a declaração `branch = master`:
```ini
[submodule ".agent"]
path = .agent
url = https://git2.idz.one/publico/.agent.git
branch = master
```
Caso o atributo `branch` esteja ausente no `.gitmodules`, o script de governança ou o próprio agente deve configurá-lo executando:
```bash
git submodule set-branch --branch master .agent
```
---
## 2. Protocolo de Automação via Lifecycle Hook
O framework `.agent` disponibiliza um hook nativo do Antigravity em `.agent/hooks.json` vinculado ao evento `PreInvocation`:
1. No início da conversa, o hook aciona o script `.agent/scripts/atualizar-submodulo.sh`.
2. O script detecta a raiz do projeto pai (superprojeto) e verifica a existência de uma trava temporária da sessão (`/tmp/.antigravity_agent_updated_${conversationId}`).
3. **Idempotência:** A sincronização remota é executada apenas no primeiro turno da sessão. Turnos subsequentes retornam imediatamente (`{}`), garantindo zero latência adicional durante o diálogo.
4. Ao concluir com sucesso, o script emite uma notificação efêmera informando a IA sobre a sincronização na branch `master`.
---
## 3. Resiliência e Fallback Offline
A atualização do submódulo nunca deve interromper ou impedir o atendimento ao operador:
- Se o ambiente estiver sem acesso à internet, com DNS indisponível ou falha temporária de rede, o script captura o erro graciosamente.
- O agente emite um aviso no log/contexto informando que a sincronização remota não pôde ser completada e prossegue normalmente a execução com a versão local já presente no submódulo.
---
## Proibições
- **NUNCA** travar o submódulo `.agent` em branches experimentais ou desatualizadas sem autorização explícita do operador.
- **NUNCA** abortar a sessão ou falhar com crash caso a rede esteja indisponível para atualização remota.
- **NUNCA** executar `git submodule update --remote` descartando alterações locais em desenvolvimento sem verificação prévia.
---
## Referências
- Rule: `rules/autonomia-agente.md`
- Rule: `rules/identidade-modulo.md`
- Script: `.agent/scripts/atualizar-submodulo.sh`
- Hook: `.agent/hooks.json`
- Script: `.agent/validar-setup.sh`

1
rules/autonomia-agente.md
View file

@ -29,6 +29,7 @@ O agente pode executar sem perguntar:
- Aplicar padrões de nomenclatura já definidos em rules
- Executar `git add`, `git commit`, `git push` e resolver conflitos diretamente na branch `master` no repositório da Wiki (`<base_projeto>/../wiki` ou `wiki/`) ao criar ou atualizar documentações
- Executar `git commit` na aplicação principal em branches de trabalho (criando compulsoriamente uma nova branch caso o repositório esteja na `master`)
- Atualizar o submódulo `.agent` ao iniciar uma sessão executando `git submodule update --init --recursive --remote` na branch `master`
## Ações que Requerem Confirmação

4
rules/identidade-modulo.md
View file

@ -67,7 +67,8 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
2. **Rota ou URL base (`modulo-caminho`)**: para configurar rotas frontend, rotas backend, endpoints de documentação de IA (`/llm.md` e `<modulo-caminho>llm.md`), links de navegação ou proxies;
3. **Propósito ou Stack (`modulo-descricao` e `modulo-tipo`)**: para contextualizar novos agentes, gerar propostas comerciais, marketing, reels, análises de arquitetura ou testes;
4. **Credenciais de Testes (`modulo-acesso`)**: O agente de testes (`@testes`, rotinas com `agent-browser`, QA) DEVE extrair `usuario` e `senha` de `modulo-acesso` em `memorias-ia/modulo.yml` para autenticação determinística em rotinas de teste e validação de interface;
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia.
5. **Caminho da Wiki (`modulo-wiki`)**: Qualquer operação de documentação, leitura de regras ou commit na Wiki deve resolver o caminho a partir de `modulo-wiki`, adotando compulsoriamente `../wiki/` caso a chave não esteja presente ou esteja vazia;
6. **Sincronização do Submódulo (`.agent`)**: Ao iniciar qualquer sessão ou interação no projeto hospedeiro, o agente DEVE assegurar que o submódulo `.agent` esteja atualizado com a branch `master` remota executando `git submodule update --init --recursive --remote`.
👉 **O agente DEVE obrigatoriamente ler e extrair as informações de `memorias-ia/modulo.yml`.**
@ -83,6 +84,7 @@ Sempre que qualquer agente, persona, workflow ou skill necessitar de:
## Referências
- Rule: `global/rules/atualizacao-submodulo-sessao.md`
- Rule: `global/rules/ddd-documentacao-primeiro.md`
- Rule: `global/rules/regras-negocio-md.md`
- Rule: `global/rules/testes-interface-agent-browser.md`

77
scripts/atualizar-submodulo.sh Executable file
View file

@ -0,0 +1,77 @@
#!/usr/bin/env bash
# ==============================================================================
# Script de Ciclo de Vida: Atualização do Submódulo .agent ao Iniciar Sessão
# Executa: git submodule update --init --recursive --remote na branch master
# Compatível com CLI e Lifecycle Hook do Antigravity (PreInvocation).
# ==============================================================================
set -e
INPUT_JSON=""
IS_PIPE=0
if [ ! -t 0 ]; then
IS_PIPE=1
INPUT_JSON=$(cat 2>/dev/null || true)
fi
# Extrair conversationId se chamado via Hook Antigravity
CONV_ID=""
if [ -n "$INPUT_JSON" ]; then
CONV_ID=$(echo "$INPUT_JSON" | grep -o '"conversationId":[[:space:]]*"[^"]*' | sed 's/.*"//' || true)
fi
# Idempotência: executar apenas uma vez por sessão de conversa
if [ -n "$CONV_ID" ]; then
LOCK_FILE="/tmp/.antigravity_agent_updated_${CONV_ID}"
if [ -f "$LOCK_FILE" ]; then
echo "{}"
exit 0
fi
fi
# Detectar diretório raiz do superprojeto
SUPER_DIR=$(git rev-parse --show-superproject-working-tree 2>/dev/null || true)
if [ -z "$SUPER_DIR" ]; then
if [ -f ".gitmodules" ]; then
SUPER_DIR="."
elif [ -f "../.gitmodules" ]; then
SUPER_DIR=".."
elif [ -f "../../.gitmodules" ]; then
SUPER_DIR="../.."
else
SUPER_DIR="."
fi
fi
if [ -f "$SUPER_DIR/.gitmodules" ]; then
# Garantir configuração branch = master no .gitmodules
CURRENT_BRANCH=$(git -C "$SUPER_DIR" config -f .gitmodules submodule..agent.branch 2>/dev/null || true)
if [ "$CURRENT_BRANCH" != "master" ]; then
git -C "$SUPER_DIR" config -f .gitmodules submodule..agent.branch master 2>/dev/null || true
fi
# Executar a atualização remota do submódulo .agent
if git -C "$SUPER_DIR" submodule update --init --recursive --remote .agent >/dev/null 2>&1; then
[ -n "$CONV_ID" ] && touch "$LOCK_FILE" 2>/dev/null || true
if [ "$IS_PIPE" -eq 1 ] && [ -n "$INPUT_JSON" ]; then
echo '{"injectSteps":[{"ephemeralMessage":"ℹ️ Submódulo .agent sincronizado com sucesso na branch master (git submodule update --init --recursive --remote)."}]}'
else
echo "✅ Submódulo .agent sincronizado com sucesso na branch master."
fi
exit 0
else
if [ "$IS_PIPE" -eq 1 ] && [ -n "$INPUT_JSON" ]; then
echo '{"injectSteps":[{"ephemeralMessage":"⚠️ Não foi possível sincronizar o submódulo .agent com origin/master (sem conexão ou erro de rede). Continuando com versão local."}]}'
else
echo "⚠️ Não foi possível sincronizar o submódulo .agent com origin/master. Continuando com versão local."
fi
exit 0
fi
fi
if [ "$IS_PIPE" -eq 1 ]; then
echo "{}"
else
echo "ℹ️ Nenhum arquivo .gitmodules detectado."
fi
exit 0

12
skills/onboarding-projeto/SKILL.md
View file

@ -22,14 +22,22 @@ flowchart LR
---
## PASSO 1 — Adicionar o Submódulo `.agent`
## PASSO 1 — Adicionar e Configurar o Submódulo `.agent` na Branch Master
Na raiz do repositório do novo projeto:
```bash
git submodule add https://git2.idz.one/publico/.agent.git.agent
# 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`)

22
validar-setup.sh
View file

@ -30,6 +30,28 @@ echo -e "${AZUL}${NEGRITO}======================================================
TOTAL_ERROS=0
TOTAL_AVISOS=0
# 0. Validar Submódulo .agent e tracking da branch master
echo -e "\n${NEGRITO}[0/6] Submódulo .agent (Sincronização & Branch Master)${RESET}"
if [ -f "$ROOT_DIR/.gitmodules" ]; then
if grep -q '\[submodule "\.agent"\]' "$ROOT_DIR/.gitmodules"; then
echo -e " ${VERDE}✓${RESET} Submódulo .agent configurado em .gitmodules."
SUBMODULE_BRANCH=$(git -C "$ROOT_DIR" config -f .gitmodules submodule..agent.branch 2>/dev/null || true)
if [ "$SUBMODULE_BRANCH" = "master" ]; then
echo -e " ${VERDE}✓${RESET} Submódulo configurado para rastrear branch: ${NEGRITO}master${RESET}"
else
echo -e " ${AMARELO}⚠${RESET} Submódulo .agent não possui 'branch = master' configurado no .gitmodules."
echo -e " Execute: git submodule set-branch --branch master .agent"
TOTAL_AVISOS=$((TOTAL_AVISOS + 1))
fi
else
echo -e " ${VERMELHO}✗${RESET} Entrada do submódulo .agent não encontrada em .gitmodules."
TOTAL_ERROS=$((TOTAL_ERROS + 1))
fi
else
echo -e " ${AMARELO}⚠${RESET} Arquivo .gitmodules não encontrado na raiz."
fi
# 1. Validar memorias-ia/modulo.yml (Pilar 6 - Identidade)
MODULO_YML="$ROOT_DIR/memorias-ia/modulo.yml"
echo -e "\n${NEGRITO}[1/6] Identidade do Módulo (memorias-ia/modulo.yml)${RESET}"