Development style: spec-driven, constitution-first #

This project is an experiment in describing a good video game into existence. The spec comes first; the code is downstream of it.

The constitution rule #

DESIGN.md is the constitution: a single document that communicates the entire purpose of the game — vision, pillars, decided mechanics, and roadmap.

Any change to how the game functions must be accompanied by a change to the constitution, in the same commit. Not as an afterthought — the spec change is the decision; the code change is its implementation. If you cannot express a change as an amendment to the constitution, that is the signal it does not belong in the game.

Corollaries:

• If code and constitution disagree, the constitution wins. Either fix the code or amend the constitution deliberately (with a decisions-log entry) — never let them drift silently.
• Pure refactors, formatting, tooling, and bug fixes toward already-specified behavior need no amendment. Tuning changes that alter game feel do.
• Decisions get dated entries in the constitution's decisions log. Rejected alternatives are worth a sentence — future agents will otherwise re-propose them.

Why this shape #

The intent is to run agents at this repository over many sessions and have them build the game coherently without a human re-explaining it each time. That only works if:

1. The spec is complete enough to implement from. An agent reading only DESIGN.md should know what the game is supposed to be.
2. The knowledge base is honest. knowledge/ says how things work now; stale knowledge poisons every downstream session.
3. History is preserved. devlogs/ (session writeups) and DEVLOG.md (quick ledger) explain why the code looks the way it does, including the dead ends.

The working loop #

1. Read the constitution (DESIGN.md) and relevant knowledge/ files.
2. Amend the constitution with what is about to change (or confirm it already specifies it).
3. Implement in the sim core first, frontends second (see architecture.md).
4. Verify: tests, clippy, both-feature builds, and an actual run (see workflows.md).
5. Update any knowledge/ file the change made stale.
6. Write it down: devlog entry for a session's work, DEVLOG.md line for the ledger.
7. Commit (spec + code + knowledge together) and push.