# 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

```bash
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

```go
// 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.