Setup Run

setup-run

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

This skill executes deterministic manifests. If metadata.execution_mode: provider-orchestrated, validate the manifest and hand it to the current supported AI provider; do not begin deterministic CLI execution.

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: ${CLAUDE_PLUGIN_ROOT}/schemas/v1/setup-manifest.schema.json
• Agent: ${CLAUDE_PLUGIN_ROOT}/agents/installer-agent.md
• Script lib: ${CLAUDE_PLUGIN_ROOT}/scripts/lib/
• Generate skill: ${CLAUDE_PLUGIN_ROOT}/skills/setup-generate/SKILL.md