Overview

This specification describes a complete, production-quality tic tac toe game that runs entirely in a web browser. It is small enough to be built in one sitting by a coding agent, but specified strictly enough that the result is not a throwaway toy: the rules engine is a pure, framework-agnostic module with an exhaustively tested API, the computer opponent is a real minimax search with three difficulty levels, and the interface is fully operable by keyboard and screen reader.

What gets built

A single-page static web application:

• A 3x3 board where two humans can play locally, or one human can play against the computer.
• Three AI difficulty levels: Easy (random), Medium (greedy win/block heuristic) and Hard (alpha-beta minimax that never loses).
• A running scoreboard for X wins, O wins and draws, persisted in localStorage across sessions.
• Settings for game mode, difficulty and which mark starts, also persisted.
• Win/draw detection with the winning line highlighted, and an alternating start mark between rounds.
• Light and dark themes driven by system preference, responsive from a 320 px phone to a desktop.
• No backend, no network calls, no third-party runtime dependencies, no accounts, no tracking.

Who it is for

Two audiences at once. For the player it is an instant, offline-capable game that loads in under a second and works with a mouse, a touchscreen or the keyboard alone. For the developer it is a reference implementation: a clean separation between a pure rules engine, a search-based AI and a thin rendering layer, with a test suite that proves the AI is unbeatable rather than merely asserting that it is.

How to use this specification

The articles are ordered implementation steps. Build them in sequence — each one assumes the previous is finished and its acceptance criteria are green.

Order	Article	What it delivers
10	Project setup	Repository layout, tooling, strict TypeScript, scripts
20	Game engine	Pure immutable rules module and its API
30	AI opponent	Random, heuristic and alpha-beta minimax strategies
40	User interface	DOM rendering, input, accessibility, announcements
50	Game flow and persistence	Round lifecycle, settings, scoreboard, storage
60	Visual design and motion	Theming, layout, animation, reduced-motion support
70	Testing and deployment	Unit, exhaustive and a11y tests, build, static hosting

CONSTITUTION.md holds the rules that every article must respect. Read it first and treat any conflict between it and an article as a defect in the article.

Definition of done

The build is finished when every acceptance checkbox in every article is ticked, npm run verify passes with no errors or warnings, and a human cannot beat the Hard opponent in ten consecutive games.