Deploying Metadata

deploying-metadata: Comprehensive Salesforce DevOps Automation

Use this skill when the user needs deployment orchestration: dry-run validation, targeted or manifest-based deploys, CI/CD workflow advice, scratch-org management, failure triage, or safe rollout sequencing for Salesforce metadata.

When This Skill Owns the Task

Use deploying-metadata when the work involves:

• sf project deploy start, quick, report, or retrieval workflows
• release sequencing across objects, permission sets, Apex, and Flows
• CI/CD gates, test-level selection, or deployment reports
• troubleshooting deployment failures and dependency ordering

Delegate elsewhere when the user is:

• authoring Apex code → generating-apex
• authoring LWC components → generating-lwc-components
• creating custom objects or fields → generating-custom-object, generating-custom-field
• building Flows → generating-flow
• doing org data operations → handling-sf-data
• authoring or testing Agentforce agents → developing-agentforce

---

Critical Operating Rules

• Use `sf` CLI v2 only.
• On non-source-tracking orgs, deploy/retrieve commands require an explicit scope such as --source-dir, --metadata, or --manifest.
• Prefer `--dry-run` first before real deploys.
• For Flows, deploy safely and activate only after validation.
• Keep test-data creation guidance delegated to `handling-sf-data` after metadata is validated or deployed.

Default deployment order

This ordering prevents many dependency and FLS failures.

---

Required Context to Gather First

Ask for or infer:

• target org alias and environment type
• deployment scope: source-dir, metadata list, or manifest
• whether this is validate-only, deploy, quick deploy, retrieve, or CI/CD guidance
• required test level and rollback expectations
• whether special metadata types are involved (Flow, permission sets, agents, packages)

Preflight checks:

sf --version
sf org list
sf org display --target-org <alias> --json
test -f sfdx-project.json

---

Recommended Workflow

1. Preflight

Confirm auth, repo shape, package directories, and target scope.

2. Validate first

sf project deploy start --dry-run --source-dir force-app --target-org <alias> --wait 30 --json

Use manifest- or metadata-scoped validation when the change set is targeted.

3. If validation succeeds, offer the next safe workflow

After a successful validation, guide the user to the correct next action: 1. deploy now 2. assign permission sets 3. create test data via handling-sf-data 4. run tests / smoke checks 5. orchestrate multiple post-deploy steps in order

4. Deploy the smallest correct scope

# source-dir deploy
sf project deploy start --source-dir force-app --target-org <alias> --wait 30 --json

# manifest deploy
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunLocalTests --wait 30 --json

# manifest deploy with Spring '26 relevant-test selection
sf project deploy start --manifest manifest/package.xml --target-org <alias> --test-level RunRelevantTests --wait 30 --json

# quick deploy after successful validation
sf project deploy quick --job-id <validation-job-id> --target-org <alias> --json

5. Verify

sf project deploy report --job-id <job-id> --target-org <alias> --json

Then verify tests, Flow state, permission assignments, and smoke-test behavior.

6. Report clearly

Summarize what deployed, what failed, what was skipped, and what the next safe action is.

Output template: references/deployment-report-template.md

---

High-Signal Failure Patterns

Full workflows: references/orchestration.md, references/trigger-deployment-safety.md

---

CI/CD Guidance

Default pipeline shape: 1. authenticate 2. validate repo / org state 3. static analysis 4. dry-run deploy 5. tests + coverage gates 6. deploy 7. verify + notify

• When org policy and release risk allow it, consider --test-level RunRelevantTests for Apex-heavy deployments.
• Pair this with modern Apex test annotations such as @IsTest(testFor=...) and @IsTest(isCritical=true) — see generating-apex for authoring guidance.

Static analysis now uses Code Analyzer v5 (sf code-analyzer), not retired sf scanner.

Deep reference: references/deployment-workflows.md

---

Agentforce Deployment Note

Use this skill to orchestrate deployment/publish sequencing around agents, but use the agent-specific skill for authoring decisions:

• developing-agentforce for .agent authoring, Agent Builder, Prompt Builder, and metadata config

For full agent DevOps details, including Agent: pseudo metadata, publish/activate, and sync-between-orgs, see:

• references/agent-deployment-guide.md

---

Cross-Skill Integration

---

Reference Map

Start here

• references/orchestration.md
• references/deployment-workflows.md
• references/deployment-report-template.md

Specialized deployment safety

• references/trigger-deployment-safety.md
• references/agent-deployment-guide.md
• references/deploy.sh

Asset templates

• assets/package.xml — manifest template covering common metadata types
• assets/destructiveChanges.xml — template for removing metadata from target orgs

---

Score Guide

---

Completion Format

Deployment goal: <validate / deploy / retrieve / pipeline>
Target org: <alias>
Scope: <source-dir / metadata / manifest>
Result: <passed / failed / partial>
Key findings: <errors, ordering, tests, skipped items>
Next step: <safe follow-up action>

Credits & Acknowledgments

This skill is built on established Salesforce DevOps practices, official platform tooling, and the collective knowledge embedded in Salesforce's documentation and developer ecosystem.

---

Key Concepts

Two-Phase Deployment Pattern

The --dry-run validation before actual deployment is a community-established best practice to prevent production failures, widely promoted across official Salesforce documentation.

Quick Deploy Strategy

The workflow of validating with tests, then using quick deploy for actual deployment, originates from Salesforce release management best practices.

Test Level Recommendations

The guidance on appropriate test levels (RunLocalTests vs RunAllTests vs RunSpecifiedTests) comes from official Salesforce deployment documentation.

Incremental Deployment Strategy

The recommendation for small, frequent deployments over large batches is a DevOps industry best practice adapted for Salesforce.

---

Special Thanks

To the entire Salesforce DevOps community — release managers, architects, developers, and CI/CD engineers — for continuously improving deployment practices and making Salesforce deployments more reliable.

deploying-metadata

Comprehensive Salesforce DevOps automation using sf CLI v2. Validate, deploy, verify, and hand off cleanly to post-deploy activities.

Features

• Deployment Management: Execute, validate, and monitor deployments
• DevOps Automation: CI/CD pipelines, automated testing workflows
• Org Management: Authentication, scratch orgs, environment management
• Quality Assurance: Dry-run validation, tests, code coverage, pre-production verification
• Post-Deploy Handoff: Guide users to the next safe step after validation or deployment
• Troubleshooting: Debug failures, analyze logs, provide solutions

Quick Start

1. Invoke the skill

Skill: deploying-metadata
Request: "Deploy all changes to org dev with validation"

2. Common operations

Key Commands

# Validate before deploy (ALWAYS DO THIS)
sf project deploy start --dry-run --source-dir force-app --target-org [alias]

# Deploy with tests
sf project deploy start --source-dir force-app --test-level RunLocalTests --target-org [alias]

# Quick deploy (after validation)
sf project deploy quick --job-id [id] --target-org [alias]

# Check status
sf project deploy report --job-id [id] --target-org [alias]

# Cancel deployment
sf project deploy cancel --job-id [id] --target-org [alias]

Recommended post-validation flow

After a successful dry run, guide the user to the next safe step: 1. deploy now 2. assign permission sets 3. create test data with handling-sf-data 4. run tests or smoke checks 5. combine multiple post-deploy steps in order

Orchestration Order

generating-custom-object/generating-flow → deploying-metadata → handling-sf-data

Within deploying-metadata: 1. Objects/Fields 2. Permission Sets 3. Apex 4. Flows (as Draft) 5. Activate Flows

Best Practices

Cross-Skill Integration

Documentation

• SKILL.md - Full workflow and orchestration guidance
• references/orchestration.md - Deployment sequencing
• references/deployment-workflows.md - CI/CD and workflow examples
• references/deploy.sh - Sample deployment script

Requirements

• sf CLI v2
• Target Salesforce org
• Proper permissions for deployment

<!-- Parent: deploying-metadata/SKILL.md -->

Agentforce Agent Deployment Guide

Complete DevOps guide for deploying Agentforce agents using SF CLI

Overview

This guide covers the complete deployment lifecycle for Agentforce agents, including:

• Agent metadata types and pseudo metadata
• Sync operations (retrieve/deploy)
• Lifecycle management (activate/deactivate)
• Full deployment workflows

Related Skills:

• developing-agentforce - Agent authoring, publishing, Agent Builder, and Prompt Builder
• deploying-metadata - This skill - deployment orchestration

---

Agent Metadata Types

Agentforce agents consist of multiple metadata components:

Metadata Hierarchy

Bot (Agent Definition)
└── BotVersion (Version Config)
    └── GenAiPlannerBundle (Reasoning Engine)
        ├── GenAiPlugin (Topic 1)
        │   ├── GenAiFunction (Action 1)
        │   └── GenAiFunction (Action 2)
        └── GenAiPlugin (Topic 2)
            └── GenAiFunction (Action 3)

---

Agent Pseudo Metadata Type

The Agent pseudo metadata type is a convenience wrapper that retrieves or deploys all agent-related components at once.

Using the Agent Pseudo Type

# Retrieve agent + all dependencies from org
sf project retrieve start --metadata Agent:[AgentName] --target-org [alias]

# Deploy agent metadata to org
sf project deploy start --metadata Agent:[AgentName] --target-org [alias]

What Gets Synced

When using --metadata Agent:[Name]:

Retrieved/Deployed:

• Bot - Top-level chatbot
• BotVersion - Version configuration
• GenAiPlannerBundle - Reasoning engine
• GenAiPlugin - All topics
• GenAiFunction - All actions

NOT Included:

• Apex classes (deploy separately)
• Flows (deploy separately)
• Named Credentials (deploy separately)

---

Sync Operations

Retrieving Agents from Org

# Retrieve agent using pseudo metadata type
sf project retrieve start --metadata Agent:Customer_Support_Agent --target-org myorg

# Retrieve to specific output directory
sf project retrieve start --metadata Agent:Customer_Support_Agent --output-dir ./retrieved --target-org myorg

# Retrieve multiple agents
sf project retrieve start --metadata Agent:Support_Agent,Agent:Sales_Agent --target-org myorg

Retrieving Specific Components

# Retrieve just the bot definition
sf project retrieve start --metadata Bot:Customer_Support_Agent --target-org myorg

# Retrieve a specific BotVersion along with the bot definition
sf project retrieve start \
  --metadata Bot:Customer_Support_Agent \
  --metadata BotVersion:Customer_Support_Agent.v3 \
  --target-org myorg

# Retrieve just the planner bundle
sf project retrieve start --metadata GenAiPlannerBundle:Customer_Support_Agent_Planner --target-org myorg

# Retrieve all plugins (topics)
sf project retrieve start --metadata GenAiPlugin --target-org myorg

# Retrieve all functions (actions)
sf project retrieve start --metadata GenAiFunction --target-org myorg

Versioned retrieve note: Current SF CLI releases correctly retrieve the specific BotVersion you request instead of always pulling only the latest version.

Deploying Agents to Org

# Deploy agent using pseudo metadata type
sf project deploy start --metadata Agent:Customer_Support_Agent --target-org myorg

# Deploy with validation only (dry run)
sf project deploy start --metadata Agent:Customer_Support_Agent --dry-run --target-org myorg

# Deploy multiple agents
sf project deploy start --metadata Agent:Support_Agent,Agent:Sales_Agent --target-org myorg

---

Agent Lifecycle Management

Activate Agent

Makes an agent available to users.

# Manual activation
sf agent activate --api-name [AgentName] --target-org [alias]

# CI / deterministic activation of a known BotVersion
sf agent activate --api-name [AgentName] --version [N] --target-org [alias] --json

Requirements:

• Agent must be published first (sf agent publish authoring-bundle)
• All Apex classes and Flows must be deployed
• default_agent_user must be a valid org user with Agentforce permissions

Activation notes:

• --version [N] maps to the vN suffix in BotVersion metadata
• Omitting --version triggers interactive version selection
• Using --json without --version activates the latest agent version
• For CI/CD and reproducible rollouts, prefer --version [N] --json

Post-Activation:

• Agent is immediately available to users
• Preview command can be used for testing
• Changes require deactivation first

Deactivate Agent

Deactivates an agent for modifications. Required before making changes.

# Manual deactivation
sf agent deactivate --api-name [AgentName] --target-org [alias]

# Script-friendly deactivation
sf agent deactivate --api-name [AgentName] --target-org [alias] --json

When Deactivation is Required:

• Adding or removing topics
• Modifying action configurations
• Changing system instructions
• Updating variable definitions

Modification Workflow

# 1. Deactivate agent
sf agent deactivate --api-name Customer_Support_Agent --target-org myorg

# 2. Make changes to Agent Script

# 3. Re-publish
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 4. Re-activate
sf agent activate --api-name Customer_Support_Agent --target-org myorg

---

Agent Preview

Preview allows testing agent behavior before production deployment.

Preview Modes

Simulated Mode (Default)

sf agent preview --api-name Customer_Support_Agent --target-org myorg

• LLM simulates action responses
• No actual Apex/Flow execution
• Safe for testing - no data changes

Live Mode

sf agent preview --api-name Customer_Support_Agent --use-live-actions --target-org myorg

Requirements:

• Standard org auth (sf org login web)
• Apex classes and Flows deployed
• Agent must be active

Preview with Debug Output

sf agent preview --api-name Customer_Support_Agent --output-dir ./preview-logs --apex-debug --target-org myorg

v2.121.7+: Live preview no longer requires a Connected App. Standard org auth (sf org login web) suffices.

---

Full Deployment Workflows

New Agent Deployment

Complete workflow for deploying a new agent:

# 1. Deploy Apex classes (if any)
sf project deploy start --metadata ApexClass --target-org myorg

# 2. Deploy Flows
sf project deploy start --metadata Flow --target-org myorg

# 3. Validate Agent Script
sf agent validate authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 4. Publish agent
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 5. Preview (simulated mode)
sf agent preview --api-name Customer_Support_Agent --target-org myorg

# 6. Activate
sf agent activate --api-name Customer_Support_Agent --target-org myorg

# 7. Preview (live mode - optional)
sf agent preview --api-name Customer_Support_Agent --use-live-actions --target-org myorg

Update Existing Agent

# 1. Deactivate
sf agent deactivate --api-name Customer_Support_Agent --target-org myorg

# 2. Deploy updated dependencies (if any)
sf project deploy start --metadata ApexClass,Flow --target-org myorg

# 3. Validate
sf agent validate authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 4. Re-publish
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org myorg

# 5. Preview
sf agent preview --api-name Customer_Support_Agent --target-org myorg

# 6. Re-activate
sf agent activate --api-name Customer_Support_Agent --target-org myorg

Sync Between Orgs

# 1. Retrieve from source org
sf project retrieve start --metadata Agent:Customer_Support_Agent --target-org source-org

# 2. Deploy dependencies to target org first
sf project deploy start --source-dir force-app/main/default/classes --target-org target-org
sf project deploy start --source-dir force-app/main/default/flows --target-org target-org

# 3. Deploy agent metadata
sf project deploy start --metadata Agent:Customer_Support_Agent --target-org target-org

# 4. Publish agent in target org
sf agent publish authoring-bundle --api-name Customer_Support_Agent --target-org target-org

# 5. Activate in target org
sf agent activate --api-name Customer_Support_Agent --target-org target-org

CI/CD Pipeline Integration

Example deployment script for CI/CD:

#!/bin/bash
# deploy-agent.sh

set -e  # Exit on error

ORG_ALIAS=$1
AGENT_NAME=$2
AGENT_VERSION=$3

echo "🚀 Deploying agent: $AGENT_NAME to $ORG_ALIAS (version: $AGENT_VERSION)"

# Step 1: Deploy dependencies
echo "📦 Deploying Apex classes..."
sf project deploy start --metadata ApexClass --target-org $ORG_ALIAS --wait 10 --json

echo "📦 Deploying Flows..."
sf project deploy start --metadata Flow --target-org $ORG_ALIAS --wait 10 --json

# Step 2: Validate agent script
echo "✅ Validating Agent Script..."
sf agent validate authoring-bundle --api-name $AGENT_NAME --target-org $ORG_ALIAS --json

# Step 3: Check if agent exists (deactivate if needed)
echo "🔍 Checking agent status..."
if sf agent deactivate --api-name $AGENT_NAME --target-org $ORG_ALIAS --json 2>/dev/null; then
    echo "⏸️ Agent deactivated for update"
fi

# Step 4: Publish agent (--skip-retrieve skips metadata retrieval, faster in CI)
echo "📤 Publishing agent..."
sf agent publish authoring-bundle --api-name $AGENT_NAME --target-org $ORG_ALIAS --skip-retrieve --json

# Step 5: Activate agent deterministically
echo "▶️ Activating agent..."
sf agent activate --api-name $AGENT_NAME --version $AGENT_VERSION --target-org $ORG_ALIAS --json

echo "✅ Agent deployment complete: $AGENT_NAME"

Usage:

./deploy-agent.sh myorg Customer_Support_Agent 4

Pass the BotVersion number you intend to activate as the third argument.

---

Dependency Deployment Order

Critical: Dependencies must be deployed BEFORE the agent.

1. Custom Objects/Fields (generating-custom-object, generating-custom-field)
   ↓
2. Apex Classes (generating-apex)
   ↓
3. Flows (generating-flow)
   ↓
4. Named Credentials (building-sf-integrations, if external APIs)
   ↓
5. Agent Metadata (developing-agentforce publish)
   ↓
6. Agent Activation

Deployment Commands by Order

# 1. Objects/Fields
sf project deploy start --metadata CustomObject,CustomField --target-org myorg

# 2. Apex
sf project deploy start --metadata ApexClass --target-org myorg

# 3. Flows
sf project deploy start --metadata Flow --target-org myorg

# 4. Named Credentials (if needed)
sf project deploy start --metadata NamedCredential --target-org myorg

# 5. Publish agent
sf agent publish authoring-bundle --api-name My_Agent --target-org myorg

# 6. Activate
sf agent activate --api-name My_Agent --target-org myorg

---

Post-Deployment Validation for API Access

After deploying and activating an agent, verify it is accessible via the Agent Runtime API. Missing metadata causes silent 500 errors.

Validation Checklist

# 1. Verify GenAiPlannerBundle has plannerSurfaces
sf project retrieve start --metadata GenAiPlannerBundle --target-org myorg --output-dir ./check
grep -l "plannerSurfaces" ./check/**/*.xml
# If no results → add plannerSurfaces block (see below)

# 2. Verify BotVersion has surfacesEnabled=true
sf project retrieve start --metadata BotVersion --target-org myorg --output-dir ./check
grep "surfacesEnabled" ./check/**/*.xml
# Should show: <surfacesEnabled>true</surfacesEnabled>

# 3. Test API connectivity
curl -s -X POST "https://DOMAIN.my.salesforce.com/services/oauth2/token" \
  -d "grant_type=client_credentials&client_id=KEY&client_secret=SECRET" | jq .access_token

Fix: Add Missing plannerSurfaces

If the GenAiPlannerBundle XML is missing the plannerSurfaces block, add CustomerWebClient:

<GenAiPlannerBundle xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- existing elements -->
    <plannerSurfaces>
        <adaptiveResponseAllowed>false</adaptiveResponseAllowed>
        <callRecordingAllowed>false</callRecordingAllowed>
        <surface>SurfaceAction__CustomerWebClient</surface>
        <surfaceType>CustomerWebClient</surfaceType>
    </plannerSurfaces>
</GenAiPlannerBundle>

Note: EinsteinAgentApiChannel surfaceType is NOT available on all orgs. Use CustomerWebClient instead — it enables both Agent Builder Preview and Agent Runtime API access.

⚠️ Agent Script agents: connection messaging: in the .agent DSL ONLY generates a Messaging plannerSurface — CustomerWebClient is never auto-generated. You must manually patch it after EVERY sf agent publish authoring-bundle. See the post-publish workflow in developing-agentforce.

Fix: Add plannerSurfaces when agent is active

If the agent is active, you must deactivate before deploying:

# Deactivate → Deploy → Activate
sf agent deactivate --api-name AgentName -o TARGET_ORG --json
sf project deploy start --metadata "GenAiPlannerBundle:AgentName_vNN" -o TARGET_ORG --json
sf agent activate --api-name AgentName --version NN -o TARGET_ORG --json

Use the same NN value from the planner bundle version you just patched so activation is deterministic.

Fix: Enable surfacesEnabled on BotVersion

<BotVersion xmlns="http://soap.sforce.com/2006/04/metadata">
    <!-- existing elements -->
    <surfacesEnabled>true</surfacesEnabled>
</BotVersion>

Then redeploy:

sf project deploy start --metadata GenAiPlannerBundle,BotVersion --target-org myorg

Why this matters: Without CustomerWebClient plannerSurface, the Agent Builder Preview shows "Something went wrong" and the Agent Runtime API returns 500 UNKNOWN_EXCEPTION on session creation.

---

ISV Packaging (BotTemplate)

Use sf agent generate template to package an agent for distribution via managed packages on AppExchange.

Generate a BotTemplate

sf agent generate template \
    --agent-file force-app/main/default/bots/My_Agent/My_Agent.bot-meta.xml \
    --agent-version 1 \
    --output-dir my-package \
    --source-org my-scratch-org \
    --json

Important: This command packages Bot / BotVersion-based agents. It does not package Agent Script .agent authoring bundles.

What Gets Generated

The command generates a BotTemplate metadata type that wraps:

• Bot — Top-level agent definition
• BotVersion — Version configuration
• GenAiPlannerBundle — Reasoning engine and topic/action bindings

Packaging Workflow

1. Generate template: Run sf agent generate template as shown above 2. Include in package: Add the BotTemplate and GenAiPlannerBundle metadata to your managed package directory 3. Create package version: sf package version create --package <name> --installation-key <key> --wait 20 4. Install in subscriber org: sf package install --package <version-id> --target-org <alias> --wait 10 5. Publish agent in subscriber org: sf agent publish authoring-bundle --api-name <name> --target-org <alias>

Key Considerations

• The BotTemplate is designed for ISV distribution — it allows subscribers to install and customize the agent
• Subscribers can modify topics, actions, and instructions after installation
• The --agent-version flag specifies which BotVersion to template (typically 1 for new agents)
• The --agent-file must point to the .bot-meta.xml file in your local project
• --source-org must be a namespaced scratch org that contains the source agent
• Agent Script .agent bundles currently need a different rollout path; use source-driven publish workflows instead of sf agent generate template

---

Troubleshooting

"Internal Error, try again later"

Causes:

• Invalid default_agent_user
• Dependencies not deployed
• Flow/action variable name mismatch

Solutions:

# Verify user exists
sf data query --query "SELECT Id, Username FROM User WHERE Username = 'agent@example.com'" --target-org myorg

# Deploy dependencies first
sf project deploy start --metadata ApexClass,Flow --target-org myorg

"No active agents found"

Cause: Agent not activated

Solution:

sf agent activate --api-name My_Agent --target-org myorg

"Agent must be deactivated before changes"

Cause: Trying to modify active agent

Solution:

sf agent deactivate --api-name My_Agent --target-org myorg
# Make changes
sf agent publish authoring-bundle --api-name My_Agent --target-org myorg
sf agent activate --api-name My_Agent --target-org myorg

Deployment Fails with Missing Dependencies

Cause: Apex/Flows not deployed before agent

Solution: Follow the dependency deployment order above.

---

Cross-Skill Integration

Integration Pattern

# 1. generating-apex creates InvocableMethod class
# 2. generating-flow creates wrapper Flow
# 3. developing-agentforce creates agent with flow:// action
# 4. deploying-metadata orchestrates deployment in correct order

---

Command Reference

Agent-Specific Commands

Metadata Commands with Agent Pseudo Type

Management Commands

---

Related Documentation

• Agentforce Development Guide
• Agentforce Testing Guide

<!-- Parent: deploying-metadata/SKILL.md -->

Deployment Report Template

Standard output format for Salesforce deployment summaries.

Full Report Format

## Salesforce Deployment Report

### Pre-Deployment Checks
✓ Org authenticated: <org-alias> (<org-id>)
✓ Project validated: sfdx-project.json found
✓ Components identified: X classes, Y triggers, Z components

### Deployment Execution
→ Deployment initiated: <timestamp>
→ Job ID: <deployment-job-id>
→ Test Level: RunLocalTests

### Results
✓ Status: Succeeded
✓ Components Deployed: X/X
✓ Tests Passed: Y/Y (Z% coverage)

### Deployed Components
- ApexClass: AccountController, ContactTriggerHandler
- LightningComponentBundle: accountCard, contactList
- CustomObject: CustomObject__c

### Next Steps
1. Verify functionality in target org
2. Monitor for any post-deployment issues
3. Update documentation and changelog

Compact Report Format

For quick summaries:

✓ Deployment: [org-alias] | Job: [job-id]
  Components: X/X | Tests: Y/Y (Z% coverage)
  Status: Succeeded

Failure Report Format

## Deployment Failed

### Error Summary
✗ Status: Failed
✗ Failed Components: 2/15

### Errors
1. ApexClass: MyController
   - Line 45: Variable 'acc' does not exist

2. CustomField: Account.Custom__c
   - Missing referenced field: Contact.Email

### Suggested Actions
1. Fix compilation error in MyController.cls:45
2. Deploy Contact.Email field before Account.Custom__c
3. Re-run deployment after fixes

CI/CD Pipeline Output

For automated pipelines (GitHub Actions, GitLab CI):

deployment:
  status: success|failure
  job_id: "0Af..."
  org: "<alias>"
  components:
    total: 15
    deployed: 15
    failed: 0
  tests:
    total: 45
    passed: 45
    failed: 0
    coverage: 87.5
  duration: "2m 34s"
  errors: []

<!-- Parent: deploying-metadata/SKILL.md -->

Salesforce Deployment Workflow Examples

This file contains practical examples of common Salesforce deployment scenarios using the deploying-metadata skill.

Example 1: Basic Production Deployment

User Request:

"Deploy my changes to production with full test coverage"

Skill Execution:

1. Pre-deployment checks

   sf org display --target-org production
   sf project deploy start --dry-run --test-level RunLocalTests --target-org production --wait 30

2. Validation output

   ✓ Deployment validation succeeded
   ✓ Tests passed: 145/145 (92% coverage)
   ✓ Components validated: 23

3. Quick deploy (using validation ID)

   sf project deploy quick --job-id 0Af5g00000XXXXX --target-org production

4. Final output

   ## Salesforce Deployment Report

   ✓ Status: Succeeded
   ✓ Components Deployed: 23/23
   ✓ Tests Passed: 145/145 (92% coverage)
   ✓ Duration: 8m 32s

   ### Deployed Components:
   - ApexClass: AccountController, ContactTriggerHandler, LeadProcessor
   - ApexTrigger: AccountTrigger, ContactTrigger
   - LightningComponentBundle: accountCard, contactList

---

Example 2: Selective Component Deployment

User Request:

"Deploy only the new Lightning Web Components to sandbox"

Skill Execution:

1. Identify LWC components

   # Find all LWC components
   ls -R force-app/main/default/lwc/

2. Deploy specific directory

   sf project deploy start \
     --source-dir force-app/main/default/lwc \
     --target-org dev-sandbox \
     --test-level NoTestRun \
     --wait 15

3. Output

   ✓ Deployment succeeded
   ✓ Components Deployed:
     - accountCard (LWC)
     - contactList (LWC)
     - opportunityBoard (LWC)

---

Example 3: Hotfix Deployment

User Request:

"I need to deploy an urgent bug fix in AccountController to production"

Skill Execution:

1. Verify the specific file

   cat force-app/main/default/classes/AccountController.cls

2. Run targeted tests

   sf apex run test \
     --tests AccountControllerTest \
     --target-org production \
     --wait 5

3. Deploy single class

   sf project deploy start \
     --source-dir force-app/main/default/classes/AccountController.cls \
     --target-org production \
     --test-level RunSpecifiedTests \
     --tests AccountControllerTest \
     --wait 10

4. Verification

   sf project deploy report --job-id <job-id> --target-org production

---

Example 4: Manifest-Based Deployment

User Request:

"Deploy using the package.xml manifest for release v2.3"

Skill Execution:

1. Read manifest file

   cat manifest/package-v2.3.xml

2. Validate deployment

   sf project deploy start \
     --manifest manifest/package-v2.3.xml \
     --target-org production \
     --dry-run \
     --test-level RunLocalTests \
     --wait 30

3. Quick deploy

   sf project deploy quick --job-id 0Af5g00000XXXXX --target-org production

---

Example 5: Scratch Org Development Workflow

User Request:

"Create a scratch org and deploy my feature branch"

Skill Execution:

1. Create scratch org

   sf org create scratch \
     --definition-file config/project-scratch-def.json \
     --alias feature-branch-123 \
     --duration-days 7 \
     --set-default

2. Push source

   sf project deploy start --target-org feature-branch-123

3. Assign permission sets

   sf org assign permset --name AdminPermSet --target-org feature-branch-123

4. Import test data

   sf data import tree --plan data/sample-data-plan.json --target-org feature-branch-123

5. Open org

   sf org open --target-org feature-branch-123

---

Example 6: Deployment Rollback

User Request:

"The deployment failed, I need to rollback to the previous version"

Skill Execution:

1. Retrieve current production metadata (if not backed up)

   sf project retrieve start \
     --manifest manifest/package-production.xml \
     --target-org production

2. Check out previous version from git

   git checkout v2.2-stable

3. Deploy previous version

   sf project deploy start \
     --manifest manifest/package-v2.2.xml \
     --target-org production \
     --test-level RunLocalTests \
     --wait 30

4. Verify rollback

   sf org open --target-org production

---

Example 7: Destructive Changes

User Request:

"Remove the deprecated CustomObject__c and old Apex classes"

Skill Execution:

1. Create destructiveChanges.xml

   <?xml version="1.0" encoding="UTF-8"?>
   <Package xmlns="http://soap.sforce.com/2006/04/metadata">
       <types>
           <members>DeprecatedClass1</members>
           <members>DeprecatedClass2</members>
           <name>ApexClass</name>
       </types>
       <types>
           <members>CustomObject__c</members>
           <name>CustomObject</name>
       </types>
       <version>66.0</version>
   </Package>

2. Deploy with destructive changes

   sf project deploy start \
     --manifest manifest/package.xml \
     --post-destructive-changes manifest/destructiveChanges.xml \
     --target-org production \
     --test-level RunLocalTests \
     --wait 30

Current SF CLI releases support this combined pattern correctly, including runs where the manifest deploys one set of components while a destructive changes file deletes different components in the same operation.

---

Example 8: Multi-Environment Deployment

User Request:

"Deploy to dev, then staging, then production after each passes validation"

Skill Execution:

1. Deploy to Dev

   sf project deploy start --target-org dev --test-level NoTestRun --wait 10

2. Deploy to Staging

   sf project deploy start --target-org staging --test-level RunLocalTests --wait 20

3. Validate Production

   sf project deploy start --target-org production --dry-run --test-level RunLocalTests --wait 30

4. Deploy to Production (after manual approval)

   sf project deploy quick --job-id <validation-job-id> --target-org production

---

Example 9: Code Coverage Analysis

User Request:

"Check my code coverage and identify classes that need more tests"

Skill Execution:

1. Run all tests

   sf apex run test \
     --test-level RunLocalTests \
     --target-org dev \
     --code-coverage \
     --result-format human \
     --wait 15

2. Analyze coverage report

   Overall Code Coverage: 87%

   Classes with <75% coverage:
   - LeadProcessor: 62%
   - OpportunityHelper: 71%
   - AccountBatchProcessor: 45%

   Recommendations:
   1. Add test methods for LeadProcessor.processLeads()
   2. Test error handling in OpportunityHelper
   3. Create comprehensive tests for AccountBatchProcessor

---

Example 10: Deployment Error Recovery

User Request:

"Deployment failed with 'INVALID_CROSS_REFERENCE_KEY' error"

Skill Execution:

1. Analyze error

   Error: INVALID_CROSS_REFERENCE_KEY
   Component: CustomObject__c.SomeLookupField__c
   Message: Field references non-existent object

2. Identify dependency

   grep -r "ReferencedObject__c" force-app/

3. Solution provided

   The error indicates that SomeLookupField__c references an object
   that doesn't exist in the target org.

   Solutions:
   1. Deploy the referenced object first
   2. Include both objects in the same deployment
   3. Update the field to reference a different object
   4. Check if the referenced object exists: sf org list metadata --metadata-type CustomObject

4. Deploy with dependencies

   # Include both in manifest
   sf project deploy start \
     --manifest manifest/package-with-dependencies.xml \
     --target-org production

---

Tips for Successful Deployments

1. Always validate first - Use --dry-run for production 2. Monitor test execution - Watch for test failures early 3. Check code coverage - Ensure >75% minimum 4. Deploy incrementally - Smaller deployments are easier to troubleshoot 5. Use version control - Tag releases for easy rollback 6. Document changes - Keep deployment logs 7. Test in sandbox - Never test directly in production 8. Handle dependencies - Deploy referenced metadata first

---

These examples demonstrate common patterns. The deploying-metadata skill adapts to your specific use case and provides guided assistance.

<!-- Parent: deploying-metadata/SKILL.md -->

Multi-Skill Orchestration: deploying-metadata Perspective

This document details how deploying-metadata fits into the multi-skill workflow for Salesforce development.

---

Standard Orchestration Order

┌─────────────────────────────────────────────────────────────────────────────┐
│  STANDARD MULTI-SKILL ORCHESTRATION ORDER                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. generating-custom-object / generating-custom-field                      │
│     └── Create object/field definitions (LOCAL files)                       │
│                                                                             │
│  2. generating-flow                                                         │
│     └── Create flow definitions (LOCAL files)                               │
│                                                                             │
│  3. deploying-metadata  ◀── YOU ARE HERE                                            │
│     └── Deploy all metadata (REMOTE)                                        │
│                                                                             │
│  4. handling-sf-data                                                                 │
│     └── Create test data (REMOTE - objects must exist!)                     │
└─────────────────────────────────────────────────────────────────────────────┘

---

Why deploying-metadata Goes Third (Not Last)

deploying-metadata is the bridge between local files and the org:

handling-sf-data REQUIRES deployed objects. The error SObject type 'X' not supported means objects weren't deployed.

---

Deploy Order WITHIN deploying-metadata

When deploying multiple metadata types:

┌─────────────────────────────────────────────────────────────────────────────┐
│  INTERNAL DEPLOY ORDER                                                      │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. Custom Objects & Fields                                                 │
│     └── Objects must exist before anything references them                  │
│                                                                             │
│  2. Permission Sets                                                         │
│     └── Field-Level Security requires fields to exist                       │
│                                                                             │
│  3. Apex Classes                                                            │
│     └── @InvocableMethod for Flow actions                                   │
│                                                                             │
│  4. Flows (as Draft)                                                        │
│     └── Flows reference fields and Apex                                     │
│                                                                             │
│  5. Activate Flows                                                          │
│     └── Change status Draft → Active                                        │
└─────────────────────────────────────────────────────────────────────────────┘

Why this order?

• Flows need fields to exist
• Users need Permission Sets for field visibility
• Triggers may depend on active flows
• Draft flows can be tested before activation

---

Integration + Agentforce Extended Order

When deploying agents with external API integrations:

┌─────────────────────────────────────────────────────────────────────────────┐
│  AGENTFORCE DEPLOYMENT ORDER                                                │
├─────────────────────────────────────────────────────────────────────────────┤
│  1. configuring-connected-apps → Create OAuth Connected App                 │
│  2. building-sf-integrations    → Create Named Credential + External Service          │
│  3. generating-apex   → Create @InvocableMethod (if needed)                 │
│  4. generating-flow   → Create Flow wrapper                                 │
│                                                                             │
│  5. deploying-metadata         ◀── FIRST DEPLOYMENT                                 │
│     └── Deploy: Objects, Fields, Permission Sets, Apex, Flows              │
│                                                                             │
│  6. developing-agentforce → Create agent with flow:// target               │
│                                                                             │
│  7. deploying-metadata         ◀── SECOND DEPLOYMENT (Agent Publish)                │
│     └── sf agent publish authoring-bundle --api-name [AgentName]           │
│                                                                             │
│  8. handling-sf-data           → Create test data                                    │
└─────────────────────────────────────────────────────────────────────────────┘

---

Common Deployment Errors from Wrong Order

---

Two-Step Deployment Pattern (Recommended)

Always validate before deploying:

# Step 1: Dry-run validation
sf project deploy start --dry-run --source-dir force-app --target-org alias

# Step 2: Actual deployment (only if validation passes)
sf project deploy start --source-dir force-app --target-org alias

---

Cross-Skill Dependencies

Before deploying, verify these prerequisites:

---

developing-agentforce Integration

For agent deployments, use the specialized commands:

# Deploy dependencies first
sf project deploy start --metadata ApexClass,Flow --target-org alias

# Validate agent syntax
sf agent validate authoring-bundle --api-name AgentName --target-org alias --json

# Publish agent
sf agent publish authoring-bundle --api-name AgentName --target-org alias --json

# Activate a specific BotVersion deterministically in automation
sf agent activate --api-name AgentName --version N --target-org alias --json

If you omit --version, activation is interactive. For CI/CD and scripted orchestration, prefer --version N --json.

---

Invocation Patterns

---

Related Documentation

<!-- Parent: deploying-metadata/SKILL.md -->

Trigger Deployment Safety Guide

Overview

This guide covers deployment considerations for triggers, focusing on cascade failures, atomicity patterns, and async decoupling strategies.

---

1. Understanding Cascade Failures

What Are Cascade Failures?

When an exception in one trigger causes rollback of operations from preceding triggers in the chain.

Account Insert → AccountTrigger → ContactTrigger → OpportunityTrigger
                     ✓               ✓                 ✗ (Exception)

                 All three operations ROLL BACK

Default Behavior

• Uncaught exceptions in triggers cause rollback of all operations in the transaction
• This includes operations from other triggers that fired successfully
• This behavior may or may not be desired depending on business requirements

When Cascade Failure is DESIRED

• All operations represent ONE atomic business process
• Example: Order with line items must be complete or not exist
• Same business unit/persona owns all the data

// DESIRED cascade: Order and OrderItems must both succeed
trigger OrderTrigger on Order__c (after insert) {
    // If this fails, we WANT the Order insert to roll back
    List<OrderItem__c> items = createDefaultLineItems(Trigger.new);
    insert items;  // Exception here rolls back Order insert - GOOD
}

When Cascade Failure is PROBLEMATIC

• Operations represent INDEPENDENT business processes
• Example: Creating account + syncing to external CRM
• Different business units own different parts of the process

// PROBLEMATIC cascade: CRM sync failure shouldn't prevent Account creation
trigger AccountTrigger on Account (after insert) {
    // If CRM sync fails, Account creation also fails - BAD
    CRMService.syncNewAccounts(Trigger.new);  // Exception here rolls back Account
}

---

2. Atomicity Patterns

Explicit Savepoints

Use Database.setSavepoint() for explicit transaction control within a single process.

/**
 * Demonstrates explicit atomicity control for cross-object operations
 */
public class AccountOwnership {

    /**
     * Reassigns all related records when account owner changes.
     * This is an ATOMIC operation - all changes succeed or all roll back.
     */
    public static void reassignRelatedRecords(
        List<Account> accountsWithNewOwner,
        Map<Id, Account> oldAccountsById
    ) {
        // Create savepoint for atomic operation
        Savepoint sp = Database.setSavepoint();

        try {
            Map<Id, Id> newOwnerByAccountId = buildOwnerMap(accountsWithNewOwner);

            // Step 1: Reassign opportunities
            reassignOpportunities(newOwnerByAccountId);

            // Step 2: Reassign cases
            reassignCases(newOwnerByAccountId);

            // Step 3: Create transition tasks
            createOwnerTransitionTasks(accountsWithNewOwner, oldAccountsById);

        } catch (Exception e) {
            // Rollback ALL changes if ANY step fails
            Database.rollback(sp);

            // Log the failure for investigation
            ErrorLogger.log('AccountOwnership.reassignRelatedRecords', e);

            // Re-throw to inform the caller
            throw new AccountOwnershipException(
                'Failed to reassign related records: ' + e.getMessage()
            );
        }
    }
}

When to Use Savepoints

---

3. Async Decoupling Patterns

The Problem

After-trigger logic that represents an independent business process can cause cascade failures.

Solution: Queueable Jobs

/**
 * Queueable job for processing that should not block the main transaction
 */
public class AccountSyncQueueable implements Queueable, Database.AllowsCallouts {

    private Set<Id> accountIds;
    private TriggerOperation operationType;

    public AccountSyncQueueable(Set<Id> accountIds, TriggerOperation operationType) {
        this.accountIds = accountIds;
        this.operationType = operationType;
    }

    public void execute(QueueableContext context) {
        try {
            List<Account> accounts = [
                SELECT Id, Name, Website, Industry, BillingAddress
                FROM Account
                WHERE Id IN :accountIds
            ];

            switch on operationType {
                when AFTER_INSERT {
                    ExternalCRM.createAccounts(accounts);
                }
                when AFTER_UPDATE {
                    ExternalCRM.updateAccounts(accounts);
                }
                when AFTER_DELETE {
                    ExternalCRM.deleteAccounts(accountIds);
                }
            }

        } catch (Exception e) {
            // Log error but don't fail - this is independent of main transaction
            ErrorLogger.log('AccountSyncQueueable', e, accountIds);
        }
    }
}

Usage in Trigger Handler

public void afterInsert(List<Account> newAccounts, Map<Id, Account> newAccountsById) {
    // Synchronous operations that SHOULD block
    AccountNotifications.notifySalesTeam(newAccounts);

    // Async operations that should NOT block main transaction
    if (canEnqueueJob()) {
        System.enqueueJob(new AccountSyncQueueable(
            newAccountsById.keySet(),
            TriggerOperation.AFTER_INSERT
        ));
    }
}

private Boolean canEnqueueJob() {
    return !System.isBatch() &&
           !System.isFuture() &&
           Limits.getQueueableJobs() < Limits.getLimitQueueableJobs();
}

Platform Events for Maximum Decoupling

// Publisher (in trigger)
EventBus.publish(new Account_Changed__e(
    Account_Id__c = account.Id,
    Change_Type__c = 'INSERT'
));

// Subscriber (separate trigger on platform event)
trigger AccountChangedSubscriber on Account_Changed__e (after insert) {
    // Process events - failures here don't affect original transaction
    List<Id> accountIds = new List<Id>();
    for (Account_Changed__e event : Trigger.new) {
        accountIds.add(event.Account_Id__c);
    }
    // Sync to external system
}

Decoupling Decision Matrix

---

4. Pre-Deployment Checklist

Trigger Cascade Analysis

Before deploying triggers, analyze the cascade impact:

CHECKLIST:
□ List all triggers that fire on the same transaction
□ Identify which operations are atomic (same business process)
□ Identify which operations are independent (different processes)
□ Verify exception handling in each trigger
□ Check for recursive trigger prevention
□ Review async job usage and limits

Questions to Answer

1. What triggers will fire together?

• Map the full trigger chain for each DML operation
• Include triggers on related objects (parent-child)

2. What happens if each trigger fails?

• Which operations will roll back?
• Is that the desired behavior?

3. Are there external system calls?

• Should they be async?
• What happens if they fail?

4. What about governor limits?

• How many DML statements in the chain?
• How many SOQL queries?
• Can bulk operations stay within limits?

---

5. Testing Cascade Scenarios

Test Cascade Success

@IsTest
static void testTriggerChain_AllSucceed() {
    Test.startTest();
    Account acc = new Account(Name = 'Test');
    insert acc;  // Should fire AccountTrigger, create child records, etc.
    Test.stopTest();

    // Verify all expected records were created
    Assert.areEqual(1, [SELECT COUNT() FROM Contact WHERE AccountId = :acc.Id]);
    Assert.areEqual(1, [SELECT COUNT() FROM Task WHERE WhatId = :acc.Id]);
}

Test Cascade Failure (Expected Rollback)

@IsTest
static void testTriggerChain_ChildFailure_RollsBack() {
    // Configure scenario that will cause child trigger to fail
    Test.startTest();
    try {
        Account acc = new Account(Name = 'Trigger Failure Test');
        insert acc;
        Assert.fail('Expected DmlException');
    } catch (DmlException e) {
        // Expected - verify Account was NOT created
        Assert.areEqual(0, [SELECT COUNT() FROM Account WHERE Name = 'Trigger Failure Test']);
    }
    Test.stopTest();
}

Test Async Decoupling

@IsTest
static void testAccountInsert_CRMSyncAsync_DoesNotBlock() {
    // Even if CRM sync would fail, Account should be created
    Test.startTest();
    Account acc = new Account(Name = 'Async Test');
    insert acc;
    Test.stopTest();

    // Account should exist regardless of async job outcome
    Assert.areEqual(1, [SELECT COUNT() FROM Account WHERE Name = 'Async Test']);

    // Verify async job was enqueued
    Assert.areEqual(1, [SELECT COUNT() FROM AsyncApexJob WHERE JobType = 'Queueable']);
}

---

6. Deployment Commands for Trigger Safety

Validate Before Deploying

# Always validate triggers before deploying
sf project deploy start --dry-run \
    --source-dir force-app/main/default/triggers \
    --source-dir force-app/main/default/classes \
    --test-level RunLocalTests \
    --target-org alias

Deploy with Test Coverage

# Deploy triggers with their test classes
sf project deploy start \
    --source-dir force-app/main/default/triggers \
    --source-dir force-app/main/default/classes \
    --test-level RunSpecifiedTests \
    --tests AccountTriggerTest,ContactTriggerTest \
    --target-org alias

Verify Trigger Order

After deployment, verify trigger execution order if you have multiple triggers on the same object:

# Query trigger execution order (via Debug Logs)
sf apex tail log --target-org alias

# Or check in Setup: Object Manager → [Object] → Triggers

---

Summary

Key Principles

1. Make atomicity decisions explicit - Don't rely on default behavior accidentally 2. Decouple independent processes - Use async for cross-domain operations 3. Test cascade scenarios - Verify both success and failure paths 4. Document trigger chains - Future maintainers need to understand dependencies 5. Validate before deploying - Use --dry-run to catch issues early