py2rs-loop-lab

Architecture skills for creating project-specific engineering-loop skills.

中文 README

py2rs-loop-lab is a loop-engineering repository for controlled engineering work: rewrites, feature additions, dependency decisions, DAG scheduling and independent review.

It is not a drop-in skill pack. Use AI to read this repository as an architecture reference, then ask it to create concrete skills for your actual project. The real loop starts only after the project has its own facts, constraints, manifest, records, verification policy and review gates.

If you want open-ended creative exploration, this is the wrong tool. This project is for bounded engineering work: durable state, verification evidence, dependency alignment, review reports, rollback and release decisions.

How To Use It

  1. Start with a real project repository.
  2. Ask AI to study this repository's ideas and architecture.
  3. Have AI design project-specific skills for that repository: coordinator, writer, review, dependency/bootstrap, or other roles that are actually useful.
  4. Initialize the workspace: mission, resources, notes, records, manifest, verification policy, dependency policy, unit granularity, review cadence, phase-DAG execution and resource-lock policy.
  5. Enter the loop selected by a composition skill, such as py2rs for rewrites or feature-addition for regression-first feature work.

The core output is not Rust code. The core output is a project-specific loop that can keep producing reviewed, verified engineering changes.

Migration Note

The top-level skills moved from py2rs-specific names to three layers:

  • skills/foundations/*: reusable mechanisms such as unit slicing, DAG execution, review gates, dependency alignment and seam bootstrap.
  • skills/compositions/*: engineering loops that compose those mechanisms, including py2rs and feature-addition.
  • skills/practices/*: concrete project skills bound to real repositories.

Old top-level py2rs-runtime, py2rs-review-r0-r6, py2rs-crate-recon, py2rs-dep-align and py2rs-env-bootstrap directories were removed rather than kept as compatibility wrappers.

Current Architecture

The architecture separates five decisions that are easy to conflate:

  • Dependency and work policy: initialization records project preferences, relevant framework constraints, crate reconnaissance mode and registry policy. When a capability is actually needed, recon and alignment decide whether to reuse a dependency, call a lower backend, add an adapter, or hand-write the project-owned behavior.
  • Verification target: every unit records how it proves completion and what old behavior might regress. py2rs uses behavior_parity_first; feature-addition uses regression_first.
  • Review budget and cadence: review roles are selected by risk. A batch may share one review context while still giving every unit its own verdict.
  • Manifest partitioning and execution mode: shards group context, ownership and rollback boundaries; a compiled phase DAG selects runnable work from artifact dependencies, path/resource locks and capacity, rather than shard order. Start in dry_run with one slot. Enable parallel mutation only after explicit user acceptance, an approved baseline, isolated worktrees and a coordinator for integration, shared dependencies and the Cargo build queue.
  • Project skill execution mode: each coordinator, dependency bootstrap, writer or review role independently selects prompt or scaffold. Use prompt while the workflow still needs creative iteration; switch to scaffold only after its inputs, outputs and failure paths are stable and validated, so scripts can own deterministic operations.

The two variants may replace each other as the project matures, but exactly one variant per role may remain under agent discovery roots. Archive the counterpart outside those roots, write the new state back to NOTES.md, then start a fresh session. This preserves freedom for architectural judgment without spending prompt tokens on mechanics that have already stabilized.

Why There Seem To Be Many Steps

These mechanisms do not require every migration unit to run every possible flow. They trade a small amount of up-front control work for less repeated search, context reconstruction and rework. The goal is to save tokens and time and increase rewrite throughput while preserving user control, project fit and strong behavioral consistency.

Mechanism What it saves or protects in this project
Manifest, records and reviews A new session reads owners, rollback routes, prior decisions and evidence instead of rescanning the project or relying on chat memory.
Separate granularity and review cadence Code stays in small testable, rollbackable units while a writer completes several units continuously and three share one review context by default. Fewer role switches increase rewrite throughput; a small project can use end_of_scope and review after all writing finishes.
review_budget and per-unit verdicts Low-risk units do not need every role. Batch reports reuse context while still allowing passing units to advance independently.
Explicit verification target Every unit names acceptance, regression, or parity evidence before implementation. Tensor, codec, artifact, model-loading and handoff checks remain in parity review when they cross the selected seam.
Phase DAG with dry-run admission A large inventory can be partitioned for context without forcing an execution order. The compiler derives ready work from real artifacts and locks, exposes the critical path, and starts with one slot before any parallel mutation is enabled.
Canonical shared dependencies Concurrent Cargo builds contend for locks and target artifacts, while shared dependencies may also change Cargo.toml/Cargo.lock. If Burn lacks a required capability, one hand-written canonical prerequisite is created in the project and reused; agents may not build mutually invisible copies under /tmp.
Rewrite preferences and relevant-only framework questions Initialization records crate-reuse depth and asks only about framework categories the project needs. Later units do not repeat the interview or preinstall speculative dependencies.
Fresh-context crate reconnaissance with compact reports Registry search, Context7 checks and Cargo dependency paths stay in an isolated context; dependency alignment normally reads only the summary, reducing both prompt load and rework from a poor dependency choice. Users can select manual or disabled mode to control that cost.
Project-specific skills Stable registry queries, state transitions, batch flushing and report validation can move into project scripts, increasing the speed of repeated operations.
Project truth, accepted seam and rollback py2rs does not force one router or directory layout. A Tauri project may keep its command -> backend facade, while a Python-orchestrated project may use a Python router, and the manifest retains a route back to the legacy owner.

Parallel mutation remains an exception. A coordinator exclusively owns the canonical graph, integration branch, shared dependency registry, shared Cargo files and serialized build queue; workers use isolated worktrees and edit only their assigned paths. Reviews still serialize per unit, while disjoint review sets may proceed only when their checks and state writes cannot race.

The objective is not "more process is more rigorous." It is to spend tokens where judgment is needed, encode stable mechanics once, let writers progress continuously for higher rewrite throughput, let the user control review frequency, and preserve consistency with canonical dependencies, R0, per-unit evidence and promotion rules. The user controls the seam and any explicit comparison tolerance before implementation.

Stateful Incremental Repository Architecture

py2rs does not rely on one long prompt to finish a migration. It turns the migration into a stateful, resumable, reviewable and rollbackable repository workflow. Each AI session should read the durable state instead of relying on chat memory.

  • mission: records why the rewrite exists, what success means and which behaviors or constraints must not be lost
  • resources: stores source-of-truth docs, existing tests, dependency source snapshots, protocol notes and trusted references so AI does not rewrite from memory
  • notes: captures user preferences, including the rewrite-depth and framework profile, plus project constraints and temporary observations
  • records: preserves non-obvious decisions, lessons, behavior differences, dependency tradeoffs and review conclusions for later sessions
  • manifest / checklist: records each migration unit's state, owner, target owner, behavior verification seam and commands, rollback route, required review gates, cadence, partitioning, phases, artifacts, owned paths and resource locks; this is the rewrite control plane
  • compiled DAG snapshot: records the input commit, manifest revision, runnable nodes, dependencies, locks, capacity and critical-path estimate; changed inputs make affected downstream evidence stale
  • shared dependency registry: records the one project path, owner, consumers and build evidence for shared crates, forks, adapters, generated sources or hand-written capabilities
  • crate reconnaissance: searches by capability, uses Context7 for focused API/feature docs, and follows Cargo dependencies before a high-level crate is rejected or behavior is hand-written
  • dependency alignment: applies the recorded rewrite/framework preferences while mapping Python dependencies, Rust crates, semantic-delta adapters and hand-written replacements by capability coverage
  • bootstrap: proves the chosen seam handles parameters, return values, errors, logs, tests and rollback before business logic is migrated
  • review evidence: lets a batch share each role's context while requiring per-unit verdicts; a unit advances only after its R0 behavior and required R1-R6 reviews

The point of this architecture is that the system stays runnable, testable and rollbackable at every migration state. Even if a new AI session takes over, it can continue from the repository's mission, records, manifest and reviews instead of guessing project state.

Initialization Preferences And Dependency Timing

The initialization architecture separates user intent from migration state. A two-stage interview records strategy and relevant frameworks, crate reconnaissance/network choices, review cadence, partitioning and execution policy. DAG execution begins in dry_run with one agent slot; the bundled compiler validates artifact edges, locks and cycles before any executor is enabled. Each unit records its legacy public behavior seam and comparison policy before implementation. Durable dependency preferences live in NOTES.md; verification/review/execution policy, ownership and rollback remain in the manifest.

Initialization does not preinstall speculative crates. Agent reconnaissance runs in a fresh context and gives dependency alignment a compact evidence report; manual mode lets a Rust-ecosystem expert provide the same evidence. Reconnaissance can be disabled to save tokens, but py2rs then warns that the user must understand or manually research crates.io, docs.rs and feature/dependency paths. Only after alignment are required crates added and locked.

See Architecture for the mode lifecycle and Usage for the operational sequence.

What The Rust Output Should Look Like

After using these skills to migrate Python to Rust, the first-stage code is not a line-by-line translation or an immediate style exercise. Every unit targets strict behavior parity at its declared legacy public seam, backed by complete tests. Deep framework internals remain outside scope only when they do not change that observable behavior.

The migrated Rust code should prove:

  • every unit matches original Python public behavior at its declared seam
  • model/artifact loading, tensor, codec and handoff cases are included whenever they cross that seam
  • edge cases, error paths, fixtures and regressions are covered by tests
  • each migration unit has review evidence instead of relying on code that merely looks correct

After the py-to-rs behavior migration is complete, give AI a separate goal:

Adopt Rust community standards and build complete documentation.

If you still have capacity after that, ask AI to optimize the code toward Rust community style and structure. That phase should happen only after behavior tests are stable, and every style pass should rerun behavior review and the full test suite.

If you only want to install the skills into Codex or Claude first, see docs/installation.md. It covers both discovery directories, Context7 setup, an "ask AI to install" prompt and macOS/Linux and Windows manual commands.

Foundation Skills

  • work-unit-slicing: minimum independently verifiable work units.
  • phase-dag-execution: phase DAGs, artifact edges, locks, capacity and stale evidence.
  • review-gate: independent review roles, batches, per-unit verdicts and reports.
  • crate-recon: Rust crate capability, feature and dependency-path evidence.
  • dependency-alignment: dependency reuse, backend, adapter or handwritten capability decisions.
  • env-bootstrap: seam and execution-environment proof before business logic.
  • teach: mission/resources/records progression.

Composition Skills

See docs/review-gates.md.

Where The Ideas Come From

py2rs combines:

  • teach-style progression: mission-grounded work, resources before memory, durable records, notes, small units and feedback loops.
  • rewrite discipline: behavior before architecture, reversible state, manifest-driven progress and independent review gates.
  • project-specific adaptation: each real project keeps its accepted seam instead of adopting a fixed py2rs directory layout.

The source skill is included at skills/foundations/teach. It comes from Matt Pocock's mattpocock/skills repository; see THIRD_PARTY.md.

Practice Skills

These are examples of project-specific skills created from the same architecture. They are not universal templates.

Docs

English:

Chinese:

License

MIT. See LICENSE.