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

# 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

# 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

# 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