custom-agents-boilerplate 0.1.2

CLI para gerar Custom Agents (VS Code + GitHub Copilot Chat) em qualquer projeto.

Agent Boilerplate 🤖

Ambiente de Custom Agents para o VS Code + GitHub Copilot Chat, com variações por:

• Role (papel): Dev 🧑‍💻 | QA 🧪 | PO 📋 | Estudante 🎓 | Professor 🧑‍🏫 | UX 🎨
• Nível (mentoria): Iniciante 🌱 | Intermediário 🚀 | Avançado ⚡

Objetivo: para a mesma tarefa, obter respostas coerentes e visivelmente diferentes dependendo do papel e do nível.

Uso profissional (sem clonar repo)

Você pode instalar um CLI e gerar os agentes dentro de qualquer projeto.

Instalar

Recomendado (instala o comando globalmente, sem sujar o Python do sistema):

pipx install custom-agents-boilerplate

Alternativa (instala no ambiente atual):

pip install custom-agents-boilerplate

Gerar no seu projeto

Dentro da pasta do seu projeto:

• Rodar custom-agents sem subcomando abre o menu guiado (wizard).
• Rodar custom-agents generate é o modo sem menu (bom para CI).

Rodar o wizard:

custom-agents

Ele cria .github/agents/ (e opcionalmente chatmodes/). Depois abra o projeto no VS Code → Copilot Chat → dropdown de Agents.

Usar sem menu (CI / comando direto)

Se você não passar --roles e --levels, o generate cria todas as combinações (ex.: 12 agentes) no diretório atual:

custom-agents generate

Para ser específico (recomendado em CI):

custom-agents generate --roles dev,qa --levels iniciante,avancado --output .

Listar opções:

custom-agents list

Publicar no PyPI

Guia completo (manual + GitHub Actions com Trusted Publishing): veja PUBLISHING.md.

O que você ganha com cada role

• Dev: implementação, arquitetura, debugging, qualidade de código.
• QA: plano de testes, casos de teste, estratégia de automação, risco e severidade.
• PO: user stories, critérios de aceite, métricas de sucesso, priorização.
• Estudante: explicação didática, exemplos progressivos, exercícios.
• Professor: plano de aula, objetivos de aprendizagem, avaliações e feedback.
• UX: fluxos/jornadas, revisão heurística, acessibilidade, microcopy e critérios de validação.

O que muda em cada nível

• Iniciante: define termos, passo a passo curto, exemplo completo.
• Intermediário: trade-offs, perguntas de contexto, snippets relevantes.
• Avançado: direto, crítico, edge cases, implicações de longo prazo.

Onde ficam os agentes (importante)

O formato atual do VS Code chama isso de Custom Agents e o VS Code detecta automaticamente os arquivos em:

• .github/agents/*.agent.md

Este repo também mantém uma pasta chatmodes/ com arquivos *.chatmode.md por compatibilidade/legado.

Nota: neste projeto, os arquivos em .github/agents/ e chatmodes/ são gerados. Quem clonar o repo deve gerar pela primeira vez (passo abaixo).

Como usar no VS Code (passo a passo)

1. Abra a pasta agent-boilerplate/ no VS Code.
2. Abra o Copilot Chat.
3. No dropdown de Agents, selecione um agente (por exemplo dev-iniciante).
4. Faça sua solicitação normalmente.

Se você não enxergar os agentes:

• Garanta que o workspace está Trusted.
• Abra a tela de customizações do chat (ícone de engrenagem) e confira a lista de agentes carregados.

Agentes disponíveis (18 combinações)

• dev-iniciante, dev-intermediario, dev-avancado
• qa-iniciante, qa-intermediario, qa-avancado
• po-iniciante, po-intermediario, po-avancado
• estudante-iniciante, estudante-intermediario, estudante-avancado
• professor-iniciante, professor-intermediario, professor-avancado
• ux-iniciante, ux-intermediario, ux-avancado

Estrutura do projeto

agent-boilerplate/
├── agents/                  # Fonte da verdade: base + roles
├── levels/                  # Fonte da verdade: níveis
├── config/                  # Fonte da verdade: catálogo (roles/levels)
├── .github/
│   └── agents/               # 12 custom agents (formato atual)
├── src/custom_agents_boilerplate/templates/  # Espelho (package data) — gerado via sync
│   ├── config/
│   ├── agents/
│   └── levels/
├── chatmodes/                # Arquivos legacy (*.chatmode.md)
├── examples/                 # Exemplos para demo (entrada/saída)
└── scripts/                  # validate + list + regenerate

Validar a instalação

Primeiro clone/primeira vez:

python scripts/generate_agents.py --chatmodes --force

Depois valide:

python scripts/validate.py

Se você quiser validar apenas as “fontes” (sem exigir arquivos gerados), use:

python scripts/validate.py --source-only

Regenerar os agentes após mudanças

Quando você editar qualquer arquivo em agents/, levels/ ou config/, regenere:

python scripts/generate_agents.py --chatmodes --force
python scripts/validate.py

Se você for publicar no PyPI, sincronize o espelho do pacote antes:

python scripts/sync_templates.py

Gerar um pacote custom (baixar só o que escolher)

Se você quer distribuir/usar apenas algumas combinações (por exemplo, só dev-iniciante e qa-avancado), use o empacotador:

Opção 1 (recomendado): menu guiado

Rode e siga o passo a passo:

python scripts/package_agents.py

Ele vai perguntar quais roles, quais níveis, a pasta de saída, se é para recriar ou adicionar mais, e se gera .zip.

Opção 2: comando direto (sem menu)

1. (Opcional) veja as opções disponíveis:

python scripts/package_agents.py --list

2. Gere uma pasta (e opcionalmente um .zip) com apenas os agentes escolhidos:

python scripts/package_agents.py --roles dev,qa --levels iniciante,avancado --zip

Isso cria dist/agent-boilerplate-package/ contendo somente:

• .github/agents/*.agent.md (os selecionados)
• README.md (instruções rápidas)

3. Para “baixar mais” depois (adicionar mais agentes no mesmo pacote), rode novamente com --add apontando para a mesma saída:

python scripts/package_agents.py --output dist/agent-boilerplate-package --add --roles po --levels intermediario --zip

Observação: para o VS Code detectar, basta abrir a pasta do pacote no VS Code; ele carrega o que estiver em .github/agents/.

Como customizar / evoluir

• Regras universais: agents/_base/base-prompt.md e agents/_base/rules.md
• Especialização por role: agents/<role>/prompt.md e agents/<role>/tasks.md
• Ajuste por nível: levels/<nivel>.md

Créditos

Projeto acadêmico para a disciplina de Inteligência Artificial.