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 (log out and back in)
  Dev server:   http://myapp.local:3000

Dry Run Output

[setup:dry-run] Would execute: setup.manifest.yaml
  Platform: linux/ubuntu/x86_64
  Install type: developer

  OS Config (2 entries, 1 needs configuration):
    ✓ docker-group: already configured
    ✗ inotify-watches: needs configuration (current: 8192, required: 524288)

  Step 1: clone (script)
    script: installer/scripts/clone.sh
    env:    INSTALL_DIR=/opt/myapp BRANCH=main
    verify: test -d ${INSTALL_DIR}/.git

  Step 2: apply-inotify (os-config)
    config_id: inotify-watches
    platform:  linux

  Step 3: configure-dev (script)
    script: installer/scripts/dev/configure-dev.sh

  Step 4: verify-dev (script)
    script: installer/scripts/dev/verify-dev.sh

Recovery Handling

When a step fails and a recovery procedure matches:

[setup] Step 'clone' failed:
  Error: destination path already exists and is not empty

Recovery procedure 'full-reset' is available:
  This will: remove /opt/myapp and re-clone from git

Proceed with recovery? [y/N]: _

Never run destructive recovery steps without explicit user confirmation.

Agentic Steps

When a step has

type: agentic

, the skill delegates to

installer-agent

with the step's

instruction

field as context, plus:

• The full manifest (for environment context)
• The current param values
• The failure output from any preceding script attempt

The installer-agent must explain what it detects and what it will do before making changes.

References

• Schema:

  agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json

• Agent:

  agentic/code/addons/agentic-installer/agents/installer-agent.md

• Script lib:

  agentic/code/addons/agentic-installer/scripts/lib/

• Generate skill:

  agentic/code/addons/agentic-installer/skills/setup-generate/SKILL.md