Skip to content

t1k:cocos:playable:modularize

FieldValue
Moduleplayable
Version4.33.13
Efforthigh
Tools—

Keywords: cpm-package, modularize, playablelabs

/t1k:cocos:playable:modularize
[phase0|structure-audit|reuse-scan|refactor|contribute] [<project-root>] [--apply] [--continue] [--implement] [--force-manual-queue] [--attended] [--iterate] [--max-iterations N]

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.

  • 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”.
#Sub-skillPillarOutput
0t1k-cocos-base-system-design + t1k-cocos-base-architecture-patterns (Phase 0)— design baselineprobe-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.
1t1k-cocos-playable-modularize-structure-auditA — structural conformancePer-rule CONFORMANT / DRIFT / MISSING vs the vendored blueprint.md + a normalization plan.
2t1k-cocos-playable-modularize-reuse-scanB — reusePer-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.5t1k-cocos-playable-preproduction (refactor mode) — runs automatically in Mode A— design targetdocs/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.
3t1k-cocos-playable-modularize-refactorC — project-firstOrdered 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.
4t1k-cocos-playable-modularize-contributeD — 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:

PhaseNeeds docs/system-design.md?Why
0produces it—
1 structure-auditNo — not a gateGrades 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-scanNo — not a gateGrades local subsystems against upstream packages. Independent of the project’s own architecture target.
2.5 preproduction (refactor mode)Consumes it — and rewrites itReads 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 refactorYes — ENFORCED preconditionTier 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 contributeNo — 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:

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

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 withEntry pointDoc state on arrival → departure
From scratch — a spec, no codepreproduction (it calls system-design to author --state to-be)none → to-be → converged when built
Existing doc to checkarchitecture-patterns auditconverged → drift is the finding
Old code, refactor — this pipeline’s main casePhase 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–4as-is → revised to-be → converged on land
Old code → new gameplaysystem-design for as-is, then preproduction for the upgradeas-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.
  • --apply mutates — and only after the AskUserQuestion decision gate. See references/shared-cli-contract.md for the exact flag semantics, the decision-gate options, and the report/exit format.
  • The orchestrator’s own bare run is UNATTENDED (Mode A), and --implement is the unattended execution pass (Mode B). Both ask nothing and resolve every fork through references/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 / --continue are 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-scan must 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.

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.

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

StepAgent
Run loop-state.cjs and report the current pillar and counterst1k-fact-fetcher
Run each pillar (structure-audit, reuse-scan, refactor, contribute)their own skills — see § Pipeline
  • Hard rules, the after-report guidance and the iteration loop: references/hard-rules-and-after-report.md.
  • 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 --continue walks; § “After the report — what to do next” below names the invocation that reaches it.
  • references/shared-cli-contract.md — report-only default, --apply semantics, 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 from theonekit-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), the reports/IMPLEMENT.md + reports/implement-state.json contract, 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 mandatory AskUserQuestion, single-branch discipline, and a worked three-iteration example.
  • references/shared-cpm-facts.md — playableSync install SSOT, @playablelabs scope + 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 the doc_search contract 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-be doc out) and never restates its procedure.
  • references/shared-project-map.md — canonical vs AnimalHunter layout; embedded PLAGameFoundation/PlayableParamterTool vs packages/@playablelabs/.