AI-Assisted Migration

Vivid provides an AI-powered migration skill that automates upgrading your project to the latest version. It combines codemods for repeatable changes with an AI agent that handles the rest - minimizing manual effort while keeping you in control.

Migrating between major versions of Vivid involves renaming attributes, updating CSS selectors, adjusting component defaults, and fixing type errors. Doing this manually is tedious and error-prone.

The vivid-v6-migration skill takes a hybrid approach:

1. Codemods handle repetitive, deterministic changes (attribute renames, CSS selector rewrites, package version bumps). This saves the AI’s context window for more complex work.
2. Local checks capture your project’s typecheck and lint baselines before and after migration, so only newly introduced errors are fixed.
3. AI agent takes over after the codemods, fixing remaining type errors, lint issues, and edge cases that require contextual understanding.
4. Manual review is flagged for changes that neither codemods nor the agent can safely automate. If there are changes that codemods or the agent could not migrate, a manual check is required.

After the migration, you should review the changes and run your test suites locally to confirm that everything is correct.

The skill automatically detects your current version and determines which migration steps are needed.

• Clean git state - commit or stash any uncommitted changes before starting.
• Node.js and npm installed.
• Your project must have at least one package.json containing @vonage/vivid or @vonage/vivid-vue.
• An AI coding assistant with terminal access (e.g., OpenCode or GitHub Copilot in VS Code agent mode).

The migration skill is distributed via the skills CLI - the standard tool for installing agent skills into AI coding assistants.

Run the following command in your project directory:

npx skills add https://github.com/Vonage/vivid-api/tree/main/libs/skills/vivid-v6-migration

The CLI will detect which supported agents you have installed and prompt you to select where to install the skill.

Once the skill is installed, ask your AI assistant to migrate your project:

Migrate my project to the latest version of Vivid.

The skill orchestrates the full migration workflow automatically. At a high level, the agent will:

1. Detect your current Vivid version by scanning package.json files across your project.
2. Capture a baseline of your project’s typecheck and lint output before making any changes.
3. Upgrade Vivid packages to the latest version.
4. Run the appropriate codemods (dry-run first, then apply) to handle all repeatable changes.
5. Flag items requiring manual review - changes that cannot be safely automated.
6. Fix newly introduced errors by comparing typecheck and lint output against the baseline and resolving only the differences.
7. Run your build and report the result.
8. Provide a summary of everything that was done, what was fixed, and what needs your attention.

For the full details of each step, including the exact codemod transforms and manual migration items, see the reference documentation:

• v4 Codemods (AGENTS.md) - CLI usage, all 13 transforms, and architecture
• v4 Manual Migration (MIGRATION.md) - breaking changes not covered by codemods
• v5 Codemods (AGENTS.md) - CLI usage, all 6 transforms, and architecture
• v5 Manual Migration (MIGRATION.md) - breaking changes not covered by codemods
• v6 Codemods (AGENTS.md) - CLI usage, all transforms, and architecture
• v6 Manual Migration (MIGRATION.md) - breaking changes not covered by codemods

Even with codemods and AI assistance, some changes may require your attention:

• Review the agent’s changes - look through the diff to confirm the changes are correct.
• Run your test suites locally - unit tests, integration tests, and end-to-end tests should all pass.
• Check visual regression tests - especially for components with visual changes (e.g., File Picker).
• Address any flagged manual review items from the migration summary.

The migration system is built in three layers, each handling a different aspect of the upgrade process.

At the base are the codemods - deterministic AST-based transforms that handle repeatable, mechanical changes. They use posthtml for HTML and Vue template transforms and jscodeshift for JSX transforms. The codemods operate on standard file patterns (**/*.{html,vue,jsx,tsx,css,scss,less}) and automatically skip node_modules, dist, and build directories. By offloading these repetitive changes to codemods, the AI agent’s context window is preserved for more complex work.

Above the codemods sit the migration guides (MIGRATION.md files), which document the breaking changes that require human judgment - cases where the correct fix depends on the developer’s intent, such as ambiguous Vue 2 prop bindings or visual design changes that need manual verification.

The top layer is the skill itself (SKILL.md), a structured set of instructions that the AI agent follows. It orchestrates the entire workflow: detecting the current version, capturing baselines, running codemods, consulting the migration guides, fixing newly introduced errors, and producing a final summary. The skill is agent-agnostic - it works with any AI coding tool that can read a SKILL.md file and execute shell commands.