skill-spawn

name	skill-spawn
description	Research blockers and spawn new tasks to overcome them, updating parent task dependencies
allowed-tools	Task, Bash, Edit, Read, Write

Spawn Skill

Thin wrapper that delegates blocker analysis to spawn-agent subagent, then handles all state management in postflight: creates new task entries, establishes parent-child relationships, and updates dependencies.

IMPORTANT: This skill implements the skill-internal postflight pattern. After the subagent returns, this skill handles all postflight operations (task creation, dependency linking, git commit) before returning. This eliminates the "continue" prompt issue between skill return and orchestrator.

Context References

Reference (do not load eagerly):

• Path: .opencode/context/formats/return-metadata-file.md - Metadata file schema
• Path: .opencode/context/patterns/postflight-control.md - Marker file protocol
• Path: .opencode/context/patterns/jq-escaping-workarounds.md - jq escaping patterns (Issue #1132)

Note: This skill is a thin wrapper with internal postflight. Context is loaded by the delegated agent.

Trigger Conditions

This skill activates when:

• Task status is not terminal (completed, abandoned, expanded)
• /spawn command is invoked with a valid task number

---

Execution Flow

Stage 1: Parse Delegation Context

Parse inputs from the /spawn command:

# Extract from delegation context
task_number=$1
session_id="$2"
blocker_prompt="$3"  # May be empty

# Lookup task data
task_data=$(jq -r --argjson num "$task_number" \
  '.active_projects[] | select(.project_number == $num)' \
  specs/state.json)

# Validate exists
if [ -z "$task_data" ]; then
  echo "Error: Task $task_number not found"
  exit 1
fi

# Extract fields
project_name=$(echo "$task_data" | jq -r '.project_name')
task_type=$(echo "$task_data" | jq -r '.task_type // "general"')
status=$(echo "$task_data" | jq -r '.status')
description=$(echo "$task_data" | jq -r '.description // ""')

---

Stage 2: Preflight Status Update

Determine spawn type and preserve original status before updating.

Spawn type detection:

• If status is blocked, implementing, or partial -> Blocker-driven spawn
• If status is any other non-terminal state -> Holistic decomposition

Note: [BLOCKED] means "has unmet dependencies", not "encountered an error". The parent task transitions to blocked because it now depends on spawned subtasks.

Update state.json (preserve previous_status):

padded_num=$(printf "%03d" "$task_number")
previous_status=$(echo "$task_data" | jq -r '.status')

jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
   --arg status "blocked" \
   --arg prev "$previous_status" \
   --arg sid "$session_id" \
  '(.active_projects[] | select(.project_number == '$task_number')) |= . + {
    status: $status,
    previous_status: $prev,
    last_updated: $ts,
    session_id: $sid
  }' specs/state.json > specs/tmp/state.json && mv specs/tmp/state.json specs/state.json

---

Stage 3: Update TODO.md Parent Status

Use Edit tool to change status marker to [BLOCKED] if not already blocked.

old_string: - **Status**: [{current_status}]
new_string: - **Status**: [BLOCKED]

---

Stage 4: Create Postflight Marker

Create the marker file to prevent premature termination:

mkdir -p "specs/${padded_num}_${project_name}"

cat > "specs/${padded_num}_${project_name}/.postflight-pending" << EOF
{
  "session_id": "${session_id}",
  "skill": "skill-spawn",
  "task_number": ${task_number},
  "operation": "spawn",
  "reason": "Postflight pending: task creation, dependency linking, git commit",
  "created": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
  "stop_hook_active": false
}
EOF

---

Stage 5: Prepare Delegation Context

Find the latest plan path (if exists):

plan_path=""
if [ -d "specs/${padded_num}_${project_name}/plans" ]; then
  plan_path=$(ls -t "specs/${padded_num}_${project_name}/plans/"*.md 2>/dev/null | head -1)
fi

Determine analysis mode for the agent:

analysis_mode="holistic"
if [ "$status" = "blocked" ] || [ "$status" = "implementing" ] || [ "$status" = "partial" ] || [ -n "$blocker_prompt" ]; then
    analysis_mode="blocker"
fi

Prepare delegation context for the subagent:

{
  "session_id": "sess_{timestamp}_{random}",
  "delegation_depth": 2,
  "delegation_path": ["orchestrator", "spawn", "skill-spawn"],
  "timeout": 1800,
  "task_number": N,
  "task_data": {
    "project_number": N,
    "project_name": "{slug}",
    "status": "blocked",
    "task_type": "{task_type}",
    "description": "{description}",
    "effort": "{effort}"
  },
  "blocker_prompt": "{optional user description}",
  "plan_path": "{path to latest plan or null}",
  "analysis_mode": "blocker" | "holistic",
  "metadata_file_path": "specs/{NNN}_{SLUG}/.return-meta.json"
}

---

Stage 6: Invoke Subagent

CRITICAL: You MUST use the Task tool to spawn the subagent.

Required Tool Invocation:

Tool: Task (NOT Skill)
Parameters:
  - subagent_type: "spawn-agent"
  - prompt: [Include task_number, task_data, blocker_prompt, plan_path, metadata_file_path, session_id]
  - description: "Analyze blocker for task {N} and propose new tasks"

DO NOT use Skill(spawn-agent) - this will FAIL.

The subagent will:

• Load task context and plan
• Analyze the blocker and identify root cause
• Propose minimal new tasks with dependencies
• Write blocker analysis report
• Write .spawn-return.json with task definitions
• Return a brief text summary (NOT JSON)

---

Stage 6b: Self-Execution Fallback

CRITICAL: If you performed the work above WITHOUT using the Task tool (i.e., you read files, wrote artifacts, or updated metadata directly instead of spawning a subagent), you MUST write a .return-meta.json file now before proceeding to postflight. Use the schema from return-metadata-file.md with the appropriate status value for this operation.

If you DID use the Task tool, skip this stage -- the subagent already wrote the metadata.

---

Postflight (ALWAYS EXECUTE)

The following stages MUST execute after work is complete, whether the work was done by a subagent or inline (Stage 6b). Do NOT skip these stages for any reason.

Stage 7: Read Return Metadata

Read the spawn return file:

spawn_file="specs/${padded_num}_${project_name}/.spawn-return.json"

if [ -f "$spawn_file" ] && jq empty "$spawn_file" 2>/dev/null; then
    new_tasks=$(jq -r '.new_tasks' "$spawn_file")
    task_count=$(jq '.new_tasks | length' "$spawn_file")

    if [ "$task_count" -eq 0 ]; then
        echo "Spawn cancelled: no tasks selected."
        # Cleanup and restore parent status if needed
        rm -f "specs/${padded_num}_${project_name}/.postflight-pending"
        rm -f "specs/${padded_num}_${project_name}/.spawn-return.json"
        exit 0
    fi

    dependency_order=$(jq -r '.dependency_order' "$spawn_file")
    analysis_summary=$(jq -r '.analysis_summary' "$spawn_file")
    report_path=$(jq -r '.report_path' "$spawn_file")
else
    echo "Error: Invalid or missing spawn return file"
    exit 1
fi

---

Stage 8: Get Next Task Numbers

Get the next available task numbers from state.json:

next_num=$(jq -r '.next_project_number' specs/state.json)

# Calculate task numbers for each new task based on dependency_order
# First task gets next_num, second gets next_num+1, etc.

---

Stage 9: Apply Topological Sort (Kahn's Algorithm)

The agent provides dependency_order which is already topologically sorted (foundational tasks first). Map internal indices to actual task numbers:

# Example: dependency_order = [0, 1] means task at index 0 is foundational
# If next_num = 242:
#   - Index 0 -> Task {N} (foundational)
#   - Index 1 -> Task {M} (depends on {N})

# Build index->task_number mapping
declare -A task_num_map
order_idx=0
for idx in $(echo "$dependency_order" | jq -r '.[]'); do
    task_num_map[$idx]=$((next_num + order_idx))
    order_idx=$((order_idx + 1))
done

---

Stage 10: Create New Task Directories

For each new task, create directory structure:

for idx in $(echo "$dependency_order" | jq -r '.[]'); do
    new_task_num=${task_num_map[$idx]}
    new_padded=$(printf "%03d" "$new_task_num")

    # Get task data from spawn return
    task_title=$(jq -r --argjson i "$idx" '.new_tasks[$i].title' "$spawn_file")
    task_slug=$(echo "$task_title" | tr '[:upper:]' '[:lower:]' | tr ' ' '_' | sed 's/[^a-z0-9_]//g')

    # Create directory with research artifact stub
    mkdir -p "specs/${new_padded}_${task_slug}/reports"

    # Copy spawn analysis as initial research for first task
    # (or create stub pointing to parent's spawn analysis)
done

---

Stage 11: Update state.json with New Tasks

Insert new tasks in topological order (foundational first):

for idx in $(echo "$dependency_order" | jq -r '.[]'); do
    new_task_num=${task_num_map[$idx]}

    # Extract task fields
    task_title=$(jq -r --argjson i "$idx" '.new_tasks[$i].title' "$spawn_file")
    task_desc=$(jq -r --argjson i "$idx" '.new_tasks[$i].description' "$spawn_file")
    task_effort=$(jq -r --argjson i "$idx" '.new_tasks[$i].effort' "$spawn_file")
    task_lang=$(jq -r --argjson i "$idx" '.new_tasks[$i].task_type' "$spawn_file")
    internal_deps=$(jq -r --argjson i "$idx" '.new_tasks[$i].dependencies' "$spawn_file")

    # Convert internal deps to task numbers
    resolved_deps="[]"
    for dep_idx in $(echo "$internal_deps" | jq -r '.[]'); do
        dep_num=${task_num_map[$dep_idx]}
        resolved_deps=$(echo "$resolved_deps" | jq --argjson n "$dep_num" '. + [$n]')
    done

    # Create task slug
    task_slug=$(echo "$task_title" | tr '[:upper:]' '[:lower:]' | tr ' ' '_' | sed 's/[^a-z0-9_]//g')

    # Add to state.json
    jq --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \