Skip to content
T1KTheOneKit

t1k:cocos:playable:modularize

FieldValue
Moduleplayable
Version0.15.0
Efforthigh
Tools—

Keywords: contribute, cpm-package, migration, modularize, playablelabs, refactor, reuse, structure-audit

How to invoke

Section titled “How to invoke”
/t1k:cocos:playable:modularize
[structure-audit|reuse-scan|refactor|contribute] [<project-root>] [--apply]

t1k-cocos-playable-modularize

Section titled “t1k-cocos-playable-modularize”

Main goal: refactor/reuse/modularize the PROJECT itself — grade its structure, use the CPM library lookup to find tested @playablelabs/* packages that replace embedded source, and migrate the project to consume them. Contributing novel code back is a smaller, optional follow-on. Documentation-only orchestration — this file describes a 4-phase pipeline; there is no runtime skill-spawning. Each sub-skill runs standalone or in sequence.

When to invoke

Section titled “When to invoke”
  • Grade a project’s layout against the canonical playable-ad structure → structure-audit.
  • Look up the CPM library for existing tested packages that duplicate local code + suggest install → reuse-scan.
  • Produce an ordered plan to migrate embedded framework source → CPM packages → refactor.
  • (Optional) Separate a novel local subsystem into a real @playablelabs/<name> package → contribute.
  • Run the whole thing end-to-end → the four in order (audit → reuse → refactor → optionally contribute).

Pipeline

Section titled “Pipeline”
#Sub-skillPillarOutput
1t1k-cocos-playable-modularize-structure-auditA — structural conformancePer-rule CONFORMANT / DRIFT / MISSING vs the vendored blueprint.md + a normalization plan.
2t1k-cocos-playable-modularize-reuse-scanB — reusePer-subsystem REUSE / KEEP / CONTRIBUTE via CPM-library lookup (doc_search); suggests installing reusable tested packages (manual, or via the package-manager).
3t1k-cocos-playable-modularize-refactorC — project-firstOrdered project refactor plan: folder-norm → REUSE swaps → embedded-submodule→CPM migration → tag CONTRIBUTE. No package splitting.
4t1k-cocos-playable-modularize-contributeD — contribute (optional)If worth it, separate a novel assets/scripts subsystem into assets/packages/@playablelabs/<name>/ + a package.json, as plain readable TS; dev decides publish (manual/AI). Never publishes.

Dependencies: 2 and 4 need the knowledge-retrieval MCP (doc_search) live in the session; 3 needs 1+2’s reports; 4 needs 3 landed. Full ordering + gates live in each sub-skill body.

Shared contract (stated ONCE here; children reference, never restate)

Section titled “Shared contract (stated ONCE here; children reference, never restate)”

All four sub-skills obey the SAME operating contract. Read it once, then apply per phase:

  • Report-only by default. A bare run reads the project and emits a markdown report + a machine JSON artifact. It NEVER mutates the project.
  • --apply mutates — and only after the AskUserQuestion decision gate. See references/shared-cli-contract.md for the exact flag semantics, the decision-gate options, and the report/exit format.
  • Errors over silent fallbacks. A missing MCP, absent input report, or unreadable project is a clear surfaced error — never a false “nothing found”. (e.g. reuse-scan without the MCP errors “requires knowledge-retrieval MCP”, it does not report “0 packages”.)
  • One unit at a time for anything risky. Migration and .meta-adjacent changes run on a git branch, one migration unit per --apply, each behind its own gate.

CPM ground facts (SSOT for all children)

Section titled “CPM ground facts (SSOT for all children)”

Composition is plain import. register(ctx) does NOT exist in this framework — do not design or assume a DI seam. The install SSOT is the playableSync array in the Cocos project’s package.json; the @playablelabs scope resolves via .npmrc. All code the skill reads/writes is plain, readable TypeScript. Full facts (package-manager handler set, registry) live in references/shared-cpm-facts.md. Where AnimalHunter (the guinea pig) actually keeps things: references/shared-project-map.md.

References

Section titled “References”
  • references/shared-cli-contract.md — report-only default, --apply semantics, AskUserQuestion gate, report + exit-code format. Every sub-skill’s CLI section links here.
  • references/shared-cpm-facts.md — playableSync install SSOT, @playablelabs scope + registry, real package-manager handlers, “plain readable TS”, “no register(ctx)”.
  • references/shared-project-map.md — canonical vs AnimalHunter layout; embedded PLAGameFoundation/PlayableParamterTool vs packages/@playablelabs/.

Gotchas

Section titled “Gotchas”
  • Folder-grading is layout-only. structure-audit grades folders, never verifies that declared packages are actually imported — that consumption check belongs to reuse-scan/refactor.
  • Never move or delete a .meta silently. .meta files carry Cocos asset UUIDs; moving/deleting one re-points every scene/prefab reference. Quarantine-to-report only, behind a gate.
  • Code work is scoped to assets/scripts. reuse-scan/refactor/contribute analyze and modularize the project’s own scripts; structure-audit still grades the whole assets/ folder layout. Everything is plain, readable TypeScript — the skill never rewrites or transforms source (publishing is a separate dev option it doesn’t touch).