2026-06-18 11:59:57 -03:00

21 KiB

Raw Blame History

Plano de Trabalho — Reestruturação Multiagente do `.agent`

Projeto: AGENT-IA (repositório de conhecimento centralizado da Azteca) Data: 2026-06-18 Premissa 1: Estrutura atualizada com multiagente Premissa 2: Capacidade de aprendizado ao longo da execução de cada módulo Premissa 3: Compatibilidade com múltiplas LLMs para futuras migrações (vendor-neutral)

Diagnóstico da Estrutura Atual

Estado atual (flat/monolítico)

.agent/
├── atualizar-agente.global.sh     ← script de distribuição (hardcoded)
├── tools.md                       ← ferramentas CLI recomendadas
├── verificar-linhas.sh            ← governance: limite de linhas
├── rules/                         ← 11 rules globais (flat)
│   ├── autonomia-agente.global.md
│   ├── carta-principios-agente-azteca.global.md
│   ├── escrita-natural.global.md
│   ├── estrutura-vue.global.md
│   ├── fronteiras-monorepo.global.md
│   ├── jsdoc-padrao.global.md
│   ├── limite-linhas.global.md
│   ├── mensagens-usuario.global.md
│   ├── regras-negocio-md.global.md
│   ├── typescript-sem-any.global.md
│   └── zod-validacao-padrao.global.md
├── workflows/                     ← 11 workflows globais (flat)
│   └── (...)
└── skills/                        ← 6 skills globais (flat)
    └── (...)

Problemas identificados

#	Problema	Impacto
1	Estrutura flat — todos os artefatos são globais, sem separação por agente	Agentes recebem instruções irrelevantes (ex: ag-comercial recebe rules de TypeScript)
2	Sem definição formal de agentes — os 8 agentes do readme.md não existem como configuração	Impossível acionar agentes especializados
3	Acoplamento ao Antigravity — estrutura segue convenções de um único vendor	Migração para outra LLM exige reescrita total
4	Script de distribuição hardcoded — `atualizar-agente.global.sh` lista cada arquivo manualmente	Cada novo artefato exige edição manual do script
5	Sem sistema de herança — não há mecanismo global → plugin → agente	Rules duplicadas quando um agente precisa de variação
6	Sem orquestração — falta um mecanismo para agentes colaborarem em tarefas complexas	Trabalho em silos, sem passagem de contexto

Arquitetura Proposta

Princípio Central: Separação de Camadas

┌─────────────────────────────────────────────────┐
│           Camada Universal (Markdown)            │ ← vendor-neutral
│  Rules, Skills, Workflows, Personas, Prompts     │   compatível com qualquer LLM
├─────────────────────────────────────────────────┤
│         Camada de Adaptador (JSON/YAML)          │ ← vendor-specific
│  agent.json (Antigravity), claude.json, etc.     │   gerado a partir da camada universal
├─────────────────────────────────────────────────┤
│            Camada de Distribuição                │ ← scripts + manifesto
│  manifesto.json + atualizar-agente.sh            │   auto-discovery, sem hardcode
└─────────────────────────────────────────────────┘

IMPORTANTE: A camada universal (Markdown puro) é a fonte de verdade. Os adaptadores JSON são derivados e podem ser regenerados para qualquer plataforma.

Nova estrutura de diretórios

.agent/
├── manifesto.json                         ← inventário auto-gerado de todos os artefatos
├── atualizar-agente.sh                    ← script baseado em manifesto (não hardcoded)
├── tools.md                               ← ferramentas CLI (mantido)
├── verificar-linhas.sh                    ← governance (mantido)
│
├── global/                                ← artefatos herdados por TODOS os agentes
│   ├── rules/
│   │   ├── autonomia-agente.md
│   │   ├── carta-principios-agente-azteca.md
│   │   ├── typescript-sem-any.md
│   │   ├── zod-validacao-padrao.md
│   │   ├── fronteiras-monorepo.md
│   │   ├── regras-negocio-md.md
│   │   └── limite-linhas.md
│   ├── workflows/
│   │   ├── aprimorar-IA.md
│   │   ├── documentar-regras-negocio.md
│   │   └── otimizar-codigos.md
│   └── skills/
│       ├── mapear-codigo-fonte/SKILL.md
│       ├── diagnosticar-erros-build/SKILL.md
│       ├── documentar-decisao-tecnica/SKILL.md
│       ├── documentar-regras-negocio/SKILL.md
│       ├── criar-schema-zod/SKILL.md
│       └── documentar-dominio-modulo/SKILL.md
│
├── agents/                                ← definições dos 8 agentes especializados
│   ├── ag-arquiteto/
│   │   ├── persona.md                    ← identidade, tom, escopo (vendor-neutral)
│   │   ├── agent.json                    ← config Antigravity (vendor-specific)
│   │   ├── rules/                        ← rules exclusivas deste agente
│   │   ├── workflows/                    ← workflows exclusivos
│   │   └── skills/                       ← skills exclusivas
│   │
│   ├── ag-back/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── jsdoc-padrao.md           ← movida de global (só back precisa)
│   │   │   └── estrutura-api.md
│   │   ├── workflows/
│   │   └── skills/
│   │
│   ├── ag-front/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── estrutura-vue.md          ← movida de global (só front precisa)
│   │   │   ├── escrita-natural.md        ← movida (foco em UI text)
│   │   │   └── mensagens-usuario.md      ← movida (foco em UX)
│   │   ├── workflows/
│   │   │   ├── adicionar-ajuda.md
│   │   │   ├── criar-fluxograma.md
│   │   │   └── ux.md
│   │   └── skills/
│   │
│   ├── ag-testes/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   ├── workflows/
│   │   └── skills/
│   │
│   ├── ag-deploy/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   ├── workflows/
│   │   │   └── atualizar-agente.md       ← movido de global
│   │   └── skills/
│   │
│   ├── ag-documentacao/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── jsdoc-padrao.md           ← compartilhada com back (herança)
│   │   │   └── escrita-natural.md
│   │   ├── workflows/
│   │   └── skills/
│   │
│   ├── ag-ux/
│   │   ├── persona.md
│   │   ├── agent.json
│   │   ├── rules/
│   │   │   ├── mensagens-usuario.md
│   │   │   └── escrita-natural.md
│   │   ├── workflows/
│   │   │   └── ux.md
│   │   └── skills/
│   │
│   └── ag-comercial/
│       ├── persona.md
│       ├── agent.json
│       ├── rules/
│       │   └── escrita-natural.md
│       ├── workflows/
│       │   ├── comercial.md
│       │   ├── marketing.md
│       │   ├── orcamento.md
│       │   └── reels.md
│       └── skills/
│
└── adaptadores/                           ← templates de conversão por plataforma
    ├── antigravity/
    │   └── gerar-agent-json.sh           ← gera agent.json a partir de persona.md
    ├── claude/
    │   └── README.md                     ← futuro: instruções para Claude
    └── openai/
        └── README.md                     ← futuro: instruções para OpenAI/GPT

Fases do Trabalho

Fase 1 — Fundação: Camada Universal (vendor-neutral)

Objetivo: Criar os arquivos persona.md de cada agente — a fonte de verdade que funciona com qualquer LLM.

Estrutura padrão do `persona.md`

---
name: ag-back
display_name: "Agente Backend"
description: >
  Responsável pelo desenvolvimento do backend...
scope: [back, comuns, migracao]
inherits: [global]
tools: [view_file, replace_file_content, run_command, grep_search]
---

# Agente Backend (@ag-back)

## Identidade
Você é o agente especialista em backend...

## Escopo de Atuação
- Pacotes: *-back, *-comuns, *-migracao
- Linguagem: TypeScript (Node.js)
- Frameworks: Express/Fastify, Knex, BullMQ

## Responsabilidades
1. Implementação da lógica de negócio
2. Rotas e APIs REST
3. Integrações com banco de dados
4. Processamento de filas
5. CRONs e workers

## Restrições
- NUNCA alterar pacotes *-front
- NUNCA criar componentes Vue
- Respeitar todas as rules globais herdadas

## Colaborações
- Recebe especificações de: @ag-arquiteto
- Schemas compartilhados com: @ag-front (via *-comuns)
- Valida integridade com: @ag-testes

O persona.md é Markdown puro — funciona como instrução para Antigravity, Claude, GPT, Gemini, LLaMA ou qualquer LLM futura. O frontmatter YAML contém metadados estruturados que os adaptadores leem programaticamente.

Tarefas

#	Tarefa	Arquivos
1.1	Criar `persona.md` para `ag-arquiteto`	`agents/ag-arquiteto/persona.md`
1.2	Criar `persona.md` para `ag-back`	`agents/ag-back/persona.md`
1.3	Criar `persona.md` para `ag-front`	`agents/ag-front/persona.md`
1.4	Criar `persona.md` para `ag-testes`	`agents/ag-testes/persona.md`
1.5	Criar `persona.md` para `ag-deploy`	`agents/ag-deploy/persona.md`
1.6	Criar `persona.md` para `ag-documentacao`	`agents/ag-documentacao/persona.md`
1.7	Criar `persona.md` para `ag-ux`	`agents/ag-ux/persona.md`
1.8	Criar `persona.md` para `ag-comercial`	`agents/ag-comercial/persona.md`

Estimativa: 1-2 sessões de trabalho

Fase 2 — Redistribuição de Artefatos Existentes

Objetivo: Mover rules, workflows e skills para seus donos corretos (global vs agente específico).

Mapa de redistribuição de Rules

Rule atual	Destino	Justificativa
`autonomia-agente`	global	Todos os agentes devem respeitar
`carta-principios-agente-azteca`	global	Constituição comportamental universal
`typescript-sem-any`	global	Todo código TS, independente do agente
`zod-validacao-padrao`	global	Validação é transversal
`fronteiras-monorepo`	global	Todos devem respeitar fronteiras
`regras-negocio-md`	global	Qualquer agente que toque lógica de negócio
`limite-linhas`	global	Governance universal
`estrutura-vue`	ag-front	Só o front usa Vue
`escrita-natural`	ag-front, ag-ux, ag-documentacao, ag-comercial	Agentes que produzem texto para humanos
`jsdoc-padrao`	ag-back, ag-documentacao	Agentes que documentam código
`mensagens-usuario`	ag-front, ag-ux	Agentes que criam UI/UX

Mapa de redistribuição de Workflows

Workflow atual	Destino	Justificativa
`aprimorar-IA`	global	Meta-workflow de evolução contínua
`otimizar-codigos`	global	Refatoração transversal
`documentar-regras-negocio`	global	Qualquer agente pode documentar
`atualizar-agente`	ag-deploy	Infraestrutura
`adicionar-ajuda`	ag-front	Interface
`criar-fluxograma`	ag-front	Interface
`ux`	ag-front, ag-ux	UX
`comercial`	ag-comercial	Comercial
`marketing`	ag-comercial	Marketing
`orcamento`	ag-comercial	Orçamento
`reels`	ag-comercial	Marketing digital

Tarefas

#	Tarefa	Impacto
2.1	Criar diretório `global/` e mover artefatos globais	7 rules, 3 workflows, 6 skills
2.2	Criar diretórios por agente e distribuir artefatos específicos	4 rules, 8 workflows
2.3	Remover sufixo `.global` dos nomes de arquivo	Todos os artefatos
2.4	Atualizar referências cruzadas nos artefatos	Seções `Referências`
2.5	Criar mecanismo de herança via `inherits` no frontmatter	`persona.md` → resolve rules efetivas

ATENÇÃO: A redistribuição altera mais de 5 arquivos. Requer confirmação conforme rule autonomia-agente.

Estimativa: 1-2 sessões de trabalho

Fase 3 — Camada de Adaptador (Antigravity-first)

Objetivo: Gerar os agent.json compatíveis com Antigravity a partir dos persona.md.

Formato `agent.json` (Antigravity)

{
  "name": "ag-back",
  "description": "Responsável pelo desenvolvimento do backend...",
  "hidden": false,
  "config": {
    "customAgent": {
      "systemPromptSections": [
        {
          "title": "Identidade e Escopo",
          "content": "<!-- conteúdo extraído de persona.md -->"
        },
        {
          "title": "Rules Efetivas",
          "content": "<!-- rules globais + rules do agente, concatenadas -->"
        }
      ],
      "toolNames": [
        "view_file", "replace_file_content", "multi_replace_file_content",
        "write_to_file", "run_command", "grep_search", "list_dir",
        "send_message"
      ],
      "systemPromptConfig": {
        "includeSections": [
          "user_information", "user_rules", "skills",
          "subagent_reminder", "messaging", "artifacts"
        ]
      }
    }
  }
}

Script adaptador `gerar-agent-json.sh`

Lê o persona.md + rules efetivas (globais + do agente) e gera o agent.json automaticamente. Passos:

Parsear frontmatter YAML do persona.md
Resolver herança: inherits: [global] → incluir todas as rules de global/rules/
Concatenar rules do agente (agents/{nome}/rules/)
Gerar systemPromptSections a partir do corpo do persona.md
Mapear tools do frontmatter para toolNames
Escrever agent.json

Tarefas

#	Tarefa
3.1	Criar script `adaptadores/antigravity/gerar-agent-json.sh`
3.2	Gerar `agent.json` para cada um dos 8 agentes
3.3	Criar stub `adaptadores/claude/README.md` (placeholder para futuro)
3.4	Criar stub `adaptadores/openai/README.md` (placeholder para futuro)
3.5	Validar que os `agent.json` são reconhecidos pelo Antigravity

Estimativa: 1 sessão de trabalho

Fase 4 — Manifesto e Distribuição Inteligente

Objetivo: Substituir o script hardcoded por um sistema baseado em manifesto com auto-discovery.

`manifesto.json`

{
  "versao": "2.0.0",
  "base_url": "https://paiol.idz.one/desenvolvimento/agent-ia",
  "gerado_em": "2026-06-18T10:00:00-03:00",
  "artefatos": {
    "global": {
      "rules": [
        "global/rules/autonomia-agente.md",
        "global/rules/carta-principios-agente-azteca.md",
        "global/rules/typescript-sem-any.md"
      ],
      "workflows": [
        "global/workflows/aprimorar-IA.md"
      ],
      "skills": [
        "global/skills/mapear-codigo-fonte/SKILL.md"
      ]
    },
    "agents": {
      "ag-back": {
        "persona": "agents/ag-back/persona.md",
        "config": "agents/ag-back/agent.json",
        "rules": ["agents/ag-back/rules/jsdoc-padrao.md"],
        "workflows": [],
        "skills": []
      }
    }
  }
}

Novo `atualizar-agente.sh`

# Em vez de listar cada arquivo:
# 1. Baixa manifesto.json
# 2. Itera sobre todos os caminhos listados
# 3. Baixa cada artefato automaticamente
# Resultado: novos artefatos são incluídos sem editar o script

Tarefas

#	Tarefa
4.1	Criar `manifesto.json` com inventário completo
4.2	Criar script `gerar-manifesto.sh` (auto-discovery via `fd`)
4.3	Reescrever `atualizar-agente.sh` baseado em manifesto
4.4	Testar distribuição end-to-end em um módulo de teste

Estimativa: 1 sessão de trabalho

Fase 5 — Orquestração entre Agentes

Objetivo: Definir como agentes colaboram em tarefas que cruzam fronteiras.

Modelo de colaboração

@ag-arquiteto ──especificação──► @ag-back ──schemas *-comuns──► @ag-front
       │                              │                              │
       │                              ▼                              ▼
       │                        @ag-testes ◄──────────────── @ag-testes
       │                              │
       ├──wireframes──► @ag-front ──fluxos──► @ag-ux ──melhorias──► @ag-front
       │
       ├──features──► @ag-comercial
       │
       └──────────────► @ag-documentacao ──docs──► @ag-comercial
                              ▲
                    @ag-back ──código──┘
                    @ag-front ─código──┘

@ag-back ──build──► @ag-deploy
@ag-front ─build──► @ag-deploy

Skill de orquestração

Criar uma skill global orquestrar-agentes/SKILL.md que define:

Protocolo de handoff — como um agente passa contexto para outro
Formato de mensagem — estrutura padrão para send_message entre agentes
Regras de escopo — qual agente pode chamar qual
Resolução de conflito — quando dois agentes discordam

Tarefas

#	Tarefa
5.1	Criar `global/skills/orquestrar-agentes/SKILL.md`
5.2	Definir protocolo de mensagens inter-agentes
5.3	Adicionar seção `Colaborações` em cada `persona.md`
5.4	Testar fluxo: arquiteto → back → front (end-to-end)

Estimativa: 1-2 sessões de trabalho

Fase 6 — Validação e Documentação

Objetivo: Garantir integridade da nova estrutura e documentar para o time.

Tarefas

#	Tarefa
6.1	Atualizar `readme.md` com a nova arquitetura
6.2	Criar `AGENTS.md` na raiz (ponto de entrada para ativação de agentes)
6.3	Executar validação: todo `persona.md` tem `agent.json` correspondente
6.4	Executar validação: toda rule referenciada existe no caminho correto
6.5	Executar validação: manifesto cobre 100% dos artefatos
6.6	Testar distribuição em módulo real do e-licencie

Estimativa: 1 sessão de trabalho

Resumo de Esforço

Fase	Descrição	Sessões
1	Camada Universal (personas)	1-2
2	Redistribuição de artefatos	1-2
3	Adaptador Antigravity	1
4	Manifesto e distribuição	1
5	Orquestração	1-2
6	Validação e documentação	1
Total		6-9 sessões

Compatibilidade Multi-LLM

A arquitetura foi desenhada para que trocar de LLM não exija reescrever o conhecimento dos agentes.

Camada	O que contém	Formato	Portabilidade
Universal	Personas, Rules, Skills, Workflows	Markdown puro + frontmatter YAML	✅ 100% portável — qualquer LLM entende Markdown
Adaptador	`agent.json`, configs de plataforma	JSON específico do vendor	🔄 Regenerável via script para cada plataforma
Distribuição	Manifesto, scripts de deploy	Shell + JSON	✅ Independente de LLM

Para migrar para outra LLM:

Criar novo adaptador em adaptadores/{nova-llm}/
Implementar script que lê persona.md + rules e gera config nativa
Zero alteração na camada universal

Plataformas previstas:

Plataforma	Status	Adaptador
Antigravity (Google)	🟢 Ativo	`adaptadores/antigravity/`
Claude (Anthropic)	🟡 Preparado	`adaptadores/claude/` (stub)
GPT (OpenAI)	🟡 Preparado	`adaptadores/openai/` (stub)
Gemini (Google AI)	⚪ Futuro	—
LLaMA (Meta)	⚪ Futuro	—

Riscos e Mitigações

Risco	Probabilidade	Mitigação
Rules globais muito genéricas perdem eficácia	Média	Revisão por agente na Fase 2
Overhead de manutenção com 8 agentes	Média	Manifesto auto-gerado + herança automática
Antigravity muda API de plugins	Baixa	Camada universal não é afetada
Agentes concorrentes editam mesmo arquivo	Alta	Protocolo de handoff (Fase 5)

Próximo Passo

Aguardando aprovação do plano para iniciar a Fase 1 — criação dos persona.md dos 8 agentes.

21 KiB Raw Blame History

Plano de Trabalho — Reestruturação Multiagente do .agent

Diagnóstico da Estrutura Atual

Estado atual (flat/monolítico)

Problemas identificados

Arquitetura Proposta

Princípio Central: Separação de Camadas

Nova estrutura de diretórios

Fases do Trabalho

Fase 1 — Fundação: Camada Universal (vendor-neutral)

Estrutura padrão do persona.md

Tarefas

Fase 2 — Redistribuição de Artefatos Existentes

Mapa de redistribuição de Rules

Mapa de redistribuição de Workflows

Tarefas

Fase 3 — Camada de Adaptador (Antigravity-first)

Formato agent.json (Antigravity)

Script adaptador gerar-agent-json.sh

Tarefas

Fase 4 — Manifesto e Distribuição Inteligente

manifesto.json

Novo atualizar-agente.sh

Tarefas

Fase 5 — Orquestração entre Agentes

Modelo de colaboração

Skill de orquestração

Tarefas

Fase 6 — Validação e Documentação

Tarefas

Resumo de Esforço

Compatibilidade Multi-LLM

Para migrar para outra LLM:

Plataformas previstas:

Riscos e Mitigações

Próximo Passo

21 KiB

Raw Blame History

Plano de Trabalho — Reestruturação Multiagente do `.agent`

Estrutura padrão do `persona.md`

Formato `agent.json` (Antigravity)

Script adaptador `gerar-agent-json.sh`

`manifesto.json`

Novo `atualizar-agente.sh`