t1k:cocos:playable:stdlib-autocontribute
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: auto contribute stdlib, contribute all packages, refactor and contribute, refactor rồi contribute, stdlib-autocontribute, tự động contribute, tự động đóng gói lên stdlib
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:stdlib-autocontribute[<project-root>] [--scope <glob>] [--index <clone-index-dir>] [--stop-after <stage>] [--max-packages N]stdlib-autocontribute
Section titled “stdlib-autocontribute”One autonomous lane, 13 stages (0-12), over a single PLA project’s assets/scripts/** only —
never assets/packages/ (a sync mirror of published output, not source), never scenes, prefabs or
other assets. It audits, fixes, relocates and decomposes what is packageable, reviews each
candidate with a fable gatekeeper, contributes the approved ones into
The1Studio/cocos-stdlib, and re-measures.
The default run is ALL stages 0-12 back-to-back with no mid-run halts. The only point the user
is asked is the terminal acceptance handoff after Stage 12: before/after packaged builds plus the
final acceptance report — one playtest, at the end.
Adopting already-published packages onto this same project is a different skill —
t1k-cocos-playable-stdlib-adopt. This lane finds and ships NEW packages; that one wires EXISTING
ones back in. Stage 4 hands work to it explicitly (below).
Why this is a thin orchestrator, not a new pipeline
Section titled “Why this is a thin orchestrator, not a new pipeline”Every mechanic this lane needs already exists as a skill; what was missing is a mode that runs
them back-to-back without each one’s own AskUserQuestion — t1k-cocos-playable-modularize chains
audit → reuse → refactor → contribute, but is documentation-only, every --apply gated on a
question; t1k-cocos-base-stdlib-contribute owns Steps 0-10 (scope gate → decouple → scaffold
→ verify → review → PR → publish); t1k-cocos-playable-reuse-coverage owns the reuse-coverage.cjs
/ adoption.cjs measurement; t1k-cocos-playable-characterization owns the golden-master
equivalence gate. This body cites the skill that owns a step; it never re-explains how that
skill’s script works.
Autonomy contract
Section titled “Autonomy contract”Autonomous — decide and proceed, never ask: package name and layer label, port/interface shape, folder placement, which of several fix shapes to apply, extraction granularity, commit message wording, REUSE/EXTEND/KEEP/CONTRIBUTE verdict, vitest alias placement, retire ordering, per-file deletion during retire.
Retained hard limits — the autonomy grant does not reach these, and every one is skip-and-record, never a halt. Mid-run the item is simply not performed: it is recorded under the final report’s “needs human” section and the run continues. The one abort is “this is not a Cocos project” — nothing else stops the lane:
- Scope breach → skip that item. A write outside
assets/scripts/**(neverassets/packages/;package.json/vitest.config.tsbelong tot1k-cocos-playable-stdlib-adopt) is skipped — with ONE exception, the Stage-0 Vitest bootstrap below, the lane’s single sanctioned write to them. Any other write to either file is still skip-and-record. bun publish→ never, and never a stop for it. Each package ends at “PR merged”; the final report lists merged packages awaiting publish as a handoff item.- Gameplay-gate failure (layers 1-3, below) → revert that change. The change is reverted, the failure recorded in the final report, and the lane continues with what still passes.
- Gatekeeper REJECT / 3rd REVISE → drop that candidate (Stage 10, below) — recorded, run continues.
- Never-offload set → skip, never perform (
theonekit-core/.claude/modules/t1k-orchestration/rules/off-scope-finding-offload.md): destructive ops, credentials, permission/config changes. Mid-run such an item is skipped and recorded under “needs human”; the run continues — at Preflight it is simply not reached. - Never merge non-green; never
--autoon cocos-stdlib — a red check never converts into a merge; see the Stage-11 red-CI loop.
A retained limit is never silently downgraded to a “decide and proceed” item: a skip carries its reason, a revert the failing layer, and the terminal handoff is the only ask.
Measured constants — do not re-derive
Section titled “Measured constants — do not re-derive”Extraction expansion runs 1.14x-1.26x codeLines; size a slate at 1.20x. A suspiciously HIGH
ratio is a defect signal, not a win, and it has a counterpart: never ship a fragment — both
directions in references/measured-constants.md, together with
the --index / templateBaseline reporting rules and the coverage-numerator caveat.
The four-layer gameplay gate
Section titled “The four-layer gameplay gate”Layers 1-3 gate every change automatically in the lane (no ask); layer 4 is the terminal acceptance step, not a mid-run stop:
- Vitest suite green and not shrunk.
- Characterization goldens replay identical —
t1k-cocos-playable-characterization. - 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 — terminal, once, at the end. Nothing in this lane substitutes for it (see Final acceptance report, below).
Stage table
Section titled “Stage table”| # | Stage | Owned by | Gate |
|---|---|---|---|
| 0 | Preflight — detect Cocos project, settle the two preconditions below (Vitest bootstrap, checkpoints anchor), 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; Vitest harness present (bootstrapped if absent); checkpoints anchor present; suite green BEFORE anything moves |
| 1 | Baseline measure | t1k-cocos-playable-reuse-coverage | templateBaseline: available confirmed, --index explicit, --json to session-scratchpad (no in-repo files) |
| 2 | Prior-art sweep, corpus FIRST then grep | t1k-cocos-base-knowledge-sweep | a reuse-verdict: line per candidate need; MCP down → unverified, never CONTRIBUTE |
| 3 | Audit, three lanes in parallel | scan-structure.cjs (t1k-cocos-playable-modularize-structure-audit), t1k-cocos-base-architecture-patterns audit mode, source-scan-guard.cjs (t1k-cocos-base-source-scan-guard), plus t1k-cocos-playable-primitive-decompose --sweep | one ranked findings list |
| 4 | Name the Wave-0 free wins and hand off | reported, not executed — see below | — |
| 5 | Characterization goldens, every module in scope, committed BEFORE anything moves | record-baseline.cjs (t1k-cocos-playable-characterization) | goldens recorded; replay green on unchanged code |
| 6 | Fix pass — every source-scan-guard ERROR and audit defect | t1k-cocos-base-developer | guard exits 0; suite green |
| 7 | Relocate (R) — pure logic out of cc-bound files into domain/application behind ports | t1k-cocos-base-developer | verify-golden.cjs replay identical |
| 8 | Decompose methods over budget to expose seams | t1k-cocos-playable-primitive-decompose --fix | baseline not regressed |
| 9 | Mechanic-first candidate slate + purity, sized at 1.20x | feature/mechanics enumeration + corpus sweep (main session, § Stage 9 below), then stdlib-candidates.cjs (t1k-cocos-playable-stdlib-harvest), purity-check.cjs (t1k-cocos-playable-stdlib-harvest) | each candidate REUSE/EXTEND/CONTRIBUTE/KEEP with a reason and a Transplant Card (references/value-contract.md) |
| 10 | Fable review gate, ≤3 rounds | t1k-cocos-base-stdlib-gatekeeper (model: fable) | one JSON verdict APPROVE/REVISE/REJECT per candidate, judged GK-VALUE-first |
| 11 | Contribute, one PR per package | t1k-cocos-playable-stdlib-contributor | CI watched via the Stage-11 red-CI loop; merge only on green — never --auto |
| 12 | Re-measure every 3-4 packages; build before/after artifacts; write the final acceptance report | t1k-cocos-playable-reuse-coverage | no next wave planned on a projection; report complete, terminal acceptance handed to user, --json to session-scratchpad (no in-repo files) |
Stage 0 — bootstraps what is missing; abort only if this is not a Cocos project
Section titled “Stage 0 — bootstraps what is missing; abort only if this is not a Cocos project”A missing precondition is bootstrapped, not fatal, and this is the only point at which the lane
is still cheap to stop. Each one blocks a later stage, so a check skipped here burns stages 1-4
before the lane discovers it cannot finish. Abort is reserved for “not a Cocos project”; a
remedy that fails skips stages 5-8 and the lane continues at mechanic scope. Procedure, remedies
and the failure path:
references/stage0-preconditions.md.
- No project-resolvable Vitest → Stage 0 bootstraps one — its ONE sanctioned write outside
assets/scripts/**, committed on its own before Stage 1 (vitestdevDependency +testscript,vitest.config.ts,bun install,--passWithNoTestsprobe). Existing setup untouched. - No checkpoints anchor → Stage 0 resolves it itself via
t1k-cocos-playable-project-info(writesproject-info.json, runst1k-checkpoints.cjs init). Thecocos-checkpoints-anchor-guard.cjshook blocks edits 6/7/8 until the anchor is valid; its override (T1K_SKIP_COCOS_CHECKPOINTS_GUARD=1) is never this lane’s remedy — silencing a guard rather than satisfying it is routing around a stop. - The one allowed Stage-0 ask. A project-side remedy that cannot be completed without user
input (e.g.
project-infoneeds a client name no source file resolves) is the singleAskUserQuestionStage 0 may raise. - A project-side remedy that fails does NOT abort the lane (a Vitest bootstrap that will not install, a declined remedy): stages 5-8 are skipped and recorded, and stages 9-11 still run at full mechanic scope, never as a leaf-only slate. Abort is reserved for “not a Cocos project” — the one condition no later stage can route around.
--stop-after <stage> is an explicit opt-in only — the default is the full lane 0→12 with no
mid-run halts. --max-packages N caps how many stage-9 candidates reach 10/11 in one run.
Stage 11 — the red-CI loop: fix, don’t halt; drop at 3
Section titled “Stage 11 — the red-CI loop: fix, don’t halt; drop at 3”A red CI check on a cocos-stdlib PR is not a halt. Per PR: t1k-ci-watcher watches checks to
terminal and reports the failure (never retries, fixes or merges) → t1k-cocos-base-developer reads
the failing check’s log and applies the fix on the same PR branch → re-watch. Max 3 fix
rounds; still red after round 3 → drop that package: close the PR, record it in the final
report as dropped with the failing check name and a log excerpt, continue with remaining
candidates. Two invariants survive the loop unchanged: never merge non-green, and never
--auto on cocos-stdlib — the loop fixes redness, it never converts it.
Stage 9 — mechanic-first, and the Transplant Card
Section titled “Stage 9 — mechanic-first, and the Transplant Card”The symbol scan is the LAST step of Stage 9, never its slate, and every candidate reaches
Stage 10 with a Transplant Card: mechanic-first enumeration of the game’s own features, then the
card’s transplant test, and stdlib-candidates.cjs only to catch what that missed. The contract
is references/value-contract.md — the order, the card’s fields
and PASS/FAIL rule, the four FAIL shapes, FOLD/EXTEND/KEEP, and the HexaBugFlowPLA@983e546
counter-example (~9% retire-able of 1779 project lines, from a slate that passed every gate).
Stages 5-8 are not a prerequisite for contributing — cc-bound logic is extracted
package-side behind ports, so stages 9-11 are never leaf-only. Same reference.
Stage 4 — why the free wins are handed off, not executed here
Section titled “Stage 4 — why the free wins are handed off, not executed here”A published package duplicating in-repo code, and a vendored package imported by zero files, are
both adoption work — t1k-cocos-playable-stdlib-adopt’s subject, not this lane’s. Stage 4
NAMES them (path + line count each) and tells the caller to run t1k:cocos:playable:stdlib-adopt
first: import edits against already-CI-green upstream code, no extraction, no fable round, no new
cocos-stdlib PR. Measured precedent: ~420 duplicated lines across four such packages, plus a
31-curve easing library vendored (in playableSync), imported by nothing, while the game
hand-rolled the same curves in two places.
Stage 10 — what “review with fable” resolves to
Section titled “Stage 10 — what “review with fable” resolves to”t1k-cocos-base-stdlib-gatekeeper is the kit’s only model: fable review agent — advisory by
construction (no Edit; its final message IS the deliverable). Fable judges, a developer agent
repairs: one JSON verdict, rubric-id findings, per candidate; APPROVE → stage 11; REVISE →
t1k-cocos-base-developer applies the named findings and re-gates (round 2, then 3); REJECT or a
third REVISE → the candidate is dropped, verdict quoted, run continues. Dropping a rejected
candidate IS the autonomy grant — never grind a REJECT until it passes.
t1k-cocos-base-reviewer (opus) remains the right agent for gameplay-diff review. This lane uses fable
for the package-contribution gate only, never as a substitute for gameplay review.
Final acceptance report
Section titled “Final acceptance report”The single terminal artifact, delivered with the before/after builds. Required contents:
- Coverage before/after — both figures with their
templateBaselinestate;partial/unavailablereported as the upper/lower bounds they are, never bare numbers. - Packages merged — each with its cocos-stdlib PR URL and its Transplant Card.
- The retire projection — per merged package, the projected retire-able codeLines in the
source project on adoption, and that figure as a share of
projectcodeLines. Then one honest line: a run whose packages together retire a small share is reported as a thin run, with the reason. No numeric threshold defines “thin” — state the number and let the reader judge (references/value-contract.md). - Packages dropped — with its reason: gatekeeper verdict quoted, or Stage-11 failing check name + log excerpt (max-3-rounds drop).
- Items needing human — every skip-and-record entry: scope-breach skips, never-offload
skips, and merged packages awaiting
bun publish. State whether Stage 0 bootstrapped the Vitest harness, and whether stages 5-8 were skipped. - Stage-4 adoption hand-off list — path + line count each, for
t1k-cocos-playable-stdlib-adopt. - Before/after build paths — where the two packaged builds live, for the layer-4 playtest.
Hard rules
Section titled “Hard rules”Each earned in a real run — SignalBus constructor-identity collision, the layering law, TSDoc not
reaching the coverage numerator, @ccclass scene-attachment reachability, and
parameter-scan --deep’s *Config.ts glob gap: references/incident-history.md.
Executed by
Section titled “Executed by”Depth 0 spawns to depth 1; the fan-out cap and the depth budget are
theonekit-core/.claude/modules/t1k-base/rules/agent-security-boilerplate.md § agent-only (8/3/2 by depth). This lane is a leaf consumer
of that budget, not a setter of it.
| Work | Agent |
|---|---|
| Stage 0, 1, 3 (audit-mode + guard), 9, 12 mechanics | no agent — deterministic CLI plus main-session reasoning |
| Stage 3 architecture audit | t1k-cocos-base-architecture-patterns (AI-driven, read-only) |
| Stage 5 characterization | t1k-cocos-playable-characterization |
| Stage 6/7 fix + relocate | t1k-cocos-base-developer |
| Stage 8 decompose | t1k-cocos-playable-primitive-decompose |
| Stage 9 corpus sweep (candidate-level) | t1k-corpus-scout |
| Stage 10 gatekeeper | t1k-cocos-base-stdlib-gatekeeper (fable), one candidate at a time |
| Stage 11 extract/scaffold/PR | t1k-cocos-playable-stdlib-contributor |
| Stage 11 PR watching | t1k-ci-watcher — watches to terminal, never retries, fixes or merges |
| Stage 11 red-CI fix rounds (≤3 per PR) | t1k-cocos-base-developer — fixes from the failing check’s log on the same branch |
| Stage 0 anchor self-resolution | t1k-cocos-playable-project-info — writes project-info.json + t1k-checkpoints.cjs init |
| Stage 0 Vitest bootstrap | t1k-cocos-base-developer — writes package.json/vitest.config.ts once, as its own commit |
| Git ops throughout | t1k-git-manager |
Routing rows live in theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md; this table is the lane-specific map, not a
second copy of that one.
Related
Section titled “Related”t1k-cocos-playable-stdlib-adopt— the sibling lane Stage 4 hands off to; wires published packages back into a project instead of shipping new ones.t1k-cocos-base-stdlib-contribute— Steps 0-10 this lane’s Stage 9-11 hand each candidate to.t1k-cocos-playable-stdlib-harvest— the org-wide harvest pipeline this lane runs a single-repo slice of; ownspurity-check.cjs.t1k-cocos-playable-reuse-coverage— the measurement this lane’s Stage 1/12 call.t1k-cocos-playable-characterization— the equivalence gate this lane’s Stage 5/7 call.t1k-cocos-base-knowledge-sweep— the reuse-loop sweep this lane’s Stage 2 calls.t1k-cocos-playable-project-info— Stage 0’s checkpoints-anchor remedy.