Architecture

TheOneKit uses registry-based IoC — Inversion of Control — rather than file overrides. Engine kits register their agents and skills as JSON fragments; core commands read those fragments at runtime to decide what to delegate to. No core file is ever replaced.

Why IoC?

Traditional toolkit extension swaps files: an engine kit replaces a core skill file with its own version. This breaks when core is updated (the override is lost) and creates implicit coupling (the kit must mirror core’s file paths).

TheOneKit’s approach: core commands contain no engine-specific logic. They read JSON routing fragments to find the right agent for each role. Engine kits supply higher-priority fragments; the command picks the highest-priority match.

Benefits:

• Core updates never break engine kits — fragments are additive and versioned independently.
• Multiple kit layers coexist. A Unity project with the Designer kit active has both engine-role agents (DOTS implementer) and design-role agents (game-designer) available simultaneously.
• Every slash command (/t1k:cook, /t1k:fix, /t1k:test) is engine-agnostic. The same command routes to the correct Unity, Cocos, or web agent transparently.
• New kits need only three JSON files plus skills and agents — no forking of core.

Priority resolution

Every fragment carries a numeric priority. It is a plain integer the fragment picks for itself ("priority": 90 in the fragment’s root JSON) — not a fixed set of tiers. There is no reserved slot for “engine kit”, “designer”, or any other label; a kit chooses whatever value it needs to override what it intends to. You can have as many layers as you want, at any values — the architecture does not cap or name them.

The merge behaviour depends on the fragment type:

• Routing and config — override: for a given role/key, the highest priority wins.
• Activation — additive: every matching fragment contributes; priority never suppresses.

The ladder today (illustrative, not fixed)

The values below are simply the numbers the current kits happen to use — examples, not an architectural contract. A new kit drops in anywhere on the ladder by picking an integer.

flowchart TD
  MO["Module overlays\npriority 91+\ne.g. ui\n(91 + dependency depth)"]
  EK["Engine kits\npriority 90\nUnity, Web (Cocos, RN, Nakama)"]
  VK["Domain / vertical kits\npriority 85\nBusiness, Marketing, Comms"]
  DK["Designer kit\npriority 50\nGame-design agents"]
  CO["Core\npriority 10\nFallback roles, universal commands"]

  MO --> EK --> VK --> DK --> CO

  style MO fill:#1e3a5f,color:#e0f0ff
  style EK fill:#1a4a2e,color:#d0ffe0
  style VK fill:#13343b,color:#d0f0ff
  style DK fill:#3a2a1e,color:#ffe8c0
  style CO fill:#2a1a3e,color:#e8d0ff

Priority (current)	Who ships it	Purpose
91 + depth	Individual modules (e.g., dots-core, ui)	Module-specific agent overrides
90	Engine kits (theonekit-unity, theonekit-web)	Domain roles — implementer, tester, etc.
85	Domain kits (theonekit-business, theonekit-marketing, theonekit-comms-mcp)	Vertical-domain roles and skills
50	theonekit-designer	Game-design agents
10	theonekit-core — this repo	Fallback roles, universal commands

None of these numbers are reserved or guaranteed — they are the current layout, and they can change as kits are added or re-tuned. The contract is the integer comparison, not the label: to win a role, pick a priority higher than whatever you want to override; to defer to it, pick lower. That is why an engine kit uses 90 — so its dots-implementer beats both core’s generic implementer (10) and the designer kit’s (50).

Fragment types and merge rules

Each kit ships exactly three fragment types. They live under .claude/ after install and are named by layer (core, unity, designer, etc.) so multiple kits never collide.

Fragment	Naming pattern	Merge rule
t1k-routing-{layer}.json	One per kit	Override — highest priority wins per role
t1k-activation-{layer}.json	One or more per module	Additive — all keyword matches collected
t1k-config-{layer}.json	One per kit	Override — highest priority wins per key

Routing — override, highest priority wins per role

Routing fragments map logical roles (implementer, tester, reviewer, …) to agent names. When two fragments define the same role, the higher-priority fragment wins.

t1k-routing-core.json   (p10): implementer → t1k-fullstack-developer
t1k-routing-unity.json  (p90): implementer → dots-implementer

Result: implementer → dots-implementer  (p90 wins)

Unregistered roles fall through to core. If a role exists only in t1k-routing-core.json, it is always resolved regardless of which kits are installed.

Activation — additive, all matches collected

Activation fragments map keyword phrases to lists of skills that should be loaded when those keywords appear in a user prompt. All matching fragments contribute; there is no suppression.

t1k-activation-core.json  (p10): "auth" → ["t1k-security"]
t1k-activation-unity.json (p90): "auth" → ["unity-auth-skill"]

Prompt containing "auth" activates BOTH: t1k-security + unity-auth-skill

Deduplication applies — the same skill is activated at most once per prompt, even if multiple fragments list it.

Config — override, highest priority wins per key

Config fragments control features, repo URLs, MCP requirements, telemetry, and more. When two fragments set the same key, the higher-priority value wins.

t1k-config-core.json   (p10): features.mcp → false
t1k-config-unity.json  (p90): features.mcp → true

Result: features.mcp → true  (p90 wins)

Module-first architecture (v2)

Modules are the primary installable unit. Kits are container repos.

A module is independently versioned (its own module.json with name, version, dependencies, skills, and agents). Users install modules, not kits. Installing a module resolves its dependency graph and copies the relevant .claude/ files locally.

theonekit-core ships three required modules:

Module	Purpose	Skills
t1k-base	Core workflow — cook, plan, fix, debug, test, review, git, docs	19
t1k-extended	Advanced reasoning, collaboration, security tools	17
t1k-maintainer	Kit maintainer tools — release, triage, sync, scaffolding	14

A Unity project typically adds unity-base (required) plus optional modules like dots-core, ui, or rendering. The Designer kit adds design-base plus game-specific modules.

Presets

Presets are named module groups defined by the kit author in t1k-modules.json. They are applied via --preset at t1k init time.

Core ships three presets:

Preset	Modules included	Also installs
full	t1k-base, t1k-extended, t1k-maintainer	theonekit-model-router:model-router
developer	t1k-base, t1k-extended	theonekit-model-router:model-router
maintainer	t1k-base, t1k-extended, t1k-maintainer	theonekit-model-router:model-router

The crossKitModules field in each preset causes t1k init to also install the model-router module from theonekit-model-router, enabling transparent multi-model routing out of the box.

File layout after install

After t1k init, the consumer project’s .claude/ directory contains merged fragments from every installed kit:

.claude/
├── t1k-routing-core.json        ← from theonekit-core
├── t1k-routing-unity.json       ← from theonekit-unity (if installed)
├── t1k-activation-core.json
├── t1k-activation-t1k-base.json
├── t1k-activation-t1k-extended.json
├── t1k-config-core.json
├── t1k-config-mr.json           ← from theonekit-model-router (if installed)
├── agents/                      ← merged agent definitions from all kits
├── skills/                      ← merged skill directories from all kits
├── hooks/                       ← all hooks route through hook-runner.cjs gateway
└── modules/{name}/module.json   ← per-module manifests

There are no network calls at runtime. After install, all files are local. The CLI (t1k modules update) fetches the latest kit releases and re-extracts the fragments.

Hook gateway

All hooks route through a single hook-runner.cjs gateway with a dedupGuard() (MD5 lock, 3-second window). This prevents double-execution when T1K is installed both globally (~/.claude/) and at project level (.claude/). theonekit-core is the canonical hook host — no non-core kit ships hooks.

Related pages

• Configuration Explained — routing, activation, config fragment schemas in detail
• Kits — browse individual kit pages with auto-generated module and skill tables
• Skills — auto-generated skill reference
• Agents — auto-generated agent reference