sf-agent-framework

# Workflows Documentation ## Overview Workflows in SF-Agent Framework orchestrate complex multi-step processes, coordinating agents, managing context, and ensuring quality gates. They support sequential, parallel, and interactive execution patterns. ## Workflow Architecture ``` ┌──────────────────────────────────────────────────────────────┐ │ Workflow Engine │ ├──────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Parser │→ │ Validator │→ │ Executor │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Execution Patterns │ │ │ ├────────────────────────────────────────────────────┤ │ │ │ Sequential │ Parallel │ Conditional │ Interactive │ │ │ └──────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────┐ │ │ │ Quality Gates & Validation │ │ │ └──────────────────────────────────────────────────┘ │ │ │ └──────────────────────────────────────────────────────────────┘ ``` ## Core Workflows ### 1. Comprehensive Planning Workflow **Purpose**: Complete planning phase for new features. ```yaml # comprehensive-planning.yaml workflow: id: comprehensive-planning name: Comprehensive Planning Workflow phase: planning version: 1.0.0 description: | Complete planning workflow for new Salesforce features. Includes requirements, architecture, and design. prerequisites: - authenticated_org - project_initialized phases: - name: requirements parallel: false steps: - id: gather-requirements agent: sf-product-manager task: requirement-elicitation interactive: true prompts: - 'What is the primary business objective?' - 'Who are the key stakeholders?' - 'What are the success metrics?' output: requirements/business-requirements.md - id: analyze-processes agent: sf-business-analyst task: process-analysis input: requirements/business-requirements.md output: requirements/process-analysis.md - id: create-stories agent: sf-product-manager task: story-creation input: - requirements/business-requirements.md - requirements/process-analysis.md output: stories/user-stories.yaml validation: gate: requirements-complete checks: - requirements_documented - stories_created - stakeholder_approval - name: architecture parallel: true tracks: - name: solution-design steps: - agent: sf-architect task: solution-architecture output: architecture/solution-design.md - name: data-design steps: - agent: sf-data-architect task: data-modeling output: architecture/data-model.md - name: integration-design steps: - agent: sf-integration-architect task: integration-patterns output: architecture/integration-design.md - name: security-design steps: - agent: sf-security-architect task: security-model output: architecture/security-design.md validation: gate: architecture-complete checks: - architecture_reviewed - patterns_validated - security_approved - name: review steps: - id: architecture-review type: multi-agent-review agents: - sf-architect - sf-technical-architect - sf-security-architect artifacts: - architecture/*.md criteria: - scalability - security - performance - maintainability - id: final-approval type: human-gate prompt: 'Review and approve the planning artifacts' required_approvers: - architect - product_owner outputs: documents: - requirements/*.md - architecture/*.md - stories/*.yaml metrics: - planning_duration - tokens_used - artifacts_created ``` ### 2. Agile Development Workflow **Purpose**: Implement user stories in development phase. ```yaml # agile-development.yaml workflow: id: agile-development name: Agile Development Workflow phase: development version: 1.0.0 configuration: context_limit: 32000 parallel_execution: true auto_test: true phases: - name: story-implementation type: story-queue steps: - id: get-next-story action: queue.next filter: status: ready priority: high - id: load-context action: context.load sources: - story-file - coding-standards - api-reference - id: implement agent: sf-developer task: implement-story validation: - syntax_check - security_scan - id: create-tests agent: sf-developer task: generate-tests coverage_target: 85 - id: code-review agent: sf-architect task: review-code criteria: - best_practices - performance - security - name: testing steps: - id: unit-tests agent: sf-qa task: run-unit-tests fail_on_error: true - id: integration-tests agent: sf-qa task: run-integration-tests - id: coverage-check action: validate.coverage minimum: 85 - name: documentation parallel: true optional: false steps: - agent: sf-developer task: generate-docs types: - apex_docs - component_docs - readme ``` ### 3. Interactive Workflow **Purpose**: User-guided workflow with decision points. ```yaml # interactive-implementation.yaml workflow: id: interactive-implementation name: Interactive Implementation Workflow interactive: true phases: - name: approach-selection type: user-choice prompt: 'Select implementation approach' options: - id: comprehensive label: 'Comprehensive (Full architecture)' next: comprehensive-flow - id: rapid label: 'Rapid (MVP approach)' next: rapid-flow - id: iterative label: 'Iterative (Phased delivery)' next: iterative-flow - name: comprehensive-flow condition: choice == 'comprehensive' steps: - agent: sf-architect task: detailed-design duration: extended - agent: sf-data-architect task: complete-data-model - type: user-choice prompt: 'Include advanced features?' options: - id: yes actions: - include: advanced-features.yaml - id: no actions: - skip: advanced-features - name: validation-gates type: progressive-validation gates: - name: design-review type: human prompt: 'Approve design?' on_reject: return-to-design - name: security-review type: automated agent: sf-security on_fail: security-remediation - name: performance-check type: automated thresholds: response_time: 2000ms cpu_time: 1000ms ``` ### 4. Deployment Workflow **Purpose**: Managed deployment process. ```yaml # deployment-workflow.yaml workflow: id: deployment-workflow name: Staged Deployment Workflow environments: - dev - qa - uat - production phases: - name: preparation steps: - id: create-package agent: sf-devops-lead task: package-components - id: validate-package agent: sf-devops-lead task: validate-deployment check_only: true - name: staged-deployment type: progressive environments: - name: dev steps: - deploy - smoke-test - full-test - name: qa approval_required: false steps: - deploy - regression-test - performance-test - name: uat approval_required: true approvers: [product_owner, qa_lead] steps: - deploy - user-acceptance-test - sign-off - name: production approval_required: true approvers: [release_manager, product_owner] maintenance_window: true steps: - backup - deploy - smoke-test - monitor - name: rollback condition: deployment_failed steps: - id: initiate-rollback agent: sf-devops-lead task: rollback-deployment - id: verify-rollback agent: sf-qa task: verify-system-state ``` ## Workflow Patterns ### 1. Sequential Pattern Execute steps one after another: ```yaml pattern: sequential steps: - step1 - step2 # Waits for step1 - step3 # Waits for step2 ``` ### 2. Parallel Pattern Execute multiple tracks simultaneously: ```yaml pattern: parallel tracks: - track1: - step1a - step1b - track2: # Runs parallel to track1 - step2a - step2b ``` ### 3. Conditional Pattern Branch based on conditions: ```yaml pattern: conditional condition: if: result.status == 'success' then: success-branch else: failure-branch ``` ### 4. Loop Pattern Iterate over items: ```yaml pattern: loop items: ${stories} steps: - implement: ${item} - test: ${item} - deploy: ${item} ``` ### 5. Pipeline Pattern Stream processing with transformations: ```yaml pattern: pipeline stages: - extract: source-data - transform: apply-rules - validate: check-quality - load: target-system ``` ## Interactive Workflows ### User Choice Points ```javascript // Interactive workflow implementation class InteractiveWorkflow { async executeWithChoices() { // Present choice to user const choice = await this.promptUser({ question: 'Select implementation approach:', options: [ { id: 'comprehensive', label: 'Full Architecture' }, { id: 'rapid', label: 'MVP Approach' }, { id: 'iterative', label: 'Phased Delivery' }, ], }); // Branch based on choice switch (choice.id) { case 'comprehensive': await this.executeComprehensive(); break; case 'rapid': await this.executeRapid(); break; case 'iterative': await this.executeIterative(); break; } // Validation gate const approved = await this.validationGate({ reviewers: ['architect', 'product_owner'], artifacts: this.artifacts, criteria: ['completeness', 'quality', 'security'], }); if (!approved) { await this.handleRejection(); } } } ``` ### Dynamic Workflow Adjustment ```javascript // Adjust workflow based on context class DynamicWorkflow { async adjustForContext(context) { const workflow = this.baseWorkflow; // Add steps based on project type if (context.projectType === 'greenfield') { workflow.addPhase('complete-architecture'); } else if (context.projectType === 'brownfield') { workflow.addPhase('impact-analysis'); } // Adjust for team size if (context.teamSize > 10) { workflow.enableParallelExecution(); } // Add compliance steps if (context.compliance.includes('hipaa')) { workflow.addPhase('hipaa-validation'); } return workflow; } } ``` ## Validation Gates ### Gate Types ```yaml validation_gates: - type: automated name: code-quality checks: - syntax: valid - coverage: '>= 85%' - complexity: '< 10' - security: pass - type: human name: architecture-review reviewers: - role: architect required: true - role: security_lead required: false - type: conditional name: performance-gate condition: 'response_time < 2000ms' on_fail: optimize-performance - type: multi-stage name: deployment-gate stages: - automated-checks - human-approval - final-validation ``` ### Gate Implementation ```javascript class ValidationGate { async validate(artifacts, criteria) { const results = []; // Run automated checks for (const check of criteria.automated) { const result = await this.runCheck(check, artifacts); results.push(result); if (!result.passed && check.required) { return { passed: false, reason: `Failed required check: ${check.name}`, results, }; } } // Request human review if needed if (criteria.humanReview) { const review = await this.requestReview({ reviewers: criteria.reviewers, artifacts, deadline: criteria.deadline, }); if (!review.approved) { return { passed: false, reason: 'Human review rejected', feedback: review.feedback, }; } } return { passed: true, results, }; } } ``` ## Custom Workflows ### Creating Custom Workflows ```yaml # custom-workflow.yaml workflow: id: industry-specific name: Healthcare Implementation extends: base-workflow custom_phases: - name: hipaa-compliance steps: - agent: sf-security-architect task: hipaa-assessment - agent: sf-developer task: implement-encryption - agent: sf-qa task: compliance-testing - name: phi-handling steps: - agent: sf-data-architect task: design-phi-model - agent: sf-security-architect task: access-control-design custom_validations: - id: hipaa-gate type: compliance framework: hipaa required: true - id: audit-trail type: automated check: audit-completeness ``` ### Workflow Templates ```javascript // Workflow template system class WorkflowTemplate { static manufacturing() { return { id: 'manufacturing-template', phases: ['production-planning', 'inventory-management', 'quality-control', 'supply-chain'], agents: ['sf-manufacturing-specialist', 'sf-inventory-expert'], }; } static financialServices() { return { id: 'financial-services-template', phases: ['compliance-check', 'risk-assessment', 'transaction-processing', 'reporting'], compliance: ['sox', 'pci-dss'], }; } } ``` ## Workflow Execution ### Execution Engine ```javascript class WorkflowExecutor { async execute(workflow, context) { const execution = { id: generateId(), workflow: workflow.id, started: Date.now(), context, state: {}, artifacts: [], }; try { // Initialize workflow await this.initialize(workflow, execution); // Execute phases for (const phase of workflow.phases) { execution.currentPhase = phase.name; // Check prerequisites if (!(await this.checkPrerequisites(phase))) { throw new Error(`Prerequisites not met for ${phase.name}`); } // Execute phase const result = await this.executePhase(phase, execution); execution.artifacts.push(...result.artifacts); // Validation gate if (phase.validation) { const valid = await this.validate(phase.validation, result); if (!valid) { await this.handleValidationFailure(phase, result); } } // Update state execution.state[phase.name] = result; } // Complete workflow await this.complete(execution); } catch (error) { await this.handleError(error, execution); throw error; } return execution; } } ``` ### Parallel Execution ```javascript class ParallelExecutor { async executeTracks(tracks, context) { const promises = tracks.map((track) => this.executeTrack(track, context)); const results = await Promise.allSettled(promises); // Check for failures const failures = results.filter((r) => r.status === 'rejected'); if (failures.length > 0) { throw new AggregateError( failures.map((f) => f.reason), 'Parallel execution failed' ); } // Merge results return this.mergeResults(results.map((r) => r.value)); } } ``` ## Workflow Monitoring ### Metrics Collection ```javascript const workflowMetrics = { execution: { total: 1247, successful: 1198, failed: 49, averageDuration: 12.5, // minutes byWorkflow: { 'comprehensive-planning': { executions: 234, avgDuration: 45.2, successRate: 0.97, }, 'agile-development': { executions: 567, avgDuration: 8.3, successRate: 0.95, }, }, }, performance: { tokenUsage: { average: 35000, peak: 125000, }, parallelization: { efficiency: 0.82, speedup: 3.2, }, }, validation: { gatesPassed: 1145, gatesFailed: 52, averageReviewTime: 2.3, // hours }, }; ``` ### Workflow Analytics ```javascript class WorkflowAnalytics { analyzeBottlenecks(executions) { const phaseTimings = {}; executions.forEach((exec) => { exec.phases.forEach((phase) => { if (!phaseTimings[phase.name]) { phaseTimings[phase.name] = []; } phaseTimings[phase.name].push(phase.duration); }); }); // Identify slowest phases const bottlenecks = Object.entries(phaseTimings) .map(([phase, timings]) => ({ phase, avgDuration: average(timings), variance: variance(timings), })) .sort((a, b) => b.avgDuration - a.avgDuration) .slice(0, 5); return bottlenecks; } } ``` ## Best Practices ### 1. Workflow Design ```yaml best_practices: design: - Keep workflows focused and single-purpose - Use composition over complexity - Include validation gates at critical points - Provide rollback procedures - Document prerequisites clearly ``` ### 2. Error Handling ```javascript // Robust error handling class WorkflowErrorHandler { async handle(error, execution) { // Log error await this.logError(error, execution); // Attempt recovery if (this.isRecoverable(error)) { return await this.recover(error, execution); } // Rollback if needed if (execution.supportsRollback) { await this.rollback(execution); } // Notify stakeholders await this.notify({ error, execution, severity: this.getSeverity(error), }); throw error; } } ``` ### 3. Performance Optimization ```javascript // Optimize workflow execution const optimizations = { // Cache frequently used data caching: { strategy: 'lru', ttl: 3600, keys: ['templates', 'standards', 'references'], }, // Parallelize where possible parallelization: { maxConcurrency: 4, batchSize: 10, }, // Compress context contextOptimization: { compression: true, lazyLoading: true, pruning: true, }, }; ``` ## Troubleshooting ### Common Issues **Issue: Workflow stuck** ```bash # Check workflow status sf-agent workflow status WORKFLOW-ID # Force continue sf-agent workflow continue WORKFLOW-ID --force # Abort workflow sf-agent workflow abort WORKFLOW-ID ``` **Issue: Validation gate failing** ```bash # Get gate details sf-agent workflow gate-info GATE-ID # Override gate (with caution) sf-agent workflow override-gate GATE-ID --reason "Approved by PM" ``` **Issue: Performance degradation** ```bash # Analyze workflow performance sf-agent workflow analyze WORKFLOW-ID # Optimize workflow sf-agent workflow optimize WORKFLOW-ID ``` ## Summary Workflows in SF-Agent Framework provide: 1. **Orchestration**: Coordinate complex multi-agent processes 2. **Flexibility**: Sequential, parallel, and interactive patterns 3. **Quality**: Built-in validation gates 4. **Customization**: Extend and create custom workflows 5. **Monitoring**: Track execution and performance Workflows are the backbone of automated Salesforce development, ensuring consistent, high-quality delivery. --- _Last Updated: 2025-08-11_ _Version: 4.0.0_