devflow-kit 1.0.0 → 1.2.0

package/plugins/devflow-core-skills/skills/test-driven-development/references/rationalization-prevention.md

@@ -0,0 +1,111 @@
+# TDD Rationalization Prevention — Extended Examples
+
+Detailed code examples showing how each rationalization leads to worse outcomes.
+
+## "I'll write tests after"
+
+### What happens:
+
+```typescript
+// Developer writes production code first
+function calculateDiscount(price: number, tier: string): number {
+  if (tier === 'gold') return price * 0.8;
+  if (tier === 'silver') return price * 0.9;
+  return price;
+}
+
+// Then "writes tests after" — but only for the happy path they remember
+test('gold tier gets 20% off', () => {
+  expect(calculateDiscount(100, 'gold')).toBe(80);
+});
+// Missing: negative prices, unknown tiers, zero prices, NaN handling
+```
+
+### What TDD would have caught:
+
+```typescript
+// Test first — forces you to think about the contract
+test('returns error for negative price', () => {
+  expect(calculateDiscount(-100, 'gold')).toEqual({ ok: false, error: 'NEGATIVE_PRICE' });
+});
+// Now the interface includes error handling from the start
+```
+
+## "Too simple to test"
+
+### What happens:
+
+```typescript
+// "It's just a config getter, no test needed"
+function getMaxRetries(): number {
+  return parseInt(process.env.MAX_RETRIES || '3');
+}
+// 6 months later: someone sets MAX_RETRIES="three" and prod crashes with NaN retries
+```
+
+### What TDD would have caught:
+
+```typescript
+test('returns default when env var is not a number', () => {
+  process.env.MAX_RETRIES = 'three';
+  expect(getMaxRetries()).toBe(3); // Forces validation logic
+});
+```
+
+## "Test is too hard to write"
+
+### What happens:
+
+```typescript
+// "I can't test this easily because it needs database + email + filesystem"
+async function processOrder(orderId: string) {
+  const db = new Database();
+  const order = await db.find(orderId);
+  await sendEmail(order.customerEmail, 'Your order is processing');
+  await fs.writeFile(`/invoices/${orderId}.pdf`, generateInvoice(order));
+  await db.update(orderId, { status: 'processing' });
+}
+// Result: untestable monolith, test would need real DB + email + filesystem
+```
+
+### What TDD forces:
+
+```typescript
+// Hard-to-test = bad design. TDD forces dependency injection:
+async function processOrder(
+  orderId: string,
+  deps: { db: OrderRepository; emailer: Emailer; invoices: InvoiceStore }
+): Promise<Result<void, OrderError>> {
+  // Now trivially testable with mocks
+}
+```
+
+## "I'll refactor later"
+
+### What happens:
+
+```typescript
+// Sprint 1: "just get it working"
+function handleRequest(req: any) {
+  if (req.type === 'create') { /* 50 lines */ }
+  else if (req.type === 'update') { /* 50 lines */ }
+  else if (req.type === 'delete') { /* 30 lines */ }
+  // Sprint 2-10: more conditions added, function grows to 500 lines
+  // "Refactor later" never comes because nobody wants to touch it
+}
+```
+
+### What TDD enforces:
+
+Step 3 (REFACTOR) happens every cycle. The function never grows beyond what's clean because you clean it every 5-10 minutes.
+
+## "Tests slow me down"
+
+### The math:
+
+| Approach | Time to write | Time to first bug | Time to fix bug | Total (1 month) |
+|----------|:---:|:---:|:---:|:---:|
+| No TDD | 2h | 4h | 3h (no repro test) | 9h+ |
+| TDD | 3h | Caught in test | 15min (test pinpoints) | 3h 15min |
+
+TDD is slower for the first 30 minutes. It's faster for everything after that.

package/plugins/devflow-debug/.claude-plugin/plugin.json

@@ -5,7 +5,7 @@
     "name": "DevFlow Contributors",
     "email": "dean@keren.dev"
   },
-  "version": "1.0.0",
+  "version": "1.2.0",
   "homepage": "https://github.com/dean0x/devflow",
   "repository": "https://github.com/dean0x/devflow",
   "license": "MIT",

package/plugins/devflow-frontend-design/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "devflow-frontend-design",
+  "description": "Frontend design patterns - typography, color systems, spacing, motion, responsive design",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.2.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["design", "typography", "color", "css"],
+  "agents": [],
+  "skills": ["frontend-design"]
+}

package/plugins/devflow-go/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "devflow-go",
+  "description": "Go language patterns - error handling, interfaces, concurrency, package design",
+  "author": {
+    "name": "DevFlow Contributors",
+    "email": "dean@keren.dev"
+  },
+  "version": "1.2.0",
+  "homepage": "https://github.com/dean0x/devflow",
+  "repository": "https://github.com/dean0x/devflow",
+  "license": "MIT",
+  "keywords": ["go", "golang", "concurrency", "errors"],
+  "agents": [],
+  "skills": ["go"]
+}

package/plugins/devflow-go/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/plugins/devflow-go/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
+}
+```