Spawner — Instant Agent Hiring

Takes job postings → spawns the right agent → passes context → tracks completion.

Activation

Invoked by the orchestrator after JOB_BOARD.md is written with job postings. Can also be invoked directly when the user says "spawn an agent to do X".

Input

Read workspace/JOB_BOARD.md for pending job postings.

Each posting has:

• Job title
• Bucket (BUILD/OUTREACH/etc)
• Task description
• Context (files, prior work)
• Acceptance criteria
• Workspace path
• Timeout
• Dependencies
• Expected outputs

Spawning Rules

Concurrency

• Max 3 sub-agents running at once. Period.
• Before spawning, check subagents list for active count.
• If at limit, queue the job and wait for a completion event.

Agent Configuration by Bucket

Task Description Template

For each sub-agent spawn, construct the task as:

You are working on: [workspace path]

## Job
[Bucket emoji] [Bucket name]: [Job title]

## What to Do
[Detailed task description from job posting]

## Context
[Relevant file contents or summaries — keep under 2K tokens]
[Reference to full files the agent can read itself]

## Acceptance Criteria
[Specific, testable conditions — copied from job posting]
- [ ] [criterion 1]
- [ ] [criterion 2]
- [ ] [criterion 3]

## Constraints
- [Bucket-specific constraints from table above]
- Do NOT modify .env files with real keys
- Build must pass before committing
- Git commit with descriptive message

Dependency Handling

• Check the "Depends On" field of each job.
• If dependency job is ✅ DONE → spawn immediately.
• If dependency job is still running → queue, spawn after completion event.
• If dependency job ❌ FAILED → mark this job as BLOCKED, notify orchestrator.

Context Passing Between Related Jobs

When jobs in the same wave are related:

• Job A produces output/analysis.md → Job B needs it as input
• Include in Job B's context: "Read [path] for context from related job"
• If Job A hasn't finished yet, Job B waits (dependency handling above)

Spawn Execution

# Pseudocode for spawning logic
for wave in execution_plan.waves:
    active = get_active_subagents()
    
    for job in wave.jobs:
        if job.effort == "QUICK":
            execute_inline(job)  # No sub-agent needed
            job.status = "✅"
            continue
        
        # Wait for slot
        while len(active) >= 3:
            wait_for_completion_event()
            active = get_active_subagents()
        
        # Check dependencies
        if job.depends_on and not all_done(job.depends_on):
            job.status = "QUEUED"
            continue
        
        # Spawn
        agent = sessions_spawn(
            label=f"{bucket_prefix}-{job.slug}",
            mode="run",
            runTimeoutSeconds=job.timeout,
            task=build_task_description(job)
        )
        job.status = "🔄"
        job.agent_key = agent.childSessionKey
        active.append(agent)
    
    # Wait for wave to complete before next wave
    wait_for_all_wave_completions(wave)

Completion Tracking

When a sub-agent completion event arrives:

1. Match to job in JOB_BOARD.md by session key or label.
2. Check acceptance criteria:
   • Does the expected output exist?
   • Did the build pass?
   • Did it push to git?
3. Mark job: ✅ DONE (with artifact link) or ❌ FAILED (with reason) or ⚠️ PARTIAL.
4. Update JOB_BOARD.md.
5. Check if any QUEUED jobs can now be spawned (dependency resolved).
6. If all jobs in current wave done → start next wave.

Failure Handling

Anti-patterns

• ❌ Spawning 10 agents at once (max 3)
• ❌ Spawning an agent for a 2-minute task (do it inline)
• ❌ Not passing context (agent wastes time re-reading)
• ❌ Marking ✅ without checking output exists
• ❌ Polling subagents in a loop (wait for push events)
• ❌ Spawning duplicate agents for the same job
• ❌ Not killing stale agents (> timeout + 5 min buffer)

Output

Update workspace/JOB_BOARD.md with:

• Status per job (⏳ → 🔄 → ✅/❌/⚠️)
• Agent session key (for tracking)
• Artifact link (file path, URL, commit hash)
• Completion time

When all jobs complete, notify orchestrator for reconciliation.