Add API Resource

Add/change an API resource (agent-manager-service)

Spec-first, layered, per-route-authz workflow for the Go control plane. The request/response types and mocks are generated — never hand-write them.

Read first: agent-manager-service/AGENTS.md → "Golden path", "Layering", "Permissions (RBAC)", "Code generation". This skill is the executable checklist; that guide has the why.

Steps (do in order)

1. Edit the OpenAPI spec — agent-manager-service/docs/api_v1_openapi.yaml. Add/modify the path, operation, and schemas. This is the source of truth for request/response shapes.
2. make spec (needs Docker) — regenerates spec/ from the YAML. The whole spec/ dir is deleted and rebuilt, so never hand-edit a struct there; your edits would be lost.
3. Add permission(s) in rbac/permissions.go — name them resource:verb (:create/:read/:update/:delete, or :manage only where peers already do).
4. Implement controller → service → repository (controllers/ → services/ → repositories/):
   • Controller: HTTP only — parse/validate, map result→status, translate sentinel errors→HTTP.
   • Service: business logic; depend on repo/client interfaces, never concrete types.
   • Repository: persistence only (interface + impl). Add an interface if you introduce a new one.
5. Register the route with authz in api/<resource>_routes.go using HandleFuncWithValidationAndAuthz(pattern, rbac.<Perm>, ctrl.<Handler>). Every route declares its own permission.
6. Grant the permission to at least one role in rbac/predefined_roles.go (PredefinedRolePermissions). An ungranted permission is unreachable.
7. make codegen — only if you added/changed an interface (regenerates wire DI + mocks; needs moq on PATH). A new repo interface needs a //go:generate moq ... directive above its declaration — copy an existing one.
8. Write a service unit test — use the add-service-unit-test skill.

Audit logging

Step 5 audits the route automatically — a mutating route cannot ship unaudited, and api/audit_coverage_test.go fails the build if one does. Two cases need you:

• The build says cannot derive an action for audited route, or the route's rbac.Permission does not describe what it does (one permission gating several operations, or naming a different resource). Add one line to actionOverrides in audit/policy.go.
• The operation touches credentials, privileges, membership, deployment or deletion. The envelope record cannot say what changed, so add a semantic event — use the add-audit-event skill.

Never read a request or response body into a record; pass named fields via audit.Detail, which takes scalars and []string only.

Guardrails

• Multi-tenancy: the service must validate the caller's org against the target resource it loads, not just the path (RequireOrgMatch is a first-pass filter, not the enforcement layer).
• Errors: map gorm.ErrRecordNotFound → the specific utils.ErrXxxNotFound; wrap everything else with %w. Never flatten an unexpected error into not-found; never silently fall back to a default on a real error. Compare with errors.Is.
• Context: every I/O method takes context.Context first and propagates it.
• Don't re-fetch a resource already loaded earlier in the request path — pass it down.

Done checklist

• spec/ regenerated (make spec) and committed if the YAML changed.
• New permission exists in rbac/permissions.go and is granted in rbac/predefined_roles.go.
• Route registered with an authz registrar (not plain HandleFuncWithValidation unless deliberate).
• make codegen run + mocks committed if an interface changed.
• Service unit test added; make test-unit passes (includes TestEveryMutatingRouteIsAudited).
• Semantic audit event added if the operation is security-critical (add-audit-event skill).
• go build -tags=integration ./... compiles.
• CI lint clean: golangci-lint run --config .github/linters/.golangci.yaml ./...