|
| 1 | +--- |
| 2 | +name: oxidizer-workflow |
| 3 | +description: | |
| 4 | + Automated Python-to-Rust migration via iterative convergence loops. |
| 5 | + Treats the Python codebase as the living specification and produces a |
| 6 | + fully-tested Rust equivalent with zero-tolerance parity validation. |
| 7 | + Use when migrating Python modules, libraries, or CLIs to Rust. |
| 8 | + Activates for: migration, oxidize, python to rust, port to rust, rewrite in rust. |
| 9 | +--- |
| 10 | + |
| 11 | +# Oxidizer Workflow Skill |
| 12 | + |
| 13 | +## Purpose |
| 14 | + |
| 15 | +Orchestrates the `oxidizer-workflow` recipe to migrate Python codebases to Rust. |
| 16 | +The workflow is recursive and goal-seeking — it loops until 100% feature parity |
| 17 | +is achieved, with quality audit and silent degradation checks on every iteration. |
| 18 | + |
| 19 | +## When to Use |
| 20 | + |
| 21 | +- Migrating a Python module, package, or CLI to Rust |
| 22 | +- Porting a Python library to a standalone Rust crate |
| 23 | +- Creating a Rust binary that replaces a Python tool |
| 24 | + |
| 25 | +## Core Principles |
| 26 | + |
| 27 | +1. **Tests first** — Python test coverage must be complete before any porting begins |
| 28 | +2. **Zero tolerance** — 100% parity required; partial results are not accepted |
| 29 | +3. **Quality gates** — Every iteration runs clippy, fmt, and a full test suite |
| 30 | +4. **No silent degradation** — Every feature, edge case, and error path must be preserved |
| 31 | +5. **Iterative convergence** — Module-by-module, loop until converged |
| 32 | + |
| 33 | +## Required Inputs |
| 34 | + |
| 35 | +| Input | Example | Description | |
| 36 | +|-------|---------|-------------| |
| 37 | +| `python_package_path` | `src/amplihack/recipes` | Path to the Python package to migrate | |
| 38 | +| `rust_target_path` | `rust/recipe-runner` | Where to create the Rust project | |
| 39 | +| `rust_repo_name` | `amplihack-recipe-runner` | GitHub repo name for the Rust project | |
| 40 | +| `rust_repo_org` | `rysweet` | GitHub org or user for the repo | |
| 41 | + |
| 42 | +## Execution |
| 43 | + |
| 44 | +### Via Recipe Runner |
| 45 | + |
| 46 | +```bash |
| 47 | +recipe-runner-rs amplifier-bundle/recipes/oxidizer-workflow.yaml \ |
| 48 | + --set python_package_path=src/mypackage \ |
| 49 | + --set rust_target_path=rust/mypackage \ |
| 50 | + --set rust_repo_name=my-rust-package \ |
| 51 | + --set rust_repo_org=myorg |
| 52 | +``` |
| 53 | + |
| 54 | +### Via Python API |
| 55 | + |
| 56 | +```python |
| 57 | +from amplihack.recipes import run_recipe_by_name |
| 58 | +from amplihack.recipes.adapters.cli_subprocess import CLISubprocessAdapter |
| 59 | + |
| 60 | +result = run_recipe_by_name( |
| 61 | + "oxidizer-workflow", |
| 62 | + adapter=CLISubprocessAdapter(), |
| 63 | + user_context={ |
| 64 | + "python_package_path": "src/mypackage", |
| 65 | + "rust_target_path": "rust/mypackage", |
| 66 | + "rust_repo_name": "my-rust-package", |
| 67 | + "rust_repo_org": "myorg", |
| 68 | + }, |
| 69 | +) |
| 70 | +``` |
| 71 | + |
| 72 | +## Workflow Phases |
| 73 | + |
| 74 | +``` |
| 75 | +Phase 1: Analysis |
| 76 | + └─ AST analysis, dependency mapping, type inference, public API extraction |
| 77 | +
|
| 78 | +Phase 1B: Test Completeness Gate |
| 79 | + └─ Measure coverage → write missing tests → re-verify → BLOCK if < 100% |
| 80 | +
|
| 81 | +Phase 2: Scaffolding |
| 82 | + └─ cargo init, add dependencies, create module structure |
| 83 | +
|
| 84 | +Phase 3: Test Extraction |
| 85 | + └─ Port Python tests to Rust test modules → quality audit tests |
| 86 | +
|
| 87 | +Phase 4-6: Iterative Convergence Loop (× N until 100% parity) |
| 88 | + ├─ Select next module (priority order from Phase 1) |
| 89 | + ├─ Implement module in Rust |
| 90 | + ├─ Compare: feature matrix diff against Python |
| 91 | + ├─ Quality gate: cargo clippy + fmt + test |
| 92 | + ├─ Silent degradation audit: check for lossy conversions |
| 93 | + ├─ Fix any degradation found |
| 94 | + └─ Convergence check: if < 100% parity → loop again |
| 95 | +
|
| 96 | +Final: Summary report with parity matrix |
| 97 | +``` |
| 98 | + |
| 99 | +## Convergence Rules |
| 100 | + |
| 101 | +- Each iteration processes one module at a time (core-out strategy) |
| 102 | +- Up to 5 unrolled loops in the recipe, plus `max_depth: 8` for sub-recipes |
| 103 | +- The recipe terminates when `convergence_status == "CONVERGED"` or |
| 104 | + `iteration_number > max_iterations` (default 30) |
| 105 | +- If max iterations reached without convergence, the final summary reports |
| 106 | + which modules are still incomplete |
| 107 | + |
| 108 | +## What Success Looks Like |
| 109 | + |
| 110 | +- Rust project builds cleanly (`cargo build`) |
| 111 | +- All tests pass (`cargo test`) |
| 112 | +- Zero clippy warnings (`cargo clippy -- -D warnings`) |
| 113 | +- Formatted (`cargo fmt --check`) |
| 114 | +- Feature parity matrix shows 100% coverage |
| 115 | +- No silent degradation detected |
0 commit comments