Skip to content

t1k:cocos:playable:stdlib-autocontribute

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
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

/t1k:cocos:playable:stdlib-autocontribute
[<project-root>] [--scope <glob>] [--index <clone-index-dir>] [--stop-after <stage>] [--max-packages N]

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.

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/** (never assets/packages/; package.json/vitest.config.ts belong to t1k-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 --auto on 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.

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.

Layers 1-3 gate every change automatically in the lane (no ask); layer 4 is the terminal acceptance step, not a mid-run stop:

  1. Vitest suite green and not shrunk.
  2. Characterization goldens replay identical — t1k-cocos-playable-characterization.
  3. Headless runtime verify on the packaged build — t1k-gamedev-playable-preview-verify: zero console errors, CTA fires, diffPercent against baseline.
  4. Human playtest of the before/after builds — terminal, once, at the end. Nothing in this lane substitutes for it (see Final acceptance report, below).
#StageOwned byGate
0Preflight — detect Cocos project, settle the two preconditions below (Vitest bootstrap, checkpoints anchor), resolve --scope, cut a branch, baseline bun testdetect-cocos-project.cjs (t1k-cocos-base-knowledge-sweep); branch per theonekit-core/.claude/modules/t1k-base/rules/branch-discipline.mdproject detected; Vitest harness present (bootstrapped if absent); checkpoints anchor present; suite green BEFORE anything moves
1Baseline measuret1k-cocos-playable-reuse-coveragetemplateBaseline: available confirmed, --index explicit, --json to session-scratchpad (no in-repo files)
2Prior-art sweep, corpus FIRST then grept1k-cocos-base-knowledge-sweepa reuse-verdict: line per candidate need; MCP down → unverified, never CONTRIBUTE
3Audit, three lanes in parallelscan-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 --sweepone ranked findings list
4Name the Wave-0 free wins and hand offreported, not executed — see below—
5Characterization goldens, every module in scope, committed BEFORE anything movesrecord-baseline.cjs (t1k-cocos-playable-characterization)goldens recorded; replay green on unchanged code
6Fix pass — every source-scan-guard ERROR and audit defectt1k-cocos-base-developerguard exits 0; suite green
7Relocate (R) — pure logic out of cc-bound files into domain/application behind portst1k-cocos-base-developerverify-golden.cjs replay identical
8Decompose methods over budget to expose seamst1k-cocos-playable-primitive-decompose --fixbaseline not regressed
9Mechanic-first candidate slate + purity, sized at 1.20xfeature/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)
10Fable review gate, ≤3 roundst1k-cocos-base-stdlib-gatekeeper (model: fable)one JSON verdict APPROVE/REVISE/REJECT per candidate, judged GK-VALUE-first
11Contribute, one PR per packaget1k-cocos-playable-stdlib-contributorCI watched via the Stage-11 red-CI loop; merge only on green — never --auto
12Re-measure every 3-4 packages; build before/after artifacts; write the final acceptance reportt1k-cocos-playable-reuse-coverageno 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 (vitest devDependency + test script, vitest.config.ts, bun install, --passWithNoTests probe). Existing setup untouched.
  • No checkpoints anchor → Stage 0 resolves it itself via t1k-cocos-playable-project-info (writes project-info.json, runs t1k-checkpoints.cjs init). The cocos-checkpoints-anchor-guard.cjs hook 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-info needs a client name no source file resolves) is the single AskUserQuestion Stage 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.

The single terminal artifact, delivered with the before/after builds. Required contents:

  1. Coverage before/after — both figures with their templateBaseline state; partial/ unavailable reported as the upper/lower bounds they are, never bare numbers.
  2. Packages merged — each with its cocos-stdlib PR URL and its Transplant Card.
  3. The retire projection — per merged package, the projected retire-able codeLines in the source project on adoption, and that figure as a share of project codeLines. 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).
  4. Packages dropped — with its reason: gatekeeper verdict quoted, or Stage-11 failing check name + log excerpt (max-3-rounds drop).
  5. 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.
  6. Stage-4 adoption hand-off list — path + line count each, for t1k-cocos-playable-stdlib-adopt.
  7. Before/after build paths — where the two packaged builds live, for the layer-4 playtest.

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.

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.

WorkAgent
Stage 0, 1, 3 (audit-mode + guard), 9, 12 mechanicsno agent — deterministic CLI plus main-session reasoning
Stage 3 architecture auditt1k-cocos-base-architecture-patterns (AI-driven, read-only)
Stage 5 characterizationt1k-cocos-playable-characterization
Stage 6/7 fix + relocatet1k-cocos-base-developer
Stage 8 decomposet1k-cocos-playable-primitive-decompose
Stage 9 corpus sweep (candidate-level)t1k-corpus-scout
Stage 10 gatekeepert1k-cocos-base-stdlib-gatekeeper (fable), one candidate at a time
Stage 11 extract/scaffold/PRt1k-cocos-playable-stdlib-contributor
Stage 11 PR watchingt1k-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-resolutiont1k-cocos-playable-project-info — writes project-info.json + t1k-checkpoints.cjs init
Stage 0 Vitest bootstrapt1k-cocos-base-developer — writes package.json/vitest.config.ts once, as its own commit
Git ops throughoutt1k-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.

  • 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; owns purity-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.