/setup-run

namespace: aiwg
name: setup-run
platforms: [all]
description: "Execute a `setup.aiwg.io/v1` SetupManifest, performing cross-platform installati"

setup-run

Execute a `setup.aiwg.io/v1` SetupManifest, performing cross-platform installation step by step.

Trigger Phrases

• "run the setup manifest"
• "install using setup.manifest.yaml"
• "execute installer for [project]"
• "aiwg setup-run [manifest]"
• "run setup for [project]"
• "run dev setup for [project]"

Parameters

manifest (positional, optional)

Path to the `setup.manifest.yaml`. Default: `./setup.manifest.yaml`.

--dry-run (optional)

Print what would be executed without running any scripts.

--platform (optional)

Override platform detection: `linux`, `macos`, `windows`, `wsl2`.

--distro (optional)

Override distro detection: `ubuntu`, `debian`, `fedora`, `arch`, etc.

--params-file (optional)

Path to a YAML file with pre-set param values (avoids interactive prompts).

--step (optional)

Run only a specific step by `id`. Useful for resuming after failure.

--skip (optional)

Comma-separated step IDs to skip.

--type (optional)

Filter which manifest to run by install type: `user`, `developer`, or `ci`.

When `--type developer` is specified and no manifest path is given, the skill looks for `installer/setup.dev.manifest.yaml` before falling back to `setup.manifest.yaml`. When `--type user` is specified, the skill looks for `installer/setup.user.manifest.yaml`.

Execution Flow

Phase 1: Load and Validate

1. Read the manifest file 2. Validate against `setup.aiwg.io/v1` schema (run setup-validate internally) 3. If invalid, report errors and stop — do not attempt partial execution

Phase 2: Platform Detection

1. Detect OS: `uname -s` (Linux/Darwin) or `$PSVersionTable` (Windows) 2. Detect distro: `/etc/os-release` → `ID` field 3. Detect arch: `uname -m` 4. Detect shell: `$SHELL` or `$0` 5. Match against manifest `platform` block — if no match, warn and ask to proceed or abort

Phase 3: Param Collection

For each param in manifest `params`: 1. Check if already set in environment or `--params-file` 2. If `required: true` and no value: prompt interactively 3. If `interactive_required: true`: always prompt interactively, even if a default exists — do not use the default without asking 4. If `choices` list present: validate input against choices 5. Expand `~` and `$HOME` in `type: path` params

Phase 4: Prerequisite Check

For each prerequisite: 1. Run `detect` command 2. If `version_min` set: compare version output against minimum 3. On failure: print `install_hint` and stop with non-zero exit

Phase 5: OS Config Summary (developer manifests only)

When `metadata.install_type` is `developer` and the manifest has an `os_config` block:

1. Run each `os_config` entry's `check` command 2. Collect entries where `check` returns non-zero (needs configuration) 3. Print a summary of OS mutations that will be made:

   [setup] OS Configuration Required

   The following OS-level changes will be made:
     • docker-group: Add user 'alice' to docker group (requires re-login)
     • inotify-watches: Set fs.inotify.max_user_watches=524288

   These changes require elevated privileges (sudo).

4. Ask for explicit user confirmation before proceeding with any `os-config` steps:

   Proceed with OS configuration? [y/N]:

5. If denied, skip all `os-config` steps and warn that the environment may be incomplete.

Never apply OS mutations without this explicit confirmation. This is a separate gate from the normal params phase.

Phase 6: Step Execution

Execute steps in dependency order:

For each step (respecting depends_on order):
  1. Evaluate `when` condition — skip step if false
  2. Skip steps not applicable to current platform
  3. Dispatch by step type:
     - script:         run the script with params as env vars
     - detect:         run detect command, set env var with result
     - ask:            prompt user, set param
     - verify:         run verify expression; fail if false
     - agentic:        delegate to installer-agent with instruction
     - platform-route: resolve platform → script path, run script
     - chain:          run aiwg setup-run on sub-manifest
     - os-config:      run the referenced os_config entry (see below)
  4. Run `verify` expression if present
  5. On failure:
     a. Check recovery_procedures for a matching trigger
     b. If found: show recovery plan and ask user to confirm before running
     c. If not found or recovery fails: report step ID + error, stop

os-config Step Execution

When executing an `os-config` step:

1. Look up the `config_id` in the manifest's `os_config` block 2. Run the `check` command — if exit 0, print "already configured" and skip 3. If the entry has `interactive: true`:

• Print an explanation of what the `apply` command will do
• Warn: "This step will trigger an interactive dialog or GUI prompt."
• Ask for user acknowledgment before running:

     [setup] Interactive step: xcode-cli-tools
     This will trigger the Xcode Command Line Tools installation dialog.
     Acknowledge and continue? [y/N]:

4. Run the `apply` command 5. If the entry has `requires_relogin: true`:

• After the step completes, pause and print:

     [setup] NOTICE: docker-group requires re-login to take effect.
     Log out and back in, then re-run setup-run with --step <next-step-id>
     to continue from where you left off.

     Continue (if you have already re-logged in)? [y/N]:

Phase 7: Completion Report

[setup] Installation complete

  Steps run:    4/4
  Steps skipped: 0
  Duration:     45s

  Installed to: /opt/myapp
  Config dir:   ~/.config/myapp

Run `myapp --version` to verify.

For developer installs, also report:

[setup] Developer environment ready

  OS config applied: docker-group, inotify-watches
  Re-login required: docker-group (l