Configuration Explained

The auto-generated Config reference pages show the raw JSON tables for each kit’s registry fragments. This page explains what those fragments mean and how they work together at runtime.

The three fragment types

TheOneKit’s runtime reads three types of JSON fragment files from .claude/. Each type has a different job and a different merge strategy. See Architecture for the priority stack that determines which fragment wins when multiple kits define the same key.

`t1k-routing-{layer}.json` — agent delegation

Routing fragments answer the question: “For role X in this project, which agent should handle it?”

Commands like /t1k:cook, /t1k:fix, /t1k:test, and /t1k:review are role-based — they ask for the implementer, tester, or reviewer rather than hard-coding an agent name. The routing fragment resolves the role to a concrete agent name.

Core routing (priority 10) — the fallback layer:

Role	Default agent
`implementer`	`t1k-fullstack-developer`
`tester`	`t1k-tester`
`reviewer`	`t1k-code-reviewer`
`debugger`	`t1k-debugger`
`brainstormer`	`t1k-brainstormer`
`planner`	`t1k-planner`
`docs-manager`	`t1k-docs-manager`
`git-manager`	`t1k-git-manager`
`project-manager`	`t1k-project-manager`
`skills-manager`	`t1k-skills-manager`
`kit-developer`	`t1k-kit-developer`

Engine kits (priority 90) override specific roles without touching the others. A Unity project replaces implementer with dots-implementer but leaves reviewer and planner pointing to the core defaults.

Engine-specific roles (optimizer, shader, game-developer, ui-developer, etc.) are intentionally absent from core — they are only provided by engine kits. This prevents the wrong agent from being silently selected when an engine role keyword fires in a project that does not have an engine kit installed.

The routing fragment also contains an errorRecovery map:

{
  "errorRecovery": {
    "compilation": "implementer",
    "test-failure": "t1k-tester",
    "runtime": "t1k-debugger",
    "performance": "optimizer"
  }
}

`t1k-activation-{layer}.json` — keyword-to-skill mapping

Activation fragments answer the question: “When the user’s prompt contains keyword X, which skills should be pre-loaded?”

Unlike routing, activation is additive — all matching fragments contribute, and higher-priority fragments cannot suppress lower-priority ones. This lets engine kits add domain-specific skills on top of core without losing any core coverage.

Each mapping entry has a keywords list and a skills list:

{
  "mappings": [
    {
      "keywords": ["auth", "login", "token", "oauth"],
      "skills": ["t1k-security"]
    }
  ]
}

When the user types a prompt containing "auth", the activation algorithm collects every skill from every fragment whose keyword list includes "auth". If the Unity kit also maps "auth" to "unity-auth-skill", both t1k-security and unity-auth-skill are activated.

sessionBaseline — an optional list of skills that are always activated at session start, regardless of prompt content. Core’s baseline is empty; engine kits may add engine-specific skills.

`t1k-config-{layer}.json` — session behaviour and feature flags

Config fragments control everything that isn’t routing or activation: feature flags, MCP server requirements, telemetry, repo URLs, CLI configuration, and more.

Key sections in t1k-config-core.json:

features — boolean flags controlling session behaviour:

Flag	Default	Effect
`executionTrace`	`true`	Log agent delegation chain for debugging
`telemetry`	`true`	Send anonymised usage data to the T1K telemetry endpoint
`autoUpdate`	`true`	Check for kit updates at session start
`autoUpdateMajor`	`true`	Include major-version updates in auto-update
`autoIssueSubmission`	`true`	Auto-file GitHub issues for detected skill bugs
`autoLessonSync`	`true`	Auto-sync learned lessons back to kit repos via PR
`hookLogging`	`true`	Write hook execution logs for debugging
`autoCommitKitSync`	`true`	Auto-commit kit-sync changes
`autoPushKitSync`	`true`	Auto-push kit-sync commits

mcp — required and optional MCP server declarations:

{
  "mcp": {
    "required": [
      {
        "name": "github",
        "purpose": "GitHub issue/PR management for triage, sync-back, issue reporting",
        "installCmd": "claude mcp add github"
      },
      {
        "name": "context7",
        "purpose": "Library/framework documentation lookup for planning and implementation",
        "installCmd": "claude mcp add context7 --transport http -- https://mcp.context7.com/mcp"
      },
      {
        "name": "sequential-thinking",
        "purpose": "Structured step-by-step analysis for problem-solving when stuck",
        "installCmd": "claude mcp add sequential-thinking -- npx -y @modelcontextprotocol/server-sequential-thinking"
      },
      {
        "name": "memory",
        "purpose": "Cross-session knowledge persistence via knowledge graph",
        "installCmd": "claude mcp add memory -- npx -y @modelcontextprotocol/server-memory"
      }
    ],
    "optional": [
      { "name": "playwright", "purpose": "Browser automation for E2E testing and visual regression" },
      { "name": "chrome-devtools", "purpose": "Browser DevTools for console, network, and performance analysis" }
    ]
  }
}

telemetry — sends anonymised session data to https://t1k-telemetry.the1studio.org/ingest (GitHub token auth, max 2000 chars of prompt, 90-day retention).

issueClaim — prevents duplicate PRs by claiming GitHub issues before work starts. In-scope repos: The1Studio/theonekit-* and The1Studio/t1k-*. enforcementMode: "hard-block" means the CLI blocks work if another engineer already holds the claim.

Model Router — `t1k-config-mr.json`

The model-router kit ships its own config fragment at t1k-config-mr.json. This is separate from the core config and is only present when theonekit-model-router:model-router is installed (included in all three core presets by default).

Transparent mode

In transparent mode, the model-router intercepts every Task tool call (sub-agent spawn) and re-routes it to a cheaper provider, while keeping the agent’s identity, prompt, and tools intact. The calling agent sees the same result as if the original Anthropic model had run.

{
  "modelRouter": {
    "enabled": true,
    "mode": "transparent",
    "modelMapping": {
      "claude-sonnet-4-6": {
        "provider": "kimi",
        "model": "kimi-k2.6"
      },
      "claude-haiku-4-5-20251001": {
        "provider": "kimi",
        "model": "kimi-k2.5"
      }
    },
    "excludeAgents": []
  }
}

modelMapping is keyed by the agent’s declared model: frontmatter field. When a sub-agent is spawned whose frontmatter declares model: claude-sonnet-4-6, the router intercepts the Task and runs the agent on kimi/kimi-k2.6 instead. The agent code, prompt, and tools are unchanged.

excludeAgents is an array of agent names that are never intercepted — they always run on Anthropic. Use this to protect agents where reasoning quality is critical (e.g., the planner or architect agents).

Failover chain

{
  "failover": {
    "enabled": true,
    "chain": {
      "kimi": "opencode-go",
      "opencode-go": "kimi",
      "codex": "kimi"
    },
    "fallbackToAnthropic": true
  }
}

When the primary provider returns a failure signal (HTTP 429, 5xx, timeout, rate-limit message), the router advances to the next hop in the chain map. If all hops fail and fallbackToAnthropic is true, the original Anthropic Task runs as the final fallback.

Enabling / disabling the router

The router is only active when modelRouter.enabled is true and modelRouter.mode is "transparent". Setting either to a different value disables routing without removing the config file.

Presets and module selection

Presets are defined in t1k-modules.json under the presets key. Each preset lists the modules to install and an optional crossKitModules array for modules from other kits.

{
  "presets": {
    "full": {
      "modules": ["t1k-base", "t1k-extended", "t1k-maintainer"],
      "crossKitModules": ["theonekit-model-router:model-router"]
    },
    "developer": {
      "modules": ["t1k-base", "t1k-extended"],
      "crossKitModules": ["theonekit-model-router:model-router"]
    },
    "maintainer": {
      "modules": ["t1k-base", "t1k-extended", "t1k-maintainer"],
      "crossKitModules": ["theonekit-model-router:model-router"]
    }
  }
}

crossKitModules entries use the format "{kit-repo}:{module-name}". The CLI resolves the correct release ZIP for the referenced kit and installs the named module alongside the local ones.

All three core presets include theonekit-model-router:model-router — so transparent routing is enabled by default on every fresh t1k init --preset * invocation.

Customising config in a consumer project

Config fragments are merged at priority order. To override a feature flag for your project, add a higher-priority fragment:

{
  "registryVersion": 1,
  "priority": 95,
  "features": {
    "autoUpdate": false
  }
}

Name the file following the pattern t1k-config-{your-layer}.json and place it under .claude/. It will be picked up at session start and merged with the standard fragments.

Do not hand-edit the kit-shipped fragments under .claude/ — they are overwritten on t1k modules update.

Architecture — priority resolution and merge strategy overview
Auto-generated config tables — raw JSON tables for every fragment in every kit
Model Router kit — full model-router reference with provider table

Configuration Explained

The three fragment types

t1k-routing-{layer}.json — agent delegation

t1k-activation-{layer}.json — keyword-to-skill mapping

t1k-config-{layer}.json — session behaviour and feature flags

Model Router — t1k-config-mr.json