HTML Puzzle Game
Build a single-file HTML logic or puzzle game such as a match-3, sliding tile, Sokoban, 2048, minesweeper, or sudoku. Locks the rule system, the solve/fail condition, and the win detection first, then a clean grid visual language, then implements deterministic board state with valid-move enforcement. Puzzle games live or die on correct rules and reliable win detection, so the design phase pins the exact legal-move and victory logic before any rendering — the ordering that prevents a small model from shipping a grid that looks right but never registers a win.
Steps
Entry step: game-design. Each step names the specialist role it wants; the full working prompt is expandable.
- Game designgame-designerentry
rules, legal moves, win/fail detection
Show working prompt
Specify the PUZZLE precisely. (1) State the board: dimensions and what each cell can hold. (2) Enumerate the legal moves and the exact rule that makes a move valid or invalid. (3) Define the win condition as a checkable predicate over board state (e.g. 'a tile reaches 2048', 'every mine is flagged and every safe cell revealed') and the fail/stuck condition if any. (4) Describe the initial state and how a new puzzle is generated or shuffled so it is solvable. (5) Write an acceptance-criteria checklist of 5-8 binary items, e.g. 'illegal moves are rejected with no state change', 'a win triggers a visible win message', 'the board reshuffles on new-game', 'score/move-count updates each move', 'no console errors during a full solve'. Write it to notes/game-design.md and via write_task_note. No code yet.
- Visual designvisual-designer
grid look, tile states, feedback
Show working prompt
Design the grid look from the locked rules. (1) Choose a palette (hex) and how each cell value or state maps to a color/glyph. (2) Specify the grid layout, cell sizing, gaps, and how the board stays square and centered. (3) Define visual feedback: selected cell, invalid-move shake, merge/clear animation, and the win banner. (4) Lay out the HUD (score, moves, timer, new-game button) and the typography. (5) Keep it self-contained with CSS grid or canvas — no external assets. Write the visual spec to notes/visual-design.md and via write_task_note. No game logic yet.
- Builddeveloper
implement board state + move rules in index.html
Show working prompt
Implement the puzzle in a single index.html (inline CSS + JS) matching the visual spec and satisfying every criterion. (1) Model the board as a 2D array or flat array; render it to a CSS grid or canvas. (2) Implement the legal-move function so illegal inputs change nothing. (3) Implement the win predicate and check it after every move; show the win banner when true. (4) Wire input (clicks, drags, or arrow keys as designed) and a new-game button that reshuffles to a solvable state. (5) Update the HUD each move. Vanilla JS only, no CDN. On a loop-back, fix only the named gaps without regressing passing criteria. write_task_note the path and passing criteria.
- Evaluatereviewer
Grade the deliverable against every acceptance criterion. All pass → finish; any fail → loop back and fix the gap.
Show working prompt
Play the puzzle. Open index.html if a browser is available, otherwise trace the move and win logic in source. Check EACH criterion from notes/game-design.md and write PASS/FAIL with a reason: are illegal moves truly rejected, does a real solve trigger the win message, does new-game reshuffle solvably, does the HUD update, are there zero console errors? Most important: drive the board to a winning state and confirm the win actually fires — if it never does, FAIL and loop back. Then route — this is the whole point of the loop: - **Every criterion PASSES →** call `advance_task_step({ ref, stepId: "evaluate", next: "finish" })`. - **Any criterion FAILS →** write the specific gaps to notes, then call `advance_task_step({ ref, stepId: "evaluate", next: "build" })` to loop back. The builder fixes exactly those gaps. Never route to `finish` while any criterion is unmet. The build phase's completion gate already blocked a grossly-incomplete deliverable; your job is the judgment an automated check cannot make (does it actually work, read well, look right). After ~3 unproductive loops, stop and report DONE_WITH_CONCERNS so the user can step in. - Finishdeveloper
All acceptance criteria met. Stamp a short summary and report DONE.
Show working prompt
Every acceptance criterion passed. Write a one-paragraph DONE summary to task notes via `write_task_note`: what was built, the deliverable path(s), and a one-line confirmation that each criterion is met. Then report DONE.
Triggers
Phrases that suggest this craftbook to a crew.
- puzzle game
- logic game
- make a 2048
- sliding puzzle
- match three game
- sudoku
Source
View this craftbook on GitHub · MIT license