Agent-Skills.md

Agent Skills: ln-831-oss-replacer

Replaces custom modules with OSS packages using atomic keep/discard testing. Use when migrating custom code to established libraries.

UncategorizedID: levnikolaevich/claude-code-skills/ln-831-oss-replacer

Repository

levnikolaevich/claude-code-skills
levnikolaevichLicense: MIT
29647

Install this agent skill to your local

pnpm dlx add-skill https://github.com/levnikolaevich/claude-code-skills/tree/HEAD/plugins/optimization-suite/skills/ln-831-oss-replacer

Skill Files

Browse the full folder contents for ln-831-oss-replacer.

Download Skill

Loading file tree…

plugins/optimization-suite/skills/ln-831-oss-replacer/SKILL.md

Skill Metadata

Name
ln-831-oss-replacer
Description
"Replaces custom modules with OSS packages using atomic keep/discard testing. Use when migrating custom code to established libraries."

Paths: File paths (references/, ../ln-*) are relative to this skill directory.

ln-831-oss-replacer

Type: L3 Worker Category: 8XX Optimization

Executes OSS replacement plans from ln-645-architecture-modernization-auditor. For each custom module with a viable OSS alternative: install package, rewrite imports, run verification, then keep or discard atomically.

Overview

| Aspect | Details | |--------|---------| | Input | Migration plan from audit output or a target module | | Output | Replaced modules plus a machine-readable modernization summary | | Companion | ln-645-architecture-modernization-auditor identifies candidates, ln-831 executes them |

Workflow

Phases: Pre-flight -> Load Plan -> Prioritize -> Replace Loop -> Report

Phase 0: Pre-flight Checks

| Check | Required | Action if Missing | |-------|----------|-------------------| | Migration plan or target module | Yes | Block replacement | | Test infrastructure | Yes | Block replacement | | Package manager available | Yes | Block replacement | | Workspace baseline safe | Yes | In managed runs coordinator already prepared it; in standalone runs protect rollback locally |

MANDATORY READ: Load references/ci_tool_detection.md for test detection. Tool policy: follow host AGENTS.md MCP preferences; load references/mcp_tool_preferences.md and references/mcp_integration_patterns.md only when host policy is absent or MCP behavior is unclear.

Use hex-line first for local code edits and reads when available, and use hex-graph first when cross-file reference checks materially improve replacement safety. If MCP is unavailable, unsupported, or not indexed, continue with built-in Read/Grep/Glob/Bash and state the fallback in the summary.

Runtime Coordination

Managed runs receive deterministic runId and exact summaryArtifactPath from ln-830. Standalone runs remain supported; if runtime arguments are omitted, generate a standalone run-scoped artifact before returning.

Phase 1: Load Migration Plan

From audit report, extract:

| Field | Description | |-------|-------------| | custom_module | Path to the custom implementation | | loc | Lines of code in the custom module | | oss_package | Recommended OSS replacement | | confidence | HIGH, MEDIUM, or LOW | | api_mapping | Custom function to OSS equivalent |

If no audit report exists, analyze the target module and search Context7 or Ref for viable OSS alternatives.

MANDATORY READ: Load references/research_tool_fallback.md

Phase 2: Prioritize Replacements

| Priority | Criteria | |----------|----------| | 1 | HIGH confidence and >200 LOC | | 2 | HIGH confidence and 100-200 LOC | | 3 | MEDIUM confidence and >200 LOC | | 4 | MEDIUM confidence and 100-200 LOC | | Skip | LOW confidence |

Phase 3: Replace Loop (Keep/Discard)

Per-module cycle:

FOR each replacement candidate:
  1. INSTALL: add the OSS package
  2. REWRITE: update imports and call sites using api_mapping
  3. VERIFY: run tests
     IF tests fail -> DISCARD and revert all changes for this candidate
  4. KEEP: only after verification passes
  5. DELETE: remove old custom module after keep
  6. LOG: record result for the final report

Stop conditions:

| Condition | Action | |-----------|--------| | All candidates processed | Stop and report | | 3 consecutive discards | Warn and stop for manual review | | Test infrastructure itself breaks | Stop and revert to last known good state | | No candidates above confidence threshold | Stop and report no viable replacements |

Atomic revert on discard:

| Step | Revert Action | |------|---------------| | Package installed | Uninstall it | | Files modified | Restore module files | | Lock file changed | Restore lock file |

Safety rules:

| Rule | Description | |------|-------------| | One module at a time | Never replace multiple modules simultaneously | | No API signature drift | Public interfaces must stay compatible | | Tests required | Skip modules with no coverage when risk is unclear | | Confidence gate | Skip LOW-confidence replacements |

Phase 4: Report Results

| Field | Description | |-------|-------------| | source | Audit report path or target module | | candidates_total | Total replacement candidates | | replacements_applied | Successfully replaced modules | | replacements_discarded | Failed replacements with reasons | | replacements_skipped | Skipped due to low confidence or missing tests | | loc_removed | Total lines of custom code removed | | packages_added | New OSS packages installed | | details[] | Per replacement summary | | artifact_path | Durable worker report path, if written |

Configuration

Options:
  audit_report: "docs/project/codebase_audit.md"
  target_module: ""
  min_confidence: "MEDIUM"
  run_tests: true
  require_test_coverage: true
  delete_old_module: true

Error Handling

| Error | Cause | Solution | |-------|-------|----------| | Package not found | OSS package name changed | Search current docs for the new package name | | API mismatch | Mapping differs from real library API | Query docs and retry only if fix is clear | | Circular dependency | New package conflicts with current architecture | Skip and report manual follow-up | | No test coverage | Too risky for automated replacement | Skip and report |

References

  • ../ln-645-architecture-modernization-auditor/SKILL.md
  • references/ci_tool_detection.md
  • references/research_tool_fallback.md
  • references/epistemic_protocol.md

Runtime Summary Artifact

MANDATORY READ: Load references/coordinator_summary_contract.md

Emit a modernization-worker summary envelope.

Managed mode:

  • ln-830 passes deterministic runId and exact summaryArtifactPath
  • write the summary to the provided summaryArtifactPath

Standalone mode:

  • omit runId and summaryArtifactPath
  • write .hex-skills/runtime-artifacts/runs/{run_id}/modernization-worker/ln-831--{identifier}.json

Monitor (2.1.98+): For install + test verification loops expected >30s, use Monitor. Fallback: Bash(run_in_background=true).

Definition of Done

  • [ ] Migration plan loaded or target module analyzed
  • [ ] Candidates prioritized by confidence and code-reduction value
  • [ ] Each replacement executed atomically with keep/discard verification
  • [ ] Discarded replacements fully reverted
  • [ ] Kept replacements remove old custom code only after verification passes
  • [ ] Report captures applied, discarded, skipped replacements, and LOC removed
  • [ ] modernization-worker summary artifact written to the managed or standalone path

Version: 1.0.0 Last Updated: 2026-03-08