wizard

Files (3)

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

SKILL.md (first lines)

# Wizard

Um **wizard** é um script bash que conduz um humano, passo a passo, por um procedimento manual que é tedioso de fazer na mão e tedioso de reexplicar para uma IA toda vez. Ele abre cada URL, diz exatamente o que clicar e copiar, captura os valores, escreve-os onde devem ficar (`.env`, secrets do GitHub), confirma a cada etapa e mostra quantos estágios faltam. Pode configurar serviços de terceiros, rodar uma migração pontual, ou mover o projeto de um estado para outro.

A UX refinada já está resolvida pelo [template.sh](template.sh) — progresso estágio a estágio, portões de confirmação, abertura de URL cross-platform (incluindo WSL), entrada oculta de secrets, upserts idempotentes no `.env`, escrita via `gh secret`/`gh variable` e um resumo final. **Seu trabalho é apenas escopar o procedimento e escrever os estágios dele.** A biblioteca acima do marcador `STAGES` é idêntica em todo wizard; essa consistência é o ponto — nunca a edite à mão.

Um wizard é efêmero por padrão — feito para uma execução, salvo num caminho de scratch ou em `scripts/`, apagado quando o trabalho termina. Faça commit dele apenas quando o usuário quiser um caminho de setup repetível que deva viver no repo.

## Processo

### 1. Escope o procedimento

Levante todo passo manual que o humano precisa dar e todo valor capturado pelo caminho. Leia o repo primeiro — não pergunte no vácuo:

- Para setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, config do framework e `.github/workflows/*` (cada referência `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.

Então mostre ao usuário a lista ordenada de estágios e os valores que cada um produz, e confirme — ele pode adicionar, remover ou reordenar.

**Pronto quando:** todo estágio está nomeado em ordem, e para cada valor capturado você sabe (a) onde o humano o obtém, (b) onde ele é escrito (`.env`, um secret do GitHub, ambos, ou lugar nenhum — alguns estágios são ações puras) e (c) se é secreto (entrada oculta) ou público.

### 2. Mapeie a jornada de cada estágio

Para cada estágio, escreva o caminho preciso que um humano percorre: qual URL abrir, o que fazer lá, onde o valor aparece, qual variável ele preenche — ex.: "Dashboard → Developers → API keys → Reveal test key → copiar". Onde você não souber de fato a UI atual ou o comando exato, diga isso e pergunte ao usuário ou consulte a documentação — nunca invente passos que podem não existir.

**Pronto quando:** todo estágio se traduz em instruções concretas que um estranho conseguiria seguir.

### 3. Escreva o wizard

Copie o `template.sh` para o caminho alvo. Substitua o estágio de exemplo por um `stage` por passo, em ordem de dependência. Use os helpers 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 estágios que você escreveu.

Mantenha o nível que o template estabelece: abra a URL antes de pedir o valor dela, use `ask_secret` para tudo que for secreto, use `write_env` em todo valor persistido, use `set_secret` só nos valores que o CI realmente precisa, e use `confirm` antes de qualquer ação irreversível. Cada `stage` limpa a tela para que só o passo atual esteja visível — mantenha um estágio numa única tarefa focada, para que nada de que o humano precisa role para fora da tela. Não toque na biblioteca acima do marcador.

### 4. Verifique e entregue

- `bash -n <script>`; rode `shellcheck` se disponível.
- `chmod +x <script>`.
- Não rode o script de ponta a ponta você mesmo — ele abre navegadores e bloqueia esperando input humano. Em vez disso, trace-o estaticamente: todo valor do passo 1 é capturado e vai parar onde o passo 1 disse, e todo nome em `set_secret` bate exatamente com uma referência `secrets.*` no CI.
- Diga ao usuário como rodá-lo. Se for um caminho de setup repetível, faça commit e linke-o do README, para que a próxima pessoa rode o script em vez de perguntar a uma IA.

From leandrocfe/skills, MIT.

More from leandrocfe/skills