Project-M/.claude/skills/dots-dev/references/workflow-patterns.md

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}. Use Glob/Grep on Assets/_Project/**/*.cs + **/*.asmdef (serena was removed 2026-07-07 — C# nav is Glob/Grep). 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.