koolamusic/spawn

Spawn

Dispatch parallel sub-agents with isolation guarantees. You are the orchestrator — you coordinate, delegate, track, and integrate. You never write application code yourself.

Input

$ARGUMENTS is one of:

• A file path — read it as the scope document (PLAN.md, HANDOFF.md, a GitHub issue, any structured doc)
• Inline text — treat it as the scope description directly
• auto — look for .jira/CURRENT and read the active sprint's plans. If no sprint, check .project/ROADMAP.md for the next unstarted phase. If neither exists, ask.
• Empty — ask via AskUserQuestion what work to dispatch

Process

1. Parse scope into units

Read the input and decompose into spawn units — independently executable chunks of work. Each unit must have:

• ID — short label (A, B, C or descriptive slug)
• Objective — one sentence: what this agent delivers
• Inputs — files to read, context to pass
• Outputs — files to create/modify, commits expected
• Depends on — other unit IDs that must complete first (empty = wave 1)

2. Build the wave map

Group units into waves by dependency:

Wave 1: [A, B, C]  — no dependencies, run in parallel
Wave 2: [D]         — depends on A
Wave 3: [E, F]      — depends on D

Units within a wave touch disjoint files. If two units in the same wave would modify the same file, split the wave or merge the units.

3. Present the dispatch plan

Show the user:

## Dispatch Plan

**Total units:** N across W waves
**Isolation:** worktree / same-tree (recommend worktree if >1 unit per wave)

| ID | Wave | Objective | Depends on | Est. complexity |
|---|---|---|---|---|
| A | 1 | ... | — | small |
| B | 1 | ... | — | medium |
| C | 2 | ... | A | small |

Proceed?

Wait for explicit approval. The user may reorder, merge, split, or cancel units.

4. Execute wave-by-wave

For each wave in order:

a. Spawn agents in parallel. Single message, one Agent tool call per unit in the wave. Each agent gets:

You are sub-agent <ID> in a spawn dispatch.

## Your objective
<objective>

## Context
<brief from scope doc + any outputs from prior waves>

## Files you own
<list of files this agent may create/modify — no others>

## Constraints
- Commit your work with a descriptive message
- Do NOT push to remote
- Do NOT open PRs
- Do NOT modify files outside your scope
- If blocked, commit what you have and report the blocker

Isolation decision:

• If wave has >1 unit: use isolation: "worktree" on each Agent call
• If wave has 1 unit: foreground without worktree (simpler)
• User can override in the dispatch plan approval step

b. Collect results. When all agents in the wave return:

• Read each agent's reported status
• Run git log --oneline -5 (or per-worktree equivalent) to verify commits landed
• If any agent reports a blocker: surface it via AskUserQuestion — retry, skip, or abort
• If any agent's worktree has changes: note the worktree branch for integration

c. Integrate worktree results (if using worktrees):

• For each completed worktree agent, cherry-pick or merge its commits onto the working branch
• Resolve conflicts if any — surface to user if non-trivial
• Verify the integrated state compiles / passes basic checks

5. Report

When all waves complete:

## Spawn Complete

**Units dispatched:** N
**Waves executed:** W
**Status:**
| ID | Status | Commits | Notes |
|---|---|---|---|
| A | complete | abc1234 | — |
| B | complete | def5678 | — |
| C | blocked | — | <blocker description> |

**Integration:** all cherry-picked onto <branch>
**Next step:** <recommendation — run tests, open PR, continue with next spawn>

Hard rules

• You are the orchestrator. Never write application code, tests, or configuration yourself. Your job is dispatch, tracking, and integration.
• Wave-safe parallelism. Never dispatch two agents that modify the same file in the same wave.
• Foreground parallel, not background. Use multiple Agent calls in a single message for within-wave parallelism. Background agents have worktree isolation issues.
• Never force-push. If integration has conflicts, surface and ask.
• Never auto-merge PRs. Open them, report them, stop.
• Git state verification after every wave. Don't trust agent self-reports alone — check git log and git status.
• User approval before dispatch. Always show the dispatch plan and wait for "go."

Integration with jira

When invoked by jira:execute or with auto argument in a jira-managed repo:

• Read wave structure from *-PLAN.md frontmatter (plans already have wave: fields)
• Pass CONTEXT.md (locked decisions) to every agent
• Write integration results to EXECUTION.md (append-only)
• Don't duplicate jira:execute's Nyquist/verifier gates — those run after spawn returns

Integration with studio

If .workspacerc exists, resolve all .jira/ and .project/ paths through the workspace. Worktree agents don't get symlinks automatically — pass resolved absolute paths in agent prompts.