Apply approved plugin changes to a PaperMC server — prepare staging, download plugins, research configs, boot-verify, and cut over to production with rollback safety.
How this skill is triggered — by the user, by Claude, or both
Slash command
/minecraft-papermc-server:executorThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents
REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents REQUIRED SUB-SKILL: superpowers:systematic-debugging REQUIRED SUB-SKILL: compat-check
Apply all approved changes from the decision doc. Prepares a staging server, verifies everything boots cleanly, then cuts over to production with player warning and rollback safety.
This is a FOREGROUND skill — the staging boot and cutover steps require user interaction.
All passed from version-refresh or provided directly. Ask for any not yet provided:
minecraft. Used for backup, stop, apply, start./home/minecraft/serverfiles/home/minecraft/mcserverminecraft-staging. Used for all staging operations./opt/minecraft/stagingcd {staging-files-path} && {staging-java-path} -Xms512M -Xmx1536M -jar paper.jar nogui/usr/bin/java1.21.4Read the decision doc at the provided path. Collect all approved changes across all sections:
Paper decisions (from ## Paper decisions):
Meta decisions (from ## Meta decisions):
ADD — new plugins to installREPLACE — plugins to swap (install new, remove old)REMOVE / REDUNDANT — plugins to deleteVersion decisions (from ## Version decisions):
UPDATE — plugins to upgrade in placeMAJOR UPDATE — same as UPDATE, note as potentially breakingOnly collect rows with approved in the Decision column. Rows with skipped or cancelled are ignored.
Summarise what you found before proceeding:
Found N approved changes: M adds, P updates, Q removes, R replaces. Paper upgrade: yes/no.
ssh <staging-alias> "mkdir -p {staging-files-path}/plugins {staging-files-path}/logs"
Pull plugins and essential configs from production to staging:
# JAR files only — use --delete to remove stale JARs
ssh <prod-alias> "rsync -avz --delete {server-files-path}/plugins/*.jar <staging-alias>:{staging-files-path}/plugins/"
# Essential configs — do NOT use --delete
ssh <prod-alias> "rsync -avz {server-files-path}/server.properties <staging-alias>:{staging-files-path}/"
ssh <prod-alias> "rsync -avz {server-files-path}/bukkit.yml <staging-alias>:{staging-files-path}/"
ssh <prod-alias> "rsync -avz {server-files-path}/spigot.yml <staging-alias>:{staging-files-path}/"
ssh <prod-alias> "rsync -avz {server-files-path}/config/paper-world-defaults.yml <staging-alias>:{staging-files-path}/config/"
Do NOT sync world data. Staging only needs plugins and configs. World data is large and unnecessary for boot verification.
ssh <prod-alias> "rsync -avz {server-files-path}/paper.jar <staging-alias>:{staging-files-path}/paper.jar"
If Paper version is being upgraded: download the target Paper JAR from the PaperMC API and place it at {staging-files-path}/paper.jar on staging. The current production paper.jar is NOT copied in this case.
# PaperMC API download:
# GET https://api.papermc.io/v2/projects/paper/versions/{mc-version}/builds
# Find latest stable build number, then:
# GET https://api.papermc.io/v2/projects/paper/versions/{mc-version}/builds/{build}/downloads/paper-{mc-version}-{build}.jar
ssh <staging-alias> "curl -L -o '{staging-files-path}/paper.jar' '{download-url}'"
REQUIRED SUB-SKILL: superpowers:dispatching-parallel-agents — use it to dispatch and manage all download agents.
For every ADD, REPLACE, and UPDATE in the approved decisions, dispatch one download agent with run_in_background: true.
Read ./download-agent-prompt.md (in this skill's directory) for the full agent spec. Pass each agent:
ADD, REPLACE, or UPDATE){staging-files-path}/plugins)REPLACE and UPDATE only)Wait for all download agents to complete before proceeding.
If any download agent returns FAILED: report the failure to the user and stop. Ask how to proceed before continuing.
These two happen in parallel.
For each REMOVE or REDUNDANT in approved decisions, delete the JAR from staging:
ssh <staging-alias> "rm -f '{staging-files-path}/plugins/{jar-filename}'"
If the JAR is not found on staging, note it and continue — it may have already been absent.
For each ADD or REPLACE in approved decisions, dispatch one config research agent with run_in_background: true.
Read ../meta-refresh/config-research-agent.md (resolve this relative path against this skill's base directory before dispatching) for the agent spec.
Pass each agent: plugin name, target MC version, staging alias, staging files path.
Wait for all config research agents to complete before Step 5.
Read ./staging-verification-agent.md (in this skill's directory). Dispatch the staging verification agent (run_in_background: false — wait for result).
Pass:
KEEP plugins (infer from production JAR list minus removals) + all ADD + REPLACE target names + all UPDATE target namesReport the full verification output to the user. Invoke superpowers:systematic-debugging to diagnose the cause. Do NOT proceed to cutover. Ask:
- Retry — fix the issue and re-run verification
- Abandon — abort, no production changes
Present the warnings to the user with the full verification output. Ask:
Boot verification passed with warnings (listed above).
- Proceed — continue to cutover despite warnings
- Abandon — abort, no production changes
Continue to Step 6.
Present options to the user:
Staging verified. Ready to cut over to production.
- Apply now — check players, backup, stop production, apply changes, start
- Push to update folder — upload new JARs to
plugins/update/for next restart (plugins-only changes)- Abandon — discard staging, no production changes
Read ./cutover-agent-prompt.md (in this skill's directory). Execute the full cutover procedure as described there.
Pass:
If cutover returns CUTOVER: ROLLBACK: invoke superpowers:systematic-debugging with the rollback reason. Report to the user that production was restored from backup and must be investigated before retrying.
Only available when the approved changes are plugin-only (no Paper JAR upgrade, no REMOVE actions). If the changes include a Paper upgrade or plugin removals, inform the user that "Apply now" is required and skip this option.
Important: The plugins/update/ folder only works for updating existing plugins — it matches JARs by plugin name (from plugin.yml), not by filename. This means:
BlueMap-5.16-paper.jar will replace BlueMap-5.15-paper.jar)Procedure:
Create the update directory on production:
ssh <prod-alias> "mkdir -p {server-files-path}/plugins/update"
Upload UPDATE and REPLACE JARs to the update folder:
rsync -avz -e ssh {staging-files-path}/plugins/<update-jar-1> {staging-files-path}/plugins/<update-jar-2> ... <prod-alias>:{server-files-path}/plugins/update/
Upload ADD JARs directly to plugins/ (they won't load until restart, but they must be in the main folder):
rsync -avz -e ssh {staging-files-path}/plugins/<new-jar-1> ... <prod-alias>:{server-files-path}/plugins/
Report what was pushed and note: "Changes will take effect on next server restart."
Discard staging. No production changes. Ask:
- Delete decision doc — keep tidy
- Keep decision doc — save for a future run
Read ./changelog-digest-format.md (in this skill's directory). Compile the accumulated changelog from all phases using the format specified.
Append ## Changelog digest to the decision doc.
Append ## Execution summary to the decision doc with:
## Execution summary
- **Staging verification:** PASS | WARN | FAIL
- **Cutover result:** SUCCESS | ROLLBACK | DEFERRED (pushed to update folder) | ABANDONED
- **Changes applied:**
- Added: <list>
- Updated: <list>
- Removed: <list>
- Replaced: <list>
- Paper: <old version> → <new version> | no change
- **Warnings:** <list any staging warnings, or "none">
Invoke superpowers:systematic-debugging on any unexpected failure — SSH errors, rsync failures, API errors during Paper JAR download, config research agent failures, or cutover procedure errors not covered by known patterns.
If cutover fails: the rollback procedure in ./cutover-agent-prompt.md is the recovery path. Do not attempt a second cutover without the user explicitly asking.
world/, world_nether/, world_the_end/, or any other world directories to staging.--delete on the plugins/ JAR directory. Never use --delete when syncing plugin config directories — it would wipe user data (permissions, settings, world configs).npx claudepluginhub disqt/minecraft-claude-marketplace --plugin minecraft-papermc-serverGuides Minecraft server plugin development using Bukkit, Spigot, and Paper APIs, covering events, commands, NMS internals, performance optimization, and integrations with databases and Docker.
Outlines production deployment principles: platform selection trees, pre-deployment checklists, 5-phase workflows, verification steps, and rollback strategies for safe releases.
Discovers MCP servers from Claude Code configs, detects dependencies, updates packages using best practices. Run after fresh installs, connection errors, or periodically.