MindForge is not one game with a settings screen bolted on. It is an engine: everything except the board rectangle — home, game detail, difficulty select, countdown, the play scaffold, pause, results, stats, settings — is written once and shared.

Adding a game means supplying its rules, one board widget and one accent colour. It inherits every screen for free.

What a game contributes

A GameDefinition, holding:

Home cards, BEST pills, difficulty lists and score formatting are then data read off the registry — never a switch (gameId) in a shell file.

What a game may not do

lib/games/** is fenced, and the fence is enforced by a gate script rather than by convention:

• no go_router import and no Navigator — only the shell navigates
• no Scaffold, AppBar or HUD widgets — the shell owns everything outside the board
• no Color(0x...) — colours come from the theme
• no run timer of its own — there is one clock, injected

A board reports outcomes into a snapshot. The shell reads the snapshot and decides what happens next. That separation is the whole design.

The proof that it works

Schulte Grid was built second, deliberately, as the test of the seam: it had to ship without editing lib/features/** at all. It did. A policy test now asserts that property so the seam cannot quietly rot.

That is the bar a third game should clear too.

The process

Work is planned as an epic before it is written — a file describing what it delivers, why, and every task with its tests stated before its implementation. Then test-first implementation, granular commits, all gates green, a screenshot comparison against the references, and a pull request.

A new game starts with an epic file, not with a board widget. See CONTRIBUTING.md in the repository for the full path.