t1k:playablelabs:ci:deliver
| Field | Value |
|---|---|
| Module | ci |
| Version | 1.17.3 |
| Effort | medium |
| Tools | — |
Keywords: build and deliver playable, deliver playable to discord, playable ci deliver, playable engine deliver
How to invoke
Section titled “How to invoke”/t1k:playablelabs:ci:deliver--client <name> --project <PascalName> --engine-host <cocos-3.8|web> [--game-repo <ssh-url>] [--branch develop] [--delivery-channel <id>] --game-dir <clone> [--accept-unverified "<reason>" --accepted-by "<name>"]Build and deliver a playable to Discord
Section titled “Build and deliver a playable to Discord”The kit-side half of the one-prompt playable loop. Core t1k:playable-start installs the kits and hands off
here; the Cocos kit’s pipeline hands off here once the game repo exists. This skill cites the skills that
do each step and never re-implements them. No Jenkins job is created: the shared job
CocosPlayableLabs/PlayablePacker builds every playable, and no PlayableLabs login or vault entry is used.
Input contract
Section titled “Input contract”--client <name> --project <PascalName> --engine-host <cocos-3.8|web> --game-repo <ssh-url> [--branch develop] [--delivery-channel <id>] --game-dir <local clone at the commit to build>. web is what the user calls “playable engine”; only there may --game-repo be
omitted (step 0). Any other missing flag is AskUserQuestion, never a guess.
D=~/.claude/skills/t1k-playablelabs-ci-deliver/scripts/deliver.cjs (use the project .claude/ copy when
installed locally). Every D subcommand prints one JSON object; exit codes are at the end.
-
Web with no
--game-repo: provision a bare game repo. PlaybleEngine holds no web game and the Jenkinsfile always clonesPARAM_GAME_REPOintogame/(checked atPlaybleEngine@d2bead0), so a web game is its own repo:Terminal window bun "$D" provision-web-repo --project <Project> --parent-dir <dir> [--dry-run] # {repo, sshUrl, branch: develop}Creates private
The1Studio/<Project>PLA(a project already ending inPLAis not doubled), clones over SSH, writes the minimum file set (scripts/web-repo-template.cjs:package.json(no dependencies, so no lockfile:bun install --frozen-lockfilesucceeds without one),index.html, a hello-worldsrc/game.js,scripts/build.cjsemittingdist/index.html+ top-leveldist/game.js) and pushesdevelop. The hello-world sets the__PLA_*globals and fires the CTA (game_end()thendownload()); packed with--engine-host webit passed smoke 4/4 locally (applovin, google). PlaybleEngine is not an npm dependency: the job checks the packer out itself. FeedsshUrland branchdevelopinto the steps below. Exit 7 (repo-exists,target-dir-exists): stop and ask the user, never reuse silently.--game-repopointing atPlaybleEngineitself stays refused (step 3, exit 7). -
Thread name and channel.
bun "$D" thread-name --client "<client>" --project <Project> [--delivery-channel <id>]gives{threadName: "<Client> - <Project>", deliveryChannelId, guildId}. The default channelcocos-playable-build-deliveryand the guild live inreferences/delivery-config.json(one thread per playable there); the flag overrides the channel. -
Find or create the thread. Inline in the main session: a routed fork has no MCP.
- Find, in order:
channels_list_active_threads_guildfiltered byparent_id == deliveryChannelIdand exactthreadName, thenchannels_list_public_archived_threadson the channel. Found: reuse it (an archived one is unarchived by posting; if the build post fails, say so). Never create a second thread of the same name. - Absent: create per core
t1k-setup-project/references/discord-thread.md:channels_getthe channel (type0: permission preflight, anchor message naming the playable,messages_create_thread; type15: forum create; any other type: stop),channels_getthe new id to read it back (type 11 or 12), thent1k-service-binding.cjs set-thread --service discord --job <Project> --thread-id <id> --source created. An unbound repo makesset-threada skip: continue, the thread exists. Never trigger a build with an id you did not read back.
- Find, in order:
2a. Web or none targeting Google: lazy policy, committed before the playthrough. On the built dist/ of --game-dir,
run bun "<web-lazy-load skill dir>/scripts/gen-playable-lazy.cjs" --build <dist> --out public/playable-lazy.json
(--check when the file exists) and commit public/playable-lazy.json. The commit changes what is built, so this
runs before step 3, which binds the GREEN report to that commit. Skip for Cocos. Pre-pack steps and exit codes:
t1k-playablelabs-base-pack § “Before you pack”; the contract: t1k-playablelabs-web-lazy-load.
-
Playthrough gate, then trigger the shared job from the main session. No build without a GREEN playthrough (rule
playablelabs-playthrough-before-build.md):trigger-paramsREFUSES (exit 7,reason: "playthrough-gate", nothing triggered) unless<game-dir>/playthrough/report.jsonis a GREENplareport1for the commit being built. Produce it from the game repo withbun playthrough.cjs run ... --publish(t1k-playablelabs-base-playthrough), commitplaythrough/report.json+report.md(the evidence frames may stay untracked), push, then trigger. What the gate checks, in order, none of it escapable unless marked:- The clone.
--game-diris the root of a clone whoseoriginis--game-repo(a subdirectory, a..path, a symlink out: refused). - The commit.
--commit, when given, must equal the clone’s HEAD (elsebad-commit).git ls-remote origin refs/heads/<--branch>must equal HEAD (elseremote-mismatch; origin unreachable:remote-unreachable, it fails closed).report.jsonandreport.mdmust be git-tracked and unmodified (elsedirty). - The inputs. The game repo’s committed
package.jsondeclares"playthrough": {"profile": "<file>", "dist": "<dir>"}(scaffold-profile.cjswrites it; missing:no-declaration); the report must be about exactly that profile and dist. - The report. Written by the installed tool version (generator + per-run nonce, also in
report.md); the verdict is re-derived from its own checks (a GREEN with a failing or unverified check isinvalid); the declared states, levels, strips and invariants each have their check and frames; the profile, the dist and every evidence file re-hash the same. - The code. The report counts for the commit it names, or a later commit that only touched
playthrough/; code changed after it, or a dirty tree: refused. - Squash merges (
stale). A report sealed on a PR branch commit isstaleonce the PR is squash-merged: the squash commit on the base branch is not a descendant of that branch commit, so the gate refuses it. Run the playthrough on the exact commit the build will check out. Squash-merge first, pull the base branch, runplaythrough.cjs run ... --publishfrom that commit, commitplaythrough/, push the build branch (--branch,developby default), then trigger. The gate does not accept a squash commit by tree comparison: a report is for the commit it names, and a re-run is one command. Honest limits. A deliberately forged report passes the gate: it is an accident and laziness guard, and the Jenkins build and smoke, plus the delivery post that must attachreport.mdand the frames, are the real checks unless the game repo opts in to the keyed seal, see below. There is no secret, so anyone who can run the tool’s code could write a consistent report. What must be covered is read from the committed profile (hash-checked, loaded by the gate), never from the report’s own coverage block.--commitmay be a full sha or an abbreviation of HEAD (7+ hex). The escape log is not required to be tracked: the audit line lives in the clone that wrote it, so the delivery post must carry the marker. The Jenkins job takes a branch (PARAM_GAME_BRANCH), not a commit: the gate pins the remote tip at the moment it runs, a push between the gate and Jenkins’ checkout is not seen.
Optional keyed seal. A game repo opts in with
"seal": "hmac"insidepackage.jsonplaythrough.--publishthen addsintegrity.hmac({alghmac-sha256, kid, value}: HMAC over the integrity digest and the ordered evidence digests), and the gate refuses a report without a valid one (unsealed,bad-hmac, orno-seal-keywhen the gate host cannot read the key; none of these has an escape). The key is the vault secretplayablelabs-playthrough-seal(t1k vault get playablelabs-playthrough-seal; CI may inject it asPLAYTHROUGH_SEAL_KEY); it is never in a repo. Whoever publishes reports and the delivery host hold read access; a person with only the repo cannot forge a report the gate accepts. If the key is unreadable at--publishthe tool prints a WARNING and writes an unsealed report. Rotation:t1k vault putthe new value, then every game repo republishes its report (--publish, commit): an old report fails asbad-hmacwith a rotated-key hint until then. Repos that do not opt in are unchanged. RED has no escape; neither doinvalid(tampered or self-contradicting),bad-game-dir,bad-commitorremote-*. A missing, stale, dirty, undeclared or UNVERIFIED report is built only when the user accepts it by name:--accept-unverified "<why>" --accepted-by "<name>"(reason of 3+ distinct words; both required), logged with commit, accepted-by, OS user and time toplaythrough/accepted-unverified.jsonl(a log that cannot be written refuses the build). That build exits 0 exactly like a GREEN one; only the marker line tells them apart.trigger-paramsprints it on stderr before the JSON and returns it asplaythroughGate.marker:[playthrough-gate] ACCEPTED-UNVERIFIED status=<s> commit=<sha10> accepted-by="<name>" os-user=<u> at=<iso> reason="<why>"(a GREEN gate prints[playthrough-gate] GREEN commit=<sha10>). The delivery post (and the PR) must carry that line verbatim. Never pass the escape on your own.A named vision waiver (
ACCEPTED-WAIVED). A negative vision verdict (VFX missing, animation frozen, colour different) stays RED unlessplaythrough/vision-review.jsonhas awaivers[]entry for that item and answer (shape:t1k-playablelabs-base-playthroughreferences/CONTRACT.mdsection 7; ruleplayablelabs-playthrough-before-build.mditem 6). A failingcolourstate is accepted the same way by awaivers[]entry withcheck: "colour"for<objective>:state:<id>(its marker readswaived="<id> colour"). Then the report’svision.statusiswaived(orreport.colourWaivers.appliedis non-empty), which is not GREEN:trigger-paramsrefuses it (exit 7,waived) unless--accepted-by "<name>"is exactly theacceptedByevery waiver names. It builds with exit 0 and the marker[playthrough-gate] ACCEPTED-WAIVED commit=<sha10> accepted-by="<name>" os-user=<u> at=<iso> waived="<id> <answer>" reason="<reason>", logged to the sameaccepted-unverified.jsonlwith each waiver’s reason, look-at and date. A waiver needs no--accept-unverifiedand never takes one: a different name, or--accept-unverifiedon its own, is refused with no escape. A RED is still RED whatever waivers exist.Terminal window bun "$D" trigger-params --thread <threadId> --game-repo <ssh> --engine-host <host> --game-dir <clone> --accepted-by "<the waiver's acceptedBy>"Terminal window bun "$D" trigger-params --thread <threadId> --game-repo <ssh> --engine-host <host> --game-dir <clone> [--commit <sha>] [--branch <b>] [--build-file-name <n>] [--accept-unverified "<reason>" --accepted-by "<name>"]More than one game: never trigger them back to back. The job runs 1 build at a time and a newer trigger aborts the older. Save each
parametersobject into a JSON array and runbun "$D" trigger-batch --batch-file <file> [--poll-ms 5000] [--max-polls 120](needsJENKINS_URL,JENKINS_USER,JENKINS_API_TOKEN): it triggers one build, waits until its queue item hasinQueue=falseand anexecutable.number, then the next; a build stuck in the queue stops the batch (exit 7,queue-timeout, rest not triggered).Pass
parameterstomcp__jenkins__triggerBuildonjob(CocosPlayableLabs/PlayablePacker):PARAM_DISCORD_THREAD_ID,PARAM_GAME_REPO,PARAM_GAME_BRANCH(defaultdevelop),PARAM_ENGINE_HOST,PARAM_BUILD_FILE_NAME(the game repo name unless overridden; Cocos builds readgame/Cocos<Name>, so a Cocos repo whose project dir differs needs--build-file-name),PARAM_SMOKE=true,PARAM_SHOULD_NOTIFY_TO_CHAT_CHANNEL=true, and forwebPARAM_AGENT_LABEL=web-linux(proven by Jenkins build #133 onTimelineUpThreePLA);cocos-3.8keeps the defaultauto-cocos(Windows agent). Parameter meanings:t1k-playablelabs-ci-jenkins. The job is shared by every project, so resolve YOUR build from the queue idtriggerBuildreturns and assert itsParametersActionmatchesPARAM_GAME_REPO/PARAM_GAME_BRANCH/thread before reporting — neverlastBuild(the rule ist1k-playablelabs-ci-jenkinsstep 3). Watch that number with a backgroundt1k-ci-watcher(mcp__jenkins__getBuild); the build, not this skill, uploads and posts the embed. - The clone.
-
Report: thread link (
https://discord.com/channels/<guildId>/<threadId>), Jenkins build number and URL, and the verdict read from the console log, not the colour. Forcocos-3.8say “not editor-previewed; the Jenkins smoke is the gate”. A red smoke or red pack is reported as red with the failing stage, never as delivered.The post must carry the visual-parity verdict. Run the G9 gate (clean-room Phase 3 / gate G9) on the packed build — or read its result from the build QA — and state one line:
visual-parity: GREEN, orvisual-parity: <region> dS=… dContrast=… (outside band, accepted: <reason>). Outside the stated tolerance with no accepted reason blocks the post. A build that was never measured postsvisual-parity: BLOCKED (<why>), never an implied pass. Both engine hosts; procedure and bands:skills/t1k-playablelabs-base-clean-room/references/visual-parity.md.The post must also carry the runtime-performance verdict. Profile the packed artifact against the original at the same state and viewport (G11) and state either
runtime-performance: GREENor the measured regression (runtime-performance: <p50/p95 delta> (outside floor, accepted: <reason>)). An unmeasured build postsruntime-performance: BLOCKED (<why>); a fully obfuscatedgame.jsfails outright. Procedure:skills/t1k-playablelabs-base-clean-room/references/runtime-performance.md.The post also carries one
reuse:line, report only:bun "$D" reuse-line --game-dir <clone>prints{reuse, source}from the theonekit-cocos build-size skill’sreuse-ship-check.cjs(checkship-reuse: packages used, NEW verdicts with a package hit and how many are unwaived, KEEP without index). It always exits 0; a missing script or an empty ledger readsreuse: unverified (...)/reuse: no data, never an implied pass. It runs in modereportand never blocks a delivery. -
One review request per MILESTONE, never per build (references/review-request.md). Posting every build to the thread is expected; the
**🙋 Needs from you:**ping is not. It fires at a milestone only — first playable end-to-end, polish bar passed, or a decision the reviewer owns — and carries the ref-vs-port strips/video, the polish-bar table, the exact ask, named reviewers, a stated deadline and the fallback: no answer by the deadline means the AI proceeds on its best judgement and flags the decision[review] unreviewed — ...in the thread and in the next post. While waiting, start ONLY work the answer cannot change (per-network packs, size, parameter audit/stamp, store link, dashboard publish prep, orientation checks, next polish backlog) and queue it before a weekend. Measured cost of a ping per build: 6.6 h for one weekday reply, 72 h over a weekend, against 28 min to ship the fix once the answer arrived. -
Client loop (references/client-loop.md). Before the first build reaches a client: the
## Sign-offblock is recorded (reference, bar, viewports, networks, store link, and the client’s OWN baseline ornone-searched); the first build they see is the polish-bar-green milestone build; and the ask goes out as numbered items each taggedbug/taste/scope-change. Ascope-changeis a NEW ask with its own work item, never a defect folded into the current round. Count every round in the game repo README## Client rounds. -
Process numbers (references/process-metrics.md). Six metrics with the exact command for each, every rate printed with its sample size beside it: AI-active ratio (commit-gap proxy, sleep caveat), ping-to-reply latency, reviews per game, client rounds, days to first external-eyes build (single sample), UNSTABLE rate. Read, never invent: no seventh script.
Hard rules
Section titled “Hard rules”- Do not poll the Quick Play URL before the build finishes. Cloudflare caches a 404 for the Quick Play URL for
about an hour, so a probe before the Jenkins build uploads can keep the link dead after it exists. Wait for a
finished build; if the 404 is already cached, add a query string (
?t=<n>) to bypass the cache.
A green board is not a match: the lesson behind the visual-parity and runtime-performance lines of the delivery
post is in ledger/gotchas/t1k-playablelabs-ci-deliver.md.
deliver.cjs exit codes
Section titled “deliver.cjs exit codes”| Code | Meaning | Action |
|---|---|---|
| 0 | ok | continue |
| 2 | usage (bad flag, bad snowflake, non-SSH repo, unknown subcommand) | fix input, rerun |
| 6 | gh or git error (create, clone, push) | report the stderr |
| 7 | stop-and-name (in-repo-game-unsupported, repo-exists, target-dir-exists, playthrough-gate, queue-timeout) | stop, tell the user (gate: run the playthrough, commit the report, or get the user’s named acceptance) |
Exit 0 after --accept-unverified means “accepted”, not “GREEN”: grep the output for [playthrough-gate] ACCEPTED-UNVERIFIED and carry it into the post. Exit 0 after a named waiver means ACCEPTED-WAIVED (also not GREEN): grep for [playthrough-gate] ACCEPTED-WAIVED.
Tests: bun test scripts/deliver.test.cjs scripts/playthrough-gate.test.cjs (gh mocked; the gate tests use throwaway local git repos; no network).
Executed by
Section titled “Executed by”Steps 0 and 1 (script) and the trigger-params call are mechanical; the Discord and Jenkins MCP calls need the main
session, and which thread is right is a user decision. Routing SSOT: rules/orchestration-rules.md
§ “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run deliver.cjs, tabulate the JSON | t1k-data-verifier |
Thread find/create, triggerBuild, user questions | main session (MCP + user) |
| Watch the build to a verdict (status only) | t1k-ci-watcher |
| Judge a red build or a packer fault | t1k-playablelabs-base-packer-engineer |