t1k:unity:base:agent-domain-routing
| Field | Value |
|---|---|
| Module | base |
| Version | 5.116.6 |
| Effort | low |
| Tools | — |
Keywords: agent domain, agent for, agent lookup, agent routing, discover agent, dots agent, route to agent, spawn agent, unity agent, which agent
How to invoke
Section titled “How to invoke”/t1k:unity:base:agent-domain-routingAgent Domain Routing (theonekit-unity)
Section titled “Agent Domain Routing (theonekit-unity)”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.mdon 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-skillalso resolves this table by keyword.
| Task pattern | Agent |
|---|---|
ISystem, IComponentData, authoring, baker | t1k-unity-dots-core-implementer |
DOTS tests — World harness, ECB flush, IEnableableComponent, SubScene baking | t1k-unity-dots-core-tester |
| Headless batchmode compile loop after a blind refactor — collect the full error set, fix by root cause, re-run to green | t1k-unity-dots-core-compile-doctor |
| DOTS review — Burst compat, parallel safety, ECS architecture | t1k-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 validation | t1k-unity-dots-core-validator |
| DOTS perf — chunk utilisation, draw calls, job parallelism | t1k-unity-dots-core-optimizer |
| Scene composition — Synty, terrain, lighting, NavMesh | t1k-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 work | t1k-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 store | t1k-unity-base-feature-implementer |
| Blueprint CSV/JSON rows, Addressables entry text, design-doc-to-blueprint parity | t1k-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 pin | t1k-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 spec | t1k-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 file | t1k-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 script | t1k-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/scene | t1k-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 RED | t1k-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 profiling | t1k-unity-base-optimizer |
| DOTS-feasibility ideation | t1k-unity-base-brainstormer |
| Screen-level feel — camera shake, zoom/FOV punch, hit-stop/slow-motion, screen flashes, post-process kicks | t1k-unity-rendering-feel-developer |
SFX/music slot publication, IAudioManager wiring, loudness bands, audio Addressables | t1k-unity-audio-developer |
| Visual judgment (not implementation) — design brief or screenshot review of UI, scene composition, shaders/look, game feel | t1k-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 |
Pick by task shape, not by who is nearest
Section titled “Pick by task shape, not by who is nearest”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:
- 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. - 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.
- 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 onrun-tests.sh/ a project gate script (Tools/gates/*.sh) burns 90-turn Sonnet context onsleep-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 (ortest-writer) commits the change, thent1k-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 coret1k-tester(haiku) with the same brief; do not fall back to the developer. - Seed a worktree’s
Libraryinstead 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. - Routed (cheap) hops need
worktree: <abs>alone on its own line and a validatedcontract:line (requireContractis on androutableWriteAgentsis 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.
- 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.
- The hop writes a progress file (
plans/<lane>/progress.mdor 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. - 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. - 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-onlyfirst; wait or defer rather than spawning into a queue. - 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.AttachresetlocalPosition/localScaleon every visual resolve, so the hop worked a dead lever. Cite thergcommand 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:
- Mark the lane.
bun $HOME/.claude/scripts/t1k-lane-directive.cjs mark <abs-worktree>once, thenemit <abs-worktree>for every brief. The emittedworktree: <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. - Write each contract, then validate it.
bun $HOME/.claude/scripts/t1k-contract.cjs validate <contract.json>must exit 0 before the spawn.allowed_filesnames 1–2 files (laneRouting.limits.maxAllowedFiles, the SSOT int1k-config-core.json), disjoint across a wave;tests.pathsmust not overlapallowed_files; the JSON block stays under the cap (maxContractCharsin that same block;t1k-contract.cjs’s ownMAX_CONTRACT_CHARSis slightly looser, so obey the smaller one). - Spawn the narrowest specialist per unit (rows above):
t1k-unity-base-feature-implementerfor C#,t1k-unity-base-data-authorfor CSV/JSON/Addressables text,t1k-unity-base-test-writerfor tests with a RED proof,t1k-unity-base-asset-porterfor imports and prefab builders,t1k-unity-base-ui-implementerfor 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. - Wave by disjointness. Hops whose
allowed_filessets 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 nativet1k-git-managerhop; a rawgitcall in the lead is the wrong tool. - A denied brief is split, never floored. The lane gate refuses more than
maxAllowedFilesfiles, a missing contract, an over-long contract, atests.paths/allowed_filesoverlap and a brief touching.claude/**. The response is to cut the deliverable again and re-route — NOT to spawnt1k-unity-base-developernatively. The cap is a measured pilot value, not a style rule: readlaneRouting.limitsint1k-config-core.jsonand its_note, which forbids restating the curve anywhere else (docs/mr-lane-brief-gate.mdin core). - Editor work is the one exception, and it is not the lead’s. A scene, prefab, Canvas, compile check or
t1k unityverb goes to a nativet1k-unity-base-developerbrief (or a manual checklist), because a routed hop cannot reach the Editor.t1k-unity-base-lane-leaddoes 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 exactt1k unitycall, itscwd, theexpectpath and a checkabledone-when. The lead’s spawner runs that call and replies with aBLOCKED 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”. - 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.
Related
Section titled “Related”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.