coding-os 0.3.2__py3-none-any.whl

templates/go-fiber/scaffold/docs/engineering/fiber-rules.md

@@ -0,0 +1,97 @@
+<!-- domain:BACKEND | layer:reference | ssot:true | updated:{{DATE}} -->
+# Fiber Engineering Rules
+
+Purpose: Canonical rules for Fiber v3 backend code in this project.
+Read when: Writing or reviewing any Go file under `src/backend/`.
+Skip when: Task is frontend-only or infra-only (no Fiber code).
+Read next: `docs/playbooks/fiber-service.md`, `docs/api-contracts/error-format.md`
+
+> Nav: [Docs Index](../00-index.md)
+
+## Handler Contract
+
+Every handler returns `error` and follows this shape:
+
+1. **Parse** — `c.Bind().Body()` / `c.Bind().Query()` / `c.Bind().URI()` (v3 binding API). On parse failure return `fiber.NewError(400, "invalid body")`.
+2. **Validate** — `validate.Struct(&dto)` with `go-playground/validator` tags. Failure → `fiber.NewError(422, err.Error())`.
+3. **Delegate** — call a service with `c.Context()`.
+4. **Respond** — `c.Status(code).JSON(payload)` for success, `return err` for failure (the central `ErrorHandler` renders the envelope).
+
+No handler calls the database directly. No handler runs business logic inline.
+
+## Error Envelope
+
+Every non-2xx response MUST match `docs/api-contracts/error-format.md`:
+
+```json
+{
+  "error": {
+    "code":    "unprocessable_entity",
+    "message": "email: invalid format",
+    "details": { "field": "email", "constraint": "email" }
+  }
+}
+```
+
+The central `ErrorHandler` wired into `fiber.New(fiber.Config{ErrorHandler: ...})` is the ONLY place response status codes are mapped to slugs. Service and handler code returns typed errors (`fmt.Errorf("…: %w", domain.ErrNotFound)`), not HTTP codes.
+
+## Context Propagation
+
+- `c.Context()` (v3 returns the request `context.Context`) is the *only* context passed into downstream calls.
+- Never `context.Background()` inside a handler scope — cancellations must flow from client disconnect all the way to the DB driver.
+- Background workers get their own root context, cancelled via `app.ShutdownWithContext`.
+
+## Middleware Order (fixed)
+
+```
+recover → requestid → logger → cors → compress → auth (per-group) → route
+```
+
+Business logic never lives in middleware. Middleware handles only: panic recovery, correlation, structured logging, CORS, compression, auth. Everything else is a service concern.
+
+## Request DTOs
+
+- Separate DTO types per endpoint (`CreateOrderDTO`, `UpdateOrderDTO`) — do NOT reuse domain models as request bodies.
+- DTOs carry `validate` tags; domain models carry business invariants.
+- The service receives the *validated* DTO and returns a domain type — not the DTO.
+
+## Database Access
+
+- Repositories own SQL. Never a query in a service or handler.
+- Pool lifetime matches the app: injected via constructor, closed in `defer` before `ShutdownWithContext` returns.
+- Prepared statements for hot-path queries — use `sqlx`, `pgx`, or `ent` consistently per project, never mixed.
+- Transactions start at the service boundary, not the repository — commit/rollback decision belongs to business logic.
+
+## Testing
+
+- `app.Test(httptest.NewRequest(...))` is the canonical pattern — no external server, no HTTP client.
+- Every handler ships with a table-driven test covering happy + at least two error paths (validation failure, service error).
+- Test fixtures live in `testdata/`; reset the DB via `testmain.go` global setup, not per-test.
+- No mocks for `fiber.Ctx` — use the real app through `app.Test()`.
+
+## Project Layout
+
+```
+src/backend/
+├── cmd/api/main.go                    # app.Listen + shutdown
+├── internal/
+│   ├── handlers/<domain>.go           # Fiber handlers
+│   ├── services/<domain>.go           # business logic
+│   ├── repositories/<domain>_pg.go    # DB adapter
+│   ├── models/<domain>.go             # domain types
+│   └── middleware/{auth,logging}.go
+├── pkg/                               # cross-service helpers (rare)
+├── go.mod / go.sum
+└── testdata/
+```
+
+`handlers → services → repositories → models` is the only allowed dependency direction. Back-edges break the architecture.
+
+## Forbidden Patterns
+
+- Parsing a body without validating it
+- Calling `fiber.NewError(500, ...)` for a business error (use typed error + central handler)
+- Using `context.Background()` inside a handler
+- Package-level `var db *sql.DB`
+- Goroutine launched from a handler without a cancellation path
+- Skipping `recover` middleware (one panic kills the whole server)

templates/go-fiber/scaffold/docs/playbooks/fiber-service.md

@@ -0,0 +1,149 @@
+<!-- domain:BACKEND | layer:playbook | ssot:true | updated:{{DATE}} -->
+# Fiber Service Playbook
+
+Purpose: End-to-end workflow for adding or changing a Fiber HTTP endpoint.
+Read when: Starting any task that touches `src/backend/internal/handlers/**` or adds a new route group.
+Skip when: Task is infra-only, test-only, or doesn't touch HTTP surface.
+Read next: `docs/engineering/fiber-rules.md`, `docs/api-contracts/error-format.md`
+
+> Nav: [Docs Index](../00-index.md)
+
+## Read-Pack (max 6 files)
+
+1. `docs/playbooks/fiber-service.md` — this playbook
+2. `docs/engineering/fiber-rules.md` — rules
+3. `docs/api-contracts/error-format.md` — error envelope
+4. `src/backend/internal/handlers/<existing-similar>.go` — closest existing handler
+5. `src/backend/internal/services/<existing-similar>.go` — its service
+6. `src/backend/cmd/api/main.go` — where the route is registered
+
+Do not read more than these. If something's missing, grep for it.
+
+## Ordered Steps
+
+### 1 — Define the DTO
+
+Add a typed request + response struct in `internal/handlers/<domain>_dto.go`:
+
+```go
+type CreateOrderRequest struct {
+    UserID   string  `json:"user_id"   validate:"required,uuid4"`
+    Amount   float64 `json:"amount"    validate:"required,gt=0"`
+    Currency string  `json:"currency"  validate:"required,len=3,uppercase"`
+}
+
+type CreateOrderResponse struct {
+    ID        string    `json:"id"`
+    Status    string    `json:"status"`
+    CreatedAt time.Time `json:"created_at"`
+}
+```
+
+### 2 — Write the service method
+
+`internal/services/orders.go`:
+
+```go
+func (s *Orders) Create(ctx context.Context, dto CreateOrderRequest) (*model.Order, error) {
+    if err := s.users.Exists(ctx, dto.UserID); err != nil {
+        return nil, fmt.Errorf("users.Exists: %w", err)
+    }
+    order := model.NewOrder(dto.UserID, dto.Amount, dto.Currency)
+    if err := s.repo.Insert(ctx, order); err != nil {
+        return nil, fmt.Errorf("repo.Insert: %w", err)
+    }
+    return order, nil
+}
+```
+
+Errors wrap with `%w` so the central handler + `errors.Is` work.
+
+### 3 — Write the handler
+
+`internal/handlers/orders.go`:
+
+```go
+func CreateOrder(svc *service.Orders) fiber.Handler {
+    return func(c fiber.Ctx) error {
+        var req CreateOrderRequest
+        if err := c.Bind().Body(&req); err != nil {
+            return fiber.NewError(fiber.StatusBadRequest, "invalid body")
+        }
+        if err := validate.Struct(&req); err != nil {
+            return fiber.NewError(fiber.StatusUnprocessableEntity, err.Error())
+        }
+        order, err := svc.Create(c.Context(), req)
+        if err != nil {
+            return err
+        }
+        return c.Status(fiber.StatusCreated).JSON(CreateOrderResponse{
+            ID:        order.ID,
+            Status:    order.Status,
+            CreatedAt: order.CreatedAt,
+        })
+    }
+}
+```
+
+### 4 — Register the route
+
+`cmd/api/main.go`:
+
+```go
+orders := app.Group("/api/orders", middleware.Auth(jwt))
+orders.Post("/", handlers.CreateOrder(services.Orders))
+```
+
+### 5 — Write the table-driven test
+
+`internal/handlers/orders_test.go`:
+
+```go
+func TestCreateOrder(t *testing.T) {
+    cases := []struct {
+        name   string
+        body   string
+        status int
+    }{
+        {"ok",         `{"user_id":"…","amount":10.5,"currency":"USD"}`, 201},
+        {"bad_json",   `{`,                                              400},
+        {"bad_amount", `{"user_id":"…","amount":-1,"currency":"USD"}`,   422},
+    }
+    app := newTestApp(t)
+    for _, tc := range cases {
+        t.Run(tc.name, func(t *testing.T) {
+            req := httptest.NewRequest("POST", "/api/orders", strings.NewReader(tc.body))
+            req.Header.Set("Content-Type", "application/json")
+            req.Header.Set("Authorization", "Bearer "+testJWT(t))
+
+            res, err := app.Test(req, fiber.TestConfig{Timeout: 2 * time.Second})
+            require.NoError(t, err)
+            assert.Equal(t, tc.status, res.StatusCode)
+        })
+    }
+}
+```
+
+### 6 — Verify
+
+```
+cd backend && go vet ./... && go test ./...
+```
+
+Any `vet` warning is a blocker. Any test failure is a blocker.
+
+## Common Gotchas
+
+- **Parse then validate** — never return from `c.Bind().Body()` failure without `validate.Struct`. A valid JSON with garbage field values binds cleanly but fails `validate.Struct`.
+- **Context propagation** — if you call a goroutine from a handler, derive its context from `c.Context()` AND handle cancellation, otherwise the client disconnecting leaks work.
+- **Error envelope** — if you see raw `{"message": "..."}` in a response, someone skipped the central `ErrorHandler` registration. Check `fiber.Config{ErrorHandler: ...}` in `main.go`.
+- **Handler → DB shortcut** — resist the urge. When you're tempted, add a service method. Handlers orchestrate; services decide.
+
+## Verification
+
+```
+make lint-backend    # go vet + golangci-lint
+make test-backend    # go test ./...
+```
+
+Both must pass before `cos task-done`.

templates/go-fiber/scaffold/src/backend/cmd/api/main.go

@@ -0,0 +1,21 @@
+package main
+
+import (
+	"log"
+
+	"github.com/gofiber/fiber/v3"
+)
+
+func newApp() *fiber.App {
+	app := fiber.New()
+	app.Get("/health", func(c fiber.Ctx) error {
+		return c.JSON(fiber.Map{"status": "ok"})
+	})
+	return app
+}
+
+func main() {
+	if err := newApp().Listen(":8080"); err != nil {
+		log.Fatal(err)
+	}
+}

templates/go-fiber/scaffold/src/backend/cmd/api/main_test.go

@@ -0,0 +1,17 @@
+package main
+
+import (
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestHealth(t *testing.T) {
+	resp, err := newApp().Test(httptest.NewRequest(http.MethodGet, "/health", nil))
+	if err != nil {
+		t.Fatalf("test request failed: %v", err)
+	}
+	if resp.StatusCode != http.StatusOK {
+		t.Fatalf("got status %d, want 200", resp.StatusCode)
+	}
+}

templates/go-fiber/scaffold/src/backend/go.mod

@@ -0,0 +1,23 @@
+module {{PROJECT_NAME}}
+
+go 1.25.0
+
+require github.com/gofiber/fiber/v3 v3.0.0
+
+require (
+	github.com/andybalholm/brotli v1.2.0 // indirect
+	github.com/gofiber/schema v1.6.0 // indirect
+	github.com/gofiber/utils/v2 v2.0.0 // indirect
+	github.com/google/uuid v1.6.0 // indirect
+	github.com/klauspost/compress v1.18.3 // indirect
+	github.com/mattn/go-colorable v0.1.14 // indirect
+	github.com/mattn/go-isatty v0.0.20 // indirect
+	github.com/philhofer/fwd v1.2.0 // indirect
+	github.com/tinylib/msgp v1.6.3 // indirect
+	github.com/valyala/bytebufferpool v1.0.0 // indirect
+	github.com/valyala/fasthttp v1.69.0 // indirect
+	golang.org/x/crypto v0.47.0 // indirect
+	golang.org/x/net v0.49.0 // indirect
+	golang.org/x/sys v0.40.0 // indirect
+	golang.org/x/text v0.33.0 // indirect
+)

templates/go-fiber/scaffold/src/backend/go.sum

@@ -0,0 +1,49 @@
+github.com/andybalholm/brotli v1.2.0 h1:ukwgCxwYrmACq68yiUqwIWnGY0cTPox/M94sVwToPjQ=
+github.com/andybalholm/brotli v1.2.0/go.mod h1:rzTDkvFWvIrjDXZHkuS16NPggd91W3kUSvPlQ1pLaKY=
+github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
+github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
+github.com/fxamacker/cbor/v2 v2.9.0 h1:NpKPmjDBgUfBms6tr6JZkTHtfFGcMKsw3eGcmD/sapM=
+github.com/fxamacker/cbor/v2 v2.9.0/go.mod h1:vM4b+DJCtHn+zz7h3FFp/hDAI9WNWCsZj23V5ytsSxQ=
+github.com/gofiber/fiber/v3 v3.0.0 h1:GPeCG8X60L42wLKrzgeewDHBr6pE6veAvwaXsqD3Xjk=
+github.com/gofiber/fiber/v3 v3.0.0/go.mod h1:kVZiO/AwyT5Pq6PgC8qRCJ+j/BHrMy5jNw1O9yH38aY=
+github.com/gofiber/schema v1.6.0 h1:rAgVDFwhndtC+hgV7Vu5ItQCn7eC2mBA4Eu1/ZTiEYY=
+github.com/gofiber/schema v1.6.0/go.mod h1:WNZWpQx8LlPSK7ZaX0OqOh+nQo/eW2OevsXs1VZfs/s=
+github.com/gofiber/utils/v2 v2.0.0 h1:SCC3rpsEDWupFSHtc0RKxg/BKgV0s1qKfZg9Jv6D0sM=
+github.com/gofiber/utils/v2 v2.0.0/go.mod h1:xF9v89FfmbrYqI/bQUGN7gR8ZtXot2jxnZvmAUtiavE=
+github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
+github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/klauspost/compress v1.18.3 h1:9PJRvfbmTabkOX8moIpXPbMMbYN60bWImDDU7L+/6zw=
+github.com/klauspost/compress v1.18.3/go.mod h1:R0h/fSBs8DE4ENlcrlib3PsXS61voFxhIs2DeRhCvJ4=
+github.com/mattn/go-colorable v0.1.14 h1:9A9LHSqF/7dyVVX6g0U9cwm9pG3kP9gSzcuIPHPsaIE=
+github.com/mattn/go-colorable v0.1.14/go.mod h1:6LmQG8QLFO4G5z1gPvYEzlUgJ2wF+stgPZH1UqBm1s8=
+github.com/mattn/go-isatty v0.0.20 h1:xfD0iDuEKnDkl03q4limB+vH+GxLEtL/jb4xVJSWWEY=
+github.com/mattn/go-isatty v0.0.20/go.mod h1:W+V8PltTTMOvKvAeJH7IuucS94S2C6jfK/D7dTCTo3Y=
+github.com/philhofer/fwd v1.2.0 h1:e6DnBTl7vGY+Gz322/ASL4Gyp1FspeMvx1RNDoToZuM=
+github.com/philhofer/fwd v1.2.0/go.mod h1:RqIHx9QI14HlwKwm98g9Re5prTQ6LdeRQn+gXJFxsJM=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
+github.com/shamaton/msgpack/v3 v3.0.0 h1:xl40uxWkSpwBCSTvS5wyXvJRsC6AcVcYeox9PspKiZg=
+github.com/shamaton/msgpack/v3 v3.0.0/go.mod h1:DcQG8jrdrQCIxr3HlMYkiXdMhK+KfN2CitkyzsQV4uc=
+github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
+github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
+github.com/tinylib/msgp v1.6.3 h1:bCSxiTz386UTgyT1i0MSCvdbWjVW+8sG3PjkGsZQt4s=
+github.com/tinylib/msgp v1.6.3/go.mod h1:RSp0LW9oSxFut3KzESt5Voq4GVWyS+PSulT77roAqEA=
+github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
+github.com/valyala/bytebufferpool v1.0.0/go.mod h1:6bBcMArwyJ5K/AmCkWv1jt77kVWyCJ6HpOuEn7z0Csc=
+github.com/valyala/fasthttp v1.69.0 h1:fNLLESD2SooWeh2cidsuFtOcrEi4uB4m1mPrkJMZyVI=
+github.com/valyala/fasthttp v1.69.0/go.mod h1:4wA4PfAraPlAsJ5jMSqCE2ug5tqUPwKXxVj8oNECGcw=
+github.com/x448/float16 v0.8.4 h1:qLwI1I70+NjRFUR3zs1JPUCgaCXSh3SW62uAKT1mSBM=
+github.com/x448/float16 v0.8.4/go.mod h1:14CWIYCyZA/cWjXOioeEpHeN/83MdbZDRQHoFcYsOfg=
+github.com/xyproto/randomstring v1.0.5 h1:YtlWPoRdgMu3NZtP45drfy1GKoojuR7hmRcnhZqKjWU=
+github.com/xyproto/randomstring v1.0.5/go.mod h1:rgmS5DeNXLivK7YprL0pY+lTuhNQW3iGxZ18UQApw/E=
+golang.org/x/crypto v0.47.0 h1:V6e3FRj+n4dbpw86FJ8Fv7XVOql7TEwpHapKoMJ/GO8=
+golang.org/x/crypto v0.47.0/go.mod h1:ff3Y9VzzKbwSSEzWqJsJVBnWmRwRSHt/6Op5n9bQc4A=
+golang.org/x/net v0.49.0 h1:eeHFmOGUTtaaPSGNmjBKpbng9MulQsJURQUAfUwY++o=
+golang.org/x/net v0.49.0/go.mod h1:/ysNB2EvaqvesRkuLAyjI1ycPZlQHM3q01F02UY/MV8=
+golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.40.0 h1:DBZZqJ2Rkml6QMQsZywtnjnnGvHza6BTfYFWY9kjEWQ=
+golang.org/x/sys v0.40.0/go.mod h1:OgkHotnGiDImocRcuBABYBEXf8A9a87e/uXjp9XT3ks=
+golang.org/x/text v0.33.0 h1:B3njUFyqtHDUI5jMn1YIr5B0IE2U0qck04r6d4KPAxE=
+golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

templates/go-fiber/scaffold-boundary.yaml

@@ -0,0 +1,26 @@
+# Scaffold boundary for the go-fiber stack.
+# Schema: docs/governance/scaffold-boundary-contract.md
+
+version: 1
+stack: go-fiber
+
+roots:
+  - src/backend/
+
+file_patterns:
+  - "src/backend/**/*.go"
+
+imports_from:
+  - src/shared/
+  - src/shared/types/
+  - src/shared/contracts/
+
+forbids_writing_in:
+  - src/frontend/
+  - src/mobile/
+  - src/ai-service/
+
+notes:
+  - "Go module root is src/backend/ (go.mod lives there). Hexagonal: cmd → internal handler → service → repo."
+  - "Fiber v3 handler signature: `func(c fiber.Ctx) error`."
+  - "Race detector mandatory on CI (`go test -race`)."

templates/go-fiber/skills/go-fiber/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: go-fiber
+tier: stack
+domain: [backend]
+description: Use when creating or modifying Go files under src/backend/ in a Fiber project — handlers, middleware, request validation, graceful shutdown, and table-driven tests with app.Test(). Triggers on any .go file change under src/backend/. Covers idiomatic Fiber v3 (GA 2026, Go 1.25+) patterns plus the Go fundamentals (error wrapping, context propagation, struct tags for validation); see references/fiber-v3-patterns.md for the v2→v3 changes.
+globs: "src/backend/**/*.go"
+depends_on:
+  - clean-code
+  - backend-fundamentals
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+
+---
+
+REQUIRED BACKGROUND: This skill `depends_on: [clean-code, backend-fundamentals]`. Both are loaded transitively — `clean-code` gives universal code quality, `backend-fundamentals` gives stack-agnostic backend patterns (services/selectors, idempotency, envelopes, N+1, migrations, auth). This skill adds ONLY Fiber-specific layering on top.
+
+## Pre-Code Checklist
+
+- [ ] Read `docs/engineering/fiber-rules.md` — canonical Fiber policy
+- [ ] If touching HTTP handlers: read `docs/playbooks/fiber-service.md`
+- [ ] If touching request parsing: read `docs/api-contracts/error-format.md`
+- [ ] Confirm Fiber version in `go.mod` (v3, Go 1.25+; see references/fiber-v3-patterns.md)
+- [ ] `go vet ./...` clean before editing
+
+## Handler Pattern
+
+Every handler has the same signature and lifecycle:
+
+```go
+func ListOrders(svc *service.Orders) fiber.Handler {
+    return func(c fiber.Ctx) error {
+        // 1. Parse + validate
+        var q ListQuery
+        if err := c.Bind().Query(&q); err != nil {
+            return fiber.NewError(fiber.StatusBadRequest, "invalid query")
+        }
+        if err := validate.Struct(&q); err != nil {
+            return fiber.NewError(fiber.StatusUnprocessableEntity, err.Error())
+        }
+
+        // 2. Call the service with a context (cancellation propagates)
+        orders, err := svc.List(c.Context(), q)
+        if err != nil {
+            return err  // central error handler renders the envelope
+        }
+
+        // 3. Respond
+        return c.Status(fiber.StatusOK).JSON(fiber.Map{
+            "data": orders,
+            "meta": fiber.Map{"count": len(orders)},
+        })
+    }
+}
+```
+
+**Rules:**
+- No business logic inside the handler. Orchestrate only.
+- No direct DB calls. Handler → service → repository.
+- Always pass `c.Context()` downstream — never `context.Background()`.
+
+## Error Envelope
+
+Central error handler in `app.Config{}`:
+
+```go
+app := fiber.New(fiber.Config{
+    ErrorHandler: func(c fiber.Ctx, err error) error {
+        code := fiber.StatusInternalServerError
+        msg  := "internal error"
+        if e, ok := err.(*fiber.Error); ok {
+            code = e.Code
+            msg  = e.Message
+        }
+        return c.Status(code).JSON(fiber.Map{
+            "error": fiber.Map{
+                "code":    statusToSlug(code),
+                "message": msg,
+                "details": extractDetails(err),
+            },
+        })
+    },
+})
+```
+
+Typed errors at the service layer (`fmt.Errorf("…: %w", ErrNotFound)`) translate to HTTP codes via the middleware — never hand-code status codes in service code.
+
+## Middleware Stack (in order)
+
+```go
+app.Use(recover.New())         // panic → 500, don't crash the process
+app.Use(requestid.New())       // X-Request-ID for correlation
+app.Use(logger.New(logger.Config{ /* structured */ }))
+app.Use(cors.New())
+app.Use(compress.New())
+// group-specific below:
+auth := app.Group("/api", middleware.Auth(jwtSecret))
+auth.Get("/orders", ListOrders(svc))
+```
+
+**Never** put business logic in middleware. Middleware handles cross-cutting concerns only (auth, logging, rate-limit).
+
+## Validation
+
+Use `go-playground/validator` via struct tags on DTOs:
+
+```go
+type CreateOrderDTO struct {
+    UserID    string  `json:"user_id"    validate:"required,uuid4"`
+    Amount    float64 `json:"amount"     validate:"required,gt=0"`
+    Currency  string  `json:"currency"   validate:"required,len=3,uppercase"`
+}
+```
+
+Validation failure → 422 (UnprocessableEntity), not 400. 400 is for malformed JSON only.
+
+## Graceful Shutdown
+
+```go
+func main() {
+    app := buildApp()
+    go func() { _ = app.Listen(":8080") }()
+
+    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()
+    _ = app.ShutdownWithContext(ctx)
+}
+```
+
+Every long-running process in the app (background workers, DB pool, queue consumers) must respect the same shutdown context.
+
+## Testing
+
+Use Fiber's built-in `app.Test()` — no external server needed, no `httptest` mocking:
+
+```go
+func TestListOrders_ok(t *testing.T) {
+    app := newTestApp(t)
+    req := httptest.NewRequest("GET", "/api/orders?limit=5", nil)
+    req.Header.Set("Authorization", "Bearer "+testJWT(t))
+
+    res, err := app.Test(req, fiber.TestConfig{Timeout: 2 * time.Second})
+    require.NoError(t, err)
+    assert.Equal(t, 200, res.StatusCode)
+
+    var body struct{ Data []Order }
+    require.NoError(t, json.NewDecoder(res.Body).Decode(&body))
+    assert.Len(t, body.Data, 5)
+}
+```
+
+**Table-driven for variants:**
+
+```go
+cases := []struct {
+    name   string
+    query  string
+    status int
+}{
+    {"ok",       "?limit=5",        200},
+    {"invalid",  "?limit=-1",       422},
+    {"too_big",  "?limit=10000",    422},
+}
+for _, tc := range cases {
+    t.Run(tc.name, func(t *testing.T) { /* … */ })
+}
+```
+
+## Project Layout
+
+```
+src/backend/
+├── cmd/api/main.go          # app.Listen
+├── internal/
+│   ├── handlers/            # Fiber handlers — orchestration only
+│   ├── services/            # business logic, context-propagating
+│   ├── repositories/        # DB access, sqlx / pgx / ent
+│   ├── models/              # domain types + validator tags
+│   └── middleware/          # auth, cors, requestid
+├── pkg/                     # reusable across services (rare)
+├── go.mod
+└── go.sum
+```
+
+Never import `handlers` from `services` (back-edge). Services are the leaf of the dependency DAG; handlers depend on services.
+
+## Anti-Patterns (hard no)
+
+- `c.Bind().Body(&req)` without follow-up `validate.Struct(&req)`
+- Returning `fmt.Errorf("bad request")` from a handler — use `fiber.NewError(status, msg)` so the central handler picks up the code.
+- Using `context.Background()` inside handler scope — always `c.Context()`.
+- Mixing goroutines with Fiber without a context-derived cancellation.
+- Global DB pool held in a package-level `var db *sql.DB` — inject it via the service constructor.
+
+## Deepening + tooling
+
+- [references/fiber-v3-patterns.md](references/fiber-v3-patterns.md) — Fiber v3 (2026) handlers, binding, central error handler, middleware order, fasthttp gotchas.
+- [references/anatomy.md](references/anatomy.md) — file map + scaffold; `scripts/new_endpoint.py` to generate one.
+- [assets/fiber-checklist.md](assets/fiber-checklist.md) — the review gate.
+- Versions pinned in [versions.json](versions.json) — `make skills-check-versions`.

templates/go-fiber/skills/go-fiber/assets/fiber-checklist.md

@@ -0,0 +1,26 @@
+<!-- domain:GO | layer:asset | ssot:false | updated:2026-06-04 -->
+# Fiber Review Checklist
+
+Run when writing or reviewing a Fiber v3 handler/app.
+
+## Handlers & errors
+- [ ] Handlers return `error`; no inline error responses — central `ErrorHandler` formats the envelope.
+- [ ] `fiber.NewError(status, msg)` for client errors; wrap server errors with context.
+- [ ] Request context passed down (`c.Context()`) to services/queries.
+
+## Binding & validation
+- [ ] Body bound via `c.Bind().Body(&dto)` then validated (go-playground/validator).
+- [ ] DTOs separate from domain types; never trust raw input.
+
+## Middleware order
+- [ ] `recover` first → requestid → logger → cors → auth (on protected group).
+- [ ] Auth on a route group, not duplicated per handler.
+
+## fasthttp gotchas
+- [ ] No reference to `c` or its byte slices retained after the handler returns (copy what you keep).
+- [ ] `BodyLimit`, `ReadTimeout`, `WriteTimeout` set; large bodies streamed.
+
+## Verify
+- [ ] `go test -race ./...` clean; table-driven handler tests (httptest).
+- [ ] `golangci-lint`/`go vet` clean.
+- [ ] `make skills-check-versions` — Fiber/Go pins current.