/platform-metadata-deploy

name: platform-metadata-deploy
description: "Salesforce DevOps automation using sf CLI v2. TRIGGER when: user deploys metadata, creates/manages scratch orgs or sandboxes, sets up CI/CD pipelines, or troubleshoots deployment errors with sf project deploy. DO NOT TRIGGER when: writing Apex code (use platform-apex-generate), building LWC components (use experience-lwc-generate), creating metadata definitions (use platform-custom-object-generate or platform-custom-field-generate), or querying org data (use platform-data-manage)."
metadata:
  version: "1.1"
  relatedSkills:
    - "agentforce-generate"
    - "agentforce-test"
    - "automation-flow-generate"
    - "experience-lwc-generate"
    - "integration-connectivity-connected-app-configure"
    - "integration-connectivity-generate"
    - "platform-apex-generate"
    - "platform-apex-test-run"
    - "platform-custom-field-generate"
    - "platform-custom-object-generate"
    - "platform-data-manage"
  cliTools:
    - tool: ["curl"]
      semver: ">=7.0.0"
    - tool: ["git"]
      semver: ">=2.0.0"
    - tool: ["jq"]
      semver: ">=1.7.0"
    - tool: ["sf"]
      semver: ">=2.0.0"

platform-metadata-deploy: 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 `platform-metadata-deploy` 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 → [platform-apex-generate](../platform-apex-generate/SKILL.md)
• authoring LWC components → [experience-lwc-generate](../experience-lwc-generate/SKILL.md)
• creating custom objects or fields → [platform-custom-object-generate](../platform-custom-object-generate/SKILL.md), [platform-custom-field-generate](../platform-custom-field-generate/SKILL.md)
• building Flows → [automation-flow-generate](../automation-flow-generate/SKILL.md)
• doing org data operations → [platform-data-manage](../platform-data-manage/SKILL.md)
• authoring or testing Agentforce agents → [agentforce-generate](../agentforce-generate/SKILL.md)

---

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 **`platform-data-manage`** after metadata is validated or deployed.

Default deployment order

| Phase | Metadata | |---|---| | 1 | Custom objects / fields | | 2 | Permission sets | | 3 | Apex | | 4 | Flows as Draft | | 5 | Flow activation / post-verify |

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 [platform-data-manage](../platform-data-manage/SKILL.md) 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](references/deployment-report-template.md)

---

High-Signal Failure Patterns

| Error / symptom | Likely cause | Default fix direction | |---|---|---| | `FIELD_CUSTOM_VALIDATION_EXCEPTION` | validation rule or bad test data | adjust data or rule timing | | `INVALID_CROSS_REFERENCE_KEY` | missing dependency | include referenced metadata first | | `CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY` | trigger / Flow / validation side effect | inspect automation stack and failing logic | | tests fail during deploy | broken code or fragile tests | run targeted tests, fix root cause, revalidate | | field/object not found in permset | wrong order | deploy objects/fields before permission sets | | Flow invalid / v