Skip to content

Moving settings out of WORKFLOW.md

Itervox reads its settings from layered JSONC files — your user file (~/.itervox/settings.jsonc), the project file (.itervox/settings.jsonc, committed) and the project-local file (.itervox/settings.local.jsonc, gitignored) — all described by one published schema. Since #239 that covers every runtime section: agent, automations, dependencies, hooks, hub, polling, server, tracker and workspace. WORKFLOW.md holds the prompt: its body is the Liquid prompt template, and it stays the import and export format.

Nothing breaks. A workflow that keeps these sections in its front matter loads and behaves exactly as before, with itervox_schema_version: 2 (no schema bump). The order is: defaults < your user file (~/.itervox/settings.jsonc) < WORKFLOW.md front matter < the project file < the project-local file. The one change in precedence: when the project or local file and the front matter set the same key, the file wins. Your user file holds personal defaults for every project, so a project’s own front matter still wins over it.

New projects start migrated. itervox init (every template) and itervox quickstart write the layered sections to .itervox/settings.jsonc; this guide is for projects created before that.

  • itervox doctor prints one deprecated: line per front-matter key, naming .itervox/settings.jsonc as where it moves.
  • The daemon’s startup log names the deprecated keys once.
  • A key set both in the front matter and in the project or local settings file is reported once as a conflict (a WARNING: line in itervox doctor, one startup-log line), naming the file whose value is in effect. A user-file value under the front matter is not a conflict.

Preview first; --dry-run writes nothing:

Terminal window
itervox init --update --workflow WORKFLOW.md --dry-run

It prints the keys that would move and the full .itervox/settings.jsonc it would write. Then run it:

Terminal window
itervox init --update --workflow WORKFLOW.md

What it does:

  1. Writes WORKFLOW.md.bak with the workflow as it was, before anything else (an existing backup is not overwritten without --force).
  2. Runs the schema-2 steps it always ran (profile prompts to files, the guardrails block).
  3. Moves every layered front-matter key into .itervox/settings.jsonc. YAML comments above, beside and below a moved key become // comments in the same place; a settings file that already exists keeps its own comments and keys. A key the settings file already sets keeps the file’s value — it was already the one in effect — and the front-matter copy is dropped.
  4. Checks that the merged configuration is the same before and after, and refuses the move (writing nothing) if it is not.

Before:

---
itervox_schema_version: 2
# How Itervox reaches the team's issues.
tracker:
kind: linear # the team's tracker
api_key: $LINEAR_API_KEY
project_slug: core
hooks:
timeout_ms: 90000
---
Work on {{ issue.identifier }}: {{ issue.title }}.

After, .itervox/settings.jsonc:

{
"$schema": "https://itervox.dev/schema/settings.schema.json",
// How Itervox reaches the team's issues.
"tracker": {
"kind": "linear", // the team's tracker
"api_key": "$LINEAR_API_KEY",
"project_slug": "core",
},
"hooks": {
"timeout_ms": 90000,
},
}

and WORKFLOW.md keeps the marker and the prompt:

---
itervox_schema_version: 2
---
Work on {{ issue.identifier }}: {{ issue.title }}.
  • The body (the prompt template) and itervox_schema_version.
  • The sections that are not layered: guardrails, memory, sessions, pr_events.
  • agent.profiles (the profile editor writes them there), agent.available_models (itervox models refresh writes it there unless a settings file sets it) and the legacy agent.reviewer_prompt (which itervox init --update --force moves into the reviewer’s INSTRUCTIONS.md).
  • A key holding an inline secret — see below.

Settings files never hold a secret, only a $VAR reference to one: "api_key": "$LINEAR_API_KEY", with the value in the environment or .itervox/.env. The move copies a $VAR reference as written (it is never resolved). A key holding the secret itself (api_key: lin_…, or a URL with a password) stays in WORKFLOW.md, and the migration names it without printing the value: put the value in .itervox/.env, set the key to $VAR, and run itervox init --update again. The Settings page and itervox config set refuse to write an inline secret.

  • Saves. Dashboard and TUI saves of the moved sections (tracker states, the failed state, the project filter and tracker scope, the dependency analysis mode, automations) write the settings file — the project file, or the project-local file when it already sets the key — through the same comment-preserving writer as every other setting. The Settings page’s All settings section lists the new sections, and its layer tab picks the file a save writes.
  • Reloads. The daemon watches .itervox/settings.jsonc, .itervox/settings.local.jsonc and ~/.itervox/settings.jsonc together with WORKFLOW.md, so a hand edit of any of them is applied live, with the same debounce, validation and drain-then-reload as a WORKFLOW.md edit. A file that does not exist yet is picked up when you create it; deleting one reloads without it. Saves from the Settings page never reload, and itervox config set or itervox init --update reload a running daemon once. An edit that does not load keeps the running config and shows on the dashboard banner, naming the file and line. See What an edit to WORKFLOW.md or a settings file does.
  • Commit .itervox/settings.jsonc with WORKFLOW.md. Keep .itervox/settings.local.jsonc and .itervox/.env out of git (itervox init --update makes sure they are ignored).
  • Remove WORKFLOW.md.bak once you have reviewed the result.

The front matter still works, so moving a key back is a hand edit: set it in the front matter and delete it from the project and local settings files (they would win). itervox export --symphony writes a Symphony WORKFLOW.md from the merged configuration wherever the keys live.