From 45c8bbf4f1c1e3b3e23b1fd4979477bd93b22f9e Mon Sep 17 00:00:00 2001 From: Himamshu Soni Date: Tue, 25 Aug 2026 09:38:21 +0530 Subject: [PATCH 1/2] feat(skills): add migrate skill and plugin manifest --- .oxcode-plugin/marketplace.json | 7 + plugins/migrate/.oxcode-plugin/plugin.json | 13 ++ plugins/migrate/skills/migrate/SKILL.md | 198 +++++++++++++++++++++ 3 files changed, 218 insertions(+) create mode 100644 plugins/migrate/.oxcode-plugin/plugin.json create mode 100644 plugins/migrate/skills/migrate/SKILL.md diff --git a/.oxcode-plugin/marketplace.json b/.oxcode-plugin/marketplace.json index 5eda5d8..d590da6 100644 --- a/.oxcode-plugin/marketplace.json +++ b/.oxcode-plugin/marketplace.json @@ -47,6 +47,13 @@ "description": "Measure, profile, and optimise code with before-and-after numbers, without guessing or unverified claims.", "category": "development", "author": "Oxlo.ai" + }, + { + "name": "migrate", + "source": "./plugins/migrate", + "description": "Upgrade dependencies and frameworks where equivalence is proven against tests, with codebase-filtered breaking changes.", + "category": "development", + "author": "Oxlo.ai" } ] } diff --git a/plugins/migrate/.oxcode-plugin/plugin.json b/plugins/migrate/.oxcode-plugin/plugin.json new file mode 100644 index 0000000..94d933c --- /dev/null +++ b/plugins/migrate/.oxcode-plugin/plugin.json @@ -0,0 +1,13 @@ +{ + "name": "migrate", + "version": "1.0.0", + "description": "Upgrade dependencies and frameworks where equivalence is proven against tests, with codebase-filtered breaking changes.", + "author": { + "name": "Oxlo.ai" + }, + "license": "MIT", + "homepage": "https://github.com/Cyborg-Network/oxcode-skills", + "requires": { + "oxcode": ">=0.4.0" + } +} diff --git a/plugins/migrate/skills/migrate/SKILL.md b/plugins/migrate/skills/migrate/SKILL.md new file mode 100644 index 0000000..ad216cc --- /dev/null +++ b/plugins/migrate/skills/migrate/SKILL.md @@ -0,0 +1,198 @@ +--- +name: migrate +command: migrate +label: Migrate +hint: Upgrade dependencies and frameworks with proven equivalence +description: >- + Upgrade dependencies and frameworks where equivalence is proven against tests. + Use when updating versions, running codemods, or adapting breaking changes + without unverified claims. +category: development +order: 70 +icon: arrow-up-circle +capability: Coding +workspace: required +tools: full +--- + +You are performing a version, dependency, or framework migration. Your job is to +upgrade software safely by proving behavioural equivalence against an +executable test suite, applying targeted codemods, and stopping at +architectural decisions rather than guessing. + +Version and framework upgrades are where AI tooling is most confidently wrong: +it knows the public migration guide and does not know this codebase. It hallucinates +version numbers from memory, applies sweeping unneeded changes from generic +changelogs, and asserts that code is safe without running a test. A migration +built on a remembered version number or an unverified API claim is the most +expensive kind of wrong. + +## Verify versions and capabilities by running commands, never from memory + +Model memory of package versions, release dates, and API availability is frozen, +incomplete, or hallucinated. Never trust remembered version numbers. + +1. **Verify target version existence**: Always run a package manager or + registry command to confirm the target version exists, is published, and is + stable before editing dependency files: + - Node / JS: `npm view versions --json` or `pnpm info versions` + - Python: `pip index versions ` or `pip install ==` + - Rust: `cargo search ` or `cargo outdated` + - Go: `go list -m -versions ` + - Ruby: `gem list -r ` +2. **Verify API shapes empirically**: Never assume a method, parameter, or + configuration key exists in the target version. Inspect the installed package + declarations, run the compiler or type checker (`tsc`, `mypy`, `cargo check`, + `go build`), or execute a one-line evaluation in the terminal. + +If network access is unavailable or a remote registry cannot be queried, state +the boundary explicitly: +`"Cannot query remote registry for versions because network is unavailable. Proceeding with locally available target ."` + +## Filter breaking changes to THIS codebase, not the full changelog + +Upstream migration guides and release notes list dozens of breaking changes, the +vast majority of which do not apply to this repository. Dumping an upstream +changelog is not a migration plan; it is noise. + +- **Scan the codebase**: Search the codebase (using grep or AST search) for each + breaking symbol, deprecated pattern, removed configuration key, or signature + change mentioned upstream. +- **Cite file and line**: The output of a migration audit is a short, filtered + list containing only the breaking changes that actually bite THIS code, with + the exact `file:line` reference where each one hits. +- **Omit unused changes**: If a breaking change in the upstream guide is not + present in this repository, explicitly exclude it. Do not pad the report with + irrelevant upstream notes. + +## Prove equivalence with paired before-and-after test runs + +Equivalence must be proven by executing the test suite against both versions, +never claimed or asserted. "This change is safe" is a banned assertion without +test proof. + +1. **Establish the green baseline before touching code**: + - Run the existing test suite and type checker against the current codebase + before modifying any file. + - Record the exact test command executed, total tests run, and passing status. + - If any test fails before starting, **STOP**. Never start a migration on a + failing baseline. Report the failure and refuse to proceed until the baseline + is green or pre-existing defects are resolved. +2. **Execute paired after-tests**: + - Run the exact same test command under the updated version. + - Prove that all assertions pass and observable behaviour is preserved. + - Report the before-and-after test counts and status side by side. +3. **Handle missing test coverage**: + - If a breaking API change affects code with no existing test coverage, write + a minimal characterization test proving current behaviour *before* changing + the dependency or code. + +## Use ecosystem migration tools and codemods first + +Where official codemods, migration scripts, or automated upgrade tools exist, +use them rather than hand-editing what a dedicated tool does deterministically. + +- **Check for official tooling**: + - React / Next.js: `npx @next/codemod `, `npx react-codemod ` + - TypeScript / JS: `npx ts-migrate`, framework upgrade CLIs + - Python / Django: `django-upgrade`, `pyupgrade`, `libcst` codemods + - Rust: `cargo fix --edition`, `cargo fix --allow-no-vcs` + - Go: `go fix ./...` +- **Inspect tool output**: State the exact command executed, inspect the diff + produced by the codemod, and run the test suite immediately after. +- Never hand-edit hundreds of lines of mechanical AST transformations when the + framework authors provide a tested codemod. + +## Separate mechanical changes from judgement calls, and stop at decisions + +Upgrades contain two distinct classes of changes: + +1. **Mechanical changes**: Deterministic 1-to-1 replacements with identical + semantics (e.g. import path renames, deprecated argument renames, codemod + outputs, straightforward syntax updates). + - Apply these changes in small, atomic steps. + - Re-run tests between steps to verify each transformation. +2. **Judgement calls / Semantic decisions**: Deprecations or architectural + shifts with multiple valid solutions: + - A removed library requiring a choice between competing replacement libraries. + - A change from synchronous callbacks to async/await, streams, or promises + where error propagation strategy must be decided. + - Changed security defaults (e.g. strict CORS, disabled automatic deserialization, + new authentication requirements). + - Altered lifecycle hooks requiring business logic redesign. + +**Hard stopping rule**: Never make a judgement call or architectural choice on +the user's behalf. When a migration hits a decision point, stop. Present the +alternatives, the trade-offs, and the affected `file:line` locations, and await +instruction before making modifications. + +## The migration sequence + +1. **Baseline**: Run test suite and type check on current code; record exact + command and passing count. +2. **Version verification**: Run registry/package command to verify target + version exists and can be installed. +3. **Impact audit**: Grep codebase for breaking symbols and list only those that + hit this codebase, with `file:line` citations. +4. **Automated codemods**: Run ecosystem migration CLI or codemod if available; + verify diff and run tests. +5. **Mechanical edits**: Apply 1-to-1 deterministic changes; run tests after + each edit. +6. **Flag judgement calls**: Document any decision points with options and trade-offs; + stop and await user decision. +7. **Equivalence proof**: Run the full test suite and type checker; report paired + before-and-after proof. + +## Worked example + +Consider upgrading `pydantic` from v1 to v2: + +> **1. Baseline Measurement:** +> Command: `pytest tests/ -q` +> Result: 38 passed in 1.42s (pre-migration baseline green). +> +> **2. Target Version Verification:** +> Command: `pip index versions pydantic` +> Result: Verified `pydantic==2.7.4` available on PyPI. +> +> **3. Codebase Impact Audit (Filtered to this repo):** +> Upstream changelog lists 40+ breaking changes. Only 2 affect this codebase: +> - `@validator` deprecated in favor of `@field_validator`: +> `src/models/user.py:14` and `src/models/order.py:22`. +> - `.dict()` deprecated in favor of `.model_dump()`: +> `src/api/routes.py:88` and `src/services/billing.py:45`. +> *(Unused upstream changes such as ORM mode and root validators do not exist in +> this repository and are omitted.)* +> +> **4. Automated Codemod Execution:** +> Command: `bump-pydantic src/` +> Result: Applied mechanical updates across 4 files; diff inspected. +> +> **5. Judgement Call Stopped At:** +> `src/models/custom_types.py:31` uses `__get_validators__`, which has no 1-to-1 +> replacement in v2. Two valid paths exist: +> - *Option A*: Implement `__get_pydantic_core_schema__` for core schema validation. +> - *Option B*: Wrap with `Annotated[T, PlainValidator(...)]`. +> Stopped to let user choose the serialization architecture. +> +> **6. Paired Equivalence Proof:** +> Command: `pytest tests/ -q` +> Result: 38 passed in 1.18s (equivalence proven across all 38 test cases). + +## Output + +Structure your migration report as follows: + +1. **Baseline Test Evidence**: Starting test command, passing test count, and + type check status. +2. **Target Version Verification**: Exact command executed and target version + verified. +3. **Applicable Breaking Changes**: Filtered list of breaking changes affecting + THIS codebase, with `file:line` references and brief description. +4. **Tooling & Codemods**: Ecosystem migration commands run and files modified. +5. **Mechanical Changes Applied**: Summary of 1-to-1 edits and intermediate test + checks. +6. **Judgement Calls / Decisions Required** (if any): Unresolved architectural + choices, affected files, options with trade-offs, and stopping status. +7. **Equivalence & Verification Evidence**: Paired test suite command, before + count vs. after count, and type checker results. From 9e66f3628af5e28a669e15d5ea80eec9d7e14e4f Mon Sep 17 00:00:00 2001 From: Himamshu Soni Date: Wed, 26 Aug 2026 15:49:39 +0530 Subject: [PATCH 2/2] fix(skills): address reviewer feedback for migrate baseline and codemod disciplines --- plugins/migrate/skills/migrate/SKILL.md | 40 ++++++++++++++----------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/plugins/migrate/skills/migrate/SKILL.md b/plugins/migrate/skills/migrate/SKILL.md index ad216cc..6c2b5f3 100644 --- a/plugins/migrate/skills/migrate/SKILL.md +++ b/plugins/migrate/skills/migrate/SKILL.md @@ -71,16 +71,19 @@ Equivalence must be proven by executing the test suite against both versions, never claimed or asserted. "This change is safe" is a banned assertion without test proof. -1. **Establish the green baseline before touching code**: - - Run the existing test suite and type checker against the current codebase - before modifying any file. - - Record the exact test command executed, total tests run, and passing status. - - If any test fails before starting, **STOP**. Never start a migration on a - failing baseline. Report the failure and refuse to proceed until the baseline - is green or pre-existing defects are resolved. +1. **Establish the baseline before touching code**: + - Record the baseline as a set, not a verdict. Run the suite and the type + checker before modifying any file, and record the exact command, the total, + and the NAMES of any tests already failing. A repository with pre-existing + failures is normal and is not a reason to refuse the migration. Equivalence + afterwards means the same named tests fail and no new ones do. + - **STOP** only when the baseline cannot be run at all, or when a test that + already fails covers the code being migrated. Say which test and why it + blocks, rather than refusing on a count. 2. **Execute paired after-tests**: - Run the exact same test command under the updated version. - - Prove that all assertions pass and observable behaviour is preserved. + - Prove that observable behaviour is preserved: the same named tests fail and + no new ones do. - Report the before-and-after test counts and status side by side. 3. **Handle missing test coverage**: - If a breaking API change affects code with no existing test coverage, write @@ -98,8 +101,9 @@ use them rather than hand-editing what a dedicated tool does deterministically. - Python / Django: `django-upgrade`, `pyupgrade`, `libcst` codemods - Rust: `cargo fix --edition`, `cargo fix --allow-no-vcs` - Go: `go fix ./...` -- **Inspect tool output**: State the exact command executed, inspect the diff - produced by the codemod, and run the test suite immediately after. +- **Inspect tool output**: State the exact command executed, name the files the + codemod changed and the transformation applied to each, and run the test suite + immediately after. - Never hand-edit hundreds of lines of mechanical AST transformations when the framework authors provide a tested codemod. @@ -129,19 +133,19 @@ instruction before making modifications. ## The migration sequence 1. **Baseline**: Run test suite and type check on current code; record exact - command and passing count. + command, total count, and the names of any failing tests. 2. **Version verification**: Run registry/package command to verify target version exists and can be installed. 3. **Impact audit**: Grep codebase for breaking symbols and list only those that hit this codebase, with `file:line` citations. 4. **Automated codemods**: Run ecosystem migration CLI or codemod if available; - verify diff and run tests. + state files changed and transformations applied, then run tests. 5. **Mechanical edits**: Apply 1-to-1 deterministic changes; run tests after each edit. 6. **Flag judgement calls**: Document any decision points with options and trade-offs; stop and await user decision. 7. **Equivalence proof**: Run the full test suite and type checker; report paired - before-and-after proof. + before-and-after proof showing zero new regressions. ## Worked example @@ -183,16 +187,18 @@ Consider upgrading `pydantic` from v1 to v2: Structure your migration report as follows: -1. **Baseline Test Evidence**: Starting test command, passing test count, and - type check status. +1. **Baseline Test Evidence**: Starting test command, total test count, + names of any pre-existing failing tests, and type check status. 2. **Target Version Verification**: Exact command executed and target version verified. 3. **Applicable Breaking Changes**: Filtered list of breaking changes affecting THIS codebase, with `file:line` references and brief description. -4. **Tooling & Codemods**: Ecosystem migration commands run and files modified. +4. **Tooling & Codemods**: Ecosystem migration commands run, files modified, and + transformations applied. 5. **Mechanical Changes Applied**: Summary of 1-to-1 edits and intermediate test checks. 6. **Judgement Calls / Decisions Required** (if any): Unresolved architectural choices, affected files, options with trade-offs, and stopping status. 7. **Equivalence & Verification Evidence**: Paired test suite command, before - count vs. after count, and type checker results. + count vs. after count, regression status (confirming no new failing tests), + and type checker results.