diff --git a/server/agent/README.md b/server/agent/README.md
new file mode 100644
index 0000000..0015d90
--- /dev/null
+++ b/server/agent/README.md
@@ -0,0 +1,298 @@
+# 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 
\ No newline at end of file