t1k:playablelabs:base:stdlib-contribute
| Field | Value |
|---|---|
| Module | base |
| Version | 2.29.2 |
| Effort | medium |
| Tools | — |
Keywords: check-neutral-core, contribute core package to cocos-stdlib, engine-neutral core package, extract core package from playable, playablelabs stdlib contribute, stdlibContribute, T1K_STDLIB_CONTRIBUTE
How to invoke
Section titled “How to invoke”/t1k:playablelabs:base:stdlib-contribute<file-or-dir> [--symbol <Name>] [--package core-<name>] | --from-queuestdlib-contribute: move an engine-neutral capability into cocos-stdlib
Section titled “stdlib-contribute: move an engine-neutral capability into cocos-stdlib”Packages ONE capability out of a game and into The1Studio/cocos-stdlib
(pnpm workspace of @playablelabs/* packages published to CPM). This skill decides whether and how it may be packaged
(Steps 0-2); the accepted candidate goes to the agent t1k-playablelabs-base-stdlib-contributor (Steps 3-7).
Scope is core-* only. Three/web-specific or cc-specific code is NOT contributed; it stays in the game. There is
no web-* layer and this skill does not create one. The Cocos side of this flow (cc layer, feature/mechanic/sdk
layers, harvest and auto-triage lanes) is t1k-cocos-base-stdlib-contribute in theonekit-cocos: when it is
installed, link to it for those; do not copy it. This skill is the playablelabs-engine implementation of the shared
CONTRIBUTE verdict (vocabulary: theonekit-core data/reuse-gate.json; core’s default destination is
t1k-lib-contribute, its cocos arm is the skill above) for engine-neutral core-* packages. Facts shared with the sweep (auth, CPM-only consumption,
versioning, ADD vs UPDATE): ../t1k-playablelabs-base-cpm-sweep/references/cpm-facts.md.
The law
Section titled “The law”A core-* package imports nothing: no other workspace package, no cc, no three, type-only imports included
(kit rule playablelabs-decouple-game-code.md; cocos-stdlib CONTRIBUTING.md section 3 for the layer table).
cocos-stdlib’s own gates do not enforce the three/type-only half, so Step 0 and Step 4 here do
(scripts/check-neutral-core.cjs).
Step 0: scope gate
Section titled “Step 0: scope gate”Run all of these; any “no” ends the contribution with verdict KEEP and the reason.
| # | Test | Fail means |
|---|---|---|
| 1 | The candidate’s whole closure has no cc/three import and no cc./THREE. global: bun scripts/check-neutral-core.cjs <paths> exits 0, OR the coupling is a thin seam you can cut in Step 4 (a few call sites, replaceable by plain data or a port) | engine-coupled: stays in the game |
| 2 | It needs no other stdlib package (a core-* imports nothing) | it is feature/mechanic-level: out of scope here, KEEP or use the Cocos flow |
| 3 | A second, different game would configure it, not edit it (config object with defaults, injectable strategies, callbacks) | game-specific code: KEEP |
| 4 | Code only: .ts plus the .meta sidecars stdlib needs; no .prefab/.png/.effect/audio/shader asset | report the asset dependency and stop; never strip it silently |
| 5 | Granularity: state, a collaborator or a lifecycle means its own package; a tiny stateless helper belongs in core-utils; always-installed-together halves are ONE package | label new-package or extend:<existing> |
Pass: a label (new-package / extend:<pkg>), the layer core, and a one-line granularity reason.
Step 1: sweep (mandatory)
Section titled “Step 1: sweep (mandatory)”Run t1k-playablelabs-base-cpm-sweep for the capability. Proceed only on CONTRIBUTE (ADD) or EXTEND (UPDATE).
REUSE ends here (install it); NEW and KEEP end here (nothing to contribute). unverified ends here (never contribute on an unanswered sweep). Carry the
reuse-verdict: line, with scope: and via:, into the brief and the PR body.
Step 2: name, then dedupe, then hand off
Section titled “Step 2: name, then dedupe, then hand off”Directory = package name without scope = core-<name>; scope stays @playablelabs. Then the mechanical check
against cocos-stdlib’s published capability index:
bun scripts/dedupe-against-index.cjs --name core-<name> --tags <tag,list> [--symbols <ExportedClass,...>] \ [--index <path-to-capability-index.json>] [--allow-duplicate "<reason>"]Exit 3 (duplicate-of: <pkg> (layer: <layer>)) stops the handoff: take that package as the Step 1 REUSE/EXTEND
target, or re-run with --allow-duplicate for a deliberate, tracked divergence. A cc layer duplicate is design prior
art on web, not an install. Exit 0 ok: or index: unavailable proceeds (the sweep is the guard when the index is
unreachable). Tags come from the index’s tags vocabulary (capability-index.json tags, docs/taxonomy.md).
Handoff, same turn, to t1k-playablelabs-base-stdlib-contributor, carrying: source path + symbol(s), the Step 0
label and layer, the Step 1 verdict line, the chosen package name and tags, and the resolved contribute mode
(below). The brief must also say the working copy of cocos-stdlib is a worktree off fresh origin/main.
Steps 3-7: executed by the contributor agent
Section titled “Steps 3-7: executed by the contributor agent”| Step | What | Pass condition |
|---|---|---|
| 3 Extract | strip project tokens; config object with defaults, injectable strategies, callbacks; list every file | a second project adopts it by configuration alone |
| 4 Decouple | cut every three/cc seam: plain data types ({x,y,z}, own math), ports the game wires at its composition root; see references/decouple-from-three.md | bun scripts/check-neutral-core.cjs packages/core-<name> exits 0 |
| 5 Scaffold | per cocos-stdlib CONTRIBUTING.md section 4: package.json (no dependencies, devDependencies.typescript, publishConfig.registry), README with ## Requires (None.), src/*.ts + .meta, dot-prefixed .tests/, TSDoc on every export, module.json, commit pnpm-lock.yaml | stdlib’s own CI list passes locally |
| 6 Verify | in the stdlib checkout, with ITS tooling (the packageManager its package.json pins), run the whole CONTRIBUTING.md section 6 list, refreshed onto origin/main first: the typecheck AND typecheck:all scripts, lint, test (workspace, not filtered), the scripts/deps-check.mjs --strict, scripts/sync-meta.mjs --check and scripts/check-release-tags.mjs checks, plus module-json:check and harvest:check | all exit 0, quoted |
| 7 Changeset + PR | pnpm changeset; PR on The1Studio/cocos-stdlib (base per the stdlib’s default branch) with the verdict line, the neutral-core output, the test results | PR URL returned |
The Cocos skill’s Steps 5.5 (re-entrancy pre-flight) and 6.5 (independent review against five criteria) are worth
running for any package exposing a port, callback or event; they live in t1k-cocos-base-stdlib-contribute and are
not restated. Without theonekit-cocos, have the spawner arrange a read-only review of the package diff before the PR.
--from-queue: contribute a triaged batch
Section titled “--from-queue: contribute a triaged batch”The candidate queue is core’s detector state (~/.claude/session-state/stdlib-candidates, written by the
theonekit-cocos detector CLI; a Stop hook in theonekit-core triages it and, under stdlibContribute.mode=auto,
asks the session to start THIS entry NOW via a [t1k:stdlib-candidates ... action=start] frame). This kit adds no
detector and no hook; it only consumes the queue. The frame names the Project: root and the CLI’s own report/ack
commands; use those, do not spell them.
reportfor the project (triaged-unacked candidates, each with the scout’s verdict).- Per
NEW/EXTENDcandidate run Step 0 (neutral-core scope gate), Step 1 (t1k-playablelabs-base-cpm-sweep, or reuse the triage evidence when swept <= 7 days ago) and Step 2 (name, dedupe). A candidate that fails Step 0 or sweeps toREUSE/KEEP/unverifiedis ackeddismissedwith the verdict and reason; it is never contributed. mode=auto: no ask, the passing candidates are the approval (ack ... --decision approved).mode=suggest/unset:AskUserQuestionover the report first.- Hand the approved candidates to
t1k-playablelabs-base-stdlib-contributorin the same turn (Step 2 handoff), then Steps 3-7.
A project on stdlibContribute.holdProjects is never started by the trigger; an explicit user request for it still runs.
The flow stops where Steps 3-7 stop: PR opened, gatekeeper verdict on record (Hard gates), nothing merged.
Hard gates
Section titled “Hard gates”- The flow stops at “PR opened; the orchestrator merges after an observed green
ci”. Never hand-merge, never admin-merge, and nevergh pr merge, with or without--auto: the cocos-stdlib ruleset has norequired_status_checks, so--automerges at once withcistill pending (cocos-stdlib#30). - cocos-stdlib PRs self-merge: its
auto-merge.ymlsquash-merges a PR whencicompletes green, unless the PR is a draft or carries theno-automergelabel. Open the PR ready, with nono-automergelabel; hold it (draft or--label no-automerge) ONLY on an explicit user or command instruction to hold, never on your own judgment (cocos-stdlib#536/#537, #548 and #608 sat draft indefinitely because nothing promoted them). A real human decision (new-package seed tag, peer-range question) is put to the user withAskUserQuestionby the orchestrator, or stated in the PR body under “Not verified”; it does not auto-hold the PR. The contributor’scontribute/*heads are also refused byauto-merge.ymlwithout a gatekeeper APPROVE for the exact head sha (commit statusgatekeeper, or an owner/member commentgatekeeper: APPROVE <sha>); say so in the PR body when the verdict is not yet on record. Same wording ast1k-cocos-base-stdlib-contribute(theonekit-cocos) Step 9; revisit if the ruleset ever gains required checks. - Gatekeeper guarantee. A
contribute/*PR is reported “opened” (and a held draft is taken out of draft) ONLY after thegatekeepercommit status issuccesson the live head sha. Withtheonekit-cocosinstalled, post it with that kit’st1k-cocos-base-stdlib-contribute/scripts/post-gatekeeper-status.cjsand verify/ready it with.../scripts/require-gatekeeper-status.cjs --pr <n> --mark-ready(exit 5 = no verdict, not ready). Without it, the PR stays a draft and the report saysgatekeeper: missing, loudly; never post the status or comment by hand. - Never publish to CPM by hand, never
npm publish, never push or seed a release tag, never hand-editversion. If a tag is needed, the PR body carries the commands and names a maintainer. - Never write to the game from here without the adopt step’s order: publish first, verify the version on CPM
(
bun info @playablelabs/core-<name> version --registry=https://cpm.playablelabs.ai), then swap the game’s local copy for the installed package. A registry that is unreachable (401/502) stops the adopt step and is reported. - Do not touch
PlaybleEngine,PlayableLabsorParamToolfrom this skill.
Same as the Cocos kit, and what differs
Section titled “Same as the Cocos kit, and what differs”Same: the verdict words and fields (REUSE|EXTEND|NEW|CONTRIBUTE|KEEP|unverified; NEW needs scope:, KEEP needs
reason: >= 20 chars and index:; SSOT core data/reuse-gate.json, table in cpm-facts.md “Verdict vocabulary”),
the destination (an engine-free core-* package in The1Studio/cocos-stdlib), the PR rules above, and the mode switch.
Different: no playableSync, no assets/packages/, no Cocos assemblies (the sweep scope is CPM plus the corpus); no
detector hook of its own (the queue is core’s and the Cocos kit’s; this kit consumes it through --from-queue), so a
web/none candidate still enters through the sweep or by hand; scope is core-* only. Not doable
from a playablelabs-only project: the .tests/ and typecheck:all gates need a cocos-stdlib checkout and its pnpm
toolchain, and the Step 6.5 review needs theonekit-cocos; the contributor works in a stdlib worktree instead.
Mode: how automatic is it?
Section titled “Mode: how automatic is it?”T1K_STDLIB_CONTRIBUTE=off|suggest|auto and the config key stdlibContribute.mode: the SAME setting
theonekit-cocos owns, so one switch governs both kits. Resolution, meaning of each value, and why this kit ships no
key of its own: references/auto-contribute-setting.md.
Executed by
Section titled “Executed by”Running the two scripts is mechanical; deciding scope, ports and the verdict is judgment. Routing SSOT:
rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run dedupe-against-index.cjs and check-neutral-core.cjs, report exit codes and output verbatim | t1k-data-verifier |
| Steps 0-2 scope gate and verdict; Steps 3-7 extract, decouple, scaffold, verify, PR | t1k-playablelabs-base-stdlib-contributor (reasoning tier) |
Hard rules
Section titled “Hard rules”- A green stdlib CI does not prove neutrality: an erased
import type ... from 'three'passes everything. Runcheck-neutral-core.cjsyourself and quote it. wiring.importin the capability index is the Cocosdb://assets/packages/...form; do not paste it into a web game.- Do not copy a package’s source into the game to “keep going” while the PR is open. CPM-only consumption holds
(
cpm-facts.md); a game keeps its local copy until the published version is installed. - Published stdlib packages ship readable
src/*.ts; do not scaffold anything minified orobfuscate-flagged. - The
.tests/directory is dot-prefixed on purpose (Cocos asset-db skips dot dirs); a plaintests/ships in the bundle. - Scripts here are
.cjsand run underbun; the stdlib workspace has its own toolchain (pnpm), which is that repo’s business, not a violation of this kit’s Bun-only rule for its own workflows.