Spawn Subagent

Purpose

Launch a Claude Code subagent in an isolated git worktree to execute a specific task. The subagent operates independently with its own context window while the parent agent continues coordinating.

When to Use

• Task has a well-defined PLAN.md ready for execution
• Task is independent enough to execute in isolation
• Parent agent needs to continue with other work
• Context window management requires task isolation

Workflow

1. Generate Subagent Identifiers

# Generate UUID for uniqueness
UUID=$(uuidgen | cut -c1-8)

# Construct names from task context
# Format: {major}.{minor}-{task-name}-sub-{uuid}
WORKTREE_NAME="1.2-implement-parser-sub-a1b2c3d4"
BRANCH_NAME="1.2-implement-parser-sub-a1b2c3d4"

2. Create Worktree and Branch

# Create worktree directory
WORKTREE_PATH=".worktrees/${WORKTREE_NAME}"

# Create branch and worktree together
git worktree add -b "${BRANCH_NAME}" "${WORKTREE_PATH}" HEAD

3. Prepare Task Context

Copy or reference the task's PLAN.md that the subagent will execute:

# Ensure PLAN.md exists in task directory
TASK_PLAN=".claude/dog/tasks/${MAJOR}.${MINOR}-${TASK_NAME}/PLAN.md"

# Subagent will read this directly - no copy needed

4. Configure Session Tracking

Create session file for token tracking:

# Session file location
SESSION_FILE="/home/node/.config/claude/projects/-workspace/${SESSION_ID}.jsonl"

# Record spawn event
echo '{"type":"spawn","parent_session":"'${PARENT_SESSION}'","task":"'${TASK_NAME}'","timestamp":"'$(date -Iseconds)'"}' >> "${SESSION_FILE}"

5. Launch Subagent

# Change to worktree and launch Claude Code
cd "${WORKTREE_PATH}"

# Launch with task context
claude --resume "${SESSION_ID}" \
  --prompt "Execute PLAN.md at ${TASK_PLAN}. Report completion status and metrics."

6. Record Spawn in Parent STATE.md

Update parent's tracking:

subagents:
  - id: a1b2c3d4
    task: 1.2-implement-parser
    worktree: .worktrees/1.2-implement-parser-sub-a1b2c3d4
    branch: 1.2-implement-parser-sub-a1b2c3d4
    session: ${SESSION_ID}
    spawned_at: 2026-01-10T14:30:00Z
    status: running

Examples

Basic Spawn

# Parent agent spawning subagent for parser task
TASK="1.2-implement-parser"
UUID="a1b2c3d4"

git worktree add -b "${TASK}-sub-${UUID}" ".worktrees/${TASK}-sub-${UUID}" HEAD

# Launch subagent
cd ".worktrees/${TASK}-sub-${UUID}"
claude --prompt "Execute task 1.2 PLAN.md"

Spawn with Token Budget

# Include token budget in subagent prompt
claude --prompt "Execute task 1.2 PLAN.md. Token budget: 80,000 tokens. Report if approaching limit."

Anti-Patterns

Do NOT spawn without PLAN.md

# ❌ Spawning with vague instructions
claude --prompt "Work on the parser"

# ✅ Spawning with concrete plan
claude --prompt "Execute PLAN.md at .claude/dog/tasks/1.2-implement-parser/PLAN.md"

Do NOT spawn dependent tasks simultaneously

# ❌ Spawning B that depends on A's output
spawn-subagent task-a
spawn-subagent task-b  # Depends on task-a!

# ✅ Wait for dependency
spawn-subagent task-a
# ... wait for completion ...
spawn-subagent task-b

Do NOT forget worktree cleanup path

# ❌ No tracking of worktree location
git worktree add somewhere

# ✅ Track for later cleanup
WORKTREE=".worktrees/${TASK}-sub-${UUID}"
git worktree add "${WORKTREE}"
# Record in STATE.md for merge-subagent skill

Do NOT spawn from within a subagent worktree

Subagents should not spawn further subagents. If a task needs decomposition, report back to the parent agent.

Related Skills

• dog:monitor-subagents - Check status of spawned subagents
• dog:collect-results - Gather results when subagent completes
• dog:merge-subagent - Merge subagent work back to task branch
• dog:parallel-execute - Spawn multiple subagents concurrently