wizard is a bash script that walks a person step by step through a manual process: the kind of process that is tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, states exactly what to click and what to copy, captures those values, writes them where they belong (.env, GitHub secrets), confirms at each stage, and shows how many stages remain. It might be used to configure a third-party service, run a one-off migration, or move a project from one state to another.
The excellent UX is already handled by template.sh : stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret input, idempotent .env upserts、gh secret/gh variable writes, and a closing summary.Your job is only to scope the process and write its individual stages. STAGES The library above the marker is identical in every wizard; this consistency is the point: never edit it by hand.
Wizards are ephemeral by default: built for a single run, saved to scratch or a scripts/ path, and deleted once the task is done. Commit it only when the user wants a repeatable setup path that should stay in the repo.
Process
1. Scope the process
Figure out every manual step the person must perform, and every value captured along the way. Read the repo first; don't ask out of thin air:
- For setup:
.env、.env.example、.env.*、README、docker-compose*, framework config, and.github/workflows/*(everysecrets.*/vars.*reference is a value the wizard must produce). - For a migration or transition: the current state, the target state, and the irreversible operations between them.
Then show the user the ordered list of stages and the value each stage produces, and confirm: they may add, remove, or reorder them.
Done when: Each stage is named in order, and for every captured value you know (a) where the person gets it from, (b) where it gets written (.env, a GitHub secret, both, or neither; some stages are purely operational), and (c) whether it is a secret (hidden input) or public.
2. Map out the path for each stage
For each stage, write the precise path the person follows: which URL to open, what to do there, where the value is displayed, which variable it fills, e.g. "Dashboard → Developers → API keys → Reveal test key → copy". Where you genuinely do not know the current UI or the exact command, say so honestly and ask the user or check the documentation: never invent steps that may not exist.
Done when: Every stage can be traced back to concrete instructions a stranger could follow.
3. Write the wizard
Copy template.sh to the target path. Replace the example stage with one stage per step, arranged in dependency order. Use the library helpers (stage、say/step、open_url、ask/ask_secret、write_env、set_secret/set_var、pause/confirm), and set TOTAL_STAGES to the number of stages you wrote.
Hold to the standard set by the template: open a URL before asking for its value, use ask_secretfor any secret, use write_envfor every persisted value, use set_secretonly for values CI actually needs, and before any irreversible operation confirm. Each stage clears the screen, so only the current step is shown: keep a stage focused on one task, so what the person needs does not scroll out of view. Do not touch the library above the marker.
4. Verify and hand off
bash -n <script>; if available, runshellcheck。chmod +x <script>。- Do not run it end to end yourself: it will open a browser and block on human input. Instead, trace it statically: every value in step 1 is captured and lands where step 1 says it lands, and every
set_secretname exactly matches somesecrets.*reference in CI. - Tell the user how to run it. If it is a repeatable setup path, commit it and link to it from the README, so the next person runs the script instead of asking an AI.