t1k:cocos:playable:project-info
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: anchor-guard, canonicalName, checkpoints init, cocos playable-ad, jenkins job, missing project-info, plane work item, project-info.json
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:project-info(no arguments — run inside the target repo's git toplevel)Cocos Playable-Ad — project-info.json Resolver
Section titled “Cocos Playable-Ad — project-info.json Resolver”Resolves the fields t1k-checkpoints.cjs init cannot reach on its own (Jenkins job/branch, Plane
client) via MCP, confirms the rest with the user, then writes project-info.json at the git
TOPLEVEL (not inside the Cocos*/ project dir).
Why This Is a Skill, Not CLI Code
Section titled “Why This Is a Skill, Not CLI Code”t1k-checkpoints.cjs init is plain Node with no MCP access — it can gather evidence from disk
(package.json, git remote, folder names) but cannot query Jenkins or Plane. A Claude session run
as this skill CAN reach mcp__jenkins__* and mcp__plane__*. That gap is the entire reason this
is a skill and not more CLI code (theonekit-core/.claude/modules/t1k-engineering/rules/ai-driven-design.md).
Target Schema
Section titled “Target Schema”Every canonical key is always present, in every project, in this order. A value this session
did not resolve is written as its empty leaf — null for a scalar, [] for a collection.
There is no “omit until confirmed”: that was the status quo this shape removes, and it is what
made two projects’ files structurally incomparable.
{ "project": { "engine": "cocos", "type": "playable-ad", "canonicalName": "AnimalHunterPLA", "client": "Matchingham", "git": { "repo": "The1Studio/AnimalHunterPLA" }, "jenkins": { "jobs": [ { "folder": "CocosPlayableLabs", "name": "AnimalHunterPLA", "branch": "main" } ] }, "plane": { "workspaceSlug": "cocos", "projectIdentifier": "MATCHING", "projectName": "Matchingham", "projectId": "7a7ffdce-1a10-4f8b-b321-51e55c8b122a", "moduleId": null, "moduleName": null }, "naming": { "staleTokens": ["PlayableAdsTemplate","TemplateProject","CocosPlayableAdsTemplate"], "protectedTerms": [] }}}engine/type are always the literals above — this skill passes them on every run. Every other
canonical key below project can come back empty, and the file then reads:
{ "project": { "engine": "cocos", "type": "playable-ad", "canonicalName": null, "client": null, "git": { "repo": null }, "jenkins": { "jobs": [] }, "plane": { "workspaceSlug": null, "projectIdentifier": null, "projectName": null, "projectId": null, "moduleId": null, "moduleName": null }, "naming": { "staleTokens": [], "protectedTerms": [] }}}null is the honest answer for “not resolved” — never guess one from the folder name
(theonekit-core/.claude/modules/t1k-base/rules/agent-anti-rationalization.md). jenkins.jobs[] entries carry all three keys
(folder, name, branch) or do not exist.
State blocks are exempt but shape-pinned — they are per-project state written by other
systems, never conjured into a project that has no such state, and their key sets are fixed:
project._checkpointsStatus and the top-level paramTest block (written by
tools/ci/stamp-param-test.cjs, and read by Jenkins to gate the dashboard publish).
Opt-in keys are legal, and are never written by this skill — a third category beside the
canonical set and the state blocks. An opt-in is a documented, hand-authored override: LEGAL
when present, shape-checked when present, never conjured, and never in required. There are
two:
| Key | Read by | Absent means |
|---|---|---|
project.cocosDir | t1k-cocos-base-editor-mcp-truth, t1k-cocos-playable-build-size | fall through to the Cocos*-prefix disk scan |
paramTestGate (top level) | cocos-param-gate-verify.cjs | the parameter-gate checkpoint is simply not adopted |
Neither is part of the identity set, so neither breaks “every project carries the same fields” — an opt-in is by definition not carried by every project. Do NOT add either one here; a project declares it by hand when it adopts the mechanism. An opt-in BLOCK does not require its own keys (its reader defaults them), but an unknown key inside it is still rejected.
t1k-checkpoints.cjs init accepts --git-repo, --jenkins-folder/--jenkins-jobs, and six
--plane-* flags (--plane-workspace-slug, --plane-project-identifier, --plane-project-name,
--plane-project-id, --plane-module-id, --plane-module-name) alongside
--engine/--type/--canonical-name/--client/--stale-tokens — it writes ALL of
project.engine/type/canonicalName/client/naming/git/jenkins/plane in one pass, in the § Target
Schema shape: a flag you do not pass leaves that key’s empty leaf, never a missing key. The CLI
itself has no MCP access to discover the Jenkins/Plane values (that gap is this skill’s whole
reason to exist, per the section above), but once this session has resolved and confirmed them, it
passes every field through as flags rather than writing project-info.json a second time by hand.
The plane block IS read, and is now the PREFERRED binding source. ~/.claude/scripts/t1k-plane-binding.cjs’s resolveBinding() calls
readProjectInfoPlaneBinding(projectRoot), which reads project.plane first and reports
source: 'project-info.json'; the legacy .claude/plane-bindings.json is consulted only when the
block is absent or names neither projectId nor moduleId (nothing to bind to). It resolves a
binding only when at least one of those two ids is set — all-null plane keys are correctly a
no-op, not a half-binding. (git/jenkins have no reader this skill knows of; this note is about
plane specifically, and it replaced an earlier claim that nothing read these blocks at all.)
Workflow
Section titled “Workflow”-
Anchor check.
git rev-parse --show-toplevel. Readproject-info.jsonthere if present — report which fields are already set and only resolve what’s missing, unless the user asked for a full re-resolve. -
git.repo—git remote get-url origin, strip toOwner/Repo. -
Jenkins jobs —
mcp__jenkins__findJobsWithScmUrlon that remote URL.- An NPE from this call means “cannot enumerate” (a matching job has zero builds —
jenkinsci/mcp-server-plugin#251), not “no jobs exist.” A clean empty result instead reads
"no results were found". Do not report an NPE as “this repo has no Jenkins jobs.” - For every job found, call
mcp__jenkins__getJobScmto get its actual branch — never assume the default branch. Jobs span multiple folders (CocosPlayableLabs,TestPipeline, …) — folder and branch are per-job, record both per entry. - A repo can legitimately host jobs for several playables on different branches — report every job, never collapse to one.
- An NPE from this call means “cannot enumerate” (a matching job has zero builds —
jenkinsci/mcp-server-plugin#251), not “no jobs exist.” A clean empty result instead reads
-
Plane client — search by the resolved Jenkins JOB NAMES, never by the repo name. Repo names and playable names diverge, and one repo can host several playables. Query
mcp__plane__search_work_itemsper job name, workspacecocos.- Work items are titled
<Client> | <Playable> | <task>. search_work_itemsis a plain substring match despite its description, and caps at 10 results — ten hits means “at least ten,” not “exactly ten.”- Calibration reference: searching
"Animal Hunter"returnsMatchingham | Animal Hunter Wild | …→AnimalHunterPLA’s client isMatchingham. - A repo may legitimately have MULTIPLE clients (it hosts playables for different ones on different branches). Report all matches found; never silently collapse to one guess.
- Plane rate-limits under burst and answers 404 on reads — this is not a server outage. Throttle (small delay between calls) and retry once before treating a 404 as a real miss; never escalate a burst-404 to “Plane is down.”
- Work items are titled
-
AskUserQuestionfor:canonicalName— never auto-fill from the folder/branch/package name.audit-naming.cjs:10GRADES the repo directory, branch, and package name againstcanonicalName— it deliberately never trusts them, and on a re-checkout all three point the same wrong way at once. Present them as evidence, not a default. Which of the two directory names it is (#1014b): the BARE identity token — the one shared withgit.repo’s basename and the Jenkins job name (AnimalHunterPLAin § Target Schema), never theCocos-prefixed Cocos project directory (CocosAnimalHunterPLA). The Cocos directory is derived from it,Cocos<canonicalName>, not the other way round:checkpoints-init.cjswritesexpected.cocosDir/expected.packageNameas'Cocos' + canonicalName.replace(/^Cocos/, '')butexpected.scriptNamespaceas the barecanonicalName— so a prefixedcanonicalNamemakes the script-namespace check compareassets/scripts/<bare>against<prefixed>and go permanently RED. When the repo directory and the Cocos directory carry the same name, that name is the bare one and theCocosprefix only exists in the Cocos directory’s own name.client— always, even when exactly one Plane match was found (agreement across sources is weak evidence, never proof — same disciplinecheckpoints-init.cjs’s own evidence model uses). When multiple distinct clients were found across jobs, list all of them and ask which one(s) apply to this repo.
-
Invoke the CLI once, passing every resolved field as a flag. Resolve the script path the same way
cocos-checkpoints-anchor-guard.cjs#initScriptPath()does — the project-localscriptsdirectory under.claudeif it holds at1k-checkpoints.cjsfile at the git toplevel, else the globalscriptsdirectory under$HOME/.claude(same filename). Pass a flag only for a value this session actually resolved: leaving one out is how you say “not found”, and the CLI fills that key with its empty leaf (§ Target Schema). Never pass a placeholder (--client "unknown",--plane-project-id "") to manufacture a non-null —nullis the honest answer, and a fabricated one is indistinguishable from a confirmed one downstream.--jenkins-jobstakes a comma-separated list of[folder|]name[@branch]entries.Terminal window bun "$SCRIPT_PATH" init --yes \--engine cocos --type playable-ad \--canonical-name "<confirmed canonicalName>" \--client "<confirmed client>" \--stale-tokens "<comma-separated staleTokens>" \--git-repo "<owner/repo>" \--jenkins-jobs "<folder|name@branch>,<folder|name@branch>" \--plane-workspace-slug "<slug>" \--plane-project-identifier "<identifier>" \--plane-project-name "<name>" \--plane-project-id "<uuid>"$SCRIPT_PATHis the resolved directory joined with thet1k-checkpoints.cjsfilename.This writes
project.engine/type/canonicalName/client/naming/git/jenkins/planedirectly intoproject-info.json— every one of those keys, always, with the flags you did not pass landing as their empty leaf (§ Target Schema) — plus the p10naming/plane/sweepconfig blocks intocheckpoints.config.json. Never pass--forceunless the user explicitly asked to overwrite an existing file. -
Read back
project-info.jsonand report its final content to the user — this is a verification read, not a second write. If a field this session resolved is missing from the file, the flag was mistyped or omitted in step 6; re-run with it corrected rather than hand-editing the JSON.
Hard rules
Section titled “Hard rules”- Search Plane by Jenkins job name, never by repo name. A prior attempt searched by repo name
and mis-assigned
PixelBallFlowPLA → Joybitoff a work item titled “Food Flow: Pixel Hunt PLA 1” — butgetJobScmproves that playable actually builds fromHexaBugFlowPLA.giton branch*/FoodHuntPLA. Wrong repo, wrong client, and the correct repo (HexaBugFlowPLA) was simultaneously reported as “no match” because nobody had searched its actual job name. findJobsWithScmUrlNPEs on any zero-build matching job (upstream bug) — treat as “cannot enumerate,” not “no jobs.” (§ Workflow step 3.)- Plane burst → 404 is a rate limit, not an outage. (§ Workflow step 4.)
canonicalNameis graded, never trusted, from disk signals. (§ Workflow step 5.)- A repo hosting multiple playables/clients is normal — never collapse to a single guess.
t1k-checkpoints.cjs initDOES accept--git-repo/--jenkins-*/--plane-*flags — pass every resolved value through in the single step-6 invocation rather than hand-mergingproject-info.jsonafterward.project.planeis read:t1k-plane-binding.cjs’sresolveBinding()prefers it over the legacy.claude/plane-bindings.jsonwhen eitherprojectIdormoduleIdis set (§ Target Schema). An earlier revision of this bullet claimed no checkpoints code read these blocks at all; that was measured against.claude/hooks/lib/*.cjsonly and missed the reader inscripts/.- A missing key is not the same as a null key. The schema writes every canonical key on every
run, so an absent
clientin a file this skill wrote means the file predates the current shape — not that the value is unknown. Re-runinitrather than hand-adding the key.
Executed by
Section titled “Executed by”Runs inline in the main session — MCP tool access (mcp__jenkins__*, mcp__plane__*) and
AskUserQuestion are session-scoped; a spawned sub-agent would need the same MCP servers granted
separately and cannot itself call AskUserQuestion back to the user mid-task. Not delegated.