Expert guidance for working with the Regolith (ReGo) Go library - a unified abstraction layer for multiple REST APIs including Google Workspace, Okta, Jamf, Slack, and more.
You are working with Regolith (ReGo), an open-source Go library that provides a unified abstraction layer for multiple REST APIs. Named from Greek rhegos (blanket) + lithos (rock), it acts as a foundational "blanket layer" over enterprise services.
ReGo simplifies interactions with Google Workspace, Okta, Jamf, Active Directory, Slack, SnipeIT, Atlassian, LenelS2, Backupify, and more through:
When first exploring the ReGo codebase:
1. Review the project structure in `pkg/` to identify the service you need to work with
2. Check if a service-specific `CLAUDE.md` exists in `pkg/[service_name]/CLAUDE.md` for detailed guidance
3. Examine `pkg/common/` packages to understand shared utilities
4. Look at `pkg/orchestrators/` for multi-service workflow examples
**Before making changes:**
1. Run tests to ensure baseline functionality:
```bash
make test
```
2. Check code quality:
```bash
make pretty
```
**When implementing new features:**
1. Follow the established design patterns (see Architecture section)
2. Ensure all new services follow the standard Client Pattern
3. Implement generic request handling using the `do[T any]` pattern
4. Add appropriate pagination handling if needed
5. Include comprehensive error handling
6. Add tests for new functionality
**After making changes:**
1. Run tests: `make test`
2. Check coverage: `go test -cover ./...`
3. Format code: `make pretty`
4. Update copyright headers: `make update-copyright`
5. Update documentation: `make docs`
**CRITICAL:** All commits MUST follow this structured format:
```
[Primary Change Description]; [Secondary Changes] & more…
{PackageName}
{AnotherPackage}
(No dependency updates.)
```
**Rules:**
**Example:**
```
SnipeIT Overhaul; Update {Jamf, Requests, Makefile, Dependencies} & more…
{Makefile}
{Dependencies}
{Requests}
{Jamf}
(No dependency updates.)
```
Follow this checklist when adding a new service:
1. **Create service package**: `pkg/[service_name]/`
2. **Implement core files**:
- `[service_name].go` - Main client with `NewClient()` constructor
- `entities.go` - API resource structs
- Domain-specific files (`users.go`, `devices.go`, etc.)
- `CLAUDE.md` - Service-specific guidance
3. **Follow Client Pattern**:
```go
type Client struct {
BaseURL string
HTTP *requests.Client
Log *log.Logger
Cache *cache.Cache
Rate *ratelimit.RateLimiter
}
```
4. **Environment variable configuration**:
- Check required vars at initialization, not usage
- Use `config.GetEnv()` for all env vars
- Require `REGO_ENCRYPTION_KEY` for cache encryption
5. **Implement generic request handling**:
```go
func do[T any](c *Client, method, url string, query, data any) (T, error)
```
6. **Add pagination** if the API supports it (choose appropriate pattern: Interface-based, Slice-based, or Concurrent Offset)
7. **Add tests** in `pkg/internal/tests/[service_name]/`
8. **Update documentation**: Run `make docs` and `./gen_hugo_index.sh`
1. **Consistency Over Cleverness** - All services follow similar patterns
2. **Type Safety with Generics** - Use Go generics for type-safe operations
3. **Environment-First Configuration** - All config via environment variables
4. **Defensive Programming** - Check required vars at initialization
5. **Performance Optimization** - Use caching, rate limiting, concurrent ops
6. **Developer Experience** - Method chaining, intuitive naming, consistent patterns
7. **Security by Default** - Mandatory encryption for cached data
8. **Flexibility Through Composition** - Services can be composed together
9. **Progressive Enhancement** - Start basic, add advanced features as needed
10. **API-Specific Adaptations** - Adapt to each API's peculiarities while maintaining consistency
**Method Chaining (Jamf)**:
```go
devices, err := client.Devices().
Sections([]string{Section.General, Section.Hardware}).
PageSize(100).
Sort("id:asc").
Filter("general.platform==\"Mac\"").
ListAllComputers()
```
**Generic Request Handling**:
```go
user, err := do[User](client, "GET", "/users/123", nil, nil)
users, err := do[[]User](client, "GET", "/users", query, nil)
```
**Builder Pattern (SnipeIT)**:
```go
lic := snipeit.NewLicense("name").
LicenseEmail("[email protected]").
Maintained(true).
Seats("100").
Build()
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/rego-development-guide/raw