kronic/Project-M
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Rewrite /dots-dev skill: Workflow-first, two-review sandwich, 6.5 pins

Browse Source 
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>
This commit is contained in:
Luis Gonzalez
2026-06-18 21:19:49 -07:00
parent 6b368d1a29
commit 4ac1ae5a2e
6 changed files with 180 additions and 329 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.claude/skills/dots-dev/references/context7-libraries.md
+36 -29
View File
@@ -1,44 +1,51 @@
# context7 — DOTS library IDs & query playbook
# ctx7 / find-docs — DOTS library IDs & query playbook
**context7 is the primary source of truth for every DOTS API, signature, and "current best practice."** Unity's Entities/Netcode packages change between minor versions; training-data recall is stale. Resolve → query before writing DOTS code.
**The `ctx7` CLI (or the `find-docs` skill) is the primary source of truth for every DOTS API, signature, and "current best practice."** Unity's Entities/Netcode/Physics packages change between versions and training-data recall is stale — resolve → query before writing DOTS code.
## Flow
> The old context7 **MCP** verbs (`resolve-library-id` / `query-docs`) are **not in this environment's tool surface** — do not call them. Use the CLI / skill below.
1. `resolve-library-id(libraryName, query)` → pick the Context7 ID (prefer High reputation + high snippet count + version matching the **installed** package).
2. `query-docs(libraryId, query)` with a *specific* question ("How do I declare an IInputComponentData and read it in a predicted system in Netcode 1.x?"), not a bare keyword.
3. Cross-check working patterns against the official **ECS Samples** repo ID below.
4. Limit: ≤3 `resolve` calls and ≤3 `query` calls per question (the tool enforces this). Reuse IDs across a session.
## Flow (per the global `ctx7` rule)
1. **Resolve:** `npx ctx7@latest library "<official name>" "<your specific question>"` → pick the `/org/project` ID (prefer High reputation + high snippet count + the version closest to **installed**). Use proper punctuation in the name ("Netcode for Entities", "Unity Physics", "Entities Graphics").
2. **Fetch:** `npx ctx7@latest docs <libraryId> "<your specific question>"` — ask a *specific* question ("How do I read an `IInputComponentData` inside a predicted system filtered by `Simulate`?"), not a bare keyword.
3. Cross-check working patterns against the **ECS Samples** repo ID below.
4. Limit ≤3 `library` + ≤3 `docs` calls per question; reuse IDs across a session. On a quota error, suggest `npx ctx7@latest login` / `CONTEXT7_API_KEY` — don't silently fall back to memory.
5. The **`find-docs` skill** is an equivalent path (it wraps the same source) — either is fine.
## Two-source rule (do BOTH)
Pair every doc lookup with **`unity_reflect` on the installed type** for the real, version-pinned shape. Docs give the *current API*; reflection gives *what's actually compiled in this project* — they can disagree, and **reflection wins for the pinned engine version.** (A research-only lookup once produced a false-negative on a character-controller API that reflection would have caught.)
## Pin to the installed version
Before querying, read the installed version from `Packages/packages-lock.json` (or `manage_packages action=list`). If it differs from a seed ID's version, **re-resolve** and prefer the doc set matching what's installed. The seeds below were captured during skill authoring and may lag the project.
Read installed versions from `Packages/packages-lock.json` (or `manage_packages action=list`) before querying. This project runs the **unified Unity 6.5 line**: `com.unity.entities` / `com.unity.netcode` / `com.unity.physics` all **6.5.0** (the 6.x scheme tracks the Editor; it succeeded the old 1.x lines — Entities 6.4/6.5 is the direct successor to 1.4, Netcode 6.5 to the old ~1.12/1.13 line). **"1.13.2" is no longer an installable version** — treat any 1.x number as API-shape *lineage*, not a target string.
## Seed library IDs (re-resolve if installed version differs)
## Seed library IDs (verified live 2026-06-18 — re-resolve at code-time)
| Package | Primary Context7 ID | Alt | Notes |
|---|---|---|---|
| **Entities (DOTS)** | `/websites/unity3d_packages_com_unity_entities_1_4` | `/needle-mirror/com.unity.entities` | ~7,099 snippets, High. Core ECS. |
| **Netcode for Entities** | `/websites/unity3d_packages_com_unity_netcode_1_10_api` | `/websites/unity3d_packages_com_unity_netcode_1_9` | ~2,512 snippets, High. Ghosts/prediction/RPC/input. |
| **Entities Graphics** | `/websites/unity3d_packages_com_unity_entities_graphics_1_4` | — | Rendering entities under URP/HDRP. |
| **Official ECS Samples** | `/unity-technologies/entitycomponentsystemsamples` | — | Working sample patterns; Entities, Netcode, Physics, Graphics. |
| **Unity Physics** | resolve at runtime | — | `resolve-library-id(libraryName="Unity Physics", query="DOTS collision/triggers")`. |
| **Burst** | resolve at runtime | — | `libraryName="Unity Burst"`. |
| **Collections** | resolve at runtime | — | `libraryName="Unity Collections"` (Native/Unsafe containers, allocators). |
| **Mathematics** | resolve at runtime | — | `libraryName="Unity Mathematics"` (float3/quaternion/math). |
The doc sets on context7 currently **lag the package version** for most DOTS packages — only Entities has a `6_5` set. Pin the live top hit, knowing the package is 6.5.0; re-resolve when a newer set publishes.
> Confirm Netcode for Entities is `com.unity.netcode` (the ECS netcode), **not** `com.unity.netcode.gameobjects` (Netcode for GameObjects). They are different products.
| Package | Pin (live top hit) | Alt / notes |
|---|---|---|
| **Entities (DOTS)** | `/websites/unity3d_packages_com_unity_entities_6_5_manual` | version-matched; matches CLAUDE.md. Alt `…entities_1_4` has far more snippets (~10.8k) — useful for code patterns. |
| **Netcode for Entities** | `/websites/unity3d_packages_com_unity_netcode_1_10_api` | the live top hit (~4.3k snippets, High) — **no `netcode_6_5` set exists yet.** Package is 6.5.0; this is the closest published. Alt `…netcode_1_9`. |
| **Unity Physics** | `/websites/unity3d_packages_com_unity_physics_1_4` | live top hit (~4k snippets, High) — **no `physics_6_5` set yet.** Package is 6.5.0. |
| **Entities Graphics** | `/websites/unity3d_packages_com_unity_entities_graphics_1_4` | live top hit — **no `_graphics_6_5` set yet.** Package is 6.5.0. |
| **Official ECS Samples** | `/unity-technologies/entitycomponentsystemsamples` | working sample patterns (Entities/Netcode/Physics/Graphics). |
| **Burst / Collections / Mathematics** | resolve at runtime | `library "Unity Burst"` / `"Unity Collections"` / `"Unity Mathematics"`. |
## Query patterns that work (examples)
> **Netcode for Entities ≠ Netcode for GameObjects.** Confirm it's `com.unity.netcode` (ECS), not `com.unity.netcode.gameobjects`.
> **CLAUDE.md's own pinned-ID note is itself partly stale** (it still says "we run 1.13.2") — lead with the installed 6.5.0 + the live re-resolve, and reconcile CLAUDE.md when you touch it.
- "Entities 1.x: declare an `IJobEntity` that writes through an `EntityCommandBuffer.ParallelWriter` and schedule it with the right dependency."
- "Netcode for Entities: minimal `GhostAuthoringComponent` + `[GhostField]` setup for a predicted player-controlled ghost."
- "Netcode for Entities: read `IInputComponentData` inside a system in `PredictedSimulationSystemGroup`, filtered by `Simulate`."
- "Entities: correct `Baker<T>` use of `GetEntity` with `TransformUsageFlags` and `DependsOn`."
- "Netcode for Entities: subclass `ClientServerBootstrap` to create client/server worlds and target systems with `WorldSystemFilter`."
- "Entities: `IEnableableComponent` vs add/remove tag — API and when each is cheaper."
## Query patterns that work
## When NOT to use context7
- "Entities: declare an `IJobEntity` writing through an `EntityCommandBuffer.ParallelWriter`, schedule with the right dependency."
- "Netcode for Entities: minimal `GhostAuthoringComponent` + `[GhostField]` for a predicted player-controlled ghost."
- "Netcode for Entities: read `IInputComponentData` in a system in `PredictedSimulationSystemGroup`, filtered by `Simulate`."
- "Entities: `Baker<T>` use of `GetEntity` with `TransformUsageFlags` + `DependsOn`."
- "Entities: `IEnableableComponent` vs add/remove tag — API + when each is cheaper."
- Genre/design precedent ("how do other games pace waves") → `WebSearch`/`WebFetch`.
## When NOT to use ctx7
- Genre/design precedent ("how do other games pace waves") → `WebSearch`/`WebFetch`. **Never use web for a DOTS API shape.**
- Pure C#/algorithm questions unrelated to a library → reason directly.
- The project's own conventions/design → `CLAUDE.md` + the vault.