From 30bc3c8eff8a2481bdb742a021ac8c41d699d05d Mon Sep 17 00:00:00 2001
From: Levi Neely <141506390+lneely@users.noreply.github.com>
Date: Mon, 20 Apr 2026 22:07:06 +0200
Subject: [PATCH] prompts: tools-subagent clarify -n vs parallel

---
 prompts/tools-subagent.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/prompts/tools-subagent.md b/prompts/tools-subagent.md
index d6f4817..8cb5c9f 100644
--- a/prompts/tools-subagent.md
+++ b/prompts/tools-subagent.md
@@ -2,7 +2,7 @@
 
 Delegate work to one or more specialized agents running concurrently. Each subagent receives the prompt, executes a single job, and returns a result.
 
-**Trigger condition**: a task decomposes into N independent subtasks each requiring multi-step reasoning or multiple tool calls; you are processing N items with the same operation; a subtask is better handled by a different agent (model, backend, or prompt). Use a `{parallel: [...]}` stage in `execute_code` instead when the subtasks are single shell commands — subagents are for agent-level work.
+**Trigger condition**: a task decomposes into independent subtasks each requiring multi-step reasoning or multiple tool calls; you are processing N items with the same operation; a subtask is better handled by a different agent (model, backend, or prompt). Use a `{parallel: [...]}` stage in `execute_code` instead when the subtasks have different prompts — subagents are for agent-level work, not single shell commands.
 
 **Calling convention**:
 ```
@@ -11,7 +11,7 @@ execute_code: steps=[{tool: "subagent_spawn", args: ["-n", "N", "-agent", "A", "
 
 | Flag | Default | Description |
 |---|---|---|
-| `-n N` | 1 | Number of parallel subagents |
+| `-n N` | 1 | Number of parallel subagents, all receiving the same prompt (homogeneous fan-out) |
 | `-agent A` | server default | Agent config name |
 | `-backend B` | server default | Backend override |
 | `-model M` | server default | Model override |
@@ -31,7 +31,7 @@ Prompt is all remaining arguments after flags.
 
 ## Heterogeneous fan-out
 
-To run N subagents with N different prompts, use a `{parallel: [...]}` stage:
+To run N subagents with N *different* prompts, use a `{parallel: [...]}` stage. Each entry is an independent `subagent_spawn` call with its own prompt — use this when the subtasks differ:
 
 ```
 execute_code: steps=[{parallel: [