sf-agent-framework
Version:
AI Agent Orchestration Framework for Salesforce Development - Two-phase architecture with 70% context reduction
450 lines (313 loc) • 13.9 kB
Markdown
# SF-Agent Framework v4.0
<div align="center">
**AI-Powered Salesforce Development Framework | 70% Less Context | 3x Faster Delivery**
[🚀 Quick Start](#quick-start) | [📚 Documentation](./docs) | [💡 Features](#features) | [🤖 Agents](#agents) | [📦 Installation](#installation)
</div>
## 📋 Table of Contents
- [Overview](#overview)
- [Features](#features)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [How It Works](#how-it-works)
- [Agents](#agents)
- [Workflows](#workflows)
- [Templates](#templates)
- [Project Structure](#project-structure)
- [Advanced Features](#advanced-features)
- [Use Cases](#use-cases)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
## Overview
SF-Agent Framework is an intelligent orchestration system that transforms Salesforce development through AI agents. It dramatically reduces development time and improves code quality by leveraging specialized AI agents that understand Salesforce best practices.
### Why SF-Agent Framework?
| Benefit | Impact | How It Works |
| -------------------------- | -------------------------------- | ----------------------------------------------------- |
| **70% Less Context** | Faster AI responses, lower costs | Two-phase architecture separates planning from coding |
| **3x Faster Development** | 20-minute story implementation | Lean agents optimized for specific tasks |
| **85% First-Pass Success** | Less rework, higher quality | Agents trained on Salesforce best practices |
| **30+ Specialized Agents** | Complete coverage | Each agent masters specific Salesforce domains |
| **Enterprise-Ready** | Production-safe | Built-in security, compliance, and governance |
### Real-World Results
- **Implementation Time**: 60 min → 20 min per story
- **Context Usage**: 100k → 30k tokens per task
- **Documentation**: 30 min → 6 min generation
- **Test Coverage**: 75% → 90% automated
## Features
### 🔄 Two-Phase Development Architecture
Separate planning from coding for maximum efficiency:
```
PLANNING PHASE (128k context) DEVELOPMENT PHASE (32k context)
┌─────────────────────┐ ┌──────────────────────┐
│ • Full requirements │ │ • Focused stories │
│ • Architecture │ ────→ │ • Fast execution │
│ • Complex analysis │ │ • Lean agents │
│ • Story generation │ │ • 3x faster │
└─────────────────────┘ └──────────────────────┘
```
### 📝 Story-Based Development
Transform requirements into actionable, self-contained stories:
```markdown
# STORY-001: Implement Customer Portal Login
## Context
All information needed for implementation...
## Requirements
- User authentication via OAuth 2.0
- Session management with 30-min timeout
- Multi-factor authentication support
## Technical Specifications
- Apex controller: CustomerPortalController
- LWC component: customerLogin
- Integration: Auth0 SSO
```
### 🤖 Specialized Agent Teams
- **Architecture Team**: Solution design, technical patterns, data modeling
- **Development Team**: Apex/LWC coding, configuration, testing
- **Deployment Team**: CI/CD, release automation, monitoring
### 📦 Enterprise Workflows
Pre-built workflows for common scenarios:
- New Salesforce implementations
- Org enhancements and features
- Lightning migration
- DevOps pipeline setup
- Package development
## Installation
### Prerequisites
- Node.js >= 20.0.0
- Git
- 8GB RAM minimum
- 2GB disk space
### Install Commands
```bash
# Global installation (recommended)
npm install -g sf-agent-framework@latest
# Verify installation
sfa --version
# Output: 4.0.1
# Or use directly with npx
npx sf-agent-framework install
```
## Quick Start
### 1. Initialize Your Project
```bash
# Create new project
sfa init my-salesforce-project
cd my-salesforce-project
# Or add to existing project
cd existing-project
sfa install
```
### 2. Start Building (5 Minutes)
```bash
# Start interactive workflow
sfa workflow
# Or use agents directly
sfa phase planning
/sf-business-analyst *requirements "customer portal"
/sf-architect
# Switch to development
sfa phase development
/sf-developer-lean
/sf-qa-lean
/sf-devops-lead-lean
```
### 3. Common Commands
| Command | Description | Example |
| ------------------ | -------------------------- | ----------------------------------------- |
| `sfa init [name]` | Create new project | `sfa init my-app` |
| `sfa workflow` | Start interactive workflow | `sfa workflow` |
| `sfa phase [mode]` | Switch context mode | `sfa phase planning` |
| `sfa story create` | Generate stories | `sfa story create --from requirements.md` |
| `sfa help` | Show all commands | `sfa help` |
## How It Works
### Step 1: Planning Phase (Rich Context)
```bash
sfa phase planning
```
AI agents analyze requirements with full context to create comprehensive plans.
### Step 2: Story Generation
```bash
sfa story create --from requirements.md
```
Requirements are broken into self-contained, implementable stories.
### Step 3: Development Phase (Lean Context)
```bash
sfa phase development
```
Switch to optimized agents that work 3x faster with focused context.
### Step 4: Implementation
```bash
/sf-developer-lean
```
Lean agents implement each story with all necessary context included.
## Agents
### Planning Phase Agents (Rich Context)
| Agent | Specialization | Commands |
| ------------------------ | ---------------------- | ---------------------------- |
| `sf-business-analyst` | Requirements gathering | `*requirements`, `*analysis` |
| `sf-architect` | Solution architecture | `*design`, `*patterns` |
| `sf-technical-architect` | Technical design | `*integration`, `*api` |
| `sf-data-architect` | Data modeling | `*datamodel`, `*migration` |
| `sf-security-architect` | Security framework | `*security`, `*compliance` |
### Development Phase Agents (Lean Context)
| Agent | Context Size | Focus | Speed |
| --------------------- | ------------ | --------------------- | ----------- |
| `sf-developer-lean` | 32k | Apex, LWC, Triggers | 3x faster |
| `sf-admin-lean` | 24k | Configuration, Fields | 2.5x faster |
| `sf-qa-lean` | 24k | Testing, Quality | 2x faster |
| `sf-devops-lead-lean` | 30k | Deployment, CI/CD | 2x faster |
## Workflows
### Interactive Workflows
Start with `sfa workflow` and choose:
1. 🆕 **New Salesforce Implementation** - Greenfield projects
2. 🔄 **Enhance Existing Org** - Add features
3. 🚀 **Modernize to Lightning** - Classic to Lightning
4. 🔧 **Setup DevOps** - CI/CD pipeline
5. 📦 **Build Package** - Managed/Unmanaged packages
### Workflow Example
```bash
$ sfa workflow
? Select your project type: New Salesforce Implementation
? Choose your approach: Requirements-driven development
? Select clouds: Sales Cloud, Service Cloud
✅ Workflow initialized: salesforce-greenfield-fullstack-v2
📋 Generated 12 implementation stories
🚀 Ready to start development!
```
## Templates
AI-powered document generation that adapts to your needs:
| Template | Purpose | Time Saved |
| --------------------------- | ------------------------------------- | --------------- |
| `user-story-enhanced` | User stories with acceptance criteria | 20 min → 2 min |
| `technical-design-enhanced` | Architecture documents | 60 min → 10 min |
| `test-class-enhanced` | Complete test classes | 30 min → 5 min |
| `apex-class-enhanced` | Apex classes with best practices | 15 min → 3 min |
| `lwc-component-enhanced` | LWC with HTML, JS, metadata | 25 min → 5 min |
### Using Templates
```bash
# Interactive mode
sfa template process user-story-enhanced
# With variables
sfa template process technical-design-enhanced \
--var project_name="Customer Portal" \
--var complexity="high"
```
## Project Structure
```
your-salesforce-project/
├── .sf-core/ # Framework core (auto-managed)
│ ├── agents/ # 30+ specialized agents
│ ├── workflows/ # Enterprise workflows
│ └── templates/ # Document templates
├── src/ # Your Salesforce code
│ ├── classes/ # Apex classes
│ ├── lwc/ # Lightning Web Components
│ ├── objects/ # Custom objects
│ └── triggers/ # Apex triggers
├── docs/ # Generated documentation
│ ├── stories/ # Implementation stories
│ ├── architecture/ # Design documents
│ └── handoffs/ # Agent handoff packages
└── config/ # Configuration files
└── sf-agent.config.json
```
## Advanced Features
### Document Sharding
Break large requirements into manageable stories:
```bash
sfa shard docs/100-page-requirements.md
# Output: 20 focused implementation stories
```
### Agent Handoffs
Seamless collaboration between AI agents:
```bash
sfa handoff create --from sf-architect --to sf-developer
# Packages all context for smooth transition
```
### Web Bundle Generation
Use with ChatGPT, Claude, or Gemini:
```bash
sfa build --teams-only
# Upload dist/teams/salesforce-core-team.txt to any AI chat
```
### IDE Integration
Works with all major IDEs:
- Cursor
- VS Code + Salesforce Extensions
- IntelliJ with Illuminated Cloud
- Code Builder
## Use Cases
### Perfect For
✅ **Greenfield Implementations** - New Salesforce orgs
✅ **Feature Development** - Complex features for existing orgs
✅ **Lightning Migration** - Classic to Lightning Experience
✅ **DevOps Setup** - CI/CD pipelines and automation
✅ **Package Development** - Managed/unmanaged packages
✅ **Integration Projects** - Connect with external systems
✅ **Data Migration** - Move data between orgs
### Success Stories
- **Enterprise Retail**: 70% reduction in implementation time
- **Financial Services**: 85% first-pass code accuracy
- **Healthcare Provider**: 3x faster Lightning migration
- **SaaS Company**: 90% automated test coverage
## Documentation
### Core Guides
- [Complete Documentation](./docs)
- [Quick Start Guide](./docs/05-quick-start/README.md)
- [Best Practices](./docs/31-best-practices/README.md)
- [API Reference](./docs/api-reference.md)
### Getting Help
- 🐛 [Report Issues](https://github.com/kripaSFDC/sf-agent-framework/issues)
- 💬 [Discussions](https://github.com/kripaSFDC/sf-agent-framework/discussions)
- 📧 Email: support@sf-agent-framework.com
## Contributing
We welcome contributions! Areas where you can help:
- 🤖 Create new specialized agents
- 📝 Improve templates and documentation
- 🔧 Enhance workflows
- 🐛 Report and fix bugs
- 💡 Suggest new features
See [Contributing Guide](./docs/how-to-contribute-with-pull-requests.md) for details.
## License
MIT License - See [LICENSE](./LICENSE) file for details.
## Why Choose SF-Agent Framework?
| Feature | SF-Agent | Traditional Dev | Generic AI |
| ------------------------ | -------------------------- | ------------------- | ---------------- |
| **Salesforce Expertise** | ✅ Deep platform knowledge | ✅ Manual expertise | ❌ No context |
| **Development Speed** | ✅ 3x faster | ❌ Standard pace | ⚠️ Variable |
| **Context Efficiency** | ✅ 70% reduction | ❌ Full context | ❌ Massive usage |
| **Code Quality** | ✅ 85% first-pass | ⚠️ Varies | ⚠️ Heavy review |
| **Best Practices** | ✅ Built-in | ⚠️ Manual | ❌ Unaware |
| **Cost** | ✅ Lower AI costs | ❌ High dev costs | ❌ High tokens |
<div align="center">
### 🚀 Ready to Transform Your Salesforce Development?
```bash
npm install -g sf-agent-framework@latest
```
**Join thousands of developers building smarter with AI**
[](https://github.com/kripaSFDC/sf-agent-framework)
[](https://www.npmjs.com/package/sf-agent-framework)
[](./LICENSE)
</div>