FIELD GUIDE / 04

Create a play with an AI agent

Start with a clear idea, let an AI coding agent develop and build it, then install the play on a real AI Passport.

STEP / 01

Start with a problem worth solving

The small display, physical buttons, and wearable form can support learning tools, mini games, timers, identity displays, and more. Pick a real context and describe in one sentence what the user should accomplish after picking up the device.

AI Passport showing several tools and plays — One small display can support many different experiences

Context: when and by whom will it be used?
Goal: what action means the experience succeeded?
Scope: keep only one core experience in the first version.

STEP / 02

Try an official play and confirm the connection

Connect AI Passport with a USB data cable, choose a published release from the official play library, and install it once. This confirms that the cable, browser serial permission, and device connection work before custom development begins.

Installing an official AI Passport play from the website — Confirm the connection and install flow with a published play

Tip
This does not replace development. It gives the custom play workflow a known-good connection baseline.

STEP / 03

Define the smallest version of your play

Reduce the idea to a first version that can be tested on real hardware. Specify what appears on the display, what each of the three buttons does, and whether the experience needs sound, Bluetooth, networking, or local storage.

A programmable AI Passport connected over USB — Keep the first version focused on real hardware capabilities

Interface: list the main screens, text, and states
Input: define short- and long-press behavior for Up, Down, and Confirm
Feedback: describe success, failure, loading, and exit behavior
Constraints: include display size, offline needs, asset limits, and target hardware

STEP / 04

Choose an AI coding agent

Use TRAE, Codex, Claude Code, or another AI coding agent that can read a project, edit code, and run build commands. Open the play project directory and have the agent inspect its instructions, examples, and build workflow before making changes.

Prompt for the Agent

Please download and use this project as a reference:
https://github.com/folotoy/ai-passport
Help me build a wooden-fish tapping app.

TRAE, Codex, and Claude Code AI coding agents — Choose an agent that can develop and build inside the complete project

Tip
Do not work from an isolated code snippet. Giving the agent the complete project lets it reuse the correct dependencies, hardware configuration, and build process.

STEP / 05

Describe the requirements clearly

Give the agent the context, interface, button behavior, and constraints you prepared, then ask it to restate the design and implementation plan. Specific input makes the first build much closer to a usable experience.

Describing an AI Passport play to an AI coding agent — Make the requirements clear before implementation starts

What I am making and who it is for
The first screen and the complete interaction flow
How each button behaves in each state
Existing code, assets, or interfaces that must be reused
Definition of done: a successful build and an installable play file

STEP / 06

Let the agent develop, build, and check its work

Have the agent implement the plan, run the project's build commands, and continue fixing errors. At the end, ask for a summary of changes, test results, the play file path, and any remaining limitations.

An AI coding agent completing an AI Passport project — Keep implementation, building, and error correction in one workflow

Tip
Generated source code is not a finished result. Confirm that the build succeeds and that the project produced an actual play file.

STEP / 07

Install the play and test real hardware

Open the local play installer, select the play built by the agent, and connect AI Passport. Check the file and device before installation. Restart when it finishes, then test the display, buttons, sound, and connectivity one by one.

A custom play running on a real AI Passport — The build must ultimately be verified on real hardware

Do not unplug the cable or close the page during installation
Use a development device first and keep a recoverable official play
Record unexpected screens, button behavior, and logs, then give them back to the agent

STEP / 08

Use it in context, then iterate

Try the play away from the computer. Check whether text is readable, one-handed controls feel natural, feedback is timely, and battery and connectivity fit the context. Prioritize the issues that most affect use, then ask the agent for another focused build.

A child using AI Passport as a learning tool — It can be a learning tool, a mini game, or a wearable experience of your own

Fix problems that block the core flow first
Change only a small set of testable details per iteration
Keep a version number, source commit, and play backup for every usable build