Luis Gonzalez
a5af81c8a8
Move the dots-dev skill from machine-local ~/.claude/skills/ into the repo at .claude/skills/dots-dev/ so it travels with a clone. Update the CLAUDE.md per-machine setup note to reflect that the skill no longer needs manual placement; unity-mcp-skill and native memory/ stay local. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
99 lines
7.6 KiB
Markdown
99 lines
7.6 KiB
Markdown
# 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.
|