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

---
description: Create a detailed upgrade plan for a recipe
argument-hint: <recipe-name>
allowed-tools: [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:
   ```bash
   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:
   ```bash
   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`:
   ```bash
   # 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.