# Go Framework

> Go framework design patterns for Beluga AI v2. Use when designing package structure, registries, lifecycle, or creating new packages. Use when this capability is needed.

- Skill: `tomevault-io/go-framework` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/go-framework`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/go-framework/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/go-framework

---


# Go Framework Patterns

## Package Structure

```
<package>/
├── <interface>.go     # Extension contract
├── registry.go        # Register(), New(), List()
├── hooks.go           # Lifecycle hooks
├── middleware.go       # Middleware type + Apply()
└── providers/          # Built-in implementations
```

## Registry + Factory

```go
var (
    mu       sync.RWMutex
    registry = make(map[string]Factory)
)

func Register(name string, f Factory) {
    mu.Lock()
    defer mu.Unlock()
    registry[name] = f
}

func New(name string, cfg ProviderConfig) (Interface, error) {
    mu.RLock()
    f, ok := registry[name]
    mu.RUnlock()
    if !ok {
        return nil, fmt.Errorf("unknown provider %q (registered: %v)", name, List())
    }
    return f(cfg)
}

func List() []string { /* sorted keys */ }
```

## Functional Options

```go
type Option func(*options)
func WithTimeout(d time.Duration) Option { return func(o *options) { o.timeout = d } }
func New(opts ...Option) *Thing { o := defaults(); for _, opt := range opts { opt(&o) }; return &Thing{opts: o} }
```

## Provider Registration

```go
func init() {
    llm.Register("openai", func(cfg llm.ProviderConfig) (llm.ChatModel, error) { return New(cfg) })
}
// Users import: import _ "github.com/lookatitude/beluga-ai/llm/providers/openai"
```

## Rules

- Compile-time interface check: `var _ Interface = (*Impl)(nil)`
- Lifecycle: Start(ctx), Stop(ctx), Health() — shutdown in reverse order.
- Error handling: return `(T, error)`, wrap with core.Error, check IsRetryable().
- context.Context is always first parameter.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/lookatitude) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->