1# Crush Development Guide
 2
 3## Build/Test/Lint Commands
 4
 5- **Build**: `go build .` or `go run .`
 6- **Test**: `task test` or `go test ./...` (run single test: `go test ./internal/llm/prompt -run TestGetContextFromPaths`)
 7- **Lint**: `task lint-fix`
 8- **Format**: `task fmt` (gofumpt -w .)
 9- **Dev**: `task dev` (runs with profiling enabled)
10
11## Code Style Guidelines
12
13- **Imports**: Use goimports formatting, group stdlib, external, internal packages
14- **Formatting**: Use gofumpt (stricter than gofmt), enabled in golangci-lint
15- **Naming**: Standard Go conventions - PascalCase for exported, camelCase for unexported
16- **Types**: Prefer explicit types, use type aliases for clarity (e.g., `type AgentName string`)
17- **Error handling**: Return errors explicitly, use `fmt.Errorf` for wrapping
18- **Context**: Always pass context.Context as first parameter for operations
19- **Interfaces**: Define interfaces in consuming packages, keep them small and focused
20- **Structs**: Use struct embedding for composition, group related fields
21- **Constants**: Use typed constants with iota for enums, group in const blocks
22- **Testing**: Use testify's `require` package, parallel tests with `t.Parallel()`,
23  `t.SetEnv()` to set environment variables. Always use `t.Tempdir()` when in
24  need of a temporary directory. This directory does not need to be removed.
25- **JSON tags**: Use snake_case for JSON field names
26- **File permissions**: Use octal notation (0o755, 0o644) for file permissions
27- **Comments**: End comments in periods unless comments are at the end of the line.
28
29## Testing with Mock Providers
30
31When writing tests that involve provider configurations, use the mock providers to avoid API calls:
32
33```go
34func TestYourFunction(t *testing.T) {
35    // Enable mock providers for testing
36    originalUseMock := config.UseMockProviders
37    config.UseMockProviders = true
38    defer func() {
39        config.UseMockProviders = originalUseMock
40        config.ResetProviders()
41    }()
42
43    // Reset providers to ensure fresh mock data
44    config.ResetProviders()
45
46    // Your test code here - providers will now return mock data
47    providers := config.Providers()
48    // ... test logic
49}
50```
51
52## Formatting
53
54- ALWAYS format any Go code you write.
55  - First, try `goftumpt -w .`.
56  - If `gofumpt` is not available, use `goimports`.
57  - If `goimports` is not available, use `gofmt`.
58  - You can also use `task fmt` to run `gofumpt -w .` on the entire project,
59    as long as `gofumpt` is on the `PATH`.