kronic
4ac1ae5a2e
Realigns the skill with how sessions actually run now — it predated the Workflow tool and the ultracode two-review practice. Driven by an analysis of the full session history + the 26-file memory corpus + skill-authoring research, adversarially reviewed. Key changes: - Workflow-first orchestration: drop the dead manual "swarm (<=N agents)" model and the impossible 3-5-agent impl swarm; implementation is serial orchestrator MCP edits. New references/workflow-patterns.md (ground fan-out + design-review lens/critic) replaces agent-briefs.md. - Pre-code design-review + post-impl diff-review are now first-class gated phases (the spine that catches what green tests + a clean Play miss). - Size by blast-radius / netcode-heaviness, not time estimates. - Lean SKILL.md (222 -> 131 lines, -25% KB): leans on CLAUDE.md instead of duplicating its MCP cheat-sheet / anti-patterns / error-recovery. - ctx7 CLI / find-docs mechanism (the MCP verbs are gone); live-verified 6.5-era library pins; kill the dead NetCodeTestWorld test path. - Encode operator gates (no-time-estimates, present-forks, never-defer, tuning-autonomy) + the highest-recurrence MCP-edit / Workflow gotchas. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
132 lines
17 KiB
Markdown
132 lines
17 KiB
Markdown
---
|
||
name: dots-dev
|
||
description: 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`](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`](references/memory-protocol.md).
|
||
4. **DOTS-correct.** ECS conventions per `CLAUDE.md` + [`references/dots-conventions.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`](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`](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`](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`](references/dots-conventions.md) — the reusable ECS/Netcode rule set this skill enforces (defers to `CLAUDE.md`).
|
||
- [`references/context7-libraries.md`](references/context7-libraries.md) — `ctx7`/`find-docs` flow + 6.5-era pinned library IDs.
|
||
- [`references/workflow-patterns.md`](references/workflow-patterns.md) — the named Workflow patterns (ground fan-out · design-review lens + adversarial-critic).
|
||
- [`references/memory-protocol.md`](references/memory-protocol.md) — the four memory layers + bookend detail.
|