@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/deploying-metadata/README.md

@@ -0,0 +1,104 @@
+# 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
+
+| Operation | Example Request |
+|-----------|-----------------|
+| Deploy | "Deploy force-app to org dev" |
+| Validate | "Dry-run deploy to check for errors" |
+| Quick deploy | "Quick deploy validated changes" |
+| Cancel | "Cancel the current deployment" |
+| Status | "Check deployment status" |
+
+## Key Commands
+
+```bash
+# 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
+
+| Rule | Details |
+|------|---------|
+| Always `--dry-run` first | Validate before actual deployment |
+| Deploy order matters | Objects → Permissions → Code |
+| Test levels | Use `RunLocalTests` for production |
+| Flow activation | Deploy as Draft, activate manually |
+| Post-deploy data | Hand off to `handling-sf-data` rather than mixing raw data creation into deploy logic |
+
+## Cross-Skill Integration
+
+| Related Skill | When to Use |
+|---------------|-------------|
+| generating-custom-object / generating-custom-field | Create objects/fields BEFORE deploy |
+| running-apex-tests | Run tests AFTER deployment |
+| handling-sf-data | Create describe-validated test data AFTER deployment |
+
+## Documentation
+
+- [SKILL.md](SKILL.md) - Full workflow and orchestration guidance
+- [references/orchestration.md](references/orchestration.md) - Deployment sequencing
+- [references/deployment-workflows.md](references/deployment-workflows.md) - CI/CD and workflow examples
+- [references/deploy.sh](references/deploy.sh) - Sample deployment script
+
+## Requirements
+
+- sf CLI v2
+- Target Salesforce org
+- Proper permissions for deployment

package/skills/deploying-metadata/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: deploying-metadata
+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 generating-apex), building LWC components (use generating-lwc-components), creating metadata definitions (use generating-custom-object or generating-custom-field), or querying org data (use handling-sf-data)."
+license: MIT
+metadata:
+  version: "1.1"
+---
+
+# 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](../generating-apex/SKILL.md)
+- authoring LWC components → [generating-lwc-components](../generating-lwc-components/SKILL.md)
+- creating custom objects or fields → [generating-custom-object](../generating-custom-object/SKILL.md), [generating-custom-field](../generating-custom-field/SKILL.md)
+- building Flows → [generating-flow](../generating-flow/SKILL.md)
+- doing org data operations → [handling-sf-data](../handling-sf-data/SKILL.md)
+- authoring or testing Agentforce agents → [developing-agentforce](../developing-agentforce/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 **`handling-sf-data`** 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:
+```bash
+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
+```bash
+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](../handling-sf-data/SKILL.md)
+4. run tests / smoke checks
+5. orchestrate multiple post-deploy steps in order
+
+### 4. Deploy the smallest correct scope
+```bash
+# 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
+```bash
+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 / version conflict | dependency or activation problem | deploy as Draft, verify, then activate |
+
+Full workflows: [references/orchestration.md](references/orchestration.md), [references/trigger-deployment-safety.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](../generating-apex/SKILL.md) for authoring guidance.
+
+Static analysis now uses **Code Analyzer v5** (`sf code-analyzer`), not retired `sf scanner`.
+
+Deep reference: [references/deployment-workflows.md](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](../developing-agentforce/SKILL.md) 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](references/agent-deployment-guide.md)
+
+---
+
+## Cross-Skill Integration
+
+| Need | Delegate to | Reason |
+|---|---|---|
+| custom object creation | [generating-custom-object](../generating-custom-object/SKILL.md) | define objects before deploy |
+| custom field creation | [generating-custom-field](../generating-custom-field/SKILL.md) | define fields before deploy |
+| Apex authoring / fixes | [generating-apex](../generating-apex/SKILL.md) | code authoring and repair |
+| Flow creation / repair | [generating-flow](../generating-flow/SKILL.md) | Flow authoring and activation guidance |
+| test data or seed records | [handling-sf-data](../handling-sf-data/SKILL.md) | describe-first data setup and cleanup |
+| Agent authoring and publish readiness | [developing-agentforce](../developing-agentforce/SKILL.md) | agent-specific correctness |
+
+---
+
+## Reference Map
+
+### Start here
+- [references/orchestration.md](references/orchestration.md)
+- [references/deployment-workflows.md](references/deployment-workflows.md)
+- [references/deployment-report-template.md](references/deployment-report-template.md)
+
+### Specialized deployment safety
+- [references/trigger-deployment-safety.md](references/trigger-deployment-safety.md)
+- [references/agent-deployment-guide.md](references/agent-deployment-guide.md)
+- [references/deploy.sh](references/deploy.sh)
+
+### Asset templates
+- [assets/package.xml](assets/package.xml) — manifest template covering common metadata types
+- [assets/destructiveChanges.xml](assets/destructiveChanges.xml) — template for removing metadata from target orgs
+
+---
+
+## Score Guide
+
+| Score | Meaning |
+|---|---|
+| 90+ | strong deployment plan and execution guidance |
+| 75–89 | good deploy guidance with minor review items |
+| 60–74 | partial coverage of deployment risk |
+| < 60 | insufficient confidence; tighten plan before rollout |
+
+---
+
+## Completion Format
+
+```text
+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>
+```

package/skills/deploying-metadata/assets/destructiveChanges.xml

@@ -0,0 +1,143 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!--
+    Destructive Changes Template
+
+    Use this file to specify metadata components to delete from the target org.
+    This file should be used with --pre-destructive-changes or --post-destructive-changes
+
+    Example:
+    sf project deploy start \
+      --manifest manifest/package.xml \
+      --post-destructive-changes manifest/destructiveChanges.xml \
+      --target-org production
+    -->
+
+    <!-- Delete Apex Classes -->
+    <!--
+    <types>
+        <members>DeprecatedClass1</members>
+        <members>DeprecatedClass2</members>
+        <name>ApexClass</name>
+    </types>
+    -->
+
+    <!-- Delete Apex Triggers -->
+    <!--
+    <types>
+        <members>OldTrigger</members>
+        <name>ApexTrigger</name>
+    </types>
+    -->
+
+    <!-- Delete Custom Objects -->
+    <!--
+    <types>
+        <members>ObsoleteObject__c</members>
+        <name>CustomObject</name>
+    </types>
+    -->
+
+    <!-- Delete Custom Fields -->
+    <!--
+    <types>
+        <members>Account.DeprecatedField__c</members>
+        <members>Contact.OldField__c</members>
+        <name>CustomField</name>
+    </types>
+    -->
+
+    <!-- Delete Lightning Components -->
+    <!--
+    <types>
+        <members>oldComponent</members>
+        <name>LightningComponentBundle</name>
+    </types>
+    -->
+
+    <!-- Delete Aura Components -->
+    <!--
+    <types>
+        <members>deprecatedAuraComponent</members>
+        <name>AuraDefinitionBundle</name>
+    </types>
+    -->
+
+    <!-- Delete Validation Rules -->
+    <!--
+    <types>
+        <members>Account.OldValidationRule</members>
+        <name>ValidationRule</name>
+    </types>
+    -->
+
+    <!-- Delete Workflow Rules -->
+    <!--
+    <types>
+        <members>Account.OldWorkflowRule</members>
+        <name>WorkflowRule</name>
+    </types>
+    -->
+
+    <!-- Delete Flows -->
+    <!--
+    <types>
+        <members>Deprecated_Flow</members>
+        <name>Flow</name>
+    </types>
+    -->
+
+    <!-- Delete Permission Sets -->
+    <!--
+    <types>
+        <members>ObsoletePermissionSet</members>
+        <name>PermissionSet</name>
+    </types>
+    -->
+
+    <!-- Delete Static Resources -->
+    <!--
+    <types>
+        <members>oldStaticResource</members>
+        <name>StaticResource</name>
+    </types>
+    -->
+
+    <!-- API Version -->
+    <version>66.0</version>
+</Package>
+
+<!--
+IMPORTANT NOTES:
+
+1. Order of operations:
+   - Pre-destructive: Deleted BEFORE deployment (--pre-destructive-changes)
+   - Post-destructive: Deleted AFTER deployment (--post-destructive-changes)
+
+2. Best practices:
+   - Test destructive changes in sandbox first
+   - Backup metadata before deletion
+   - Use --dry-run to validate before actual deployment
+   - Delete fields before objects
+   - Be careful with dependencies
+
+3. Common destructive change scenarios:
+   - Removing deprecated features
+   - Cleaning up unused metadata
+   - Refactoring object structures
+   - Removing test/demo data objects
+
+4. Example usage:
+   sf project deploy start \
+     --manifest manifest/package.xml \
+     --post-destructive-changes manifest/destructiveChanges.xml \
+     --target-org sandbox \
+     --dry-run \
+     --test-level RunLocalTests \
+     --wait 30
+
+5. Rollback:
+   - Keep backup of deleted metadata in version control
+   - Tag the commit before destructive deployment
+   - Can redeploy from backup if needed
+-->

package/skills/deploying-metadata/assets/package.xml

@@ -0,0 +1,121 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <!-- Apex Classes -->
+    <types>
+        <members>*</members>
+        <name>ApexClass</name>
+    </types>
+
+    <!-- Apex Triggers -->
+    <types>
+        <members>*</members>
+        <name>ApexTrigger</name>
+    </types>
+
+    <!-- Aura Components -->
+    <types>
+        <members>*</members>
+        <name>AuraDefinitionBundle</name>
+    </types>
+
+    <!-- Lightning Web Components -->
+    <types>
+        <members>*</members>
+        <name>LightningComponentBundle</name>
+    </types>
+
+    <!-- Custom Objects -->
+    <types>
+        <members>Account</members>
+        <members>Contact</members>
+        <members>Opportunity</members>
+        <!-- <members>CustomObject__c</members> -->
+        <name>CustomObject</name>
+    </types>
+
+    <!-- Custom Fields (if needed) -->
+    <!--
+    <types>
+        <members>Account.CustomField__c</members>
+        <name>CustomField</name>
+    </types>
+    -->
+
+    <!-- Layouts -->
+    <types>
+        <members>*</members>
+        <name>Layout</name>
+    </types>
+
+    <!-- Profiles (be careful with profiles) -->
+    <!--
+    <types>
+        <members>Admin</members>
+        <members>Standard User</members>
+        <name>Profile</name>
+    </types>
+    -->
+
+    <!-- Permission Sets -->
+    <types>
+        <members>*</members>
+        <name>PermissionSet</name>
+    </types>
+
+    <!-- Flows -->
+    <types>
+        <members>*</members>
+        <name>Flow</name>
+    </types>
+
+    <!-- Validation Rules -->
+    <types>
+        <members>*</members>
+        <name>ValidationRule</name>
+    </types>
+
+    <!-- Workflow Rules -->
+    <types>
+        <members>*</members>
+        <name>WorkflowRule</name>
+    </types>
+
+    <!-- Static Resources -->
+    <types>
+        <members>*</members>
+        <name>StaticResource</name>
+    </types>
+
+    <!-- Email Templates -->
+    <types>
+        <members>*</members>
+        <name>EmailTemplate</name>
+    </types>
+
+    <!-- Reports -->
+    <types>
+        <members>*</members>
+        <name>Report</name>
+    </types>
+
+    <!-- Dashboards -->
+    <types>
+        <members>*</members>
+        <name>Dashboard</name>
+    </types>
+
+    <!-- Custom Tabs -->
+    <types>
+        <members>*</members>
+        <name>CustomTab</name>
+    </types>
+
+    <!-- Applications -->
+    <types>
+        <members>*</members>
+        <name>CustomApplication</name>
+    </types>
+
+    <!-- API Version -->
+    <version>66.0</version>
+</Package>