codemod

# 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 reusable JSSG 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. --- > Source: [codemod/codemod](https://github.com/codemod/codemod) — distributed by [TomeVault](https://tomevault.io). <!-- tomevault:4.0:skill_md:2026-07-20 -->