# Spawn

> Fan out a confirmed research/implementation brief to named Pi agents in parallel via pi-spawn tools. Use when the user asks to spawn agents, run the agents on this, compare models on a question, get the agents to investigate, or otherwise parallelize the same brief across configured named agents.

- Skill: `smarzban/spawn` (Agent Skill)
- Install (CLI): `npx skillmds@latest add smarzban/spawn`
- Raw SKILL.md: https://api.skillmd.com/api/skills/smarzban/spawn/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: smarzban (https://skillmd.com/u/smarzban)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/smarzban/spawn

---


# Spawn parallel Pi agents

Use this skill instead of manually opening Herdr tabs or inventing your own fan-out.

## Workflow

1. **Draft** a short brief from the conversation (or from “on this”: summarize the current topic).
2. **Present** the brief in chat and ask the user to confirm: yes / edit / cancel.
3. **Only after explicit confirm**, call the `spawn_run` tool with:
   - `brief`: the confirmed text
   - `confirmed`: `true`
   - `useDefaultSet: true` for “the agents”, or `names: ["…"]` for a named agent
   - `background: true` if the user asked for background/headless
4. **Synthesize** the returned findings in chat. Mark missing/failed agents clearly. Do not claim they finished.
5. **Follow-ups**: when the user asks the same already-spawned Herdr agents “what if…?”, asks them to reconsider, or asks a direct follow-up, call `spawn_follow_up` instead of `spawn_run`. It reuses the existing child sessions and creates no tabs. Do not substitute a new spawn if no resumable Herdr run exists.
6. **Investigate stragglers**: for each missing agent that has a pane, use **non-blocking** herdr tools (`herdr_agent` get/read) to see whether it is stuck, blocked, waiting on usage limits, or still working.
7. **Late findings**: use `/spawn status` (or ask to check the run) and read finding files under the kept run dir. Children do **not** ping the parent chat.

## Surfaces

- `/spawn` — ask what to look into, then draft → confirm → `spawn_run`
- `/spawn <name> on this` — draft from current topic for that named agent
- `/spawn the agents on this` — draft from current topic for the default set
- `/spawn status` — list kept partial runs and which findings landed
- Follow-up requests to the parent (“ask the spawned agents what if we use X?”) — call `spawn_follow_up` to reuse the latest Herdr tabs
- Natural language (“spawn the agents on this”, “run opus and fable on …”, “get the agents to investigate …”) — same workflow

## Rules

- Never start children until the user confirms the brief.
- Never open Herdr tabs or run `pi -p` yourself for spawn; the tools own runtime selection (`HERDR_ENV=1` → Herdr tabs, else headless; background forces headless).
- **`spawn_run` waits until every child finishes** (returns early when the last one lands). Optional `timeoutMs` in `spawn.json` is only a safety ceiling; omit/`null` means wait until done or cancel.
- **Never call `herdr_agent wait` on spawn children.** That freezes the parent chat. `spawn_follow_up` owns its own wait/collect cycle.
- **Never close spawn tabs or panes, on success or failure, unless the user explicitly asks.**
- Children write findings under `~/.pi/agent/spawn-runs/`. Complete runs are cleaned up; partial/cancelled runs are kept for `/spawn status`.
- `spawn_follow_up` works only for Herdr children. Headless `--no-session` children cannot be resumed, so say so instead of starting replacement children.
- Parent owns synthesis. There are no modes, no editor/optimizer model, and no parent-pane pings.