sf-agent-framework/sf-core/utils/script-generator.md

AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction

# Script Generator Utility - Agent Instructions

## Purpose

This utility provides instructions for AI agents to generate automated scripts
for Salesforce development, deployment, data management, and administrative
tasks, enabling consistent and repeatable processes.

## Agent Instructions

### When to Generate Scripts

Generate script components when:

- Repetitive tasks need automation
- Deployment processes require standardization
- Data migration needs orchestration
- Administrative tasks need scheduling
- Development workflows need optimization
- Testing processes require automation
- Monitoring activities need scripting

### Core Components to Generate

#### 1. Script Template Engine

Generate script templates for:

- Apex anonymous scripts
- SFDX CLI commands
- PowerShell automation
- Bash/Shell scripts
- Python data processing
- JavaScript utilities

Key script categories:

- Deployment scripts
- Data management scripts
- Administrative scripts
- Development utilities
- Testing automation
- Monitoring scripts

#### 2. Dynamic Script Builder

Create generation logic for:

- Parameter-driven scripts
- Environment-specific configurations
- Conditional logic handling
- Error handling and logging
- Progress tracking
- Rollback procedures

#### 3. Script Execution Framework

Implement execution capabilities:

- Scheduled execution
- Event-driven triggers
- Dependency management
- Parallel processing
- Result aggregation
- Notification systems

### Configuration Requirements

#### Script Templates Structure

```yaml
Script_Template__c:
  - Name (Text)
  - Script_Type__c (Picklist)
  - Template_Body__c (Long Text Area)
  - Parameters__c (Long Text Area)
  - Description__c (Text Area)
  - Category__c (Picklist)
  - Language__c (Picklist)
  - Execution_Environment__c (Picklist)
  - Author__c (Lookup - User)
  - Version__c (Text)

Script_Execution__c:
  - Script_Template__c (Master-Detail)
  - Execution_Time__c (DateTime)
  - Status__c (Picklist)
  - Parameters_Used__c (Long Text Area)
  - Output_Log__c (Long Text Area)
  - Error_Details__c (Text Area)
  - Duration_ms__c (Number)
  - Executed_By__c (Lookup - User)
```

### Script Types to Generate

#### Deployment Scripts

```
1. Metadata deployment scripts
2. Data deployment scripts
3. Pre/post deployment hooks
4. Environment provisioning
5. Configuration setup
6. Permission assignments
```

#### Data Management Scripts

```
1. Data migration scripts
2. Data cleansing routines
3. Bulk data operations
4. Data archival scripts
5. ETL processes
6. Data validation checks
```

#### Administrative Scripts

```
1. User management
2. Permission set assignments
3. Org maintenance
4. License management
5. Security audits
6. Cleanup routines
```

#### Development Scripts

```
1. Code generation
2. Test data creation
3. Environment setup
4. Build automation
5. Quality checks
6. Documentation generation
```

### Implementation Patterns

#### Template-Based Generation Pattern

1. Define script templates
2. Identify parameters
3. Implement substitution logic
4. Validate generated scripts
5. Execute with parameters
6. Capture results

#### Modular Script Pattern

1. Create reusable modules
2. Define interfaces
3. Implement composition logic
4. Handle dependencies
5. Enable customization
6. Maintain versions

#### Pipeline Script Pattern

1. Define pipeline stages
2. Implement stage scripts
3. Handle stage transitions
4. Manage data flow
5. Track progress
6. Handle failures

### Script Generation Instructions

#### Apex Anonymous Scripts

Generate scripts for:

- Data manipulation
- Administrative tasks
- Debugging operations
- Testing scenarios
- One-time operations
- System maintenance

#### SFDX CLI Scripts

Create command sequences for:

- Org authentication
- Metadata operations
- Data import/export
- Package management
- Scratch org operations
- Source synchronization

#### PowerShell Scripts

Develop automation for:

- Windows environments
- Active Directory integration
- File system operations
- Service management
- Report generation
- Monitoring tasks

#### Python Scripts

Build solutions for:

- Data processing
- API integrations
- File manipulations
- Report generation
- Analytics operations
- Machine learning tasks

### Best Practices to Implement

1. **Script Design**
   - Modular architecture
   - Clear parameters
   - Comprehensive logging
   - Error handling
   - Progress indicators

2. **Security Considerations**
   - Credential management
   - Access control
   - Audit logging
   - Secure communications
   - Data protection

3. **Performance Optimization**
   - Efficient algorithms
   - Parallel processing
   - Resource management
   - Caching strategies
   - Bulk operations

4. **Maintainability**
   - Clear documentation
   - Version control
   - Testing procedures
   - Change management
   - Regular updates

### Advanced Features to Consider

1. **Dynamic Code Generation**
   - Template engines
   - Parameter substitution
   - Conditional logic
   - Loop constructs
   - Variable scoping

2. **Script Orchestration**
   - Workflow management
   - Dependency resolution
   - Parallel execution
   - State management
   - Error recovery

3. **Integration Capabilities**
   - API connections
   - Database access
   - File system operations
   - External tools
   - Cloud services

### Error Handling Instructions

#### Exception Management

Handle these scenarios:

1. Authentication failures
2. Permission errors
3. Data validation issues
4. Network connectivity
5. Resource limitations

#### Recovery Strategies

Implement recovery for:

- Partial failures
- Timeout conditions
- Data inconsistencies
- Resource exhaustion
- External dependencies

#### Logging Requirements

Generate comprehensive logs for:

- Execution tracking
- Error diagnostics
- Performance metrics
- Audit trails
- Debugging information

### Script Categories

#### System Administration

- User provisioning scripts
- Permission management
- Org configuration
- Security compliance
- License management
- Backup procedures

#### Data Operations

- Migration scripts
- Transformation routines
- Validation checks
- Cleanup operations
- Archive procedures
- Quality assessments

#### Development Support

- Environment setup
- Test data creation
- Code generation
- Build automation
- Deployment scripts
- Documentation tools

#### Monitoring and Maintenance

- Health checks
- Performance monitoring
- Alert generation
- Maintenance tasks
- Report automation
- Cleanup routines

### Testing Requirements

Generate test strategies for:

1. Script functionality validation
2. Parameter testing
3. Error condition handling
4. Performance benchmarking
5. Integration testing

#### Test Scenarios

- Happy path execution
- Error conditions
- Edge cases
- Performance limits
- Security boundaries
- Integration points

### Documentation Standards

#### Script Documentation

Include in generated scripts:

- Purpose and description
- Parameter definitions
- Usage examples
- Error codes
- Dependencies
- Version history

#### User Guides

Generate guides covering:

- Installation procedures
- Configuration steps
- Usage instructions
- Troubleshooting
- Best practices
- FAQ sections

### Success Metrics

Track and measure:

- Script execution success rate
- Performance improvements
- Error reduction
- Time savings
- User adoption
- Maintenance efficiency

### Deployment Considerations

#### Environment Management

- Development environments
- Testing environments
- Staging environments
- Production environments
- Disaster recovery
- Version control

#### Change Control

- Script versioning
- Approval processes
- Testing requirements
- Rollback procedures
- Documentation updates
- Communication plans