1. Executive Summary

ASTO is a cozy, mobile-friendly word puzzle game inspired by Connections, but built around analogical reasoning instead of category matching. Players are presented with a board of 16 word tiles and must solve four hidden analogy sets by selecting words in the correct relationship order:

In plain language: “A is to B as C is to D.” Each puzzle contains four analogy sets and four difficulty tiers: Green, Yellow, Red, and Black. The player loses on the 4th mistake. When a player selects the correct four words in the wrong order, ASTO displays “So close!” and counts the submission as a mistake, turning the penalty into a useful hint.

ASTO's product is the game. The AI Puzzle Studio is a behind-the-scenes development pipeline that exists to produce puzzles for it — never something the player sees. The game itself should feel handcrafted to players. AI is used behind the scenes to support puzzle design: generating candidate analogies, validating logic, stress-testing ambiguity, rating difficulty, enforcing style, and exporting human-approved puzzles into game-ready JSON. This is a prototype-stage document: its mechanics, feedback, difficulty economy, and onboarding are working hypotheses meant to be validated and revised through playtesting.

1.1 Success Definition

The deliverable is a playable ASTO game. Everything else exists to support it:

• The product: a playable mobile-vertical browser prototype, shipping with at least 10 curated puzzles (20 as a stretch goal).
• A clean puzzle data schema that can be loaded from local JSON.
• A documented AI Puzzle Studio pipeline with multiple specialist agents — the project's primary technical and learning focus, and designed to scale beyond the prototype's 10–20 puzzles to open-ended content production.
• A final demo showing the path from prompt to agent review to human approval to playable puzzle.

2. Game Vision

ASTO is designed for the satisfying moment when a player suddenly sees the relationship hiding between words. The puzzle is not simply “which words are similar?” It is “what relationship repeats across these pairs?”

2.1 High-Level Pitch

Connections, but with analogies. Players tap four words in the order that forms an analogy. The fourth tap fills the frame; the player reviews it and confirms to submit. The experience should encourage players to quietly speak the analogy under their breath while playing:

2.2 Product Identity

ASTO is a cozy analogy word game. That game is the product. The AI Puzzle Studio is the workshop behind it — a development-time pipeline whose job is to feed the game fair, elegant puzzles, first 10–20 for the prototype and open-ended thereafter. Building that pipeline well is a core goal of the project; it is never something the player sees.

2.3 Long-Term Direction

The long-term vision is a daily puzzle experience with curated boards, optional themed puzzle packs, streaks, and eventually community or editorial features. The prototype should not attempt to build all of that. It should prove the core puzzle loop, the content data model, and the AI-assisted editorial pipeline.

3. Design Pillars

4. Target Audience and Player Fantasy

4.1 Primary Audience

• Players who enjoy Connections, crosswords, word ladders, logic puzzles, trivia, and daily puzzle rituals.
• Players who like the feeling of being briefly stumped, then rewarded by a clean insight.
• Players who appreciate wordplay, double meanings, and elegant puzzle construction.

4.2 Player Fantasy

The player fantasy is not power or speed. It is recognition. ASTO lets the player feel like they are catching a hidden pattern in language. The game should support the feeling of leaning in, testing a theory, whispering the analogy, and locking in a satisfying answer.

4.3 Accessibility and Approachability Goals

• Simple tap/click interaction with no time pressure.
• Readable type and strong mobile layout.
• Clear feedback after every submission.
• No penalty for taking time to think.
• Relationship labels that teach without over-explaining.

5. Core Gameplay Loop

1. Player opens a puzzle.
2. The board displays 16 shuffled word tiles.
3. The player selects four words in order.
4. Selected words fill the analogy frame: ___ : ___ :: ___ : ___.
5. The fourth selection fills the last slot. The player can review the frame, drag tiles to reorder them, or deselect, then presses Confirm to submit.
6. If correct, the solved analogy locks into the solved area (reordering into canonical form if a non-canonical accepted order was confirmed).
7. If the correct four words are selected in the wrong order, the game displays “So close!” and counts a mistake.
8. If incorrect, the selected tiles shake, clear, and count as a mistake.
9. The player wins by solving all four analogy sets.
10. The player loses on the 4th mistake.

5.1 Core Screen Layout

• Header with title, current puzzle title or date, and mistake counter.
• Analogy frame: ___ : ___ :: ___ : ___.
• 16 word tile board, reduced as sets are solved.
• Confirm, Clear, and Shuffle buttons (Confirm is enabled once four words are selected).
• Solved sets area, displayed above or below the active board depending on screen size.

5.2 First-Run Tutorial

Ordered analogies and the :: notation are unfamiliar to most players, so a first-time player is taught before they are tested. On first launch, ASTO forces a guided, no-lose first board: a real but gentle puzzle where mistakes cost nothing. Coach-marks introduce the three ideas that make ASTO different:

• You are hunting a relationship, not a category — what pattern repeats across the pairs, not which words are alike.
• Order matters: the words are submitted as an analogy, not just grouped.
• What :: means — "A is to B as C is to D."

The tutorial has no loss state; a wrong attempt simply nudges the player with a hint. Once the player solves the guided board, ASTO transitions into normal puzzles with the standard rules in effect. The tutorial's worked example must demonstrate a genuine relationship rather than a category — for instance Seed : Tree :: Spark : Fire ("small origin becomes larger result"). It should not use a set that reads as category membership (such as "home of animal" or "tool used by profession"), since that would teach the exact habit the first design pillar warns against.

6. Rules and Mechanics

7. Puzzle Structure and Validation

7.1 Puzzle Board

Each standard ASTO puzzle contains 16 words, divided into four hidden analogy sets. Each set contains two ordered pairs that share a relationship.

7.2 Answer Model

A solution is stored as two ordered pairs: A : B :: C : D — source data [[A, B], [C, D]].

The data model must preserve order because the same four words can become invalid if rearranged incorrectly. For example, if the intended answer is Seed : Tree :: Spark : Fire, the order Seed : Spark :: Tree : Fire should not be accepted.

7.3 Equivalent Accepted Orders

Because analogies can remain valid when both sides are swapped or both relationships are reversed, ASTO accepts logically equivalent orders. For a solution stored as A : B :: C : D, the game should accept:

The game should not accept cross-pair arrangements such as A : C :: B : D unless that order is explicitly defined as a separate valid solution.

All four accepted orders count as correct, but because relationship labels are directional, the solved display normalizes to the canonical stored order (A : B :: C : D). On a correct non-canonical submission the tiles reorder into the canonical form as the set locks, so the analogy shown always matches its relationship label.

7.4 Correct Words, Wrong Order

If the submitted four words match a solution set but the order is not one of the accepted equivalent orders, the game displays “So close!” and counts the submission as a mistake. This gives the player a meaningful hint: the four words belong together, but the relationship structure needs to be rethought.

7.5 Board Construction as the Core Problem

Generating four sound analogy sets in isolation is the easy part. The hard part—and the part where ASTO puzzles will live or die—is assembling all sixteen words onto a single board so that cross-set interactions create intentional false trails without creating accidental valid solutions. This is a constraint-satisfaction problem, not a simple generation problem.

A board succeeds when its tempting wrong groupings are deliberate and its only clean solution is the intended one. The interesting design and AI work therefore lives in the relationships between sets, not within any single set. A word that is unambiguous inside its own analogy can become a trap once fifteen other words surround it—and that is desirable when planned and a defect when accidental. The validation pipeline must treat the whole board as the unit of review, not the individual set.

8. Feedback, Win, and Loss Conditions

8.1 Win Condition

The player wins when all four analogy sets are solved before the 4th mistake.

8.2 Loss Condition

The player loses on the 4th mistake. The end screen should reveal the remaining unsolved answers so the loss still feels educational and fair.

8.3 Playtest Note

The “So close!” feedback currently costs a mistake because it is still a submitted answer. The working hypothesis is that the penalty should stay: a free “you have the right four, just reorder” signal is powerful enough to trivialize many boards, and the cost is what makes the information worth something. Playtesting should test that hypothesis directly by tracking how often players reach the “So close!” state, how often they solve that set on the next attempt, and how often a fourth mistake follows a “So close!”. Based on that evidence, the rule may stay, become a non-consuming warning, or become free only the first time per puzzle.

9. Difficulty Tiers

Each puzzle contains four difficulty tiers. These tiers are revealed when each set is solved. They are not initially visible on the board.

9.1 Measuring Difficulty

Difficulty is a property of each individual analogy set, never the board: every board contains exactly one set at each grade, and boards themselves are not graded. Before board assembly, the Difficulty Rater Agent grades each candidate set from 1 (easiest) to 4 (hardest) — the grade maps one-to-one onto the Green/Yellow/Red/Black tiers — and the Board Builder assembles each board from one set of each grade. The primary difficulty signal should still be empirical rather than declared: after assembly, the goal-oriented test-player agent actually attempts the board with perception, guess confidence, and memory of failed attempts, producing evidence of how hard each set really plays in board context — how many guesses it took, where it went wrong, and which false trails it fell for. The human editor reviews any mismatch between a set’s intended grade and its observed play, and approves or adjusts before the puzzle ships. The 1–4 grade is the fine-grained authoring signal; the tier color remains the player-facing label.

10. Content Philosophy

ASTO puzzles should support a large mix of relationship types. The best boards may include words with double meanings, tempting false categories, and relationships that only become obvious after the correct analogy is found.

10.1 Relationship Types

10.2 Editorial Standards

• Every pair in a set must share the same relationship.
• The relationship label should make the answer feel fair once revealed.
• A puzzle should avoid accidental alternate solutions unless intentionally designed for them.
• Words should be familiar enough that the challenge is the relationship, not obscure vocabulary.
• Hard puzzles can be abstract, but they should not be arbitrary.
• AI-generated content must be reviewed and edited by a human before use.

10.3 Board Themes

The MVP uses one consistent visual theme. Future versions may include custom board themes based on puzzle content, such as ocean, forest, space, garden, library, kitchen, or cozy home aesthetics. Themed boards should support the puzzle mood without making answers too obvious.

11. Visual and UX Direction

11.1 Art Direction

ASTO should feel simple but artistic. The desired emotional space is warm, calm, lightly whimsical, and adult. A useful shorthand is: Animal Crossing for sophisticated adults.

• Soft, readable interface.
• Tile-based board with tactile feedback.
• Warm neutral backgrounds with selective color accents.
• Paper-like tiles, soft shadows, and subtle bounce feedback.
• Clear hierarchy: active analogy frame, tile board, solved sets, mistakes.
• No clutter, timers, flashing ads, casino effects, or generic mobile game polish.

11.2 Prototype Layout

• Mobile vertical canvas as the primary layout.
• Responsive enough to play in a desktop browser.
• Large tiles that support touch input.
• Visible analogy frame while selecting.
• Subtle shake animation for incorrect answers.
• Solved sets arranged cleanly above or below the active board.

11.3 UI Copy Guidelines

• Use short, friendly labels.
• Do not over-explain solved answers unless needed.
• Keep feedback clear: Correct, So close!, Try again, Puzzle solved.
• Avoid snark, punishment, or overly academic language.

12. AI Puzzle Studio

The AI Puzzle Studio is a developer-facing pipeline that helps the human designer create better ASTO puzzles. It is not visible during normal gameplay. The player should experience ASTO as a handcrafted puzzle game, while a pipeline demo can reveal the behind-the-scenes multi-agent workflow.

12.1 Agent Crew

Token figures are planning estimates, to be replaced with measured numbers once each agent has run a few times (see 12.5). Scoped, single-job agents keep most of the crew on smaller, cheaper models — only whole-board reasoning needs the larger tier.

12.2 AI Wow Moment

One agent authors analogy pairs, another clusters them into themes, another grades each set, another assembles the board, another validates it, another tries to break it, another plays it the way a player would, and a human editor makes the final call. Each agent does one job extraordinarily well rather than everything adequately. This supports a responsible, human-guided content pipeline rather than a fully automated puzzle generator. The AI is not the author of record; it is an editorial room that helps the designer produce stronger work.

12.3 Proposed Pipeline

12.4 Puzzle Studio Output Format

Each agent should produce structured, reviewable output. A pipeline demo should show these artifacts, even if the player-facing game only consumes the final JSON.

12.5 Token Budget & Projections

ASTO’s AI is dev-time batch content production, so tokens are a content-production cost — like paying for editorial hours — not an operating cost. Every number below is a planning estimate to be replaced with measured figures once each agent has run a few times; the discipline of budgeting from day one matters more than the precision of the first guesses.

13. Technical Plan

13.1 MVP Technology

The preferred prototype path is HTML, CSS, JavaScript, and local JSON files. This is likely faster and more appropriate than a full engine for a word puzzle. Godot remains an option if engine-based development becomes preferable, but it may be overkill for the core ASTO prototype.

13.2 Data Model

Puzzles should be stored as editable JSON. The game loads puzzle data, shuffles unsolved words, validates submitted orders, tracks mistakes, and displays solved sets. In v0.3, sets are stored as ordered pairs. Accepted equivalent orders are derived at runtime unless a special puzzle explicitly defines extra valid orders. Because the pairs-based model exists to eliminate hand-authoring errors, the Validator and Adversarial Solver agents must test against the runtime-derived accepted orders, not against a separately typed list—otherwise the two code paths can drift and reintroduce the very error the model was designed to remove.

13.3 Engine Architecture

The game is a headless puzzle engine plus a read-only view, wired by one thin GameController. The engine owns the game state and all validation — accepted orders are derived at runtime from each set's pairs — and a submission resolves as a single synchronous reducer: guard, ordered comparison (never sorted), solve / "So close!" / mistake, then win-loss check. Because the engine runs with the view turned off, the Test-Player Agent and unit tests drive its API directly. The engine validates the order the player submitted; the view canonicalizes the display order on solve, animating a non-canonical accepted order into the stored [A, B, C, D] so the solved card matches the directional label. Puzzle data arrives through a PuzzleSource seam: local JSON for the MVP, swappable for a content API later with no engine or view changes. No LLM runs at play time. Full design: asto-architecture.md (companion engine-architecture document).

13.4 Backend Needs

The MVP does not require a backend database. Local JSON files are enough for 10 to 20 curated puzzles, a puzzle select screen, and an AI export/import workflow. A backend becomes relevant later for daily puzzle delivery, user accounts, leaderboards, streak tracking across devices, analytics, or user-submitted puzzles.

13.5 Future Backend Features

14. MVP Feature Scope

15. Development Plan

Development moves from GDD drafting into the agent crew, the dynamic content pipeline, goal-oriented test agents, generation/evaluation/refinement loops, style enforcement, adversarial QA, the complete AI pipeline, and finally a playable game. ASTO suits this progression because the game itself is contained, while the engineering and learning depth lives in the content pipeline that serves it — and the player-facing game remains the product.

15.1 Prototype Goal

• A playable ASTO browser prototype.
• 10 to 20 curated puzzles.
• A working or semi-working AI Puzzle Studio pipeline.
• Structured puzzle JSON export.
• Agent review reports showing generation, validation, ambiguity testing, difficulty rating, and human approval.
• A demonstrable path from prompt to agent crew to puzzle data to playable game.

16. Prototype Acceptance Criteria

The prototype is complete when a player can complete the full ASTO loop without developer intervention and when the AI pipeline can produce reviewable artifacts that connect to the playable data format.

17. Risks, Assumptions, and Open Questions

17.1 Risks

• Puzzle quality risk: analogy puzzles can become arbitrary or unfair if relationships are too loose.
• Ambiguity risk: word boards may accidentally contain alternate valid answers.
• Scope risk: leaderboards, accounts, backend services, and daily delivery could distract from the core prototype.
• AI reliability risk: generated puzzle ideas may sound plausible but fail under closer logic review.
• UX risk: ordered selection may initially confuse players familiar with category grouping games. The first-run tutorial (§5.2) is the primary mitigation.

17.2 Assumptions

• Local JSON puzzle files are sufficient for the initial release.
• The AI pipeline can be demonstrated separately from the player-facing game.
• Human editorial review is an acceptable and intentional part of the content pipeline.

17.3 Open Questions

• Does “So close!” feel fair when it costs a mistake?
• Should the game eventually include a non-penalty hint system?
• How much explanation should solved sets reveal?
• Should the first public version use a daily puzzle format or puzzle packs?
• How should the puzzle editor UI work once the pipeline is more mature?
• Should the game log anonymized playtest data such as guess count, “So close!” frequency, and solve rate?

{{ schemaJson }}

B. Complete Sample Board

This onboarding board is intentionally clean so the rule can be understood quickly. It is not meant to represent the full sophistication of later ASTO puzzles. A production-quality board should include more intentional false trails while still avoiding accidental alternate solutions.

B.1 Shuffled Board Words

B.2 Solutions

B.3 Intentional False Trails to Notice

• Brush, Chisel, Clay, Sculptor, Painter, and Pottery create an art/craft surface category, but the correct sets depend on relationship structure.
• Seed, Tree, Nest, Bird, Den, and Bear create a nature/animal surface category, but those words split across different relationships.
• The board is still too clean for a final puzzle; its purpose is to teach ASTO’s ordered analogy mechanic.

C. Sample Analogy Sets

D. UI Wireframes

Key screens from the wireframe pass, rendered in the ASTO design system and using the Appendix B sample board (“First Light”). Screens 1–3 are the prototype's core UI specification per §5.1 and §11.2. A Screen 0 — First-run tutorial (guided, no-lose) is specified in §5.2; its wireframe is pending.