sf-agent-framework/tools/README-CLI.md

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

# SF-Agent Framework CLI

## Quick Install

```bash
npm install -g sf-agent-framework@latest
```

That's it! You're ready to supercharge your Salesforce development with AI.

---

## What You Get

SF-Agent Framework transforms how you build on Salesforce by providing:

### 🤖 30+ Specialized AI Agents

Each agent is an expert in specific Salesforce domains - from Apex development to Lightning components to security configuration.

### ⚡ 70% Faster Development

Our two-phase architecture separates planning from coding, making AI responses 3x faster while using 70% less context.

### 📦 Complete Project Automation

From requirements gathering to deployment, our workflows handle entire project lifecycles.

### 🎯 Salesforce Best Practices Built-In

Every agent follows Salesforce best practices, security guidelines, and governance limits.

---

## Getting Started (2 Minutes)

### 1. Install the Framework

```bash
# Global installation (recommended)
npm install -g sf-agent-framework

# Or use directly with npx
npx sf-agent-framework install
```

### 2. 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
```

### 3. Build Your First Feature

```bash
# Start interactive workflow
sfa workflow

# Or use agents directly
sfa phase planning
/sf-architect *design "customer portal with SSO"
```

---

## Essential Commands

### 🎯 Core Commands

| Command            | Description                | Example              |
| ------------------ | -------------------------- | -------------------- |
| `sfa init [name]`  | Create new project         | `sfa init my-app`    |
| `sfa install`      | Add to existing project    | `sfa install`        |
| `sfa workflow`     | Start interactive workflow | `sfa workflow`       |
| `sfa phase [mode]` | Switch context mode        | `sfa phase planning` |
| `sfa help`         | Show all commands          | `sfa help`           |

### 🤖 Using AI Agents

```bash
# Planning Phase (Requirements & Architecture)
/sf-business-analyst *requirements
/sf-architect *design
/sf-data-architect *datamodel

# Development Phase (Implementation)
/sf-developer-lean *implement
/sf-admin-lean *configure
/sf-qa-lean *test

# Deployment Phase
/sf-devops-lead-lean *deploy
```

### 📝 Story Management

```bash
# Create stories from requirements
sfa story create --from requirements.md

# Work through story queue
sfa story list              # View all stories
sfa story next              # Get next story
sfa story accept STORY-001  # Start working
sfa story complete STORY-001 # Mark complete
```

---

## Workflows Explained

### What Are Workflows?

Workflows are pre-built project templates that guide you through complete implementations:

```bash
sfa workflow
```

You'll see options like:

1. 🆕 **New Salesforce Implementation** - Start from scratch
2. 🔄 **Enhance Existing Org** - Add features
3. 🚀 **Modernize to Lightning** - Upgrade Classic UI
4. 🔧 **Setup DevOps** - CI/CD pipeline
5. 📦 **Build Package** - Create managed package

### Interactive Workflow Example

```bash
$ sfa workflow

? Select your project type: New Salesforce Implementation
? Choose your approach: Requirements-driven development
? Select clouds: Sales Cloud, Service Cloud
? Include integrations? Yes
? Setup DevOps? Yes

✅ Workflow initialized: salesforce-greenfield-fullstack-v2
📋 Generated 12 implementation stories
🚀 Ready to start development!

Next steps:
1. Run: sfa story next
2. Follow the implementation guide
```

---

## Two-Phase Development

### Why Two Phases?

Traditional AI tools try to handle everything at once, leading to:

- Slow responses
- High token costs
- Context limits
- Confused outputs

### Our Solution

```
PLANNING PHASE (128k context)        DEVELOPMENT PHASE (32k context)
┌─────────────────────┐              ┌──────────────────────┐
│ • Full requirements │              │ • Focused stories    │
│ • Architecture      │    ────→     │ • Fast execution     │
│ • Complex analysis  │              │ • Lean agents        │
│ • Story generation  │              │ • 3x faster          │
└─────────────────────┘              └──────────────────────┘
```

### Using Phases

```bash
# Planning: Big picture thinking
sfa phase planning
/sf-architect *design    # Full context for architecture

# Development: Fast execution
sfa phase development
/sf-developer-lean *implement  # Optimized for speed
```

---

## Advanced Features

### 📄 Document Sharding

Break large documents into manageable pieces:

```bash
# Shard 100-page requirements doc
sfa shard docs/massive-requirements.pdf

# Output:
# ✅ Created 15 implementation stories
# 📁 Saved to: docs/stories/
```

### 🤝 Agent Handoffs

Formal handoffs between agents with full context:

```bash
# Create handoff package
sfa handoff create \
  --from sf-architect \
  --to sf-developer \
  --artifacts "architecture.md, data-model.json"

# Accept handoff
sfa handoff accept HO-2024-001 --agent sf-developer
```

### 🌐 Web Bundle Generation

Use SF-Agent with any AI chat interface:

```bash
# Build bundle for web UI
sfa build --teams-only

# Upload to ChatGPT/Claude/Gemini
# File: dist/teams/salesforce-core-team.txt
```

Then in ChatGPT:

```
*agent sf-developer
*task implement customer portal
```

### 🔧 IDE Integration

Configure for your IDE during installation:

```bash
sfa install --ide cursor vscode

# Supported IDEs:
# - Cursor
# - VS Code
# - IntelliJ IDEA
# - Code Builder
# - Windsurf (Claude Code)
```

---

## Real-World Examples

### Example 1: Build Customer Portal

```bash
# 1. Initialize project
sfa init customer-portal
cd customer-portal

# 2. Planning phase
sfa phase planning
/sf-business-analyst *requirements "customer self-service portal"

# 3. Architecture design
/sf-architect *design

# 4. Generate stories
sfa story create --from docs/requirements.md

# 5. Development phase
sfa phase development

# 6. Implement first story
sfa story next
/sf-developer-lean *implement

# 7. Test
/sf-qa-lean *test

# 8. Deploy
/sf-devops-lead-lean *deploy --target dev
```

### Example 2: Lightning Migration

```bash
# 1. Analyze current org
sfa workflow salesforce-org-modernization-v2

# 2. Follow interactive prompts
# - Analyzes Classic components
# - Creates migration plan
# - Generates LWC components
# - Handles data migration
# - Updates page layouts
```

### Example 3: Setup CI/CD Pipeline

```bash
# 1. Start DevOps workflow
sfa workflow salesforce-devops-cicd-v2

# 2. Configure pipeline
/sf-devops-lead-lean *setup-pipeline

# 3. Create GitHub Actions
/sf-release-automation-lean *github-actions

# 4. Setup environments
/sf-build-engineer-lean *configure-environments
```

---

## Project Structure

After installation, your project looks like:

```
my-salesforce-project/
├── .sf-core/              # Framework (auto-managed)
│   ├── agents/            # AI agent definitions
│   ├── workflows/         # Workflow templates
│   └── templates/         # Document templates
├── src/                   # Salesforce source
│   ├── classes/          # Apex classes
│   ├── lwc/              # Lightning components
│   ├── objects/          # Custom objects
│   └── flows/            # Flows & processes
├── docs/                  # Documentation
│   ├── requirements/     # Business requirements
│   ├── stories/          # Implementation stories
│   ├── architecture/     # Technical designs
│   └── handoffs/         # Agent handoffs
├── config/               # Configuration
│   └── sf-agent.json     # Framework config
└── scripts/              # Automation scripts
```

---

## Troubleshooting

### Common Issues

**Installation fails with permission error**

```bash
# Use sudo on Mac/Linux
sudo npm install -g sf-agent-framework

# Or use npx instead
npx sf-agent-framework install
```

**Agent not responding**

```bash
# Check current phase
sfa phase status

# Reset if needed
sfa phase planning
```

**Story queue is empty**

```bash
# Generate stories from requirements
sfa story create --from docs/requirements.md

# Or start a workflow
sfa workflow
```

---

## Configuration

### Project Configuration

Create `sf-agent.config.json`:

```json
{
  "version": "4.0.1",
  "defaultPhase": "planning",
  "ide": ["cursor", "vscode"],
  "features": {
    "autoHandoff": true,
    "storySharding": true,
    "webBundles": true
  },
  "agents": {
    "preferLean": true,
    "contextLimits": {
      "planning": 128000,
      "development": 32000
    }
  }
}
```

### Environment Variables

```bash
# Optional configuration
export SF_AGENT_PHASE=development
export SF_AGENT_IDE=cursor
export SF_AGENT_AUTO_HANDOFF=true
```

---

## Support & Resources

### Getting Help

- 📚 **Documentation**: Full docs in `./docs` after installation
- 🐛 **Issues**: [GitHub Issues](https://github.com/kripaSFDC/sf-agent-framework/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/kripaSFDC/sf-agent-framework/discussions)

### System Requirements

- **Node.js**: >= 20.0.0
- **Memory**: 8GB RAM minimum
- **Disk**: 2GB free space
- **Git**: For version control
- **Salesforce CLI**: Optional but recommended

### Contributing

We welcome contributions! See our [Contributing Guide](https://github.com/kripaSFDC/sf-agent-framework/blob/main/CONTRIBUTING.md).

---

## License

MIT License - Free for commercial and personal use.

---

<div align="center">

### 🚀 Start Building Smarter Today

```bash
npm install -g sf-agent-framework@latest
```

**Transform your Salesforce development with AI**

[![npm version](https://img.shields.io/npm/v/sf-agent-framework.svg)](https://www.npmjs.com/package/sf-agent-framework)
[![Downloads](https://img.shields.io/npm/dm/sf-agent-framework.svg)](https://www.npmjs.com/package/sf-agent-framework)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/kripaSFDC/sf-agent-framework/blob/main/LICENSE)

</div>