Skip to content

t1k:unity:base:agent-domain-routing

FieldValue
Modulebase
Version5.116.6
Effortlow
Tools—

Keywords: agent domain, agent for, agent lookup, agent routing, discover agent, dots agent, route to agent, spawn agent, unity agent, which agent

/t1k:unity:base:agent-domain-routing

Unity/DOTS rows for core rules/orchestration-rules.md § “Task-Type → Agent Routing”. Role keys, file globs and error-recovery mappings: .claude/t1k-routing-unity.json. Skills: t1k-unity-base-skill-domain-routing. Rationale and incident: docs/agent-domain-routing-unity.md.

Roles are architecture-aware, and the fact resolves without you. Each row below has a DOTS counterpart in the dots-core p91 overlay (.claude/modules/dots-core/t1k-routing-unity-dots-core.json), selected by the project fact architecture — which core resolves itself, automatic on core with architectureDetect support; until then use --set. .claude/scripts/detect-unity-architecture.cjs only INSPECTS the signals (--json; report-only) or PINS the fact (--set dots|mono). Full map, resolution order and the held-back bare-key flip: docs/agent-tier-map.md.

Moved out of .claude/rules/agent-domain-routing-unity.md on 2026-08-24 (context-budget lever — this table is consulted only after the agent already decided to spawn a sub-agent for Unity/DOTS work). The tie-break and parallel-fan-out constraints that fire unsummoned — before an agent would otherwise pick the wrong specialist — stayed behind in the rule; only this table moved. /t1k:find-skill also resolves this table by keyword.

Task patternAgent
ISystem, IComponentData, authoring, bakert1k-unity-dots-core-implementer
DOTS tests — World harness, ECB flush, IEnableableComponent, SubScene bakingt1k-unity-dots-core-tester
Headless batchmode compile loop after a blind refactor — collect the full error set, fix by root cause, re-run to greent1k-unity-dots-core-compile-doctor
DOTS review — Burst compat, parallel safety, ECS architecturet1k-unity-dots-core-reviewer
Runtime ECS diagnosis (briefs t1k-unity-base-developer for the t1k unity dots calls)t1k-unity-dots-core-debugger
Read-only Play-mode validationt1k-unity-dots-core-validator
DOTS perf — chunk utilisation, draw calls, job parallelismt1k-unity-dots-core-optimizer
Scene composition — Synty, terrain, lighting, NavMesht1k-unity-dots-core-environment
URP/HLSL, GPU instancing, StructuredBuffer (DOTS project; role shader-dots)t1k-unity-dots-core-shader
Shader / material / ShaderGraph work in a mono (non-DOTS) project, where dots-core is not installed (bare role shader resolves here; native, Editor work)t1k-unity-base-developer
Mono/VContainer/SignalBus game code needing Editor, scene, prefab or compile-check workt1k-unity-base-developer
Implement (default): a feature or fix with no more specific row (implementer for engine/package code)t1k-unity-base-feature-implementer (code-only) or t1k-unity-base-developer (needs Editor, scene, prefab or compile-check)
Code-only C# edit batch — rewire to a library module, delete a duplicated type, add or drop using aliases, move a type, add a service or storet1k-unity-base-feature-implementer
Blueprint CSV/JSON rows, Addressables entry text, design-doc-to-blueprint parityt1k-unity-base-data-author
Mechanical: rebase / merge / lock re-point — replay a lane onto a moved base, resolve a packages-lock.json or manifest.json conflict, re-point a version pint1k-unity-base-feature-implementer (no Editor verbs; a conflict inside a .unity/.prefab YAML is NOT this row — that needs t1k-unity-base-developer)
Mechanical: regenerate records, pins or tests — re-run a generator, refresh a golden/fixture file, restamp a version across manifests, rewrite a lockfile from a spect1k-unity-base-feature-implementer
Mechanical: denylist / leak-scan reword — edit an allow-list row, reword a scan hit, add or drop a forbiddenTokens entry, refresh an allowlist text filet1k-unity-base-feature-implementer
Mechanical: data / CSV — bulk row edits in blueprint CSVs, key renames across a data table, a CSV→asset regeneration driven by an existing scriptt1k-unity-base-data-author
Mechanical: asset / clip / audio wiring — import a set of already-produced files, fill an Addressables entry, wire an AudioClip reference or an AnimationClip binding into an existing prefab/scenet1k-unity-base-asset-porter (a clip or prefab that must be AUTHORED, not wired, is t1k-unity-base-developer with the animation module’s skills loaded — that module ships no agent)
Import/copy original or ripped assets into the clone, author Scripts/Editor/<Lane>PrefabBuilder.cs and the placeholder-assets-<lane>.md ledger (role asset-porter; cheap-routed)t1k-unity-base-asset-porter
Write or port NUnit/DOTS tests, prove each REDt1k-unity-base-test-writer
Run an EditMode/PlayMode suite or a gate script and report pass/fail with failure triage (never diagnoses or fixes; haiku, no Editor verbs)t1k-unity-base-mono-tester
Map overlap, UI scan or “does the library have this” over a repo (read-only)t1k-gamedev-architecture-system-mapper (theonekit-gamedev architecture; the lane brief is skill t1k:gamedev:architecture:system-mapping)
Canvas/uGUI, incl. an ECS→UI bridge (the layout decision and the brief)t1k-unity-base-ui-developer
Code-only runtime uGUI view scripts and RectTransform layout tests, once the layout is decided (no prefab, no Editor)t1k-unity-base-ui-implementer
Mobile perf profilingt1k-unity-base-optimizer
DOTS-feasibility ideationt1k-unity-base-brainstormer
Screen-level feel — camera shake, zoom/FOV punch, hit-stop/slow-motion, screen flashes, post-process kickst1k-unity-rendering-feel-developer
SFX/music slot publication, IAudioManager wiring, loudness bands, audio Addressablest1k-unity-audio-developer
Visual judgment (not implementation) — design brief or screenshot review of UI, scene composition, shaders/look, game feelt1k-unity-base-visual-director
Adversarial PR, branch or fix-delta review of Unity C# (read-only; proves each new test RED in a scratch copy)t1k-unity-base-pr-reviewer
Parity or closure audit of a reconstructed port, or porting a confirmed deviation (brief must state owner-authorised or non-commercial research)t1k-unity-base-parity-porter

Unity lanes do NOT default to t1k-fullstack-developer (engine-agnostic fallback only). Implement lanes use feature-implementer / developer; asset import and prefab builders use asset-porter; code and shader work stay native.

t1k-unity-base-developer is a 90-turn lead with Editor tools. Using it as the default for any Unity task is the slow path (measured 2026-10-13, PirateEndlessPuncher: pin bump 92 min, three migration lanes 26 to 38 min each and still unfinished). Rules:

  1. Mechanical or code-only work goes to a hop agent (rows above: feature-implementer, data-author, test-writer), 30 turns, no Editor tools, one deliverable each. A pin bump, an alias edit, a delete-and-rewire batch is a hop, not a lead.
  2. A lead only decides and briefs. When a phase spans C#, data and tests, the lead splits it into those hops, in parallel when files are disjoint, and keeps only Editor, scene or compile-check work for itself. A lead that edits 50 files itself serially is the failure this section exists to stop.
  3. Verify the smallest thing that can fail. ./run-tests.sh editmode -filter <expr> for a lane’s own assemblies; the full suite (about 25 min through the one-slot gate, FIFO) runs once on the integrated branch, not once per lane. Three lanes each running the full suite wait 75 min on the gate alone. Finish-then-verify: a lane writes its WHOLE phase blind and does not touch Unity between steps; the filtered run is for a lane that must prove a NEW shape, and everything else waits for the one total gate (rules/ai-velocity-batch-compile-unity.md, “Fast, fail fast, finish-then-verify”). 3a. Running a suite is not a lead’s job. A lead that edits then waits on run-tests.sh / a project gate script (Tools/gates/*.sh) burns 90-turn Sonnet context on sleep-style polling (measured 2026-10-15, WarShip: a developer lane spent most of its turns waiting on one EditMode run while machine load was 70+). Split it: the lead (or test-writer) commits the change, then t1k-unity-base-mono-tester (haiku) runs the suite. The brief MUST name the exact gate command and its -filter, the one-Unity-per-project rule and the results path; the tester reports failures and never edits. If the tester is absent from the session registry (agent-registry-snapshotted-at-session-start), spawn core t1k-tester (haiku) with the same brief; do not fall back to the developer.
  4. Seed a worktree’s Library instead of re-importing. On btrfs, cp -a --reflink=always <main>/<UnityProject>/Library <worktree>/<UnityProject>/ is instant and free; a cold import is the first-run cost of every fresh worktree. Close the editor on the source first, or copy while it is idle. The other three fresh-worktree prerequisites (submodules, bash not zsh, the results XML): t1k-unity-editor-cli/references/headless-vs-windowed.md.
  5. Routed (cheap) hops need worktree: <abs> alone on its own line and a validated contract: line (requireContract is on and routableWriteAgents is empty by default, so an unmarked brief silently runs native). Do not assume a hop agent is routed.

Editor loops — never one big brief to a cheap hop

Section titled “Editor loops — never one big brief to a cheap hop”

An Editor loop (edit prefab/scene → recompile → play-mode capture → measure → decide) is the one shape a routed hop performs WORST: no Editor access, no way to see the result, and a brief whose acceptance criterion is only checkable at the end. A measured Editor-loop brief to a cheap t1k-fullstack-developer hop took 1.8 to 3.5 h and 24-35 tool calls per hop for what a human reads as one step.

  1. One measurable step per hop. A loop brief states ONE step with a numeric or file-shaped check (“the captured frame has the crosshair at x≈960”, “the recompile log is empty”). A brief naming three steps is cut into three.
  2. The hop writes a progress file (plans/<lane>/progress.md or the path the brief names): steps done, last measurement, next step. The orchestrator reads it while the hop runs instead of waiting blind, and a killed hop resumes from it rather than from scratch.
  3. Native verification is the orchestrator’s. The hop reports what it ran; the orchestrator runs the final Editor check itself (t1k unity …) and owns the verdict. A routed hop’s “verified” is a claim, not evidence.
  4. Check the memory gate before spawning. Under mem-low (free RAM low, or Unity instances queued) an Editor step waits behind the gate for tens of minutes. bun $HOME/.claude/scripts/mr-wait-memory.cjs --check-only first; wait or defer rather than spawning into a queue.
  5. Grep every “X is never written by code” premise before it enters a brief. A brief asserting a lever that is in fact overridden at runtime burns the whole hop: one asserted “the TankView prefab root transform is never written by code” while CharacterVisualSelector.Attach reset localPosition/localScale on every visual resolve, so the hop worked a dead lever. Cite the rg command and its hits in the brief; no grep, no premise.

Phase lanes — one lead, hops of one or two files

Section titled “Phase lanes — one lead, hops of one or two files”

A plan phase that edits game code (plans/*/phase-NN-*.md) is led by t1k-unity-base-lane-lead (native, routable: false, holds Agent). It edits nothing itself: it cuts the phase into routed hops of one or two files each, authors and validates each hop’s contract, marks the lane worktree, and reports one summary.

The recipe, in order:

  1. Mark the lane. bun $HOME/.claude/scripts/t1k-lane-directive.cjs mark <abs-worktree> once, then emit <abs-worktree> for every brief. The emitted worktree: <abs> line goes alone on its own line, pasted byte-identical: a hand-typed one reads as malformed, the router refuses the lane and runs the hop NATIVE at full price with no error.
  2. Write each contract, then validate it. bun $HOME/.claude/scripts/t1k-contract.cjs validate <contract.json> must exit 0 before the spawn. allowed_files names 1–2 files (laneRouting.limits.maxAllowedFiles, the SSOT in t1k-config-core.json), disjoint across a wave; tests.paths must not overlap allowed_files; the JSON block stays under the cap (maxContractChars in that same block; t1k-contract.cjs’s own MAX_CONTRACT_CHARS is slightly looser, so obey the smaller one).
  3. Spawn the narrowest specialist per unit (rows above): t1k-unity-base-feature-implementer for C#, t1k-unity-base-data-author for CSV/JSON/Addressables text, t1k-unity-base-test-writer for tests with a RED proof, t1k-unity-base-asset-porter for imports and prefab builders, t1k-unity-base-ui-implementer for runtime view scripts and layout tests. All five are cheap-routed and all five commit, push and open the PR on their OWN topic branch (owner decision 2026-10-20); none merges.
  4. Wave by disjointness. Hops whose allowed_files sets do not intersect spawn in one message; a hop reading another’s output is the next wave. Commit/push/PR, branch or worktree work is a native t1k-git-manager hop; a raw git call in the lead is the wrong tool.
  5. A denied brief is split, never floored. The lane gate refuses more than maxAllowedFiles files, a missing contract, an over-long contract, a tests.paths/allowed_files overlap and a brief touching .claude/**. The response is to cut the deliverable again and re-route — NOT to spawn t1k-unity-base-developer natively. The cap is a measured pilot value, not a style rule: read laneRouting.limits in t1k-config-core.json and its _note, which forbids restating the curve anywhere else (docs/mr-lane-brief-gate.md in core).
  6. Editor work is the one exception, and it is not the lead’s. A scene, prefab, Canvas, compile check or t1k unity verb goes to a native t1k-unity-base-developer brief (or a manual checklist), because a routed hop cannot reach the Editor. t1k-unity-base-lane-lead does not hold that agent in its allowlist on purpose, so the need surfaces as a BLOCKED HOP instead of a silent native fallback: a fixed block naming the one exact t1k unity call, its cwd, the expect path and a checkable done-when. The lead’s spawner runs that call and replies with a BLOCKED HOP RESOLVED <H-id> SendMessage (exit, output path, stdout, files changed), which is what resumes the lane — the lead is paused, not finished, and is never re-spawned from scratch. Shape: the agent’s § “Blocked hop hand-off”.
  7. Review has its owner. t1k-unity-base-pr-reviewer (native, read-only) reviews a Unity C# PR, proves each new test RED in a scratch copy, and is never replaced by the lead reading the diff.

t1k-lane-worker is for .claude/** lanes only: it is native, has no Agent tool so it cannot spawn hops, and bills at full Sonnet price with none of these specialists’ skills. Pairing it with a plan phase is the mistake this section exists to stop.

How a data lane is cut. A data lane rarely looks like one hop. Take “add a new item table”: the runtime blueprint CSV is t1k-unity-base-data-author (hop 1, one file), its docs/data/ mirror is the same agent (hop 2, one file), the design doc prose is hop 3, and the inverted tests that fail while the table is absent are t1k-unity-base-test-writer (hop 4, tests.paths only). Four hops of one or two files, disjoint, two waves — instead of one hop naming four files and being refused by the gate.

The tie-break rule (a task naming a DOTS concept takes its row above even when it also touches Assets/Scripts/) and the “parallel fan-out does not license a generalist” constraint live in .claude/rules/agent-domain-routing-unity.md — read that first; it is what tells you when to consult this table.