server/agent/README.md

# Agent Package

The `agent` package provides an AI agent system that can autonomously process tasks using LLM services, manage tasks through a task management system, and create pull requests with solutions.

## Overview

The agent system consists of:

- **AI Agent**: Processes tasks using LLM services
- **Task Manager**: Manages task lifecycle and assignment
- **Git Integration**: Creates pull requests with solutions
- **Infinite Loop**: Continuously processes assigned tasks

## Features

- **Autonomous Task Processing**: Agents automatically pick up and process assigned tasks
- **LLM Integration**: Uses configurable LLM providers (OpenAI, Claude, etc.)
- **Task Management**: Integrates with task management systems
- **Git Operations**: Creates branches and pull requests for solutions
- **Configurable Roles**: Different agents can have different roles and system prompts
- **Error Handling**: Robust error handling with graceful recovery

## Quick Start

### 1. Basic Setup

```go
package main

import (
    "log"
    "time"
    
    "github.com/iomodo/staff/agent"
    "github.com/iomodo/staff/git"
    "github.com/iomodo/staff/llm"
    "github.com/iomodo/staff/tm"
    "github.com/iomodo/staff/tm/git_tm"
)

func main() {
    // Create git interface for task management
    gitInterface := git.DefaultGit("./tasks-repo")
    
    // Create task manager
    taskManager := git_tm.NewGitTaskManager(gitInterface, "./tasks-repo")

    // Create LLM configuration
    llmConfig := llm.Config{
        Provider: llm.ProviderOpenAI,
        APIKey:   "your-openai-api-key-here",
        BaseURL:  "https://api.openai.com/v1",
        Timeout:  30 * time.Second,
    }

    // Create agent configuration
    config := agent.AgentConfig{
        Name:        "backend-engineer-1",
        Role:        "Backend Engineer",
        GitUsername: "backend-agent",
        GitEmail:    "backend-agent@company.com",
        WorkingDir:  "./workspace",
        LLMProvider: llm.ProviderOpenAI,
        LLMModel:    "gpt-4",
        LLMConfig:   llmConfig,
        SystemPrompt: `You are a skilled backend engineer. Your role is to:
1. Analyze tasks and provide technical solutions
2. Write clean, maintainable code
3. Consider performance, security, and scalability
4. Provide clear documentation for your solutions
5. Follow best practices and coding standards`,
        TaskManager: taskManager,
        GitRepoPath: "./code-repo",
        GitRemote:   "origin",
        GitBranch:   "main",
    }

    // Create agent
    agent, err := agent.NewAgent(config)
    if err != nil {
        log.Fatalf("Failed to create agent: %v", err)
    }

    // Run the agent
    if err := agent.Run(); err != nil {
        log.Fatalf("Agent failed: %v", err)
    }
}
```

### 2. Create a Task

```go
// Create a task for the agent to process
ctx := context.Background()
task, err := taskManager.CreateTask(ctx, &tm.TaskCreateRequest{
    Title:       "Implement user authentication API",
    Description: "Create a REST API endpoint for user authentication with JWT tokens. Include login, logout, and token refresh functionality.",
    OwnerID:     "backend-engineer-1", // Must match agent name
    Priority:    tm.PriorityHigh,
})
if err != nil {
    log.Fatalf("Failed to create task: %v", err)
}
```

## Configuration

### AgentConfig

The `AgentConfig` struct contains all configuration for an agent:

```go
type AgentConfig struct {
    Name        string        // Agent identifier
    Role        string        // Agent role (e.g., "Backend Engineer")
    GitUsername string        // Git username for commits
    GitEmail    string        // Git email for commits
    WorkingDir  string        // Working directory for files
    
    // LLM Configuration
    LLMProvider llm.Provider  // LLM provider type
    LLMModel    string        // Model name (e.g., "gpt-4")
    LLMConfig   llm.Config    // LLM provider configuration
    
    // System prompt for the agent
    SystemPrompt string       // Instructions for the LLM
    
    // Task Manager Configuration
    TaskManager tm.TaskManager // Task management interface
    
    // Git Configuration
    GitRepoPath string        // Path to git repository
    GitRemote   string        // Remote name (usually "origin")
    GitBranch   string        // Default branch name
}
```

### System Prompts

System prompts define the agent's behavior and expertise. Here are some examples:

#### Backend Engineer
```
You are a skilled backend engineer. Your role is to:
1. Analyze tasks and provide technical solutions
2. Write clean, maintainable code
3. Consider performance, security, and scalability
4. Provide clear documentation for your solutions
5. Follow best practices and coding standards

When responding to tasks, provide:
- Detailed technical analysis
- Code examples where appropriate
- Implementation considerations
- Testing recommendations
- Documentation suggestions
```

#### Frontend Engineer
```
You are a frontend engineer. Focus on:
- User interface design and implementation
- React/Vue/Angular development
- Responsive design and accessibility
- Performance optimization
- User experience best practices
```

#### Product Manager
```
You are a product manager. Focus on:
- Product strategy and roadmap
- User research and requirements gathering
- Feature prioritization and planning
- Stakeholder communication
- Product documentation and specifications
```

## How It Works

### 1. Task Processing Loop

The agent runs in an infinite loop that:

1. **Fetches Tasks**: Gets tasks assigned to the agent from the task manager
2. **Filters Tasks**: Looks for tasks with "todo" status
3. **Starts Task**: Marks the task as "in progress"
4. **Processes with LLM**: Sends task description to LLM for solution
5. **Creates PR**: Creates a git branch and pull request with the solution
6. **Completes Task**: Marks the task as completed

### 2. Git Operations

For each task, the agent:

1. Creates a new branch: `task/{task-id}-{clean-title}`
2. Writes solution to a markdown file
3. Commits the solution
4. Pushes the branch to create a pull request

### 3. Solution Format

Solutions are formatted as markdown files containing:

- Task metadata (ID, title, agent info)
- Original task description
- LLM-generated solution
- Timestamp and attribution

## Multiple Agents

You can run multiple agents with different roles:

```go
// Create agents with different roles
agents := []agent.AgentConfig{
    {
        Name:        "backend-engineer-1",
        Role:        "Backend Engineer",
        // ... backend configuration
    },
    {
        Name:        "frontend-engineer-1",
        Role:        "Frontend Engineer",
        // ... frontend configuration
    },
    {
        Name:        "product-manager-1",
        Role:        "Product Manager",
        // ... product manager configuration
    },
}

// Start all agents
for _, config := range agents {
    agent, err := agent.NewAgent(config)
    if err != nil {
        log.Printf("Failed to create agent %s: %v", config.Name, err)
        continue
    }

    go func(agent *agent.Agent, name string) {
        log.Printf("Starting agent: %s", name)
        if err := agent.Run(); err != nil {
            log.Printf("Agent %s stopped with error: %v", name, err)
        }
    }(agent, config.Name)
}
```

## Error Handling

The agent includes robust error handling:

- **Configuration Validation**: Validates all required fields
- **Graceful Recovery**: Continues running even if individual tasks fail
- **Logging**: Comprehensive logging of all operations
- **Resource Cleanup**: Proper cleanup of LLM connections

## Testing

Run the tests with:

```bash
go test ./server/agent/...
```

The test suite includes:

- Configuration validation
- Branch name generation
- Task prompt building
- Solution formatting
- Error handling

## Dependencies

The agent package depends on:

- `github.com/iomodo/staff/llm` - LLM service interface
- `github.com/iomodo/staff/tm` - Task management interface
- `github.com/iomodo/staff/git` - Git operations interface

## Examples

See `example.go` for complete working examples:

- `ExampleAgent()` - Single agent setup
- `ExampleMultipleAgents()` - Multiple agents with different roles

## Best Practices

1. **Unique Agent Names**: Ensure each agent has a unique name
2. **Role-Specific Prompts**: Tailor system prompts to the agent's role
3. **Task Assignment**: Assign tasks to agents by setting the `OwnerID` to the agent's name
4. **Monitoring**: Monitor agent logs for errors and performance
5. **Resource Management**: Ensure proper cleanup when stopping agents