spec.development

Everything about the local developer experience for the agent project: reproducible sandboxes, AI coding-agent integration, and extra sandbox-level dependencies.

spec:
  development:
    sandbox:
      flox:
        enabled: true
      devcontainer:
        enabled: false
      dockerCompose:
        enabled: false
    ai:
      orchestrators:
        claudecode:
          enabled: true
        codex:
          enabled: false
        gemini:
          enabled: false
        opencode:
          enabled: false
        infer:
          enabled: false
    deps:
      - [email protected]
      - [email protected]
      - [email protected]

Fields

Field	Reference	Description
sandbox	sandbox	Reproducible dev environments (flox, devcontainer, dockerCompose).
ai	ai	AI-assistant integration; coding-agent orchestrators (Claude Code, Codex, Gemini, OpenCode, Infer).
deps	deps	Sandbox-level extra packages (cross-cutting, language-agnostic).

sandbox

Selects reproducible dev environments. flox, devcontainer, and dockerCompose are alternative ways to package the same sandbox; pick what suits the team. Each is independently toggleable.

spec:
  development:
    sandbox:
      flox:
        enabled: true
      devcontainer:
        enabled: false
      dockerCompose:
        enabled: false

Sandbox	When to use
flox	Reproducible per-project dev shells via Nixpkgs, no container layer needed.
devcontainer	VS Code (and compatible) Dev Containers - boots the project in a container.
dockerCompose	Existing multi-service Docker Compose stack you want the agent to live in.

Each sub-block has the shape { enabled: boolean }. Enabling more than one is allowed if your project wants to ship multiple ways to enter the sandbox.

ai

Configures generation of AI-assistant documentation (CLAUDE.md, AGENTS.md) and provisioning of coding-agent orchestrators inside the sandbox. The orchestrators live under spec.development.ai.orchestrators; each supported orchestrator is toggled independently, and every orchestrator is disabled by default.

spec:
  development:
    ai:
      orchestrators:
        claudecode:
          enabled: true
        codex:
          enabled: false
        gemini:
          enabled: false
        opencode:
          enabled: false
        infer:
          enabled: false

Field	Orchestrator
orchestrators.claudecode.enabled	Anthropic Claude Code
orchestrators.codex.enabled	OpenAI Codex
orchestrators.gemini.enabled	Google Gemini
orchestrators.opencode.enabled	OpenCode
orchestrators.infer.enabled	Inference Gateway infer

Each sub-block has the shape { enabled: boolean }. Multiple orchestrators can be enabled at once if a project wants to ship configuration for more than one.

deps

Extra packages to install into the development sandbox itself (flox, devcontainer, dockerCompose) on top of whatever the generator pulls in by default.

Use this for cross-cutting tools that aren't tied to a single language - e.g. a Go service that also needs deno for quick scripting, or a TypeScript agent that wants kubectl available in the dev shell.

spec:
  development:
    sandbox:
      flox:
        enabled: true
    deps:
      - [email protected]
      - [email protected]
      - [email protected]

Aspect	Detail
Shape	string[], each entry matching ^\S+@\S+$ (i.e. <package>@<version>).
Default	Empty.
Resolution	Consumer responsibility: Nixpkgs for flox, apt/apk/devcontainer feature for devcontainer, image layers for dockerCompose.

The schema only validates the <package>@<version> shape. Consumers (e.g. adl-cli) are responsible for resolving each entry against the sandbox's native package source.

If you need a package that is tied to a specific language, use that language's vendor.deps / vendor.devdeps instead.