Update to Go: Production Engineering

{
  "description": "Use for exported Go APIs, packages, modules, versioning, and compatibility. Do not use for local semantics or wire protocols.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 253
    },
    {
      "relative_path": "evals.json",
      "size_in_bytes": 2975
    },
    {
      "relative_path": "references/api-evolution.md",
      "size_in_bytes": 701
    },
    {
      "relative_path": "references/module-release-compatibility.md",
      "size_in_bytes": 4151
    },
    {
      "relative_path": "skill.json",
      "size_in_bytes": 2650
    }
  ],
  "name": "go-project-and-api-design",
  "skill_md_contents": "---\nname: go-project-and-api-design\ndescription: \"Use for exported Go APIs, packages, modules, versioning, and compatibility. Do not use for local semantics or wire protocols.\"\nlicense: Apache-2.0\ncompatibility: \"Go 1.24 or newer; module and toolchain behavior must match the repository's declared versions.\"\n---\n\n# Go project and API design\n\nOrganize code around stable behavior and dependency direction, not a universal directory tree.\n\n## Map the dependency graph\n\nIdentify the domain decision, its inputs and effects, the outer mechanisms that provide them, and the package that owns each contract. Core behavior should not need to import HTTP, SQL, a broker, or process bootstrap merely to be exercised.\n\n## Design packages\n\n- Give a package one coherent reason to change and a name describing what it provides.\n- Keep `internal/` boundaries deliberate; they control import visibility, not architecture quality.\n- Avoid catch-all `util`, `common`, `models`, and `interfaces` packages.\n- Put interfaces with consumers unless an external implementation contract requires otherwise.\n- Use `cmd/<name>` for multiple binaries when useful; keep `main` thin enough that startup can report errors deterministically.\n\n## Design APIs from caller decisions\n\n- Make zero values useful when that is cheap and unambiguous; otherwise require construction.\n- Use functional options for a growing set of independent optional settings, not required arguments or every constructor.\n- Validate immutable configuration at startup and distinguish secret values from ordinary settings. For reloadable configuration, parse and validate a complete candidate snapshot before atomic publication; retain the last known-good snapshot on failure.\n- Return concrete types unless callers need substitution at that boundary.\n- Preserve error, cancellation, and ownership contracts in names and documentation.\n\n## Manage evolution\n\nTreat exported Go APIs, serialized fields, schemas, config keys, CLI flags, and default behavior as compatibility surfaces. For breaking storage or protocol changes, design expand/migrate/contract steps that tolerate mixed versions and rollback.\n\nPin CI and release inputs by immutable versions. Keep generated files reproducible and make the source of truth explicit. Do not add dependencies or frameworks without a demonstrated capability or maintenance benefit.\n\nRead [references/api-evolution.md](references/api-evolution.md) for compatibility and constructor decisions. For a public-module release or major-version migration, use [references/module-release-compatibility.md](references/module-release-compatibility.md) to inventory consumer-visible contracts and prove the cutover outside the producer repository.\n\n## Output contract\n\nState the dependency invariant, compatibility constraints, and smallest design that satisfies them. Avoid architecture ceremony, speculative abstractions, and repository-wide reshaping.\n"
}