sf-agent-framework

# SF-Agent Framework Simulation Engine ## Overview The Simulation Engine provides realistic team orchestration visualization that runs **parallel to actual agent work**. This ensures that while users see an engaging simulation, real work is being performed in the background. ## Key Features ### 1. **Parallel Execution with Real Work** - Simulation shows actual progress, not fake animations - Real agent work drives the visualization - Errors immediately stop simulation and show actual issues - Progress reflects true task completion ### 2. **Dynamic Virtual Team Generation** - Automatically generates team members from agent definitions - Extracts personas from agent YAML configurations - Maintains personality consistency throughout workflow - Adapts to phase-based team compositions ### 3. **ASCII Art Dashboards** - Real-time progress visualization - Team status dashboard - Active task tracking - Live activity feed - Customizable visualization types (ASCII/text/none) ### 4. **Integration with Orchestrators** Both `sf-orchestrator` and `sf-orchestrator-v2` now support: - `*simulation [on|off|status]` - Toggle simulation - `*visual [ascii|text|none]` - Set visualization type - `*team-status` - Show virtual team dashboard ## Architecture ``` simulation/ ├── simulation-engine.js # Core engine - coordinates everything ├── persona-engine.js # Generates consistent personas from agents ├── progress-tracker.js # Tracks ACTUAL work progress ├── visualization-engine.js # Creates ASCII dashboards ├── index.js # Main entry point and integration └── test-example.js # Demonstration of the system ``` ## How It Works ### 1. Workflow Starts When a workflow begins, the orchestrator: 1. Loads the workflow definition 2. Identifies required agents from team configuration 3. Dynamically generates virtual team members 4. Starts simulation parallel to actual work ### 2. During Execution As agents perform real work: 1. Agents report actual progress to the simulation engine 2. Progress tracker updates based on real completion 3. Visualization refreshes showing actual status 4. Team members reflect real agent activities ### 3. Error Handling If an error occurs: 1. Simulation immediately stops 2. Error is displayed to user 3. No fake progress is shown 4. Actual error details are provided ## Configuration ### In sf-orchestrator.md and sf-orchestrator-v2.md: ```yaml simulation-config: enabled: true # Toggle simulation on/off mode: parallel-with-real-work # Always sync with actual work visualization: type: ascii # ascii, text, or none auto_display: true # Show automatically refresh_interval: 5000 # Update every 5 seconds team_dynamics: generate_from_agents: true # Create team from agent definitions use_existing_teams: true # Use team YAML files progress_tracking: sync_with_actual_work: true # Only show real progress show_intermediate_updates: false # No fake updates error_stops_simulation: true # Stop on errors persona_generation: dynamic: true # Generate dynamically use_agent_definitions: true # From agent YAML personality_consistency: true # Maintain throughout ``` ## Usage Examples ### 1. Start a Workflow with Simulation ```bash # Activate orchestrator sf-orchestrator # Start security audit workflow (simulation auto-starts) *workflow security-audit # The simulation will show: # - Team members being assigned # - Real progress as tasks complete # - Actual results from agents ``` ### 2. Control Simulation ```bash # Check simulation status *simulation status # Turn off simulation *simulation off # Change visualization type *visual text # Show team status *team-status ``` ### 3. Phase-Aware Simulation (sf-orchestrator-v2) ```bash # In planning phase *phase planning *workflow # Simulation shows planning team: # - Product Manager # - Business Analyst # - Architect # In development phase *phase development *workflow # Simulation shows dev team: # - Developer (lean) # - Admin (lean) # - QA (lean) ``` ## Visualization Examples ### ASCII Dashboard: ``` ╔══════════════════════════════════════════════════════════════════════════╗ ║ SECURITY AUDIT WORKFLOW ORCHESTRATION ║ ╚══════════════════════════════════════════════════════════════════════════╝ ▶ PROGRESS: [████████████░░░░░░░░░░░░░░░░░░░░░░░░░░░] 30% ▶ PHASE: Security Assessment ▶ STATUS: Scanning for vulnerabilities... ═══════════════════════════════════════════════════════════════════════════ TEAM STATUS DASHBOARD ═══════════════════════════════════════════════════════════════════════════ 🔒 Jennifer Walsh (Security Officer) Status: 🔄 WORKING Task: Vulnerability scan Progress: [████████░░░░░░░] 50% 👨‍💻 Jordan Davis (Lead Developer) Status: 🔄 WORKING Task: Code security review Progress: [████░░░░░░░░░░░] 25% 👩‍💼 Maria Rodriguez (Senior Admin) Status: 🟢 AVAILABLE Task: Available for assignment ═══════════════════════════════════════════════════════════════════════════ ``` ## Testing Run the test example: ```bash cd sf-core/simulation node test-example.js ``` This will demonstrate: - Virtual team creation - Progress simulation based on actual work - Visualization updates - Error handling ## Key Principles 1. **Reality Over Simulation**: Always show actual progress, never fake it 2. **Immediate Error Response**: Stop simulation instantly on errors 3. **Dynamic Team Generation**: Create teams from actual agent definitions 4. **Personality Consistency**: Maintain agent personas throughout 5. **User Control**: Allow toggling and customization via commands ## Benefits 1. **Enhanced User Experience**: See work happening in real-time 2. **Team Visibility**: Understand which agents are working on what 3. **Progress Transparency**: Clear view of actual completion status 4. **Error Clarity**: Immediate feedback when issues occur 5. **Engaging Interface**: ASCII dashboards make CLI more interactive ## Future Enhancements - [ ] Add more visualization themes - [ ] Support for concurrent workflow simulations - [ ] Historical simulation playback - [ ] Performance metrics visualization - [ ] Custom persona templates - [ ] Integration with MCP servers ## Troubleshooting ### Simulation Not Showing - Check if enabled: `*simulation status` - Verify visualization type: `*visual ascii` - Ensure workflow has team definition ### Progress Not Updating - Confirms agents are reporting progress - Check refresh interval in config - Verify actual work is proceeding ### Error During Simulation - Simulation stops immediately (by design) - Check error message for actual issue - Resolve underlying problem and restart