itera.yml Reference

This page documents the shipped itera.yml / itera.yaml contract as Iteration Service currently resolves it, with notes where Product Agent consumes a narrower subset.

For examples first, start with the itera.yml guide.

Discovery and parsing rules

• Iteration Service checks the repository root for itera.yaml first, then itera.yml.
• Fast quality resolution can also merge request execution_policy data with local itera.yaml / itera.yml values when the request does not provide every quality command directly.
• Missing config is allowed. Iteration Service falls back to built-in behavior when no file is present.
• The top-level YAML value must be a mapping.
• Unknown keys are warned about, not treated as fatal errors.

Top-level keys

Key	Required?	Type	Default / behavior
version	Yes	integer	Must be 1. Any other value is rejected.
project	No	mapping	Defaults to root: ".", packageManager: "auto", framework: "auto".
commands	No	mapping	Defaults to no explicit commands.
defaults	No	mapping	Defaults to onMissing: infer_then_fallback and fallbackProfile: current_itera.

project

Key	Required?	Type	Default / behavior
project.root	No	string	Defaults to ".". If left empty or ".", Iteration Service may use the active app base path as the effective project root when it is already scoped to a nested app.
project.packageManager	No	string	Allowed values: auto, npm, pnpm, yarn, bun. Defaults to auto.
project.framework	No	string	Defaults to "auto". Parsed and validated as a string, but not used by the current resolver.

defaults

Key	Required?	Type	Default / behavior
defaults.onMissing	No	string	infer_then_fallback or strict. Defaults to infer_then_fallback.
defaults.fallbackProfile	No	string	Must be current_itera. Any other value is rejected.

Supported command paths

Path	Optional?	Default timeout	Notes
commands.install	Yes	900 seconds	Managed install command. Explicit run and script overrides are rejected.
commands.dev	Yes	no timeout	Supports readiness settings.
commands.test	Yes	1200 seconds	No built-in fallback profile in Iteration Service.
commands.quality.lint	Yes	600 seconds	Part of the fast quality command set.
commands.quality.typecheck	Yes	900 seconds	Part of the fast quality command set.
commands.quality.format	Yes	600 seconds	Part of the fast quality command set.

Command object keys

The same command object shape is parsed under install, dev, test, and quality.*, but not every key has meaning for every command type.

Key	Required?	Applies to	Default / behavior
run	No	dev, test, quality.*	null by default. A non-empty value other than auto wins first, but only if it is a safe package-manager script invocation.
script	No	dev, test, quality.*	null by default. Resolved through the active package manager.
args	No	all command objects	Defaults to [] after trimming blank entries. For dev, default host/port args are added only when Itera resolves the command through script, package.json, or the Vite heuristic and you did not provide args.
cwd	No	all command objects	Defaults to the effective project root. Accepts repo_root, project_root, or a repo-relative directory. The path must stay inside the repo and already exist.
timeoutSeconds	No	all command objects	Must be a positive integer when set. Otherwise the command-type default is used.
readyUrl	No	commands.dev	Defaults to http://127.0.0.1:3000/ after dev resolution succeeds or falls back. Must use http:// and target localhost or 127.0.0.1.
readyTimeoutSeconds	No	commands.dev	Defaults to 120. Must be a positive integer when set.

Install-specific behavior

install is the biggest source of confusion because its command object is parsed with the shared schema, but the resolver does not allow command-text overrides.

Key	Behavior
commands.install.run	auto, empty, or omitted behaves like no override. Any explicit command string is rejected.
commands.install.script	Empty or omitted behaves like no override. Any non-empty script value, including auto, is rejected.
commands.install.args	Parsed, but does not change the managed install command. Treat it as ineffective for current behavior.
commands.install.cwd	Supported. Controls the working directory used when Itera runs the managed install command.
commands.install.timeoutSeconds	Supported. Overrides the default 900 second timeout.
commands.install.readyUrl / readyTimeoutSeconds	Parsed by the shared schema but unused for install resolution.

cwd resolution

• repo_root resolves to the repository root.
• project_root resolves to the effective project root.
• The constants are case-insensitive.
• Any other string is treated as a repo-relative directory.
• Absolute paths are rejected.
• Paths that escape the repository with .. are rejected.
• Paths must already exist and be directories.

Package-manager auto-resolution

Iteration Service uses two closely related resolution paths.

For dev, test, and quality.*

When project.packageManager is auto, Iteration Service checks in this order:

1. project.root directory package.json#packageManager
2. active base-path directory package.json#packageManager, when a base path exists
3. repository root package.json#packageManager
4. lockfiles in those same directories, preferring pnpm, then yarn, then bun, then npm
5. fallback to npm

For install

Install resolution is more workspace-aware:

1. Use project.packageManager if it is explicit.
2. Infer an authoritative install root from workspace definitions when the repo is a monorepo.
3. Prefer package.json#packageManager on the install root, then the repository root.
4. Prefer a lockfile on the install root before looking at child app hints.
5. Fall back to project-root package.json#packageManager, then repository or project lockfiles, then npm.

This is why a nested app can still resolve a workspace-root install command even when its own package.json suggests something else.

Managed install command heuristics

Once Itera knows the install root and package manager, it builds the command like this:

Package manager	With lockfile	Without lockfile
npm	npm ci --ignore-scripts --no-audit --no-fund	npm install --ignore-scripts --no-audit --no-fund
pnpm	pnpm install --frozen-lockfile --ignore-scripts	pnpm install --ignore-scripts
yarn classic	yarn install --frozen-lockfile	yarn install
yarn berry	yarn install --immutable	yarn install
bun	bun install --ignore-scripts	bun install --ignore-scripts

Command resolution order

dev, test, and quality.*

Iteration Service resolves these commands in order:

1. run when it is explicit and safe
2. script
3. conventional package.json scripts
4. built-in heuristics
5. fallback behavior, if strict mode allows it

Conventional script names:

Command	Script names checked
dev	dev, then start
test	test
quality.lint	lint
quality.typecheck	typecheck, type-check, tsc
quality.format	format

Built-in heuristics:

Command	Heuristic
dev	npx vite plus default dev args when needed
quality.typecheck	npx tsc --noEmit
test, quality.lint, quality.format	no direct heuristic beyond conventional scripts

Fallback behavior

• Missing config file: Iteration Service falls back to the current Itera behavior.
• dev unresolved with infer_then_fallback: Iteration Service falls back to the current profile and uses the default readiness probe.
• Fast quality unresolved with infer_then_fallback: Iteration Service may synthesize format, lint, and typecheck from repo package scripts and the built-in typecheck heuristic as fallback.fast_quality_profile.
• test has no equivalent fallback profile in the current Iteration Service resolver.

Readiness defaults

For commands.dev:

Setting	Default
readyUrl	http://127.0.0.1:3000/
readyTimeoutSeconds	120

readyUrl must:

• use http://
• target localhost or 127.0.0.1
• avoid embedded credentials
• use a valid positive TCP port when a port is present

Strict mode

defaults.onMissing: strict changes missing-command behavior:

• install must still be resolvable through the managed install logic.
• dev must resolve from explicit config, package scripts, or heuristics. If it cannot, Iteration Service raises an error instead of falling back.
• Fast quality commands do not get the repo fallback profile in strict mode.

Strict mode does not make unsupported install overrides valid.

Product Agent subset

Product Agent does not consume the full runtime contract.

Today its dedicated quality-gate path focuses on request execution_policy plus the fast quality subset of local config.

What that means in practice:

• Product Agent can pass project_root, strict_mode, and a narrowed allowed_commands list in execution_policy.
• When those request fields do not provide every fast quality command, local defaults.onMissing, project.packageManager, project.root, and commands.quality.* can still affect the resolved checks.
• Product Agent does not use install heuristics, install readiness, dev readiness, or commands.test through this quality-gate path.
• commands.dev, commands.install, readyUrl, and readyTimeoutSeconds matter for Iteration Service, not for Product Agent's execution-policy payload.

Unsupported or misleading configurations

These are common mistakes:

• Treating commands.install.run as an install override. It is not supported.
• Treating commands.install.script: auto as a neutral placeholder. Current Iteration Service rejects any non-empty install script value.
• Treating commands.install.script as an install override. It is not supported.
• Assuming commands.install.args changes the managed install command. It does not.
• Using arbitrary shell commands in explicit run values. Itera accepts package-manager script execution only.
• Assuming Product Agent consumes the same install/dev behavior as Iteration Service.