adept code style

Conventions for Go in github.com/itaywol/adeptability. CI enforces formatting and lint; the rest is reviewed.

Formatting & lint (enforced)

• gofmt + goimports — tabs for indentation, grouped imports (stdlib / third-party /

local). CI fails on any unformatted file.

• golangci-lint run (.golangci.yml): errcheck (incl. type assertions), staticcheck,

govet, gocritic, revive (every exported symbol needs a doc comment), errorlint, nilerr, bodyclose, prealloc, unconvert, misspell, unused, ineffassign.

Errors

• Always wrap with context and %w: fmt.Errorf("clone %s: %w", url, err).
• Compare with errors.Is against the sentinels in pkg/adept/errors.go

(ErrSkillNotFound, ErrMergeConflict, ErrBudgetOverflow, …). Never match on error strings. Need a new category? Add a sentinel there.

• errcheck is strict — handle or explicitly _ = an ignored error, and say why if it isn't

obvious. Don't drop an error that loses data.

Structure

• Composition root, no globals. Concrete implementations are wired behind interfaces into

*Deps in internal/cli/deps.go. No package-level mutable state, no init() side effects. Take dependencies as parameters so code is testable with fakes/mocks.

• `pkg/adept` is types-only. Keep it dependency-light and stable; behavior lives in

internal/. (Example: SkillIDPattern is a string in pkg/adept, compiled in internal/canonical — don't add a regexp import to pkg/adept.)

• Doc comments are full sentences starting with the symbol name (// NewRoot builds …).

Readability

• Small, single-purpose functions; prefer early returns over deep nesting.
• Name things for what they are; avoid one-letter names outside tight loops/receivers.
• No magic numbers/strings — name on-disk paths and limits as constants (see

pkg/adept/constants.go).

• Comments explain why, not what. Keep them in sync with the code — a stale comment is a

bug.

Invariants you must not break

1. Identity is (id, content-hash) — no version numbers as a sync signal.
2. Secrets never written to disk — API keys come from the environment at call time.
3. Harness models differ (per-skill / single-file / aggregator) — renderers and importers

must respect each; aggregators parse their own section markers and honor byte budgets.

1. Canonical layout <root>/skills/<id>/SKILL.md; the directory name is the authoritative id.