Skip to content

t1k:playablelabs:ci:deliver

FieldValue
Moduleci
Version1.17.3
Effortmedium
Tools—

Keywords: build and deliver playable, deliver playable to discord, playable ci deliver, playable engine deliver

/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>"]

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.

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

  1. Web with no --game-repo: provision a bare game repo. PlaybleEngine holds no web game and the Jenkinsfile always clones PARAM_GAME_REPO into game/ (checked at PlaybleEngine@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 in PLA is 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-lockfile succeeds without one), index.html, a hello-world src/game.js, scripts/build.cjs emitting dist/index.html + top-level dist/game.js) and pushes develop. The hello-world sets the __PLA_* globals and fires the CTA (game_end() then download()); packed with --engine-host web it passed smoke 4/4 locally (applovin, google). PlaybleEngine is not an npm dependency: the job checks the packer out itself. Feed sshUrl and branch develop into the steps below. Exit 7 (repo-exists, target-dir-exists): stop and ask the user, never reuse silently. --game-repo pointing at PlaybleEngine itself stays refused (step 3, exit 7).

  2. Thread name and channel. bun "$D" thread-name --client "<client>" --project <Project> [--delivery-channel <id>] gives {threadName: "<Client> - <Project>", deliveryChannelId, guildId}. The default channel cocos-playable-build-delivery and the guild live in references/delivery-config.json (one thread per playable there); the flag overrides the channel.

  3. Find or create the thread. Inline in the main session: a routed fork has no MCP.

    • Find, in order: channels_list_active_threads_guild filtered by parent_id == deliveryChannelId and exact threadName, then channels_list_public_archived_threads on 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_get the channel (type 0: permission preflight, anchor message naming the playable, messages_create_thread; type 15: forum create; any other type: stop), channels_get the new id to read it back (type 11 or 12), then t1k-service-binding.cjs set-thread --service discord --job <Project> --thread-id <id> --source created. An unbound repo makes set-thread a skip: continue, the thread exists. Never trigger a build with an id you did not read back.

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.

  1. Playthrough gate, then trigger the shared job from the main session. No build without a GREEN playthrough (rule playablelabs-playthrough-before-build.md): trigger-params REFUSES (exit 7, reason: "playthrough-gate", nothing triggered) unless <game-dir>/playthrough/report.json is a GREEN plareport1 for the commit being built. Produce it from the game repo with bun playthrough.cjs run ... --publish (t1k-playablelabs-base-playthrough), commit playthrough/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-dir is the root of a clone whose origin is --game-repo (a subdirectory, a .. path, a symlink out: refused).
    • The commit. --commit, when given, must equal the clone’s HEAD (else bad-commit). git ls-remote origin refs/heads/<--branch> must equal HEAD (else remote-mismatch; origin unreachable: remote-unreachable, it fails closed). report.json and report.md must be git-tracked and unmodified (else dirty).
    • The inputs. The game repo’s committed package.json declares "playthrough": {"profile": "<file>", "dist": "<dir>"} (scaffold-profile.cjs writes 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 is invalid); 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 is stale once 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, run playthrough.cjs run ... --publish from that commit, commit playthrough/, push the build branch (--branch, develop by 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 attach report.md and 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. --commit may 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" inside package.json playthrough. --publish then adds integrity.hmac ({alg hmac-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, or no-seal-key when the gate host cannot read the key; none of these has an escape). The key is the vault secret playablelabs-playthrough-seal (t1k vault get playablelabs-playthrough-seal; CI may inject it as PLAYTHROUGH_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 --publish the tool prints a WARNING and writes an unsealed report. Rotation: t1k vault put the new value, then every game repo republishes its report (--publish, commit): an old report fails as bad-hmac with a rotated-key hint until then. Repos that do not opt in are unchanged. RED has no escape; neither do invalid (tampered or self-contradicting), bad-game-dir, bad-commit or remote-*. 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 to playthrough/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-params prints it on stderr before the JSON and returns it as playthroughGate.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 unless playthrough/vision-review.json has a waivers[] entry for that item and answer (shape: t1k-playablelabs-base-playthrough references/CONTRACT.md section 7; rule playablelabs-playthrough-before-build.md item 6). A failing colour state is accepted the same way by a waivers[] entry with check: "colour" for <objective>:state:<id> (its marker reads waived="<id> colour"). Then the report’s vision.status is waived (or report.colourWaivers.applied is non-empty), which is not GREEN: trigger-params refuses it (exit 7, waived) unless --accepted-by "<name>" is exactly the acceptedBy every 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 same accepted-unverified.jsonl with each waiver’s reason, look-at and date. A waiver needs no --accept-unverified and never takes one: a different name, or --accept-unverified on 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 parameters object into a JSON array and run bun "$D" trigger-batch --batch-file <file> [--poll-ms 5000] [--max-polls 120] (needs JENKINS_URL, JENKINS_USER, JENKINS_API_TOKEN): it triggers one build, waits until its queue item has inQueue=false and an executable.number, then the next; a build stuck in the queue stops the batch (exit 7, queue-timeout, rest not triggered).

    Pass parameters to mcp__jenkins__triggerBuild on job (CocosPlayableLabs/PlayablePacker): PARAM_DISCORD_THREAD_ID, PARAM_GAME_REPO, PARAM_GAME_BRANCH (default develop), PARAM_ENGINE_HOST, PARAM_BUILD_FILE_NAME (the game repo name unless overridden; Cocos builds read game/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 for web PARAM_AGENT_LABEL=web-linux (proven by Jenkins build #133 on TimelineUpThreePLA); cocos-3.8 keeps the default auto-cocos (Windows agent). Parameter meanings: t1k-playablelabs-ci-jenkins. The job is shared by every project, so resolve YOUR build from the queue id triggerBuild returns and assert its ParametersAction matches PARAM_GAME_REPO/PARAM_GAME_BRANCH/thread before reporting — never lastBuild (the rule is t1k-playablelabs-ci-jenkins step 3). Watch that number with a background t1k-ci-watcher (mcp__jenkins__getBuild); the build, not this skill, uploads and posts the embed.

  2. 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. For cocos-3.8 say “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, or visual-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 posts visual-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: GREEN or the measured regression (runtime-performance: <p50/p95 delta> (outside floor, accepted: <reason>)). An unmeasured build posts runtime-performance: BLOCKED (<why>); a fully obfuscated game.js fails 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’s reuse-ship-check.cjs (check ship-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 reads reuse: unverified (...) / reuse: no data, never an implied pass. It runs in mode report and never blocks a delivery.

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

  4. Client loop (references/client-loop.md). Before the first build reaches a client: the ## Sign-off block is recorded (reference, bar, viewports, networks, store link, and the client’s OWN baseline or none-searched); the first build they see is the polish-bar-green milestone build; and the ask goes out as numbered items each tagged bug / taste / scope-change. A scope-change is 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.

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

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

CodeMeaningAction
0okcontinue
2usage (bad flag, bad snowflake, non-SSH repo, unknown subcommand)fix input, rerun
6gh or git error (create, clone, push)report the stderr
7stop-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).

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

StepAgent
Run deliver.cjs, tabulate the JSONt1k-data-verifier
Thread find/create, triggerBuild, user questionsmain session (MCP + user)
Watch the build to a verdict (status only)t1k-ci-watcher
Judge a red build or a packer faultt1k-playablelabs-base-packer-engineer