refactor: remover extensões .md de todos os artefatos — v3.0.0

- 55 arquivos .md renomeados para sem extensão
- Convenção: artefatos de conhecimento sem extensão, scripts (.sh) e dados (.json) mantêm extensão
- Scripts atualizados: gerar-manifesto.sh, atualizar-agente.sh, atualizar-agente.global.sh, gerar-agent-json.sh, verificar-linhas.sh
- Documentação reescrita: AGENTS, README, EXTEND para refletir uso como submodule .agent direto
- manifesto.json regenerado v3.0.0
- Todas as referências internas entre artefatos atualizadas

BREAKING CHANGE: arquivos não possuem mais extensão .md
This commit is contained in:
Luiz Silva 2026-06-19 16:04:37 -03:00
parent 22023df81e
commit bf9be375e2
58 changed files with 506 additions and 514 deletions

132
AGENTS Normal file
View file

@ -0,0 +1,132 @@
# AGENTS — Ponto de entrada dos agentes Azteca
Este arquivo descreve como ativar e colaborar com os agentes especializados do ecossistema Azteca.
---
## Agentes disponíveis
| Agente | Handle | Especialidade |
|--------|--------|--------------|
| Arquiteto | `@ag-arquiteto` | Arquitetura, especificações, ADRs |
| Backend | `@ag-back` | APIs, banco de dados, filas, CRONs |
| Frontend | `@ag-front` | Vue 3, telas, composables, integração API |
| Testes | `@ag-testes` | Testes unitários, integração, roteiros de QA |
| Deploy | `@ag-deploy` | Docker, CI/CD, infraestrutura, ambientes |
| Documentação | `@ag-documentacao` | JSDoc, regras de negócio, guias de usuário |
| UX | `@ag-ux` | Fluxos de uso, usabilidade, mensagens de interface |
| Comercial | `@ag-comercial` | Propostas, marketing, Reels, orçamentos |
| Agente de Agentes | `@ag-agente` | Construção, melhoria e manutenção do ecossistema de agentes |
| Refatoração | `@ag-refatorar` | SOLID, Design Patterns GoF, code smells, refatoração segura |
---
## Como ativar um agente
Mencione o agente pelo handle:
```
@ag-back implementa o endpoint POST /usuarios conforme schema zUsuarioCriar
```
```
@ag-ux revisa o fluxo de cadastro de empreendimento
```
---
## Estrutura do `.agent/`
Este repositório é usado como **git submodule** `.agent` nos monorepos.
```
.agent/ ← este repositório (submodule)
├── AGENTS ← este arquivo
├── EXTEND ← como projetos filhos herdam e estendem
├── README ← documentação do repositório
├── TOOLS ← ferramentas CLI recomendadas
├── manifesto.json ← inventário de todos os artefatos
├── gerar-manifesto.sh ← gera manifesto.json automaticamente
├── atualizar-agente.sh ← distribui artefatos para os módulos
├── verificar-linhas.sh ← governance: limite de linhas
│
├── global/ ← artefatos herdados por TODOS os agentes
│ ├── rules/ ← 11 rules globais
│ ├── workflows/ ← 4 workflows globais
│ └── skills/ ← 7 skills globais (incluindo orquestrar-agentes)
│
├── agents/ ← definições dos 10 agentes
│ ├── ag-arquiteto/
│ │ └── persona ← identidade, escopo, responsabilidades
│ ├── ag-back/
│ │ └── persona
│ ├── ag-front/
│ │ ├── persona
│ │ ├── rules/
│ │ └── workflows/
│ ├── ag-refatorar/
│ │ ├── persona
│ │ ├── rules/ ← refatoracao-segura, solid-compliance, design-patterns-pragmatico
│ │ ├── skills/ ← diagnosticar-code-smells
│ │ └── workflows/ ← refatorar-modulo
│ ├── ag-testes/
│ ├── ag-deploy/
│ ├── ag-documentacao/
│ ├── ag-ux/
│ ├── ag-comercial/
│ └── ag-agente/
│
└── adaptadores/ ← conversores por plataforma LLM
├── antigravity/
│ └── gerar-agent-json.sh ← gera agent.json para o Antigravity
├── claude/
│ └── README ← instruções para migração futura
└── openai/
└── README ← instruções para migração futura
```
> **Convenção:** artefatos de conhecimento (personas, rules, workflows, skills) não possuem extensão. Scripts (`.sh`) e dados (`.json`) mantêm suas extensões nativas.
---
## Compatibilidade com outras LLMs
A estrutura foi projetada para ser **vendor-neutral**:
- `persona` + `global/rules/` + `agents/*/rules/` = **Markdown puro**, funciona com qualquer LLM
- `agent.json` = configuração específica do Antigravity, **gerada automaticamente** pelo script adaptador
- Para migrar para outra LLM: criar adaptador em `adaptadores/{nome}/` sem alterar o conhecimento
---
## Orquestração entre agentes
Consulte a skill `global/skills/orquestrar-agentes/SKILL` para o protocolo completo de colaboração.
Sequência padrão para uma nova feature:
```
@ag-arquiteto → @ag-back → @ag-front → @ag-testes → @ag-deploy
↕ ↕
@ag-refatorar @ag-ux
↓
@ag-documentacao → @ag-comercial
```
> `@ag-refatorar` pode ser acionado em qualquer ponto do fluxo quando código existente precisa ser melhorado antes de evoluir.
---
## Distribuição para módulos
Para copiar os artefatos do `.agent/` para um módulo:
```sh
sh .agent/atualizar-agente.sh
```
Para gerar/atualizar o `manifesto.json` após adicionar novos artefatos:
```sh
sh .agent/gerar-manifesto.sh
```