# 프로젝트 킥오프 오케스트레이터 설계서

**task_id**: task-198.1
**작성일**: 2026-03-03
**작성자**: 헤르메스 (개발1팀장)
**상태**: Phase 1 완료 (설계서)

---

## 1. 기존 스킬 분석

### 1.1 agent-meeting (Agent 미팅)

**역할**: 여러 페르소나를 소집해 전문 의견을 수집하고, 보리스 워크플로우(Annotation Cycle)를 통해 합의에 도달한 뒤 결과를 기록한다.

**입력**:
- 미팅 주제 (한 문장으로 명확히 정의)
- 선행 리서치 결과 (`memory/research/` 확인 필수)
- 소집할 페르소나 목록 (조직도 기반 선택)

**출력**:
- 미팅 기록: `memory/meetings/YYYY-MM-DD-<주제-kebab-case>.md`
- 최종 합의 사항 (번호 매기기)
- 미해결 항목 목록
- 다음 단계 제안 (3문서 반영 방법)

**한계**:
- 최대 6사이클로 제한, 초과 시 강제 종료
- 리서치 없이 소집 금지 (리서치 선행 의존성)
- 아누(개발실장)가 직접 실행해야 함 — 팀장이 직접 소집할 수 없음
- 미팅 결과를 3문서에 자동 반영하는 메커니즘 없음 (수동 반영 필요)

### 1.2 3docs-create (3문서 자동 생성)

**역할**: 계획서/맥락노트/체크리스트 3개 파일의 빈 템플릿을 생성한다.

**입력**:
- `task_id` (명시적 제공 또는 task-timer에서 자동 감지)
- `project_name` (kebab-case)

**출력**:
- `memory/plans/<project_name>/plan.md` (계획서 템플릿)
- `memory/plans/<project_name>/context-notes.md` (맥락노트 템플릿)
- `memory/plans/<project_name>/checklist.md` (체크리스트 템플릿)
- 모든 내용 필드는 `[TODO]`로 비워둠

**한계**:
- 빈 템플릿만 생성 — [TODO] 항목은 별도로 채워야 함
- 미팅 결과를 자동으로 반영하는 기능 없음
- 스키마 참조: `memory/specs/3docs-schema.md` 준수 필요
- 기존 디렉토리 존재 시 사용자 확인 필요 (덮어쓰기 방지)

### 1.3 nuclear-approval (핵미사일 발사코드)

**역할**: 3문서 검증 → Context Purge 제안 → 제이회장님 승인 요청 → 승인 후 실행 시작.

**입력**:
- 프로젝트의 3문서 경로 (plan.md, context-notes.md, checklist.md)

**출력**:
- 3문서 유효성 검증 결과 (YAML 프론트매터, 근거 확인)
- Context Purge 제안 메시지
- 제이회장님 승인 요청 메시지 (핵심 계획 요약 포함)
- 승인 시: task-timer start + 팀 dispatch

**한계**:
- 3문서가 모두 존재하고 유효해야만 진행 가능
- 근거 없는 판단이 계획서에 있으면 즉시 중단
- 승인/거부는 제이회장님의 수동 응답에 의존
- 승인 후 dispatch 대상 팀 정보가 계획서에 명시되어 있어야 함

---

## 2. 전체 Phase 흐름도

아누 가이드 Section 2.3의 Phase 분리 원칙에 따라, 프로젝트 킥오프는 4개 Phase로 구성된다.

```
Phase 0: 리서치
  ┃  입력: 제이회장님 지시 (주제/요구사항)
  ┃  출력: memory/research/<topic>.md
  ┃  실행: 아누 직접 또는 팀 dispatch
  ┃  종료조건: 리서치 파일 저장 + .done 이벤트
  ┃
  ┃  ▼ [아누 검토 + 제이회장님 보고]
  ┃
Phase 1: Agent 미팅
  ┃  입력: Phase 0 리서치 결과 경로
  ┃  출력: memory/meetings/YYYY-MM-DD-<topic>.md
  ┃  실행: 아누가 /agent-meeting 스킬 호출
  ┃  종료조건: 합의 도달 (또는 6사이클 강제 종료) + .done 이벤트
  ┃
  ┃  ▼ [아누 검토, 추가 사이클 필요 시 Phase 1 반복]
  ┃
Phase 2: 3문서 작성
  ┃  입력: Phase 1 미팅 합의 결과 경로
  ┃  출력: memory/plans/<project>/plan.md
  ┃         memory/plans/<project>/context-notes.md
  ┃         memory/plans/<project>/checklist.md
  ┃  실행: 아누가 /3docs-create 호출 후 [TODO] 채움
  ┃  종료조건: 3문서 완성 (모든 [TODO] 해소) + .done 이벤트
  ┃
  ┃  ▼ [아누 검토]
  ┃
Phase 3: 핵미사일 발사코드 (승인)
  ┃  입력: Phase 2에서 완성된 3문서 경로
  ┃  출력: 제이회장님 승인 결과
  ┃  실행: 아누가 /nuclear-approval 스킬 호출
  ┃  종료조건: 승인 완료 → task-timer start + 코딩 Phase dispatch
  ┃
  ┃  ▼ [승인 후]
  ┃
Phase 4~N: 코딩 (이 설계서 범위 밖)
     체크리스트 기반 순차 구현
```

---

## 3. 각 Phase에서 호출할 기존 스킬 매핑

### Phase 0: 리서치
- **기존 스킬**: 없음 (전용 스킬 미존재)
- **실행 방식**: 아누가 직접 리서치하거나, Task tool을 통해 팀원 소집
- **도구**: WebSearch, WebFetch, Read, Grep 등 탐색 도구
- **규약**: 아누 가이드 Section 2.5 (리서치 단계) 준수

### Phase 1: Agent 미팅
- **기존 스킬**: `/agent-meeting` (agent-meeting/SKILL.md)
- **호출 주체**: 아누
- **입력 바인딩**: Phase 0 리서치 결과 경로를 미팅 안건 배경에 인용
- **추가 규약**: 보리스 워크플로우 최대 6사이클

### Phase 2: 3문서 작성
- **기존 스킬**: `/3docs-create` (3docs-create/SKILL.md)
- **호출 주체**: 아누
- **입력 바인딩**: Phase 1 미팅 합의 결과를 기반으로 [TODO] 항목 채움
- **추가 작업**: 템플릿 생성 후 아누가 미팅 결과를 참조하여 내용 작성

### Phase 3: 핵미사일 발사코드
- **기존 스킬**: `/nuclear-approval` (nuclear-approval/SKILL.md)
- **호출 주체**: 아누
- **입력 바인딩**: Phase 2에서 완성된 3문서 경로
- **후속 처리**: 승인 시 dispatch.py로 코딩 팀에 위임

---

## 4. Phase 간 연결 방식 (파일 기반 상태 전달)

아누 가이드 Section 2.3 규칙 2: "Phase 간 연결 = 파일"

### 4.1 Phase 간 전달 파일 맵

```
Phase 0 → Phase 1:
  전달 파일: memory/research/<topic>.md
  전달 방식: Phase 1 미팅 안건에 리서치 파일 경로를 명시적으로 인용
  검증: 파일 존재 여부 확인

Phase 1 → Phase 2:
  전달 파일: memory/meetings/YYYY-MM-DD-<topic>.md
  전달 방식: 3문서 작성 시 미팅 기록의 "최종 합의 사항"과 "미해결 항목"을 참조
  검증: 미팅 기록에 "최종 합의 사항" 섹션 존재 확인

Phase 2 → Phase 3:
  전달 파일:
    - memory/plans/<project>/plan.md
    - memory/plans/<project>/context-notes.md
    - memory/plans/<project>/checklist.md
  전달 방식: /nuclear-approval 스킬이 직접 3문서 경로를 확인
  검증: YAML 프론트매터 유효성 + 근거 인용 확인 (nuclear-approval STEP 1)

Phase 3 → Phase 4:
  전달 파일: 3문서 전체 (변경 없음)
  전달 방식: dispatch.py --task-file로 작업 지시 전달 시 3문서 경로 포함
  검증: 제이회장님 승인 완료 확인
```

### 4.2 Phase 상태 추적 파일

각 Phase 완료 시 이벤트 파일로 상태를 기록한다:

```
memory/events/<task_id>-phase0.done   → Phase 0 리서치 완료
memory/events/<task_id>-phase1.done   → Phase 1 미팅 완료
memory/events/<task_id>-phase2.done   → Phase 2 3문서 완성
memory/events/<task_id>-phase3.done   → Phase 3 승인 완료
```

### 4.3 오케스트레이터 상태 파일

전체 흐름의 현재 상태를 추적하는 메타파일:

```
memory/kickoff/<project>/kickoff-state.json
```

```json
{
  "project": "<project_name>",
  "task_id": "<root_task_id>",
  "current_phase": 0,
  "phases": {
    "0": {
      "status": "completed",
      "output": "memory/research/<topic>.md",
      "completed_at": "2026-03-03T12:00:00"
    },
    "1": {
      "status": "in_progress",
      "output": null,
      "started_at": "2026-03-03T13:00:00"
    },
    "2": { "status": "pending" },
    "3": { "status": "pending" }
  },
  "approval_points": {
    "phase0_review": { "status": "approved", "by": "anu", "at": "..." },
    "phase2_review": { "status": "pending" },
    "phase3_approval": { "status": "pending", "by": "jay" }
  }
}
```

---

## 5. 제이회장님 확인/승인 포인트 정의

### 5.1 승인 포인트 요약

```
[보고] Phase 0 완료 → 아누가 리서치 결과를 제이회장님께 보고
  └─ 유형: 보고 (정보 전달, 명시적 승인 불필요)
  └─ 조건: 제이회장님이 방향 수정을 지시하면 Phase 0 재실행

[보고] Phase 1 완료 → 아누가 미팅 합의 결과를 제이회장님께 보고
  └─ 유형: 보고 (정보 전달)
  └─ 조건: 추가 미팅 사이클 필요 시 제이회장님 판단

[승인] Phase 3 실행 → 핵미사일 발사코드 = 제이회장님 명시적 승인 필수
  └─ 유형: 강제 승인 (DON'T IMPLEMENT YET 해제)
  └─ 조건: 3문서 확인 + "위 계획대로 구현을 시작해도 되겠습니까?" 질문
  └─ 거부 시: Phase 2로 되돌아가 3문서 수정
```

### 5.2 승인 흐름 상세

```
Phase 0 완료
  → 아누: "리서치 완료. [요약]. 미팅 진행해도 되겠습니까?"
  → 제이회장님: 방향 확인 또는 수정 지시
  → (수정 시 Phase 0 재실행, 확인 시 Phase 1 진행)

Phase 1 완료
  → 아누: "미팅 [N]사이클 완료. 합의 사항: [요약]. 3문서 작성 진행합니다."
  → 제이회장님: 확인 (보고 수준, 특별 이견 없으면 자동 진행)

Phase 3 (핵미사일)
  → 아누: 핵미사일 발사코드 형식으로 승인 요청
  → 제이회장님: 승인/거부 (명시적 응답 필수)
  → 승인 시: task-timer start + 코딩 dispatch
```

---

## 6. 세션 끊기/이어가기 방법

### 6.1 원칙

아누 가이드 Section 2.3 규칙 1: "1 Phase = 1 세션(dispatch)"

각 Phase는 독립된 세션에서 실행되며, Phase 완료 시:
1. 산출물을 파일로 저장
2. .done 이벤트 파일 생성
3. 아누에게 완료 통보 (cokacdir --cron)
4. 아누가 검토 후 다음 Phase를 dispatch

### 6.2 dispatch 메커니즘 (2가지 방식)

#### 방식 A: 수동 dispatch (아누 주도)

아누가 각 Phase 완료를 확인하고, 수동으로 다음 Phase를 시작한다.

```
Phase 0 완료
  → .done 이벤트 → 아누 확인
  → 아누가 새 세션에서 /agent-meeting 호출 (Phase 1 시작)

Phase 1 완료
  → .done 이벤트 → 아누 확인
  → 아누가 새 세션에서 /3docs-create 호출 (Phase 2 시작)

Phase 2 완료
  → .done 이벤트 → 아누 확인
  → 아누가 새 세션에서 /nuclear-approval 호출 (Phase 3 시작)

Phase 3 승인
  → dispatch.py로 코딩 팀에 위임 (Phase 4 시작)
```

장점: 아누가 각 Phase 사이에 개입하여 방향 수정 가능
단점: 수동 개입 필요, 지연 발생 가능

#### 방식 B: chain.py 자동 체이닝

chain.py를 활용하여 Phase 완료 시 자동으로 다음 Phase를 dispatch한다.

```bash
# 킥오프 체인 생성
python3 chain.py create --id <project>-kickoff --desc "프로젝트 킥오프"

# Phase 0 추가 (리서치)
python3 chain.py add-phase --chain <project>-kickoff --name "Phase 0: 리서치" \
  --tasks '[{"team":"dev1-team","desc":"리서치 수행","level":"normal"}]'

# Phase 1 추가 (미팅) — 주의: 아누가 직접 수행해야 하므로 자동화 제한
# Phase 2 추가 (3문서)
# Phase 3 추가 (승인)
```

장점: Phase 전환 자동화, 중간 보고 자동 발송
단점: Phase 1~3은 아누/제이회장님 개입이 필수이므로 완전 자동화 불가

#### 권장: 하이브리드 방식

```
Phase 0: chain.py 자동 (리서치는 팀 dispatch 가능)
  ↓ 자동 통보 → 아누 검토
Phase 1: 아누 수동 (미팅은 아누가 직접 주도)
  ↓ 아누 판단 후 수동 진행
Phase 2: 아누 수동 (/3docs-create 호출 + [TODO] 채움)
  ↓ 아누 완료 후 수동 진행
Phase 3: 아누 수동 (/nuclear-approval → 제이회장님 승인)
  ↓ 승인 후 dispatch.py/chain.py 자동
Phase 4~N: chain.py 자동 (코딩은 팀 dispatch)
```

### 6.3 세션 간 컨텍스트 전달 템플릿

각 Phase 시작 시 아누가 새 세션에 전달할 컨텍스트:

```
## Phase [N] 시작 컨텍스트

**프로젝트**: <project_name>
**현재 Phase**: Phase [N] - [Phase 이름]
**이전 Phase 산출물**:
- [이전 Phase 출력 파일 경로 1]
- [이전 Phase 출력 파일 경로 2]

**킥오프 상태**: memory/kickoff/<project>/kickoff-state.json
**참조 문서**: memory/specs/project-kickoff-design.md
```

---

## 7. 기존 스킬 수정 필요 사항

### 7.1 agent-meeting 수정 사항

**수정 필요도**: 낮음 (선택적 개선)

1. **Phase 컨텍스트 인식** (선택):
   - 미팅 소집 시 `kickoff-state.json`을 참조하여 현재 어떤 Phase에서 호출되었는지 인식
   - 리서치 파일 경로를 자동으로 미팅 배경에 포함

2. **미팅 결과 → 3문서 매핑 가이드 추가** (권장):
   - "다음 단계" 섹션에 합의 사항이 3문서의 어떤 섹션에 대응하는지 매핑 가이드 추가
   - 예: "합의 사항 1 → 계획서 '범위/포함'에 반영"

### 7.2 3docs-create 수정 사항

**수정 필요도**: 중간

1. **미팅 결과 자동 참조** (권장):
   - 새 파라미터: `--meeting <meeting_file_path>`
   - 미팅 기록을 읽어 [TODO] 항목에 힌트를 추가 (자동 채움은 아님, 환각 방지)
   - 예: 계획서의 "목표" [TODO] 옆에 `<!-- 미팅 합의 #1 참조 -->` 주석 삽입

2. **킥오프 상태 자동 업데이트** (선택):
   - 3문서 생성 완료 시 `kickoff-state.json`의 Phase 2 상태를 자동 업데이트

### 7.3 nuclear-approval 수정 사항

**수정 필요도**: 낮음

1. **킥오프 상태 업데이트** (선택):
   - 승인 완료 시 `kickoff-state.json`의 Phase 3 상태를 `completed`로 업데이트

2. **dispatch 대상 자동 결정** (권장):
   - 계획서의 "위임 계획" 섹션을 파싱하여 dispatch.py 호출 시 팀 ID를 자동 결정
   - 현재는 아누가 수동으로 팀을 지정해야 함

### 7.4 신규 필요 요소

1. **project-kickoff 오케스트레이터 스킬** (Phase 2에서 구현):
   - `/project-kickoff <topic>` 명령으로 전체 흐름 시작
   - `kickoff-state.json` 생성 및 관리
   - Phase 전환 로직 (현재 Phase 확인 → 다음 Phase 안내)

2. **kickoff-state.json 관리 유틸리티**:
   - 상태 조회: `python3 kickoff.py status --project <name>`
   - Phase 완료 마킹: `python3 kickoff.py phase-done --project <name> --phase 0`
   - 전체 흐름 초기화: `python3 kickoff.py init --project <name> --task <task_id>`

---

## 8. 위험 요소 및 대응

### 8.1 컨텍스트 유실 위험
- **위험**: Phase 간 세션이 분리되므로 이전 Phase의 논의 맥락이 유실될 수 있음
- **대응**: 맥락노트(context-notes.md)에 모든 결정 근거를 기록. kickoff-state.json에 산출물 경로 추적

### 8.2 Phase 순서 위반 위험
- **위험**: 리서치 없이 미팅 소집, 3문서 없이 승인 요청 등
- **대응**: 각 Phase 시작 시 이전 Phase의 .done 파일 존재 확인. nuclear-approval은 이미 3문서 검증 게이트 내장

### 8.3 환각 위험
- **위험**: 3문서 [TODO] 항목을 근거 없이 채우는 것
- **대응**: 아누 가이드 환각 방지 게이트 준수. 모든 결정에 근거(코드 위치, 문서, 미팅 기록) 인용 필수

---

## 9. 구현 로드맵 (이후 Phase 참조용)

### Phase 2 (다음 작업): 오케스트레이터 스킬 구현
- `skills/project-kickoff/SKILL.md` 작성
- `kickoff.py` 유틸리티 스크립트 구현
- `kickoff-state.json` 스키마 정의
- 기존 스킬 수정 (7.1~7.3)

### Phase 3: 통합 테스트
- 실제 프로젝트로 Phase 0~3 전체 흐름 테스트
- 세션 끊기/이어가기 검증
- 승인 포인트 동작 확인

---

**문서 버전**: v1.0
**참조**: 아누 가이드 v1.1, agent-meeting SKILL.md, 3docs-create SKILL.md, nuclear-approval SKILL.md, dispatch.py, chain.py