agentic-team-templates 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-team-templates",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "AI coding assistant templates for Cursor IDE. Pre-configured rules and guidelines that help AI assistants write better code. - use at your own risk",
   "keywords": [
     "cursor",

package/src/index.js

@@ -44,6 +44,10 @@ const TEMPLATES = {
     description: 'Full-stack web applications (Next.js, Nuxt, SvelteKit, Remix)',
     rules: ['api-contracts.md', 'architecture.md', 'overview.md', 'shared-types.md', 'testing.md']
   },
+  'golang-expert': {
+    description: 'Principal-level Go engineering (concurrency, stdlib, production patterns, testing)',
+    rules: ['concurrency.md', 'error-handling.md', 'interfaces-and-types.md', 'overview.md', 'performance.md', 'production-patterns.md', 'stdlib-and-tooling.md', 'testing.md']
+  },
   'javascript-expert': {
     description: 'Principal-level JavaScript engineering across Node.js, React, vanilla JS, and testing',
     rules: ['language-deep-dive.md', 'node-patterns.md', 'overview.md', 'performance.md', 'react-patterns.md', 'testing.md', 'tooling.md']

package/src/index.test.js

@@ -79,6 +79,7 @@ describe('Constants', () => {
         'devops-sre',
         'documentation',
         'fullstack',
+        'golang-expert',
         'javascript-expert',
         'ml-ai',
         'mobile',

package/templates/golang-expert/.cursorrules/concurrency.md

@@ -0,0 +1,290 @@
+# Go Concurrency
+
+Concurrency is Go's defining feature. It is also the easiest way to write bugs that are impossible to reproduce. Use it deliberately, not by default.
+
+## Fundamental Rules
+
+### 1. Don't Start a Goroutine You Can't Stop
+
+```go
+// Good: Goroutine respects context cancellation
+func (w *Worker) Run(ctx context.Context) error {
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err()
+        case job := <-w.jobs:
+            if err := w.process(ctx, job); err != nil {
+                return fmt.Errorf("processing job: %w", err)
+            }
+        }
+    }
+}
+
+// Bad: Goroutine runs forever with no way to stop it
+go func() {
+    for {
+        doWork() // No context, no signal, no way out
+    }
+}()
+```
+
+### 2. The Caller Decides Concurrency
+
+```go
+// Good: Synchronous function — caller decides whether to use goroutine
+func FetchUser(ctx context.Context, id string) (*User, error) {
+    // ...
+}
+
+// Caller makes it concurrent when needed
+go func() {
+    user, err := FetchUser(ctx, id)
+    results <- result{user, err}
+}()
+
+// Bad: Function that forces concurrency on the caller
+func FetchUserAsync(id string) <-chan *User {
+    ch := make(chan *User)
+    go func() {
+        // Caller can't pass context, can't handle errors properly
+    }()
+    return ch
+}
+```
+
+### 3. Share Memory by Communicating
+
+```go
+// Good: Channels for ownership transfer
+func generator(ctx context.Context) <-chan int {
+    ch := make(chan int)
+    go func() {
+        defer close(ch)
+        for i := 0; ; i++ {
+            select {
+            case <-ctx.Done():
+                return
+            case ch <- i:
+            }
+        }
+    }()
+    return ch
+}
+
+// Good: Mutex when protecting shared state with simple access patterns
+type SafeCounter struct {
+    mu sync.Mutex
+    v  map[string]int
+}
+
+func (c *SafeCounter) Inc(key string) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.v[key]++
+}
+```
+
+## Channel Patterns
+
+### Pipeline
+
+```go
+func pipeline(ctx context.Context, input <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for v := range input {
+            select {
+            case <-ctx.Done():
+                return
+            case out <- v * 2:
+            }
+        }
+    }()
+    return out
+}
+```
+
+### Fan-Out, Fan-In
+
+```go
+func fanOut(ctx context.Context, input <-chan Job, workers int) <-chan Result {
+    results := make(chan Result)
+    var wg sync.WaitGroup
+
+    for range workers {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for job := range input {
+                select {
+                case <-ctx.Done():
+                    return
+                case results <- process(job):
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    return results
+}
+```
+
+### Bounded Concurrency with Semaphore
+
+```go
+func processAll(ctx context.Context, items []Item, maxConcurrent int) error {
+    sem := make(chan struct{}, maxConcurrent)
+    g, ctx := errgroup.WithContext(ctx)
+
+    for _, item := range items {
+        g.Go(func() error {
+            select {
+            case sem <- struct{}{}:
+                defer func() { <-sem }()
+            case <-ctx.Done():
+                return ctx.Err()
+            }
+            return process(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+```
+
+## sync Package
+
+### sync.WaitGroup
+
+```go
+// Always Add before launching the goroutine
+var wg sync.WaitGroup
+for _, item := range items {
+    wg.Add(1)
+    go func() {
+        defer wg.Done()
+        process(item)
+    }()
+}
+wg.Wait()
+```
+
+### sync.Once
+
+```go
+// For lazy, thread-safe initialization
+type Client struct {
+    initOnce sync.Once
+    conn     *grpc.ClientConn
+}
+
+func (c *Client) getConn() *grpc.ClientConn {
+    c.initOnce.Do(func() {
+        c.conn = dial() // Only called once, even from many goroutines
+    })
+    return c.conn
+}
+```
+
+### sync.Map
+
+```go
+// Use sync.Map ONLY when:
+// 1. Keys are stable (write-once, read-many)
+// 2. Disjoint goroutines access disjoint key sets
+// Otherwise, a regular map with sync.Mutex is simpler and often faster.
+```
+
+## errgroup
+
+```go
+import "golang.org/x/sync/errgroup"
+
+func fetchAll(ctx context.Context, urls []string) ([]Response, error) {
+    g, ctx := errgroup.WithContext(ctx)
+    responses := make([]Response, len(urls))
+
+    for i, url := range urls {
+        g.Go(func() error {
+            resp, err := fetch(ctx, url)
+            if err != nil {
+                return fmt.Errorf("fetching %s: %w", url, err)
+            }
+            responses[i] = resp // Safe: each goroutine writes to its own index
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return responses, nil
+}
+```
+
+## Context
+
+```go
+// Context is the first parameter, always
+func DoWork(ctx context.Context, id string) error { ... }
+
+// Never store context in a struct
+// Bad:
+type Server struct {
+    ctx context.Context // Don't do this
+}
+
+// Derive child contexts for scoped deadlines
+ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+defer cancel() // Always defer cancel to avoid leaks
+
+// Use context values sparingly — only for request-scoped data
+// that transits process boundaries (trace IDs, auth tokens)
+// Never use context for passing optional parameters
+```
+
+## Race Condition Prevention
+
+```go
+// Always run tests with -race
+// go test -race ./...
+
+// Common race: closing over loop variable (fixed in Go 1.22+)
+// Pre-1.22, you needed:
+for _, item := range items {
+    item := item // Shadow the loop variable
+    go process(item)
+}
+// Go 1.22+ loop variables are per-iteration — no shadowing needed
+
+// Common race: reading and writing a map concurrently
+// Maps are NOT safe for concurrent use — use sync.Mutex or sync.Map
+```
+
+## Anti-Patterns
+
+```go
+// Never: Goroutine without ownership
+go doSomething() // Who waits for this? Who handles the error?
+
+// Never: time.Sleep for synchronization
+time.Sleep(100 * time.Millisecond) // Hoping goroutine finishes — use sync primitives
+
+// Never: Unbounded goroutine spawning
+for _, item := range millionItems {
+    go process(item) // OOM or file descriptor exhaustion
+}
+
+// Never: Closing a channel from the receiver side
+// Only the sender closes. Receivers check with range or ok idiom.
+
+// Never: Sending on a closed channel (panics)
+// Design your channel lifecycle so ownership is clear
+```

package/templates/golang-expert/.cursorrules/error-handling.md

@@ -0,0 +1,199 @@
+# Go Error Handling
+
+Errors in Go are values. They are the primary control flow mechanism for failure cases. Treat them with the same rigor as your business logic.
+
+## Fundamental Rules
+
+### Always Handle Errors
+
+```go
+// Good: Every error is handled
+f, err := os.Open(filename)
+if err != nil {
+    return fmt.Errorf("opening config file: %w", err)
+}
+defer f.Close()
+
+// Bad: Silently discarding errors
+f, _ := os.Open(filename) // What happens when this fails?
+
+// Bad: Logging and continuing as if nothing happened
+f, err := os.Open(filename)
+if err != nil {
+    log.Println(err) // Then what? f is nil. You'll panic below.
+}
+```
+
+### Wrap With Context Using %w
+
+```go
+// Good: Each layer adds context about what it was doing
+func (s *UserService) GetByEmail(ctx context.Context, email string) (*User, error) {
+    user, err := s.repo.FindByEmail(ctx, email)
+    if err != nil {
+        return nil, fmt.Errorf("getting user by email %q: %w", email, err)
+    }
+    return user, nil
+}
+
+// The error chain reads like a stack trace:
+// "getting user by email "bob@example.com": querying users table: sql: connection refused"
+
+// Bad: Wrapping without adding useful context
+if err != nil {
+    return fmt.Errorf("error: %w", err) // "error:" adds nothing
+}
+
+// Bad: Wrapping with redundant "failed to" prefix
+if err != nil {
+    return fmt.Errorf("failed to get user: %w", err) // "failed to" is implied — it's an error
+}
+```
+
+### Sentinel Errors and Custom Types
+
+```go
+// Use sentinel errors for conditions callers need to check
+var (
+    ErrNotFound      = errors.New("not found")
+    ErrAlreadyExists = errors.New("already exists")
+    ErrUnauthorized  = errors.New("unauthorized")
+)
+
+// Check with errors.Is
+if errors.Is(err, ErrNotFound) {
+    http.Error(w, "not found", http.StatusNotFound)
+    return
+}
+
+// Use custom error types when you need to carry structured data
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
+}
+
+// Check with errors.As
+var ve *ValidationError
+if errors.As(err, &ve) {
+    // Access ve.Field, ve.Message
+}
+```
+
+### When to Use %w vs %v
+
+```go
+// Use %w when callers should be able to unwrap and inspect the cause
+return fmt.Errorf("querying database: %w", err)
+
+// Use %v when you want to break the error chain
+// (hide implementation details across API boundaries)
+return fmt.Errorf("internal error: %v", err)
+```
+
+## Error Handling Patterns
+
+### Errors in Main
+
+```go
+func main() {
+    if err := run(); err != nil {
+        fmt.Fprintf(os.Stderr, "error: %v\n", err)
+        os.Exit(1)
+    }
+}
+
+func run() error {
+    cfg, err := loadConfig()
+    if err != nil {
+        return fmt.Errorf("loading config: %w", err)
+    }
+    // ...
+    return nil
+}
+```
+
+### Errors in HTTP Handlers
+
+```go
+// Define an application handler that returns errors
+type appHandler func(w http.ResponseWriter, r *http.Request) error
+
+func (fn appHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
+    if err := fn(w, r); err != nil {
+        var ve *ValidationError
+        switch {
+        case errors.As(err, &ve):
+            http.Error(w, ve.Message, http.StatusBadRequest)
+        case errors.Is(err, ErrNotFound):
+            http.Error(w, "not found", http.StatusNotFound)
+        case errors.Is(err, ErrUnauthorized):
+            http.Error(w, "unauthorized", http.StatusUnauthorized)
+        default:
+            // Log the full error, return generic message to client
+            slog.Error("internal error", "error", err, "path", r.URL.Path)
+            http.Error(w, "internal server error", http.StatusInternalServerError)
+        }
+    }
+}
+```
+
+### Deferred Cleanup Errors
+
+```go
+// Capture close errors from deferred calls
+func writeFile(path string, data []byte) (err error) {
+    f, err := os.Create(path)
+    if err != nil {
+        return fmt.Errorf("creating file: %w", err)
+    }
+    defer func() {
+        if closeErr := f.Close(); closeErr != nil && err == nil {
+            err = fmt.Errorf("closing file: %w", closeErr)
+        }
+    }()
+
+    if _, err := f.Write(data); err != nil {
+        return fmt.Errorf("writing data: %w", err)
+    }
+    return nil
+}
+```
+
+### Multi-Error Collection
+
+```go
+// Collect multiple errors (Go 1.20+ with errors.Join)
+func validateUser(u User) error {
+    var errs []error
+    if u.Name == "" {
+        errs = append(errs, &ValidationError{Field: "name", Message: "required"})
+    }
+    if u.Email == "" {
+        errs = append(errs, &ValidationError{Field: "email", Message: "required"})
+    }
+    return errors.Join(errs...)
+}
+```
+
+## Anti-Patterns
+
+```go
+// Never: panic for expected error conditions
+func MustParse(s string) Config {
+    // Only acceptable in init() or test helpers, never in request paths
+    panic("don't do this in production code paths")
+}
+
+// Never: Checking error strings
+if err.Error() == "not found" { } // Fragile — use errors.Is or errors.As
+
+// Never: Returning both a value and an error that are both valid
+// If err != nil, the other return values should be zero values
+
+// Never: Using naked returns in functions with error handling
+// Named returns for error capture in defer is the one acceptable use
+```