Bump Deps

Bump Dependencies

Analyze outdated dependencies and safely upgrade them with breaking change detection.

Workflow

1. Detect package manager based on current directory:

• If in frontend/ directory or working with TypeScript/JavaScript: use `pnpm` reference
• If in backend/ directory or working with Python: use `uv` reference

2. List outdated dependencies using the package manager-specific command from the reference

3. Spawn background analysis tasks for EACH notable upgrade:

CRITICAL: You MUST spawn the package-upgrade-analyzer sub-agent as a background Task for EACH and EVERY notable upgrade. Do NOT take shortcuts.

   Task(
     subagent_type="package-upgrade-analyzer",
     run_in_background=true,
     prompt="Analyze upgrade for {package_name} from {old_version} to {new_version}. GitHub: {repo_url}"
   )

Notable upgrades include:

• Major version bumps (e.g., v4 → v5)
• Packages with known breaking changes
• Core dependencies (React, Next.js, FastAPI, SQLAlchemy, etc.)

Spawn ALL tasks in a single message with multiple tool calls for maximum parallelism.

4. Wait for all background tasks to complete:

• Use TaskOutput to retrieve results from each background task
• Once ALL tasks are complete, ultrathink about the suggestions, migration guides, and release notes
• Invoke the Plan tool and its sub-agents to strategically address the breaking changes
• Plan carefully to maintain as much of the original behavior as possible

5. Ask clarifying questions:

• If the migration path forward is ambiguous, ASK questions
• Do NOT proceed unless you're sure about the safety of the dependency version bumps

6. Generate PR summary document:

Write a .claude/scratchpad/PR.md file using the PR template. Ensure that all package identifiers are properly wrapped in backticks for readability.

7. Create PR (user confirmation required):

After generating .claude/scratchpad/PR.md, use AskUserQuestion to confirm:

   AskUserQuestion(
     question="Ready to create the PR? You can edit .claude/scratchpad/PR.md first if needed.",
     header="Create PR?",
     options=[
       { label: "Create PR", description: "Create the PR with current PR.md content" },
       { label: "Let me edit first", description: "I'll edit PR.md and confirm when ready" }
     ]
   )

Once the user confirms, derive PR_TITLE and create the PR:

Deriving `PR_TITLE`:

1. Scope: Use app for frontend (pnpm), api for backend (uv) 2. Content (pick first applicable):

• ≤3 notable packages: List them by name with target major version

→ "deps(app): bump react-query to v5, next to v15"

• >3 packages with notable ones: Highlight 1-2 notable + count

→ "deps(api): bump sqlalchemy to v2 (+4 packages)"

• Many minor bumps only: Just the count

→ "deps(app): bump 12 dependencies" 3. Keep under 72 characters

   PR_TITLE="deps(app): bump react-query to v5, next to v15"
   gh pr create --base dev --head "$(git rev-parse --abbrev-ref HEAD)" --title "$PR_TITLE" --body-file .claude/scratchpad/PR.md

After successful PR creation:

   # Clean up the scratchpad file
   rm .claude/scratchpad/PR.md

Return the PR URL to the user.

Important Notes

• Always analyze breaking changes BEFORE upgrading
• Use parallel Task agents for efficiency
• Focus on safety over speed - better to ask than to break production
• Consider rollback strategies for risky upgrades

Additional Instructions

The remaining instructions are behavior overrides by the user.

<user-guidelines>

$ARGUMENTS

</user-guidelines>

Pull Request Template

Write the PR summary to .claude/scratchpad/PR.md using this template:

# Dependency Upgrade Summary

## Intended Changes

| Package | Current | Target | Migration Effort |
| ------- | ------- | ------ | ---------------- |
| pkg-a   | 1.0.0   | 2.0.0  | Medium           |
| pkg-b   | 3.1.0   | 3.2.0  | Low              |

## Resolved Breaking Changes

<details>
<summary><strong>pkg-a</strong>: 1.0.0 → 2.0.0 (Medium effort)</summary>

### Breaking Change 1: [Title]

- **Change**: [Description]
- **Resolution**: [How we addressed it]
- **Source**: [Link to GitHub Release or CHANGELOG entry]

### Breaking Change 2: [Title]

- **Change**: [Description]
- **Resolution**: [How we addressed it]
- **Source**: [Link to GitHub Release or CHANGELOG entry]

</details>

<details>
<summary><strong>pkg-b</strong>: 3.1.0 → 3.2.0 (Low effort)</summary>

No breaking changes. Minor version bump with backwards-compatible additions.

</details>

## Confidence Assessment

| Category         | Score | Notes                          |
| ---------------- | ----- | ------------------------------ |
| Breaking Changes | X/10  | All identified changes handled |
| Test Coverage    | X/10  | Relevant tests exist           |
| Documentation    | X/10  | Sources were authoritative     |
| **Overall**      | X/10  |                                |

## Deferred Work (Major Versions)

These major version upgrades require separate, dedicated migration efforts:

- **pkg-c**: v2.x → v3.x (blocked by: reason)
- **pkg-d**: v1.x → v2.x (requires: prerequisite)

## Source References

All breaking changes and migrations are backed by authoritative sources:

| Package | Source Type    | URL                                                        |
| ------- | -------------- | ---------------------------------------------------------- |
| pkg-a   | GitHub Release | https://github.com/owner/pkg-a/releases/tag/v2.0.0         |
| pkg-b   | CHANGELOG.md   | https://github.com/owner/pkg-b/blob/main/CHANGELOG.md#v320 |

Requirements

• Every breaking change MUST reference a specific changelog entry from the sub-agent analysis
• Confidence score reflects how well-documented the upgrade path is
• Deferred work section captures major versions that should NOT be upgraded in this PR
• Each package's breaking changes should be in a collapsible <details> section

pnpm Dependencies

Configuration for Next.js (TypeScript) frontend projects.

Check Outdated Dependencies

pnpm outdated --format list

Upgrade Commands

# Upgrade a specific package
pnpm update <package-name>

# Upgrade to latest (including major versions)
pnpm update <package-name> --latest

# Upgrade all packages
pnpm update

# Interactive upgrade
pnpm update --interactive

Directory

Run from frontend/ directory.

uv Dependencies

Configuration for FastAPI (Python) backend projects.

Check Outdated Dependencies

uv sync --upgrade --dry-run

Upgrade Commands

# Sync and upgrade all dependencies
uv sync --upgrade

# Add/upgrade a specific package
uv add <package-name>

# Add with version constraint
uv add <package-name>@<version>

Directory

Run from backend/ directory.