golang-user-conventions

Files (7)

• PKGSITE.md
• SKILL.md
• TUI.md
• WEB.md
• release.yml · templates/
• nord.go · templates/theme/
• nord_huh.go · templates/theme/

SKILL.md (first lines)

# Go CLI/TUI Project Conventions

Standards for building small, focused Go tools — single self-contained binaries
that are easy to share and cross-compile. These are opinionated defaults, not
laws. Scale up or down based on the project.

## Conditional sections

This skill is split across files. SKILL.md (this file) covers conventions that
apply to any Go CLI. Two satellite files cover situational topics — only read
them when relevant:

- **`TUI.md`** — Bubble Tea, lipgloss, huh, theming, the `Width()` footgun,
  shelling out to `$EDITOR`.
  Read when: `go.mod` imports `github.com/charmbracelet/...`, **or** the user's
  request mentions a TUI / Bubble Tea / interactive terminal UI / list / form /
  picker, **or** you're starting a new project and the user has described
  something interactive.
- **`WEB.md`** — embedded web UI conventions (`serve` subcommand, `go:embed`,
  `http.Handler` patterns, JSON API).
  Read when: the project has a `serve` subcommand or imports `net/http` for
  serving (not just fetching), **or** the user's request mentions a web
  dashboard, browser UI, or `serve` command.
- **`PKGSITE.md`** — the official pkg.go.dev API (v1beta) for querying
  module/package metadata, versions, exported symbols, importers, and
  vulnerabilities.
  Read when: you need to look up the latest tagged version of a third-party
  module, check known vulnerabilities, list a package's exports, find what
  imports a package, or search the public Go ecosystem — **or** the user
  mentions pkg.go.dev, `pkgsite-cli`, or the v1beta API.

Don't load these defensively — the savings only work if you actually skip
them when they don't apply. If a session shifts direction (a CLI gains a TUI,
a tool grows a `serve` command), pull the satellite file in mid-session.

Reusable code lives under `templates/` (e.g. `templates/theme/nord.go` for
Nord-themed lipgloss + huh styles) and is referenced from the satellite that
covers it.  There is also an example of a straightforward golang GitHub action to build
and publish a release in `templates/release.yml` taken from a project called 'agent-issue-tracker' 
that creates the `ait` binary.

## Project Layout

Choose the simplest layout that fits the project's complexity:

### Single file (`main.go` only)
For scripts-with-a-GUI. Under ~400 lines, no real domain logic, mostly glue
between config/OS/UI. Example: a music shuffler, a quick file picker.

### Flat `package main`, multiple files
When you have distinct concerns (storage, domain types, UI) but they're tightly
coupled and nobody will import the code as a library. Split by concern:

```
myapp/
  main.go       # Entrypoint, arg parsing, wiring
  store.go      # Database access, queries, migrations
  types.go      # Domain types, enums, validation
  ui.go         # Bubble Tea model, update, view
  *_test.go     # Tests alongside source
  go.mod
```

This is the default for most projects.

### `internal/<name>/` package
When the tool has 5+ source files, subcommands, a public-facing contract (JSON
API, stable exit codes, documented ID format), or genuinely separable concerns.
The `internal/` boundary prevents accidental imports.

```
myapp/
  main.go                  # Thin: flag extraction, open DB, dispatch
  internal/myapp/
    app.go                 # Command router, handlers
    store.go               # DB access, schema, migrations
    migrate.go             # Migration definitions
    types.go               # Domain types, validation
    config.go              # Config detection, defaults
    format.go              # Output formatting
  main_test.go             # Integration tests
  go.mod
```

### Multiple distinct domains under `internal/`
When the project has genuinely separate domains (not just layers of one domain),
use separate packages under `internal/`. For example, a tool that fetches RSS
feeds, stores data, and serves a web UI has three distinct domains:

```
myapp/
  main.go                  # Entrypoint, wiring
  internal/
    db/db.go               # Storage layer
    models/models.go       # Shared data types
    youtube/               # External API integration
      youtube.go
      rss.go
      fetch.go
    web/                   # Embedded web UI
      server.go
      static/index.html
  go.mod
```

This is appropriate when each package has its own distinct responsibility and
the packages communicate through the shared models. Don't flatten genuinely
separate domains into a single package just for consistency.

**Heuristic:** if you're reaching for more than ~4 source files, or the tool has
subcommands, use `internal/`. Otherwise flat is fine.

**Module path and binary name:** always `go mod init github.com/<owner>/<repo>`,
never a bare name - a bare module path permanently breaks
`go install github.com/<owner>/<repo>@latest`, because Go refuses to install
when the requested path doesn't match the declared one. And `go install` names
the binary after the last element of the main package's path, so when the repo
and command names differ (`agent-issue-tracker` vs `ait`), put the entrypoint in
`cmd/<toolname>/` instead of the repo root and users install with

From ohnotnow/agentic-stuff, MIT.

More from ohnotnow/agentic-stuff