Skip to main content
The simplified format makes Momentic YAML easier to review and maintain: no volatile step IDs on disk, shorter command aliases, relative module references, and JSON Schema support in modern editors.
The migration rewrites Momentic test and module files. Back up your repository first, start from a clean Git state, and make sure there are no untracked changes before running it.
Web (momentic) and mobile (momentic-mobile) are separate CLIs with separate migrations. Each command only rewrites files belonging to its own CLI and only flips fileFormat: v2 on its own project’s momentic.config.yaml. If your repo has both web and mobile Momentic projects, run both migrations; one will not touch the other’s files.

​
Migrate with a coding agent

Paste this prompt into your coding agent. It checks the working tree, runs the migration, reinstalls the skills, and reviews the diff with you.

​
Before you start

Pick a migration window when teammates are not actively changing Momentic tests. Everyone should move to the simplified format at roughly the same time. If one branch keeps editing legacy YAML while another branch lands the rewrite, later merges can be noisy. Before running the migration:
Commit, stash, or otherwise back up any local changes before continuing. For an extra local backup, create a branch before the migration:

​
1. Update Momentic

Always invoke the migration through momentic@latest / momentic-mobile@latest so the project config and YAML rewrites are produced by the new CLI’s serializers, not the version currently pinned in your package.json. Running the bare npx momentic upgrade on an older pinned version installs the new CLI but completes the rest of the upgrade with the old one, which means you would need a second invocation to see the new behavior take effect. Check your currently-pinned versions before continuing:
If your MCP server is pinned in an editor config, update that command too. The MCP server must run a version that understands simplified format files before agents can create, preview, or edit them.

​
2. Run the migration

You have two entry points, depending on how much of the project you want to change:
  • momentic@latest upgrade / momentic-mobile@latest upgrade: overarching. Installs the latest CLI into your project, applies the latest recommended project-config defaults (ai.agentConfig agent versions, ai.useMemory, ai.failureRecovery), sets fileFormat: v2, and rewrites every legacy *.test.yaml / *.module.yaml through the simplified format serializer. Use this when you want one command to bring the whole project current.
  • momentic migrate simplified-format / momentic-mobile migrate simplified-format: file migration only. Rewrites legacy test and module files to the simplified format and flips fileFormat: v2 on the project config, but leaves your CLI version and ai.* defaults alone. Use this when you want a tight, isolated diff with no config-default changes mixed in. Runs against the CLI version already installed in your project; if it is older than the published momentic@latest the command will warn you and point at npx momentic@latest upgrade so you can install the newest serializers.
Both paths share the same simplified format serializer and skip files that already use the simplified format. The first file that fails to migrate aborts the run; the migration is not designed to be resumable, so resolve the surfaced error and rerun the command before continuing.

​
Preview with --dry-run

Both upgrade commands accept --dry-run to preview what would change without writing anything to disk or pushing any snapshots:
The output lists how many tests and modules would be migrated, how many already use the simplified format, and which ai.agentConfig entries would be updated.

​
Web

From the web project root, run one of:
A typical web test in the simplified format should start with fileType: momentic/test/v2; a module should start with fileType: momentic/module/v2.

​
Mobile

From the mobile project root, run one of:
A typical mobile test in the simplified format should start with fileType: momentic/mobile-test/v2; a mobile module should start with fileType: momentic/mobile-module/v2. If you maintain both a web and a mobile project, run the command in each project root. Neither CLI touches the other’s files, so a single-platform run will silently leave the other platform’s tests in legacy YAML.

​
What to expect

Each migration takes about 1 minute per 50 tests. Existing step caches are preserved across the conversion. Review the diff like application code, then commit all rewritten Momentic YAML files together with the momentic.config.yaml change. Do not split the config change into a separate commit because the project should switch formats as one unit. If your repo already uses the simplified format and the agent config is current, the upgrade command is a no-op. It will not rewrite any files.

​
3. Reinstall Momentic skills

The Momentic skills teach coding agents and the MCP server how to author and edit simplified format files, including which MCP tools to reach for when making small edits to the readable YAML. Reinstall them from your project root after the migration so every editor that reads them picks up the latest guidance:
Use npx momentic-mobile skills --yes for mobile projects. The command detects .claude/, .cursor/, .agents/, .opencode/, and .github/ directories and rewrites the installed skill files in place. Run it once after the migration, then restart your editor so it loads the new skill content.

​
4. Enable editor validation

Momentic publishes static JSON Schemas for simplified format tests and modules. Add them to your editor to get autocomplete and inline validation as you write. The schemas work for web, mobile, and mixed repos. See IDE lint for VS Code, Cursor, Windsurf, and Zed config. The onboarding wizard (npx @momentic/wizard@latest) configures this automatically for the editors it detects.

​
5. Use lint for agent edits

Editor schemas catch shape errors early. Momentic also runs simplified format lint automatically before starting the local app and before executing tests, so the local app and test runs already block invalid YAML. Use the lint command when a coding agent or direct YAML edit changes Momentic test files and you want validation without starting the app or running tests. It checks schema validity, local file references, and entity conflicts. Web:
Mobile:
Run the matching command once after the migration, then use it as a check for agent-authored changes. To check one file during review:

​
6. Author simplified format files

After migration, restart your editor so it launches the updated MCP command when you do need browser-backed authoring. MCP is still the supported way to create, preview, and execute steps against a live browser. For lightweight changes, simplified format files are also fine to edit directly. The readable YAML format, static schemas, and editor completions make small updates easier:
  • Prompt coding agents to directly edit *.test.yaml and *.module.yaml for changes that do not need a browser.
  • Hand-author tests with YAML tab completions and schema suggestions in your editor.
  • Reference local files from steps. JavaScript steps can point at local JS files, and those JS files can reference other local files with relative paths.
See File format for the top-level YAML structure, Steps for step syntax, and MCP for MCP setup. For a spec-driven process that uses Momentic tests as product specs, see Spec-driven development on the Skills page.