wizard

Files (3)

• SKILL.md
• openai.yaml · agents/
• template.sh

SKILL.md (first lines)

# Wizard

Um **wizard** é um script em bash que guia um humano, passo a passo, por um procedimento manual cansativo de fazer à mão e cansativo de reexplicar a uma IA toda vez. Ele abre cada URL, diz exatamente o que clicar e copiar, captura os valores, grava-os onde pertencem (`.env`, secrets do GitHub), pede confirmação em cada etapa e mostra quantas etapas restam. Ele pode configurar serviços de terceiros, rodar uma migração pontual ou mudar o projeto de um estado para outro.

A experiência de uso elegante já está resolvida pelo [template.sh](template.sh) — progresso etapa por etapa, travas de confirmação, abertura de URL multiplataforma (incluindo WSL), inserção oculta de segredos, upserts idempotentes em `.env`, gravação via `gh secret`/`gh variable` e um resumo de encerramento. **Seu trabalho é apenas delimitar o escopo do procedimento e escrever suas etapas.** A biblioteca acima do marcador `STAGES` é idêntica em todo wizard; essa consistência é o objetivo — nunca a edite manualmente.

Um wizard é efêmero por padrão — criado para uma única execução, salvo em um diretório temporário (scratch) ou em `scripts/`, e excluído quando o trabalho termina. Faça commit dele apenas quando o usuário desejar um fluxo de configuração repetível que deva residir no repositório.

## Processo

### 1. Delimitar o escopo do procedimento

Mapeie cada passo manual que o humano precisa realizar e cada valor que deve ser capturado ao longo do caminho. Leia o repositório primeiro — não faça perguntas sem contexto:

- Para configuração (setup): `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, configurações do framework e `.github/workflows/*` (toda referência a `secrets.*` / `vars.*` é um valor que o wizard precisa produzir).
- Para uma migração ou transição: o estado atual, o estado alvo e as ações irreversíveis entre eles.

Em seguida, mostre ao usuário a lista ordenada de etapas e os valores que cada uma produz, e confirme — ele pode adicionar, remover ou reordenar.

**Concluído quando:** cada etapa estiver nomeada em ordem, e para cada valor capturado você souber (a) de onde o humano o obtém, (b) onde ele é gravado (`.env`, um secret do GitHub, ambos ou em nenhum lugar — algumas etapas são puramente ações) e (c) se é secreto (entrada oculta) ou público.

### 2. Mapear a jornada de cada etapa

Para cada etapa, escreva o caminho exato que o humano segue: qual URL abrir, o que fazer lá, onde o valor é exibido, qual variável ele preenche — ex.: "Dashboard → Desenvolvedores → Chaves de API → Revelar chave de teste → copiar". Quando você não souber a interface atual real ou o comando exato, diga isso e pergunte ao usuário ou consulte a documentação — nunca invente passos que possam não existir.

**Concluído quando:** cada etapa puder ser rastreada até instruções concretas que qualquer pessoa conseguiria seguir.

### 3. Escrever o wizard

Copie `template.sh` para o caminho de destino. Substitua a etapa de exemplo por um `stage` por passo, em ordem de dependência. Use os auxiliares da biblioteca — `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm` — e defina `TOTAL_STAGES` com o número de etapas escritas.

Mantenha o padrão de qualidade definido pelo modelo: abra a URL antes de pedir o valor, use `ask_secret` para qualquer dado confidencial, use `write_env` em todo valor persistido, use `set_secret` apenas nos valores de que o CI realmente precisa e use `confirm` antes de qualquer ação irreversível. Cada `stage` limpa a tela para que apenas o passo atual fique visível — mantenha cada etapa restrita a uma tarefa focada para que nada do que o humano precisa saia da tela por rolagem. Não mexa na biblioteca acima do marcador.

### 4. Verificar e entregar

- `bash -n <script>`; execute `shellcheck` se disponível.
- `chmod +x <script>`.
- Não o execute de ponta a ponta você mesmo — ele abre navegadores e aguarda entradas humanas. Em vez disso, faça o rastreamento estático: certifique-se de que cada valor do passo 1 é capturado e gravado onde o passo 1 definiu, e que cada nome de `set_secret` corresponde exatamente a uma referência `secrets.*` no CI.
- Diga ao usuário como executá-lo. Se for um caminho de configuração repetível, faça o commit e crie um link no README para que a próxima pessoa execute o script em vez de perguntar a uma IA.

From matheusdmlopes/skills-ptbr, MIT.

More from matheusdmlopes/skills-ptbr