devflow-kit 1.8.2 → 2.0.0

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

@@ -1,312 +0,0 @@
-# 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

@@ -1,129 +0,0 @@
-# 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
-```

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

@@ -1,232 +0,0 @@
-# Go Correct Patterns
-
-Extended correct patterns for Go development. Reference from main SKILL.md.
-
-## Table-Driven Tests
-
-```go
-func TestAdd(t *testing.T) {
-    tests := []struct {
-        name     string
-        a, b     int
-        expected int
-    }{
-        {"positive numbers", 2, 3, 5},
-        {"negative numbers", -1, -2, -3},
-        {"zero", 0, 0, 0},
-        {"mixed signs", -1, 3, 2},
-    }
-
-    for _, tt := range tests {
-        t.Run(tt.name, func(t *testing.T) {
-            result := Add(tt.a, tt.b)
-            if result != tt.expected {
-                t.Errorf("Add(%d, %d) = %d, want %d", tt.a, tt.b, result, tt.expected)
-            }
-        })
-    }
-}
-```
-
----
-
-## Functional Options
-
-```go
-type Server struct {
-    addr    string
-    timeout time.Duration
-    logger  *slog.Logger
-}
-
-type Option func(*Server)
-
-func WithAddr(addr string) Option {
-    return func(s *Server) { s.addr = addr }
-}
-
-func WithTimeout(d time.Duration) Option {
-    return func(s *Server) { s.timeout = d }
-}
-
-func WithLogger(l *slog.Logger) Option {
-    return func(s *Server) { s.logger = l }
-}
-
-func NewServer(opts ...Option) *Server {
-    s := &Server{
-        addr:    ":8080",           // sensible default
-        timeout: 30 * time.Second,  // sensible default
-        logger:  slog.Default(),
-    }
-    for _, opt := range opts {
-        opt(s)
-    }
-    return s
-}
-
-// Usage
-srv := NewServer(
-    WithAddr(":9090"),
-    WithTimeout(60 * time.Second),
-)
-```
-
----
-
-## Custom Error Types
-
-```go
-type ValidationError struct {
-    Field   string
-    Message string
-}
-
-func (e *ValidationError) Error() string {
-    return fmt.Sprintf("validation failed on %s: %s", e.Field, e.Message)
-}
-
-type NotFoundError struct {
-    Resource string
-    ID       string
-}
-
-func (e *NotFoundError) Error() string {
-    return fmt.Sprintf("%s %s not found", e.Resource, e.ID)
-}
-
-// Usage with errors.As
-func handleErr(err error) {
-    var validErr *ValidationError
-    if errors.As(err, &validErr) {
-        log.Printf("bad input: field=%s msg=%s", validErr.Field, validErr.Message)
-        return
-    }
-    var notFound *NotFoundError
-    if errors.As(err, &notFound) {
-        log.Printf("missing: %s/%s", notFound.Resource, notFound.ID)
-        return
-    }
-    log.Printf("unexpected: %v", err)
-}
-```
-
----
-
-## Middleware Pattern
-
-```go
-type Middleware func(http.Handler) http.Handler
-
-func Logging(logger *slog.Logger) Middleware {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            start := time.Now()
-            next.ServeHTTP(w, r)
-            logger.Info("request",
-                "method", r.Method,
-                "path", r.URL.Path,
-                "duration", time.Since(start),
-            )
-        })
-    }
-}
-
-func Recovery() Middleware {
-    return func(next http.Handler) http.Handler {
-        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-            defer func() {
-                if err := recover(); err != nil {
-                    w.WriteHeader(http.StatusInternalServerError)
-                    slog.Error("panic recovered", "error", err)
-                }
-            }()
-            next.ServeHTTP(w, r)
-        })
-    }
-}
-
-// Chain composes middleware in order
-func Chain(handler http.Handler, middlewares ...Middleware) http.Handler {
-    for i := len(middlewares) - 1; i >= 0; i-- {
-        handler = middlewares[i](handler)
-    }
-    return handler
-}
-
-// Usage
-mux := http.NewServeMux()
-mux.HandleFunc("/api/users", handleUsers)
-handler := Chain(mux, Recovery(), Logging(logger))
-```
-
----
-
-## Graceful Shutdown
-
-```go
-func main() {
-    srv := &http.Server{Addr: ":8080", Handler: mux}
-
-    go func() {
-        if err := srv.ListenAndServe(); err != http.ErrServerClosed {
-            slog.Error("server error", "error", err)
-        }
-    }()
-
-    quit := make(chan os.Signal, 1)
-    signal.Notify(quit, syscall.SIGINT, syscall.SIGTERM)
-    <-quit
-
-    ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
-    defer cancel()
-
-    if err := srv.Shutdown(ctx); err != nil {
-        slog.Error("shutdown error", "error", err)
-    }
-    slog.Info("server stopped")
-}
-```
-
----
-
-## Constructor Pattern
-
-```go
-// Validate at construction - enforce invariants
-func NewUser(name, email string) (*User, error) {
-    if name == "" {
-        return nil, &ValidationError{Field: "name", Message: "required"}
-    }
-    if !strings.Contains(email, "@") {
-        return nil, &ValidationError{Field: "email", Message: "invalid format"}
-    }
-    return &User{
-        ID:        uuid.New().String(),
-        Name:      name,
-        Email:     email,
-        CreatedAt: time.Now(),
-    }, nil
-}
-```
-
----
-
-## Structured Logging with slog
-
-```go
-func ProcessOrder(ctx context.Context, orderID string) error {
-    logger := slog.With("order_id", orderID, "trace_id", traceID(ctx))
-
-    logger.Info("processing order")
-
-    items, err := fetchItems(ctx, orderID)
-    if err != nil {
-        logger.Error("failed to fetch items", "error", err)
-        return fmt.Errorf("fetching items for order %s: %w", orderID, err)
-    }
-
-    logger.Info("items fetched", "count", len(items))
-    return nil
-}
-```