---
name: milestone-runner
description: master_roadmap.md의 마일스톤 하나(M1~M9, M2a/M2b, M8a/M8b/M8.5 포함)를 선택하면 content-design → balance-design → data-generation → dev-spec 4개 페이즈를 체크포인트 기반으로 순차 진행한다. 각 페이즈 종료 시 사용자 승인을 받고, Docs/milestone-runs/에 상태를 기록하여 중단/재개를 지원한다. 다중 산출물 계획과 페이즈 스킵을 허용한다.
---

Recommended Model : Claude Opus
** 한국어 스타일 유지 **

## 언제 사용하나요?

- 사용자의 명시적 호출(`/milestone-runner`)에 의해서만 사용한다
- 로드맵의 마일스톤 하나를 착수할 때 진입점으로 사용한다
- 여러 스킬(content-designer, balance-designer, data-generator, spec-writer)을 순서대로 거쳐야 하는 경우에 사용한다

## 입력 형식

```
/milestone-runner {마일스톤} [--resume] [--phase {번호}]
```

- `{마일스톤}` (필수): `M1`, `M2a`, `M2b`, `M3`, `M4`, `M5`, `M6`, `M7`, `M8a`, `M8b`, `M8.5`, `M9` 중 하나
- `--resume` (선택): 기존 상태 파일을 읽어 중단된 지점에서 재개
- `--phase {번호}` (선택): 특정 페이즈 번호로 점프 (1~4). 체크포인트는 유지된다

호출 예:
- 신규 시작: `/milestone-runner M1`
- 재개: `/milestone-runner M1 --resume`
- 특정 페이즈부터: `/milestone-runner M1 --phase 3`
- 신규 후속 마일스톤 시작: `/milestone-runner M8a`
- 후속 마일스톤 재개: `/milestone-runner M8a --resume`

## 4개 페이즈 구조

| 페이즈 | 이름 | 사용 스킬 | 산출물 디렉토리 |
|--------|------|----------|----------------|
| 1 | 컨텐츠 설계 | content-designer | `Docs/content-design/` |
| 2 | 밸런스 확정 | balance-designer | `Docs/balance-design/` |
| 3 | 데이터 생성 | data-generator | `Docs/content-data/` |
| 4 | 개발 명세 | spec-writer | `Docs/spec/` |

**핵심 원칙:**
- 각 페이즈 종료 시 **사용자 승인 체크포인트**에서 멈춘다. 자동으로 다음 페이즈로 넘어가지 않는다
- 마일스톤에 따라 일부 페이즈는 스킵 가능 (예: M5는 페이즈 3 불필요)
- 한 페이즈 내 다중 산출물을 허용하며, 의존 관계/순서를 권장한다
- child 스킬을 **직접 호출하지 않는다.** 사용자에게 실행할 명령어를 안내하고, 사용자가 `--resume`으로 돌아오도록 유도한다

## 상태 파일

**위치**: `Docs/milestone-runs/{마일스톤}/state.md`

**형식 (마크다운 + 체크리스트):**

```markdown
# {마일스톤} 실행 상태

> 시작: {ISO timestamp}
> 마지막 업데이트: {ISO timestamp}
> 현재 페이즈: {N}
> 상태: {planned | in_progress | completed | paused}

## 로드맵 요구사항 요약

{roadmap에서 추출한 이 마일스톤의 핵심 요구사항 3~5줄}

## 페이즈 1: 컨텐츠 설계

**상태**: pending | in_progress | completed | skipped

계획된 산출물:
- [ ] 1. {주제} — 권장 주제
  - 참고 문서: {추천 참고 문서}
  - 산출물: (미생성)
- [x] 2. {주제}
  - 산출물: Docs/content-design/[content]20260417_xxx.md
  - 완료: {ISO timestamp}

## 페이즈 2: 밸런스 확정

(동일 형식)

## 페이즈 3: 데이터 생성

**상태**: ...

계획된 산출물:
- [ ] 1. {타입} × {수량} — data-generator 호출
  - 입력 기획서: {페이즈 1/2의 산출물 경로}
  - 대상 테이블: {테이블명}
  - 산출물: (미생성)

## 페이즈 4: 개발 명세

(동일 형식)

## 실행 이력

- {timestamp}: 마일스톤 시작
- {timestamp}: 페이즈 1 계획 승인
- {timestamp}: "주제A" 완료 (Docs/content-design/...)
- ...
```

상태 파일은 **사람도 읽을 수 있는 마크다운**으로 유지한다. 기계 파싱은 체크리스트(`- [x]` / `- [ ]`)와 섹션 헤더로 수행한다.

## 수행 절차

### 0단계: 모드 판별

- `Docs/milestone-runs/{마일스톤}/state.md` 파일 존재 여부 확인
- `--resume` 있고 상태 파일 존재 → **재개 모드** (5단계로 이동)
- `--resume` 있는데 상태 파일 없음 → 에러 보고 후 중단
- `--resume` 없고 상태 파일 **이미 존재** → 사용자에게 확인 요청 (덮어쓸지 / 재개할지 / 중단할지)
- 그 외 → **신규 시작 모드** (1단계로 진행)

### 1단계: 컨텍스트 로딩 및 요구사항 추출

Read로 다음을 읽는다:
1. `Docs/roadmap/master_roadmap.md` — **해당 마일스톤 섹션만** 집중 분석
2. `Docs/milestone-runs/{이전 마일스톤}/state.md` — 선행 마일스톤 완료 상태와 후속 연결
3. `Docs/game_overview.md` — 게임 전반 톤
4. `Docs/content_status.md` — 보관본일 수 있으므로 최신성 표시를 확인하고 보조 참고로만 사용

해당 마일스톤 섹션에서 추출할 항목:
- 마일스톤 테마/목표
- 포함될 시스템 목록
- 종료 조건 (누적 플레이 기준 + 완료 체크리스트)
- 선행 의존성 (다른 마일스톤 결과물)
- 스키마 확장 여부

추출 결과를 사용자에게 요약 보고한다.

### 2단계: 4개 페이즈별 산출물 계획 제안

roadmap의 해당 마일스톤 섹션을 기반으로 각 페이즈의 권장 산출물 목록을 제안한다.

**페이즈별 권장 항목 추출 규칙:**

| 페이즈 | roadmap에서 찾을 항목 | 산출물 생성 가이드 |
|--------|---------------------|-----------------|
| 1 (컨텐츠) | "기획 참고 문서", "컨텐츠 설계 대상" 섹션 | 독립적 기획 주제별로 1개씩 분리 |
| 2 (밸런스) | "수치", "경제 영향", "밸런스 체크포인트" 언급 | 수치 영역별로 1개씩 분리 |
| 3 (데이터) | 컨텐츠 밀도 기준표, 데이터 채우기 언급 | 지원되는 data-generator 타입만 포함 |
| 4 (개발 명세) | "구현 대상 시스템", 코드 변경 설명 | 독립적 시스템별로 1개씩 분리 |

**산출물 간 의존 관계/순서를 명시**한다. 예:
```
페이즈 3 산출물 1 → 입력: 페이즈 1 산출물 2 + 페이즈 2 산출물 1
```

**페이즈 스킵이 가능한 경우** 사용자에게 명시한다:
```
페이즈 3: 이 마일스톤은 벌크 데이터 생성이 불필요하여 스킵 권장
```

제안 후 사용자 승인:
```
## 제안하는 산출물 계획

### 페이즈 1: 컨텐츠 설계 (N개)
1. ...
2. ...

### 페이즈 2: 밸런스 확정 (N개)
1. ...

### 페이즈 3: 데이터 생성 (N개) [스킵 가능]
1. ...

### 페이즈 4: 개발 명세 (N개)
1. ...

### 페이즈 간 의존
- 페이즈 3 항목 1 → 페이즈 1 항목 2 + 페이즈 2 항목 1 필요
- 페이즈 4 항목 2 → 페이즈 1 항목 1 + 페이즈 2 항목 2 필요

이 계획으로 진행할까요?
- (y) 승인, 상태 파일 생성 후 페이즈 1 시작
- (수정 내용) 추가/제거/순서 변경 요청
- (n) 중단
```

### 3단계: 상태 파일 생성

- `Docs/milestone-runs/{마일스톤}/` 디렉토리 생성 (이미 있으면 확인)
- 승인된 계획을 바탕으로 `state.md` 작성
- 현재 페이즈: 1
- 모든 산출물: `pending`
- 실행 이력에 "마일스톤 시작" + "계획 승인" 기록

### 4단계: 페이즈 시작 안내

현재 페이즈(기본 1)의 **첫 번째 pending 산출물**에 대한 액션을 사용자에게 안내한다.

```
## 페이즈 {N}: {페이즈 이름} 시작

**현재 액션: {페이즈 내 순서}/{총개수}**

주제: {산출물 주제}
참고 입력: {선행 페이즈 산출물 경로 목록}

실행할 명령어:
`/{해당 스킬} {인자}`

예상 산출물 경로: `Docs/{디렉토리}/[{접두사}]{날짜}_{슬러그}.md`

해당 스킬이 산출물을 생성하면 아래 명령어로 돌아오세요:
`/milestone-runner {마일스톤} --resume`
```

페이즈별 명령어 템플릿:

| 페이즈 | 추천 호출 형식 |
|--------|--------------|
| 1 | `/content-designer` (인자로 주제 전달) |
| 2 | `/balance-designer` (인자로 분석 대상 전달) |
| 3 | `/data-generator {타입} --brief @{기획서 경로}` |
| 4 | `/spec-writer @{기획서 경로}` |

**milestone-runner는 여기서 종료한다.** child 스킬은 사용자가 직접 실행한다.

### 5단계: 재개 모드 (`--resume`)

1. `state.md`를 Read
2. 현재 페이즈, 완료 체크 목록, 계획된 산출물 파악
3. 해당 페이즈의 산출물 디렉토리를 Glob으로 스캔
   - 예: 페이즈 1이면 `Docs/content-design/*.md`
   - 상태 파일의 "마지막 업데이트" 이후 생성/수정된 파일 식별
4. 새 파일을 기존 pending 항목에 매칭 제안:
   ```
   ## 재개 상태 확인

   새로 감지된 산출물:
   - Docs/content-design/[content]20260417_xxx.md

   아래 계획 항목 중 어느 것과 매칭되나요?
   - 1. 세력 패시브 매핑 기획 (pending)
   - 2. 세력 퀘스트 컨셉 (pending)
   - (새 항목으로 추가)
   - (무시)
   ```
5. 사용자 매칭 입력 후 state.md 갱신 (체크 + 경로 + 완료 timestamp)
6. 다음 액션 결정:
   - 현재 페이즈에 pending 항목 남음 → 4단계 스타일로 다음 산출물 안내
   - 모든 pending 완료 → **6단계 (페이즈 종료 체크포인트)**

### 6단계: 페이즈 종료 체크포인트

```
## 페이즈 {N}: {페이즈 이름} 완료

### 생성된 산출물 ({N}개)
- {경로1}
- {경로2}
- ...

### 다음 페이즈 {N+1}: {다음 페이즈 이름} 미리보기

계획된 산출물:
- {주제1}
  - 입력: {의존 산출물 경로}
- {주제2}
- ...

### 진행 결정
- (y) 페이즈 {N+1} 시작
- (skip) 다음 페이즈 스킵 (이 마일스톤에 불필요한 경우)
- (수정) 다음 페이즈 산출물 계획 수정
- (중단) 여기서 중단. 상태 저장됨. 나중에 `--resume`으로 재개 가능
```

- `y`: state.md의 현재 페이즈를 `N+1`로 갱신 후 4단계 실행
- `skip`: 다음 페이즈 상태를 `skipped`로 기록 후 다음 페이즈의 종료 체크포인트로 바로 이동
- `수정`: 계획 수정 후 다시 체크포인트 표시
- `중단`: state.md의 상태를 `paused`로 기록하고 종료. `--resume`으로 재진입 가능

마지막 페이즈(4) 완료 시 → **7단계**로 이동

### 7단계: 마일스톤 완료 보고

```
## {마일스톤} 실행 완료

### 전체 산출물 요약
- 페이즈 1 (컨텐츠 설계): {N}개
  - {경로 목록}
- 페이즈 2 (밸런스): {N}개
  - {경로 목록}
- 페이즈 3 (데이터): {N}개
  - {경로 목록}
- 페이즈 4 (개발 명세): {N}개
  - {경로 목록}

### 다음 단계 권장

페이즈 4에서 생성된 개발 명세서를 구현:
- `/implement-spec @{명세서 경로}` (소규모)
- `/implement-agent @{명세서 경로}` (대규모)

### 상태 파일 최종
`Docs/milestone-runs/{마일스톤}/state.md`에 전체 이력이 기록되었습니다.
상태가 `completed`로 변경되었습니다.
```

## 주의사항

- **child 스킬을 직접 호출하지 않는다.** 각 child는 인터랙티브 Q&A가 많으므로 사용자가 직접 실행해야 한다. milestone-runner는 조율자일 뿐
- **state.md가 진실의 원천이다.** 산출물 경로는 매 재개 시 파일시스템에서 재검증한다
- **roadmap 파싱 실패 시 임의 계획을 생성하지 않는다.** 사용자에게 질문한다
- **체크포인트 없이 페이즈를 건너뛰지 않는다.** `--phase N`으로 명시적 점프한 경우에도 해당 페이즈 시작 시점에 승인을 받는다
- **data-generator 타입 스펙이 없는 컨텐츠는 페이즈 3을 자동 스킵 권장한다.** 예: M2a의 정수·아이템은 `types/essence.md` / `types/item.md`가 아직 없으면 "페이즈 3 실행 전 타입 스펙 작성 필요" 안내
- **여러 사용자가 동시에 상태 파일을 수정하는 경우를 가정하지 않는다.** 단일 사용자 도구
- **자동으로 산출물 계획을 변경하지 않는다.** 재개 시 계획 항목과 매칭되지 않는 신규 파일이 있으면 반드시 사용자에게 확인

## 페이즈 스킵 힌트 (마일스톤별)

각 마일스톤별 페이즈 스킵 권장 사례 (roadmap 기반 추론, 실제 계획은 2단계에서 사용자와 확정):

| 마일스톤 | 페이즈 1 | 페이즈 2 | 페이즈 3 | 페이즈 4 |
|---------|---------|---------|---------|---------|
| M1 | 필수 | 필수 | faction-quest | 필수 |
| M2a | 필수 | 필수 | 타입 스펙 추가 필요 (essence, item) | 필수 |
| M2b | 필수 | 필수 | 타입 스펙 추가 필요 (elite-monster) | 필수 |
| M3 | 필수 | 필수 | 타입 스펙 추가 필요 (linked-quest, narrative) | 필수 |
| M4 | 필수 | 필수 | 타입 스펙 추가 필요 (faction-facility, faction-shop) | 필수 |
| M5 | 필수 | 필수 | 스킵 권장 (시스템 중심) | 필수 |
| M6 | 간단 | 필수 (전체 재조정) | 모든 기존 타입 활용 | 간단 (stub 연결) |
| M7 | 필수 | 필수 | 일부 타입 스펙 부재 시 SQL/수동 데이터 생성 병행 | 필수 |
| M8a | 필수 | 필수 | 전투 보고서 템플릿/세력 데이터 생성 필요 | 필수 |
| M8b | 필수 | 필수 | 적 유형/스킬/상태 효과 데이터 생성 필요 | 필수 |
| M8.5 | 필수 | 필수 | 이미지 메타데이터/랭킹 지표 데이터 필요 시 진행 | 필수 |
| M9 | 필수 | 필수 | 대규모 데이터 확장 및 검증 데이터 필요 | 필수 |

실제 스킵 여부는 2단계 계획 제안 단계에서 사용자가 결정한다.