Skip to content

t1k:cocos:playable:pla-retrofit

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: cocos-stdlib retrofit, đưa code lên stdlib, lordmobile retrofit, pla retrofit, retrofit pipeline, stdlib retrofit

/t1k:cocos:playable:pla-retrofit
[<project-root>] [--stage b0..b9] [--integration-branch <name>]

Main goal: take a shipped playable project and make its reusable code live in the studio library (The1Studio/cocos-stdlib, @playablelabs/* packages) — measured, gated, and provably done.

This skill orchestrates; it implements nothing. Every stage below is an existing skill or an existing script. What this file owns is the order, the gate between stages, and the six decisions that are the same on every project — the ones a fresh session gets wrong because they are not written down anywhere else.

Documentation-only orchestration — there is no runtime skill-spawning here. Each stage runs standalone; this file tells you which one, in what order, and what must be true before the next.

  • Running the whole retrofit on one project end to end (<project-root>).
  • Resuming at a stage (--stage b4) after a stop.
  • Answering “is this retrofit done?” → walk § “Definition of Done” and then run stage B9.

Not for: a greenfield playable (→ t1k-cocos-playable-gen), a one-off refactor (→ t1k-cocos-playable-modularize), or a single component split (→ t1k-cocos-playable-primitive-decompose).

The six decisions this file fixes (read before stage B0)

Section titled “The six decisions this file fixes (read before stage B0)”

These are not preferences. Each one has a failure attached.

  1. Pure-TS packages only. core-/feature-/mechanic- — no cc-* package. The cc layer shrinks by refactor/relocate, never by packaging it. Moving a cc.Component into a package changes its script UUID and re-wires nothing; a cc-* package also cannot be reused by a non-Cocos consumer, which defeats the library’s purpose.
  2. Goldens gate every logic move. No logic is moved before the characterization golden covering it is written and committed. A move without a golden is unverifiable — you cannot tell a faithful relocation from a silent behaviour change, and the suite that would have caught it is the one you did not write.
  3. Measurement writes nothing into the repo. Every --json report goes to a scratch path outside the project. A measurement that mutates the tree it is measuring has invalidated itself, and the diff noise buries the real change.
  4. ONE integration branch. All lanes merge into refactor/stdlib-packages (or the name given by --integration-branch), cut from the project’s real base branch. At the end it merges back and is deleted — the repo is left with its normal branch count, not a branch per stage.
  5. Lane worktrees live under the scratchpad and are reaped immediately. One worktree per parallel lane, created under scratch (never inside the project), removed and its lane branch deleted the moment that lane merges. A retrofit leaves zero worktrees behind. git worktree list is part of the final report — the count is an output, not an implementation detail.
  6. Package granularity is by functional group, not by file. A ~330-line mechanic becomes one package; a ~50-line helper does not become its own package — it goes into an existing one (core-utils for math/hysteresis/vector helpers). Micro-packages trade a real reuse win for publishing overhead and version churn.

Stage table — the gates are the contract

Section titled “Stage table — the gates are the contract”
StageWorkExecutorGate OUT (do not advance until this holds)
B0Test harness: vitest at environment: 'node', a narrow db:// alias (@playablelabs/core-*|mechanic-*|feature-* only), colocated tests dot-prefixed (.tests/)t1k-cocos-playable-characterization (harness mode) + t1k-game-archthe test script RUNS (a vacuous pass is not a pass — at least one real import resolves through the alias)
B1Characterization goldens for every reachable piece of logic, seeded inputst1k-cocos-playable-characterizationgoldens committed; replay green against the unmodified tree
B2Dead code: delete what the sweep proves unreachableverify-reachability.cjs --all (A1)every deletion is ORPHAN; every UNKNOWN kept, with its keep-reason recorded
B3Hardcode → named constants / confighardcode-scan.cjs (A4)0 findings in files this work touched. Pre-existing findings elsewhere are a backlog line, not a gate
B4Relocate logic out of cc.Component into pure-TS modules — each module’s unit test written immediately before that module movest1k-cocos-playable-primitive-decompose, t1k-cocos-base-clean-architecture--cc-thickness gluePct down AND goldens replay green AND a typecheck:game pass over assets/scripts/** (see below). All three, not any two
B5Contribute to cocos-stdlib — scope gate, corpus sweep, decouple, scaffold, PRt1k-cocos-base-stdlib-contribute / t1k-cocos-playable-stdlib-autocontributePR merged, CI green, gatekeeper APPROVE. Merging publishes
B6Adopt: vendor → repoint db:// imports → retire the originals, one commit per unitt1k-cocos-playable-stdlib-adoptreachability re-run before each deletion; each commit prints its git revert <sha>
B7Re-measure: coverage + adoption + cc-thicknessreuse-coverage.cjs (A2) + adoption.cjsall three numbers reported, --index explicit, reports outside the repo
B8Four-layer gate: vitest → equivalence → headless preview-verify → human playtestpreview-verify + a humanconsole clean, CTA fired, diffPercent reported, and the human’s confirmation on the record. STOP here — do not self-certify this layer
B9Whole-repo reviewt1k-tester (runs G1-G8) → t1k-cocos-playable-pla-retrofit-reviewer (A5, reads the gate JSON, judges)verdict PASS — zero gates errored/not-run, zero blocking findings

Full per-stage detail, the commands, and the lane-management recipe: references/stage-gates.md.

Portability (A3) — enforced by another repo, referenced by name. bun <cocos-stdlib>/scripts/portability-check.mjs --strict runs against every core-/feature-/ mechanic- package before its PR. The script lives in cocos-stdlib, which owns the rule — locate it, never vendor it into this kit. It forbids decorators, Proxy/Reflect, eval/new Function, dynamic import(), prototype mutation, explicit any, arguments, loose ==, unqualified DOM/Node/window, undeclared-side-effect getters, and magic Symbol beyond iteration. cc-* is exempt — and since decision 1 rules those out, every package this pipeline produces is subject to it.

The core hook (A7) — the net has a hole, and CI is under it. cocos-stdlib-portability-guard.cjs is a theonekit-core PreToolUse hook (this kit ships zero hooks by design — gate #22). It runs the same A3 check on the content about to be written, inside a cocos-stdlib checkout, and blocks a violation. It fires on Edit/Write only — a sed, a heredoc, or any Bash-based write goes straight past it. That hole is precisely why stage B5’s CI check is not optional and why B9 re-runs A3 by hand: the hook and CI are two layers of one gate, and neither covers what the other misses.

Measurement discipline — applies to every --json in the table. Write reports to a scratch dir; pass --index <clone-index-dir> explicitly on every coverage and adoption run. Omitting it lets the resolver’s <cwd> candidate win, and two runs of the same command from different shell directories read two different clone-index dirs while both report templateBaseline: available. A bare “available” proves an index was read, not which one.

Lane discipline. Parallel lanes each get a worktree under scratch, cut from the integration branch; they merge back with --no-ff, and the worktree plus its branch are removed immediately on merge — not at the end. A lane left standing holds a branch, a checkout, and a merge conflict waiting to happen. The final report states the worktree count, and the number after the last merge is zero.

references/stage-gates.md § “Definition of Done” is the SSOT — eight goals, each with the gate that proves it, and the prohibition against reporting done on a green suite alone. Walk it before reporting anything. A green vitest run is evidence for one clause of one row, and a report that leads with it and omits the rest is the exact failure that section’s prohibition exists to stop.

  • Coverage moving DOWN mid-relocation is expected, not regression. Moving pure logic out of a component without a package vendored yet raises the project denominator — stdlib + project grows while stdlib stays 0. The payoff lands at B6. A report must say this, or a reader sees the number fall and concludes the strategy failed while it is doing what the metric predicts.
  • cc-thickness is the before/after pair for B4, and it must be taken at the same --scope. Two numbers describing different file sets are not a comparison.
  • gluePct down does not mean the relocated code still runs — B4 also needs a typecheck:game. A project typecheck covering only .tests/ compiles none of assets/scripts/**, i.e. exactly the cc.Components this stage rewrites. A finished retrofit’s review found two runtime crashes that the unit suite and that typecheck both passed clean, because the suite imports the logic unit directly and never loads the component. Run tsc-baseline.cjs (from t1k-cocos-playable-modularize-refactor) over the game against the editor’s temp/declarations cc types, with the pre-existing vendored errors held in an identity-keyed known-gap list asserted in both directions — new fails, vanished reports STALE (theonekit-core/.claude/modules/t1k-verification/rules/pinned-baseline-test-companion.md). Never a raw exit code: a legacy tree is red before B4 starts, and an always-red gate is ignored as surely as an always-green one.
  • adoption and coverage measure different things — what is used vs what is installed. B7 reports both; a package installed and never called raises coverage and leaves adoption flat.
  • references/stage-gates.md — per-stage commands, the Definition of Done (including the DoD prohibition), the lane recipe, and the failure modes
  • t1k-cocos-playable-pla-retrofit-reviewer — the stage-B9 agent
  • t1k-cocos-playable-modularize — the sibling CPM pipeline (this one is the retrofit-specific order)
  • t1k-cocos-playable-reuse-coverage — the B7 metrics, including --cc-thickness
  • rules/knowledge-sweep-cocos.md — the reuse loop every B5 package starts from