scc-universal 1.1.0

package/.cursor/skills/sf-deployment/SKILL.md

@@ -0,0 +1,291 @@
+---
+name: sf-deployment
+description: >-
+  Use when deploying to a Salesforce org. SF CLI source deploy, metadata API, package deployment, validation-then-quick-deploy, rollback planning, and production deployment best practices.
+disable-model-invocation: true
+---
+
+# Salesforce Deployment Strategies
+
+Reference: @../_reference/DEPLOYMENT_CHECKLIST.md
+
+## When to Use
+
+- Deploying Apex, LWC, or metadata changes to a sandbox or production org
+- Planning deployment order for metadata with dependencies
+- Setting up validation-then-quick-deploy workflows for zero-downtime production releases
+- Troubleshooting deployment errors, coverage failures, or metadata conflicts
+- Choosing between Change Sets, SF CLI source deploy, or Unlocked Packages
+
+---
+
+## Deployment Method Comparison
+
+| Method            | Speed  | Rollback | Best For                              | Tracking  |
+|-------------------|--------|----------|---------------------------------------|-----------|
+| Change Sets       | Slow   | Manual   | Admin-managed, simple orgs            | None      |
+| SF CLI (Source)   | Fast   | Manual   | Developer workflow, CI/CD             | Git       |
+| Metadata API      | Medium | Manual   | Automated scripts, complex manifests  | External  |
+| Unlocked Package  | Fast   | Version  | Modular orgs, ISV, internal products  | Version   |
+| Managed Package   | Slow   | Version  | AppExchange ISV, protected IP         | Version   |
+
+---
+
+## SF CLI Deploy Commands
+
+### Basic Deployments
+
+```bash
+# Deploy entire source directory
+sf project deploy start \
+    --source-dir force-app \
+    --target-org myOrg \
+    --wait 30
+
+# Deploy specific metadata types
+sf project deploy start \
+    --metadata ApexClass \
+    --target-org myOrg
+
+# Deploy specific components
+sf project deploy start \
+    --metadata "ApexClass:AccountService,ApexClass:AccountServiceTest" \
+    --target-org myOrg
+
+# Deploy using package.xml manifest
+sf project deploy start \
+    --manifest manifest/package.xml \
+    --target-org myOrg \
+    --wait 60
+
+# Deploy with test execution
+sf project deploy start \
+    --source-dir force-app \
+    --test-level RunLocalTests \
+    --target-org myOrg \
+    --wait 60
+
+# Deploy specific tests
+sf project deploy start \
+    --source-dir force-app \
+    --test-level RunSpecifiedTests \
+    --tests AccountServiceTest,OpportunityServiceTest \
+    --target-org myOrg
+```
+
+### Deploy Flags Reference
+
+| Flag                   | Description                                           |
+|------------------------|-------------------------------------------------------|
+| `--source-dir`         | Local source directory to deploy                      |
+| `--manifest`           | package.xml manifest file path                        |
+| `--metadata`           | Specific metadata types or components                 |
+| `--test-level`         | Test level: NoTestRun/RunSpecifiedTests/RunLocalTests/RunAllTestsInOrg |
+| `--tests`              | Comma-separated test class names (with RunSpecifiedTests) |
+| `--wait`               | Minutes to wait for async deploy (default: 33)        |
+| `--ignore-errors`      | Ignore deploy errors (use with caution)               |
+| `--ignore-conflicts`   | Ignore source tracking conflicts                      |
+| `--async`              | Run deploy asynchronously, return job ID              |
+| `--verbose`            | Show detailed output                                  |
+
+> **Note:** There is no `--dry-run` on `deploy start`. Use `sf project deploy validate` instead.
+
+---
+
+## Test Level Guide
+
+### NoTestRun
+
+```bash
+sf project deploy start --test-level NoTestRun --source-dir force-app --target-org sandbox
+```
+
+Use for sandbox deployments of non-Apex metadata. Allowed for production only when the deployment contains no Apex code.
+
+### RunSpecifiedTests
+
+```bash
+sf project deploy start \
+    --test-level RunSpecifiedTests \
+    --tests AccountServiceTest,ContactTriggerTest \
+    --source-dir force-app \
+    --target-org myOrg
+```
+
+Runs only the named test classes. Sufficient for production if coverage >= 75% for deployed classes.
+
+### RunLocalTests (Recommended for most deployments)
+
+```bash
+sf project deploy start \
+    --test-level RunLocalTests \
+    --source-dir force-app \
+    --target-org myOrg
+```
+
+Runs all tests in the org except managed package tests. Required standard for production deployments.
+
+### RunAllTestsInOrg
+
+```bash
+sf project deploy start \
+    --test-level RunAllTestsInOrg \
+    --source-dir force-app \
+    --target-org myOrg
+```
+
+Runs every test including managed package tests. Use for major releases or full org validation.
+
+---
+
+## package.xml (Manifest) Format
+
+### Targeted Component Deployment
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>AccountService</members>
+        <members>AccountServiceTest</members>
+        <name>ApexClass</name>
+    </types>
+    <types>
+        <members>AccountTrigger</members>
+        <name>ApexTrigger</name>
+    </types>
+    <types>
+        <members>accountCard</members>
+        <name>LightningComponentBundle</name>
+    </types>
+    <types>
+        <members>Account.Status__c</members>
+        <name>CustomField</name>
+    </types>
+    <version>66.0</version>
+</Package>
+```
+
+> `<members>*</members>` deploys ALL components of that type, including test classes. For production, prefer listing specific members when you need to exclude certain components.
+
+---
+
+## Validation-Then-Quick-Deploy Workflow
+
+Validation separates test execution from the actual deployment. Use this for production to minimise downtime.
+
+### Step 1: Validate (runs tests, does not deploy)
+
+```bash
+sf project deploy validate \
+    --source-dir force-app \
+    --test-level RunLocalTests \
+    --target-org prod \
+    --wait 60
+
+# Capture the Job ID from output
+JOB_ID=0Af5e00000BnXXX
+```
+
+### Step 2: Wait for Tests to Pass
+
+```bash
+sf project deploy report --job-id $JOB_ID --target-org prod
+sf project deploy resume --job-id $JOB_ID --target-org prod --wait 60
+```
+
+### Step 3: Quick Deploy (no tests re-run)
+
+```bash
+sf project deploy quick \
+    --job-id $JOB_ID \
+    --target-org prod \
+    --wait 10
+```
+
+Quick deploy window: 10 days after successful validation, but only if no Apex code modifications have been made to the org since the validation.
+
+---
+
+## Destructive Changes (Removing Metadata)
+
+Deploy a `destructiveChanges.xml` alongside an empty `package.xml`.
+
+```xml
+<!-- destructiveChanges.xml -->
+<?xml version="1.0" encoding="UTF-8"?>
+<Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    <types>
+        <members>OldAccountService</members>
+        <name>ApexClass</name>
+    </types>
+    <types>
+        <members>Account.LegacyField__c</members>
+        <name>CustomField</name>
+    </types>
+    <version>66.0</version>
+</Package>
+```
+
+```bash
+sf project deploy start \
+    --manifest deploy-package/package.xml \
+    --post-destructive-changes deploy-package/destructiveChanges.xml \
+    --test-level RunLocalTests \
+    --target-org myOrg
+```
+
+`--pre-destructive-changes` runs before deployment; `--post-destructive-changes` after. Use post for removing replaced components.
+
+---
+
+## Rollback Strategies
+
+Salesforce does not have native one-click rollback. Plan ahead.
+
+### Full Commit Revert (Preferred)
+
+```bash
+git revert HEAD
+sf project deploy start --source-dir force-app --test-level RunLocalTests --target-org prod
+```
+
+> Single-file rollback is only safe for isolated, dependency-free components. For coupled changes, revert the full git commit and deploy the complete set of changed files.
+
+### Pre-Deployment Snapshot
+
+```bash
+sf project retrieve start \
+    --manifest manifest/package.xml \
+    --target-org prod \
+    --output-dir backup/pre-deploy-$(date +%Y%m%d)
+```
+
+### Package Version Rollback (Unlocked Packages)
+
+```bash
+sf package install \
+    --package "04t5e000000XXXXX" \
+    --target-org prod \
+    --wait 30
+```
+
+---
+
+## Common Deployment Errors and Fixes
+
+| Error | Cause | Fix |
+|---|---|---|
+| "Test coverage of selected Apex Trigger is 0%" | Trigger has no test class | Write and include a test class |
+| "Average test coverage below 75%" | Org-wide coverage insufficient | Add tests for uncovered classes |
+| "Entity of type X not found" | Component missing in target org | Deploy dependency first or check name |
+| "CANNOT_INSERT_UPDATE_ACTIVATE_ENTITY" | Trigger or validation rule blocking deploy | Check error details for the specific rule |
+| "duplicate value found" | Unique field constraint violation | Check for existing records or duplicate picklist values |
+| "Object X not available in this org" | Feature not enabled in target org | Enable the feature flag or include org setting |
+
+---
+
+## Related
+
+- **Constraints**: `sf-deployment-constraints` -- deployment safety rules
+- **Agent**: `sf-architect` -- interactive, in-depth guidance

package/.cursor/skills/sf-deployment-constraints/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: sf-deployment-constraints
+description: >-
+  Enforce deployment safety — validation-only first, test coverage gates, metadata ordering, rollback readiness. Use when deploying or packaging ANY Salesforce metadata. Do NOT use for local dev or scratch org pushes.
+disable-model-invocation: true
+---
+
+# Salesforce Deployment Constraints
+
+## When to Use
+
+This skill auto-activates when deploying, promoting, or packaging Salesforce metadata. It enforces validation-only-first, test coverage gates, dependency ordering, and rollback readiness for all deployment artifacts.
+
+Hard rules that MUST be followed when deploying, promoting, or packaging
+Salesforce metadata to any sandbox or production org. Violations are blocking.
+
+Reference: @../_reference/DEPLOYMENT_CHECKLIST.md
+@../_reference/DEPRECATIONS.md
+
+---
+
+## Never
+
+1. **Never deploy without validation-only first.**
+   Run `sf project deploy validate` before every real deployment to production.
+   Quick-deploy (`sf project deploy quick --job-id <ID>`) is only valid within
+   10 days and only if no Apex has been deployed to the org since validation.
+
+2. **Never skip the test level flag.**
+   Every `sf project deploy start` to a shared org MUST include `--test-level`.
+   Omitting it lets the platform pick a default that may be `NoTestRun`,
+   which silently passes with zero coverage.
+
+3. **Never deploy Profiles alongside other metadata.**
+   Profiles depend on every other metadata type (objects, fields, record types,
+   Apex, permission sets). Deploy Profiles in a separate, final deployment step
+   after all dependencies are confirmed in the target org.
+
+4. **Never force-push to production.**
+   Do not use `--ignore-errors` or `--ignore-conflicts` against a production
+   org. If the deployment fails, fix the root cause rather than suppressing
+   errors. Force flags are acceptable only in developer sandboxes during
+   active prototyping.
+
+5. **Never deploy destructive changes without a pre-deploy snapshot.**
+   Before any `--post-destructive-changes` or `--pre-destructive-changes`
+   deployment, retrieve the current state of affected components:
+
+   ```bash
+   sf project retrieve start \
+       --manifest manifest/package.xml \
+       --target-org prod \
+       --output-dir backup/pre-deploy-$(date +%Y%m%d)
+   ```
+
+6. **Never use `--use-most-recent` for quick deploy in multi-team orgs.**
+   Another team's deployment between your validate and quick-deploy
+   invalidates the job. Always pass `--job-id` explicitly.
+
+---
+
+## Always
+
+1. **Always validate before deploy.**
+
+   ```bash
+   sf project deploy validate \
+       --source-dir force-app \
+       --test-level RunLocalTests \
+       --target-org <org> \
+       --wait 60
+   ```
+
+   Then quick-deploy using the returned job ID.
+
+2. **Always specify an appropriate test level.**
+
+   | Target Environment | Required Test Level |
+   |---|---|
+   | Developer sandbox (no Apex) | `NoTestRun` acceptable |
+   | Developer sandbox (with Apex) | `RunLocalTests` |
+   | Staging / UAT sandbox | `RunLocalTests` |
+   | Production | `RunLocalTests` (minimum) |
+   | Major release / full regression | `RunAllTestsInOrg` |
+   | CI/CD PR validation (v66.0+) | `RunRelevantTests` with `@testFor` |
+
+3. **Always check metadata dependency order.**
+   Deploy in this sequence; never deploy a later type before its dependency:
+   1. CustomObject
+   2. CustomField
+   3. RecordType
+   4. ValidationRule
+   5. Layout
+   6. ApexClass
+   7. ApexTrigger
+   8. LightningComponentBundle
+   9. FlexiPage / App Page
+   10. PermissionSet
+   11. Profile (always last)
+
+4. **Always have a rollback plan before production deploy.**
+
+   | Strategy | When |
+   |---|---|
+   | `git revert` + full redeploy | Coupled multi-file changes |
+   | Single-file restore from git | Isolated, dependency-free component |
+   | Pre-deploy snapshot retrieve | Any production deployment |
+   | Package version rollback | Unlocked/managed package orgs |
+
+5. **Always confirm 75%+ org-wide code coverage before production.**
+   Run `sf apex run test --test-level RunLocalTests --code-coverage` locally
+   and verify aggregate coverage meets the threshold. Individual deployed
+   triggers must have > 0% coverage.
+
+6. **Always include test classes in the deployment package.**
+   If deploying Apex classes or triggers, include their corresponding test
+   classes in the same `package.xml` or `--source-dir`. Deploying production
+   code without its tests causes coverage drift.
+
+---
+
+## Anti-Pattern Table
+
+| Anti-Pattern | Why It Fails | Correct Approach |
+|---|---|---|
+| Deploy directly to production without validation | Test failures discovered mid-deploy; partial state | Validate first, then quick-deploy |
+| Use `NoTestRun` for production Apex deployments | Salesforce rejects or silently drops coverage | Use `RunLocalTests` or `RunRelevantTests` |
+| Deploy Profiles in the same package as objects/fields | Profile references fail if dependencies missing | Deploy Profiles separately after all dependencies |
+| Use `--ignore-errors` on production | Partial metadata deployed; org left in broken state | Fix errors, re-validate, re-deploy |
+| Skip pre-deploy snapshot for destructive changes | No way to restore deleted metadata | Always `sf project retrieve start` first |
+| Rely on `--use-most-recent` for quick deploy | Another team's deploy invalidates your validation | Use explicit `--job-id` |
+| Deploy test classes separately from production code | Coverage numbers drift; tests may reference stale code | Co-deploy test and production classes together |
+| Omit `--test-level` flag entirely | Platform default may be `NoTestRun` | Always specify `--test-level` explicitly |
+| Deploy dependent metadata out of order | "Entity not found" errors | Follow the 11-step dependency order above |
+| Single-file rollback for coupled changes | Breaks dependencies between related classes | `git revert` the full commit and redeploy all affected files |
+| Deploy Custom Labels after referencing Apex/LWC | Components fail to compile if label not yet in target org | Include Custom Labels in same package or deploy them first |
+| Deploy Report Types without underlying objects | Report Type references fail on missing custom objects/fields | Deploy objects and fields before Report Types |
+| Deploy Connected App with hardcoded consumer secret | Secrets exposed in source control; revoked secrets break auth | Use Named Credentials or environment-specific Connected App config |
+| Deploy Flow without testing in sandbox first | Flows fire on existing data immediately; no rollback for record changes | Always test Record-Triggered Flows in sandbox with representative data |
+| Use `sf project deploy start` without `--wait` | Detached deploy with no feedback; failures discovered late | Always use `--wait` to monitor deployment progress inline |
+
+---
+
+## Quick Reference: Production Deploy Sequence
+
+```
+1. Pre-deploy snapshot   sf project retrieve start --manifest ... --output-dir backup/
+2. Validate              sf project deploy validate --test-level RunLocalTests --wait 60
+3. Confirm tests pass    sf project deploy report --job-id <ID>
+4. Quick deploy          sf project deploy quick --job-id <ID> --wait 10
+5. Smoke test            Execute post-deploy verification plan
+6. Confirm or rollback   If issues found: git revert + redeploy from backup
+```