t1k:cocos:playable:pipeline
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | medium |
| Tools | — |
Keywords: board, client project, deliverable, git repo, log tasks, module, playable build, playable jenkins, playable pipeline, playable plane, playable work item, provision repo, task tree, tracking
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:pipeline<report-or-breakdown | --brief <text>> [--client <name>] [--project <name>] [--playable <name>] [--no-jenkins] [--provision-repo] [--dry-run]Cocos Playable — Plane + Jenkins Pipeline
Section titled “Cocos Playable — Plane + Jenkins Pipeline”One playable becomes one Plane module under its client’s project, holding the whole task
tree, plus a build-and-deliver handoff (t1k:playablelabs:ci:deliver). This skill wires those together from a source
document that already exists — an agreed task breakdown, or a
t1k:cocos:playable:preproduction estimate report — or from the {client, project, brief} handoff
of core’s one-prompt router t1k:playable-start (see One-prompt entry).
Orchestrator only. Every Plane lifecycle mechanic — binding, state resolution by group,
guarded writes, the 4-hour leaf cap, degrade-never-block — is owned by core’s
theonekit-core/.claude/skills/t1k-plane/references/workflow-enforcement.md and
theonekit-core/.claude/skills/t1k-plane/references/binding.md. Every Jenkins
config.xml mechanic is owned by theonekit-core/.claude/skills/t1k-jenkins-job/SKILL.md. This skill cites them and
adds only the three things neither can know: the studio hierarchy convention, the required-task set
for a playable, and the hand-off between the two systems.
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “Log this estimate report to Plane” | Workflow steps 1-4, then --no-jenkins |
| “Set up the full pipeline for this playable” | Workflow, all steps |
| “Does this module have everything it needs?” | Step 4 alone — see task-template.md (references/task-template.md) |
| “Just build and deliver” | Skip to step 5 (hands off to t1k:playablelabs:ci:deliver) |
Router handoff {client, project, brief}, no estimate report | One-prompt entry |
| “Create the actual git repo for this playable” | Step 6 — repo-provisioning.md (references/repo-provisioning.md). Playable already has a repo? Skip step 6 |
| “Why is the title format like that?” | hierarchy-contract.md (references/hierarchy-contract.md) |
Prerequisites
Section titled “Prerequisites”| Need | Check | If missing |
|---|---|---|
| Plane MCP | mcp__plane__* tools loaded | ~/.claude/skills/t1k-mcp-management/scripts/install-plane.sh — prompts for the key with hidden input, so the user runs it, then restart Claude Code |
| Deliver skill (step 5) | t1k:playablelabs:ci:deliver installed (theonekit-playablelabs) | Install that kit, or pass --no-jenkins to skip delivery. Jenkins creds and the Discord thread are deliver’s concern, not this skill’s |
| A source document | An estimate report, an agreed breakdown in-conversation, or a router {client, project, brief} | None of these: run t1k:cocos:playable:preproduction on the brief first — do not invent a task list |
| Repo provisioning (optional step 6) | gh + git on PATH, gh auth status ok | repo-provisioning.md (references/repo-provisioning.md) — parent-dir prompt required first run |
Plane absent is not fatal — core’s degrade rule applies unchanged: warn once and continue. A delivery run with no Plane tree is still a valid partial outcome; say so explicitly rather than reporting success.
Delegation — the main session orchestrates, it does not do the work
Section titled “Delegation — the main session orchestrates, it does not do the work”This skill’s inputs are large (a 350-line estimate report) and its writes are numerous (30+ work
items). Reading and performing all of that inline burns the main session’s
context on material it never needs again. Default to delegating every step below that is marked
fork; keep inline only what genuinely needs the conversation.
| Step | Where | Why |
|---|---|---|
| 1 Bind | inline | One status call plus a judgment about the project. Cheap. |
| 2 Read the source document | fork → Explore | The report is the single biggest context cost in the skill. Return the § 9 line-item table as JSON, not prose, and never the report body. |
| 3a Derive the tree | fork → Explore | Splitting rows to the 4h cap and reconciling against the report total is deterministic arithmetic over step 2’s JSON. |
| 3b The ONE confirmation | inline, always | Core requires the user see the whole tree before any write. A fork cannot ask. |
| 3c Write the tree | fork → t1k-fullstack-developer (generic on purpose: Plane API writes, no Cocos code, so no engine role applies; any Cocos code fork uses implementer / feature-implementer per t1k-cocos-base-agent-domain-routing) | Bulk API writes. See the MCP warning below — the fork must drive Plane’s REST API, not mcp__plane__*. |
| 4 Required-task check | fork → Explore | A set comparison against task-template.md (references/task-template.md). Read-only. |
| 5 Deliver | inline handoff | Invokes t1k:playablelabs:ci:deliver, which builds on the shared PlayablePacker job and owns the Discord thread. Nothing to ask here. |
| 6 Provision repo (optional) | inline for the parent-dir prompt and any conflict/existing-repo stop; the run/plan call itself may be forked | Preflight, the parent-dir choice and merge-conflict handling are unresolved-decision points; the git/gh calls are deterministic. |
| 7 Link back | inline | One comment and one URL. |
Two separate savings: forking protects the main session, cheap routing depends on the floors. Detail, the Explore lane and the mr-delegate.sh note: references/delegation-economics.md.
The hierarchy
Section titled “The hierarchy”workspace cocos <- the engine project <Client> <- the CLIENT (publisher / partner) module <Playable> <- the PLAYABLE (the deliverable) work item <Client> | <Playable> | <task> work item <Client> | <Playable> | <task>This is core’s documented deliverable convention (binding.md § “What each hierarchy level
means”), under which the module binding is REQUIRED, not optional — a repo bound to the project
alone is a mis-binding, because every item then lands on the whole client’s board with nothing
identifying which playable it belongs to.
The Client | Playable | Task title is a studio deviation from core’s [Discipline][Kind] Title
taxonomy. It is deliberate, it is recorded, and it has a cost. Read
hierarchy-contract.md (references/hierarchy-contract.md) before changing it.
Phase parents carry the prefix too — <Client> | <Playable> | First Build, not a bare
First Build. Both spellings exist on the board today; the prefixed one is the convention this
skill composes.
The separator changed from brackets to pipes on 2026-08-22. This skill used to compose
[Client][Playable] Task was the old form. The live board holds three forms and none is ever renamed. Details: references/hierarchy-contract.md § “Separator history”.
Workflow
Section titled “Workflow”Steps 2, 3a, 3c and 4 are forked by default — see Delegation for which agent and why. Doing them inline is the exception, and worth a sentence saying why.
-
Bind the repo.
bun $HOME/.claude/scripts/t1k-plane-binding.cjs status. Unbound → run core’sbinding.md§ “Repo → project” resolution. Two Cocos-specific notes:- Score projects against the client name, not the repo name. A repo called
blast-festscores near-zero against a project calledRollic, and that is the convention working, not a missing project. Never create a project to fix a low score — the client already exists. - The module is the playable. Missing → creating one is the right guarded write far more often than creating a project.
- Score projects against the client name, not the repo name. A repo called
-
Read the source document — fork to
Explore; return the § 9 table as JSON, never the report body. An estimate report’s line-item table (preproduction § “Estimate — full line-item breakdown”) is the tree, already carrying per-row hours. A conversation breakdown is the tree as agreed. Never synthesise tasks that appear in neither. Mapping rules:report-ingest.md(references/report-ingest.md). -
Build the work-item tree — 3a derive and 3c write are forked; the confirmation between them is not. Core owns this entirely —
workflow-enforcement.md§ Stage 1 and § “Decomposition”. Do not reimplement the 4-hour leaf cap, the parent-carries-no-estimate rule, theget_me()assignment, or the one-confirmed-batch presentation. Compose each title with:Terminal window bun .claude/skills/t1k-cocos-playable-pipeline/scripts/pipeline-title.cjs compose \--client '<project name>' --playable '<module name>' --title '<task>'Pass the module name exactly as the board has it —
compose()derives the playable segment itself, stripping a leading<client> |where a board uses one and passing a bare name through. Both live shapes therefore work unchanged;hierarchy-contract.md§ “Why pipes” records the measured distribution. Single-quote every argument:<task>is report-derived text, and inside double quotes a title containing$(…)or a backtick would be executed by the shell.Core’s
t1k-plane-taxonomy.cjs composeis still called — for itslabelsoutput only. The title it returns is discarded. Seehierarchy-contract.md(references/hierarchy-contract.md). -
Verify the required-task set — fork to
Explore. Compare the module’s work items againsttask-template.md(references/task-template.md): the five-item phase skeleton, then the build packages underFirst Build. Only2/2rows count as missing —1/2rows are surfaced as consider, never as a gap. Report them; propose, never auto-create — the same rule core applies to work items applies here. -
Deliver — hand off, do not build the job here. Invoke
t1k:playablelabs:ci:deliver(theonekit-playablelabs) with:--client <client> --project <PascalName> --engine-host cocos-3.8 --game-repo <ssh url from step 6> --branch develop --game-dir <local clone of that repo at the commit to build>--projectis the playable’s PascalCase name (deliver rejects anything else);--clientis the Plane client project.--game-repois the SSH URLprovision-repo.cjsprinted (step 6), or the playable’s existing repo when step 6 was skipped.--game-diris required by deliver. Deliver owns the build on the sharedCocosPlayableLabs/PlayablePackerjob and the Discord thread — it creates the thread, so this skill never asks the user for a thread ID.--no-jenkinsskips this step entirely. Deliver absent: say so and stop at the Plane tree; do not fall back to hand-building a job. -
Provision the repo — OPTIONAL, off by default; skip it whenever the playable already has a repo.
scripts/provision-repo.cjs plan|run --playable '<name>' --parent-dir '<dir>'creates<org>/<Name>PLAfromPlayableAdsTemplatewith realmain+develophistory, runsSetupProject.baton Windows, commits the result. Ask for (and persist) the parent dir; never auto-resolve a conflict or existing-repo hit. This script already lands onmaincorrectly — the hazard is a handgit cloneof the template done outside this step; seerepo-provisioning.md(references/repo-provisioning.md) § “Hand-cloning the template”. -
Link back.
create_work_item_commenton the module’s parent work item with the job URL deliver reports, and hand the user a clickable Plane link built witht1k-plane-binding.cjs url --work-item <uuid>— no Plane tool returns a URL, and a bareROLLIC-289is not clickable.
One-prompt entry (from t1k:playable-start)
Section titled “One-prompt entry (from t1k:playable-start)”Core’s router hands off {client, project, brief}. This is a valid source document, so no estimate
report is required. Run in this order (step numbers refer to Workflow):
- Step 1 (bind) with
projectas the client project. - No estimate report → run
t1k:cocos:playable:preproductionon the brief; its report feeds steps 2-4 unchanged. - Step 6 — repo provisioning (
scripts/provision-repo.cjs), needed here because the game repo does not exist yet. - Implementation:
t1k:cocos:playable:genscaffolds from the brief, thent1k:cook. - Step 5 — deliver, with the repo from step 3.
Plane steps (1-4, 7) are unchanged.
Executed by
Section titled “Executed by”Title composition and repo provisioning are scripts; the skill is an orchestrator. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run pipeline-title.cjs compose and provision-repo.cjs and report the output | t1k-fact-fetcher |
| Build the work-item tree | stays with the orchestrating skill/user — gated Plane writes |
Hard rules
Section titled “Hard rules”- A routed fork has NO MCP servers — so a fork cannot call
mcp__plane__*at all.mr-delegate.shlaunches the hop with--strict-mcp-config --mcp-config '{"mcpServers":{}}'(verified in the shipped script, not inferred from docs), which strips every server including Plane and Jenkins. A brief that says “create the work items withcreate_work_item” therefore fails inside a routed hop while working perfectly when you test it inline. Drive Plane from a fork through its REST API —POST {base}/api/v1/workspaces/{slug}/projects/{id}/issues/with anx-api-keyheader, credentials read from theplaneentry of~/.claude.json. (Deliver is not driven from a fork.) - Prefer one REST script over N MCP calls even inline. Reasons (round-trips, dry-run, reconciliation, read-back):
references/rest-over-mcp.md. PLANE_WORKSPACE_SLUGmay hold a full URL rather than a slug. On at least one machine it ishttps://plane.the1studio.org/cocos/. The MCP server normalises it internally, so the misconfiguration is invisible through the tools and only bites a script that builds the API path itself. Take the last non-empty path segment rather than using the value raw.titleFormatcannot be configured to do this. Core’s parser is the exact inverse of itscompose(), so the prefix is composed by this skill’s own script:references/hierarchy-contract.md§ “Title-composition traps”.- Never append
[3D][Feature]after the scope to “get both”. Core’sparse()reads tokens only at the start of the string, soRollic | Blast Fest | [3D] Xreturnskind:null, discipline:null— the scope prefix blinds core to the taxonomy tokens that follow. The pipe change did not fix this; it is a scope-first problem, not a bracket problem. Measured, with the full table, inhierarchy-contract.md(references/hierarchy-contract.md). Kind and discipline belong in labels. - Turning
taxonomy.enabled: falseto get the title you want also kills the labels. Stage 1 steps (a), (b), (c) and (e) are all skipped together. Labels are the only thing left carrying kind/discipline once the prefix is gone — keep the taxonomy enabled and discard only its title. applyTo: "created-only"still holds. An item this skill matched is never renamed into the scope convention. An inconsistent board is a smaller failure than renaming a teammate’s item.- A low project score is the convention, not an error. See step 1.
- The estimate report’s hours are per line item, not per leaf. A 6-hour row is an undecomposed leaf under core’s cap — split it before writing any estimate, never write the 6.
- Estimate-report tasks and required-template tasks overlap but are not the same set. The report covers what was quoted; the template covers what every playable ships. Reconcile both, and report anything present in one and absent from the other.
- Step 6 is optional and off by default — a playable on an existing repo never runs it. When it
does: the clone dir MUST be
<parent>/<Name>PLAexactly (SetupProject.batreads its own folder name); an existing target repo, a non-ancestor templatedevelop(preflight), or adevelopmerge conflict is a hard stop; non-Windows skips setup.
Binding a Cocos playable repo to its Plane client-project + playable-module, turning an existing
breakdown or estimate report into the module’s work-item tree under the studio title convention,
checking that tree against the required-task set, and handing the playable to
t1k:playablelabs:ci:deliver for build and delivery. Not for: producing the breakdown itself (t1k:cocos:playable:preproduction), Plane
lifecycle mechanics (t1k:plane), Jenkins/Discord mechanics (t1k:playablelabs:ci:deliver), triggering or
watching builds, or any per-phase state transition during the cook (core’s Stage 2 already owns it).
Related
Section titled “Related”See references/related.md.