Skip to content

t1k:cocos:playable:project-info

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: anchor-guard, canonicalName, checkpoints init, cocos playable-ad, jenkins job, missing project-info, plane work item, project-info.json

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

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

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:

KeyRead byAbsent means
project.cocosDirt1k-cocos-base-editor-mcp-truth, t1k-cocos-playable-build-sizefall through to the Cocos*-prefix disk scan
paramTestGate (top level)cocos-param-gate-verify.cjsthe 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.)

  1. Anchor check. git rev-parse --show-toplevel. Read project-info.json there if present — report which fields are already set and only resolve what’s missing, unless the user asked for a full re-resolve.

  2. git.repo — git remote get-url origin, strip to Owner/Repo.

  3. Jenkins jobs — mcp__jenkins__findJobsWithScmUrl on 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__getJobScm to 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.
  4. 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_items per job name, workspace cocos.

    • Work items are titled <Client> | <Playable> | <task>.
    • search_work_items is 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" returns Matchingham | Animal Hunter Wild | … → AnimalHunterPLA’s client is Matchingham.
    • 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.”
  5. AskUserQuestion for:

    • canonicalName — never auto-fill from the folder/branch/package name. audit-naming.cjs:10 GRADES the repo directory, branch, and package name against canonicalName — 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 with git.repo’s basename and the Jenkins job name (AnimalHunterPLA in § Target Schema), never the Cocos-prefixed Cocos project directory (CocosAnimalHunterPLA). The Cocos directory is derived from it, Cocos<canonicalName>, not the other way round: checkpoints-init.cjs writes expected.cocosDir/expected.packageName as 'Cocos' + canonicalName.replace(/^Cocos/, '') but expected.scriptNamespace as the bare canonicalName — so a prefixed canonicalName makes the script-namespace check compare assets/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 the Cocos prefix 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 discipline checkpoints-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.
  6. 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-local scripts directory under .claude if it holds a t1k-checkpoints.cjs file at the git toplevel, else the global scripts directory 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 — null is the honest answer, and a fabricated one is indistinguishable from a confirmed one downstream. --jenkins-jobs takes 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_PATH is the resolved directory joined with the t1k-checkpoints.cjs filename.

    This writes project.engine/type/canonicalName/client/naming/git/jenkins/plane directly into project-info.json — every one of those keys, always, with the flags you did not pass landing as their empty leaf (§ Target Schema) — plus the p10 naming/plane/sweep config blocks into checkpoints.config.json. Never pass --force unless the user explicitly asked to overwrite an existing file.

  7. Read back project-info.json and 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.

  • Search Plane by Jenkins job name, never by repo name. A prior attempt searched by repo name and mis-assigned PixelBallFlowPLA → Joybit off a work item titled “Food Flow: Pixel Hunt PLA 1” — but getJobScm proves that playable actually builds from HexaBugFlowPLA.git on 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.
  • findJobsWithScmUrl NPEs 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.)
  • canonicalName is 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 init DOES accept --git-repo/--jenkins-*/--plane-* flags — pass every resolved value through in the single step-6 invocation rather than hand-merging project-info.json afterward. project.plane is read: t1k-plane-binding.cjs’s resolveBinding() prefers it over the legacy .claude/plane-bindings.json when either projectId or moduleId is 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/*.cjs only and missed the reader in scripts/.
  • A missing key is not the same as a null key. The schema writes every canonical key on every run, so an absent client in a file this skill wrote means the file predates the current shape — not that the value is unknown. Re-run init rather than hand-adding the key.

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.