You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Rewrite dispatch around spawn_agent and wait_agents, named directors, and
the git-worktrees background skill. Remove fake fan-out caps and pin the
runtime agent_id flow in catalog coverage.
Closes CL-7017
description: Multi-lane DAG orchestration. Skywalker recipe — use_skill("dispatch"). Spawns explorer, intern, builder, counsel, and critic. DAG product tasks go through builder; Skywalker may DIY tiny edits outside the DAG.
5
+
description: Multi-lane DAG orchestration. Skywalker recipe — use_skill("dispatch"). Spawns explorer, intern, builder, counsel, critic (and specialists like rand). DAG product tasks go through builder; Skywalker may DIY tiny edits outside the DAG.
6
6
---
7
7
8
8
# Dispatch
9
9
10
-
You are Skywalker. This skill is loadable with `use_skill("dispatch")`. Follow this recipe. DAG product tasks go through builder workers. Do not write `dispatch.yaml` or `plan.md` yourself (intern cannot write; builder writes manifests). Tiny / single-file / one-route product edits outside this DAG may be DIY with write_file/edit_file/delete_file.
10
+
You are Skywalker. Load with `use_skill("dispatch")`. Orchestrate parallel director runs across a dependency graph: classify lanes, spawn independent work together, wait/synthesize, critique, verify, re-dispatch fixes, report.
11
11
12
-
Orchestrate parallel director runs across a dependency graph. Fan out work, fan in reports, critique, verify, re-dispatch fixes, and synthesize until done.
12
+
DAG product tasks go through **builder**. Do not write `dispatch.yaml` or `plan.md` yourself (intern cannot write; builder writes manifests). Tiny / single-file / one-route product edits outside this DAG may be DIY with write_file/edit_file/delete_file.
13
13
14
-
Default batch size: **4 live workers** (recipe default — not a hard runtime cap). Widen when lanes are named and non-overlapping, or when the operator asks. Track progress with `manage_tasks`.
14
+
**Fleet default:**`spawn_agent` then `wait_agents` — fire independent workers in one turn, wait on the reports you need next. Prefer `task()` only when a single blocking spawn is enough. No worker-count or fan-out ceiling — width follows named, non-overlapping lanes (distinct path/package/ownership). Track progress with `manage_tasks`.
15
15
16
-
Closed directors used here: `explorer`, `intern`, `builder`, `counsel`, `critic`. Optional consults: `greybeard`, `tester`. Never a catch-all worker. DAG node agents are `explorer`, `intern`, and `builder` only.
16
+
Closed directors used here: `explorer`, `intern`, `builder`, `counsel`, `critic`. Optional: `greybeard`, `tester`, `rand` (DESIGN.md / brand). Never a catch-all worker. DAG node agents are `explorer`, `intern`, and `builder` only.
| Review a landed task (defects, evidence, no fix) |`task(agent="critic")`|
39
-
| Architecture judgment before a large DAG |`task(agent="greybeard")`|
40
-
| Independent suite / repro evidence |`task(agent="tester")`|
41
-
42
-
Skywalker classifies, spawns, tracks, and synthesizes. Path tools (`write_file` / `edit_file` / `delete_file`) are mounted for DIY tiny/bounded product edits; spawn remains the default for DAG product work. Durable orchestration artifacts (`dispatch.yaml`, `plan.md`, status) still go through builder — intern does not have write tools (`INTERN_TOOLS` = run_shell, read_file, list_dir). Do not spawn a blob agent to author the manifest. Do not write those manifests on Skywalker.
30
+
| Work | Director |
31
+
| ---- | -------- |
32
+
| Map the codebase, gather facts |`explorer`|
33
+
| Eng plan from a spec (no ship) |`counsel`|
34
+
| Write `dispatch.yaml` / `plan.md` / status (mechanical; no product feature work) |`builder`|
35
+
| Ship product code + tests |`builder`|
36
+
| Review a landed task (defects, evidence, no fix) |`critic`|
37
+
| Architecture judgment before a large DAG |`greybeard`|
38
+
| Independent suite / repro evidence |`tester`|
39
+
| DESIGN.md / brand gate for UI lanes |`rand`|
43
40
44
-
Prefer typed briefs: `intent`, `success_criteria`, `do_not`, `report_focus`, and `agent`.
41
+
Skywalker classifies, spawns, tracks, and synthesizes. Durable orchestration artifacts still go through builder — intern has no write tools. Prefer typed briefs: `intent`, `success_criteria`, `do_not`, `report_focus`, and `agent`.
45
42
46
43
## Agent type selection
47
44
48
-
Use**explorer**when the task is pure research. No code changes. Output is findings for downstream tasks.
49
-
50
-
Use**intern**when the work is mechanical and well-specified: git commit after a level fans in, exact shell, mechanical git. Intern cannot write files.
45
+
-**explorer**— pure research; no code changes; findings for downstream.
-**builder**— ships product code (judgment, abstractions, tests) and mechanical writes of `dispatch.yaml` / `plan.md` / status.
51
48
52
-
Use **builder** when the task ships product code — including work that needs judgment, new abstractions, or tests — and for mechanical writes of `dispatch.yaml` / `plan.md` / status artifacts (write tools; intern does not have them). There is no catch-all implementation agent.
53
-
54
-
Critique is not a DAG node agent type. After builder (and after non-trivial intern landings), spawn `task(agent="critic")` with the task's objective, paths, and diff. Simple intern tasks may skip critique.
49
+
Critique is not a DAG node type. After builder (and non-trivial intern landings), spawn `critic` with objective, paths, and diff. Simple intern tasks may skip critique.
55
50
56
51
Classify each product task as `feature` or `bugfix`:
57
52
58
-
-`bugfix`: incorrect behavior that exists today → test-first (fail, then fix, then pass)
59
-
-`feature`: everything else → tests for the new behavior
53
+
-`bugfix` → test-first (fail, then fix, then pass)
54
+
-`feature` → tests for the new behavior
60
55
- When unsure, default to `feature`
61
56
57
+
## Isolated worktree (when needed)
58
+
59
+
When the run needs a clean branch / isolated tree: load `use_skill("git-worktrees")`, copy the create (or teardown) recipe into an intern brief, spawn `intern`. Do not inline git worktree commands here. Skywalker does not run the git.
60
+
62
61
## Phase 1: Planning
63
62
64
-
Runs when the input is a spec (or a request with no existing manifest). The spec should be complete enough that a builder worker could succeed from it.
63
+
Runs when the input is a spec (or a request with no existing manifest).
65
64
66
-
1.If the spec still needs an ordered eng plan, spawn `task(agent="counsel")`. Do not skip this when requirements are large or ambiguous.
67
-
2. Spawn `explorer` workers only as needed to map scope. Distinct path/package lenses if parallel.
68
-
3. Consult `greybeard` before large multi-lane work when architecture is in play.
65
+
1.Spec needs an ordered eng plan → spawn `counsel`.
66
+
2. Spawn `explorer` workers only as needed (distinct path/package lenses if parallel).
67
+
3. Consult `greybeard` before large multi-lane work when architecture is in play; `rand` when UI/brand is in play.
69
68
4. Break the goal into discrete tasks, each small enough for one director.
70
-
5. Identify dependencies (DAG edges). Same-file writers at the same level must be merged or serialized via `depends-on`.
69
+
5. Identify dependencies (DAG edges). Same-file writers at the same level → merge or serialize via `depends-on`.
71
70
6. Assign `explorer` | `intern` | `builder` per the guide above.
72
-
7. Detect verify commands from `package.json`, Makefile, or project docs.
73
-
8. Add per-task verification to each plan (build for compiled changes, tests for test-writing tasks).
74
-
9. Default commit strategy is **per-task** (debuggable). Use grouped only when the operator wants a cleaner history **and** Phase 5 will catch issues.
75
-
10. Mark which tasks need critique (complex builder → yes; simple intern → no; when unsure, yes).
76
-
11. Seed `manage_tasks` with one item per DAG task (plus plan / verify / critique items as needed).
71
+
7. Detect verify commands from `package.json`, Makefile, or project docs; add per-task verification.
72
+
8. Default commit strategy: **per-task**. Grouped only when the operator wants a cleaner history **and** Phase 5 will catch issues.
73
+
9. Mark which tasks need critique (complex builder → yes; simple intern → no; unsure → yes).
74
+
10. Seed `manage_tasks` with one item per DAG task (plus plan / verify / critique as needed).
77
75
78
76
If requirements are not actionable, stop. Ask: "Can a builder worker succeed with only this information?"
79
77
80
78
## Phase 2: Directory structure
81
79
82
-
Have **builder** write the run tree (mechanical brief; no product feature work). Do not write these files on Skywalker. Do not use intern — intern cannot write files. Do not use a catch-all worker.
80
+
Have **builder** write the run tree (mechanical brief). Do not write these on Skywalker. Do not use intern for writes.
Builder writes one per task (mechanical brief). Include: objective, requirements covered, context (paths and symbols — no line numbers, no dispatch-dir cross-refs), files to modify, constraints, verification (test-first for bugfix), and `do_not`.
143
+
Builder writes one per task. Include: objective, requirements covered, context (paths and symbols — no line numbers, no dispatch-dir cross-refs), files to modify, constraints, verification (test-first for bugfix), and `do_not`.
147
144
148
145
Every product-task brief must tell the worker:
149
146
150
147
- Do **not** run mutating git (`git add` / `commit` / `checkout` / `stash`). Intern commits after the level fans in.
151
148
- Leave changes uncommitted. Multiple tasks may share a worktree.
152
-
- Read the full `plan.md` before acting. If it is unclear, fail closed.
149
+
- Read the full `plan.md` before acting. If unclear, fail closed.
153
150
154
151
## Phase 3: Validate, then present
155
152
156
153
Before any product spawn:
157
154
158
-
**Structural:** DAG is acyclic; every `depends-on` / `receives` id exists; `receives` ⊆ `depends-on`; every task has `plan.md`; no orphan directories.
155
+
**Structural:** DAG acyclic; every `depends-on` / `receives` id exists; `receives` ⊆ `depends-on`; every task has `plan.md`; no orphan directories.
159
156
160
-
**Completeness:** clear objectives; files named; union of tasks covers the goal; every spec requirement maps to at least one task.
157
+
**Completeness:** clear objectives; files named; union of tasks covers the goal; every spec requirement maps to ≥1 task.
161
158
162
-
**Coherence:** no two ready-in-parallel tasks write the same file; constraints do not contradict; `explorer` is never assigned product writes.
159
+
**Coherence:** no two ready-in-parallel tasks write the same file; constraints do not contradict; `explorer` never gets product writes.
163
160
164
-
**Feasibility:** referenced files exist or are created by this task or an upstream dependency; scope fits one worker.
161
+
**Feasibility:** referenced files exist or are created by this task or an upstream; scope fits one worker.
165
162
166
-
Empty task list → mark the run `completed` and report. Do not invent work.
163
+
Empty task list → mark `completed` and report. Do not invent work.
167
164
168
-
Present the DAG (ids, agents, deps, critique flags, verify commands, commit strategy) to the operator. Wait for go-ahead on large or ambiguous runs. Then set status `in-progress` (builder updates the manifest if it is on disk).
165
+
Present the DAG (ids, agents, deps, critique flags, verify commands, commit strategy) to the operator. Wait for go-ahead on large or ambiguous runs. Then set status `in-progress` (builder updates the manifest if on disk).
169
166
170
167
## Phase 4: Execute the DAG
171
168
172
169
1. **Ready set:** `pending` tasks whose `depends-on` are all `completed`.
173
-
2. **Batch:** take a safe parallel subset; default batch size is **4 live workers** (including in-flight critique) — widen when lanes are named and non-overlapping. Same-file writers and shared mutable state (build artifacts, test DBs) must not share a batch — serialize with `depends-on`.
174
-
3. **Spawn** each task with `task(agent="<id from manifest>")`. Inject upstream reports (not a rewritten `plan.md`) into the brief. Split ownership by path/package when two builder workers run together.
170
+
2. **Parallel lanes:** spawn every independent ready task whose ownership does not overlap (same-file writers and shared mutable state must serialize via `depends-on`). No batch-size ceiling.
171
+
3. **Spawn:** call `spawn_agent(agent=<task.agent director id>, …)` for each ready task in one turn; record each returned `agent_id`, then `wait_agents` on those runtime ids. Inject upstream reports (not a rewritten `plan.md`) into the brief. Split ownership by path/package when two builders run together.
175
172
4. **Fan in:** trust the worker report (and `output.yaml` when builder wrote one). Missing report or `status: failed` → mark `failed`. Do not re-fan-out an identical brief; change `success_criteria` / `do_not` or tell the operator.
176
173
5. **Level commit:** after a level's product tasks self-report complete, intern commits per the strategy (per-task default). Workers must not have committed.
177
-
6. **Critique:** for tasks with `critique.enabled`, spawn `task(agent="critic")` on that commit/diff + objective. Blocking findings → re-dispatch `builder` with those findings in `success_criteria` / `do_not` (status `fixing`). Cap re-fix rounds (1–2), then report Blockers.
174
+
6. **Critique:** for tasks with `critique.enabled`, spawn `critic` on that commit/diff + objective. Blocking findings → re-dispatch `builder` with those findings in `success_criteria` / `do_not` (status `fixing`). Cap re-fix rounds (1–2), then report Blockers.
178
175
7. Repeat until no pending tasks remain, or deadlock / all remaining failed → stop and ask.
179
176
180
-
Keep `manage_tasks` in sync as items move `todo` → `doing` → `done` / stay blocked.
If the working tree has unrelated uncommitted changes before Phase 4, ask the operator. Do not mix them into level commits.
183
180
184
181
## Phase 5: Verify
185
182
186
-
Must `task(agent="tester")` for the suite (or intern for one named mechanical command). Do not run the full verify pipeline on the parent via Skywalker `run_shell`. Compare against any baseline you captured.
183
+
Spawn `tester` for the suite (or intern for one named mechanical command). Do not run the full verify pipeline on the parent via Skywalker `run_shell`. Compare against any baseline you captured.
187
184
188
185
- Green, or same failures as baseline → proceed.
189
186
- New failures → attribute to a task/commit, re-dispatch `builder` on that lane, re-verify. Cap rounds, then Blockers.
@@ -201,7 +198,7 @@ Synthesize for the operator:
201
198
202
199
## Paths
203
200
204
-
Include: what landed, which directors ran, verify evidence, remaining failed/fixing tasks. Mark the run `completed` or `failed`. `manage_tasks` should reflect the same.
201
+
Include: what landed, which directors ran, verify evidence, remaining failed/fixing tasks. Mark the run `completed` or `failed`. `manage_tasks` should match.
205
202
206
203
## Resume
207
204
@@ -210,7 +207,7 @@ Re-resolve input to the existing `dispatch/<name>/`. Re-validate the remaining D
210
207
## Non-negotiables
211
208
212
209
- You are Skywalker. Spawn directors. Do not implement product features. Do not author dispatch YAML/plan files yourself or via a catch-all worker. Durable orchestration files go through builder.
213
-
- `use_skill("dispatch")`loads this recipe. It is a command.
214
-
- Agents: `explorer`, `intern`, `builder` only for DAG nodes. Critique via `task(agent="critic")`. Plan via `task(agent="counsel")` when a spec needs an eng plan first.
215
-
- Progress: `manage_tasks`.
216
-
- Default batch size 4 live workers (recipe default, not a hard runtime cap); widen for named non-overlapping lanes or when the operator asks.
210
+
- `use_skill("dispatch")`loads this recipe. It is not a slash command.
211
+
- Fleet verbs: `spawn_agent`+ `wait_agents` for multi-lane work. DAG nodes: `explorer`, `intern`, `builder` only. Critique via `critic`. Plan via `counsel` when a spec needs an eng plan first.
212
+
- Isolated trees: `use_skill("git-worktrees")`→ intern executes. Do not inline worktree git here.
213
+
- Progress: `manage_tasks`. Parallelize named non-overlapping lanes — no worker-count cap.
0 commit comments