custom-agents-boilerplate 0.1.0

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 🎓
• 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, rode 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)

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.

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 (12 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

Estrutura do projeto

agent-boilerplate/
├── .github/
│   └── agents/               # 12 custom agents (formato atual)
├── src/custom_agents_boilerplate/templates/
│   ├── config/               # Fonte da verdade de roles e níveis
│   ├── agents/               # Prompts por role (+ base)
│   └── levels/               # Ajuste de comportamento por nível
├── chatmodes/                # Arquivos legacy (*.chatmode.md)
├── examples/                 # Exemplos para demo (entrada/saída)
└── scripts/                  # validate + list + regenerate

Validar a instalação

Primeiro clone/primeira vez:

bash scripts/generate-agents.sh

Depois valide:

bash scripts/validate.sh

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

bash scripts/validate.sh --source-only

Regenerar os agentes após mudanças

Quando você editar qualquer arquivo em src/custom_agents_boilerplate/templates/agents/ ou src/custom_agents_boilerplate/templates/levels/, regenere:

bash scripts/generate-agents.sh
bash scripts/validate.sh

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: src/custom_agents_boilerplate/templates/agents/_base/base-prompt.md e src/custom_agents_boilerplate/templates/agents/_base/rules.md
• Especialização por role: src/custom_agents_boilerplate/templates/agents/<role>/prompt.md e src/custom_agents_boilerplate/templates/agents/<role>/tasks.md
• Ajuste por nível: src/custom_agents_boilerplate/templates/levels/<nivel>.md

Créditos

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