go-stack

Go Stack Standard (Go 1.26+)

Canonical guidelines for Go development: project scaffolding, libraries, CLI/TUI tools, web apps (GOTH), and ADK agents.

1. Core & Quality Stack

• Go Version: Target latest stable (Go 1.26+). Adopt current idioms mechanically — run go fix ./... (modernizers) and gofumpt rather than hand-porting.
• Dependency & Tooling: Manage heavy standalone CLI tools via mise.toml (mise.toml) — golangci-lint (v2+), lefthook, gotestsum, air (web live reload), esbuild (web asset bundling) — to prevent go.mod dependency bloat and compile errors. Reserve the native tool directive in go.mod (Go 1.24+) for code generators and small Go-native utilities invoked as go tool <name> — templ, goimports, gofumpt, govulncheck (plus sqlc, gomodifytags, impl on demand).
• Task Runner & Hooks: Use mise.toml (mise.toml) for commands (install, format, check, test, build, watch) per the mise skill. Use lefthook (lefthook.yml) for pre-commit (format → check:leaks --staged → check) and pre-push (test) per the lefthook skill. Order the hook commands with explicit priority (formatters low, check high) so formatters restage before check reads the files — lefthook sorts alphabetically otherwise.
• Linting & Formatting: Clean markdown/JSON/YAML with dprint using the configuration maintained by the dprint skill. Format Go files with goimports/gofumpt. Enforce zero-warning rule with golangci-lint (golangci.yml).
• Testing: Standard library testing (starters stay dependency-free); reach for stretchr/testify when you want richer assertions. Run with gotestsum.
  • Use testing/synctest (Go 1.25+) for deterministic concurrent testing (virtualized clocks).
• Logging: Use standard log/slog. Local: slog.TextHandler (or charmbracelet/log) with dynamic slog.LevelVar. Production: slog.JSONHandler with OpenTelemetry span/trace context propagation.
• Diagnostics & Observability: Standardize on OpenTelemetry (otel) for traces — wired for web and agents only, not CLIs. The web starter's SetupOTel (telemetry.go) installs an OTLP/HTTP exporter and wraps the router in otelhttp for per-request spans; OtelHandler then stamps the active trace_id/span_id onto every slog record. Tracing activates only when OTEL_EXPORTER_OTLP_ENDPOINT is set, so local runs stay quiet. ADK agents inherit tracing from the launcher (same OTLP env var, or --otel_to_cloud for GCP Cloud Trace). For deep local debugging, runtime/trace.FlightRecorder (Go 1.25+) keeps a rolling in-memory trace to dump on error/panic.
• Container Awareness: Go 1.25+ is cgroups/container-aware—GOMAXPROCS aligns automatically (do not use automaxprocs).
• Omit Zero Struct Tags: Use native json:",omitzero" (Go 1.24+) on structs/types (e.g., time.Time) instead of omitempty.