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/agent-briefs.md
-98
View File
@@ -1,98 +0,0 @@
# Per-phase swarm brief templates
Fill the `{…}` variables and paste into the agent prompt. Keep each agent's context lean — pass only the immediately upstream summary, not the whole session. Every research/scan brief is **read-only** (plan mode through Phase 5). All briefs assume the agent will return raw data/findings, not a human-facing message.
Conventions referenced below live in [`dots-conventions.md`](dots-conventions.md); the context7 playbook in [`context7-libraries.md`](context7-libraries.md).
---
## Phase 1 — Context (Explore, read-only)
**A — Code/asset graph**
> READ-ONLY. Map the code surface relevant to `{goal}`. Prefer serena `find_symbol`/`find_referencing_symbols` over text search; if serena's C# LSP errors or times out on the Unity solution, fall back to `Glob`/`Grep` on `Assets/_Project/**/*.cs` and `**/*.asmdef`. Identify: existing components/systems/bakers touching `{surface}`, the asmdef each lives in (shared-simulation / client / server / authoring), and any TODOs. Also `manage_scene(action="get_hierarchy")` for relevant subscenes. Return a terse symbol/asmdef map (names + paths), not file dumps.
**B — Knowledge state**
> READ-ONLY. Search the in-repo vault (obsidian-cli) and `basic-memory` for design docs, decision records, and notes touching `{goal}`. Return: relevant doc paths, any locked decisions that constrain `{goal}`, open questions already recorded. Quote ≤2 load-bearing lines each; link by path otherwise.
**C — Unity live state**
> READ-ONLY. Read `mcpforunity://editor/state`, `project/info`, `instances`. `read_console(types=["error","warning"], count=20)`. `manage_packages(action="list")` — report the **installed** Entities + Netcode versions (needed to pin context7). Flag any pre-existing compile/Burst errors as a baseline.
---
## Phase 2 — Goal spec (general-purpose)
> Inputs: operator's verbatim goal + the Phase 1 Project Brief, nothing else. Produce a Goal Spec: **Deliverables** (each: name, surface, "done when"), **Assumptions** (to validate at review), **Open ambiguities** (frame each as a yes/no or multiple-choice question). Flag any conflict with a locked decision from the brief.
---
## Phase 3 — Research (context7-first)
**A — DOTS/Netcode implementation (context7 primary)**
> Inputs: Goal Spec only. For each API/pattern `{goal}` needs, use context7: `resolve-library-id` (seeds in context7-libraries.md; pin to the installed version `{entities_ver}`/`{netcode_ver}`) → `query-docs` with specific questions. Cross-check the official ECS Samples repo. Return: for each deliverable, the current correct API shape + a minimal code pattern + the exact context7 query used. Flag any API the plan assumes that context7 shows removed/renamed.
**B — Determinism / netcode correctness (context7 + samples)**
> Inputs: Goal Spec only. Confirm via context7: prediction-group placement, `Simulate` filtering, ghost replication setup, input (`IInputComponentData`) flow, world/bootstrap shape for `{goal}`. Return current API shapes + determinism pitfalls specific to `{goal}`.
**C — Genre/design precedent (web, optional)**
> Inputs: Goal Spec only. `WebSearch`/`WebFetch` ONLY. How do comparable games solve the *design* of `{mechanic}`? Return: what to steal / what to avoid. Do NOT return DOTS API claims from the web.
Orchestrator synthesizes a ≤500-word Research Digest (steal / avoid / still-unclear + the context7 queries used).
---
## Phase 4 — Design & plan (Plan, read-only)
**A — Code architect**
> Inputs: Brief + Goal Spec + Research Digest. Design the C#/ECS layer for `{goal}` respecting dots-conventions.md: components (`IComponentData`/buffer/enableable), systems (`ISystem`+Burst vs `SystemBase`), jobs, system groups/order, ECB usage, and which asmdef each file lands in. Output: file list (repo-relative) + class/system signatures only (no bodies) + build order with compile checkpoints.
**B — Scene/subscene/baking architect**
> Inputs: same. Design authoring + baking: `…Authoring` MonoBehaviours + `Baker<T>`, subscene layout, ghost prefabs/authoring, config assets, URP/Entities-Graphics needs. Output: assets/subscenes to create (repo-relative) + what bakes into what.
**C — Vault doc architect**
> Inputs: same. Design vault changes: which design docs get edited in place, whether a decision record is warranted, the session-log scaffold. Output: doc paths + one-line intent each (wikilink, don't duplicate).
Orchestrator writes the Unified Implementation Plan (see SKILL Phase 4).
---
## Phase 6 — Implementation (general-purpose)
**A — Script author**
> Inputs: the approved plan slice for `{files}`. Create via `create_script`, edit existing via `get_sha`→`apply_text_edits`. `validate_script` non-trivial files first. `read_console(types=["error"])` after EVERY write; fix before moving on. Re-query context7 for any signature the digest left ambiguous. Honor dots-conventions.md (Burst-compatible, unmanaged components, deterministic sim, ECB for structural changes).
**B — Scene/subscene/baking wirer**
> Inputs: the approved plan slice. Create authoring components, subscenes, ghost prefabs, config assets; save scenes. Confirm Edit Mode (`manage_editor(action="play_state")`) before structural changes. `batch_execute` for bulk. Wait for a referenced component to compile before attaching/baking it.
**C — Asmdef/package guardian** (conditional)
> Inputs: the approved plan slice. Add/adjust `.asmdef`s keeping the client/server/shared/authoring split clean. Never touch `.csproj`/`.sln`. Verify it compiles via `read_console`.
**D — Doc-skeleton author** (conditional)
> Inputs: the approved plan slice. Create new vault docs with full frontmatter skeletons via obsidian-cli (bodies are written in Phase 8).
---
## Phase 7 — Validate (general-purpose, DOTS-aware)
**A — Console/Burst/source-gen sweep**
> `read_console(types=["error","warning","exception"], count=50, include_stacktrace=True)`. Compare to the Phase-1 baseline. Any NEW error/warning — including Burst/source-gen — is a finding. Return blocking vs nit.
**B — Test runner**
> If the plan specified tests: `run_tests(mode="EditMode")`→`get_test_job(... include_failed_tests=True)`; PlayMode if applicable. For netcode: a `NetCodeTestWorld` connect/tick test or a thin-client check. Return pass/fail with failing-test detail.
**C — Runtime/determinism spot-check**
> If visual/runtime: brief Play Mode entry (`set_play_state`), step ticks, confirm predicted/interpolated ghosts behave; screenshot Game/Scene view (`manage_camera`); exit to Edit Mode. Verify each plan-specified entity/component exists (`get_hierarchy` + `manage_components(action="get")`). Return findings.
Fix loop: ≤3 iterations per finding via a tight 1–2 agent fix sub-swarm, re-running only the affected validator.
---
## Phase 8 — Doc + memory (general-purpose)
**A — Session log**
> Write `<repo>/Docs/Vault/07_Sessions/{year}/{date}_{Topic}.md` via obsidian-cli using the vault's session-log template. Sections: Goal, What happened, Decisions (link records), Files touched (Unity + vault, repo-relative), Open questions, Next-session intent, Notes. Same-day collision → suffix `_A`/`_B`.
**B — Decision records + design docs**
> For each firm decision, write a decision record in `_Decisions/`, back-referenced from the session log. Edit touched design docs in place (wikilink, don't duplicate). Update roadmap/backlog for deferred items.
**C — Memory updater**
> Durable cross-machine knowledge → a `basic-memory` note in the vault. Machine-local facts/feedback/working-style → native `MEMORY.md` (+ a memory file if substantive). Do NOT put cross-machine truth only in native memory — it doesn't sync between the Mac and Windows machines.
.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.
.claude/skills/dots-dev/references/dots-conventions.md
+4 -4
View File
@@ -1,6 +1,6 @@
# DOTS / Netcode for Entities — Conventions & Gotchas
Reusable rule set the `/dots-dev` skill enforces. Targets **Unity 6.x, Entities 1.3+/1.4+, Netcode for Entities 1.x**. These APIs move fast — anything flagged **[verify]** must be confirmed via context7 at code-time (see [`context7-libraries.md`](context7-libraries.md)), not trusted from memory. The project's `CLAUDE.md` is authoritative where it differs.
Reusable rule set the `/dots-dev` skill enforces. Targets **Unity 6.5, Entities 6.5, Netcode for Entities 6.5 (≡ the old ~1.12/1.13 API lineage), Unity Physics 6.x** — the unified 6.x DOTS line. These APIs move fast — anything flagged **[verify]** must be confirmed via `ctx7`/`find-docs` at code-time (see [`context7-libraries.md`](context7-libraries.md)), not trusted from memory. The project's `CLAUDE.md` is authoritative where it differs.
These conventions **replace** classic MonoBehaviour/GameObject conventions. If a design reaches for a MonoBehaviour singleton, a ScriptableObject "service" for runtime simulation, `[SerializeField] private` data carriers, or coroutines for sim logic, it is almost certainly wrong for DOTS.
@@ -53,9 +53,9 @@ These conventions **replace** classic MonoBehaviour/GameObject conventions. If a
## 6. Testing (what "compiles clean" misses)
- **`NetCodeTestWorld`** — spins up in-process client+server worlds for deterministic tick-by-tick netcode tests (connect, tick, assert on ghosts/RPCs).
- **Thin clients** — stripped dummy clients for soak/load testing in-editor (no rendering/full sim); spawn via Multiplayer PlayMode Tools.
- **Entities logic** — standard test world + `World.Update()` stepping (EntitiesTestFixture-style).
- **Default = plain-Entities EditMode test:** `new World` → register the system in `SimulationSystemGroup` → `SortSystems` → `Update()` → assert. Public API, version-independent. This is the project's actual harness.
- **Extract pure logic to a `*Math.cs` helper and unit-test it** — deterministic, fast, version-proof. Cover swept hit-detection with a **tunnelling regression** (a point-based test won't catch the tunnel).
- **Netcode coverage = one live Play smoke:** boot client+server (`execute_code`), step ticks, assert **server == client** for the replicated surface (identify worlds by `world.Name == "ServerWorld"/"ClientWorld"`). **`NetCodeTestWorld` is `internal`** in this line (exposed only to a fixed allow-list) and **0 of the project's test files use it** — do not prescribe it as the primary path. (Thin clients via Multiplayer PlayMode Tools exist for soak/load testing if ever needed — not in current practice.)
- Burst/source-gen failures surface at **editor compile/play**, not a plain C# build. Determinism desync, rollback bugs, sync-point stalls, and structural-change invalidation only show at **runtime under prediction** — always run a play/tick test, not just a build.
## 7. Verify via context7 at code-time (volatile — do NOT hardcode)
.claude/skills/dots-dev/references/memory-protocol.md
+10 -26
View File
@@ -1,25 +1,8 @@
# Memory & Documentation Protocol
How `/dots-dev` reads and writes knowledge. Four layers, each with a distinct job. The **in-repo vault is the single source of human-facing, cross-machine truth**; everything else serves or accelerates it.
How `/dots-dev` reads and writes knowledge. **`CLAUDE.md`'s "Memory — four layers" section is authoritative** for the layer definitions and the which-tool-when routing (in-repo vault · `basic-memory` · `serena` · native `memory/`) — this file does not re-table them; it carries the **session bookends** and the **fallback chain**.
## The four layers
| Layer | Holds | Interface | Crosses machines? |
|---|---|---|---|
| **In-repo Obsidian vault** `<repo>/Docs/Vault/` | Design docs, decision records, session logs, roadmap — the canonical human-facing record | **obsidian-cli** skill (read/create/search); Obsidian REST MCP optional | **Yes** (committed to git) |
| **basic-memory** MCP | Semantic + wikilink-graph recall over the *same* vault files (so the agent finds knowledge without grepping) | `basic-memory` MCP tools | Yes (indexes the committed vault) |
| **serena** MCP | C# symbol-level code navigation (`find_symbol`, references, edit-by-symbol) of a growing codebase | `serena` MCP tools | N/A (derived from code) |
| **Native Claude memory** | Machine-local facts, feedback, working-style; the per-project `memory/` dir + `MEMORY.md` + `CLAUDE.md` | Write tool / memory files | **No** — local to each machine |
**Cross-machine rule:** anything that must be true on both your Mac and Windows machines goes in the **vault** (or `CLAUDE.md`, which is also committed). Native `memory/` is convenience only — never the sole home of a decision or design fact.
## Which tool when
- **"Where is X defined / who calls it?"** → serena `find_symbol` / references. Fall back to `Glob`/`Grep` if serena's C# LSP stalls on the Unity solution.
- **"What did we decide about Y / how does system Z work conceptually?"** → `basic-memory` recall, then obsidian-cli to read the doc.
- **"Find the literal string/asset GUID"** → `Grep`/`Glob`.
- **"What's the current DOTS/Netcode API for…?"** → context7 (NOT memory). See [`context7-libraries.md`](context7-libraries.md).
- **"What conventions/preferences apply here?"** → `CLAUDE.md` + native memory.
**Cross-machine rule:** anything that must be true on both the Mac and Windows machines goes in the **vault** (`Docs/Vault/`) or **`CLAUDE.md`** (both committed). Native `memory/` is machine-local convenience — never the sole home of a decision or design fact.
## Session bookends (non-negotiable for non-trivial work)
@@ -30,19 +13,20 @@ How `/dots-dev` reads and writes knowledge. Four layers, each with a distinct jo
4. `basic-memory` recall on the goal's nouns; native `MEMORY.md` + `memory/`.
**End — update (Phase 8):**
1. Session log written to the vault (obsidian-cli).
2. Firm decisions → decision records, back-referenced from the log.
1. Session log → the vault (obsidian-cli or direct Write).
2. Firm decisions → decision records, back-referenced from the log. **The kept design-review Build Spec feeds the DR** (don't re-derive it).
3. Touched design docs edited in place (wikilink, don't duplicate into the log).
4. Durable knowledge → `basic-memory` note in the vault; machine-local facts → native `MEMORY.md`.
4. Durable cross-machine knowledge → a `basic-memory` note in the vault; machine-local facts/feedback → native `MEMORY.md` (+ a memory file if substantive).
5. **CLAUDE.md self-maintenance** — if a new build gotcha or convention emerged, fold it in under the 40 KB budget (archive the displaced detail to the gotchas archive, don't delete). Never silently defer this — do it now or explicitly ask the operator to defer.
If the operator says "skip the protocol", still write a one-line stub session log so the gap is visible, and record the preference as a native feedback memory.
If the operator says "skip the protocol," still write a one-line stub session log so the gap is visible, and record the preference as a native feedback memory.
## Fallbacks
- **No obsidian-cli configured** → direct `Read`/`Write` on `<repo>/Docs/Vault/**` (it's plain markdown; Obsidian/basic-memory pick up changes on next index).
- **No obsidian-cli configured** → direct `Read`/`Write` on `Docs/Vault/**` (it's plain markdown; Obsidian/basic-memory pick up changes on next index). This is the operative path on a fresh machine.
- **basic-memory down** → obsidian-cli search + `Grep` over the vault.
- **serena C# unavailable** → `Glob`/`Grep`, or `claude-context` (local LanceDB) if it was added as the documented fallback.
- **serena C# unavailable / stalls on the Unity solution** → `Glob`/`Grep` (or `claude-context`/LanceDB if it was added as the documented fallback).
## Setup pointer
The vault scaffold, the `basic-memory`/`serena` `.mcp.json` entries (using `${CLAUDE_PROJECT_DIR}`), and `CLAUDE.md` are created by the **one-time project setup task**, not by this skill. If this skill runs and the vault or memory MCPs are missing, it notes the gap and points to that setup task.
The vault scaffold, the `basic-memory`/`serena` `.mcp.json` entries (using `${CLAUDE_PROJECT_DIR}`), and `CLAUDE.md` are created by the **one-time project setup task** (`Docs/dots-setup-task.md`), not by this skill. If this skill runs and the vault or memory MCPs are missing, it notes the gap and points to that setup task.
.claude/skills/dots-dev/references/workflow-patterns.md
+48
View File
@@ -0,0 +1,48 @@
# Workflow patterns for /dots-dev
The read-only fan-out phases run as deterministic **Workflows** (the `Workflow` tool), not hand-spawned agents. This file holds the two reusable patterns SKILL.md names. **There is no implementation pattern** — implementation is always serial orchestrator MCP edits (SKILL.md Phase 5), never a Workflow.
Two rules apply to every pattern here:
- **Check the failures list.** A Workflow whose agents die on a session/quota limit returns empty findings that look like a clean pass. If any agent died, wait for the reset and re-run with `resumeFromRunId` — never read an empty result as "no findings."
- **Scope guardrails positively.** Tell each agent what it MAY do (read-only; these tools), never "do NOT use tool X" — a blanket prohibition gets read as a *user* rule by the auto-approver and can deny the orchestrator's own later calls. Every brief here is read-only; pass only the upstream summary downstream.
---
## Pattern A — Ground fan-out (Phase 1, Feature scope)
Three read-only lens agents in `parallel()`; the orchestrator synthesizes the ≤400-word Project Brief and discards the raw returns.
**A1 — Code/asset graph (read-only).**
> Map the code surface relevant to `{goal}`. Prefer serena `find_symbol`/`find_referencing_symbols`; if serena's C# LSP stalls on the Unity solution, use `Glob`/`Grep` on `Assets/_Project/**/*.cs` + `**/*.asmdef`. Identify the existing components/systems/bakers touching `{surface}`, the asmdef each lives in (Simulation / Client / Server / Authoring), and any `*Math.cs` helper or system you'd otherwise duplicate. `manage_scene get_hierarchy` for relevant subscenes. Return a terse symbol/asmdef map (names + paths), not file dumps.
**A2 — Knowledge state (read-only).**
> Search the in-repo vault (obsidian-cli) and `basic-memory` for design docs, decision records, and notes touching `{goal}`. Return: relevant doc paths, any **locked** decisions that constrain `{goal}`, open questions already recorded. Quote ≤2 load-bearing lines each; link by path otherwise.
**A3 — Live state (read-only).**
> Read `mcpforunity://editor/state`, `project/info`, `instances`. `read_console(types=["error","warning"], count=20)` for a baseline. Report the **installed** Entities + Netcode versions (`packages-lock.json`) so ctx7 lookups pin correctly. Flag any pre-existing compile/Burst error.
---
## Pattern B — Design-review (lens + adversarial-critic)
Used **pre-code** over the plan (Phase 4) and **post-impl** over the git diff (Phase 7) — identical lenses, two inputs. Stage 1 = three lens agents in `parallel()` over ground-truth code; stage 2 = synthesize; stage 3 = adversarial critics that try to *refute* each finding against the actual code. **Findings default-refuted** — a finding stands only if a critic confirms it against the code. Post-impl additionally: **flag any simplification of a reviewed design as a likely regression** (this is the catch green tests + a clean Play miss). The synthesized output is a **durable Build Spec** — keep it (it feeds the build and the DR), unlike research which is discarded.
**B1 — Netcode / relevancy lens (read-only).**
> Review `{plan|diff}` against ground-truth code for netcode correctness: ghost ownership (predicted vs interpolated vs ownerless — move ownerless interpolated ghosts server-only); `[GhostField]` vs server-only fields; `GhostRelevancy` region splits (`SetIsIrrelevant`, untagged-stays-relevant); singleton-collision (a second `StorageEntry`/buffer of the same type → resolve by distinct tag, never `GetSingleton<T>`); command-vs-input choice (one-shot shared actions → `IRpcCommand`, not a dropped `InputEvent`); RPC wire-hash stability (unconditional struct, re-mean-don't-rename). Return findings: claim · file:line · why it's wrong · fix.
**B2 — Determinism / prediction lens (read-only).**
> Review for rollback-safety: `PredictedSimulationSystemGroup` runs multiple times per frame → idempotent, `.WithAll<Simulate>()`, no wall-clock/`Time.deltaTime`/`System.Random`; tick sentinels routed through `TickUtil.NonZero` + compared with `NetworkTick.IsNewerThan` (never raw `uint <`); predicted-physics group ordering (OrderFirst quirks); swept-not-point hit tests (tunnelling); ECB at-most-once destroy. Cross-assembly generics + enums in a Bursted system → ICE (store ops as `byte`). Return findings as in B1.
**B3 — Reuse / scope lens (read-only).**
> Does `{plan|diff}` duplicate an existing system or `*Math` helper instead of reusing it? Is the scope minimal — anything over-built, or a feature that could reuse a replicated component already on the wire? Any MonoBehaviour-world shortcut (MonoBehaviour singleton, ScriptableObject "service" for runtime sim, coroutine for sim) where ECS is correct? Any new `IAspect` (deprecated)? Return findings as in B1.
**Critic (stage 3, read-only).**
> Here is a candidate finding: `{finding}`. Try to REFUTE it by reading the actual code at `{paths}`. Default to "refuted" unless the code confirms the problem is real and reachable. Return: refuted | confirmed · the code evidence · (if confirmed) severity + the minimal fix.
---
## Orchestration notes
- Sizes scale to the ask: a small ghost change → one lens + a single critic pass; "thoroughly review this slice" / ultracode → all three lenses + 3-vote adversarial critics + a completeness pass.
- Keep agent context lean — each gets the plan/diff slice + the relevant ground-truth paths, not the whole session.
- The Build Spec is line-numbered and lives at `Docs/Vault/.../<Slice>_Build_Spec.md`; the run-ID (`wf_…`) is recorded in the session log / DR for `resumeFromRunId`.