orchestrate

# /orchestrate - Agent Teams 기반 병렬 오케스트레이션 (v6)

v5의 worktree 기반 병렬 실행을 **Agent Teams API**로 대체.
TeamCreate, TaskCreate, SendMessage 등을 활용한 네이티브 팀 조율.

## 전제조건 (CRITICAL)

Agent Teams는 **실험적 기능**이며 기본 비활성화 상태이다.
반드시 아래 환경변수를 설정해야 /orchestrate가 동작한다:

```json
// settings.json (프로젝트 또는 글로벌)
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}
```

미설정 시 TeamCreate 등 팀 관련 도구가 사용 불가하다.

### 토큰 비용 경고

Agent Teams는 단일 세션보다 **훨씬 더 많은 토큰**을 사용한다.
각 팀원은 자신의 컨텍스트 윈도우를 가지며, 토큰 사용은 활성 팀원 수에 비례하여 증가한다.

- 연구, 검토, 새 기능 작업 → 추가 토큰의 가치가 있음
- 일상적 작업 → 단일 세션이 더 비용 효율적

## v5 대비 변경사항

| v5 | v6 |
|----|-----|
| git worktree 기반 병렬 | Agent Teams API (TeamCreate, TaskCreate, SendMessage) |
| 파일 시스템 분리 | 태스크 목록 기반 조율 |
| worktree 생성/정리 필요 | 자동 팀 라이프사이클 관리 |
| --effort 플래그 | 제거 (불필요한 복잡성) |
| --graph, --status 플래그 | --status 제거 (TaskList로 대체) |
| --milestone 플래그 | 제거 (task 필터링으로 대체) |

## 0단계: 파라미터 파싱

$ARGUMENTS에서 플래그를 추출한다:

| 플래그 | 기본값 | 설명 |
|--------|--------|------|
| `--dry-run` | false | 실행하지 않고 계획만 출력 |
| `--type` | auto | `feature` / `bugfix` / `refactor` / `review` |
| `--parallel` | 3 | 동시 팀원 수 상한 (최대 3) |

파싱 규칙:
- `--type`이 없으면 prompt_plan.md 키워드로 자동 감지한다.
- `--parallel`은 최대 3 (Agent Teams 제한: 리더 1 + 팀원 최대 3).

## 1단계: 프로젝트 도메인 감지

프로젝트 루트에서 설정 파일을 탐색하여 도메인을 결정한다.

```
탐색 순서 (첫 매칭 우선):
  package.json          → Node.js / TypeScript
  go.mod                → Go
  requirements.txt      → Python
  pyproject.toml        → Python
  Cargo.toml            → Rust
  Makefile (단독)       → Make-based
  *.sln / *.csproj      → .NET
```

감지 결과를 기반으로 도메인별 명령을 설정한다:

| 도메인 | 빌드 명령 | 테스트 명령 | 린트 명령 |
|--------|-----------|------------|-----------|
| Node.js/TS | `pnpm build` | `pnpm test` | `pnpm lint` |
| Go | `go build ./...` | `go test ./...` | `golangci-lint run` |
| Python | `python -m build` | `pytest` | `ruff check .` |
| Rust | `cargo build` | `cargo test` | `cargo clippy` |
| .NET | `dotnet build` | `dotnet test` | `dotnet format --verify-no-changes` |

도메인 감지에 실패하면 사용자에게 명시적으로 질문한다. 추측하지 않는다.

## 2단계: Task 파싱

`prompt_plan.md`에서 미완료 Task를 추출한다.

```
파싱 대상:
  - [ ] Task 설명 (depends: Task N)          → 미완료
  - [x] Task 설명                             → 완료 (스킵)
```

각 Task에서 추출하는 정보:
- Task 번호 / 이름
- depends 필드 (명시적 의존성)
- 관련 파일 경로 (설명에서 추론)
- 예상 복잡도 (라인 수, 파일 수 기반)

## 3단계: 의존성 분석

4가지 유형의 의존성을 분석한다:

### 명시적 의존성 (depends:)
```
- [ ] Task 3: API 엔드포인트 (depends: Task 1, Task 2)
  → Task 1, Task 2 완료 후 실행
```

### 파일 기반 의존성
```
Task A: src/lib/auth.ts 수정
Task B: src/app/api/login/route.ts 수정 (auth.ts import)
  → Task B는 Task A에 의존
```

### 모듈 기반 의존성
```
Task C: 새 모듈 src/lib/payment/ 생성
Task D: src/app/checkout/ 에서 payment 모듈 사용
  → Task D는 Task C에 의존
```

### 독립 Task
```
위 3가지에 해당하지 않는 Task → 병렬 실행 가능
```

의존성 결과를 DAG(Directed Acyclic Graph)로 구성한다.
순환 의존성이 감지되면 오류를 출력하고 중단한다:

```
[ERROR] 순환 의존성 감지:
  Task 3 → Task 5 → Task 3

해결 방법:
  prompt_plan.md에서 depends 필드를 수정하세요.
```

## 4단계: Type별 팀 구성

### Type 자동 감지 (--type 미지정 시)

prompt_plan.md 키워드 분석:
- `새 기능`, `구현`, `추가`, `feature` → `feature`
- `버그`, `수정`, `fix`, `hotfix` → `bugfix`
- `리팩토링`, `정리`, `마이그레이션`, `refactor` → `refactor`
- `리뷰`, `검토`, `분석`, `review` → `review`

### Type별 팀 구성

**feature** (팀원 3명):

| 역할 | subagent_type | 모델 | 담당 |
|------|--------------|------|------|
| Implementer 1 | general-purpose | sonnet | 핵심 기능 구현 |
| Implementer 2 | general-purpose | sonnet | 보조 기능 구현 |
| Tester | general-purpose | sonnet | 테스트 작성 + 리뷰 |

**bugfix** (팀원 2명):

| 역할 | subagent_type | 모델 | 담당 |
|------|--------------|------|------|
| Investigator | Explore | sonnet | 버그 원인 분석 |
| Fixer | general-purpose | sonnet | 수정 + 테스트 |

**refactor** (팀원 3명):

| 역할 | subagent_type | 모델 | 담당 |
|------|--------------|------|------|
| Analyzer | Explore | sonnet | 코드 분석 + 계획 |
| Implementer | general-purpose | sonnet | 리팩토링 실행 |
| Verifier | general-purpose | sonnet | 테스트 + 검증 |

**review** (팀원 3명):

| 역할 | subagent_type | 모델 | 담당 |
|------|--------------|------|------|
| Security Reviewer | Explore | sonnet | 보안 분석 |
| Performance Reviewer | Explore | sonnet | 성능 분석 |
| Quality Reviewer | Explore | sonnet | 코드 품질 분석 |

## 5단계: Wave 그룹화

의존성 DAG를 기반으로 Task를 Wave(동시 실행 그룹)로 나눈다.

```
Wave 1: [Task 1, Task 2, Task 4]     ← 의존성 없음, 병렬 실행
Wave 2: [Task 3]                      ← Task 1, 2에 의존
Wave 3: [Task 5, Task 6]             ← Task 3, 4에 의존
```

Wave별 제약:
- 동시 팀원 수는 `--parallel` 값 이하로 유지한다 (최대 3).
- 같은 파일을 수정하는 Task는 같은 Wave에 배치하지 않는다.
- Wave 내 Task 수가 `--parallel`을 초과하면 sub-wave로 분할한다.

## 6단계: 실행 모드

### --dry-run 모드

계획만 출력하고 실행하지 않는다:

```
════════════════════════════════════════════════════════════════
  Orchestration Engine v6 (type: feature)
  Agent Teams API
════════════════════════════════════════════════════════════════

  Domain: Node.js/TypeScript (pnpm)
  Tasks: 6 pending, 2 completed
  Waves: 3
  Team: Implementer 1 + Implementer 2 + Tester

Wave 1 (parallel: 3)
  Task 1: 인증 모듈 구현       → Implementer 1
  Task 2: DB 스키마 설정        → Implementer 2
  Task 4: 설정 파일 생성        → Tester (구현 겸)

Wave 2 (parallel: 1)
  Task 3: API 엔드포인트        → Implementer 1

Wave 3 (parallel: 2)
  Task 5: 프론트 연동           → Implementer 1
  Task 6: E2E 테스트            → Tester

════════════════════════════════════════════════════════════════

다음 단계:
  --dry-run 제거하고 다시 실행하면 Wave 1부터 시작합니다.
════════════════════════════════════════════════════════════════
```

### 실행 모드 (기본)

Agent Teams API를 사용하여 실제 실행한다:

**Step 1: 팀 생성**
```
TeamCreate → 팀 생성
```

**Step 2: 태스크 생성 (의존성 포함)**
```
TaskCreate → Wave 1 태스크들 (blockedBy 없음)
TaskCreate → Wave 2 태스크들 (blockedBy: Wave 1 태스크)
TaskCreate → Wave 3 태스크들 (blockedBy: Wave 2 태스크)
```

**Step 3: 팀원 생성 (Task 도구)**
```
Task → Implementer 1 (general-purpose, sonnet)
Task → Implementer 2 (general-purpose, sonnet)
Task → Tester (general-purpose, sonnet)
```

**Step 4: 태스크 배정**
```
TaskUpdate → Task 1 owner: Implementer 1
TaskUpdate → Task 2 owner: Implementer 2
TaskUpdate → Task 4 owner: Tester
```

**Step 5: 팀원 작업 수행**

각 팀원은:
1. TaskList로 자신의