feat: initial release of go-coldbrew/workers

Worker lifecycle library built on thejerf/suture with:
- Worker struct with builder pattern (NewWorker, WithRestart, Every,
  WithFailureBackoff, WithFailureThreshold, WithFailureDecay,
  WithBackoffJitter, WithTimeout)
- WorkerContext interface extending context.Context with Name(),
  Attempt(), Add(), Remove(), Children() for dynamic worker management
- Every worker is a supervisor subtree — scoped child lifecycle
- Tracing via go-coldbrew/tracing (OTEL spans per worker execution)
- Logging via go-coldbrew/log
- Helpers: EveryInterval, ChannelWorker, BatchChannelWorker
- Run(ctx, []*Worker) and RunWorker(ctx, *Worker) entry points
- 12 examples including dynamic worker pool reconciliation
- GitHub Actions CI (build, test, lint)

Author: ankurs

.github/workflows/go.yml

@@ -0,0 +1,54 @@
+# This workflow will build a golang project
+# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-go
+
+name: Go
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    branches: [ "main" ]
+
+permissions:
+  contents: read
+
+jobs:
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+    - name: Set up Go
+      uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+      with:
+        go-version-file: go.mod
+
+    - name: Build
+      run: make build
+
+  test:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+    - name: Set up Go
+      uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+      with:
+        go-version-file: go.mod
+
+    - name: Test
+      run: make test
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+    - name: Set up Go
+      uses: actions/setup-go@40f1582b2485089dde7abd97c1529aa768e1baff # v5
+      with:
+        go-version-file: go.mod
+
+    - name: Lint
+      run: make lint

.golangci.yml

@@ -0,0 +1,28 @@
+version: "2"
+linters:
+  exclusions:
+    generated: lax
+    presets:
+      - comments
+      - common-false-positives
+      - legacy
+      - std-error-handling
+    rules:
+      - linters:
+          - funlen
+          - goconst
+          - errcheck
+          - ineffassign
+          - staticcheck
+        path: (.+)_test\.go
+    paths:
+      - third_party$
+      - builtin$
+      - examples$
+formatters:
+  exclusions:
+    generated: lax
+    paths:
+      - third_party$
+      - builtin$
+      - examples$

AGENTS.md

@@ -0,0 +1,57 @@
+# AGENTS.md
+
+## Package Overview
+
+`go-coldbrew/workers` is a worker lifecycle library built on [thejerf/suture](https://github.com/thejerf/suture). It manages background goroutines with panic recovery, configurable restart, tracing, and structured shutdown.
+
+## Build & Test
+
+```bash
+make build    # go build ./...
+make test     # go test -race ./...
+make lint     # golangci-lint + govulncheck
+make bench    # benchmarks
+make doc      # regenerate README.md via gomarkdoc
+```
+
+## Architecture
+
+Every worker runs inside its own suture supervisor subtree:
+
+```
+Root Supervisor (created by Run)
+├── Worker-A supervisor
+│   ├── Worker-A run func
+│   ├── Child-A1 supervisor (added via ctx.Add)
+│   │   └── Child-A1 run func
+│   └── Child-A2 supervisor
+│       └── Child-A2 run func
+└── Worker-B supervisor
+    └── Worker-B run func
+```
+
+Key properties:
+- **Scoped lifecycle**: when a parent stops, all children stop
+- **Independent restart**: each worker restarts independently via suture
+- **Panic recovery**: suture catches panics and converts to errors
+- **Backoff**: configurable exponential backoff with jitter on restart
+- **Tracing**: each worker execution gets an OTEL span via `go-coldbrew/tracing`
+
+## Key Types
+
+- `Worker` — struct with builder pattern (`NewWorker().WithRestart().Every()`)
+- `WorkerContext` — extends `context.Context` with `Name()`, `Attempt()`, `Add()`, `Remove()`, `Children()`
+- `Run(ctx, []*Worker) error` — starts all workers, blocks until ctx cancelled
+- `RunWorker(ctx, *Worker)` — runs a single worker
+
+## Helpers
+
+- `EveryInterval(d, fn)` — periodic ticker loop
+- `ChannelWorker[T](ch, fn)` — consume from channel
+- `BatchChannelWorker[T](ch, maxSize, maxDelay, fn)` — batch with size/timer flush
+
+## Rules
+
+- Always run `make doc` after changing exported APIs or docstrings
+- Always run `make test` and `make lint` before committing
+- Don't add `replace` directives to go.mod

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Makefile

@@ -0,0 +1,16 @@
+.PHONY: build test doc lint bench
+build:
+	go build ./...
+
+test:
+	go test -race ./...
+
+doc:
+	go tool gomarkdoc --output '{{.Dir}}/README.md' ./...
+
+lint:
+	go tool golangci-lint run
+	go tool govulncheck ./...
+
+bench:
+	go test -run=^$$ -bench=. -benchmem ./...