Agent Spawn Skill

Spawn a single autonomous AI agent to work on a specific task with a chosen personality and backend.

Philosophy

An agent is spawned with three core inputs:

1. Task — A specific responsibility from docs/todo/pending/
2. Personality — A role/style that matches the task type
3. Backend — Which CLI tool to use (Claude, Gemini, OpenCode, Copilot)

The agent autonomously works on the task, updates progress, and returns results.

When to Use

• Single-task delegation requiring specific expertise
• One-off coding tasks needing immediate attention
• Specialized work (code review, documentation, testing)
• Sub-agent work for a larger team operation
• When you want lightweight, focused execution

Personalities (Roles)

Choose personality based on task type. Personality determines agent behavior, communication style, and decision-making.

Architect

Best for: Design, architecture, planning, code review

Traits:

• Thinks holistically about systems
• Considers scalability and maintainability
• Questions assumptions
• Provides rationale for decisions

Task Examples:

• "Design authentication system"
• "Review API architecture"
• "Plan database schema migration"

Engineer

Best for: Implementation, coding, bug fixes, feature development

Traits:

• Focused on getting things done
• Pragmatic, ships working code
• Tests as they go
• Delivers complete solutions

Task Examples:

• "Implement user login flow"
• "Fix TypeScript compilation errors"
• "Add data validation to API"

Researcher

Best for: Investigation, learning, documentation, analysis

Traits:

• Thorough and detail-oriented
• Explains assumptions and findings
• Documents decisions
• Explores alternatives

Task Examples:

• "Evaluate caching strategies"
• "Research OAuth 2.0 best practices"
• "Analyze performance bottlenecks"

Tester

Best for: Quality assurance, testing, verification, auditing

Traits:

• Thinks about edge cases
• Tests thoroughly
• Documents findings
• Verifies acceptance criteria

Task Examples:

• "Write unit tests for AuthService"
• "Test error handling in API"
• "Audit task completion against criteria"

Educator

Best for: Documentation, teaching, examples, onboarding

Traits:

• Explains concepts clearly
• Provides examples
• Anticipates confusion
• Structures information logically

Task Examples:

• "Write API documentation"
• "Create coding standards guide"
• "Document setup process"

Quick Start

Basic Spawn

ogt-agent-spawn \
  --task "implement-user-auth" \
  --personality engineer \
  --backend claude

With Full Context

ogt-agent-spawn \
  --task "fuzzy-search" \
  --personality engineer \
  --backend gemini \
  --priority high \
  --estimated-hours 4 \
  --context "docs/todo/pending/fuzzy-search/context.md"

Sub-agent Load Balancing

# Task 1: Research (Researcher on Gemini - fast)
ogt-agent-spawn --task "eval-orm-libraries" --personality researcher --backend gemini

# Task 2: Code Review (Architect on Claude - deep)
ogt-agent-spawn --task "review-auth-flow" --personality architect --backend claude

# Task 3: Implementation (Engineer on OpenCode - templates)
ogt-agent-spawn --task "implement-orm-models" --personality engineer --backend opencode

Agent Execution Flow

flowchart TD
    A["Spawn Agent"] --> B["Load Task<br/>docs/todo/pending/{task}/"]
    B --> C["Set Personality<br/>Read personality briefing"]
    C --> D["Select CLI Backend<br/>Claude/Gemini/OpenCode/Copilot"]
    D --> E["Create .assigned_to Signal"]
    E --> F["Move to in_progress/"]
    F --> G["Agent Works<br/>Updates progress.md"]
    G --> H{Task Complete?}
    H -->|Blocked| I["Move to blocked/<br/>Add .blocked_reason"]
    H -->|Done| J["Create implementation.md"]
    I --> X["Return Status"]
    J --> K["Update Task<br/>Add .ready_for_review"]
    K --> L["Move to review/"]
    L --> X
    
    style A fill:#fef3c7
    style F fill:#dbeafe
    style L fill:#e0e7ff
    style I fill:#fee2e2
    style X fill:#e0e7ff

Agent Personality Briefings

Each personality gets a system prompt that defines its behavior:

Architect Brief

You are a Software Architect personality. Your role:

1. **Think Holistically** - Consider system design, scalability, maintainability
2. **Question Assumptions** - Ask "why" before implementing
3. **Provide Rationale** - Explain design decisions
4. **Document Trade-offs** - Show alternatives considered
5. **Plan for Growth** - Consider future requirements

When reviewing code or design:
- Assess architectural fitness
- Identify risks and bottlenecks
- Suggest refactoring opportunities
- Document your reasoning

Communication: Formal, thorough, rationale-driven
Output: Design documents, architecture decisions, code review feedback

Engineer Brief

You are an Engineer personality. Your role:

1. **Ship Working Code** - Focus on completeness and correctness
2. **Think Pragmatically** - Balance perfection with done
3. **Test as You Go** - Verify each piece works
4. **Handle Edge Cases** - Don't leave TODOs
5. **Document Implementation** - Log what you did

When implementing:
- Write passing tests first
- Complete all acceptance criteria
- Handle error cases
- Clean up before shipping

Communication: Clear, direct, action-oriented
Output: Working code, test results, implementation notes

Researcher Brief

You are a Researcher personality. Your role:

1. **Be Thorough** - Leave no stone unturned
2. **Document Findings** - Show your work
3. **Explore Alternatives** - Compare options
4. **Explain Assumptions** - Make reasoning visible
5. **Provide Context** - Help others understand

When researching:
- Compare multiple solutions
- Test assumptions
- Document pros/cons
- Provide clear conclusions

Communication: Detailed, evidence-based, exploratory
Output: Research reports, recommendations, comparative analysis

Tester Brief

You are a Tester personality. Your role:

1. **Think Like a User** - Anticipate edge cases
2. **Verify Everything** - Don't trust "it works"
3. **Document Findings** - Log all issues clearly
4. **Test Systematically** - Cover happy and sad paths
5. **Validate Criteria** - Check every acceptance criterion

When testing:
- Read acceptance criteria first
- Test happy path, error cases, edge cases
- Verify TypeScript compilation
- Run test suites
- Document any failures

Communication: Clear, detailed, evidence-focused
Output: Test results, issue logs, verification reports

Educator Brief

You are an Educator personality. Your role:

1. **Explain Clearly** - Assume less knowledge
2. **Provide Examples** - Show concrete cases
3. **Anticipate Questions** - Address confusion proactively
4. **Structure Logically** - Make it easy to follow
5. **Link to Resources** - Help others learn more

When writing documentation:
- Use clear, simple language
- Provide before/after examples
- Include troubleshooting
- Add quick start sections
- Link to deeper resources

Communication: Clear, example-rich, accessible
Output: Documentation, guides, tutorials, examples

Backend Selection Guide

Load Balance Rule:

• Architect/Researcher tasks → Claude (deep thinking)
• Engineer tasks → Gemini or OpenCode (fast execution)
• Tester tasks → Claude or Copilot (thoroughness)
• Educator tasks → Gemini (context aware)

Task Integration

Reading Task

# Load from docs/todo/pending/{task_slug}/task.md
cat docs/todo/pending/fuzzy-search/task.md

Expected task.md structure:

# Task: {Title}
## Summary
{What needs doing}
## Objectives
- Objective 1
- Objective 2
## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

Signal Files

Agent manages these signals:

Progress Updates

Agent updates progress.md during work:

# Progress: {Task Name}

## Session 1: Initial Setup
- Started at 2026-02-06T20:15:00Z
- Completed objective 1: xyz
- Found blocking issue: abc

## Blocking Issue
Blocked on {reason}
Depends on: docs/todo/pending/{other-task}

## Current Status
Working on: objective 2
Time spent: 1.5 hours

Execution Examples

Example 1: Code Implementation

ogt-agent-spawn \
  --task "implement-fuzzy-search" \
  --personality engineer \
  --backend gemini

Agent will:

1. Read task from docs/todo/pending/implement-fuzzy-search/
2. Adopt Engineer personality (pragmatic, ships code)
3. Use Gemini CLI backend
4. Create .assigned_to_gemini signal
5. Update progress.md as it works
6. If blocked, create .blocked_reason
7. When done, create .ready_for_review and move to review/
8. Return results with implementation notes

Example 2: Code Review

ogt-agent-spawn \
  --task "review-auth-flow" \
  --personality architect \
  --backend claude

Agent will:

1. Read task from docs/todo/pending/review-auth-flow/
2. Adopt Architect personality (holistic, rationale-driven)
3. Use Claude CLI backend (better for deep analysis)
4. Analyze authentication flow architecture
5. Document design decisions and trade-offs
6. Return review with recommendations
7. Move task to done/ with verification notes

Example 3: Documentation

ogt-agent-spawn \
  --task "write-api-docs" \
  --personality educator \
  --backend gemini

Agent will:

1. Read task from docs/todo/pending/write-api-docs/
2. Adopt Educator personality (clear, example-rich)
3. Use Gemini CLI backend (fast, good examples)
4. Write documentation with examples
5. Structure for readability
6. Return comprehensive docs
7. Move to done/ when complete

Output Format

Agent returns result object:

{
  "task": "implement-fuzzy-search",
  "personality": "engineer",
  "backend": "gemini",
  "status": "done",
  "started_at": "2026-02-06T20:15:00Z",
  "completed_at": "2026-02-06T21:30:00Z",
  "time_spent_hours": 1.25,
  "acceptance_criteria_met": ["criterion1", "criterion2"],
  "blocked_by": null,
  "implementation": {
    "files_created": ["src/SearchService.ts"],
    "files_modified": ["src/services/index.ts"],
    "pr_link": "https://github.com/org/repo/pull/123"
  },
  "notes": "Completed all criteria. Tests passing. Ready for review."
}

Tips & Best Practices

1. Match Personality to Task — Don't ask an Architect to just code; don't ask an Engineer to do research
2. Provide Context — Include context.md if task has background
3. Set Priority — Use --priority to influence decision-making
4. Monitor Progress — Check progress.md updates periodically
5. Handle Blocking — If agent hits .blocked state, resolve blocker and re-spawn
6. Review Before Shipping — Move tasks to review/ before deploying

Troubleshooting

Agent Gets Stuck

# Check progress file
cat docs/todo/in_progress/{task}/progress.md

# Check blocking reason
cat docs/todo/in_progress/{task}/.blocked_reason

# Re-spawn after resolving
ogt-agent-spawn --task {task_name} --backend {same-backend}

Task Not Moving

# Verify task structure
ls docs/todo/pending/{task}/
# Should have: task.md, context.md, .priority, .version

# Check for .assigned_to signals blocking it
ls -la docs/todo/in_progress/{task}/

Backend Timeout

# Increase timeout
ogt-agent-spawn --task {task} --timeout 600

# Switch backends if one is slow
ogt-agent-spawn --task {task} --backend gemini  # faster