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

# 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