library-updater

name	library-updater
description	Update dependencies to latest stable versions. Use when upgrading libraries, updating Cargo.toml, pyproject.toml, package.json, go.mod, Gemfile, or modernizing dependencies.

Library Updater

Core: Update one dependency at a time. Research before updating. Test after each. Never batch untested changes.

THE EXACT PROMPT

Update all dependencies in this project to their latest stable versions.

For each dependency:
1. Use /software-research to find breaking changes between current and target version
2. Update the version
3. Run tests
4. Fix any issues (search web for recent solutions if needed)
5. If unfixable after 3 attempts, rollback and log why

Log everything to UPGRADE_LOG.md. Ask me before any refactoring that touches >10 files.

---

Supported Languages

Language	Manifest	Lock File	Registry
Rust	Cargo.toml	Cargo.lock	crates.io
Python	pyproject.toml, requirements.txt	poetry.lock, uv.lock	PyPI
Node.js	package.json	package-lock.json, yarn.lock	npm
Go	go.mod	go.sum	proxy.golang.org
Ruby	Gemfile	Gemfile.lock	rubygems.org

---

Workflow

Phase 1: Discovery

• Detect manifest: Cargo.toml | pyproject.toml | package.json | go.mod | Gemfile
• List dependencies with current versions
• Create UPGRADE_LOG.md from template

Phase 2: Per-Dependency Loop

For each dependency where current != latest stable:
│
├─ 1. RESEARCH (invoke software-research skill)
│     /software-research [package] changelog [current] to [latest]
│     → Get: breaking changes, deprecations, migration notes
│
├─ 2. UPDATE
│     Edit manifest → run install command
│
├─ 3. TEST
│     Run test suite
│     │
│     ├─ PASS → Log success, next dependency
│     │
│     └─ FAIL → Research fix (web search 2025-2026)
│               → Apply fix → Retest
│               → 3 failures? Rollback, log reason, continue
│
└─ 4. LOG to UPGRADE_LOG.md

Phase 3: Finalize

• Run full test suite
• Run security audit
• Complete UPGRADE_LOG.md summary

---

Commands Quick Reference

Language	Outdated	Update One	Test	Audit
Rust	cargo outdated	cargo update -p X	cargo test	cargo audit
Python	uv pip list --outdated	uv add X@latest	pytest	pip-audit
Node	npm outdated	npm i X@latest	npm test	npm audit
Go	go list -m -u all	go get X@latest	go test ./...	govulncheck
Ruby	bundle outdated	bundle update X	rspec	bundle audit

Full commands & gotchas: LANGUAGES.md

---

Version Rules

UPGRADE:  1.2.3 → latest stable (e.g., 1.3.0)
PRESERVE: alpha/beta/rc, git refs, path deps, nightly → note in log
SKIP:     if only alpha/beta available → stay on current stable

---

Failure Handling

Scenario	Action
Tests fail	Research fix → apply → retest (max 3 attempts)
Can't fix	Rollback, log details with error messages
Deprecation warnings	Fix if <5 call sites, else log for user
Major refactor needed	Stop and ask user before proceeding
Network/registry error	Retry 3x, then skip with note

Circuit Breakers — Stop and Ask User

• 5+ dependencies fail consecutively
• Total test failures exceed 10
• Estimated refactoring exceeds 20 files
• Security vulnerability introduced (detected by audit tools)

Rollback Procedure

# Git-based (preferred)
git checkout -- Cargo.toml Cargo.lock

# Or restore from backup
cp .upgrade-backup/Cargo.toml .

---

Integrating software-research

For each dependency upgrade, invoke the software-research skill:

/software-research [package-name] breaking changes [old-version] to [new-version]

This returns:

• Breaking changes with code examples
• Deprecation notices
• Migration guides
• Recent issues/PRs about upgrade problems

Why: software-research searches GitHub releases, changelogs, and recent web content more effectively than manual lookup.

---

Progress Tracking

Create claude-upgrade-progress.json for crash recovery:

{
  "status": "in_progress",
  "current": "serde",
  "completed": ["tokio", "anyhow"],
  "failed": [],
  "pending": ["reqwest", "tracing"]
}

Update after each dependency. Resume from this state if interrupted.

---

Validation

After all updates:

# Verify everything works
./scripts/validate-upgrade.sh

# Or manually:
# 1. Clean build
# 2. Full test suite
# 3. Security audit
# 4. No new deprecation warnings (or documented)

---

UPGRADE_LOG.md Format

# Dependency Upgrade Log

**Date:** 2025-01-16  |  **Project:** my-project  |  **Language:** Rust

## Summary
- **Updated:** 12  |  **Skipped:** 3  |  **Failed:** 1  |  **Needs attention:** 2

## Updates

### serde: 1.0.190 → 1.0.215
- **Breaking:** None
- **Tests:** ✓ Passed

### tokio: 1.35.0 → 1.40.0
- **Breaking:** `runtime::Handle::block_on` removed
- **Migration:** Replaced with `Runtime::block_on`
- **Tests:** ✓ Passed after fix

## Failed

### problematic-crate: 0.5.0 → 0.6.0
- **Reason:** Requires Rust 1.75+, project uses 1.70
- **Action:** Rolled back

## Needs Attention

### legacy-lib: 2.0.0 → 3.0.0
- **Issue:** Major API redesign, ~50 call sites
- **Migration guide:** https://example.com/migration

---

Reference Index

Topic	Reference
Commands by language	LANGUAGES.md
Changelog reading tips	CHANGELOG-TIPS.md
Progress template	assets/progress-template.json
Log template	assets/UPGRADE_LOG_TEMPLATE.md

---

Anti-Patterns

❌ Batch updates — Update 10 deps, then test. Which one broke it? ❌ Skip research — "It's just a patch version" → surprise breaking change ❌ Ignore deprecations — They become errors in the next major ❌ Force through failures — If it won't fix in 3 tries, it needs human judgment