Skip to content

t1k:playablelabs:base:stdlib-contribute

FieldValue
Modulebase
Version2.29.2
Effortmedium
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

/t1k:playablelabs:base:stdlib-contribute
<file-or-dir> [--symbol <Name>] [--package core-<name>] | --from-queue

stdlib-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.

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).

Run all of these; any “no” ends the contribution with verdict KEEP and the reason.

#TestFail means
1The 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
2It needs no other stdlib package (a core-* imports nothing)it is feature/mechanic-level: out of scope here, KEEP or use the Cocos flow
3A second, different game would configure it, not edit it (config object with defaults, injectable strategies, callbacks)game-specific code: KEEP
4Code only: .ts plus the .meta sidecars stdlib needs; no .prefab/.png/.effect/audio/shader assetreport the asset dependency and stop; never strip it silently
5Granularity: state, a collaborator or a lifecycle means its own package; a tiny stateless helper belongs in core-utils; always-installed-together halves are ONE packagelabel new-package or extend:<existing>

Pass: a label (new-package / extend:<pkg>), the layer core, and a one-line granularity reason.

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.

Directory = package name without scope = core-<name>; scope stays @playablelabs. Then the mechanical check against cocos-stdlib’s published capability index:

Terminal window
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”
StepWhatPass condition
3 Extractstrip project tokens; config object with defaults, injectable strategies, callbacks; list every filea second project adopts it by configuration alone
4 Decouplecut 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.mdbun scripts/check-neutral-core.cjs packages/core-<name> exits 0
5 Scaffoldper 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.yamlstdlib’s own CI list passes locally
6 Verifyin 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:checkall exit 0, quoted
7 Changeset + PRpnpm changeset; PR on The1Studio/cocos-stdlib (base per the stdlib’s default branch) with the verdict line, the neutral-core output, the test resultsPR 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.

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.

  1. report for the project (triaged-unacked candidates, each with the scout’s verdict).
  2. Per NEW/EXTEND candidate 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 to REUSE/KEEP/unverified is acked dismissed with the verdict and reason; it is never contributed.
  3. mode=auto: no ask, the passing candidates are the approval (ack ... --decision approved). mode=suggest/unset: AskUserQuestion over the report first.
  4. Hand the approved candidates to t1k-playablelabs-base-stdlib-contributor in 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.

(contractual, not a judgment call)

  • The flow stops at “PR opened; the orchestrator merges after an observed green ci”. Never hand-merge, never admin-merge, and never gh pr merge, with or without --auto: the cocos-stdlib ruleset has no required_status_checks, so --auto merges at once with ci still pending (cocos-stdlib#30).
  • cocos-stdlib PRs self-merge: its auto-merge.yml squash-merges a PR when ci completes green, unless the PR is a draft or carries the no-automerge label. Open the PR ready, with no no-automerge label; 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 with AskUserQuestion by the orchestrator, or stated in the PR body under “Not verified”; it does not auto-hold the PR. The contributor’s contribute/* heads are also refused by auto-merge.yml without a gatekeeper APPROVE for the exact head sha (commit status gatekeeper, or an owner/member comment gatekeeper: APPROVE <sha>); say so in the PR body when the verdict is not yet on record. Same wording as t1k-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 the gatekeeper commit status is success on the live head sha. With theonekit-cocos installed, post it with that kit’s t1k-cocos-base-stdlib-contribute/scripts/post-gatekeeper-status.cjs and 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 says gatekeeper: 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-edit version. 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, PlayableLabs or ParamTool from this skill.

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.

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.

Running the two scripts is mechanical; deciding scope, ports and the verdict is judgment. Routing SSOT: rules/orchestration-rules.md § “Task-Type → Agent Routing”.

StepAgent
Run dedupe-against-index.cjs and check-neutral-core.cjs, report exit codes and output verbatimt1k-data-verifier
Steps 0-2 scope gate and verdict; Steps 3-7 extract, decouple, scaffold, verify, PRt1k-playablelabs-base-stdlib-contributor (reasoning tier)
  • A green stdlib CI does not prove neutrality: an erased import type ... from 'three' passes everything. Run check-neutral-core.cjs yourself and quote it.
  • wiring.import in the capability index is the Cocos db://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 or obfuscate-flagged.
  • The .tests/ directory is dot-prefixed on purpose (Cocos asset-db skips dot dirs); a plain tests/ ships in the bundle.
  • Scripts here are .cjs and run under bun; 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.