# 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`, 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 `/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.