statamic-upgrade-major

Type	Skill
Plugin	awl-web · v0.0.6
Invoke	/awl-web:statamic-upgrade-major
Tools	Bash(composer:), Bash(php:)
Source	plugins/awl-web/skills/statamic-upgrade-major/SKILL.md

When Claude uses it

Upgrades a Statamic CMS site to the next major version following the official upgrade guide — bumps statamic/cms and Laravel constraints, migrates addons and config, runs tests. Use when asked to “upgrade statamic”, “statamic 5”, “bump statamic major”, or when composer.json pins an outdated statamic/cms major. Not for plain Laravel apps (use laravel-upgrade-major).

Trigger phrases: upgrade statamic · statamic 5 · bump statamic major

Definition

Upgrades a Statamic CMS application to the next major version following official upgrade guides.

Instructions

Step 1: Detect Current Version

1. Read composer.json for Statamic version:

   cat composer.json | grep -A1 '"statamic/cms"'

2. Extract major version (e.g., ^4.0 → 4, ^5.48 → 5)

3. Calculate target version: current + 1

   • Statamic 4 → 5
   • Statamic 5 → 6
   • NEVER skip versions

Step 2: Fetch Upgrade Guide

WebFetch the official upgrade documentation:

https://statamic.dev/upgrade-guide/{CURRENT}-to-{TARGET}

Example for upgrading from Statamic 4 to 5:

https://statamic.dev/upgrade-guide/4-to-5

Special version formats: Versions before 4 did not follow semver and incremented from 3.1 → 3.2 with breaking changes. Some guides use format like 3-4-to-4-0. Try alternate patterns if primary URL fails.

IMPORTANT: Read the ENTIRE guide. Do not skim or assume changes don’t apply.

Step 3: Check Laravel Compatibility

CRITICAL: This command does NOT upgrade Laravel.

1. Read current Laravel version from composer.json
2. Check upgrade guide for minimum Laravel version required by Statamic {TARGET}
3. Compare versions

If Laravel version is incompatible: STOP.

Laravel {CURRENT_LARAVEL} is installed, but Statamic {TARGET} requires Laravel {REQUIRED_LARAVEL}+.

Run `/laravel-upgrade-major` first to upgrade Laravel, then re-run `/statamic-upgrade-major`.

If Laravel version is compatible: Continue to Step 4.

Step 4: Pre-Upgrade Gate (Tests Must Pass)

Tests must be green before proceeding. Run tests in quiet mode (exit code only, output omitted to save context):

php artisan test -q

Or if using PHPUnit directly:

./vendor/bin/phpunit -q

If tests fail: STOP. Report failures to user and do not proceed with upgrade.

• Upgrading with failing tests makes it impossible to verify upgrade success
• Ask user to fix tests first, then re-run /statamic-upgrade-major

If tests pass: Continue to Step 5.

Step 5: Identify Statamic Addons

Scan composer.json for Statamic-related packages:

1. Official addons - statamic/* namespace:

   • statamic/seo-pro
   • statamic/eloquent-driver
   • statamic/collaboration
   • etc.

2. Third-party addons - Package name contains “statamic”:

   • appswithlove/statamic-charfield
   • doublethreedigital/runway
   • etc.

List all identified addons for updating in Step 6.

Step 6: Update Dependencies

Use composer require with all packages in a single command. Omit version for addons to let composer install latest compatible version.

composer require statamic/cms:^{TARGET}.0 statamic/seo-pro vendor/statamic-addon --update-with-dependencies

Building the Command

1. Start with statamic/cms:^{TARGET}.0
2. Add all addons identified in Step 4 (no version suffix)
3. Include --update-with-dependencies flag

Example (upgrading to Statamic 5 with addons):

composer require statamic/cms:^5.0 statamic/seo-pro appswithlove/statamic-charfield --update-with-dependencies

If conflicts occur:

• Read the composer error output carefully
• If third-party addon blocker: STOP and report to user with exact error message
• Do NOT search the web to check if addons support Statamic {TARGET}
• Do NOT try to force or work around the conflict

Step 7: Apply Code Changes

CRITICAL: Check EVERY item in the upgrade guide against the project. No assumptions.

For EACH breaking change listed in the guide:

1. Search the codebase for affected code (use Grep/Glob)
2. Verify whether the project uses the affected feature
3. Apply fix if affected, or confirm not affected if clean

Do NOT assume a breaking change doesn’t apply without searching the codebase first.

Common areas to check:

• Config Files - Compare with new defaults, update/publish as needed
• Blueprints/Fieldtypes - Search for deprecated field types
• Tags/Modifiers - Check for renamed or removed tags
• Antlers Templates - Search for syntax changes
• Control Panel Customizations - Check for CP API changes
• Middleware - Apply any middleware changes
• Service Providers - Update if needed

Use Edit tool for each change. Explain what’s changing and why.

Step 8: Post-Upgrade Verification

Clear all caches:

php artisan optimize:clear

Clear Statamic caches:

php artisan statamic:stache:clear
php artisan statamic:static:clear

Run tests (quiet mode, exit code only):

php artisan test -q

Optionally run linting:

./vendor/bin/pint --test -q

Optionally run static analysis:

./vendor/bin/phpstan analyse -q

Step 9: Report Results

Output summary:

## Statamic Upgrade Complete: {CURRENT} → {TARGET}

### Files Changed
- composer.json
- [list other changed files]

### Packages Updated
- statamic/cms: ^{CURRENT}.0 → ^{TARGET}.0
- [other packages]

### Addons Updated
- [addon]: [old version] → [new version]

### Blockers Encountered
- [package]: [reason]

### Test Results
- Passed: X
- Failed: X
- [failure details if any]

### Manual Steps Remaining
- [if any]

Constraints

• NEVER skip major versions - Always current + 1
• NEVER upgrade Laravel - Abort if incompatible, user must run /laravel-upgrade-major first
• NEVER force-update addons that block - Report as blockers
• NEVER assume a breaking change doesn’t apply - Search the codebase first
• ALWAYS check EVERY item in the upgrade guide against the project
• ALWAYS run tests before and after
• ALWAYS explain changes - User should understand what changed
• Backup first - Ensure git status is clean before starting
• NO WEB SEARCHES for addon compatibility - Do NOT search the web to check if addons support the target Statamic version. Let composer determine compatibility:
  • Run composer require and let it fail if incompatible
  • Read error output to identify blocking packages
  • Report blockers to user with the exact composer error

Example

User: /statamic-upgrade-major

1. Read composer.json → Statamic 4.48
2. Target: Statamic 5
3. WebFetch statamic.dev/upgrade-guide/4-to-5
4. Check Laravel version compatible with Statamic 5 requirements
5. Run pre-upgrade tests
6. Identify addons: statamic/seo-pro, appswithlove/statamic-charfield
7. Run composer require statamic/cms:^5.0 statamic/seo-pro appswithlove/statamic-charfield --update-with-dependencies
8. Apply breaking changes from guide
9. Clear caches, run tests, report results