feat: usage-driven optimization and Go 1.27 support (v0.5.0)

[sebastian-iancu]

Usage-driven optimization (v0.5.0)

A usage analysis of this plugin found the router loaded often but the focused skills it routes to
rarely followed, several skills with no concrete trigger words, and the two slash commands
effectively undiscovered. This release turns those findings into changes, shrinks the surface, and
adds Go 1.27 support (the floor stays Go 1.26.4+).

What changed

Routing

• go-coding gains a Route, then load diff→skill table and a minimum checklist for when a second
  skill load is not affordable; its description leads with the trigger.
• go-layout, go-concurrency and go-testing descriptions name the words a prompt or diff
  actually contains.
• The SessionStart banner names the router→skill hop and go-reviewer, and offers /go-lint-setup
  only when the workspace has no golangci-lint config.
• A PostToolUse/afterFileEdit hook (hooks/skill-nudge.sh, dual-host) names one matching skill
  after a Go edit. Under Claude Code it matches only the text the edit adds — new_string, or
  content for a write — not the file, not the deleted text, and not the surrounding lines the
  payload echoes back; Cursor passes a path alone, so there it matches the file and says so. Once
  per skill per session, at most three per session. Delivered as a hook systemMessage under
  Claude Code, where the model actually sees it; a plain line under Cursor.

Smaller surface

• go-linting is removed, its content merged into go-lint-setup (re-fronted as "scaffold, adopt,
  or debug").
• /go-explain is removed: one-shot lookups are what the focused skills already do, with the same
  citations and the code in view. One invocation in four weeks of transcripts.
• All seven remaining descriptions rewritten trigger-first and 10% shorter, with no trigger dropped.

Other

• "Writing for the human" in the router and go-reviewer: anything a person reads — PR text, review
  findings, a question — states the effect before the mechanism, in plain English, kept short.
• One review seat per diff, plus implementer/reviewer brief templates for orchestrators (a subagent
  does not inherit the parent session's skills).
• scripts/usage-report.py measures skill and agent adoption from local transcripts;
  docs/testing.md documents what counts and the target.
• Go 1.27: cited hints in go-idioms (the new go fix modernizers, json/v2-backed encoding/json,
  generic methods, stdversion by default), a golangci-lint ≥ v2.13.0 note, install docs
  recommending 1.27.x on a 1.26.4+ floor, and a CI matrix over 1.26.x and 1.27.x.
• rules/go-context.mdc (the Cursor mirror) is level with the router again: it had the topic table
  but neither the diff→skill mapping nor the minimum checklist, so a Cursor session got the index
  and none of the routing.
• scripts/hooks-test.sh: 28 bash tests over all three hooks, on production-shaped payloads,
  asserting exit status as well as output, with committed self-tests proving the silence
  assertions can fail. Runs in CI on both Go legs.
• scripts/validate.py gains two checks that previously needed a human reading two files side by
  side: hook parity (the same hooks/*.sh wired for the equivalent event on both hosts, each
  existing and executable, none left unwired) and doc inventories (every shipped skill, agent
  and hook named where the docs claim to list them). Both were run against a deliberately broken
  tree first. The inventory check found a real gap on its first run — no triggering check for
  format-on-save in docs/testing.md — now added.
• python3 scripts/validate.py --selftest rebuilds each structural check's failure case in a
  temporary tree, requires the check to catch it, then requires it to go quiet once the defect is
  removed. Eight checks, run in CI: a green validator over a valid tree never proved the checks
  still check.

Verification

• ./scripts/validate.sh, ./scripts/hooks-test.sh (28/28), python3 scripts/validate.py --selftest (8/8), claude plugin validate . all green at
  the branch head.
• Always-on context: the descriptions loaded into every session total 5,425 characters, against
  5,658 on main — the surface costs less than the released version while carrying more trigger
  words. (An intermediate commit on this branch peaked at 6,513.)
• Live trigger checks need an interactive session and have not been run: the five checks under
  Local triggering tests in docs/testing.md, including that the model acts on a nudge rather
  than the line merely appearing.
• CI runs on push.

Addressed from the external review (2026-09-04)

• Nudge matched the raw payload, not the edit. A real PostToolUse payload carries old_string
  and a tool_response echo, so deleting an fmt.Errorf — or editing beside one — still nudged
  go-errors. Fixed, and two fixtures now fail against the old implementation.
• Four Go 1.27 claims re-verified against their sources. encoding/json/v2 no longer says
  "prefer" (the release notes say users are not required to migrate); embedlit is the
  promoted-field rewrite, not the builder one; unsafefuncs gained its table row; stdversion is
  dated to when go test starts running it by default. httptest.NewTestServer carries its
  signature.
• Doc drift: README lede, the Cursor commands claim in AGENTS, the CI line in docs/testing.md,
  the gopls pin (now v0.23.x, the Go 1.27 line), and the Claude-only variable in the Cursor rule.
• Not changed, with reasons. The Cursor rule keeps both the hop table and the minimum checklist:
  the checklist is explicitly the fallback for when opening a skill is not affordable, and stripping
  Cursor back to a bare index gives that host less than it has today. golangci-lint run --fix
  stays in the rule — it is editing guidance; the ban on in-place flags belongs to go-reviewer,
  which has it. Live triggering on both hosts is still outstanding and still blocks the tag.

Notes for reviewers

• Three defects in the implementation plan's own code were caught here and fixed: a multi-file ls
  existence check that misfired whenever any one name was missing; a silence assertion that could
  never fail; and a nudge printed to stdout, which under Claude Code reaches only the transcript and
  never the model.
• The nudge's false-positive rate is what drove the edit-vs-file change: matching the whole file
  claimed "this edit touches an error path" for 43% of non-test files in one real Go SDK and 65% in
  another, because most Go files define a sentinel somewhere.
• Hook timeouts are in seconds ("timeout": 5).

🤖 Generated with Claude Code