itera.yml Guide

itera.yml and itera.yaml are the root-level config files that tell Itera how to resolve your project root, package manager, install behavior, dev command, and quality commands.

Use this page for practical setup patterns. Use the itera.yml reference for exact defaults and edge cases.

Before you write the file

• Put the file at the repository root. Iteration Service does not search nested folders.
• If both itera.yaml and itera.yml exist, Iteration Service loads itera.yaml.
• Keep the file small. Only set fields that remove ambiguity in your repo.
• Prefer script over run when a normal package script works.
• Do not try to override the install command text. Itera manages install commands itself.

Minimal recommended example

For a single-package app, start with the smallest file that makes your runtime obvious:

version: 1

project:
  packageManager: npm

commands:
  dev:
    script: dev

Why this is usually enough:

• version: 1 is required.
• project.packageManager removes guesswork when multiple lockfiles or package-manager hints exist.
• commands.dev.script tells Itera to run your real dev script instead of falling back to generic heuristics.
• install is intentionally omitted because Itera resolves it automatically.

If your app lives in a subdirectory, add project.root.

Monorepo example

For a monorepo, the most important decision is often where install runs. If dependencies are installed from the workspace root, point install there explicitly and keep app commands on the project root.

version: 1

project:
  root: apps/web
  packageManager: pnpm

commands:
  install:
    cwd: repo_root

  dev:
    script: dev

  quality:
    lint:
      script: lint
    typecheck:
      script: type-check

What this does:

• project.root makes project_root resolve to apps/web.
• commands.install.cwd: repo_root keeps the managed install command at the workspace root.
• dev, lint, and typecheck run from project_root by default, so no extra cwd is needed.

Use cwd: repo_root on individual commands only when the script itself must execute from the workspace root.

Strict-mode example

Strict mode is useful when you want Itera to fail instead of inferring missing commands.

version: 1

project:
  root: apps/iter_web
  packageManager: npm

commands:
  install:
    cwd: repo_root

  dev:
    script: dev
    args:
      - --host
      - 0.0.0.0

  quality:
    lint:
      script: lint:ci
    typecheck:
      script: type-check

defaults:
  onMissing: strict

This pattern matches real first-party usage closely:

• Install is still managed by Itera, but strict mode requires enough information to resolve it.
• dev is explicit, so Itera does not need to guess between dev, start, or a fallback tool.
• Quality commands are explicit instead of relying on conventional script-name inference.

How command resolution works

Most command types follow this order:

1. Use commands.<name>.run when it is non-empty and not auto.
2. Otherwise use commands.<name>.script.
3. Otherwise look for conventional package.json scripts.
4. Otherwise use a built-in heuristic if one exists.
5. Otherwise fall back to the current Itera profile when strict mode does not block fallback.

Important exceptions:

• install is special. Explicit commands.install.run and commands.install.script are rejected.
• dev can inherit default args of --port 3000 --host 0.0.0.0 when Itera resolves it through script, package.json, or the Vite heuristic.
• Fast quality commands only cover quality.format, quality.lint, and quality.typecheck.
• test does not have a current-profile fallback in the current Iteration Service resolver.

cwd constants

Command cwd values accept normal repo-relative paths plus two built-in constants:

• repo_root: the repository root
• project_root: the effective project root

project_root comes from project.root when you set it. If you leave project.root at . and Iteration Service is already scoped to a nested app path, that active app path becomes the effective project root.

Unsupported or misleading patterns

Avoid these configurations:

• commands.install.run: npm install
• commands.install.script: auto
• commands.install.script: install
• commands.install.args: [...] if you expect those args to change the managed install command
• Arbitrary shell commands such as python -c ... in commands.dev.run, commands.test.run, or commands.quality.*.run

The supported way to influence install behavior is:

• Set project.packageManager explicitly when auto-detection is ambiguous.
• Set commands.install.cwd to repo_root, project_root, or a repo-relative directory when install must run somewhere specific.

Product Agent scope

The full itera.yml contract is broader than what Product Agent currently consumes directly.

• Iteration Service uses install, dev, readiness, and runtime fallback behavior.
• Product Agent's code-change flow only merges the fast quality command set with request execution-policy fields such as project_root, strict_mode, and allowed_commands.

If you are troubleshooting Product Agent behavior, do not assume that commands.dev, commands.install, or commands.dev.readyUrl will affect it.