sf-agent-framework

# Agent CLI Instructions - Modern SF CLI Usage ## Overview This document provides instructions for all SF-Agent Framework agents to use the modern Salesforce CLI (`sf`) commands. ## Critical Instructions for All Agents ### 1. Command Migration **ALWAYS use `sf` commands, NEVER use deprecated `sfdx` commands** When executing Salesforce CLI commands: - ✅ USE: `sf org login web` - ❌ AVOID: `sfdx force:auth:web:login` - ✅ USE: `sf project deploy start` - ❌ AVOID: `sfdx force:source:deploy` ### 2. Project Configuration **ALWAYS read configuration from `sfdx-project.json`** Before executing any Salesforce commands: ```bash # Check if in a valid Salesforce project if [ ! -f "sfdx-project.json" ]; then echo "Error: Not in a Salesforce DX project directory" echo "Please navigate to a project with sfdx-project.json" exit 1 fi # Read API version dynamically API_VERSION=$(cat sfdx-project.json | grep sourceApiVersion | sed 's/.*"sourceApiVersion": "$.*$".*/\1/') # Read package directory PACKAGE_DIR=$(cat sfdx-project.json | jq -r '.packageDirectories[0].path') ``` ### 3. Reference Documentation When agents need CLI command syntax, reference: - Primary: `/sf-core/data/sf-cli-reference.md` - Utility: `/sf-core/utils/project-config-reader.md` ### 4. Directory Structure **NEVER hardcode directory paths** - ❌ AVOID: Hardcoding `src-core` or `force-app` - ✅ USE: Read from `sfdx-project.json` packageDirectories ### 5. API Version Management **NEVER hardcode API versions** - ❌ AVOID: Hardcoding `59.0` or `63.0` - ✅ USE: Read from `sfdx-project.json` sourceApiVersion - If not found, check latest at: https://developer.salesforce.com/docs/atlas.en-us.api.meta/api/ ### 6. Date Handling **ALWAYS use current system date/time** - ❌ AVOID: Hardcoded dates like `2025-01-11` - ✅ USE: Dynamic dates from system - In JavaScript: `new Date().toISOString()` - In Bash: `date -u +"%Y-%m-%dT%H:%M:%SZ"` ## Agent-Specific Instructions ### For Developer Agents (sf-developer, sf-architect) ```javascript // Before running any SF command const projectConfig = require('./project-config-reader'); const config = new projectConfig.SfdxProjectConfig(); // Use dynamic values const apiVersion = config.getApiVersion(); const packageDir = config.getDefaultPackageDirectory(); // Execute commands with dynamic config `sf project deploy start --source-dir ${packageDir} --api-version ${apiVersion}`; ``` ### For DevOps Agents (sf-devops-lead, sf-release-manager) ```bash # CI/CD Pipeline commands sf org login sfdx-url --sfdx-url-stdin --alias ci-org sf project deploy validate --source-dir $PACKAGE_DIR --test-level RunLocalTests sf project deploy start --source-dir $PACKAGE_DIR --test-level RunLocalTests ``` ### For QA Agents (sf-qa, sf-tester) ```bash # Test execution with new CLI sf apex test run --test-level RunLocalTests --code-coverage --wait 30 sf apex test report --test-run-id <id> --code-coverage ``` ### For Admin Agents (sf-admin, sf-platform-owner) ```bash # User and permission management sf org create user --definition-file config/user-def.json sf org assign permset --name <permset> --target-org <alias> ``` ## Common Patterns ### Pattern 1: Deployment with Validation ```bash # Step 1: Validate VALIDATION_ID=$(sf project deploy validate \ --source-dir $PACKAGE_DIR \ --test-level RunLocalTests \ --target-org prod \ --json | jq -r '.result.id') # Step 2: Quick Deploy sf project deploy quick --job-id $VALIDATION_ID --target-org prod ``` ### Pattern 2: Scratch Org Creation ```bash # Create scratch org with dynamic config sf org create scratch \ --definition-file config/project-scratch-def.json \ --alias dev-org \ --duration-days 7 \ --set-default ``` ### Pattern 3: Data Operations ```bash # Query with dynamic API version sf data query \ --query "SELECT Id, Name FROM Account LIMIT 10" \ --target-org myorg \ --api-version $API_VERSION ``` ## Error Handling All agents should implement proper error handling: ```bash # Function for safe SF command execution execute_sf_command() { local command="$1" local description="$2" echo "Executing: $description" if eval "$command"; then echo "✅ Success: $description" return 0 else echo "❌ Failed: $description" return 1 fi } # Usage execute_sf_command \ "sf project deploy start --source-dir $PACKAGE_DIR" \ "Deploying to org" ``` ## Notification Requirements When agents detect outdated practices, they should: 1. **Notify the user about deprecated commands**: ``` ⚠️ Note: Your project may be using deprecated SFDX commands. The modern SF CLI should be used instead. Reference: /sf-core/data/sf-cli-reference.md ``` 2. **Suggest API version updates**: ``` ℹ️ Your project uses API version X.0 Latest stable version is 63.0 (Winter '25) Consider updating sourceApiVersion in sfdx-project.json ``` 3. **Report missing configuration**: ``` ❌ sfdx-project.json not found This appears to not be a Salesforce DX project. Please ensure you're in the correct directory. ``` ## Integration Points ### When Loading Agent Dependencies Agents should check for CLI reference when loading tasks: ```yaml dependencies: - data/sf-cli-reference.md - utils/project-config-reader.md ``` ### When Executing Tasks Tasks should use the modern CLI: ```markdown ## Execute Deployment \`\`\`bash sf project deploy start \ --source-dir $(cat sfdx-project.json | jq -r '.packageDirectories[0].path') \ --target-org production \`\`\` ``` ## Validation Checklist Before executing any Salesforce operation, agents must verify: - [ ] Using `sf` commands (not `sfdx`) - [ ] Reading from `sfdx-project.json` (not hardcoded) - [ ] Using dynamic API version - [ ] Using dynamic package directories - [ ] Proper error handling implemented - [ ] User notified of any issues ## Updates and Maintenance This instruction set should be: - Referenced by all Salesforce agents - Updated when new SF CLI versions are released - Validated against latest Salesforce documentation - Tested with actual project configurations ## Related Documentation - `/sf-core/data/sf-cli-reference.md` - Complete command reference - `/sf-core/utils/project-config-reader.md` - Configuration reading utilities - Salesforce CLI Documentation: https://developer.salesforce.com/docs/atlas.en-us.sfdx_cli_reference.meta/sfdx_cli_reference/