CLAUDE.md@plugins/golang · diff

git:20260828.ee1bb05 to git:20260830.aa015d7

21 added, 40 removed. Audit A to A.

# golang Plugin

Go language discipline: conventions, idioms, error handling, concurrency, testing, toolchain practices, and LSP-powered

code intelligence via `gopls`.

## Skills

- - **`golang`** — Go language conventions, idioms, error handling, concurrency patterns, generics, project structure,

- testing, toolchain (go mod, golangci-lint, go fix, go vet), language-version gating, and LSP navigation rules

+ - **`golang`** — the language: idioms, errors, concurrency, generics, testing, project structure, toolchain,

+ language-version gating, LSP-first navigation

- **`templ`** — templ (a-h/templ) type-safe HTML templating: syntax, components, attributes, escaping and sanitization,

- styling, JavaScript data passing, code generation, and testing

- - **`charm-tui`** — Charmbracelet v2 TUI stack (`charm.land/*/v2`): Bubble Tea Elm architecture, Bubbles components, Lip

- Gloss styling/layout, Huh forms, Glamour markdown, fang/log, at-scale architecture (crush patterns), golden-file and

- teatest testing

- - **`zog`** — Zog schema validation library: schema shape, Parse against Validate, required and default semantics, tests

- and transforms, issue handling, and the zhttp/zjson/zenv adapters

+ styling, JavaScript data passing, code generation, testing

+ - **`charm-tui`** — Charmbracelet v2 TUI stack (`charm.land/*/v2`): Bubble Tea, Bubbles, Lip Gloss, Huh, Glamour,

+ fang/log, at-scale architecture, golden-file and teatest testing

+ - **`zog`** — Zog schema validation: schema shape, Parse against Validate, required and default semantics, tests and

+ transforms, issue handling, the zhttp/zjson/zenv adapters

## LSP Integration

- This plugin ships a `gopls` LSP server configuration (`.lsp.json`). When installed, Claude Code automatically connects

- to `gopls` for `.go` files, enabling LSP tools (`goToDefinition`, `findReferences`, `hover`, `workspaceSymbol`, etc.).

- The `golang` skill enforces LSP-first navigation: agents must use LSP tools for semantic code navigation (finding

- definitions, references, implementations, call hierarchies) instead of falling back to Grep/Glob pattern matching. Text

- search tools remain appropriate for non-semantic searches (comments, string literals, config values).

- **Prerequisite:** Users must have `gopls` installed and available in PATH.

+ Ships a `gopls` LSP server config (`.lsp.json`); Claude Code binds it to `.go` files on install. The `golang` skill's

+ LSP-first navigation rules assume that config ships — the two change together.

## Skill Dependencies

- The `golang` skill provides language-specific conventions and wins on any question of how Go code reads. The `templ`,

- `zog`, and `charm-tui` skills each own one library stack and defer to `golang` for language conventions. Each states

- that boundary in its own Integration section, and each ships a `references/` directory loaded on demand.

- One boundary inverts: the `zog` key-naming rule outranks Go naming inside a `z.Shape`, because a shape key names a

- struct field rather than reading as Go code.

- All skills assume the `the-coder` plugin for language-agnostic coding discipline (discovery, planning, verification).

+ - `golang` wins on any question of how Go code reads; `templ`, `zog`, and `charm-tui` each own one library stack and

+ defer to it. All four Integration sections state that boundary — moving it means editing four files

+ - One boundary inverts: the `zog` key-naming rule outranks Go naming inside a `z.Shape`, because a shape key names a

+ struct field rather than reading as Go code

## Plugin Scope

- This plugin covers Go language specifics and Go-specific tooling like templ and gopls. Language-agnostic coding

- practices (discovery, planning, verification) are provided by the `the-coder` plugin. Platform-specific concerns

- (backend, CLI) are provided by their respective platform plugins.

+ Go language specifics and Go-specific tooling (gopls, templ, Charm, Zog). Language-agnostic workflow belongs to

+ `the-coder`; platform concerns to `backend` and `cli`.

## Language Version References

- The floor-version index lives in the `Language Version` section of `skills/golang/SKILL.md` — it decides what the

model may write, so it stays inline rather than in a reference the model can skip

- `skills/golang/references/versions/go1.NN.md` holds one version each: its additions, the behavior changes its `go`

directive gates, and its traps

- Body rules and the topic references carry no version gates — the index is the only place a floor version appears

- When a Go version ships: add `references/versions/go1.NN.md` from

`https://raw.githubusercontent.com/golang/website/master/_content/doc/go1.NN.md`, add one index line naming only the

- features the skill's own rules reference, extend the route-list version range, update `.dev/reference-inventory.json`,

- and drop any gate the new floor makes obsolete

+ features the skill's own rules reference, extend the route-list version range, update

+ `skills/golang/.dev/reference-inventory.json`, and drop any gate the new floor makes obsolete

## Conventions

- - Go code prioritizes simplicity and explicitness over abstraction

- - Error handling is mandatory — never discard errors with `_`

- - Interfaces are defined consumer-side, not producer-side

- - LSP tools are required for code navigation — Grep/Glob only for non-semantic text search

+ - Library API claims are verified against the module source in the Go module cache, never against memory or upstream

+ prose. A module missing from the cache is resolved through `proxy.golang.org` — absence from the cache is not evidence

+ it does not exist

- Every skill in this plugin splits its references by load condition, and every pointer states the condition that loads

it at the point of need. A catalog block listing the reference set is the anti-pattern

- A reference is one hop from SKILL.md — a reference never routes to another reference, nor back to SKILL.md

- - `golang` skill references split by kind: `references/conventions/` for topic depth, `references/versions/` for

+ - `golang` splits its references by kind: `references/conventions/` for topic depth, `references/versions/` for

per-release notes

- - Library API claims are verified against the module source in the Go module cache, never against memory or upstream

- prose. A module missing from the cache is resolved through `proxy.golang.org` — absence from the cache is not evidence

- it does not exist

- - The `go` directive in `go.mod`, not the installed toolchain, decides which language features and stdlib symbols apply

- - All `.templ` files must be compiled with `templ generate` before building

- - Generated `*_templ.go` files must be committed to version control