@salesforce/afv-skills 1.22.0 → 1.24.0

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

@@ -1,89 +0,0 @@
-<!-- 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

@@ -1,395 +0,0 @@
-<!-- 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

@@ -1,183 +0,0 @@
-<!-- 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` |