Skip to content

t1k:cocos:base:stdlib-contribute

FieldValue
Modulebase
Version4.51.9
Effortmedium
Tools—

Keywords: auto-triage, cocos-stdlib, contribute package, core-, corpus-scout, decouple package, feature-, from-queue, layered dependency law, mechanic-, package granularity, peerDependencies, playablelabs package, port injection, review step, sdk-, stdlib candidates

/t1k:cocos:base:stdlib-contribute
<file.ts> [--symbol <Name>] [--package <name>] | --from-queue

Packages one standalone Cocos capability out of a project and into The1Studio/cocos-stdlib — a pnpm-workspace monorepo of independently-installable @playablelabs/* packages, published via CPM (https://cpm.playablelabs.ai).

This skill decides whether and how a capability may be packaged (Steps 0-2) — the accepted candidate goes to t1k-cocos-playable-stdlib-contributor, which owns Steps 3-10.

Two entry points. The interactive one takes a <file.ts>; --from-queue takes a batch the auto-triage lane already detected and triaged (references/auto-triage.md). Both converge at Step 2.

stdlibContribute.mode decides whether --from-queue asks. The kit default (auto) spawns this skill’s --from-queue entry in the background without asking when [t1k:stdlib-candidates … mode=auto] fires — the flag is the standing approval, never re-asked. The flow stops at “PR opened; cocos-stdlib auto-merge.yml merges it on a green ci” and returns the PR URL(s); it never runs gh pr merge (never --auto: the stdlib ruleset has no required_status_checks), never publishes to CPM by hand, never seeds a first-release tag. Values, env override (T1K_STDLIB_CONTRIBUTE), project override, frame reaction: references/stdlib-contribute-setting.md; version-bump and first-release rules: t1k-cocos-playable-modularize/references/shared-cpm-facts.md. Registry token, publish-scope, size-limit and 401/403 questions belong to the t1k:registry skill (theonekit-core); this skill restates none of them.

The law this skill exists to enforce — the dependency layer

Section titled “The law this skill exists to enforce — the dependency layer”

Dependencies run one way, downhill, and a package’s label says which layer it sits at (CONTRIBUTING.md § “Naming and layers”):

LayerMay importMay be imported by
core-*nothingfeature-*, mechanic-*, sdk-*, cc-*
feature-* / mechanic-* / sdk-*core-* onlycc-* only — no package may import a feature, mechanic, or sdk package
cc-*core-*/feature-*/mechanic-*/sdk-* public files, and ccnothing — not a lower layer, not another cc-*, not a consumer

cc-* is the top of the stack, the only layer that may name cc, and its test is coupling rather than role (DESIGN.md §4.1). A cc candidate arrives as lane: cc from S6a of t1k-cocos-playable-stdlib-harvest — same skill, one extra label, a different verify: references/cc-layer-scaffold.md.

Exactly one import form is legal, and it is narrow:

packages/feature-x/src/UsesCounter.ts
import { Counter } from '../../core-y/src/index';
  • Sibling-relative, to the barrel — never a *.core* path. Never a bare @playablelabs/core-y, never workspace:*, never db://.
  • Pair every such import with a peerDependencies entry. A dependencies entry stays forbidden.
  • Directory basename == package name without the scope.

Single-instance runtime services still travel by port (signal bus, audio, object pool): never through an import. bun scripts/deps-check.mjs --strict enforces the layer rule in CI; why each prohibited form breaks: references/dependency-layer.md.

Scope — code only, not a repo-wide rule. This skill packages .ts source plus the .meta sidecar Cocos’s asset-db requires — nothing else. A candidate that cannot function without a .prefab/.png/.effect/audio asset is reported and stopped, never silently stripped or carried. That is this skill’s footprint, not an architecture rule of the repo — a package may ship an asset (references/scope-and-granularity.md).

Test: does the candidate have state (this. reads/writes outside the constructor), a collaborator (calls another class/service), or a lifecycle (onLoad/onDestroy/update, or anything constructed-then-torn-down)?

  • Yes to any → a new package in cocos-stdlib (a class, not a bare function) — continue.
  • No to all → check whether an existing package already owns this concern closely enough to extend (same domain, narrow addition); still continue, to confirm via the sweep.

This is a classification gate, not a rejection gate — every candidate proceeds to Step 1 labelled “new package” or “extend <existing-package>”. Nothing is dropped silently.

Granularity — the unit of packaging is one capability a game feature would name. The signal-to-verdict table and the layer-label rules: references/step-detail.md § “Step 0 — granularity”.

Pass/fail: an explicit label (new-package or extend:<package-name>) and a layer label before Step 1 runs, plus a one-line granularity justification.

Three prior-art sources, all mandatory — the corpus “does this exist anywhere in the studio?”, installed packages “is it already on this disk, paid for, possibly un-wired?”, and the kit’s own skills “did we write this down?”.

Harvest flow: the corpus is already swept — cite the run’s evidence/knowledge-sweep.json entry, never a re-sweep; the other two sources still run; a missing entry is unverified, never NEW (references/harvest-mode.md § Step 1).

Spawn t1k-corpus-scout (a core agent, sonnet) for the sweep. Its brief (portability gate first, scoped knowledge-sweep queries, all three sources) is in references/step-detail.md § “Step 1 — scout brief”. The return line is byte-exact: candidate: <id> verdict: <REUSE|EXTEND|NEW|SKIP|unverified> target: <pkg/path#symbol or -> why: <one line> plus its own reuse-search: / scope: lines.

If the scout returns corpus-unavailable, run one inline fallback through t1k-cocos-base-knowledge-sweep; if that also cannot reach the corpus, the verdict is unverified — never NEW.

VerdictMeaningRecord
REUSEAn existing package (installed or corpus) already covers thisName it and the path/symbol. Stop — report the reuse target; package nothing
EXTENDA close but not identical package inside the cocos-stdlib packages/ workspace should absorb thisName the package (its core-*/feature-*/mechanic-*/sdk-* directory). Continue as an addition to it. Preferred whenever available — cheaper than a new package, no new install line
NEWNothing — corpus or installed — is closeContinue as a new package. Must carry reuse-search: not-found-after-corpus-and-grep + scope: / swept:. Exception: a NEW verdict backed by a project-source hit carries that hit in target:/why: instead — do not write the not-found line (#527, contribute-back.md:60-61)
SKIPNot a library candidate — project-specific code a second game would edit, not configure (GameplayConfig, LevelData.validateAndRepair)One-line why:. Stop — nothing to package, and no sweep was run, so no reuse-search: / scope: lines

EXTEND is cocos-stdlib-workspace-only — a game-foundation/project-source hit verdicts REUSE/NEW instead (Steps 3-10 can only PR into cocos-stdlib; PLAGameFoundation’s default branch is develop, not main). Rationale: references/scope-and-granularity.md.

Duplicated code across packages is forbidden. If the sweep finds the capability already implemented in an installed cocos-stdlib package, the verdict is REUSE/EXTEND even when the candidate’s version is nicer — a second implementation is not an improvement.

Pass/fail: a verdict with its required evidence recorded before Step 2 runs; a REUSE verdict ends the skill here (references/scope-and-granularity.md).

Pick the directory name (mechanic-<name>, feature-<name>, core-<name>, sdk-<name>, cc-<name>) and confirm the scope. The label is the layer, so it decides what the package may import, and the directory basename must equal the package name without the scope. Step 2.5 runs before the handoff (below); once it passes, hand off to t1k-cocos-playable-stdlib-contributor in the same turn, carrying: the source file + symbol, the Step 0 label (scope and layer), the Step 1 verdict + evidence, and the chosen package name/label.

Pass/fail: the agent is spawned with all four items above present in its brief.

Step 2.5 — Dedupe against the capability index (mandatory)

Section titled “Step 2.5 — Dedupe against the capability index (mandatory)”

A semantic sweep (Step 1) can still miss an exact match (SortingManager vs. @playablelabs/ core-depth-sort, BlockFader vs. @playablelabs/cc-mesh-fade). Before the Step 2 handoff, run the mechanical check against the CI-published capability index (plans/260924-game-library-flywheel/capability-index-contract.md):

Terminal window
bun scripts/dedupe-against-index.cjs --name <chosen-package-name> --tags <candidate-tag,list> \
[--symbols <ExportedClass,AnotherClass>] [--index <path-to-capability-index.json>]
  • Exit 3 (duplicate-of: <package>) → stop — the handoff does not happen. Either accept the named package as the Step 1 REUSE/EXTEND target, or re-run with --allow-duplicate "<reason>" (exit 0, duplicate-override: <package> — <reason>) when the candidate is a deliberate, tracked divergence.
  • Exit 0 with ok: no duplicate found or index: unavailable → proceed to the handoff. An unavailable index is never a failure — Step 1’s corpus sweep is the guard in that case.

Pass/fail: the command ran and its exit code is recorded; a 3 without an --allow-duplicate re-run blocks the handoff.

Strip every project-specific token. Apply the theonekit-core/.claude/skills/t1k-lib-contribute/references/pass-test.md five-part pass-test: domain-neutral, data-driven, tested, charter-conformant, documented. The extraction is finished when a second project can adopt it by configuration alone — config object with defaults, injectable strategies/hooks, callbacks for observable outcomes.

File list check (code-only): list every file the extraction will carry; if anything outside .ts + its own .meta appears, stop and report it (references/extract-decouple-scaffold.md).

4a — anything the package reaches into becomes a port. Three shapes, only two legal:

#ShapeVerdict
1Package owns and exports the signal class; the app imports it. Port is fire(signal: object).Legal
2App owns the signal class; the package only calls a plain callback.Legal — the narrowest port
3The package declares its OWN copy of a class the app has, then fires the copy.FORBIDDEN

Why #3 is forbidden: SignalBus.fire matches by constructor identity, so a copied class fails silently. Choose #1 for a package-lifecycle signal, #2 for a game-domain one. Never #3. A port too wide to write means the two sides are one concept: propose a merge. Reasoning: references/step-detail.md § “Step 4a — why #3 is forbidden”.

4b — sibling core-* imports. Per import: importer is feature-*/mechanic-*/sdk-*/cc-* (a core-* package imports nothing); target is packages/core-*/src/ and the specifier points at the barrel or another public (non-.core) file; the specifier is relative; a peerDependencies entry names that package and dependencies does not.

Pass/fail: every cross-boundary call is #1 or #2 — never #3; every sibling import is the relative-barrel form with a matching peer and no dependencies; no db:// under <package>/src/. deps-check.mjs --strict is the mechanical gate — run it, do not eyeball it. Detail: references/extract-decouple-scaffold.md.

Per CONTRIBUTING.md § “Scaffolding a package”; a cc-* package also follows references/cc-layer-scaffold.md.

  • package.json has no dependencies field (imported core-* go in peerDependencies); .tests/ is dot-prefixed and mandatory (optional only in cc-*). The README.md, module.json (regenerate on every surface change, EXTEND included), .meta and src/ checklist: references/step-detail.md § “Step 5 — scaffold checklist”.
  • TSDoc on every exported symbol, shipped in the same change — never a follow-up pass.
  • Extension points are part of the scaffold: the config/defaults surface from Step 3 appears in the public API from the first commit. Adding it later is a breaking change.

Pass/fail: .ts and .meta counts match; .tests/ exists with the leading dot (a cc-* package may omit it, never the dot); package.json has no dependencies; every imported core-* sibling is in peerDependencies. Detail: references/extract-decouple-scaffold.md.

Step 5.5 — Re-entrancy pre-flight (the author’s gate; blocking — prose does not satisfy it)

Section titled “Step 5.5 — Re-entrancy pre-flight (the author’s gate; blocking — prose does not satisfy it)”

Settle, then report: every field updated before anything is emitted; events queued and drained in one guarded pass, each re-checked against live state immediately before it fires. A re-entrancy spec, seen failing first: any package exposing a port, callback, injected hook or emitted event ships ≥1 spec calling a public method from inside a callback, asserting the sequence and not just the endpoint. Pass/fail — all four, recorded in the PR body: (a) every mutator settles all state before its first emission; (b) that spec exists and is green now; (c) it was observed RED against the un-fixed code before the fix, with the failing assertion, run output or commit SHA quoted — a bare “it would have failed” fails the gate; (d) no port/callback/hook/event → a written N/A with the reason. Both defect shapes, the probe repro, the spec shape and the seen-red order: references/re-entrancy-preflight.md.

From the cocos-stdlib workspace root. Its CI runs pnpm (pinned package.json:21, frozen-lockfile ci.yml:85); ci.yml is the authority for the step list. Exact commands, new-package checklist, re-gate after a rebase, slow specs, Windows baseline, first-release tag: references/verify-and-release.md.

Refresh against origin/main FIRST, then re-run: a red module-json on a diff that never touches it means main itself is stale; regenerate generated files, never hand-merge them (references/gotchas.md).

Check 0 first (verify-and-release.md §1b): bun run <kit>/skills/t1k-cocos-base-stdlib-contribute/scripts/verify-package-typecheck.cjs --package packages/<pkg>; exit 0 only, a failure stops the flow before the PR and the gatekeeper, exit 3 is a block, never a skip.

Preflight before any push: scripts/preflight-contribute.cjs --stdlib <clone> --package <dir-name>, exit 0 only; exit 3 means NOT VERIFIED.

Self-block on any failure. Pass/fail: every step exits 0 (Windows host: clean-origin/main baseline, Linux ci arbitrates); a finding is resolved, never merely noted. Run the workspace test script, never only the per-package filtered test — a new package’s crosswalk and module.json specs sit at the repo root under scripts/.tests/.

Before the PR opens, t1k-cocos-base-reviewer reviews the package diff in the worktree. Five criteria: GK-MANDATE, GK-PORT (port shape never #3), GK-SCAFFOLD (Step 5.5 settling rule and re-entrancy spec, seen-red evidence included), GK-TSDOC, GK-LAYER, spelled out in references/review-step.md. Blocking findings are fixed, then Step 6 is re-run in full: re-running only the failed command manufactures a green over a broken tree. 3 rounds maximum, then escalate via AskUserQuestion (theonekit-core/.claude/skills/t1k-cook/references/workflow-gates.md §4); the PR body carries the verdict and round count. Every reviewer brief carries [t1k:review --single] (references/review-step.md § “The reviewer brief”).

Verdict artifact: posted by scripts/post-gatekeeper-status.cjs after the PR opens (Step 8); the contributor agent never spawns the gatekeeper and never writes a verdict. Harvest flow: the fable gatekeeper replaces this step (references/harvest-mode.md § Step 6.5).

bun changeset (patch/minor/major) — a declaration only; the git tag is the source of truth for the published version. A core-* major bump carries its dependents in the SAME PR (peer range widened, code updated, core-* published before them) and lists them so publish order is explicit.

Branch + PR on The1Studio/cocos-stdlib. Branch name: contribute/<package>, the head pattern auto-merge.yml gates on a gatekeeper verdict (a feat/* head skips that gate). After gh pr create, run scripts/post-gatekeeper-status.cjs with the Step 6.5 verdict and the exact head sha; on EVERY contribute/* PR, draft included; report “PR opened” only when it exits 0 (references/review-step.md § “Posting the verdict”), then run scripts/require-gatekeeper-status.cjs --pr <n> --mark-ready: exit 5 (no success gatekeeper status on the live head) means the PR is NOT ready and NOT reported as opened. The body states: the Step 1 verdict + evidence, the port shape(s) chosen at Step 4 and why, every core-* peer import with its peerDependencies range (or “none”), the .meta sidecar list, the library-quality-mandate pass-test result, and the Step 6.5 review verdict. A brand-new package needs no pre-merge seed tag (publish.yml seeds it on merge: references/verify-and-release.md § 5). Open the PR ready, with no no-automerge label: a contribute PR merges itself on green ci, and that is the intended outcome. To hold, do NOT open a PR: stdlib-candidates.cjs hold keeps it queued; draft / no-automerge only if the user names it. An unverified runtime check or a self-assessed risk is never a reason to hold, state it in the PR body instead: references/hard-rules.md § Step 9.

The queue path: references/hard-rules.md § --from-queue; the setting (values, T1K_STDLIB_CONTRIBUTE override, project override, frame reaction): references/stdlib-contribute-setting.md. One behavioural fork:

modeCandidate-approval step
suggest / unsetAskUserQuestion over the report — never auto-select; approval is the boundary
autoNo ask. NEW/EXTEND candidates auto-approve; REUSE/SKIP ack dismissed with verdicts noted

Under both modes the flow stops at “PR opened; cocos-stdlib auto-merge.yml merges it on a green ci” and returns the PR URL(s) — never a gh pr merge (no --auto), never a hand-merge, a CPM publish by hand, or a seeded first-release tag (references/stdlib-contribute-setting.md HARD-GATE, contractual).

dedupe-against-index.cjs runs on t1k-data-verifier; deps-check.mjs --strict / sync-meta.mjs --check on t1k-cocos-base-tester. Scope gate, naming, decouple, extract and review stay on t1k-cocos-playable-stdlib-contributor (reasoning tier).