@dv.nghiem/flowdeck 0.1.0

package/src/skills/golang-patterns/SKILL.md

@@ -0,0 +1,511 @@
+---
+name: golang-patterns
+description: Idiomatic Go patterns covering error handling, interfaces, goroutines, channels, testing, and common pitfalls. Activate when writing or reviewing Go code.
+origin: FlowDeck
+---
+
+# Go Patterns Skill
+
+Idiomatic Go for production systems. Focuses on simplicity, explicitness, and composition.
+
+## When to Activate
+
+Activate when:
+- Writing new Go packages or services
+- Reviewing Go code for idiom and correctness
+- Designing concurrent processing pipelines
+- Debugging goroutine leaks or race conditions
+- Setting up module structure or build configuration
+
+## Error Handling
+
+Go errors are values. Handle them at the point where you have enough context to act.
+
+### Wrapping and Unwrapping
+
+```go
+import "errors"
+import "fmt"
+
+// Wrap with %w to preserve the chain
+func loadConfig(path string) (*Config, error) {
+    data, err := os.ReadFile(path)
+    if err != nil {
+        return nil, fmt.Errorf("loadConfig %q: %w", path, err)
+    }
+    // ...
+}
+
+// Inspect with errors.Is (sentinel) and errors.As (type)
+var ErrNotFound = errors.New("not found")
+
+if err := loadConfig("app.yaml"); err != nil {
+    if errors.Is(err, os.ErrNotExist) {
+        // file missing
+    }
+    var pathErr *os.PathError
+    if errors.As(err, &pathErr) {
+        log.Printf("path problem: %s", pathErr.Path)
+    }
+}
+```
+
+### Sentinel Errors
+
+```go
+// Define at package level, exported when callers need to check
+var (
+    ErrNotFound   = errors.New("not found")
+    ErrPermission = errors.New("permission denied")
+)
+
+// Prefer typed errors when you need to attach data
+type ValidationError struct {
+    Field   string
+    Message string
+}
+
+func (e *ValidationError) Error() string {
+    return fmt.Sprintf("validation: %s %s", e.Field, e.Message)
+}
+```
+
+### Error String Conventions
+
+```go
+// ✅ lowercase, no trailing punctuation
+errors.New("connection refused")
+fmt.Errorf("user %d not found", id)
+
+// ❌ uppercase or punctuation
+errors.New("Connection refused.")
+```
+
+## Interface Design
+
+Keep interfaces small. A one-method interface is a feature, not a limitation.
+
+### The io.Reader / io.Writer Pattern
+
+```go
+// Standard library interfaces — use them where they fit
+type Reader interface {
+    Read(p []byte) (n int, err error)
+}
+
+type Writer interface {
+    Write(p []byte) (n int, err error)
+}
+
+// Compose for more complex contracts
+type ReadWriter interface {
+    Reader
+    Writer
+}
+
+// Accept interfaces, return concrete types
+func Process(r io.Reader) ([]byte, error) {
+    return io.ReadAll(r)
+}
+
+// os.File, bytes.Buffer, http.Response.Body all satisfy io.Reader
+```
+
+### Define Interfaces at the Consumer
+
+```go
+// ❌ Defining in the producer package forces coupling
+package store
+type Repository interface { ... }  // in the store package
+
+// ✅ Define in the consumer package
+package service
+type userStore interface {
+    FindByID(ctx context.Context, id int64) (*User, error)
+    Save(ctx context.Context, u *User) error
+}
+
+type UserService struct {
+    store userStore
+}
+```
+
+### Single-Method Naming
+
+```go
+// Verb + "er" for single-method interfaces
+type Reader interface { Read(...) }
+type Writer interface { Write(...) }
+type Stringer interface { String() string }
+type Closer interface { Close() error }
+type Handler interface { ServeHTTP(...) }
+```
+
+## Goroutines and Channels
+
+### Worker Pool Pattern
+
+```go
+func workerPool(ctx context.Context, jobs <-chan Job, workers int) <-chan Result {
+    results := make(chan Result)
+
+    var wg sync.WaitGroup
+    wg.Add(workers)
+    for range workers {
+        go func() {
+            defer wg.Done()
+            for job := range jobs {
+                select {
+                case results <- process(job):
+                case <-ctx.Done():
+                    return
+                }
+            }
+        }()
+    }
+
+    go func() {
+        wg.Wait()
+        close(results)
+    }()
+
+    return results
+}
+```
+
+### Fan-Out / Fan-In
+
+```go
+// Fan-out: send work to N goroutines
+func fanOut(in <-chan int, n int) []<-chan int {
+    outs := make([]<-chan int, n)
+    for i := range n {
+        ch := make(chan int)
+        outs[i] = ch
+        go func() {
+            defer close(ch)
+            for v := range in {
+                ch <- v * 2
+            }
+        }()
+    }
+    return outs
+}
+
+// Fan-in: merge N channels into one
+func merge(channels ...<-chan int) <-chan int {
+    out := make(chan int)
+    var wg sync.WaitGroup
+    wg.Add(len(channels))
+    for _, ch := range channels {
+        go func(c <-chan int) {
+            defer wg.Done()
+            for v := range c {
+                out <- v
+            }
+        }(ch)
+    }
+    go func() {
+        wg.Wait()
+        close(out)
+    }()
+    return out
+}
+```
+
+### Select and Context Cancellation
+
+```go
+func doWork(ctx context.Context) error {
+    ticker := time.NewTicker(500 * time.Millisecond)
+    defer ticker.Stop()
+
+    for {
+        select {
+        case <-ctx.Done():
+            return ctx.Err()
+        case t := <-ticker.C:
+            if err := tick(t); err != nil {
+                return fmt.Errorf("tick: %w", err)
+            }
+        }
+    }
+}
+```
+
+### Channel Ownership Rule
+
+The goroutine that creates a channel is responsible for closing it. Closing a channel from a reader or having multiple goroutines close the same channel causes panics.
+
+## Struct Embedding vs Composition
+
+### Embedding for Behaviour Promotion
+
+```go
+type Logger struct {
+    level string
+}
+
+func (l *Logger) Log(msg string) {
+    fmt.Printf("[%s] %s\n", l.level, msg)
+}
+
+type Server struct {
+    Logger           // promotes Log method
+    addr   string
+}
+
+s := Server{Logger: Logger{level: "INFO"}, addr: ":8080"}
+s.Log("starting")   // calls s.Logger.Log
+```
+
+### Prefer Explicit Fields for Data
+
+```go
+// ❌ Embedding for data models creates implicit API surface
+type FullUser struct {
+    User    // every User field/method becomes part of FullUser's API
+    Profile
+}
+
+// ✅ Explicit fields make dependencies obvious
+type FullUser struct {
+    User    User
+    Profile Profile
+}
+```
+
+## defer, panic, recover
+
+### defer — Always for Cleanup
+
+```go
+func writeFile(path string, data []byte) error {
+    f, err := os.Create(path)
+    if err != nil {
+        return err
+    }
+    defer f.Close()  // runs even if Write returns error
+
+    _, err = f.Write(data)
+    return err
+}
+
+// defer evaluates arguments immediately — useful for timing
+func trace(name string) func() {
+    start := time.Now()
+    return func() { log.Printf("%s: %v", name, time.Since(start)) }
+}
+defer trace("expensiveOp")()
+```
+
+### panic / recover — Only at Boundaries
+
+```go
+// Use panic only for programmer errors (invariant violations)
+func mustPositive(n int) int {
+    if n <= 0 {
+        panic(fmt.Sprintf("expected positive, got %d", n))
+    }
+    return n
+}
+
+// Recover at the top of a goroutine or HTTP handler to convert to error
+func safeExec(fn func()) (err error) {
+    defer func() {
+        if r := recover(); r != nil {
+            err = fmt.Errorf("panic: %v", r)
+        }
+    }()
+    fn()
+    return nil
+}
+```
+
+Never use panic/recover as a substitute for regular error handling.
+
+## Table-Driven Tests
+
+```go
+func TestParseDate(t *testing.T) {
+    cases := []struct {
+        name    string
+        input   string
+        want    time.Time
+        wantErr bool
+    }{
+        {
+            name:  "ISO format",
+            input: "2024-01-15",
+            want:  time.Date(2024, 1, 15, 0, 0, 0, 0, time.UTC),
+        },
+        {
+            name:    "empty string",
+            input:   "",
+            wantErr: true,
+        },
+        {
+            name:    "invalid format",
+            input:   "15/01/2024",
+            wantErr: true,
+        },
+    }
+
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            got, err := ParseDate(tc.input)
+            if (err != nil) != tc.wantErr {
+                t.Fatalf("ParseDate(%q) error = %v, wantErr %v", tc.input, err, tc.wantErr)
+            }
+            if !tc.wantErr && !got.Equal(tc.want) {
+                t.Errorf("ParseDate(%q) = %v, want %v", tc.input, got, tc.want)
+            }
+        })
+    }
+}
+```
+
+## Go Modules
+
+### go.mod Structure
+
+```
+module github.com/org/myservice
+
+go 1.23
+
+require (
+    github.com/some/dep v1.2.3
+)
+```
+
+### Workspace Mode (go.work) for Multi-Module Repos
+
+```
+go 1.23
+
+use (
+    ./cmd/api
+    ./internal/core
+    ./pkg/client
+)
+```
+
+```bash
+go work init ./cmd/api ./internal/core
+go work use ./pkg/client
+```
+
+### Module Commands
+
+```bash
+go mod tidy          # add missing, remove unused
+go mod vendor        # copy deps to vendor/
+go get github.com/x@v1.2.3  # add or upgrade
+go mod why github.com/x     # explain why dep is needed
+```
+
+## sync Package
+
+```go
+var mu sync.Mutex
+mu.Lock()
+defer mu.Unlock()
+
+// RWMutex — many readers, one writer
+var rw sync.RWMutex
+rw.RLock()
+defer rw.RUnlock()
+
+// WaitGroup — wait for goroutines to finish
+var wg sync.WaitGroup
+wg.Add(1)
+go func() {
+    defer wg.Done()
+    // ...
+}()
+wg.Wait()
+
+// Once — run exactly once (e.g., lazy init)
+var once sync.Once
+var instance *DB
+func getDB() *DB {
+    once.Do(func() { instance = newDB() })
+    return instance
+}
+
+// Atomic operations — simple counters without a mutex
+var counter atomic.Int64
+counter.Add(1)
+n := counter.Load()
+```
+
+## Build Tags
+
+```go
+//go:build linux && amd64
+
+package platform
+
+// This file only compiles on 64-bit Linux.
+func pageSize() int { return 4096 }
+```
+
+```bash
+go build -tags integration ./...
+go test -tags integration ./...
+```
+
+## Common Pitfalls
+
+### Goroutine Leaks
+
+```go
+// ❌ Nothing reads from results — goroutines block forever
+func leak() {
+    results := make(chan int)
+    go func() { results <- compute() }()
+    // forgot to read results
+}
+
+// ✅ Always ensure goroutines can exit — use buffered channels or context
+func noLeak(ctx context.Context) {
+    results := make(chan int, 1)
+    go func() {
+        select {
+        case results <- compute():
+        case <-ctx.Done():
+        }
+    }()
+}
+```
+
+### nil Interface vs nil Pointer
+
+```go
+// ❌ Returning a typed nil as an interface is NOT nil
+func getErr() error {
+    var p *os.PathError = nil
+    return p  // error interface is not nil!
+}
+
+// ✅ Return untyped nil
+func getErr() error {
+    return nil
+}
+```
+
+### Map Race Conditions
+
+```go
+// ❌ Concurrent read/write on map causes data race
+m := map[string]int{}
+go func() { m["a"] = 1 }()
+go func() { _ = m["a"] }()
+
+// ✅ Use sync.Map or protect with a mutex
+var mu sync.RWMutex
+mu.Lock()
+m["a"] = 1
+mu.Unlock()
+```

package/src/skills/human-review-routing/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: human-review-routing
+description: Route risky patches to the right reviewer type — security, backend, infra, or domain owner — based on the nature of the change and its patch trust score.
+origin: FlowDeck
+---
+
+# Human Review Routing
+
+When a patch is flagged as `review-required` or `high-risk` by the Patch Trust Score, it must be routed to the right human reviewer. This skill defines the routing logic.
+
+## Reviewer Types and Triggers
+
+| Reviewer | Triggered by |
+|----------|-------------|
+| security | auth, token, password, crypto, secret, jwt, permission, rbac, xss, sql |
+| backend | api, route, controller, service, database, query, migration |
+| infra | docker, kubernetes, terraform, ci, cd, deploy, helm, nginx, aws, gcp |
+| domain-owner | business, billing, payment, checkout, order, subscription, pricing |
+| frontend | component, css, html, react, vue, ui, ux, style |
+| data | schema, migration, model, index, constraint, foreign key |
+| devops | pipeline, workflow, .yml, .yaml, action, cron, schedule |
+
+## Routing Logic
+
+1. Scan the changed file paths and change description for keywords from the table above
+2. Check the Patch Trust Score verdict
+3. **High-risk** always adds `security` to the reviewer list
+4. Multiple reviewer types can be assigned to one patch
+5. If no keywords match and verdict is `safe`, route to `general-reviewer`
+
+## Workflow
+
+Run `/review-route` with `--files` and `--change` to get the routing decision.
+
+Example:
+```
+/review-route {"files": "src/services/auth.ts,src/api/payment.ts", "change": "refactor JWT validation"}
+```
+Output:
+```
+Route to: security, backend, domain-owner
+Trust verdict: review-required
+```
+
+## Review Request Format
+
+When routing a patch, include:
+```markdown
+## Review Request
+
+**Patch**: [brief description]
+**Files**: [list]
+**Trust Score**: [score] ([verdict])
+**Route to**: [reviewer types]
+**Reason**: [why this routing]
+**Deadline**: [if blocking release]
+
+### Key areas to check
+- [specific concern 1]
+- [specific concern 2]
+```
+
+## Escalation
+
+If no appropriate reviewer is available within 24h, escalate to the tech lead. Never merge a `high-risk` patch without at least one human approval.

package/src/skills/intent-translator/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: intent-translator
+description: Convert vague requests like "make checkout faster" into concrete, ranked implementation options with tradeoffs before coding starts.
+origin: FlowDeck
+---
+
+# Intent-to-Change Translator
+
+Run `/translate-intent` with a plain-language description of what you want. Get back a ranked menu of concrete implementation options with tradeoffs — before writing a single line of code.
+
+## When to Activate
+
+- The request is vague ("make it faster", "improve reliability", "clean this up")
+- Multiple valid approaches exist and the choice has significant consequences
+- The user hasn't specified which files or systems to touch
+
+## Workflow
+
+1. Parse the intent: what outcome is the user seeking?
+2. Search the codebase for relevant context:
+   - What does the system currently do in this area?
+   - What are the bottlenecks or pain points?
+3. Generate ≤5 concrete implementation options, each with:
+   - **Name**: short label
+   - **Description**: 1–2 sentences of what it does
+   - **Files affected**: list of files to touch
+   - **Effort**: S (hours) / M (1–2 days) / L (week+)
+   - **Risk**: low / medium / high
+   - **Tradeoffs**: what you gain and what you give up
+4. Rank options by impact-to-effort ratio (best first)
+5. Ask clarifying questions if the intent is still ambiguous after step 2
+
+## Output Format
+
+```markdown
+## Intent Translation: "[original intent]"
+
+### Option 1 (Recommended): [Name]
+**Description**: [what it does]
+**Files**: [list]
+**Effort**: S | M | L  **Risk**: low | medium | high
+**Tradeoffs**: ✅ [gain] | ⚠️ [cost]
+
+### Option 2: [Name]
+...
+
+### Clarifying Questions (if needed)
+1. [question]
+
+### Recommendation
+Proceed with **Option 1** because [reason].
+To start: run `/plan` after confirming your choice.
+```
+
+## Confidence Rule
+
+If the intent could mean two fundamentally different things, list both interpretations explicitly and ask the user to choose BEFORE generating options. Do not guess silently.