dispatch-plan

Files (1)

• SKILL.md

SKILL.md (first lines)

# dispatch-plan

You are coordinating work that has been broken into multiple independent items (typically captured as checkboxes in `plan.md`). Use `delegate_task` to fan items out so each runs in its own context window, and gather the results in your own context with bounded size.

## When to invoke

Use this pattern when:

- The work is captured as a list of items (in `plan.md`, a markdown checklist, or any equivalent file).
- The items are **independent** — completing one does not change the input to another. (If they must run in order, do them yourself sequentially.)
- The items would individually consume meaningful context (file reads, edits, test runs).

Do NOT use this pattern when:

- There are fewer than two independent items.
- The items must share intermediate state (open editor buffers, partial git index, etc.).
- The items are tiny (a one-line edit each) — the overhead of dispatching outweighs the win.

## How to dispatch

For each independent item, issue one `delegate_task` call. The harness runs up to 3 children in parallel by default; if you have more items, the rest queue automatically.

```
delegate_task({
  goal: "<one sentence stating exactly what the child should accomplish>",
  context: "<everything the child needs that isn't in the working copy: parent intent, constraints, success criteria>",
  toolsets: ["read", "write", "edit", "bash", "glob"],   // narrow as appropriate
  isolated: false,                                        // share parent's working copy
})
```

**Goal phrasing.** Make it actionable and atomic: "Refactor src/api/users.ts to the new error-shape pattern" not "Look at users.ts." Specify the file path and the verb.

**Context contents.** The child gets a fresh conversation with no memory of yours. Include in `context`:
- The parent task's overall goal (one line).
- Conventions and constraints not visible from the working copy (lint rules, commit message format).
- Definition of done — when can the child stop?
- Any files outside the immediate scope the child should NOT touch.

**Toolset narrowing.** If the child only needs to read + edit files, drop `bash` and `fetch` from its toolset. Narrower scope = faster + safer.

**Sharing vs isolating.** Default `isolated: false` shares the parent's working copy with the child — they edit the same files via the same git checkout. Use `isolated: true` only when you need a clean filesystem (rare; e.g., experimenting with a destructive operation).

## What you receive back

When all children complete, the harness re-enters your conversation with the results substituted into your earlier `delegate_task` tool-invocations. Each result has the shape:

```
{
  taskId: "...",
  childSessionId: "...",
  status: "completed" | "failed" | "cancelled",
  artifactPath: "<path/to/output>" | null,
  oneLineNote: "<terse summary the child wrote>",
}
```

The `artifactPath` (when set) points at a file the child wrote in the working copy — read it for the child's full output. The `oneLineNote` is the child's summary; trust it for routing decisions, but read the artifact when you need detail.

## After dispatch

Once you have the results:

1. **Update `plan.md`** — flip checkboxes to `[x]` for completed items, leave `[ ]` for failed/cancelled. Add a brief note next to each line citing the child's `oneLineNote` (e.g., `- [x] users.ts (refactored to new error shape)`).
2. **Re-dispatch failures** if the failure was transient (rate limit, sandbox blip). For real failures (the child can't accomplish the goal), update the plan to capture what's needed and either tackle it yourself or surface the blocker to the user.
3. **Synthesize.** Write a short final message describing what's done, what remains, and any decisions you're flagging for review.

## Anti-patterns

- **Don't dispatch sequentially.** If items A and B are independent, dispatch them in the same turn — both go in parallel up to the concurrency cap.
- **Don't recurse.** Children cannot dispatch their own children by default (depth=1). If you find yourself wanting to, the parent's plan is too granular — flatten it.
- **Don't leak parent context.** The child only has what's in the working copy + your `goal` + `context`. If you find yourself describing a long history in `context`, write a `journal.md` artifact for the child to read instead.

From iarmankhan/zuno, MIT.

More from iarmankhan/zuno