t1k:cocos:playable:modularize
| Field | Value |
|---|---|
| Module | playable |
| Version | 4.33.13 |
| Effort | high |
| Tools | — |
Keywords: cpm-package, modularize, playablelabs
How to invoke
Section titled “How to invoke”/t1k:cocos:playable:modularize[phase0|structure-audit|reuse-scan|refactor|contribute] [<project-root>] [--apply] [--continue] [--implement] [--force-manual-queue] [--attended] [--iterate] [--max-iterations N]t1k-cocos-playable-modularize
Section titled “t1k-cocos-playable-modularize”Main goal: refactor/reuse/modularize the PROJECT itself — grade its structure, use the CPM library
lookup to find tested @playablelabs/* packages that replace embedded source, and migrate the project
to consume them. Contributing novel code back is a smaller, optional follow-on. Documentation-only
orchestration — this file describes a 4-phase pipeline; there is no runtime skill-spawning. Each
sub-skill runs standalone or in sequence.
When to invoke
Section titled “When to invoke”- Establish or verify the architecture target before anything else → Phase 0 (docs/system-design.md).
- Grade a project’s layout against the canonical playable-ad structure →
structure-audit. - Look up the CPM library for existing tested packages that duplicate local code + suggest install →
reuse-scan. - Produce an ordered plan to migrate embedded framework source → CPM packages →
refactor. - (Optional) Separate a novel local subsystem into a real
@playablelabs/<name>package →contribute. - Run the whole thing end-to-end → the four in order (audit → reuse → refactor → optionally contribute).
- Run it hands-off → a bare
t1k-cocos-playable-modularize <project-root>(Mode A: every phase, zero questions, ends on the reports + docs + plan +reports/IMPLEMENT.md), then--implement(Mode B) in a fresh session to execute the plan. See § “Unattended”.
Pipeline
Section titled “Pipeline”| # | Sub-skill | Pillar | Output |
|---|---|---|---|
| 0 | t1k-cocos-base-system-design + t1k-cocos-base-architecture-patterns (Phase 0) | — design baseline | probe-design-doc.cjs runs first — does the doc describe THIS project at all? Then docs/system-design.md authored --state as-is or audited for drift — from the project’s template, or system-design’s verbatim vendored blank if the project ships none. Everything below is graded against it. Plus the architecture-audit JSON (SOLID/pattern/enabling-extraction findings) that feeds pillar C. |
| 1 | t1k-cocos-playable-modularize-structure-audit | A — structural conformance | Per-rule CONFORMANT / DRIFT / MISSING vs the vendored blueprint.md + a normalization plan. |
| 2 | t1k-cocos-playable-modularize-reuse-scan | B — reuse | Per-subsystem REUSE / EXTEND / KEEP / CONTRIBUTE via two-source library lookup (knowledge MCP + CPM registry). It NAMES the package to install; pillar C’s Tier 1.5 performs the install with install-package.cjs, so a REUSE verdict now reaches an executable step instead of stopping at a suggestion. |
| 2.5 | t1k-cocos-playable-preproduction (refactor mode) — runs automatically in Mode A | — design target | docs/system-design.md rewritten --state to-be: the modules this system should have. Inputs are the as-is doc + the architecture audit + the reuse verdicts — not a spec. Module slicing only; the WP costing pass is skipped unless a number was asked for. This is the phase that makes pillar C a diff instead of a violation list. |
| 3 | t1k-cocos-playable-modularize-refactor | C — project-first | Ordered project refactor plan: outdated-package upgrades → folder-norm → INSTALL missing packages (Tier 1.5) → REUSE swaps → SOLID/pattern refactor + enabling extractions → MECHANIC SLICE the design doc’s modules into vertical folders (Tier 2.6) → second REUSE pass → embedded-submodule→CPM migration → tag CONTRIBUTE. No package splitting. Two tiers delegate rather than reimplement: Tier 2.6 → t1k-cocos-playable-mechanic-split (invoked --mechanics-from docs/design-manifest.json, so boundaries come from the design doc and never from a coupling audit re-run there) and Tier 3 → t1k-cocos-playable-submodule-to-package. |
| 4 | t1k-cocos-playable-modularize-contribute | D — contribute (optional) | ADD a novel subsystem as a new @playablelabs/<name> package, or UPDATE an existing package with a local fix/extension (+ version bump). Plain readable TS; dev decides publish (manual/AI). Never publishes. |
Dependencies — which phases actually need the design doc, and which merely read better with it:
| Phase | Needs docs/system-design.md? | Why |
|---|---|---|
| 0 | produces it | — |
1 structure-audit | No — not a gate | Grades folders against the pinned blueprint. It never reads the doc’s content; its R9 rule only checks the file exists. Runs standalone on a project with no doc. |
2 reuse-scan | No — not a gate | Grades local subsystems against upstream packages. Independent of the project’s own architecture target. |
2.5 preproduction (refactor mode) | Consumes it — and rewrites it | Reads the as-is doc as its baseline and emits the to-be target over it. Also needs the architecture audit (what is wrong) and 2’s report (what a package will delete). |
3 refactor | Yes — ENFORCED precondition | Tier 2.5 is graded against the doc’s § Code Structure Rules. Planning without it measures against nothing. plan-refactor.cjs --design-probe now withholds Tiers 2.5/2.6/2.75 (blockers[], per-step blockedBy) until the probe verdict is ok. Also needs 1+2’s reports, and 2.5’s manifest for designState. |
4 contribute | No — needs 3 landed, except UPDATE mode unblocking a Tier 2 EXTEND unit (decision-policy § Rule 1) | ADD extracts from an already-healthy project. UPDATE ports an existing local improvement into the package’s upstream source repo, so it may run mid-walk. |
The architecture audit (Phase 0’s second output) has the same hard dependency as 3, for the same reason. Run Phase 0 first regardless — it is cheap, it is the only phase that can author the baseline, and 3 is the phase the whole pipeline exists to reach. But do not report 1 or 2 as blocked on it: they are not, and treating them as blocked is what makes operators skip the pipeline entirely on a repo with no doc. Full ordering + gates live in each sub-skill body.
“The doc exists” is not “the doc is ours” — probe before planning
Section titled ““The doc exists” is not “the doc is ours” — probe before planning”The single highest-risk state this pipeline can be in is a docs/system-design.md inherited
verbatim from another project — typically PlayableAdsTemplate’s own doc, committed at the repo’s
initial commit and never rewritten. It defeats every other check here by construction: pillar 1’s R9
rule only asks whether the file EXISTS, pillars 1 and 2 never read its content at all, and
generate-manifest refuses it for a missing state: — a failure that surfaces downstream only as
the generic designState: null. Nothing anywhere asked whose project the doc was about.
Phase 0 therefore starts with a probe, and its verdict gates the design-dependent tiers:
bun <system-design>/scripts/probe-design-doc.cjs docs/system-design.md <repo-root> > reports/design-probe.json# exit 0 = ok · 1 = repair required (absent | template-verbatim | template-unfilled |# foreign | non-canonical | indeterminate)A non-ok verdict means repair the doc to describe this project, then re-probe — it is never
“note it and continue”. The verdict names its own repair; foreign and non-canonical are repaired
by authoring the as-is doc from the code (system-design Step 0a, or migrate-design-doc.cjs
for a doc that is merely off-template).
Phase 0 ends on the SECOND probe, not the first. Re-run it after the repair and require ok;
that re-run is the only part of the step that can fail, and re-planning against the pre-repair
design-probe.json reproduces the defect with a repair step in the transcript to make it look
handled. In Mode A this is automatic for every repairable verdict — which is all of them except
indeterminate, whose identity check has no input to repair from
(references/decision-policy.md rule 9).
What the gate does and does not withhold. Pass reports/design-probe.json to
plan-refactor.cjs --design-probe; while the verdict is not ok it emits blockers[] and marks
every Tier 2.5/2.6/2.75 step blockedBy. Tiers 0/1/2/3/4 stay free, the report still prints in full,
and the exit code stays 0. That scoping is deliberate: version bumps, folder normalization and
import repoints are graded by no design doc, and a gate that refuses the whole pipeline on a legacy
repo is one operators route around — after which it protects nothing.
Phase 0 is the baseline; phase 2.5 is the target. They are two tenses of one artifact, and
running only the first is the pipeline’s default failure: pillar C then plans against
designState: null — neither toward a documented target nor away from a documented baseline. The
audits tell you what is wrong; only 2.5 decides what modules this system has. Skipping it does
not produce a smaller refactor, it produces one whose boundaries land wherever the split test
happened to cut.
Phase 0 is a service call, not step zero
Section titled “Phase 0 is a service call, not step zero”t1k-cocos-base-system-design owns the design artifact and is invoked by whichever entry
point needs it — which is not always this pipeline, and not always at the start. Where you enter
depends on what you are holding:
| You arrive with | Entry point | Doc state on arrival → departure |
|---|---|---|
| From scratch — a spec, no code | preproduction (it calls system-design to author --state to-be) | none → to-be → converged when built |
| Existing doc to check | architecture-patterns audit | converged → drift is the finding |
| Old code, refactor — this pipeline’s main case | Phase 0 = system-design authors --state as-is; pillars 1–2; then Phase 2.5 = preproduction (refactor mode) revises it to --state to-be; then pillars 3–4 | as-is → revised to-be → converged on land |
| Old code → new gameplay | system-design for as-is, then preproduction for the upgrade | as-is → to-be (retained + new modules) → converged |
Lifecycle semantics — what each state means and what verify checks in it — live in
t1k-cocos-base-architecture-patterns. This table states entry points only; two tables
describing one thing is the duplication this design removes.
The manifest is the machine-readable half. Phase 0’s doc is generated into
docs/design-manifest.json, and pillars 2 and 3 read it (--manifest) so module boundaries come
from the design rather than from folder shape. Without it they fall back to readdir and label the
report discovery: "readdir-fallback" — valid, but a guess.
Library source — two options, neither mandatory alone: the knowledge-retrieval MCP
(doc_search, hybrid lexical+vector discovery) and the Cocos Package Manager at
https://cpm.playablelabs.ai/ (web UI, CLI, or the editor extension’s list-packages — authoritative
on package names and versions). Prefer both: MCP to discover, CPM to confirm. One available → degraded
but valid; both unavailable → stop rather than report a false “nothing found”. See
references/shared-cpm-facts.md § Library discovery.
Run the MCP half ONCE, at pipeline level, and share it. Invoke
t1k-cocos-base-knowledge-sweep before Phase 0 and carry its prior-art table into the briefs for
0, 3 and 4 — do not leave pillar 2 as the only step that ever queries the corpus. Phase 0 needs it
to know which documented modules already exist upstream; pillar 3 needs it so a Tier 2.5 extraction is
not performed on code a swap will delete; pillar 4 needs it so nothing is contributed that already
ships.
How it is carried: these are AI-driven phases, so the table travels in the invoking prompt/brief —
there is no --prior-art flag, and none of the pillar scripts accept one. Pillar 1 is excluded on
purpose: scan-structure.cjs is a deterministic folder scan with no judgment step, so there is
nothing for a prior-art table to inform. Pillar 2 runs its own per-subsystem doc_search and needs no
hand-off.
The sweep must be Cocos-scoped: most corpus members are Unity/.NET (59.4% as of 2026-08-28) and their C# members outrank the
real Cocos hits on Cocos questions — the SSOT is the sweep skill reference
t1k-cocos-base-knowledge-sweep/references/doc-search-contract.md.
Why reuse and architecture interleave: reuse swaps run before the quality refactor (never
refactor code a swap will delete), but a god-class with no seam cannot be swapped until SRP splits it
out — an enabling extraction. So pillar C runs reuse → architecture → reuse again over the newly
exposed seams. See t1k-cocos-base-architecture-patterns § Enabling extraction.
Shared contract (stated ONCE here; children reference, never restate)
Section titled “Shared contract (stated ONCE here; children reference, never restate)”All four sub-skills obey the SAME operating contract. Read it once, then apply per phase:
- Report-only by default. A bare run reads the project and emits a markdown report + a machine JSON artifact. It NEVER mutates the project.
--applymutates — and only after the AskUserQuestion decision gate. Seereferences/shared-cli-contract.mdfor the exact flag semantics, the decision-gate options, and the report/exit format.- The orchestrator’s own bare run is UNATTENDED (Mode A), and
--implementis the unattended execution pass (Mode B). Both ask nothing and resolve every fork throughreferences/decision-policy.md— a named rule if one applies, decide-and-record (rule 0) if none does — and record the resolution either way; only a genuine verification failure hard-stops. Sub-skills invoked standalone keep their gates, and--apply/--continueare unchanged. Contract:shared-cli-contract.md§ “Unattended modes”. - Errors over silent fallbacks. An absent input report or unreadable project is a clear surfaced
error — never a false “nothing found”. For library lookup specifically: one discovery source down →
fall back to the other and label the report (
discovery: cpm-only/mcp-only); both down → error out.reuse-scanmust never report “0 packages” because a source was unavailable. - One unit at a time for anything risky. Migration and
.meta-adjacent changes run on a git branch, one migration unit per--apply, each behind its own gate.
CPM ground facts (SSOT for all children)
Section titled “CPM ground facts (SSOT for all children)”Composition is plain import. register(ctx) does NOT exist in this framework — do not design or
assume a DI seam. The install SSOT is the playableSync array in the Cocos project’s
package.json; the @playablelabs scope resolves via .npmrc against the CPM registry
(https://cpm.playablelabs.ai/), reachable manually or by CLI. All code the skill reads/writes is
plain, readable TypeScript. Full facts (package-manager handler set, registry) live in
references/shared-cpm-facts.md. Where AnimalHunter (the guinea
pig) actually keeps things: references/shared-project-map.md.
Executed by
Section titled “Executed by”Loop state is a script; the pipeline orchestrates reasoning-tier children. Routing SSOT: theonekit-core/.claude/modules/t1k-orchestration/rules/orchestration-rules.md § “Task-Type → Agent Routing”.
| Step | Agent |
|---|---|
Run loop-state.cjs and report the current pillar and counters | t1k-fact-fetcher |
| Run each pillar (structure-audit, reuse-scan, refactor, contribute) | their own skills — see § Pipeline |
Hard rules
Section titled “Hard rules”- Hard rules, the after-report guidance and the iteration loop: references/hard-rules-and-after-report.md.
References
Section titled “References”references/end-to-end-runbook.md— start here to actually run this. Operator guide: Phase 0 → audits → one plan → tier-by-tier apply → contribute, with per-phase gates and the three failure modes that bite in practice. Its § “Phase 5 — apply, tier by tier” is the loop--continuewalks; § “After the report — what to do next” below names the invocation that reaches it.references/shared-cli-contract.md— report-only default,--applysemantics, AskUserQuestion gate, report + exit-code format. Every sub-skill’s CLI section links here.references/decision-policy.md— the rules that replace the human gates in Mode A/B. Every fork the unattended modes resolve without asking, each with its rejected alternative; the four measured errors that motivated them; the conditional exemption fromtheonekit-core/.claude/modules/t1k-base/rules/always-ask-on-unresolved.md; and what is a hard-stop instead.references/unattended-implement.md— Mode B’s procedure. The walk, the editor probe, the pre-verify table, git-per-unit rollback, the eight hard-stop conditions (four of them run through a revert/retry-once/skip-or-stop failure policy first), thereports/IMPLEMENT.md+reports/implement-state.jsoncontract, and § “Why unattended is safe here” — the measured basis and the failure→check table that replaced each human gate.references/iteration-loop.md— Mode L (--iterate). What one iteration is phase by phase, why the loop is the family’s own sanctioned fresh pass rather than mid-walk re-planning, the notes ledger + fingerprint rule, convergence and the cap’s mandatoryAskUserQuestion, single-branch discipline, and a worked three-iteration example.references/shared-cpm-facts.md—playableSyncinstall SSOT,@playablelabsscope + registry, real package-manager handlers, “plain readable TS”, “no register(ctx)”.t1k-cocos-base-knowledge-sweep— the pipeline-level Cocos-scoped prior-art sweep; owns thedoc_searchcontract that pillar B (and now 0/3/4) consume.t1k-cocos-playable-preproduction— the Phase 2.5 producer. Owns top-down module slicing in both archetypes; this pipeline invokes it in refactor mode (as-is doc + audits in,to-bedoc out) and never restates its procedure.references/shared-project-map.md— canonical vs AnimalHunter layout; embeddedPLAGameFoundation/PlayableParamterToolvspackages/@playablelabs/.