Skip to content

Commit c70ed10

Browse files
UbuntuCopilot
andcommitted
feat: Oxidizer recipe — automated Python-to-Rust migration workflow
Adds the oxidizer-workflow recipe, skill definition, and documentation. - amplifier-bundle/recipes/oxidizer-workflow.yaml: 65-step recipe with iterative convergence loops, quality audits, and zero-tolerance parity - .claude/skills/oxidizer-workflow/SKILL.md: Skill definition with activation keywords and usage examples - docs/OXIDIZER.md: Full documentation covering all phases, context variables, and the zero-tolerance policy - mkdocs.yml: Navigation entries for the workflow and skill Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 617f9ea commit c70ed10

4 files changed

Lines changed: 1410 additions & 0 deletions

File tree

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
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

Comments
 (0)