Skip to content
T1KTheOneKit

t1k:cocos:playable:modularize-contribute

FieldValue
Moduleplayable
Version0.15.0
Effortmedium
Tools—

Keywords: contribute, modularize, novel-subsystem, package-extraction, playablelabs, scaffold-package, split-proposal

How to invoke

Section titled “How to invoke”
/t1k:cocos:playable:modularize-contribute
<project-root> [--apply] [--split game-foundation]

contribute (Pillar D — secondary)

Section titled “contribute (Pillar D — secondary)”

The main goal of t1k-cocos-playable-modularize is to refactor/reuse/modularize the project itself (structure-audit → reuse-scan → refactor), scoped to assets/scripts. This phase is the smaller follow-on: if something in assets/scripts is worth contributing back, separate it into a real @playablelabs/<name> package (plain readable TS) and let the dev decide on publishing. Obeys the shared CLI contract.

When to invoke

Section titled “When to invoke”
  • After refactor landed: turn reuse-scan’s CONTRIBUTE tags (subsystems under assets/scripts) into real local packages.
  • To propose decomposing the coarse @playablelabs/game-foundation into finer packages.

Skip this phase entirely if assets/scripts has no novel, self-contained, generally-useful subsystem — contribution is optional, not a required step.

What it does

Section titled “What it does”

For each CONTRIBUTE candidate:

  1. Re-verify it has no upstream equivalent (one doc_search per candidate — a missed synonym can hide an existing package).
  2. Separate it into a package: copy the subsystem source (from assets/scripts/<sub>) into assets/packages/@playablelabs/<name>/, add a package.json (with publishConfig.registry) + an index.ts barrel. Straight, readable TypeScript — the code is copied as-is.
  3. STOP. Print the publish-decision note. The dev decides whether/how to publish — manually, or by asking the AI. This skill NEVER publishes.

Details: references/package-skeleton.md.

Publishing is the dev’s call (not this skill’s)

Section titled “Publishing is the dev’s call (not this skill’s)”
  • contribute scaffolds the package locally only (plain readable TS) and prints the manual/AI publish steps. It never runs npm publish.
  • There is no package-manager build/publish/bump handler — publish is manual npm (or AI-assisted) by design. Don’t try to route publish through the extension.

Workflow

Section titled “Workflow”
  1. Validate <project-root> + confirm the project refactor landed (healthy project — don’t extract from one still failing structure-audit/reuse-scan). Else exit 2 with the reason.
  2. Collect CONTRIBUTE candidates from the reuse-scan report; re-run doc_search per candidate.
  3. Separate (report-only): node scripts/scaffold-package.cjs --name <n> --from <dir-or-file> prints the file plan + publish-decision note. --from takes a directory OR a single .ts file and is repeatable — extract exactly the files the CONTRIBUTE unit needs, since a folder often mixes REUSE/KEEP/CONTRIBUTE files (a file’s sibling .meta is co-copied). --apply copies the source + writes package.json + index barrel.
  4. Split proposal (optional): --split game-foundation emits the advisory split table (references/split-proposal-format.md) — proposals only.
  5. Report the new package path(s) + the publish-decision note → reports/.

Scripts

Section titled “Scripts”
Terminal window
node scripts/scaffold-package.cjs --name <n> --from assets/scripts/utils/Log.ts             # report-only: single-file unit
node scripts/scaffold-package.cjs --name <n> --from assets/scripts/foo.ts --from .../bar.ts  # multi-file unit (repeatable)
node scripts/scaffold-package.cjs --name <n> --from assets/scripts/<sub> --apply             # whole dir -> @playablelabs/<n> (plain readable TS)

References

Section titled “References”

Gotchas

Section titled “Gotchas”
  • Secondary phase — optional. The deliverable of the skill set is a modularized project (assets/scripts); contribute only fires when there’s genuinely novel code worth extracting.
  • Extract at file granularity, not whole folders. A folder like assets/scripts/utils often mixes verdicts (e.g. MathConstants.ts=REUSE, Log.ts/MeshFoot.ts=CONTRIBUTE, ImageScaler.ts=KEEP). Use --from <file.ts> (repeatable) to package exactly the CONTRIBUTE files — don’t --from the whole dir when it’s mixed.
  • Never publishes. Scaffolds locally (plain readable TS); the dev decides publish (manual or AI). Prints the steps.
  • Runs on a healthy project only — require refactor landed; re-verify CONTRIBUTE via doc_search before extracting.