setup-generate

Generate a setup.manifest.yaml file for a project using the setup.aiwg.io/v1 SetupManifest language.

Trigger Phrases

"generate a setup manifest for [project]"
"create installer for [project]"
"scaffold setup manifest"
"write a setup.manifest.yaml for [directory]"
"generate install workflow for [project]"
"generate dev installer for [project]"

Parameters

project-dir (positional, optional)

Path to the project root. Defaults to ..

--from-readme (optional)

Extract requirements from README.md or INSTALL.md in the project dir.

--from-existing (optional)

Update an existing setup.manifest.yaml rather than creating from scratch.

--platforms (optional)

Comma-separated list of target platforms: linux,macos,windows,wsl2. Default: linux,macos.

--type (optional)

Install type to generate: user, developer, or ci. Default: user.

user — production/end-user deployment (default, behavior unchanged from previous versions)
developer — local development environment standup with OS configuration
ci — headless pipeline setup

When --type developer, output filename is setup.dev.manifest.yaml. When --type user, output is setup.user.manifest.yaml (or setup.manifest.yaml if no type is specified for backwards compatibility).

--interactive (optional)

Ask clarifying questions before generating.

Execution Flow

Phase 1: Discovery

Read the project root to understand structure:
- Check for package.json, requirements.txt, Cargo.toml, go.mod, Makefile, etc.
- Check for README.md, INSTALL.md, docs/install.md
- Check for existing setup.manifest.yaml
If --from-readme, parse installation instructions from readme
If --interactive, ask:
- What OSes must be supported?
- What are the hard prerequisites (git, node, python version)?
- Is there a config directory that needs to be created?
- Does the project chain sub-projects?

Developer Install Discovery (when `--type developer`)

Additional discovery steps for developer manifests:

Scan for dev-specific indicators: .nvmrc, .tool-versions, mise.toml, pyproject.toml [dev], Brewfile, .devcontainer/
Detect Docker-in-dev usage patterns (bind mounts, live reload, --watch flags)
If --interactive or key information is absent, ask mandatory interactive questions:
- "What OS(es) do developers use? (linux/macos/windows)"
- "Is there a local domain for HTTPS development? (e.g., myapp.local)"
- "Do developers need GPU access for local dev? (yes/no)"
- "Is SSH key setup required as a project prerequisite? (yes/no)"
- "Which IDE(s) are standard? (vscode/jetbrains/none)"
- "Any kernel/OS parameters required? (inotify watches, vm.max_map_count, etc.)"
- "Does the project use a local certificate authority for HTTPS dev?"

Phase 2: Assemble Manifest

Build the manifest YAML following this priority order:

metadata block — include install_type matching --type flag (default: user)
platform block — from --platforms or detected by project type
params block — standard params: INSTALL_DIR, BRANCH (default: main); add CONFIG_DIR if a config step is needed
prerequisites block — from project type (e.g., node for npm projects, python3 for Python)
steps block — construct from script templates:
- Always start with a clone or verify-existing detect step
- Add install-deps-* steps for each target platform
- Add configure step if config files are needed
- End with a verify step
recovery_procedures block — always include a full-reset fallback

Developer Manifest Assembly Rules (when `--type developer`)

When assembling developer manifests, apply these additional rules:

os_config block — emit entries based on detection:

Condition	Entry
Linux + Docker in project	`docker-group` (requires_relogin: true)
Linux + file watchers detected (webpack/jest/vite/nodemon)	`inotify-watches`
Linux + Elasticsearch/Weaviate/OpenSearch detected	`vm-mapcount`
macOS	`xcode-cli-tools` (interactive: true)
HTTPS dev + local domain	mkcert install step (not os_config, but a script step)
GPU dev	`nvidia-container-toolkit` os_config entry

params — emit with interactive_required: true for:

LOCAL_DOMAIN — when HTTPS dev or local domain detected
SSH_EMAIL — when SSH key setup is required
GIT_USER_NAME, GIT_USER_EMAIL — when git config step is included
GIT_GPG_KEY_ID — when GPG signing is requested
IDE — when IDE-specific extension installation is included

steps — emit os-config steps for each os_config entry:

- id: apply-docker-group
  type: os-config
  config_id: docker-group
  depends_on: [install-docker]
  platform: linux

dev-specific prerequisites — add as detected:

nvm or mise — when .nvmrc or .tool-versions found
mkcert — when HTTPS dev requested
act — when GitHub Actions local testing detected

Docker-based Project Detection

When docker-compose.yml or compose.yaml is found during Phase 1 discovery, apply these additional behaviors:

Platform (#676):

Include macos in the platform block alongside linux — Docker Desktop covers both.
Any GPU or nvidia steps must add when: "$(uname -s) = Linux" so they are skipped on macOS.
Update install_hint for docker prereqs to include macOS install links.

Prerequisites (#672, #674):

Replace command -v docker with docker version --format '{{.Server.Version}}' 2>/dev/null to catch both "not installed" and "installed but no permission" cases.
Expand the docker install_hint to mention sudo usermod -aG docker $USER.

When Docker images or ML models are present, add disk space prereq (≥20GB free):

- name: disk-space
  detect: "df --output=avail -BG / | tail -1 | tr -d ' G'"
  version_min: "20"
  install_hint: "At least 20GB free disk space required for Docker images."

When ML models are detected (Ollama, HuggingFace, etc.), add RAM prereq (≥8GB):

- name: ram
  detect: "awk '/MemTotal/ {printf \"%.0f\", $2/1024/1024}' /proc/meminfo"
  version_min: "8"
  install_hint: "At least 8GB RAM recommended. 16GB+ for GPU profiles."

Params (#671, #675):

When a DOMAIN or ISSUER_URL param is emitted, also emit a PROTOCOL param with a smart default:

- name: PROTOCOL
  type: choice
  choices: [http, https]
  default: "$(echo ${DOMAIN} | grep -qE '^(localhost|127\\.0\\.0\\.1)' && echo http || echo https)"
  description: "Protocol for OAuth/API URLs. Defaults to http for localhost."

Then reference ${PROTOCOL}://${DOMAIN} in configure.sh instead of hardcoding https://.

Default DATA_DIR to ${INSTALL_DIR}/data (project-local, user-writable) rather than any system path like /var/lib/<project>. If the project explicitly requires a system path, emit a check-data-dir step (see steps below).

Steps (#673, #675, #677):

Emit a check-ports step before deploy that validates all ports declared in the compose file are free:

- id: check-ports
  type: script
  script: installer/scripts/check-ports.sh
  depends_on: [configure]

When the default DATA_DIR is a system path, emit a check-data-dir step before configure:

- id: check-data-dir
  type: script
  script: installer/scripts/check-data-dir.sh
  depends_on: [clone]

When Ollama is detected in the compose file or .env template, emit a pull-models step after deploy:

- id: pull-models
  type: script
  description: Pull Ollama models (may take several minutes)
  script: installer/scripts/pull-models.sh
  depends_on: [deploy]
  verify: "docker exec $(docker compose ps -q ollama) ollama list | grep -q ${OLLAMA_GEN_MODEL%%:*}"

Script templates used for Docker projects:

installer/scripts/check-ports.sh — port availability check before deploy
installer/scripts/pull-models.sh — Ollama model pull after deploy (when applicable)

Phase 3: Script Assembly

For each script step:

Copy the relevant template from agentic/code/addons/agentic-installer/scripts/templates/
For developer manifests, copy dev templates from scripts/templates/dev/
Place in <project>/installer/scripts/ (user install) or <project>/installer/scripts/dev/ (developer install)
Customize placeholders (package lists, config paths, extension IDs, etc.)
Record relative path in the manifest script: field

Phase 4: Output

Write the manifest to the appropriate path:

installer/setup.user.manifest.yaml — user install (when installer/ dir exists)
installer/setup.dev.manifest.yaml — developer install (when installer/ dir exists)
setup.manifest.yaml — backwards-compatible default (no --type flag, no installer/ dir)

Report:

Generated: setup.dev.manifest.yaml
  Install type:  developer
  Platform:      linux, macos
  OS config:     docker-group (linux), inotify-watches (linux), xcode-cli-tools (macos)
  Params:        INSTALL_DIR, LOCAL_DOMAIN [required], SSH_EMAIL [required]
  Prerequisites: git, node (>=20), nvm, mkcert
  Steps:         clone, install-deps, apply-docker-group, apply-inotify, configure-dev, verify-dev
  Recovery:      full-reset
  Scripts:       installer/scripts/dev/ (6 files)

Note: 2 OS config steps require re-login to take effect. Installer will warn user.
Note: 1 OS config step (xcode-cli-tools) triggers a GUI dialog on macOS.

Validate with: aiwg setup-validate installer/setup.dev.manifest.yaml
Run with:      aiwg setup-run installer/setup.dev.manifest.yaml

Output File Structure

A full-suite project (both user and developer install) ships these files:

installer/
├── setup.user.manifest.yaml          # end-user deploy
├── setup.dev.manifest.yaml           # developer standup
├── docs/
│   ├── install-user-linux.md
│   ├── install-user-macos.md
│   ├── install-user-windows.md
│   ├── install-dev-linux.md
│   ├── install-dev-macos.md
│   ├── install-dev-windows.md
│   └── install-dev-wsl2.md
└── scripts/
    ├── clone.sh
    ├── configure.sh
    ├── verify.sh
    ├── dev/
    │   ├── configure-dev.sh
    │   ├── install-mkcert.sh
    │   ├── apply-docker-group.sh
    │   ├── apply-inotify.sh
    │   ├── apply-vm-mapcount.sh
    │   ├── install-ide-extensions.sh
    │   ├── setup-git-config.sh
    │   ├── setup-ssh-key.sh
    │   └── verify-dev.sh
    └── user/
        ├── install-deps-ubuntu.sh
        ├── install-deps-macos.sh
        └── install-deps-windows.ps1

Script-First Rule

Every step that can be scripted MUST be a script step. Only use type: agentic for:

Steps that require real-time environment inspection that cannot be expressed in bash
Recovery from unexpected failures where the script approach has been exhausted

Example Output (Developer Manifest)

apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata:
  name: myapp-dev
  version: 1.0.0
  description: Developer environment setup for myapp
  install_type: developer

spec:
  platforms:
    - os: linux
      distros: [ubuntu, debian, fedora]
      arch: [x86_64, arm64]
      shell: bash
    - os: macos
      arch: [x86_64, arm64]
      shell: zsh

  params:
    - name: INSTALL_DIR
      type: path
      required: true
      description: Directory to clone the project into
    - name: LOCAL_DOMAIN
      type: string
      interactive_required: true
      description: Local domain for HTTPS dev (e.g., myapp.local)
    - name: SSH_EMAIL
      type: string
      interactive_required: true
      description: Email address for SSH key generation
    - name: IDE
      type: choice
      choices: [vscode, jetbrains, none]
      interactive_required: true
      description: IDE to install extensions for

  prerequisites:
    - name: git
      detect: "command -v git"
      version_min: "2.30"
      install_hint: "Install git: https://git-scm.com"
    - name: docker
      detect: "docker version --format '{{.Server.Version}}' 2>/dev/null"
      install_hint: "Install Docker: https://docs.docker.com/get-docker/"

  os_config:
    - id: docker-group
      description: Add current user to docker group (avoids sudo for docker)
      check: "id -nG | grep -qw docker"
      apply: "sudo usermod -aG docker ${USER}"
      requires_relogin: true
      platforms: [linux]

    - id: inotify-watches
      description: Increase inotify watches for file watchers (webpack, jest, vite)
      check: "sysctl fs.inotify.max_user_watches | awk '{print $3}' | xargs -I{} test {} -ge 524288"
      apply: |
        echo 'fs.inotify.max_user_watches=524288' | sudo tee -a /etc/sysctl.d/99-dev.conf
        sudo sysctl -p /etc/sysctl.d/99-dev.conf
      platforms: [linux]

    - id: xcode-cli-tools
      description: Xcode Command Line Tools (required for native compilation on macOS)
      check: "xcode-select -p 2>/dev/null | grep -q CommandLineTools"
      apply: "xcode-select --install"
      interactive: true
      platforms: [macos]

  steps:
    - id: clone
      type: script
      script: installer/scripts/clone.sh
      verify: "test -d ${INSTALL_DIR}/.git"

    - id: setup-git-config
      type: script
      script: installer/scripts/dev/setup-git-config.sh
      params: [GIT_USER_NAME, GIT_USER_EMAIL]
      depends_on: [clone]

    - id: setup-ssh-key
      type: script
      script: installer/scripts/dev/setup-ssh-key.sh
      params: [SSH_EMAIL]
      depends_on: [clone]

    - id: apply-docker-group
      type: os-config
      config_id: docker-group
      platform: linux
      depends_on: [clone]

    - id: apply-inotify
      type: os-config
      config_id: inotify-watches
      platform: linux
      depends_on: [clone]

    - id: apply-xcode-tools
      type: os-config
      config_id: xcode-cli-tools
      platform: macos
      depends_on: [clone]

    - id: install-mkcert
      type: script
      script: installer/scripts/dev/install-mkcert.sh
      params: [LOCAL_DOMAIN]
      depends_on: [clone]

    - id: configure-dev
      type: script
      script: installer/scripts/dev/configure-dev.sh
      params: [INSTALL_DIR, LOCAL_DOMAIN]
      depends_on: [install-mkcert]

    - id: install-ide-extensions
      type: script
      script: installer/scripts/dev/install-ide-extensions.sh
      params: [IDE]
      depends_on: [clone]

    - id: verify-dev
      type: script
      script: installer/scripts/dev/verify-dev.sh
      params: [LOCAL_DOMAIN]
      depends_on: [configure-dev, apply-docker-group, apply-inotify]

  recovery:
    - id: full-reset
      steps:
        - id: reset
          type: script
          script: installer/scripts/reset.sh

References

Schema: agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json
Templates (user): agentic/code/addons/agentic-installer/scripts/templates/
Templates (dev): agentic/code/addons/agentic-installer/scripts/templates/dev/
Run skill: agentic/code/addons/agentic-installer/skills/setup-run/SKILL.md
Validate skill: agentic/code/addons/agentic-installer/skills/setup-validate/SKILL.md