t1k:cleanroom
| Field | Value |
|---|---|
| Module | t1k-cleanroom |
| Version | 2.18.52 |
| Effort | high |
| Tools | — |
Keywords: apk teardown, asset ripper, clean room, cleanroom, clone game, game clone, il2cpp, il2cppdumper, recreate game, reverse engineer game, spec from apk
How to invoke
Section titled “How to invoke”/t1k:cleanroom<game-link|apk|zip> [focus: one mechanic] [engine: unity|cocos, default unity] [platform: webgl|standalone|android|ios, default webgl] [build: true|false, default false — player build is OPT-IN] [stage: wire|test|all, default wire]Cleanroom — Clean-Room Game Recreation
Section titled “Cleanroom — Clean-Room Game Recreation”Invoking this skill IS the user’s request for multi-agent orchestration. Run the
bundled workflow with the Workflow tool; all behavior lives in its node prompts.
- Step 0, resolve the engine adapter (every launch):
bun ~/.claude/skills/t1k-cleanroom/scripts/cleanroom-adapter.cjs resolve --engine <unity|cocos> [--platform <p>] --out "$(mktemp -d)/adapter.json" --json(engine = the engine arg, defaultunity). Pass itsadapterPathandadapterSha256asargs.adapterPath/args.adapterSha256, never the bundle itself. Exit 3 = no adapter for the engine: tell the user which kit to install (the message names it,references/engine-kits.json); 4 = two kits in two scopes; 5 = invalid manifest or bundle; 6 = contract mismatch (update theonekit-core or the engine kit). Details:references/adapter-contract.md. scriptPath:~/.claude/skills/t1k-cleanroom/cleanroom.workflow.js(expand~) — a Workflow script body (top-levelexport/await/return) that theWorkflowtool loads as a module; pass its contents as the script.args:{"target": "<link|apk|zip>", "adapterPath": "<from step 0>", "adapterSha256": "<from step 0>", "focus": "<mechanic, optional>", "engine": "unity|cocos, optional", "platform": "webgl|standalone|android|ios, optional", "build": true|false (optional; default false — see "Editor-first, build is opt-in"), "cwd": "<absolute cwd>", "name": "<project id (Assets/ game folder, asmdef root), optional; default = the SCAFFOLD AGENT chooses a PascalCase id from the store listing / package id / app name it sees, never from the URL>", "owner": "<GitHub owner for the created repo, optional; default =repoCreation.defaultOwner(The1Studio)>", "title": "<repo name for the clone, optional; default = the project id>", "template": "'puzzle' | '<owner>/<repo>', optional; default 'puzzle'>", "assetsFrom": "<absolute path of an EXISTING extraction dir, optional; see Assets>", "ui": "'code' | 'convert', optional; default code", "branch": "<fixed work branch for every clone commit/push, optional; default = the clone's current branch; letters, digits, . _ / - only>"— first argument after/t1k-cleanroomis the target; the rest is the focus unless it names an engine/platform. There is no asset-selection arg: assets are always ALL (see Assets). plus the state args"skip","redo"(see “Per-project progress”) — run the state helper’splanFIRST and pass its WHOLE printed object ({skip, loop, projectName, ...}) asskip, never just its.skiparray (a bare array is rejected with an error), or a rerun re-does finished work.
The result is {report, finalize?}. report.passed == false names the stage, why
and the last verdicts — relay them; never claim success without report.passed == true.
Fatal vs non-fatal stages (scaffold, acquire, a failed spec gate with proceededPastFailedGate) and the lifecycle record: references/skill-body-detail.md § “Result and failure stages”.
cwd is NEVER asked for and never taken from the user: run pwd with Bash first and pass its trimmed, absolute output as "cwd" on every call, including the cleanroom-state.cjs plan call (--cwd). The workflow still validates that it is absolute. Spec writes only <cwd>/{docs,refs,reports}; the explore agent’s FIRST step moves them to the clone root — the repo <cwd>/<title>, beside the engine project subdir (<proj>, e.g. Unity<repo>/), never inside it — pre-Explore; logs,builds,playthrough stay in <cwd> (references/layout-and-reports.md).
Wire first, test later (default: stage: wire)
Section titled “Wire first, test later (default: stage: wire)”stage: wire (default) fans out every wiring lane once and stops at the WIRED checkpoint audit. stage: test refuses unless the wire record says wired, then validates, playtests, gates and fixes it and ends with one improve round (args.improveRounds, default 1; references/improve-round.md). stage: all is the old end-to-end order. Detail: references/done-and-verification.md § 5, references/wire-everything.md § “Wire stage”.
Editor-first, build is opt-in (default: NO player build)
Section titled “Editor-first, build is opt-in (default: NO player build)”The run develops and validates entirely in the engine editor, headless — EditMode + PlayMode tests and a
scripted PlayMode playthrough that drives the real input path — and exports no player build. A player build runs only when the caller passes "build": true (the developer’s explicit
request); then validation (validate, the three stage playtests, the gate) runs on a WebGL player build driven by headless Playwright Chromium, whatever platform is, and platform only picks the FINAL deliverable built in Finalize (webgl: the validated build IS the deliverable; otherwise it is built afterwards, build only). Policy: finish the game in the editor first; build only when the developer asks for it.
A build: true run is an INTERNAL QA build; a release deliverable is refused while any original remains (the hard rule under Assets, references/done-and-verification.md § 6).
Detail (why, never inferred, agents report, build: true changes, state and report.build): references/editor-first.md.
Verdict and report files
Section titled “Verdict and report files”Numbered doccheck-/validate-/playtest-<stage>-/gate-<n>.md files are the hand-off (paths only): references/layout-and-reports.md.
Assets: ALL, never ask (refs/assets placeholders, internal and non-commercial only)
Section titled “Assets: ALL, never ask (refs/assets placeholders, internal and non-commercial only)”Hard rule: originals never ship (owner order 2026-11-07). The original game’s assets are INTERNAL, non-commercial reference only. A debug or internal QA build is allowed. A RELEASE, store, ad-network, public or signed build is FORBIDDEN while ANY original-derived asset (art, audio, fonts, localisation text, data tables, models, shaders, icons) remains in the clone. When a caller asks for release, store, public or signed output, this skill REFUSES until the release gate exits 0, and names the remaining rows (scripts/cleanroom-release-check.cjs --release). The procedure: references/done-and-verification.md § 6.
The code and identifiers are clean-room (from the spec); the assets are not: the original game’s assets are the clone’s MOCK/PLACEHOLDER
assets, TRACKED in the clone’s git and BUILT BY DEFAULT (wire all, commit all, build; reskin replaces them). Internal only, private repo, never git-ignored, never asked: references/placeholder-assets.md.
- ALL assets, never ask. The run always takes EVERY asset the source holds, vendor art included, with no filter (duplicates once, non-art technical files skipped; see
references/placeholder-assets.md). Neither the run nor the session that launches it asks whether to include all assets, how many or which kinds (noAskUserQuestion, no prose question); there is no asset-selection arg, so do not offer one. - Spec extracts. The asset owners COPY (never move) EVERY asset of every kind in
<cwd>/extracted/(andassetsFrom) into<cwd>/refs/assets/<kind>/(kind = sprites|ui|fonts|audio|vfx|animations|models) and list every copied asset, unused ones asunusedrows, in their doc asslot | what it is | original path in extracted/ | placeholder path in refs/assets/… OR MISSING; each owner writesrefs/assets/MISSING-<owner>.md(nonewhen empty) naming what to generate. The docscheck judge verifies on disk that every row resolves and itself runsscripts/cleanroom-assets.cjs census --dir refs/assets --src extracted [--src <assetsFrom>](copying its lines into thecensusfield of its answer); the source’s unique files per kind must all exist inrefs/assets/(ASSET-PARITY status=ok) or the round fails and the asset owners re-run. - Build uses ONLY refs;
assetsFrom. Build reads onlyrefs/assets/and generates code-made stand-ins for MISSING slots;assetsFromis an extra read-only Spec source. Verbatim rules:references/skill-body-detail.md§ “Asset bullets: Build uses ONLY refs, assetsFrom”. - Empty source stops. After the Spec copy,
refs/assets/with no texture and no audio (or an unreadable count) STOPS the run:gate:'no-assets', stagespec.allowListingOnlyis the escape. - UI chrome, sprite metadata, layout, LitMotion tweens. Verbatim rules:
references/skill-body-detail.md§ “Asset bullets: UI chrome, sprite metadata, layout, tweens”. - Rigs, release gate and fail-closed purchases. Spec writes
<clone>/docs/rigs.md;scripts/cleanroom-release-check.cjs --project <dir>gates validate andgameplay; a monotonic persisted clock, versioned save with.bak. Detail:references/rebuild-guards.md. - Logic recovery. Acquire exports Unity data with AssetRipper; the spec owners recover the real rules from that data, from prefab wiring and from code, so
mechanics.mdrows are EXACT/OBSERVED/INFERRED/SPEC-SILENT and only a SPEC-SILENT question reaches the user (AskUserQuestion). The five rules (data first, prefab-first, code, provenance, decision order). Detail:references/logic-recovery.md. - Wire everything, never ask. All original assets, data, config, localization, settings as slots with stable ids into OUR code (never the original’s) and COMMITS them.
uiselects the UI mode; gap audit, modes:references/wire-everything.md; done gate:references/done-and-verification.md. A build generates NO art and NO audio;release-gate.shblocks a public build while any TEMP placeholder remains. - Full original data. Every table in the artifact is imported WHOLE by
scripts/cleanroom-data-import.cjs(deterministic, fail-closed,--check) and checked byscripts/cleanroom-data-validate.cjs; Build reads only the imported blueprints, never an invented curve, and each table is aTEMP-ORIGINALregister row the release gate blocks on. Detail:references/data-import.md. - Original first. Data, config and balancing follow the original; rebalance after parity only. Rule:
references/original-first.md. - Retired. The
placeholdersstage,Assets/_Placeholderoverlay and thefidelity/placeholder*args are gone: passing one throws (so doesoriginals:'overlay').
What the rebuild runs on (studio defaults)
Section titled “What the rebuild runs on (studio defaults)”The clone is a NEW PRIVATE repo created FROM the studio template The1Studio/PuzzleTemplate under repoCreation.defaultOwner (The1Studio); a failed create stops at scaffold. Project-id choice, RPG library, packages, Unity runs, bootstrap: references/skill-body-detail.md § “What the rebuild runs on (studio defaults)” and references/skill-detail.md § “What the rebuild runs on”.
- Commits (waves). Nine commit waves, in order (
scaffold,import,explore,implement_models,implement_gameplay,implement_presentation,validate_playtest,gate,finalize), each a prepared script in the doing agent’s brief: commit ascleanroom(<wave>): <summary>,git push origin <pinned>, post a Discordwaveevent. The generated clone repo (and ONLY it, never this kit repo) is committed and pushed DIRECTLY to the ONE branch the run is pinned to —args.branch, else the clone’s current branch, never a re-detected repo default (HEAD-CHANGED/HEAD-UNKNOWNabort); there is no topic branch (report.cloneBranchis that name). Push, post and even a failed local commit are notes (report.notes,report.pushFailures), never a failure or stall. Each implement agent edits ONLY its ownAssets/<game>/{Models|Gameplay|Presentation}folder (violations noted, never reverted). Detail:references/routing.md§ “Commit waves”.
Parity with the personal templates
Section titled “Parity with the personal templates”The flow tracks the personal Claude workflow ~/.claude/skills/cleanroom/; every deliberate difference (template repo, routing, per-wave commits, playtest re-spawn safety net, strict judge) is listed in references/routing.md § “Parity with the personal templates”. Anything else is a defect to align.
Per-project progress (skip finished stages on a rerun)
Section titled “Per-project progress (skip finished stages on a rerun)”A finished stage must NOT run again: the run keeps <cwd>/.cleanroom/state.json (never inside the clone, never committed). A stage is skipped only when its input hash is unchanged AND its output files still exist. Stages: acquire, spec, scaffold, explore, build, finalize.
S=~/.claude/skills/t1k-cleanroom/scripts/cleanroom-state.cjsbun $S plan --cwd <cwd> --target '<target>' # prints an OBJECT; pass that whole object as args.skip (not its `.skip` array)bun $S adopt --cwd <cwd> --target '<target>' # ONCE for a project already built by handbun $S reset build --cwd <cwd> --target '<target>' # invalidate a stage and its dependentsAdd --build to every stage command when the run has "build": true. Pass the SAME --cwd/--target/--name/--title/--platform/--template as the Workflow. "redo": ["build"] forces a fresh start. Records are written by the owning agents; a corrupt state file FAILS LOUDLY (exit 3). Everything else (the skip rule, record, fingerprint, spec-only recording, exit codes): references/skill-detail.md § “Per-project progress”.
Acquire gate — no artifact, no run
Section titled “Acquire gate — no artifact, no run”Acquire tries ANY source it can find (store, user file/URL, apkeep/gplaycli, APKPure direct, mirrors, web search), each candidate
checked (package id EXACT, valid zip, never run): references/artifact-store.md § Sources.
No obtainable APK/XAPK/zip stops the run before Spec with {report:{passed:false, stage:'acquire', gate:'no-artifact', warning, options}}
naming the package id, every source tried and the ways forward. "allowListingOnly": true (default OFF) restores listing-only, loudly.
A store reuse hit counts as an artifact. A valid "assetsFrom" satisfies the asset-source half of the gate (code stays listing-only, logged). Detail: references/artifact-store.md.
Reuse a stored extraction (no new APK version)
Section titled “Reuse a stored extraction (no new APK version)”A later run, even from another project dir, reuses a finished extraction when the artifact is unchanged: the Acquire prompt runs
scripts/cleanroom-store.cjs find then reuse (exact sha256 or packageId+versionCode; a package-id-only match is a flagged
suggestion, never auto-reused; reuse re-verifies the tree digest and refuses on drift). Store: ${T1K_CLEANROOM_STORE:-$HOME/.cache/t1k-cleanroom}.
CLI, ranking and limits: references/artifact-store.md.
Tool preflight
Section titled “Tool preflight”The Acquire phase installs and verifies its tools before any extraction, via this skill’s installer:
bun ~/.claude/skills/t1k-cleanroom/scripts/install-tools.cjs --list # inventory + statebun ~/.claude/skills/t1k-cleanroom/scripts/install-tools.cjs --check # non-zero, naming missing REQUIRED toolsbun ~/.claude/skills/t1k-cleanroom/scripts/install-tools.cjs --install <target>The tool SSOT (install.json: pinned AssetRipper, Il2CppDumper, ilspycmd), the checksum rule and
the required-tool stop (stage: 'acquire'): references/tool-preflight.md.
Executed by
Section titled “Executed by”scripts/install-tools.cjs is mechanical; everything else runs as agents inside the Workflow run, and this body only passes scriptPath and relays the report. Full text: references/skill-body-detail.md § “Executed by”.
Spec-only mode (stopAfter: 'spec')
Section titled “Spec-only mode (stopAfter: 'spec')”Acquire and Spec only, no repository: references/skill-detail.md § “Spec-only mode”.
Model map (who runs each node; the ONE table is DEFAULT_MODELS in the script)
Section titled “Model map (who runs each node; the ONE table is DEFAULT_MODELS in the script)”Every node is a native agent() with an explicit model except acquire (routed, ACQUIRE_MODEL); the ONE table is DEFAULT_MODELS in the script, args.models / args.agents override it, and there are no shell hops. Table, overrides and self-check rules: references/skill-body-detail.md § “Model map”.
Before you launch
Section titled “Before you launch”- The triggering user message must BE the cleanroom ask (or a goal check-in for it). If the current message is about something else, answer it first and launch from the next turn that authorizes the run.
- Run the state helper’s
planfirst and pass it asskip(see “Per-project progress”). - Discord status posts (progress file, live
Monitoronwatch, visuals):references/discord-status.md;"progress": falsedisables. - Deterministic screenshot set (
docs/screens.json,cleanroom-capture.cjs plan|register):references/screen-capture.md.
Hard rules
Section titled “Hard rules”- The Workflow relays the triggering user request, and it wins. Launched from an unrelated turn, every agent answers that
message and builds nothing (detail:
references/routing.md§ “Relayed request wins”). Never launch or relaunch inside an unrelated turn; read the first agent result in the journal within minutes and, if it answers the relayed request instead of the brief, kill the run and relaunch from a turn that authorizes it. - Empty
apkeeplist ≠ absent: tryscripts/pureapk-fetch.cjs. - Do not build the player on your own initiative. The default run never exports one (see “Editor-first, build is
opt-in”): a shared machine OOM-killed player builds repeatedly, and a build inside the k≤3 fix loop burns a whole
iteration on bugs the editor playtest finds in minutes. Report
build deferred (developer has not requested)instead; only"build": truestarts an export. - Export names are not portable.
Armature|BirdIdle.animbroke a Windows clone: copies usecleanroom-path-portability.cjs --sanitize, waves unstage offenders, release-check fails (references/placeholder-assets.md).
Parallel schedule, feature-build layout: references/schedule.md.
Fan-out lane lessons
Section titled “Fan-out lane lessons”Before you launch or verify a multi-lane wave, read references/lane-lessons.md: commit before a
long Unity wait, Unity runs (not agents) are the bottleneck, verify in two phases, filtered tests
prove nothing, no named donor worktree, check before removing index.lock, a fresh verifier per wave, and a UI or layout lane names its UI skills and measures the frame (lesson 8).
The suite is tests/*.test.cjs (node:test API). Bare bun test does not discover these files.
The local gates job in quality-gates.yml runs 10 of the 18 files. Where each file runs, the golden re-baseline, and what the suites cover: references/tests.md.
- Nesting. The
Workflowtool allows one level, so cleanroom can no longer be started as another workflow’s child; start it from the main session.