Salesforce Delta Deployment Skill

This skill provides an interactive, polished experience for Salesforce delta deployments using sfdx-git-delta. It replaces manual script execution with guided decision points.

Quick Mode

If the user invokes /sf-deploy quick, skip all confirmations and use these defaults:

•Mode: Validate only (dry-run)
•Range: All changes on this branch vs develop
•Tests: Run related tests

With commit count: /sf-deploy quick N (where N is a number)

•Mode: Validate only (dry-run)
•Range: Last N commits
•Tests: Run related tests

Examples:

code

/sf-deploy quick      # Validate all changes vs develop
/sf-deploy quick 1    # Validate last 1 commit
/sf-deploy quick 3    # Validate last 3 commits

For standard /sf-deploy, follow the full interactive flow below.

Workflow

Step 1: Prerequisite Checks

Run all prerequisite checks upfront before any interactive prompts. If any check fails, stop immediately with a clear error message.

Run these checks in parallel:

bash

# Check 1: Is this a git repository?
git rev-parse --git-dir 2>/dev/null

# Check 2: Is sf CLI installed?
command -v sf

# Check 3: Is there an authenticated org?
sf org display --json 2>/dev/null

Evaluate results:

Check	Failure Condition	Error Message
Git repo	Command fails or returns error	"This directory is not a git repository. Run this command from a Salesforce project with git initialized."
sf CLI	Command returns empty	"Salesforce CLI (sf) is not installed. Install it with: `npm install -g @salesforce/cli`"
Authenticated org	Returns NoDefaultEnvError or fails	"No default Salesforce org found. Authenticate with: `sf org login web --set-default`"

If all checks pass:

•Extract and store the alias and username from the org display JSON output
•Continue to Step 2

Step 2: Confirm Target Org

Use AskUserQuestion to confirm the target org:

•Header: "Target Org"
•Question: "Deploy to org: {alias} ({username})?"
•
Options:
- •"Continue" - Proceed with deployment
- •"Cancel" - Stop the deployment process

If user selects Cancel, stop and inform them to authenticate to the correct org.

Step 3: Get and Confirm Branch

Get the current branch:

bash

git rev-parse --abbrev-ref HEAD

Use AskUserQuestion to confirm:

•Header: "Branch"
•Question: "Deploy from branch: {branch_name}?"
•
Options:
- •"Continue" - Proceed
- •"Cancel" - Stop

If user selects Cancel, stop and advise them to checkout the correct branch.

Step 4: Check for Uncommitted Changes

Check for uncommitted changes:

bash

git status --porcelain

If output is not empty, use AskUserQuestion to warn:

•Header: "Warning"
•Question: "You have uncommitted changes. These will NOT be included in the deployment. Continue anyway?"
•
Options:
- •"Continue anyway" - Proceed with deployment
- •"Cancel" - Stop to commit changes

Step 5: Sync with Remote

Pull latest changes:

bash

git pull origin {branch_name}

Report any issues if this fails.

Step 6: Select Deployment Mode

Use AskUserQuestion (skip in quick mode):

•Header: "Mode"
•Question: "What type of deployment?"
•
Options:
- •"Validate Only (Recommended)" - Run validation without deploying
- •"Deploy to Org" - Actually deploy changes to the org

Store the selection: validate or deploy.

Step 7: Select Commit Range

Use AskUserQuestion (skip in quick mode):

•Header: "Range"
•Question: "Which changes to include?"
•
Options:
- •"All changes vs develop (Recommended)" - Compare current branch to origin/develop
- •"Last 1 commit" - Only the most recent commit
- •"Last 3 commits" - The 3 most recent commits
- •"Up to specific commit" - Deploy up to a specific commit hash

Parsing user input from "Other":

If the user types custom text, parse it intelligently:

•"last 5 commits", "5 commits", "5" → Use last 5 commits
•"last commit", "1" → Use last 1 commit
•A commit hash (7+ hex chars) → Use as target commit
•"abc123", "feature-branch~2" → Treat as commit reference

Only ask a follow-up question if the input cannot be parsed.

If "Up to specific commit": Ask follow-up:

•Header: "Commit"
•Question: "Which commit? (select or type a hash)"
•
Options:
- •Show recent commits from git log --oneline -5 as selectable options

Store the range parameters for delta generation.

Step 8: Select Test Mode

Use AskUserQuestion (skip in quick mode):

•Header: "Tests"
•Question: "How should tests be handled?"
•
Options:
- •"Run related tests (Recommended)" - Extract and run test classes from the delta
- •"Skip tests" - Deploy without running tests

Step 9: Confirmation

Display a summary of all gathered information and ask for confirmation before proceeding.

Output a formatted summary:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Deployment Summary
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Org:      {alias} ({username})
  Branch:   {branch_name}
  Mode:     {Validate Only | Deploy}
  Range:    {All changes vs develop | Last N commits | Up to <hash>}
  Tests:    {Run related tests | Skip tests}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Use AskUserQuestion to confirm:

•Header: "Confirm"
•Question: "Proceed with deployment?"
•
Options:
- •"Yes, proceed" - Continue with deployment
- •"Cancel deployment" - Cancel the deployment

If user selects "Cancel deployment", stop and inform them the deployment was cancelled.

Step 10: Install sfdx-git-delta

Ensure sfdx-git-delta is installed:

bash

npm install -g sfdx-git-delta@latest

Step 11: Create Output Directory

Get project name from the git repository:

bash

basename "$(git rev-parse --show-toplevel)"

This returns the folder name of the git repository root (e.g., "my-salesforce-project").

Check for configuration: Look for deploy_base in the project's CLAUDE.md file under "Salesforce Deployment Configuration" section.

If deploy_base is NOT configured, use AskUserQuestion to prompt for it:

•Header: "Output Path"
•Question: "Where should deployment artifacts be saved? (This will be remembered if you add it to your project's CLAUDE.md)"
•
Options:
- •"./Delta" - Use a Delta folder in the current project (Recommended)
- •"~/SalesforceDeltas" - Use a shared folder in your home directory
- •Other - Let the user specify a custom path

Directory structure: The output is organized by project and version:

code

{deploy_base}/{project_name}/v{major}_{minor}/

Example with ~/SalesforceDeltas and project "acme-crm":

code

~/SalesforceDeltas/
└── acme-crm/
    ├── v1_0/
    ├── v1_1/
    └── v1_2/

Determine the next version number by checking existing directories under {deploy_base}/{project_name}/.

Create the versioned output directory:

bash

mkdir -p "{deploy_base}/{project_name}/v{major}_{minor}"

Step 12: Generate Delta Package

Based on the commit range selection, run the appropriate delta command:

All changes vs develop:

bash

sf sgd source delta --from origin/develop --to "origin/{branch}" -o "{output_dir}" --api-version 64.0

Last N commits:

bash

sf sgd source delta --from "HEAD~{N}" --to HEAD -o "{output_dir}" --api-version 64.0

Up to specific commit:

bash

sf sgd source delta --from "$(git merge-base origin/develop HEAD)" --to "{hash}" -o "{output_dir}" --api-version 64.0

Step 13: Process LightningTypeBundle

Check if any LightningTypeBundle components exist that need to be added to Package.xml.

Look for LWC TypeScript bundles in the source and add them to Package.xml if present.

Exclude lightningDesktopGenAi bundles as configured.

Step 14: Extract Test Classes (if running tests)

If test mode is "Run related tests":

•Read the generated Package.xml
•Find all Apex classes
•Filter to those containing "Test" in the name
•Store in a list for the deploy command

Example extraction:

bash

grep -oP '(?<=<members>)[^<]*Test[^<]*(?=</members>)' "{output_dir}/package/package.xml" | sort -u

Step 15: Execute Deployment

Build and run the deployment command:

Validation mode:

bash

sf project deploy start \
  --manifest "{output_dir}/package/package.xml" \
  --dry-run \
  [--test-level RunSpecifiedTests --tests {test_classes}] \
  --verbose

Deploy mode:

bash

sf project deploy start \
  --manifest "{output_dir}/package/package.xml" \
  [--test-level RunSpecifiedTests --tests {test_classes}] \
  --verbose

If destructive changes exist at {output_dir}/destructiveChanges/destructiveChanges.xml, add: --post-destructive-changes "{output_dir}/destructiveChanges/destructiveChanges.xml"

Step 16: Report Results

After deployment completes:

•Report success or failure status
•Show the number of components deployed/validated
•If tests ran, show test results summary
•Show the path to the generated delta package for reference

Error Handling

Prerequisite failures (Step 1) - Stop immediately with actionable fix:

Error	Fix
Not a git repository	`git init` or navigate to a git-initialized Salesforce project
sf CLI not installed	`npm install -g @salesforce/cli`
No authenticated org	`sf org login web --set-default`

Runtime failures:

Error	Fix
Invalid commit hash	Ask user to provide a valid hash from `git log --oneline`
Delta generation fails	Show error, suggest checking git history and remote branch exists
Deployment fails	Show Salesforce error messages with component details
No remote branch	Suggest pushing the branch first: `git push -u origin {branch}`

Configuration Reference

The skill looks for these values in the project's CLAUDE.md under a "Salesforce Deployment Configuration" section. All settings have sensible defaults or will prompt if needed:

Setting	Default	Description
`deploy_base`	prompts user	Base path for deployment artifacts
`major_version`	`1`	Major version number for output directories
`api_version`	`64.0`	Salesforce API version
`base_branch`	`origin/develop`	Branch to compare against for delta generation
`excluded_bundles`	`lightningDesktopGenAi`	LWC bundles to exclude from deployment

Example CLAUDE.md Configuration

To pre-configure a Salesforce project, add this section to its CLAUDE.md:

markdown

## Salesforce Deployment Configuration

| Setting | Value |
|---------|-------|
| `deploy_base` | `/path/to/your/Delta` |
| `major_version` | `1` |
| `api_version` | `64.0` |
| `base_branch` | `origin/develop` |
| `excluded_bundles` | `lightningDesktopGenAi` |