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
# Run the application
cd server && go run cmd/main.go server  



### Testing
```bash
# Run all tests
cd server && go test ./...

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

### Common Development Tasks
```bash
# Check for linting issues
cd server && go vet ./...

# Update dependencies
cd server && go mod tidy
```

## 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 (via Ollama)
- Fake provider (for testing)

### 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

Configuration can be provided via:
- `config.yaml` file in server directory
- Environment variables (OPENAI_API_KEY, GITHUB_TOKEN, etc.)
- Command-line configuration during setup

## File Structure Patterns

### Agent Definitions
- Agent system prompts stored in `/operations/agents/{name}/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: `solution/{task-id}-{clean-title}` or `subtasks/{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 for command-line interface
- `github.com/google/uuid` - UUID generation for task and agent IDs
- `github.com/joho/godotenv` - Environment variable loading from .env files
- `golang.org/x/text` - Text processing utilities
- `gopkg.in/yaml.v3` - YAML parsing for configuration files

### Development Dependencies
- Go 1.24.4+ required 
- Git for version control and PR operations
- Access to LLM provider APIs (OpenAI, xAI, Claude, Gemini, etc.)
- Environment variables or config.yaml for API keys and credentials

## 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


## 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 (GitHub/Gerrit)
- LLM provider APIs for agent intelligence
- Task management systems via Git-based task tracking

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