spawn-agent

Category: Tools & Productivity | Uploader: khanhbkqt | Downloads: 0 | Version: v1.0（Latest）

Spawn worker agents (Gemini CLI or Codex CLI) to keep main context clean. Use for implementation, codebase research, context gathering, or any scoped work that would pollute the orchestrator's context.

Changelog: Source: GitHub https://github.com/khanhbkqt/spawn-agent

Directory Structure

Current level: Root

📁 scripts/
- 📄 spawn-agent.sh 6.5 KB
📁 templates/
- 📄 bugfix-task.md 1.5 KB
- 📄 implementation-task.md 4.3 KB
- 📄 research-task.md 1.8 KB
📄 .gitignore 124 B
📄 CHANGELOG.md 766 B
📄 CONTRIBUTING.md 1.3 KB
📄 LICENSE 1.0 KB
📄 README.md 8.1 KB
📄 SKILL.md 4.8 KB

SKILL.md

---
name: spawn-agent
description: Spawn worker agents (Gemini CLI or Codex CLI) to keep main context clean. Use for implementation, codebase research, context gathering, or any scoped work that would pollute the orchestrator's context.
---

# 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 `/tmp/spawn-agent-task-<name>.md`.

#### 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)

```markdown
# 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

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

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

# Gemini — research (yolo is fine for read-only research)
spawn-agent.sh --gemini --yolo --timeout 120 \
  -f /tmp/spawn-agent-task-<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 `/tmp/spawn-agent-output-<timestamp>.log`.

```bash
cat /tmp/spawn-agent-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

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

spawn-agent

Directory Structure

SKILL.md

Report

Notice