/orchestrate

allowed-tools: Bash(git:*), Read, Write, Glob, Grep, Task, TeamCreate, TaskCreate, TaskUpdate, TaskList, SendMessage
description: Agent Teams 기반 병렬 오케스트레이션 (v6)
argument-hint: [--type feature|bugfix|refactor|review] [--parallel N] [--dry-run]

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

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

전제조건 (CRITICAL)

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

// 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-