# 오케스트레이터 스킬 템플릿 (Antigravity CLI)

오케스트레이터는 팀 전체를 조율하는 상위 스킬이다. Antigravity CLI에서는 메인 에이전트가 오케스트레이터 역할을 하며, `invoke_subagent` 도구를 호출하여 각 서브에이전트에게 작업을 위임하고 전체 워크플로우를 통제한다.

**실행 모드별 3가지 템플릿:**
- **템플릿 A: 서브에이전트 모드 (기본)** — 순차적 위임, 파일 기반 데이터 전달
- **템플릿 B: 병렬 서브에이전트 모드** — 독립 작업 동시 실행
- **템플릿 C: 하이브리드 모드** — Phase마다 다른 패턴 혼합

---

## 템플릿 A: 서브에이전트 모드 (기본 · 순차)

2명 이상의 서브에이전트가 순차적으로 협업할 때 사용한다. 각 서브에이전트는 독립된 격리 컨텍스트에서 실행되며, 약속된 파일 경로를 통해 중간 결과를 넘겨받아 가공한다.

```markdown
---
name: {domain}-orchestrator
description: "{도메인} 서브에이전트 팀을 조율하는 오케스트레이터. {초기 실행 키워드}. 후속 작업: {도메인} 결과 수정, 부분 재실행, 업데이트, 보완, 다시 실행, 이전 결과 개선 요청 시에도 반드시 이 스킬을 사용."
---

# {Domain} Orchestrator

{도메인}의 서브에이전트 팀을 조율하여 {최종 산출물}을 생성하는 통합 스킬.

## 실행 모드: 서브에이전트 (순차)

## 서브에이전트 구성

| 에이전트 TypeName | 역할 | 스킬 | 출력 |
|:---|:---|:---|:---|
| {agent-1} | {역할} | {skill} | `_workspace/{phase}_{agent}_{artifact}.md` |
| {agent-2} | {역할} | {skill} | `_workspace/{phase}_{agent}_{artifact}.md` |

## 워크플로우

### Phase 0: 컨텍스트 확인 (후속 작업 지원)

기존 산출물 존재 여부를 확인하여 실행 모드를 결정한다:

1. `_workspace/` 디렉토리 존재 여부 확인
2. 실행 모드 결정:
   - **`_workspace/` 미존재** → 초기 실행. Phase 1로 진행
   - **`_workspace/` 존재 + 사용자가 부분 수정 요청** → 부분 재실행. `invoke_subagent`를 통해 해당 서브에이전트만 호출하고, 기존 산출물 중 수정 대상만 덮어쓴다.
   - **`_workspace/` 존재 + 새 입력 제공** → 새 실행. 기존 `_workspace/`를 `_workspace_{YYYYMMDD_HHMMSS}/`로 백업 이동한 뒤 Phase 1 진행.
3. 부분 재실행 시: 이전 산출물 경로를 `invoke_subagent` 프롬프트에 포함하여, 서브에이전트가 기존 결과를 읽고 피드백을 반영하도록 지시한다.

### Phase 1: 준비
1. 사용자 입력 분석 — {무엇을 파악하는지}
2. 작업 디렉토리에 `_workspace/` 생성
   - **초기 실행**: 새 `_workspace/` 생성
   - **새 실행**: 기존 `_workspace/`를 백업 이동한 직후 새 `_workspace/` 재생성
3. 입력 데이터를 `_workspace/00_input/`에 저장

### Phase 2: {주요 작업 — 예: 분석/조사}

1. `invoke_subagent` 도구 호출로 {agent-1} 구동:
   - **TypeName**: "{agent-1}"
   - **Role**: "{agent-1-role}"
   - **Prompt**: "지정된 입력 경로 `_workspace/00_input/`에서 데이터를 읽어 {구체적 분석 수행 내용}을 수행하고, 결과를 `_workspace/02_{agent-1}_result.md`에 작성하세요."
   
2. `invoke_subagent` 도구 호출로 {agent-2} 구동:
   - **TypeName**: "{agent-2}"
   - **Role**: "{agent-2-role}"
   - **Prompt**: "{agent-1}의 분석 결과 파일 `_workspace/02_{agent-1}_result.md`를 로드하여 {구체적 가공 내용}을 수행하고, 결과를 `_workspace/02_{agent-2}_result.md`에 최종 작성하세요."

### Phase 3: {후속 작업 — 예: 생성/구현}

3. `invoke_subagent` 도구 호출로 {agent-3} 구동:
   - **TypeName**: "{agent-3}"
   - **Role**: "{agent-3-role}"
   - **Prompt**: "`_workspace/02_{agent-2}_result.md`를 로드하여 {구체적 생성 내용}을 수행하고, 결과를 `_workspace/03_{agent-3}_result.md`에 작성하세요."

### Phase 4: 통합
1. 모든 서브에이전트의 산출물 파일 Read (`view_file` 도구 활용)
2. {통합/검증 로직 적용}
3. 최종 산출물 생성: `{output-path}/{filename}`

### Phase 5: 정리
1. `_workspace/` 디렉토리 보존 (중간 산출물은 삭제하지 않음 — 사후 검증 및 히스토리 역추적용)
2. 사용자에게 결과 요약 보고

## 데이터 흐름

```
[오케스트레이터/메인]
    │
    ├── invoke_subagent("agent-1") ──→ _workspace/02_agent1_result.md
    │                                         │
    │                                         ↓ (Read)
    ├── invoke_subagent("agent-2") ──→ _workspace/02_agent2_result.md
    │                                         │
    │                                         ↓ (Read)
    ├── invoke_subagent("agent-3") ──→ _workspace/03_agent3_result.md
    │
    └── 최종 결과 통합 및 생성 → 최종 산출물
```

## 에러 핸들링

| 상황 | 전략 |
|------|------|
| 서브에이전트 1명 실패 | 1회 재호출 시도. 재실패 시 보고서에 누락을 명시하고 다음 단계 진행 |
| 과반 실패 | 사용자에게 즉각 에러 로그를 보고하고 진행 여부 컨펌 |
| 타임아웃 | 현재까지 수집된 부분 결과 및 백업 파일을 활용하여 복구 진행 |
| 서브에이전트 간 데이터 충돌 | 데이터를 덮어쓰지 않고 출처를 병기하여 보존 |

## 테스트 시나리오

### 정상 흐름
1. 사용자가 {입력}을 제공
2. Phase 1에서 {분석 결과} 도출
3. Phase 2에서 서브에이전트들 순차 실행
4. Phase 3에서 산출물을 통합하여 최종 결과 생성
5. 예상 결과: `{output-path}/{filename}` 생성

### 에러 흐름
1. Phase 2에서 {agent-2} 실행 도중 에러 중단
2. 오케스트레이터가 1회 재호출을 수행
3. 재실행 실패 시 해당 단계를 누락 처리
4. 나머지 결과로 Phase 3 진행
5. 최종 보고서에 "{agent-2} 작업 영역 수집 실패"를 명시하고 보존
```

---

## 템플릿 B: 병렬 서브에이전트 모드 (병렬)

독립적인 여러 작업을 동시에 실행하여 리소스를 아끼고 속도를 높일 때 사용한다. 출력 파일들이 겹치지 않도록 경로 및 파일명을 명확히 구별해야 한다.

```markdown
---
name: {domain}-orchestrator
description: "{도메인} 서브에이전트 팀을 병렬 조율하는 오케스트레이터. {초기 실행 키워드}. 후속 작업 키워드 포함."
---

## 실행 모드: 병렬 서브에이전트

## 서브에이전트 구성

| 에이전트 TypeName | 역할 | 스킬 | 출력 |
|:---|:---|:---|:---|
| {agent-1} | {역할} | {skill} | `_workspace/02_{agent-1}.md` |
| {agent-2} | {역할} | {skill} | `_workspace/02_{agent-2}.md` |
| {agent-3} | {역할} | {skill} | `_workspace/02_{agent-3}.md` |

## 워크플로우

### Phase 0: 컨텍스트 확인
(Template A와 동일 — `_workspace/` 존재 여부 분기)

### Phase 1: 준비
1. 입력 분석
2. `_workspace/` 생성

### Phase 2: 병렬 실행
모든 서브에이전트가 백그라운드에서 실행될 수 있도록 순차적으로 `invoke_subagent` 도구를 즉시 호출한다 (각각 고유 출력 경로 지정):

1. `invoke_subagent` 호출 ({agent-1})
2. `invoke_subagent` 호출 ({agent-2})
3. `invoke_subagent` 호출 ({agent-3})
*모든 서브에이전트 완료 노티 및 응답을 수집할 때까지 대기.*

### Phase 3: 통합
1. 각 서브에이전트 완료 보고를 확인하고 `_workspace/` 하위 결과 수집 (Read)
2. 통합 로직 적용 → 최종 산출물 작성

### Phase 4: 정리
1. `_workspace/` 보존
2. 결과 요약 보고

## 에러 핸들링
- 에이전트 1개 실패: 1회 재실행. 지속 실패 시 누락 명시 후 파이프라인 진행.
- 과반 실패: 사용자 조작 유도 및 컨펌.
- 출력 파일 경로 중복 방지: 각 에이전트의 출력 파일명에 TypeName을 포함하여 고유화.
```

---

## 템플릿 C: 하이브리드 모드

Phase마다 서로 다른 실행 패턴(순차, 병렬, 직접 실행)을 혼합하여 워크플로우를 설계한다. 각 Phase 상단에 `**실행 패턴:** {순차 | 병렬 | 직접}`를 필히 명시한다.

```markdown
---
name: {domain}-orchestrator
description: "{도메인} 오케스트레이터 (하이브리드). {키워드}. 후속 작업 키워드 포함."
---

## 실행 모드: 하이브리드

| Phase | 패턴 | 이유 |
|:---|:---|:---|
| Phase 2 (병렬 수집) | 병렬 서브에이전트 | 복수의 독립 자료 수집 속도 최적화 |
| Phase 3 (합의 통합) | 직접 실행 (메인 통합) | 복합적 정합성 및 가치 판단 필요 |
| Phase 4 (독립 검증) | 순차 서브에이전트 | QA 전문 에이전트를 통한 철저한 사후 분석 |

## 워크플로우

### Phase 2: 병렬 자료 수집
**실행 패턴:** 병렬 서브에이전트

여러 서브에이전트를 동시 구동한다. 결과는 각기 `_workspace/02_{agent}_raw.md`에 안전하게 분할 저장된다.

### Phase 3: 합의 기반 통합
**실행 패턴:** 직접 실행

메인 에이전트가 Phase 2의 출력 파일들을 모두 취합하여 읽어들여 상충 내용을 보완하고 종합적인 정합성을 반영한다. 최종 통합본 `_workspace/03_integrated.md`를 생산한다.

### Phase 4: 독립 검증
**실행 패턴:** 순차 서브에이전트

QA 서브에이전트 `invoke_subagent`를 구동하여, 입력으로 넘겨받은 `_workspace/03_integrated.md`에 대한 객관적인 품질 및 정합성 검증 레포트를 작성하도록 한다.
```

**하이브리드 전환 규칙:**
- **병렬 → 순차**: 병렬 구동 중인 모든 백그라운드 서브에이전트의 작업 완료(메시지 수집)를 완전 대기한 뒤 순차 Phase로 진입한다.
- **순차 → 병렬**: 이전 순차 단계 완료 후 저장된 최종 결과 경로를 모든 병렬 서브에이전트 프롬프트에 공유 및 전달하여 동시 작업을 시작한다.
- **서브에이전트 → 직접 실행**: 서브에이전트가 완성해 둔 산출물들을 메인 오케스트레이터가 직접 도구로 읽고 처리한다.

---

## 작성 원칙

1. **실행 패턴 명시**: 오케스트레이터 스킬 상단에 어떤 패턴("순차 서브에이전트", "병렬 서브에이전트", "직접 실행", "하이브리드")을 쓰는지 반드시 적는다.
2. **`invoke_subagent` 도구 호출로 위임**: 서브에이전트 호출이 텍스트(예: @analyst)가 아닌, Antigravity CLI의 `invoke_subagent` 도구 실행임을 규정한다.
3. **고유 절대 경로 지정**: 에이전트 간 산출물이 엉키거나 덮어써지지 않도록 `_workspace/` 하위에 에이전트 이름이 들어간 고유 파일명을 설정한다.
4. **에러 폴백 설계**: 현실적인 실행 실패 및 복구 수단을 에러 핸들링 섹션에 기재한다.
5. **description 내 후속 제어 키워드 필수 반영**: 스킬이 1회용으로 사장되지 않도록 "재실행, 다시 실행, 수정, 업데이트, 보완" 등의 키워드를 description에 확실히 담는다.
6. **에러 핸들링은 현실적으로** — "모든 것이 성공한다"고 가정하지 않는다.
7. **테스트 시나리오 필수** — 정상 흐름 1개 + 에러 흐름 1개 이상 기술한다.

## description 작성 시 후속 작업 키워드

오케스트레이터 description은 초기 실행 키워드만으로는 부족하다. 다음 후속 작업 표현을 반드시 포함하라:

- 재실행/다시 실행/업데이트/수정/보완
- "{도메인}의 {부분}만 다시"
- "이전 결과 기반으로", "결과 개선"
- 도메인 관련 일상적 요청 (예: 런치 전략 하네스라면 "런치", "홍보", "트렌딩" 등)

후속 키워드가 없으면 첫 실행 후 하네스가 사실상 죽은 코드가 된다.

## 실제 오케스트레이터 참고

병렬 서브에이전트 패턴의 오케스트레이터 기본 구조:
준비 → Phase 0(컨텍스트 확인) → invoke_subagent 병렬 호출 → 결과 수집 → 통합 → 정리.
`rules/team-examples.md`의 리서치 팀 예시를 참조.