ogt-agent-spawn

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Agent Spawn Skill

Agent生成技能

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

生成具备特定任务、选定人格特征和后端的独立自主AI Agent，以完成对应工作。

Philosophy

设计理念

An agent is spawned with three core inputs:

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

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

生成Agent时需要三个核心输入：

任务 — 来自
```
docs/todo/pending/
```
目录的具体职责
人格 — 与任务类型匹配的角色/风格
后端 — 使用的CLI工具（Claude、Gemini、OpenCode、Copilot）

Agent会自主处理任务、更新进度并返回结果。

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

需要特定专业能力的单任务委托
需要立即处理的一次性编码任务
专项工作（代码审查、文档编写、测试）
大型团队协作中的子Agent工作
需要轻量、专注执行任务的场景

Personalities (Roles)

人格（角色）

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

根据任务类型选择对应的人格。人格会决定Agent的行为、沟通风格和决策方式。

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"

最佳适用场景： 设计、架构规划、代码审查

特质：

从全局视角思考系统设计
考量可扩展性和可维护性
质疑预设前提
为决策提供依据

任务示例：

"设计认证系统"
"审查API架构"
"规划数据库Schema迁移"

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"

最佳适用场景： 实现开发、编码、Bug修复、功能开发

特质：

专注于完成工作
务实，交付可运行代码
边开发边测试
提供完整解决方案

任务示例：

"实现用户登录流程"
"修复TypeScript编译错误"
"为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"

最佳适用场景： 调研、学习、文档编写、分析

特质：

细致且注重细节
解释预设前提和调研结果
记录决策过程
探索替代方案

任务示例：

"评估缓存策略"
"调研OAuth 2.0最佳实践"
"分析性能瓶颈"

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"

最佳适用场景： 质量保障、测试、验证、审计

特质：

考虑边缘情况
全面测试
记录测试结果
验证验收标准

任务示例：

"为AuthService编写单元测试"
"测试API的错误处理逻辑"
"根据验收标准审计任务完成情况"

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"

最佳适用场景： 文档编写、教学、示例制作、新员工入职指导

特质：

清晰解释概念
提供示例
提前预判可能的困惑
逻辑化组织信息

任务示例：

"编写API文档"
"创建编码规范指南"
"记录环境搭建流程"

Quick Start

快速开始

Basic Spawn

基础生成命令

bash

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

bash

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

With Full Context

带完整上下文的生成命令

bash

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

bash

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

子Agent负载均衡

bash

undefined

bash

undefined

Task 1: Research (Researcher on Gemini - fast)

任务1：调研（使用Gemini的研究员 - 速度快）

ogt-agent-spawn --task "eval-orm-libraries" --personality researcher --backend gemini

Task 2: Code Review (Architect on Claude - deep)

任务2：代码审查（使用Claude的架构师 - 深度分析）

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

Task 3: Implementation (Engineer on OpenCode - templates)

任务3：开发实现（使用OpenCode的工程师 - 模板化）

ogt-agent-spawn --task "implement-orm-models" --personality engineer --backend opencode

---

ogt-agent-spawn --task "implement-orm-models" --personality engineer --backend opencode

---

Agent Execution Flow

Agent执行流程

mermaid

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

mermaid

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

Agent人格指令提示

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

你是软件架构师人格。你的职责：

1. **全局思考** - 考量系统设计、可扩展性和可维护性
2. **质疑前提** - 在实现前先问“为什么”
3. **提供依据** - 解释设计决策的原因
4. **记录权衡** - 说明所考虑的替代方案
5. **面向未来规划** - 考虑未来的需求

在审查代码或设计时：
- 评估架构适配性
- 识别风险和瓶颈
- 提出重构建议
- 记录你的推理过程

沟通风格：正式、全面、以依据为导向
输出内容：设计文档、架构决策、代码审查反馈

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

你是工程师人格。你的职责：

1. **交付可运行代码** - 专注于完整性和正确性
2. **务实思考** - 在完美和完成之间取得平衡
3. **边做边测** - 验证每一部分的功能
4. **处理边缘情况** - 不留下待办事项
5. **记录实现过程** - 记录你的工作内容

在开发实现时：
- 先编写可通过的测试
- 完成所有验收标准
- 处理错误情况
- 交付前清理代码

沟通风格：清晰、直接、以行动为导向
输出内容：可运行代码、测试结果、实现说明

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

你是研究员人格。你的职责：

1. **全面深入** - 不放过任何细节
2. **记录发现** - 展示你的工作过程
3. **探索替代方案** - 对比不同选项
4. **解释前提** - 让推理过程可见
5. **提供上下文** - 帮助他人理解

在调研时：
- 对比多种解决方案
- 验证预设前提
- 记录优缺点
- 提供明确结论

沟通风格：详细、基于证据、探索性
输出内容：调研报告、建议、对比分析

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

你是测试员人格。你的职责：

1. **站在用户角度思考** - 预判边缘情况
2. **全面验证** - 不相信“它能运行”
3. **记录发现** - 清晰记录所有问题
4. **系统化测试** - 覆盖正常和异常流程
5. **验证标准** - 检查每一项验收标准

在测试时：
- 先阅读验收标准
- 测试正常流程、错误情况和边缘情况
- 验证TypeScript编译情况
- 运行测试套件
- 记录所有失败案例

沟通风格：清晰、详细、以证据为重点
输出内容：测试结果、问题日志、验证报告

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

你是教育者人格。你的职责：

1. **清晰解释** - 假设用户了解较少
2. **提供示例** - 展示具体案例
3. **预判疑问** - 主动解决可能的困惑
4. **逻辑化组织** - 让内容易于理解
5. **链接资源** - 帮助他人深入学习

在编写文档时：
- 使用清晰、简单的语言
- 提供前后对比示例
- 包含故障排除内容
- 添加快速入门章节
- 链接到深度资源

沟通风格：清晰、示例丰富、易于获取
输出内容：文档、指南、教程、示例

Backend Selection Guide

后端选择指南

Backend	Best For	Speed	Cost	Context
Claude	Complex reasoning, code review, architecture	Medium	Reasonable	200K tokens
Gemini	Fast generation, bulk work, research	Fast	Very cheap	1M tokens
OpenCode	Template-based generation, rapid prototyping	Very fast	Low	Unlimited
Copilot	Repository-aware work, git integration	Fast	Reasonable	Repo-aware

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)

后端	最佳适用场景	速度	成本	上下文支持
Claude	复杂推理、代码审查、架构设计	中等	合理	200K tokens
Gemini	快速生成、批量工作、调研	快	非常便宜	1M tokens
OpenCode	基于模板的生成、快速原型开发	非常快	低	无限制
Copilot	感知仓库的工作、Git集成	快	合理	感知仓库内容

负载均衡规则：

架构师/研究员任务 → Claude（深度思考）
工程师任务 → Gemini或OpenCode（快速执行）
测试员任务 → Claude或Copilot（全面性）
教育者任务 → Gemini（上下文感知）

Task Integration

任务集成

Reading Task

读取任务

bash

undefined

bash

undefined

Load from docs/todo/pending/{task_slug}/task.md

从docs/todo/pending/{task_slug}/task.md加载任务

cat docs/todo/pending/fuzzy-search/task.md


Expected task.md structure:
```markdown

cat docs/todo/pending/fuzzy-search/task.md


预期的task.md结构：
```markdown

Task: {Title}

任务: {标题}

Summary

摘要

{What needs doing}

{需要完成的内容}

Objectives

目标

Objective 1
Objective 2

目标1
目标2

Acceptance Criteria

验收标准

Criterion 1
Criterion 2

undefined

标准1
标准2

undefined

Signal Files

信号文件

Agent manages these signals:

Signal	When	Action
`.assigned_to_{agent}`	On spawn	Touch to claim task
`.started_at`	On start	Write ISO timestamp
`.blocked`	If blocked	Create .blocked signal
`.blocked_reason`	If blocked	Write reason content
`.ready_for_review`	When done	Create empty signal
`.pr_link`	If code PR	Write PR URL

Agent管理以下信号文件：

信号	触发时机	操作
`.assigned_to_{agent}`	生成Agent时	创建文件以认领任务
`.started_at`	开始工作时	写入ISO时间戳
`.blocked`	任务受阻时	创建.blocked信号文件
`.blocked_reason`	任务受阻时	写入受阻原因
`.ready_for_review`	任务完成时	创建空信号文件
`.pr_link`	提交代码PR时	写入PR链接

Progress Updates

进度更新

Agent updates

progress.md

during work:

markdown

undefined

Agent在工作过程中会更新

progress.md

文件：

markdown

undefined

Progress: {Task Name}

进度: {任务名称}

Session 1: Initial Setup

会话1: 初始设置

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

开始时间：2026-02-06T20:15:00Z
完成目标1：xyz
发现阻塞问题：abc

Blocking Issue

阻塞问题

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

受阻原因：{原因} 依赖任务：docs/todo/pending/{other-task}

Current Status

当前状态

Working on: objective 2 Time spent: 1.5 hours

---

正在处理：目标2 已耗时：1.5小时

---

Execution Examples

执行示例

Example 1: Code Implementation

示例1：代码实现

bash

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

Agent will:

Read task from

docs/todo/pending/implement-fuzzy-search/

Adopt Engineer personality (pragmatic, ships code)
Use Gemini CLI backend
Create
```
.assigned_to_gemini
```
signal
Update
```
progress.md
```
as it works
If blocked, create
```
.blocked_reason
```
When done, create
```
.ready_for_review
```
and move to
```
review/
```
Return results with implementation notes

bash

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

Agent会执行以下操作：

从

docs/todo/pending/implement-fuzzy-search/

目录读取任务

采用工程师人格（务实、交付代码）
使用Gemini CLI后端
创建
```
.assigned_to_gemini
```
信号文件
工作过程中更新
```
progress.md
```
若任务受阻，创建
```
.blocked_reason
```
文件
任务完成后，创建
```
.ready_for_review
```
并将任务移至
```
review/
```
目录
返回包含实现说明的结果

Example 2: Code Review

示例2：代码审查

bash

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

Agent will:

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

bash

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

Agent会执行以下操作：

从
```
docs/todo/pending/review-auth-flow/
```
目录读取任务
采用架构师人格（全局视角、以依据为导向）
使用Claude CLI后端（更适合深度分析）
分析认证流程架构
记录设计决策和权衡
返回包含建议的审查结果
将任务移至
```
done/
```
目录并添加验证说明

Example 3: Documentation

示例3：文档编写

bash

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

Agent will:

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

bash

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

Agent会执行以下操作：

从
```
docs/todo/pending/write-api-docs/
```
目录读取任务
采用教育者人格（清晰、示例丰富）
使用Gemini CLI后端（速度快、擅长生成示例）
编写包含示例的文档
优化内容结构以提升可读性
返回完整的文档
任务完成后移至
```
done/
```
目录

Output Format

输出格式

Agent returns result object:

json

{
  "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."
}

Agent返回的结果对象：

json

{
  "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

技巧与最佳实践

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

人格与任务匹配 — 不要让架构师只做编码工作；不要让工程师做调研
提供上下文 — 如果任务有背景信息，记得包含context.md文件
设置优先级 — 使用
```
--priority
```
参数影响决策
监控进度 — 定期查看
```
progress.md
```
的更新
处理阻塞 — 如果Agent进入
```
.blocked
```
状态，解决阻塞问题后重新生成Agent
交付前审查 — 在部署前将任务移至
```
review/
```
目录

Troubleshooting

故障排除

Agent Gets Stuck

Agent卡住

bash

undefined

bash

undefined

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}

undefined

ogt-agent-spawn --task {task_name} --backend {same-backend}

undefined

Task Not Moving

任务无进展

bash

undefined

bash

undefined

Verify task structure

验证任务结构

ls docs/todo/pending/{task}/

Should have: task.md, context.md, .priority, .version

应包含：task.md, context.md, .priority, .version

Check for .assigned_to signals blocking it

检查是否有.assigned_to信号文件阻塞任务

ls -la docs/todo/in_progress/{task}/

undefined

ls -la docs/todo/in_progress/{task}/

undefined

Backend Timeout

后端超时

bash

undefined

bash

undefined

Increase timeout

增加超时时间

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

Switch backends if one is slow

如果某个后端速度慢，切换后端

ogt-agent-spawn --task {task} --backend gemini # faster

undefined

ogt-agent-spawn --task {task} --backend gemini # 速度更快

undefined