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

.

Browse source
This commit is contained in:
Luiz Silva 2026-06-18 12:04:15 -03:00
parent 1cb4c14d33
commit ce7cb4b746
1 changed files with 0 additions and 553 deletions
Download patch file Download diff file Expand all files Collapse all files

553
plano-01.md
View file

@ -1,553 +0,0 @@
# 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`
```markdown
---
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)
```json
{
"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:
1. Parsear frontmatter YAML do `persona.md`
2. Resolver herança: `inherits: [global]` → incluir todas as rules de `global/rules/`
3. Concatenar rules do agente (`agents/{nome}/rules/`)
4. Gerar `systemPromptSections` a partir do corpo do `persona.md`
5. Mapear `tools` do frontmatter para `toolNames`
6. 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`
```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`
```bash
# 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:
1. Criar novo adaptador em `adaptadores/{nova-llm}/`
2. Implementar script que lê `persona.md` + rules e gera config nativa
3. **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.