t1k:cocos:playable:stdlib-adopt
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| 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
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:stdlib-adopt[<project-root>] [--scope <glob>] [--index <clone-index-dir>] [--packages <a,b,c>] [--measure-only]stdlib-adopt
Section titled “stdlib-adopt”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
--jsonto a path outside the project, in the session scratchpad (e.g.--json "$SCRATCH/coverage-$(date +%s).json"). Never let--jsondefault — 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.cjspatches anyreports/reuse-coverage*.jsonalready present in the project, in place, and auto-includes it in its own commit (it walks<project>/reports/forreuse-coverage*.jsonand rewrites the candidate’s row out of every hit it finds). Two lanes that both left a report inreports/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 racetheonekit-core/.claude/modules/t1k-parallel/rules/parallel-teammate-git-index-race.mdwarns about, produced here by a script rather than bygit add -A. Keeping the file out of the repo removes the hazard instead of working around it. --verdictmode is the one exception worth naming. It already re-spawns the parent script against its own throwaway temp path internally, so it never touchesreports/— 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.cjsprints 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-runreuse-coverage.cjs— and substitute a scratchpad path for the one it suggests.
The autonomy contract
Section titled “The autonomy contract”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 publishof 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.
Stage table
Section titled “Stage table”| # | stage | owned by | gate |
|---|---|---|---|
| 0 | Preflight — detect Cocos project, resolve scope, cut a branch, baseline bun test | detect-cocos-project.cjs (t1k-cocos-base-knowledge-sweep); branch per theonekit-core/.claude/modules/t1k-base/rules/branch-discipline.md | project detected; suite green BEFORE the first edit and temp/declarations + temp/tsconfig.cocos.json present |
| 1 | Baseline measure, --json to scratchpad | reuse-coverage.cjs (t1k-cocos-playable-reuse-coverage) | templateBaseline: available, --index passed explicitly |
| 2 | Discover what is adoptable | enumerate-subsystems.cjs (t1k-cocos-playable-modularize-reuse-scan), CPM registry, t1k-cocos-base-knowledge-sweep corpus sweep | REUSE / EXTEND / KEEP per subsystem, plus vendored-but-unimported flagged as a first-class finding |
| 3 | Vendor | install-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 |
| 4 | Register playableSync and peers BY HAND | manual, from each package README ## Requires | every peer present — the installer copies exactly one directory and resolves no transitive dependency |
| 5 | Repoint imports | t1k-cocos-base-developer | verify-imports.cjs (t1k-cocos-playable-modularize-refactor) resolves: unresolvedImports: 0 and directorySpecifiers: 0 |
| 6 | Reachability, BEFORE any deletion | verify-reachability.cjs (t1k-cocos-playable-modularize-reuse-scan) | ORPHAN only when all four checks are empty; UNKNOWN never degrades to ORPHAN |
| 7 | Retire, one commit per file | retire-consumed.cjs --apply (t1k-cocos-playable-modularize-refactor) | suite still green; git revert <sha> printed |
| 8 | Re-measure and report to stdout | reuse-coverage.cjs (t1k-cocos-playable-reuse-coverage) | figures quoted only with the templateBaseline state attached |
| 9 | Verify | bun test, source-scan-guard.cjs (t1k-cocos-base-source-scan-guard), optionally t1k-gamedev-playable-preview-verify | test 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.
--measure-only
Section titled “--measure-only”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”- Vitest suite green and not shrunk (stage 9).
- Characterization goldens replay identical (
t1k-cocos-playable-characterization) when the repointed subsystem has goldens recorded. - Headless runtime verify on the packaged build (
t1k-gamedev-playable-preview-verify): zero console errors, CTA fires,diffPercentagainst baseline. - 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.
--indexresolves relative to CWD when omitted, silently reclassifying template-inherited files and moving the denominator. Always pass--indexexplicitly, and confirmtemplateBaseline: available(notpartial/unavailable) before quoting any figure or delta —partial/unavailablemeansprojectis an upper bound andcoveragea lower bound; say so.cocos-stdlib’smaincarries norequired_status_checks, sogh pr merge --autowould merge withcistill pending. This skill is a consumer, not a publisher — it never opens a PR againstcocos-stdlib— but if a stage-2 sweep surfaces a package that needs a fix upstream first, route that tot1k-cocos-base-stdlib-contribute, which owns that PR’s merge discipline, rather than working around the gap here.
Related
Section titled “Related”t1k-cocos-playable-stdlib-harvest— the producing half of this lane. Its S15 hands over anadopt-plan.cjsplan (--run <harvest-run.json> --package <pkg> --project <source-repo-root>), andbrief.argumentHint/brief.packagesare 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, theinstall-package.cjsupgrade-guard refusal, the commit triad, the no-prompt retire’s mechanical replacement, and thetests/vs.tests/read.t1k-cocos-playable-modularize-refactor— ownsinstall-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— ownsenumerate-subsystems.cjs,verify-reachability.cjs.t1k-cocos-playable-reuse-coverage— ownsreuse-coverage.cjs,adoption.cjs, the four-bucket model,--verdictmode.t1k-cocos-base-knowledge-sweep— ownsdetect-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 anEXTENDverdict 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.