sf-agent-framework/docs/05-quick-start/README.md

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

# Quick Start Guide

## Get Started in 5 Minutes

This guide will have you using SF-Agent Framework productively in minutes. We'll cover installation, basic usage, and your first workflow.

## Prerequisites Checklist

Before starting, ensure you have:

- [ ] **Node.js 20+** installed (`node --version`)
- [ ] **Salesforce CLI** installed (`sfdx --version` or `sf --version`)
- [ ] **A Salesforce Org** (Developer Edition, Sandbox, or Scratch Org)
- [ ] **Git** installed (`git --version`)

## 1. Installation (1 minute)

### Option A: Quick Install (Recommended)

```bash
# One-command installation
npx sf-agent-framework install

# Follow the interactive prompts
```

### Option B: Global Install

```bash
# Install globally
npm install -g sf-agent-framework

# Initialize in your project
cd your-salesforce-project
sf-agent install
```

## 2. Initial Configuration (2 minutes)

When you run the installer, you'll be prompted for:

1. **Project Type**: Select your project type
   - `greenfield` - New project from scratch
   - `brownfield` - Existing project enhancement
   - `package` - ISV/Package development

2. **Primary IDE**: Choose your main development environment
   - `cursor` - Cursor IDE
   - `claude-code` - Claude Code (Windsurf)
   - `vscode` - Visual Studio Code
   - `idea` - IntelliJ IDEA

3. **Features**: Enable framework features
   - Two-Phase Development? → **Yes** (recommended)
   - Interactive Workflows? → **Yes** (recommended)
   - Web Bundles? → **Yes** (if using ChatGPT/Gemini)

## 3. Connect to Salesforce (1 minute)

```bash
# Authorize your Salesforce org
sfdx auth:web:login -a myorg

# Configure SF-Agent to use this org
sf-agent config set org.alias myorg
```

## 4. Your First Workflow (1 minute)

### Quick Start for Existing Projects (Brownfield)

If you're working with an existing Salesforce project, this quick start guide will help you get up and running quickly.

**1. Document Your Project:**

The first step is to document your existing codebase. This provides the necessary context for the AI agents.

```bash
# Document the entire project
sf-agent task document-all
```

**2. Plan Your Enhancement:**

Once your project is documented, you can start planning your new feature or enhancement.

```bash
# Start the brownfield planning workflow
sf-agent workflow create-brownfield-prd
```

This will guide you through the process of creating a PRD for your enhancement, taking into account the existing codebase.

**3. Implement and Test:**

After planning, you can move on to implementation and testing, following the standard development workflow.

```bash
# Get the next story
sf-agent story next

# Implement the story
sf-agent story implement STORY-ID

# Test your changes
sf-agent test
```

### Example 1: Create a New Feature

```bash
# Start the requirements workflow
sf-agent workflow requirements

# This will:
# 1. Launch the requirements gathering agent
# 2. Guide you through feature definition
# 3. Create requirements documentation
# 4. Prepare for implementation
```

### Example 2: Generate Documentation

```bash
# Document existing code
sf-agent task document-apex --class AccountController

# This creates comprehensive documentation for your class
```

### Example 3: Build for Web UI

```bash
# Create a web bundle for ChatGPT/Gemini
sf-agent build web

# This creates a single file in dist/
# Upload this file to ChatGPT or Gemini for AI assistance
```

## Common First Tasks

### 1. Planning a New Feature

```bash
# Start in planning phase
sf-agent phase planning

# Run planning workflow
sf-agent workflow feature-planning

# You'll be guided through:
# - Requirements gathering
# - Architecture design
# - Story creation
```

### 2. Implementing a User Story

```bash
# Switch to development phase
sf-agent phase development

# Implement next story
sf-agent story next

# This will:
# - Load the story context
# - Generate implementation
# - Create tests
# - Validate code
```

### 3. Creating Custom Objects

```bash
# Use the admin agent
sf-agent agent sf-admin

# Create custom object
sf-agent task create-object --name "Project__c"

# Add fields
sf-agent task add-field --object "Project__c" --field "Status__c" --type "Picklist"
```

### 4. Building Lightning Web Components

```bash
# Use developer agent for LWC
sf-agent agent sf-developer

# Create new LWC
sf-agent task create-lwc --name "projectList"

# This generates:
# - Component JavaScript
# - HTML template
# - CSS styling
# - Unit tests
```

### 5. Running Quality Checks

```bash
# Run security scan
sf-agent validate security

# Run code quality check
sf-agent validate quality

# Run all validations
sf-agent validate all
```

## Interactive Mode

For a guided experience, use interactive mode:

```bash
# Start interactive session
sf-agent interactive

# You'll see a menu:
? What would you like to do?
  ❯ Start a workflow
    Work on a story
    Create documentation
    Run validation
    Build bundles
    Configure settings
```

## Working with Web UIs

### For ChatGPT

1. Build the bundle:

```bash
sf-agent build web --target chatgpt
```

2. Upload the file from `dist/chatgpt-bundle.md`

3. Use slash commands:

```
*workflow start requirements
*agent sf-architect
*task design-solution
```

### For Gemini

1. Build the bundle:

```bash
sf-agent build web --target gemini
```

2. Upload the file from `dist/gemini-bundle.md`

3. Use slash commands similarly

## Project Structure After Setup

After installation, your project will have:

```
your-project/
├── .sf-core/           # Framework core (don't edit)
│   ├── agents/         # Agent definitions
│   ├── workflows/      # Workflow configurations
│   └── templates/      # Document templates
│
├── .sf-agent/          # Your configuration
│   └── config.yaml     # Project settings
│
├── docs/               # Generated documentation
│   ├── requirements/   # Requirements docs
│   ├── architecture/   # Architecture docs
│   └── stories/        # User stories
│
└── dist/               # Build outputs
    ├── agents/         # Agent bundles
    └── teams/          # Team bundles
```

## Quick Tips

### 1. Check Framework Status

```bash
# Verify installation
sf-agent doctor

# Check current phase
sf-agent status

# View configuration
sf-agent config list
```

### 2. Get Help

```bash
# General help
sf-agent --help

# Command-specific help
sf-agent workflow --help

# Interactive help
sf-agent help interactive
```

### 3. Update Framework

```bash
# Check for updates
sf-agent update --check

# Update to latest
sf-agent update
```

## Common Workflows

### Workflow 1: New Feature Development

```bash
# 1. Planning Phase
sf-agent phase planning
sf-agent workflow feature-planning

# 2. Transition to Development
sf-agent phase development

# 3. Implement Stories
sf-agent story list
sf-agent story implement STORY-001

# 4. Test
sf-agent test

# 5. Deploy
sf-agent deploy
```

### Workflow 2: Bug Fix

```bash
# 1. Analyze the issue
sf-agent task analyze-issue --description "Login fails for portal users"

# 2. Get fix recommendations
sf-agent agent sf-developer
sf-agent task debug-apex --class "PortalLoginController"

# 3. Implement fix
sf-agent task fix-bug --issue "ISSUE-123"

# 4. Test fix
sf-agent test --class "PortalLoginController"
```

### Workflow 3: Documentation Generation

```bash
# 1. Document entire codebase
sf-agent task document-all

# 2. Generate specific docs
sf-agent task document-apex
sf-agent task document-lwc
sf-agent task document-flows

# 3. Create user guide
sf-agent task create-user-guide
```

## Keyboard Shortcuts (Interactive Mode)

When in interactive mode:

- `↑/↓` - Navigate options
- `Enter` - Select option
- `Ctrl+C` - Exit
- `Tab` - Auto-complete
- `?` - Show help

## VS Code / Cursor Integration

If using VS Code or Cursor:

1. Install the extension:

```bash
sf-agent integrate vscode
```

2. Use Command Palette (`Cmd/Ctrl + Shift + P`):
   - `SF-Agent: Start Workflow`
   - `SF-Agent: Switch Phase`
   - `SF-Agent: Build Bundle`

3. Right-click context menu:
   - `Generate with SF-Agent`
   - `Document with SF-Agent`
   - `Test with SF-Agent`

## Environment Variables

Set these for advanced configuration:

```bash
# Set default org
export SF_AGENT_ORG=myorg

# Set default phase
export SF_AGENT_PHASE=development

# Enable debug mode
export SF_AGENT_DEBUG=true

# Set custom config location
export SF_AGENT_CONFIG=/path/to/config
```

## Troubleshooting Quick Fixes

### Issue: "Command not found"

```bash
# Reinstall globally
npm install -g sf-agent-framework

# Or use npx
npx sf-agent-framework [command]
```

### Issue: "Cannot connect to Salesforce"

```bash
# Re-authenticate
sfdx auth:web:login -a myorg

# Update configuration
sf-agent config set org.alias myorg
```

### Issue: "Context overflow"

```bash
# Switch to development phase (smaller context)
sf-agent phase development

# Or clear context
sf-agent context clear
```

### Issue: "Agent not found"

```bash
# Rebuild agent bundles
sf-agent build --agents-only

# List available agents
sf-agent agent list
```

## What's Next?

Now that you're up and running:

1. **Explore Agents**: See [Agent System](../07-agents/README.md)
2. **Learn Workflows**: See [Workflows](../08-workflows/README.md)
3. **Try Templates**: See [Templates](../09-templates/README.md)
4. **Advanced Features**: See [Advanced Features](../17-advanced-features/README.md)

## Quick Reference Card

### Essential Commands

| Command                                  | Description       |
| ---------------------------------------- | ----------------- |
| `sf-agent install`                       | Install framework |
| `sf-agent workflow [name]`               | Start workflow    |
| `sf-agent phase [planning\|development]` | Switch phase      |
| `sf-agent story implement [id]`          | Implement story   |
| `sf-agent build web`                     | Build web bundle  |
| `sf-agent validate`                      | Run validations   |
| `sf-agent test`                          | Run tests         |
| `sf-agent deploy`                        | Deploy to org     |
| `sf-agent doctor`                        | Check health      |
| `sf-agent help`                          | Get help          |

### Slash Commands (Web UI)

| Command            | Description        |
| ------------------ | ------------------ |
| `*help`            | Show all commands  |
| `*status`          | Show current state |
| `*workflow [name]` | Start workflow     |
| `*agent [name]`    | Switch agent       |
| `*task [name]`     | Run task           |
| `*phase [name]`    | Switch phase       |
| `*context`         | Show context usage |
| `*artifacts`       | List artifacts     |

## Support

Need help?

- **Documentation**: [Full Documentation](../README.md)
- **Issues**: [GitHub Issues](https://github.com/kripaSFDC/sf-agent-framework/issues)
- **Community**: [Discussions](https://github.com/kripaSFDC/sf-agent-framework/discussions)

---

_Last Updated: 2025-08-11_
_Version: 4.0.0_