Migrate Legacy Codebases to Safe Rust
Act as a Systems Architect, Performance Engineer, and Rust Specialist. Your goal
is to migrate legacy codebases into 100% Safe, PGO-tuned Rust while recording
measured telemetry and a first-person engineering narrative via
scripts/telemetry.py.
Execution Contract & Portability
When migrating a repository or local directory ({github_url} or
{codebase_path}), follow these execution rules across agentic harnesses:
- Stage 0 External Code Confirmation Gate: After cloning an external
repository and inspecting its build files, present the resolved legacy
build command, run command, and target directory to the user and obtain
confirmation before compiling or executing cloned code. (For local code
that the user explicitly instructed you to run, or once Stage 0 confirmation
is granted, proceed directly.)
- Continuous Stage 1 -> Stage 2 Progression: Once Stage 0 baseline
capture is complete, proceed directly from writing the Architectural
Blueprint (Stage 1) into implementing and verifying the Rust workspace
(Stage 2) without pausing between milestones, where the host environment
permits autonomous tool execution.
- Bounded Automated Self-Healing (Max 5 Iterations): When tests,
clippy
lints, or A/B parity checks fail, log the failure via
scripts/telemetry.py, diagnose and fix the root
cause, and re-test automatically up to a budget of 5 self-healing
iterations (or 15 minutes per phase). If any test or seed still diverges
after the budget is exhausted, record the partial state in
migration_telemetry.json and document the remaining gap in the final
report rather than looping indefinitely.
- Verification Targets & Definition of Done:
#![forbid(unsafe_code)] Rust crate compiles with a target of 0
cargo clippy warnings (any unavoidable exception must be documented).
- Unit, integration, doc, and property-based (
proptest) tests pass with
a target of >= 95% branch coverage (any unavoidable exception must be
documented), with every run logged in migration_telemetry.json.
- A/B differential output parity is verified across
N deterministic
seeds within a documented numerical epsilon (--max-abs-error), with
any floating-point/FMA/PRNG divergence root-caused and logged.
- All 4 benchmark stages (
legacy_baseline, safe_rust, soa_simd,
pgo_lto) are measured and logged (or omitted cleanly if a tool such as
llvm-profdata is unavailable).
- The interactive HTML infographic (
migration_infographic.html) is
rendered via scripts/telemetry.py render-infographic.
End-to-End Workflow Checklist
Copy this checklist to track progress across the three stages (detailed command
recipes and architectural specifications are in
references/pgo_and_telemetry_guide.md):
- [ ] Stage 0: Acquire repo, initialize `migration_telemetry.json` (`discovery` bucket), scan legacy codebase, confirm resolved build/run commands, and benchmark baseline
- [ ] Stage 1: Audit legacy code (`blueprint` bucket), log opportunities & latent legacy bugs, and generate 6-section Architectural Blueprint
- [ ] Stage 2.1: Scaffold `#![forbid(unsafe_code)]` Rust workspace & deterministic PRNG parity layer (`rewrite` bucket)
- [ ] Stage 2.2: Implement core domain types & SoA/SIMD kernels (<= 400 LOC/file target, full rustdoc) & benchmark `safe_rust` + `soa_simd`
- [ ] Stage 2.3: Run Verification Crucible (`test_heal` bucket, max 5 iterations) — log initial test failure % and each self-healing fix
- [ ] Stage 2.4: Run A/B differential parity harness (`parity` bucket, max 5 iterations) across N seeds within documented epsilon tolerance
- [ ] Stage 2.5: Run LLVM Profile-Guided Optimization (`pgo_bench` bucket), scan final Rust codebase, and render `migration_infographic.html`
Stage 0: Repository Acquisition, Telemetry Init & Legacy Baseline
Resolve context parameters from the repository or directory:
| Parameter |
Placeholder |
Resolution Strategy |
| Source Input |
{codebase_path} or {github_url} |
Accept a GitHub URL (https://github.com/...) or a local filesystem path |
| Original Language / Framework |
{legacy_language} |
Auto-detect from file extensions and build files (CMakeLists.txt, Makefile, meson.build, pyproject.toml, pom.xml, *.f90, *.cpp) |
| Baseline Run Command |
{baseline_run_command} |
Identify from README.md, CI workflows (.github/workflows/*.yml), Makefile, or test scripts |
| Telemetry Ledger |
{workspace_dir}/migration_telemetry.json |
Initialized via scripts/telemetry.py init at the start of Stage 0 |
Stage 0 Execution Steps
- Clone Repository (if GitHub URL): Choose a clean local directory
(default to
~/rust_migrations/{repo_name}, or inside the current workspace
if requested) and run git clone {github_url} ~/rust_migrations/{repo_name}.
- Initialize Telemetry & Scan Legacy Codebase: Run
scripts/telemetry.py init --telemetry "{workspace_dir}/migration_telemetry.json" --project-name "{project_name}" --legacy-lang "{legacy_language}". Start the discovery
bucket and run scripts/telemetry.py scan-codebase --phase before on the
legacy source directory to record baseline file count, code LOC, comment
density %, max file LOC, nesting depth, average function length, and raw
pointer/memory hazards.
- Confirm & Benchmark Legacy Baseline: Before executing build or run
commands from a cloned external repository, surface the resolved build
command,
{baseline_run_command}, and working directory for user
confirmation. Once confirmed, compile the legacy project in release mode
(-O3 / Release), capture golden reference outputs across deterministic
seeds, measure baseline wall-clock runtime (ms) and peak RSS (MB), and log
Stage 1 via scripts/telemetry.py log-benchmark --stage legacy_baseline.
Stage 1: Deep Audit, Opportunity Discovery & Architectural Blueprint
Start the blueprint timer bucket (scripts/telemetry.py start-bucket --bucket blueprint), inspect the repository, log every discovered opportunity and
latent legacy bug (scripts/telemetry.py log-opportunity), and generate the
6-section Markdown blueprint defined in Section 2 of
references/pgo_and_telemetry_guide.md.
Stage 1 -> Stage 2 Transition: Save the blueprint and proceed directly to
Stage 2 (unless the user explicitly requested a blueprint-only plan).
Stage 2: Phased Safe Rust Implementation, Self-Healing, PGO & Infographic
Follow the command recipes and core engineering standards in
references/pgo_and_telemetry_guide.md
for each step:
Step 1: Scaffold Safe Rust Workspace & Port Modules (rewrite Bucket)
- Start the
rewrite timer bucket (scripts/telemetry.py start-bucket --bucket rewrite).
- Initialize the Rust workspace with
#![forbid(unsafe_code)] in src/lib.rs
and src/main.rs.
- Implement the deterministic PRNG wrapper, domain types, and modules in
dependency order (
<= 400 LOC per file target, complete //! and ///
rustdoc with runnable doc-tests).
- Benchmark and log Stage 2 (
safe_rust) and Stage 3 (soa_simd) via
scripts/telemetry.py log-benchmark.
Step 2: The Verification Crucible — Test, Fail, Diagnose & Fix (test_heal Bucket)
- Start the
test_heal timer bucket (scripts/telemetry.py start-bucket --bucket test_heal).
- Write unit tests, runnable doc-tests, and
proptest boundary tests.
- Run
cargo test --all-targets, cargo test --doc, and cargo clippy --all-targets.
- Log Every Iteration (Up to 5 Iterations): After Run 1 and each
subsequent run, invoke
scripts/telemetry.py log-test-run with total tests,
passed, failed, coverage %, clippy warnings, diagnostic summary, and fix
applied. Iterate until 0 failures and 0 warnings (or until the
5-iteration budget is reached, documenting any unavoidable exception).
Step 3: A/B Differential Output Parity (parity Bucket)
- Start the
parity timer bucket (scripts/telemetry.py start-bucket --bucket parity).
- Run the automated A/B differential harness across
N deterministic seeds
comparing {baseline_run_command} and the Rust binary within the documented
epsilon tolerance.
- Log each parity iteration via
scripts/telemetry.py log-parity-run. If any
seed diverges beyond epsilon, bisect the first diverging step, repair the
discrepancy, and re-run (up to 5 iterations).
Step 4: Profile-Guided Optimization (PGO) & Final Benchmarks (pgo_bench Bucket)
- Start the
pgo_bench timer bucket (scripts/telemetry.py start-bucket --bucket pgo_bench).
- Execute the LLVM PGO workflow in
references/pgo_and_telemetry_guide.md:
build with
RUSTFLAGS="-Cprofile-generate=./pgo-data", run representative
workloads, merge profiles via llvm-profdata, and rebuild with
RUSTFLAGS="-Cprofile-use=./pgo-data/merged.profdata" and lto = "fat"
(or use the documented -Ctarget-cpu=native fallback if llvm-profdata is
unavailable).
- Verify that tests and A/B parity still pass on the PGO binary, then measure
wall-clock runtime and peak RSS and log Stage 4 (
pgo_lto) via
scripts/telemetry.py log-benchmark --stage pgo_lto.
Step 5: Final Census, First-Person AI Story & Visual Infographic
Run scripts/telemetry.py scan-codebase --phase after on src/ to capture
final LOC, <= 400 LOC compliance, comment/rustdoc density, runnable
doc-tests, nesting depth, and unsafe block count.
Log a Before vs. After Code Spotlight (scripts/telemetry.py log-spotlight) and populate the First-Person AI Story Chapters
(scripts/telemetry.py set-story).
End the pgo_bench timer bucket and render the interactive HTML infographic
(where {skill_dir} is the directory containing this SKILL.md):
python3 "{skill_dir}/scripts/telemetry.py" render-infographic \
--telemetry "{workspace_dir}/migration_telemetry.json" \
--out "{output_dir}/migration_infographic.html" \
--scope-summary "{short_summary_of_ported_modules}"
Output a concise executive summary referencing the generated
migration_infographic.html report and key measured before/after metrics.
Bundled Resources
- Telemetry & Infographic CLI:
scripts/telemetry.py
- Engineering Standards, Blueprint Spec, PGO & Telemetry Recipes:
references/pgo_and_telemetry_guide.md
- Interactive HTML Infographic Template:
references/infographic_template.html
1---2name: migrate-to-rust3metadata:4 source: https://skillmd.com/skills/google/migrate-to-rust5 version: "1.0.0"6 category: ApplicationDevelopment7description: >-8 Clones, analyzes, plans, and migrates legacy codebases (C++, Fortran, Java,9 Python, C, Shell) from a GitHub URL or local directory to a modern,10 high-performance, deterministic, 100% Safe Rust architecture, tracking live11 telemetry across every task bucket, test failure/fix cycle, and12 Profile-Guided Optimization (PGO) stage, and producing a first-person AI13 storytelling report and interactive HTML infographic. Use when migrating a14 GitHub repository or local codebase to Rust, porting legacy C++, Fortran,15 Python, or Java workloads to memory-safe Rust, designing Struct-of-Arrays16 (SoA) or SIMD Rust architectures, or optimizing Rust ports with LLVM PGO.17 Don't use for unrelated non-Rust refactoring or single-line syntax questions.18---1920# Migrate Legacy Codebases to Safe Rust2122Act as a Systems Architect, Performance Engineer, and Rust Specialist. Your goal23is to migrate legacy codebases into 100% Safe, PGO-tuned Rust while recording24measured telemetry and a first-person engineering narrative via25[`scripts/telemetry.py`](scripts/telemetry.py).2627## Execution Contract & Portability2829When migrating a repository or local directory (`{github_url}` or30`{codebase_path}`), follow these execution rules across agentic harnesses:31321. **Stage 0 External Code Confirmation Gate**: After cloning an external33 repository and inspecting its build files, **present the resolved legacy34 build command, run command, and target directory to the user and obtain35 confirmation before compiling or executing cloned code**. (For local code36 that the user explicitly instructed you to run, or once Stage 0 confirmation37 is granted, proceed directly.)382. **Continuous Stage 1 -> Stage 2 Progression**: Once Stage 0 baseline39 capture is complete, proceed directly from writing the Architectural40 Blueprint (Stage 1) into implementing and verifying the Rust workspace41 (Stage 2) without pausing between milestones, where the host environment42 permits autonomous tool execution.433. **Bounded Automated Self-Healing (Max 5 Iterations)**: When tests, `clippy`44 lints, or A/B parity checks fail, log the failure via45 [`scripts/telemetry.py`](scripts/telemetry.py), diagnose and fix the root46 cause, and re-test automatically up to a budget of **5 self-healing47 iterations** (or 15 minutes per phase). If any test or seed still diverges48 after the budget is exhausted, record the partial state in49 `migration_telemetry.json` and document the remaining gap in the final50 report rather than looping indefinitely.514. **Verification Targets & Definition of Done**:52 - `#![forbid(unsafe_code)]` Rust crate compiles with a target of `0`53 `cargo clippy` warnings (any unavoidable exception must be documented).54 - Unit, integration, doc, and property-based (`proptest`) tests pass with55 a target of `>= 95%` branch coverage (any unavoidable exception must be56 documented), with every run logged in `migration_telemetry.json`.57 - A/B differential output parity is verified across `N` deterministic58 seeds within a documented numerical epsilon (`--max-abs-error`), with59 any floating-point/FMA/PRNG divergence root-caused and logged.60 - All 4 benchmark stages (`legacy_baseline`, `safe_rust`, `soa_simd`,61 `pgo_lto`) are measured and logged (or omitted cleanly if a tool such as62 `llvm-profdata` is unavailable).63 - The interactive HTML infographic (`migration_infographic.html`) is64 rendered via `scripts/telemetry.py render-infographic`.6566## End-to-End Workflow Checklist6768Copy this checklist to track progress across the three stages (detailed command69recipes and architectural specifications are in70[references/pgo_and_telemetry_guide.md](references/pgo_and_telemetry_guide.md)):7172```markdown73- [ ] Stage 0: Acquire repo, initialize `migration_telemetry.json` (`discovery` bucket), scan legacy codebase, confirm resolved build/run commands, and benchmark baseline74- [ ] Stage 1: Audit legacy code (`blueprint` bucket), log opportunities & latent legacy bugs, and generate 6-section Architectural Blueprint75- [ ] Stage 2.1: Scaffold `#![forbid(unsafe_code)]` Rust workspace & deterministic PRNG parity layer (`rewrite` bucket)76- [ ] Stage 2.2: Implement core domain types & SoA/SIMD kernels (<= 400 LOC/file target, full rustdoc) & benchmark `safe_rust` + `soa_simd`77- [ ] Stage 2.3: Run Verification Crucible (`test_heal` bucket, max 5 iterations) — log initial test failure % and each self-healing fix78- [ ] Stage 2.4: Run A/B differential parity harness (`parity` bucket, max 5 iterations) across N seeds within documented epsilon tolerance79- [ ] Stage 2.5: Run LLVM Profile-Guided Optimization (`pgo_bench` bucket), scan final Rust codebase, and render `migration_infographic.html`80```8182--------------------------------------------------------------------------------8384## Stage 0: Repository Acquisition, Telemetry Init & Legacy Baseline8586Resolve context parameters from the repository or directory:8788Parameter | Placeholder | Resolution Strategy89:-------------------------------- | :----------------------------------------- | :------------------90**Source Input** | `{codebase_path}` or `{github_url}` | Accept a GitHub URL (`https://github.com/...`) or a local filesystem path91**Original Language / Framework** | `{legacy_language}` | Auto-detect from file extensions and build files (`CMakeLists.txt`, `Makefile`, `meson.build`, `pyproject.toml`, `pom.xml`, `*.f90`, `*.cpp`)92**Baseline Run Command** | `{baseline_run_command}` | Identify from `README.md`, CI workflows (`.github/workflows/*.yml`), `Makefile`, or test scripts93**Telemetry Ledger** | `{workspace_dir}/migration_telemetry.json` | Initialized via `scripts/telemetry.py init` at the start of Stage 09495### Stage 0 Execution Steps96971. **Clone Repository (if GitHub URL)**: Choose a clean local directory98 (default to `~/rust_migrations/{repo_name}`, or inside the current workspace99 if requested) and run `git clone {github_url}100 ~/rust_migrations/{repo_name}`.1012. **Initialize Telemetry & Scan Legacy Codebase**: Run `scripts/telemetry.py102 init --telemetry "{workspace_dir}/migration_telemetry.json" --project-name103 "{project_name}" --legacy-lang "{legacy_language}"`. Start the `discovery`104 bucket and run `scripts/telemetry.py scan-codebase --phase before` on the105 legacy source directory to record baseline file count, code LOC, comment106 density %, max file LOC, nesting depth, average function length, and raw107 pointer/memory hazards.1083. **Confirm & Benchmark Legacy Baseline**: Before executing build or run109 commands from a cloned external repository, surface the resolved build110 command, `{baseline_run_command}`, and working directory for user111 confirmation. Once confirmed, compile the legacy project in release mode112 (`-O3` / `Release`), capture golden reference outputs across deterministic113 seeds, measure baseline wall-clock runtime (ms) and peak RSS (MB), and log114 Stage 1 via `scripts/telemetry.py log-benchmark --stage legacy_baseline`.115116--------------------------------------------------------------------------------117118## Stage 1: Deep Audit, Opportunity Discovery & Architectural Blueprint119120Start the `blueprint` timer bucket (`scripts/telemetry.py start-bucket --bucket121blueprint`), inspect the repository, log every discovered opportunity and122**latent legacy bug** (`scripts/telemetry.py log-opportunity`), and generate the1236-section Markdown blueprint defined in Section 2 of124[references/pgo_and_telemetry_guide.md](references/pgo_and_telemetry_guide.md).125126**Stage 1 -> Stage 2 Transition**: Save the blueprint and proceed directly to127Stage 2 (unless the user explicitly requested a blueprint-only plan).128129--------------------------------------------------------------------------------130131## Stage 2: Phased Safe Rust Implementation, Self-Healing, PGO & Infographic132133Follow the command recipes and core engineering standards in134[references/pgo_and_telemetry_guide.md](references/pgo_and_telemetry_guide.md)135for each step:136137### Step 1: Scaffold Safe Rust Workspace & Port Modules (`rewrite` Bucket)1381391. Start the `rewrite` timer bucket (`scripts/telemetry.py start-bucket140 --bucket rewrite`).1412. Initialize the Rust workspace with `#![forbid(unsafe_code)]` in `src/lib.rs`142 and `src/main.rs`.1433. Implement the deterministic PRNG wrapper, domain types, and modules in144 dependency order (`<= 400` LOC per file target, complete `//!` and `///`145 rustdoc with runnable doc-tests).1464. Benchmark and log Stage 2 (`safe_rust`) and Stage 3 (`soa_simd`) via147 `scripts/telemetry.py log-benchmark`.148149### Step 2: The Verification Crucible — Test, Fail, Diagnose & Fix (`test_heal` Bucket)1501511. Start the `test_heal` timer bucket (`scripts/telemetry.py start-bucket152 --bucket test_heal`).1532. Write unit tests, runnable doc-tests, and `proptest` boundary tests.1543. Run `cargo test --all-targets`, `cargo test --doc`, and `cargo clippy155 --all-targets`.1564. **Log Every Iteration (Up to 5 Iterations)**: After Run 1 and each157 subsequent run, invoke `scripts/telemetry.py log-test-run` with total tests,158 passed, failed, coverage %, clippy warnings, diagnostic summary, and fix159 applied. Iterate until `0` failures and `0` warnings (or until the160 5-iteration budget is reached, documenting any unavoidable exception).161162### Step 3: A/B Differential Output Parity (`parity` Bucket)1631641. Start the `parity` timer bucket (`scripts/telemetry.py start-bucket --bucket165 parity`).1662. Run the automated A/B differential harness across `N` deterministic seeds167 comparing `{baseline_run_command}` and the Rust binary within the documented168 epsilon tolerance.1693. Log each parity iteration via `scripts/telemetry.py log-parity-run`. If any170 seed diverges beyond epsilon, bisect the first diverging step, repair the171 discrepancy, and re-run (up to 5 iterations).172173### Step 4: Profile-Guided Optimization (PGO) & Final Benchmarks (`pgo_bench` Bucket)1741751. Start the `pgo_bench` timer bucket (`scripts/telemetry.py start-bucket176 --bucket pgo_bench`).1772. Execute the LLVM PGO workflow in178 [references/pgo_and_telemetry_guide.md](references/pgo_and_telemetry_guide.md):179 build with `RUSTFLAGS="-Cprofile-generate=./pgo-data"`, run representative180 workloads, merge profiles via `llvm-profdata`, and rebuild with181 `RUSTFLAGS="-Cprofile-use=./pgo-data/merged.profdata"` and `lto = "fat"`182 (or use the documented `-Ctarget-cpu=native` fallback if `llvm-profdata` is183 unavailable).1843. Verify that tests and A/B parity still pass on the PGO binary, then measure185 wall-clock runtime and peak RSS and log Stage 4 (`pgo_lto`) via186 `scripts/telemetry.py log-benchmark --stage pgo_lto`.187188### Step 5: Final Census, First-Person AI Story & Visual Infographic1891901. Run `scripts/telemetry.py scan-codebase --phase after` on `src/` to capture191 final LOC, `<= 400` LOC compliance, comment/rustdoc density, runnable192 doc-tests, nesting depth, and `unsafe` block count.1932. Log a **Before vs. After Code Spotlight** (`scripts/telemetry.py194 log-spotlight`) and populate the **First-Person AI Story Chapters**195 (`scripts/telemetry.py set-story`).1963. End the `pgo_bench` timer bucket and render the interactive HTML infographic197 (where `{skill_dir}` is the directory containing this `SKILL.md`):198199 ```bash200 python3 "{skill_dir}/scripts/telemetry.py" render-infographic \201 --telemetry "{workspace_dir}/migration_telemetry.json" \202 --out "{output_dir}/migration_infographic.html" \203 --scope-summary "{short_summary_of_ported_modules}"204 ```2054. Output a concise executive summary referencing the generated206 `migration_infographic.html` report and key measured before/after metrics.207208--------------------------------------------------------------------------------209210## Bundled Resources211212- **Telemetry & Infographic CLI**:213 [`scripts/telemetry.py`](scripts/telemetry.py)214- **Engineering Standards, Blueprint Spec, PGO & Telemetry Recipes**:215 [references/pgo_and_telemetry_guide.md](references/pgo_and_telemetry_guide.md)216- **Interactive HTML Infographic Template**:217 [references/infographic_template.html](references/infographic_template.html)