One-command onboarding for new laptops

A new engineer joins. You point them at SETUP.md. It says install Homebrew, then "the usual tools," then run a script that hasn't worked since the team switched to a new package manager. By lunch they've installed two versions of Node, missed a dependency three steps later, and you've both lost an afternoon.

Setup docs rot because prose can't be run. The only thing that stays correct is something you actually execute on every fresh machine. So make day-one setup a task: check what's already there, install what's missing, configure the rest — and make it safe to run twice, because the first run never goes cleanly.

A setup task that's safe to re-run

Two properties make this work. First, it asserts its prerequisites up front, so it fails with a clear message instead of halfway through. Second, it's idempotent: an if: guard skips the install when the tools are already present, so re-running after a hiccup doesn't double-install anything.

name: onboarding
# Idempotent: re-running is safe — it checks before it installs.
defaults:
  installed: "false"

tasks:
  # `orchstep run setup`
  setup:
    steps:
      - name: detect
        func: shell
        do: echo "checking for git, node, docker..."
        outputs:
          tools: "git node docker"
      - name: assert-prerequisites
        func: assert
        args:
          condition: '{{ ne steps.detect.tools "" }}'
          message: "expected git, node and docker on PATH"
      - name: install
        if: '{{ eq vars.installed "false" }}'
        then:
          - name: brew-bundle
            func: shell
            do: echo "brew bundle --file Brewfile"
        else:
          - name: skip
            func: shell
            do: echo "tools already present, skipping install"
      - name: configure
        func: shell
        do: echo "linking dotfiles and writing config (safe to repeat)"
      - name: done
        func: shell
        do: echo "laptop is ready to commit"

The assert step is the contract: if the detection turns up nothing, the run stops with expected git, node and docker on PATH instead of failing five steps later with a confusing error. The if: / then: / else: block is the idempotency: the second run takes the skip path instead of reinstalling.

Run it

orchstep run setup

That's the whole onboarding instruction now. Not "follow the wiki" — one command that does the same thing on every machine. The demo echos each action so you can watch the plan; swap the echos for brew bundle, mise install, and your dotfile linker to make it real.

Run it again — on purpose

The first setup run on a real laptop never finishes clean. A network blip, a tool already half-installed, a prompt you missed. So you fix the snag and run it again:

orchstep run setup --var installed=true

Because the install is guarded by an if:, the second run skips what's already done and only completes the rest. Idempotent setup means "run it until it's green" is a safe instruction, not a gamble.

See the plan first

New hire nervous about what a setup script will do to their machine? Show them:

orchstep run setup --dry-run

The resolved plan prints every step — including which branch of the if: will run — without touching the machine. Full tour: Previewing with Dry Run.

What you actually gained

OrchStep doesn't replace brew or your dotfiles — it makes the sequence something you run instead of something you read. If a single well-maintained bootstrap script already onboards people cleanly, keep it. When your setup doc is prose nobody trusts, this is the fix.

Where to go next

• The assert function — turn prerequisites into a contract
• Quick Start — your first workflow in two minutes
• Variables & Outputs — conditionals and the scoping model

Got a SETUP.md that's always one package manager behind? Make it a task that asserts its prerequisites and is safe to run twice.