Sub Agent Patterns

Sub-Agent Patterns Skill

Best practices for spawning and managing sub-agents via sessions_spawn.

When to Use

• Task will take >30 minutes
• Need parallel work streams
• Complex coding/building tasks
• Overnight autonomous work
• Want to avoid context pollution in main session

Agent Routing

Choose the right agent for the task:

Default: sonnet unless specific reason for another.

Overnight dev builds: Always use codex - won't get distracted.

Spawn Template

sessions_spawn({
  agentId: 'codex',  // or haiku, sonnet, opus
  task: `[CONTEXT]
  Brief background on what this is for.
  
  [TASK]
  Specific deliverable(s) expected.
  
  [SUCCESS CRITERIA]
  - Criterion 1
  - Criterion 2
  
  [FILES TO CREATE/MODIFY]
  - /path/to/file1
  - /path/to/file2
  
  [WHEN COMPLETE]
  Use sessions_send to main session with:
  '✅ [task name] complete. Files: [list]. Ready for QA.'
  
  [IF BLOCKED]
  Use sessions_send to main session with:
  '❌ [task name] blocked: [reason]. Need: [what you need]'`,
  label: 'descriptive-label',
  runTimeoutSeconds: 7200  // 2 hours, adjust as needed
})

Always Log Spawns

Log to: /projects/subagent-tracking/SPAWN-LOG.md

Entry format:

## YYYY-MM-DD HH:MM - [label]
- **Agent:** codex/sonnet/haiku/opus
- **Task:** Brief description
- **Status:** SPAWNED / RUNNING / COMPLETED / FAILED
- **Session Key:** [from spawn response]
- **Notes:** [any issues or outcomes]

Monitoring Sub-Agents

Check Status

sessions_list({ kinds: ['spawn'], activeMinutes: 120 })

Get History

sessions_history({ sessionKey: 'the-session-key', limit: 20 })

Send Message

sessions_send({ sessionKey: 'the-session-key', message: 'Status update?' })

Common Patterns

1. Overnight Build

// Before McKinzie sleeps
sessions_spawn({
  agentId: 'codex',
  task: `Build [feature] for [project].
  
  Requirements:
  - [req 1]
  - [req 2]
  
  Start from: /projects/[project]/
  
  When done, update SESSION_STATE.md with completion status
  and use sessions_send to notify main session.`,
  label: 'overnight-feature-build',
  runTimeoutSeconds: 14400  // 4 hours
})

2. Research Task

sessions_spawn({
  agentId: 'sonnet',
  task: `Research [topic] for McKinzie.
  
  Sources to check:
  - [source 1]
  - [source 2]
  
  Output: Create /projects/[project]/research/[topic].md
  
  Include: Executive summary, key findings, recommendations.`,
  label: 'research-[topic]',
  runTimeoutSeconds: 3600
})

3. Quick Parallel Task

// When you need something done while continuing main work
sessions_spawn({
  agentId: 'haiku',
  task: `Update [file] with [specific change].
  
  Just do this one thing and confirm when done.`,
  label: 'quick-edit',
  runTimeoutSeconds: 600
})

Sub-Agent Rules

DO:

• Give complete context (sub-agent has no memory of main session)
• Specify exact deliverables
• Include file paths
• Set appropriate timeout
• Log all spawns to SPAWN-LOG.md
• Check on long-running agents periodically

DON'T:

• Assume sub-agent knows anything about prior work
• Spawn multiple agents for tightly coupled tasks
• Forget to verify completed work
• Let agents run indefinitely without monitoring

Verification Checklist

After sub-agent completes:

• Check the files were actually created/modified
• Run/test the code if applicable
• Update SPAWN-LOG.md with completion status
• Update kanban card if relevant
• Notify McKinzie if significant

Watchdog Script

Run periodically to check sub-agent health:

/Users/mmcassistant/clawd/scripts/subagent-watchdog.sh

Troubleshooting

Last Updated

Feb 2, 2026 - Initial skill creation