---

name: salesforce-upgrade-migration description: 'Migrate Salesforce API, seasonal release, CLI, client-library, metadata, and integration contracts under compatibility and rollback controls. Use when planning platform upgrades. Trigger with "plan a Salesforce upgrade".' argument-hint: "[repository] [target-release]" allowed-tools: Read, Glob, Grep, WebFetch, Write, Edit version: 1.8.0 author: Jeremy Longshore jeremy@intentsolutions.io license: MIT tags: [saas, salesforce, upgrade, api-lifecycle, compatibility] model: inherit effort: high compatibility: Designed for Claude Code; API version, dependency, metadata, and production changes require code and Salesforce platform owner approval

Salesforce API and Toolchain Upgrade Control

Overview

Replace fixed-version guesswork with a complete inventory, compatibility matrix, staged validation, explicit ownership, and reversible consumer migration.

Prerequisites

• Repository and org inventory with API versions, libraries, CLI, metadata, events, packages, and consumers
• Current Salesforce API EOL policy, seasonal release notes, dependency releases, and customer support constraints
• Test environments, representative fixtures, compatibility owner, migration window, and rollback point

Tool Discipline

Use Read, Glob, and Grep to inspect approved repository and evidence files, WebFetch to re-check current first-party Salesforce documentation, and Write or Edit only for secretless plans, fixtures, configuration, and redacted receipts.

Current Contract

Salesforce supports REST API versions for a documented lifecycle and retires older versions after notice. As of this review, versions 21.0 through 30.0 are unavailable, while the current support table must be re-fetched before every migration.

Authentication

Use existing approved app and principal contracts for compatibility tests. Do not add a password fallback, copy production tokens into test, or broaden access to compensate for an upgrade defect.

Instructions

1. Inventory every explicit and library-default API version, CLI and library version, endpoint, schema snapshot, event client, and metadata consumer.
2. Re-fetch the API EOL table, release notes, client-library releases, CLI contract, and org upgrade schedule.
3. Classify each dependency as supported, deprecated, retired, preview, beta, or customer-specific and name an owner.
4. Build fixtures for response, error, pagination, metadata, event schema, limits, and partial-failure compatibility.
5. Upgrade one boundary at a time in a branch and validate static, unit, contract, sandbox, and deployment checks.
6. Canary representative reads and approved non-production writes, then migrate consumers in reversible cohorts.
7. Reconcile results, remove old versions only after all consumers and rollback windows close, and schedule the next review.

Approval Boundaries

Do not change API versions, dependencies, org settings, metadata, event consumers, or production traffic without code, platform, security, and business-owner approval.

Output

Return the version inventory, authority evidence, compatibility matrix, changed contracts, test results, cohort plan, rollback point, and retirement date.

Error Handling

Condition	Response
Requested API version is retired	Stop requests and migrate through a supported version after contract testing; do not retry the retired URI.
Library default differs from configured version	Pin and test the effective version at the raw request boundary.
Seasonal release changes org behavior	Hold rollout, reproduce in the preview or sandbox path, and update the compatibility decision.

Example

A redacted completion receipt might look like this:

apis=14; retired=2; target=discovered-supported; fixtures=12; sandbox=pass; cohorts=3; rollback=tagged

Resources

• REST API end-of-life policy
• Salesforce release notes

Next Steps

Run the workflow first in the lowest-risk authorized org and preserve its redacted receipt. Schedule a review against the next Salesforce seasonal release and the customer change calendar.