diff --git a/plano-01.md b/plano-01.md deleted file mode 100644 index 57203ce..0000000 --- a/plano-01.md +++ /dev/null @@ -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": "" - }, - { - "title": "Rules Efetivas", - "content": "" - } - ], - "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.