Wizard is a bash script that guides a human step by step through a manual process—processes that are tedious to do by hand and troublesome to re-explain to an AI each time. It opens each URL, states exactly what to click and copy, captures values, writes them to the correct place (.env, GitHub secrets), confirms at each stage, and shows the number of remaining stages. It may configure a third-party service, run a one-time migration, or move a project from one state to another.
The convenient UX is already handled by template.sh —staged progress display, confirmation gates, cross-platform URL opening (including WSL), hidden secret input, idempotent .env writes,gh secret/gh variable writes, and an end-of-run summary.Your job is only to scope the process and write its stages. The library code above the STAGES marker in every wizard is the same—this consistency is exactly the point, and it should never be edited by hand.
Wizards are temporary by default—created for a single run, kept in scratch or a scripts/ path, and deleted once the task is complete. Commit one only when the user wants a repeatable setup path (one that should remain in the repository).
Process
1. Scope the process
Identify every manual step the human must perform and every value captured along the way. Read the repository first—do not ask questions out of thin air:
- For setup:
.env、.env.example、.env.*、README、docker-compose*, framework configuration, and.github/workflows/*(everysecrets.*/vars.*reference is a value the wizard must produce). - For a migration or cutover: 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.
Completion criteria: Every stage is named in order, and for each captured value, you know (a) where the human gets it, (b) where it is written (.env, a GitHub secret, both, or neither—some stages are purely operational), and (c) whether it is secret (hidden input) or public.
2. Map the path for each stage
For each stage, write the exact path the human follows: which URL to open, what to do there, where the value is displayed, which variable to fill—for example "Dashboard → Developers → API keys → Reveal test key → copy". If you are unsure about the current UI or the exact command, say so and ask the user or consult the documentation—never invent steps that may not exist.
Completion criteria: Each stage can be traced back to concrete instructions that let a stranger follow along.
3. Write the wizard
Copy template.sh to the target path. Replace the example stages with one stageper step, in dependency order. Use the library helper functions—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.
Keep the standard set by the template: open the URL before asking for the value, and use ask_secret, every persisted value uses write_env, use only for values that CI actually needs set_secret, use before any irreversible operation confirm. Every stage clears the screen, making the current step the only visible content—keep one stage to one task, so what a human needs does not scroll out of view. Do not touch the library code 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 waiting for human input. Instead, trace statically: every value in step 1 is captured and written to the location specified in step 1, and every
set_secretname exactly matches thesecrets.*reference in CI. - Tell the user how to run it. If this is a repeatable setup path, commit it and link it in the README, so the next person can run the script directly instead of asking an AI for help.