go-package-hygiene

name	go-package-hygiene
description	Use when adding a new `.go` file to any `internal/` package, when an existing file grows past ~400 lines, when introducing a helper function, or when considering a new package. Enforces itervox's package dependency order, file-size discipline, reuse of stdlib builtins, and the no-premature-utils-package rule.

Go Package Hygiene (itervox)

Apply these rules whenever you touch Go code under internal/ or cmd/.

1. Respect the package dependency order

domain → tracker, prompt, logbuffer, prdetector
workflow → config → workspace
agent           (imports domain, config)
orchestrator    (imports agent, config, domain, logbuffer, prdetector, prompt, tracker, workspace)
app             (imports domain, tracker)
server          (imports domain, config)
cmd/itervox     (wires everything)

Never introduce a cycle. Before adding an import, trace it: does it reverse the arrow? If domain starts importing tracker, stop. Move the type, not the import.

2. No utils/ or helpers/ package — ever

Shared code lives in the most specific package that owns the concept. Function used only inside orchestrator/? It belongs there. Type shared by orchestrator/ and app/? It belongs in domain/. A utils package is where architecture goes to die.

3. File size discipline (~400 lines)

When a file grows past ~400 lines, split by responsibility, not alphabet. The canonical example is internal/orchestrator/: event_loop.go, worker.go, snapshot.go, dispatch.go, reconcile.go, retry.go, reviewer.go, issue_control.go, ssh_host.go, logging.go, state.go. Each file name names a concern.

4. Reuse stdlib builtins — do not reinvent

• maps.Copy(dst, src) — not a for k, v := range loop
• max(a, b) / min(a, b) — not if/else clamping
• slices.Contains, slices.Index, slices.Sort — not handwritten loops
• cmp.Or(a, b, c) — not nested fallback ifs
• strings.Cut — not strings.Index + manual slicing

5. Grep before writing a new helper

Before adding func somethingX(...), search the current package for an existing helper. Then the parent package. Extend or reuse — do not create a second helper with a similar name. Common targets: internal/agent/helpers*.go, the bottom of internal/config/config.go, internal/orchestrator/*.go.

6. Error conventions

• fmt.Errorf("package: lowercase message: %w", err) — always wrap with %w
• errors.New("package: static message") for static strings
• errors.Is / errors.As for checking wrapped errors — never string matching

7. Logging via log/slog

Structured key/value, not log.Printf. Canonical:

slog.Info("orchestrator: dispatched", "identifier", issue.Identifier, "profile", profileName)

Message is a short sentence; details are key/value pairs.

8. Tests in the same package (whitebox)

Unexported helpers are tested via helpers_test.go in the same package. Use package foo_test only when deliberately testing the public surface from outside.

9. Exported symbols need doc comments

golangci-lint enforces this. Describe behavior, not type:

• Good: // RunTurn executes one claude turn as a subprocess and streams progress to onProgress.
• Useless: // RunTurn is a method.

10. New package creation requires justification

Adding internal/<name>/ requires that the concept (a) fits in no existing package and (b) has multiple consumers. Single-use code stays in its consumer.

Verification

go vet ./...
golangci-lint run ./...
go test -race ./...
make verify

Common mistakes

• Duplicating a helper across two files in the same package instead of grepping first
• Creating internal/util/ or internal/helpers/ as a "temporary" dumping ground
• Letting domain import tracker and creating a cycle
• Handwritten for k, v := range src { dst[k] = v } instead of maps.Copy
• log.Printf("dispatched %s", id) instead of slog.Info("orchestrator: dispatched", "identifier", id)
• Splitting a 600-line file into a.go / b.go instead of by responsibility
• Adding a new internal/<name>/ package for a single-call-site helper