Windsurf rules

1---
2name: dispatch-agents
3model: sonnet
4description: "Dispatch multiple subagents in parallel on independent tasks. No waiting between them — all run concurrently. Use when tasks are truly decoupled and speed matters. Distinct from delegate-task (concurrent here, no inter-task review gate)."
5---
6 
7# story: e09s04
8# story: e45s38
9<!-- story: e45s11 -->
10 
11 
12# story: e45s30
13 
14# Dispatch Agents
15> **HARD GATE** — **HARD GATE** — Agent work must be parallelizable and have explicit synchronization points. Do NOT dispatch work that has hidden dependencies between agents.
16 
17 
18Run multiple subagents in parallel on independent tasks. Use when tasks are genuinely decoupled — no agent needs the output of another to start.
19 
20**Distinct from `delegate-task`:** This skill maximizes throughput via concurrency. There is no sequential review gate between tasks. Use `delegate-task` instead when a single task needs careful two-stage oversight before proceeding.
21 
22## When to use
23 
24- Tasks that can run simultaneously without shared state
25- Large plans that can be broken into parallel workstreams
26- Exploration: gather information from multiple parts of the codebase at once
27 
28## When NOT to use
29 
30- Task B depends on Task A's output
31- You need to review Task A before Task B can start safely
32- The tasks share a file and concurrent edits would conflict
33 
34## Process
35 
36### 1. Confirm independence
37 
38Before dispatching, verify each task pair is truly independent:
39- No shared files being written
40- No shared state (DB migrations, config files)
41- No ordering dependency between outcomes
42 
43If any two tasks conflict, sequence them with `delegate-task` or `execute-plan` instead.
44 
45## Subagent depth tiers (e45s30)
46 
47Map `effort:` frontmatter and story `risk:` to prompt depth — do not send `minimal_decisive` agents a `full_maturity` brief.
48 
49| Tier | When | Brief shape | Token budget |
50|------|------|-------------|----------------|
51| `full_maturity` | `effort: heavy`, `risk: P0`, security-sensitive diffs | Full `task_brief` + CONVENTIONS excerpts + threat model if present | Full envelope |
52| `standard` | `effort: standard`, `risk: P1`–`P2` | Standard `task_brief` fields below | Default |
53| `minimal_decisive` | `effort: light`, `risk: P3`, read-only exploration | `goal` + `verify` + `in_scope` only | ≤15 lines |
54 
55Record `depth: <tier>` in the Agent tool description when dispatching.
56 
57### 2. Write typed task briefs (Orca message protocol)
58 
59Before writing briefs, read `specs/state.yaml` if it exists — each agent gets only the decisions relevant to its task, nothing else.
60 
61Every inter-agent message uses a **typed envelope** — no freeform prose between waves:
62 
63| `type` | When | Required fields |
64|--------|------|-----------------|
65| `task_brief` | Dispatch | `task_id`, `goal`, `in_scope`, `out_of_bounds`, `verify`, `prior_decisions` |
66| `checkpoint` | Mid-wave progress | `task_id`, `status` (`running`\|`blocked`), `comment` (one line) |
67| `result` | Agent return | `task_id`, `exit` (`pass`\|`fail`), `summary`, `verify_output` |
68| `circuit_open` | 3 consecutive failures | `task_id`, `failures` (3), `escalate_to` (`user`) |
69 
70Example `task_brief` (each agent starts cold — brief size directly controls token cost and hallucination risk):
71 
72```yaml
73type: task_brief
74task_id: agent-1
75goal: [one sentence — what success looks like]
76in_scope: [explicit file or module list]
77out_of_bounds: [what NOT to touch]
78verify: [runnable command]
79prior_decisions: [relevant entries from specs/state.yaml — omit if none]
80```
81 
82Emit **`checkpoint`** comments when an agent is slow or blocked — one line, no stack traces. Parent reads checkpoints before spawning follow-ups.
83 
84Do not include the full conversation, full file contents, or decisions unrelated to this agent's task.
85 
86### 3. Circuit breaker + iterative retrieval (max 3 cycles)
87 
88Track **consecutive failures per `task_id`**. On the **3rd consecutive `result.exit: fail`** for the same task, emit `type: circuit_open` and **stop dispatching** that task — escalate to user with the three failure summaries. Reset counter on any `pass`.
89 
90After each wave completes:
911. **Dispatch** — run parallel agents with typed `task_brief` envelopes.
922. **Evaluate** — read `result` messages; list gaps vs goal; honor open circuits.
933. **Refine** — tighten briefs or spawn follow-up agents (max **3 cycles** total).
94 
95Stop when gaps empty, circuit opens, or cycle 3 reached — escalate to user. If agents go silent without returning, invoke `diagnose-stall` before spawning another wave.
96 
97### 4. Dispatch in parallel
98 
99Spawn all agents in a single message using multiple Agent tool calls. Each agent gets its own complete brief.
100 
101```
102Agent 1: brief for task A
103Agent 2: brief for task B
104Agent 3: brief for task C
105```
106 
107### 5. Collect and review results
108 
109When all agents return: review each result, run verify commands, check diffs for scope violations.
110 
111### 6. Integrate
112 
113Merge accepted results. Resolve conflicts manually; note in summary.
114 
115Report: which tasks succeeded, which need revision, overall verify status.
116 
117## Verify
118→ verify: `test -f skills/dispatch-agents/SKILL.md && test -f scripts/lib/completeness-critic.sh`
119