sf-agent-framework/docs/06-configuration/README.md

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

# Configuration Guide

## Overview

The SF-Agent Framework uses a hierarchical configuration system that allows customization at multiple levels: global, project, and runtime. This guide covers all configuration options and best practices.

## Configuration Hierarchy

Configuration is loaded in this order (later overrides earlier):

1. **Default Configuration** - Built-in defaults
2. **Global Configuration** - User-level settings
3. **Project Configuration** - Project-specific settings
4. **Environment Variables** - Runtime overrides
5. **Command-line Arguments** - Immediate overrides

```
┌─────────────────────────┐
│  Command-line Args      │ ← Highest Priority
├─────────────────────────┤
│  Environment Variables  │
├─────────────────────────┤
│  Project Configuration  │
├─────────────────────────┤
│  Global Configuration   │
├─────────────────────────┤
│  Default Configuration  │ ← Lowest Priority
└─────────────────────────┘
```

## Configuration Files

### Project Configuration

**Location**: `.sf-agent/config.yaml`

```yaml
# .sf-agent/config.yaml
# Project-specific configuration

project:
  name: 'my-salesforce-project'
  type: 'brownfield' # greenfield | brownfield | package
  version: '1.0.0'
  description: 'Customer portal implementation'

organization:
  alias: 'myorg'
  type: 'sandbox' # production | sandbox | scratch | developer
  api_version: '59.0'
  namespace: 'myapp'
  my_domain: 'company-dev-ed.my.salesforce.com'

framework:
  version: '4.0.0'
  auto_update: true
  check_updates: 'weekly' # daily | weekly | monthly | never

phases:
  planning:
    enabled: true
    context_limit: 128000
    default_agents:
      - sf-architect
      - sf-business-analyst
      - sf-data-architect

  development:
    enabled: true
    context_limit: 32000
    default_agents:
      - sf-developer
      - sf-admin
      - sf-qa

ide:
  primary: 'cursor' # cursor | claude-code | vscode | idea
  additional:
    - 'vscode'
    - 'windsurf'

  integration:
    auto_complete: true
    show_hints: true
    context_awareness: true

agents:
  parallel_execution: 4
  timeout: 300 # seconds
  retry_attempts: 3

  preferences:
    sf-developer:
      language_style: 'functional'
      test_coverage: 85
      naming_convention: 'camelCase'

    sf-architect:
      detail_level: 'comprehensive'
      include_diagrams: true

workflows:
  interactive: true
  auto_save: true
  validation_gates: true

  defaults:
    planning_workflow: 'comprehensive-planning'
    development_workflow: 'agile-development'
    deployment_workflow: 'staged-deployment'

templates:
  custom_path: './templates'
  override_defaults: false

  variables:
    company_name: 'Acme Corp'
    default_author: 'Development Team'
    copyright_year: '2025'

storage:
  artifacts:
    location: './artifacts'
    retention_days: 90
    compression: true

  documents:
    location: './docs'
    format: 'markdown'
    auto_index: true

  cache:
    enabled: true
    location: './.sf-agent/cache'
    ttl: 3600 # seconds
    max_size: '1GB'

integration:
  git:
    enabled: true
    auto_commit: false
    commit_message_format: 'conventional' # conventional | simple | custom
    branch_strategy: 'feature' # feature | gitflow | trunk

    hooks:
      pre_commit: true
      commit_msg: true
      pre_push: false

  salesforce:
    api_retry: 3
    api_timeout: 120
    bulk_api: true
    metadata_api: true
    tooling_api: true

    deployment:
      check_only: false
      run_tests: 'LocalTests' # NoTestRun | RunSpecifiedTests | RunLocalTests | RunAllTestsInOrg
      rollback_on_error: true

  mcp:
    enabled: true
    servers:
      - name: 'salesforce-mcp'
        path: './sf-core/mcp/servers/salesforce-mcp-server.js'
      - name: 'git-mcp'
        path: './sf-core/mcp/servers/git-mcp-server.js'

security:
  encryption:
    enabled: true
    algorithm: 'aes-256-gcm'
    key_storage: 'keychain' # keychain | file | environment

  credentials:
    storage: 'secure' # secure | environment | file
    rotation_days: 90

  audit:
    enabled: true
    log_level: 'info' # debug | info | warn | error
    retention_days: 365

  compliance:
    frameworks: ['soc2', 'gdpr']
    pii_detection: true
    data_classification: true

performance:
  parallel_agents: 4
  batch_size: 100

  optimization:
    context_compression: true
    lazy_loading: true
    predictive_caching: true

  monitoring:
    enabled: true
    metrics_collection: true
    performance_tracking: true

logging:
  level: 'info' # debug | info | warn | error
  format: 'json' # json | text | pretty

  outputs:
    console: true
    file: true
    file_path: './.sf-agent/logs/sf-agent.log'

  rotation:
    enabled: true
    max_size: '10MB'
    max_files: 5

notifications:
  enabled: true

  channels:
    slack:
      enabled: false
      webhook_url: '${SLACK_WEBHOOK_URL}'
      mentions:
        errors: '@channel'
        success: '@here'

    email:
      enabled: false
      smtp_host: '${SMTP_HOST}'
      from: 'sf-agent@company.com'
      to: ['team@company.com']

  events:
    workflow_complete: true
    deployment_status: true
    validation_errors: true
    security_alerts: true

experimental:
  features:
    ai_review: false
    auto_refactor: false
    predictive_planning: false

  beta:
    graphql_api: false
    websocket_support: false
    distributed_execution: false
```

### Global Configuration

**Location**: `~/.sf-agent/config.yaml`

```yaml
# ~/.sf-agent/config.yaml
# User-level global configuration

user:
  name: 'John Developer'
  email: 'john@example.com'
  default_org: 'myorg'

preferences:
  theme: 'dark' # light | dark | auto
  editor: 'vim' # vim | emacs | nano

  output:
    color: true
    emoji: false
    verbose: false

  interaction:
    confirm_destructive: true
    auto_accept: false
    default_yes: false

defaults:
  project_type: 'brownfield'
  phase: 'development'
  ide: 'cursor'

  context_limits:
    planning: 128000
    development: 32000

credentials:
  github_token: '${GITHUB_TOKEN}'
  npm_token: '${NPM_TOKEN}'

telemetry:
  enabled: true
  anonymous: true
```

## Environment Variables

All configuration options can be overridden using environment variables:

```bash
# Framework Settings
export SF_AGENT_CONFIG=/custom/path/config.yaml
export SF_AGENT_PHASE=development
export SF_AGENT_DEBUG=true
export SF_AGENT_VERBOSE=true

# Salesforce Settings
export SF_AGENT_ORG=myorg
export SF_AGENT_API_VERSION=59.0
export SF_AGENT_NAMESPACE=myapp

# Context Settings
export SF_AGENT_CONTEXT_LIMIT=32000
export SF_AGENT_CONTEXT_COMPRESSION=true

# Performance Settings
export SF_AGENT_PARALLEL=4
export SF_AGENT_TIMEOUT=300
export SF_AGENT_RETRY=3

# Security Settings
export SF_AGENT_ENCRYPTION=true
export SF_AGENT_AUDIT=true

# Integration Settings
export SF_AGENT_GIT_AUTO_COMMIT=false
export SF_AGENT_MCP_ENABLED=true

# Logging Settings
export SF_AGENT_LOG_LEVEL=debug
export SF_AGENT_LOG_FORMAT=json
```

## Command-Line Configuration

### Setting Configuration Values

```bash
# Set a single value
sf-agent config set organization.alias myorg

# Set nested values
sf-agent config set phases.development.context_limit 32000

# Set with validation
sf-agent config set --validate organization.api_version 59.0

# Set globally (user-level)
sf-agent config set --global user.email john@example.com

# Set for current session only
sf-agent config set --session-only performance.parallel_agents 8
```

### Getting Configuration Values

```bash
# Get a single value
sf-agent config get organization.alias

# Get all values
sf-agent config list

# Get with defaults shown
sf-agent config list --show-defaults

# Get effective configuration (merged)
sf-agent config list --effective

# Export configuration
sf-agent config export > config-backup.yaml
```

### Managing Configuration

```bash
# Validate configuration
sf-agent config validate

# Reset to defaults
sf-agent config reset

# Reset specific section
sf-agent config reset organization

# Import configuration
sf-agent config import config-backup.yaml

# Edit configuration interactively
sf-agent config edit
```

## Configuration Profiles

Create different configuration profiles for different scenarios:

### Creating Profiles

```bash
# Create a new profile
sf-agent config profile create production

# Copy existing profile
sf-agent config profile copy development staging

# Set profile-specific values
sf-agent config set --profile production organization.type production
sf-agent config set --profile production security.audit.enabled true
```

### Using Profiles

```bash
# Switch profile
sf-agent config profile use production

# Run command with specific profile
sf-agent --profile staging workflow deploy

# List profiles
sf-agent config profile list

# Delete profile
sf-agent config profile delete old-profile
```

### Profile Examples

**Development Profile**

```yaml
# .sf-agent/profiles/development.yaml
profile: development
organization:
  type: scratch
  alias: dev-scratch
phases:
  default: development
logging:
  level: debug
security:
  audit:
    enabled: false
```

**Production Profile**

```yaml
# .sf-agent/profiles/production.yaml
profile: production
organization:
  type: production
  alias: prod-org
phases:
  default: planning
security:
  audit:
    enabled: true
  encryption:
    enabled: true
workflows:
  validation_gates: true
```

## Advanced Configuration

### Dynamic Configuration

Use JavaScript for dynamic configuration:

```javascript
// .sf-agent/config.js
module.exports = {
  project: {
    name: process.env.PROJECT_NAME || 'default-project',
    version: require('./package.json').version,
  },

  organization: {
    alias: process.env.SF_ORG || 'myorg',
    api_version: getCurrentApiVersion(),
  },

  // Conditional configuration
  ...(process.env.NODE_ENV === 'production'
    ? {
        security: {
          encryption: { enabled: true },
          audit: { enabled: true },
        },
      }
    : {}),
};

function getCurrentApiVersion() {
  // Logic to determine API version
  return '59.0';
}
```

### Configuration Templates

Create reusable configuration templates:

```yaml
# .sf-agent/templates/enterprise.yaml
_extends: default

security:
  encryption:
    enabled: true
  compliance:
    frameworks: ['soc2', 'hipaa', 'gdpr']
  audit:
    enabled: true
    retention_days: 2555 # 7 years

performance:
  parallel_agents: 8
  monitoring:
    enabled: true

integration:
  git:
    hooks:
      pre_commit: true
      commit_msg: true
      pre_push: true
```

### Configuration Validation Schema

Define custom validation rules:

```yaml
# .sf-agent/config-schema.yaml
properties:
  organization:
    properties:
      api_version:
        type: string
        pattern: "^[0-9]{2}\\.[0-9]$"
        minimum: '58.0'

      type:
        type: string
        enum: ['production', 'sandbox', 'scratch', 'developer']

    required: ['alias', 'type', 'api_version']

  phases:
    properties:
      planning:
        properties:
          context_limit:
            type: number
            minimum: 32000
            maximum: 200000
```

## Configuration Best Practices

### 1. Use Profiles for Environments

```bash
# Development
sf-agent config profile use development

# Staging
sf-agent config profile use staging

# Production
sf-agent config profile use production
```

### 2. Secure Sensitive Data

```yaml
# Never commit sensitive data
credentials:
  salesforce_password: '${SF_PASSWORD}' # Use environment variable
  api_key: '${API_KEY}' # Use environment variable
```

### 3. Version Control Configuration

```bash
# .gitignore
.sf-agent/cache/
.sf-agent/logs/
.sf-agent/credentials

# DO commit
.sf-agent/config.yaml
.sf-agent/profiles/
```

### 4. Validate Before Deployment

```bash
# Always validate configuration changes
sf-agent config validate

# Test with dry-run
sf-agent --dry-run workflow deploy
```

### 5. Document Custom Configuration

```yaml
# Add comments explaining custom settings
performance:
  parallel_agents: 8 # Increased for our 16-core build server
  batch_size: 200 # Optimized for our data volume
```

## Troubleshooting Configuration

### Common Issues

**Issue: Configuration not loading**

```bash
# Check configuration path
sf-agent config path

# Validate configuration
sf-agent config validate

# Show effective configuration
sf-agent config list --effective
```

**Issue: Conflicting settings**

```bash
# Show configuration sources
sf-agent config list --show-source

# Reset to defaults
sf-agent config reset
```

**Issue: Environment variable not working**

```bash
# Check environment variables
sf-agent config env

# Debug configuration loading
SF_AGENT_DEBUG=true sf-agent config list
```

## Configuration API

For programmatic configuration:

```javascript
const { Config } = require('sf-agent-framework');

// Load configuration
const config = new Config();
await config.load();

// Get values
const orgAlias = config.get('organization.alias');
const contextLimit = config.get('phases.development.context_limit');

// Set values
config.set('organization.alias', 'neworg');
config.set('phases.development.context_limit', 40000);

// Save configuration
await config.save();

// Validate configuration
const errors = await config.validate();
if (errors.length > 0) {
  console.error('Configuration errors:', errors);
}
```

## Migration Guide

### Migrating from v3 to v4

```bash
# Automatic migration
sf-agent migrate config

# This will:
# 1. Backup existing configuration
# 2. Convert to new format
# 3. Validate migrated configuration
# 4. Apply new defaults
```

### Manual Migration

```yaml
# Old format (v3)
context_limit: 100000
agents:
  - name: developer
    type: coding

# New format (v4)
phases:
  development:
    context_limit: 32000
    default_agents:
      - sf-developer
```

## Summary

The SF-Agent Framework's configuration system provides:

1. **Flexibility**: Configure at multiple levels
2. **Security**: Protect sensitive data
3. **Profiles**: Environment-specific settings
4. **Validation**: Ensure configuration correctness
5. **Version Control**: Track configuration changes

Proper configuration is key to maximizing the framework's effectiveness for your specific needs.

---

_Last Updated: 2025-08-11_
_Version: 4.0.0_