Skip to main content

Documentation Index

Fetch the complete documentation index at: https://momentic.ai/docs/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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: 
git status --short
Commit, stash, or otherwise back up any local changes before continuing. For an extra local backup, create a branch before the migration: 
git branch backup/momentic-v1-format

​
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: 
npx momentic --version          # web
npx momentic-mobile --version   # mobile
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. 
npx momentic mcp --config /absolute/path/to/momentic.config.yaml
npx momentic-mobile mcp --config /absolute/path/to/mobile-momentic.config.yaml

​
2. Run the migration

You have two entry points, depending on how much you want to touch:
  • 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: 
npx momentic@latest upgrade --dry-run
npx momentic-mobile@latest upgrade --dry-run
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: 
npx momentic@latest upgrade        # everything: CLI version + config + files
npx momentic migrate simplified-format     # just rewrite the YAML files (uses the installed CLI)
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: 
npx momentic-mobile@latest upgrade        # everything: CLI version + config + files
npx momentic-mobile migrate simplified-format     # just rewrite the YAML files (uses the installed CLI)
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 clean 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 efficiently, including which MCP tools to reach for when making surgical 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: 
npx skills add momentic-ai/skills
The skills CLI is idempotent and auto-detects .claude/, .cursor/, .agents/, .opencode/, and .github/copilot/ directories, rewriting the installed skill files in place. Run it once after the migration, then restart your editor so the new skill content is loaded. If you previously installed skills with npx momentic install-skills or npx momentic-mobile install-skills, switch to the standalone skills CLI; the bundled commands are deprecated.

​
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 Editor validation 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 normal app and test workflows already block invalid YAML. Use the lint command when a coding agent or direct YAML edit changes Momentic test files and you want a quick validation without starting the app or running tests. It checks schema validity, local file references, and entity conflicts. Web: 
npx momentic lint
Mobile: 
npx momentic-mobile lint
Run the matching command once after the migration, then use it as a lightweight guardrail for agent-authored changes. To check one file during review: 
npx momentic lint tests/checkout.test.yaml
npx momentic-mobile lint mobile-tests/login.test.yaml

​
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 most reliable way to create, preview, and execute steps against a live browser. For lightweight changes, simplified format files are also safe 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 simple 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 Test format for the YAML shape and MCP for MCP setup. For a spec-driven workflow that uses Momentic tests as living product specs, see Spec-driven development in the MCP guide.