Kickoff & agent files

Paste the block below into a fresh Claude Code session opened in zoen/ to start (or resume) game development. It is written for the agent. You (the owner) only answer the questions it raises at gates.

You are building Zoen, an action MMORPG for Windows, Android, iOS and the browser, in this monorepo.
The client is Unity 6 LTS + URP (C#, ADR-024); servers are Rust. Use the unity-batchmode and unity-toolchain-gate skills
(.claude/skills/) and docs/tech/UNITY_TOOLKIT.md for anything Unity.

Read in this order before your first action:
1. CLAUDE.md (working rules — re-read after every compaction)
2. CONTINUE_HERE.md (current status and the next smallest action)
3. docs/process/GAME_DEV_GUIDE.md and packages/game-data/data/development-standards.json (movement-first direction and preparation gates)
4. docs/INDEX.md, then only the docs and data files that the current task touches
5. The current roadmap task: `node tools/ctx.mjs task <ID>` (never open the large data files whole; use `node tools/ctx.mjs`)

Process (mandatory, see docs/process/AI_WORKFLOW.md):
- One task per fresh session (ADR-029): do the task, update CONTINUE_HERE.md, then stop. The next task starts in a new session.
- Every finish opens the next session (ADR-031): end by opening the next smallest action as a new desktop-app session
  (task chip) with a self-contained prompt (task id, files to load, the test that proves it). The owner clicks once.
- Hooks enforce the token rules: the read guard refuses whole reads of the large data files (use the slice it names),
  and the context meter warns at 150k (finish soon, hand off) and at 250k (finish now).
- Work in small tasks (S ≈ 30–60 min). For each task:
  node tools/task-log.mjs start <ID> "<title>" --phase <milestone>
  … implement …
  node tools/task-log.mjs test <ID> "<what>" -- <test command>   (at least one, must pass)
  node tools/task-log.mjs note <ID> "<evidence path / decision>"
  node tools/task-log.mjs finish <ID>
- Never mark a task done with a failing or missing test. Save evidence (screenshot, 5–10 s video, metrics JSON) under logs/evidence/<ID>/.
- Game rules come from packages/game-data (JSON). Do not invent numbers; if a number is missing, add it to the data with "proposed": true and log a note.
- Visual or feel changes end with a short clip and a review request to the owner.
- Before skill expansion: versioned mannequin, movement cancellation in all attack phases, C1–C18 control tests, multi-angle animation self-review and the one-skill gate. These are required engine tests, not proven by wiki previews.
- No purchases, accounts, deployments or paid API calls without explicit owner approval (PHP 5,000 cap on all new expenses).

Start with the next smallest action in CONTINUE_HERE.md. A roadmap task may start when everything in its `needs` is installed, even before Unity is. After the task, update CONTINUE_HERE.md with the next smallest action and open it as a new session (task chip).

◆Owner checklist before kickoff

1. Setup (Setup page): Rust and the .NET SDK are installed (2026-10-06). Still open: Unity Hub + Unity 6.3 LTS with the Android, iOS, Web and Windows (Mono) modules. An agent may install it by command line; you sign in with your Unity ID.
2. Decide the open items in Decisions, or accept the defaults.
3. Generate the P0 art in art-requests/MISSING_ART.md whenever convenient. The game starts on placeholders.
4. Watch the Ledger page in the wiki (pnpm wiki:dev → http://localhost:4310/ledger) for tokens per task.

◆Resume prompt (after a break or compaction)

Resume Zoen in a fresh session. Re-read CLAUDE.md and CONTINUE_HERE.md, check `git log --oneline -5`, then do the next smallest action there (one task, then stop). Keep logging every task.

◆Milestone wrap-up prompt

Wrap up milestone <M#>: run the full test suite, capture the gate evidence listed in roadmap.json, write logs/milestones/<M#>.md (what works, what does not, numbers: tests, tokens, frame times, bandwidth), update CONTINUE_HERE.md, and ask the owner for the gate review.

Status (2026-10-11): pre-production is complete. M0-04 is done (…M0-04D): apps/client-unity (URP, four tiers from feel-quality.json) passes its smokes on Web, macOS and the Android APK. M0-03 is done: the Cargo workspace, crates/zoen-sim (integer, allocation-free step) and golden vectors in packages/sim-golden (pnpm sim:test). M0-09 is done: the engine-free C# core packages/core-cs (xunit, pnpm core:test; Unity loads it as the package com.zoen.core). M0-02 is done: pnpm blender:smoke. M0-12 is done: day/night and weather (ADR-030) with the dev GM sky panel on Web, macOS and Android. The other milestones are not started. M0-05 is done: the capability probe is measured on all four owner targets. M0-11 is done: crates/zoen-sim-ffi (C ABI) passes the golden vectors on macOS, Android and Web; iOS built (paused), Windows DLL to be built on the owner's PC; result in ADR-029. M0-06 is done: ADR-003 (servers + protocol), 004, 005 and the M0 write-up of 024 are complete in Decisions; owner approval pending. M1-03 A–D: services/zone tick, AOI, delta snapshots, pnpm zone:run, pnpm zone:loadcheck (200 clients p99 5.5 ms). M1-04 A–C: pnpm zone:bots (--steps), snapshot pool on 4 threads; 10-min 1,000-bot soak: 0 disconnects, 2.4 KB/s, memory flat, loop p99 missed at load 200–380 (M1-04D re-run). History: changelog.

One task per fresh session (ADR-029). Read CLAUDE.md and this file, then only what the task needs (node tools/ctx.mjs skill|monster|zone|polish|task <id>). At the end of a task update this file and keep it short: status and next actions only.

◆State

• Decisions of 2026-10-06: ADR-028 (AAA detail catalog = polish standard), ADR-029 (token rules, order of work, one-simulation spike), ADR-030 (day/night and weather, time-weather.json). Numbers are starting values.
• Decisions of 2026-10-07 (ADR-031, review): catalog round 2 accepted (217 details, 44 core, a fourth stage alpha); hits online: both impact modes are built and judged at 80 ms at G2; voices are non-verbal from the local generator; the enforcement pack is approved; video-to-motion later. The agents make the action AAA; the owner gives feedback later.
• Toolchain: Rust 1.99.0 and .NET SDK 10.0.401 are installed (SETUP-20261006-01). Check with bash tools/setup/toolchain-smoke.sh rust|dotnet. Blender 4.5.9 LTS and ffmpeg are present. Unity 6000.3.25f1 with Android, iOS, Web and Windows Mono modules is in ~/Unity/Hub/Editor (Unity Hub 3.22.2, SETUP-20261007-01). Unity Personal licence active (2026-10-08): batchmode -createProject exits 0 (DEC-20261008-01). Xcode 26.6 is installed (seen 2026-10-11); Homebrew is absent.
• Art: 393 of 508 requests delivered; B10–B26 generated and synced 170 assets. Source of truth: art-requests/queue.json. Two requests are logged ok:false (ART-WEB-boss-regent-splash, ART-ATL-notable-crossbow). Next queue head: ART-NPC-lockkeeper_suren.
• Audio: 318 of 320 delivered; the two boss themes are briefs only. Night variants of the beds and weather layers (ADR-030) have no requests yet.
• Unity client (M0-04 to M0-04D, M0-09, M0-12, M0-11): EditMode 81/81, PlayMode 6/6. Tier defaults and caps come from feel-quality.json → tierSelection (proposed); measured per device in logs/evidence/M0-04C/tier-defaults.txt. Smokes pass with 0 app/console errors. Tests and builds: node tools/unity-run.mjs (docs/tech/UNITY_TOOLKIT.md).
• 3D direction (ADR-033): Blender and the versioned mannequin first; Tripo models by hand from the model request log (MODEL-01); no Tripo API or auto-rig; undersuit bodies, armour as separate meshes.
• Test platforms (ADR-032, 2026-10-11): Web (Chrome on the Mac and the phone), the Android APK (nubia) and Windows (Mono player built here, tested by the owner on his PC). macOS and iOS are paused. Low references stay unverified until units exist.
• Evidence: every logs/evidence/<ID>/ now shows on the wiki /ledger (gallery: /ledger/<ID>/).
• Known failures: the site's largest paint on phones is 2–3.5 s locally (budget 2.5 s).

◆Owner — waiting on you

1. Windows PC: install Rust + Visual Studio Build Tools to build the sim DLL (WIN-01 gives the steps). 1b. 3D models: open the wiki page Model requests (/model-requests/; 100 requests, the Dune Beetle first). Make each in Tripo from its views and prompt (auto-rig off) and save it as art/3d/inbox/<id>.glb (git-ignored; see its README); agents check it with node tools/model-inbox.mjs. Steps: Tripo pipeline.
2. Gamepad (optional): connect one when available so M2-10 can verify gamepad controls.
3. Reviews pending: the Wukong demo (python3 -m http.server 4320 --directory art/3d/wukong/demo, then http://127.0.0.1:4320/), the public site rework of 2026-10-07 (scroll rail on the right, seal buttons, header logo, skill showcase, path emblems, flush window headers; pnpm site:dev, http://127.0.0.1:4340; history in the changelog) and the music takes (Audio generation page: pick one take per theme), and the sky sheets logs/evidence/M0-12H/sky-review-high.jpg.
4. Decisions: OPEN-8 (team events), OPEN-7 (Zoe prices), OPEN-10 (code signing). Approve ADR-003/004/005/024 (M0 gate, logs/reviews.jsonl). Site hover cards (SITE-POPUP-20261007-03): may the cards show prices, monster life, material names and the orb drop-chance source the wiki shows? They are withheld until you say yes. The wiki/site comparison for all 8 card kinds is logs/evidence/SITE-POPUP-20261007-03/contact-sheet.png (completed in SITE-POPUP-20261007-04).
5. Web platform: pnpm admin:bootstrap-owner, the AI keys, site direction A, legal review and hosting. Details are in the changelog under "Web platform".

◆Next smallest actions (one fresh session each)

1. GM-arena run (hand-off 2026-10-11): branch dev/gm-arena (local; never push or merge). Done: MODEL-01…01E, GM-00, M0-02…M0-07, M0-09, M0-10, M0-12…12I, M0-11…11D, M1-03 A–D, M1-04 A–C, WIKI-EVIDENCE-01. Owner approved (2026-10-10) all four Rust targets and vetted crates. Next: WIN-01 (Windows test build + owner smoke kit), M1-06, M1-01, M1-02, M1-05; M1-04D (soak re-run on a quiet Mac). Brief: .claude/briefs/task-worker.md; evidence shows on /ledger.
2. Server lane: M2-02 (cast phases and the ADR-027 cancels on crates/zoen-sim; Reed Rush first needs its authored mana cost and travel time) and M1-04D (soak re-run when the load average is near 8).
3. Art: continue in queue order from ART-NPC-lockkeeper_suren in art-requests/queue.json.
4. Audio: write the night-variant and weather-layer requests in gen-audio-requests.mjs (ADR-030), and non-verbal effort sets per lineage and gender (ADR-031, SFX-27).

◆Commands

pnpm data:test · pnpm sim:test · pnpm core:test · pnpm docs:lint · pnpm wiki:build && pnpm wiki:test · node tools/ctx.mjs … · bash tools/setup/toolchain-smoke.sh rust|dotnet · node tools/unity/serve-web.mjs (Web build on :4350) · node tools/unity/web-smoke.mjs|macos-smoke.mjs|android-smoke.mjs · pnpm art:sync · pnpm ui:sprites · node tools/task-log.mjs report · node tools/token-ledger.mjs · node tools/codex-ledger.mjs

All checks for a docs, data or wiki task in one command: node tools/verify.mjs <ID> [--e2e tests/<spec>.ts | --changed]. This Mac is often heavily loaded: run typechecks, builds and renders in the background.

Zoen is an action MMORPG for Windows, Android, iOS and the browser (Unity 6 LTS client, Rust servers — ADR-024). This monorepo holds the wiki (source of truth), the canonical game data, and later the client and servers. Re-read this file after every context compaction.

◆Read first

1. CONTINUE_HERE.md – status and next smallest action.
2. docs/process/GAME_DEV_GUIDE.md – mandatory direction before character, controls, battle or world work (ADR-027). Read the sections your task card names (node tools/ctx.mjs task <ID> prints the guide command; ctx.mjs guide lists every section); read the whole guide only for direction work.
3. docs/INDEX.md – map of every doc and data file. Load only what the task needs.
4. packages/game-data/data/*.json – canonical rules and content. Docs explain; data decides. Preparation defaults are in development-standards.json; Low references are in reference-devices.json. Proposed tuning and selected hardware are not measured runtime support.

◆Task loop (always)

• node tools/task-log.mjs start <ID> "<title>" --phase <phase> before touching files.
• Small steps: one behaviour at a time, ≤ ~60 min per task. Split bigger work.
• node tools/task-log.mjs test <ID> "<name>" -- <cmd> runs and logs the test. At least one test must pass to finish.
• node tools/task-log.mjs note <ID> "<evidence or decision>", then finish <ID>.
• Evidence goes in logs/evidence/<ID>/ (screenshots, 5–10 s clips, metrics JSON).
• Update CONTINUE_HERE.md at the end of each task: status and next actions only. History goes to docs/roadmap/CHANGELOG.md.

◆Token discipline (ADR-029)

• One task = one fresh session. Finish, update CONTINUE_HERE.md, then start the next task in a new session. finish warns when the average context passes 150k tokens.
• Load slices, not files: node tools/ctx.mjs skill|monster|zone|polish|task <id>. Never read skills.json, audio-requests.json, art-requests*.json or logs/tasks.json whole.
• Batch checks into one command and read logs/test-output/ only on failure. Queues and loops run as scripts, not turns.
• Numbers before pictures: validators first, then one contact sheet, then only the flagged frames. Wide searches go to a sub-agent.

◆Commands

• Data tests: pnpm data:test (dots and failures; full report in logs/test-output/data-test-latest.log) · Regenerate data: pnpm data:build
• Wiki: pnpm wiki:dev (http://localhost:4310) · build pnpm wiki:build · e2e pnpm --filter @zoen/wiki test
• Art: python3 tools/optimize-art.py · Blender: ~/Applications/Blender.app/Contents/MacOS/Blender -b -P <script>
• Tokens: node tools/token-ledger.mjs · Tasks report: node tools/task-log.mjs report
• Context packs: node tools/ctx.mjs skill|monster|zone|polish|task <id>, guide [<section>], doc <path>#<anchor> · Toolchain check: bash tools/setup/toolchain-smoke.sh rust|dotnet
• All checks in one command: node tools/verify.mjs <ID> [--e2e tests/<spec>.ts | --changed] (data tests, docs lint, wiki typecheck and build, logged per step; --changed runs only the e2e specs this task changed, the full suite is for milestone gates)

◆Hard rules

• The server owns outcomes. Animation/VFX never apply damage. No global time-scale hitstop.
• Never cull boss/monster telegraphs on any quality tier.
• Time of day and weather are look and sound only (ADR-030). Check visuals across the review matrix in time-weather.json, not in one lighting state.
• polish-standards.json is the polish standard (ADR-028). Build the stage that is due (core for the first skill), not later stages.
• A valid movement gem cancels own attacks in windup, active and recovery, including finishers; animation/hitstop never delays it (ADR-027).
• Movement gems consume mana; jump/dash reuse targets are proposed, not startup delays. Respect CC/root/destination eligibility and never infer every gem shares a cooldown. R3 toggles views only (ADR-027).
• Use the versioned mannequin before skill clips. Run control self-tests, inspect animation from every required angle, and record VFX/environment evidence before owner review.
• Don't invent numbers. Add missing values to data with "proposed": true and a note.
• Don't edit generated files by hand (atlas.json, progression.json, art-requests.json, art-requests/*.md, model-requests.json). Change the generator.
• Never modify anything outside zoen/ (archived folders) or art/originals/** (accepted art). Never cite archived folders as a source.
• No purchases, account creation, deployments, paid APIs or publishing without explicit owner approval. All new expenses share the PHP 5,000 cap.
• Don't claim a test passed unless the task log shows it. Report failures plainly.

◆Style

TypeScript strict, small modules, data-oriented hot paths (no per-frame allocations), comments only where intent isn't obvious. Rust: no unwrap() in server paths; fixed-tick systems are pure functions of state + inputs.

Follow CLAUDE.md. The rules are the same for every agent. Image-generation work comes from art-requests/MISSING_ART.md: one request per image, deliver to art/source/<category>/<file>, then run python3 tools/optimize-art.py and pnpm data:test.

◆Local SFX generation

When the user asks to generate/create/render SFX or game audio, execute the local generator unless they explicitly ask for prompt text only:

./tools/sfxgen --prompt "heavy sword impact on stone, isolated game sound effect" --seconds 1.2 --out audio/source/weapons/sword-impact.wav

Engine: Stable Audio 3 Small SFX, MLX/Metal, sm-sfx, same-s; installed at ~/AI/stable-audio-3/optimized/mlx. Use catalog paths, durations, takes and loop flags when supplied. Preserve prompts, including intentional creature vocals. Verify the output exists and decodes as valid audio, then report its exact path. Never replace an existing final asset unless replacement was requested (--overwrite), or use an online/API generator unless explicitly requested. See local SFX operations. Record production asset source/license/date in docs/LICENSES.md and run pnpm data:build after delivery.

Browser + mobile action MMORPG on the caravan roads of the Amber Basin. Up to 1,000 players per channel, 18 weapon builds, AAA-feel combat. This monorepo is the single source of truth: the wiki, the canonical game data, the AI process logs, and later the game client and servers.

zoen/
├─ KICKOFF.md            prompt to start/resume game development with an AI agent
├─ CLAUDE.md / AGENTS.md working rules for agents
├─ CONTINUE_HERE.md      current status + next smallest action
├─ docs/                 guides (vision, process, tech, design, production, roadmap) — Markdown
├─ packages/game-data/   canonical JSON (skills, builds, atlas, world, quests, hud, …) + generators + tests
├─ apps/wiki/            Next.js wiki that renders docs + data + interactive tools (Atlas, map, HUD, ledger)
├─ art-requests/         Codex-ready image briefs for every missing art piece
├─ art/source/           where newly generated art is dropped
├─ tools/                token ledger, task/test log, art optimizer, Blender scripts
└─ logs/                 tasks.jsonl, tasks.json, token-ledger.json, test outputs, evidence
   (later) apps/client-unity/  Unity 6 LTS game client · services/ Rust zone + gateway · crates/zoen-sim

◆Quick start

pnpm install
pnpm data:test                 # 45+ data contract tests
pnpm wiki:dev                  # http://localhost:4310
node tools/token-ledger.mjs    # tokens used so far

Start reading at docs/vision/VISION.md, or open the wiki home page. This repo is standalone: sibling folders outside zoen/ are archived and never cited. Accepted art lives in art/originals/ (read-only).