sf-agent-framework

# Web Bundles Documentation ## Overview Web Bundles enable the SF-Agent Framework to work seamlessly with web-based AI platforms like ChatGPT, Claude, and Gemini. They package the entire framework, agents, and project context into a single uploadable file with built-in slash commands for control. ## What Are Web Bundles? Web Bundles are self-contained markdown files that include: - Complete framework functionality - All agent definitions - Project context and documentation - Slash command system - Interactive workflows - Session state management ``` ┌──────────────────────────────────────────────────────────┐ │ Web Bundle │ ├──────────────────────────────────────────────────────────┤ │ ┌─────────────────────────────────────────────────┐ │ │ │ Framework Core │ │ │ │ - Two-phase architecture │ │ │ │ - Context management │ │ │ │ - Workflow engine │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Agent Library │ │ │ │ - 30+ specialized agents │ │ │ │ - Phase-aware variants │ │ │ │ - Handoff protocols │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Slash Commands │ │ │ │ - Workflow control │ │ │ │ - Agent switching │ │ │ │ - Context management │ │ │ └─────────────────────────────────────────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────┐ │ │ │ Project Context │ │ │ │ - Requirements │ │ │ │ - Architecture │ │ │ │ - Standards │ │ │ └─────────────────────────────────────────────────┘ │ └──────────────────────────────────────────────────────────┘ ``` ## Building Web Bundles ### Basic Build ```bash # Build for all platforms sf-agent build web # Build for specific platform sf-agent build web --target chatgpt sf-agent build web --target gemini sf-agent build web --target claude # Build with options sf-agent build web \ --include-project \ --include-docs \ --compress \ --output ./custom-bundle.md ``` ### Build Configuration ```yaml # .sf-agent/bundle-config.yaml bundle: name: 'My Salesforce Project Bundle' version: '1.0.0' description: 'Complete SF development environment' targets: chatgpt: enabled: true max_size: '2MB' format: markdown gemini: enabled: true max_size: '1MB' format: markdown claude: enabled: true max_size: '5MB' format: markdown include: framework: core: true agents: all # or specific list workflows: all templates: essential project: requirements: true architecture: true standards: true examples: false documentation: quickstart: true commands: true full_docs: false optimization: compression: true minification: true deduplication: true slash_commands: enabled: true prefix: '*' shortcuts: true ``` ## Slash Command System ### Core Commands ```markdown # Slash Commands Reference ## 🎯 Core Commands ### Workflow Management *workflow list # List available workflows *workflow start [name] # Start a workflow *workflow status # Current workflow status *workflow pause # Pause current workflow *workflow resume # Resume paused workflow *workflow abort # Abort current workflow ### Agent Control *agent list # List all agents *agent [name] # Switch to specific agent *agent info # Current agent information *agent reset # Reset to default agent ### Phase Management *phase # Show current phase *phase planning # Switch to planning (128k) \*phase development # Switch to development (32k) ### Context Management *context status # Show context usage *context clear # Clear loaded context *context load [file] # Load specific context *context optimize # Optimize current context ### Task Execution *task list # List available tasks *task [name] # Execute specific task \*task status # Current task status ### Story Management *story list # List all stories *story next # Get next story *story implement [id] # Implement specific story *story complete [id] # Mark story complete ### Documentation *doc requirements # Show requirements *doc architecture # Show architecture *doc standards # Show coding standards *doc api # Show API reference ### Utilities *help # Show all commands *status # Complete status *reset # Reset session *artifacts # List created artifacts *metrics # Show metrics *validate # Run validation ``` ### Advanced Commands ```markdown ## 🚀 Advanced Commands ### Multi-Agent Collaboration *handoff create --from [agent] --to [agent] --artifacts [list] *handoff list \*handoff accept [id] ### Interactive Workflows *interactive start *choice [option] *gate approve *gate reject --reason [text] ### Parallel Execution *parallel start --tracks [track1,track2] *parallel status \*parallel wait ### Custom Commands *custom [command] [args] *macro [name] \*script [file] ``` ### Command Implementation ```javascript // Slash command processor class SlashCommandProcessor { constructor() { this.commands = new Map(); this.registerCoreCommands(); } registerCoreCommands() { // Workflow commands this.register('*workflow', { subcommands: { list: () => this.listWorkflows(), start: (name) => this.startWorkflow(name), status: () => this.workflowStatus(), pause: () => this.pauseWorkflow(), resume: () => this.resumeWorkflow(), abort: () => this.abortWorkflow(), }, }); // Agent commands this.register('*agent', { subcommands: { list: () => this.listAgents(), _default: (name) => this.switchAgent(name), info: () => this.agentInfo(), reset: () => this.resetAgent(), }, }); // Phase commands this.register('*phase', { handler: (phase) => { if (!phase) return this.getCurrentPhase(); return this.switchPhase(phase); }, }); } async process(command) { const [cmd, ...args] = command.split(' '); if (!cmd.startsWith('*')) { return null; // Not a slash command } const handler = this.commands.get(cmd); if (!handler) { throw new Error(`Unknown command: ${cmd}`); } return await handler(...args); } } ``` ## Platform-Specific Bundles ### ChatGPT Bundle ```markdown # SF-Agent Framework for ChatGPT Version: 4.0.0 | Mode: Interactive | Context: Optimized ## 🚀 Quick Start You now have access to the complete SF-Agent Framework for Salesforce development. Use slash commands (starting with \*) to control the framework. ## 📋 Available Commands *help - Show all commands *workflow start - Begin a workflow *agent sf-developer - Switch to developer agent *phase planning - Switch to planning phase (128k context) ## 🤖 Current State - Phase: Planning - Agent: sf-architect - Context: 45,231 / 128,000 tokens - Workflow: None ## 💡 Try These 1. Start planning: \*workflow comprehensive-planning 2. Create requirements: \*task gather-requirements 3. Design architecture: \*agent sf-architect [Full framework content follows...] ``` ### Gemini Bundle ```markdown # SF-Agent Framework for Gemini Optimized for Gemini's context window and capabilities ## Configuration - Compressed format for efficiency - Gemini-specific optimizations - Enhanced code generation ## Command Interface Commands use \* prefix for clarity: - \*w start (workflow start) - \*a dev (agent sf-developer) - \*p dev (phase development) [Compressed framework content...] ``` ### Claude Bundle ```markdown # SF-Agent Framework for Claude Extended context support with full framework capabilities ## Features - Full 200k context utilization - Complete documentation included - All agents and workflows available ## Enhanced Capabilities - Deep architectural analysis - Comprehensive code generation - Extended planning sessions [Complete framework with documentation...] ``` ## Bundle Structure ### 1. Header Section ```markdown # SF-Agent Framework Bundle Generated: 2025-08-11 Version: 4.0.0 Project: Customer Portal Target: ChatGPT ## Bundle Contents - ✅ Framework Core (v4.0.0) - ✅ 32 Agents (Planning + Development) - ✅ 12 Workflows - ✅ Slash Commands - ✅ Project Context - ✅ Documentation ``` ### 2. Instructions Section ```markdown ## How to Use This Bundle ### Initial Setup 1. Upload this file to ChatGPT/Gemini 2. The framework is now active 3. Use \*help to see available commands ### Recommended Workflow 1. Start with: \*workflow planning 2. Define requirements 3. Create architecture 4. Switch to development: \*phase development 5. Implement stories ### Tips - Use \*status to check current state - Use \*context to manage token usage - Use \*help [command] for detailed help ``` ### 3. Framework Section ```markdown ## Framework Core ### Two-Phase Architecture [Planning Phase - 128k tokens] - Comprehensive analysis - Full documentation access - Deep architectural thinking [Development Phase - 32k tokens] - Focused implementation - Lean context - Fast execution ### Context Management [Automatic optimization based on phase] ``` ### 4. Agents Section ```markdown ## Available Agents ### Planning Agents (128k) - sf-product-manager: Requirements and roadmap - sf-business-analyst: Process analysis - sf-architect: Solution design [... complete agent list ...] ### Development Agents (32k) - sf-developer: Code implementation - sf-admin: Configuration [... complete agent list ...] ``` ### 5. Project Context ```markdown ## Project Context ### Requirements [Project-specific requirements] ### Architecture [Architecture decisions and patterns] ### Standards [Coding standards and conventions] ### Current Status - Phase: Development - Sprint: 3 - Stories Completed: 12/45 ``` ## Interactive Features ### Session State Management ```javascript // Bundle maintains session state const sessionState = { id: 'session-123', startTime: '2025-08-11T10:00:00Z', current: { phase: 'development', agent: 'sf-developer', workflow: 'agile-development', story: 'STORY-015', }, context: { loaded: ['story-015.md', 'standards.md'], used: 12500, limit: 32000, }, artifacts: ['AccountService.cls', 'AccountServiceTest.cls', 'accountList.lwc'], history: [ { command: '*phase development', time: '10:05:00' }, { command: '*story next', time: '10:06:00' }, { command: '*agent sf-developer', time: '10:07:00' }, ], }; ``` ### Interactive Workflows ```markdown ## Interactive Workflow Example \*workflow interactive-planning > System: Select your approach: > > 1. Comprehensive (Full architecture) > 2. Rapid (MVP approach) > 3. Iterative (Phased delivery) \*choice 1 > System: Comprehensive approach selected. > Starting requirements gathering... > > What is the primary business objective? [User provides answer] > System: Requirements captured. > Would you like to proceed to architecture design? (yes/no) \*choice yes > System: Switching to sf-architect agent... > Beginning solution architecture... ``` ### Validation Gates ```markdown ## Validation Gate Example \*gate status > Current Gate: Architecture Review > Status: Pending Approval > Reviewers: > > - ✅ Technical Architect (Approved) > - ⏳ Security Architect (Pending) > - ⏳ Product Owner (Pending) > > Artifacts Under Review: > > - architecture/solution-design.md > - architecture/security-model.md \*gate approve --role "Security Architect" --comment "LGTM with minor suggestions" > Gate Status Updated > 2/3 approvals received ``` ## Bundle Optimization ### Size Management ```javascript // Bundle size optimization class BundleOptimizer { optimize(content, targetSize) { let optimized = content; // Level 1: Remove comments if (this.getSize(optimized) > targetSize) { optimized = this.removeComments(optimized); } // Level 2: Compress whitespace if (this.getSize(optimized) > targetSize) { optimized = this.compressWhitespace(optimized); } // Level 3: Minify code if (this.getSize(optimized) > targetSize) { optimized = this.minifyCode(optimized); } // Level 4: Remove examples if (this.getSize(optimized) > targetSize) { optimized = this.removeExamples(optimized); } // Level 5: Essential only if (this.getSize(optimized) > targetSize) { optimized = this.essentialOnly(optimized); } return optimized; } } ``` ### Compression Strategies ```yaml compression: strategies: - name: deduplication description: Remove duplicate content savings: '~20%' - name: minification description: Minimize code and text savings: '~30%' - name: selective_inclusion description: Include only used components savings: '~40%' - name: reference_linking description: Use references instead of inline savings: '~25%' ``` ## Advanced Bundle Features ### Macro System ```markdown ## Macros for Common Tasks ### Define Macros *macro define quick-setup " *phase planning *workflow requirements *agent sf-business-analyst " ### Use Macros \*macro run quick-setup ### List Macros \*macro list > Available Macros: > > - quick-setup: Planning phase initialization > - dev-cycle: Development iteration > - test-deploy: Test and deploy sequence ``` ### Bundle Extensions ```javascript // Extend bundle functionality class BundleExtension { constructor(bundle) { this.bundle = bundle; this.extensions = new Map(); } register(name, extension) { this.extensions.set(name, extension); // Add slash commands extension.commands?.forEach((cmd) => { this.bundle.registerCommand(cmd); }); // Add agents extension.agents?.forEach((agent) => { this.bundle.registerAgent(agent); }); } } // Example extension const manufacturingExtension = { name: 'manufacturing-cloud', commands: [ { name: '*mfg', handler: (args) => { // Manufacturing-specific commands }, }, ], agents: [ { id: 'sf-manufacturing-specialist', // Agent definition }, ], }; ``` ## Deployment & Distribution ### Automated Bundle Generation ```javascript // CI/CD bundle generation const bundleCI = { triggers: ['push', 'release'], steps: [ { name: 'Generate Bundles', run: ` sf-agent build web --target chatgpt sf-agent build web --target gemini sf-agent build web --target claude `, }, { name: 'Upload to CDN', run: 'aws s3 cp dist/bundles/ s3://bundles/', }, { name: 'Update Registry', run: 'sf-agent bundle register', }, ], }; ``` ### Bundle Versioning ```yaml versioning: strategy: semantic versions: - version: 4.0.0 date: 2025-08-11 changes: - Two-phase architecture - Slash commands - Interactive workflows - version: 3.5.0 date: 2025-07-01 changes: - Agent handoffs - Validation gates ``` ## Troubleshooting ### Common Issues **Issue: Bundle too large** ```bash # Use compression sf-agent build web --compress --minimal # Exclude non-essential content sf-agent build web --essential-only ``` **Issue: Commands not working** ```markdown *debug on *command-trace on \*help commands ``` **Issue: Context overflow** ```markdown *context clear *phase development # Switch to lean context \*context optimize ``` ## Best Practices ### 1. Bundle Organization ```markdown Structure bundles with clear sections: 1. Quick reference at top 2. Commands easily accessible 3. Agents grouped by phase 4. Project context at end ``` ### 2. Command Design ```markdown Keep commands: - Short and memorable - Consistent naming - Well-documented - With helpful feedback ``` ### 3. User Experience ```markdown Optimize for: - Fast initial orientation - Progressive disclosure - Clear feedback - Error recovery ``` ## Summary Web Bundles enable: 1. **Portability**: Use framework anywhere 2. **Completeness**: Full functionality in one file 3. **Control**: Slash commands for interaction 4. **Optimization**: Platform-specific tuning 5. **Extensibility**: Add custom features Web Bundles bridge the gap between the SF-Agent Framework and web-based AI platforms, enabling powerful Salesforce development in any environment. --- _Last Updated: 2025-08-11_ _Version: 4.0.0_