@salesforce/afv-skills 1.8.0 → 1.9.0

package/skills/deploying-metadata/references/deployment-report-template.md

@@ -0,0 +1,89 @@
+<!-- Parent: deploying-metadata/SKILL.md -->
+# Deployment Report Template
+
+Standard output format for Salesforce deployment summaries.
+
+## Full Report Format
+
+```markdown
+## 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:
+
+```markdown
+✓ Deployment: [org-alias] | Job: [job-id]
+  Components: X/X | Tests: Y/Y (Z% coverage)
+  Status: Succeeded
+```
+
+## Failure Report Format
+
+```markdown
+## 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):
+
+```yaml
+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: []
+```

package/skills/deploying-metadata/references/deployment-workflows.md

@@ -0,0 +1,395 @@
+<!-- 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**
+   ```bash
+   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)
+   ```bash
+   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**
+   ```bash
+   # Find all LWC components
+   ls -R force-app/main/default/lwc/
+   ```
+
+2. **Deploy specific directory**
+   ```bash
+   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**
+   ```bash
+   cat force-app/main/default/classes/AccountController.cls
+   ```
+
+2. **Run targeted tests**
+   ```bash
+   sf apex run test \
+     --tests AccountControllerTest \
+     --target-org production \
+     --wait 5
+   ```
+
+3. **Deploy single class**
+   ```bash
+   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**
+   ```bash
+   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**
+   ```bash
+   cat manifest/package-v2.3.xml
+   ```
+
+2. **Validate deployment**
+   ```bash
+   sf project deploy start \
+     --manifest manifest/package-v2.3.xml \
+     --target-org production \
+     --dry-run \
+     --test-level RunLocalTests \
+     --wait 30
+   ```
+
+3. **Quick deploy**
+   ```bash
+   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**
+   ```bash
+   sf org create scratch \
+     --definition-file config/project-scratch-def.json \
+     --alias feature-branch-123 \
+     --duration-days 7 \
+     --set-default
+   ```
+
+2. **Push source**
+   ```bash
+   sf project deploy start --target-org feature-branch-123
+   ```
+
+3. **Assign permission sets**
+   ```bash
+   sf org assign permset --name AdminPermSet --target-org feature-branch-123
+   ```
+
+4. **Import test data**
+   ```bash
+   sf data import tree --plan data/sample-data-plan.json --target-org feature-branch-123
+   ```
+
+5. **Open org**
+   ```bash
+   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)
+   ```bash
+   sf project retrieve start \
+     --manifest manifest/package-production.xml \
+     --target-org production
+   ```
+
+2. **Check out previous version from git**
+   ```bash
+   git checkout v2.2-stable
+   ```
+
+3. **Deploy previous version**
+   ```bash
+   sf project deploy start \
+     --manifest manifest/package-v2.2.xml \
+     --target-org production \
+     --test-level RunLocalTests \
+     --wait 30
+   ```
+
+4. **Verify rollback**
+   ```bash
+   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
+   <?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**
+   ```bash
+   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**
+   ```bash
+   sf project deploy start --target-org dev --test-level NoTestRun --wait 10
+   ```
+
+2. **Deploy to Staging**
+   ```bash
+   sf project deploy start --target-org staging --test-level RunLocalTests --wait 20
+   ```
+
+3. **Validate Production**
+   ```bash
+   sf project deploy start --target-org production --dry-run --test-level RunLocalTests --wait 30
+   ```
+
+4. **Deploy to Production** (after manual approval)
+   ```bash
+   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**
+   ```bash
+   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**
+   ```bash
+   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**
+   ```bash
+   # 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.*

package/skills/deploying-metadata/references/orchestration.md

@@ -0,0 +1,183 @@
+<!-- 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:
+
+| Before deploying-metadata | After deploying-metadata |
+|------------------|-----------------|
+| Metadata exists locally | Metadata exists in org |
+| Flows reference objects | Flows can run |
+| Data can't be created | handling-sf-data can create records |
+
+**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
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| `Invalid reference: Quote__c` | Object not deployed | Deploy objects first |
+| `Field does not exist: Status__c` | Field not deployed | Deploy fields first |
+| `no CustomObject named X found` | Permission Set deployed before object | Deploy objects, then Permission Sets |
+| `SObject type 'X' not supported` | handling-sf-data ran before deploy | Deploy before creating data |
+| `Flow is invalid` | Flow references missing object | Deploy objects before flows |
+| `Flow not found` | Agent references undeploy flow | Deploy flows before agent publish |
+
+---
+
+## Two-Step Deployment Pattern (Recommended)
+
+Always validate before deploying:
+
+```bash
+# 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:
+
+| Dependency | Check Command | Required For |
+|------------|---------------|--------------|
+| TAF Package | `sf package installed list` | TAF trigger pattern |
+| Custom Objects | `sf sobject describe` | Apex/Flow field refs |
+| Permission Sets | `sf org list metadata --metadata-type PermissionSet` | FLS for fields |
+| Flows | `sf org list metadata --metadata-type Flow` | Agent actions |
+
+---
+
+## developing-agentforce Integration
+
+For agent deployments, use the specialized commands:
+
+```bash
+# 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
+
+| From Skill | To deploying-metadata | When |
+|------------|--------------|------|
+| generating-custom-object | → deploying-metadata | "Deploy objects to [org]" |
+| generating-flow | → deploying-metadata | "Deploy flow with --dry-run" |
+| generating-apex | → deploying-metadata | "Deploy classes with RunLocalTests" |
+| developing-agentforce | → deploying-metadata | "Deploy and publish agent" |
+
+---
+
+## Related Documentation
+
+| Topic | Location |
+|-------|----------|
+| Deployment workflows | `deploying-metadata/references/deployment-workflows.md` |
+| Agent deployment guide | `deploying-metadata/references/agent-deployment-guide.md` |
+| Deploy script template | `deploying-metadata/references/deploy.sh` |