go-agentic/CLAUDE.md

CLAUDE.md

What This Is

AI service lifecycle and task management client. Module: forge.lthn.ai/core/go-agentic

Implements the Core framework service pattern for AI-assisted CLI operations: allowance/quota management, context building, completion requests, and claude CLI subprocess spawning.

Commands

go test ./...                    # Run all tests
go test -v -run TestAllowance    # Single test
go test -bench=. ./...           # Benchmarks

Architecture

File	LOC	Purpose
service.go	Service lifecycle (OnStartup, ServiceRuntime)
allowance.go	Quota/allowance tracking per workspace
allowance_service.go	Allowance persistence and enforcement
client.go	HTTP client for AI provider APIs
completion.go	Completion request/response types and logic
config.go	YAML/env configuration loading
context.go	Context building for AI prompts
types.go	Shared types (Task, Plan, etc.)
embed.go	Embedded prompt templates
prompts/	Markdown prompt templates (commit.md)

Dependencies

• forge.lthn.ai/core/go — Core DI framework (ServiceRuntime, framework, io, log)
• gopkg.in/yaml.v3 — Configuration parsing
• github.com/stretchr/testify — Tests

Key Interfaces

// Implements Core service pattern
type Service struct {
    *framework.ServiceRuntime[Config]
}

// Allowance management
type Allowance struct {
    WorkspaceID string
    Model       string
    Used        int
    Limit       int
}

Coding Standards

• UK English
• Tests: testify assert/require
• Conventional commits: type(scope): description
• Co-Author: Co-Authored-By: Virgil <virgil@lethean.io>
• Licence: EUPL-1.2

Task Queue

See TODO.md for prioritised work. See FINDINGS.md for research notes.