About this skill

Problem Being Solved

Cross-language migration of open-source projects is not just translating code files. It also requires preserving directory structure, algorithm steps, control flow, test data, ecosystem differences, and state across sessions. If an agent runs the migration autonomously, it may mark work complete without reading the source, generate content in bulk, silently confirm gaps, or advance phases prematurely.

How the Workflow Constrains the Migration

lang-migration uses an auditable multi-session workflow: every source file is analyzed and assigned a migration strategy, with priority on 1:1 structural equivalence. Behavioral equivalence is used only when an ecosystem gap makes structural parity impossible. Tests must use real implementations and real test data; mocking is not allowed. When a decision cannot be made autonomously, the workflow enters BLOCKED and waits for human input instead of skipping.

The pipeline covers P0 bootstrap of migration_workspace/ and YAML state, P1 asset scan, P2 ecosystem mapping, P3 IPO analysis, P4 translation, and P5 verification. Every fix requires a TDD retrospective and a full test re-run. After each phase, a PGR gate review must pass with zero findings and set phase_gates.PGR_N.passed_at before the phase can be marked DONE.

Boundaries

It fits engineering migrations with a clear source project, target language, and runnable tests. Projects with missing tests, poor structure, or large target-language ecosystem gaps will likely trigger frequent blocking and human confirmation.

Screenshots

Use Cases

Take over a Python open-source library and migrate it to Rust while preserving layout, control flow, and test structure.
Convert a C++ CLI tool to Go with per-file analysis, real tests, and no mocks.
Resume a large migration across sessions by restoring phase, task, and blocked state from migration-state.yaml.
Run a TDD retrospective after every compile or test failure, record root-cause rules, and re-run the full suite.

Best For

Senior engineers owning legacy-language migrations who need auditable migration state and phase gate reviews.
Development leads using AI agents for refactoring who need to prevent batch fabrication or premature task completion.
Open-source maintainers who need preserved control flow, test evidence, and root-cause fixes after a language switch.
Platform engineers handling technical debt who need cross-language migrations split into resumable, inspectable YAML workflows.