Internal Package Building Skill

Use this skill when creating or refactoring internal Go packages.

When to create a new package

• New domain → new directory under internal/ (e.g. new feature area or bounded context).
• Existing domain → add or edit files in the existing package; do not split without a clear boundary.
• Shared cross-cutting concern (DB, config, models) → use or extend existing shared packages (internal/db, internal/models, internal/env) rather than creating a new one unless the concern is clearly separate.

Layout

• One package per directory; package name = directory name (e.g. internal/candidate_tree → package candidate_tree).
• Entrypoints live only in cmd/ (e.g. cmd/api, cmd/evaluator, cmd/importer). All shared logic lives in internal/.
• internal/ must not import cmd/; cmd packages wire and call internal packages.

Imports

• Import internal packages by module path: tarkov-build-optimiser/internal/<pkg>
• Example: import "tarkov-build-optimiser/internal/models"

Existing internal packages (use, don’t duplicate)

Checklist for a new internal package

1. Create internal/<name>/ with at least one .go file; package name = <name>.
2. Add only code that belongs to that domain; put shared DB/config in internal/db or internal/env.
3. Import other internal packages via tarkov-build-optimiser/internal/....
4. Keep the package focused; if it grows into two clear domains, consider splitting into two packages only when the boundary is obvious.
5. Add tests in the same package (*_test.go); use *_unit_test.go or *_integration_test.go per project conventions.

Boundaries to respect

• No business logic in cmd/ — cmd only parses flags/env, opens DB, and calls internal packages.
• No circular imports — internal packages may depend on each other only acyclically; if you introduce a cycle, extract a shared type or helper into a lower-level package.
• Database access — use internal/db for connections and internal/models for SQL and data types; do not add new ad-hoc DB packages.