21-migration-companion

contentstack-migration-companion

Guide a user through migrating a project from Contentful to Contentstack — first the content (content types, entries, assets, locales) via the Contentstack CLI migrate plugin, then the website code that reads from the CMS.

This is a sequential workflow where each step produces output that the next step consumes (the create command produces a populated stack and a bundle with credentials, which feeds the code migration). Treat the artifact paths and counts that each command prints as state you must capture and carry forward.

Operating principles

Follow these throughout — they matter more than any single command:

• Work in a unique session workspace. At the very start of Step 1, create a session-scoped directory by running:

  SESSION_ID=$(date +%Y%m%d-%H%M%S) && SESSION_DIR="/tmp/migrate-to-cs/$SESSION_ID" && mkdir -p "$SESSION_DIR" && echo "SESSION_DIR=$SESSION_DIR"
  

  Record the printed SESSION_DIR value (e.g. /tmp/migrate-to-cs/20260608-143022) and carry it as a concrete literal through every shell command in this migration — do not regenerate it. This keeps each migration run isolated so concurrent sessions and re-runs never collide. If the user points you to a different workspace, use their path instead.
• Bundled scripts & references live next to this skill — resolve them via {SKILL_DIR}. This skill ships helper scripts (a scripts/ folder) and reference docs (a references/ folder) alongside this SKILL.md file. Wherever these instructions write {SKILL_DIR}, substitute the absolute path of the directory this SKILL.md was loaded from — i.e. the skill's own install directory. Do not assume a fixed path. The location differs by AI assistant, by OS, and by whether the skill was installed per-project or per-user — for example it may be <project>/.claude/skills/contentstack-migration-companion, ~/.claude/skills/contentstack-migration-companion, or a Windows path like %USERPROFILE%\.claude\skills\contentstack-migration-companion. Determine the real path once (it is the folder you read this SKILL.md from; if unsure, search the workspace and home directory for */contentstack-migration-companion/SKILL.md), and for shell commands set it as a variable up front (SKILL_DIR="<that absolute path>") so bundled scripts can be invoked as "$SKILL_DIR/scripts/<name>". The bundled scripts self-locate their own siblings, so once you invoke them by absolute path they work regardless of your current directory.
• Pin the Node version for the whole session. A machine often has several Node versions (system, Homebrew, multiple nvm installs) and a non-interactive shell may resolve an old one (e.g. /usr/local/bin/node v14) ahead of the user's nvm default. The Step 1 prereq checker finds the highest installed Node ≥ 20 and reports its directory as node.bin_dir in the JSON. Record that value as a concrete literal NODE_BIN_DIR and prefix every csdx, npm, and contentful command for the rest of the migration with it, e.g. PATH="<NODE_BIN_DIR>:$PATH" csdx migrate:create …. This guarantees the CLI runs on the Node the prereq check validated, not whatever an unconfigured shell picks first. If node.bin_dir is absent (older check output), fall back to the plain command.
• One step at a time, and show the result. After each command, surface the meaningful output to the user — the summary tables, the counts, the artifact path — not a wall of raw logs. The user is watching this like a progress bar; give them a clean status, then the path/handle the next step needs.
• Track migration progress with the checklist. At each [PROGRESS] trigger below, output a progress block in your response using these emoji: ✅ = completed, ⏳ = currently running, ⬜ = not yet started. Example for Step 3 in progress:

  **Migration progress**
  - ✅ Step 1 — Prerequisites & inputs
  - ✅ Step 2 — Install migrate plugin
  - ⏳ Step 3 — Content Migration
  - ⬜ Step 4 — Code Migration
  

  Output it at two moments: (1) at the start of each step, and (2) when each step's eval passes. Only one step is ⏳ at a time. Step 4 stays ⏳ through all sub-steps 4.1–4.6. Step 5 (Welcome) is not tracked — it triggers automatically once Step 4 is ✅.
• Gate the destructive or expensive steps. Confirm before logging in, before creating a new stack, and before editing the user's code. These either touch live accounts or modify their repo, so a quick "ready to proceed?" prevents nasty surprises.
• Capture the outputs explicitly. When a command prints a bundle path, a log directory, or a stack API key, record the exact path/value and reuse it verbatim. Do not guess paths — read them back from the command output.
• Browser-based login is normal here. csdx auth:login --oauth opens the user's browser; the terminal then blocks and auto-detects when they finish. Run it, tell the user to complete login in the browser, and simply wait for the command to return — do not try to script the browser or kill the command.
• Currently Contentful is the only supported source. Do not ask the user which legacy platform they're on; assume Contentful. (The CLI flag is --source contentful.)
• If a step fails, stop and diagnose rather than barrelling ahead. Most failures here are recoverable (expired token → re-login, missing content model → inform the user), and the relevant recovery is described in the step that can fail.
• Never display code in your text output. Do not show shell commands, code snippets, scripts, or any fenced code blocks (``` blocks) in your chat messages at any point during the migration. Just run commands silently and report the result in plain prose. The user sees tool calls in the tool panel — repeating code in chat is noise.