[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7FEYPP7P6D7XQ644YVT4H66":3,"skill-same:01M7FEYPP7P6D7XQ644YVT4H66":104},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":24,"commitSha":25,"skillDirectory":26,"forksCount":14,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":29,"ownerDescription":30,"updatedAt":31,"install":32,"resources":45},"01M7FEYPP7P6D7XQ644YVT4H66","go-http-api",null,"Go HTTP API services on Fiber v3, fx, zap, GORM\u002FPostgreSQL, Redis, Prometheus and OpenTelemetry. Use when scaffolding a Go API service, adding a resource\u002Fendpoint\u002Ffeature module to one, or changing its middleware, caching, migrations, observability or Bruno collection.","heynemann\u002Fdotfiles-stow","heynemann","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F60965?v=4","01M7DFBD9ZDB2J2QE7R4AR0PES","Bernardo Heynemann","01M7FERV0J6GMQ0RHEH6EHGYRW",0,"MIT","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002FSKILL.md",[],[],"2026-11-16 10:05:34",false,"---\nname: go-http-api\ndescription: Go HTTP API services on Fiber v3, fx, zap, GORM\u002FPostgreSQL, Redis, Prometheus and OpenTelemetry. Use when scaffolding a Go API service, adding a resource\u002Fendpoint\u002Ffeature module to one, or changing its middleware, caching, migrations, observability or Bruno collection.\n---\n\n# Go HTTP API services\n\nAn opinionated stack and layout for Go HTTP APIs. The contract is written first\nin OpenAPI, and each feature is a self-wiring fx module. Every reference below\nwas verified end-to-end against a running service (Go 1.27, Fiber v3.5, Postgres\n18, Redis 8) in October 2026. For general Go topics (concurrency, generics,\ninterfaces, idioms), use `skill:\u002F\u002Fgolang-pro`.\n\n## Stack\n\n| Concern | Choice | Reference |\n| --- | --- | --- |\n| Layout, layers, wiring | feature packages under `internal\u002F`, generated code under `gen\u002F` | [architecture.md](references\u002Farchitecture.md) |\n| Dependency injection | `go.uber.org\u002Ffx`: one `Module` per package | [fx.md](references\u002Ffx.md) |\n| Configuration | `caarlos0\u002Fenv\u002Fv11`, a prefix per module, injectable `config.Source` | [config.md](references\u002Fconfig.md) |\n| Logging | `zap`, request-scoped `logger.From(ctx)`, GORM adapter | [logging.md](references\u002Flogging.md) |\n| HTTP | Fiber v3, sonic JSON, RFC 9457 problems, admin port, graceful drain | [http.md](references\u002Fhttp.md) |\n| Contract | OpenAPI 3.0.3, oapi-codegen strict server per tag, kin-openapi validator, keyset cursors, `\u002Fv1` | [openapi.md](references\u002Fopenapi.md) |\n| Data | GORM + PostgreSQL 18, UUIDv7, TxManager in ctx, per-feature errors | [database.md](references\u002Fdatabase.md) |\n| Schema | goose SQL migrations embedded in the binary, `migrate` subcommand (cobra) | [migrations.md](references\u002Fmigrations.md) |\n| Cache, rate limit | go-redis v9, repository decorator, singleflight, fail-open; `redis_rate` GCRA | [redis.md](references\u002Fredis.md) |\n| Metrics, traces | Prometheus `client_golang`; OpenTelemetry with `autoexport` | [observability.md](references\u002Fobservability.md) |\n| Tests | testify + mockery, testcontainers with a template DB, fxtest + `app.Test` | [testing.md](references\u002Ftesting.md) |\n| Build, lint, format, run | `go tool`, Makefile, golangci-lint v2 (lint, forbidigo stack rules, gofumpt\u002Fgoimports\u002Fgolines), distroless Docker, compose | [tooling.md](references\u002Ftooling.md) |\n| Auth (opt-in) | JWT bearer via JWKS, enforced through spec `security` | [auth.md](references\u002Fauth.md) |\n| Manual API testing | Bruno collection generated from the spec into `gen\u002Fbruno` | [bruno.md](references\u002Fbruno.md) |\n\nWhen you change one concern in an existing service, read that row's reference\nand follow its rules. Check the invariants below before you finish.\n\n## Invariants\n\nThese hold in every service built with this skill. A change that breaks one is\nwrong even if it compiles. `make lint` enforces the library choices behind them\nwith forbidigo (tooling.md): no mutexes (xsync\u002Fatomic), no logger but zap, no\nJSON but sonic, no `os.Getenv`, no global Prometheus registry, no\n`AutoMigrate`\u002F`Save`, no UUIDv4, no `time.Sleep`.\n\n1. **Contract first.** `api\u002Fopenapi.yaml` defines every operation. The validator\n   rejects requests that don't match it before any handler runs, so handlers\n   never re-check shape. Handlers return only the responses the spec declares.\n2. **Generated code goes in `gen\u002F` only** (`gen\u002Fgo\u002F\u003Cfeature>api`,\n   `gen\u002Fgo\u002Fhttpapi`, `gen\u002Fgo\u002F\u003Cfeature>mocks`, `gen\u002Fbruno`). It is committed and\n   never edited by hand. Run `make generate` after every change to the spec or\n   to an interface.\n3. **Features wire themselves.** `internal\u002F\u003Cfeature>\u002Fmodule.go` provides the\n   repository, service and handler, and registers routes through\n   `httpserver.AsRoutes`. Turning a feature on means adding `\u003Cfeature>.Module`\n   to `internal\u002Fapp\u002Fapp.go`.\n4. **Config is per module.** Each module parses its own env prefix from\n   `config.Source`. Nothing calls `os.Getenv`.\n5. **Repositories are the only GORM users.** They start every query with\n   `tm.DB(ctx)`. They translate `gorm`\u002F`pgconn` errors into the feature's\n   sentinel errors, matching on named constraints. Services depend on the\n   `Repository` interface they declare themselves, and on `db.Transactor`.\n6. **Errors become HTTP responses in exactly two places.** Expected feature\n   errors become typed spec responses in `handler.go`. Everything else becomes a\n   logged 500 in `httpserver.ErrorHandler`. Response bodies never contain\n   internal error text.\n7. **Log or return an error, not both.** Inside a request, log through\n   `logger.From(ctx)` so every line carries `request_id` and `trace_id`.\n8. **Cache only through a repository decorator.** Invalidate with\n   `db.AfterCommit`, bypass the cache inside transactions, and fail open.\n9. **Metric labels stay bounded.** The route label is the template, never the\n   raw path. No metric uses the global Prometheus registry.\n10. **Migrations own the schema.** Never call `AutoMigrate`. IDs are UUIDv7,\n    generated in Go by `db.Base`. Convert timestamps with `.UTC()` at the DTO\n    boundary.\n11. **Runnable as documented.** From a fresh clone and a clean shell, every\n    command in the README works as written: `make deps-up migrate-up run` serves\n    the API with no exported variables, and a missing tool, dependency or\n    setting fails with one line naming the fix. A command that needs an\n    undocumented `export` is a bug in the Makefile defaults, not in the docs.\n\n## Workflow A: scaffold a new service\n\nAsk for these if they're missing: the module path, the binary name, and the\nfirst feature with its operations. Then work through the steps in order. Each\nstep has a done-condition; don't start the next step until it holds.\n\n1. **Module, tools and Makefile** ([tooling.md](references\u002Ftooling.md)): run\n   `go mod init`, then `go mod edit -go=1.27`, then add the `go get -tool` lines\n   for oapi-codegen and mockery. Add the Makefile now; step 3 needs\n   `make generate-api`. Node must be installed: `make generate-bruno` runs\n   pinned tools through `npx`.\n   *Done:* `go tool oapi-codegen -version` and `go tool mockery version` both\n   print a version.\n2. **Platform packages.** Create\n   `internal\u002Fplatform\u002F{config,logger,otel,metrics,db,redisx,cache,ratelimit,admin,problem,pagination,httpserver}`\n   and `platform.go`, taking the code from config.md, logging.md,\n   observability.md, database.md, redis.md, http.md and openapi.md (validator\n   and pagination). Leave `auth\u002F` out unless the user asked for auth.\n   *Done:* every package in architecture.md's layout exists. They compile only\n   after step 3 generates `gen\u002Fgo\u002Fhttpapi` and adds `api\u002Fembed.go`.\n3. **Contract** ([openapi.md](references\u002Fopenapi.md)): write `api\u002Fcommon.yaml`,\n   `api\u002Fopenapi.yaml` (`servers: \u002Fv1`, the first feature's tag), `api\u002Fembed.go`,\n   `api\u002Fcodegen\u002Fhttpapi.yaml`, one `api\u002Fcodegen\u002F\u003Cfeature>.yaml` per tag, and\n   `api\u002Fbruno\u002Fenvironments\u002Flocal.yml` ([bruno.md](references\u002Fbruno.md)).\n   *Done:* `make generate-api generate-bruno` writes `gen\u002Fgo\u002Fhttpapi`,\n   `gen\u002Fgo\u002F\u003Cfeature>api` and `gen\u002Fbruno` without errors.\n4. **Entrypoint and schema** ([architecture.md](references\u002Farchitecture.md),\n   [migrations.md](references\u002Fmigrations.md)): write `cmd\u002F\u003Cbinary>\u002Fmain.go`,\n   `internal\u002Fcli\u002F{root,serve,migrate}.go`, `internal\u002Fapp\u002Fapp.go`,\n   `migrations\u002Fembed.go` and the first migration. Write that migration by hand\n   as `migrations\u002F\u003CYYYYMMDDhhmmss>_create_\u003Cthings>.sql`: `\u002F\u002Fgo:embed *.sql`\n   doesn't compile with no files, so `make migration` only works once one\n   exists. Then run `go mod tidy`.\n   *Done:* `go build .\u002F...` succeeds.\n5. **First feature:** follow Workflow B.\n6. **Test kit** ([testing.md](references\u002Ftesting.md)): write\n   `internal\u002Ftestkit\u002F{testkit,main}.go` and `.mockery.yml`, then run\n   `go mod tidy`.\n7. **Tooling** ([tooling.md](references\u002Ftooling.md)): add `.golangci.yml`, the\n   Dockerfile, `.dockerignore`, `compose.yaml` and `.gitignore`. Write the\n   README: a Run section that is exactly `make deps-up`, `make migrate-up`,\n   `make run`, the endpoints, the dev commands (`make generate\u002Ffmt\u002Flint\u002Ftest`),\n   and the env var table (config.md).\n8. **Verify:** pass the gate below.\n\n## Workflow B: add a feature, resource or endpoint\n\nTo add an endpoint to an existing feature, run steps 1, 2 and 4 to 8 and skip\nwhatever doesn't change.\n\n1. **Spec:** add the paths, tagged `\u003Cfeature>`, plus their schemas. List every\n   error status each operation can return, using the shared responses from\n   `common.yaml`. Give request properties `example`s so the Bruno requests are\n   ready to send ([openapi.md](references\u002Fopenapi.md)).\n2. **Codegen:** for a new feature, copy `api\u002Fcodegen\u002F\u003Cother>.yaml` and change\n   `package`, `output` and `include-tags`. Then run\n   `make generate-api generate-bruno`.\n3. **Migration:** run `make migration name=create_\u003Cthings>` (a service's first\n   feature already has one from Workflow A step 4). Name every constraint, and\n   give foreign keys no `RESTRICT` ([migrations.md](references\u002Fmigrations.md)).\n4. **Feature package** `internal\u002F\u003Cfeature>\u002F`\n   ([architecture.md](references\u002Farchitecture.md),\n   [database.md](references\u002Fdatabase.md), [openapi.md](references\u002Fopenapi.md)):\n   - `model.go`: GORM model embedding `db.Base`.\n   - `errors.go`: sentinel errors whose messages are safe to show clients.\n   - `service.go`: the `Repository` interface, input structs, and `Service`\n     (`WithinTx` for anything that must be atomic).\n   - `repository.go`: a GORM implementation with `translate`.\n   - `handler.go`: the strict handler, with a\n     `var _ \u003Cfeature>api.StrictServerInterface = (*Handler)(nil)` check, a\n     `switch` mapping errors to typed responses, a `toDTO` that calls `.UTC()`,\n     and `NewRoutes`.\n   - `module.go`: provides the above, plus `fx.Decorate(NewCachedRepository)` if\n     reads are hot ([redis.md](references\u002Fredis.md)).\n5. **Wire it:** add `\u003Cfeature>.Module` to `internal\u002Fapp\u002Fapp.go`. Add the\n   `Repository` interface to `.mockery.yml`, then run `make generate-mocks`.\n6. **Tests** ([testing.md](references\u002Ftesting.md)), all in\n   `package \u003Cfeature>_test`:\n   - `main_test.go`\n   - service unit tests for each rule\n   - a repository test for each translated error\n   - an API test per operation covering the happy path and its main error\n7. **Metrics or spans** for business events, only if the feature needs them\n   ([observability.md](references\u002Fobservability.md)).\n8. **Verify:** pass the gate below.\n\n## Verification gate\n\nWork is done only when all of these hold:\n\n- `make generate` leaves `git diff -- gen\u002F` limited to the changes you intended.\n  In CI, `make check-generated` passes.\n- `make fmt` has been run and `make fmt-check` exits 0 (no diff).\n- `make lint` reports `0 issues`.\n- `make test` passes. It needs Docker for testcontainers.\n- Clean-shell run, after scaffolding or any change to the Makefile, config or\n  startup: in a shell with nothing exported\n  (`env -i HOME=\"$HOME\" PATH=\"$PATH\" bash`), run the README's Run commands\n  verbatim (`make deps-up migrate-up run`). The API must come up. Also start it\n  once with Postgres stopped and confirm the output is a single\n  `startup failed: ...` line. If the default ports are taken, set only\n  `PG_PORT`\u002F`REDIS_PORT`\u002F`HTTP_ADDR`\u002F`ADMIN_ADDR`, plus `COMPOSE_PROJECT_NAME`\n  so you don't touch someone's running stack.\n- Smoke test against that running service: `curl` each new or changed operation\n  once on its happy path and once on a 4xx path. Confirm that:\n  - 4xx responses are `application\u002Fproblem+json` with a `request_id`;\n  - `curl \u003CADMIN_ADDR>\u002Fmetrics` shows the operation's `route` template.\n- Drain check, after changes to the server or lifecycle: with `make run` up,\n  send `kill -TERM` to the server process (the pid listening on `HTTP_ADDR`,\n  e.g. `lsof -ti :8080`). For `HTTP_SHUTDOWN_DRAIN_DELAY`, `\u002Freadyz` should\n  return 503 `{\"status\":\"shutting_down\"}` while the API still answers. After\n  that `make run` should exit 0.\n","# Go HTTP API services\n\nAn opinionated stack and layout for Go HTTP APIs. The contract is written first\nin OpenAPI, and each feature is a self-wiring fx module. Every reference below\nwas verified end-to-end against a running service (Go 1.27, Fiber v3.5, Postgres\n18, Redis 8) in October 2026. For general Go topics (concurrency, generics,\ninterfaces, idioms), use `skill:\u002F\u002Fgolang-pro`.\n\n## Stack\n\n| Concern | Choice | Reference |\n| --- | --- | --- |\n| Layout, layers, wiring | feature packages under `internal\u002F`, generated code under `gen\u002F` | [architecture.md](references\u002Farchitecture.md) |\n| Dependency injection | `go.uber.org\u002Ffx`: one `Module` per package | [fx.md](references\u002Ffx.md) |\n| Configuration | `caarlos0\u002Fenv\u002Fv11`, a prefix per module, injectable `config.Source` | [config.md](references\u002Fconfig.md) |\n| Logging | `zap`, request-scoped `logger.From(ctx)`, GORM adapter | [logging.md](references\u002Flogging.md) |\n| HTTP | Fiber v3, sonic JSON, RFC 9457 problems, admin port, graceful drain | [http.md](references\u002Fhttp.md) |\n| Contract | OpenAPI 3.0.3, oapi-codegen strict server per tag, kin-openapi validator, keyset cursors, `\u002Fv1` | [openapi.md](references\u002Fopenapi.md) |\n| Data | GORM + PostgreSQL 18, UUIDv7, TxManager in ctx, per-feature errors | [database.md](references\u002Fdatabase.md) |\n| Schema | goose SQL migrations embedded in the binary, `migrate` subcommand (cobra) | [migrations.md](references\u002Fmigrations.md) |\n| Cache, rate limit | go-redis v9, repository decorator, singleflight, fail-open; `redis_rate` GCRA | [redis.md](references\u002Fredis.md) |\n| Metrics, traces | Prometheus `client_golang`; OpenTelemetry with `autoexport` | [observability.md](references\u002Fobservability.md) |\n| Tests | testify + mockery, testcontainers with a template DB, fxtest + `app.Test` | [testing.md](references\u002Ftesting.md) |\n| Build, lint, format, run | `go tool`, Makefile, golangci-lint v2 (lint, forbidigo stack rules, gofumpt\u002Fgoimports\u002Fgolines), distroless Docker, compose | [tooling.md](references\u002Ftooling.md) |\n| Auth (opt-in) | JWT bearer via JWKS, enforced through spec `security` | [auth.md](references\u002Fauth.md) |\n| Manual API testing | Bruno collection generated from the spec into `gen\u002Fbruno` | [bruno.md](references\u002Fbruno.md) |\n\nWhen you change one concern in an existing service, read that row's reference\nand follow its rules. Check the invariants below before you finish.\n\n## Invariants\n\nThese hold in every service built with this skill. A change that breaks one is\nwrong even if it compiles. `make lint` enforces the library choices behind them\nwith forbidigo (tooling.md): no mutexes (xsync\u002Fatomic), no logger but zap, no\nJSON but sonic, no `os.Getenv`, no global Prometheus registry, no\n`AutoMigrate`\u002F`Save`, no UUIDv4, no `time.Sleep`.\n\n1. **Contract first.** `api\u002Fopenapi.yaml` defines every operation. The validator\n   rejects requests that don't match it before any handler runs, so handlers\n   never re-check shape. Handlers return only the responses the spec declares.\n2. **Generated code goes in `gen\u002F` only** (`gen\u002Fgo\u002F\u003Cfeature>api`,\n   `gen\u002Fgo\u002Fhttpapi`, `gen\u002Fgo\u002F\u003Cfeature>mocks`, `gen\u002Fbruno`). It is committed and\n   never edited by hand. Run `make generate` after every change to the spec or\n   to an interface.\n3. **Features wire themselves.** `internal\u002F\u003Cfeature>\u002Fmodule.go` provides the\n   repository, service and handler, and registers routes through\n   `httpserver.AsRoutes`. Turning a feature on means adding `\u003Cfeature>.Module`\n   to `internal\u002Fapp\u002Fapp.go`.\n4. **Config is per module.** Each module parses its own env prefix from\n   `config.Source`. Nothing calls `os.Getenv`.\n5. **Repositories are the only GORM users.** They start every query with\n   `tm.DB(ctx)`. They translate `gorm`\u002F`pgconn` errors into the feature's\n   sentinel errors, matching on named constraints. Services depend on the\n   `Repository` interface they declare themselves, and on `db.Transactor`.\n6. **Errors become HTTP responses in exactly two places.** Expected feature\n   errors become typed spec responses in `handler.go`. Everything else becomes a\n   logged 500 in `httpserver.ErrorHandler`. Response bodies never contain\n   internal error text.\n7. **Log or return an error, not both.** Inside a request, log through\n   `logger.From(ctx)` so every line carries `request_id` and `trace_id`.\n8. **Cache only through a repository decorator.** Invalidate with\n   `db.AfterCommit`, bypass the cache inside transactions, and fail open.\n9. **Metric labels stay bounded.** The route label is the template, never the\n   raw path. No metric uses the global Prometheus registry.\n10. **Migrations own the schema.** Never call `AutoMigrate`. IDs are UUIDv7,\n    generated in Go by `db.Base`. Convert timestamps with `.UTC()` at the DTO\n    boundary.\n11. **Runnable as documented.** From a fresh clone and a clean shell, every\n    command in the README works as written: `make deps-up migrate-up run` serves\n    the API with no exported variables, and a missing tool, dependency or\n    setting fails with one line naming the fix. A command that needs an\n    undocumented `export` is a bug in the Makefile defaults, not in the docs.\n\n## Workflow A: scaffold a new service\n\nAsk for these if they're missing: the module path, the binary name, and the\nfirst feature with its operations. Then work through the steps in order. Each\nstep has a done-condition; don't start the next step until it holds.\n\n1. **Module, tools and Makefile** ([tooling.md](references\u002Ftooling.md)): run\n   `go mod init`, then `go mod edit -go=1.27`, then add the `go get -tool` lines\n   for oapi-codegen and mockery. Add the Makefile now; step 3 needs\n   `make generate-api`. Node must be installed: `make generate-bruno` runs\n   pinned tools through `npx`.\n   *Done:* `go tool oapi-codegen -version` and `go tool mockery version` both\n   print a version.\n2. **Platform packages.** Create\n   `internal\u002Fplatform\u002F{config,logger,otel,metrics,db,redisx,cache,ratelimit,admin,problem,pagination,httpserver}`\n   and `platform.go`, taking the code from config.md, logging.md,\n   observability.md, database.md, redis.md, http.md and openapi.md (validator\n   and pagination). Leave `auth\u002F` out unless the user asked for auth.\n   *Done:* every package in architecture.md's layout exists. They compile only\n   after step 3 generates `gen\u002Fgo\u002Fhttpapi` and adds `api\u002Fembed.go`.\n3. **Contract** ([openapi.md](references\u002Fopenapi.md)): write `api\u002Fcommon.yaml`,\n   `api\u002Fopenapi.yaml` (`servers: \u002Fv1`, the first feature's tag), `api\u002Fembed.go`,\n   `api\u002Fcodegen\u002Fhttpapi.yaml`, one `api\u002Fcodegen\u002F\u003Cfeature>.yaml` per tag, and\n   `api\u002Fbruno\u002Fenvironments\u002Flocal.yml` ([bruno.md](references\u002Fbruno.md)).\n   *Done:* `make generate-api generate-bruno` writes `gen\u002Fgo\u002Fhttpapi`,\n   `gen\u002Fgo\u002F\u003Cfeature>api` and `gen\u002Fbruno` without errors.\n4. **Entrypoint and schema** ([architecture.md](references\u002Farchitecture.md),\n   [migrations.md](references\u002Fmigrations.md)): write `cmd\u002F\u003Cbinary>\u002Fmain.go`,\n   `internal\u002Fcli\u002F{root,serve,migrate}.go`, `internal\u002Fapp\u002Fapp.go`,\n   `migrations\u002Fembed.go` and the first migration. Write that migration by hand\n   as `migrations\u002F\u003CYYYYMMDDhhmmss>_create_\u003Cthings>.sql`: `\u002F\u002Fgo:embed *.sql`\n   doesn't compile with no files, so `make migration` only works once one\n   exists. Then run `go mod tidy`.\n   *Done:* `go build .\u002F...` succeeds.\n5. **First feature:** follow Workflow B.\n6. **Test kit** ([testing.md](references\u002Ftesting.md)): write\n   `internal\u002Ftestkit\u002F{testkit,main}.go` and `.mockery.yml`, then run\n   `go mod tidy`.\n7. **Tooling** ([tooling.md](references\u002Ftooling.md)): add `.golangci.yml`, the\n   Dockerfile, `.dockerignore`, `compose.yaml` and `.gitignore`. Write the\n   README: a Run section that is exactly `make deps-up`, `make migrate-up`,\n   `make run`, the endpoints, the dev commands (`make generate\u002Ffmt\u002Flint\u002Ftest`),\n   and the env var table (config.md).\n8. **Verify:** pass the gate below.\n\n## Workflow B: add a feature, resource or endpoint\n\nTo add an endpoint to an existing feature, run steps 1, 2 and 4 to 8 and skip\nwhatever doesn't change.\n\n1. **Spec:** add the paths, tagged `\u003Cfeature>`, plus their schemas. List every\n   error status each operation can return, using the shared responses from\n   `common.yaml`. Give request properties `example`s so the Bruno requests are\n   ready to send ([openapi.md](references\u002Fopenapi.md)).\n2. **Codegen:** for a new feature, copy `api\u002Fcodegen\u002F\u003Cother>.yaml` and change\n   `package`, `output` and `include-tags`. Then run\n   `make generate-api generate-bruno`.\n3. **Migration:** run `make migration name=create_\u003Cthings>` (a service's first\n   feature already has one from Workflow A step 4). Name every constraint, and\n   give foreign keys no `RESTRICT` ([migrations.md](references\u002Fmigrations.md)).\n4. **Feature package** `internal\u002F\u003Cfeature>\u002F`\n   ([architecture.md](references\u002Farchitecture.md),\n   [database.md](references\u002Fdatabase.md), [openapi.md](references\u002Fopenapi.md)):\n   - `model.go`: GORM model embedding `db.Base`.\n   - `errors.go`: sentinel errors whose messages are safe to show clients.\n   - `service.go`: the `Repository` interface, input structs, and `Service`\n     (`WithinTx` for anything that must be atomic).\n   - `repository.go`: a GORM implementation with `translate`.\n   - `handler.go`: the strict handler, with a\n     `var _ \u003Cfeature>api.StrictServerInterface = (*Handler)(nil)` check, a\n     `switch` mapping errors to typed responses, a `toDTO` that calls `.UTC()`,\n     and `NewRoutes`.\n   - `module.go`: provides the above, plus `fx.Decorate(NewCachedRepository)` if\n     reads are hot ([redis.md](references\u002Fredis.md)).\n5. **Wire it:** add `\u003Cfeature>.Module` to `internal\u002Fapp\u002Fapp.go`. Add the\n   `Repository` interface to `.mockery.yml`, then run `make generate-mocks`.\n6. **Tests** ([testing.md](references\u002Ftesting.md)), all in\n   `package \u003Cfeature>_test`:\n   - `main_test.go`\n   - service unit tests for each rule\n   - a repository test for each translated error\n   - an API test per operation covering the happy path and its main error\n7. **Metrics or spans** for business events, only if the feature needs them\n   ([observability.md](references\u002Fobservability.md)).\n8. **Verify:** pass the gate below.\n\n## Verification gate\n\nWork is done only when all of these hold:\n\n- `make generate` leaves `git diff -- gen\u002F` limited to the changes you intended.\n  In CI, `make check-generated` passes.\n- `make fmt` has been run and `make fmt-check` exits 0 (no diff).\n- `make lint` reports `0 issues`.\n- `make test` passes. It needs Docker for testcontainers.\n- Clean-shell run, after scaffolding or any change to the Makefile, config or\n  startup: in a shell with nothing exported\n  (`env -i HOME=\"$HOME\" PATH=\"$PATH\" bash`), run the README's Run commands\n  verbatim (`make deps-up migrate-up run`). The API must come up. Also start it\n  once with Postgres stopped and confirm the output is a single\n  `startup failed: ...` line. If the default ports are taken, set only\n  `PG_PORT`\u002F`REDIS_PORT`\u002F`HTTP_ADDR`\u002F`ADMIN_ADDR`, plus `COMPOSE_PROJECT_NAME`\n  so you don't touch someone's running stack.\n- Smoke test against that running service: `curl` each new or changed operation\n  once on its happy path and once on a 4xx path. Confirm that:\n  - 4xx responses are `application\u002Fproblem+json` with a `request_id`;\n  - `curl \u003CADMIN_ADDR>\u002Fmetrics` shows the operation's `route` template.\n- Drain check, after changes to the server or lifecycle: with `make run` up,\n  send `kill -TERM` to the server process (the pid listening on `HTTP_ADDR`,\n  e.g. `lsof -ti :8080`). For `HTTP_SHUTDOWN_DRAIN_DELAY`, `\u002Freadyz` should\n  return 503 `{\"status\":\"shutting_down\"}` while the API still answers. After\n  that `make run` should exit 0.\n",{"name":5,"description":7},"main","e4d0a0940fd53fc8a3a1e1dcb967c0a18ea8ba0f","omp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow","https:\u002F\u002Fgithub.com\u002Fheynemann","http:\u002F\u002Fwww.thumbor.org","CTO @ Flutter Brazil | Former Meta & Coinbase","2026-10-29 20:46:15",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":44},[34,37,40],{"tool":35,"command":36},"npx","npx skills add heynemann\u002Fdotfiles-stow --skill go-http-api",{"tool":38,"command":39},"bunx","bunx skills add heynemann\u002Fdotfiles-stow --skill go-http-api",{"tool":41,"command":42},"pnpm","pnpm dlx skills add heynemann\u002Fdotfiles-stow --skill go-http-api","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002FSKILL.md",true,[46,52,56,60,64,68,72,76,80,84,88,92,96,100],{"path":47,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":50,"sourceHtmlUrl":51},"references\u002Farchitecture.md","REFERENCE","参考文档",8325,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Farchitecture.md",{"path":53,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":54,"sourceHtmlUrl":55},"references\u002Fauth.md",7551,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fauth.md",{"path":57,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":58,"sourceHtmlUrl":59},"references\u002Fbruno.md",4624,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fbruno.md",{"path":61,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":62,"sourceHtmlUrl":63},"references\u002Fconfig.md",3595,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fconfig.md",{"path":65,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":66,"sourceHtmlUrl":67},"references\u002Fdatabase.md",17590,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fdatabase.md",{"path":69,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":70,"sourceHtmlUrl":71},"references\u002Ffx.md",5627,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Ffx.md",{"path":73,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":74,"sourceHtmlUrl":75},"references\u002Fhttp.md",14931,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fhttp.md",{"path":77,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":78,"sourceHtmlUrl":79},"references\u002Flogging.md",8632,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Flogging.md",{"path":81,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":82,"sourceHtmlUrl":83},"references\u002Fmigrations.md",5619,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fmigrations.md",{"path":85,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":86,"sourceHtmlUrl":87},"references\u002Fobservability.md",7369,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fobservability.md",{"path":89,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":90,"sourceHtmlUrl":91},"references\u002Fopenapi.md",23423,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fopenapi.md",{"path":93,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":94,"sourceHtmlUrl":95},"references\u002Fredis.md",12032,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Fredis.md",{"path":97,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":98,"sourceHtmlUrl":99},"references\u002Ftesting.md",16556,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Ftesting.md",{"path":101,"resourceType":48,"resourceTypeDesc":49,"sizeBytes":102,"sourceHtmlUrl":103},"references\u002Ftooling.md",18708,"https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Fhep\u002Fskills-sh\u002F.agents\u002Fskills\u002Fgo-http-api\u002Freferences\u002Ftooling.md",[105,112,119,126,133,140],{"skillNo":106,"name":107,"nameZh":6,"description":108,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":109,"categories":110,"keywords":111,"publishedAt":19},"01M7FFA0PAN04C2DVK6A7CXK6K","unity-scriptableobjects","Architect Unity 6.3 LTS data and decoupling with ScriptableObjects: config\u002Fdata assets, shared runtime variables, event channels, and runtime sets\u002Fregistries. Use when designing data-driven systems, replacing singletons\u002Fmanagers, creating .asset data with CreateAssetMenu, or when the user mentions ScriptableObject, SO architecture, or data assets.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Funity\u002Fskills-sh\u002F.agents\u002Fskills\u002Funity-scriptableobjects\u002FSKILL.md",[],[],{"skillNo":113,"name":114,"nameZh":6,"description":115,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":116,"categories":117,"keywords":118,"publishedAt":19},"01M7FF9SPKA8BC4EGCHJGGJK5P","unity-package-management","Adds, removes, upgrades, and discovers Unity (UPM) packages from outside the Editor. Use for headless or CI package installs, verifying package IDs and versions, or choosing which packages a game needs. The Unity CLI doesn't manage packages.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Funity\u002Fskills-sh\u002F.agents\u002Fskills\u002Funity-package-management\u002FSKILL.md",[],[],{"skillNo":120,"name":121,"nameZh":6,"description":122,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":123,"categories":124,"keywords":125,"publishedAt":19},"01M7FF9KBCKR352R6ZSY2BB2J3","unity-input-system","Wire player input in Unity 6.3 LTS with the Input System package: Input Actions, action maps, the PlayerInput component, and reading values via callbacks or polling. Use when the project has a .inputactions asset or com.unity.inputsystem, or when the user mentions the Unity Input System, InputAction, action maps, PlayerInput, control schemes, or rebinding.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Funity\u002Fskills-sh\u002F.agents\u002Fskills\u002Funity-input-system\u002FSKILL.md",[],[],{"skillNo":127,"name":128,"nameZh":6,"description":129,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":130,"categories":131,"keywords":132,"publishedAt":19},"01M7FF9FREKNGB4PQP8ZHTN1D8","unity-ecs-patterns","Master Unity ECS (Entity Component System) with DOTS, Jobs, and Burst for high-performance game development. Use when building data-oriented games, optimizing performance, or working with large entity counts.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Funity\u002Fskills-sh\u002F.agents\u002Fskills\u002Funity-ecs-patterns\u002FSKILL.md",[],[],{"skillNo":134,"name":135,"nameZh":6,"description":136,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":137,"categories":138,"keywords":139,"publishedAt":19},"01M7FF99B1DV7RDAY98QVFFMA9","unity-csharp-scripting","Write Unity 6.3 LTS C# gameplay scripts: the MonoBehaviour lifecycle (Awake\u002FOnEnable\u002FStart\u002FUpdate\u002FFixedUpdate\u002FLateUpdate), GameObject and component access, coroutines, and Inspector serialization. Use when creating or editing .cs scripts in a Unity project, or when the user mentions MonoBehaviour, Start\u002FUpdate, GetComponent, SerializeField, coroutines, or \"Unity script\".","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Funity\u002Fskills-sh\u002F.agents\u002Fskills\u002Funity-csharp-scripting\u002FSKILL.md",[],[],{"skillNo":141,"name":142,"nameZh":6,"description":143,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":144,"categories":145,"keywords":146,"publishedAt":19},"01M7FF8ZK7PAPR4QZ44SY9ZDAJ","unity-cli","Controls the Unity Editor and projects from the command line, driving a running Editor to edit scenes and assets or run C#. Use when asked to install or manage Editors, licenses, or projects, set up version control, build, test, configure the Unity MCP server, or run any unity command.","https:\u002F\u002Fgithub.com\u002Fheynemann\u002Fdotfiles-stow\u002Fblob\u002Fmain\u002Fomp\u002F.omp\u002Fprofiles\u002Funity\u002Fskills-sh\u002F.agents\u002Fskills\u002Funity-cli\u002FSKILL.md",[],[]]