# 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](../../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](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](../../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](../engineering/architecture.md)).
4. Verify: tests, clippy, both-feature builds, and an actual run (see
   [workflows.md](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](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).