Phase 1: Foundation

Objective

Establish a working prototype with core functionality: prompt handling, LLM integration, and basic persistence.

Week 1-2: Project Setup

Week 1: Repository and Tooling

Tasks:

• Initialize Git repository
• Create Cargo workspace structure
• Set up GitHub Actions CI:
  • Format check (rustfmt)
  • Lint check (clippy)
  • Test execution
  • Security audit (cargo audit)
• Configure Dependabot
• Set up branch protection rules
• Create CONTRIBUTING.md
• Add LICENSE (MIT/Apache-2.0 dual)

Deliverables:

• Green CI pipeline
• Contribution guidelines
• Repository structure established

Week 2: Core Infrastructure

Tasks:

• Create workspace crates:
  • harness-types - shared types and errors
  • harness-core - domain logic
  • harness-api - HTTP server
  • harness-cli - command-line interface
• Set up SQLx with compile-time checking
• Create initial database schema
• Implement configuration system (config crate)
• Add structured logging (tracing)
• Create health check endpoint

Deliverables:

• Workspace compiles
• Database migrations working
• Configuration loading from file/env
• Health endpoint returns 200 OK

Week 3-4: Domain Layer

Week 3: Core Types and Models

Tasks:

• Define core domain types:

  #![allow(unused)]
  fn main() {
  struct Conversation { ... }
  struct Message { ... }
  struct ToolCall { ... }
  enum Role { User, Assistant, System }
  }

• Implement conversation state machine
• Create LLM provider trait
• Define prompt templates structure
• Add validation rules

Deliverables:

• Types compile with all derives
• Unit tests for domain logic
• Documentation for all public types

Week 4: LLM Integration

Tasks:

• Implement OpenAI provider
  • Completion API
  • Streaming support
  • Error handling
• Create LLM client abstraction
• Add request/response logging
• Implement retry logic with backoff
• Add circuit breaker pattern

Deliverables:

• Can send requests to OpenAI API
• Streaming responses work
• Errors handled gracefully
• Unit tests with mocked LLM

Week 5-6: API Layer

Week 5: REST API Endpoints

Tasks:

• Implement endpoints:
  • POST /conversations - Create conversation
  • GET /conversations/:id - Get conversation
  • POST /conversations/:id/messages - Send message
  • GET /conversations/:id/messages - List messages
  • DELETE /conversations/:id - Delete conversation
• Add request/response validation
• Implement error responses (RFC 7807 Problem Details)
• Add OpenAPI/Swagger documentation

Deliverables:

• All endpoints functional
• API documentation available
• Error responses consistent

Week 6: Persistence and State

Tasks:

• Implement conversation repository
• Add message persistence
• Create conversation service layer
• Add pagination for message lists
• Implement conversation listing with filters
• Add soft delete support

Deliverables:

• Conversations persist across restarts
• Can list and filter conversations
• Deletion is soft (recoverable)

Week 7-8: Execution and Polish

Week 7: Basic Code Execution

Tasks:

• Implement simple in-process executor (for development only)
• Parse tool calls from LLM responses
• Create tool registry
• Add echo/math/read_file example tools
• Implement tool result formatting

Deliverables:

• LLM can invoke tools
• Tool results return to conversation
• Basic tool examples working

Week 8: CLI and Integration

Tasks:

• Build interactive CLI
  • Create conversation command
  • Send message command
  • List conversations command
  • Configuration command
• Add Docker support
  • Dockerfile
  • docker-compose.yml with PostgreSQL
• Create integration tests
• Write initial README

Deliverables:

• CLI usable for basic interactions
• Docker setup works
• Integration tests pass
• README with setup instructions

Technical Decisions for Phase 1

Database Schema

-- conversations table
CREATE TABLE conversations (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title VARCHAR(255),
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at TIMESTAMPTZ
);

-- messages table
CREATE TABLE messages (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    conversation_id UUID NOT NULL REFERENCES conversations(id),
    role VARCHAR(20) NOT NULL,
    content TEXT NOT NULL,
    tool_calls JSONB,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

-- indexes
CREATE INDEX idx_messages_conversation ON messages(conversation_id);
CREATE INDEX idx_conversations_updated ON conversations(updated_at DESC);

API Response Format

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Hello conversation",
  "messages": [
    {
      "id": "...",
      "role": "user",
      "content": "Hello, can you help me?"
    },
    {
      "id": "...",
      "role": "assistant",
      "content": "I'd be happy to help! What do you need?"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:31:00Z"
}

Configuration Structure

[server]
host = "0.0.0.0"
port = 8080

[database]
url = "postgres://user:pass@localhost/harness"
max_connections = 10

[llm]
provider = "openai"
api_key = "${OPENAI_API_KEY}"
model = "gpt-4"
timeout_seconds = 30

[logging]
level = "info"
format = "json"

Definition of Done for Phase 1

• All code compiles without warnings
• CI pipeline passes
• Unit test coverage > 70%
• Integration tests pass
• API documentation complete
• Docker setup works
• CLI functional
• Can create conversation, send messages, receive responses
• Conversations persist in database
• Basic tool execution works
• README with quickstart guide

Risks and Mitigations

Next Phase Preview

Phase 2 (Security) will build on this foundation by:

• Replacing in-process execution with sandboxed environments
• Adding authentication and authorization
• Implementing comprehensive audit logging
• Hardening all endpoints

The foundation laid here must support these additions without major refactoring.