Skip to content
T1KTheOneKit

t1k:cocos:playable:modularize-reuse-scan

FieldValue
Moduleplayable
Version0.15.0
Efforthigh
Tools—

Keywords: cpm-package, doc-search, knowledge-retrieval, modularize, playablelabs, reuse, reuse-scan, subsystem

How to invoke

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

reuse-scan (Pillar B)

Section titled “reuse-scan (Pillar B)”

Classify every local framework-ish subsystem as REUSE (duplicates an upstream foundation subsystem → swap for a package import), KEEP (game-specific glue), or CONTRIBUTE (novel, self-contained, general → hand to contribute). Part of the t1k-cocos-playable-modularize set — obeys the shared CLI contract.

When to invoke

Section titled “When to invoke”
  • After structure-audit flags embedded framework (R1 DRIFT): decide which subsystems to reuse.
  • “Which of our local systems already exist as @playablelabs packages?”
  • Before refactor: produce the REUSE/KEEP/CONTRIBUTE input its migration plan consumes.

Hard dependency — the knowledge-retrieval MCP

Section titled “Hard dependency — the knowledge-retrieval MCP”

The REUSE signal requires mcp__knowledge-retrieval__doc_search live in the session.

  • If the MCP is absent: the skill MUST error reuse-scan requires the knowledge-retrieval MCP (mcp.the1studio.org); restart the session and exit 3. It MUST NOT report “0 packages found” — that would falsely mark every subsystem CONTRIBUTE (errors over silent fallbacks).
  • Corpus reality (verified): doc_search indexes the TheOne .NET/Unity API corpus PLUS the Cocos template’s own subsystems (objectPool, signalBus, async, gameControl, GameFoundation.*, …). It is NOT a @playablelabs npm registry. Full contract + how to filter .NET noise: references/doc-search-contract.md.

Module contract (do not re-derive)

Section titled “Module contract (do not re-derive)”

Composition is plain import; there is no register(ctx). A REUSE swap replaces embedded-source imports with the owning package’s import and records the package in playableSync + assets/packages/@playablelabs/. Install SSOT + the package↔subsystem folder map: references/playablesync-ssot.md.

Workflow

Section titled “Workflow”
  1. Validate <project-root>; check the MCP — absent → exit 3 with the restart message.
  2. Enumerate: node scripts/enumerate-subsystems.cjs <project-root> → per-subsystem JSON with a self-containment / reuseLikelihood heuristic (game-coupled = low, self-contained = high).
  3. Query per subsystem: one behaviour-keyword doc_search each (see the contract). Read the top hits’ assembly; a high-similarity hit on a known foundation subsystem = “exists upstream”.
  4. Classify via references/classification-rubric.md (exists-upstream × game-coupled → REUSE / KEEP / CONTRIBUTE). Map REUSE subsystems to their owning package via the folder map.
  5. Report + suggest installs → reports/; persist JSON. For each REUSE subsystem, the report names the owning @playablelabs/* package and gives an install suggestion — the manual steps (npm/package-manager install-package, which appends playableSync + copies to assets/packages/@playablelabs/) so the dev can run it, or so --apply can do it. The REUSE/KEEP/CONTRIBUTE lists are the direct input to refactor (and contribute reads CONTRIBUTE).
  6. (--apply only) Decide via AskUserQuestion — with approval, reuse-scan may perform the suggested install via the package-manager install-package handler (append playableSync + copy the package). It NEVER rewrites game source imports (that is refactor). Gate per package.

Scripts

Section titled “Scripts”
Terminal window
node scripts/enumerate-subsystems.cjs <project-root>                 # subsystem list + heuristic (report-only)
node scripts/enumerate-subsystems.cjs <project-root> --roots assets/PLAGameFoundation,assets/PlayableParamterTool

References

Section titled “References”

Gotchas

Section titled “Gotchas”
  • A doc_search miss is only meaningful when the MCP ran. Never classify CONTRIBUTE off a miss caused by an absent MCP — error instead.
  • Filter .NET noise. The corpus is mostly Unity/.NET TheOne.*; treat a hit as REUSE evidence ONLY when its assembly is a known Cocos foundation subsystem. Use assembly_prefix to constrain.
  • doc_search proves existence, not the package name. Resolve the @playablelabs/* target from the folder map, not the hit.
  • No register(ctx). If you catch yourself designing a DI seam, stop — it does not exist.
  • AnimalHunter: embedded PLAGameFoundation/* and PlayableParamterTool/* are mostly REUSE (they mirror game-foundation / parameter-tool); scripts/AnimalHunterPLA/ wiring is KEEP.