Project-M/.claude/skills/dots-dev/SKILL.md

name, description

name	description
dots-dev	Orchestrates a Unity DOTS (Entities) + Netcode-for-Entities dev session — grounding, design-review, plan-gated implementation, validation, and a doc bookend. Use when the operator types /dots-dev or opens DOTS/ECS/Netcode work ("let's work on <game>", "implement X", "design Y system"). The default driver for non-trivial DOTS work; defers a missing DOTS foundation to the one-time setup task.

/dots-dev — Adaptive Unity DOTS / Netcode Dev Session Orchestrator

Drives a Unity 6.5 DOTS (Entities) + Netcode for Entities session. CLAUDE.md (always-loaded) is authoritative for conventions, build gotchas, the MCP cheat-sheet, anti-patterns, the memory layers, git rules, and the bootstrap/world model — this skill does not re-teach them; it carries the orchestration process CLAUDE.md lacks, and inlines only the few highest-recurrence gates it directly depends on (flagged ★). When the two disagree, CLAUDE.md wins.

The spine: size by blast-radius → ground → (design-review) → plan-gate → serial implement → verify-ladder → (diff-review) → doc/memory bookend → offer commit. Two adversarial reviews bookend the code; everything else flexes by size.

Non-negotiables (every track)

1. context7-first for volatile DOTS APIs ★. Resolve Entities/Netcode/Physics/Burst/Collections API shape via the ctx7 CLI (or the find-docs skill) before writing it — never training-data recall. Two-source rule: docs for the current API, unity_reflect for the installed engine shape (they can disagree — reflection wins for the pinned version). Pins + flow → references/context7-libraries.md.
2. Plan-approval gate ★. Phases up to approval are read-only. Code is written only after the operator approves and you call ExitPlanMode. Self-policed, not harness-enforced.
3. Doc + memory bookend ★. Scan the vault/memory at start; update it at end (incl. CLAUDE.md self-maintenance). Protocol → CLAUDE.md Memory section + references/memory-protocol.md.
4. DOTS-correct. ECS conventions per CLAUDE.md + references/dots-conventions.md. Any violation found in review is blocking.
5. Commit only when asked. Gated like the plan — offer + propose grouping in the final report; commit only on explicit "commit"; never push unless asked.
6. Operator gates. Present-forks-don't-auto-decide · no time/effort/deadline estimates · never-silently-defer · tuning-defaults autonomy. See Operator gates below.
7. Path-portable. Never write machine-specific absolute paths (/Users/…, C:\…) into the skill, code, docs, or .mcp.json — use repo-relative / ${CLAUDE_PROJECT_DIR}.

When to use / not use

Use for real DOTS work on an existing foundation: a system, component set, ghost/netcode surface, baking pipeline, refactor, or balance pass.

Don't use for: one-shot questions (answer directly); mechanical edits the operator already designed (just do them); harness/tooling setup; installing the DOTS stack (separate one-time task — Phase 0); non-DOTS work.

Size by blast-radius — do this first (NOT by time)

Pick the track from the surface touched, never from a minutes estimate.

Track	When	Path
Inline	one-file edit, rename, a fix you already understand; a pure *Math helper with no wire/bake change	scan → do → read_console clean → one-line session-log append. Plan-gate only if it mutates anything non-obvious.
Small	a single system/component, clear design, no ghost/prediction/RPC/relevancy/ordering/singleton-collision change	Ground (lite) → ctx7 verify → plan → approve → serial implement → verify L1–L2 → doc.
Feature	new mechanic, any replicated-surface change, cross-cutting refactor, anything on netcode-heavy surface	full spine incl. both reviews. The standard ultracode mode.

Blast-radius trigger (forces Feature + the pre-code review) — touches any of: a [GhostField] / ghost prefab · prediction or rollback · an IRpcCommand / input · GhostRelevancy · cross-system [UpdateBefore/After] / group ordering · a singleton resolve where a second of that type exists. A pure *Math.cs helper that doesn't change wire/bake is cheap — but still run the ghost/ordering check. Unsure → one AskUserQuestion ("quick edit or full feature pass?"), don't guess big.

ultracode = the named heavy mode for Feature work: raise reasoning, run the two-review sandwich + Workflow orchestration. The project ships in numbered Slices; run the Phase 4 review before each netcode-heavy Slice (standing practice — see CLAUDE.md / MEMORY).

The spine

Phase 0 — Pre-flight

1. Foundation check. com.unity.entities/com.unity.netcode in Packages/packages-lock.json? If absent, STOP — point to the one-time setup task (Docs/dots-setup-task.md). Never install/scaffold inline.
2. Unity ready. mcpforunity://editor/state → ready_for_tools. Not ready / no instance → surface, ask operator to focus Unity. Multiple editors → mcpforunity://instances + set_active_instance. (An unfocused editor throttles to near-idle and breaks Burst recompiles — ask for focus on heavy build/test/Burst sessions.)
3. Memory stack. Probe basic-memory + serena; on failure fall back (obsidian-cli + Glob/Grep) and continue.
4. Intake gate. Unclear scope/surface/output → bundle 2–4 ambiguities into one AskUserQuestion. Specific prompt → skip.

Phase 1 — Ground (read-only, plan mode)

Declare plan mode: read-only tools only (Read/Glob/Grep, MCP resource reads, unity_reflect, unity_docs, read_console, ctx7/find-docs, obsidian-cli reads, basic-memory, serena reads). No writes.

Run the Documentation-Protocol scan (CLAUDE.md → vault MoC + latest session log → open DRs/roadmap → basic-memory recall on the goal's nouns → native MEMORY.md), then ground the work along three lenses: code/asset graph (serena find_symbol/refs, else Glob/Grep on Assets/_Project/**/*.cs + *.asmdef; manage_scene get_hierarchy; unity_reflect for goal types) · knowledge state (vault + basic-memory; quote locked decisions that constrain the goal) · live state (editor/state, read_console baseline, installed Entities/Netcode versions for ctx7 pinning). For Feature scope, fan this out read-only via the Ground fan-out Workflow pattern; for Small, do it inline.

Synthesize a ≤400-word Project Brief; discard raw dumps. If the goal contradicts a locked vault/CLAUDE.md decision, halt and surface.

Phase 2 — ctx7 API verification

For every API/pattern the goal needs: ctx7 CLI (or find-docs) pinned to the installed version, cross-checked against ECS Samples, plus unity_reflect on the installed type. Synthesize a ≤500-word Research Digest (steal / avoid / still-unclear + the exact queries used). If a planned API is shown removed/renamed, halt and re-plan. Web (WebSearch/WebFetch) is allowed ONLY for design/genre precedent — never for a DOTS API shape (that path hallucinates). Research synthesizes-and-discards (reviews don't — Phase 4).

Phase 3 — Plan → ExitPlanMode gate

Produce a Unified Implementation Plan: summary; exhaustive files-to-create/modify (Unity + vault, repo-relative); code skeletons (signatures only); build order with explicit "compile + read_console" checkpoints; the verification approach (L1→L3 ladder); wire/bake-churn classification (does this re-bake the subscene, change a ghost hash, or change an RPC collection hash? — re-mean bytes vs rename, per CLAUDE.md); vault updates; risks & open questions. Present it; AskUserQuestion on any high-stakes ambiguity. On approval, ExitPlanMode — the hard boundary. Do not start Phase 5 without it.

Phase 4 — Pre-code design review (Feature / any blast-radius trigger)

Before writing code for any ghost/prediction/RPC/relevancy/ordering slice, run the Design-review (lens + adversarial-critic) Workflow pattern over the plan + ground-truth code. Three lenses — netcode/relevancy · determinism/prediction · reuse/scope — then adversarial critics that try to refute each finding against the actual code. This catches what green tests + a clean Play miss. The synthesized, code-grounded output is a durable Build Spec (kept at Docs/Vault/.../<Slice>_Build_Spec.md) that drives the build and feeds the DR — do not discard it. A surfaced design flaw loops back to Phase 3. Lens prompts → references/workflow-patterns.md.

Phase 5 — Implement (SERIAL orchestrator MCP edits — never an impl swarm)

The single stateful editor + domain-reload ordering make parallel writes unsafe — all Unity mutations are done by the orchestrator, serially. Parallelism is reserved for read-only research/review.

• Edit Assets .cs ONLY via MCP ★ (create_script new / get_sha→apply_text_edits existing / script_apply_edits for method+anchor edits). Raw Write/Edit on Assets/*.cs leaves a stale compiled assembly (and a raw-created .cs gets no .meta/test-discovery until refresh_unity scope=all mode=force). Write/Edit are fine for non-asset files (vault, asmdef JSON).
• apply_text_edits: one edit per call ★ (multiple non-adjacent edits can misalign), always with precondition_sha256.
• read_console(types=["error"]) after every write; fix before moving on. validate_script non-trivial files first. Re-query ctx7 for any ambiguous signature. Sequence across domain reloads (a component compiles before a system/baker references it). batch_execute for bulk wiring.
• Further MCP-edit hazards (script_apply_edits can't target a struct : ISystem; manage_gameobject/manage_prefabs silently drop enum + Vector3 → set via manage_components + verify; unfocused-editor stale-Burst) → CLAUDE.md "MCP / editor workflow" + "Burst hazards".
• Tuning autonomy: within an approved plan, pick sensible defaults + expose live knobs; consult only on a real gameplay/design fork.

Phase 6 — Verify ladder (definition of done — show evidence, not "done")

NetCodeTestWorld is internal and unused here — do NOT prescribe it.

• L1 — read_console(types=["error","warning","exception"], include_stacktrace=True) clean vs the Phase-1 baseline. Burst/source-gen failures surface here, not in a plain build — any new one is a finding.
• L2 — EditMode tests: plain-Entities new World → register in SimulationSystemGroup → SortSystems → Update → assert (run_tests mode=EditMode). Extract pure logic to a *Math.cs helper and unit-test it (cover swept hit-detection with a tunnelling regression). Plus one live Play netcode smoke — execute_code boot, step ticks, assert server == client for the replicated surface (identify worlds by world.Name == "ServerWorld"/"ClientWorld").
• L3 (visual/asset work) — screenshot via execute_code ScreenCapture → Read PNG, and verify asset values (shader.GetPropertyType-guard before GetColor/GetFloat) — a dark/stylized render masks material bugs.

Loop ≤3 fix iterations per finding; if iteration 3 still fails, halt and surface "I can't resolve X without a decision."

Phase 7 — Post-impl diff review (Feature)

Run the Design-review Workflow pattern over the git diff (same three lenses). Findings default-refuted — each must be confirmed against the code to stand — but flag any simplification of a reviewed design as a likely regression. This is the phase that has caught rollback bugs, region-routing regressions, and born-correct flaws that hundreds of green tests + a clean Play all missed. Real findings loop back to Phase 5.

Phase 8 — Doc + memory bookend (never skip)

Per CLAUDE.md Memory section + references/memory-protocol.md: session log → Docs/Vault/07_Sessions/<year>/<YYYY-MM-DD>_<Topic>.md (same-day → _A/_B); firm decisions → a DR in _Decisions/ back-referenced from the log (the kept Build Spec feeds it); touched design docs edited in place (wikilink); durable cross-machine knowledge → a basic-memory note; machine-local facts → native MEMORY.md. CLAUDE.md self-maintenance is part of this bookend — a new gotcha updates it under its 40 KB budget (archive, don't delete); never silently defer it. "Skip the protocol" → still write a one-line stub log + record the preference as a native memory.

Phase 9 — Final report + offer commit

## /dots-dev session complete — <Topic>
**Summary**: ≤4 sentences — goal, delivered, did it land cleanly.
**What changed**: Unity / Vault — <repo-relative path> — <one line> (repeat)
**Validation**: L1 console clean · L2 tests X/Y + Play smoke (server==client) · L3 <if visual>.
**Reviews**: pre-code <result> · post-impl <result>.
**Next step**: <one concrete next action from the log's Next-session intent>.

Then offer to commit and propose grouping; commit only on explicit approval. Review first (git status + git diff --stat); stage explicit paths — never git add -A (excludes Library/Temp/obj/Logs/UserSettings, .csproj/.sln, scratch screenshots/exports); keep each asset with its .meta in one commit; one commit per concern; match the repo's message style + the Co-Authored-By trailer; never push. Don't auto-loop into a fresh session.

Workflow orchestration (the parallelism primitive)

Manual "spawn ≤N agents" is dead — read-only fan-out (ground, design-review, diff-review) runs as deterministic Workflows with run-IDs and resumeFromRunId. Implementation never fans out (serial, Phase 5). Per-pattern lens prompts live in references/workflow-patterns.md; the two cross-cutting rules:

• Always check the failures list ★. A Workflow whose agents die on a session/quota limit returns empty findings that masquerade as a clean pass. Check failures explicitly; if any died, wait for the reset and re-run with resumeFromRunId — never treat an empty result as "no findings."
• Scope subagent guardrails POSITIVELY ★. A blanket "do NOT use tool X" in a subagent prompt gets read by the auto-approver as a user rule and can deny the orchestrator's own later call. Tell agents what they MAY do (read-only, these tools), not what they mustn't.

Pass only the upstream summary downstream — never raw agent dumps (research discards; the design-review Build Spec is the deliberate exception — keep it).

Operator gates

• Present forks, don't auto-decide. Gameplay/design forks are the operator's call: present each with a recommendation, lock only what's approved, re-run the fork-locking ritual before each new milestone set. A Workflow that tries to auto-lock forks must be halted.
• No time estimates. Never frame work by minutes/effort/deadlines — the operator owns scheduling. Size by blast-radius, keep the engineering discipline.
• Never silently defer/descope mid-task (incl. CLAUDE.md maintenance) — do it now or explicitly ask the operator to decide.
• Tuning-defaults autonomy — for polish/balance, pick sensible defaults + live knobs; consult only on a real fork.
• Aggressive-cleanup opt-in — for an explicit cleanup session the operator may opt into max scope (deep behavior-preserving refactor, aggressive deletion, "commit for me" in logical groups on main, no push).

Boundaries

Stop and consult when: intake too thin · goal contradicts a locked decision · a material design choice has no clear best answer · plan gate (always) · 3 failed fix iterations on one finding · operator intent drifts · a destructive op outside the approved plan is implied · the DOTS foundation is missing.

May loop without consulting (≤3): compile/Burst fix→recompile · test fail→fix→retest · vault write fail→re-read→retry.

Abort without writing partial state when: Unity unreachable >60s mid-session · project broken (asmdefs missing, won't load). If the Phase-8 vault write fails repeatedly, write a local fallback note + tell the operator — don't lose the session record.

A bare mcp__UnityMCP__* error is NOT proof Unity is down — before reporting it, run the diagnostic probe (CLAUDE.md / mcpforunity://instances → editor/state → manage_editor telemetry_ping; InputValidationError for an unknown tool = deferred schema → ToolSearch select: then retry). Escalate only after those fail.

References (load on demand)

• references/dots-conventions.md — the reusable ECS/Netcode rule set this skill enforces (defers to CLAUDE.md).
• references/context7-libraries.md — ctx7/find-docs flow + 6.5-era pinned library IDs.
• references/workflow-patterns.md — the named Workflow patterns (ground fan-out · design-review lens + adversarial-critic).
• references/memory-protocol.md — the four memory layers + bookend detail.