migrate-skill

name

migrate-skill

description

Build a full-parity software implementation from one programming language to another. Use whenever the user wants to port, rewrite, mirror, rebuild, migrate, or 1:1 replicate an existing codebase, subsystem, service, runtime, CLI, SDK, or workflow engine from a source language into a target language while preserving public contracts, schemas, configuration semantics, runtime behavior, tests, operational boundaries, and interruption-safe checkpoint recovery. Also use this skill when the user asks for a parity migration plan, checkpoint recovery plan, missing-capability list, migration roadmap/process/execution-context files, diff/report strategy, phased migration order, or verification gates for a cross-language reimplementation.

Cross-Language Parity Rebuild

A general-purpose skill for full cross-language parity rebuilds.

It is designed for clearly bounded engineering work with verifiable parity goals and strong traceability, not for mechanically translating a few snippets from one language into another.

This skill is meant for work such as:

• fully rebuilding an existing software system from a source language into a target language
• preserving APIs, DSLs, database schemas, configuration semantics, runtime behavior, output contracts, and test baselines
• establishing implementation order, diff reports, missing lists, validation gates, checkpoint recovery, and delivery standards

When to use

Load this skill when any of the following is true:

• The user wants to rebuild a system, service, SDK, toolchain, runtime, CLI, workflow engine, or component library from language A into language B.
• The user wants a 1:1 rewrite, parity rebuild, mirror implementation, or dual-stack parallel rebuild.
• The user wants a migration plan, gap analysis, validation matrix, or regression strategy for a cross-language rebuild.
• The user wants to know which layer to rebuild first, how to avoid protocol drift, or how to verify that the target implementation still matches the source.

Typical examples:

• Python → TypeScript
• Java → Go
• Ruby → Kotlin
• C# → Rust

When not to use

Do not use this skill when:

• you are only translating a single algorithm, function, or script
• you are only doing a same-language refactor with no cross-language parity target
• the goal is a roughly equivalent replacement instead of a full rebuild
• the goal is only a fast MVP with no strict contract, behavior, configuration, or data-shape alignment

Information that must be clarified first

Before implementation begins, try to confirm the following inputs. If anything is missing, call out the gap explicitly instead of guessing:

1. Source scope: the entire repository, a subsystem, a package, a group of services, or a class of components
2. Target language and runtime: language, framework, runtime, package manager, and build model
3. Parity target: full parity, interface parity, behavior parity, or only public-contract parity
4. Replacement strategy: dual-stack parallel run, full replacement, or long-term coexistence
5. Critical parity surfaces: API, database schema, workflow DSL, configuration, permissions, cache, events, output, deployment, performance, logging
6. Validation rules: which diffs must be zero and which blocked / missing items may remain as long as they are documented

If these inputs are still incomplete, list the gaps first and only then continue. The biggest danger in cross-language rebuilds is not speed; it is getting 70% right while the remaining 30% silently drifts.

Core principles

1. Define the source of truth before writing the target implementation
   The target implementation must not invent public contracts. The source implementation defines the truth.

2. Build extraction and comparison tooling before the main implementation
   Without inventory, contract extraction, and diff reports, parity work usually degrades into risky manual comparison.

3. Rebuild the protocol layer first, then the runtime, then business modules
   Align shapes first, execution semantics second, and module behavior last.

4. Do not hide uncertainty behind fallback logic
   If the source is unclear, the target capability is missing, or a third-party library is not equivalent, mark it explicitly as blocked / missing instead of guessing.

5. Temporary placeholders must be discoverable and explicitly marked
   If a rebuilt feature cannot be implemented yet and you must temporarily use a stub, fake empty implementation, placeholder return, or disabled branch, add a TODO at the implementation site and explain why the real implementation is blocked, what the expected behavior should be, and what condition would allow the placeholder to be replaced.

6. Record every difference
   That includes missing capabilities, replaced dependencies, temporarily blocked target modules, and explicitly unsupported features.

7. Long-running work must be checkpoint-recoverable
   Migrations may last for weeks or months and will be interrupted by shutdowns, session resets, and context loss. Maintain migration-roadmap, migration-process, and migration-execution-context by default so recovery does not depend on guesswork.

8. Validation must cover structure, behavior, and operational semantics
   Compilation alone is not enough. Validate interfaces, schemas, configuration behavior, golden cases, error behavior, and output stability as well.

Standard procedure

The goal of the following steps is not ceremony. The goal is to make the work verifiable, traceable, and recoverable. In multi-round projects, any interruption should be recoverable from the existing artifacts rather than from memory.

Step 1: Define scope and success criteria

Answer these questions first:

• What is being rebuilt?
• What is the main module or main surface?
• Which surfaces must achieve parity?
• Which surfaces may remain temporarily missing as long as they are documented?
• What exactly counts as done for final delivery?

Produce at least:

• a scope statement
• a description of main and supporting modules
• a parity-surface list
• a definition of done

Step 2: Build the source truth inventory

Inventory the source implementation systematically. Do not rely on directory names alone.

At a minimum, inspect these dimensions:

• package / directory structure
• public API / OpenAPI / RPC / CLI surfaces
• data structures / schemas / DTOs / DSLs / serialization formats
• configuration / .env / default precedence
• permissions / scopes / visibility / audit boundaries
• runtime lifecycle / events / exceptions / error structures
• persistence layer / tables / indexes / constraints
• test baselines / fixtures / golden cases

If the project is large, establish inventory, file-map, and contract extraction entry points first.

See ./references/implementation-checklist.md for the detailed execution checklist.

Step 3: Break the source implementation into the layers that must be rebuilt first

At a minimum, split the work into three layers:

1. Protocol truth layer
   Public shapes, schemas, DSLs, OpenAPI, serialization, shared DTOs
2. Runtime support layer
   Input systems, executors, lifecycle, events, errors, loading, scheduling
3. Business / adapter layer
   Modules, components, routes, services, providers, storage adapters, tool integrations

If the user does not provide an order, use this default priority:

1. extraction / diff / reporting tools
2. protocol layer
3. runtime layer
4. business modules
5. integration / external exposure layer

Step 4: Build tooling, trace artifacts, and recovery files first

Before large-scale target implementation begins, establish the following first:

• migration-roadmap: fixed route, phase breakdown, dependency order, and completion criteria
• migration-process: append-only migration log recording each day or iteration, evidence, blockers, and next steps
• migration-execution-context: current checkpoint, latest validation results, working set, and next recovery order
• file inventory / file map
• contract extraction
• OpenAPI / schema / DSL diff
• component / plugin / workflow contract diff
• missing-capability list
• progress log / decision log

If the task requires a full rebuild, these artifacts are prerequisites, not decorative extras for the end.

Without the three recovery files, large-scale implementation should not begin. Otherwise, interruption recovery becomes memory-driven and high-risk.

Step 5: Implement the target-language version phase by phase, layer by layer

Each layer follows the same pattern:

1. Read the source truth.
2. Define the target landing directory.
3. Define the target-language public contract.
4. Implement in small steps.
5. If a temporary stub / fake empty implementation is unavoidable, mark it with a TODO and explain the missing prerequisite, expected real behavior, and replacement trigger.
6. Validate in small steps.
7. Update diffs, missing items, and progress.

Step 6: Validate each layer structurally and behaviorally

For every completed layer, confirm at least the following:

• build / lint / typecheck pass
• corresponding contract diffs converge
• golden cases / unit tests cover the main behavior
• configuration, errors, and outputs have not drifted

See ./references/verification-matrix.md for the detailed validation matrix.

Step 7: Handle missing / blocked items instead of pretending the work is complete

When the target language lacks an equivalent capability:

• explain why the item is missing
• document dependency differences
• document the impact scope
• state whether the item is blocked or approved-missing
• do not use empty implementations or fake success paths without a TODO and an explicit explanation

If a temporary placeholder is unavoidable, record at least the following:

• the exact implementation location
• a TODO marker near the placeholder code
• the reason the real implementation is currently blocked
• the expected real behavior once conditions are met
• the condition, dependency, or milestone that should trigger the real implementation work

Step 8: Form the final delivery surface

At the end, you should be able to answer at least these questions:

• Which areas already achieve parity?
• Which areas are still missing / blocked?
• Which reports show zero diff?
• Which validations have already run?
• Where should the next recovery step resume?

Output requirements

When using this skill, the final output should include at least:

1. Migration roadmap: phase order, main path, key dependencies, and completion criteria
2. Migration process: append-only process record preserving implementation history and evidence
3. Migration execution context: current checkpoint, validated state, and next recovery order
4. Parity surface list: which objects require 1:1 alignment
5. Validation matrix: which tests / diffs / gates apply to each layer
6. Missing / blocked list: cannot be omitted

If any temporary placeholders exist, the output should also make them discoverable by identifying where the TODO markers live and what still needs to happen before they can be replaced.

If the current round does not finish the full goal, also state clearly:

• which layer has been completed so far
• which validations have already run
• which diffs still need to converge
• where the next round should resume

General rules

1. The target-language directory structure must remain stable.
2. A single public semantic should have only one source of truth.
3. Public contract field names, types, defaults, and nullable / optional semantics must not be changed casually.
4. Any new adapter, compatibility, or transitional fields require explicit approval; otherwise they are forbidden by default.
5. Environment variables, configuration parsing order, and default chains must align or be explicitly documented as differences.
6. Any temporary stub, fake empty implementation, placeholder return value, or disabled path must include a nearby TODO describing the blocker, expected behavior, and replacement trigger.
7. Before pausing work at the end of any phase, refresh migration-process and migration-execution-context so recovery can resume directly after interruption.
8. Tests must trace back to source-language baselines rather than only checking whether the target is internally self-consistent.

Recommended delivery rhythm

For multi-round engineering work, use this default rhythm:

1. Produce inventory / diff / roadmap first.
2. Rebuild the protocol layer.
3. Rebuild the runtime layer.
4. Rebuild business modules and providers.
5. Rebuild integration / backend / CLI / deployment surfaces.
6. Run regression and drift checks at the end.

Failure handling

If the current task cannot continue, explain which type of blocker applies:

• insufficient source truth
• target runtime / framework not defined
• third-party dependencies lack equivalent capabilities
• validation rules not defined
• replacement strategy not defined

Do not offer a “default version for now.” That is not a rebuild; that is wishful thinking. 🙂

References to read during execution

• For the implementation steps and layer-by-layer checklist: ./references/implementation-checklist.md
• For validation, checks, diffs, and acceptance gates: ./references/verification-matrix.md
• For creating the migration roadmap: ./references/migration-roadmap-template.md
• For recording the migration process: ./references/migration-process-template.md
• For saving checkpoint recovery context: ./references/migration-execution-context-template.md