Development style: spec-driven, constitution-first #

Type: knowledge

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. Type: knowledge wiki pages say how things work now; stale knowledge poisons every downstream session.
3. History is preserved. wiki/log/ (session writeups) and wiki/log/DEVLOG.md (quick ledger) explain why the code looks the way it does, including the dead ends.

The working loop #

0. Take a tick (tick.md): audit the constitution against the code; act on one violation / contradiction / question / bug / insecurity. Contradictions and directional questions become Tangled issues (tang).
1. Read the constitution (DESIGN.md) and relevant Type: knowledge wiki pages.
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 Type: knowledge wiki page 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, with a Defense: paragraph in every behavior-changing commit) and merge to main (see workflows.md — PRs are the norm in principle, but CLI-created PRs don't appear on tangled.org's website yet; push main directly until the Tangled indexing issue is resolved).