CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an AI multi-agent system called "Staff" that simulates a tech startup organization with different specialized AI agents (CEO, Product Manager, Engineers, etc.). The system integrates multiple LLM providers and implements a comprehensive task management workflow with Git-based operations.

### Core Architecture

- **Multi-Agent System**: Different AI agents with specialized roles (CEO, PM, Backend Engineer, Frontend Engineer, etc.)
- **Task Management**: Git-based task tracking system with automated PR creation
- **LLM Integration**: Unified interface supporting multiple providers (OpenAI, xAI, Claude, Gemini, local models)
- **Agent Workflow**: Agents fetch tasks → process with LLM → create solutions → submit PRs

### Key Components

1. **`/server/`** - Go backend with core agent infrastructure
   - **`agent/`** - Agent system that processes tasks autonomously using LLMs
   - **`llm/`** - Unified LLM provider interface and factory system
   - **`tm/`** - Task management interfaces and types
   - **`git/`** - Git operations for PR creation and repository management
   - **`cmd/`** - CLI commands and main entry point

2. **`/operations/`** - Company operational structure
   - **`agents/`** - Agent role definitions and system prompts
   - **`tasks/`** - Task files and examples

## Development Commands

### Building and Running
```bash
# Build the application
cd server && go build -o staff ./cmd/main.go

# Run with specific commands
./staff [command] [args]

# Run tests
go test ./server/...

# Run specific package tests
go test ./server/agent/...
go test ./server/llm/...
go test ./server/tm/...
```

### Common Development Tasks

```bash
# Format code
go fmt ./...

# Check for linting issues
go vet ./...

# Update dependencies
go mod tidy

# View available commands
./staff --help
```

## Agent System Architecture

### Agent Lifecycle
1. **Configuration**: Each agent has a unique name, role, Git credentials, LLM provider, and system prompt
2. **Task Processing Loop**: Continuously fetches assigned tasks from task manager
3. **LLM Integration**: Sends task descriptions to configured LLM for solutions
4. **Git Operations**: Creates branch, commits solution, pushes PR
5. **Task Completion**: Marks task as completed in task management system

### Agent Configuration
- Each agent requires unique name, role, Git credentials, working directory
- LLM configuration includes provider type, model, API credentials
- System prompts define agent behavior and expertise area
- Task manager integration for fetching and updating tasks

### Task Management
- Tasks have states: todo → in_progress → completed → archived
- Task priorities: low, medium, high
- Git-based task tracking with markdown files
- Automated PR creation for task solutions

## LLM Provider System

### Supported Providers
- OpenAI (GPT models)
- xAI (Grok models)
- Claude (Anthropic)
- Gemini (Google)
- Local models

### Provider Interface
All providers implement the same interface:
- `ChatCompletion()` - Main chat completion endpoint
- `CreateEmbeddings()` - Text embedding generation
- `Close()` - Resource cleanup

### Configuration
Each provider requires:
- API key and base URL
- Timeout and retry settings
- Provider-specific extra parameters

## File Structure Patterns

### Agent Definitions
- Agent system prompts stored in `/operations/agents/{role}/system.md`
- Each agent has detailed role definition and behavioral guidelines

### Task Files
- Task templates in `/operations/tasks/`
- Format: `task-{timestamp}-{id}.md`
- Include task metadata, description, and assignment info

### Solution PRs
- Agents create branches: `task/{task-id}-{clean-title}`
- Solutions formatted as markdown with task metadata
- Automated commit messages and PR descriptions

## Key Dependencies

### Go Modules
- `github.com/spf13/cobra` - CLI framework
- `github.com/google/uuid` - UUID generation
- `github.com/stretchr/testify` - Testing framework
- `golang.org/x/text` - Text processing
- `gopkg.in/yaml.v3` - YAML parsing

### Development Dependencies
- Go 1.24.4+ required
- Git for version control and PR operations
- Access to LLM provider APIs (OpenAI, etc.)

## Testing Strategy

### Test Coverage
- Unit tests for all major components
- Agent configuration validation
- LLM provider interface compliance
- Task management operations
- Git operations and branch creation

### Test Execution
```bash
# Run all tests
go test ./server/...

# Run with coverage
go test -cover ./server/...

# Run specific test suites
go test ./server/agent/ -v
go test ./server/llm/ -v
go test ./server/tm/ -v
```

## Security Considerations

- API keys managed through environment variables
- No hardcoded credentials in codebase
- Git operations use configured user credentials
- LLM responses processed but not executed directly

## Integration Points

### External Systems
- Git repositories for task management and code storage
- LLM provider APIs for agent intelligence
- Task management systems (GitHub Projects, Asana, Jira)

### Internal Communication
- Agents communicate through task management system
- PR review process for human oversight
- Automated task assignment and completion tracking