Metadata-Version: 2.4
Name: custom-agents-boilerplate
Version: 0.1.4
Summary: CLI para gerar Custom Agents (VS Code + GitHub Copilot Chat) em qualquer projeto.
Author: Agent Boilerplate
License-Expression: MIT
Project-URL: Homepage, https://github.com/EngelRyan/agent-boilerplate
Project-URL: Repository, https://github.com/EngelRyan/agent-boilerplate
Project-URL: Issues, https://github.com/EngelRyan/agent-boilerplate/issues
Keywords: vscode,copilot,agents,prompt,cli
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Agent Boilerplate 🤖

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

- **Role (papel)**: Dev 🧑‍💻 | QA 🧪 | PO 📋 | 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):

```bash
pipx install custom-agents-boilerplate
```

Alternativa (instala no ambiente atual):

```bash
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**.

Rodar o wizard:

```bash
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.: 18 agentes) no diretório atual:

```bash
custom-agents generate
```

Para ser específico (recomendado em CI):

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

Listar opções:

```bash
custom-agents list
```

## 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.
- **Professor**: explicação guiada, analogias, checagem de compreensão, exercícios e próximos passos.
- **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 (15 combinações)

- `dev-iniciante`, `dev-intermediario`, `dev-avancado`
- `qa-iniciante`, `qa-intermediario`, `qa-avancado`
- `po-iniciante`, `po-intermediario`, `po-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/               # 15 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:

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

Depois valide:

```bash
python scripts/validate.py
```

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

```bash
python scripts/validate.py --source-only
```

## Regenerar os agentes após mudanças

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

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

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

```bash
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:

```bash
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:

```bash
python scripts/package_agents.py --list
```

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

```bash
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:

```bash
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.
