t1k:cocos:playable:modularize-refactor
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: embedded-to-cpm, import-repoint, modularize refactor, playablesync
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:modularize-refactor<cocos-project-root> --audit <path> --reuse <path> [--arch <path>] [--apply]refactor (Pillar C, project-first)
Section titled “refactor (Pillar C, project-first)”Turn the audit + reuse classifications into an ordered project refactor plan and (with --apply)
execute it incrementally. Migrates the embedded framework (PLAGameFoundation, PlayableParamterTool)
to CPM-package consumption. No package splitting — that is contribute. Part of the
t1k-cocos-playable-modularize set — obeys the shared CLI contract (../t1k-cocos-playable-modularize/references/shared-cli-contract.md).
Graph grounding — t1k-cocos-base-code-graph
Section titled “Graph grounding — t1k-cocos-base-code-graph”The studio code graph (code-graph-cocos) answers the one question the corpus and grep both cannot:
what is structurally connected to this symbol. Recipes, the Cocos-only gaps and the provenance
line: t1k-cocos-base-code-graph; usage SSOT: core’s t1k-code-graph.
Every tier below that repoints or retires an import edge — Tier 0 upgrades, Tier 2 swaps,
Tier 2.75, Tier 3’s submodule removal — deletes or moves a source the graph sees as an edge source.
Before any such unit, get_neighbors on the symbols it touches bounds who depends on them, so a
non-empty incoming set is the argument against retiring.
It is corroboration, not a gate. The graph is nightly and default branch only: a call site added
since the last build is invisible, and a call site the unit itself just deleted is still listed. So
verify-imports.cjs / verify-reachability.cjs on disk stay the pass condition for every unit, and
the graph answer is recorded beside them — a divergence is a finding to report, not a tie to break
silently. Nothing in the unattended-walk block below may be released on a graph result alone.
Read it as blast radius for scoping a unit, never as a licence to delete: no dead-code verdicts on
Cocos (@ccclass attaches via prefab __uuid__, not an import).
When to invoke
Section titled “When to invoke”- After
structure-audit+reuse-scan: produce the ordered migration plan. - To execute a migration incrementally (
--apply, one package per gate).
Hard precondition
Section titled “Hard precondition”Requires BOTH input reports: a structure-audit JSON (--audit) and a reuse-scan JSON (--reuse).
plan-refactor.cjs sets preconditionsOk: false if either is missing/empty — the skill then
hard-blocks --apply (report the missing input; do not guess a plan).
An architecture-audit JSON (--arch, from t1k-cocos-base-architecture-patterns audit mode) is
optional but strongly recommended. Without it Tiers 2.5/2.75 are skipped and the plan reports
archAudit: absent — a legacy project then migrates its structural debt into packages untouched.
The design-doc probe BLOCKS Tiers 2.5/2.6/2.75 — always pass --design-probe
Section titled “The design-doc probe BLOCKS Tiers 2.5/2.6/2.75 — always pass --design-probe”bun <system-design>/scripts/probe-design-doc.cjs docs/system-design.md <repo-root> > design-probe.jsonbun scripts/plan-refactor.cjs --audit <a> --reuse <r> --arch <arch> --design-probe design-probe.jsonplan-refactor.cjs records designDoc: ok | foreign | template-verbatim | template-unfilled | non-canonical | absent | indeterminate | unchecked, and emits a machine-readable blockers[] +
blockedTiers whenever that verdict is anything but ok. Every step in a blocked tier repeats the
block inline as blockedBy, so an --apply walker refuses those units mechanically rather than
relying on the operator having read a warning two hundred lines up.
unchecked (flag omitted) blocks too. Not asking is not a pass — it is precisely the state an
inherited doc sits in while looking healthy to every other check here
(theonekit-core/.claude/modules/t1k-verification/rules/negative-result-scope.md).
Three reasons this is a block and not a warning: (1) a doc describing another project satisfies
every other check identically — structure-audit R9 only asks whether the file exists, and
generate-manifest’s failure surfaces as the generic designState: null; measured 2026-08-20
(HexaBugFlowPLA), a 16-step plan with six Tier 2.5 module-boundary steps graded against
PlayableAdsTemplate’s doc. (2) designState: null and “the doc belongs to someone else” need
different repairs — regenerating a manifest fixes the first and is useless against the second, so the
plan names them separately (design-manifest-missing vs design-doc-foreign). (3) Tier 2.5 is the
only tier that rewrites source logic, and its splits break scene references tsc cannot see;
boundaries nobody decided are the most expensive thing this pipeline can produce.
The block is scoped on purpose, and the scoping is what keeps it enabled. Tiers 0/1/2/3/4 are
version, folder and import-path work no design doc grades — fully plannable and appliable on a legacy
repo with no doc, with plan-refactor.cjs still exiting 0 and still printing the blocked
findings. A gate that refuses the whole report is one operators route around, and then it protects
nothing.
Phase 0 — design doc before planning
Section titled “Phase 0 — design doc before planning”This is the pillar that genuinely requires docs/system-design.md (pillars A and B do not — see
the dependency table in t1k-cocos-playable-modularize). Its § “Code Structure Rules (Mandatory)” is
the SSOT Tier 2.5 is graded against, so planning without it means measuring against nothing.
Resolving, authoring and drift-auditing the doc is owned end-to-end by t1k-cocos-base-system-design
(authoring + template resolution) and t1k-cocos-base-architecture-patterns (audit), including the
missing-template and legacy “no architecture to document” cases. Do not re-derive that procedure
here; it is report-or-author only and never mutates code.
Generate the manifest from the doc, then pass it so the plan records what it was graded against:
bun <system-design>/scripts/generate-manifest.cjs docs/system-design.md --out docs/design-manifest.jsonbun scripts/plan-refactor.cjs --audit <a> --reuse <r> --arch <arch> --manifest docs/design-manifest.jsonThe plan reports manifest: present | absent | unchecked. unchecked (flag omitted) is not
absent — the first makes no claim about the project, the second is a checked negative. Omitting
the flag on a project that has no doc is the case that reads as fine and is not.
It also records designState — the doc’s tense. A plan built from a to-be manifest moves TOWARD
a documented target; from as-is, AWAY from documented current reality. Identical step lists,
opposite meaning; say which one you are executing. designParse: "partial" means the module map was
only partly readable, so the plan is not fully informed.
designState: null is a third case, and the common one. No manifest was read at all, so the plan
moves neither toward a target nor away from a baseline — a bottom-up list of violation fixes whose
module boundaries land wherever the split test happened to cut. The script says so on stderr and
mirrors it into the artifact as designStateWarning (null in every other case), because a plan built
against nothing reads exactly like one built against a target: ordered tiers, real evidence,
plausible steps. The fix is upstream: run t1k-cocos-playable-modularize Phase 2.5
(t1k-cocos-playable-preproduction in refactor mode) to author the to-be doc from the as-is doc
architecture-audit.json+reuse-scan.json, regenerate the manifest, re-plan with--manifest. Exit stays 0, but the design-probe gate above also raises adesign-manifest-missingblocker withholding Tiers 2.5/2.6/2.75 — the report still prints in full, which is what keeps pillars 1 and 2 usable on a repo with no doc. Exiting non-zero is what would get the pipeline abandoned on exactly the legacy projects it exists for; withholding tiers does not.
verify-manifest gates --apply
Section titled “verify-manifest gates --apply”Before mutating anything, the manifest must still describe the code:
bun <system-design>/scripts/verify-manifest.cjs docs/design-manifest.json <project-root>Non-zero exit blocks --apply. Planning against a manifest that no longer matches the tree means
every Tier 2.5 step is aimed at a file layout that has already moved. Verification is
state-dependent, so read pathsChecked in the report: under to-be it is false and a pass proves
only internal consistency — it is not evidence the code matches. Unclaimed files are reported and
never block; a legacy project is mostly unclaimed and that is the finding, not an error.
Plan generation — once, up front
Section titled “Plan generation — once, up front”The whole-refactor plan is built once, in step 2 below, from all three audits, before any
mutation. Architecture findings are an input to planning, not a mid-flight discovery: audit early,
mutate in tier order. Do not replan between units — if a finding emerges during --apply, record it
and re-plan in a fresh pass.
Ordering (safe → risky) — never reorder
Section titled “Ordering (safe → risky) — never reorder”-
Tier 0 — upgrade installed-but-outdated packages: one row per
@playablelabs/*package whose installed version is behind the registry latest, from the reuse-scan report’sinstalledVersionsblock. Lowest risk, highest value — and the ONLY tier that fires on a project that already finished CPM migration, where Tier 3 is empty by construction. Gated per-unit: an upgrade is a small diff but can still change behaviour.The action is a command, never a panel instruction — every row renders as
bun <refactor-skill>/scripts/upgrade-package.cjs <cocos-project-root> <pkg> --to <latest> --expect-installed <installed>, which self-verifies by re-reading the vendoredpackage.jsonand exits non-zero unless the version on disk is the one asked for.update-package via package-managernames an editor-panel handler no MCP tool exposes, so--implementreached the row with nothing to run and the upgrade silently never happened (pinned byplan-refactor-tier0-executable-action.test.cjs).Two axes decide routine vs BLOCKED, both read from the reuse-scan:
vendoredDivergence/locallyModified(#274 — the upgrade overwrites the vendored tree and deletes a local patch whiletscstays clean) andimportPathCheck/removedImportPaths(#294 — semver is no proxy: the measured case was a patch bump removing 3 of 14 imported paths). A recorded finding blocks atrisk: highwith arequires:prerequisite; an absent check blocks atrisk: medium(divergence-never-checked/import-paths-never-checked), because unchecked is “nobody compared”, not “nothing is patched”. One row per package carrying everyblockReasonsentry it trips and onerequires:per reason. A Tier 0 row reachesunattended.walkOrderonly when both axes ran and neither recorded anything — full matrix in decision-policy rule 5, full rationale inreferences/migration-playbook.md§ Tier 0.A VERIFIED
@playablelabs/parameter-toolsync is not a wired one (#1719). Read the result’shostWiring: the host must callPlayableConfigProvider.initialize(PlayableConfig, meta, CURRENT_SDK)and register theParameterToolRuntimeseams itself, and the sync only warns. Steps: § Tier 0 “Host wiring” in the same playbook. -
Tier 1 — folder normalizations (create canonical dirs, gitignore artifacts, quarantine orphan metas to report, review unexpected top-level dirs, relocate stray
game-assets/entries). Rules that grade more than one sub-condition (R2, R3) emit one row per sub-condition that actually fired, each carrying only its own evidence — never a fixed action per rule ID (#249). R11 (a script directory that has become the codebase) emits areport-onlyrow, not a move: the audit knows which directory is crowded, only the design doc knows which module each file belongs to. With--manifestthe row names the real target modules and points at the Tier 2.6 rows that actually order the moves; without one it says plainly that no targets are known and routes to Phase 2.5, because a split into invented folders is worse than the pile it replaces. -
Tier 1.5 — INSTALL a package a live REUSE swap needs and the project does not have, via
install-package.cjs. One unit per package ROOT,editorState: closed, and the Tier 2 swap that needs it declaresdependsOnthis unit. Only a live swap earns an install — akeep-retract, anextendor amanual-queueis a decision NOT to import that package, and installing anyway vendors code the plan already declined. Before this tier the install was a parenthetical (install package first — Tier 3) pointing at a tier that emits nothing for a package which is merely absent: ordered by prose, owned by no tier, executable by nobody (theonekit-core/.claude/modules/t1k-verification/rules/wired-not-just-present.md). -
Tier 2 — REUSE swaps for packages installed already or by Tier 1.5 (pure import-path changes). Runs before architecture work: never refactor code a swap is about to delete.
-
Tier 2.5 — architecture refactor (SOLID + mandatory pattern triggers per
rules/code-quality-cocos.md), driven by the--archfindings. Includes enabling extractions — SRP splits whose purpose is to expose a seam that a package can then fill. -
Tier 2.6 — MECHANIC SLICE: move each design-doc module into its own vertical folder, one unit per module,
editorState: closed. Delegated in full tot1k-cocos-playable-mechanic-split— that skill is the SSOT for the procedure (cid snapshot/diff around every move,.ts+.ts.metaco-move, barrel + README contract, portability-blocker scans). This skill owns only the wrapper: which modules, in what order, gated per unit. Boundaries come from the manifest, never from a coupling audit re-run here — every row invokes it as--mechanics-from docs/design-manifest.json, because a second module map decided by a different method is the one failure this delegation exists to avoid. Rows carrydependsOnthe Tier 2.5 extraction that rewrites their files, and a module already living in its own folder emits no row at all. This is the tier that turns R11’s report into work: it stayed report-only for want of the module table, and the manifest is that table. -
Tier 2.75 — second REUSE pass over the seams Tier 2.5 exposed (
exposesSeamForin the arch findings). Skipping this makes Tier 2.5 a net loss: more files, same duplicated logic. -
Tier 3 — embedded-submodule → CPM migration, per package. Highest blast-radius. Delegated in full to
t1k-cocos-playable-submodule-to-package, the SSOT for the procedure (submodule removal, vendoring,playableSync, import repoint + API-signature changes,ParameterToolRuntimeseams, scene/prefab uuid remap, its own defect scanner); this skill owns only the wrapper: gate → invoke → both verifiers green → editor confirm → remove embedded dir → pathspec commit. Tier 1.5 supersedes it for a package that is merely ABSENT — Tier 3 ends in “remove the embedded dir”, and there is none when the source was never vendored; before 1.5 this loop doubled as the install path and named the dead panel handler to do it. -
Tier 4 — tag CONTRIBUTE (no mutation; hand-off to
contribute).
editorState and the unattended walk block — see references/editorstate-walk-block.md
Section titled “editorState and the unattended walk block — see references/editorstate-walk-block.md”Executed by
Section titled “Executed by”Plan generation, status and delta reporting are scripts; executing the refactor is not. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run plan-refactor.cjs --audit, refactor-status.cjs and symbol-delta.cjs and relay their tables | t1k-list-classifier |
Run install-package.cjs / retire-consumed.cjs for one planned step | t1k-cocos-base-tester |
Execute a refactor step or resolve an editorState block | t1k-cocos-base-developer — reasoning tier |