> ## 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.

# Simplified format

> Move existing tests and modules from legacy YAML to Momentic's simplified format, on web and mobile.

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.

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

## 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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.

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
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](/core-concepts/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:

```bash theme={null}
npx momentic lint
```

Mobile:

```bash theme={null}
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:

```bash theme={null}
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](/core-concepts/test-format) for the YAML shape and
[MCP](/integrations/mcp-server) for MCP setup. For a spec-driven workflow that
uses Momentic tests as product specs, see
[Spec-driven development](/integrations/mcp-server#spec-driven-development) in
the MCP guide.