go-framework_skill

Overview

This skill captures recommended Go framework design patterns tailored for Beluga AI v2. It provides concise conventions for package layout, provider registries, lifecycle hooks, middleware, and functional options. Use it to standardize new packages, implementations, and integrations within the Beluga ecosystem.

How this skill works

The skill defines a canonical package structure with clear file responsibilities: interface contracts, registry/factory, lifecycle hooks, middleware, and built-in providers. It prescribes a thread-safe registry + factory pattern, functional options for configuration, provider registration via init hooks, and a consistent lifecycle and error-handling contract. These patterns are lightweight and composable so you can plug implementations into common registries and lifecycle managers.

When to use it

• Designing a new Beluga package that will have multiple provider implementations
• Creating a registry or plugin system that needs thread-safe lookup and factory creation
• Defining lifecycle-aware components that must start, stop, and report health in order
• Implementing middleware that should be applied consistently across implementations
• Standardizing configuration using functional options for clear defaults and overrides

Best practices

• Follow the recommended package layout: interface, registry, hooks, middleware, providers
• Use a sync.RWMutex protected map for registries and expose Register, New, and List
• Prefer functional options for optional settings and sensible defaults
• Register built-in providers in init() so users can import side-effect packages
• Enforce compile-time interface adherence with var _ Interface = (*Impl)(nil)
• Make context.Context the first function parameter and return (T, error) for ops

Example use cases

• Implementing a new LLM provider and registering it under a name for dynamic selection
• Building a lifecycle manager that starts components in order and shuts them down in reverse
• Creating middleware chains for request/response processing across providers
• Providing a factory-based client constructor that accepts functional options for timeout and retries
• Listing available implementations to populate configuration UIs or validation logic