Skip to content

t1k:cocos:base:apk-unbuild

FieldValue
Modulebase
Version4.51.9
Efforthigh
Tools—

Keywords: apk unbuild, cocos 2.4 apk, cocos-unbuild, decrypted client, editable project, editor open gate, rebuild from apk, shipped apk, slot lock, xxtea

/t1k:cocos:base:apk-unbuild
[<toolkit-root>] [--rebuild | --maintain | --re-verify]

APK Unbuild — orchestrating the cocos-unbuild toolkit

Section titled “APK Unbuild — orchestrating the cocos-unbuild toolkit”

The toolkit is its own private repo, The1Studio/cocos-unbuild. It turns a shipped Cocos Creator 2.4.x APK into an editable project that opens in the editor and builds. This skill is the orchestrator’s half: it never touches APK-derived data and never runs the toolkit for a verdict. It briefs headless omp lanes, then verifies what they report. The toolkit’s own GUIDE.md and README tool index are the per-tool reference; read the toolkit’s VERSION and top CHANGELOG.md entry first, because stage names and flags move between releases.

IntentPath
Ship an editable project from an APK, first timestage order — pipeline-stages (references/pipeline-stages.md)
Change the toolkit or the readable overlay, re-run--maintain — pipeline-stages (references/pipeline-stages.md) § rerun
Prove an existing project still passes the gate--re-verify — acceptance-and-evidence (references/acceptance-and-evidence.md)
Draft a lane briefbrief-template (references/brief-template.md)
A lane stalled, or exited without its reportlane-orchestration (references/lane-orchestration.md) § 3
Which toolkit release this skill’s facts describeSKILL.md § 0.2 — read VERSION and CHANGELOG.md first

Applies to: rebuilding an editable project from a shipped 2.4.x build; maintaining it; re-verifying it. Not for: Cocos Creator 3.x, Unity references (see t1k-cocos-playable-pla-from-ref), repackaging or signing an APK, or a project that already has readable sources, where there is nothing to unbuild.

0.1 Rule 1 — Claude Code only orchestrates

Section titled “0.1 Rule 1 — Claude Code only orchestrates”
Whoever runs this skill (the Claude Code orchestrator session) **never does unbuild work itself and never hands it to a Claude sub-agent or Claude worker.** Unbuild work is anything that reads an APK, XAPK or split; anything derived from one (decrypted client, asset mirror, readable overlay, generated or promoted project, preview and build output); and any run of the toolkit: pipeline, generator, promote, headless build, gate, verify-all, self-tests, editor-open probe, browser drive, **including every re-run done only to check a worker's report.** A headless `omp` worker lane executes all of it — one `omp -p` process per lane (recipe and probe evidence: lane-orchestration (`references/lane-orchestration.md`) § 2). The orchestrator plans, writes briefs, reads worker reports, logs and the toolkit's own source, cross-checks evidence files, talks to the user, and drives git through `t1k-git`. No worker lane available (preflight line 4 fails): **stop and tell the user which line is missing.** Never fall back to doing it in Claude, not even for a one-line probe. Override: none. Only the user can lift it, for one named task, in the same conversation, in plain words.

0.2 Toolkit versions — read VERSION and CHANGELOG.md first

Section titled “0.2 Toolkit versions — read VERSION and CHANGELOG.md first”

This skill does not ship the toolkit; it points at The1Studio/cocos-unbuild. Stage names, flags and exit codes move between releases, so a lane reads its clone’s VERSION and top changelog entry before its first step. As of 1.12.4 (each line checked against that release’s README, config README and changelog):

  • Gate exemptions are per project. The shipped WARNING_LEDGER.md is a template (generic entries 1-5); the per-project entries are read from the project’s own ledger named by config gate.ledger (or --project-ledger). A missing, unset or placeholder ledger exempts nothing, and that is reported.
  • Example-config placeholders fail loudly. Copy config/example.json to config/toolkit.json (or set TOOLKIT_CONFIG); loaders never fall back to the example, and an example value such as path/to/project, build.unpackCheck: example or verify.apiHost: game.example:3000 makes config/get.cjs exit 2 and pipeline.cjs --dry-run exit 1.
  • The runtime check needs project data. Without verify.runtimeCases/verify.runtimeGolden the runtime check is NOT-RUN and the verify verdict caps at GREEN (no runtime).
  • The intake mirror lands in <client.mirror>/assets, and the toolkit is self-contained.

Never cite this section against a different toolkit version.

RoleOwnsNever does
Orchestrator (this session)plan, briefs, evidence cross-checks, user comms, git via t1k-gitanything in § 0.1
Worker lane (a headless omp process)everything that reads the APK or runs the toolkitopen a PR, push, decide scope, add a ledger entry
Verify lane (a second, fresh-context worker)re-runs the acceptance commands, runs the editor-open probe, writes a per-claim verdictthe same as a worker lane

You verify a worker’s report by briefing a verify lane and cross-checking its evidence files, never by running the check yourself and never from the summary alone.

2. Preflight — say which line is missing, then stop

Section titled “2. Preflight — say which line is missing, then stop”

Exact checks: lane-orchestration (references/lane-orchestration.md) § 1.

  1. toolkit present at <toolkit-root> (GUIDE.md, README tool index, pipeline.cjs, gate.py, verify/);
  2. the shipped APK and its split present at the paths the toolkit config (TOOLKIT_CONFIG) resolves;
  3. Python 3, Node 18+ (Node 22+ for verify/), a Cocos Creator 2.4.15 install at cocos.creator, Chrome/Chromium for the browser stages; every tool and download: prerequisites (references/prerequisites.md). The toolkit runs on node, never bun — node pipeline.cjs, not bun pipeline.cjs; selftest.cjs resolves a node --test step’s binary from process.execPath, so under bun every node --test suite is executed by bun’s runner and fails, and bun --version proves nothing about Node (#1573);
  4. the omp CLI works (omp --version prints a version) — the lane’s only runtime dependency;
  5. the shared editor slot lock <toolkit-root>/.editor-slot.lock absent, and no stray editor process.

Before the first lane launch, in one message: the prerequisites notice above, then the user notice and the Bash(omp -p *) rule (permissions (references/permissions.md)) or the user’s choice to paste each printed command with the ! prefix. The orchestrator may ls/stat the APK and split files, but never lists or opens their contents — that is the lane’s job.

Order, the command per stage, exit codes and what GREEN means: pipeline-stages (references/pipeline-stages.md). In short: intake, uuid-map, rebuild, verify-pre, promote, build (slot lock), gate, verify, optional beautify, preview, smoke, then the opt-in acceptance and native stages, compare, selftest. Split any stage into a part that only writes derived files and a part that needs the editor slot, so two lanes never collide.

“Beautify” is a decision with five options, not one. Rename (the overlay, what the beautify stage applies) plus four the toolkit ships separately: C strip the cc._RF frame (tools/strip_rf.cjs), D folder split by feature (relayout/), E var f = function → function f (tools/fn_decl_rewrite.cjs), and the blind naming audit (tools/naming_audit_blind.cjs). Before any beautify run, present every option to the user with the toolkit’s own current status, one decision each — the table, the tools and the gate each option then needs: pipeline-stages (references/pipeline-stages.md) § 2b. Never run one the user did not choose (#1575).

Write the brief in English (brief-template (references/brief-template.md)), then start ONE headless lane:

Terminal window
omp -p @<brief-file> --cwd <toolkit-root> --max-time <duration> --no-session --auto-approve < /dev/null > <log> 2>&1

The steps a lane executes live only in omp-run-plan (references/omp-run-plan.md); the brief names paths, the duration and which plan steps this lane owns. Completion = the process exits AND the report file exists; a lane that exits without it failed, whatever its exit code. Run loop, replacing a stalled lane and small-model hygiene: lane-orchestration (references/lane-orchestration.md).

5. Acceptance before “it opens in the editor” — or a PR

Section titled “5. Acceptance before “it opens in the editor” — or a PR”
All of, in order: the headless build exits 0 with the slot lock held; `gate.py` and `verify-all.cjs` are GREEN; **a verify lane ran the editor-open probe** (`tools/editor_open_probe.cjs`, or `verify-all.cjs --editor-open`), which takes the slot lock, launches the GUI editor on the project with no build flag, judges only the log region its own run appended, kills the process it started and releases the lock; for web output the `runtime` check or the browser `acceptance` stage also ran. You cross-check the saved logs; you run none of it (§ 0.1). Contract for every gate: `theonekit-core/.claude/skills/t1k-cook/references/workflow-gates.md`. Override: a documented, user-approved deviation in the toolkit's approved-deviations section (`GUIDE.md` § 8), never a silent skip. An `INCONCLUSIVE` probe verdict (exit 3) is not a pass.

Why the editor step is not optional: a fidelity oracle is GREEN on a defect copied faithfully from the shipped data, and a headless build never runs the scene-loading path. Oracles green is not “a human can open it”.

6. Evidence standard — CONFIRMED vs REPORTED

Section titled “6. Evidence standard — CONFIRMED vs REPORTED”

Every claim carries the exact command, its exit code, and the raw output saved to a path (never retyped). A claim with no evidence path is unverified, not fact. An independent verify lane re-runs the acceptance commands and labels each claim CONFIRMED / MISMATCH / UNVERIFIABLE; a phase is done only after that verdict. In anything you report to the user, label each number CONFIRMED or REPORTED. Detail: acceptance-and-evidence (references/acceptance-and-evidence.md).

7. Approval gates — stop and ask the user

Section titled “7. Approval gates — stop and ask the user”

Never decide these yourself: a warning-ledger entry (the shipped WARNING_LEDGER.md template or the project’s own gate.ledger ledger), a logic deviation from shipped behaviour, a deletion (including “unused” code), opening or merging a PR, and tearing down the lane run.

  • references/omp-run-plan.md — the steps an omp lane executes (the SSOT; hand it to the lane)
  • references/pipeline-stages.md — stage order, commands, exit codes, invariants, what is NOT verified
  • references/lane-orchestration.md — preflight, starting and replacing an omp lane, small-model hygiene
  • references/prerequisites.md — tools and downloads to tell the user before the first lane
  • references/permissions.md — the Bash(omp -p *) rule, and the user-runs-it fallback
  • references/acceptance-and-evidence.md — the acceptance gate, the ledger and deviation path, evidence labels
  • references/brief-template.md — the short brief that wraps the plan
  • The1Studio/cocos-unbuild — the pipeline itself; its README ## Tool index is the per-tool reference
  • t1k-cocos-playable-pla-from-ref — the sibling for a Unity reference build (a different input, no APK)