--- description: Audit and update all software and dependencies, test each change, commit individually, write release notes, tag the release, push argument-hint: "[optional scope, e.g. 'patch and minor only' or 'skip docker']" --- # Dependency & Software Update Update everything this application depends on to current, supported versions. Work carefully and verify each change, and pause at the checkpoints marked **STOP** so I can review. Extra scope or instructions for this run (may be empty): $ARGUMENTS If this project's CLAUDE.md has an "Updates" section, follow it. It may list test commands, smoke-test URLs, pinned versions, or packages to leave alone, and it takes priority over the defaults below. ## Phase 0: Preflight 1. Run `git status`. If the working tree is not clean, **STOP** and tell me. Do not stash or commit my in-progress work. 2. Note the current branch and confirm it tracks a remote. Record the starting commit (`git rev-parse HEAD`) as ``. It's the rollback reference for the code. 3. Find out how this project builds, tests, lints, and runs. Check CLAUDE.md, README, package scripts, Makefile, Dockerfile, and docker-compose files. 4. **Run a baseline** of build, tests, lint, and (if possible) a container build, *before changing anything*. Record what passes and what already fails, so that later failures can be traced to a specific update and pre-existing problems aren't blamed on it. 5. **Create a rollback point** before changing anything. Use today's date as `` (YYYY-MM-DD): - **Images:** for each image this project builds or runs (from the Dockerfile and compose files), tag the version currently in use with a **project-scoped** tag: `docker tag : :-pre-update--` (e.g. `mysql:8.0-pre-update-myapp-2026-11-17`). Shared images like `mysql` or `redis` are often used by several projects on the same server, so the project name keeps one project's rollback tags from overwriting another's. - `` is the compose project name (`docker compose config --format json` → `name`), or the repo folder name if there is no compose file. Lowercase it and replace anything other than `a-z 0-9 . _ -` with `-`. - If the tag already exists (a second run on the same day), add a suffix like `-2`. - List the tags you created. - **Data:** if the project has a database or stateful volume, back it up yourself (see "Database backup" below) before any changes. If the backup fails or can't be verified, **STOP**. Do not continue the update without a good backup. ### Database backup - **Location:** use the backup path from CLAUDE.md's "Updates" section if one is set. Otherwise use `~/backups//`. It must be **outside the repo**. Create it with `chmod 700`, make each backup file `chmod 600`, and never commit a backup. - **Filename:** `-pre-update-.` - **Method:** take a consistent backup *without stopping the app* when the database supports it. Get credentials from the running container's environment or the compose/env files. Never print passwords in your output. - PostgreSQL: `docker compose exec -T pg_dump -U -Fc > .dump` - MySQL/MariaDB: `docker compose exec -T mysqldump --single-transaction -u -p"$PASS" > .sql`, then gzip it - SQLite: `sqlite3 ".backup '.sqlite'"`. Never use a plain `cp` on a live SQLite file. - MongoDB: `mongodump --archive --gzip` - Redis or caches that only hold rebuildable data: skip them and say so. - Anything else (an unknown volume, a database that can't be dumped live): **STOP and ask me** before stopping containers to tar the volume, because that means downtime. - **Verify the backup** before moving on. The file must not be empty, and it must pass a quick check that it can be read: `pg_restore --list` for Postgres, `PRAGMA integrity_check` for SQLite, `gunzip -t` for gzipped dumps, or checking that a `.sql` file ends with the dump-complete marker. Report the file's size and path. - **Write down the restore command** for this specific backup. It goes in the release notes Rollback section. Don't run a restore unless I ask. - **Pruning:** keep the 5 most recent pre-update backups for each database. List any older ones and ask before deleting them. ## Phase 1: Inventory Check every layer that applies, not just the main package manifest: - **Language runtime**: Node, Python, Go, PHP, etc. Look at `.nvmrc`, `.python-version`, `engines`, `pyproject.toml`, `go.mod`, and Docker base images. - **App dependencies**: npm/pnpm/yarn, pip/poetry/uv, composer, go modules, etc. Use the ecosystem's own tools (`npm outdated`, `pip list --outdated`, `go list -m -u all`, ...). - **Container images**: `FROM` lines in Dockerfiles and `image:` tags in compose files, including databases, Redis, reverse proxies, and other sidecars. Check for newer tags and whether the current tag is still supported. - **OS packages** installed in Dockerfiles. - **Tooling**: build tools, linters, test frameworks, TypeScript, bundlers. - **CI config**, if present (GitHub Actions versions, etc.). - **Security**: run `npm audit`, `pip-audit`, or the equivalent. Note any CVEs, especially ones affecting current versions. For every **major** version bump, and for runtime or database image bumps, read the changelog or migration guide and list the breaking changes that actually affect this codebase (search the code for the affected APIs). ## Phase 2: Plan (**STOP**) Present a table: | Component | Current | Latest | Type (patch/minor/major) | Security fix? | Breaking changes affecting us | Plan | Then give a proposed update order: 1. Security fixes first 2. Patch and minor updates (related packages grouped, e.g. a framework and its `@types` or plugins) 3. Major updates, one per commit 4. Runtime and base image updates last Call out anything you recommend **skipping or deferring** and why (e.g. a major version that requires a rewrite, or a version that is too new or unstable). Never move a database image across a major version without my explicit approval, because that can require a data migration. **Wait for my approval before changing anything.** ## Phase 3: Apply, one unit at a time For each update unit in the approved order: 1. Make the change and regenerate lockfiles with the project's package manager. Do not hand-edit lockfiles. 2. Apply any code changes the update requires. 3. Verify: build, tests, lint, and, where applicable, a container build plus a quick smoke test (start the app, hit the health/home endpoint, then shut it down). 4. If verification passes and matches the baseline, **commit just this unit**: - Format: `chore(deps): bump → `. Use `fix(deps):` for security fixes and `feat!`/`chore(deps)!:` with a body for majors that needed code changes. - In the commit body, briefly note any code changes and why. 5. If it fails: make a reasonable attempt to fix it. If the fix becomes large or risky, **revert this unit** (`git checkout -- .` / restore the lockfile), record it as deferred with the error, and continue with the next unit. Rules: - Don't commit secrets, `.env` files, or build output. - Don't skip git hooks (`--no-verify`) and don't force-push. - Don't disable, skip, or delete tests to make things pass. - Don't push during this phase. ## Phase 4: Release notes Write to `release-notes/YYYY.MM.md`, using the current year and month (e.g. `release-notes/2026.10.md`). - If the file **already exists**, append a new dated section. Never overwrite or rewrite earlier entries. - If it doesn't exist, create it with a `# YYYY.MM Release Notes` heading. - Match the style of earlier files in `release-notes/` if there are any. Otherwise use this structure: ```markdown ## YYYY-MM-DD: Dependency & software updates ### Summary One or two sentences on what changed and anything notable. ### Updated | Component | From | To | Type | Notes | |---|---|---|---|---| ### Security - CVE / advisory → fixed by (or "None") ### Code changes - Changes made to support updates (or "None") ### Deferred / skipped - : reason, and what's needed to do it later ### Verification - Build / tests / lint / container build / smoke test results ### Rollback - Starting commit: `` - Image tags: `:-pre-update--` (list each) - Database backup: path and size, or "not applicable" - Restore command: the exact command for this backup ``` Commit it as `docs(release-notes): YYYY.MM dependency updates`. ## Phase 5: Final verification and push (**STOP**) 1. Do a clean verification from scratch: fresh dependency install (`npm ci`, a clean venv, etc.), full build, full test suite, and `docker build --no-cache` if there's a Dockerfile. 2. Show me: - `git log --oneline` of the commits made in this run - Before and after test results compared with the baseline - Deferred items - Anything I need to do manually on deploy (env var changes, DB migrations, volume or permission changes, image re-pulls) 3. **Ask me to confirm**, then: - **Create a release tag** on the final commit, named `vYYYY.MM` with the current year and month (e.g. `v2026.11`), matching the release notes file: `git tag -a vYYYY.MM -m "YYYY.MM dependency updates"`. If that tag already exists (a second run in the same month), add a suffix like `-2`. Never move or overwrite an existing release tag. - Push the commits and the release tag together: `git push && git push origin vYYYY.MM`. - If any final check fails, don't tag or push. Explain what failed instead. 4. Print the rollback commands specific to this project. Fill in the real tag and image names: - Undo one bad update: `git revert `, then rebuild and redeploy - Undo the whole run: `git revert --no-edit ..HEAD`, then rebuild and redeploy - Run the old images immediately: change the image tags in compose to `-pre-update--`, then `docker compose up -d` - Restore the database from the backup, only if a schema or data migration happened 5. Run **Housekeeping** (below) for this project's image tags. ## Housekeeping Run at the end of Phase 5, after the push. Rollback image tags pile up over time. - **Scope:** only touch tags matching `*-pre-update--*` for this project's images. Never remove another project's `pre-update` tags, even if they're on the same image. List them with `docker images --format '{{.Repository}}:{{.Tag}}' | grep -- "-pre-update--"`. - **Keep:** this run's tags plus the 2 most recent earlier runs (3 runs total) for each image. - **Prune:** list the older tags and **ask me** before running `docker rmi :` on them. Removing a tag only deletes the image if no other tag or container still uses it, so a shared image used by another project stays. - Old-format tags (`:pre-update-` with no project name) came from earlier runs and may belong to any project. List them separately, but don't include them in the prune unless I say so. - Keep git tags. They cost nothing.