---
name: ayf:spawn
description: |
  Spawn a real parallel agent for a task using cmux. Each agent gets its own
  Claude process in an isolated workspace — turning ay-framework into a real swarm.
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
---

# /spawn [N] — Launch a Real Parallel Agent

Spawn an independent Claude agent for task N in its own cmux workspace. Unlike
running tasks sequentially, `/spawn` creates a separate Claude process that runs
in parallel with the current session.

## Prerequisites

```bash
cmux ping   # must return OK
```

If cmux is not available, fall back to running the task in the current session with `/task-start N`.

## Step 1: Check cmux

```bash
cmux ping 2>/dev/null && echo "cmux available" || echo "cmux not available"
```

If not available, inform the human and offer `/task-start N` as fallback.

## Step 2: Read the task

Read `.ay/tasks/task-{N}.md` to understand:
- What the task does
- Which agent scope owns it
- What its dependencies are (must all be DONE)

## Step 3: Spawn the workspace

```bash
WS=$(cmux --json new-workspace | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
cmux rename-workspace --workspace "$WS" "task-{N}-{short-title}"
cmux workspace-action --action set-color --color Green --workspace "$WS"
```

## Step 3.5: Record the dispatch in the fleet manifest

Before launching the agent, append a dispatch entry to `.ay/fleet/manifest.yaml`
so the fleet operator (`/monitor`) knows which surface owns which task and when it
was assigned. Create the directory if it does not exist yet.

```bash
mkdir -p .ay/fleet
MANIFEST=.ay/fleet/manifest.yaml
# Ensure a top-level dispatches: list exists, then append this record.
grep -qE '^dispatches:' "$MANIFEST" 2>/dev/null || printf '\ndispatches:\n' >> "$MANIFEST"
cat >> "$MANIFEST" <<EOF
  - surface_id: task-{N}-{short-title}
    task_id: {N}
    assigned_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)
    workspace: $WS
EOF
```

Each entry has exactly these fields:
- `surface_id` — the surface name (the renamed workspace, e.g. `task-52-ayf-server`).
- `task_id` — the BOARD.md task number this dispatch owns.
- `assigned_at` — UTC ISO-8601 timestamp of the dispatch.
- `workspace` — the cmux workspace ref the agent runs in.

## Step 4: Launch Claude and dispatch

```bash
cmux send --workspace "$WS" "cd $(pwd) && claude"
cmux send-key --workspace "$WS" "enter"

# Poll for ready — never blind-sleep
for i in 1 2 3 4 5 6; do
  sleep 2
  cmux read-screen --workspace "$WS" --lines 5 | grep -qE "What do you want|❯" && break
done

cmux send --workspace "$WS" "/task-start {N}"
sleep 0.3
cmux send-key --workspace "$WS" "enter"
```

## Step 5: Verify and notify

```bash
sleep 3
cmux read-screen --workspace "$WS" --lines 10   # confirm spinner running
cmux trigger-flash --workspace "$WS"
cmux notify --workspace "$WS" \
  --title "Agent spawned: Task #{N}" \
  --body "{short-title} running in {workspace-name}"
```

## Step 6: Update BOARD.md

Update `.ay/tracking/BOARD.md`: set task status to IN PROGRESS, note the workspace ID.

## Step 7: Report to human

Tell the human:
- Which workspace the agent is in (cmux workspace name)
- What the agent is working on
- How to check progress: `cmux read-screen --workspace {WS} --lines 20`
- The agent will write to `.ay/tracking/HANDOFFS.md` when done

## Spawn multiple tasks in parallel

If multiple tasks are READY with no shared dependencies, offer to spawn all of them:

```
Found 3 READY tasks with no dependencies: #50, #54, #55
Spawn all 3 in parallel? Each gets its own workspace.
```

Use the color conventions:
- Green = working
- Amber = waiting for input
- Charcoal = done

## Monitor running agents

After spawning, the human can run `/monitor` to watch all workspaces, or check manually:

```bash
cmux tree   # full hierarchy of all workspaces
```