wizard

Files (3)

• LICENSE
• SKILL.md
• template.sh

SKILL.md (first lines)

<!--
Modified copy of https://github.com/mattpocock/skills/tree/3cca18b368ae95cdbdebbff572ccafa662551015/skills/engineering/wizard
(mattpocock-skills v1.2.3). Copyright (c) 2026 Matt Pocock, MIT — see LICENSE.
Changes: every captured value declares a destination (ci, box, local); box values
are recorded with `box_ref` and the closing summary prints the exact 1Password
reference lines for the box's env template plus the not-live-until-converged
warning.
-->

# Wizard

A **wizard** is a bash script that walks a human, step by step, through a manual procedure that's tedious to do by hand and tedious to re-explain to an AI every time. It opens each URL, says exactly what to click and copy, captures the values, writes them where they belong (`.env`, GitHub secrets, 1Password for the box), confirms at every stage, and shows how many stages are left. It might configure third-party services, run a one-off migration, or move the project from one state to another.

The delightful UX is already solved by [template.sh](template.sh): stage-by-stage progress, confirmation gates, cross-platform URL opening (including WSL), hidden secret entry, idempotent `.env` upserts, `gh secret`/`gh variable` writes, box credential references, and a closing summary. **Your job is only to scope the procedure and author its stages.** The library above the `STAGES` marker is identical in every wizard; that consistency is the point: never hand-edit it.

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

## Destinations

Every captured value has exactly one of three destinations, decided in step 1 and visible in the script:

| Destination | Meaning | Helper |
|---|---|---|
| `ci` | GitHub Actions reads it | `set_secret` / `set_var` |
| `box` | The agent-ops box reads it from 1Password through its env template | `box_ref KEY "op://agent-ops/<item>/<FIELD>"` after the human stores it |
| `local` | Only this machine's `.env` needs it | `write_env` alone |

A value can also be written to `.env` for local development on top of `ci` or `box`. The box is the one that silently fails: a wizard that captures a value the box needs but stops at the laptop finishes green while the box still cannot see it. `box_ref` is what makes that visible.

## Process

### 1. Scope the procedure

Work out every manual step the human must take and every value that gets captured along the way. Read the repo first, don't ask cold:

- For setup: `.env`, `.env.example`, `.env.*`, `README`, `docker-compose*`, framework config, and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the wizard must produce). For anything the box runs, also the env template in agent-ops (`provision/op.env.tpl`): every key there is a `box` value.
- For a migration or transition: the current state, the target state, and the irreversible actions between them.

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

**Done when:** every stage is named in order, and for each captured value you know (a) where the human gets it, (b) its destination (`ci`, `box` or `local`) plus whether `.env` also gets it, and (c) whether it's secret (hidden entry) or public.

### 2. Map each stage's journey

For each stage, write the precise path a human follows: which URL to open, what to do there, where a value is shown, which variable it fills: e.g. "Dashboard → Developers → API keys → Reveal test key → copy". For a `box` value the journey continues into 1Password: which vault, item and field the human stores it under, which is exactly the `op://` reference the box will read. Where you don't actually know the current UI or the exact command, say so and ask the user or check the docs: never invent steps that may not exist.

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

### 3. Author the wizard

Copy `template.sh` to the target path. Replace the example stage with one `stage` per step, in dependency order. Use the library helpers: `stage`, `say`/`step`, `open_url`, `ask`/`ask_secret`, `write_env`, `set_secret`/`set_var`, `box_ref`, `pause`/`confirm`. Set `TOTAL_STAGES` to the number of stages you wrote.

Hold the bar the template sets: open the URL before asking for its value, use `ask_secret` for anything secret, `write_env` every value local development needs, `set_secret` only the values CI actually needs, `box_ref` every value the box needs (after a `step` telling the human where to store it in 1Password and a `pause`), and `confirm` before any irreversible action. Each `stage` clears the screen so only the current step is visible: keep a stage to one focused task so nothing the human needs scrolls away. Don't touch the library above the marker.

### 4. Verify and hand off

- `bash -n <script>`; run `shellcheck` if available.
- `chmod +x <script>`.
- Don't 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 and lands where step 1 said, every `set_secret` name exactly matches a `secrets.*` reference in CI, and every `box_ref` key matches a key the box's env template has or will get.
- Tell the user how to run it, and repeat what the closing summary will say: box values are not live until the env template change is merged in agent-ops and the box has converged. If it's a repeatable setup path, commit it and link it from the README so the next person runs the script instead of asking an AI.

From jesdi/general-skills, MIT.

More from jesdi/general-skills