Oxidizer Workflow Skill
Purpose
Orchestrates the oxidizer-workflow recipe to migrate Python codebases to Rust.
The workflow is recursive and goal-seeking — it loops until 100% feature parity
is achieved, with quality audit and silent degradation checks on every iteration.
When to Use
- Migrating a Python module, package, or CLI to Rust
- Porting a Python library to a standalone Rust crate
- Creating a Rust binary that replaces a Python tool
Core Principles
- Tests first — Python test coverage must be complete before any porting begins
- Zero tolerance — 100% parity required; partial results are not accepted
- Quality gates — Every iteration runs clippy, fmt, and a full test suite
- No silent degradation — Every feature, edge case, and error path must be preserved
- Iterative convergence — Module-by-module, loop until converged
Required Inputs
| Input |
Example |
Description |
python_package_path |
crates/amplihack-recipe/src |
Path to the package to migrate |
rust_target_path |
rust/recipe-runner |
Where to create the Rust project |
rust_repo_name |
amplihack-recipe-runner |
GitHub repo name for the Rust project |
rust_repo_org |
rysweet |
GitHub org or user for the repo |
Execution
Via Recipe Runner
amplihack recipe run amplifier-bundle/recipes/oxidizer-workflow.yaml \
-c python_package_path=src/mypackage \
-c rust_target_path=rust/mypackage \
-c rust_repo_name=my-rust-package \
-c rust_repo_org=myorg
Workflow Phases
Phase 1: Analysis
└─ AST analysis, dependency mapping, type inference, public API extraction
Phase 1B: Test Completeness Gate
└─ Measure coverage → write missing tests → re-verify → BLOCK if < 100%
Phase 2: Scaffolding
└─ cargo init, add dependencies, create module structure
Phase 3: Test Extraction
└─ Port Python tests to Rust test modules → quality audit tests
Phase 4-6: Iterative Convergence Loop (× N until 100% parity)
├─ Select next module (priority order from Phase 1)
├─ Implement module in Rust
├─ Compare: feature matrix diff against Python
├─ Quality gate: cargo clippy + fmt + test
├─ Silent degradation audit: check for lossy conversions
├─ Fix any degradation found
└─ Convergence check: if < 100% parity → loop again
Final: Summary report with parity matrix
Convergence Rules
- Each iteration processes one module at a time (core-out strategy)
- Up to 5 unrolled loops in the recipe, plus
max_depth: 8 for sub-recipes
- The recipe terminates when
convergence_status == "CONVERGED" or
iteration_number > max_iterations (default 30)
- If max iterations reached without convergence, the final summary reports
which modules are still incomplete
Recipe Location
The oxidizer recipe is at:
amplifier-bundle/recipes/oxidizer-workflow.yaml
The recipe is the executable workflow — this skill is the discovery and activation
layer. When investigating or customizing the workflow phases, agent prompts, or
convergence rules, start with the recipe file above.
Effective Rust Compliance
The oxidizer workflow enforces idiomatic Rust practices aligned with the
Effective Rust guide by David Drysdale. Key rules
baked into every iteration:
Types (Items 1–6)
- Use Rust's type system to make invalid states unrepresentable (
enum with data)
- Use
Option<T> for optional values — never sentinel values like -1 or null
- Use
Result<T, E> for fallible operations — never panic on expected errors
- Use the newtype pattern for domain-specific semantics (units, IDs, validated strings)
- Prefer
From/Into conversions over as casts
- Use
thiserror for library error types, anyhow for application error handling
Unsafe (Item 16)
- Avoid writing
unsafe code — use standard library and crate abstractions instead
- If
unsafe is absolutely required (FFI), isolate it in a wrapper module with safety comments
- Run Miri over any
unsafe code
- Enable the
unsafe_op_in_unsafe_fn lint
Parallelism (Item 17)
- Prefer channels (
std::sync::mpsc) over shared state when possible
- Use
Arc<Mutex<T>> for shared state — keep lock scopes small
- Group related data under a single lock to prevent deadlocks
- Never invoke closures or return
MutexGuard with locks held
- Include deadlock detection in CI (
parking_lot::deadlock, ThreadSanitizer)
Tooling (Items 29, 31, 32)
cargo clippy -- -D warnings on every iteration
cargo fmt --check on every iteration
cargo doc to verify documentation compiles
cargo-udeps to detect unused dependencies
cargo-deny for license and advisory checks
cargo bench with std::hint::black_box for realistic benchmarks
What Success Looks Like
- Rust project builds cleanly (
cargo build)
- All tests pass (
cargo test)
- Zero clippy warnings (
cargo clippy -- -D warnings)
- Formatted (
cargo fmt --check)
- Feature parity matrix shows 100% coverage
- No silent degradation detected
- Zero
unsafe blocks (or justified, isolated, and Miri-tested)
- Idiomatic Rust types — no sentinel values, no stringly-typed APIs
1---
2name: oxidizer-workflow
3description: |
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.
9metadata:
10 source: https://skillmd.com/skills/rysweet/oxidizer-workflow
11---
12
13# Oxidizer Workflow Skill
14
15## Purpose
16
17Orchestrates the `oxidizer-workflow` recipe to migrate Python codebases to Rust.
18The workflow is recursive and goal-seeking — it loops until 100% feature parity
19is achieved, with quality audit and silent degradation checks on every iteration.
20
21## When to Use
22
23- Migrating a Python module, package, or CLI to Rust
24- Porting a Python library to a standalone Rust crate
25- Creating a Rust binary that replaces a Python tool
26
27## Core Principles
28
291. **Tests first** — Python test coverage must be complete before any porting begins
302. **Zero tolerance** — 100% parity required; partial results are not accepted
313. **Quality gates** — Every iteration runs clippy, fmt, and a full test suite
324. **No silent degradation** — Every feature, edge case, and error path must be preserved
335. **Iterative convergence** — Module-by-module, loop until converged
34
35## Required Inputs
36
37| Input | Example | Description |
38| --------------------- | ------------------------- | ------------------------------------- |
39| `python_package_path` | `crates/amplihack-recipe/src` | Path to the package to migrate |
40| `rust_target_path` | `rust/recipe-runner` | Where to create the Rust project |
41| `rust_repo_name` | `amplihack-recipe-runner` | GitHub repo name for the Rust project |
42| `rust_repo_org` | `rysweet` | GitHub org or user for the repo |
43
44## Execution
45
46### Via Recipe Runner
47
48```bash
49amplihack recipe run amplifier-bundle/recipes/oxidizer-workflow.yaml \
50 -c python_package_path=src/mypackage \
51 -c rust_target_path=rust/mypackage \
52 -c rust_repo_name=my-rust-package \
53 -c rust_repo_org=myorg
54```
55
56
57
58## Workflow Phases
59
60```
61Phase 1: Analysis
62 └─ AST analysis, dependency mapping, type inference, public API extraction
63
64Phase 1B: Test Completeness Gate
65 └─ Measure coverage → write missing tests → re-verify → BLOCK if < 100%
66
67Phase 2: Scaffolding
68 └─ cargo init, add dependencies, create module structure
69
70Phase 3: Test Extraction
71 └─ Port Python tests to Rust test modules → quality audit tests
72
73Phase 4-6: Iterative Convergence Loop (× N until 100% parity)
74 ├─ Select next module (priority order from Phase 1)
75 ├─ Implement module in Rust
76 ├─ Compare: feature matrix diff against Python
77 ├─ Quality gate: cargo clippy + fmt + test
78 ├─ Silent degradation audit: check for lossy conversions
79 ├─ Fix any degradation found
80 └─ Convergence check: if < 100% parity → loop again
81
82Final: Summary report with parity matrix
83```
84
85## Convergence Rules
86
87- Each iteration processes one module at a time (core-out strategy)
88- Up to 5 unrolled loops in the recipe, plus `max_depth: 8` for sub-recipes
89- The recipe terminates when `convergence_status == "CONVERGED"` or
90 `iteration_number > max_iterations` (default 30)
91- If max iterations reached without convergence, the final summary reports
92 which modules are still incomplete
93
94## Recipe Location
95
96The oxidizer recipe is at:
97
98```
99amplifier-bundle/recipes/oxidizer-workflow.yaml
100```
101
102The recipe is the executable workflow — this skill is the discovery and activation
103layer. When investigating or customizing the workflow phases, agent prompts, or
104convergence rules, start with the recipe file above.
105
106## Effective Rust Compliance
107
108The oxidizer workflow enforces idiomatic Rust practices aligned with the
109[Effective Rust](https://effective-rust.com/) guide by David Drysdale. Key rules
110baked into every iteration:
111
112### Types (Items 1–6)
113
114- Use Rust's type system to make invalid states unrepresentable (`enum` with data)
115- Use `Option<T>` for optional values — never sentinel values like `-1` or `null`
116- Use `Result<T, E>` for fallible operations — never panic on expected errors
117- Use the newtype pattern for domain-specific semantics (units, IDs, validated strings)
118- Prefer `From`/`Into` conversions over `as` casts
119- Use `thiserror` for library error types, `anyhow` for application error handling
120
121### Unsafe (Item 16)
122
123- **Avoid writing `unsafe` code** — use standard library and crate abstractions instead
124- If `unsafe` is absolutely required (FFI), isolate it in a wrapper module with safety comments
125- Run [Miri](https://github.com/rust-lang/miri) over any `unsafe` code
126- Enable the `unsafe_op_in_unsafe_fn` lint
127
128### Parallelism (Item 17)
129
130- Prefer channels (`std::sync::mpsc`) over shared state when possible
131- Use `Arc<Mutex<T>>` for shared state — keep lock scopes small
132- Group related data under a single lock to prevent deadlocks
133- Never invoke closures or return `MutexGuard` with locks held
134- Include deadlock detection in CI (`parking_lot::deadlock`, ThreadSanitizer)
135
136### Tooling (Items 29, 31, 32)
137
138- `cargo clippy -- -D warnings` on every iteration
139- `cargo fmt --check` on every iteration
140- `cargo doc` to verify documentation compiles
141- `cargo-udeps` to detect unused dependencies
142- `cargo-deny` for license and advisory checks
143- `cargo bench` with `std::hint::black_box` for realistic benchmarks
144
145## What Success Looks Like
146
147- Rust project builds cleanly (`cargo build`)
148- All tests pass (`cargo test`)
149- Zero clippy warnings (`cargo clippy -- -D warnings`)
150- Formatted (`cargo fmt --check`)
151- Feature parity matrix shows 100% coverage
152- No silent degradation detected
153- Zero `unsafe` blocks (or justified, isolated, and Miri-tested)
154- Idiomatic Rust types — no sentinel values, no stringly-typed APIs