From f32f49c0a15f9738fde2c04d4a582c8a68344a78 Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Sun, 17 May 2026 13:39:44 +0200
Subject: [PATCH] add tools-cascade.md prompt for orchestrator agents

---
 prompts/tools-cascade.md | 57 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 57 insertions(+)
 create mode 100644 prompts/tools-cascade.md

diff --git a/prompts/tools-cascade.md b/prompts/tools-cascade.md
new file mode 100644
index 0000000..7490220
--- /dev/null
+++ b/prompts/tools-cascade.md
@@ -0,0 +1,57 @@
+# cascade
+
+Delegate mechanical subtasks to a cheaper/weaker model. Fire-and-forget: returns immediately, worker reports back to your prompt when done.
+
+**Trigger condition**: a subtask is purely mechanical — no judgment, no multi-step reasoning, no ambiguity. Examples: apply a known edit, extract data from a file, reformat text, run a grep and summarize matches, generate boilerplate from a spec.
+
+**Do NOT cascade when**: the task requires judgment, interpretation, multi-step planning, or access to context you cannot fully articulate in the instruction.
+
+**Calling convention**:
+```
+cascade: instruction="<fully self-contained task description>" [id="<optional-name>"]
+```
+
+Parallel — use `{parallel: [...]}`:
+```
+execute_code: steps=[{parallel: [
+  {code: "cascade 'Read /src/a.go and list all exported functions'"},
+  {code: "cascade 'Read /src/b.go and list all exported functions'"},
+  {code: "cascade 'Read /src/c.go and list all exported functions'"}
+]}]
+```
+
+**Returns** (KV, one per line):
+```
+session=<session-id>
+path=<full session path>
+backend=<worker backend>
+model=<worker model>
+```
+
+**Worker callback**: When the worker finishes, it writes to your prompt:
+```
+[from=<session-id>]
+STATUS: done
+SUMMARY: <result>
+```
+
+You will receive this as your next queued turn. Correlate via the `[from=...]` header.
+
+## Key constraints
+
+- **Instructions must be fully self-contained.** The worker has zero context beyond what you put in the instruction string. Include file paths, expected formats, relevant snippets — everything it needs.
+- **Never wait for results.** After calling cascade, continue your own work or end your turn. You will be woken when results arrive.
+- **One task per call.** Do not bundle multiple unrelated tasks into one instruction.
+- **Parallelism is safe.** cascade is marked `ollie:parallel read` — multiple calls execute concurrently.
+
+## When to use cascade vs subagent_spawn
+
+| | cascade | subagent_spawn |
+|---|---|---|
+| Model | Always cheap (configured globally) | Any model (specified per call) |
+| Identity | Fixed worker identity | JIT-generated identity via subagent_generate |
+| Use case | Mechanical grunt work | Tasks needing specialized reasoning or identity |
+| Complexity | Single tool call | Pipeline: generate config → spawn |
+| Callback | Automatic (worker writes to parent prompt) | Automatic (same protocol) |
+
+Use `cascade` when the task is dumb and the worker doesn't need a custom identity. Use `subagent_spawn` when the subtask itself requires reasoning, a specialized persona, or coordination with peers.