recipe-maintainer/.claude/commands/recipe-upgrade-plan.md

description, argument-hint, allowed-tools

description	argument-hint	allowed-tools
Create a detailed upgrade plan for a recipe	<recipe-name>	Bash Read Write Glob Grep WebFetch WebSearch

Recipe Upgrade Plan

Research available upgrades for a Co-op Cloud recipe and create a detailed plan file for review before applying.

The recipe name is: $ARGUMENTS

Read and follow the instructions in .claude/commands/includes/logging.md. Read and follow the instructions in .claude/commands/includes/guidelines.md.

Steps

1. Get the domain and server for this recipe:

   python3 scripts/get_test_instance.py --recipe $ARGUMENTS
   

   This outputs DOMAIN and SERVER for the active instance.

   • If the recipe has no recipe-info/$ARGUMENTS/recipe.toml, tell the user to run /recipe-init $ARGUMENTS first and stop.

2. Fetch the recipe AND pull latest upstream main — first check for uncommitted local changes:

   git -C ~/.abra/recipes/$ARGUMENTS status --short
   git -C ~/.abra/recipes/$ARGUMENTS diff
   git -C ~/.abra/recipes/$ARGUMENTS diff --cached
   git -C ~/.abra/recipes/$ARGUMENTS ls-files --others --exclude-standard
   

   If there are uncommitted changes, do NOT silently skip the fetch. Instead:

   • Show the user a concise summary of what's modified, staged, and untracked (with file paths and a few representative lines of diff).
   • Ask whether they want to:
     • (a) commit and keep — stage and commit the changes with a message they approve, then continue with fetch + rebase (git rebase origin/main after fetch),
     • (b) stash temporarily — stash with a descriptive label, then continue with fetch, and remind them to git stash pop afterwards,
     • (c) discard — only after explicit confirmation, run git checkout -- . and git clean -fd, then continue with fetch.
   • Do not invent a default — wait for the user's choice before proceeding.

   If the working tree is clean, run:

   abra recipe fetch $ARGUMENTS --force
   git -C ~/.abra/recipes/$ARGUMENTS fetch origin main
   

   • abra recipe fetch pulls all tags and branches and checks out the latest tagged version.
   • The explicit git fetch origin main ensures origin/main is up to date even if the latest published tag is older than main.

3. Check what already exists on upstream main — before planning anything, compare the recipe's currently-checked-out version to origin/main:

   # Recent commits on upstream main
   git -C ~/.abra/recipes/$ARGUMENTS log origin/main --oneline -10
   
   # Commits on origin/main that are NOT in the current checkout
   git -C ~/.abra/recipes/$ARGUMENTS log HEAD..origin/main --oneline
   

   • If origin/main has commits beyond the current checkout, inspect them carefully. Someone may have already started the upgrade (image bumps, version label changes, env var additions). If yes, re-plan from the tip of origin/main, not from the deployed version — your goal becomes "what's left to add on top of what's already there," not "duplicate everything from scratch."
   • Also check upstream PRs at https://git.coopcloud.tech/coop-cloud/$ARGUMENTS/pulls for in-flight work that might overlap.

4. Show current released versions and check for upgrades:

   abra recipe versions $ARGUMENTS -m
   abra recipe upgrade $ARGUMENTS -m -n
   

   • If no upgrades are available, tell the user the recipe is already up to date and stop.

5. Look up upstream release notes:

   • Check if recipe-info/$ARGUMENTS/upstream.md exists in the workspace.
   • If it exists, read it to get the release notes URLs for each image/service.
   • If it does NOT exist, try to discover the upstream project and release notes URLs:
     • Read the recipe's compose.yml to identify all images.
     • For each image, search for its GitHub repository and releases page.
     • Create recipe-info/$ARGUMENTS/upstream.md with the discovered URLs (follow the format of existing upstream.md files in sibling recipe directories).
     • Also create the recipe-info/$ARGUMENTS/tests/ directory if it doesn't exist.

6. For each service with available upgrades, fetch and summarise the release notes between the current version and the upgrade version(s). Pay special attention to and explicitly call out:

   • Breaking changes — API removals, renamed/removed config options, changed defaults, dropped support for older runtimes/dependencies
   • Required migration steps — database migrations, data format changes, manual upgrade procedures
   • Config changes needed by the operator — new required environment variables, changed variable names/formats, new secrets, changed ports or volume paths, deprecated settings that will stop working
   • Dependency version requirements — e.g. "now requires PostgreSQL 15+", "minimum Redis 6.2"
   • If any of the above are found, present them in a clearly marked "Operator Action Required" section per service.

7. Read the recipe's README at ~/.abra/recipes/$ARGUMENTS/README.md (if it exists):

   • Check for upgrade-specific instructions, migration steps, or breaking change notes.

8. Write upgrade info for future reference:

   • Create the planned-updates/ directory if it doesn't already exist.
   • Write all gathered information to planned-updates/$ARGUMENTS-upgrade-info-<YYYY-MM-DD>.md (using today's date).
   • The file should be structured markdown containing:
     • Current version(s) of the recipe
     • Available image tag upgrades
     • Operator Action Required items (breaking changes, config changes, migrations)
     • Changelog summaries with links to full release notes
     • Suggested next steps

9. Create the upgrade plan:

   • Create the plans/ directory if it doesn't already exist.
   • Write an upgrade plan to plans/$ARGUMENTS-upgrade-<YYYY-MM-DD>.md (using today's date).
   • The plan focuses on updating the recipe itself (the compose.yml, config files, and recipe version label). It should include:
     • Goal: one-line summary (e.g. "Upgrade CryptPad recipe from 2025.9.0 to 2026.2.0 and nginx from 1.25 to 1.29")
     • Image tag changes: a table of service / current tag / new tag
     • Upstream release-notes links: the release-notes URL for each upgraded image/service (from recipe-info/$ARGUMENTS/upstream.md, between the current → new version), recorded verbatim so /recipe-upgrade-apply can put them in the PR body (**Upstream release notes:** <service> <old>→<new>: <url>), not just the report.
     • Recipe version bump: the semver reasoning (patch/minor/major) — i.e. which abra recipe release flag applies (-z patch / -y minor / -x major). The PR does not bump the coop-cloud.*.version label; /recipe-upgrade-apply records the recommended abra recipe release <recipe> -<x|y|z> in the PR body, and the label bump + tag + publish happen at the end via that real command (after the upstream PR merges — see /recipe-upstream). So just state the bump kind + reasoning here, not a version string.
     • Recipe changes needed: any modifications to compose.yml beyond the image tags — new env vars, changed config templates, new volumes, updated labels, added/removed services, etc. based on what the upstream release notes require
     • Risks and caveats: breaking changes from upstream, known issues from release notes, things that need manual verification
   • At the bottom, in a separate Deployment section (clearly marked as not part of the recipe update plan itself), briefly note:
     • The user can run /recipe-upgrade-apply $ARGUMENTS to apply the plan, deploy to the test instance, run tests, and commit/tag
     • Any post-deploy steps operators will need when applying this update to production (migration commands, scripts to run, etc.)

10. Tell the user the plan file path and suggest they review it, then run /recipe-upgrade-apply $ARGUMENTS to execute.