| name | go-project |
| description | Scaffold a Go project with the canonical layout — cmd/ entrypoints with a thin main, private packages under internal/ (no pkg/), a separate tools module pinning Go developer CLIs (invoked directly via go tool -modfile=tools/go.mod, no GOBIN), Node tools pinned in package.json and run from node_modules/.bin, and a Makefile whose pr target runs the full local gate. Use when creating a new Go project, service, or repository, or restructuring an existing Go repo to the standard layout; pinning Go or Node developer tooling or adding a tools module to an existing repo; creating or adding a Makefile with the standard targets (pr, fmt, vet, test, fuzz, build); or deciding where Go code should live (internal vs pkg). |
| license | MIT |
Scaffold a Go project
Creates a Go repository with the canonical layout, pinned tooling, and a Makefile gate. Apply the
go-style and go-testing skills while filling in real code, and wire releases with the
go-release skill.
1. Lay out the tree
cmd/<app>/main.go # one directory per binary; main stays thin
internal/<pkg>/ # all business logic; the compiler enforces privacy
tools/ # separate Go module pinning developer CLIs
Makefile
go.mod go.sum
package.json # pins Node tooling (prettier, markdownlint-cli2)
- One package per concern, named for what it provides (
clientmap, token, telemetry) — never
util, common, or helpers.
- No
pkg/ directory: code stays under internal/ until a consumer outside the repo needs it.
2. Keep main thin
Copy templates/main.go: main derives the root context from process
signals, builds the JSON slog logger, and delegates to run(ctx, log, args) error. Everything
testable lives in run and the internal/ packages; main is the only place that may call
os.Exit.
3. Pin Go developer CLIs in a separate tools module
Developer tools (addlicense, goreleaser, syft, …) are pinned in tools/go.mod — its own
module, so their large dependency graphs never touch the application's go.mod:
module example.com/myapp/tools
go 1.26
tool (
github.com/google/addlicense
github.com/goreleaser/goreleaser/v2
github.com/anchore/syft/cmd/syft
)
Add a tool with go -C tools get -tool <module>@<version> and invoke it with
go tool -modfile=tools/go.mod <name> — no GOBIN, no prebuilt binaries: Go compiles the tool
into the build cache on first use and reuses it after that.
go tool -modfile=tools/go.mod addlicense -f LICENSE -v cmd internal
-modfile points the go command at the tools module while the tool keeps running in the current
directory, so relative paths work and every tool — including goreleaser, which resolves
.goreleaser.yaml and ./cmd/... against its working directory — is invoked the same way. The
flag anchors on the module root, so it needs the root go.mod this scaffold already has; a repo
with no root Go module instead adds a root go.work with use ./tools and runs plain
go tool <name>. Never combine the two — -modfile cannot be used in workspace mode — and never
add a developer tool to the root go.mod or run a global or npx-downloaded copy.
4. Create the Makefile with the pr gate
Copy templates/Makefile and set APP. It provides:
pr — the full local gate, in order: license tidy fmt vet test fuzz build snapshot. It must
pass before every commit.- Direct
go tool -modfile=tools/go.mod invocations of the pinned CLIs (addlicense,
goreleaser) — the build cache compiles and reuses them, so there is no GOBIN and nothing to
install. Never emit a GOBIN, TOOLBIN, a tools/.bin directory, or a -C tools tool step —
the pinned CLIs are always run via go tool -modfile=tools/go.mod <name>.
- Version metadata (
git describe, short SHA, build date) stamped via -ldflags -X into
internal/version — the same import path GoReleaser injects on release (see the go-release
skill).
fuzz parameterized by FUZZ= / FUZZTIME= / FUZZ_PKG=.
5. Pin Node tooling
package.json pins prettier and markdownlint-cli2 as devDependencies at exact versions
(no ranges). npm ci installs them reproducibly from package-lock.json, and the Makefile runs
them from node_modules/.bin ($(NPMBIN)/…).
6. Finish
- Write the first
internal/ package and its tests (go-style, go-testing skills).
- Document every package and exported identifier as you go (
go-docs skill).
- Wire releases, CI, and Dependabot with the
go-release skill.
- Run
make pr and make sure it passes before committing.
