Golang

These are the conventions for Go code in this repo, which targets the Go version in the root go.mod. Some existing code breaks these conventions; do not copy it.

Scope. The language conventions (comments, constants and types, functions, errors, logging style, testing style) apply to all Go in the repo. The package map, service wiring, and testenv guidance describe server/; its internal packages cannot be imported from cli/ or functions/. In those trees, use the accessible local equivalent (Functions logging attributes live in functions/internal/attr) and search the target tree before introducing a helper or dependency. Do not export server internals or add a shared package just to follow this skill.

• Prefer the standard library and the dependencies already in go.mod over adding a new one.
• Do not edit files that start with a "DO NOT EDIT" comment; change their source and regenerate.
• If you are unsure about a convention or implementation detail, say so instead of guessing.

Tooling

Never invoke go bare. Use a mise task when one exists: for server tests, mise run test:server runs from server/ and accepts the same arguments as go test (mise run test:server ./internal/oops/). Otherwise prefix the command with mise exec -- (mise exec -- go test ./server/internal/oops/). A bare go may resolve to a system toolchain that differs from the mise pin, which fails every stdlib compile with a version … does not match go tool version error. The same applies to the other pinned tools (golangci-lint, gotestsum, sqlc, gomigrate) and to goa, which is a go.mod tool directive and inherits whichever toolchain invoked it.

Run mise lint:server before finishing server changes and fix what it reports. cli/ and functions/ do not run the glint analyzers, so follow this skill there by hand. Fix the code or use an existing compliant helper instead of adding nolint directives. Suppression is a last resort: use it only when complying with the rule would defeat the intended behavior or test, and explain why a compliant alternative cannot work.

If a suppression is necessary, scope it to the reported line and name the specific linter and reason using //nolint:<linter> // <reason>; for glint, use //nolint:glint // <analyzer>: <reason>. Put it on the reported line (the func line for a whole test), or directly above a multi-line statement inside a function or trailing its first line. Never suppress an entire file; glint directives may not sit above the package clause or a top-level declaration.

Which skill

When a change touches one of these areas, activate the matching skill as well:

Packages

Reuse existing packages

Before writing a helper, fake, or client, search the current package (including its setup_test.go) and the target tree for one that already does the job; grep for the concept (an RFC number, a vendor name). Extend what you find rather than adding a near-duplicate beside it, and when the owning package lacks a variant you need, add it there.

Reusable packages in server/internal:

Package boundaries

Give a cohesive domain its own subpackage (e.g. dpop, remotesessions/delegation) instead of growing a large parent package. Domain types live in the domain package, not in the metrics, view, or handler package that happened to need them first.

Comments

Comments describe current intent and behavior.

• Do not narrate the edit you just made ("previously this returned X, now it returns Y", "renamed from Foo"); that belongs in the commit message or PR body. Build tags, //go: directives, and TODO(TICKET-123) notes are not narration.
• Mark a deprecated symbol with a trailing Deprecated: use X instead paragraph (the form gopls and pkg.go.dev surface), and keep the rest of its doc in the present tense.
• Do not write "see X" comments that send the reader elsewhere ("see Registry for locking rules"); the target moves and the pointer goes stale. State the fact where the reader needs it ("callers must hold Registry.mu"). Referencing a symbol, ticket, or spec that the comment is about is fine. When the full explanation is too long to restate, document it on the type or package that owns the invariant and give each use site the one-line consequence.
• Document each struct field with its own comment, at least on exported types. gofmt does not catch the mistakes here: a comment above only the first field of a group documents just that field, so go doc and editor hovers show nothing for the rest, and a blank line between a comment and its field silently detaches it. Put a blank line before each field's comment after the first. Grouped const/var blocks and interface methods follow the same rule, and a comment above const ( documents the block, not its specs.

type Config struct {
    // ReadTimeout bounds how long the client waits for response headers.
    // Retries each get a fresh budget, so a request can exceed this in total.
    ReadTimeout time.Duration

    // WriteTimeout bounds how long the client spends sending the request body.
    WriteTimeout time.Duration
}

Constants and types

• Name the actual state or behavior. Avoid relative labels such as legacy and modern in identifiers, comments, and messages. Use the condition or mechanism they represent (for example, agentIdentityIsNotConfigured or creatorAttributedExecution). Choose the name from the actual condition. Preserve externally contracted values, including metric labels used by queries or alerts, unless the change includes a compatibility plan.

• Name and explain numeric values. Limits, sizes, budgets, timeouts, retry counts, and thresholds are named constants, each with a comment saying what the value represents and why it was chosen. Write bitwise and multiplied sizes with the human-readable value alongside. Obvious literals (0, 1, 2 for halving or pairs, base 10 in strconv) need no name.

  const (
      // maxManifestBytes bounds a plugin manifest upload. Real manifests are
      // under 64 KiB; 1 MiB leaves headroom without letting one request
      // hold a large buffer.
      maxManifestBytes = 1 << 20 // 1 MiB
  
      // syncRetryTTL is how long a failed sync waits before retrying. The
      // upstream API rate limits per hour, so retrying sooner cannot succeed.
      syncRetryTTL = time.Hour
  )

• Fully initialize struct literals that exhaustruct covers. Its excluded types and paths (test files among them) are listed in server/.golangci.yaml. When adding a field, update every covered literal, including zero values (MyStruct{} becomes MyStruct{NewField: nil}).

• Use new(expr) for a pointer to a value (Go 1.26+, e.g. new("secret")) instead of a local ptr helper.

• Use string enums. Declare type fooOutcome string with string constants so values go straight into logs and metric dimensions. If the zero value means "unknown", declare that constant explicitly rather than relying on "".

• Use struct types for context keys. Declare a distinct unexported type per key (type domainKey struct{}) so keys from different packages cannot collide.

• Do not alias constants or variables. If another package or an external test needs one, export it where it is declared (including instead of an export_test.go alias). Keep a separate name only when it deliberately decouples from its source: it selects a policy that must stay a one-line change (const DefaultInEffect = Version20250326), or it names a separate concept that shares the value today but may diverge. Say in its doc comment why the name must stay separate.

• Use protocol constants, not string literals. If a string's meaning comes from an RFC or spec (OAuth parameters and error codes, HTTP statuses and methods), use the constant from its owning package (see Reuse existing packages, and net/http for HTTP), and add one there if it is missing.

• Type contractual JSON. A JSON object whose shape is defined by a standard or an external contract gets a named struct type with a comment on each field, not a map[string]any.

Functions

• Take context.Context as the first argument of any function that does I/O, runs queries, or waits. To wait, use a time.Timer or time.After in a select on ctx.Done(), a Temporal timer, or ratelimit. In Temporal workflow code, use workflow.Now(ctx) for the current time.
• Pass time-dependent logic a now time.Time argument, or give its struct a now func() time.Time field, instead of calling time.Now() inside, so tests control the clock.
• Extract a function only when it adds reuse, names non-trivial logic, adapts a type to a required interface, or provides a seam that tests need. A function that only forwards to another call does none of these, in production code or tests (func newFoo(t) *Foo { return NewFoo(deps) }, func seedX(...) { repo.New(db).InsertX(...) }). When a signature changes, update the callers instead of adding a wrapper that keeps the old signature.

// Bad: the wrapper adds no abstraction and has one caller.
func (s *Service) listWidgets(ctx context.Context) error {
    return s.repo.ListWidgets(ctx)
}

func (s *Service) List(ctx context.Context) error {
    return s.listWidgets(ctx)
}

Call s.repo.ListWidgets(ctx) directly from List.