Human Step Wizard

Some steps in an otherwise automated task need a person: creating a token in a
dashboard, approving a DNS change, rotating a key the agent must never see,
cutting traffic over at a moment someone chose. The usual hand-off is a
paragraph of instructions in chat, which the human skims, half-follows, and
reports back on from memory. This skill replaces that paragraph with a
generated bash wizard: one step at a time, the exact link to open, hidden
prompts for secrets, format validation on every pasted value, checks that
confirm the step really happened, a typed confirmation before anything
irreversible, and progress saved so the human can stop and resume.

The agent writes a small JSON spec; the tools validate it and generate the
script. This is distinct from engineering/runbook-generator, which produces
static operational documentation. A wizard is executable, interactive and
tied to one concrete task.

When to use this skill

• Credentials only a human can create: first admin token, OAuth app, API

keys behind MFA, values the agent must not see

• Approvals and authority: DNS changes, change tickets, spending, accepting terms
• Rotations: roll a secret, deploy it, verify, revoke the old one
• Cutovers: DNS, load balancer, database primary, feature launch at a chosen time
• Onboarding setup: a new developer wiring up a dozen third-party accounts

into .env and CI secrets

Not for steps the agent can perform itself; do those directly.

Clarify First

The procedure, not the script, is the hard part, and its details live with the
human. Settle the inputs below before writing the spec. When one is missing or
vague and would change the result, ask about it; when it wouldn't, use a
sensible default and say which one you used.

• The step list and which step is irreversible: this sets the order (gather

and verify everything before the point of no return) and where the typed
confirmation goes.

• Where each value goes: env file, CI secret, both, or nowhere. Values a

later check or the application needs must be stored, and secrets must not be
stored more widely than they are used.

• Exact dashboard paths: if the agent is not sure of the current UI, it asks

or links the page instead of inventing menu names.

• How to verify each step from outside: a dig, curl, gh or test

command that proves the outcome; without it, the wizard trusts the Enter key.

Ask about the two or three inputs that matter most for this request, not the
whole list. If the user wants a result straight away, generate from what you
know and state your assumptions at the top of your reply.

Quick Start

# 1. Validate the spec (exit 1 on errors)
python3 engineering/human-step-wizard/scripts/wizard_spec_validate.py \
  --spec engineering/human-step-wizard/assets/sample_wizard_spec.json

# 2. Generate the wizard (runs bash -n on the output)
python3 engineering/human-step-wizard/scripts/wizard_generate.py \
  --spec engineering/human-step-wizard/assets/sample_wizard_spec.json --out scripts/cutover-wizard.sh

# 3. Hand it to the human
./scripts/cutover-wizard.sh          # --list, --from STEP, --reset, --help

Tools Overview

Both tools take --format text|json. The generator also takes --stdout to
print the script and --force to overwrite an existing file.

Generated wizard behaviour

Workflows

Workflow 1: Hand a human step to a person [RECOMMENDED]

1. Do every step the agent can do first. Collect what remains and confirm the

list, order and irreversible step with the user.

1. For each human step, write the navigation path, the value(s) produced, where

each value goes, and a command that proves the step happened.

1. Write the spec (start from assets/sample_wizard_spec.json).
2. Validate with --strict; fix every error and justify every remaining warning.
3. Generate the script. Add the env file to .gitignore.
4. Tell the human the command, the time it takes, any waiting periods, and which

step is irreversible. Wait for them; do not run it yourself.

python3 engineering/human-step-wizard/scripts/wizard_spec_validate.py \
  --spec engineering/human-step-wizard/assets/sample_wizard_spec.json --strict --format json
python3 engineering/human-step-wizard/scripts/wizard_generate.py \
  --spec engineering/human-step-wizard/assets/sample_wizard_spec.json --stdout > /tmp/wizard.sh
bash -n /tmp/wizard.sh && echo syntax-ok

Workflow 2: Verify a wizard before hand-off

The agent cannot complete the wizard (it blocks on human input), so it validates
the script statically and with a scripted run in a scratch directory:

1. bash -n (the generator already did) and shellcheck -S warning if installed.
2. Copy the spec, replace network checks with local ones (test -n "$VAR"),

generate, and pipe answers in, including a hostile value such as
$(touch PWNED).

1. Verify that the env file holds the literal values, that no PWNED file

appeared, that --list shows the right progress after an abort, and that a
re-run resumes at the right step.

printf '%s\n' 'first-answer' 'abc' 'step-id' '' | \
  WIZARD_ALLOW_NONINTERACTIVE=1 WIZARD_STATE_DIR=./state bash wizard.sh

Workflow 3: Fix a rejected spec

python3 engineering/human-step-wizard/scripts/wizard_spec_validate.py \
  --spec engineering/human-step-wizard/assets/sample_wizard_spec_flawed.json

The flawed sample fails on purpose (exit 1) with eight errors: a non-slug
slug, a lowercase variable name, eval in a check, a value used before it is
captured, a duplicate step id, an irreversible step without rollback, a \d
pattern bash cannot match, and an input named PATH. Fix in that order:
naming errors first, because later rules depend on names resolving.

Spec Format

{
  "title": "Move api.example.com to the new load balancer",
  "slug": "api-lb-cutover",
  "env_file": ".env.cutover",
  "steps": [
    {
      "id": "cutover-dns",
      "title": "Point api.example.com at the new load balancer",
      "instructions": ["DNS -> Records -> api.example.com (A) -> Edit.", "Set the new address and save."],
      "url": "https://dash.dns-provider.example/example.com/dns/records",
      "inputs": [{"name": "NEW_LB_IP", "prompt": "New IPv4", "pattern": "^([0-9]{1,3}\\.){3}[0-9]{1,3}$", "store": "env"}],
      "checks": [{"description": "DNS returns the new address", "command": "dig +short api.example.com A | grep -qxF \"$NEW_LB_IP\""}],
      "irreversible": true,
      "rollback": "Set the A record back to OLD_LB_IP from .env.cutover; 60 s TTL.",
      "pause": true,
      "allow_skip": false
    }
  ]
}

Anti-Patterns

The Chat Runbook

Mistake: Pasting ten numbered steps into the chat and asking the human to "let me know when done".
Why it happens: It is the fastest thing for the agent to produce.
Instead: Generate a wizard. The human sees one step at a time, values are captured and validated where they are produced, and the agent gets a verifiable result instead of "done, I think".

The Trust-the-Enter-Key Wizard

Mistake: Steps with a pause and no check, so pressing Enter marks them done.
Why it happens: Writing a check means knowing how to observe the outcome, which takes thought.
Instead: Attach a check that observes the world from outside (dig, curl, gh secret list, test -s). The validator warns on irreversible steps without one.

The Late Rollback Data

Mistake: Asking the human to change the DNS record without first capturing the old address.
Why it happens: Rollback feels like a separate concern from the forward path.
Instead: Capture rollback inputs in an earlier step and store them, so the rollback text can point at a saved value.

The PCRE Pattern

Mistake: Validating with ^\d+$ or (?:...), copied from a Python or JavaScript regex.
Why it happens: Most regex knowledge is PCRE; bash's [[ =~ ]] silently uses POSIX ERE.
Instead: Use [0-9], [A-Za-z0-9_], [[:space:]], plain groups. The validator rejects PCRE-only syntax because the human would be told their correct value is wrong.

The Sourced Env File

Mistake: Hand-editing the generated script to source .env or eval a captured value.
Why it happens: It is the shortest way to load variables.
Instead: Regenerate from the spec. The runtime parses the env file and assigns only declared names; a pasted $(...) stays text.

Verification Checklist

• [ ] Spec validates with --strict (or each warning has a stated reason)
• [ ] Every value a later check or the application needs has store: env
• [ ] Every irreversible step has rollback text that names the saved old value
• [ ] Generated script passes bash -n (and shellcheck -S warning when available)
• [ ] Scripted run in a scratch dir: hostile input stays literal, resume works
• [ ] Env file path is gitignored; the human knows which step is irreversible

Reference Documentation

Files

Scope & Limitations

In Scope:

• Interactive bash wizards for human-only steps, generated from a validated spec.
• Validation, resumable progress, hidden secret entry, env-file storage, outside-in checks.

Out of Scope:

• Static runbooks and on-call documentation.
• Performing the human steps or driving dashboards through a browser.
• Writing to CI secret stores directly; add a check such as gh secret list or

an instruction line that tells the human which command to run.

Important Caveats:

• Requires bash 3.2+ (macOS default works) and a terminal. Windows needs WSL or Git Bash.
• Check commands are the spec author's code and run with the human's

permissions; review them like any script.

• The env file holds secrets in plain text with mode 0600; keep it out of git

and delete it when the task is finished.