galactic-bloodshed

Add a new field to a persisted entity (Race, Ship, Planet, Sector, ServerState, etc.). Use when extending a struct that is stored as JSON in SQLite, adding a flag/counter/name to an existing entity, or migrating a feature from filesystem state to database state. Covers struct edit, Glaze meta update, default values, optional schema/index changes, and updating call sites and tests.

Use clang-query AST matchers to find every call site that needs to change before a codebase-wide refactor (e.g. migrating direct field access to accessor methods, finding all uses of a deprecated API). Use when a refactor touches dozens of files and grep would over-match, when verifying every mutation site has been migrated, or when planning a safe API change. Covers compile_commands.json setup, writing matchers, running across the tree, and pairing matcher output with replacement.

Implement a new player-facing game command in gb/commands/. Use when adding a command, registering a command alias, validating scope/permissions, parsing argv, or producing player output. Covers the command file template, registration in GB_server.cc, CMakeLists wiring, and the standard validate/parse/act/respond structure.

Write unit tests that exercise EntityManager and repositories against an in-memory SQLite database. Use when adding a *_test.cc file under gb/, verifying database persistence, testing a command end-to-end, or debugging segfaults caused by missing schema initialization. Covers the in-memory DB setup, schema init order, cache-clear verification, GameObj construction in tests, and CMake/CTest wiring.

Iterate over collections of game entities (races, stars, planets, ships, commodities) using XxxList helpers. Use when scanning every race/star/planet/ship in a command, turn-processing loop, or test, when deciding between read-only and mutable iteration, or when migrating a numeric for-loop to the entity list pattern. Covers ::readonly() factory, mutable handle iteration, composite-key lists (PlanetList), ShipList iteration modes, and when raw numeric loops are still appropriate.

Access game entities (races, ships, stars, planets, sectors, commodities) through EntityManager. Use when reading or modifying any persistent game entity in commands, services, or turn processing. Covers peek_* vs get_*, the two-step RAII handle pattern, EntityNotFoundError handling, and validated vs user-input ID rules.

Generate git commit messages from the current repository diff. Use when asked for a commit message, commit summary, or to review staged or unstaged changes before writing a commit message. Always inspect the git diff first and return the suggested message in markdown.

Apply the C++26 module file structure used throughout this codebase. Use when creating any new .cc, .cppm, or test file, deciding between import gblib/import std vs include, choosing module partition names, or fixing module-related build errors. Covers global module fragment, import order, partition syntax, and when (rarely) #include is allowed.

Decide which layer (DAL, Repository, Service, Application/Command) a new piece of code belongs in. Use when adding a feature that touches the database, when reviewing whether SQL or game rules are leaking across layers, or when planning a refactor that crosses persistence and game-logic boundaries. Covers layer responsibilities, allowed dependencies, and common cross-layer mistakes.

Author or update a phased plan-*.md document for a multi-step migration or refactor. Use when a change is too large for a single commit, when coordinating database/architecture migrations across many call sites, or when the user asks for a "plan" before implementation. Covers the standard plan structure used in this repo (plan-database, plan-enrol, plan-telegram, plan-strong-id-governor, plan-nogo), per-step completion markers, commit-message convention, and update workflow.

Implement or extend a repository in dallib/gblib for an entity persisted as JSON in SQLite. Use when adding a new entity type to the database, adding fields that need to round-trip through JSON, or wiring a new repository into EntityManager. Covers Glaze meta specialization, JsonStore CRUD, composite-key repositories, and gap-finding ID allocation.

Work with strong ID types like player_t and governor_t (defined as ID<"name", int>). Use when declaring identifier-typed variables, comparing IDs, passing IDs across function boundaries, serializing IDs to JSON, or fixing compile errors caused by ID type confusion. Covers when raw int is wrong, comparison rules, and migration patterns.