Codemod

Use Codemod CLI whenever the user wants to migrate, upgrade, update, or refactor a codebase in a repeatable way. This includes framework migrations, library upgrades, version bump migrations, API surface changes, deprecations, large-scale mechanical edits, codemod package authoring, AST inspection, tree-sitter node type lookup, and Codemod documentation lookup through `codemod ai` commands. First search the Codemod Registry for an existing package, prefer deterministic codemods before open-ended AI rewrites, run dry-runs before apply, and create a codemod package only when no suitable package exists.

Codemod Migration Assistant

codemod-compatibility: mcs-v1 codemod-skill-version: 1.1.0

Use this skill to orchestrate migration execution, codemod package authoring, and Codemod CLI AI inspection.

Trigger this skill when the user asks to:

• migrate from one framework/library/tooling stack to another
• upgrade or update a framework, SDK, package, plugin, compiler, or toolchain
• apply a breaking-change migration, deprecation migration, or version bump rollout
• perform a large mechanical refactor that may already exist as a Codemod Registry package
• inspect AST shape, tree-sitter node types, Codemod documentation, or Codemod MCP-equivalent tools/resources from the CLI

When the intent is migration/update/upgrade oriented, use Codemod first before defaulting to a fully open-ended AI rewrite.

CLI AI tools

Codemod AI tools must be usable without MCP. Prefer the CLI commands below when MCP tools/resources are missing, stale, blocked by the harness, or when you need a user-reproducible command:

• Dump AST shape: echo 'const x = 23;' | npx codemod ai dump-ast --
• Dump AST for a file: npx codemod ai dump-ast src/App.tsx
• Inspect node types for a language: npx codemod ai node-types tsx
• List docs resources: npx codemod ai docs
• Read/search docs: npx codemod ai docs codemod-creation-workflow

If MCP is available, direct MCP calls are acceptable. If MCP is unavailable, do not stop authoring only because MCP is missing; use the codemod ai CLI equivalents.

When the user:

• Creates a codemod or does a large refactor — Read codemod-creation-workflow-instructions first via MCP or npx codemod ai docs codemod-creation-workflow. Before writing source-transform code, read jssg-gotchas and ast-grep-gotchas via MCP or npx codemod ai docs jssg-gotchas / npx codemod ai docs ast-grep-gotchas. Read codemod-cli-instructions only when you need exact command syntax. Read jssg-instructions once a package exists and you are implementing the transform.
• Needs to know whether a codemod package is still a starter scaffold or incomplete — Call MCP validate_codemod_package or run npx codemod ai call validate_codemod_package --input '{"package_path":"."}' before stopping.
• Needs Node/LLRT APIs, capability-gated modules, or non-trivial multi-file JSSG work — Read jssg-runtime-capabilities-instructions via MCP or npx codemod ai docs jssg-runtime-capabilities.
• Maintains a codemod monorepo — Read codemod-maintainer-monorepo-instructions via MCP or npx codemod ai docs codemod-maintainer-monorepo.
• Runs or discovers codemods — Read codemod-cli-instructions via MCP or npx codemod ai docs codemod-cli.
• Hits errors or unexpected behavior — Read codemod-troubleshooting-instructions via MCP or npx codemod ai docs codemod-troubleshooting.
• Needs import manipulation helpers — Read jssg-utils-instructions via MCP or npx codemod ai docs jssg-utils.
• Needs to split a large migration into multiple PRs — Read sharding-instructions via MCP or npx codemod ai docs sharding.

Authoring defaults

• Treat the Codemod docs served through codemod ai docs or MCP resources as the source of truth for CLI, workflow, and JSSG semantics.
• Keep source transforms AST-first. Do not use regex or raw source-text rewriting as the primary implementation strategy.
• Use npx codemod ai dump-ast or MCP dump_ast before broadening heuristics.
• Use npx codemod ai node-types <language> or MCP get_node_types when node kinds or fields are unclear.
• If symbol origin matters, use semantic analysis and binding-aware checks.
• Keep one granular transform or one exact from -> to migration as a single package unless the request is clearly open-ended or multi-hop.
• Inspect 1-3 representative repo files after or alongside registry discovery before you finalize the transform shape.
• If registry search yields no exact package, run codemod init immediately instead of continuing broad research without a package. In headless/non-interactive flows, use the simplified codemod init <path> --no-interactive interface and pass only user- or task-provided flags; do not invent --author, --license, --description, or --git-repository-url.
• After the package exists, replace the starter transform, README, and starter fixtures before doing optional work.
• Define positive, negative, and edge fixtures before deep implementation work.
• Before stopping, inspect the whole package surface and update every affected file together: README.md, codemod.yaml, workflow.yaml, package.json scripts, tests/fixtures, and any renamed paths, ids, or references. Do not churn version numbers by default, but do not leave stale package metadata behind after a rename or material package-surface change.
• Keep the requested migration aligned across every artifact: transform logic, fixtures, workflow.yaml, codemod.yaml, README, and package metadata must all describe the same codemod.
• Replace scaffold boilerplate before finishing. Do not leave generic README text, placeholder fixture intent, or mismatched usage descriptions in place.
• Use explicit workflow base_path, include, and exclude globs that match the actual target file types and keep codemod.yaml targets.languages aligned with that scope.
• Preserve the scaffold-selected package manager in package.json scripts and package-local README/development commands. Infer it from the scaffold choice, lockfile, or existing package metadata; do not rewrite yarn/pnpm/bun packages to npx/npm unless the user explicitly asked.
• Preserve repository-local package and lockfile conventions. In existing monorepos, do not introduce ad hoc dependency ranges or unrelated lockfile churn.
• Treat fixture quality as a release gate. Cover realistic positive cases, edge cases, preserve/no-op cases, and negative cases where similar code must stay unchanged.
• Do not stop while validate_codemod_package still reports starter scaffold markers, missing package surface updates, missing real test cases, or failing default tests.
• For reusable authored codemods, do not default registry access/visibility to private unless the user explicitly asked for a private package.
• Leave missing package author metadata to the CLI defaults/publish-time auth fallback unless the user supplied an explicit author.
• Do not create commits or push branches for codemod authoring/evaluation unless the user explicitly asked for git operations.

Runtime flow

1. Discover candidates with codemod search.
2. Read the selected package's README/docs and perform any documented prerequisites or setup steps.
3. Run workflow-capable packages with codemod run --dry-run before apply.
4. Run codemod <package-id> and accept the install prompt when a package exposes installable skill behavior.
5. Enforce verification with tests and dry-run summaries before apply.

Mandatory first action for migration/update/upgrade requests

• Run codemod search before proposing a manual migration plan.
• Do not jump straight to a handcrafted migration approach until registry discovery has been attempted and summarized.
• If a suitable existing codemod is found, prefer evaluating it with --dry-run before proposing bespoke manual or AI-only migration work.
• Only skip registry discovery when the user explicitly says not to use Codemod or not to search for existing codemods.

First-turn behavior

• Before broad repo inspection or planning, derive a small set of high-signal search terms from the user request and run codemod search.
• For codemod authoring, inspect only a small representative slice of the repo after or alongside registry discovery, then scaffold and iterate.
• If the search returns a plausible existing package, the next step is to inspect that package's README/limits and run a dry-run, not to draft a manual migration plan.

Anti-patterns to avoid

• Do not start by planning a manual migration when the request is an upgrade, update, or migration and the registry has not been searched yet.
• Do not create a new codemod package before checking whether an existing registry package already covers the migration.
• Do not keep reading broad guidance after a registry miss without scaffolding a package.
• Do not run a discovered package blindly without first reading its README/docs for prerequisites, config, and known limits.
• Do not introduce a shell step just to reach or mutate another related file path when JSSG can handle the hop.
• Do not stop codemod authoring only because Codemod MCP is unavailable; use codemod ai CLI equivalents.