/commerce-app-migrate

name: commerce-app-migrate
description: >
  Migrate an Adobe Commerce App Builder project from the Integration Starter Kit or Checkout Starter Kit to the new App Management approach. Run from the root of the App Builder project to be migrated. Pass --auto to skip confirmation prompts (suitable for CI or batch use) — auto mode prints a summary of all Q&A questions answered with their defaults. Pass --doc-scan-only to scan README.md and env.dist for outdated content without modifying any files. Use when the user wants to migrate an App Builder project from the Integration Starter Kit or Checkout Starter Kit to the App Management approach, or mentions upgrading their Adobe Commerce extension architecture.
license: Apache-2.0
compatibility: >
  Requires Node.js 22+, aio CLI, and @adobe/aio-commerce-lib-app.
  Run from the root of the App Builder project being migrated.
metadata:
  author: adobe
  sdk-package: "@adobe/aio-commerce-lib-app"
  version: "0.0.1"

Migrate to App Management

Use this skill when the user wants to migrate an Adobe Commerce App Builder project from the Integration Starter Kit or Checkout Starter Kit to the new App Management approach using `@adobe/aio-commerce-lib-app`.

This skill orchestrates the full migration: detection → domain analysis → Q&A → config assembly → execution. It leaves the project fully migrated and ready to deploy.

Confirmation protocol

At each step marked **[await]**: end your turn immediately, output nothing further, and wait for the developer's reply before proceeding.

**Autonomous mode:** If invoked with `--auto` or `--yes`, or the context indicates an automated pipeline (no interactive terminal), skip all **[await]** points and proceed directly to the next step.

**Doc-scan-only mode:** If invoked with `--doc-scan-only`, skip all migration steps after the Analyzer. After Step 1 completes (Analyzer returns a `ProjectSnapshot`):

• If `alreadyMigrated === false`, output:

--doc-scan-only requires the project to already be migrated to App Management. No app.commerce.config.ts (or .js) was found.

Run /commerce-app-migrate (without --doc-scan-only) to perform the migration first.

Then stop.

• If `alreadyMigrated === true`, apply any applicable Cross-cutting Warnings, then

dispatch the Executor in doc-scan-only mode. No files are modified. Do not proceed to Steps 2–5.

---

Preflight Check

Before doing anything else, verify the current directory looks like an App Builder project. Check that ALL of these exist:

• `app.config.yaml`
• `package.json`
• At least one of: `actions/` directory OR `src/` directory OR `actions-src/` directory

(some projects compile TypeScript from `actions-src/` to `actions/`; `actions/` may be gitignored and absent in a fresh checkout)

If none of those pass, stop immediately and output:

This directory does not appear to be a Commerce App Builder project. Expected to find: app.config.yaml, package.json, and an actions/ or src/ directory.

Please run this skill from the root of your App Builder project.

Do not proceed further if the preflight fails.

---

Step 1: Run Analyzer Agent

Dispatch the Analyzer agent (defined in `${CLAUDE_SKILL_DIR}/agents/analyzer.md`) using the Agent tool. The Analyzer reads the current directory and returns a `ProjectSnapshot` JSON object (schema defined in `${CLAUDE_SKILL_DIR}/shared/schema.md`).

**Before printing the summary, check these early-exit conditions:**

**If `alreadyMigrated === true`:** Output:

This project appears to already be migrated to App Management. Found: app.commerce.config.ts (or app.commerce.config.js with ESM defineConfig)

Re-running migration would overwrite your existing configuration. If you want to re-generate specific sections, please specify which section to update: metadata / eventing / installation / adminUi / businessConfig

Then apply any applicable Cross-cutting Warnings (see subsection below).

Then dispatch the Executor agent (`${CLAUDE_SKILL_DIR}/agents/executor.md`) in **doc-scan-only mode** to produce documentation recommendations for the project:

• Pass `mode = "doc-scan-only"` to the Executor
• Pass the `ProjectSnapshot` JSON from the Analyzer
• Pass `assembled config = null` (no new config to write)

The Executor will scan `README.md` and `env.dist` against the existing `app.commerce.config.ts` and print the "Documentation recommendations" report without modifying any files.

**Do not proceed to Steps 2–5 (domain agents, Q&A, config assembly, full execution) unless the developer explicitly requests a specific section update.**

After the Executor prints the documentation recommendations, **stop**. Do not continue to the "Detected project:" summary block or the migration confirmation prompt below.

After the Analyzer returns, print a human-readable summary:

Detected project: Type: <starterKitType> Starter Kit Auth mode: <authMode> (<paas = "PaaS/OAuth1" | saas = "SaaS/IMS" | dual = "Both PaaS + SaaS" | unknown = "Unknown">) Action packages: <comma-separated list of package names> (<count> packages) Onboarding: <comma-separated list of script paths with purposes, or "none"> Package manager: <packageManager>

Migration will include: <list domains where confidence !== "none">

Apply any applicable Cross-cutting Warnings (see subsection below).

**If `hasMeshConfig === true`**, also append:

⚠ API Mesh configuration detected (mesh.json). Mesh configuration cannot be migrated automatically and must be preserved manually.

Then ask:

Does this look correct? (yes / no — if no, describe what's wrong) Press Enter or type "yes" to proceed automatically.

**[await]**

**Handle corrections:**

• If developer corrects `starterKitType`, update it in the ProjectSnapshot before proceeding
• If developer corrects `authMode`, update it
• Re-print summary with corrections and ask again until confirme