| name | spawn-agents |
| description | Use when facing 2+ independent problems (different test files, unrelated bugs, separate subsystems) that can be investigated in parallel without shared state — covers the dispatch decision, the actual Claude Code parallelism mechanism, prompt construction, and integration after agents return |
Spawn Agents
Overview
Delegate independent work to subagents with isolated context. By precisely crafting the agent's prompt, you ensure it stays focused and succeeds. Subagents inherit nothing from your session — you construct exactly what they need. This preserves your own context for coordination.
Core principle: One agent per independent problem. Parallel only when truly independent. Over-dispatching is more common than under-dispatching.
The Decision: Dispatch or Not?
Dispatch when ALL of these hold:
- 2+ problems exist that are genuinely independent
- Each can be understood without context from the others
- Agents won't edit the same files or rely on the same in-flight changes
- You'd otherwise lose tokens to context bloat investigating sequentially yourself
DO NOT dispatch when:
- The problems share a domain model, schema, or core utility (the bugs may have one root cause)
- The work is one cohesive feature decomposed into pieces (e.g. "implement auth: signup + login + reset + verify" — all four touch User, middleware, and schema)
- You don't yet know what's broken (exploratory debugging needs full context)
- The task fits in one agent (don't shard for the sake of sharding)
Over-dispatch is the failure mode to fear most. Capable models reach for parallelism reflexively. Resist: if streams share state, agents will conflict and you'll spend more time integrating than you saved dispatching.
Soft cap: ~3-4 agents per message. If you're tempted to spawn 5+ in parallel, the more likely diagnosis is that they aren't truly independent — re-examine the decomposition before dispatching.
The Mechanism (Claude Code)
Parallelism in Claude Code is NOT a special Task() function. It is:
Multiple Agent tool invocations in a single assistant message.
The harness runs them concurrently. Sequential Agent calls across messages run sequentially.
✅ One message containing 3 Agent tool calls → all 3 run in parallel
❌ Three messages, one Agent call each → all 3 run sequentially
When dispatching N parallel agents, emit all N tool calls in one block.
Subagent Dynamics
Spawned subagents auto-load using-kisune, which has <SUBAGENT-STOP> — the subagent skips the bootstrap dance and runs your assignment directly. Implications for your prompt:
- The subagent will NOT auto-invoke other kisune skills unless you tell it to.
- The subagent has NO conversation memory — your prompt must be self-contained.
- If you want the subagent to follow TDD or use
completion-validation, say so explicitly.
Prompt Construction
Brief the agent like a smart colleague who walked into the room — they have not seen your conversation, do not know what you've tried, do not know why this matters.
A good dispatch prompt has four parts:
- Goal — one sentence on what to accomplish
- Context — relevant file paths, error messages, prior attempts, why this matters
- Constraints — what NOT to change; scope boundaries
- Expected output — what the agent should report back, in what shape
Investigate why src/auth/middleware.ts:42 throws "token not found"
on valid sessions.
Context: Started after PR #312 merged the session-cookie refactor.
Failing path: GET /api/me with valid cookie → 401. Repro: tests/integration/auth.test.ts case "valid session returns user".
Constraints: Do NOT modify production code. Identify root cause only.
You may add console.log in tests.
Return: Root cause in 1-2 sentences, the exact line(s) responsible,
and a proposed fix (do not apply it).
When "Independent" Turns Out Wrong
Mid-flight, you may notice agent A and agent B are converging on the same root cause (shared utility, same schema column, same race). When this happens:
- Stop further work — if either agent has already returned, do not commit those changes blind.
- Consolidate — open a single new investigation that covers both problems together.
- Re-dispatch only after the shared root cause is understood; the new agents must not overlap on the now-shared edit surface.
Sunk-cost fallacy: "the agents are already running, let them finish." Resist. Conflicting edits cost more to untangle than to abort.
After Agents Return
For each returned agent:
- Read the summary critically — agent reports describe intent, not necessarily reality.
- Verify via diff/state, not the report. Run
git status, git diff, read the changed files. (See completion-validation for the discipline gate before claiming "the agent succeeded".)
- Check for cross-agent conflicts (same file edited twice, same dependency added differently).
- Run the full test suite once integrated — independent fixes can still combine into a regression.
Partial failure (1 of N fails): Do not silently drop the failed agent's task. Either (a) re-dispatch it with the lessons learned from siblings, (b) take it on yourself if it now needs full-system context, or (c) report the partial state honestly: "2 of 3 fixed, the third needs further investigation". Never claim the whole batch succeeded when one stream failed.
Common Mistakes
| ❌ | ✅ |
|---|
| "Fix all the failing tests" (too broad) | "Fix the 3 failures in src/agents/abort.test.ts" (focused scope) |
| No context, just a goal | Paste error messages, file:line, repro steps |
| No constraints | "Do not change production code" / "Tests only" |
| "Fix it" (vague output) | "Return root cause + line numbers + proposed fix" |
| Dispatch 4 agents on one feature | Sequential single agent for cohesive work |
| Trust agent's "all tests pass" | Verify via git diff + re-run suite yourself |
| One Agent call per message | All N Agent calls in one message → real parallelism |
When NOT to Spawn
- Scoped lookups already known: use
Read / Grep directly, not an agent.
- One-shot tool execution: don't wrap a single
Bash call in an agent.
- Short reactive tasks: if the next action is dictated by what you just read, do it yourself.
- Anything where you'd give the agent the same context you already have: dispatching adds latency without isolation benefits.
Integration With Other Kisune Skills
using-kisune — defines the <SUBAGENT-STOP> semantics that let dispatched agents skip the bootstrap.completion-validation — the verification gate after an agent returns. "Agent said success" is not evidence; check the diff.brainstorming — if the dispatch decision itself is non-obvious (independent vs not?), brainstorm before dispatching.spec-driven-implementation — for Full-mode features, do NOT shard task execution across agents unless tasks are explicitly independent in the plan.
