devflow-kit 1.0.0 → 1.2.0

package/shared/skills/go/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: go
+description: This skill should be used when the user works with Go files (.go), asks about "error handling", "interfaces", "goroutines", "channels", "packages", or discusses Go idioms and concurrency. Provides patterns for error handling, interface design, concurrency, and package organization.
+user-invocable: false
+allowed-tools: Read, Grep, Glob
+activation:
+  file-patterns:
+    - "**/*.go"
+  exclude:
+    - "vendor/**"
+---
+
+# Go Patterns
+
+Reference for Go-specific patterns, idioms, and best practices.
+
+## Iron Law
+
+> **ERRORS ARE VALUES**
+>
+> Never ignore errors. `if err != nil` is correctness, not boilerplate. Every error
+> return must be checked, wrapped with context, or explicitly documented as intentionally
+> ignored with `_ = fn()`. Silent error swallowing causes cascading failures.
+
+## When This Skill Activates
+
+- Working with Go codebases
+- Designing interfaces and packages
+- Implementing concurrent code
+- Handling errors
+- Structuring Go projects
+
+---
+
+## Error Handling
+
+### Wrap Errors with Context
+
+```go
+// BAD: return err
+// GOOD: return fmt.Errorf("reading config %s: %w", path, err)
+```
+
+### Sentinel Errors for Expected Conditions
+
+```go
+var ErrNotFound = errors.New("not found")
+
+func FindUser(id string) (*User, error) {
+    u, err := db.Get(id)
+    if err != nil {
+        return nil, fmt.Errorf("finding user %s: %w", id, err)
+    }
+    if u == nil {
+        return nil, ErrNotFound
+    }
+    return u, nil
+}
+// Caller: if errors.Is(err, ErrNotFound) { ... }
+```
+
+---
+
+## Interface Design
+
+### Accept Interfaces, Return Structs
+
+```go
+// BAD: func NewService(repo *PostgresRepo) *Service
+// GOOD: func NewService(repo Repository) *Service
+
+type Repository interface {
+    FindByID(ctx context.Context, id string) (*Entity, error)
+    Save(ctx context.Context, entity *Entity) error
+}
+```
+
+### Keep Interfaces Small
+
+```go
+// BAD: 10-method interface
+// GOOD: single-method interfaces composed as needed
+type Reader interface { Read(p []byte) (n int, err error) }
+type Writer interface { Write(p []byte) (n int, err error) }
+type ReadWriter interface { Reader; Writer }
+```
+
+---
+
+## Concurrency
+
+### Use Context for Cancellation
+
+```go
+func Process(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    for _, item := range items {
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+    return g.Wait()
+}
+```
+
+### Channel Direction
+
+```go
+// Declare direction in function signatures
+func producer(ch chan<- int) { ch <- 42 }
+func consumer(ch <-chan int) { v := <-ch; _ = v }
+```
+
+---
+
+## Package Design
+
+### Organize by Domain, Not by Type
+
+```go
+// BAD: models/, controllers/, services/
+// GOOD: user/, order/, payment/
+```
+
+### Export Only What's Needed
+
+```go
+// Internal helpers stay unexported (lowercase)
+func (s *Service) validate(u *User) error { ... }
+
+// Public API is exported (uppercase)
+func (s *Service) CreateUser(ctx context.Context, req CreateUserReq) (*User, error) { ... }
+```
+
+---
+
+## Zero Values
+
+```go
+// Use zero values as valid defaults
+var mu sync.Mutex     // Ready to use
+var buf bytes.Buffer  // Ready to use
+var wg sync.WaitGroup // Ready to use
+
+// Design types with useful zero values
+type Config struct {
+    Timeout time.Duration // zero = no timeout
+    Retries int           // zero = no retries
+}
+```
+
+---
+
+## Anti-Patterns
+
+| Pattern | Bad | Good |
+|---------|-----|------|
+| Ignoring error | `val, _ := fn()` | `val, err := fn(); if err != nil { ... }` |
+| Naked return | `return` in named returns | Explicit `return val, err` |
+| init() abuse | Complex `init()` functions | Explicit initialization in `main()` or constructors |
+| Interface pollution | Defining interfaces before use | Define interfaces at the consumer site |
+| Goroutine leak | `go fn()` without lifecycle | Use context, errgroup, or done channels |
+
+---
+
+## Extended References
+
+For additional patterns and examples:
+- `references/violations.md` - Common Go violations
+- `references/patterns.md` - Extended Go patterns
+- `references/detection.md` - Detection patterns for Go issues
+- `references/concurrency.md` - Advanced concurrency patterns
+
+---
+
+## Checklist
+
+- [ ] All errors checked or explicitly ignored with `_ =`
+- [ ] Errors wrapped with `fmt.Errorf("context: %w", err)`
+- [ ] Interfaces defined at consumer, not producer
+- [ ] Interfaces kept small (1-3 methods)
+- [ ] Context passed as first parameter
+- [ ] Goroutines have clear lifecycle/cancellation
+- [ ] Channel direction specified in signatures
+- [ ] Zero values are useful defaults
+- [ ] Packages organized by domain
+- [ ] No `init()` with side effects

package/shared/skills/go/references/concurrency.md

@@ -0,0 +1,312 @@
+# Go Concurrency Patterns
+
+Advanced concurrency patterns for Go. Reference from main SKILL.md.
+
+## errgroup for Structured Concurrency
+
+```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 unique index
+            return nil
+        })
+    }
+
+    if err := g.Wait(); err != nil {
+        return nil, err
+    }
+    return responses, nil
+}
+```
+
+### errgroup with Concurrency Limit
+
+```go
+func ProcessItems(ctx context.Context, items []Item) error {
+    g, ctx := errgroup.WithContext(ctx)
+    g.SetLimit(10) // Maximum 10 concurrent goroutines
+
+    for _, item := range items {
+        g.Go(func() error {
+            return processItem(ctx, item)
+        })
+    }
+
+    return g.Wait()
+}
+```
+
+---
+
+## Worker Pool
+
+```go
+func WorkerPool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
+    results := make(chan Result, workers)
+
+    var wg sync.WaitGroup
+    for range workers {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for {
+                select {
+                case job, ok := <-jobs:
+                    if !ok {
+                        return
+                    }
+                    results <- process(ctx, job)
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    return results
+}
+
+// Usage
+jobs := make(chan Job, 100)
+results := WorkerPool(ctx, jobs, 5)
+
+// Send jobs
+go func() {
+    defer close(jobs)
+    for _, j := range allJobs {
+        jobs <- j
+    }
+}()
+
+// Collect results
+for r := range results {
+    fmt.Println(r)
+}
+```
+
+---
+
+## Fan-Out / Fan-In
+
+```go
+// Fan-out: one source, multiple workers
+func fanOut(ctx context.Context, input <-chan int, workers int) []<-chan int {
+    channels := make([]<-chan int, workers)
+    for i := range workers {
+        channels[i] = worker(ctx, input)
+    }
+    return channels
+}
+
+func worker(ctx context.Context, input <-chan int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for n := range input {
+            select {
+            case out <- n * n:
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+
+// Fan-in: multiple sources, one destination
+func fanIn(ctx context.Context, channels ...<-chan int) <-chan int {
+    merged := make(chan int)
+    var wg sync.WaitGroup
+
+    for _, ch := range channels {
+        wg.Add(1)
+        go func() {
+            defer wg.Done()
+            for val := range ch {
+                select {
+                case merged <- val:
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(merged)
+    }()
+
+    return merged
+}
+```
+
+---
+
+## Select with Timeout
+
+```go
+func fetchWithTimeout(ctx context.Context, url string) ([]byte, error) {
+    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
+    defer cancel()
+
+    ch := make(chan result, 1)
+    go func() {
+        data, err := doFetch(ctx, url)
+        ch <- result{data, err}
+    }()
+
+    select {
+    case r := <-ch:
+        return r.data, r.err
+    case <-ctx.Done():
+        return nil, fmt.Errorf("fetch %s: %w", url, ctx.Err())
+    }
+}
+
+type result struct {
+    data []byte
+    err  error
+}
+```
+
+### Select for Multiple Sources
+
+```go
+func merge(ctx context.Context, primary, fallback <-chan Event) <-chan Event {
+    out := make(chan Event)
+    go func() {
+        defer close(out)
+        for {
+            select {
+            case e, ok := <-primary:
+                if !ok {
+                    return
+                }
+                out <- e
+            case e, ok := <-fallback:
+                if !ok {
+                    return
+                }
+                out <- e
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+```
+
+---
+
+## Mutex vs Channels
+
+### Use Mutex When
+
+```go
+// Protecting shared state with simple read/write
+type SafeCounter struct {
+    mu sync.RWMutex
+    v  map[string]int
+}
+
+func (c *SafeCounter) Inc(key string) {
+    c.mu.Lock()
+    defer c.mu.Unlock()
+    c.v[key]++
+}
+
+func (c *SafeCounter) Get(key string) int {
+    c.mu.RLock()
+    defer c.mu.RUnlock()
+    return c.v[key]
+}
+```
+
+### Use Channels When
+
+```go
+// Communicating between goroutines / coordinating work
+func pipeline(ctx context.Context, input []int) <-chan int {
+    out := make(chan int)
+    go func() {
+        defer close(out)
+        for _, n := range input {
+            select {
+            case out <- transform(n):
+            case <-ctx.Done():
+                return
+            }
+        }
+    }()
+    return out
+}
+```
+
+### Decision Guide
+
+| Scenario | Use |
+|----------|-----|
+| Guarding shared state | `sync.Mutex` or `sync.RWMutex` |
+| Passing ownership of data | Channels |
+| Coordinating goroutine lifecycle | `context.Context` + channels |
+| Waiting for N goroutines | `sync.WaitGroup` or `errgroup` |
+| One-time initialization | `sync.Once` |
+| Concurrent map access | `sync.Map` (high read, low write) |
+
+---
+
+## sync.Once for Initialization
+
+```go
+type Client struct {
+    once sync.Once
+    conn *grpc.ClientConn
+    err  error
+}
+
+func (c *Client) connection() (*grpc.ClientConn, error) {
+    c.once.Do(func() {
+        // requires: "google.golang.org/grpc/credentials/insecure"
+        c.conn, c.err = grpc.Dial("localhost:50051",
+            grpc.WithTransportCredentials(insecure.NewCredentials()))
+    })
+    return c.conn, c.err
+}
+```
+
+---
+
+## Rate Limiting
+
+```go
+func rateLimited(ctx context.Context, items []Item, rps int) error {
+    limiter := rate.NewLimiter(rate.Limit(rps), 1)
+
+    for _, item := range items {
+        if err := limiter.Wait(ctx); err != nil {
+            return fmt.Errorf("rate limiter: %w", err)
+        }
+        if err := process(ctx, item); err != nil {
+            return fmt.Errorf("processing item %s: %w", item.ID, err)
+        }
+    }
+    return nil
+}
+```

package/shared/skills/go/references/detection.md

@@ -0,0 +1,129 @@
+# Go Issue Detection
+
+Grep and regex patterns for finding common Go issues. Reference from main SKILL.md.
+
+## Error Handling Detection
+
+### Unchecked Errors
+
+```bash
+# Find ignored error returns (blank identifier)
+grep -rn ', _ := ' --include='*.go' .
+grep -rn ', _ = ' --include='*.go' .
+
+# Find bare error returns without wrapping
+grep -rn 'return.*err$' --include='*.go' . | grep -v 'fmt.Errorf' | grep -v ':= err'
+
+# Find deferred calls that return errors (Close, Flush, Sync)
+grep -rn 'defer.*\.Close()' --include='*.go' .
+grep -rn 'defer.*\.Flush()' --include='*.go' .
+```
+
+### Missing Error Context
+
+```bash
+# Find raw error returns (no wrapping)
+grep -rn 'return nil, err$' --include='*.go' .
+grep -rn 'return err$' --include='*.go' .
+```
+
+---
+
+## Concurrency Detection
+
+### Goroutine Without Context
+
+```bash
+# Find goroutines that don't reference ctx
+grep -rn 'go func()' --include='*.go' .
+
+# Find goroutines without done/cancel/ctx
+grep -B5 -A10 'go func' --include='*.go' . | grep -L 'ctx\|done\|cancel\|errgroup'
+```
+
+### Potential Goroutine Leaks
+
+```bash
+# Find unbuffered channel creation followed by goroutine
+grep -rn 'make(chan ' --include='*.go' . | grep -v ', [0-9]'
+
+# Find goroutines with infinite loops
+grep -A5 'go func' --include='*.go' . | grep 'for {'
+```
+
+---
+
+## Interface Detection
+
+### Empty Interface Usage
+
+```bash
+# Find empty interface (pre-1.18 style)
+grep -rn 'interface{}' --include='*.go' .
+
+# Find any type (1.18+ style) - may be intentional, review context
+grep -rn '\bany\b' --include='*.go' . | grep -v '_test.go' | grep -v 'vendor/'
+```
+
+### Large Interfaces
+
+```bash
+# Find interface declarations and count methods (interfaces > 5 methods)
+grep -B1 -A20 'type.*interface {' --include='*.go' .
+```
+
+---
+
+## Panic Detection
+
+### Panic in Library Code
+
+```bash
+# Find panic calls outside main/test
+grep -rn 'panic(' --include='*.go' . | grep -v '_test.go' | grep -v 'main.go'
+
+# Find log.Fatal (calls os.Exit) in library code
+grep -rn 'log.Fatal' --include='*.go' . | grep -v 'main.go' | grep -v '_test.go'
+
+# Find os.Exit in library code
+grep -rn 'os.Exit' --include='*.go' . | grep -v 'main.go' | grep -v '_test.go'
+```
+
+---
+
+## init() Detection
+
+```bash
+# Find all init functions
+grep -rn '^func init()' --include='*.go' .
+
+# Find init functions with side effects (network, file, global state)
+grep -A10 '^func init()' --include='*.go' . | grep -E 'http\.|sql\.|os\.|Open|Dial|Connect'
+```
+
+---
+
+## Mutex and Race Detection
+
+```bash
+# Find mutex passed by value (function params with Mutex, not pointer)
+grep -rn 'func.*sync\.Mutex[^*]' --include='*.go' .
+
+# Find Lock without corresponding Unlock
+grep -rn '\.Lock()' --include='*.go' . | grep -v 'defer.*Unlock'
+
+# Find RLock without RUnlock
+grep -rn '\.RLock()' --include='*.go' . | grep -v 'defer.*RUnlock'
+```
+
+---
+
+## Map and Slice Safety
+
+```bash
+# Find uninitialized map declarations (potential nil map panic)
+grep -rn 'var.*map\[' --include='*.go' . | grep -v 'make\|:='
+
+# Find slice append without pre-allocation hint
+grep -rn 'append(' --include='*.go' . | head -20
+```