agentic-team-templates 0.11.0 → 0.12.1

package/templates/golang-expert/.cursorrules/production-patterns.md

@@ -0,0 +1,320 @@
+# Go Production Patterns
+
+Patterns for building Go services that run reliably in production.
+
+## Application Lifecycle
+
+### The run() Pattern
+
+```go
+func main() {
+    ctx, cancel := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+    defer cancel()
+
+    if err := run(ctx, os.Stdout, os.Args[1:]); err != nil {
+        fmt.Fprintf(os.Stderr, "error: %v\n", err)
+        os.Exit(1)
+    }
+}
+
+func run(ctx context.Context, stdout io.Writer, args []string) error {
+    cfg, err := loadConfig()
+    if err != nil {
+        return fmt.Errorf("loading config: %w", err)
+    }
+
+    logger := slog.New(slog.NewJSONHandler(stdout, nil))
+    db, err := connectDB(ctx, cfg.DatabaseURL)
+    if err != nil {
+        return fmt.Errorf("connecting to database: %w", err)
+    }
+    defer db.Close()
+
+    srv := NewServer(logger, db)
+    httpSrv := &http.Server{
+        Addr:    cfg.Addr,
+        Handler: srv,
+    }
+
+    // Start server in background
+    go func() {
+        logger.Info("server starting", "addr", cfg.Addr)
+        if err := httpSrv.ListenAndServe(); err != nil && !errors.Is(err, http.ErrServerClosed) {
+            logger.Error("server error", "error", err)
+        }
+    }()
+
+    // Wait for shutdown signal
+    <-ctx.Done()
+    logger.Info("shutting down")
+
+    shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+    defer cancel()
+
+    return httpSrv.Shutdown(shutdownCtx)
+}
+```
+
+### Dependency Injection
+
+```go
+// Wire dependencies explicitly in main/run — no magic, no frameworks
+func run(ctx context.Context) error {
+    // Infrastructure
+    db := connectDB(cfg.DatabaseURL)
+    cache := redis.New(cfg.RedisURL)
+
+    // Repositories
+    userRepo := postgres.NewUserRepo(db)
+    orderRepo := postgres.NewOrderRepo(db)
+
+    // Services
+    userSvc := service.NewUserService(userRepo, cache)
+    orderSvc := service.NewOrderService(orderRepo, userSvc)
+
+    // Handlers
+    handler := handler.New(userSvc, orderSvc)
+
+    // Server
+    srv := &http.Server{Handler: handler}
+    return srv.ListenAndServe()
+}
+```
+
+## Configuration
+
+```go
+// Validate all configuration at startup — fail fast
+type Config struct {
+    Addr        string        `env:"ADDR" default:":8080"`
+    DatabaseURL string        `env:"DATABASE_URL,required"`
+    LogLevel    slog.Level    `env:"LOG_LEVEL" default:"info"`
+    Timeout     time.Duration `env:"TIMEOUT" default:"30s"`
+}
+
+func loadConfig() (*Config, error) {
+    cfg := &Config{}
+    // Parse from env...
+
+    // Validate
+    if cfg.DatabaseURL == "" {
+        return nil, errors.New("DATABASE_URL is required")
+    }
+    if cfg.Timeout <= 0 {
+        return nil, errors.New("TIMEOUT must be positive")
+    }
+    return cfg, nil
+}
+```
+
+## Health Checks
+
+```go
+func (s *Server) handleHealthz(w http.ResponseWriter, r *http.Request) {
+    ctx, cancel := context.WithTimeout(r.Context(), 2*time.Second)
+    defer cancel()
+
+    checks := map[string]error{
+        "database": s.db.PingContext(ctx),
+        "cache":    s.cache.Ping(ctx),
+    }
+
+    status := http.StatusOK
+    result := make(map[string]string, len(checks))
+    for name, err := range checks {
+        if err != nil {
+            status = http.StatusServiceUnavailable
+            result[name] = err.Error()
+        } else {
+            result[name] = "ok"
+        }
+    }
+
+    w.Header().Set("Content-Type", "application/json")
+    w.WriteHeader(status)
+    json.NewEncoder(w).Encode(result)
+}
+```
+
+## Observability
+
+### Structured Logging
+
+```go
+// Use slog with consistent field names
+logger.Info("request completed",
+    "method", r.Method,
+    "path", r.URL.Path,
+    "status", status,
+    "duration_ms", time.Since(start).Milliseconds(),
+    "request_id", middleware.RequestID(r.Context()),
+)
+
+// Log levels have meaning:
+// Debug: Development-only information
+// Info: Normal operations worth recording
+// Warn: Something unexpected but handled
+// Error: Something failed and needs attention
+
+// Never log sensitive data (passwords, tokens, PII)
+// Never log at Error level for expected conditions (404, validation failures)
+```
+
+### Metrics
+
+```go
+import "github.com/prometheus/client_golang/prometheus"
+
+var (
+    httpRequestsTotal = prometheus.NewCounterVec(
+        prometheus.CounterOpts{
+            Name: "http_requests_total",
+            Help: "Total number of HTTP requests",
+        },
+        []string{"method", "path", "status"},
+    )
+
+    httpRequestDuration = prometheus.NewHistogramVec(
+        prometheus.HistogramOpts{
+            Name:    "http_request_duration_seconds",
+            Help:    "HTTP request duration in seconds",
+            Buckets: prometheus.DefBuckets,
+        },
+        []string{"method", "path"},
+    )
+)
+
+func init() {
+    prometheus.MustRegister(httpRequestsTotal, httpRequestDuration)
+}
+```
+
+## Graceful Degradation
+
+```go
+// Circuit breaker for external dependencies
+type CircuitBreaker struct {
+    mu          sync.Mutex
+    failures    int
+    threshold   int
+    resetAfter  time.Duration
+    lastFailure time.Time
+    state       string // "closed", "open", "half-open"
+}
+
+func (cb *CircuitBreaker) Execute(fn func() error) error {
+    cb.mu.Lock()
+    if cb.state == "open" {
+        if time.Since(cb.lastFailure) > cb.resetAfter {
+            cb.state = "half-open"
+        } else {
+            cb.mu.Unlock()
+            return ErrCircuitOpen
+        }
+    }
+    cb.mu.Unlock()
+
+    err := fn()
+
+    cb.mu.Lock()
+    defer cb.mu.Unlock()
+    if err != nil {
+        cb.failures++
+        cb.lastFailure = time.Now()
+        if cb.failures >= cb.threshold {
+            cb.state = "open"
+        }
+        return err
+    }
+
+    cb.failures = 0
+    cb.state = "closed"
+    return nil
+}
+```
+
+## Retry with Backoff
+
+```go
+func RetryWithBackoff(ctx context.Context, maxAttempts int, base time.Duration, fn func() error) error {
+    var err error
+    for attempt := range maxAttempts {
+        err = fn()
+        if err == nil {
+            return nil
+        }
+
+        if attempt == maxAttempts-1 {
+            break
+        }
+
+        // Exponential backoff with jitter
+        backoff := base * time.Duration(1<<uint(attempt))
+        jitter := time.Duration(rand.Int64N(int64(backoff) / 2))
+        wait := backoff + jitter
+
+        select {
+        case <-ctx.Done():
+            return ctx.Err()
+        case <-time.After(wait):
+        }
+    }
+    return fmt.Errorf("after %d attempts: %w", maxAttempts, err)
+}
+```
+
+## Database Patterns
+
+```go
+// Repository pattern with transactions
+type TxFunc func(ctx context.Context, tx *sql.Tx) error
+
+func WithTransaction(ctx context.Context, db *sql.DB, fn TxFunc) error {
+    tx, err := db.BeginTx(ctx, nil)
+    if err != nil {
+        return fmt.Errorf("beginning transaction: %w", err)
+    }
+
+    if err := fn(ctx, tx); err != nil {
+        if rbErr := tx.Rollback(); rbErr != nil {
+            return fmt.Errorf("rolling back: %w (original: %v)", rbErr, err)
+        }
+        return err
+    }
+
+    if err := tx.Commit(); err != nil {
+        return fmt.Errorf("committing transaction: %w", err)
+    }
+    return nil
+}
+
+// Usage
+err := WithTransaction(ctx, db, func(ctx context.Context, tx *sql.Tx) error {
+    if err := createOrder(ctx, tx, order); err != nil {
+        return err
+    }
+    return updateInventory(ctx, tx, order.Items)
+})
+```
+
+## Anti-Patterns
+
+```go
+// Never: Global mutable state
+var db *sql.DB // Package-level mutable state makes testing impossible
+
+// Never: init() for complex initialization
+func init() {
+    db, _ = sql.Open(...) // Errors swallowed, untestable, order-dependent
+}
+
+// Never: Shared context.Background() in request handlers
+func handler(w http.ResponseWriter, r *http.Request) {
+    db.QueryContext(context.Background(), ...) // Ignores request cancellation!
+    // Use r.Context() instead
+}
+
+// Never: Unbounded work queues
+ch := make(chan Job) // Unbuffered or unbounded — will block or OOM
+// Use bounded channels and handle backpressure explicitly
+```

package/templates/golang-expert/.cursorrules/stdlib-and-tooling.md

@@ -0,0 +1,276 @@
+# Go Standard Library and Tooling
+
+The standard library is Go's greatest asset. Know it deeply before reaching for third-party packages.
+
+## Essential stdlib Packages
+
+### net/http
+
+```go
+// The stdlib HTTP server is production-ready. You rarely need a framework.
+mux := http.NewServeMux()
+
+mux.HandleFunc("GET /users/{id}", getUser)
+mux.HandleFunc("POST /users", createUser)
+mux.HandleFunc("GET /healthz", healthCheck)
+
+srv := &http.Server{
+    Addr:         ":8080",
+    Handler:      mux,
+    ReadTimeout:  10 * time.Second,
+    WriteTimeout: 10 * time.Second,
+    IdleTimeout:  120 * time.Second,
+}
+
+// Always set timeouts — an http.Server with no timeouts will leak goroutines
+```
+
+### Middleware Pattern
+
+```go
+// Middleware is just a function that wraps an http.Handler
+func Logging(logger *slog.Logger) func(http.Handler) http.Handler {
+    return func(next http.Handler) http.Handler {
+        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+            start := time.Now()
+            wrapped := &responseRecorder{ResponseWriter: w, statusCode: http.StatusOK}
+
+            next.ServeHTTP(wrapped, r)
+
+            logger.Info("request",
+                "method", r.Method,
+                "path", r.URL.Path,
+                "status", wrapped.statusCode,
+                "duration", time.Since(start),
+            )
+        })
+    }
+}
+
+type responseRecorder struct {
+    http.ResponseWriter
+    statusCode int
+}
+
+func (r *responseRecorder) WriteHeader(code int) {
+    r.statusCode = code
+    r.ResponseWriter.WriteHeader(code)
+}
+
+// Chain middleware
+handler := Logging(logger)(Recovery()(Auth(secret)(mux)))
+```
+
+### encoding/json
+
+```go
+// Struct tags control serialization
+type User struct {
+    ID        string    `json:"id"`
+    Email     string    `json:"email"`
+    Name      string    `json:"name,omitempty"`
+    CreatedAt time.Time `json:"created_at"`
+    password  string    // unexported — never serialized
+}
+
+// Use json.NewDecoder for streams, json.Unmarshal for []byte
+func decodeBody(r *http.Request, v any) error {
+    dec := json.NewDecoder(r.Body)
+    dec.DisallowUnknownFields() // Reject unexpected fields
+    if err := dec.Decode(v); err != nil {
+        return fmt.Errorf("decoding request body: %w", err)
+    }
+    return nil
+}
+```
+
+### log/slog (Go 1.21+)
+
+```go
+// slog is the standard structured logger — use it
+logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
+    Level: slog.LevelInfo,
+}))
+
+logger.Info("server starting", "addr", addr, "version", version)
+logger.Error("query failed", "error", err, "query", query)
+
+// Add context to a sub-logger
+reqLogger := logger.With("request_id", requestID, "user_id", userID)
+reqLogger.Info("processing request")
+```
+
+### context
+
+```go
+// Context carries deadlines, cancellation signals, and request-scoped values
+// across API boundaries and goroutines
+
+// Timeouts
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel()
+
+result, err := db.QueryContext(ctx, query)
+
+// Values — sparingly, for request-scoped cross-cutting concerns only
+type contextKey string
+const requestIDKey contextKey = "request_id"
+
+func WithRequestID(ctx context.Context, id string) context.Context {
+    return context.WithValue(ctx, requestIDKey, id)
+}
+
+func RequestID(ctx context.Context) string {
+    id, _ := ctx.Value(requestIDKey).(string)
+    return id
+}
+```
+
+### io and io/fs
+
+```go
+// io.Reader and io.Writer are the universal interfaces
+// If your function accepts io.Reader, it works with:
+// - files, HTTP bodies, buffers, strings, gzip streams, network connections...
+
+func CountLines(r io.Reader) (int, error) {
+    scanner := bufio.NewScanner(r)
+    count := 0
+    for scanner.Scan() {
+        count++
+    }
+    return count, scanner.Err()
+}
+
+// Works with anything
+CountLines(os.Stdin)
+CountLines(strings.NewReader("hello\nworld"))
+CountLines(resp.Body)
+
+// io/fs for filesystem abstraction (Go 1.16+)
+func LoadTemplates(fsys fs.FS) (*template.Template, error) {
+    return template.ParseFS(fsys, "templates/*.html")
+}
+
+// Production: os.DirFS("./templates")
+// Tests: fstest.MapFS{"templates/index.html": {Data: []byte("...")}}
+```
+
+### time
+
+```go
+// Always use time.Duration for durations, never raw int64
+func Retry(attempts int, delay time.Duration, fn func() error) error { ... }
+
+// Use time.NewTicker, not time.Tick (Tick leaks)
+ticker := time.NewTicker(30 * time.Second)
+defer ticker.Stop()
+
+// Use monotonic clock for elapsed time (time.Since does this automatically)
+start := time.Now()
+doWork()
+elapsed := time.Since(start) // Monotonic, not affected by clock adjustments
+
+// Parse and format with the reference time: Mon Jan 2 15:04:05 MST 2006
+t, err := time.Parse("2006-01-02", "2025-03-15")
+s := t.Format(time.RFC3339)
+```
+
+## Toolchain
+
+### Essential Commands
+
+```bash
+# Build and run
+go build ./...          # Compile all packages
+go run ./cmd/myapp      # Compile and execute
+go install ./cmd/myapp  # Install binary to $GOBIN
+
+# Testing
+go test ./...           # Run all tests
+go test -race ./...     # Run with race detector (always in CI)
+go test -count=1 ./...  # Disable test caching
+go test -short ./...    # Skip long-running tests
+go test -cover ./...    # Show coverage percentage
+go test -coverprofile=coverage.out ./... && go tool cover -html=coverage.out
+
+# Vetting
+go vet ./...            # Official static analysis
+
+# Modules
+go mod tidy             # Remove unused, add missing dependencies
+go mod verify           # Verify dependency checksums
+go mod why <module>     # Explain why a dependency is needed
+```
+
+### Linters
+
+```yaml
+# .golangci-lint.yml — recommended configuration
+linters:
+  enable:
+    - errcheck          # Check that errors are handled
+    - govet             # Official Go vet checks
+    - staticcheck       # The gold standard static analyzer
+    - unused            # Find unused code
+    - gosimple          # Simplify code
+    - ineffassign       # Detect ineffectual assignments
+    - gocritic          # Opinionated style checks
+    - revive            # Fast, configurable linter
+    - misspell          # Find common spelling mistakes
+    - prealloc          # Suggest preallocating slices
+    - unconvert         # Remove unnecessary type conversions
+    - errname           # Check error variable naming conventions
+    - errorlint         # Check error handling idioms
+
+linters-settings:
+  errcheck:
+    check-type-assertions: true
+    check-blank: true
+  gocritic:
+    enabled-tags:
+      - diagnostic
+      - style
+      - performance
+```
+
+### Makefile
+
+```makefile
+.PHONY: build test lint vet check
+
+build:
+	go build ./...
+
+test:
+	go test -race -count=1 ./...
+
+lint:
+	golangci-lint run
+
+vet:
+	go vet ./...
+	staticcheck ./...
+
+check: vet lint test
+
+cover:
+	go test -coverprofile=coverage.out ./...
+	go tool cover -html=coverage.out -o coverage.html
+```
+
+## When to Use Third-Party Packages
+
+Use the stdlib unless:
+- The stdlib genuinely lacks the capability (e.g., database drivers, protocol buffers)
+- A well-maintained package provides significantly better ergonomics for a complex domain (e.g., `sqlc` for SQL, `chi` for routing in complex APIs)
+- The package is from the Go team's extended ecosystem (`golang.org/x/...`)
+
+Respected packages in the ecosystem:
+- **Router**: `net/http` (Go 1.22+ patterns), `chi` for complex routing
+- **SQL**: `sqlc`, `pgx`, `database/sql` with driver
+- **Testing**: `go-cmp`, `testify` (use sparingly — stdlib is usually enough)
+- **CLI**: `cobra`, `kong`
+- **Config**: `envconfig`, `viper`
+- **Observability**: `prometheus/client_golang`, `opentelemetry-go`
+- **Concurrency**: `golang.org/x/sync/errgroup`, `golang.org/x/sync/semaphore`