khanhbkqt/spawn-agent

Spawn Agent

Orchestration & Delegation pattern: The main agent acts as the orchestrator (plan, delegate, review). Worker agents (Gemini/Codex) execute specific tasks and report results.

When to Use

Use when:

• Implementation task has a clear scope (fix bug, add function, refactor file)
• You need to research/query the codebase without polluting the main context
• The task is independent and doesn't need intermediate human review
• You want to keep the main context clean for high-level reasoning

Do NOT use when:

• Task requires interactive discussion with the user
• Scope is too broad (refactoring an entire module)
• Multiple files with complex inter-dependencies need coordination
• Task needs browser interaction or external API calls

Choosing an Agent

| Agent | CLI | Strengths | Best for | |-------|-----|-----------|----------| | Gemini | gemini | Fast, good at codebase understanding, reads project context | Research, context gathering, quick implementations | | Codex | codex exec | Strong reasoning, sandboxed execution, code review capability | Complex implementation, refactoring, bug fixing |

[!TIP] Choose the agent based on the task — don't stick to one CLI. Each has its own strengths.

Delegation Protocol

Step 1: DEFINE — Clearly define the task

Before spawning, the orchestrator must determine:

• Goal: What should the task achieve?
• Scope: Which files/directories are involved?
• Agent: Is Gemini or Codex more suitable?
• Constraints: What must NOT be modified?
• Expected output: What result is expected (code changes, summary, list)?

Step 2: COMPOSE — Write the prompt file using a template

Choose the appropriate template and fill it in. Save to .agent/spawn_agent_tasks/<name>.md.

[!NOTE] Create the directory if it doesn't exist: mkdir -p .agent/spawn_agent_tasks Add .agent/spawn_agent_tasks/ to .gitignore if you don't want to track task files.

Template Selection Guide

| Task type | Template | Key sections | |-----------|----------|-------------| | Complex implementation | templates/implementation-task.md | Architecture context, File Map, Step-by-step, Conventions, Acceptance criteria | | Codebase research | templates/research-task.md | Where to look, Questions to answer, Output format | | Bug fix | templates/bugfix-task.md | Bug description, Suspected location, Fix approach |

[!IMPORTANT] Headless worker = no Q&A. The worker agent cannot ask clarifying questions. The more detailed the template, the more accurate the output. Each missing section = one point where the agent may go wrong.

Quick inline prompt (for simple tasks)

# Task: <short name>
## Goal: <one sentence describing the objective>
## Files: <files to modify>
## Constraints: DO NOT modify files outside <scope>
## When done: Summarize changes made and any issues found.

Step 3: SPAWN — Call the worker agent

# Gemini — implementation task
spawn-agent.sh --gemini --auto-edit --timeout 300 \
  -f .agent/spawn_agent_tasks/<name>.md

# Codex — implementation task
spawn-agent.sh --codex --auto-edit --timeout 300 \
  -f .agent/spawn_agent_tasks/<name>.md

# Gemini — research (yolo is fine for read-only research)
spawn-agent.sh --gemini --yolo --timeout 120 \
  -f .agent/spawn_agent_tasks/<name>.md

# Quick task — any agent
spawn-agent.sh --codex --yolo --timeout 60 \
  -p "Fix typo 'recieve' -> 'receive' in auth.service.ts"

Approval modes (mapped per agent):

| Mode | Flag | Gemini | Codex | |------|------|--------|-------| | Auto-edit | --auto-edit | auto_edit | auto-edit | | Full auto | --yolo | yolo | full-auto | | Safest | --safe | default | suggest |

Step 4: REVIEW — Read the output

Output is saved to .agent/spawn_agent_tasks/output-<timestamp>.log.

cat .agent/spawn_agent_tasks/output-*.log | tail -100

Verify:

• Did the task achieve the goal?
• Are there changes outside the defined scope?
• Are there errors/warnings that need handling?

Step 5: REPORT — Summarize for the user

• ✅ Success: summarize changes
• ❌ Failure: root cause + next steps
• ⚠️ Partial: what was completed, what still needs to be done

Anti-Patterns

❌ Delegating too broadly: "Refactor the entire backend" ✅ Specific scope: "Refactor auth.service.ts to extract token logic into token.service.ts"

❌ No constraints: Agent may modify files outside scope ✅ Set boundaries: "DO NOT modify files outside packages/backend/src/auth/"

❌ Not reading output: Spawning and assuming success ✅ Always review: Read output, verify changes, check errors

❌ Delegation chain: Spawn A → output feeds spawn B → ... ✅ Orchestrator controls flow: Read result A, decide next step, then spawn B if needed