Project-M/.claude/skills/dots-dev/references/agent-briefs.md

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; the context7 playbook in 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 .asmdefs 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.