Setup Manifest
setup.aiwg.io/v1 manifest reference
SetupManifest Reference (`setup.aiwg.io/v1`)
Prompt-first procedure: Describe the outcome you want in your agent conversation. The agent should select and load the appropriate AIWG assets, explain material changes, request any needed approval, and report verification evidence. Exact commands and flags appear only in the CLI reference.
Overview
`setup.aiwg.io/v1` is a Kubernetes-style YAML language for declaring cross-platform, software installation. A SetupManifest declares a platform matrix, user-facing parameters, prerequisite checks, OS-level configuration entries, ordered installation steps, and named recovery procedures. Manifests are validated, executed, and authored by the agentic-installer addon.
The default `deterministic` execution mode is script-first: `agentic` steps are reserved for exception handling and adaptive recovery. The `provider-orchestrated` mode is for a manifest deliberately interpreted by a capable AI provider, such as AIWG's public install/repair flow. It may use reasoning steps as its primary workflow because inspection, authorization, and non-destructive repair vary by machine and project. the agent-owned setup-run operation executes only deterministic manifests.
The authoritative JSON Schema lives at `agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json`. This document mirrors that schema; on conflict the schema wins.
File Location and Discovery
By convention manifests live at `setup.manifest.yaml` in the project root. The agentic-installer runtime commands (`setup-generate`, `setup-validate`, `setup-run`) are agent-facing CLI surfaces. `setup-validate` and `setup-run` accept a manifest path or the manifest option; otherwise they look for `setup.manifest.yaml` relative to the working directory. `setup-generate` writes a starter manifest to the output option or `setup.manifest.yaml`.
Top-Level Structure
apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata: { ... }
spec:
platforms: [ ... ]
params: [ ... ]
prerequisites: [ ... ]
os_config: [ ... ]
steps: [ ... ]
recovery: [ ... ]
briefing: { ... }| Field | Type | Required | Description |
|---|---|---|---|
| `apiVersion` | const `"setup.aiwg.io/v1"` | yes | API version literal. |
| `kind` | const `"SetupManifest"` | yes | Resource kind literal. |
| `metadata` | object | yes | Identity and audience info. |
| `spec` | object | yes | Platform matrix and execution plan. |
`additionalProperties: false` at every object — unknown fields are rejected.
`metadata`
| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | yes | Identifier for this manifest. |
| `description` | string | optional | Free-form description. |
| `version` | string | optional | Manifest version. |
| `install_type` | enum (below) | optional, `user` | Audience tag. |
| `execution_mode` | enum (below) | optional, `deterministic` | Runtime contract. |
`install_type` values: `user` (production deploy), `developer` (local dev environment), `ci` (headless pipeline setup). Only `developer` manifests may use `os_config`.
`execution_mode` values:
- `deterministic` — executable through the agent-owned setup-run operation; use scripts for known work.
- `provider-orchestrated` — give the manifest URL or contents to a supported AI
provider. The CLI validates it but returns a handoff message instead of executing it.
`spec`
| Field | Type | Required | Description |
|---|---|---|---|
| `platforms` | `Platform[]` | yes (≥1) | Supported platform targets. Installer refuses to run on unlisted platforms. |
| `params` | `Param[]` | optional | User-facing parameters resolved before any step executes. |
| `prerequisites` | `Prerequisite[]` | optional | Prerequisite checks run before any step. Required ones abort if missing. |
| `os_config` | `OsConfigEntry[]` | optional | OS-level configuration entries (developer manifests only). |
| `steps` | `Step[]` | yes (≥1) | Ordered installation steps. |
| `recovery` | `RecoveryProcedure[]` | optional | Named recovery procedures referenced by steps via `on_fail`. |
| `briefing` | `{ success?, next_steps? }` | optional | Messages delivered on completion. |
Platform Matrix
platforms:
- os: linux
distros: [ubuntu, debian, fedora]
arch: [x86_64, arm64]
shell: bash| Field | Type / values | Description |
|---|---|---|
| `os` | enum (below) | OS family. Required. |
| `distros` | string[] | Optional distro filter (Linux). |
| `arch` | string[] | Optional architecture filter. |
| `shell` | enum (below) | Shell context. |
- `os` values: `linux`, `macos`, `windows`, `docker`
- `distros` values: `ubuntu`, `debian`, `fedora`, `rhel`, `rocky`, `centos`, `arch`, `alpine`
- `arch` values: `x86_64`, `arm64`, `aarch64`
- `shell` values: `bash`, `zsh`, `sh`, `wsl2` (WSL2 bash on Windows), `native` (PowerShell/cmd)
Params
User-facing parameters resolved before any step runs. Names use UPPER_SNAKE_CASE; values are passed to scripts as env vars.
| Field | Type | Description |
|---|---|---|
| `name` | string | Env-var-style name (UPPER_SNAKE_CASE). Required. |
| `type` | enum (below) | Value type. Required. |
| `default` | any | Default if not provided by user. |
| `required` | bool, default `false` | Whether the param must be supplied. |
| `description` | string | Human-readable explanation. |
| `choices` | string[] | Valid values when `type: choice`. |
| `interactive_required` | bool, default `false` | Force interactive prompt; cannot be pre-filled by default. Use when a wrong default would cause OS configuration changes (SSH key email, GPG key ID, preferred IDE). |
`type` values: `string`, `path` (expanded — `~` → home), `bool`, `int`, `choice`.
Prerequisites
prerequisites:
- name: git
detect: "command -v git"
version_min: "2.30"
install_hint: "Install git: https://git-scm.com"| Field | Type | Description |
|---|---|---|
| `name` | string | Required. |
| `detect` | string | Shell command. Exit 0 = present, non-zero = missing. Required. |
| `version_min` | string | Minimum version parsed from `detect` stdout. |
| `required` | bool, default `true` | Required prerequisites abort install if missing. |
| `install_hint` | string | Shown when missing. |
OS Config Entries (Developer Manifests Only)
`os_config` declares OS mutations (kernel params, group membership, file permissions, shell profile changes) as check/apply pairs. Reachable only via `type: os-config` steps that reference an entry by `config_id`.
| Field | Type | Description |
|---|---|---|
| `id` | string | Unique identifier referenced by `config_id`. Required. |
| `description` | string | What this entry does. Required. |
| `check` | string | Shell command. Exit 0 = already configured (skip apply), non-zero = needs configuration. Required. |
| `apply` | string | Shell command or multi-line script to apply the configuration. Required. |
| `requires_relogin` | bool, default `false` | Installer warns the user that logout/login or new shell is required. |
| `interactive` | bool, default `false` | Apply triggers a GUI dialog or interactive prompt; installer must pause and inform the user. |
| `platforms` | string[] | Optional platform filter. Values: `linux`, `macos`, `windows`. |
Steps
Ordered installation steps. Each step has a `type` that selects one of seven execution modes.
Step types
| Type | When to use |
|---|---|
| `script` | Known operation — use this first. Run a script file with declared params. |
| `detect` | Check environment state. |
| `ask` | Collect user input mid-install. |
| `verify` | Post-operation validation (run `commands`). |
| `agentic` | Exception handling only — adaptive recovery via free-form `instruction`. |
| `platform-route` | Branch by OS/distro using `routes`. |
| `chain` | Invoke a sub-project SetupManifest. |
| `os-config` | Apply a single `os_config` entry by ID (developer manifests only). |
Common step fields
| Field | Type | Description |
|---|---|---|
| `id` | string | Unique step identifier. Referenced by `depends_on` and `on_fail`. Required. |
| `type` | enum (above) | Execution mode. Required. |
| `platform` | string or string[] | Platform filter. Omit to run on all declared platforms. |
| `depends_on` | string[] | Step IDs that must complete successfully before this step runs. |
| `when` | string | Condition expression; step skipped if false. References params by name. |
| `on_fail` | string | Recovery procedure ID to invoke on failure. The literal `recover` invokes the default. |
| `interactive` | bool, default `false` | This step itself prompts directly. With every name in this step's own `params` resolved, it runs headless instead (no terminal needed); otherwise it requires a terminal, and the agent-owned setup-run operation refuses a marked step up front (naming it) instead of running it when none is attached (#3062; second review finding 5b). |
Running headless (#3062)
Without an interactive terminal attached, `script`/`verify`/`detect`/`os-config` steps run bounded (10 minutes by default, `AIWG_SYNC_LONG_TIMEOUT_MS` to override) with stdin ignored: a step whose command tries to prompt fails fast instead of hanging the agent-owned setup-run operation forever. With a terminal attached, behavior is unchanged — a step's command/script gets inherited stdio so a person can actually answer a prompt it issues.
Mark a step `interactive: true` when it is known to prompt directly. It can optionally declare which inputs would let it skip that prompt via the same `params` field a `script` step uses to pass param names as env vars (#3062 second review, finding 5b): with every declared param already resolved (the param option/the params-file option/env/`default`), the step is trusted not to need to prompt and runs headless (bounded) exactly like any other step in that same environment — no terminal required. With no `params` declared at all ("undeclared interaction" — its questions cannot be enumerated or supplied via the param option, since it runs an arbitrary script), or with a declared param still missing, a terminal is required; the agent-owned setup-run operation refuses up front, before running anything, instead of waiting out the bounded timeout. With a terminal attached and nothing resolved, behavior is unchanged from before `params` existed on this field: the step's underlying command/script runs with inherited stdio and may prompt on its own.
`type: ask` steps declare which inputs they need via `params` the same way. An `ask` step with every declared param already resolved runs headless, logging which params answered it. One with a declared param still unresolved is refused only when no terminal is attached, naming the missing name(s) so the param option/the params-file option can supply them instead; with a terminal attached, it is prompted for the missing ones (#3062 second review, finding 5b — this is the one behavioral difference from `interactive: true`: this CLI itself owns the prompting for `ask` steps, since there is no separate script to hand a terminal to, so it can actually ask instead of just letting a script do its own thing). A declared answer threads into every later step's env exactly like a the param option-supplied one. An `ask` step with no `params` declared at all is always refused, with or without a terminal — this is one of only two permanent exceptions to "an input with a terminal gets prompted for" (the other is `tools/contrib/sync-upstream.mjs`'s contributor sync-strategy choice): with nothing declared, there is no destination to store an answer in at all.
`type: agentic` and `type: chain` steps are always refused — deterministic CLI execution does not support either, regardless of terminal or supplied params.
Every selected step (including nested `platform-route` steps, and the entire recovery sequence any selected step's `on_fail` names) is checked for all of the above conditions before any step runs — not inside the per-step loop, and not only for the step about to execute — so an earlier step can never run ahead of a later step's refusal, nor can a normal step run ahead of a refusal inside the recovery sequence it would trigger on failure (#3062 second review, finding 7). A step only reachable through `on_fail` recovery and not already covered that way (i.e. a manifest with no selected step actually naming it) is checked individually, right before it would run.
Type-specific fields
| Type | Required fields | Optional fields |
|---|---|---|
| `script` | `script` (path relative to manifest) | `params`, `verify` |
| `verify` | `commands` (string[]) | — |
| `ask` | `message` | `params` (required to run headless; see "Running headless" above), `on_deny` (`abort` or `skip`) |
| `agentic` | `instruction` | — |
| `os-config` | `config_id` | — |
| `platform-route` | `routes[]` (each `{platform, steps[]}`) | — |
| `chain` | `manifest` (path or URL to chained manifest) | — |
| `detect` | — | typically uses `verify`/`commands` shape |
For `script` steps: `params` lists param names passed to the script as env vars; `verify` is one or more post-step commands (exit 0 = success).
Recovery Procedures
Named groups of steps invoked when a step's `on_fail` matches.
recovery:
- id: full-reset
steps:
- id: reset
type: script
script: scripts/reset.sh| Field | Type | Description |
|---|---|---|
| `id` | string | Required. Procedure ID referenced by `step.on_fail`. |
| `steps` | `Step[]` | Required. Recovery steps (same shape as `spec.steps`). |
Briefing
briefing:
success: "Install complete. Run the agent-owned help operation to get started."
next_steps:
- "Run the agent-owned use operation sdlc to deploy the SDLC framework"
- "Open ./README.md for project orientation"Worked Example
apiVersion: setup.aiwg.io/v1
kind: SetupManifest
metadata:
name: myapp
version: 1.0.0
install_type: user
spec:
platforms:
- os: linux
distros: [ubuntu, debian, fedora]
arch: [x86_64, arm64]
shell: bash
- os: macos
arch: [arm64]
shell: zsh
params:
- name: INSTALL_DIR
type: path
required: true
description: "Where to clone the project"
prerequisites:
- name: git
detect: "command -v git"
version_min: "2.30"
install_hint: "Install git: https://git-scm.com"
steps:
- id: clone
type: script
script: scripts/clone.sh
params: [INSTALL_DIR]
verify: "test -d ${INSTALL_DIR}/.git"
on_fail: full-reset
- id: configure
type: script
script: scripts/configure.sh
depends_on: [clone]
recovery:
- id: full-reset
steps:
- id: reset
type: script
script: scripts/reset.sh
briefing:
success: "Install complete."
next_steps:
- "cd ${INSTALL_DIR} && ./bin/myapp the help option"Tooling
The agentic-installer addon ships three agent-facing CLI entrypoints, three backing skills, one agent, two rules, and the canonical schema. These are agentic runtime assets: discovery and index automation should locate them by type (`skill`, `agent`, `rule`, `schema`) and by command name where applicable.
- `setup-generate` — generate starter manifest and script assets.
- `setup-validate` — schema + reference checks + agentic-step audit.
the fix option is reserved for future safe autofixes and currently validates only.
- `setup-run` — six-phase execution with platform detection, dry-run, and recovery
confirmation gate.
- `installer-agent` — specialized persona for manifest generation, validation, and
execution.
Use AIWG to complete this documented outcome: - setup-generate — generate starter manifest and script assets. - setup-validate — schema + reference checks + agentic-step audit. the fix option is reserved for future safe autofixes and currently validates only. - setup-run — six-phase execution w
Have it inspect the current state, explain the plan, ask before material
changes, and report the result with verification evidence.Two HIGH-severity rules govern manifest authoring and execution:
- `installer-safety` — show before run, confirm destructive ops, validate before
execute, agentic-steps-as-exceptions, params-before-steps, no inline secrets, platform mismatch = skip.
- `installer-authoring` — script-first, always source libs, manifests describe
while scripts act, one manifest per unit, every manifest needs recovery.
Cross-References
- Schema (authoritative):
`agentic/code/addons/agentic-installer/schemas/v1/setup-manifest.schema.json`
- Addon source: `agentic/code/addons/agentic-installer/`
- Script templates: `agentic/code/addons/agentic-installer/scripts/templates/`
(clone, install-deps for ubuntu/fedora/macos/windows, configure, verify, reset, hub-chain)
- Library helpers (sourced by templates):
`agentic/code/addons/agentic-installer/scripts/lib/{detect,params,verify}.sh`, `detect.ps1`
- Authoring rules:
`agentic/code/addons/agentic-installer/rules/installer-authoring.md`, `installer-safety.md`
- Release announcement (introduces the language):
`docs/releases/v2026.4.0-announcement.md` (#663–#667)
- Project-level config (separate concern): see `aiwg-config.md`