Cluedefy

The product

Cluedefy is a detective game for iPhone. Players question suspects and examine evidence by typing, not by picking from a menu: "Speak to Mrs Dunmow", "Take a look at the box".

Every reply is written by hand and goes into the player's notebook. To leave a scene, the player writes what doesn't add up. It only counts if the evidence for it is in their notebook.

Each story ends with an accusation: culprit, method and motive.

Role

I'm the only person on Cluedefy. I own the product, the design, and the engineering across three codebases: the Expo app, the Firebase backend, and an admin and authoring tool. I also make the editorial decisions on every mystery.

How I work with AI agents

Most of the code is written by AI coding agents that I direct. Each change starts as a product requirements document, which I split into tickets with explicit dependencies. Agents work through them in waves.

• Specs first. Architecture decisions are recorded as ADRs. Agents check each ticket before starting and stop to ask rather than guess.
• Models matched to tasks. The most capable model plans mysteries and anything that needs judgement. A faster model implements code tickets.
• Fresh context for review. Critics and solvers never see the work that produced what they're judging.
• Automated gates. Tests, type checks, rules tests and schema validation decide whether work lands, not an agent's own report.
• Irreversible steps stay with me. Agents don't deploy, publish or add dependencies without my approval.

Architecture

The app reads and writes Firestore directly for anything a player owns: published stories, their progress and their notebook.

Anything that needs judging goes through a single game API: a probe, a deduction or an accusation. It's the only component that can read answer keys or change game state.

• Server-only answer data. Answer keys, deduction configs, game state, logs and budgets live in collections clients can't read. The security rules deny by default and have their own test suite.
• Shared contracts. JSON Schema defines every story, scene and progress record. A script generates TypeScript types into the app and the admin tool, and a check fails if they drift.
• Validation before import. A story reaches Firestore only after it passes the schema, fair-play checks on the story graph and a prose linter. The graph checks cover dead ends, clue reachability and machine-solvable puzzles.

Runtime AI

Plain code answers first. Each scene has authored leads with trigger phrases, and a deterministic matcher picks the lead a probe refers to. The player always gets the authored response.

The model never writes text the player reads as fact. Hints and puzzle answers never call a model.

Gemini, through Genkit, is used in two places:

1. Classifying probes the matcher can't place. The model chooses one of the scene's authored leads, or none. Its structured output is validated before use.
2. Grading deductions and accusations. Each element (culprit, method, motive) is graded against the authored solution as solved, partial or missing. A correct deduction without its evidence in the notebook gets coaching, not a solve.

A pre-check rejects empty and repeated deductions before any model call, and repeated verdicts are cached.

Every model call counts against a per-player daily budget. Once it's used up, play continues without the AI-graded steps.

Authoring pipeline

Each mystery goes through seven stages:

1. Blueprint. An architect model plans the solution, each scene's contradiction, where every fact is planted, the red herrings and the puzzles. I approve every blueprint before any prose is written.
2. Scene writers. One agent per scene, each in a fresh context with only a need-to-know brief and the house style guide.
3. Integration. The architect checks the drafts against their briefs, edits for voice, and writes the server-only material: answer keys, hints and reveals.
4. Critics. Fresh agents review each scene and the whole story. Every flag is reworked and re-reviewed by a new critic.
5. Machine validation. Schema and story-graph checks, puzzle solvers, a prose linter, and a smoke test that sends every character's name to every scene through the real matcher.
6. Blind panel. Two AI solvers, one methodical and one impatient, play through the real game API with only a player's view. Each has a fixed budget of probes and attempts, and a third solver breaks ties.
7. My playthrough. I play every story before it's published.

Security and cost

• Sign-in checked on every request, with per-player rate limits on every route.
• App Check with Apple's App Attest, so the API can reject requests that don't come from the genuine app.
• Input caps on every field that reaches a model, with explicit error responses.
• A per-player daily model budget, checked before each call.
• Entitlements written only by the server, from a RevenueCat webhook that checks a shared secret.
• Tests for the Firestore security rules.

// Entitlements: written by the server, read by their owner.
match /entitlements/{userId} {
  allow read: if isOwner(userId);
  allow write: if false;
}

What broke

The starter mystery, Non-Stop to Sandbourne, passed every stage above. A blind solver solved it without hints. In my own playthrough I found six defects:

• Two hints described testimony I hadn't heard. Scene 1 could be cleared without the witness account that scene 2's deduction depended on.
• Two characters moved between carriages with no explanation.
• Typing "Colonel" on its own got no match, because only "the Colonel" was an alias.
• One scene ended with an instruction to the player instead of a line of story.
• A notice on the carriage wall was mentioned without saying what it said.

I fixed the story the same day, then changed the process:

• Setup checks. Each gate only checked its own scene. Now every fact a scene depends on must be available in that scene and pointed to in the narrative, and the smoke test fails stories that break this.
• More realistic solvers. A strong model asks the right questions; players often don't. The panel gained a budgeted, impatient solver, and every solver must start by typing bare character names.
• Easy means easy. Any friction in scene 1 of an easy story now blocks it from publishing.
• Catalogue sweeps. The rule against hints assuming notebook contents only applied to new stories. Rule changes now include a sweep of every story; the first sweep found the same defect in another live one.

Status

Cluedefy is launch-ready. The game, the backend, App Store purchases and a catalogue of panel-tested mysteries are complete.

I've chosen not to publish it yet, because doing so properly means registering a business.

Next: more mysteries through the pipeline, then visual evidence (images that carry clues, checked by a vision model) and audio evidence.