Wizard
A wizard is a bash script that walks a human through a manual procedure: it
opens each URL, says what to click and copy, captures the values, writes them where
they belong, confirms at every stage, and shows how many stages are left.
The UX lives in scripts/template.sh: stage progress, confirmation gates,
cross-platform URL opening, hidden secret entry, idempotent .env upserts,
gh secret / gh variable writes, and a closing summary. Scope the procedure and
author its stages. The library above the STAGES marker is identical in every
wizard.
Resolve every .agents/projects/ path from the repository root; never read or write
project artifacts in a global agent-installation directory.
A wizard is ephemeral by default. Write it to
.agents/projects/<project>/wizard-<slug>.sh. Commit it into the repository's
scripts/ only when the user wants a repeatable setup path.
Process
Scope every manual step and every value captured along the way. Read the repo
first: .env, .env.example, .env.*, README, compose files, framework config,
and .github/workflows/* (every secrets.* / vars.* reference is a value the
wizard must produce). For a migration, name current state, target state, and the
irreversible actions between them. Show the ordered stages and the values each
produces. Do not author the script until the user confirms the list.
Done when every stage is named in order, and for each captured value you know
where the human gets it, where it is written (.env, a GitHub secret, both, or
nowhere), and whether it is secret.
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. Check the current
UI or docs when the path is unknown.
Done when every stage traces to instructions a stranger could follow.
Copy scripts/template.sh to the target path. Replace the example 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, pause / confirm. Set TOTAL_STAGES to match.
Open the URL before asking for its value. Use ask_secret for secrets.
write_env every persisted value. set_secret only the values CI needs.
confirm before any irreversible action. Keep each stage to one focused task.
Leave the library above the marker untouched.
Done when the stages below the marker match the confirmed list.
Run bash -n on the script, and shellcheck when available. Make it executable.
Trace it statically: every value from step 1 is captured and lands where step 1
said, and every set_secret name matches a secrets.* reference in CI. Tell the
user how to run it. Trace rather than running it; it opens browsers and blocks
on human input.
Done when the script is syntactically valid, the static trace matches the
confirmed list, and the user has the command to run it.
Done when
- The confirmed stages are authored below the
STAGES marker.
- Captured values land in
.env and CI secrets as scoped.
- The user has the path and the command to run the wizard.
1---2name: wizard3description: Interactive bash wizard for steps only a human can perform. Use when provisioning infrastructure, setting up credentials or CI secrets, walking a third-party dashboard, or running a one-off migration or cutover.4---56# Wizard78A **wizard** is a bash script that walks a human through a manual procedure: it9opens each URL, says what to click and copy, captures the values, writes them where10they belong, confirms at every stage, and shows how many stages are left.1112The UX lives in `scripts/template.sh`: stage progress, confirmation gates,13cross-platform URL opening, hidden secret entry, idempotent `.env` upserts,14`gh secret` / `gh variable` writes, and a closing summary. Scope the procedure and15author its stages. The library above the `STAGES` marker is identical in every16wizard.1718Resolve every `.agents/projects/` path from the repository root; never read or write19project artifacts in a global agent-installation directory.2021A wizard is ephemeral by default. Write it to22`.agents/projects/<project>/wizard-<slug>.sh`. Commit it into the repository's23`scripts/` only when the user wants a repeatable setup path.2425## Process26271. Scope every manual step and every value captured along the way. Read the repo28 first: `.env`, `.env.example`, `.env.*`, README, compose files, framework config,29 and `.github/workflows/*` (every `secrets.*` / `vars.*` reference is a value the30 wizard must produce). For a migration, name current state, target state, and the31 irreversible actions between them. Show the ordered stages and the values each32 produces. Do not author the script until the user confirms the list.3334 Done when every stage is named in order, and for each captured value you know35 where the human gets it, where it is written (`.env`, a GitHub secret, both, or36 nowhere), and whether it is secret.37382. For each stage, write the precise path a human follows: which URL to open, what39 to do there, where a value is shown, which variable it fills. Check the current40 UI or docs when the path is unknown.4142 Done when every stage traces to instructions a stranger could follow.43443. Copy `scripts/template.sh` to the target path. Replace the example with one45 `stage` per step, in dependency order. Use the library helpers: `stage`,46 `say` / `step`, `open_url`, `ask` / `ask_secret`, `write_env`,47 `set_secret` / `set_var`, `pause` / `confirm`. Set `TOTAL_STAGES` to match.48 Open the URL before asking for its value. Use `ask_secret` for secrets.49 `write_env` every persisted value. `set_secret` only the values CI needs.50 `confirm` before any irreversible action. Keep each stage to one focused task.51 Leave the library above the marker untouched.5253 Done when the stages below the marker match the confirmed list.54554. Run `bash -n` on the script, and `shellcheck` when available. Make it executable.56 Trace it statically: every value from step 1 is captured and lands where step 157 said, and every `set_secret` name matches a `secrets.*` reference in CI. Tell the58 user how to run it. Trace rather than running it; it opens browsers and blocks59 on human input.6061 Done when the script is syntactically valid, the static trace matches the62 confirmed list, and the user has the command to run it.6364## Done when6566- The confirmed stages are authored below the `STAGES` marker.67- Captured values land in `.env` and CI secrets as scoped.68- The user has the path and the command to run the wizard.
akathecoder