---
name: wizard
description: Use when a procedure needs a human at the keyboard, meaning provisioning infrastructure, setting up credentials or CI secrets, clicking through an unfamiliar third-party dashboard, or running a one-off migration or cutover. Not for steps you can perform yourself.
---

# Wizard

A **wizard** is a bash script that walks a human, step by step, through a manual procedure that is
tedious to do by hand and tedious to re-explain to an agent every time. It opens each URL, says
exactly what to click and copy, captures the values, writes them where they belong, confirms before
anything irreversible, and shows how many stages are left.

The UX is already solved by [template.sh](template.sh): stage-by-stage progress, confirmation gates,
cross-platform URL opening, hidden secret entry, idempotent `.env` upserts, CI secret writes, and a
closing summary of what was set and what still needs doing by hand.

**Your job is only to scope the procedure and author its stages.** The library above the `STAGES`
marker is identical in every wizard, and that sameness is the point. Never hand-edit it.

A wizard is ephemeral by default: built for one run, saved to a scratch path or `scripts/`, deleted
when the job is done. Commit it only where the user wants a repeatable setup path living in the repo.

**Where you could just do it yourself, do it yourself.** This is for the steps where a human is
genuinely in the loop.

## 1. Scope the procedure

Work out every manual step the human must take and every value captured along the way. Read the repo
first rather than asking cold:

- **For setup**: `.env`, `.env.example`, `.env.*`, the README, `docker-compose*` or `Containerfile`,
  framework config, and CI workflow files. Every `secrets.*` or `$CI_` reference is a value the wizard
  must produce.
- **For a migration or cutover**: the current state, the target state, and every irreversible action
  in between.

Then show the ordered list of stages and the values each produces, and confirm. They may add, drop,
or reorder.

**Done when**, for every captured value, you know where the human gets it, where it is written
(`.env`, a CI secret, Infisical, several of those, or nowhere for a pure action stage), and whether it
is secret and so needs hidden entry.

## 2. Map each stage's journey

For each stage, write the precise path a human follows: which URL, what to do there, where the value
is shown, which variable it fills.

> Dashboard → Developers → API keys → Reveal test key → copy

Where you do not actually know the current UI or the exact command, **say so and ask, or check the
docs.** Never invent steps that may not exist: a wizard confidently naming a button that is not there
is worse than no wizard, because the human trusts it.

**Done when** every stage traces to concrete instructions a stranger could follow.

## 3. Author it

Copy `template.sh` to the target path. Replace the example stage with one `stage` per step in
dependency order, and set `TOTAL_STAGES` to match.

Use the library helpers:

| Helper | Does |
|---|---|
| `stage "Name"` | Clears the screen, announces the stage, shows progress |
| `say` / `step` / `note` / `warn` | Instruction lines |
| `open_url URL` | Opens it in the human's browser |
| `ask KEY "Prompt"` / `ask_secret KEY "Prompt"` | Reads a value, hidden for secrets, offering the existing `.env` value on a re-run |
| `write_env KEY VALUE` | Idempotent upsert into `.env` |
| `set_secret` / `set_var` | Writes a CI secret or variable, detecting GitHub or GitLab from the git remote |
| `set_infisical KEY VALUE` | Writes to Infisical, honouring `INFISICAL_ENV` (default `dev`) |
| `pause` / `confirm` | Waits, or gates an irreversible action behind y/N |

Hold the bar the template sets: open the URL **before** asking for its value, `ask_secret` anything
secret, `write_env` every persisted value, `set_secret` only what CI actually needs, and `confirm`
before anything irreversible.

Each `stage` clears the screen, so keep a stage to one focused task and nothing the human still needs
scrolls away.

**Verify the CLI invocations you rely on.** `set_secret` degrades to a warning rather than failing,
so a wrong flag silently becomes a manual to-do. Where a stage depends on a `glab`, `gh`, or
`infisical` command, confirm the syntax against its `--help` before shipping.

## 4. Verify and hand off

- `bash -n <script>`, and `shellcheck` where it is installed
- `chmod +x <script>`
- **Do not run it end to end yourself.** It opens browsers and blocks on human input. Trace it
  statically instead: every value from step 1 is captured, lands where step 1 said it would, and
  every `set_secret` name exactly matches the reference in CI.
- Tell the user how to run it. Where it is a repeatable setup path, commit it and link it from the
  README so the next person runs the script instead of asking an agent.

## Done when

- Every stage is a step only a human can take.
- Every captured value has a known source, a known destination, and correct secrecy.
- No step names a button or command you have not verified exists.
- The script passes `bash -n`, is executable, and was traced statically rather than run.
