Magento 2 Module Upgrade

Bring an existing module up to a newer Magento or PHP target. The change list is derived (from scans), not user-described.

Core Rules

• Target before scan. Always resolve the upgrade target in Phase 1; never scan without a concrete target.
• Auto-fix only known-safe Rector rules. Manual approval required for non-trivial rewrites.
• BC-breaks are documented, not silently fixed. A BC-break may break callers; surface it in UPGRADE.md so the consumer knows.
• Per-task commits. Each Rector rule run, each manual edit, each BC-break note is its own commit. Reverting one shouldn't lose others.
• Test before declare-done. A passing test suite is the gate to Phase 7.
• Output budget. Follow context/references/output-budget.md — targeted reads, summary-first test/lint output, long logs to files.

Workflow

Phase 0 — Context Resolution

Invoke context. Capture current Magento + PHP versions, framework constraint, runner, tools (rector, phpstan, semgrep).

Phase 1 — Target Resolution

Determine the upgrade target from the user request:

State the target explicitly. Ask for clarification if multiple targets fit.

Phase 2 — Scan

Run scanners in order; record what was available and what wasn't.

Emit a scan report: each finding categorized as:

• auto-fixable (Rector can do it)
• manual-fixable (needs human/LLM intervention)
• bc-break (caller must update; surfaces an API change)

Phase 3 — Plan (APPROVAL GATE)

Present the scan report grouped by category. Wait for "proceed."

The user can opt into --include-bc-breaks if they want the skill to attempt automated BC-break remediation; default is "report only."

Phase 4 — Apply

• Auto-fixable: run Rector with the relevant rule set. One commit per rule set applied.
• Manual-fixable: edit each file directly. One commit per logical change.
• BC-break: write a note in UPGRADE.md (template at templates/upgrade-md.md) and skip the code change.

Phase 5 — Test

1. Run unit tests; fix breaks introduced by changes.
2. If module has no tests: invoke test-generate --types=unit for the changed files before applying further changes.
3. Run integration tests if available; fix breaks.
4. If the module declares webapi.xml or schema.graphqls: run API tests.

Phase 6 — Review

Invoke review --diff against the pre-upgrade ref. Fix Critical/High findings.

Phase 7 — Report

Save to {output_root}/upgrades/{Vendor}_{Module}-{from}-to-{to}-{date}.md, where {output_root} is the --docs-root value when the caller passed one, else {ctx.docs_root} (see "Output Root" below):

• Scope (versions, modules, scanners run)
• Findings (auto-fixed, manually-fixed, BC-breaks)
• BC-break consumer notice (paste of UPGRADE.md)
• Test results
• Recommended next steps

Also emit the JSON + SARIF siblings. Assemble the findings array per the shared schema (context/references/findings-schema.md; category = deprecation / bc_break / magento_compat / php_compat, severity per context/references/severity.md), write it to a temp file, then run ${CLAUDE_SKILL_DIR}/scripts/emit-report.sh with FINDINGS_FILE, TARGET_MODULE, TARGET_PATH, OUTPUT_BASENAME=<Vendor>_<Module>-<from>-to-<to>-<date>, and DOCS_ROOT=<output_root>. It routes through the shared context hub emitter, so the JSON is schema-valid and the .sarif sibling feeds CI / GitHub Code Scanning like every other findings skill. (Previously an inline emitter wrote JSON only — no SARIF.)

Inputs

/upgrade --to-magento=2.4.7 --to-php=8.3 [--docs-root=<path>] <Vendor>_<Module>[,<Module>]

Flags:

• --to-magento=X.Y.Z
• --to-php=X.Y
• --scan-only — Phases 0-2 only; no edits.
• --auto-fix — Apply Rector without approval (Phase 3 skipped).
• --include-bc-breaks — Attempt automated BC-break remediation.
• --docs-root=<path> — output-root override; see "Output Root" below.

Outputs

{output_root}/upgrades/{Vendor}_{Module}-{from}-to-{to}-{date}.md
{output_root}/upgrades/{Vendor}_{Module}-{from}-to-{to}-{date}.json
{output_root}/upgrades/{Vendor}_{Module}-{from}-to-{to}-{date}.sarif
{ctx.magento_root}/app/code/{Vendor}/{Module}/UPGRADE.md   # Consumer notice (always present after upgrade)

{output_root} (.docs by default, {ctx.docs_root}) is anchored at the project root, never under {ctx.magento_root}, app/code, or a module dir. See the Artifact location rule in context/SKILL.md.

Output root (--docs-root)

This skill accepts --docs-root=<path> (see context/references/artifact-layout.md). The MD report is authored in-conversation and written under <path>/upgrades/; the JSON + SARIF are produced by scripts/emit-report.sh, which passes DOCS_ROOT=<path> to the shared context hub emitter so both land under <path>/upgrades/. When unset they default to {ctx.docs_root}/upgrades/. Orchestrators such as feature pass this to collect a run's artifacts under one folder.

Reference Files

• references/magento-version-matrix.md — known BC breaks by Magento version.
• references/php-version-matrix.md — known BC breaks by PHP version.
• references/deprecation-map.md — deprecated → replacement API mapping.
• references/rector-rule-sets.md — Rector sets by Magento version.
• references/bc-break-notification.md — how to write UPGRADE.md entries.
• references/scanner-tools.md — tool probe catalogue.
• ${CLAUDE_SKILL_DIR}/scripts/emit-report.sh — emits the findings JSON + SARIF via the shared context hub emitter (emit-findings.sh).
• context/references/severity.md — shared five-point severity scale for findings.
• context/references/findings-schema.md — JSON findings-document structure and the outputKind enum (upgrade for this skill).

Templates

• templates/upgrade-md.md — module-level UPGRADE.md
• templates/report.md — upgrade report

Edge Cases

Related Skills