# Galaxy Game — Project Conventions

This repository hosts the Galaxy Game project.

## Sources of truth

- `ARCHITECTURE.md` — global architecture, project-wide rules
  and links to the implemented services.
- `galaxy/<service>/README.md` - service conventions and agreements
  for the implemented or planned to be implemented service.

## Planning of service implementation and Implementing Plan

- `galaxy/<service>/PLAN.md` — staged implementation plan for the service.
  May be already complete and resides for historical reasons.
- `galaxy/<service>/docs/` — per-stage decision records
  (one file per decision, re-organized after full implementation
  of `PLAN.md`).

## Decision records when implementing stages from PLAN.md

- Stage-related discussion and decisions do NOT live in `README.md` or
  `ARCHITECTURE.md`. Those files describe the current state, not the history.
- Each non-trivial decision gets its own `.md` under the module's `docs/`,
  referenced from the relevant `README.md`.
- Any agreement reached during interactive planning that is not obvious from
  the code must be captured — either as a decision record or as an entry in
  the module's README.

## Scope of PLAN.md changes

The existing codebase of `galaxy/<service>` may be modified or extended when a
plan stage requires it. All such changes must be covered by new or updated tests
and reflected in documentation when they affect documented behavior.

## Documentation discipline

- Code and docs are kept in sync. If an implementation changes behavior
  described in a `.md` or `.yaml` file, update that file in the same patch.
- If existing docs are incomplete or wrong for behavior you are already
  touching, fix them in the same patch.
- Do not silently remove commitments from `galaxy/<service>/README.md`
  or `galaxy/<service>/docs/*.md`. When a rule changes, either update it
  in place with the new agreement, or move the section to a more appropriate
  doc with a reference kept.
- Cross-module impact: if a new agreement requires changes in
  already-implemented modules, make those changes — code, tests, docs — in
  the same patch, and record the new rule in `ARCHITECTURE.md`.

## Dependencies

- Before adding a new module, check its upstream repository for the latest
  stable version and use that.
- When a well-maintained library clearly outperforms stdlib for a concrete
  need, do not adopt it silently — propose a short list of 1+ candidates for
  the user to pick. Default remains stdlib.

## Language

- All code, comments, identifiers, commit messages, docs, and filenames are
  written in English.
- User-facing chat responses follow the Russian-translation rule from the
  user-level `CLAUDE.md`.