Skip to content

t1k:cocos:playable:stdlib-adopt

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: adopt stdlib packages, consumption pass, đo reuse coverage, dùng package thay code cũ, repoint imports, retire local copy, stdlib-adopt, switch onto published packages

/t1k:cocos:playable:stdlib-adopt
[<project-root>] [--scope <glob>] [--index <clone-index-dir>] [--packages <a,b,c>] [--measure-only]

One autonomous consumption lane over a PLA project: find what already ships as a published @playablelabs package, vendor it, repoint imports, retire the local original, and re-measure — choosing every design-standard decision itself instead of asking, then reporting the resulting reuse coverage to the terminal.

This skill invents nothing mechanical. Vendoring is install-package.cjs (t1k-cocos-playable-modularize-refactor) — a CPM registry install, never a hand-copy (SSOT: shared-cpm-facts.md § “Consumption is CPM-registry-only”; auth-failure procedure: vendor-fallback.md). Deletion is retire-consumed.cjs (t1k-cocos-playable-modularize-refactor). Discovery is enumerate-subsystems.cjs (t1k-cocos-playable-modularize-reuse-scan). Measurement is reuse-coverage.cjs (t1k-cocos-playable-reuse-coverage) / adoption.cjs (t1k-cocos-playable-reuse-coverage). What this skill adds is the autonomous orchestration around those four scripts, plus the retire-then-measure chaining retire-consumed.cjs deliberately stops short of (it patches one report’s denominator and prints “bySource/subsystems/declaredSources were NOT recomputed” — this skill is what runs the recomputation).

Scope. Reads assets/scripts/**. Writes: assets/scripts/** (repoint, retire), assets/packages/@playablelabs/** (vendor), package.json (playableSync), vitest.config.ts (alias). Never scenes, never prefabs, never any other asset.

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.

Stage 6 (reachability, before any deletion) is where this matters, and the graph is a second opinion for it, never a replacement. verify-reachability.cjs’s four checks on disk remain the authority: a graph zero-caller result on a Cocos @ccclass is not an ORPHAN signal, because the component is attached by prefab __uuid__ rather than imported — the exact misreading stage 6 exists to prevent.

Use get_neighbors on a subsystem’s exports before stage 7 retires a file, to bound the blast radius and decide the retire order. Still grep-ground, and re-ground after the repoint: the graph is nightly and default branch only, so it reflects neither the imports stage 5 just rewrote nor a file stage 3 vendored minutes ago.

The no-file contract — read this before invoking either measurement script

Section titled “The no-file contract — read this before invoking either measurement script”

reuse-coverage.cjs and adoption.cjs always write JSON and have no flag to suppress the write. Both print their text table to stdout unconditionally, so the terminal already carries the full result — the write is never needed to see the number.

  • Every invocation of either script MUST pass --json to a path outside the project, in the session scratchpad (e.g. --json "$SCRATCH/coverage-$(date +%s).json"). Never let --json default — its default is <project-root>/reports/<tool>.json, inside the repo.
  • reports/ must never appear inside the project tree. This is a rule, not a preference.
  • Why it is a rule: retire-consumed.cjs patches any reports/reuse-coverage*.json already present in the project, in place, and auto-includes it in its own commit (it walks <project>/reports/ for reuse-coverage*.json and rewrites the candidate’s row out of every hit it finds). Two lanes that both left a report in reports/ would have the retire commit sweep one lane’s staged measurement into the other lane’s commit, with no conflict marker — the same git-index race theonekit-core/.claude/modules/t1k-parallel/rules/parallel-teammate-git-index-race.md warns about, produced here by a script rather than by git add -A. Keeping the file out of the repo removes the hazard instead of working around it.
  • --verdict mode is the one exception worth naming. It already re-spawns the parent script against its own throwaway temp path internally, so it never touches reports/ — it is not a loophole in the rule above, it is a mode this rule does not apply to.
  • Do not follow the hint retire-consumed.cjs prints when it finishes. Its own closing note tells you to regenerate with --json reports/reuse-coverage.json, an in-repo path (retire-consumed.cjs:619). Following that advice is how the report file gets created in the first place, which then arms the in-place patch described above on the next retire. Take the instruction — re-run reuse-coverage.cjs — and substitute a scratchpad path for the one it suggests.

Decide and proceed, never ask: which subsystem is REUSE/EXTEND/KEEP, package version pin, playableSync/peer registration shape, vitest alias placement, per-file retire ordering, commit message wording, whether a coverage read is worth reporting mid-run.

Retained hard stops — not design-standard choices, the autonomy grant does not reach them:

  • bun publish of a package (out of scope for this skill anyway — it only consumes).
  • Merging a PR whose CI is not green.
  • The human playtest, layer 4 of the four-layer gameplay gate (below).
  • Any write outside the declared scope above.
  • Anything under theonekit-core/.claude/modules/t1k-orchestration/rules/off-scope-finding-offload.md’s never-offload set: destructive ops, credentials, permission/config changes.

An autonomous run that hits a retained stop reports and halts — it does not route around the stop, does not guess an answer, does not skip the stage and continue past it.

#stageowned bygate
0Preflight — detect Cocos project, resolve scope, cut a branch, baseline bun testdetect-cocos-project.cjs (t1k-cocos-base-knowledge-sweep); branch per theonekit-core/.claude/modules/t1k-base/rules/branch-discipline.mdproject detected; suite green BEFORE the first edit and temp/declarations + temp/tsconfig.cocos.json present
1Baseline measure, --json to scratchpadreuse-coverage.cjs (t1k-cocos-playable-reuse-coverage)templateBaseline: available, --index passed explicitly
2Discover what is adoptableenumerate-subsystems.cjs (t1k-cocos-playable-modularize-reuse-scan), CPM registry, t1k-cocos-base-knowledge-sweep corpus sweepREUSE / EXTEND / KEEP per subsystem, plus vendored-but-unimported flagged as a first-class finding
3Vendorinstall-package.cjs (t1k-cocos-playable-modularize-refactor)package present on disk, verified against the re-read package.json; the wipe’s preservedGateInputs names temp/tsconfig.cocos.json + temp/declarations as surviving
4Register playableSync and peers BY HANDmanual, from each package README ## Requiresevery peer present — the installer copies exactly one directory and resolves no transitive dependency
5Repoint importst1k-cocos-base-developerverify-imports.cjs (t1k-cocos-playable-modularize-refactor) resolves: unresolvedImports: 0 and directorySpecifiers: 0
6Reachability, BEFORE any deletionverify-reachability.cjs (t1k-cocos-playable-modularize-reuse-scan)ORPHAN only when all four checks are empty; UNKNOWN never degrades to ORPHAN
7Retire, one commit per fileretire-consumed.cjs --apply (t1k-cocos-playable-modularize-refactor)suite still green; git revert <sha> printed
8Re-measure and report to stdoutreuse-coverage.cjs (t1k-cocos-playable-reuse-coverage)figures quoted only with the templateBaseline state attached
9Verifybun test, source-scan-guard.cjs (t1k-cocos-base-source-scan-guard), optionally t1k-gamedev-playable-preview-verifytest count must not shrink

Stage 2’s REUSE/EXTEND/KEEP verdicts follow rules/knowledge-sweep-cocos.md — the verdict line format and the corpus-first discipline are that rule’s, not restated here. EXTEND means the local copy diverged ahead of the published package (enumerate-subsystems.cjs flags this offline, before any corpus query): swapping it for the vendored version there would delete the improvement, so EXTEND routes to t1k-cocos-base-stdlib-contribute, not to this skill’s vendor step.

A first-class mode: runs stage 0, stage 1, and stage 8’s reporting shape, nothing else. This is the “just show me the coverage” path, and it touches no file in the repo at all — not even a branch cut, since stage 0’s branch step is skipped along with everything past stage 1.

Mechanics that broke a real run — read references/mechanics.md before stages 3-7

Section titled “Mechanics that broke a real run — read references/mechanics.md before stages 3-7”

Six load-bearing details: the db:// specifier must name an explicit file, never a directory — prose until #1054, now a directorySpecifiers count that fails verify-imports.cjs in the same pass that writes it, because the Vitest prefix alias resolves both forms and green tests prove nothing; the cache wipe deletes temp/ and takes the project’s temp/tsconfig.cocos.json and temp/declarations with it unless preserved — which they now are, and the sibling-temp/ reconstruction this replaces once produced a false PASS, so never reconstruct from another project; the vitest alias must be narrow, never a blanket @playablelabs/*; install-package.cjs is an upgrade guard that refuses an already-vendored package; the adopt → deprecate → retire triad is one commit per step; retire runs with no per-deletion human prompt by design, on a branch, one file at a time; and a top-level tests/ tree (not colocated .tests/) can be a deliberate choice this skill must not “fix”. Full text: references/mechanics.md.

The four-layer gameplay gate — all four required, first three not sufficient on their own

Section titled “The four-layer gameplay gate — all four required, first three not sufficient on their own”
  1. Vitest suite green and not shrunk (stage 9).
  2. Characterization goldens replay identical (t1k-cocos-playable-characterization) when the repointed subsystem has goldens recorded.
  3. Headless runtime verify on the packaged build (t1k-gamedev-playable-preview-verify): zero console errors, CTA fires, diffPercent against baseline.
  4. Human playtest of the before/after builds. A real stop — the autonomy contract above does not reach it.

A retire that only satisfies (1) is not done. Report which of (2)/(3) ran and which did not, rather than silently treating (1) as sufficient.

Measured constants this skill must not re-derive

Section titled “Measured constants this skill must not re-derive”
  • Coverage’s numerator counts the vendored package’s size, not the volume of local code retired. Retire moves the denominator, not the ratio — measured 3.29% → 3.32% across a 3-file retire. Never promise a coverage jump from a retire pass; promise the first non-zero reading and the count of duplicated copies removed.
  • --index resolves relative to CWD when omitted, silently reclassifying template-inherited files and moving the denominator. Always pass --index explicitly, and confirm templateBaseline: available (not partial/unavailable) before quoting any figure or delta — partial/unavailable means project is an upper bound and coverage a lower bound; say so.
  • cocos-stdlib’s main carries no required_status_checks, so gh pr merge --auto would merge with ci still pending. This skill is a consumer, not a publisher — it never opens a PR against cocos-stdlib — but if a stage-2 sweep surfaces a package that needs a fix upstream first, route that to t1k-cocos-base-stdlib-contribute, which owns that PR’s merge discipline, rather than working around the gap here.
  • t1k-cocos-playable-stdlib-harvest — the producing half of this lane. Its S15 hands over an adopt-plan.cjs plan (--run <harvest-run.json> --package <pkg> --project <source-repo-root>), and brief.argumentHint/brief.packages are what this skill takes as its own invocation. Read that plan before stage 1: it states which files are repoint targets, which are retireable and which must STAY, and the peer ranges the project does not yet declare.
  • references/mechanics.md — the six load-bearing mechanics above, in full: db:// specifier shape, the narrow vitest alias, the install-package.cjs upgrade-guard refusal, the commit triad, the no-prompt retire’s mechanical replacement, and the tests/ vs .tests/ read.
  • t1k-cocos-playable-modularize-refactor — owns install-package.cjs, verify-imports.cjs, retire-consumed.cjs; read its own docs before assuming a flag this skill did not name.
  • t1k-cocos-playable-modularize-reuse-scan — owns enumerate-subsystems.cjs, verify-reachability.cjs.
  • t1k-cocos-playable-reuse-coverage — owns reuse-coverage.cjs, adoption.cjs, the four-bucket model, --verdict mode.
  • t1k-cocos-base-knowledge-sweep — owns detect-cocos-project.cjs, the corpus-first sweep stage 2 runs before naming a subsystem REUSE/EXTEND/KEEP.
  • t1k-cocos-playable-characterization, t1k-gamedev-playable-preview-verify — layers 2 and 3 of the four-layer gate.
  • t1k-cocos-base-stdlib-contribute — where an EXTEND verdict or an upstream-fix-first finding from stage 2 routes; this skill never packages or publishes.
  • rules/knowledge-sweep-cocos.md — the REUSE/EXTEND/KEEP verdict discipline stage 2 follows.