agentleFS
YomudoglyYomudogly/oh-my-agy/skills/modernize/SKILL.md

modernize

Skill4 starsChanged todayMITView on GitHub

[oh-my-agy] Phased codebase, dependency, framework, and runtime modernization workflow using behavior-lock baselines, license/coverage pre-flight checks, codemod waves, Expand-Migrate-Contract seams, and rollback checkpoints. Use for $modernize or when upgrading packages, frameworks, language versions, SDKs, or legacy modules end-to-end. Flags: --plan, --dry-run, --wave.

  • Reads credentials

14 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use takeover, unslop and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • assisjpSkill

    takeover

    Take over an existing branch, pull request, worktree, or agent handoff while preserving the original goal, contributor credit, and concurrent work. Use when the user asks to take over, finish, rescue, or continue someone else's implementation. Do not use to replace a clear request to start new work.

    Also in 4 projects that use this

  • photon-groveSkill

    unslop

    Detects and rewrites generic, overly polished, or AI-sounding prose while preserving meaning. Use when the user asks to "unslop", humanize, de-AI, tighten, or review whether writing sounds generated.

    Also in 3 projects that use this

  • BlockSkill

    frontend-design

    Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 3 are distinctive, and 8 are very specific to this project.

  • 0

    Common

    Most of the 14 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 8

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Do NOT invent an upgrade plan blindly: run pre-flight audits (dep-license-diff, coverage-map) and check upstream migration guides …

    line 21
  2. Distinctive:

    Respect host parity: avoid Antigravity-only scripts or host-locked assumptions when modernizing shared tooling.

    line 23
  3. Very specific:

    Run read-only diagnostics from the plugin root (or -C <target-repo>) before installing or editing dependencies:

    line 27
  4. Very specific:

    Supply-chain & license check: run sh <plugin>/hooks/run.sh dep-license-diff <repo> --json (or invoke supply-chain-auditor) to surface …

    line 29
  5. Very specific:

    Test coverage & risk ranking: run sh <plugin>/hooks/run.sh coverage-map <repo> --json to locate high-LOC/high-export modules lacking test …

    line 30
  6. Very specific:

    If --plan is set, stop after emitting the wave plan in .omagy/plans/modernize-{slug}.md and confirm scope with the user.

    line 34
  7. Very specific:

    Wave 0 — Behavior Lock Baseline: add or harden characterization tests via test-engineer covering critical inputs, error paths, …

    line 40
  8. Very specific:

    Migrate: run targeted codemods or incremental module ports (grep every caller first so shared abstractions update coherently), verifying …

    line 44
  9. Distinctive:

    Contract: remove temporary adapters and deprecated shims ONLY once 100% of callers pass cleanly under the target version.

    line 45
  10. Very specific:

    Wave 3 — Docs, Environment & Runtime Parity: run sh <plugin>/hooks/run.sh docs-drift <repo> --json and update README.md, setup guides, …

    line 46
  11. Distinctive:

    Every wave requires fresh evidence before moving to the next wave:

    line 50

“Common” is measured: kept by at least 6 in 10 of the 14 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Modernize

Execute controlled, reversible upgrades across dependencies, runtimes, frameworks, and legacy modules without breaking production behavior. Unlike $ralplan --migrate (which stops at planning a migration PRD), $modernize runs pre-flight dependency/coverage audits, locks existing behavior with regression tests, applies incremental codemod or adapter waves, and verifies every checkpoint before advancing.

Usage

$modernize "upgrade Node runtime, dependencies, or framework across target modules"
$modernize --plan "upgrade major ORM and router without writing code yet"
$modernize --wave 1 "bump core packages and lock characterization tests"

Boundaries

  • Load references/modernization-safety-ladder.md before designing compatibility shims, dual-write seams, or multi-wave rollbacks.
  • Do NOT invent an upgrade plan blindly: run pre-flight audits (dep-license-diff, coverage-map) and check upstream migration guides ($deep-research --quick via researcher) first.
  • Keep waves atomic and reversible: complete characterization tests before editing syntax, API signatures, or lockfiles. Never squash an entire multi-major upgrade into one unverified rewrite.
  • Respect host parity: avoid Antigravity-only scripts or host-locked assumptions when modernizing shared tooling.

Pre-Flight Audit & Dependency Triage

Run read-only diagnostics from the plugin root (or -C <target-repo>) before installing or editing dependencies:

  1. Supply-chain & license check: run sh <plugin>/hooks/run.sh dep-license-diff <repo> --json (or invoke supply-chain-auditor) to surface unpinned (*, latest), missing lockfiles, or strong copyleft (AGPL, standalone/AND GPL/SSPL) transitive additions.
  2. Test coverage & risk ranking: run sh <plugin>/hooks/run.sh coverage-map <repo> --json to locate high-LOC/high-export modules lacking test coverage and flag zero-assertion test files before touching them.
  3. Deprecation & breaking-change research: invoke researcher (or explore for internal callers via grep) to fetch official changelogs, minimum runtime versions, and removed APIs for each target package or SDK.
  4. Inspect package.json, pyproject.toml, Cargo.toml, go.mod, lockfiles, and .github/workflows to align CI runtime matrices with the target version.

If --plan is set, stop after emitting the wave plan in .omagy/plans/modernize-{slug}.md and confirm scope with the user.

Step-by-Step Wave Execution

Execute upgrades in strict sequence via executor (or directly in small bounded repos), verifying after every wave:

  1. Wave 0 — Behavior Lock Baseline: add or harden characterization tests via test-engineer covering critical inputs, error paths, serialization formats, and public contracts of every un-tested target module reported by coverage-map. Establish a green baseline before changing dependency versions or code.
  2. Wave 1 — Safe Minor/Patch & Tooling Alignment: apply non-breaking dependency bumps, type definitions, linter/compiler configs, and CI version-matrix updates first. Verify lockfile determinism (dep-license-diff) and baseline suite pass.
  3. Wave 2 — Expand-Migrate-Contract Seam (Breaking Major / API Upgrades):
    • Expand: introduce a compatibility adapter, dual-read/dual-write wrapper, or side-by-side schema column without removing legacy consumers.
    • Migrate: run targeted codemods or incremental module ports (grep every caller first so shared abstractions update coherently), verifying unit and integration checks per batch.
    • Contract: remove temporary adapters and deprecated shims ONLY once 100% of callers pass cleanly under the target version.
  4. Wave 3 — Docs, Environment & Runtime Parity: run sh <plugin>/hooks/run.sh docs-drift <repo> --json and update README.md, setup guides, .env.example keys (never inspect .env secrets), and CI workflows (devops-engineer / doc-steward).

Verification & Rollback Gates

Every wave requires fresh evidence before moving to the next wave:

  • Targeted unit/integration suite, typecheck, lint, and build pass with exit code 0.
  • sh <plugin>/hooks/run.sh dep-license-diff <repo> --json confirms zero new copyleft/unpinned regressions.
  • sh <plugin>/hooks/run.sh floor-guard <repo> --json reports 0 suppressed checkers, lost assertions, placeholder code, or hardcoded secrets.
  • Record each wave's before/after baseline, changed manifests, rollback commit/patch strategy, and residual warnings (e.g. deferred major bumps) before claiming completion. For high-risk runtime shifts, invoke runtime-qa or verifier for independent verification.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.