setup-wizard-generator

1---2name: setup-wizard-generator3description: "Generate a bash wizard guiding a human through manual setup."4version: 1.0.05author: "Matt Pocock (mattpocock/skills, wizard) + Hermes Agent"6license: MIT7platforms: [linux, macos]8metadata:9  hermes:10    tags: [wizard, setup, onboarding, credentials, secrets, migration, bash, human-in-the-loop]11    related_skills: []12---13 14# Setup Wizard Generator15 16Generates an interactive bash **wizard**: a script that walks a human, step17by step, through a manual procedure that is tedious to do by hand and tedious18to re-explain every time. It opens each URL, says exactly what to click and19copy, captures the values, writes them where they belong (`.env`, GitHub20secrets), confirms at every stage, and shows how many stages are left.21 22Ported from mattpocock/skills' MIT-licensed `wizard` skill.23 24## When to Use25 26- Provisioning infrastructure or third-party services (Stripe, Supabase,27  DNS, OAuth apps) where only a human can click through the dashboard28- Setting up credentials, CI secrets, or repo variables29- One-off migrations or cutovers with irreversible human-gated steps30- Any procedure the user will hand to a teammate to run31 32Do NOT use for steps the agent can perform itself — do those directly.33 34## Prerequisites35 36- `bash`; `gh` CLI only if stages write GitHub secrets/variables37- The library template: `templates/template.sh` in this skill's directory38 39## Procedure40 41### 1. Scope the procedure42 43Work out every manual step the human must take and every value captured44along the way. Read the repo first, don't ask cold:45 46- Setup: `.env`, `.env.example`, `README`, `docker-compose*`, framework47  config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference48  is a value the wizard must produce).49- Migration/cutover: the current state, the target state, and the50  irreversible actions between them.51 52Show the user the ordered stage list and the values each produces; they may53add, drop, or reorder. Done when every stage is named in order and, for each54captured value, you know (a) where the human gets it, (b) where it's written55(`.env`, a GitHub secret, both, or nowhere), and (c) whether it's secret56(hidden entry) or public.57 58### 2. Map each stage's journey59 60For each stage, write the precise path a human follows: which URL to open,61what to do there, where the value is shown — e.g. "Dashboard → Developers →62API keys → Reveal test key → copy". Where you don't know the current UI or63exact command, say so and check the docs or ask — never invent steps that64may not exist.65 66### 3. Author the wizard67 68Copy `templates/template.sh` (from this skill's directory) to the target69path. Replace the example stage with one `stage` per step, in dependency70order. Set `TOTAL_STAGES` to the number of stages you wrote.71 72Library helpers: `stage`, `say`/`step`/`note`/`warn`, `open_url`,73`ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `pause`/`confirm`,74`banner`, `finish`. The library above the `STAGES` marker is identical in75every wizard — never hand-edit it; that consistency is the point.76 77Hold the bar the template sets: open the URL before asking for its value,78`ask_secret` for anything secret, `write_env` every persisted value,79`set_secret` only what CI actually needs, and `confirm` before anything80irreversible. Each `stage` clears the screen — keep one focused task per81stage so nothing the human needs scrolls away.82 83A wizard is ephemeral by default: save it to a scratch or `scripts/` path,84delete it when the job's done. Commit it only when the user wants a85repeatable setup path living in the repo.86 87### 4. Verify and hand off88 89- `bash -n <script>`; run `shellcheck` if available; `chmod +x <script>`.90- Do NOT run it end-to-end yourself: it opens browsers and blocks on human91  input. Trace it statically: every value from step 1 is captured and lands92  where step 1 said, and every `set_secret` name exactly matches a93  `secrets.*` reference in CI.94- Tell the user how to run it. If it's repeatable, commit it and link it95  from the README.96 97## Pitfalls98 991. **Editing the library section.** Everything above the `STAGES` marker is100   the wizard library; author only below it.1012. **Inventing dashboard paths.** Third-party UIs drift. If unsure of the102   click path, verify against current docs or flag it as approximate.1033. **`set_secret` for values CI doesn't use.** Only push to GitHub secrets104   what a workflow actually references.1054. **Running the wizard yourself.** It blocks on human input; static tracing106   plus `bash -n` is the verification.1075. **One mega-stage.** Screen clearing per stage means a long stage scrolls108   critical instructions away; split it.109 110## Verification111 112- [ ] Stage list confirmed with the user before authoring113- [ ] `bash -n` passes; script is executable114- [ ] Every captured value traced to its declared destination115- [ ] Every `set_secret` name matches a CI `secrets.*` reference116- [ ] Library section untouched from the template117