Cross-Language Parity Rebuild

A general-purpose skill for fully rebuilding an existing software system from a source language into a target language while preserving public contracts, configuration semantics, runtime behavior, test baselines, and delivery boundaries as closely as possible.

The core skill content in this repository lives under migrate-skill/.

License: Apache-2.0

This repository maintains a standalone skill project, with its main content kept in the top-level migrate-skill/ directory for easier versioning, review, and distribution.

This project is not about “translating a few code snippets.” It is for more serious, engineering-heavy work such as:

• rebuilding an existing software system from language A into language B
• preserving API contracts, DSLs, database schemas, configuration semantics, runtime behavior, output contracts, and test baselines
• defining implementation phases, diff reports, missing-capability tracking, validation gates, checkpoint recovery, and delivery standards

When this skill is a good fit

Use this skill for tasks like these:

• fully migrating a service, SDK, CLI, runtime, workflow engine, or component library from one language to another
• doing a 1:1 rewrite, parity rebuild, dual-stack mirror implementation, or long-term parallel reimplementation
• producing a parity plan, gap analysis, migration order, and validation matrix before large-scale implementation starts
• deciding which layer should be rebuilt first, how to prevent protocol drift, and how to prove the target implementation still matches the source

Typical examples:

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

When this skill is not the right tool

This skill is not a good fit when:

• you only need to translate a single function, script, or algorithm
• you are only doing a same-language refactor with no cross-language parity goal
• you want a “roughly equivalent replacement” instead of a strict rebuild
• you only want a fast MVP and do not require protocol, behavior, and configuration alignment

Information that must be clarified first

Before implementation starts, try to confirm the following inputs. If any of them are missing, call out the gap explicitly instead of guessing:

1. Source scope: the whole repository, a subsystem, a package, or a group of services
2. Target language and runtime: language, framework, runtime, package manager, and build model
3. Parity goal: 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, DSL, configuration, permissions, cache, events, output, deployment, performance, logging
6. Validation rules: which diffs must be zero and which missing/blocked items are acceptable as long as they are documented

Checkpoint recovery requirements for long-running migrations

Cross-language migrations are often long-running efforts. They may be interrupted by shutdowns, session resets, context loss, or ownership changes. For that reason, this skill assumes that the migration process must support checkpoint recovery.

Beyond the design and implementation itself, the migration should maintain these three files:

1. Migration roadmap: the fixed route, phase order, dependencies, and completion criteria
2. Migration process: an append-only implementation log that records each round of work, evidence, blockers, and next steps
3. Migration execution context: the current checkpoint, latest validation results, working set, and recovery order

Recommended filenames:

• migration-roadmap.md
• migration-process.md
• migration-execution-context.md

Each file serves a different purpose:

• roadmap explains where the migration is going
• process explains what has already happened
• execution context explains where the work is currently paused and how to resume it

Without these three files, recovery after an interruption usually depends on memory alone, which is fragile and risky.

Core principles

1. Define the source of truth before writing the target implementation

The target implementation must not invent public contracts on its own. The source implementation is the only source of truth.

2. Build extraction and comparison tools before the main implementation

Without an inventory, contract extraction, and diff reports, parity work usually degrades into manual visual comparison.

3. Rebuild the protocol layer first, then the runtime, then the business modules

The recommended order is:

1. extraction / diff / reporting tools
2. protocol source-of-truth layer
3. runtime support layer
4. business module layer
5. integration and external exposure layer

4. Do not hide uncertainty behind fallback logic

If the source behavior is unclear, the target capability is missing, or a third-party dependency is not equivalent, mark the item as blocked or missing explicitly instead of guessing.

5. Temporary placeholders must leave a trail

If a rebuilt feature cannot be implemented yet and a stub, fake empty implementation, placeholder return, or disabled path is temporarily required, it must carry a nearby TODO plus a short explanation of the blocker, the expected real behavior, and the condition that should trigger the real implementation later.

6. Record every difference

That includes missing capabilities, dependency substitutions, temporarily blocked modules, and explicitly unsupported features.

7. Long-running work must always be recoverable

At the end of every phase, refresh migration-process and migration-execution-context. Otherwise, an interruption can turn an engineering project into an archaeology dig.

8. Validation must cover structure, behavior, and operational semantics

Compilation alone is not enough. You also need to validate interfaces, schemas, configuration behavior, golden cases, error behavior, output stability, and runtime boundaries.

Recommended execution path

Phase A: Define scope and success criteria

At a minimum, clarify:

• what is being rebuilt
• which modules are in scope
• which parity surfaces must match exactly
• which items may remain missing temporarily if they are documented
• what conditions count as “done”

Phase B: Build the source truth inventory

At a minimum, inspect these dimensions:

• repository and package structure
• public API / OpenAPI / RPC / CLI surfaces
• DTOs / schemas / DSLs / serialization formats
• configuration, environment variables, and default precedence
• permissions, audit boundaries, and visibility rules
• lifecycle, exceptions, error shapes, and event models
• database schema, indexes, constraints, and cache semantics
• test baselines, fixtures, and golden cases

Phase C: Build tooling and trace artifacts first

Before large-scale implementation begins, establish:

• migration roadmap
• migration process
• migration execution context
• file inventory
• file map
• contract extraction
• OpenAPI / schema / DSL diffs
• missing-capability list
• progress log / decision log

The first three are not optional project-management decoration. They are the infrastructure that makes interruption recovery possible.

If temporary placeholders exist, they should also be discoverable through TODO markers and documented replacement triggers.

Phase D: Implement layer by layer

The recommended main layers are:

1. Protocol truth layer: schemas, DTOs, DSLs, serialization, shared constants
2. Runtime support layer: input systems, loading, executors, events, exceptions, output handling
3. Business / adapter layer: services, routers, components, providers, repositories

Each layer should follow the same rhythm:

1. read the source truth
2. define the target location and public landing points
3. implement in small steps
4. validate in small steps
5. update diffs, missing items, and progress

Phase E: Finish the integration and delivery surface

This may include:

• backend / API
• CLI
• SDK
• integration endpoints
• deployment runtime

Validation and acceptance requirements

Basic quality gates

Every target-language package or subproject should at least support:

• build / compile
• lint
• format (if the project uses formatting)
• typecheck (if the target language supports it)

Structural parity gates

Validate whether the shapes still match:

• file map
• contract extraction
• OpenAPI diff
• schema drift
• DSL diff
• component / plugin / workflow contract diff

Behavioral parity gates

Validate whether the results still match:

• unit tests
• golden cases
• fixture replay
• endpoint behavior replay
• error-path replay
• serialization / deserialization roundtrips

Operational and runtime gates

Validate whether runtime behavior still matches:

• environment / configuration parsing parity
• logging / telemetry shape parity
• timeout / retry / concurrency behavior
• streaming / async output behavior
• startup / shutdown lifecycle parity

When the work must still be considered incomplete

You must not claim completion if any of the following is still true:

• key parity surfaces are undefined
• non-zero diffs are being hand-waved away
• missing capabilities are not explicitly documented
• only structure was validated but behavior was not
• only the target implementation validates itself without comparing against the source
• the next step cannot be recovered from the written artifacts after an interruption
• temporary stubs / fake empty implementations exist without a TODO and a clear explanation

Expected outputs

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

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

If temporary placeholders are present, the deliverables should also make them easy to rediscover by pointing to the TODO markers or equivalent tracking entries.

Common pitfalls

• writing the target implementation first and building tooling later
• confusing “similar behavior” with “matching protocol”
• silently rewriting defaults or optional / nullable semantics to fit target-language habits
• using empty implementations or fake success paths when a capability is missing
• leaving temporary placeholders behind without a TODO, explanation, or replacement trigger
• failing to keep enough checkpoint materials to resume work safely

Repository contents

• migrate-skill/SKILL.md: the full skill definition, boundaries, principles, and execution rules
• migrate-skill/references/implementation-checklist.md: implementation checklist and trace-artifact guidance
• migrate-skill/references/verification-matrix.md: validation matrix, checks, and acceptance gates
• migrate-skill/references/migration-roadmap-template.md: migration roadmap template
• migrate-skill/references/migration-process-template.md: migration process log template
• migrate-skill/references/migration-execution-context-template.md: migration checkpoint context template

Directory layout

The repository uses this structure:

• migrate-skill/SKILL.md
• migrate-skill/references/*

Key characteristics of this structure include:

• a clearly separated skill directory
• a stable directory name that matches the skill name
• a lowercase, hyphenated skill name
• relative paths for all reference documents

If you later want to embed this skill into a product repository, simply copy migrate-skill/ into .github/skills/migrate-skill/ inside the target repository.

Usage guidance

If you want to apply this skill in a real migration project, a good default rhythm is:

1. produce inventory / diff / roadmap first
2. rebuild the protocol layer
3. rebuild the runtime layer
4. rebuild business modules and providers
5. add integration / backend / CLI / deployment surfaces
6. run regression, drift checks, and delivery validation at the end

In one sentence: this is not a “code translator” skill. It is an engineering workflow for full cross-language parity rebuilds with explicit safeguards against protocol drift and behavior drift.